mirror of
https://github.com/pnpm/pnpm.git
synced 2026-10-31 03:58:35 -04:00
docs-migration-runtime-setting
14
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 KhảiandClaude Opus 5
|
1606ba03fb |
docs: add the documentation and comment principles and apply them (#16516)
* docs(agents): add the documentation and comment principles Import the principles that transfer from KSXGitHub/perfectionist's contributor guide, plus four of our own: concise and non-repeating text, structured text over prose, removal over addition when reviewing or fixing nitpicks, and a definition of the user-facing text that must not name implementation details. The root guide's "Comments" section gains "Register", "Prose that cannot go stale", "User-facing text", and "Reviewing documentation and comments". The pacquet style guide adds the Rust specifics (clap and napi doc comments are user-facing; a default is documented on the field, not the variant). DOCUMENTATION.md gains the renderer and link table for each markdown surface. The guides themselves are brought in line: counts over growable lists become plain references, a quoted heading becomes an anchor link, and the size limits are stated once, in the style guide, instead of three times. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs: keep user-facing text free of implementation names The `@pnpm/napi` README and type declarations named the Rust engine, the in-repo package name, and TypeScript internals (`filterPkgsDiff`, `nameFormatter`) that a user of the addon cannot reach. The pnpmfile page in both docs trees explained a limitation by the IPC mechanism behind it. Four changesets named the release line or implementation, which the package targets already express. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(crates): cut restating and stale comments in pack, modules-yaml and nine more crates Apply the comment principles to pack, versioning, pnpr-client, package-is-installable, fs-packlist, workspace-task-scheduler, engine-runtime-node-resolver, exportable-manifest, modules-yaml, pnpr-registry, and pnpr-auth. Removed: call-site comments that repeat the callee's doc, module rosters of exports that the `pub use` lines already list, "not yet implemented" notes for behaviour that exists (`beforePacking`, `hoistedLocations`), body narration, and history framing. Comment-only; no code changes. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(crates): cut restating and stale comments in the small resolver, catalog and pnpr crates Apply the comment principles to the local, tarball, default, deno and jsr resolvers, the catalog crates, detect-libc, config-parse-overrides, env-replace, git-utils, matcher, diagnostics, and the pnpr policy, cargo, error, osv and fixture crates. Removed: parentheticals that repeat a `#[diagnostic(code)]` attribute, counts over lists of variants, callers and entry points, rosters of callers, doc paragraphs that repeat a sibling's or the module's text, comments narrating the match arms or condition below them, and history framing. The `pnpr-prepare --help` text no longer names the test harness. Comment-only; no code changes. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(crates): cut restating and stale comments in publish, workspace, registry and graph-hasher Apply the comment principles to publish, auth-commands, registry, workspace, lockfile-verification, default-reporter, the git resolver, deps-inspection, hooks, graph-hasher, package-manifest, and the pnpr shared-artifacts and route crates. Removed: a module roster of every export, counts over lists, plan notes for work that landed ("Phase 5", "Phase 6"), call-site comments repeating the callee's doc, docs narrating match arms, a default claim on a `#[default]` variant, a misattached doc, and history framing. Comment-only; no code changes. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(crates): cut restating comments in napi, reporter and pnpr crates Apply the comment principles to napi, reporter, resolving-resolver-base, real-hoist, git-fetcher, workspace-manifest-writer, and the pnpr config and storage crates. Removed: "Mirrors X in index.d.ts" sentences on `#[napi]` items and other implementation names in addon-facing docs, stale "not emitted yet" and "when it lands" notes for behaviour that exists, step-by-step comments narrating the body, emit-site and caller rosters, docs duplicated from a sibling or the module, a doc attached to the wrong item, and history framing. Comment-only; no code changes. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs: cut restating and stale comments across the remaining crates and pnpm11 Apply the comment principles to the rest of the Rust workspace and to the TypeScript CLI: the cli crate and its clap definitions, package-manager, config, patching, the deps resolver, lockfile, pnpr, the npm resolver, tarball, network, executor, cmd-shim, the benchmark and fixture tooling, and the pnpm11 packages. Removed: comments narrating the body, docs repeating a callee's, a sibling's or the module's text, counts over growable lists, rosters of callers and exports, "not yet implemented" notes for behaviour that exists, history framing, and `@param` lines restating a signature. One exception to comment-only: in `pnpr/crates/pnpr/src/resolver/resolve.rs` the `Workspace` struct sat inside the doc block written for `resolve`, so the struct moved above it and each doc now attaches to its own item. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(crates): cut body narration and duplicated docs in resolver, fs and package-manager Removed: a numbered "Sequence:" list narrating `ensure_file`'s body and the paragraph restating its backoff constants, the stress-test module doc's roster of its own tests, refactor-history paragraphs in the peer walk's finalize pass, call-site and caller-side copies of a callee's doc (the `optional` AND-fold stays documented on `register_seeded_package` and on `ResolvedPackage`), a verbatim quotation of a TypeScript test's expected output in the pnpr search module doc, and field and digest-input rosters in the package-manager. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(deps-restorer): cut plan references and re-attach misplaced docs Removed the "slice 4" plan references and the comments narrating the bodies they sat above. The `Auto` downgrade-chain doc moved from `copy_and_log` to `auto_link`, the function it describes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(deps-restorer): cut the remaining body narration in the hoist path Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs: cut the last body narration and a history clause in the cmd-shim test `build_graph.rs` kept a `patches` parameter doc that re-derived what `BuildOptions::patches` documents. The PowerShell-arguments test on main said the arguments survived "before the shim ended its batch context too", which describes the change rather than the behaviour. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(cmd-shim): point the PowerShell-shim link at its current module Main moved `wants_powershell_shim` into `windows_shim_policy`, so the shim writer's link to it no longer resolved and `cargo doc` failed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(cli): link the fixture the ignored-build setup installs The shortened doc named `workspace_with_unapproved_build` in backticks, which `perfectionist::bare_identifier_reference` rejects for an item that resolves in scope. It is an intra-doc link now. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(crates): restore two contracts and fix four dangling references A review of this branch's sweep flagged seven places. Six needed a change: - `from_ini` documents again that a relative `cafile=` resolves against `npmrc_dir`, a precondition its callers have to honour. - `hash_object` documents again that the private serializer's bytestream has to match pnpm 11's, because the digest is persisted and read by both. - The hooked-manifests note no longer says "above" of a gate that lives in another module. - The store-dir race test states its synchronization contract instead of labelling it "Post-Option-C". - `GraphNodeHashOptions.nodeVersion` keeps `undefined` as a literal. - The pnpr streaming module drops the sentence fragment that introduced its list. The seventh, a `beforePacking` limitation in exportable-manifest, stays removed: the note said the pnpmfile bridge cannot supply that hook, and `pnpm_pack::lifecycle::apply_before_packing` has been running it since before this branch. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(cli): say in `pnpm why --help` that `--exclude-peers` is ignored Demoting the caveat to an ordinary comment took it out of the help, which then advertised a flag that does nothing: `WhyArgs::run` never reads `exclude_peers`, and pnpm 11's `why` handler never forwards its `excludePeers` either. The doc comment states that behavior in the words a user sees, and the parity reason stays in a comment beside it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW * docs(cli): drop the doc comment that described the wrong module The comment described the `pnpm_deps_inspection as deps_tree` re-export above it, but a doc comment attaches to the item that follows, so rustdoc showed it as the description of `mod dispatch`. The `use` item already names the alias, so the comment goes rather than moving. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QYTBQo8HY7xD2iz6hjo1CW --------- Co-authored-by: Claude <noreply@anthropic.com> |
||
|
Zoltan Kochan
|
658dbc30a6 |
feat: support pnpm in StackBlitz WebContainers (#16499)
Compile the shared Rust CLI for wasm32-wasip1-threads and supply filesystem, network, process, terminal and cancellation capabilities through a Node host. Select host implementations at compile time so native builds retain their native dependency/features and execution paths. Bundle the WASM runtime in the regular npm wrappers and select it from the WebContainer runtime marker. Keep Node launchers usable without installation scripts. Native installation replaces all four launchers with native bytes. Regenerate shims after upgrades or dependency builds replace Node targets with native binaries, including before dependent lifecycle scripts run. Preserve collision winners and publish replacement shims with executable permissions. Reject non-descendant permission templates and intermediate symlink escapes, validate before creating directories, and avoid path-based cleanup races. Restore direct native aliases in both version-management implementations. Retain process cleanup after failed stdin shutdown. Prevent cross-origin redirects from replaying login credentials in both CLI lines, and strip npm-otp from cross-origin WASM requests. Avoid repeated selected-snapshot and removed-bin scans. Preserve resolution, lockfile, integrity and build-approval behavior. Use an isolated WASM store with rollback journals and process leases. Patch WASI path normalization for multiple parent segments and retain that patch in bundles. Add pinned tooling, release packaging, real-browser workflow and selection tests, documentation and a release note. Document host limits, including the Corepack cold-download failure in WebContainer's streaming hash implementation. Controlled native CLI cases showed no separated slowdown, and the latest hoisted rebuild and repeat-install fixture improved. Retain the documented microbenchmark uncertainty and host limitations. Related to pnpm/tasks#63. |
||
|
|
cbb2eb04ea |
fix: lower fetch concurrency per origin when a timeout hits an active download (#15880)
A fetch timeout while another request to the same origin is still in flight now lowers that origin's in-flight cap to one connection. The configured network concurrency stays in place until that happens, and other origins keep it. Remaining retries and later requests to that origin wait for the single slot. The cap is per origin, so one slow registry or tarball host cannot drag down downloads from healthy ones. On a slow link, nearly every download comes from one registry, so that origin times out against its own peers and is lowered. In the Rust client each origin gets a gate next to the maxSockets limit, acquired before the global semaphore so a request waiting on a lowered origin holds no global slot. Behind a proxy the origin is the proxy's. In the TypeScript client each connection origin (again the proxy's when one applies) gets a gate around its registry fetches, held until the body settles, so a stalled download still counts as in flight. Already-granted requests finish. Further requests to that origin wait until one remains. pnpm/pnpm#12791 --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Zoltan Kochan <z@kochan.io> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
Zoltan Kochan
|
4edeef9176 |
style(ts): port the perfectionist lint rules to ESLint (#16415)
Add TypeScript ports of the perfectionist rules that the Rust workspace enforces through dylint.toml to @pnpm/eslint-config, with the same limits, and fix every finding that needs no refactor. The size and shape rules (function length, cognitive complexity, nesting, local bindings, file length) are enforced for packages that already meet them. The packages that do not are listed in PENDING_SIZE_AND_SHAPE_REFACTOR in eslint.config.mjs and are refactored in follow-up changes. The custom rules mirror perfectionist's semantics rather than reusing sonarjs or max-lines-per-function, so that one limit means the same thing in both codebases: a closure is a level of the body that contains it, a nested function declaration is measured on its own, and a test-framework callback plays the role of a #[test] function. Bugs found and fixed along the way: - a registry error body cut at exactly 64 KiB lost its truncation marker - removing a dependency could leave dangling .bin shims - constructor/__proto__ names crashed the projects graph, were skipped by the injected-deps syncer, and were dropped from writeWantedLockfile's returned lockfile The CI chunk runner learns to run the node:test suite of the ESLint config package. |
||
|
Zoltan Kochan
|
11b9393080 |
fix: recognize WebContainers' async fs errors (#16253)
StackBlitz WebContainers reject asynchronous fs calls with errors that inherit from Error but were not created by the native constructor, so util.types.isNativeError() returns false for them. pnpm used that check to recognize ENOENT and other codes, so a missing pnpm-lock.yaml was rethrown and pnpm install failed on any project without a lockfile. Add isError() to @pnpm/error, which accepts a native error or any instanceof Error, and use it at every non-test call site. The native check alone is still needed for Jest, where errors from another realm fail instanceof. Update the AGENTS.md guidance to match. Closes pnpm/pnpm#15649 |
||
|
kudaliar
|
b692397290 |
fix(tarball): fail fast when the package store is full (#15697)
A full content-addressable store cannot recover by re-fetching and re-extracting the same tarball. Detect ENOSPC through the store-write error chain before scheduling archive retries. The TypeScript fetch path recognizes ENOSPC in both direct and wrapped errors, including worker failures, while retaining its existing retry policy otherwise. The regression tests assert that the retry budget is not consumed. Related to pnpm/pnpm#8581; the Cypress postinstall hang remains outside this change. |
||
|
Altay
|
72baf833ca |
fix(network): fail at once on an untrusted TLS certificate (#15633)
A request to a server whose TLS certificate fails verification was retried under the fetch-retries backoff (10 s, then 60 s) although no retry can change the verdict. pnpm v12 retried every transport error, so a metadata request sat silent for 70 seconds before printing the certificate error, and a tarball download multiplied the quick connect retries by the archive retries. is_certificate_error now spots rustls' InvalidCertificate in the reqwest error chain, and send_with_retry, get_secure_bytes and the tarball retry loops fail such a request on the first attempt. pnpm v11 only skipped retries for SELF_SIGNED_CERT_IN_CHAIN; other verification codes such as UNABLE_TO_VERIFY_LEAF_SIGNATURE and DEPTH_ZERO_SELF_SIGNED_CERT were retried, and the tarball fetcher retried every one of them. The non-retryable set now covers the certificate verification codes, the tarball fetcher honours it, and the rejected error is undici's TLS cause, so the message names the certificate problem instead of "fetch failed". Closes pnpm/pnpm#9134 |
||
|
Zoltan Kochan
|
54d7268c10 |
fix(network): make fetch-timeout an inactivity timeout (#14642)
pnpm aborted a request once its total time passed `fetchTimeout`, body included, so `pnpm runtime set node` could never finish its ~62 MB download on a slow connection. pnpm v12 set reqwest's client-level `timeout`, a deadline for the whole request; pnpm v11 passed `AbortSignal.timeout` to undici, which aborts the response body too. Both stacks now bound inactivity instead. pnpm v12 sets reqwest's `read_timeout`, which restarts on every chunk received. pnpm v11 drops the abort signal and lets the undici dispatcher enforce `headersTimeout` and `bodyTimeout`, which behave the same way; the global dispatcher sets per dispatch, through an interceptor composed onto the dispatcher that would have served the request. The agents pnpm builds for a proxy or custom TLS take their connect bounds from the same value, which the abort signal used to cover. A connection that stops delivering data still fails after `fetchTimeout` in both. Closes pnpm/pnpm#14604 |
||
|
Zoltan Kochan
|
427bece813 |
feat(cli): integrate python with shared install and artifact lifecycles (#14586)
Exercise the multi-ecosystem architecture through a usable Python integration, not test-only metadata writers. Keep Python requirement, marker, lockfile and environment semantics separate from npm and Cargo. Reuse the install-wide HTTP/auth budget, verified artifact ingestion, CAS and store index. Extract a shared install lifecycle without ecosystem-specific branches. Native tasks declare metadata footprints and return prepared projections. Settle all work before publishing Cargo or Python state, and reverse attempted publications before restoring metadata on failure. Retain resources when rollback fails so recovery remains possible. Enroll npm with its existing in-place materialization semantics, and keep npm-only dispatch on its early path. Do not unify native resolvers, lockfile formats, target identity or package layouts. Consolidate archive ingestion below the ecosystem boundary. Share cache validation, authenticated requests, extraction retries and publication across tarballs and ZIPs, retaining tar streaming and ZIP decoding. Test the shared contracts across both formats and preserve npm fast paths. Use standard pylock.toml, independently validated with uv. New features target pnpm v12 only. Shared archive URL-redaction fixes also cover pnpm v11. Related to pnpm/pnpm#14566 and pnpm/rfcs#34. |
||
|
Zoltan Kochan
|
3af5322039 |
fix: authenticate node.js mirror downloads (#14375)
Reuse the existing URL-scoped registry credential lookup for every Node.js mirror request instead of introducing a separate authentication setting. This covers release indexes, SHASUMS files and signatures, and runtime archives in both implementations while retaining longest-path-prefix scoping and cross-origin redirect protections. Authenticated checksum metadata bypasses the URL-keyed disk cache so it cannot cross credential contexts. Closes pnpm/pnpm#14334. |
||
|
Zoltan Kochan
|
74f9236b67 |
feat: support integrity-addressed registry revisions (#13475)
Add registry replacement-tarball support to the TypeScript and Rust pnpm implementations. Validate explicit positive safe-integer revision metadata against complete SHA-512 integrity-addressed registry URLs, compact and hydrate revision resolutions in the lockfile, and enforce a single authenticated non-redirecting fetch with no retry or fallback. Route revision URLs through the normalized scope and prefix maps derived from the registries setting, preserving registry path prefixes. Let pnpr proxy immutable revision artifacts for concrete upstream registries with forwarded authentication, integrity verification, and digest caching. Carry revision metadata through pnpr's resolver protocol so pacquet uses the same strict fetch behavior for direct and proxied resolution paths. Leave revision selection and history, patch refresh commands, pnpr hosted publishing, and the RFC's unresolved lockfile compatibility gate for follow-up work. |
||
|
Zoltan Kochan
|
d3556f6ba9 |
refactor(text): move lexCompare and nerfDart into the monorepo (#13535)
Both utilities lived in the pnpm/components Bit workspace, where their component names collide with same-named components elsewhere in the Bit registry. Move the code here and publish it under new names: `@pnpm/util.lex-comparator` -> `@pnpm/text.ordinal-comparator` `@pnpm/config.nerf-dart` -> `@pnpm/config.registry-auth-key` The new names describe what the utilities do: the comparator is ordinal rather than locale-aware, and the mapped URL is the key that registry settings are stored under in `.npmrc`. The exported functions keep their names, so consumers only change their import specifiers. Implementations and tests are carried over unchanged. The rationale from the components' docs pages moves into doc comments: why `localeCompare` cannot be used for values compared across machines, and where `nerfDart` originates. No pacquet counterpart is needed. The Rust stack has its own implementations of both and no user-visible behavior changes. |
||
|
Alessio Attilio
|
508b8c29db |
feat(cli): implement the access command for both pnpm and pacquet (#12816)
Implement the pnpm access command in both the TypeScript CLI (pnpm11/registry-access/commands/src/access.ts) and the Rust pacquet port (pacquet/crates/cli/src/cli_args/access.rs). The command follows npm's npm access paradigm and supports: list packages (users, orgs, teams, and per-package collaborators), get status (package public/restricted access status), set status (change package visibility with restricted/private mapped to restricted), set mfa (configure two-factor authentication requirements per package with none/publish/automation levels), grant (grant read-only or read-write team access to scoped packages), revoke (revoke team access from scoped packages). Both implementations include auth header and OTP support, JSON output mode, proper error handling with pnpm error codes, and comprehensive unit tests. The TypeScript tests use mock agent fixtures and the Rust tests cover parameter validation and error paths. |
||
|
Zoltan Kochan
|
fc2f33912e |
refactor: move the TypeScript pnpm CLI into a pnpm11/ directory (#12537)
The TypeScript pnpm CLI freezes at v11; pnpm 12 will be the Rust pacquet port. To make that split legible, all TypeScript source, test, and build directories move under a new top-level pnpm11/ directory. The name states the version boundary rather than implying a behavioral fork, since the two stacks are meant to behave identically. Scope is source-only: the shared workspace root stays at the repo root. pnpm-workspace.yaml, package.json, pnpm-lock.yaml, .pnpmfile.cjs, .meta-updater, __patches__, .changeset, .husky, and the lint/spell configs remain in place, so one pnpm workspace and one Cargo workspace still span all three products. pnpr/client and pacquet/tasks/registry-mock stay as cross-product workspace members. Rewiring the move required: - pnpm-workspace.yaml globs prefixed with pnpm11/ - root package.json script paths, eslint.config.mjs, tsconfig.lint.json, .gitignore, and CODEOWNERS updated - .meta-updater/src/index.ts literals repointed (pnpm11/pnpm/package.json, pnpm11/__utils__, pnpm11/__typings__, and the main package directory) - regenerated every moved package's repository/homepage URL via meta-updater - pnpm11/pnpm/bundle-deps.ts and __utils__/scripts/src/typecheck-only.ts climb one more level to reach the repo root .meta-updater stays at the repo root because @pnpm/meta-updater resolves its config at <cwd>/.meta-updater/main.mjs. TS CI (.github/workflows/ci.yml) now only runs when pnpm11/-relevant paths change, via a dorny/paths-filter changes job plus a TS CI / Success aggregate gate; branch protection should require only that gate. |