archgen-skill 0.0.6 → 0.1.0

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

@@ -2,10 +2,11 @@
 //
 // Removes exactly what archgen owns in a project: the claude symlink, the
 // managed blocks, the canonical store (ONLY when unmodified vs the vendor
-// skill — a customized store is kept with a warning), and the install
-// manifest. `.archgen/<slug>` feature folders and `.archgen/.backup/` are
-// always preserved. Parents are pruned only when left completely empty, and
-// never past the guarded .claude/.agents levels.
+// skill — a customized store is kept with a warning), the install
+// manifest, and the legacy extension runtime directory. `.archgen/<slug>`
+// feature folders and `.archgen/.backup/` are always preserved. Parents are
+// pruned only when left completely empty, and never past the guarded
+// .claude/.agents levels.
 
 import { existsSync, lstatSync, readlinkSync, rmSync, unlinkSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
@@ -15,6 +16,7 @@ import {
   MANIFEST_REL,
   STORE_REL,
   VERSION_FILE,
+  assertWithinRoot,
   hashDir,
   pruneEmptyParents,
   rmIfExists,
@@ -35,6 +37,7 @@ function relJoin(rel) {
  * @param {string} packageRoot dir containing this CLI package (vendor source)
  * @returns {{root: string, linkRemoved: boolean, strippedBlocks: string[],
  *            storeRemoved: boolean, storeKept: boolean, manifestRemoved: boolean,
+ *            runtimeRemoved: boolean,
  *            mcpRemoved: string[], warnings: string[]}}
  */
 export function uninstallProject(projectDir, packageRoot) {
@@ -60,9 +63,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 +92,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');
@@ -104,5 +124,23 @@ export function uninstallProject(projectDir, packageRoot) {
   const manifestRemoved = rmIfExists(join(root, relJoin(MANIFEST_REL)));
   if (manifestRemoved) pruneEmptyParents(root, dirname(MANIFEST_REL));
 
-  return { root, linkRemoved, strippedBlocks, storeRemoved, storeKept, manifestRemoved, mcpRemoved, warnings };
+  // 6. The legacy extension runtime directory. The VS Code extension wrote a
+  //    heartbeat and per-command acknowledgements under `.archgen/.runtime/`;
+  //    it is dead state now that the extension and its bridge are gone, and it
+  //    is archgen-owned, so the uninstall removes it. Feature folders and
+  //    backups beside it are untouched.
+  const runtimeRemoved = rmIfExists(join(root, '.archgen', '.runtime'));
+  if (runtimeRemoved) pruneEmptyParents(root, '.archgen/.runtime');
+
+  return {
+    root,
+    linkRemoved,
+    strippedBlocks,
+    storeRemoved,
+    storeKept,
+    manifestRemoved,
+    runtimeRemoved,
+    mcpRemoved,
+    warnings,
+  };
 }

package/lib/version-stamp.js

@@ -1,7 +1,7 @@
 // version-stamp.js — the `.archgen-version` stamp contract.
 //
-// WHY: the VS Code extension reads `<skillRoot>/.archgen-version` to tell an
-// outdated skill copy from a current one and warns non-blockingly (missing or
+// WHY: the MCP server reads `<skillRoot>/.archgen-version` to tell an
+// outdated skill copy from a current one and reports it (missing or
 // unparseable content means "unknown (legacy)" — a pre-stamp install). The
 // CLI is the only writer: every operation that lays down skill files (init,
 // global install in symlink AND --copy mode, update via its init/doctor

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.1.0",
   "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",
@@ -38,10 +38,10 @@
   "bugs": {
     "url": "https://github.com/akashmaurya99/archgen/issues"
   },
-  "//": "vendor/skills/archgen is a full mirror of ../../skill synced by scripts/sync-vendor.mjs (run automatically via prepublishOnly). The extension ships separately as a VS Code vsix.",
+  "//": "vendor/skills/archgen is a full mirror of ../../skill synced by scripts/sync-vendor.mjs (run automatically via prepublishOnly).",
   "scripts": {
     "sync:config": "node scripts/sync-config.mjs",
-    "sync:check": "node scripts/sync-config.mjs --check",
+    "sync:check": "node scripts/sync-config.mjs --check && node scripts/sync-vendor.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": "ARCHGEN_CODEGRAPH=0 node --test test/*.test.mjs"