infernoflow 0.19.0 → 0.21.0

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