@dzhechkov/p-replicator 1.13.3 → 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,5 +1,5 @@
 {
-  "generatedAt": "2026-09-03T05:28:07.394Z",
+  "generatedAt": "2026-09-20T09:34:29.101Z",
   "totalFiles": 167,
   "files": {
     ".claude/agents/doc-validator.md": "e57950758cd4764b2cb54b3f1905567e9dbc1ed20ac6ecd30998614894689f4f",
@@ -25,7 +25,7 @@
     ".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",

package/tests/unit/check-external-deps.test.js

@@ -52,8 +52,12 @@ const check = (files) => run(CHECK, files);
 const GOOD_EVIDENCE = 'https://docs.example.test/email · checked 2026-08-30 · '
   + '«The API reports hard and soft bounces via webhook»';
 
+const EN_HEADER = '| Capability needed | Provider / API | Evidence | Verdict | Requirements relying on it |';
+/** The package writes its documents in Russian, so a Russian header is the TYPICAL case, not a corner. */
+const RU_HEADER = '| Возможность | Провайдер | Свидетельство | Вердикт | Требования |';
+
 /** An Architecture.md whose inventory says what the case needs. */
-function arch({ rows, before = '## Technology Stack\n\n| Layer | Technology | Rationale |\n|---|---|---|\n| Backend | Node | привычен команде |\n', section = true, prose = '' } = {}) {
+function arch({ rows, header = EN_HEADER, before = '## Technology Stack\n\n| Layer | Technology | Rationale |\n|---|---|---|\n| Backend | Node | привычен команде |\n', section = true, prose = '' } = {}) {
   const body = rows === undefined
     ? [['отправка писем', 'Postmark', GOOD_EVIDENCE, 'CONFIRMED', 'FR-010']]
     : rows;
@@ -61,7 +65,7 @@ function arch({ rows, before = '## Technology Stack\n\n| Layer | Technology | Ra
   if (section) {
     out += '## External Dependencies\n\n' + (prose ? prose + '\n\n' : '');
     if (body.length) {
-      out += '| Capability needed | Provider / API | Evidence | Verdict | Requirements relying on it |\n'
+      out += header + '\n'
         + '|---|---|---|---|---|\n'
         + body.map((r) => '| ' + r.join(' | ') + ' |').join('\n') + '\n';
     }
@@ -154,6 +158,26 @@ describe('инвентарь внешних зависимостей — the det
     assert.match(r.out, /FR-011/, 'the dependent requirements must be named, not counted');
   });
 
+  test('P9b - RU/EN twin: the header is recognised by POSITION, so a Russian header is never a data row', () => {
+    // MEASURED 2026-09-02 (backlog b8a7669d): the same table body under a Russian header produced a
+    // FALSE finding «строка инвентаря без вердикта • Возможность» — the header itself was read as a
+    // row — and that false finding fired FIRST, masking the real one. One variable differs between
+    // the twins: the header line. Every outcome below must be identical for both.
+    const clean = [['отправка писем', 'Postmark', GOOD_EVIDENCE, 'CONFIRMED', 'FR-010']];
+    for (const header of [EN_HEADER, RU_HEADER]) {
+      const r = check({ [ARCH]: arch({ rows: clean, header }) });
+      assert.equal(r.code, 0, header + '\n' + r.out);
+      assert.doesNotMatch(r.out, /Возможность|Capability needed/, 'the header must not surface as a row: ' + r.out);
+    }
+    const noVerdict = [['отправка писем', 'Postmark', GOOD_EVIDENCE, '', 'FR-010']];
+    const twins = [EN_HEADER, RU_HEADER].map((header) => check({ [ARCH]: arch({ rows: noVerdict, header }) }));
+    for (const r of twins) {
+      assert.equal(r.code, 1, r.out);
+      assert.match(r.out, /отправка писем/, 'the REAL defective row must be the one named: ' + r.out);
+      assert.doesNotMatch(r.out, /Возможность|Capability needed/, 'the header must not be the finding: ' + r.out);
+    }
+  });
+
   test('P10 - THE second fixture: CONFIRMED without a verbatim quote fails, WITH THE ROW NAMED', () => {
     const r = check({ [ARCH]: arch({ rows: [
       ['отправка писем', 'Postmark', 'https://docs.example.test/email · checked 2026-08-30', 'CONFIRMED', 'FR-010'],

package/tests/unit/detection-ladder-contract.test.js

@@ -4,11 +4,12 @@ const { test } = require('node:test');
 const assert = require('node:assert/strict');
 const { execFileSync } = require('node:child_process');
 const fs = require('node:fs');
-const Module = require('node:module');
 const os = require('node:os');
 const path = require('node:path');
 const { Worker } = require('node:worker_threads');
 
+const { announceNpmSkip, resolveNpmCli } = require('../npm-cli-resolver.js');
+
 const PKG_DIR = path.resolve(__dirname, '..', '..');
 const RULE_DIR = path.join(PKG_DIR, 'templates', '.claude', 'rules');
 const RULE_FILE = 'cost-of-detection-ladder.md';
@@ -18,13 +19,12 @@ const CLI = path.join(PKG_DIR, 'bin', 'cli.js');
 
 const read = (file) => fs.readFileSync(file, 'utf8');
 
-function npmPackDryRunFiles() {
-  const npmCli = process.env.npm_execpath && fs.existsSync(process.env.npm_execpath)
-    ? process.env.npm_execpath
-    : path.join(
-      path.dirname(require.resolve('npm/package.json', { paths: Module.globalPaths })),
-      'bin',
-      'npm-cli.js');
+// FR-3 / ADR-001. The previous line here asked whether `npm_execpath` EXISTS. Under `pnpm test` it
+// points at pnpm.cjs, that file exists, so the fallback never fired in the one case it was written
+// for — and pnpm was then loaded as the npm CLI: `Unknown option: 'dry-run'` (MEASURED 2026-09-18).
+// The resolver asks instead whether the thing at that path IS npm, and falls through to the
+// installed npm when it is not.
+function npmPackDryRunFiles(npmCli) {
   const cache = fs.mkdtempSync(path.join(os.tmpdir(), 'p-rep-npm-pack-cache-'));
 
   return new Promise((resolve, reject) => {
@@ -288,14 +288,24 @@ test('P5 — package runner and scope guards reject omitted and out-of-scope inp
     'a real out-of-scope package path must fire the scope safeguard');
 });
 
-test('A2 — package files include templates and the actual npm pack listing contains the ladder', async () => {
+test('A2 — package files include templates and the actual npm pack listing contains the ladder', async (t) => {
   const pkg = JSON.parse(read(path.join(PKG_DIR, 'package.json')));
   assert.deepEqual(packagingProblems(pkg), []);
   const omitted = JSON.parse(JSON.stringify(pkg));
   omitted.files = omitted.files.filter((entry) => entry !== 'templates/');
   assert.deepEqual(packagingProblems(omitted), ['package files[] omits templates/'],
     'a cloned files[] without templates/ must fire the distribution safeguard');
-  const packedFiles = await npmPackDryRunFiles();
+
+  // FR-4: no npm anywhere is a NAMED skip printed into the suite output, never a silent pass and
+  // never a crash. This test exists to exercise the REAL packer; a faked one would prove nothing.
+  const npmCli = resolveNpmCli(process.env);
+  if (npmCli.kind !== 'npm-cli') {
+    announceNpmSkip(npmCli);
+    t.skip(npmCli.reason);
+    return;
+  }
+
+  const packedFiles = await npmPackDryRunFiles(npmCli.path);
   assert.ok(
     packedFiles.includes(`templates/.claude/rules/${RULE_FILE}`),
     `actual npm pack listing omits templates/.claude/rules/${RULE_FILE}`);

package/tests/unit/insights-writer.test.js

@@ -6,6 +6,7 @@ const { spawnSync } = require('node:child_process');
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const { skipWhenDzAbsent } = require('../dz-availability.js');
 
 const PKG = path.resolve(__dirname, '..', '..');
 const TPL = path.join(PKG, 'templates', '.claude');
@@ -258,7 +259,7 @@ describe('PR-022 harvest insight persistence', () => {
     } finally { cleanup(broken); }
   });
 
-  test('P16b - duplicate replay imports one learned row', () => {
+  test('P16b - duplicate replay imports one learned row', (t) => {
     const { writeInsight, stableTeachText, normalizePayload } = requireWriter();
     const root = tempProject('p-rep-real-dz-teach-');
     try {
@@ -266,6 +267,9 @@ describe('PR-022 harvest insight persistence', () => {
       const first = writeInsight(root, record);
       const replay = writeInsight(root, { ...record, date: '2026-08-31' });
       assert.equal(first.status, 'created');
+      // Backlog 1b4857a6: this case queries the learned rows dz itself stores, so a missing dz is
+      // an audible skip and a broken dz stays red — the rule lives once, in tests/dz-availability.js.
+      if (skipWhenDzAbsent(t, first.teach.state, 'it reads back the learned rows dz stores')) return;
       assert.equal(first.teach.state, 'ok');
       assert.equal(replay.status, 'duplicate');
       assert.equal(replay.teach.state, 'ok');