@mindrian_os/cli 2.0.0-beta.3 → 2.0.0-beta.31

package/lib/core/node-insert.cjs

@@ -0,0 +1,274 @@
+'use strict';
+/*
+ * Phase 140-01 -- node-insert: the ONE shared NOT-NULL-safe node-insert helper.
+ * Extended R17-01 (260903-gdm): insertNode is now the SINGLE node-write
+ * chokepoint for production code (Canon Part 7 reuse-before-build, D-02).
+ * Every production `INSERT INTO nodes` outside two named exclusions
+ * (`lib/core/navigation/memory-events.cjs` append-only bookkeeping dedupe,
+ * `lib/core/rs-sqlite-mirror.cjs` bulk-write hot path) routes through here.
+ *
+ * HARD-02 root cause: the bare 3-column upsert
+ *   INSERT INTO nodes (id, type, properties) VALUES (?, ?, ?) ON CONFLICT(id) ...
+ * fails on a Phase-109-migrated room.db with
+ *   `NOT NULL constraint failed: nodes.source_path`
+ * because the migration (lib/core/migrations/phase-109-nodes-provenance.cjs)
+ * tightened the nodes table with four NOT NULL provenance columns
+ * (source_path, created_by, created_at, last_seen_at) plus a CHECK constraint
+ * on created_by. The legacy bare insert omits all four.
+ *
+ * Both-schema safety (D-02a): a migrated db requires the wide insert; an
+ * un-migrated 3-col db (the current dogfood room) rejects the wide insert
+ * (no such column). So insertNode detects the schema once via
+ * PRAGMA table_info(nodes) and builds the correct column-set:
+ *   - migrated  -> wide NOT-NULL insert with the provenance scalars
+ *   - un-migrated -> legacy 3-column insert
+ *
+ * Provenance values for these system-written nodes (per RESEARCH HARD-02 +
+ * lib/core/navigation/evidence-claim.cjs:110 correct pattern):
+ *   source_path:   'system:hsi-to-graph'   (a synthetic handle, not a real path)
+ *   created_by:    'system'                (satisfies the Phase-109 CHECK:
+ *                                           one of user/larry/import/brain/system)
+ *   review_status: DEFAULT 'proposed'      (left to the column DEFAULT, or
+ *                                           the opts.review_status override)
+ *   confidence:    NULL unless opts.confidence is a number
+ *   created_at:    Date.now()
+ *   last_seen_at:  Date.now()
+ *
+ * R17-01 overrides (all optional, all fail closed on an invalid value):
+ *   opts.confidence:    number -> bound `confidence` column; omitted -> NULL
+ *   opts.review_status: one of the eight Phase-109 CHECK enum members
+ *                        ('proposed','confirmed','rejected','stale',
+ *                        'superseded','needs_evidence','validated',
+ *                        'invalidated'); a non-empty out-of-enum string
+ *                        THROWS before prepare(). Omitted -> column DEFAULT.
+ *   opts.on_conflict:   'update' (default, existing DO UPDATE clause) or
+ *                        'nothing' (DO NOTHING; an existing row is left
+ *                        byte-identical). Any other value THROWS.
+ * Column NAMES are never caller-supplied (T-R17-01): the column list is
+ * built from fixed literals gated on typeof/set-membership checks, never
+ * from a caller string. Every caller value binds as a `?` parameter.
+ *
+ * On the legacy un-migrated 3-column schema, confidence / review_status /
+ * on_conflict-as-a-column are moot (there are no such columns to write); the
+ * legacy INSERT branch itself is otherwise unchanged from its pre-R17 shape.
+ *
+ * R17-02 (260903-gdm Task 5): `opts.epistemic_type` is REQUIRED (no default)
+ * and validated against the closed ALLOWED_EPISTEMIC_TYPES enum ('observation',
+ * 'extracted_fact', 'derived_fact', 'model_derived_assertion', 'interpretation',
+ * 'hypothesis', 'assumption', 'conclusion', 'recommendation', 'decision')
+ * BEFORE any other work in insertNode, including before isMigratedSchema() and
+ * before any prepare() -- mirrors writeEdge's edge_type gate structurally.
+ * Absent, non-string, or out-of-enum THROWS. Storage (Task 4 Decision 3):
+ * merged into the properties JSON blob, NOT a new column -- no schema
+ * migration, applies uniformly on BOTH schemas (properties is a column on
+ * both). A caller-supplied properties.epistemic_type key is always
+ * overridden by the validated value (protected-key discipline, mirrors
+ * typed-claim.cjs's PROTECTED_CLAIM_KEYS), never the other way around.
+ *
+ * Canon Part 9: these are SYSTEM-BOOKKEEPING graph nodes (Section / Artifact /
+ * CausalClaim / WhitespaceZone written by the HSI + indexer pipelines), not
+ * human truth-claims, so created_by='system' is canon-legal (Part 9
+ * audit-node carve-out spirit -- the system wrote them, no human byUser needed
+ * to reach the system-set status).
+ *
+ * Canon Part 8: zero network surface. Pure LOCAL SQLite over a caller-owned
+ * conn handle. node-insert NEVER opens room.db itself (it receives the conn),
+ * so it does not trip the room-db.cjs navigation-bypass audit and stays a
+ * thin, dependency-free insert primitive.
+ *
+ * Named coverage gaps (NOT closed by this chokepoint, per the ratified R17
+ * exclusions): `lib/core/navigation/memory-events.cjs:772` (append-only
+ * bookkeeping dedupe contract, only ever writes `memory_event` nodes) and
+ * `lib/core/rs-sqlite-mirror.cjs:407` (bulk-write hot path; a per-row
+ * insertNode call would add a `PRAGMA table_info(nodes)` round trip per row).
+ * Nodes written by these two files carry no chokepoint-validated data.
+ *
+ * NO em-dashes anywhere in this file (CLAUDE.md HARD RULE).
+ */
+
+// The four provenance columns the Phase-109 migration adds as NOT NULL.
+// source_path / created_by / created_at / last_seen_at are NOT NULL; if all
+// are present we are on the migrated (wide) schema and must supply them.
+const MIGRATED_MARKER_COLUMN = 'source_path';
+
+// System provenance defaults for HSI / indexer node writes.
+const SYSTEM_SOURCE_PATH = 'system:hsi-to-graph';
+const SYSTEM_CREATED_BY = 'system';
+
+// Mirrors the eight-member Phase-109 CHECK constraint at
+// lib/core/migrations/phase-109-nodes-provenance.cjs:300. This is a WIDER
+// set than edges.cjs's two-member VALID_REVIEW_STATUS; they govern
+// different tables and must not be conflated or shared.
+const VALID_REVIEW_STATUS = Object.freeze(new Set([
+  'proposed', 'confirmed', 'rejected', 'stale',
+  'superseded', 'needs_evidence', 'validated', 'invalidated',
+]));
+
+const VALID_ON_CONFLICT = Object.freeze(new Set(['update', 'nothing']));
+
+// R17-02 (260903-gdm Task 5): the closed epistemic_type enum, mirroring the
+// edges.cjs ALLOWED_EDGE_TYPES structural precedent. Navigator-approved
+// (Task 4, Decision 4) per-writer mapping lives in each call site's
+// insertNode(...) call, not here; this Set is only the fail-closed gate.
+const ALLOWED_EPISTEMIC_TYPES = Object.freeze(new Set([
+  'observation', 'extracted_fact', 'derived_fact', 'model_derived_assertion',
+  'interpretation', 'hypothesis', 'assumption', 'conclusion',
+  'recommendation', 'decision',
+]));
+
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+// Merge the validated epistemic_type into the caller's properties JSON blob
+// (Task 4 Decision 3: properties JSON, no schema migration, no new column).
+// Protected-key discipline (mirrors typed-claim.cjs's PROTECTED_CLAIM_KEYS):
+// epistemic_type is set AFTER parsing, so a caller-supplied
+// properties.epistemic_type can NEVER shadow the validated value.
+function mergeEpistemicType(propertiesJson, epistemicType) {
+  let obj;
+  try {
+    const parsed = JSON.parse(propertiesJson);
+    obj = isPlainObject(parsed) ? parsed : {};
+  } catch (_e) {
+    throw new Error('insertNode: properties must be valid JSON to merge epistemic_type');
+  }
+  obj.epistemic_type = epistemicType;
+  return JSON.stringify(obj);
+}
+
+/**
+ * Detect whether the nodes table carries the Phase-109 provenance columns.
+ * Robust to both schemas (D-02a). Defensive: any PRAGMA failure falls back to
+ * the legacy 3-column shape (the wider insert would throw on a real legacy db,
+ * so defaulting to legacy is the safe choice).
+ * @param {{prepare: Function}} conn - node:sqlite DatabaseSync (or compatible)
+ * @returns {boolean} true if the migrated (wide) schema is present
+ */
+function isMigratedSchema(conn) {
+  try {
+    const cols = conn.prepare('PRAGMA table_info(nodes)').all();
+    return cols.some((c) => c && c.name === MIGRATED_MARKER_COLUMN);
+  } catch (_e) {
+    return false;
+  }
+}
+
+/**
+ * NOT-NULL-safe node upsert. The single node-write chokepoint (R17-01):
+ * every production `INSERT INTO nodes` outside the two named exclusions
+ * routes through this function so the whole HARD-02 bug-class is fixed once
+ * (D-02 + D-02a), and so confidence / review_status / on_conflict can be
+ * expressed at the call site without a raw INSERT.
+ *
+ * Preserves the existing ON CONFLICT(id) DO UPDATE upsert semantics by
+ * default: re-inserting an existing id updates type + properties (and
+ * refreshes last_seen_at on the migrated schema) rather than creating a
+ * duplicate. review_status and confidence are NEVER touched by the DO
+ * UPDATE clause (the no-downgrade contract: a human-confirmed node is never
+ * silently downgraded by a system re-projection).
+ *
+ * @param {{prepare: Function}} conn - node:sqlite DatabaseSync (or compatible)
+ * @param {string} id - node id (primary key)
+ * @param {string} type - node type (Section / Artifact / CausalClaim / ...)
+ * @param {string} properties - JSON-serialized properties bag
+ * @param {object} [overrides] - optional provenance / write-shape overrides
+ * @param {string} [overrides.source_path] - default 'system:hsi-to-graph'
+ * @param {string} [overrides.created_by] - default 'system'
+ *   (MUST be one of user/larry/import/brain/system per the Phase-109 CHECK)
+ * @param {number} [overrides.confidence] - bound `confidence` column value;
+ *   omitted (or non-number) leaves the column NULL
+ * @param {string} [overrides.review_status] - one of the eight Phase-109
+ *   CHECK enum members; omitted leaves the column DEFAULT ('proposed'); an
+ *   out-of-enum non-empty string THROWS before prepare()
+ * @param {string} [overrides.on_conflict] - 'update' (default) or 'nothing';
+ *   any other value THROWS before prepare()
+ * @param {string} overrides.epistemic_type - REQUIRED (R17-02). One of
+ *   ALLOWED_EPISTEMIC_TYPES ('observation', 'extracted_fact', 'derived_fact',
+ *   'model_derived_assertion', 'interpretation', 'hypothesis', 'assumption',
+ *   'conclusion', 'recommendation', 'decision'). Absent, non-string, or
+ *   out-of-enum THROWS before prepare(), with no default. Stored inside the
+ *   properties JSON blob (Task 4 Decision 3: no schema migration, no new
+ *   column); a caller-supplied properties.epistemic_type key is always
+ *   overridden by this validated value, never the other way around.
+ * @returns {void}
+ * @throws {Error} if epistemic_type, review_status, or on_conflict is
+ *   missing (epistemic_type only) or present but invalid
+ *
+ * NOT closed by this chokepoint (named coverage gaps, per the ratified R17
+ * exclusions): nodes written by lib/core/navigation/memory-events.cjs and
+ * lib/core/rs-sqlite-mirror.cjs carry NO validated epistemic_type.
+ */
+function insertNode(conn, id, type, properties, overrides) {
+  const opts = overrides || {};
+  const sourcePath = typeof opts.source_path === 'string' ? opts.source_path : SYSTEM_SOURCE_PATH;
+  const createdBy = typeof opts.created_by === 'string' ? opts.created_by : SYSTEM_CREATED_BY;
+
+  // R17-02: epistemic_type is REQUIRED and validated FIRST, before any other
+  // work, before isMigratedSchema(), and before any prepare(). Fail closed;
+  // mirrors the writeEdge edge_type gate in navigation/edges.cjs. Required
+  // means required; there is no default.
+  if (typeof opts.epistemic_type !== 'string' || !ALLOWED_EPISTEMIC_TYPES.has(opts.epistemic_type)) {
+    throw new Error('insertNode: invalid epistemic_type ' + JSON.stringify(String(opts.epistemic_type).slice(0, 40)));
+  }
+  properties = mergeEpistemicType(properties, opts.epistemic_type);
+
+  // Fail closed before any prepare(). Do not let SQLite's CHECK constraint
+  // be the only guard (mirrors the writeEdge precedent in navigation/edges.cjs).
+  const hasReviewStatus = opts.review_status !== undefined && opts.review_status !== null && opts.review_status !== '';
+  if (hasReviewStatus && (typeof opts.review_status !== 'string' || !VALID_REVIEW_STATUS.has(opts.review_status))) {
+    throw new Error('insertNode: invalid review_status ' + JSON.stringify(String(opts.review_status).slice(0, 40)));
+  }
+  const onConflict = opts.on_conflict === undefined || opts.on_conflict === null ? 'update' : opts.on_conflict;
+  if (!VALID_ON_CONFLICT.has(onConflict)) {
+    throw new Error('insertNode: invalid on_conflict ' + JSON.stringify(String(onConflict).slice(0, 40)));
+  }
+  const hasConfidence = typeof opts.confidence === 'number';
+
+  if (isMigratedSchema(conn)) {
+    // Wide NOT-NULL insert. Build the column list dynamically, keeping the
+    // placeholder list and the bound-parameter array in lockstep so a
+    // future column cannot drift out of order.
+    const now = Date.now();
+    const columns = ['id', 'type', 'properties', 'source_path', 'created_by', 'created_at', 'last_seen_at'];
+    const params = [id, type, properties, sourcePath, createdBy, now, now];
+    if (hasConfidence) {
+      columns.push('confidence');
+      params.push(opts.confidence);
+    }
+    if (hasReviewStatus) {
+      columns.push('review_status');
+      params.push(opts.review_status);
+    }
+    const placeholders = columns.map(() => '?').join(', ');
+    const conflictClause = onConflict === 'nothing'
+      ? 'ON CONFLICT(id) DO NOTHING'
+      : 'ON CONFLICT(id) DO UPDATE SET ' +
+        'type = excluded.type, properties = excluded.properties, ' +
+        'last_seen_at = excluded.last_seen_at';
+    conn.prepare(
+      'INSERT INTO nodes (' + columns.join(', ') + ') VALUES (' + placeholders + ') ' + conflictClause
+    ).run(...params);
+    return;
+  }
+
+  // Legacy un-migrated 3-column schema. There are no confidence /
+  // review_status columns to write, so the three new overrides are silently
+  // ignored here; this branch stays exactly as it was pre-R17. on_conflict
+  // is still honored since it only changes the conflict clause shape.
+  const legacyConflictClause = onConflict === 'nothing'
+    ? 'ON CONFLICT(id) DO NOTHING'
+    : 'ON CONFLICT(id) DO UPDATE SET type = excluded.type, properties = excluded.properties';
+  conn.prepare(
+    'INSERT INTO nodes (id, type, properties) VALUES (?, ?, ?) ' + legacyConflictClause
+  ).run(id, type, properties);
+}
+
+module.exports = {
+  insertNode,
+  isMigratedSchema,
+  SYSTEM_SOURCE_PATH,
+  SYSTEM_CREATED_BY,
+  VALID_REVIEW_STATUS,
+  ALLOWED_EPISTEMIC_TYPES,
+};

package/lib/core/npm-cli-resolve.cjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * MindrianOS Plugin -- portable npm CLI resolution (debug session
+ * mcp-servers-cache-missing-node-modules, escalated mandate 2026-05-21).
+ *
+ * THE PROBLEM (code review of the prior Option D fix, commit f6cafe74):
+ * The self-heal and the SessionStart reconcile hook both ran
+ * `spawnSync('npm', ['install', ...])`. That bare invocation is NOT
+ * cross-platform:
+ *   - WINDOWS: `npm` is `npm.cmd` (a batch file). spawnSync('npm') with no
+ *     shell:true and no .cmd suffix returns ENOENT -- the heal silently does
+ *     nothing. On Windows the node_modules gap then NEVER heals.
+ *   - MAC: even with the .cmd issue aside, spawnSync('npm') depends on `npm`
+ *     being on the child process PATH. A GUI-launched (Dock/Finder) Claude
+ *     Code gives child processes a minimal PATH that frequently excludes the
+ *     nvm / Homebrew bin directory where `npm` lives -- same ENOENT, different
+ *     cause. `shell:true` does NOT fix this (it does not add the missing dir
+ *     to PATH).
+ *
+ * THE FIX (this module): resolve npm to an ABSOLUTE path, independent of PATH
+ * and independent of the platform file extension.
+ *
+ * The key insight: npm ships in the SAME distribution as the `node` binary
+ * already executing this code. `process.execPath` is the absolute path to
+ * that node binary. npm's real entry point is a plain JavaScript file --
+ * `npm-cli.js` -- which lives at a fixed location relative to the node binary:
+ *   - POSIX  (Linux, Mac): <nodeBinDir>/../lib/node_modules/npm/bin/npm-cli.js
+ *   - WINDOWS:              <nodeBinDir>/node_modules/npm/bin/npm-cli.js
+ * Running `node <absolute npm-cli.js> install ...` invokes npm directly with
+ * the SAME node binary, sidestepping PATH, the .cmd extension, and shell:true
+ * entirely. This is correct by construction on Windows, Mac, and Linux.
+ *
+ * Fallback: if npm-cli.js cannot be located off process.execPath (an unusual
+ * layout -- a system-package node, a relocated install), the resolver returns
+ * a PATH-based spawn descriptor that DOES carry the Windows .cmd handling
+ * (shell:true on win32) so the backstop is still better than the bare
+ * pre-fix invocation.
+ *
+ * Canon Part 8: zero network surface. Pure node built-ins. This module only
+ * computes a spawn descriptor; the caller runs `npm install`.
+ *
+ * HARD RULE: no em-dashes anywhere in this file (hyphens only).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const IS_WINDOWS = process.platform === 'win32';
+
+/**
+ * Candidate absolute locations of npm's JavaScript entry point (npm-cli.js),
+ * derived from the directory of the currently-running node binary.
+ *
+ * Node distributions place npm consistently:
+ *   - POSIX tarball / nvm / Homebrew / Volta:
+ *       bin/node  +  lib/node_modules/npm/bin/npm-cli.js
+ *   - Windows zip / installer:
+ *       node.exe  +  node_modules/npm/bin/npm-cli.js   (same dir as node.exe)
+ *
+ * Both layouts are probed on every platform (a defensive superset) so a
+ * non-standard packaging still resolves if npm is present anywhere npm
+ * normally ships.
+ *
+ * @param {string} [execPath] - override for process.execPath (tests)
+ * @returns {string[]} absolute candidate paths, most-likely first
+ */
+function npmCliCandidates(execPath) {
+  const nodeBin = path.dirname(execPath || process.execPath);
+  return [
+    // Windows-style: npm sits beside node.exe.
+    path.join(nodeBin, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    // POSIX-style: npm sits one level up under lib/.
+    path.join(nodeBin, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    // Some Windows installs nest under a node_modules/npm with a lib prefix.
+    path.join(nodeBin, '..', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+  ];
+}
+
+/**
+ * Resolve a portable, absolute spawn descriptor for `npm install`.
+ *
+ * Preferred result (strategy 'node-npm-cli'):
+ *   { command: process.execPath, baseArgs: [<abs npm-cli.js>], shell: false }
+ * Run npm by feeding its JS entry point to the current node binary. No PATH
+ * dependency, no .cmd extension, no shell. Correct on Windows, Mac, Linux.
+ *
+ * Fallback result (strategy 'path-npm'):
+ *   { command: 'npm', baseArgs: [], shell: true on win32 else false }
+ * Used only when npm-cli.js is not found off process.execPath. shell:true is
+ * set on Windows so the OS resolves `npm` -> `npm.cmd` (still better than the
+ * pre-fix bare spawn, though it remains PATH-dependent).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.execPath] - override process.execPath (tests)
+ * @returns {{command:string, baseArgs:string[], shell:boolean, strategy:string, npmCli:(string|null)}}
+ */
+function resolveNpmCli(opts) {
+  opts = opts || {};
+  const candidates = npmCliCandidates(opts.execPath);
+  for (const candidate of candidates) {
+    try {
+      if (fs.existsSync(candidate)) {
+        return {
+          command: opts.execPath || process.execPath,
+          baseArgs: [candidate],
+          shell: false,
+          strategy: 'node-npm-cli',
+          npmCli: candidate,
+        };
+      }
+    } catch (_) {
+      // stat failure on a candidate -- try the next one.
+    }
+  }
+  // Fallback: npm-cli.js not locatable. PATH-based spawn, with Windows .cmd
+  // handling via shell:true. Still an improvement over the bare pre-fix call.
+  return {
+    command: 'npm',
+    baseArgs: [],
+    shell: IS_WINDOWS,
+    strategy: 'path-npm',
+    npmCli: null,
+  };
+}
+
+/**
+ * Build the full argv for `npm install` (production-safe, quiet, no scripts
+ * surprises) given a resolved descriptor from resolveNpmCli().
+ *
+ * @param {{baseArgs:string[]}} descriptor
+ * @param {string[]} [installArgs] - npm args after `install`; defaults to the
+ *                                   quiet production set used by the heal path.
+ * @returns {string[]} argv to pass as the second arg of spawnSync(command, argv)
+ */
+function buildInstallArgs(descriptor, installArgs) {
+  const tail = Array.isArray(installArgs) && installArgs.length
+    ? installArgs
+    : ['--no-audit', '--no-fund', '--silent'];
+  return descriptor.baseArgs.concat(['install'], tail);
+}
+
+module.exports = {
+  resolveNpmCli,
+  buildInstallArgs,
+  npmCliCandidates,
+  IS_WINDOWS,
+};

package/lib/core/npm-cli-resolve.test.cjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Regression tests for lib/core/npm-cli-resolve.cjs -- portable npm CLI
+ * resolution (debug session mcp-servers-cache-missing-node-modules, escalated
+ * mandate 2026-05-21).
+ *
+ * The prior Option D fix (commit f6cafe74) ran a bare `spawnSync('npm', ...)`
+ * that was DEAD on Windows (npm is npm.cmd) and FRAGILE on Mac (PATH gap for
+ * GUI-launched Claude Code). These tests lock the cross-platform contract:
+ *
+ *   Test 1: resolveNpmCli on the test host returns the 'node-npm-cli' strategy
+ *           and the resolved npm-cli.js actually exists.
+ *   Test 2: the resolved command equals process.execPath (the current node
+ *           binary) -- NOT the literal string 'npm'. This is what makes it
+ *           PATH-independent.
+ *   Test 3: WINDOWS layout -- npmCliCandidates for a win32-style execPath puts
+ *           `<nodeBinDir>/node_modules/npm/bin/npm-cli.js` first (where the
+ *           Windows node installer ships npm). No `.cmd` anywhere in the argv.
+ *   Test 4: buildInstallArgs produces `[<npm-cli.js>] install --no-audit
+ *           --no-fund --silent` for the node-npm-cli strategy.
+ *   Test 5: the fallback descriptor (path-npm) sets shell:true ONLY on win32,
+ *           so even the fallback carries Windows .cmd handling.
+ *   Test 6: no em-dashes in npm-cli-resolve.cjs (HARD RULE).
+ *   Test 7: the argv never contains the bare token 'npm' as command on the
+ *           node-npm-cli strategy -- proves PATH is not relied upon.
+ *
+ * HARD RULE: no em-dashes.
+ */
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const MODULE_PATH = path.join(REPO_ROOT, 'lib', 'core', 'npm-cli-resolve.cjs');
+const { resolveNpmCli, buildInstallArgs, npmCliCandidates } = require(MODULE_PATH);
+
+let passed = 0;
+let failed = 0;
+
+function ok(name) {
+  passed += 1;
+  process.stdout.write('  ok ' + name + '\n');
+}
+function fail(name, err) {
+  failed += 1;
+  process.stdout.write('  FAIL ' + name + '\n');
+  process.stdout.write('    ' + (err && err.message ? err.message : String(err)) + '\n');
+}
+function test(name, fn) {
+  try { fn(); ok(name); } catch (err) { fail(name, err); }
+}
+
+// Test 1 -- node-npm-cli strategy on the test host, npm-cli.js exists.
+test('resolveNpmCli returns node-npm-cli strategy with a real npm-cli.js', () => {
+  const r = resolveNpmCli();
+  assert.equal(r.strategy, 'node-npm-cli', 'expected node-npm-cli strategy on a normal node install');
+  assert.ok(r.npmCli, 'npmCli path should be set');
+  assert.ok(fs.existsSync(r.npmCli), 'resolved npm-cli.js must exist on disk: ' + r.npmCli);
+});
+
+// Test 2 -- command is the node binary, not the literal 'npm'.
+test('resolveNpmCli command is process.execPath (PATH-independent)', () => {
+  const r = resolveNpmCli();
+  assert.equal(r.command, process.execPath, 'command must be the current node binary');
+  assert.notEqual(r.command, 'npm', 'command must NOT be the bare PATH-dependent string npm');
+  assert.equal(r.shell, false, 'node-npm-cli strategy needs no shell');
+});
+
+// Test 3 -- Windows layout: npm-cli.js beside node.exe is the first candidate.
+test('npmCliCandidates puts the Windows-layout path first', () => {
+  // path.win32 mirrors what require('path') resolves to on a real Windows host.
+  const winExec = 'C:\\Program Files\\nodejs\\node.exe';
+  const cands = npmCliCandidates(winExec);
+  assert.ok(Array.isArray(cands) && cands.length >= 3, 'expected >= 3 candidates');
+  // The first candidate is the <nodeBinDir>/node_modules/npm/bin/npm-cli.js
+  // layout -- exactly where the Windows node installer ships npm.
+  assert.ok(
+    cands[0].indexOf('node_modules') !== -1 && cands[0].indexOf('npm-cli.js') !== -1,
+    'first candidate must target node_modules/npm/bin/npm-cli.js'
+  );
+  // No candidate is a .cmd file -- we always run the JS entry point directly.
+  for (const c of cands) {
+    assert.ok(c.indexOf('.cmd') === -1, 'no candidate may be a .cmd batch file: ' + c);
+  }
+});
+
+// Test 4 -- buildInstallArgs argv shape for the node-npm-cli strategy.
+test('buildInstallArgs produces [npm-cli.js] install ...quiet-flags', () => {
+  const r = resolveNpmCli();
+  const argv = buildInstallArgs(r);
+  assert.equal(argv[0], r.npmCli, 'first arg must be the npm-cli.js path');
+  assert.equal(argv[1], 'install', 'second arg must be install');
+  assert.deepEqual(
+    argv.slice(2),
+    ['--no-audit', '--no-fund', '--silent'],
+    'default install args must be the quiet production set'
+  );
+  // A custom install-args override is honored.
+  const custom = buildInstallArgs(r, ['--omit=dev']);
+  assert.deepEqual(custom.slice(1), ['install', '--omit=dev']);
+});
+
+// Test 5 -- fallback descriptor: shell:true only on Windows.
+test('path-npm fallback sets shell:true only on win32', () => {
+  // Force the fallback by pointing execPath at a freshly-created EMPTY temp
+  // directory tree deep enough that none of the candidate paths (including the
+  // `../lib/node_modules/...` POSIX-layout candidate) can escape onto a real
+  // system npm. The temp dir is isolated and known to contain no node_modules.
+  const os = require('node:os');
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'mos-npm-resolve-test-'));
+  try {
+    // <tmpRoot>/x/y/z/bin/node -- candidates resolve under <tmpRoot>/x/y/z,
+    // which is empty, so resolveNpmCli must fall through to path-npm.
+    const fakeBin = path.join(tmpRoot, 'x', 'y', 'z', 'bin');
+    fs.mkdirSync(fakeBin, { recursive: true });
+    const r = resolveNpmCli({ execPath: path.join(fakeBin, 'node') });
+    assert.equal(r.strategy, 'path-npm', 'expected the path-npm fallback in an isolated empty tree');
+    assert.equal(r.command, 'npm', 'fallback command is the bare npm');
+    assert.equal(r.npmCli, null, 'fallback has no npmCli path');
+    assert.equal(
+      r.shell,
+      process.platform === 'win32',
+      'fallback shell must be true on Windows (npm.cmd handling) and false elsewhere'
+    );
+  } finally {
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+  }
+});
+
+// Test 6 -- HARD RULE: no em-dashes. The em-dash is referenced via its Unicode
+// code point (U+2014) so this test file itself stays em-dash-clean.
+test('npm-cli-resolve.cjs has no em-dashes', () => {
+  const src = fs.readFileSync(MODULE_PATH, 'utf8');
+  const EM_DASH = String.fromCharCode(0x2014);
+  assert.ok(src.indexOf(EM_DASH) === -1, 'em-dash found in npm-cli-resolve.cjs');
+});
+
+// Test 7 -- the node-npm-cli argv never relies on a bare 'npm' token.
+test('node-npm-cli argv does not depend on PATH resolution of npm', () => {
+  const r = resolveNpmCli();
+  const fullArgv = [r.command].concat(buildInstallArgs(r));
+  assert.notEqual(fullArgv[0], 'npm', 'command position must not be the bare npm token');
+  // The npm-cli.js path is absolute -- not resolved against PATH or cwd.
+  assert.ok(path.isAbsolute(r.npmCli), 'npm-cli.js path must be absolute');
+});
+
+process.stdout.write('\nnpm-cli-resolve: ' + passed + ' passed, ' + failed + ' failed\n');
+process.exit(failed === 0 ? 0 : 1);