infernoflow 0.19.0 → 0.21.0

package/dist/bin/infernoflow.mjs

@@ -45,6 +45,12 @@ const COMMAND_DESCRIPTIONS = {
   monorepo: "Manage infernoflow across monorepo packages (init | list | status | diff | sync)",
   link:    "Link capabilities to Jira, Linear, or GitHub Issues tickets",
   audit:   "Classify capabilities by sensitivity (auth, payment, PII, admin) and generate security surface map",
+  scout:   "Scan source files for undocumented capabilities not yet in the contract",
+  export:  "Export contract to OpenAPI, Backstage catalog-info.yaml, CSV, or Markdown",
+  snapshot: "Save/diff/restore named snapshots of the capability contract",
+  health:  "Compute a 0–100 health score across coverage, docs, freshness, completeness, drift",
+  vibe:    "Vibe coding mode — watches files, auto-syncs contract, regenerates context on every save",
+  adopt:   "Interactive wizard to adopt infernoflow in an existing project (detect → review → wire up)",
 };
 
 const COMMAND_HANDLERS = {
@@ -82,7 +88,13 @@ const COMMAND_HANDLERS = {
   report:  async (args) => (await import("../lib/commands/report.mjs")).reportCommand(args),
   monorepo: async (args) => (await import("../lib/commands/monorepo.mjs")).monorepoCommand(args),
   link:    async (args) => (await import("../lib/commands/link.mjs")).linkCommand(args),
-  audit:   async (args) => (await import("../lib/commands/audit.mjs")).auditCommand(args),
+  audit:    async (args) => (await import("../lib/commands/audit.mjs")).auditCommand(args),
+  scout:    async (args) => (await import("../lib/commands/scout.mjs")).scoutCommand(args),
+  export:   async (args) => (await import("../lib/commands/export.mjs")).exportCommand(args),
+  snapshot: async (args) => (await import("../lib/commands/snapshot.mjs")).snapshotCommand(args),
+  health:   async (args) => (await import("../lib/commands/health.mjs")).healthCommand(args),
+  vibe:     async (args) => (await import("../lib/commands/vibe.mjs")).vibeCommand(args),
+  adopt:    async (args) => (await import("../lib/commands/adoptWizard.mjs")).adoptWizardCommand(args),
 };
 
 function formatCommandsHelp() {
@@ -279,6 +291,54 @@ ${formatCommandsHelp()}
     --fail-on high|medium     Exit 1 if unreviewed caps at given severity exist
     --json                    Machine-readable output
 
+  ${bold("vibe options:")}
+    --dir <dirs>              Comma-separated directories to watch (default: auto-detected)
+    --no-suggest              Disable automatic contract sync on file save
+    --no-context              Disable CONTEXT.md regeneration
+    --interval <secs>         Debounce seconds between saves (default: 4)
+    --port <n>                Also run a mini status dashboard on localhost:<n>
+    --silent                  Suppress all terminal output (pure background mode)
+
+  ${bold("adopt options:")}
+    --dir <dirs>              Source directories to scan (default: src,lib,app,api,routes,controllers)
+    --yes, -y                 Auto-approve all candidates (non-interactive)
+    --json                    Machine-readable output, implies --yes
+
+  ${bold("init --template options:")}
+    --template rest-api       REST API (Express/Fastify/Hono) starter
+    --template nextjs         Next.js fullstack app starter
+    --template cli            CLI tool (Node.js/Python) starter
+    --template graphql        GraphQL API (Apollo/Pothos) starter
+    --template monorepo       Monorepo workspace starter
+
+  ${bold("scout options:")}
+    --dir <dirs>              Comma-separated directories to scan (default: src,lib,app,api,routes)
+    --apply                   Write discovered capabilities to the contract file
+    --min-confidence <0-1>    Minimum confidence threshold (default: 0.6)
+    --json                    Machine-readable output
+
+  ${bold("export options:")}
+    --format openapi|backstage|csv|markdown|json   Output format (required)
+    --out <path>              Output file path (default: project root, auto-named)
+    --json                    Machine-readable summary
+
+  ${bold("snapshot sub-commands:")}
+    save <name>               Save current contract as a named snapshot
+    list                      List all snapshots
+    show <name>               Print a snapshot's capabilities
+    diff <name1> [<name2>]    Diff two snapshots (omit name2 to diff against current)
+    restore <name>            Overwrite contract with snapshot contents
+    delete <name>             Delete a snapshot
+
+  ${bold("snapshot options:")}
+    --json                    Machine-readable output
+
+  ${bold("health options:")}
+    --fail-below <score>      Exit 1 if health score is below this threshold (CI gate)
+    --watch                   Re-run every 30s (live terminal view)
+    --interval <secs>         Watch interval in seconds (default: 30)
+    --json                    Machine-readable score + breakdown
+
   ${bold("Machine output:")}
     ${gray("status --json")}
     ${gray("check --json")}

package/dist/lib/commands/adoptWizard.mjs

@@ -0,0 +1,320 @@
+/**
+ * infernoflow adopt
+ *
+ * Interactive adoption wizard for existing projects.
+ * Takes a project from zero to fully wired in one guided flow.
+ *
+ * Steps:
+ *   1. Detect project type, framework, language
+ *   2. Scout capabilities in source files
+ *   3. Interactive approve / rename / skip each candidate
+ *   4. Write capabilities.json + contract.json
+ *   5. Generate starter scenarios
+ *   6. Install git hooks
+ *   7. Regenerate CONTEXT.md
+ *   8. Show health score and next steps
+ *
+ * Usage:
+ *   infernoflow adopt              Full interactive wizard
+ *   infernoflow adopt --yes        Auto-approve all (non-interactive)
+ *   infernoflow adopt --dir src    Custom source directory
+ *   infernoflow adopt --json       Machine-readable, implies --yes
+ */
+
+import * as fs        from "node:fs";
+import * as path      from "node:path";
+import * as readline  from "node:readline";
+import { spawnSync }  from "node:child_process";
+import { done, warn, info, bold, cyan, gray, green, yellow, red } from "../ui/output.mjs";
+
+// ── Detection ─────────────────────────────────────────────────────────────────
+
+function detectProject(cwd) {
+  const has  = (...files) => files.some(f => fs.existsSync(path.join(cwd, f)));
+  const read = (f)        => { try { return JSON.parse(fs.readFileSync(path.join(cwd, f), "utf8")); } catch { return {}; } };
+
+  const pkg   = has("package.json") ? read("package.json") : {};
+  const deps  = { ...pkg.dependencies, ...pkg.devDependencies };
+
+  let framework = "unknown", lang = "javascript", type = "backend";
+
+  if (has("tsconfig.json"))                            lang = "typescript";
+  if (has("Pipfile","pyproject.toml","requirements.txt")) lang = "python";
+  if (has("Gemfile"))                                  lang = "ruby";
+  if (has("go.mod"))                                   lang = "go";
+  if (has("Cargo.toml"))                               lang = "rust";
+
+  if      (deps["next"])              { framework = "nextjs";   type = "fullstack"; }
+  else if (deps["nuxt"])              { framework = "nuxt";     type = "fullstack"; }
+  else if (deps["react"])             { framework = "react";    type = "frontend"; }
+  else if (deps["vue"])               { framework = "vue";      type = "frontend"; }
+  else if (deps["@angular/core"])     { framework = "angular";  type = "frontend"; }
+  else if (deps["express"])           { framework = "express";  type = "backend"; }
+  else if (deps["fastify"])           { framework = "fastify";  type = "backend"; }
+  else if (deps["hono"])              { framework = "hono";     type = "backend"; }
+  else if (deps["@nestjs/core"])      { framework = "nestjs";   type = "backend"; }
+  else if (deps["graphql"])           { framework = "graphql";  type = "backend"; }
+  else if (has("config/routes.rb"))   { framework = "rails";    type = "fullstack"; }
+  else if (has("manage.py"))          { framework = "django";   type = "backend"; }
+
+  if (pkg.bin || has("bin/"))         type = "cli";
+  if (has("nx.json","turbo.json","pnpm-workspace.yaml")) type = "monorepo";
+
+  return {
+    name:        pkg.name        || path.basename(cwd),
+    version:     pkg.version     || "0.1.0",
+    description: pkg.description || "",
+    lang, framework, type,
+  };
+}
+
+// ── Scout ─────────────────────────────────────────────────────────────────────
+
+const SRC_EXTS   = new Set([".js",".mjs",".cjs",".ts",".tsx",".jsx",".py",".rb"]);
+const SKIP_DIRS  = new Set(["node_modules",".git","dist","build",".next","__pycache__","vendor","coverage","inferno"]);
+
+const PATTERNS = [
+  {
+    regex: /(?:app|router|server)\s*\.\s*(get|post|put|patch|delete)\s*\(\s*['"`]([^'"`]+)['"`]/gi,
+    extract: m => ({ id: routeId(m[2], m[1]), hint: `${m[1].toUpperCase()} ${m[2]}`, confidence: 0.85 }),
+  },
+  {
+    filePattern: /[/\\](pages[/\\]api|app[/\\]api)[/\\](.+)\.(js|ts|mjs)$/,
+    extract: fp => {
+      const m = fp.match(/[/\\](pages[/\\]api|app[/\\]api)[/\\](.+)\.(js|ts|mjs)$/);
+      if (!m) return null;
+      const r = m[2].replace(/[/\\]index$/, "").replace(/\[([^\]]+)\]/g, ":$1");
+      return { id: routeId("/" + r, "api"), hint: `Next.js API: /${r}`, confidence: 0.9 };
+    },
+  },
+  {
+    regex: /export\s+(?:async\s+)?(?:function|class|const)\s+([A-Z][A-Za-z0-9]+)/g,
+    extract: m => ({ id: camelId(m[1]), hint: `export ${m[1]}`, confidence: 0.65 }),
+  },
+];
+
+function routeId(r, method) {
+  const id = r.replace(/^\//, "").replace(/\/:?[^/]+/g, "").replace(/\//g, "-")
+    .replace(/[^a-zA-Z0-9-]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase();
+  return id || method.toLowerCase() + "-root";
+}
+function camelId(name) {
+  return name.replace(/([A-Z])/g, "-$1").toLowerCase().replace(/^-/, "").replace(/-+/g, "-");
+}
+
+function* walk(dir) {
+  if (!fs.existsSync(dir)) return;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (SKIP_DIRS.has(e.name)) continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) yield* walk(full);
+    else if (e.isFile() && SRC_EXTS.has(path.extname(e.name))) yield full;
+  }
+}
+
+function scout(dirs, cwd) {
+  const seen = new Map();
+  const add  = (id, r, file) => {
+    if (!seen.has(id) || r.confidence > seen.get(id).confidence)
+      seen.set(id, { ...r, source: path.relative(cwd, file) });
+  };
+
+  for (const dir of dirs) {
+    for (const file of walk(dir)) {
+      for (const pat of PATTERNS) {
+        if (pat.filePattern && pat.filePattern.test(file)) {
+          const r = pat.extract(file);
+          if (r && r.id.length >= 3) add(r.id, r, file);
+        }
+      }
+      let content;
+      try { content = fs.readFileSync(file, "utf8"); } catch { continue; }
+      for (const pat of PATTERNS) {
+        if (!pat.regex) continue;
+        pat.regex.lastIndex = 0;
+        let m;
+        while ((m = pat.regex.exec(content)) !== null) {
+          const r = pat.extract(m);
+          if (r && r.id.length >= 3 && !["index","app","main","root","default","handler"].includes(r.id))
+            add(r.id, r, file);
+        }
+      }
+    }
+  }
+  return [...seen.values()].filter(c => c.confidence >= 0.5).sort((a, b) => b.confidence - a.confidence);
+}
+
+// ── Interactive review ────────────────────────────────────────────────────────
+
+function ask(rl, q) { return new Promise(r => rl.question(q, r)); }
+
+async function review(candidates, autoYes) {
+  if (autoYes) return candidates.filter(c => c.confidence >= 0.6);
+
+  const approved = [];
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  console.log();
+  console.log(`  ${bold("Review candidates")}  ${cyan("y")} approve · ${yellow("e")} edit · ${red("n")} skip · ${gray("a")} approve all · ${gray("q")} stop`);
+  console.log();
+
+  for (let i = 0; i < candidates.length; i++) {
+    const c    = candidates[i];
+    const conf = `${Math.round(c.confidence * 100)}%`;
+    const col  = c.confidence >= 0.8 ? green : c.confidence >= 0.65 ? yellow : gray;
+    process.stdout.write(
+      `  [${i + 1}/${candidates.length}] ${bold(c.id.padEnd(30))} ${col(conf)}  ${gray(c.hint)}\n` +
+      `  ${gray(c.source)}\n  > `
+    );
+
+    const ans = (await ask(rl, "")).trim().toLowerCase();
+    if (ans === "q") break;
+    if (ans === "a") {
+      for (let j = i; j < candidates.length; j++) approved.push(candidates[j]);
+      break;
+    }
+    if (ans === "n") { console.log(`  ${gray("skipped")}\n`); continue; }
+
+    let id = c.id;
+    if (ans === "e") {
+      const newId = (await ask(rl, `  New id (${c.id}): `)).trim();
+      if (newId && /^[a-z0-9-_]+$/.test(newId)) id = newId;
+    }
+    approved.push({ ...c, id });
+    console.log(`  ${green("✔")} ${bold(id)}\n`);
+  }
+
+  rl.close();
+  return approved;
+}
+
+// ── Writers ───────────────────────────────────────────────────────────────────
+
+function writeFiles(infernoDir, approved, project) {
+  // contract.json
+  const cp = path.join(infernoDir, "contract.json");
+  const existing = fs.existsSync(cp) ? JSON.parse(fs.readFileSync(cp, "utf8")) : {};
+  fs.writeFileSync(cp, JSON.stringify({
+    ...existing,
+    policyId:      existing.policyId || project.name.replace(/[^a-zA-Z0-9-]/g, "-"),
+    policyVersion: existing.policyVersion || 1,
+    capabilities:  approved.map(c => c.id),
+  }, null, 2) + "\n");
+
+  // capabilities.json
+  fs.writeFileSync(path.join(infernoDir, "capabilities.json"), JSON.stringify({
+    capabilities: approved.map(c => ({
+      id: c.id, description: c.hint,
+      since: new Date().toISOString().slice(0, 10), source: "adopt",
+    })),
+  }, null, 2) + "\n");
+
+  // Starter scenarios
+  const scenDir = path.join(infernoDir, "scenarios");
+  if (!fs.existsSync(scenDir)) fs.mkdirSync(scenDir, { recursive: true });
+  for (const c of approved) {
+    const sp = path.join(scenDir, `${c.id}.json`);
+    if (fs.existsSync(sp)) continue;
+    fs.writeFileSync(sp, JSON.stringify({
+      id: `${c.id}-happy-path`, capability: c.id,
+      description: `Happy path for ${c.description || c.id}`,
+      steps: [{ action: "invoke", target: c.id, input: {} }, { action: "assert", field: "status", value: "success" }],
+      capabilitiesCovered: [c.id],
+    }, null, 2) + "\n");
+  }
+}
+
+function runCli(args, cwd) {
+  return spawnSync("infernoflow", args, {
+    cwd, encoding: "utf8", timeout: 30_000,
+    stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, NO_COLOR: "1" },
+  });
+}
+
+// ── Entry ─────────────────────────────────────────────────────────────────────
+
+export async function adoptWizardCommand(rawArgs) {
+  const args     = rawArgs.slice(1);
+  const autoYes  = args.includes("--yes") || args.includes("-y") || args.includes("--json");
+  const jsonMode = args.includes("--json");
+  const cwd      = process.cwd();
+
+  const dirIdx   = args.indexOf("--dir");
+  const dirs     = dirIdx !== -1
+    ? args[dirIdx + 1].split(",").map(d => path.resolve(cwd, d.trim()))
+    : ["src","lib","app","api","pages","routes","controllers","services","handlers"]
+        .map(d => path.join(cwd, d)).filter(d => fs.existsSync(d));
+  if (!dirs.length) dirs.push(cwd);
+
+  const project    = detectProject(cwd);
+  const infernoDir = path.join(cwd, "inferno");
+  if (!fs.existsSync(infernoDir)) {
+    fs.mkdirSync(infernoDir, { recursive: true });
+    fs.mkdirSync(path.join(infernoDir, "scenarios"), { recursive: true });
+  }
+
+  if (!jsonMode) {
+    console.log();
+    console.log(`  ${bold("🔥 infernoflow adopt")} ${gray("— existing project wizard")}`);
+    console.log();
+    console.log(`  ${bold("Project:")}   ${cyan(project.name)} v${project.version}`);
+    console.log(`  ${bold("Language:")}  ${project.lang}   ${bold("Framework:")} ${project.framework}   ${bold("Type:")} ${project.type}`);
+    console.log();
+    info(`Scanning ${dirs.map(d => path.relative(cwd, d) || ".").join(", ")} …`);
+  }
+
+  const candidates = scout(dirs, cwd);
+
+  if (!candidates.length) {
+    if (jsonMode) { console.log(JSON.stringify({ ok: false, error: "No capabilities detected." })); return; }
+    warn("No capabilities detected. Use --dir src,lib,api");
+    return;
+  }
+
+  if (!jsonMode) {
+    console.log();
+    console.log(`  ${bold(`${candidates.length} capability candidates detected`)}`);
+  }
+
+  const approved = await review(candidates, autoYes);
+
+  if (!approved.length) {
+    if (jsonMode) { console.log(JSON.stringify({ ok: false, error: "No capabilities approved." })); return; }
+    warn("Nothing approved — exiting.");
+    return;
+  }
+
+  writeFiles(infernoDir, approved, project);
+  runCli(["context"], cwd);
+
+  // Offer hooks in interactive mode
+  let hooksInstalled = false;
+  if (!autoYes) {
+    const rl3 = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const ans  = (await ask(rl3, `\n  Install git hooks for auto-sync? ${gray("[Y/n]")} `)).trim().toLowerCase();
+    rl3.close();
+    if (ans !== "n") { runCli(["setup", "--yes"], cwd); hooksInstalled = true; }
+  } else {
+    runCli(["setup", "--yes"], cwd); hooksInstalled = true;
+  }
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: true, project, detected: candidates.length, approved: approved.length, capabilities: approved.map(c => c.id), hooksInstalled }));
+    return;
+  }
+
+  console.log();
+  done(`${bold(String(approved.length))} capabilities adopted`);
+  console.log();
+  console.log(`  ${green("✔")} ${bold("inferno/contract.json")} written`);
+  console.log(`  ${green("✔")} ${bold("inferno/capabilities.json")} written`);
+  console.log(`  ${green("✔")} ${bold("inferno/scenarios/")} scaffolded`);
+  console.log(`  ${green("✔")} ${bold("inferno/CONTEXT.md")} generated`);
+  if (hooksInstalled) console.log(`  ${green("✔")} Git hooks installed`);
+  console.log();
+  console.log(`  ${bold("Next steps:")}`);
+  console.log(`  ${cyan("1.")} Paste ${bold("inferno/CONTEXT.md")} into Claude or Cursor`);
+  console.log(`  ${cyan("2.")} Run ${bold("infernoflow vibe")} to keep everything in sync automatically`);
+  console.log(`  ${cyan("3.")} Run ${bold("infernoflow health")} to see your starting score`);
+  console.log();
+}

package/dist/lib/commands/export.mjs

@@ -0,0 +1,239 @@
+/**
+ * infernoflow export
+ *
+ * Export the capability contract to external formats so it can travel
+ * outside the repo — into API docs, service catalogs, spreadsheets, wikis.
+ *
+ * Formats:
+ *   openapi      OpenAPI 3.1 JSON (stubs for each capability)
+ *   backstage    Backstage catalog-info.yaml
+ *   csv          Spreadsheet-ready CSV
+ *   markdown     Confluence/Notion-ready Markdown table
+ *   json         Clean JSON (normalised, no internal infernoflow fields)
+ *
+ * Usage:
+ *   infernoflow export --format openapi
+ *   infernoflow export --format backstage --out catalog-info.yaml
+ *   infernoflow export --format csv --out capabilities.csv
+ *   infernoflow export --format markdown
+ *   infernoflow export --format json --out contract-export.json
+ */
+
+import * as fs   from "node:fs";
+import * as path from "node:path";
+import { done, warn, info, bold, cyan, gray } from "../ui/output.mjs";
+
+// ── Contract reader ───────────────────────────────────────────────────────────
+
+function readContract(infernoDir) {
+  for (const f of ["contract.json", "capabilities.json"]) {
+    const p = path.join(infernoDir, f);
+    if (!fs.existsSync(p)) continue;
+    try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch {}
+  }
+  return null;
+}
+
+function normaliseCaps(contract) {
+  const raw = contract?.capabilities || [];
+  return raw.map(c => {
+    if (typeof c === "string") return { id: c, description: "", tags: [], status: "active" };
+    return {
+      id:          c.id || c.name || "unknown",
+      description: c.description || "",
+      tags:        c.tags || [],
+      status:      c.status || "active",
+      since:       c.since || "",
+      owner:       c.owner || "",
+    };
+  });
+}
+
+function readMeta(infernoDir) {
+  const pkgPath = path.join(path.dirname(infernoDir), "package.json");
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    return { name: pkg.name || "my-service", version: pkg.version || "0.0.0", description: pkg.description || "" };
+  } catch {
+    return { name: path.basename(path.dirname(infernoDir)), version: "0.0.0", description: "" };
+  }
+}
+
+// ── Formatters ────────────────────────────────────────────────────────────────
+
+function toOpenApi(caps, meta) {
+  const paths = {};
+  for (const cap of caps) {
+    const route = `/${cap.id.replace(/_/g, "-")}`;
+    paths[route] = {
+      get: {
+        operationId: cap.id,
+        summary:     cap.description || cap.id,
+        tags:        cap.tags.length ? cap.tags : [meta.name],
+        parameters:  [],
+        responses: {
+          "200": { description: "Success", content: { "application/json": { schema: { type: "object" } } } },
+          "401": { description: "Unauthorized" },
+          "500": { description: "Internal Server Error" },
+        },
+      },
+    };
+  }
+
+  return JSON.stringify({
+    openapi: "3.1.0",
+    info: {
+      title:       meta.name,
+      version:     meta.version,
+      description: meta.description || `Capability contract for ${meta.name}`,
+    },
+    paths,
+    components: { schemas: {}, securitySchemes: {} },
+  }, null, 2);
+}
+
+function toBackstage(caps, meta) {
+  const tags = [...new Set(caps.flatMap(c => c.tags))].slice(0, 10);
+  const lines = [
+    `apiVersion: backstage.io/v1alpha1`,
+    `kind: Component`,
+    `metadata:`,
+    `  name: ${meta.name}`,
+    `  description: "${(meta.description || meta.name).replace(/"/g, '\\"')}"`,
+    `  annotations:`,
+    `    infernoflow/capability-count: "${caps.length}"`,
+    `    infernoflow/generated-at: "${new Date().toISOString()}"`,
+    tags.length ? `  tags:\n${tags.map(t => `    - ${t}`).join("\n")}` : "",
+    `spec:`,
+    `  type: service`,
+    `  lifecycle: production`,
+    `  owner: team-default`,
+    `  providesApis: []`,
+    `---`,
+    `# Capabilities`,
+    ...caps.map(c => [
+      `# ${c.id}`,
+      `#   ${c.description || "(no description)"}`,
+      `#   tags: ${c.tags.join(", ") || "none"}`,
+      `#   status: ${c.status}`,
+    ].join("\n")),
+  ].filter(Boolean);
+  return lines.join("\n") + "\n";
+}
+
+function toCsv(caps) {
+  const header = ["id", "description", "tags", "status", "since", "owner"];
+  const rows   = caps.map(c => [
+    c.id,
+    (c.description || "").replace(/"/g, '""'),
+    c.tags.join("|"),
+    c.status,
+    c.since,
+    c.owner,
+  ].map(v => `"${v}"`).join(","));
+  return [header.join(","), ...rows].join("\n") + "\n";
+}
+
+function toMarkdown(caps, meta) {
+  const lines = [
+    `# ${meta.name} — Capability Contract`,
+    ``,
+    `> Generated by infernoflow on ${new Date().toISOString().slice(0, 10)}`,
+    `> ${caps.length} capabilities tracked`,
+    ``,
+    `| Capability | Description | Tags | Status |`,
+    `|---|---|---|---|`,
+    ...caps.map(c =>
+      `| \`${c.id}\` | ${c.description || ""} | ${c.tags.join(", ") || "—"} | ${c.status} |`
+    ),
+    ``,
+  ];
+  return lines.join("\n");
+}
+
+function toCleanJson(caps, meta) {
+  return JSON.stringify({
+    name:        meta.name,
+    version:     meta.version,
+    exportedAt:  new Date().toISOString(),
+    capabilities: caps,
+  }, null, 2) + "\n";
+}
+
+// ── Entry ─────────────────────────────────────────────────────────────────────
+
+const FORMAT_EXT = {
+  openapi:   "openapi.json",
+  backstage: "catalog-info.yaml",
+  csv:       "capabilities.csv",
+  markdown:  "capabilities.md",
+  json:      "capabilities-export.json",
+};
+
+export async function exportCommand(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 fmtIdx   = args.indexOf("--format");
+  const format   = fmtIdx !== -1 ? args[fmtIdx + 1] : null;
+  const outIdx   = args.indexOf("--out");
+  const outArg   = outIdx !== -1 ? args[outIdx + 1] : null;
+
+  const validFormats = Object.keys(FORMAT_EXT);
+
+  if (!format || !validFormats.includes(format)) {
+    const msg = `Usage: infernoflow export --format <${validFormats.join("|")}> [--out <path>]`;
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else {
+      warn(msg);
+      console.log();
+      console.log(`  ${gray("Available formats:")}`);
+      console.log(`  ${bold("openapi")}   — OpenAPI 3.1 JSON with a stub path per capability`);
+      console.log(`  ${bold("backstage")} — Backstage catalog-info.yaml component definition`);
+      console.log(`  ${bold("csv")}       — Spreadsheet-ready CSV`);
+      console.log(`  ${bold("markdown")} — Confluence/Notion table`);
+      console.log(`  ${bold("json")}      — Clean normalised JSON`);
+      console.log();
+    }
+    return;
+  }
+
+  const contract = readContract(infernoDir);
+  if (!contract) {
+    const msg = "No contract.json or capabilities.json found.";
+    if (jsonMode) console.log(JSON.stringify({ ok: false, error: msg }));
+    else warn(msg);
+    process.exit(1);
+  }
+
+  const caps = normaliseCaps(contract);
+  const meta = readMeta(infernoDir);
+  const outPath = outArg || path.join(cwd, FORMAT_EXT[format]);
+
+  let output;
+  switch (format) {
+    case "openapi":   output = toOpenApi(caps, meta);   break;
+    case "backstage": output = toBackstage(caps, meta); break;
+    case "csv":       output = toCsv(caps);             break;
+    case "markdown":  output = toMarkdown(caps, meta);  break;
+    case "json":      output = toCleanJson(caps, meta); break;
+  }
+
+  fs.writeFileSync(outPath, output);
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: true, format, file: outPath, capabilities: caps.length }));
+  } else {
+    done(`Exported ${bold(String(caps.length))} capabilities → ${cyan(path.relative(cwd, outPath))}`);
+    console.log();
+  }
+}