archgen-skill 0.0.5 → 0.0.7

package/lib/store.js

@@ -31,7 +31,7 @@ import {
   rmSync,
   writeFileSync,
 } from 'node:fs';
-import { dirname, join, sep } from 'node:path';
+import { basename, dirname, join, resolve, sep } from 'node:path';
 import { loadConfig } from './config.js';
 
 export const STORE_REL = '.agents/skills/archgen';
@@ -44,6 +44,18 @@ export const MANIFEST_REL = '.archgen/' + CONFIG_FILES.projectManifest;
 export const BACKUP_ROOT_REL = '.archgen/' + CONFIG_FILES.backupDir;
 export const VERSION_FILE = CONFIG_FILES.stamp;
 
+/**
+ * Name of the sidecar that records WHICH paths a backup snapshot holds.
+ *
+ * A snapshot's directory layout alone does not say what was backed up: the
+ * tree `<ts>/.agents/skills/archgen` and the tree `<ts>/archgen` are the same
+ * shape at different depths, and restoring the snapshot's top-level directory
+ * would replace a whole `.agents/` tree — every sibling skill with it. The
+ * record names the exact paths, so a restore puts back exactly those and
+ * leaves siblings alone.
+ */
+export const BACKUP_PATHS_FILE = '.archgen-backup-paths.json';
+
 const GUARDED_RELPATHS = new Set(['.claude', '.agents', '.claude/skills', '.agents/skills']);
 
 /**
@@ -59,6 +71,55 @@ const GUARDED_RELPATHS = new Set(['.claude', '.agents', '.claude/skills', '.agen
  */
 export const DEV_ONLY_RELPATHS = ['scripts/test'];
 
+/**
+ * Subtrees that the CURRENT packaged skill no longer ships.
+ *
+ * The skill used to ship a `scripts/` tree (11 scripts + a lib/ folder). It
+ * does any more — every capability moved into the archgen MCP server. An
+ * existing install still carries that tree, and it is dead weight: nothing
+ * reads it, and it makes the store hash as DIVERGED from the packaged skill.
+ *
+ * Pruning it is a MIGRATION, not a repair: the tree is ours (it shipped in a
+ * previous version), so removing it is safe. It is never removed from a store
+ * whose packaged skill still ships the same path — the check is always
+ * "packaged skill has no such directory".
+ */
+export const OBSOLETE_RELPATHS = ['scripts'];
+
+/**
+ * The subtrees the packaged skill no longer ships that are still present in
+ * an installed tree (report-only — nothing is touched).
+ *
+ * @param {string} absRoot the installed skill tree
+ * @param {string} packagedRoot the packaged (vendor) skill tree
+ * @returns {string[]} the relpaths that are obsolete
+ */
+export function findObsolete(absRoot, packagedRoot) {
+  const found = [];
+  for (const rel of OBSOLETE_RELPATHS) {
+    if (existsSync(join(packagedRoot, ...rel.split('/')))) continue; // still shipped — not obsolete
+    if (!existsSync(join(absRoot, ...rel.split('/')))) continue;
+    found.push(rel);
+  }
+  return found;
+}
+
+/**
+ * Remove the subtrees the packaged skill no longer ships.
+ *
+ * @param {string} absRoot the installed skill tree
+ * @param {string} packagedRoot the packaged (vendor) skill tree
+ * @returns {string[]} the relpaths actually removed
+ */
+export function pruneObsolete(absRoot, packagedRoot) {
+  const removed = [];
+  for (const rel of findObsolete(absRoot, packagedRoot)) {
+    rmSync(join(absRoot, ...rel.split('/')), { recursive: true, force: true });
+    removed.push(rel);
+  }
+  return removed;
+}
+
 /** True when relpath `r` is (or lives inside) a dev-only excluded subtree. */
 function isDevOnlyRelPath(r) {
   for (const prefix of DEV_ONLY_RELPATHS) {
@@ -84,30 +145,58 @@ export function assertNotSymlink(absPath) {
 }
 
 /**
- * Realpath-escape guard: resolve `absPath` (climbing to the nearest existing
- * ancestor when it does not exist yet, so a symlinked PARENT dir is caught
- * before anything is created beneath it) and refuse when the real location
- * lands outside `rootAbs`. Catches `.agents -> /elsewhere` style redirects
- * that a final-component lstat cannot see.
+ * Resolve `p` to the real location of its nearest existing ancestor, keeping
+ * the not-yet-existing tail as lexical segments.
+ *
+ * `realpathSync` cannot answer for a path that does not exist yet, but the
+ * guard must still work before anything is created (init's very first run) —
+ * so the tail is appended to the resolved ancestor instead of being dropped.
+ *
+ * @param {string} p absolute path
+ * @returns {string|null} resolved path, or null when nothing could be resolved
  */
-export function assertWithinRoot(rootAbs, absPath) {
-  let rootReal;
-  try { rootReal = realpathSync(rootAbs); } catch { return; }
-  let probe = absPath;
+function realpathWithTail(p) {
+  const tail = [];
+  let probe = resolve(p);
   for (;;) {
-    let exists = true;
-    try { lstatSync(probe); } catch { exists = false; }
-    if (exists) {
-      let real;
-      try { real = realpathSync(probe); } catch { return; } // broken chain: nothing writable through it
-      if (real !== rootReal && !real.startsWith(rootReal + sep)) {
-        throw new Error(refuseSymlinkMessage(absPath));
-      }
-      return;
+    try {
+      const real = realpathSync(probe);
+      return tail.length ? join(real, ...tail) : real;
+    } catch (e) {
+      if (!e || e.code !== 'ENOENT') return null;
+      const parent = dirname(probe);
+      if (parent === probe) return null;
+      tail.unshift(basename(probe));
+      probe = parent;
     }
-    const parent = dirname(probe);
-    if (parent === probe) return;
-    probe = parent;
+  }
+}
+
+/**
+ * Realpath-escape guard: refuse when the real location of `absPath` lands
+ * outside `rootAbs`. Catches `.agents -> /elsewhere` style redirects that a
+ * final-component lstat cannot see.
+ *
+ * The LEXICAL check always applies — it is the only guard that can work when
+ * the root does not exist yet (init calls this before it created anything),
+ * and a lexical escape (`../../etc/passwd`) is an escape under any root.
+ *
+ * @param {string} rootAbs project/base root
+ * @param {string} absPath path that must stay inside the root
+ */
+export function assertWithinRoot(rootAbs, absPath) {
+  const rootLex = resolve(rootAbs);
+  const pathLex = resolve(absPath);
+  if (pathLex !== rootLex && !pathLex.startsWith(rootLex + sep)) {
+    throw new Error(refuseSymlinkMessage(absPath));
+  }
+
+  const rootReal = realpathWithTail(rootLex);
+  const pathReal = realpathWithTail(pathLex);
+  // Unresolvable (no existing ancestor at all): the lexical check stands.
+  if (!rootReal || !pathReal) return;
+  if (pathReal !== rootReal && !pathReal.startsWith(rootReal + sep)) {
+    throw new Error(refuseSymlinkMessage(absPath));
   }
 }
 
@@ -136,17 +225,38 @@ function byName(a, b) {
 export function hashDir(dir, opts = {}) {
   const ignore = new Set([VERSION_FILE, ...(opts.ignore ?? [])]);
   const hash = createHash('sha256');
-  (function walk(abs, rel) {
+  // A directory contributes its marker ONLY when its subtree contributes
+  // something. Without this, a directory holding nothing but excluded
+  // dev-only content hashed a 'd <rel>' marker on one side and nothing on the
+  // other — the two trees then read as divergent even though they are
+  // identical once the exclusions are applied.
+  //
+  // File contents are hashed as BYTES, never as strings: a lossy string
+  // round-trip would change the digest for any non-UTF-8 file.
+  const walk = (abs, rel) => {
     const entries = readdirSync(abs, { withFileTypes: true }).sort((a, b) => byName(a.name, b.name));
+    const chunks = [];
     for (const ent of entries) {
       const r = rel ? rel + '/' + ent.name : ent.name;
       if (ignore.has(r) || isDevOnlyRelPath(r)) continue;
       const p = join(abs, ent.name);
-      if (ent.isSymbolicLink()) hash.update('l ' + r + ' -> ' + readlinkSync(p) + '\n');
-      else if (ent.isDirectory()) { hash.update('d ' + r + '\n'); walk(p, r); }
-      else { hash.update('f ' + r + '\0'); hash.update(readFileSync(p)); hash.update('\n'); }
+      if (ent.isSymbolicLink()) {
+        chunks.push(Buffer.from('l ' + r + ' -> ' + readlinkSync(p) + '\n'));
+      } else if (ent.isDirectory()) {
+        const sub = walk(p, r);
+        if (sub.length > 0) {
+          chunks.push(Buffer.from('d ' + r + '\n'));
+          chunks.push(...sub);
+        }
+      } else {
+        chunks.push(Buffer.from('f ' + r + '\0'));
+        chunks.push(readFileSync(p));
+        chunks.push(Buffer.from('\n'));
+      }
     }
-  })(dir, '');
+    return chunks;
+  };
+  for (const chunk of walk(dir, '')) hash.update(chunk);
   return hash.digest('hex');
 }
 
@@ -178,8 +288,11 @@ export function loadManifest(root) {
 
 export function saveManifest(root, manifest) {
   const p = join(root, ...MANIFEST_REL.split('/'));
-  mkdirSync(dirname(p), { recursive: true });
+  // Guard BEFORE creating the parent: a symlinked `.archgen` would otherwise
+  // redirect the whole manifest write outside the project.
   assertNotSymlink(p);
+  assertWithinRoot(root, p);
+  mkdirSync(dirname(p), { recursive: true });
   writeFileSync(p, JSON.stringify(manifest, null, 2) + '\n');
 }
 
@@ -195,12 +308,45 @@ export function appendEntry(root, kind, relPath) {
   saveManifest(root, m);
 }
 
+/**
+ * Read the path record of a backup snapshot.
+ * @param {string} snapshotDir absolute path of the snapshot directory
+ * @returns {string[]|null} the recorded relative paths, or null when the
+ *   snapshot carries no record (written by an older CLI)
+ */
+export function readBackupPaths(snapshotDir) {
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(join(snapshotDir, BACKUP_PATHS_FILE), 'utf8'));
+  } catch {
+    return null;
+  }
+  if (!raw || !Array.isArray(raw.paths)) return null;
+  return raw.paths.filter((p) => typeof p === 'string' && p !== '');
+}
+
+/** Add `relPaths` to a snapshot's path record (creating it when absent). */
+function recordBackupPaths(snapshotDir, relPaths) {
+  const existing = readBackupPaths(snapshotDir) ?? [];
+  const merged = [...existing];
+  for (const p of relPaths) if (!merged.includes(p)) merged.push(p);
+  writeFileSync(
+    join(snapshotDir, BACKUP_PATHS_FILE),
+    JSON.stringify({ version: 1, paths: merged }, null, 2) + '\n',
+  );
+}
+
 /**
  * Move an existing path into `<root>/<backupRootRel>/<ts>/<relPath>`, preserving
  * the relative layout so backups restore unambiguously. Generalized core shared
  * by the project vault (.archgen/.backup) and the global vault
  * (<skills-dir>/.archgen-backups); `ts` can be injected so one operation lands
  * every entry under a single timestamp.
+ *
+ * The exact relative path is RECORDED in the snapshot: a restore must put back
+ * that path, not the snapshot's top-level directory (which can hold sibling
+ * skills the snapshot never covered).
+ *
  * @returns {string} backup location relative to `root`
  */
 export function moveToBackupInto(root, relPath, backupRootRel, ts = new Date().toISOString().replace(/:/g, '-')) {
@@ -220,6 +366,7 @@ export function moveToBackupInto(root, relPath, backupRootRel, ts = new Date().t
     cpSync(srcAbs, destAbs, { recursive: true });
     rmSync(srcAbs, { recursive: true, force: true });
   }
+  recordBackupPaths(join(root, ...backupRootRel.split('/'), ts), [relPath]);
   return destRel;
 }
 

package/lib/uninstall-project.js

@@ -15,11 +15,13 @@ import {
   MANIFEST_REL,
   STORE_REL,
   VERSION_FILE,
+  assertWithinRoot,
   hashDir,
   pruneEmptyParents,
   rmIfExists,
 } from './store.js';
 import { resolveSkillSource } from './init.js';
+import { uninstallMcp } from './mcp-server.js';
 
 function lstatSafe(p) {
   try { return lstatSync(p); } catch { return null; }
@@ -33,7 +35,8 @@ function relJoin(rel) {
  * @param {string} projectDir project root to clean
  * @param {string} packageRoot dir containing this CLI package (vendor source)
  * @returns {{root: string, linkRemoved: boolean, strippedBlocks: string[],
- *            storeRemoved: boolean, storeKept: boolean, manifestRemoved: boolean, warnings: string[]}}
+ *            storeRemoved: boolean, storeKept: boolean, manifestRemoved: boolean,
+ *            mcpRemoved: string[], warnings: string[]}}
  */
 export function uninstallProject(projectDir, packageRoot) {
   const root = resolve(projectDir);
@@ -58,9 +61,18 @@ export function uninstallProject(projectDir, packageRoot) {
     warnings.push('.claude/skills/archgen is a real directory - left untouched (remove manually if unwanted)');
   }
 
-  // 2. Managed blocks — strip markers, keep all user content.
+  // 2. Managed blocks — strip markers, keep all user content. A symlinked
+  //    managed file is REFUSED (never written through) and skipped, so the
+  //    rest of the uninstall still runs and the project is left in a
+  //    coherent state instead of half-uninstalled.
   for (const name of ['AGENTS.md', 'CLAUDE.md']) {
-    if (stripManagedFile(join(root, name)).hadBlock) strippedBlocks.push(name);
+    const abs = join(root, name);
+    const fileSt = lstatSafe(abs);
+    if (fileSt && fileSt.isSymbolicLink()) {
+      warnings.push(`${name} is a symlink - left untouched (refusing to write through it)`);
+      continue;
+    }
+    if (stripManagedFile(abs).hadBlock) strippedBlocks.push(name);
   }
 
   // 3. Canonical store — remove ONLY if unmodified vs vendor.
@@ -78,18 +90,37 @@ export function uninstallProject(projectDir, packageRoot) {
     let vendor = null;
     try { vendor = hashDir(resolveSkillSource(packageRoot)); } catch { vendor = null; }
     if (vendor !== null && mine === vendor) {
-      rmSync(storeAbs, { recursive: true, force: true });
-      storeRemoved = true;
+      // Containment FIRST: a symlinked `.agents` would make this delete a
+      // tree OUTSIDE the project, so the guard runs before the removal.
+      try {
+        assertWithinRoot(root, storeAbs);
+        rmSync(storeAbs, { recursive: true, force: true });
+        storeRemoved = true;
+      } catch (e) {
+        storeKept = true;
+        warnings.push('canonical store kept at .agents/skills/archgen: ' + e.message);
+      }
     } else {
       storeKept = true;
       warnings.push('canonical store kept at .agents/skills/archgen: modified vs vendor (or unverifiable) - review manually');
     }
   }
 
-  // 4. Manifest file — then prune .archgen only if nothing else remains
+  // 4. MCP server entries — remove ONLY the archgen entries this install
+  //    wrote (the MCP server keeps a manifest of exactly what it created, so
+  //    unrelated servers in the same config are never touched).
+  let mcpRemoved = [];
+  const mcp = uninstallMcp({ projectRoot: root });
+  if (mcp.report?.removed?.length) {
+    mcpRemoved = mcp.report.removed;
+  } else if (mcp.detail) {
+    warnings.push(`archgen MCP entries not removed: ${mcp.detail}`);
+  }
+
+  // 5. Manifest file — then prune .archgen only if nothing else remains
   //    (feature folders / backups keep it alive).
   const manifestRemoved = rmIfExists(join(root, relJoin(MANIFEST_REL)));
   if (manifestRemoved) pruneEmptyParents(root, dirname(MANIFEST_REL));
 
-  return { root, linkRemoved, strippedBlocks, storeRemoved, storeKept, manifestRemoved, warnings };
+  return { root, linkRemoved, strippedBlocks, storeRemoved, storeKept, manifestRemoved, mcpRemoved, warnings };
 }

package/lib/version.js

@@ -1,15 +1,24 @@
 // version.js — semver compare + npm registry lookup (zero deps).
 import { spawnSync } from 'node:child_process';
+import { npmInvocation } from './spawn-npm.js';
 
 export function parseSemver(v) {
   const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(String(v ?? '').trim());
   return m ? { major: +m[1], minor: +m[2], patch: +m[3] } : null;
 }
 
+/**
+ * Compare two semver strings.
+ *
+ * @returns {number|null} -1 / 0 / 1, or null when either side is not a
+ *   semver. An unparseable version is NOT "equal" to anything: reporting 0
+ *   would make a registry tag like "beta" read as "already up to date" and
+ *   silently skip the caller's refusal path.
+ */
 export function compareSemver(a, b) {
   const x = parseSemver(a);
   const y = parseSemver(b);
-  if (!x || !y) return 0;
+  if (!x || !y) return null;
   for (const k of ['major', 'minor', 'patch']) {
     if (x[k] !== y[k]) return x[k] < y[k] ? -1 : 1;
   }
@@ -17,7 +26,14 @@ export function compareSemver(a, b) {
 }
 
 export function fetchLatestVersion(pkg) {
-  const r = spawnSync('npm', ['view', pkg, 'version'], { encoding: 'utf8', timeout: 15000 });
-  if (r.status !== 0 || !r.stdout) return null;
-  return r.stdout.trim().split(/\r?\n/).pop() || null;
+  // Registry-verified constant in every caller; refuse anything else outright.
+  if (!/^[a-z0-9@][a-z0-9._/-]*$/i.test(String(pkg ?? ''))) return null;
+  try {
+    const inv = npmInvocation(['view', String(pkg), 'version']);
+    const r = spawnSync(inv.command, inv.args, { encoding: 'utf8', timeout: 15000, shell: inv.shell });
+    if (r.status !== 0 || !r.stdout) return null;
+    return r.stdout.trim().split(/\r?\n/).pop() || null;
+  } catch {
+    return null;
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgen-skill",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Architecture generation & autonomous task execution for coding agents - conversational requirements in, dependency-ordered tasks out, executed wave-by-wave with verifier gates. Works with Claude Code, OpenCode, Cursor, Codex, Gemini CLI and any agentskills.io harness.",
   "license": "MIT",
   "type": "module",
@@ -14,7 +14,7 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "keywords": [
     "ai",
@@ -44,6 +44,6 @@
     "sync:check": "node scripts/sync-config.mjs --check",
     "sync": "node scripts/sync-config.mjs && node scripts/sync-vendor.mjs",
     "prepublishOnly": "node scripts/sync-config.mjs && node scripts/sync-vendor.mjs",
-    "test": "node --test test/*.test.mjs"
+    "test": "ARCHGEN_CODEGRAPH=0 node --test test/*.test.mjs"
   }
 }