archgen-skill 0.0.6 → 0.0.7

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

@@ -10,7 +10,7 @@
 // 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,8 +30,8 @@ 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 };
@@ -52,3 +53,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;
+}

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']);
 
 /**
@@ -133,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));
   }
 }
 
@@ -248,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');
 }
 
@@ -265,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, '-')) {
@@ -290,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,6 +15,7 @@ import {
   MANIFEST_REL,
   STORE_REL,
   VERSION_FILE,
+  assertWithinRoot,
   hashDir,
   pruneEmptyParents,
   rmIfExists,
@@ -60,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.
@@ -80,8 +90,16 @@ 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');

package/lib/version.js

@@ -7,10 +7,18 @@ export function parseSemver(v) {
   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;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgen-skill",
-  "version": "0.0.6",
+  "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",

package/vendor/skills/archgen/SKILL.md

@@ -4,10 +4,10 @@ description: Architecture generation and autonomous task execution for coding ag
 license: MIT
 compatibility: Requires Node.js >= 20. The archgen MCP server (archgen-mcp) provides every deterministic capability; the skill itself ships no code.
 metadata:
-  version: 0.0.6
+  version: 0.0.7
   repo: https://github.com/akashmaurya99/archgen
   requires:
-    archgen_mcp: ">=0.0.6"
+    archgen_mcp: ">=0.0.7"
 ---
 
 # archgen — architecture generation & wave execution

package/vendor/skills/archgen/archgen.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.6",
+  "version": "0.0.7",
   "skillName": "archgen",
   "markers": {
     "start": "<!-- archgen:start (managed block - do not edit between markers) -->",