@dzhechkov/p-replicator 1.13.2 → 1.13.4

package/tests/npm-cli-resolver.js

@@ -0,0 +1,366 @@
+'use strict';
+
+/**
+ * Which npm may a test use? — CommonJS twin of
+ * `packages/@dzhechkov/harness-cli/test/npm-cli-resolver.ts` (ADR-001 of feature
+ * `repo-sweep-honesty`, FR-3 + FR-4).
+ *
+ * WHY A TWIN AND NOT A SHARED HELPER. This package PUBLISHES its `tests/` directory (see the
+ * `files` field of its package.json), so an import reaching outside the package would travel into
+ * the tarball as a broken reference to a file the consumer never receives. The two packages also
+ * live in different module systems — harness-cli is `type: "module"` TypeScript, this one is
+ * CommonJS JavaScript — so one file fit for both does not exist. What is shared instead is the
+ * CONTRACT: `npm-resolver-cases.json`, one byte-identical copy per package, held in step by
+ * `packages/@dzhechkov/harness-core/test/npm-resolver-cases-twin-drift.test.ts`.
+ *
+ * THE DEFECT THIS REPLACES. The previous fallback here read
+ * `npm_execpath && fs.existsSync(npm_execpath) ? npm_execpath : <global npm>`. Under `pnpm test`,
+ * `npm_execpath` is pnpm.cjs; that file EXISTS; so the fallback never fired in the one case it was
+ * written for, and pnpm was loaded as if it were the npm CLI — `Unknown option: 'dry-run'`
+ * (MEASURED 2026-09-18). The question is therefore identity, not existence.
+ *
+ * WHAT "IDENTITY" MEANS HERE — three facts a look-alike cannot borrow together (review r1, HIGH-5):
+ *   1. the candidate is DEREFERENCED first (`realpath`), because a genuine npm is normally reached
+ *      through a symlink (`/usr/bin/npm` -> `../lib/node_modules/npm/bin/npm-cli.js`, MEASURED) and
+ *      resolving modules from `/usr/bin` finds nothing — the real npm was being REJECTED;
+ *   2. the nearest enclosing `package.json` says `"name": "npm"`, because module resolution answers
+ *      a question about a DIRECTORY, so without this any intruder dropped into a tree that contains
+ *      `libnpmpack` was ACCEPTED;
+ *   3. `libnpmpack` resolves from the dereferenced file and lives in the SAME installation.
+ */
+
+const fs = require('node:fs');
+const Module = require('node:module');
+const path = require('node:path');
+
+/** The module whose resolvability IS npm's identity. Nothing else about npm is checked. */
+const NPM_IDENTITY_MODULE = 'libnpmpack';
+
+/** Where npm's CLI entry point sits inside a global module root. */
+const NPM_CLI_RELATIVE_PATH = path.join('npm', 'bin', 'npm-cli.js');
+
+/** The name the enclosing package.json must carry for a file to be part of npm. */
+const NPM_PACKAGE_NAME = 'npm';
+
+/** How far up the tree the enclosing `package.json` is looked for. npm's CLI is 2 levels deep. */
+const PACKAGE_ROOT_SEARCH_DEPTH = 8;
+
+/**
+ * `true` when `child` is `parent` itself or lies underneath it.
+ * @param {string} parent
+ * @param {string} child
+ * @returns {boolean}
+ */
+function isInside(parent, child) {
+  if (!parent || !child) return false;
+  const base = parent.endsWith(path.sep) ? parent.slice(0, -path.sep.length) : parent;
+  return child === base || child.startsWith(base + path.sep);
+}
+
+/**
+ * @param {string} candidate
+ * @returns {string|null}
+ */
+function realPathOrNull(candidate) {
+  try {
+    return fs.realpathSync(candidate);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The directory of the npm PACKAGE that contains `realCandidate`, or `null` when the nearest
+ * enclosing `package.json` belongs to something else (or there is none at all).
+ *
+ * @param {string} realCandidate
+ * @returns {string|null}
+ */
+function npmPackageRoot(realCandidate) {
+  let dir = path.dirname(realCandidate);
+  for (let depth = 0; depth < PACKAGE_ROOT_SEARCH_DEPTH; depth += 1) {
+    const manifest = path.join(dir, 'package.json');
+    if (fs.existsSync(manifest)) {
+      try {
+        const parsed = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+        return parsed && typeof parsed === 'object' && parsed.name === NPM_PACKAGE_NAME ? dir : null;
+      } catch {
+        return null;
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * The dereferenced path of `candidate` when it really is npm's CLI, otherwise `null`.
+ * @param {string|undefined|null} candidate
+ * @returns {string|null}
+ */
+function resolveNpmCliPath(candidate) {
+  if (typeof candidate !== 'string' || candidate === '') return null;
+  if (!fs.existsSync(candidate)) return null;
+  const real = realPathOrNull(candidate);
+  if (real === null) return null;
+
+  const packageRoot = npmPackageRoot(real);
+  if (packageRoot === null) return null;
+
+  let resolved;
+  try {
+    resolved = Module.createRequire(real).resolve(NPM_IDENTITY_MODULE);
+  } catch {
+    return null;
+  }
+  const realResolved = realPathOrNull(resolved) || resolved;
+  // The identity module must belong to the SAME installation: either inside npm's own package, or
+  // hoisted into the `node_modules` directory that holds it.
+  const sameInstall = isInside(packageRoot, realResolved) || isInside(path.dirname(packageRoot), realResolved);
+  return sameInstall ? real : null;
+}
+
+/**
+ * Is the file at `candidate` npm itself? The boolean face of {@link resolveNpmCliPath}.
+ * @param {string|undefined|null} candidate
+ * @returns {boolean}
+ */
+function isNpmCli(candidate) {
+  return resolveNpmCliPath(candidate) !== null;
+}
+
+/**
+ * @param {string[]} roots
+ * @returns {string[]}
+ */
+function dedupe(roots) {
+  const seen = new Set();
+  const unique = [];
+  for (const root of roots) {
+    if (!root) continue;
+    const normalised = path.resolve(root);
+    if (seen.has(normalised)) continue;
+    seen.add(normalised);
+    unique.push(normalised);
+  }
+  return unique;
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string[]}
+ */
+function pathEntries(env) {
+  const raw = typeof env.PATH === 'string' ? env.PATH : (typeof env.Path === 'string' ? env.Path : '');
+  return raw.split(path.delimiter).filter((entry) => entry !== '');
+}
+
+/**
+ * Module roots that come from this MACHINE.
+ *
+ * MEASURED 2026-09-18 and load-bearing: `Module.globalPaths` on this machine is
+ * ['/root/.node_modules', '/root/.node_libraries', '/usr/lib/node'] and does NOT contain
+ * '/usr/lib/node_modules', where npm actually lives. A lookup that trusted `globalPaths` alone
+ * could report "npm not installed" on a machine that has npm, so the layout derived from
+ * `process.execPath` is tried first.
+ *
+ * @param {string} [execPath]
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string[]}
+ */
+function ambientGlobalRoots(execPath, env) {
+  const exec = typeof execPath === 'string' && execPath !== '' ? execPath : process.execPath;
+  const environment = env || process.env;
+  const binDir = path.dirname(exec);
+  const nodePath = typeof environment.NODE_PATH === 'string' ? environment.NODE_PATH : '';
+  return dedupe([
+    path.join(binDir, '..', 'lib', 'node_modules'),
+    path.join(binDir, '..', '..', 'lib', 'node_modules'),
+    path.join(binDir, 'node_modules'),
+    ...nodePath.split(path.delimiter).filter((entry) => entry !== ''),
+    ...Module.globalPaths,
+  ]);
+}
+
+/**
+ * npm's configured install prefix — the same value `npm config get prefix` prints, obtained WITHOUT
+ * spawning npm.
+ *
+ * Why not spawn it: running npm to find npm is circular (on the machine where the answer matters
+ * most the spawn is exactly what fails), and a subprocess inside a resolver every test calls is a
+ * hang risk on a loaded runner. The sources are npm's own, in npm's own order: the
+ * `npm_config_prefix` environment variable, then the user config file (`$npm_config_userconfig`,
+ * else `$HOME/.npmrc`).
+ *
+ * HONEST GAP: npm's builtin and global config files are not read, so a prefix set ONLY in
+ * `/usr/etc/npmrc` is not seen. The env is the only source consulted, never the ambient
+ * `homedir()`, so a caller handing in a bare env gets a deterministic answer.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string|undefined}
+ */
+function npmConfigPrefix(env) {
+  const environment = env || process.env;
+  const direct = environment.npm_config_prefix;
+  if (typeof direct === 'string' && direct !== '') return direct;
+
+  const home = typeof environment.HOME === 'string' && environment.HOME !== ''
+    ? environment.HOME
+    : (typeof environment.USERPROFILE === 'string' ? environment.USERPROFILE : '');
+  const userConfig = typeof environment.npm_config_userconfig === 'string' && environment.npm_config_userconfig !== ''
+    ? environment.npm_config_userconfig
+    : (home ? path.join(home, '.npmrc') : '');
+  if (!userConfig || !fs.existsSync(userConfig)) return undefined;
+
+  try {
+    for (const rawLine of fs.readFileSync(userConfig, 'utf8').split(/\r?\n/)) {
+      const line = rawLine.trim();
+      if (line === '' || line.startsWith('#') || line.startsWith(';')) continue;
+      const match = /^prefix\s*=\s*(.+)$/.exec(line);
+      if (match && match[1] !== undefined) return match[1].trim().replace(/^["']|["']$/g, '');
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Module roots under npm's configured prefix (both the POSIX and the Windows layout).
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string[]}
+ */
+function npmPrefixRoots(env) {
+  const prefix = npmConfigPrefix(env);
+  if (prefix === undefined) return [];
+  return dedupe([path.join(prefix, 'lib', 'node_modules'), path.join(prefix, 'node_modules')]);
+}
+
+/**
+ * Module roots derived from the directories on PATH. A machine whose npm lives under an unrelated
+ * prefix (nvm, asdf, Homebrew, a per-user install) is invisible to `process.execPath` and to
+ * `globalPaths` alike, but its `bin` directory is on PATH by construction.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string[]}
+ */
+function pathRoots(env) {
+  const environment = env || process.env;
+  const roots = [];
+  for (const entry of pathEntries(environment)) {
+    roots.push(path.join(entry, '..', 'lib', 'node_modules'), path.join(entry, 'node_modules'));
+  }
+  return dedupe(roots);
+}
+
+/**
+ * The `npm` executables sitting on PATH. Each is DEREFERENCED and identity-checked, which is what
+ * makes the usual `bin/npm -> ../lib/node_modules/npm/bin/npm-cli.js` symlink a usable answer.
+ *
+ * `npm.cmd` / `npm.ps1` on Windows are batch wrappers, not JavaScript; they are not candidates for
+ * a resolver whose answer is fed to `node <path>`, and they are deliberately not listed.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string[]}
+ */
+function pathNpmExecutables(env) {
+  return pathEntries(env || process.env).map((entry) => path.join(entry, 'npm'));
+}
+
+/**
+ * Every root this resolver would search for a given machine + environment, in order.
+ * @param {string} [execPath]
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string[]}
+ */
+function defaultGlobalRoots(execPath, env) {
+  return dedupe([...ambientGlobalRoots(execPath, env), ...npmPrefixRoots(env), ...pathRoots(env)]);
+}
+
+/**
+ * The ladder, in the one order ADR-001 fixes:
+ *   npm_execpath (only if it IS npm) -> the installed npm -> an honest, named unavailability.
+ *
+ * `options.globalRoots` replaces the AMBIENT roots only; the env-derived roots (npm's configured
+ * prefix, PATH) always apply, because they describe the environment the caller handed in.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {{ globalRoots?: string[] }} [options]
+ * @returns {{kind:'npm-cli', path:string, source:'npm_execpath'|'global-install'}|{kind:'unavailable', reason:string}}
+ */
+function resolveNpmCli(env, options) {
+  const environment = env || process.env;
+  const settings = options || {};
+  const handedOver = environment.npm_execpath;
+
+  const handedOverReal = resolveNpmCliPath(handedOver);
+  if (handedOverReal !== null) {
+    return { kind: 'npm-cli', path: handedOverReal, source: 'npm_execpath' };
+  }
+
+  const roots = dedupe([
+    ...(Array.isArray(settings.globalRoots) ? settings.globalRoots : ambientGlobalRoots(process.execPath, environment)),
+    ...npmPrefixRoots(environment),
+    ...pathRoots(environment),
+  ]);
+  for (const root of roots) {
+    const found = resolveNpmCliPath(path.join(root, NPM_CLI_RELATIVE_PATH));
+    if (found !== null) {
+      return { kind: 'npm-cli', path: found, source: 'global-install' };
+    }
+  }
+
+  const executables = pathNpmExecutables(environment);
+  for (const executable of executables) {
+    const found = resolveNpmCliPath(executable);
+    if (found !== null) {
+      return { kind: 'npm-cli', path: found, source: 'global-install' };
+    }
+  }
+
+  const handedOverNote = typeof handedOver !== 'string' || handedOver === ''
+    ? 'npm_execpath was not set'
+    : `npm_execpath=${handedOver} is not npm (module '${NPM_IDENTITY_MODULE}' does not resolve from it)`;
+  return {
+    kind: 'unavailable',
+    reason: `npm not found: ${handedOverNote}; `
+      + `no '${NPM_CLI_RELATIVE_PATH}' whose '${NPM_IDENTITY_MODULE}' resolves was found under `
+      + `[${roots.join(', ')}]`
+      + `, nor an 'npm' executable on PATH [${executables.join(', ')}]`,
+  };
+}
+
+/**
+ * FR-4 — a skip must be AUDIBLE. A silent `skip` is how a test stops proving anything without
+ * anyone noticing, so the reason (which names the missing tool) is written to the suite's output
+ * before the test steps aside.
+ *
+ * @param {{kind:'unavailable', reason:string}} resolution
+ * @param {((line: string) => void)|null} [write]
+ * @returns {string}
+ */
+function announceNpmSkip(resolution, write) {
+  const emit = typeof write === 'function' ? write : (line) => console.log(line);
+  const line = `SKIPPED — this test needs the real npm packer. ${resolution.reason}`;
+  emit(line);
+  return line;
+}
+
+module.exports = {
+  NPM_IDENTITY_MODULE,
+  NPM_CLI_RELATIVE_PATH,
+  NPM_PACKAGE_NAME,
+  ambientGlobalRoots,
+  announceNpmSkip,
+  defaultGlobalRoots,
+  isNpmCli,
+  npmConfigPrefix,
+  npmPackageRoot,
+  npmPrefixRoots,
+  pathNpmExecutables,
+  pathRoots,
+  resolveNpmCli,
+  resolveNpmCliPath,
+};

package/tests/npm-resolver-cases.json

@@ -0,0 +1,128 @@
+{
+  "contract": "resolveNpmCli(env, options) — ADR-001 of feature repo-sweep-honesty. A test that needs the real npm packer must check the IDENTITY of the tool it was handed, never the existence of a path: under pnpm, npm_execpath points at pnpm.cjs, that file exists, and an existsSync fallback therefore never fires in the one case it was written for (MEASURED 2026-09-18).",
+  "identity": [
+    "A candidate is npm only if ALL THREE hold (review r1, HIGH-5 — the first and third were missing):",
+    "1. the candidate is DEREFERENCED first (realpath), because a genuine npm is normally reached through a symlink (/usr/bin/npm -> ../lib/node_modules/npm/bin/npm-cli.js) and resolving modules from /usr/bin finds nothing;",
+    "2. the nearest enclosing package.json says name == 'npm', because module resolution answers a question about a DIRECTORY — without this, any intruder dropped into a tree that contains libnpmpack passes;",
+    "3. 'libnpmpack' resolves from the dereferenced file AND the module it resolves to lives in the SAME npm installation (inside npm's own package directory, or in the node_modules that holds it)."
+  ],
+  "ladder": [
+    "1. npm_execpath is used only if it passes the identity check above (the answer is the DEREFERENCED path).",
+    "2. otherwise the installed npm is looked up in the global module roots: the ambient machine roots (process.execPath layout, NODE_PATH, module.globalPaths), then npm's configured prefix, then the directories on PATH.",
+    "3. otherwise an 'npm' executable on PATH is dereferenced and identity-checked.",
+    "4. otherwise the answer is 'unavailable' carrying a reason that NAMES the tool that was not found and everywhere it was looked for."
+  ],
+  "twins": [
+    "packages/@dzhechkov/harness-cli/test/npm-resolver-cases.json",
+    "packages/@dzhechkov/p-replicator/tests/npm-resolver-cases.json"
+  ],
+  "twinGuard": "packages/@dzhechkov/harness-core/test/npm-resolver-cases-twin-drift.test.ts keeps the two copies byte-identical. Two implementations exist because p-replicator PUBLISHES its tests/ directory, so it may not import from the repo root; the contract, not the code, is what is shared.",
+  "givenFields": {
+    "npmExecPath": "placeholder name for env.npm_execpath, or null to leave it unset",
+    "globalRoots": "'defaultRoots' to let the resolver pick its own AMBIENT roots, or a list of placeholder names that replaces them",
+    "env": "optional map of extra environment variables; each value is a placeholder name. Env-derived roots (npm's prefix, PATH) apply even when globalRoots is overridden, because they describe the environment handed in rather than the machine",
+    "nullArguments": "optional; when true the resolver is called with explicit nulls for BOTH optional arguments instead of an env object"
+  },
+  "placeholders": {
+    "npmCli": "absolute path to a real npm-cli.js, located WITHOUT the resolver under test",
+    "pnpmCli": "absolute path to a real pnpm.cjs — an existing file that is NOT npm",
+    "decoyCli": "a freshly written .js file that exists and is NOT npm; the fixture that an existence check would wrongly accept",
+    "intruderCli": "a freshly written .js file that is NOT npm but sits in a tree where 'libnpmpack' DOES resolve; the fixture that a resolution-only check would wrongly accept",
+    "npmCliSymlink": "a symlink pointing at the real npm-cli.js; the fixture a resolver that does not dereference would wrongly reject",
+    "npmPrefix": "npm's install prefix, derived from `npm root -g` without the resolver under test",
+    "npmrcHome": "a directory holding a .npmrc whose `prefix=` names npmPrefix",
+    "npmBinDir": "a directory holding a symlink named 'npm' that points at the real npm-cli.js, as a bin directory on PATH does",
+    "missingPath": "an absolute path that does not exist",
+    "emptyRoot": "an existing directory holding no npm installation",
+    "defaultRoots": "the resolver's own ambient global-root list, whatever it is on this machine"
+  },
+  "cases": [
+    {
+      "id": "execpath-that-is-npm-is-used",
+      "why": "the happy path the whole ladder exists to preserve: a real npm hand-off is honoured",
+      "given": { "npmExecPath": "npmCli", "globalRoots": "defaultRoots" },
+      "requires": ["npmCli"],
+      "expect": { "kind": "npm-cli", "source": "npm_execpath", "path": "npmCli" }
+    },
+    {
+      "id": "execpath-that-is-pnpm-is-rejected",
+      "why": "the measured defect: pnpm.cjs exists, so an existence check accepts it and the caller then loads pnpm as if it were npm",
+      "given": { "npmExecPath": "pnpmCli", "globalRoots": "defaultRoots" },
+      "requires": ["npmCli", "pnpmCli"],
+      "expect": { "kind": "npm-cli", "source": "global-install", "path": "npmCli" }
+    },
+    {
+      "id": "execpath-that-is-an-existing-decoy-is-rejected",
+      "why": "machine-independent proof that IDENTITY is checked and not EXISTENCE; this file always exists",
+      "given": { "npmExecPath": "decoyCli", "globalRoots": "defaultRoots" },
+      "requires": ["npmCli"],
+      "expect": { "kind": "npm-cli", "source": "global-install", "path": "npmCli" }
+    },
+    {
+      "id": "intruder-in-a-tree-where-libnpmpack-resolves-is-rejected",
+      "why": "review r1 HIGH-5: resolving libnpmpack proves something about the DIRECTORY, not about the file; without the enclosing-package check any file dropped beside a node_modules/libnpmpack passed as npm",
+      "given": { "npmExecPath": "intruderCli", "globalRoots": "defaultRoots" },
+      "requires": ["npmCli", "intruderCli"],
+      "expect": { "kind": "npm-cli", "source": "global-install", "path": "npmCli" }
+    },
+    {
+      "id": "symlinked-npm-is-dereferenced-and-accepted",
+      "why": "review r1 HIGH-5, the other half: a genuine npm is normally reached through a symlink, and resolving from the symlink's own directory finds nothing — the real npm was being rejected",
+      "given": { "npmExecPath": "npmCliSymlink", "globalRoots": "defaultRoots" },
+      "requires": ["npmCli", "npmCliSymlink"],
+      "expect": { "kind": "npm-cli", "source": "npm_execpath", "path": "npmCli" }
+    },
+    {
+      "id": "execpath-that-does-not-exist-is-rejected",
+      "why": "a stale hand-off must fall through the ladder rather than crash the caller",
+      "given": { "npmExecPath": "missingPath", "globalRoots": "defaultRoots" },
+      "requires": ["npmCli"],
+      "expect": { "kind": "npm-cli", "source": "global-install", "path": "npmCli" }
+    },
+    {
+      "id": "no-execpath-falls-through-to-the-installed-npm",
+      "why": "direct runs (npx vitest run / node --test) set no npm_execpath at all",
+      "given": { "npmExecPath": null, "globalRoots": "defaultRoots" },
+      "requires": ["npmCli"],
+      "expect": { "kind": "npm-cli", "source": "global-install", "path": "npmCli" }
+    },
+    {
+      "id": "npm-config-prefix-from-the-environment-is-searched",
+      "why": "review r1 HIGH-5: an npm installed under an unrelated prefix is invisible to process.execPath and to globalPaths, and was reported absent on a machine that has it",
+      "given": { "npmExecPath": "decoyCli", "globalRoots": ["emptyRoot"], "env": { "npm_config_prefix": "npmPrefix" } },
+      "requires": ["npmCli", "npmPrefix"],
+      "expect": { "kind": "npm-cli", "source": "global-install", "path": "npmCli" }
+    },
+    {
+      "id": "npm-config-prefix-from-the-user-npmrc-is-searched",
+      "why": "the same question `npm config get prefix` answers, read from npm's own user config instead of by spawning npm (spawning the tool you are looking for is circular)",
+      "given": { "npmExecPath": "decoyCli", "globalRoots": ["emptyRoot"], "env": { "HOME": "npmrcHome" } },
+      "requires": ["npmCli", "npmrcHome"],
+      "expect": { "kind": "npm-cli", "source": "global-install", "path": "npmCli" }
+    },
+    {
+      "id": "an-npm-on-PATH-is-found-when-every-root-is-empty",
+      "why": "review r1 HIGH-5: the fallback ignored PATH, yet a bin directory on PATH is how the user runs npm at all; the entry there is a symlink, so this also proves the dereferencing",
+      "given": { "npmExecPath": "decoyCli", "globalRoots": ["emptyRoot"], "env": { "PATH": "npmBinDir" } },
+      "requires": ["npmCli", "npmBinDir"],
+      "expect": { "kind": "npm-cli", "source": "global-install", "path": "npmCli" }
+    },
+    {
+      "id": "explicit-null-arguments-behave-like-omitted-ones",
+      "why": "review r1 LOW-7: a default parameter fires only on undefined, so the TypeScript twin threw on resolveNpmCli(null) while the CommonJS twin fell back to process.env — two twins that disagree on a value a caller can pass are not twins",
+      "given": { "npmExecPath": null, "globalRoots": "defaultRoots", "nullArguments": true },
+      "requires": ["npmCli"],
+      "expect": { "kind": "npm-cli" }
+    },
+    {
+      "id": "no-npm-anywhere-is-an-honest-unavailable",
+      "why": "FR-4: absence is reported with a NAMED reason, never as a pass and never as a crash",
+      "given": { "npmExecPath": "decoyCli", "globalRoots": ["emptyRoot"] },
+      "requires": [],
+      "expect": {
+        "kind": "unavailable",
+        "reasonIncludes": ["npm", "libnpmpack", "npm/bin/npm-cli.js"]
+      }
+    }
+  ]
+}

package/tests/snapshot/baseline.json

@@ -1,6 +1,6 @@
 {
-  "generatedAt": "2026-09-02T07:49:08.074Z",
-  "totalFiles": 166,
+  "generatedAt": "2026-09-20T09:34:29.101Z",
+  "totalFiles": 167,
   "files": {
     ".claude/agents/doc-validator.md": "e57950758cd4764b2cb54b3f1905567e9dbc1ed20ac6ecd30998614894689f4f",
     ".claude/agents/harvest-coordinator.md": "71e524e8379df46bbf457dbc1d4480634e05c99b7d3a4f59a356b8d71a0a4166",
@@ -14,7 +14,7 @@
     ".claude/commands/myinsights.md": "f31c5e133b5027197359e4179cbba1ab535f990634a69ea7c5c73bd2bc329d68",
     ".claude/commands/next.md": "1e4984306c3aa80dfc8734dc1c975dfe5fdf2cf6396ddd759e4c7635646107b8",
     ".claude/commands/plan.md": "6fef889f51168981bf4a98b8392a0d595e3d199e1cfaa8e08c0a181ec6c440e4",
-    ".claude/commands/replicate.md": "165d7b3c0606be6817893b53cbfc5ca55c7b81cbe35cbdd0dccf8679d702e81a",
+    ".claude/commands/replicate.md": "f176d8ec871459b5a8d2111b8527331f34340d6e169da8cc7792953e3e334774",
     ".claude/commands/run.md": "87144dfe8c56c15ba7c117daa544d8a08b84d7205f21dafcc48d27c6c3995059",
     ".claude/commands/start.md": "fb8a7762f4073b9e8689dec3830680907efb9ec68bb2faa39b8a547793d9a078",
     ".claude/hooks/autocommit-insights.cjs": "5e7cef87b24d457f25315d79fe15f0dfaf94d9269495d638817f0faee2593c6f",
@@ -22,9 +22,10 @@
     ".claude/hooks/autocommit-roadmap.cjs": "f4dcc9ffd9a3aed91dd56e011e699fcf8af903cc81594e4ab1ef61e5432a36ad",
     ".claude/hooks/capture-source-path.cjs": "bed92548c3313d69110b6cc06e6b2b858d9d548b8c18c82750ae90d514212bf2",
     ".claude/hooks/check-canon.cjs": "99e6bff9b0078eb2ec23f7df98b7ac06c894f9018eba4a8c358e8f92e5ec7b06",
-    ".claude/hooks/check-docs-complete.cjs": "27c05c2adcedc806e395b30b455243193a4fbd0968ce96e415679e1f78db951a",
+    ".claude/hooks/check-dangling-refs.cjs": "8f012876b1af110a1093319d36a2f84208a15780dbb8abb5a43eb4aeb8f76865",
+    ".claude/hooks/check-docs-complete.cjs": "0f516df0882c9da53d166a1b4e30ff1fc37bd5a2027c7e5fbdab6cba116ca828",
     ".claude/hooks/check-embed-contract.cjs": "9e963a07c12350b760264133021e75fb699439b1f060332e1ccdd962b645b4a0",
-    ".claude/hooks/check-external-deps.cjs": "7bce49a744170a3193edf4b2238bcc5a6f1b0efa29333760a52e4fd145739d18",
+    ".claude/hooks/check-external-deps.cjs": "d671353b2e73e0790206cf963ee85f1ff6b97d56d975b9eb3ad59a14d7239e2a",
     ".claude/hooks/check-file-ownership.cjs": "c6273e7b0817d15e375586131924a08095722aff7d0e6a6a04c857a480788e1f",
     ".claude/hooks/check-growth-trace.cjs": "91994fc109c8440306c9dd3d5eea176c533eb0818fcdb09bac2b309397d9908a",
     ".claude/hooks/check-handoff-manifest.cjs": "768cd0befc0da3adcddcded86ed6d1bd1ac4f25afb563ae578002060a54968cf",
@@ -40,25 +41,25 @@
     ".claude/hooks/check-webhook-contract.cjs": "dfa27bd24cee8868fd60be5d24749c206f303fe4afcc1e72024d526324562a39",
     ".claude/hooks/session-insights.cjs": "31fbe90d81b01dfb56557ed5d68dbde2211a14d5469c5d3761f45fb63c07c3a7",
     ".claude/hooks/state-update.cjs": "47146a76b768ac2273abe8f2f017856a0e28b45afaf90048148da417dd19604e",
-    ".claude/hooks/statusline.cjs": "50c08decec3e80ed325f50d7b062fbe0add47e8594002fcc165248492242ab56",
+    ".claude/hooks/statusline.cjs": "bac385da01dd9f1548d0db48a2acdada5e89a7822a7f0ecfb61cb74ff4cda138",
     ".claude/hooks/write-insight.cjs": "743f2d85b037cf522dfaf4775947b0cd331e52f2f304e88360c160e0e8e9a589",
-    ".claude/rules/cost-of-detection-ladder.md": "f15309ee8f1494478ff7678380dbe8fc8eecd154be36d57c9090cd17126a07da",
-    ".claude/rules/docker-ports.md": "59eb430f29dd762e8b76ad6d1177fe8b5b250de007856c743387cb88ee157942",
+    ".claude/rules/cost-of-detection-ladder.md": "d2e7da3d56c8d4c6d1aa58e793fa0d5eecd65a5c01be38dfa0dc434273306838",
+    ".claude/rules/docker-ports.md": "a9e5bb9a797ea4ef4c0671cee2cbec95f2557f8b9e1d20b84bbcee7ce4c21162",
     ".claude/rules/embeddable-widget.md": "0159224f8e9599b67a860738bb42e3e40adf598176c48ea6c86a01c891f0f18c",
-    ".claude/rules/feature-lifecycle.md": "4e926f84f244feb6824114a0624733738669c93e0508693fa2afa4e9a35c2aa3",
+    ".claude/rules/feature-lifecycle.md": "a7d0adf6bc63b942d3dec339b3ae68972c3dedc0b48a91d27653309c7da7f11f",
     ".claude/rules/git-workflow.md": "7d8d2ded47fcc0fb95da3dc226efa6cb3c80d6adf7296977588c181dfce20192",
     ".claude/rules/honest-configuration.md": "851bc28e9e2baf1043bc09b982f3df3431bc7af1e076f8ff9df3d6729835bad5",
     ".claude/rules/incoming-webhooks.md": "92f3de02814ed0610df644acf554f4b41b2bae2f9d281695e2e217a1d6558e84",
     ".claude/rules/insights-capture.md": "d529e6be79178636ca362d83366b1dd7a843371e8ba4f2b09d65c009fab52dc4",
     ".claude/rules/long-running-job.md": "e6bd0efff89338998d34440a94dc9288cf7bcf790b27bcaa51b83d43f57942ed",
     ".claude/rules/model-call-cost.md": "26c3b20ac3ed7f9cf6deb5e94302ade87f9e3e51fffca7ac2377ff31bc144f34",
-    ".claude/rules/replicate-pipeline.md": "13bf073273820addeb87167402495b2f683cefac70a9f6cb07b6e054b1851e0f",
+    ".claude/rules/replicate-pipeline.md": "9c4bbaa9ac628ec5d4e44d3ace6eec0b5bd602b5dccc5d36f123d73be448f159",
     ".claude/rules/skill-interface-protocol.md": "c3f624d0a8a4c7e0f5744e529eb4486cc0589fdb732b9799bccc75091a6d63ca",
     ".claude/rules/swarm-file-evidence.md": "c71a216dbc3fd633c30949823ceac354f8439b96279a1a8dd606afb1b3ef5c45",
     ".claude/settings.json": "18db09827dce410667b93e2b1a41ef8e46d4431114733e4304a5fc2192b2fc66",
     ".claude/skills/brutal-honesty-review/evals/brutal-honesty-review.yaml": "855c155d55575e12aab23fb3a5fb2fada74d93974ff755dfedac6f2d5bd41f13",
     ".claude/skills/brutal-honesty-review/README.md": "2a026b4af50b21456e50424fbfa089cb983fbbaa0c68024c8c17c695bea25a57",
-    ".claude/skills/brutal-honesty-review/resources/assessment-rubrics.md": "dac09c91c765e2211799cc230738fb72a966f47511edb872306a906e49640cbe",
+    ".claude/skills/brutal-honesty-review/resources/assessment-rubrics.md": "b64894e1ddf8b9da7f2f146c737d35215e7281e3d8be10891d4a9b8aa2bd6d07",
     ".claude/skills/brutal-honesty-review/resources/review-template.md": "95182c8605b1d821360257e1c5dbac4300bda333d861785de417cbb84090b25b",
     ".claude/skills/brutal-honesty-review/schemas/output.json": "2e252a3497b86322e1a6e6bd1aca8708b44389db3a2d81a6f893d467b6351210",
     ".claude/skills/brutal-honesty-review/scripts/assess-code.sh": "2b10d2972b1379adde9a68ddf8bcdb399b7d65075e458a54523ffd8d99ddc746",
@@ -79,7 +80,7 @@
     ".claude/skills/cc-toolkit-generator-enhanced/references/enhanced-recommendations.md": "657e35db0cb77d3a9d1a4d01215a9b8d50441dd863593bee3a84f62aad8b00bc",
     ".claude/skills/cc-toolkit-generator-enhanced/references/extended-mapping.md": "5e87c91956eabc70b4a1084b47b2c9a20ede18bb245735812ead956eafabf3af",
     ".claude/skills/cc-toolkit-generator-enhanced/references/maturity-integration.md": "aa4e743bcd0281525336a298d0489c31481f69ff1a534e1ed1d262d888937deb",
-    ".claude/skills/cc-toolkit-generator-enhanced/references/security-patterns-library.md": "5f1d650c426cbd2c9536b385306605ea62a5a520ee4566d23ca7254409c672a5",
+    ".claude/skills/cc-toolkit-generator-enhanced/references/security-patterns-library.md": "4a7fae9ea1870c30b71c923fd5d3626a8926c5e960209fad709f4b8e0534fc80",
     ".claude/skills/cc-toolkit-generator-enhanced/references/templates/automation-commands.md": "9ce3db4c3c5b9696a312152067c1869b1f421ce77fbcfdca83edaa797c5caf3f",
     ".claude/skills/cc-toolkit-generator-enhanced/references/templates/ddd-agents.md": "c91f81da197a072b57378fd0018eea26c35d909a558bdca6f070eb60153c97b3",
     ".claude/skills/cc-toolkit-generator-enhanced/references/templates/ddd-hooks-commands.md": "8398f2493434db101476300e514a34bf8124a51eb732cf81923f9a5b5a3d5db4",