pnpm/pnpm
github.com/pnpm/pnpm ↗ · 4000 files · 22.2 MB · scan capped
简体中文 | 日本語 | 한국어 | Italiano | Português Brasileiro Fast, disk space efficient package manager: Fast.
Overview
At commit b2ef6cb63b8b7cb93d6b57f0d2efedf25d7c1385, this repository contains the Rust pnpm v12 CLI, the maintained TypeScript pnpm v11 CLI, and pnpr, a Rust registry server. It serves developers managing dependencies, workspaces, scripts, and releases, plus operators hosting or proxying packages. Distinctive mechanisms include content-addressed installation, separate wanted and installed lockfile state, policy verification, JavaScript hooks, and an optional server-assisted resolution path. This brief reflects bounded source inspection, including three concrete flows; it is not exhaustive coverage or runtime validation.
System map
The repository has two CLI implementations and a sibling registry server, with shared Rust crates rather than one uniform runtime. The Rust CLI separates startup, command routing, application state, and the installation engine. pnpr builds an Axum server around configuration, identity, routing, storage, and optional protocol surfaces. Root manifests coordinate builds and tests across both language stacks.
- The root Cargo workspace includes pnpm crates, pnpm task binaries, and pnpr crates; its shared package metadata selects Rust edition 2024.
- The Rust executable's main delegates to pnpm_cli::main, which installs diagnostics and runs CLI startup on a separate thread; normal commands use a Tokio runtime with 32 MiB stack headroom.
- The TypeScript entrypoint dynamically loads main and the worker API, routes errors through errorHandler, and drains workers in finally; its package ships bin launchers and dist output and requires Node >=22.13.
- CLI State owns manifest data, a lazy wanted lockfile, resolved-package state, and shared HTTP/tarball caches; configuration is borrowed as a process-lifetime Config.
- pnpr exposes library router/serve APIs and a Tokio binary; serve validates enabled surfaces and registry routing, loads OSV and authentication, builds the router, then binds and serves with graceful shutdown.
- pnpr separates durable hosted storage from its disposable local proxy cache. HostedBackend supports local or S3-compatible implementations, while authentication supports local htpasswd/SQLite and selectable shared SQL backends.
- Root scripts provide Rust build, affected tests, smoke tests, checks, and linting, alongside TypeScript compilation and package testing; pnpm-workspace.yaml wraps CI scripts in named pipelines and assigns task concurrency groups.
- The Rust CLI's npm wrapper is named pacquet in-repo but publishes as pnpm and exposes pnpm/pn/pnpx/pnx. A separate workflow builds the pnpm container image for amd64 and arm64 with provenance and SBOM output.
Feature catalog
The inspected Rust command table covers dependency management, workspace execution, package inspection, publishing, configuration, runtime management, and release intents. Installation exposes dependency-group and linker choices, with optional Cargo and Python participation. pnpr combines compatible registry APIs with resolution, artifact, compiler-cache, and pipeline-record surfaces. This catalog groups the inspected public surfaces; command registration alone does not establish complete implementation or successful operation.
- Dependency commands include add, install, install-test, update, remove, link/unlink, import, dedupe, prune, fetch, deploy, and patch/patch-commit/patch-remove; install accepts production, development, and optional dependency selection plus isolated, hoisted, or PnP linkers.
- Execution surfaces include recursive, run, exec, dlx, create, test/start/stop/restart shortcuts, tasks, and pipeline. Pipeline's declared contract includes frozen installation, affected-project selection, dependency ordering, and cached task restoration.
- Inspection and security commands include list/ll, why, outdated, audit, peers, licenses, sbom, doctor, ignored-builds, approve-builds, cat-file, cat-index, and find-hash.
- Publishing and account commands include pack, publish, stage, access, deprecate/undeprecate, unpublish, dist-tag, login/logout, owner, team, whoami, and star/unstar/stars; change, version, and lane manage release intents and lanes.
- Configuration and environment surfaces include config/get/set, pkg, set-script, runtime, deprecated env, shim, with, setup, self-update, completion, clean/purge, ci, store, and cache. edit/profile/token/xmas are explicitly registered as unimplemented commands directing users to npm.
- When cargo.enabled or python.enabled is set, ecosystem_install::plan adds Cargo or Python tasks to an InstallPlan; Python selection follows workspace scope and production/development dependency groups.
- pnpr mounts npm metadata, version, tarball, search, dist-tag, publish, unpublish, and staged-publish routes, including named registry prefixes; configured Cargo and PyPI ecosystems add their own route sets.
- Optional pnpr surfaces provide resolve/verify-lockfile, artifact publication/resolution/blob retrieval, compiler-cache reads and writes, and pipeline-run storage plus a viewer. NAPI separately exposes install, rebuild, pack, dependency resolution, peer checks, configuration, and lockfile APIs to Node hosts.
Data flow
CLI inputs become normalized arguments, configuration, manifest data, and lazily loaded lockfile state before entering the installation engine. The engine carries explicit workspace scope, lockfile policy, execution mode, shared caches, and verification state through resolution and materialization. Installed metadata and freshness records represent different stages of completion. Server reads add identity and declared provenance before consulting hosted storage or upstream caches.
- Rust startup consumes args_os, handles executable aliases and the pm prefix, extracts ConfigOverrides, rewrites with current, parses Clap arguments, and retains child argv for pinned-package-manager dispatch.
- Config is a merged runtime type rather than directly deserialized file data: defaults are overlaid with the auth/registry/network subset of .npmrc and structural pnpm-workspace.yaml settings.
- State::install passes shared tarball and HTTP caches, resolved packages, Config, PackageManifest, and a lazy lockfile into Install::new; dedicated-project installs also share cross-project caches and completion coordination.
- InstallArgs converts CLI/config decisions into lockfile policy, execution mode, linker, architecture, and resolution seed settings. pnpr's remote policy controls server resolution, while local materialization uses the server-produced lockfile as frozen input.
- RunExecution loads lockfiles and hooked manifests, settles the wanted lockfile, creates Verification, dispatches the chosen path, materializes, and applies the result; shared Verification holds metadata cache, planned canonical fetches, and resolution verifiers.
- Installed-state commit builds and writes .modules.yaml, then saves the current lockfile. Workspace freshness is written later, and a moved-tree filtered install deliberately skips that freshness update.
- pnpr metadata reads validate CanonicalPackageName, resolve a RegistrySource, authorize upstream access or apply hosted gates, then load bytes. Upstream responses pass through packument_response with tarball-base rewriting, OSV data, and abbreviated-response selection.
- pnpr's resolution cache distinguishes public and private fetch routes using RouteClass and a Footprint digest. RouteHook selects server-managed credentials at the auth-selection boundary; privacy depends on registry/package policy rather than simply whether a request carried credentials.
Behavior traces
Three principal flows were followed through source: CLI startup, dependency installation through installed-state persistence, and pnpr metadata/tarball reads through authorization and cache handling. Additional startup reading distinguishes pnpr's production server API from convenience router construction. The traces retain early returns and policy branches because those determine which work actually occurs. These are execution paths inferred directly from code structure, not observed runs.
- Rust startup follows bin::main → pnpm_cli::main → run_on_big_stack(run_cli) → shim dispatch → argument normalization → parse_or_answer → configure_cli_args → pinned dispatch/completion checks → Rayon setup → install fast-path check → run_cli_command.
- TypeScript startup follows buildArgv → runPnpm → main → parseCliArgs → loadCommandConfig/readCommandConfig → package-manager/runtime handling → config-dependency and hook loading → runCommandWithConfig; runPnpm finally drains workers.
- InstallArgs::run calls run_inner, resolves frozen/link options, rejects pnpr plus dry-run, and selects install_via_pnpr_inner when pnpr_target exists; otherwise run_local builds State::install and invokes run or run_selected.
- Local Install::run → run_inner acquires a store-use lock → run_inner_impl settles RunMode and discovers the workspace → RunExecution::run checks reuse, loads lockfiles, and settles wanted state → dispatch chooses frozen/fresh → materialize → finish_materialization.
- Persistence follows finish_materialization → apply_materialization_result → apply → link_apply_projects → commit_apply_state → finish_apply. commit_modules_state writes module metadata before the current lockfile; finish_apply subsequently publishes workspace freshness and completion output.
- pnpr startup follows Args::parse → Config::resolve_with_overrides → apply_cli_overrides → logging → serve. serve validates configuration, loads active OSV, calls load_startup_auth with registry journal recovery, builds routes, binds the listener, and enters graceful serving.
- A metadata read follows serve_packument → addressed_registry → serve_registry_packument → canonical-name parsing/source selection/access authorization → serve_packument_via_upstream → load_upstream_packument. A fresh cache hit returns immediately; misses fetch and cache, authoritative 404s purge cached package state, and packument_response shapes the client response.
- An upstream tarball read follows serve_registry_tarball → access authorization → serve_tarball_via_upstream → filename validation/authorized_upstream → serve_authorized_upstream_tarball. Without OSV, a cache hit can precede metadata binding; misses bind version/integrity, screen OSV, fetch, open temporary storage, and stream with integrity-gated cache promotion.
Testing signals
Tests and CI definitions were inspected, not executed; no passing result, measured coverage percentage, or benchmark outcome is established here. Rust uses ordinary and Tokio tests, process-level CLI fixtures, snapshots, and cargo-nextest configuration. TypeScript uses Jest with registry-backed project fixtures. The inspected checks span installation, filtering, integrity, recovery, and language/runtime boundaries, but the bounded sample cannot establish all untested behavior.
- The inspected Rust CLI suite is assembled in tests/suite/main.rs as one integration-test binary, while nextest runs individual tests in separate processes; its modules include install-related commands, custom resolvers/fetchers, lifecycle behavior, and linker variants.
- should_install_dependencies spawns the real CLI against a mocked registry, asserts the direct dependency is a symlink/junction, checks transitive placement in the virtual store, and snapshots workspace/store structure using insta.
- TypeScript install/only.ts uses Jest and execPnpm fixtures to check production/development filtering; its production test also checks progress counts and verifies the resolved dev-transitive version in the lockfile before store-presence assertions.
- pnpr tarball tests use Tokio, mockito, temporary storage, and Axum oneshot requests to check declaring-version integrity binding and cache replay after router reconstruction; the same file includes a tampered-stream rejection test.
- Journal-recovery tests fabricate interrupted on-disk publication state, including an older manifest format, to exercise sealed roll-forward and unsealed rollback; these recovery scenarios were read, not run.
- The nextest smoke profile selects one test per behavior area and explicitly does not prove change correctness. Default tests receive a 60-second slow interval with termination after five intervals, and separate validation is documented for stale smoke-test names.
- Rust CI invokes separate rust-test and pnpr-test pipelines and adds a Linux Node test of the built NAPI addon. TypeScript CI builds the bundle before sharded tests across Node 22.13, 24, and 26.10 on Linux, with a separate Windows shard matrix.
- Ecosystem E2E and Cargo equivalence are scheduled compatibility checks rather than per-PR merge blockers; docs CI builds the external website with repository docs and checks URLs, while the inspected CodeQL matrix selects JavaScript.
Risk map
The observations below identify trust boundaries and behavior that deserves careful review; they are not confirmed vulnerabilities. Package scripts and JavaScript hooks intentionally cross into process execution, while pnpr handles identity, remote fetches, cached private data, and persistent publication state. Several protections are explicit, including early authorization, integrity-gated cache promotion, connection policy, and verification gates. Operational assumptions and coverage limits remain relevant even when those protections are present.
- The executor exposes shell execution through sh -c and allows callers to choose the working directory; command strings therefore cross an intentional code-execution boundary, and nonzero child status is distinct from spawn/wait errors.
- pnpmfile hooks execute JavaScript in Node processes. readPackage/afterAllResolved/filterLog use a lazy long-lived worker, while preResolution uses node -e with piped JSON and a 30-second timeout; preResolution failures warn rather than abort.
- Lockfile verification can overlap resolution/fetching but must gate sensitive downstream operations. The gate aborts on drop; trustLockfile or an empty verifier set makes verification a no-op, so changes to either policy or completion ordering require review.
- pnpr mounts authentication before handlers to enforce token restrictions before buffering large write bodies. Unknown or revoked ordinary bearer tokens can resolve to anonymous, leaving route and per-package policy responsible for distinguishing public access from protected operations.
- Resolver connection policy admits public addresses, explicitly allowed private networks, and the server's configured public_url host. IP literals are checked separately from hostname resolution; own-host configuration and private-network exceptions are security-sensitive inputs.
- A warm upstream tarball cache hit without OSV intentionally skips re-binding against current metadata, so previously verified bytes can remain downloadable after a version is unpublished. The documented acceptance authority is the client's lockfile integrity.
- Inference: install completion is a broad regression hotspot because filtered selection, prior metadata, current lockfiles, and workspace freshness meet at separate writes; reordering freshness ahead of module/current-lockfile commit could advertise an incomplete tree. (inferred)
- The inspected CodeQL workflow selects only JavaScript, and the smoke profile explicitly limits its correctness claim. Neither source establishes Rust security-analysis coverage or full branch coverage; broader repository tooling was not exhaustively audited.
Extension points
The clearest extension seams are typed command registration, ordered resolver composition, hook interfaces, reporter events, and backend traits. pnpr separates feature-surface mounting from registry provenance and storage implementation. Extension contracts frequently encode security or compatibility constraints, so adding an implementation requires preserving those constraints rather than only satisfying a type signature. NAPI exposes a separate host-facing boundary over the same Rust engine.
- CliCommand is a Clap-derived enum carrying command-specific argument types, with aliases and an external-subcommand fallback; cli_args::grammar caches the assembled command grammar in OnceLock.
- DefaultResolver composes Vec<Box<dyn Resolver>> in order: Ok(None) defers, the first claim wins, and exhaustion yields a stable unsupported-spec error; resolving-resolver-base also exposes a separate ResolutionVerifier seam.
- PnpmfileHooks is an async Send+Sync interface for manifest and resolution customization. Custom fetchers can request native CafsInfo, TempDir, LocalTarball, and RemoteTarball operations through callback channels with oneshot responses.
- Reporter extensions add typed LogEvent variants serialized with a name tag; channel names and payloads are designed for consumption by the TypeScript default reporter, making the wire contract part of extension correctness.
- pnpr surface_routes conditionally mounts resolver, artifact, pipeline, and registry route factories. Shared authentication/body-limit layering is applied after surface construction, and individual protocol routes add caller gates.
- Registry supports Hosted, Upstream, and ordered Router variants with declared package patterns. A router selects a claiming concrete source authoritatively; its not-found/unavailable result cannot fall through to a different origin.
- Storage and identity implementations plug into HostedBackend and AuthState's UserBackend/TokenBackend trait objects. Hosted backends own compare-and-set and blob-promotion differences; backend selection occurs during startup.
- The NAPI crate exports typed install, resolution, configuration, packing, and lockfile boundaries; its documented JS contract lives in the wrapper declarations, and module initialization installs the engine's tracing subscriber.
Contributor handoff
Future work should first identify the owning product and the precise observable behavior being changed. Read repository policy alongside the implementation, because broad documentation and historical descriptions can lag current manifests or source. Tests and CI were inspected, not executed, and this bounded investigation provides no baseline pass result. For authorized implementation work, select meaningful scoped checks while preserving cross-version contracts, state ordering, and release-note targets.
- Read AGENTS.md and PHILOSOPHY.md plus the owning product's guide. New CLI features belong only in Rust v12; shared bugs require fixes in both supported implementations, while pnpr has no CLI counterpart to mirror.
- Prefer existing capabilities and shared abstractions before adding code. pnpr specifically directs reuse of pnpm crates and reserves pnpr-prefixed crates for registry-only logic.
- Run Rust tooling from the repository root and account for pnpm-managed Cargo source replacement. A fresh clone or changed Cargo.lock requires dependency installation before Cargo can resolve the replaced sources; cargo add is not the documented dependency-addition path.
- For authorized Rust validation, use pnpm test:rust-affected and add relevant pnpm-cli suite modules for user-visible engine changes: affected-crate selection alone does not necessarily include CLI e2e tests. Invoke root pnpm scripts to participate in task concurrency limits.
- Tests and CI in this brief were inspected, not executed. A future agent must establish actual selected-test results; smoke is explicitly insufficient to prove correctness, and TypeScript CLI e2e tests require rebuilding the bundled dist/pnpm.mjs after package changes.
- For pnpr embedding, choose APIs deliberately: router uses in-memory auth, router_with_auth can panic on invalid setup, and try_router variants return errors. Production serve loads persistent auth and recovers registry publication state before binding.
- User-visible changes require affected-version documentation and normally a changeset, with an exemption for bugs in unreleased features. Target pacquet for Rust CLI changes, pnpm plus affected packages for TypeScript fixes, and @pnpm/pnpr for server changes.
- Preserve reporter event payload/order for shared fixes and use real temporary-directory or mocked-registry fixtures before introducing test injection. Root README still calls the Rust port experimental, while product docs identify v12 as the development target; verify maturity from current policy and feature evidence.
Languages
| Language | Files | Share of source |
|---|---|---|
| Rust | 3194 | 55% |
| TypeScript | 2093 | 36% |
| JSON | 1556 | docs/config |
| Markdown | 1125 | docs/config |
| JavaScript | 384 | 7% |
| YAML | 317 | docs/config |
| TOML | 126 | 2% |
| Shell | 13 | 0% |
Start reading here
Probable source entrypoint: pnpm/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
pnpm/ (1251 files)
Repository structure
| Top-level path | Files |
|---|---|
pnpm/ | 1251 |
pnpm11/ | 1251 |
pnpr/ | 817 |
.changeset/ | 538 |
.github/ | 75 |
.agents/ | 10 |
.husky/ | 7 |
.meta-updater/ | 6 |
Docs found: AGENTS.mdCLAUDE.mdCONTRIBUTING.mdREADME.md
Package
Cargo.toml — , 0 declared dependencies.
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructionsCLAUDE.md— Claude instructions.github/workflows/audit.yml— GitHub Actions workflow.github/workflows/benchmark.yml— GitHub Actions workflow.github/workflows/build-pnpr.yml— GitHub Actions workflow.github/workflows/cancel-unapproved-workflows.yml— GitHub Actions workflow.github/workflows/cargo-equivalence.yml— GitHub Actions workflow.github/workflows/ci-performance-bencher-upload.yml— GitHub Actions workflow.github/workflows/ci.yml— GitHub Actions workflow
Structural health signals
Average score 6.4/10 across 96 analyzed source files; 49 hotspots surfaced.
pnpr/crates/storage/src/journal.rs— 591 lines, score 4.5 (Large file, Deep nesting)pnpm/crates/deps-restorer/src/shared_side_effects/tests.rs— 879 lines, score 5.2 (Large file, Deep nesting)pnpr/crates/route/src/lib.rs— 686 lines, score 5.2 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
b2ef6cb63b8b2026-10-02 — fix: take file locks with flock on Android (#16512)658dbc30a61c2026-10-02 — feat: support pnpm in StackBlitz WebContainers (#16499)da17e33bb6532026-10-02 — fix(cmd-shim): end the pnpm CLI's batch context before it runs (#16509)80afdd52f74d2026-10-02 — refactor(resolver): drop the installable flag the walk never reads (#16513)1435ce4ce6ee2026-10-02 — fix(resolving): revalidate release-age upgraded metadata with its full ETag (#16507)