archgen-skill 0.0.6 → 0.1.0

package/lib/install.js

@@ -180,7 +180,7 @@ export function installGlobal(opts = {}) {
       noMcp: opts.mcp === false,
     });
     if (!r.ok) {
-      rows.push(['WARN', '-', 'server bootstrap incomplete — run: npx archgen-mcp bootstrap --location global --yes']);
+      rows.push(['WARN', '-', 'server bootstrap incomplete' + (r.detail ? ` (${r.detail})` : '') + ' — run: npx archgen-mcp bootstrap --location global --yes']);
     }
   }
 
@@ -196,17 +196,70 @@ function stampNote(rows, dest, write) {
   }
 }
 
-export function uninstallGlobal(home = homedir()) {
+/**
+ * The exact destinations a global install may create.
+ *
+ * A manifest entry is acted on ONLY when it names one of them. A plain
+ * suffix test (`endsWith('skills/archgen')`) would let any path with that
+ * ending be removed — including paths outside the known harness dirs.
+ */
+function allowedGlobalDestinations(home) {
+  const set = new Set(globalTargets(home).map((d) => resolve(join(d, 'archgen'))));
+  set.add(resolve(join(process.cwd(), '.github', 'skills', 'archgen')));
+  return set;
+}
+
+/**
+ * Move an edited copy-mode install into the global backup vault before it is
+ * removed: the uninstall must never be the last place those edits exist.
+ * An install that still matches the packaged skill needs no backup.
+ */
+function backupEditedCopy(dest, packageRoot, backups) {
+  let identical = false;
+  try {
+    identical = hashDir(dest) === hashDir(resolveSkillSource(packageRoot));
+  } catch {
+    identical = false; // unverifiable -> preserve it
+  }
+  if (identical) return;
+  const tdir = dirname(dest);
+  const loc = moveToBackupInto(tdir, 'archgen', GLOBAL_BACKUP_REL, nextBackupTs(tdir));
+  backups.push(join(tdir, ...loc.split('/')));
+}
+
+/**
+ * Remove the globally-installed copies recorded in the manifest.
+ *
+ * Only entries that name a known harness destination are removed. An entry
+ * that cannot be verified is SKIPPED and KEPT in the manifest — the manifest
+ * is only removed when nothing was left behind.
+ *
+ * @param {string} home home directory holding the manifest
+ * @param {{packageRoot?: string}} opts
+ */
+export function uninstallGlobal(home = homedir(), opts = {}) {
   const manifest = join(home, MANIFEST_NAME);
   if (!existsSync(manifest)) return { removed: 0, failed: 0, noop: true };
+  const packageRoot = opts.packageRoot ?? PACKAGE_ROOT;
+  const allowed = allowedGlobalDestinations(home);
   let removed = 0, failed = 0;
+  const kept = [];
+  const backups = [];
   for (const line of readFileSync(manifest, 'utf8').split('\n')) {
     if (!line.trim()) continue;
     const [kind, p] = line.split('\t');
-    if (!p || !p.endsWith(join('skills', 'archgen'))) { failed++; continue; } // safety guard
-    try { rmSync(p, { force: true, recursive: true }); removed++; }
-    catch { failed++; }
+    if (!p || !allowed.has(resolve(p))) { failed++; kept.push(line); continue; } // safety guard
+    try {
+      if (kind === 'copy') backupEditedCopy(p, packageRoot, backups);
+      rmSync(p, { force: true, recursive: true }); removed++;
+    } catch { failed++; kept.push(line); }
+  }
+  if (kept.length === 0) {
+    try { rmSync(manifest, { force: true }); } catch { failed++; }
+  } else {
+    // The skipped entries stay recorded: the manifest is the only thing that
+    // knows they were never removed.
+    try { writeFileSync(manifest, kept.join('\n') + '\n'); } catch { failed++; }
   }
-  rmSync(manifest, { force: true });
-  return { removed, failed, noop: false };
+  return { removed, failed, noop: false, backups };
 }

package/lib/mcp-server.js

@@ -9,10 +9,11 @@
 // 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 } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
+import { whichOnPath } from './spawn-npm.js';
 import { homedir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 
 export const MCP_PACKAGE = 'archgen-mcp';
 
@@ -52,26 +53,127 @@ export function resolveMcpBinary(opts = {}) {
 
 /**
  * Locate an executable on PATH (cross-platform, no shell).
- * @param {string} bin
- * @param {Record<string, string|undefined>} env
- * @returns {string|null}
+ *
+ * ONE implementation, in spawn-npm.js — this module used to carry its own
+ * copy, and the two had drifted: the copy here skipped a path ending in '/',
+ * the one there did not, and neither checked that the path was a FILE. Two
+ * implementations of one rule is how the rules start disagreeing.
+ *
+ * Imported for this module's own use AND re-exported, so the callers that
+ * already import it from here keep working.
+ */
+export { whichOnPath };
+
+/**
+ * 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
  */
-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 */
-      }
+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 };
+}
+
+/**
+ * The project root an MCP call is made against.
+ *
+ * It MUST be an ABSOLUTE path.
+ *
+ * The child process resolves a relative root against ITS OWN working
+ * directory, so a root that was missing — or a property-name mismatch
+ * between the caller and the callee — did not fail. It silently wrote the
+ * harness configs, the CodeGraph index and the managed blocks into a
+ * directory named "undefined", next to the real project.
+ *
+ * The guard turns that class of mistake into an immediate, named failure.
+ *
+ * @param {unknown} projectRoot
+ * @param {string} fn the caller's name, for the message
+ * @returns {string} the absolute project root
+ */
+export function requireProjectRoot(projectRoot, fn) {
+  if (typeof projectRoot !== 'string' || projectRoot.trim() === '') {
+    throw new Error(`${fn}: projectRoot is required and must be an absolute path`);
+  }
+  if (!isAbsolute(projectRoot)) {
+    throw new Error(`${fn}: projectRoot must be an absolute path (got '${projectRoot}')`);
+  }
+  return resolve(projectRoot);
+}
+
 /**
  * Run one `archgen-mcp` subcommand and return its JSON output.
  *
@@ -80,19 +182,19 @@ export function whichOnPath(bin, env = process.env) {
  * @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 { timeout = 600000, env = process.env } = opts;
+  const projectRoot = requireProjectRoot(opts.projectRoot ?? process.cwd(), 'runMcp');
   const resolved = resolveMcpBinary({ projectRoot, env });
+  const inv = mcpInvocation(resolved.command, [...resolved.args, ...args], process.platform, env);
 
   let r;
   try {
-    r = spawnSync(resolved.command, [...resolved.args, ...args], {
+    r = spawnSync(inv.command, inv.args, {
       encoding: 'utf8',
       timeout,
       env,
       cwd: projectRoot,
-      shell: false,
-      // On Windows the npx shim is a .cmd file, which needs a shell.
-      ...(process.platform === 'win32' && /\.(cmd|bat)$/i.test(resolved.command) ? { shell: true } : {}),
+      shell: inv.shell,
     });
   } catch (e) {
     return { ok: false, code: null, data: null, stdout: '', stderr: '', detail: String(e?.message ?? e) };
@@ -116,6 +218,25 @@ export function runMcp(args, opts = {}) {
   };
 }
 
+/**
+ * The arguments for the server's bootstrap call.
+ *
+ * Exported so the project root in them can be asserted directly: the bug
+ * this guards against was a property-name mismatch that put the literal
+ * string "undefined" in this exact position.
+ *
+ * @param {string} projectRoot
+ * @param {{location?: 'project'|'global'|'both', approved?: boolean}} [opts]
+ * @returns {string[]}
+ */
+export function bootstrapArgs(projectRoot, opts = {}) {
+  const { location = 'both', approved = true } = opts;
+  const root = requireProjectRoot(projectRoot, 'bootstrapArgs');
+  const args = ['bootstrap', '--project', root, '--location', location, '--json'];
+  if (approved) args.push('--yes');
+  return args;
+}
+
 /**
  * Wire the archgen MCP server into the detected harnesses and ensure CodeGraph.
  *
@@ -123,11 +244,10 @@ export function runMcp(args, 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 { location = 'both', approved = true, env = process.env } = opts;
+  const args = bootstrapArgs(opts.projectRoot, { location, approved });
 
-  const r = runMcp(args, { projectRoot, env });
+  const r = runMcp(args, { projectRoot: opts.projectRoot, env });
   if (r.detail) {
     return { ok: false, detail: `cannot run ${MCP_PACKAGE}: ${r.detail}` };
   }
@@ -143,7 +263,8 @@ export function bootstrapMcp(opts) {
  * @param {{projectRoot: string, env?: Record<string, string|undefined>}} opts
  */
 export function mcpDoctor(opts) {
-  const { projectRoot, env = process.env } = opts;
+  const { env = process.env } = opts;
+  const projectRoot = requireProjectRoot(opts.projectRoot, 'mcpDoctor');
   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]) };
 }
@@ -153,7 +274,8 @@ export function mcpDoctor(opts) {
  * @param {{projectRoot: string, env?: Record<string, string|undefined>}} opts
  */
 export function uninstallMcp(opts) {
-  const { projectRoot, env = process.env } = opts;
+  const { env = process.env } = opts;
+  const projectRoot = requireProjectRoot(opts.projectRoot, 'uninstallMcp');
   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

@@ -5,12 +5,12 @@
 // 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
 // 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.
+// preserves them verbatim), the verifier never sees them as data, and every
+// other YAML consumer ignores them by the same contract. 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

@@ -3,11 +3,12 @@
 // 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() {
-  const fromEnv = process.env.npm_execpath;
+export function npmCliPath(env = process.env) {
+  const fromEnv = env.npm_execpath;
   if (typeof fromEnv === 'string' && fromEnv.endsWith('.js') && existsSync(fromEnv)) {
     return fromEnv;
   }
@@ -29,19 +30,29 @@ export function npmCliPath() {
  * Spawn npm with { command, args, shell }. Args MUST be registry-verified
  * constants (the shell fallback on Windows interpolates them).
  */
-export function npmInvocation(npmArgs) {
-  const cli = npmCliPath();
+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) {
+/**
+ * Cross-platform `which` (PATHEXT on Windows).
+ *
+ * The env is a PARAMETER, not an assumption: a caller may be searching a
+ * modified PATH (a test, a sandboxed HOME), and reading process.env behind
+ * its back would answer a different question than the one asked.
+ *
+ * @param {string} bin
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {string|null}
+ */
+export function whichOnPath(bin, env = process.env) {
   const exts = process.platform === 'win32'
-    ? (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';')
+    ? (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';')
     : [''];
-  const dirs = (process.env.PATH ?? '').split(process.platform === 'win32' ? ';' : ':').filter(Boolean);
+  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);
@@ -52,3 +63,47 @@ export function whichOnPath(bin) {
   }
   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;
+}