archgen-skill 0.0.2 → 0.0.4

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 };
+}

package/lib/restore.js

@@ -0,0 +1,239 @@
+// restore.js — recovery tooling for archgen backups.
+//
+// Backups live in two vaults:
+//   project: <projectRoot>/.archgen/.backup/<ts>/<relpath…>   (written by init)
+//   global:  <skills-dir>/.archgen-backups/<ts>/archgen        (written by install --copy)
+//
+// restoreBackups() discovers both, lists snapshots deterministically, and
+// restores a chosen snapshot by copying each entry back to its original path.
+// Safety invariant: the CURRENT state of every about-to-be-overwritten path is
+// moved into a fresh safety snapshot FIRST — a restore never destroys anything
+// without a prior backup of it. Restores themselves land atomically
+// (temp-sibling dir, then rename).
+
+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 { 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;
+}
+
+function lstatSafe(p) {
+  try { return lstatSync(p); } catch { return null; }
+}
+
+function summarize(dir) {
+  let files = 0;
+  let dirs = 0;
+  (function walk(d) {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      if (e.isDirectory()) { dirs++; walk(join(d, e.name)); } else { files++; }
+    }
+  })(dir);
+  const topLevel = readdirSync(dir).sort(byName);
+  return { files, dirs, topLevel };
+}
+
+function snapshotsUnder(origin, base, vaultAbs) {
+  if (!existsSync(vaultAbs)) return [];
+  return readdirSync(vaultAbs, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort(byName)
+    .reverse()
+    .map((ts) => {
+      const snapshotDir = join(vaultAbs, ts);
+      let summary = null;
+      try { summary = summarize(snapshotDir); } catch { summary = { files: 0, dirs: 0, topLevel: [] }; }
+      return { id: ts, ts, origin, base, snapshotDir, summary };
+    });
+}
+
+/**
+ * Discover backup snapshots in both vaults.
+ * @param {{projectRoot?: string|null, home?: string, includeGlobal?: boolean}} opts
+ * @returns {Array<{id: string, ts: string, origin: 'project'|'global', base: string,
+ *            snapshotDir: string, summary: {files: number, dirs: number, topLevel: string[]}}>}
+ *   Sorted newest-first, project before global (deterministic order).
+ */
+export function discoverSnapshots(opts = {}) {
+  const home = opts.home ?? homedir();
+  const out = [];
+  if (opts.projectRoot) {
+    out.push(...snapshotsUnder('project', resolve(opts.projectRoot), join(resolve(opts.projectRoot), ...BACKUP_ROOT_REL.split('/'))));
+  }
+  if (opts.includeGlobal !== false) {
+    for (const tdir of globalTargets(home)) {
+      out.push(...snapshotsUnder('global', tdir, join(tdir, GLOBAL_BACKUP_REL)));
+    }
+  }
+  return out.sort((a, b) => (a.ts === b.ts ? byName(a.origin + a.base, b.origin + b.base) : a.ts < b.ts ? 1 : -1));
+}
+
+/**
+ * List backups under a project root and the global harness dirs.
+ * @param {string} projectRoot project root to scan (may be '' when unused)
+ * @param {{home?: string, includeGlobal?: boolean}} options
+ */
+export function listBackups(projectRoot, options = {}) {
+  return discoverSnapshots({ projectRoot: projectRoot || null, home: options.home, includeGlobal: options.includeGlobal });
+}
+
+function uniqueSafetyTs(base, backupRootRel) {
+  for (;;) {
+    const ts = new Date().toISOString().replace(/:/g, '-');
+    if (!existsSync(join(base, ...backupRootRel.split('/'), ts))) return ts;
+  }
+}
+
+/** Atomic copy-back: temp sibling dir, then rename into place. */
+function layDown(srcAbs, destAbs) {
+  mkdirSync(dirname(destAbs), { recursive: true });
+  const tmp = join(dirname(destAbs), '.archgen-restore-' + randomBytes(6).toString('hex'));
+  cpSync(srcAbs, tmp, { recursive: true });
+  renameSync(tmp, destAbs);
+}
+
+/**
+ * Restore backups discovered across the project and global vaults.
+ *
+ * @param {string} projectRoot project root to scan (used for listing; may be ''
+ *   when only global snapshots are wanted)
+ * @param {{list?: boolean, snapshot?: string, target?: string, home?: string,
+ *   includeGlobal?: boolean}} options
+ *   - `list` (default true): dry-run discovery, returns `snapshots`.
+ *   - `snapshot`: timestamp id to restore (takes precedence over `list`).
+ *     Ambiguous ids (same ts in several vaults) must be narrowed via
+ *     `includeGlobal:false` or an exact single match.
+ *   - `target`: restore INTO this directory instead of the recorded origin
+ *     (entries keep their layout relative to it).
+ * @returns {{action: 'list'|'restored', snapshots?: Array<object>,
+ *            restored?: Array<{from: string, to: string}>,
+ *            safetyBackups?: Array<{rel: string, abs: string}>, warnings: string[]}}
+ */
+export function restoreBackups(projectRoot, options = {}) {
+  const warnings = [];
+  const all = discoverSnapshots({
+    projectRoot,
+    home: options.home,
+    includeGlobal: options.includeGlobal !== false,
+  });
+
+  if (!options.snapshot) {
+    return { action: 'list', snapshots: all, warnings };
+  }
+
+  const matches = all.filter((s) => s.ts === options.snapshot || s.id === options.snapshot);
+  if (matches.length === 0) {
+    throw new Error(`no backup snapshot '${options.snapshot}' found (run with list mode to see available ids)`);
+  }
+  if (matches.length > 1) {
+    throw new Error(`ambiguous snapshot '${options.snapshot}' exists in ${matches.length} vaults; narrow the scope`);
+  }
+  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) }));
+
+  // 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 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 abs = join(safetyBase, ...loc.split('/'));
+    safetyBackups.push({ rel: loc, abs });
+  }
+
+  // Pass 2 — copy back atomically.
+  const restored = [];
+  for (const en of entries) {
+    try {
+      layDown(en.srcAbs, en.destAbs);
+      restored.push({ from: en.srcAbs, to: en.destAbs });
+    } catch (e) {
+      warnings.push(`could not restore ${en.name}: ${e.message}`);
+    }
+  }
+
+  return { action: 'restored', snapshot: snap, restored, safetyBackups, warnings };
+}
+
+function parseFlags(argv) {
+  const opts = { list: true, snapshot: null, project: null, global: false, yes: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    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' };
+      opts.snapshot = v;
+    } else if (a === '--project') {
+      const v = argv[i + 1] && !argv[i + 1].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
+    else return { error: `unknown flag: ${a}` };
+  }
+  return opts;
+}
+
+/**
+ * CLI entry point (`archgen-skill restore …`). Interactive-free and
+ * deterministic; never prompts. Exit codes: 0 success/listing, 1 on errors.
+ * @param {string[]} argv flags after the command name
+ * @returns {Promise<number>} exit code
+ */
+export async function restoreMain(argv) {
+  const parsed = parseFlags(argv);
+  if (parsed.error) {
+    console.error('archgen restore: ' + parsed.error);
+    return 1;
+  }
+  const { list, snapshot, project, global: wantGlobal, yes } = parsed;
+  void yes;
+
+  const scope = {
+    projectRoot: wantGlobal ? null : (project ?? process.cwd()),
+    includeGlobal: !project || wantGlobal,
+  };
+
+  try {
+    if (!snapshot) {
+      const snapshots = listBackups(scope.projectRoot ?? '', { includeGlobal: scope.includeGlobal });
+      console.log(`archgen restore — ${snapshots.length} backup snapshot(s) found`);
+      for (const s of snapshots) {
+        const names = s.summary.topLevel.length ? s.summary.topLevel.join(', ') : '(empty)';
+        console.log(`  ${s.ts}  [${s.origin}]  ${s.base}  (${s.summary.files} file(s), ${s.summary.dirs} dir(s): ${names})`);
+      }
+      console.log('Dry-run listing only. Pass --snapshot <ts> to restore.');
+      return 0;
+    }
+
+    const r = restoreBackups(scope.projectRoot ?? '', { snapshot, includeGlobal: scope.includeGlobal });
+    console.log(`archgen restore — restoring ${snapshot} [${r.snapshot.origin}]`);
+    for (const sb of r.safetyBackups) console.log(`  ~ safety backup of current state: ${sb.abs}`);
+    for (const en of r.restored) console.log(`  + restored ${en.to}`);
+    for (const w of r.warnings) console.error('  ! ' + w);
+    console.log(`Done: ${r.restored.length} path(s) restored, ${r.safetyBackups.length} safety backup(s).`);
+    return r.warnings.length > 0 ? 1 : 0;
+  } catch (e) {
+    console.error('archgen restore: ' + (e instanceof Error ? e.message : String(e)));
+    return 1;
+  }
+}