archgen-skill 0.0.5 → 0.0.7

package/lib/mcp-server.js

@@ -0,0 +1,241 @@
+// mcp-server.js — locate and drive the `archgen-mcp` server from the CLI.
+//
+// WHY THE CLI DELEGATES: archgen's deterministic capability now lives in ONE
+// place — the MCP server. The CLI used to shell out to the skill's
+// scripts/codegraph.mjs; it now shells out to `archgen-mcp bootstrap`, which
+// runs the same code the agent's tools run. There is no second implementation
+// of harness wiring, CodeGraph bootstrap, or doctor logic.
+//
+// NEVER FATAL: no npm, no network, a read-only config, or a missing MCP
+// server must still leave a working skill install. Failures are REPORTED,
+// never thrown — the same posture bootstrapCodegraph has always had.
+import { existsSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+
+export const MCP_PACKAGE = 'archgen-mcp';
+
+/**
+ * Locate the archgen-mcp binary.
+ *
+ * Resolution order (first hit wins):
+ *   1. $ARCHGEN_MCP_BIN            — explicit override
+ *   2. <project>/node_modules/.bin/archgen-mcp
+ *   3. `archgen-mcp` on PATH       — a global npm install
+ *   4. `npx -y archgen-mcp`        — network fallback (npx caches it)
+ *
+ * @param {{projectRoot?: string, home?: string, env?: Record<string, string|undefined>}} opts
+ * @returns {{bin: string|null, source: 'override'|'local'|'path'|'npx', command: string, args: string[]}}
+ */
+export function resolveMcpBinary(opts = {}) {
+  const { projectRoot = process.cwd(), home = homedir(), env = process.env } = opts;
+
+  const override = env.ARCHGEN_MCP_BIN;
+  if (override && existsSync(override)) {
+    return { bin: override, source: 'override', command: override, args: [] };
+  }
+
+  const local = join(
+    resolve(projectRoot),
+    'node_modules',
+    '.bin',
+    process.platform === 'win32' ? 'archgen-mcp.cmd' : 'archgen-mcp',
+  );
+  if (existsSync(local)) return { bin: local, source: 'local', command: local, args: [] };
+
+  const onPath = whichOnPath('archgen-mcp', env);
+  if (onPath) return { bin: onPath, source: 'path', command: onPath, args: [] };
+
+  return { bin: null, source: 'npx', command: 'npx', args: ['-y', MCP_PACKAGE] };
+}
+
+/**
+ * Locate an executable on PATH (cross-platform, no shell).
+ * @param {string} bin
+ * @param {Record<string, string|undefined>} env
+ * @returns {string|null}
+ */
+export function whichOnPath(bin, env = process.env) {
+  const exts = process.platform === 'win32' ? (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';') : [''];
+  const dirs = (env.PATH ?? '').split(process.platform === 'win32' ? ';' : ':').filter(Boolean);
+  for (const d of dirs) {
+    for (const ext of exts) {
+      const p = join(d, bin + ext);
+      try {
+        if (existsSync(p) && !p.endsWith('/')) return p;
+      } catch {
+        /* not here */
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Quote one argument for cmd.exe.
+ *
+ * cmd.exe parses `&`, `|`, `<`, `>`, `^` and whitespace as syntax even in an
+ * unquoted argument — an unquoted project path is split on spaces and its
+ * `&`/`|` are executed. Double quotes neutralize all of them. `%` is the one
+ * character cmd expands even inside quotes, so an argument carrying one is
+ * refused rather than silently rewritten.
+ *
+ * @param {string} arg
+ * @returns {string} the quoted argument
+ */
+export function quoteWindowsArg(arg) {
+  const s = String(arg);
+  if (s === '') return '""';
+  if (/["%]/.test(s)) {
+    throw new Error(`refusing to pass an unsafe character through the Windows shell: ${JSON.stringify(s)}`);
+  }
+  return '"' + s + '"';
+}
+
+/**
+ * Find the JS entry point a Windows npm shim launches.
+ *
+ * npm writes `<name>.cmd` beside the package it points at, and the package's
+ * package.json names the real script. Resolving it lets the script run with
+ * the current node binary — no shell, no quoting, nothing to inject.
+ *
+ * @param {string} cmdPath path of the .cmd/.bat shim
+ * @returns {string|null} absolute path of the JS entry point
+ */
+function resolveShimEntry(cmdPath) {
+  const name = basename(cmdPath).replace(/\.(cmd|bat)$/i, '');
+  const dir = dirname(cmdPath);
+  const candidates = [
+    join(dir, 'node_modules', MCP_PACKAGE), // global npm prefix
+    join(dir, '..', MCP_PACKAGE), // node_modules/.bin -> node_modules/<pkg>
+    join(dir, '..', 'node_modules', MCP_PACKAGE), // prefix/lib layout
+  ];
+  for (const pkgDir of candidates) {
+    let pkg;
+    try {
+      pkg = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf8'));
+    } catch {
+      continue; // not this layout
+    }
+    const bin = pkg && pkg.bin;
+    const rel = typeof bin === 'string' ? bin : bin && typeof bin === 'object' ? bin[name] : null;
+    if (!rel) continue;
+    const js = resolve(pkgDir, rel);
+    if (existsSync(js)) return js;
+  }
+  return null;
+}
+
+/**
+ * Build the spawn invocation for the MCP server.
+ *
+ * On Windows an npm-installed binary is a `.cmd` shim that only cmd.exe can
+ * run — and cmd.exe parses unquoted arguments as shell syntax. The shim's JS
+ * entry point is preferred (run with the current node binary, no shell at
+ * all); when it cannot be resolved, every argument is quoted for cmd.exe.
+ *
+ * @param {string} command executable to run
+ * @param {string[]} args arguments
+ * @param {string} [platform] process.platform (injectable for tests)
+ * @param {Record<string, string|undefined>} [env] environment used for lookups
+ * @returns {{command: string, args: string[], shell: boolean}}
+ */
+export function mcpInvocation(command, args, platform = process.platform, env = process.env) {
+  if (platform !== 'win32') return { command, args, shell: false };
+  let cmd = command;
+  if (!/\.(cmd|bat)$/i.test(cmd) && !/[\\/]/.test(cmd)) {
+    // A bare name (e.g. 'npx') resolves to a .cmd shim on Windows.
+    const shim = whichOnPath(cmd + '.cmd', env);
+    if (shim) cmd = shim;
+  }
+  if (!/\.(cmd|bat)$/i.test(cmd)) return { command, args, shell: false };
+  const js = resolveShimEntry(cmd);
+  if (js) return { command: process.execPath, args: [js, ...args], shell: false };
+  return { command: quoteWindowsArg(cmd), args: args.map(quoteWindowsArg), shell: true };
+}
+
+/**
+ * Run one `archgen-mcp` subcommand and return its JSON output.
+ *
+ * @param {string[]} args the subcommand + flags
+ * @param {{projectRoot?: string, timeout?: number, env?: Record<string, string|undefined>}} opts
+ * @returns {{ok: boolean, code: number|null, data: any, stdout: string, stderr: string, detail?: string}}
+ */
+export function runMcp(args, opts = {}) {
+  const { projectRoot = process.cwd(), timeout = 600000, env = process.env } = opts;
+  const resolved = resolveMcpBinary({ projectRoot, env });
+  const inv = mcpInvocation(resolved.command, [...resolved.args, ...args], process.platform, env);
+
+  let r;
+  try {
+    r = spawnSync(inv.command, inv.args, {
+      encoding: 'utf8',
+      timeout,
+      env,
+      cwd: projectRoot,
+      shell: inv.shell,
+    });
+  } catch (e) {
+    return { ok: false, code: null, data: null, stdout: '', stderr: '', detail: String(e?.message ?? e) };
+  }
+  if (r.error) {
+    return { ok: false, code: null, data: null, stdout: '', stderr: '', detail: String(r.error.message ?? r.error) };
+  }
+  const stdout = r.stdout ?? '';
+  let data = null;
+  try {
+    data = JSON.parse(stdout);
+  } catch {
+    /* not JSON — the caller renders the raw output */
+  }
+  return {
+    ok: r.status === 0,
+    code: r.status ?? null,
+    data,
+    stdout,
+    stderr: r.stderr ?? '',
+  };
+}
+
+/**
+ * Wire the archgen MCP server into the detected harnesses and ensure CodeGraph.
+ *
+ * @param {{projectRoot: string, location?: 'project'|'global'|'both', approved?: boolean, env?: Record<string, string|undefined>}} opts
+ * @returns {{ok: boolean, skipped?: string, detail?: string, report?: any}}
+ */
+export function bootstrapMcp(opts) {
+  const { projectRoot, location = 'both', approved = true, env = process.env } = opts;
+  const args = ['bootstrap', '--project', projectRoot, '--location', location, '--json'];
+  if (approved) args.push('--yes');
+
+  const r = runMcp(args, { projectRoot, env });
+  if (r.detail) {
+    return { ok: false, detail: `cannot run ${MCP_PACKAGE}: ${r.detail}` };
+  }
+  if (r.data === null) {
+    const firstLine = (r.stderr || r.stdout || '').trim().split('\n')[0];
+    return { ok: false, detail: firstLine || `${MCP_PACKAGE} bootstrap produced no output` };
+  }
+  return { ok: r.ok, report: r.data, detail: r.ok ? undefined : r.stderr.trim().split('\n')[0] };
+}
+
+/**
+ * Health-check the archgen MCP install.
+ * @param {{projectRoot: string, env?: Record<string, string|undefined>}} opts
+ */
+export function mcpDoctor(opts) {
+  const { projectRoot, env = process.env } = opts;
+  const r = runMcp(['doctor', '--project', projectRoot, '--json'], { projectRoot, env, timeout: 60000 });
+  return { ok: r.ok, report: r.data, detail: r.detail ?? (r.data ? undefined : r.stderr.trim().split('\n')[0]) };
+}
+
+/**
+ * Remove the archgen MCP entries.
+ * @param {{projectRoot: string, env?: Record<string, string|undefined>}} opts
+ */
+export function uninstallMcp(opts) {
+  const { projectRoot, env = process.env } = opts;
+  const r = runMcp(['uninstall-mcp', '--project', projectRoot, '--yes', '--json'], { projectRoot, env, timeout: 60000 });
+  return { ok: r.ok, report: r.data, detail: r.detail };
+}

package/lib/migrations/001-stamp-provenance.mjs

@@ -4,13 +4,13 @@
 //
 // What it writes: three YAML COMMENT lines at the very top of tasks.yaml and
 // architecture.yaml. Comments are inert to every consumer by contract — the
-// skill's zero-dep parser records them positionally (set-status.mjs preserves
-// them verbatim), verify-plan.mjs never sees them as data, and the VS Code
-// extension port behaves identically. Additive-only: no existing key is
+// MCP core's parser records them positionally (`archgen_tasks{set_status}`
+// preserves them verbatim), the verifier never sees them as data, and the VS
+// Code extension port behaves identically. Additive-only: no existing key is
 // touched, nothing becomes required.
 //
 //   # schema_version: 1
-//   # generator: archgen v0.0.4      (version token omitted when unknowable)
+//   # generator: archgen v1.2.3      (version token omitted when unknowable)
 //   # generated_at: 2026-08-26T09:00:00.000Z
 //
 // Idempotency: detect/files/apply all key off the `# schema_version:` marker
@@ -66,11 +66,18 @@ export function files(ctx) {
   return unstampedArtifacts(ctx).map((a) => a.rel);
 }
 
-export function apply(ctx) {
+export function apply(ctx, files) {
+  // The framework passes the EXACT list it backed up: re-deriving the file
+  // set here could mutate a file that appeared after the backup and was
+  // therefore never backed up.
+  const rels = Array.isArray(files)
+    ? files
+    : unstampedArtifacts(ctx).map((a) => a.rel);
   const generatedAt = new Date().toISOString(); // one timestamp per run
-  for (const a of unstampedArtifacts(ctx)) {
-    const abs = join(ctx.projectRoot, ...a.rel.split('/'));
-    const content = readFileSync(abs, 'utf8');
+  for (const rel of rels) {
+    const abs = join(ctx.projectRoot, ...rel.split('/'));
+    let content;
+    try { content = readFileSync(abs, 'utf8'); } catch { continue; } // vanished mid-run
     if (MARKER_RE.test(content)) continue; // re-check: never double-stamp
     writeFileSync(abs, stampLines(ctx.projectRoot, generatedAt).join('\n') + '\n' + content);
   }

package/lib/migrations/index.mjs

@@ -7,9 +7,10 @@
 //   - every migration is ONE numbered file (`NNN-name.mjs`) next to this file;
 //   - `detect(ctx)` decides whether a project still needs it (must be cheap,
 //     read-only, and false once applied — migrations are idempotent);
-//   - `apply(ctx)` mutates, but ONLY after the framework has snapshotted every
-//     file the migration declared via its optional `files(ctx)` export into
-//     `.archgen/.backup/<timestamp>/migrate/`;
+//   - `apply(ctx, files)` mutates, but ONLY after the framework has snapshotted
+//     every file the migration declared via its optional `files(ctx)` export
+//     into `.archgen/.backup/<timestamp>/migrate/`; the framework hands apply
+//     the exact list it backed up, so the mutated set IS the backed-up set;
 //   - dry-run is the DEFAULT everywhere: nothing is written unless a caller
 //     explicitly passes `{ dryRun: false }`.
 //
@@ -19,7 +20,8 @@
 //   export const fromSchema  — source schema number or null (pre-schema files)
 //   export const toSchema    — target schema number
 //   export function detect(ctx) -> boolean
-//   export function apply(ctx)  -> void   (mutates; framework backed up first)
+//   export function apply(ctx, files) -> void   (mutates exactly `files`;
+//                                  the framework backed them up first)
 //   export function files(ctx)  -> string[] of project-relative paths that
 //                                  apply() may touch (drives --check output
 //                                  AND the mandatory pre-apply backup set)
@@ -163,8 +165,17 @@ export async function applyMigration(id, projectRoot, opts = {}) {
   if (!mig.detect(ctx)) return { status: 'clean', id };
   const files = mig.files ? mig.files(ctx).slice() : [];
   if (dryRun) return { status: 'would-apply', id, description: mig.description, files };
-  // Backup EVERYTHING the migration declared before it touches anything.
-  const backups = files.map((file) => ({ file, backup: ctx.backup(file) }));
-  await mig.apply(ctx);
-  return { status: 'applied', id, description: mig.description, files, backups };
+  // Backup EVERYTHING the migration declared before it touches anything, then
+  // hand apply() the exact list that was backed up: the mutated set is then
+  // the backed-up set, never a freshly re-derived one.
+  const backedUp = [];
+  const backups = [];
+  for (const file of files) {
+    const abs = join(ctx.projectRoot, ...file.split('/'));
+    if (!existsSync(abs)) continue; // vanished between the scan and now
+    backups.push({ file, backup: ctx.backup(file) });
+    backedUp.push(file);
+  }
+  await mig.apply(ctx, backedUp);
+  return { status: 'applied', id, description: mig.description, files: backedUp, backups };
 }

package/lib/restore.js

@@ -14,14 +14,10 @@
 import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, renameSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import { homedir } from 'node:os';
-import { dirname, join, relative, resolve } from 'node:path';
-import { BACKUP_ROOT_REL, moveToBackupInto } from './store.js';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { BACKUP_PATHS_FILE, BACKUP_ROOT_REL, moveToBackupInto, readBackupPaths } from './store.js';
 import { GLOBAL_BACKUP_REL, globalTargets } from './install.js';
 
-function toPosix(p) {
-  return p.split('\\').join('/');
-}
-
 function byName(a, b) {
   return a < b ? -1 : a > b ? 1 : 0;
 }
@@ -35,10 +31,11 @@ function summarize(dir) {
   let dirs = 0;
   (function walk(d) {
     for (const e of readdirSync(d, { withFileTypes: true })) {
+      if (e.name === BACKUP_PATHS_FILE) continue; // metadata, not backed-up content
       if (e.isDirectory()) { dirs++; walk(join(d, e.name)); } else { files++; }
     }
   })(dir);
-  const topLevel = readdirSync(dir).sort(byName);
+  const topLevel = readdirSync(dir).filter((n) => n !== BACKUP_PATHS_FILE).sort(byName);
   return { files, dirs, topLevel };
 }
 
@@ -102,6 +99,47 @@ function layDown(srcAbs, destAbs) {
   renameSync(tmp, destAbs);
 }
 
+/** A recorded path is usable only when it stays inside the destination base. */
+function isSafeRel(rel) {
+  if (typeof rel !== 'string' || rel === '') return false;
+  if (isAbsolute(rel)) return false;
+  return !rel.split('/').some((seg) => seg === '..' || seg === '');
+}
+
+/** Every FILE a snapshot holds, relative to the snapshot dir (legacy snapshots). */
+function snapshotFiles(snapshotDir, prefix = '') {
+  const out = [];
+  for (const e of readdirSync(join(snapshotDir, prefix), { withFileTypes: true })) {
+    if (e.name === BACKUP_PATHS_FILE) continue;
+    const rel = prefix ? prefix + '/' + e.name : e.name;
+    if (e.isDirectory()) out.push(...snapshotFiles(snapshotDir, rel));
+    else out.push(rel);
+  }
+  return out;
+}
+
+/**
+ * The paths a snapshot restores, relative to the destination base.
+ *
+ * The snapshot's OWN path record is authoritative: it names the exact paths
+ * that were backed up. Restoring the snapshot's top-level directory instead
+ * would replace a whole `.agents/` tree and take every sibling skill with it.
+ * Snapshots written before the record existed fall back to per-file restore:
+ * still exact about WHAT is written, never about what is deleted.
+ */
+function restoreEntries(snap, destBase) {
+  const recorded = readBackupPaths(snap.snapshotDir);
+  const rels = (recorded && recorded.length > 0)
+    ? recorded.filter(isSafeRel)
+    : snapshotFiles(snap.snapshotDir).filter(isSafeRel);
+  return rels.map((rel) => ({
+    rel,
+    name: rel.split('/').pop(),
+    srcAbs: join(snap.snapshotDir, ...rel.split('/')),
+    destAbs: join(destBase, ...rel.split('/')),
+  }));
+}
+
 /**
  * Restore backups discovered across the project and global vaults.
  *
@@ -141,21 +179,17 @@ export function restoreBackups(projectRoot, options = {}) {
   const snap = matches[0];
 
   const destBase = options.target ? resolve(options.target) : snap.base;
-  const entries = readdirSync(snap.snapshotDir, { withFileTypes: true })
-    .map((e) => e.name)
-    .sort(byName)
-    .map((name) => ({ name, srcAbs: join(snap.snapshotDir, name), destAbs: join(destBase, name) }));
+  const entries = restoreEntries(snap, destBase);
 
   // Pass 1 — safety: move EVERY existing destination aside before laying down
   // anything, so a mid-restore failure still leaves current state fully backed up.
   const safetyBackups = [];
   const safetyRootRel = snap.origin === 'global' ? GLOBAL_BACKUP_REL : BACKUP_ROOT_REL;
-  const safetyBase = snap.origin === 'global' ? snap.base : destBase;
+  const safetyBase = destBase;
   const safetyTs = uniqueSafetyTs(safetyBase, safetyRootRel);
   for (const en of entries) {
     if (!lstatSafe(en.destAbs)) continue;
-    const rel = snap.origin === 'global' ? en.name : toPosix(relative(destBase, en.destAbs));
-    const loc = moveToBackupInto(safetyBase, rel, safetyRootRel, safetyTs);
+    const loc = moveToBackupInto(safetyBase, en.rel, safetyRootRel, safetyTs);
     const abs = join(safetyBase, ...loc.split('/'));
     safetyBackups.push({ rel: loc, abs });
   }
@@ -181,10 +215,12 @@ function parseFlags(argv) {
     if (a === '--list') opts.list = true;
     else if (a === '--snapshot') {
       const v = argv[++i];
-      if (!v || v.startsWith('--')) return { error: '--snapshot requires a timestamp argument' };
+      // A flag-shaped value is never a value: '-foo' is an option, not an id.
+      if (!v || v.startsWith('-')) return { error: '--snapshot requires a timestamp argument' };
       opts.snapshot = v;
     } else if (a === '--project') {
-      const v = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : process.cwd();
+      const next = argv[i + 1];
+      const v = next && !next.startsWith('-') ? argv[++i] : process.cwd();
       opts.project = v;
     } else if (a === '--global') opts.global = true;
     else if (a === '--yes') opts.yes = true; // accepted for CLI ergonomics; restore is interactive-free

package/lib/spawn-npm.js

@@ -0,0 +1,99 @@
+// spawn-npm.js — run npm on every platform without a shell.
+// An unshelled spawnSync("npm", …) fails with EINVAL on Windows since the
+// CVE-2024-27980 hardening, so npm's JS entry point is invoked with the
+// current node binary instead.
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+
+/** npm-cli.js path: `npm_execpath` first, then node-relative layouts. */
+export function npmCliPath(env = process.env) {
+  const fromEnv = env.npm_execpath;
+  if (typeof fromEnv === 'string' && fromEnv.endsWith('.js') && existsSync(fromEnv)) {
+    return fromEnv;
+  }
+  const dir = dirname(process.execPath);
+  const candidates =
+    process.platform === 'win32'
+      ? [join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js')] // Windows: node.exe sits beside node_modules/
+      : [join(dir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js')]; // POSIX: bin/../lib/...
+  for (const c of candidates) if (existsSync(c)) return c;
+  // Homebrew cellar layout: /opt/homebrew/{bin,lib}/...
+  if (process.platform !== 'win32') {
+    const brew = join(dir, '..', '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js');
+    if (existsSync(brew)) return brew;
+  }
+  return null;
+}
+
+/**
+ * Spawn npm with { command, args, shell }. Args MUST be registry-verified
+ * constants (the shell fallback on Windows interpolates them).
+ */
+export function npmInvocation(npmArgs, env = process.env) {
+  const cli = npmCliPath(env);
+  if (cli) return { command: process.execPath, args: [cli, ...npmArgs], shell: false };
+  const isWin = process.platform === 'win32';
+  return { command: isWin ? 'npm.cmd' : 'npm', args: npmArgs, shell: isWin };
+}
+
+/** Cross-platform `which` (PATHEXT on Windows). */
+export function whichOnPath(bin) {
+  const exts = process.platform === 'win32'
+    ? (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';')
+    : [''];
+  const dirs = (process.env.PATH ?? '').split(process.platform === 'win32' ? ';' : ':').filter(Boolean);
+  for (const d of dirs) {
+    for (const ext of exts) {
+      const p = join(d, bin + ext);
+      try {
+        if (existsSync(p)) return p;
+      } catch { /* next */ }
+    }
+  }
+  return null;
+}
+
+/**
+ * The global npm prefix — where `npm install -g` puts its binaries.
+ * @returns {string|null} null when npm cannot be queried
+ */
+export function npmGlobalPrefix(env = process.env) {
+  try {
+    const inv = npmInvocation(['prefix', '-g'], env);
+    const r = spawnSync(inv.command, inv.args, {
+      encoding: 'utf8',
+      timeout: 15000,
+      shell: inv.shell,
+      env,
+    });
+    if (r.status !== 0 || !r.stdout) return null;
+    return r.stdout.trim().split(/\r?\n/).pop() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The path of a globally-installed npm binary.
+ *
+ * A PATH search returns the FIRST match, which is often an OLD global
+ * install shadowing the one npm just wrote — so the global prefix (the
+ * directory npm actually installs into) is consulted first.
+ *
+ * @param {string} name binary name, e.g. 'archgen-skill'
+ * @returns {string|null}
+ */
+export function globalBinPath(name, env = process.env, platform = process.platform) {
+  const prefix = npmGlobalPrefix(env);
+  if (!prefix) return null;
+  const candidates = platform === 'win32'
+    ? [join(prefix, name + '.cmd'), join(prefix, name)]
+    : [join(prefix, 'bin', name)];
+  for (const c of candidates) {
+    try {
+      if (existsSync(c)) return c;
+    } catch { /* next */ }
+  }
+  return null;
+}