Patch coverage on the bin-linking PR was 83.41% (70 lines missing) per
codecov. Three sources of gaps:

1. Edge cases I'd skipped: every fallback extension in
   `extension_program`, the `prog: None` arm of `generate_sh_shim`, the
   `path::isAbsolute(shTarget)` branch upstream uses, the lexical
   normalize `..`-past-root and `CurDir` paths, and `parse_shebang`
   empty-prog.

2. pnpm tests not yet ported. Port the ones that translate to pacquet's
   no-`directories.bin` first iteration:
   - `bins/resolver/test/index.ts`: \$-as-command-name, dangerous bin
     names, dangerous bin locations, scoped bin name strip, scoped bin
     name with traversal.
   - `bins/linker/test/index.ts`: idempotent skip when shim already
     points at the same target.

3. Unreachable IO error paths. `search_script_runtime`'s non-`NotFound`
   error path can't be triggered with real fs portably. Apply the
   per-capability DI pattern documented in
   <#332 (comment)>:
   - New `FsReadHead` trait + `RealFs` provider.
   - `search_script_runtime<Fs: FsReadHead>` and `read_shebang<Fs>`
     bind the capability; production callers (`write_shim`) turbofish
     `::<RealFs>`.
   - Tests inject `PermissionDeniedFs` and `EmptyReadFs` to cover the
     propagate-error and zero-bytes-fallthrough paths.
   - New pure `parse_shebang_from_bytes` is independently testable.

Also extract `link_direct_dep_bins` from `SymlinkDirectDependencies::run`
into a free function under `package-manager::link_bins`, so the direct-
dep bin-linking step can be unit-tested without spinning up the
mock-registry-backed install pipeline. Adds five tests for it covering
empty deps, missing manifest, and symlink-followed manifest read.

Test count: cmd-shim 19 → 49, package-manager (lib) 28 → 35.

Future AI agents will routinely hit codecov failures on patches that
add new error-handling code (IO errors, environment-specific branches).
Without a written-down reference they tend to either silence the gap
or add elaborate one-off mocks instead of applying the per-capability
DI pattern this codebase already uses.

Cross-link the two #332 comments that define the pattern:

- Critique of an earlier lumped-trait shape:
  #332 (comment 4344962816)
- Reference implementation and principles:
  #332 (comment 4345054524)

Spell out when the pattern applies (gaps that real-fs fixtures or a
free-function extraction can't close) and when it doesn't (when the
patch already has perfect coverage).

Extends the per-capability DI pattern from \`FsReadHead\` (PR #333) to
the rest of the bin-linking IO surface. New traits in
\`crates/cmd-shim/src/fs_capabilities.rs\`:

- \`FsReadDir\` — list a directory's entries
- \`FsReadFile\` — read a file into Vec<u8>  (package.json reads)
- \`FsReadString\` — read a file into String (warm-skip shim probe)
- \`FsCreateDirAll\` — mkdir -p
- \`FsWriteAtomic\` — write a file replacing if it exists
- \`FsSetPermissions\` — chmod 0o755 / OR-in 0o111

\`RealFs\` provides all of them; \`link_bins\`, \`link_bins_of_packages\`,
\`write_shim\`, \`collect_packages_in_modules_dir\`, and \`read_package\`
take a generic \`Fs: ...\` bound binding only the capabilities they
consume. Production callers (\`InstallWithoutLockfile\`,
\`SymlinkDirectDependencies\`, \`LinkVirtualStoreBins::run\`) turbofish
\`::<RealFs>\`. \`LinkVirtualStoreBins\` keeps a non-generic
\`run\` and exposes \`run_with::<Fs>\` for tests.

Adds five new fakes-injected tests covering error paths real fs can't
trigger portably:

- \`link_bins\` propagates non-NotFound \`read_dir\` failure on
  modules_dir → \`CreateBinDir\` variant
- \`link_bins_of_packages\` propagates \`create_dir_all\` failure →
  \`CreateBinDir\`
- \`link_bins_of_packages\` propagates write failure on the .sh shim →
  \`WriteShim\`
- \`link_bins_of_packages\` propagates chmod failure → \`Chmod\`
- \`LinkVirtualStoreBins::run_with\` propagates non-NotFound read_dir
  failure on the virtual store → \`ReadVirtualStore\`

Each fake is the per-test unit-struct shape documented at
#332 (comment 4345054524) — no \`&self\`, only the
capability methods that get called are non-trivial; the rest are
\`unreachable!()\` to assert the call path.

Test count: cmd-shim 59 → 63, package-manager (lib) 37 → 38.

…main neutrality

Renames the generic parameter and concrete provider type from \`Fs\`/
\`RealFs\` to \`Api\`/\`RealApi\` across pacquet-cmd-shim and the
pacquet-package-manager call sites. Also renames the module
\`fs_capabilities.rs\` -> \`capabilities.rs\`.

The trait names keep their \`Fs\` prefix (\`FsReadDir\`, \`FsReadFile\`,
\`FsReadString\`, \`FsReadHead\`, \`FsCreateDirAll\`, \`FsWriteAtomic\`,
\`FsSetPermissions\`) — domain prefixes belong on traits, not on the
provider.

Reasoning, per the revised DI reference at
#332 (comment 4345054524):

The reference uses \`RealApi\` to model a single provider that
implements every capability the install pipeline needs, regardless
of domain. Crates that today only have fs-side capabilities (this
one, modules-yaml) will likely cross domains in the next milestones
— lifecycle scripts need \`GetNodeExecPath\` or similar, fixture-
based install tests need \`GetCurrentTime\` for \`prunedAt\`. Doing the
rename now avoids a churning rename when the first non-\`Fs*\`
capability lands.

No semantic changes; tests all still pass (cmd-shim 69, package-
manager-lib 38).

The latest revision of the DI reference comment
(#332 issuecomment-4345054524) added principle 6:

> Provider names are domain-neutral; trait names are domain-scoped.
> The generic and its production impl are \`Api\` and \`RealApi\`
> regardless of how many domains they cover.

That principle is about the *production* provider. Test fakes
follow a different rule the same revision spells out:

> Test fakes describe what behaviour they fake, not their provider role.

The upstream example (\`BadYamlFs\`) names a single-trait fake by
behaviour + domain of the trait it fakes. My earlier rename had
turned \`PermissionDeniedFs\` / \`EmptyReadFs\` into
\`PermissionDeniedApi\` / \`EmptyReadApi\` — that was wrong: those
fakes implement only \`FsReadHead\`, not the full provider role,
so the \`Api\` suffix overstates what they do. Revert to the
behaviour+domain shape that matches \`BadYamlFs\`.

Multi-trait fakes (\`FailingProbe\`, \`DenyManifestRead\`, etc.)
already follow behaviour-only naming and don't need a domain
suffix — they describe the failure scenario directly.

Adopt the trait-per-capability dependency-injection pattern from
[`#332`'s reference comment][1] for environment variable
access used by `${VAR}` substitution in `.npmrc`. Replaces the
`Fn(&str) -> Option<String>` closure parameter on `env_replace`,
`NpmrcAuth::from_ini`, and `Npmrc::current` with a single
`Api: EnvVar` bound; production callers turbofish `RealApi`
explicitly.

Why: keep one DI shape across the codebase as filesystem, disk, and
other process-global capabilities follow. Tests carry their fakes as
zero-sized unit structs (per-test scenario data goes in `static`s),
so coverage of every branch still drops out of pure logic without
mutating the real environment.

Also document the principle in `plans/PORTING_GUIDE.md` so future
ports start from the same template.

[1]: #332 (comment)

Resolves #330.

Mirrors pnpm v11's `@pnpm/bins.resolver`, `@pnpm/bins.linker`, and `@zkochan/cmd-shim` (resolved at pnpm `4750fd370c` and cmd-shim `0d79ca9534`):

- New `pacquet-cmd-shim` crate parses the `bin` field of a package manifest into commands. Both `bin: string | object` and the `directories.bin` glob fallback are supported, with the same path-traversal and URL-safe-name guards as upstream. Conflict resolution follows `pkgOwnsBin` + lexical compare.
- Shim generator writes all three flavors per bin: Unix `/bin/sh` (byte-compatible with pnpm's `generateShShim`), Windows `.cmd` (CRLF, `%~dp0` paths), and PowerShell `.ps1` (`$basedir`/`$exe` header with Windows/POSIX-pwsh detection). Mirrors `generateCmdShim` and `generatePwshShim` minus the unused `nodePath`/`prependToPath`/`progArgs` branches.
- All filesystem IO behind per-capability DI traits — `FsReadHead`, `FsReadFile`, `FsReadString`, `FsReadDir`, `FsWalkFiles`, `FsCreateDirAll`, `FsWrite`, `FsSetExecutable`, `FsEnsureExecutableBits` — following the pattern documented in [#332](#332 (comment)). `FsWrite` is a thin shim over `std::fs::write` and is **not atomic**; a future atomic-write capability can build on it without renaming. Production callers turbofish the unit-struct provider `::<RealApi>`; tests inject unit-struct fakes to cover IO error paths real fs can't trigger portably. Generic param is named `Api` (not `Fs`) so the same provider can grow non-fs capabilities without a rename.
- New `LinkVirtualStoreBins` step walks each virtual-store slot and links its child packages' bins into the slot's own `node_modules/.bin`, matching `linkBinsOfDependencies` in pnpm's `building/during-install`. Slot iteration, per-slot child reads, and shim writes parallelised on rayon.
- `SymlinkDirectDependencies` and `InstallWithoutLockfile` call the bin linker after the symlink layout is in place. Direct-dep linking and the symlink loop are exposed as free `link_direct_dep_bins` / `symlink_direct_deps_into_node_modules` functions so they're unit-testable without the mock-registry scaffold.

Tests port the relevant `bins/resolver` and `bins/linker` cases from pnpm (`directories.bin` discovery, scoped bin names, dangerous locations, idempotent shim skip, conflict resolution) and add fakes-injected coverage for the IO error variants.

**Not in this PR**: hoisted-bin precedence and lifecycle-script-created bins. Both depend on subsystems pacquet hasn't built yet — hoisting (`hoistPattern` / `publicHoistPattern` resolution + the lift step) and lifecycle scripts (`exec/lifecycle/` runner + `allowBuilds` plumbing). The bin-linking side already does the right thing for both (shims are paths, so they pick up files generated post-extract; the precedence rule is a small addition once hoisting tags candidates as hoisted). Tracked separately in  with full porting coordinates.



## Performance

When the bin-linking step landed it added ~7% to the warm-cache Frozen Lockfile install ([benchmark](#333 (comment))). Closing that gap took a sequence of changes that mirror how pnpm v11 avoids the same costs in its own `linkBinsOfDependencies` ([4750fd370c](https://github.com/pnpm/pnpm/blob/4750fd370c/building/during-install/src/index.ts#L258-L309)):

- **Bundled manifests in `index.db`.** `extract_tarball_entries` captures the parsed `package.json`, picks the subset pnpm caches via a port of `normalizeBundledManifest` (`name`, `version`, `bin`, `directories`, `dependencies`, lifecycle `scripts`, …), and stuffs it into `PackageFilesIndex.manifest`. `prefetch_cas_paths` surfaces it back as a `HashMap<cache_key, Arc<Value>>` so the bin linker doesn't have to re-read `package.json` per child off disk.
- **msgpackr-records encoder learns `serde_json::Value`.** The encoder previously errored with `ManifestNotSupported` if anything ever set `manifest`; now it records-encodes nested JSON objects (slot-allocated per distinct key set) so `useRecords: true` readers see them as JS `Object`s rather than `Map`s — necessary for pnpm's `manifest.bin` / `manifest.directories?.bin` property accesses to resolve.
- **`Arc<Value>` for `PackageBinSource.manifest`.** The lockfile-driven bin-link path produces `slots × children` clones of the parsed manifest (~6k on the integrated-benchmark fixture). Sharing via `Arc` turns each push into a refcount bump.
- **`hasBin` filter via lockfile.** `LinkVirtualStoreBins` now takes the lockfile `packages:` section, pre-computes an `Option<HashSet<PackageKey>>` of `hasBin: true` keys at install start, and skips snapshot children that aren't in the set *before* any path-building or manifest lookup. ~95% of a real lockfile's packages don't declare a bin, so this short-circuits the bulk of the per-slot work. `None` is reserved for the pathological case where the lockfile lacks a `packages:` section (fall back to processing every child); `Some(empty)` is authoritative — lockfile says no package has a bin, every slot short-circuits. Mirrors pnpm's filter at `building/during-install/src/index.ts:283`.
- **Lockfile-driven slot iteration.** `run_lockfile_driven` walks `snapshots` directly and builds slot paths lexically. The previous `run_with_readdir` path enumerated every slot via `Api::read_dir(virtual_store_dir)` and probed each slot's own package directory with a wasted `read_dir` (~1267 wasted `open(O_DIRECTORY) + close` per warm install). The readdir-driven path survives as a fallback for `install_without_lockfile` and retains the existence probe there (small N, no virtual-store invariant from `create_virtual_dir_by_snapshot` to lean on).
- **Parallel prefetch decode.** `StoreIndex::get_many_raw` returns undecoded row bytes; the SQLite mutex releases before `prefetch_cas_paths` fans the msgpackr decode + integrity check across rayon.

Latest CI benchmark on this branch ([job 75462998251](https://github.com/pnpm/pacquet/actions/runs/25701679172/job/75462998251)):

| Scenario | pacquet@HEAD | pacquet@main | Relative |
|---|---|---|---|
| Frozen Lockfile | 2.074s ± 102ms | 2.026s ± 70ms | +2.4% (within noise) |
| Frozen Lockfile (Hot Cache) | **479.6ms ± 38ms** | **535.8ms ± 37ms** | **~10% faster than main** |

The follow-up #417 splits manifests into a dedicated `package_manifests` SQLite table so the unfiltered `package_index` prefetch payload stays at its original size and the manifest fetch becomes a targeted SELECT against just the `hasBin: true` subset.

---------

Co-authored-by: Zoltan Kochan <z@kochan.io>

)

Slice 2 of #438 (the `nodeLinker: 'hoisted'` umbrella). Smaller than expected — when I looked, the schema field was already in place from #332's original `.modules.yaml` port, so the work reduced to pinning behavior rather than building plumbing.

Two round-trip tests + a doc-comment on the field.

## What was actually missing

The umbrella's §"Pacquet's current state" table claimed `hoistedLocations` was "Missing entirely" — that was wrong. The field is at `crates/modules-yaml/src/lib.rs:212` and serde-handles read/write correctly. What was missing:

- **A test pinning the wire shape.** Nothing was stopping a future edit from breaking the camelCase mapping, the optional-with-skip-on-None behavior, or the `Record<string, string[]>` shape upstream relies on.
- **A doc-comment** explaining what the field is for. Other Slice-related fields (`hoisted_dependencies`, `hoisted_aliases`) have full docstrings; this one was silent.

## Tests added

Both live in `crates/modules-yaml/tests/real_fs.rs` (pacquet-side, no upstream counterpart — upstream's `installing/modules-yaml/test/index.ts` doesn't exercise `hoistedLocations` directly):

- `hoisted_locations_round_trips` — a manifest with `hoistedLocations` populated survives write+read; the raw on-disk JSON keeps the per-depPath array shape (multi-entry arrays included, to pin the nested-conflict layout).
- `absent_hoisted_locations_is_omitted_on_write` — `None` (the state every pacquet install writes today) serializes as the field *absent* from the file, matching upstream's `JSON.stringify(undefined)` behavior. Guards against accidental `Option::is_some` regressions on the `skip_serializing_if`.

## Regression catch verified

Per `plans/TEST_PORTING.md`'s "break the subject to verify the test catches it" convention, I temporarily added `#[serde(rename = "wrongName")]` to the field. `hoisted_locations_round_trips` failed at the `expect("present")` on the deserialized value (the camelCase key no longer mapped). Reverted before commit.

## Type-shape decision

Upstream's actual `ModulesRaw.hoistedLocations` is `Record<string, string[]> | undefined` — *not* `Record<DepPath, string[]>` despite the values being populated from depPaths internally. The umbrella's scope item ("`Option<BTreeMap<DepPath, Vec<String>>>`") was inconsistent with the upstream schema; I kept the existing `BTreeMap<String, Vec<String>>` because:

1. It already matches the upstream wire shape exactly.
2. Same pattern as the `hoisted_dependencies` field below, which deliberately keeps `String` keys (per its doc-comment at lines 148-153) because pnpm's `DepPath | ProjectId` union can't be statically disambiguated.