archgen-skill 0.0.3 → 0.0.5

package/lib/store.js

@@ -11,7 +11,11 @@
 // - hashDir() fingerprints a tree (stable-order walk of relpaths + contents,
 //   sha256) so mutations only ever happen after verifying ownership/divergence;
 // - GUARDED_RELPATHS (.claude, .agents, .claude/skills, .agents/skills) are
-//   never deleted: parent pruning stops before touching those levels.
+//   never deleted: parent pruning stops before touching those levels;
+// - assertNotSymlink()/assertWithinRoot() lstat BEFORE every write: a
+//   symlinked target (supply-chain attack: a malicious clone shipping
+//   .agents/skills/archgen or AGENTS.md as a link to an unrelated directory)
+//   is refused instead of written through.
 
 import { createHash } from 'node:crypto';
 import {
@@ -22,20 +26,91 @@ import {
   readFileSync,
   readdirSync,
   readlinkSync,
+  realpathSync,
   renameSync,
   rmSync,
   writeFileSync,
 } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, sep } from 'node:path';
+import { loadConfig } from './config.js';
 
 export const STORE_REL = '.agents/skills/archgen';
 export const CLAUDE_LINK_REL = '.claude/skills/archgen';
-export const MANIFEST_REL = '.archgen/.install-manifest.json';
-export const BACKUP_ROOT_REL = '.archgen/.backup';
-export const VERSION_FILE = '.archgen-version';
+
+// Filenames routed through the canonical config (STORE_REL/CLAUDE_LINK_REL
+// stay literal: they are path semantics, not config).
+const CONFIG_FILES = loadConfig().files;
+export const MANIFEST_REL = '.archgen/' + CONFIG_FILES.projectManifest;
+export const BACKUP_ROOT_REL = '.archgen/' + CONFIG_FILES.backupDir;
+export const VERSION_FILE = CONFIG_FILES.stamp;
 
 const GUARDED_RELPATHS = new Set(['.claude', '.agents', '.claude/skills', '.agents/skills']);
 
+/**
+ * Dev-only skill subtrees that must NEVER be distributed to end users. The
+ * repo's own node:test suite (scripts/test) is repo-only CI tooling: nothing
+ * imports it at runtime and it references repo-only fixtures
+ * (fixtures/yaml-corpus), so it cannot run in an installed project — shipping
+ * it into installed stores or the npm payload is dead weight. It is excluded
+ * consistently from the vendor mirror, every installed-store copy, and BOTH
+ * sides of hashDir comparisons (so its presence/absence never reads as drift).
+ * scripts/lib is deliberately NOT here — it is a runtime dependency of the
+ * skill scripts (imported by next-tasks/plan-graph/set-status/doc-index/etc).
+ */
+export const DEV_ONLY_RELPATHS = ['scripts/test'];
+
+/** True when relpath `r` is (or lives inside) a dev-only excluded subtree. */
+function isDevOnlyRelPath(r) {
+  for (const prefix of DEV_ONLY_RELPATHS) {
+    if (r === prefix || r.startsWith(prefix + '/')) return true;
+  }
+  return false;
+}
+
+/** Canonical refusal message for every symlink-write guard (CLI + install.sh). */
+export function refuseSymlinkMessage(absPath) {
+  return 'Refusing to write through symlink at ' + absPath + ' — use --copy or remove symlink';
+}
+
+/**
+ * Supply-chain guard: lstat (never stat — the LINK itself, not its target) a
+ * path before writing it. Absent paths pass (safe to create); a symlink at
+ * the target throws so no write can ever be redirected through the link.
+ */
+export function assertNotSymlink(absPath) {
+  let st = null;
+  try { st = lstatSync(absPath); } catch { return; }
+  if (st.isSymbolicLink()) throw new Error(refuseSymlinkMessage(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.
+ */
+export function assertWithinRoot(rootAbs, absPath) {
+  let rootReal;
+  try { rootReal = realpathSync(rootAbs); } catch { return; }
+  let probe = absPath;
+  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;
+    }
+    const parent = dirname(probe);
+    if (parent === probe) return;
+    probe = parent;
+  }
+}
+
 /** Version string of this CLI package (used for the in-store stamp). */
 export function cliVersion(packageRoot) {
   return JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')).version;
@@ -48,17 +123,24 @@ function byName(a, b) {
 /**
  * Stable-order directory fingerprint: sha256 over sorted relpaths plus file
  * contents (symlinks hashed via their targets). Deterministic across machines.
+ * The version stamp is ALWAYS ignored on both sides of a comparison: it is
+ * CLI metadata written at destination time (global symlink installs stamp the
+ * shared real copy), never skill content, so it must not read as divergence.
+ * DEV_ONLY_RELPATHS (scripts/test) are ALSO always ignored on both sides: they
+ * are pruned from every distributed copy, so a source tree that still carries
+ * them (the dev-checkout skill/ fallback) must hash equal to an installed store
+ * that does not — while a real edit anywhere else must still read as divergence.
  * @param {string} dir absolute directory to hash
- * @param {{ignore?: string[]}} opts relpaths to skip (e.g. our version stamp)
+ * @param {{ignore?: string[]}} opts EXTRA relpaths to skip
  */
 export function hashDir(dir, opts = {}) {
-  const ignore = opts.ignore ?? [];
+  const ignore = new Set([VERSION_FILE, ...(opts.ignore ?? [])]);
   const hash = createHash('sha256');
   (function walk(abs, rel) {
     const entries = readdirSync(abs, { withFileTypes: true }).sort((a, b) => byName(a.name, b.name));
     for (const ent of entries) {
       const r = rel ? rel + '/' + ent.name : ent.name;
-      if (ignore.includes(r)) continue;
+      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); }
@@ -68,6 +150,20 @@ export function hashDir(dir, opts = {}) {
   return hash.digest('hex');
 }
 
+/**
+ * Remove every dev-only subtree (DEV_ONLY_RELPATHS) from an absolute skill-tree
+ * root; idempotent no-op when a subtree is absent. Called after EVERY copy of
+ * the skill into a distributed location (installed store, global --copy tree,
+ * vendor mirror) so dev-only artifacts never reach end users regardless of which
+ * source resolveSkillSource picked — vendor is already pruned by sync-vendor,
+ * but the dev-checkout skill/ fallback is not, and this normalizes both.
+ */
+export function pruneDevOnly(absRoot) {
+  for (const rel of DEV_ONLY_RELPATHS) {
+    rmSync(join(absRoot, ...rel.split('/')), { recursive: true, force: true });
+  }
+}
+
 /** Load `.archgen/.install-manifest.json`; null when absent/corrupt. */
 export function loadManifest(root) {
   const p = join(root, ...MANIFEST_REL.split('/'));
@@ -83,6 +179,7 @@ export function loadManifest(root) {
 export function saveManifest(root, manifest) {
   const p = join(root, ...MANIFEST_REL.split('/'));
   mkdirSync(dirname(p), { recursive: true });
+  assertNotSymlink(p);
   writeFileSync(p, JSON.stringify(manifest, null, 2) + '\n');
 }
 
@@ -99,25 +196,38 @@ export function appendEntry(root, kind, relPath) {
 }
 
 /**
- * Move an existing project-relative path into `.archgen/.backup/<ts>/<rel>`.
- * Preserves the relative layout so backups restore unambiguously.
- * @returns {string} backup location relative to the project root
+ * 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.
+ * @returns {string} backup location relative to `root`
  */
-export function moveToBackup(root, relPath) {
-  const ts = new Date().toISOString().replace(/:/g, '-');
-  const destRel = BACKUP_ROOT_REL + '/' + ts + '/' + relPath;
+export function moveToBackupInto(root, relPath, backupRootRel, ts = new Date().toISOString().replace(/:/g, '-')) {
+  const destRel = backupRootRel + '/' + ts + '/' + relPath;
   const destAbs = join(root, ...destRel.split('/'));
   mkdirSync(dirname(destAbs), { recursive: true });
   const srcAbs = join(root, ...relPath.split('/'));
   try {
     renameSync(srcAbs, destAbs);
-  } catch {
+  } catch (err) {
+    // Fallback copy+remove must NEVER run on a symlinked source: cpSync would
+    // read through the link and rmSync would remove it — rethrow instead so
+    // the caller refuses the replace rather than touching the link's target.
+    let st = null;
+    try { st = lstatSync(srcAbs); } catch { /* vanished mid-move */ }
+    if (st && st.isSymbolicLink()) throw err;
     cpSync(srcAbs, destAbs, { recursive: true });
     rmSync(srcAbs, { recursive: true, force: true });
   }
   return destRel;
 }
 
+/** Project-root flavor: move `relPath` under `.archgen/.backup/<ts>/<relPath>`. */
+export function moveToBackup(root, relPath) {
+  return moveToBackupInto(root, relPath, BACKUP_ROOT_REL);
+}
+
 export function rmIfExists(absPath) {
   let st = null;
   try { st = lstatSync(absPath); } catch { /* absent */ }

package/lib/uninstall-project.js

@@ -69,9 +69,12 @@ export function uninstallProject(projectDir, packageRoot) {
   let storeKept = false;
   if (lstatSafe(storeAbs)) {
     const st = lstatSafe(storeAbs);
-    const mine = st.isDirectory() && !st.isSymbolicLink()
-      ? hashDir(storeAbs, { ignore: [VERSION_FILE] })
-      : null;
+    let mine = null;
+    if (st.isDirectory() && !st.isSymbolicLink()) {
+      // An unreadable/diverging-mid-walk tree must degrade to "kept", never
+      // crash the uninstall.
+      try { mine = hashDir(storeAbs, { ignore: [VERSION_FILE] }); } catch { mine = null; }
+    }
     let vendor = null;
     try { vendor = hashDir(resolveSkillSource(packageRoot)); } catch { vendor = null; }
     if (vendor !== null && mine === vendor) {

package/lib/version-stamp.js

@@ -0,0 +1,49 @@
+// 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
+// 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
+// refresh) rewrites the stamp with the CLI's own package version.
+//
+// Format: EXACTLY `MAJOR.MINOR.PATCH\n`, utf8, no BOM. Readers elsewhere trim
+// before validating, so CRLF/whitespace is tolerated on read — this writer
+// never produces it. Absent file and invalid content both read as null.
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { VERSION_FILE, assertNotSymlink } from './store.js';
+
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+
+/**
+ * Read the stamp from a skill root (the directory containing SKILL.md).
+ * @returns {string|null} the trimmed `MAJOR.MINOR.PATCH` string, or null when
+ *   the stamp is absent, unreadable, or not plain semver ("unknown").
+ */
+export function readStamp(skillRoot) {
+  if (!skillRoot) return null;
+  let raw;
+  try {
+    raw = readFileSync(join(skillRoot, VERSION_FILE), 'utf8');
+  } catch {
+    return null; // absent (legacy pre-stamp install) or unreadable
+  }
+  const body = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+  const v = body.trim();
+  return SEMVER_RE.test(v) ? v : null;
+}
+
+/**
+ * Write/refresh the stamp inside a skill root. Idempotent: overwriting an
+ * existing stamp with the same version yields byte-identical content.
+ * Creates parent directories as needed.
+ */
+export function writeStamp(skillRoot, version) {
+  const p = join(skillRoot, VERSION_FILE);
+  assertNotSymlink(skillRoot);
+  mkdirSync(dirname(p), { recursive: true });
+  assertNotSymlink(p);
+  writeFileSync(p, version + '\n', 'utf8');
+}

package/package.json

@@ -1,20 +1,49 @@
 {
   "name": "archgen-skill",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "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",
-  "bin": { "archgen-skill": "bin/archgen.mjs" },
-  "files": ["bin/", "lib/", "vendor/", "README.md"],
-  "engines": { "node": ">=18" },
-  "keywords": ["ai", "agents", "claude", "codex", "cursor", "opencode", "gemini", "architecture", "skills", "orchestration", "task-graph", "planning"],
-  "repository": { "type": "git", "url": "git+https://github.com/akashmaurya99/archgen.git" },
+  "bin": {
+    "archgen-skill": "bin/archgen.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "vendor/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "claude",
+    "codex",
+    "cursor",
+    "opencode",
+    "gemini",
+    "architecture",
+    "skills",
+    "orchestration",
+    "task-graph",
+    "planning"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/akashmaurya99/archgen.git"
+  },
   "homepage": "https://github.com/akashmaurya99/archgen#readme",
-  "bugs": { "url": "https://github.com/akashmaurya99/archgen/issues" },
-  "//": "vendor/skills/archgen is synced from ../skills/archgen by scripts/sync-vendor.mjs (run automatically via prepublishOnly). The extension ships separately as a VS Code vsix.",
+  "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.",
   "scripts": {
-    "sync": "node scripts/sync-vendor.mjs",
-    "prepublishOnly": "node scripts/sync-vendor.mjs",
+    "sync:config": "node scripts/sync-config.mjs",
+    "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"
   }
 }