archgen-skill 0.0.3 → 0.0.4

package/lib/install.js

@@ -2,19 +2,31 @@
 // Installs the archgen skill into every EXISTING harness skills dir; manifest
 // records entries so --uninstall removes exactly what we put there.
 
-import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync, lstatSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync, lstatSync, unlinkSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolveSkillSource } from './init.js';
+import { cliVersion, hashDir, moveToBackupInto } from './store.js';
+import { writeStamp } from './version-stamp.js';
+import { loadConfig } from './config.js';
 
 // Module-anchored default: works from the npm package (cli/lib -> cli/vendor)
 // AND from a monorepo checkout (packages/cli/lib -> ../../skill) without depending on cwd.
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
-const MANIFEST_NAME = '.archgen-install-manifest.list';
+export const MANIFEST_NAME = loadConfig().files.globalManifest;
 
-function globalTargets(home = homedir()) {
+// Global backup vault: global installs live OUTSIDE any project, so there is
+// no project root to host `.archgen/.backup/`. Convention chosen instead: each
+// harness skills dir keeps its own sibling vault at
+//   <skills-dir>/.archgen-backups/<ISO-timestamp>/archgen/
+// — a dot-prefixed sibling (never scanned as a skill by harnesses), colocated
+// with what it protects, and discovered by lib/restore.js alongside the
+// project vault.
+export const GLOBAL_BACKUP_REL = '.archgen-backups';
+
+export function globalTargets(home = homedir()) {
   return [
     join(home, '.claude', 'skills'),
     join(home, '.agents', 'skills'),
@@ -32,15 +44,33 @@ function record(manifest, kind, path) {
   if (!dup) writeFileSync(manifest, (existsSync(manifest) ? readFileSync(manifest, 'utf8').replace(/\n*$/, '\n') : '') + line + '\n');
 }
 
+function lstatSafe(p) {
+  try { return lstatSync(p); } catch { return null; }
+}
+
+/** Collision-free timestamp for `<tdir>/.archgen-backups/<ts>/` (ms clock can tick twice). */
+function nextBackupTs(tdir) {
+  for (;;) {
+    const ts = new Date().toISOString().replace(/:/g, '-');
+    if (!existsSync(join(tdir, GLOBAL_BACKUP_REL, ts))) return ts;
+  }
+}
+
 /**
- * @param {{copy?: boolean, home?: string}} opts
+ * @param {{copy?: boolean, home?: string, packageRoot?: string}} opts
+ * @returns {{rows: Array<[string, string, string]>, failures: number, manifest: string,
+ *            backups: string[]}} rows are [STATUS, MODE, PATH]; `backups` lists
+ *            absolute vault locations written by this run.
  */
 export function installGlobal(opts = {}) {
   const home = opts.home ?? homedir();
   if (!home) throw new Error('$HOME is not set; cannot resolve target directories.');
-  const source = resolve(resolveSkillSource(opts.packageRoot ?? PACKAGE_ROOT));
+  const packageRoot = opts.packageRoot ?? PACKAGE_ROOT;
+  const source = resolve(resolveSkillSource(packageRoot));
+  const version = cliVersion(packageRoot);
   const manifest = join(home, MANIFEST_NAME);
   const rows = [];
+  const backups = [];
   let failures = 0;
 
   const targets = [...globalTargets(home), join(process.cwd(), '.github', 'skills')];
@@ -50,23 +80,84 @@ export function installGlobal(opts = {}) {
     try {
       mkdirSync(tdir, { recursive: true }); // no-op when present
       if (opts.copy) {
-        rmSync(dest, { force: true, recursive: true });
-        cpSync(source, dest, { recursive: true });
-        record(manifest, 'copy', dest);
-        rows.push(['OK', 'copy', dest]);
+        // Safety invariant: fingerprint dest BEFORE mutating; identical
+        // (stamp-ignoring) skips like link mode, divergent moves into the
+        // vault first — nothing is rmSync'd without a prior backup of it.
+        const prev = lstatSafe(dest);
+        let identical = false;
+        if (prev && prev.isDirectory() && !prev.isSymbolicLink()) {
+          try { identical = hashDir(dest) === hashDir(source); } catch { identical = false; }
+        }
+        if (identical) {
+          stampNote(rows, dest, () => writeStamp(dest, version));
+          record(manifest, 'copy', dest);
+          rows.push(['SAME', 'copy', dest]);
+        } else {
+          if (prev) {
+            const loc = moveToBackupInto(tdir, 'archgen', GLOBAL_BACKUP_REL, nextBackupTs(tdir));
+            const abs = join(tdir, ...loc.split('/'));
+            backups.push(abs);
+            rows.push(['BACKED-UP', '-', abs]);
+          }
+          rmSync(dest, { force: true, recursive: true }); // no-op after a move; guards exotic-FS fallbacks
+          cpSync(source, dest, { recursive: true });
+          stampNote(rows, dest, () => writeStamp(dest, version));
+          record(manifest, 'copy', dest);
+          rows.push(['OK', 'copy', dest]);
+        }
       } else {
-        let same = false;
-        try { same = lstatSync(dest).isSymbolicLink(); } catch { /* absent */ }
-        if (!same) symlinkSync(source, dest, 'dir');
+        let status = 'OK';
+        const prev = lstatSafe(dest);
+        if (prev && prev.isSymbolicLink()) {
+          if (existsSync(dest)) {
+            // A live link resolving anywhere but our source belongs to the
+            // user: leave it untouched and OUT of the uninstall manifest, or
+            // `uninstall` would later delete their link. (install.sh replaces
+            // foreign links via ln -sfn — that destructive semantic is
+            // deliberately NOT copied here.)
+            const linkTarget = resolve(dirname(dest), readlinkSync(dest));
+            if (linkTarget !== source) {
+              rows.push(['KEPT', '-', dest + ' (foreign symlink, not recorded)']);
+              continue;
+            }
+            status = 'SAME';
+          } else {
+            // Dangling (npx cache eviction): recreate against the current
+            // source instead of leaving users broken while reporting SAME.
+            unlinkSync(dest); // removes the link itself, never any target
+            symlinkSync(source, dest, 'dir');
+            status = 'REPAIRED';
+          }
+        } else if (!prev) {
+          symlinkSync(source, dest, 'dir');
+        } else {
+          // Real directory/file at dest is NEVER clobbered: symlinkSync fails
+          // with EEXIST and surfaces as FAILED below (historical behavior).
+          symlinkSync(source, dest, 'dir');
+        }
+        // The link itself holds no bytes: the stamp must live INSIDE the real
+        // directory the link resolves to (the shared copy) so a read of
+        // <link>/.archgen-version sees it — true for symlinks and Windows
+        // junctions alike.
+        stampNote(rows, dest, () => writeStamp(source, version));
         record(manifest, 'link', dest);
-        rows.push([same ? 'SAME' : 'OK', 'link', dest]);
+        rows.push([status, 'link', dest]);
       }
     } catch (e) {
       failures++;
       rows.push(['FAILED', '-', dest + ' (' + e.message + ')']);
     }
   }
-  return { rows, failures, manifest };
+  return { rows, failures, manifest, backups };
+}
+
+/** Install succeeded even when the stamp could not be written (e.g. read-only vendor); surface it without failing. */
+function stampNote(rows, dest, write) {
+  try {
+    write();
+  } catch (e) {
+    rows.push(['WARN', '-', dest + ' (installed; version stamp not written: ' + e.message + ')']);
+  }
 }
 
 export function uninstallGlobal(home = homedir()) {

package/lib/migrate.js

@@ -0,0 +1,88 @@
+// migrate.js — `archgen migrate [dir] [--check] [--apply] [--migration <id>]`.
+//
+// Evolves generated-artifact formats in existing projects with zero data loss.
+// Tone and safety model mirror doctor: dry-run is the DEFAULT (--check lists
+// pending migrations and the exact files they would touch, writing nothing);
+// --apply runs them, snapshotting every affected file into
+// .archgen/.backup/<ts>/migrate/ BEFORE any modification. Exit codes:
+//   0  nothing pending, or all migrations applied cleanly
+//   1  a migration failed mid-apply (earlier files stay backed up)
+//   2  usage error (unknown flag / unknown --migration id / --check + --apply)
+//
+// bin/archgen.mjs wiring (integrator):
+//   case 'migrate': process.exitCode = await migrateMain(rest); break;
+
+import { applyMigration, listMigrations, pendingMigrations } from './migrations/index.mjs';
+import { resolve } from 'node:path';
+
+const USAGE = 'usage: archgen-skill migrate [dir] [--check|--apply] [--migration <id>]';
+
+/**
+ * @param {string[]} argv args AFTER the subcommand, e.g. ['myproj', '--apply']
+ * @returns {Promise<number>} exit code int
+ */
+export async function migrateMain(argv = []) {
+  let dir = null;
+  let check = false;
+  let apply = false;
+  let target = null;
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--check') check = true;
+    else if (a === '--apply') apply = true;
+    else if (a === '--migration') {
+      target = argv[++i];
+      if (!target || target.startsWith('-')) { console.error(USAGE); return 2; }
+    } else if (a.startsWith('-')) {
+      console.error(`unknown flag: ${a}\n${USAGE}`);
+      return 2;
+    } else if (dir === null) dir = a;
+    else { console.error(`unexpected argument: ${a}\n${USAGE}`); return 2; }
+  }
+  if (check && apply) { console.error('--check and --apply are mutually exclusive\n' + USAGE); return 2; }
+
+  const dryRun = !apply; // check mode is the default, always
+  const root = resolve(dir ?? process.cwd());
+
+  const all = await listMigrations();
+  if (target && !all.some((m) => m.id === target)) {
+    console.error(`unknown migration '${target}' (available: ${all.map((m) => m.id).join(', ') || 'none'})`);
+    return 2;
+  }
+
+  const pending = (await pendingMigrations(root)).filter((p) => !target || p.id === target);
+
+  console.log('archgen migrate — ' + root + (dryRun ? '  (check mode: no changes made)' : ''));
+
+  if (pending.length === 0) {
+    console.log('  = nothing to do — all migrations applied');
+    console.log('Summary: up to date — 0 pending');
+    return 0;
+  }
+
+  let fileCount = 0;
+  let failed = 0;
+  for (const p of pending) {
+    if (dryRun) {
+      console.log(`  [would-apply] ${p.id} — ${p.description}`);
+      for (const f of p.files) console.log(`      ${f}`);
+      fileCount += p.files.length;
+      continue;
+    }
+    try {
+      const r = await applyMigration(p.id, root, { dryRun: false });
+      if (r.status === 'clean') { console.log(`  [skip] ${r.id} — already applied`); continue; }
+      console.log(`  [applied] ${r.id} — ${r.description}`);
+      for (const b of r.backups ?? []) console.log(`      ${b.file}  (backup: ${b.backup})`);
+      fileCount += (r.files ?? []).length;
+    } catch (e) {
+      failed++;
+      console.log(`  [fail] ${p.id} — ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+
+  if (dryRun) console.log(`Summary: ${pending.length} migration(s) pending, ${fileCount} file(s) would change`);
+  else console.log(`Summary: ${pending.length - failed} applied, ${fileCount} file(s) changed, ${failed} failure(s)`);
+  return failed > 0 ? 1 : 0;
+}

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

@@ -0,0 +1,77 @@
+// 001-stamp-provenance.mjs — backfill the provenance header onto artifacts
+// generated before the convention existed (see skill/references/
+// artifact-templates.md for the forward-looking rule).
+//
+// What it writes: three YAML COMMENT lines at the very top of tasks.yaml and
+// architecture.yaml. Comments are inert to every consumer by contract — the
+// skill's zero-dep parser records them positionally (set-status.mjs preserves
+// them verbatim), verify-plan.mjs never sees them as data, and the VS Code
+// extension port behaves identically. Additive-only: no existing key is
+// touched, nothing becomes required.
+//
+//   # schema_version: 1
+//   # generator: archgen v0.0.4      (version token omitted when unknowable)
+//   # generated_at: 2026-08-26T09:00:00.000Z
+//
+// Idempotency: detect/files/apply all key off the `# schema_version:` marker
+// line; stamped files are invisible to this migration, so a second run is a
+// no-op. apply() re-checks per file before writing — it can never double-stamp.
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SCHEMA_VERSION = 1;
+const MARKER_RE = /^#\s*schema_version:\s*\d+\s*$/m;
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+const STORE_VERSION_REL = '.agents/skills/archgen/.archgen-version';
+
+export const id = '001-stamp-provenance';
+export const description = 'stamp provenance header (schema_version / generator / generated_at) onto tasks.yaml and architecture.yaml';
+export const fromSchema = null;
+export const toSchema = SCHEMA_VERSION;
+
+/**
+ * Code-defensive generator version: trust only an exact semver stamp in the
+ * canonical store; anything else (absent, corrupt, pre-stamp) omits the token
+ * rather than guessing.
+ */
+function generatorToken(projectRoot) {
+  try {
+    const v = readFileSync(join(projectRoot, ...STORE_VERSION_REL.split('/')), 'utf8').trim();
+    if (SEMVER_RE.test(v)) return `archgen v${v}`;
+  } catch { /* absent or unreadable */ }
+  return 'archgen';
+}
+
+function stampLines(projectRoot, generatedAt) {
+  return [
+    `# schema_version: ${SCHEMA_VERSION}`,
+    `# generator: ${generatorToken(projectRoot)}`,
+    `# generated_at: ${generatedAt}`,
+  ];
+}
+
+function unstampedArtifacts(ctx) {
+  return ctx.scanArtifacts().filter((a) => {
+    const abs = join(ctx.projectRoot, ...a.rel.split('/'));
+    return !MARKER_RE.test(readFileSync(abs, 'utf8'));
+  });
+}
+
+export function detect(ctx) {
+  return unstampedArtifacts(ctx).length > 0;
+}
+
+export function files(ctx) {
+  return unstampedArtifacts(ctx).map((a) => a.rel);
+}
+
+export function apply(ctx) {
+  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');
+    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

@@ -0,0 +1,170 @@
+// migrations/index.mjs — artifact-format migration framework.
+//
+// Generated artifacts live under `.archgen/<slug>/` and are written by LLM
+// agents (never the CLI). As the artifact formats evolve, old projects must be
+// brought forward WITHOUT data loss. This framework is the mechanism:
+//
+//   - 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/`;
+//   - dry-run is the DEFAULT everywhere: nothing is written unless a caller
+//     explicitly passes `{ dryRun: false }`.
+//
+// Migration file contract (named exports; a default object is also accepted):
+//   export const id          — '001-stamp-provenance' (MUST equal the filename stem)
+//   export const description — one line, doctor-tone
+//   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 files(ctx)  -> string[] of project-relative paths that
+//                                  apply() may touch (drives --check output
+//                                  AND the mandatory pre-apply backup set)
+//
+// ctx shape (built here, passed to detect/files/apply):
+//   ctx.projectRoot   absolute root
+//   ctx.dryRun        true unless explicitly applying
+//   ctx.scanArtifacts() -> [{ rel, kind }] for .archgen/*/tasks.yaml and
+//                          .archgen/*/architecture.yaml (dot-dirs skipped)
+//   ctx.backup(rel)   snapshot one project-relative file into
+//                     .archgen/.backup/<ts>/migrate/<rel>; THROWS under
+//                     dry-run so a mutating migration can never run silently
+
+import { copyFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { BACKUP_ROOT_REL } from '../store.js';
+
+const MIGRATION_FILE_RE = /^(\d{3}-[a-z0-9][a-z0-9-]*)\.mjs$/;
+
+/**
+ * Load every migration file, sorted by id (numeric prefix == order).
+ * Malformed migrations fail LOUDLY here — a silently-skipped migration would
+ * corrupt the "everything applied" invariant.
+ * @returns {Promise<Array<{id: string, description: string, fromSchema: number|null,
+ *   toSchema: number, detect: Function, apply: Function, files?: Function}>>}
+ */
+export async function listMigrations() {
+  const dir = dirname(fileURLToPath(import.meta.url));
+  const stems = readdirSync(dir)
+    .map((f) => MIGRATION_FILE_RE.exec(f)?.[1])
+    .filter(Boolean)
+    .sort();
+  const out = [];
+  for (const stem of stems) {
+    const mod = await import(pathToFileURL(join(dir, stem + '.mjs')).href);
+    out.push(normalize(mod.default ?? mod, stem));
+  }
+  return out;
+}
+
+function normalize(m, stem) {
+  const fail = (why) => {
+    throw new Error(`migration ${stem}.mjs is malformed: ${why}`);
+  };
+  if (!m || typeof m !== 'object') fail('no exports');
+  if (m.id !== stem) fail(`id '${m.id}' must equal filename stem '${stem}'`);
+  if (typeof m.description !== 'string' || !m.description) fail('missing description');
+  if (!(m.fromSchema === null || typeof m.fromSchema === 'number')) fail('fromSchema must be a number or null');
+  if (typeof m.toSchema !== 'number') fail('toSchema must be a number');
+  if (typeof m.detect !== 'function') fail('missing detect(ctx)');
+  if (typeof m.apply !== 'function') fail('missing apply(ctx)');
+  if (m.files !== undefined && typeof m.files !== 'function') fail('files must be a function');
+  return m;
+}
+
+/** Build the migration context. Internal — exported for tests only. */
+export function makeCtx(projectRoot, { dryRun }) {
+  const root = resolve(projectRoot);
+  // One timestamp per context: all backups from a single apply run group
+  // under one directory (colons stripped, same convention as store.moveToBackup).
+  const ts = new Date().toISOString().replace(/:/g, '-');
+  return {
+    projectRoot: root,
+    dryRun: dryRun === true,
+
+    /** Discover generated artifacts this framework knows how to migrate. */
+    scanArtifacts() {
+      const base = join(root, '.archgen');
+      if (!existsSync(base)) return [];
+      const out = [];
+      const slugs = readdirSync(base, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+        .map((e) => e.name)
+        .sort();
+      for (const slug of slugs) {
+        for (const f of ['tasks.yaml', 'architecture.yaml']) {
+          const abs = join(base, slug, f);
+          if (existsSync(abs) && statSync(abs).isFile()) {
+            out.push({ rel: `.archgen/${slug}/${f}`, kind: f.replace(/\.yaml$/, '') });
+          }
+        }
+      }
+      return out;
+    },
+
+    /**
+     * Snapshot a project-relative file into `.archgen/.backup/<ts>/migrate/`.
+     * Copy (not move): the original stays in place until apply() rewrites it.
+     * @param {string} relPath project-relative, e.g. `.archgen/demo/tasks.yaml`
+     * @returns {string} backup location relative to the project root
+     */
+    backup(relPath) {
+      if (this.dryRun) throw new Error(`backup('${relPath}') called during dry-run — migrations must never mutate under --check`);
+      const srcAbs = join(root, ...relPath.split('/'));
+      const destRel = `${BACKUP_ROOT_REL}/${ts}/migrate/${relPath}`;
+      const destAbs = join(root, ...destRel.split('/'));
+      mkdirSync(dirname(destAbs), { recursive: true });
+      copyFileSync(srcAbs, destAbs);
+      return destRel;
+    },
+  };
+}
+
+/**
+ * Migrations not yet satisfied by `projectRoot`, in order. ALWAYS read-only.
+ * @returns {Promise<Array<{id: string, description: string, fromSchema: number|null,
+ *   toSchema: number, files: string[]}>>}
+ */
+export async function pendingMigrations(projectRoot) {
+  const pending = [];
+  for (const mig of await listMigrations()) {
+    const ctx = makeCtx(projectRoot, { dryRun: true });
+    if (!mig.detect(ctx)) continue;
+    pending.push({
+      id: mig.id,
+      description: mig.description,
+      fromSchema: mig.fromSchema,
+      toSchema: mig.toSchema,
+      files: mig.files ? mig.files(ctx).slice() : [],
+    });
+  }
+  return pending;
+}
+
+/**
+ * Run one migration against `projectRoot`.
+ * @param {string} id migration id (filename stem)
+ * @param {string} projectRoot
+ * @param {{dryRun?: boolean}} opts dryRun defaults to TRUE — pass
+ *   `{ dryRun: false }` to mutate (every declared file is backed up first)
+ * @returns {Promise<{status: 'applied'|'would-apply'|'clean'|'not-found',
+ *   id: string, description?: string, files?: string[],
+ *   backups?: Array<{file: string, backup: string}>}>}
+ */
+export async function applyMigration(id, projectRoot, opts = {}) {
+  const dryRun = opts.dryRun !== false; // dry-run default, always
+  const mig = (await listMigrations()).find((m) => m.id === id);
+  if (!mig) return { status: 'not-found', id };
+  const ctx = makeCtx(projectRoot, { dryRun });
+  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 };
+}