infernoflow 0.19.0 → 0.21.0

package/dist/lib/commands/health.mjs

@@ -0,0 +1,309 @@
+/**
+ * infernoflow health
+ *
+ * Computes a weighted 0–100 health score for the capability contract.
+ * Breaks it down across five dimensions so you know exactly where to improve.
+ *
+ * Dimensions:
+ *   Coverage      % of capabilities that have descriptions      (weight 25)
+ *   Documentation % with at least one scenario/test             (weight 20)
+ *   Freshness     How recently the contract was updated          (weight 20)
+ *   Completeness  Version field, owner, tags present            (weight 15)
+ *   Drift risk    Open issues from `infernoflow check`           (weight 20)
+ *
+ * Usage:
+ *   infernoflow health                  Print score + breakdown
+ *   infernoflow health --json           Machine-readable
+ *   infernoflow health --fail-below 70  Exit 1 if score < 70 (CI gate)
+ *   infernoflow health --watch          Re-run every 30s (for terminals)
+ */
+
+import * as fs          from "node:fs";
+import * as path        from "node:path";
+import { execSync }     from "node:child_process";
+import { done, warn, info, bold, cyan, gray, green, yellow, red } from "../ui/output.mjs";
+
+const WEIGHTS = {
+  coverage:      25,
+  documentation: 20,
+  freshness:     20,
+  completeness:  15,
+  drift:         20,
+};
+
+// ── Readers ───────────────────────────────────────────────────────────────────
+
+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 readScenarios(infernoDir) {
+  const scenDir = path.join(infernoDir, "scenarios");
+  if (!fs.existsSync(scenDir)) return [];
+  return fs.readdirSync(scenDir)
+    .filter(f => f.endsWith(".json"))
+    .flatMap(f => {
+      try {
+        const data = JSON.parse(fs.readFileSync(path.join(scenDir, f), "utf8"));
+        return data.capability ? [data.capability] : (data.capabilities || []);
+      } catch { return []; }
+    });
+}
+
+function runCheck(cwd) {
+  try {
+    const out = execSync("npx infernoflow check --json", {
+      cwd, encoding: "utf8", timeout: 15_000, stdio: ["ignore", "pipe", "pipe"],
+    });
+    return JSON.parse(out);
+  } catch (err) {
+    try { return JSON.parse(err.stdout || "{}"); } catch { return {}; }
+  }
+}
+
+function lastModifiedDaysAgo(infernoDir) {
+  const files = ["contract.json", "capabilities.json"]
+    .map(f => path.join(infernoDir, f))
+    .filter(fs.existsSync);
+  if (!files.length) return 999;
+  const mtime = Math.max(...files.map(f => fs.statSync(f).mtimeMs));
+  return (Date.now() - mtime) / (1000 * 60 * 60 * 24);
+}
+
+// ── Scorers ───────────────────────────────────────────────────────────────────
+
+function scoreCoverage(caps) {
+  if (!caps.length) return { score: 0, detail: "No capabilities" };
+  const withDesc = caps.filter(c => c.description && c.description.length > 5).length;
+  const pct = Math.round((withDesc / caps.length) * 100);
+  return {
+    score:  pct,
+    detail: `${withDesc}/${caps.length} capabilities have descriptions`,
+    pct,
+  };
+}
+
+function scoreDocumentation(caps, scenarioCaps) {
+  if (!caps.length) return { score: 0, detail: "No capabilities" };
+  const scenSet = new Set(scenarioCaps.map(s => String(s).toLowerCase()));
+  const withScen = caps.filter(c => scenSet.has(c.id.toLowerCase())).length;
+  const pct = Math.round((withScen / caps.length) * 100);
+  return {
+    score:  Math.min(100, pct + (scenSet.size === 0 ? 0 : 10)), // bonus for having any scenarios
+    detail: `${withScen}/${caps.length} capabilities have test scenarios`,
+    pct,
+  };
+}
+
+function scoreFreshness(daysAgo) {
+  let score;
+  let label;
+  if (daysAgo <= 1)   { score = 100; label = "updated today"; }
+  else if (daysAgo <= 3)  { score = 95;  label = `updated ${Math.round(daysAgo)}d ago`; }
+  else if (daysAgo <= 7)  { score = 85;  label = `updated ${Math.round(daysAgo)}d ago`; }
+  else if (daysAgo <= 14) { score = 70;  label = `updated ${Math.round(daysAgo)}d ago`; }
+  else if (daysAgo <= 30) { score = 50;  label = `updated ${Math.round(daysAgo)}d ago`; }
+  else if (daysAgo <= 60) { score = 30;  label = `updated ${Math.round(daysAgo)}d ago — stale`; }
+  else                    { score = 10;  label = `not updated in ${Math.round(daysAgo)}d — very stale`; }
+  return { score, detail: label };
+}
+
+function scoreCompleteness(caps, contract) {
+  if (!caps.length) return { score: 0, detail: "No capabilities" };
+  const hasVersion = !!(contract?.version || contract?.contractVersion);
+  const withTags   = caps.filter(c => c.tags?.length).length;
+  const withOwner  = caps.filter(c => c.owner).length;
+  const withSince  = caps.filter(c => c.since).length;
+
+  const tagPct   = Math.round((withTags  / caps.length) * 100);
+  const ownerPct = Math.round((withOwner / caps.length) * 100);
+  const sincePct = Math.round((withSince / caps.length) * 100);
+
+  const score = Math.round(
+    (hasVersion ? 20 : 0) +
+    tagPct   * 0.3 +
+    ownerPct * 0.3 +
+    sincePct * 0.2
+  );
+
+  return {
+    score: Math.min(100, score),
+    detail: `version: ${hasVersion ? "✓" : "✗"}, tags: ${tagPct}%, owner: ${ownerPct}%, since: ${sincePct}%`,
+  };
+}
+
+function scoreDrift(checkResult) {
+  const issues   = checkResult?.issues || [];
+  const warnings = issues.filter(i => (i.severity || i.level || "error") === "warning").length;
+  const errors   = issues.filter(i => (i.severity || i.level || "error") === "error").length;
+  const status   = checkResult?.status;
+
+  if (status === "ok" || (!errors && !warnings)) return { score: 100, detail: "No issues found" };
+
+  const score = Math.max(0, 100 - (errors * 20) - (warnings * 8));
+  return {
+    score,
+    detail: `${errors} error${errors !== 1 ? "s" : ""}, ${warnings} warning${warnings !== 1 ? "s" : ""}`,
+  };
+}
+
+// ── Aggregate ─────────────────────────────────────────────────────────────────
+
+function computeHealth(infernoDir, cwd) {
+  const contract     = readContract(infernoDir);
+  const caps         = (contract?.capabilities || []).map(c =>
+    typeof c === "string" ? { id: c, description: "", tags: [], owner: "", since: "" } : c
+  );
+  const scenarioCaps = readScenarios(infernoDir);
+  const daysAgo      = lastModifiedDaysAgo(infernoDir);
+  const checkResult  = runCheck(cwd);
+
+  const dimensions = {
+    coverage:      scoreCoverage(caps),
+    documentation: scoreDocumentation(caps, scenarioCaps),
+    freshness:     scoreFreshness(daysAgo),
+    completeness:  scoreCompleteness(caps, contract),
+    drift:         scoreDrift(checkResult),
+  };
+
+  const totalScore = Math.round(
+    Object.entries(dimensions).reduce((sum, [key, dim]) => {
+      return sum + (dim.score * WEIGHTS[key]) / 100;
+    }, 0)
+  );
+
+  return { totalScore, dimensions, caps, daysAgo, checkResult };
+}
+
+// ── Renderer ──────────────────────────────────────────────────────────────────
+
+function scoreColor(score) {
+  if (score >= 80) return green;
+  if (score >= 60) return yellow;
+  return red;
+}
+
+function scoreGrade(score) {
+  if (score >= 90) return "A";
+  if (score >= 80) return "B";
+  if (score >= 70) return "C";
+  if (score >= 60) return "D";
+  return "F";
+}
+
+function barOf(score, width = 30) {
+  const filled = Math.round((score / 100) * width);
+  const empty  = width - filled;
+  return "█".repeat(filled) + "░".repeat(empty);
+}
+
+function printReport(totalScore, dimensions) {
+  const col   = scoreColor(totalScore);
+  const grade = scoreGrade(totalScore);
+
+  console.log();
+  console.log(`  ${bold("🔥 infernoflow health score")}`);
+  console.log();
+  console.log(`  ${col(bold(String(totalScore)))} / 100   ${col(bold(grade))}   ${col(barOf(totalScore))}`);
+  console.log();
+
+  const dimNames = {
+    coverage:      "Coverage     ",
+    documentation: "Docs/Tests   ",
+    freshness:     "Freshness    ",
+    completeness:  "Completeness ",
+    drift:         "Drift risk   ",
+  };
+
+  for (const [key, dim] of Object.entries(dimensions)) {
+    const w  = WEIGHTS[key];
+    const sc = dim.score;
+    const c  = scoreColor(sc);
+    const bar = barOf(sc, 20);
+    const weighted = Math.round((sc * w) / 100);
+    console.log(
+      `  ${bold(dimNames[key])} ${c(String(sc).padStart(3))}   ${c(bar)}  ${gray(`×${w}% = ${weighted}pts  ${dim.detail}`)}`
+    );
+  }
+  console.log();
+}
+
+function printTips(totalScore, dimensions) {
+  const tips = [];
+
+  if (dimensions.coverage.score < 70)
+    tips.push("Add descriptions to your capabilities in contract.json");
+  if (dimensions.documentation.score < 60)
+    tips.push("Create scenario files in inferno/scenarios/ for each capability");
+  if (dimensions.freshness.score < 70)
+    tips.push("Run `infernoflow suggest` to sync recent changes to the contract");
+  if (dimensions.completeness.score < 60)
+    tips.push("Add version, tags, owner, and since fields to your capabilities");
+  if (dimensions.drift.score < 80)
+    tips.push("Run `infernoflow check` and fix the reported issues");
+
+  if (tips.length) {
+    console.log(`  ${bold("Tips to improve:")}`);
+    tips.forEach(t => console.log(`  ${yellow("·")} ${t}`));
+    console.log();
+  }
+}
+
+// ── Entry ─────────────────────────────────────────────────────────────────────
+
+export async function healthCommand(rawArgs) {
+  const args      = rawArgs.slice(1);
+  const jsonMode  = args.includes("--json");
+  const watchMode = args.includes("--watch");
+  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 failBelowIdx = args.indexOf("--fail-below");
+  const failBelow    = failBelowIdx !== -1 ? parseInt(args[failBelowIdx + 1], 10) : null;
+
+  const intervalIdx  = args.indexOf("--interval");
+  const intervalSecs = intervalIdx !== -1 ? parseInt(args[intervalIdx + 1], 10) : 30;
+
+  const runOnce = () => {
+    const { totalScore, dimensions } = computeHealth(infernoDir, cwd);
+
+    if (jsonMode) {
+      const dimFlat = Object.fromEntries(
+        Object.entries(dimensions).map(([k, v]) => [k, { score: v.score, detail: v.detail, weight: WEIGHTS[k] }])
+      );
+      console.log(JSON.stringify({ ok: true, score: totalScore, grade: scoreGrade(totalScore), dimensions: dimFlat }));
+    } else {
+      if (watchMode) process.stdout.write("\x1Bc"); // clear screen
+      printReport(totalScore, dimensions);
+      if (!watchMode) printTips(totalScore, dimensions);
+    }
+
+    if (failBelow !== null && totalScore < failBelow) {
+      if (!jsonMode) console.error(red(`  ✗  Score ${totalScore} is below threshold ${failBelow} — failing.\n`));
+      process.exit(1);
+    }
+
+    return totalScore;
+  };
+
+  if (watchMode) {
+    if (!jsonMode) info(`Watching health score every ${intervalSecs}s — press Ctrl+C to stop`);
+    runOnce();
+    setInterval(runOnce, intervalSecs * 1000);
+    await new Promise(() => {});
+  } else {
+    runOnce();
+  }
+}

package/dist/lib/commands/init.mjs

@@ -155,6 +155,76 @@ export async function initCommand(args) {
   const force = args.includes("--force") || args.includes("-f");
   const yes = args.includes("--yes") || args.includes("-y");
   const adopt = args.includes("--adopt");
+
+  // ── Template shortcut ──────────────────────────────────────────────────────
+  const templateIdx  = args.indexOf("--template");
+  const templateName = templateIdx !== -1 ? args[templateIdx + 1] : null;
+
+  if (templateName) {
+    let tmplMod;
+    try { tmplMod = await import("../templates/index.mjs"); } catch {}
+    const tmpl = tmplMod?.getTemplate(templateName);
+    if (!tmpl) {
+      const available = tmplMod ? tmplMod.listTemplates().map(t => t.name).join(", ") : "rest-api, nextjs, cli, graphql, monorepo";
+      warn(`Unknown template: ${templateName}. Available: ${available}`);
+      process.exit(1);
+    }
+
+    const infernoDir = path.join(cwd, "inferno");
+    const scenDir    = path.join(infernoDir, "scenarios");
+    if (!fs.existsSync(infernoDir)) fs.mkdirSync(infernoDir, { recursive: true });
+    if (!fs.existsSync(scenDir))    fs.mkdirSync(scenDir,    { recursive: true });
+
+    const policyId = detectProjectName(cwd);
+    const caps     = tmpl.capabilities;
+
+    // Write contract.json
+    fs.writeFileSync(path.join(infernoDir, "contract.json"), JSON.stringify({
+      policyId, policyVersion: 1,
+      capabilities: caps.map(c => c.id),
+    }, null, 2) + "\n");
+
+    // Write capabilities.json
+    fs.writeFileSync(path.join(infernoDir, "capabilities.json"), JSON.stringify({
+      capabilities: caps.map(c => ({
+        id: c.id, description: c.description,
+        since: new Date().toISOString().slice(0, 10), source: `template:${templateName}`,
+      })),
+    }, null, 2) + "\n");
+
+    // Write one scenario per capability
+    for (const cap of caps) {
+      fs.writeFileSync(path.join(scenDir, `${cap.id}.json`), JSON.stringify({
+        id: `${cap.id}-happy-path`, capability: cap.id,
+        description: `Happy path for ${cap.description || cap.id}`,
+        steps: [
+          { action: "invoke", target: cap.id, input: {} },
+          { action: "assert", field: "status", value: "success" },
+        ],
+        capabilitiesCovered: [cap.id],
+      }, null, 2) + "\n");
+    }
+
+    // Write CHANGELOG.md
+    writeChangelog(path.join(infernoDir, "CHANGELOG.md"), policyId);
+
+    // Write CONTEXT.md hint
+    fs.writeFileSync(path.join(infernoDir, "CONTEXT.md"),
+      `# ${policyId} — infernoflow context\n\n> Template: ${templateName} — ${tmpl.description}\n\n## Hint\n${tmpl.contextHint}\n\n## Capabilities (${caps.length})\n${caps.map(c => `- \`${c.id}\`: ${c.description}`).join("\n")}\n`
+    );
+
+    if (tmpl.scripts) {
+      info(`Suggested package.json scripts for this template:`);
+      Object.entries(tmpl.scripts).forEach(([k, v]) => console.log(`  ${bold(k)}: ${gray(v)}`));
+      console.log();
+    }
+
+    done(`Initialised from template ${bold(cyan(templateName))} — ${bold(String(caps.length))} capabilities`);
+    console.log();
+    info(`Run ${cyan("infernoflow vibe")} to start vibe coding mode`);
+    console.log();
+    return;
+  }
   const cursorHooks = args.includes("--cursor-hooks");
   const vscodeCopilotHooks = args.includes("--vscode-copilot-hooks");
   const reportJson = args.includes("--report-json");

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