archgen-skill 0.0.2 → 0.0.4

package/lib/store.js

@@ -0,0 +1,161 @@
+// store.js — shared primitives for the single-store project layout.
+//
+// Layout (all paths relative to the project root):
+//   .agents/skills/archgen            canonical store (the ONLY real copy)
+//   .agents/skills/archgen/.archgen-version  CLI version stamp (rewritten every init)
+//   .claude/skills/archgen            RELATIVE symlink -> ../../.agents/skills/archgen
+//   .archgen/.install-manifest.json   manifest of everything archgen created
+//   .archgen/.backup/<timestamp>/     divergent copies moved aside before replace
+//
+// Safety rails:
+// - 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.
+
+import { createHash } from 'node:crypto';
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  readlinkSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import { loadConfig } from './config.js';
+
+export const STORE_REL = '.agents/skills/archgen';
+export const CLAUDE_LINK_REL = '.claude/skills/archgen';
+
+// 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']);
+
+/** 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;
+}
+
+function byName(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * 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.
+ * @param {string} dir absolute directory to hash
+ * @param {{ignore?: string[]}} opts EXTRA relpaths to skip
+ */
+export function hashDir(dir, opts = {}) {
+  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.has(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'); }
+    }
+  })(dir, '');
+  return hash.digest('hex');
+}
+
+/** Load `.archgen/.install-manifest.json`; null when absent/corrupt. */
+export function loadManifest(root) {
+  const p = join(root, ...MANIFEST_REL.split('/'));
+  if (!existsSync(p)) return null;
+  try {
+    const m = JSON.parse(readFileSync(p, 'utf8'));
+    return m && typeof m === 'object' ? m : null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveManifest(root, manifest) {
+  const p = join(root, ...MANIFEST_REL.split('/'));
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(manifest, null, 2) + '\n');
+}
+
+/** Record a created dir/link/block; dedupes on kind+path. */
+export function appendEntry(root, kind, relPath) {
+  const now = new Date().toISOString();
+  const m = loadManifest(root) ?? { version: 1, createdAt: now, entries: [] };
+  if (!Array.isArray(m.entries)) m.entries = [];
+  if (m.entries.some((e) => e && e.kind === kind && e.path === relPath)) return;
+  m.version = m.version ?? 1;
+  m.createdAt = m.createdAt ?? now;
+  m.entries.push({ kind, path: relPath, createdAt: now });
+  saveManifest(root, m);
+}
+
+/**
+ * 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 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 {
+    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 */ }
+  if (!st) return false;
+  rmSync(absPath, { force: true, recursive: st.isDirectory() && !st.isSymbolicLink() });
+  return true;
+}
+
+/**
+ * Walk UPWARD from relPath removing directories only while they are left
+ * completely empty by our removals. Stops at guarded levels and the root —
+ * `.claude`, `.agents`, `.claude/skills`, `.agents/skills` are never deleted.
+ */
+export function pruneEmptyParents(root, relPath) {
+  let cur = relPath;
+  while (cur && cur !== '.') {
+    if (GUARDED_RELPATHS.has(cur)) break;
+    const abs = join(root, ...cur.split('/'));
+    let empty = false;
+    try { empty = readdirSync(abs).length === 0; } catch { break; }
+    if (!empty) break;
+    rmSync(abs, { recursive: true, force: true });
+    const parent = dirname(cur);
+    cur = parent === '.' ? '' : parent;
+  }
+}

package/lib/uninstall-project.js

@@ -0,0 +1,95 @@
+// uninstall-project.js — `archgen uninstall --project [dir]` removal with rails.
+//
+// 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.
+
+import { existsSync, lstatSync, readlinkSync, rmSync, unlinkSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { stripManagedFile } from './block.js';
+import {
+  CLAUDE_LINK_REL,
+  MANIFEST_REL,
+  STORE_REL,
+  VERSION_FILE,
+  hashDir,
+  pruneEmptyParents,
+  rmIfExists,
+} from './store.js';
+import { resolveSkillSource } from './init.js';
+
+function lstatSafe(p) {
+  try { return lstatSync(p); } catch { return null; }
+}
+
+function relJoin(rel) {
+  return join(...rel.split('/'));
+}
+
+/**
+ * @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[]}}
+ */
+export function uninstallProject(projectDir, packageRoot) {
+  const root = resolve(projectDir);
+  const warnings = [];
+  const strippedBlocks = [];
+
+  const storeAbs = join(root, relJoin(STORE_REL));
+  const claudeAbs = join(root, relJoin(CLAUDE_LINK_REL));
+
+  // 1. Claude adapter — remove only our own symlink (dangling included).
+  let linkRemoved = false;
+  const lst = lstatSafe(claudeAbs);
+  if (lst && lst.isSymbolicLink()) {
+    const target = resolve(dirname(claudeAbs), readlinkSync(claudeAbs));
+    if (target === storeAbs || !existsSync(claudeAbs)) {
+      unlinkSync(claudeAbs); // removes the link itself, never its target
+      linkRemoved = true;
+    } else {
+      warnings.push('foreign symlink at .claude/skills/archgen - left untouched');
+    }
+  } else if (lst && lst.isDirectory()) {
+    warnings.push('.claude/skills/archgen is a real directory - left untouched (remove manually if unwanted)');
+  }
+
+  // 2. Managed blocks — strip markers, keep all user content.
+  for (const name of ['AGENTS.md', 'CLAUDE.md']) {
+    if (stripManagedFile(join(root, name)).hadBlock) strippedBlocks.push(name);
+  }
+
+  // 3. Canonical store — remove ONLY if unmodified vs vendor.
+  //    The version stamp is our metadata, so it is ignored when comparing.
+  let storeRemoved = false;
+  let storeKept = false;
+  if (lstatSafe(storeAbs)) {
+    const st = lstatSafe(storeAbs);
+    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) {
+      rmSync(storeAbs, { recursive: true, force: true });
+      storeRemoved = true;
+    } 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
+  //    (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 };
+}

package/lib/version-stamp.js

@@ -0,0 +1,47 @@
+// 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 } 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);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, version + '\n', 'utf8');
+}

package/lib/version.js

@@ -0,0 +1,23 @@
+// version.js — semver compare + npm registry lookup (zero deps).
+import { spawnSync } from 'node:child_process';
+
+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;
+}
+
+export function compareSemver(a, b) {
+  const x = parseSemver(a);
+  const y = parseSemver(b);
+  if (!x || !y) return 0;
+  for (const k of ['major', 'minor', 'patch']) {
+    if (x[k] !== y[k]) return x[k] < y[k] ? -1 : 1;
+  }
+  return 0;
+}
+
+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;
+}

package/package.json

@@ -1,20 +1,48 @@
 {
   "name": "archgen-skill",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "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" },
+  "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.",
   "scripts": {
-    "sync": "node scripts/sync-vendor.mjs",
-    "prepublishOnly": "node scripts/sync-vendor.mjs",
+    "sync:config": "node scripts/sync-config.mjs",
+    "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"
   }
 }