infernoflow 0.18.0 → 0.20.0

package/dist/lib/commands/scout.mjs

@@ -0,0 +1,291 @@
+/**
+ * infernoflow scout
+ *
+ * Scans your source files for undocumented capabilities — functions, routes,
+ * exports, controllers — that exist in code but are missing from the contract.
+ *
+ * Smarter than --adopt: it reads your existing contract, diffs against what
+ * it finds in source, and only surfaces genuine gaps.
+ *
+ * Usage:
+ *   infernoflow scout                   Scan src/, lib/, app/ (auto-detected)
+ *   infernoflow scout --dir src,api     Custom scan directories
+ *   infernoflow scout --apply           Write discovered caps to capabilities.json
+ *   infernoflow scout --json            Machine-readable output
+ *   infernoflow scout --min-confidence 0.7   Only show high-confidence hits
+ *
+ * Output:
+ *   Lists undocumented capabilities with confidence score + source location.
+ *   With --apply, merges them into the contract file.
+ */
+
+import * as fs   from "node:fs";
+import * as path from "node:path";
+import { done, warn, info, bold, cyan, gray, green, yellow, red } from "../ui/output.mjs";
+
+// ── Pattern library ───────────────────────────────────────────────────────────
+
+const PATTERNS = [
+  // Express / Fastify / Hono routes
+  {
+    name: "http-route",
+    regex: /(?:app|router|server)\s*\.\s*(get|post|put|patch|delete|head|options)\s*\(\s*['"`]([^'"`]+)['"`]/gi,
+    extract: (m) => ({ id: routeToId(m[2], m[1]), hint: `${m[1].toUpperCase()} ${m[2]}`, confidence: 0.85 }),
+  },
+  // Next.js / Nuxt API route files  (path from filename)
+  {
+    name: "api-file",
+    filePattern: /[/\\](pages[/\\]api|app[/\\]api)[/\\](.+)\.(js|ts|mjs)$/,
+    extract: (filePath) => {
+      const m = filePath.match(/[/\\](pages[/\\]api|app[/\\]api)[/\\](.+)\.(js|ts|mjs)$/);
+      if (!m) return null;
+      const route = m[2].replace(/[/\\]index$/, "").replace(/\[([^\]]+)\]/g, ":$1");
+      return { id: routeToId("/" + route, "api"), hint: `Next.js API: /${route}`, confidence: 0.9 };
+    },
+  },
+  // Named exports (functions, classes, consts)
+  {
+    name: "export",
+    regex: /export\s+(?:async\s+)?(?:function|class|const|let)\s+([A-Z][A-Za-z0-9]+)/g,
+    extract: (m) => ({ id: camelToId(m[1]), hint: `export ${m[1]}`, confidence: 0.65 }),
+  },
+  // Default export object keys (controller-style)
+  {
+    name: "controller-method",
+    regex: /^\s{2,}(?:async\s+)?([a-z][A-Za-z0-9]+)\s*[:(]/gm,
+    extract: (m) => ({ id: camelToId(m[1]), hint: `method ${m[1]}`, confidence: 0.5 }),
+    minLen: 5,
+  },
+  // GraphQL resolver fields
+  {
+    name: "graphql-resolver",
+    regex: /['"`]?([A-Za-z][A-Za-z0-9]+)['"`]?\s*:\s*(?:async\s+)?\([^)]*\)\s*(?:=>|{)/g,
+    extract: (m) => ({ id: camelToId(m[1]), hint: `resolver ${m[1]}`, confidence: 0.6 }),
+  },
+  // Django / Flask URL patterns
+  {
+    name: "python-route",
+    regex: /(?:path|url|re_path)\s*\(\s*['"`]([^'"`]+)['"`]\s*,\s*([A-Za-z0-9_.]+)/g,
+    extract: (m) => ({ id: routeToId(m[1], "view"), hint: `view ${m[2]} @ ${m[1]}`, confidence: 0.8 }),
+  },
+  // Rails routes
+  {
+    name: "rails-route",
+    regex: /(?:get|post|put|patch|delete)\s+['"`]([^'"`]+)['"`]\s*,\s*to:\s*['"`]([^'"`]+)['"`]/g,
+    extract: (m) => ({ id: routeToId(m[1], "rails"), hint: `Rails: ${m[2]}`, confidence: 0.8 }),
+  },
+];
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function routeToId(route, method) {
+  return route
+    .replace(/^\//, "")
+    .replace(/\/:?[^/]+/g, "")    // strip params
+    .replace(/\//g, "-")
+    .replace(/[^a-zA-Z0-9-]/g, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+    .toLowerCase() || method.toLowerCase() + "-root";
+}
+
+function camelToId(name) {
+  return name
+    .replace(/([A-Z])/g, "-$1")
+    .toLowerCase()
+    .replace(/^-/, "")
+    .replace(/-+/g, "-");
+}
+
+// ── File scanner ──────────────────────────────────────────────────────────────
+
+const SOURCE_EXTENSIONS = new Set([".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx", ".py", ".rb"]);
+const IGNORE_DIRS       = new Set(["node_modules", ".git", "dist", "build", ".next", "__pycache__", "vendor", "coverage"]);
+
+function* walkFiles(dir) {
+  if (!fs.existsSync(dir)) return;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    if (IGNORE_DIRS.has(e.name)) continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      yield* walkFiles(full);
+    } else if (e.isFile() && SOURCE_EXTENSIONS.has(path.extname(e.name))) {
+      yield full;
+    }
+  }
+}
+
+function scanFile(filePath) {
+  const hits = [];
+
+  // File-pattern rules (e.g. Next.js API files)
+  for (const pat of PATTERNS) {
+    if (pat.filePattern && pat.filePattern.test(filePath)) {
+      const result = pat.extract(filePath);
+      if (result) hits.push({ ...result, source: filePath, pattern: pat.name });
+    }
+  }
+
+  let content;
+  try { content = fs.readFileSync(filePath, "utf8"); } catch { return hits; }
+
+  for (const pat of PATTERNS) {
+    if (!pat.regex) continue;
+    pat.regex.lastIndex = 0;
+    let m;
+    while ((m = pat.regex.exec(content)) !== null) {
+      const result = pat.extract(m);
+      if (!result) continue;
+      if (pat.minLen && result.id.length < pat.minLen) continue;
+      hits.push({ ...result, source: filePath, pattern: pat.name });
+    }
+  }
+
+  return hits;
+}
+
+// ── Gap detection ─────────────────────────────────────────────────────────────
+
+function readContract(infernoDir) {
+  for (const f of ["capabilities.json", "contract.json"]) {
+    const p = path.join(infernoDir, f);
+    if (!fs.existsSync(p)) continue;
+    try { return { file: f, data: JSON.parse(fs.readFileSync(p, "utf8")) }; } catch {}
+  }
+  return null;
+}
+
+function getKnownIds(contract) {
+  const caps = contract?.data?.capabilities || [];
+  return new Set(caps.map(c => (typeof c === "string" ? c : c.id || c.name || "").toLowerCase()));
+}
+
+function dedupeHits(hits) {
+  const seen = new Map();
+  for (const h of hits) {
+    const key = h.id;
+    const existing = seen.get(key);
+    if (!existing || h.confidence > existing.confidence) {
+      seen.set(key, h);
+    }
+  }
+  return [...seen.values()].sort((a, b) => b.confidence - a.confidence);
+}
+
+// ── Apply ─────────────────────────────────────────────────────────────────────
+
+function applyToContract(infernoDir, contract, newCaps) {
+  const caps    = contract.data.capabilities || [];
+  const added   = [];
+
+  for (const cap of newCaps) {
+    const entry = {
+      id:          cap.id,
+      description: cap.hint,
+      since:       new Date().toISOString().slice(0, 10),
+      source:      "scout",
+    };
+    caps.push(entry);
+    added.push(cap.id);
+  }
+
+  contract.data.capabilities = caps;
+  fs.writeFileSync(
+    path.join(infernoDir, contract.file),
+    JSON.stringify(contract.data, null, 2) + "\n"
+  );
+  return added;
+}
+
+// ── Entry ─────────────────────────────────────────────────────────────────────
+
+export async function scoutCommand(rawArgs) {
+  const args      = rawArgs.slice(1);
+  const jsonMode  = args.includes("--json");
+  const apply     = args.includes("--apply");
+  const cwd       = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+
+  if (!fs.existsSync(infernoDir)) {
+    const msg = "inferno/ not found. Run: infernoflow init";
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    process.exit(1);
+  }
+
+  // Parse --dir flag
+  const dirIdx = args.indexOf("--dir");
+  const scanDirs = dirIdx !== -1
+    ? args[dirIdx + 1].split(",").map(d => path.resolve(cwd, d.trim()))
+    : ["src", "lib", "app", "api", "pages", "routes", "controllers", "handlers"]
+        .map(d => path.join(cwd, d))
+        .filter(fs.existsSync);
+
+  // Parse --min-confidence
+  const confIdx     = args.indexOf("--min-confidence");
+  const minConfidence = confIdx !== -1 ? parseFloat(args[confIdx + 1]) : 0.6;
+
+  if (!scanDirs.length) {
+    const msg = "No source directories found. Use --dir src,lib,api";
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    process.exit(1);
+  }
+
+  const contract = readContract(infernoDir);
+  const knownIds = getKnownIds(contract);
+
+  if (!jsonMode) {
+    info(`Scanning ${scanDirs.map(d => path.relative(cwd, d)).join(", ")} …`);
+    console.log();
+  }
+
+  // Collect hits from all source dirs
+  const allHits = [];
+  for (const dir of scanDirs) {
+    for (const file of walkFiles(dir)) {
+      allHits.push(...scanFile(file));
+    }
+  }
+
+  // Filter: unknown, above confidence threshold, non-trivial id
+  const candidates = dedupeHits(allHits).filter(h =>
+    !knownIds.has(h.id.toLowerCase()) &&
+    h.confidence >= minConfidence &&
+    h.id.length >= 3 &&
+    !["index", "app", "main", "root", "default", "handler"].includes(h.id)
+  );
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: true, found: candidates.length, candidates }));
+    return;
+  }
+
+  if (!candidates.length) {
+    done("No undocumented capabilities found — contract looks complete.");
+    return;
+  }
+
+  console.log(`  ${bold(`${candidates.length} undocumented capability candidate${candidates.length !== 1 ? "s" : ""} found`)}`);
+  console.log();
+
+  const w = Math.max(...candidates.map(c => c.id.length), 10) + 2;
+  for (const c of candidates) {
+    const confStr  = `${Math.round(c.confidence * 100)}%`;
+    const confColor = c.confidence >= 0.8 ? green : c.confidence >= 0.65 ? yellow : gray;
+    const rel      = path.relative(cwd, c.source);
+    console.log(`  ${bold(c.id.padEnd(w))} ${confColor(confStr.padEnd(5))} ${gray(c.hint)}`);
+    console.log(`  ${" ".repeat(w + 7)}${gray(rel)}`);
+  }
+  console.log();
+
+  if (apply) {
+    const added = applyToContract(infernoDir, contract, candidates);
+    done(`Added ${bold(String(added.length))} capabilities to ${contract.file}`);
+    console.log();
+  } else {
+    info(`Run with ${cyan("--apply")} to add these to your contract.`);
+    console.log();
+  }
+}

package/dist/lib/commands/snapshot.mjs

@@ -0,0 +1,383 @@
+/**
+ * infernoflow snapshot
+ *
+ * Named, timestamped snapshots of the full capability contract.
+ * Stored in inferno/snapshots/ — travel with the repo.
+ *
+ * Like git tags, but for the capability contract specifically.
+ *
+ * Usage:
+ *   infernoflow snapshot save <name>           Save current contract as a named snapshot
+ *   infernoflow snapshot list                  List all snapshots
+ *   infernoflow snapshot show <name>           Print a snapshot's capabilities
+ *   infernoflow snapshot diff <name1> <name2>  Diff two snapshots (or name vs current)
+ *   infernoflow snapshot restore <name>        Overwrite contract with a snapshot
+ *   infernoflow snapshot delete <name>         Delete a snapshot
+ *   infernoflow snapshot --json                Machine-readable output on any subcommand
+ *
+ * Snapshot file format (inferno/snapshots/<name>.json):
+ *   {
+ *     "name": "v1.2-release",
+ *     "savedAt": "2025-06-01T12:00:00Z",
+ *     "capabilities": [...],
+ *     "meta": { "version": "1.2.0", "capabilityCount": 12 }
+ *   }
+ */
+
+import * as fs   from "node:fs";
+import * as path from "node:path";
+import { done, warn, info, bold, cyan, gray, green, yellow, red } from "../ui/output.mjs";
+
+const SNAPSHOTS_DIR = "snapshots";
+
+// ── Storage ───────────────────────────────────────────────────────────────────
+
+function snapshotsDir(infernoDir) {
+  return path.join(infernoDir, SNAPSHOTS_DIR);
+}
+
+function snapshotPath(infernoDir, name) {
+  return path.join(infernoDir, SNAPSHOTS_DIR, `${name}.json`);
+}
+
+function ensureSnapshotsDir(infernoDir) {
+  const d = snapshotsDir(infernoDir);
+  if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+  return d;
+}
+
+function listSnapshots(infernoDir) {
+  const d = snapshotsDir(infernoDir);
+  if (!fs.existsSync(d)) return [];
+  return fs.readdirSync(d)
+    .filter(f => f.endsWith(".json"))
+    .map(f => {
+      try { return JSON.parse(fs.readFileSync(path.join(d, f), "utf8")); } catch { return null; }
+    })
+    .filter(Boolean)
+    .sort((a, b) => new Date(b.savedAt) - new Date(a.savedAt));
+}
+
+function readSnapshot(infernoDir, name) {
+  const p = snapshotPath(infernoDir, name);
+  if (!fs.existsSync(p)) return null;
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return null; }
+}
+
+function readContract(infernoDir) {
+  for (const f of ["contract.json", "capabilities.json"]) {
+    const p = path.join(infernoDir, f);
+    if (!fs.existsSync(p)) continue;
+    try { return { file: f, data: JSON.parse(fs.readFileSync(p, "utf8")) }; } catch {}
+  }
+  return null;
+}
+
+function normaliseCaps(contract) {
+  const raw = contract?.capabilities || contract?.data?.capabilities || contract || [];
+  return raw.map(c => (typeof c === "string" ? { id: c } : c));
+}
+
+function readPackageVersion(cwd) {
+  try { return JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8")).version || ""; } catch { return ""; }
+}
+
+// ── Diff engine ───────────────────────────────────────────────────────────────
+
+function diffCaps(capsBefore, capsAfter) {
+  const beforeIds = new Map(capsBefore.map(c => [c.id, c]));
+  const afterIds  = new Map(capsAfter.map(c => [c.id, c]));
+
+  const added    = capsAfter.filter(c => !beforeIds.has(c.id));
+  const removed  = capsBefore.filter(c => !afterIds.has(c.id));
+  const changed  = capsAfter.filter(c => {
+    const prev = beforeIds.get(c.id);
+    if (!prev) return false;
+    return JSON.stringify(c) !== JSON.stringify(prev);
+  });
+
+  return { added, removed, changed };
+}
+
+// ── Sub-commands ──────────────────────────────────────────────────────────────
+
+function subcmdSave(name, infernoDir, cwd, jsonMode) {
+  if (!name || name.startsWith("--")) {
+    const msg = "Usage: infernoflow snapshot save <name>";
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    return;
+  }
+
+  // Validate name (no spaces, no slashes)
+  if (!/^[a-zA-Z0-9._-]+$/.test(name)) {
+    const msg = `Invalid snapshot name "${name}" — use letters, digits, dots, dashes, underscores only`;
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    return;
+  }
+
+  const contract = readContract(infernoDir);
+  if (!contract) {
+    const msg = "No contract found. Run: infernoflow init";
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    return;
+  }
+
+  ensureSnapshotsDir(infernoDir);
+
+  const caps = normaliseCaps(contract.data);
+  const snapshot = {
+    name,
+    savedAt:      new Date().toISOString(),
+    capabilities: caps,
+    meta: {
+      version:         readPackageVersion(cwd),
+      capabilityCount: caps.length,
+      contractFile:    contract.file,
+    },
+  };
+
+  const p = snapshotPath(infernoDir, name);
+  const overwriting = fs.existsSync(p);
+  fs.writeFileSync(p, JSON.stringify(snapshot, null, 2) + "\n");
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: true, action: "saved", name, capabilities: caps.length }));
+  } else {
+    done(`${overwriting ? "Updated" : "Saved"} snapshot ${bold(cyan(name))} — ${bold(String(caps.length))} capabilities`);
+    console.log();
+  }
+}
+
+function subcmdList(infernoDir, jsonMode) {
+  const snapshots = listSnapshots(infernoDir);
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: true, snapshots: snapshots.map(s => ({ name: s.name, savedAt: s.savedAt, capabilities: s.meta?.capabilityCount ?? s.capabilities?.length ?? 0 })) }));
+    return;
+  }
+
+  if (!snapshots.length) {
+    info("No snapshots yet. Use: infernoflow snapshot save <name>");
+    return;
+  }
+
+  console.log();
+  console.log(`  ${bold(`${snapshots.length} snapshot${snapshots.length !== 1 ? "s" : ""}`)}`);
+  console.log();
+
+  const w = Math.max(...snapshots.map(s => s.name.length), 8) + 2;
+  for (const s of snapshots) {
+    const date = new Date(s.savedAt).toLocaleString();
+    const caps = s.meta?.capabilityCount ?? s.capabilities?.length ?? "?";
+    console.log(`  ${bold(s.name.padEnd(w))} ${gray(date)}  ${cyan(String(caps))} caps`);
+  }
+  console.log();
+}
+
+function subcmdShow(name, infernoDir, jsonMode) {
+  if (!name || name.startsWith("--")) {
+    const msg = "Usage: infernoflow snapshot show <name>";
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    return;
+  }
+
+  const snap = readSnapshot(infernoDir, name);
+  if (!snap) {
+    const msg = `Snapshot not found: ${name}`;
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    return;
+  }
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: true, snapshot: snap }));
+    return;
+  }
+
+  console.log();
+  console.log(`  ${bold("Snapshot:")} ${cyan(snap.name)}`);
+  console.log(`  ${bold("Saved:")}    ${gray(new Date(snap.savedAt).toLocaleString())}`);
+  console.log(`  ${bold("Version:")}  ${gray(snap.meta?.version || "—")}`);
+  console.log(`  ${bold("Caps:")}     ${snap.capabilities.length}`);
+  console.log();
+
+  const caps = normaliseCaps(snap.capabilities);
+  for (const c of caps) {
+    console.log(`  ${cyan("·")} ${bold(c.id)}${c.description ? gray("  " + c.description) : ""}`);
+  }
+  console.log();
+}
+
+function subcmdDiff(nameA, nameB, infernoDir, jsonMode) {
+  if (!nameA) {
+    const msg = "Usage: infernoflow snapshot diff <name1> [<name2>]  (omit name2 to diff against current)";
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    return;
+  }
+
+  const snapA = readSnapshot(infernoDir, nameA);
+  if (!snapA) {
+    const msg = `Snapshot not found: ${nameA}`;
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    return;
+  }
+
+  let capsBefore = normaliseCaps(snapA.capabilities);
+  let capsAfter;
+  let labelAfter;
+
+  if (nameB) {
+    const snapB = readSnapshot(infernoDir, nameB);
+    if (!snapB) {
+      const msg = `Snapshot not found: ${nameB}`;
+      if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+      else warn(msg);
+      return;
+    }
+    capsAfter  = normaliseCaps(snapB.capabilities);
+    labelAfter = nameB;
+  } else {
+    const contract = readContract(infernoDir);
+    if (!contract) {
+      const msg = "No current contract found.";
+      if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+      else warn(msg);
+      return;
+    }
+    capsAfter  = normaliseCaps(contract.data);
+    labelAfter = "current";
+  }
+
+  const diff = diffCaps(capsBefore, capsAfter);
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: true, from: nameA, to: labelAfter, ...diff }));
+    return;
+  }
+
+  console.log();
+  console.log(`  ${bold("Diff:")} ${cyan(nameA)} → ${cyan(labelAfter)}`);
+  console.log();
+
+  if (!diff.added.length && !diff.removed.length && !diff.changed.length) {
+    console.log(`  ${gray("No differences — snapshots are identical")}`);
+    console.log();
+    return;
+  }
+
+  if (diff.added.length) {
+    console.log(`  ${green("+")} ${bold(`${diff.added.length} added`)}`);
+    diff.added.forEach(c => console.log(`    ${green("+")} ${c.id}`));
+    console.log();
+  }
+  if (diff.removed.length) {
+    console.log(`  ${red("-")} ${bold(`${diff.removed.length} removed`)}`);
+    diff.removed.forEach(c => console.log(`    ${red("-")} ${c.id}`));
+    console.log();
+  }
+  if (diff.changed.length) {
+    console.log(`  ${yellow("~")} ${bold(`${diff.changed.length} changed`)}`);
+    diff.changed.forEach(c => console.log(`    ${yellow("~")} ${c.id}`));
+    console.log();
+  }
+}
+
+function subcmdRestore(name, infernoDir, jsonMode) {
+  if (!name || name.startsWith("--")) {
+    const msg = "Usage: infernoflow snapshot restore <name>";
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    return;
+  }
+
+  const snap = readSnapshot(infernoDir, name);
+  if (!snap) {
+    const msg = `Snapshot not found: ${name}`;
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    return;
+  }
+
+  const contract = readContract(infernoDir);
+  const contractFile = contract?.file || "capabilities.json";
+  const contractPath = path.join(infernoDir, contractFile);
+
+  const data = contract?.data || {};
+  data.capabilities = snap.capabilities;
+  fs.writeFileSync(contractPath, JSON.stringify(data, null, 2) + "\n");
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: true, action: "restored", name, capabilities: snap.capabilities.length }));
+  } else {
+    done(`Restored ${bold(cyan(name))} → ${bold(contractFile)} (${snap.capabilities.length} capabilities)`);
+    console.log();
+  }
+}
+
+function subcmdDelete(name, infernoDir, jsonMode) {
+  if (!name || name.startsWith("--")) {
+    const msg = "Usage: infernoflow snapshot delete <name>";
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    return;
+  }
+
+  const p = snapshotPath(infernoDir, name);
+  if (!fs.existsSync(p)) {
+    const msg = `Snapshot not found: ${name}`;
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    return;
+  }
+
+  fs.unlinkSync(p);
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: true, action: "deleted", name }));
+  } else {
+    done(`Deleted snapshot ${bold(name)}`);
+    console.log();
+  }
+}
+
+// ── Entry ─────────────────────────────────────────────────────────────────────
+
+export async function snapshotCommand(rawArgs) {
+  const args      = rawArgs.slice(1);
+  const jsonMode  = args.includes("--json");
+  const cwd       = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+
+  if (!fs.existsSync(infernoDir)) {
+    const msg = "inferno/ not found. Run: infernoflow init";
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    process.exit(1);
+  }
+
+  const subcmd = args.find(a => !a.startsWith("--"));
+
+  if (!subcmd || subcmd === "list") {
+    return subcmdList(infernoDir, jsonMode);
+  }
+
+  const positional = args.filter(a => !a.startsWith("--"));
+
+  if (subcmd === "save")    return subcmdSave(positional[1], infernoDir, cwd, jsonMode);
+  if (subcmd === "show")    return subcmdShow(positional[1], infernoDir, jsonMode);
+  if (subcmd === "restore") return subcmdRestore(positional[1], infernoDir, jsonMode);
+  if (subcmd === "delete")  return subcmdDelete(positional[1], infernoDir, jsonMode);
+
+  if (subcmd === "diff") {
+    return subcmdDiff(positional[1], positional[2], infernoDir, jsonMode);
+  }
+
+  warn(`Unknown snapshot sub-command: ${subcmd}`);
+  info("Available: save | list | show | diff | restore | delete");
+}