[plugins] npm resolution (PR #3): robust npm pack parse, fetcher-dir contract, docs

[kreneskyp]

Context

feat/npm-source-resolution (PR #3) lands npm source resolution: resolveSource({type:"npm", …}) → resolveNpm → defaultNpmFetcher (npm pack + tar), exact-version caching, version-as-sha pin, plus the npmPackArgs helper and an option-like-package injection guard. It is green (tsc, 100% coverage, eslint, quire) and smoke-tested live (npm pack is-number@7.0.0 resolved + cached). A /code-review pass found the non-blocking items below.

Tasks

• Medium — fragile npm-output parse. defaultNpmFetcher (src/resolve.ts ~lines 54–61) does JSON.parse(out.slice(out.indexOf("[")))[0]. A prepack/prepare script that prints a [ (e.g. [build] done) makes indexOf land on the wrong bracket and the parse throws; if there is no [, indexOf returns -1, slice(-1) yields the last char, and JSON.parse/[0] throw a cryptic error. Fix: parse npm's --json output robustly (e.g. take the last JSON value, or guard idx < 0 / empty-array and throw a descriptive SourceError). Add a test with prepack-style noise / no-bracket output.
• Medium — undocumented fetcher contract. resolveNpm cache-hit (src/resolve.ts ~lines 167–178) returns dir: <cacheDir>/package, ignoring the dir a custom NpmFetcher returned on the miss path. A custom fetcher that extracts elsewhere is authoritative on miss but silently overridden on later resolves. Fix: document that an NpmFetcher MUST extract to <destDir>/package, or persist + read the fetcher's returned dir.
• Low — stale docs (now also npm). Update: resolveSource docstring "git is the only side effect"; ResolveOptions.cacheRoot comment (only mentions <cacheRoot>/git/<key>); ResolvedSource.sha comment "(git sources)". All now also apply to npm sources.
• Low — disk accumulation. The unpinned-spec re-fetch path leaves the prior tarball in cacheDir; clean it up.

Acceptance criteria

• Prepack-noise / no-bracket npm output handled gracefully (descriptive error, with a test).
• Fetcher <destDir>/package contract documented (or the returned dir honored).
• Docstrings updated; src/resolve.ts stays at 100% coverage.

References

• PR: feat: resolve npm sources via npm pack #3 · branch feat/npm-source-resolution
• Spec: spec/functional/FR-004-source-resolution.md
• Related: the option-like-package guard already added in this PR (reqArg in src/sources.ts, FR-004-CON-3) — see the git-hardening issue for extending it to git fields.

[kreneskyp]

Build-out complete — pushed to feat/npm-source-resolution (PR #3), commit dfb3cd6. All four review follow-ups implemented with Red-Green TDD.

• Medium — fragile npm-output parse: extracted pure exported parseNpmPackJson(out) that scans every candidate [ and returns the first parsing to a non-empty JSON array, so prepack/prepare stdout noise (e.g. [build] done) no longer mis-parses; no-bracket / empty-array output now throws a descriptive SourceError instead of a cryptic crash. (+3 tests)
• Medium — fetcher-dir contract: documented on NpmFetcher that a fetcher MUST extract to <destDir>/package, and that an exact-version cache hit serves <cacheDir>/package directly (custom dir honored on miss, ignored on later cached resolves).
• Low — stale docs: resolveSource side-effect note, ResolveOptions.cacheRoot, and ResolvedSource.sha now all cover npm sources.
• Low — disk accumulation: unpinned re-fetch now rmSynces the cache dir before re-extract so stale tarballs don't pile up. (+1 test)

Gates: tests 31 passed (+4) · src/resolve.ts 100% coverage · tsc --noEmit clean · eslint + prettier clean · quire validate clean (pre-existing warnings only).

Note: the make lint wrapper's nested format:check fails on a pre-existing corepack version mismatch (configured pnpm@10.33.4 vs installed 11.5.2) — unrelated; eslint + prettier pass run directly. Worth aligning packageManager.

[kreneskyp]

Merged. PR #3 (npm source resolution + these review follow-ups) squash-merged to main as 4d7b41d. All four follow-ups (robust npm-pack parse, fetcher-dir contract, stale docs, cache hygiene) are in main, plus the spec backsync (FR-004-AC-12/13, CON-4, TC-027/028). First leg of the kit release train done.