infernoflow 0.21.0 → 0.22.1

package/dist/bin/infernoflow.mjs

@@ -51,6 +51,9 @@ const COMMAND_DESCRIPTIONS = {
   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)",
+  doctor:  "Diagnose your infernoflow setup — checks Node, git, contract, AI providers, MCP, hooks",
+  coverage: "Map test files to capabilities — show which caps have test coverage and which don't",
+  review:  "AI-powered capability impact review for staged or recent git changes",
 };
 
 const COMMAND_HANDLERS = {
@@ -95,6 +98,9 @@ const COMMAND_HANDLERS = {
   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),
+  doctor:   async (args) => (await import("../lib/commands/doctor.mjs")).doctorCommand(args),
+  coverage: async (args) => (await import("../lib/commands/coverage.mjs")).coverageCommand(args),
+  review:   async (args) => (await import("../lib/commands/review.mjs")).reviewCommand(args),
 };
 
 function formatCommandsHelp() {
@@ -339,6 +345,22 @@ ${formatCommandsHelp()}
     --interval <secs>         Watch interval in seconds (default: 30)
     --json                    Machine-readable score + breakdown
 
+  ${bold("doctor options:")}
+    --fix                     Auto-fix common issues (installs hooks, runs init, etc.)
+    --json                    Machine-readable list of pass/warn/fail results
+
+  ${bold("coverage options:")}
+    --dir <path>              Extra directory to scan for test files (repeatable)
+    --threshold <0-1>         Minimum fuzzy-match score to count a test (default: 0.25)
+    --fail-below <pct>        Exit 1 if coverage percentage is below this value (CI gate)
+    --json                    Machine-readable coverage breakdown
+
+  ${bold("review options:")}
+    --unstaged                Review all working-tree changes (not just staged)
+    --last                    Review last commit (git diff HEAD~1)
+    --dry-run                 Print the AI prompt only — no API call made
+    --json                    Machine-readable output (affectedCaps, summary, provider)
+
   ${bold("Machine output:")}
     ${gray("status --json")}
     ${gray("check --json")}

package/dist/lib/ai/providerRouter.mjs

@@ -1,73 +1,236 @@
-import { detectIdeContext } from "./ideDetection.mjs";
-
-export async function resolveProvider(requestedProvider = "auto", preferredIde = "auto") {
-  const providerRequested = String(requestedProvider || "auto").toLowerCase();
-  const ide = detectIdeContext(preferredIde);
-  const reasonCodes = [...ide.reasonCodes];
-
-  if (providerRequested === "local") {
-    reasonCodes.push("LOCAL_PROVIDER_SELECTED");
-    return {
-      providerRequested,
-      providerResolved: "local",
-      ideDetected: ide.ideDetected,
-      agentAvailable: ide.agentAvailable,
-      reasonCodes,
-    };
-  }
+/**
+ * infernoflow AI provider router
+ *
+ * Tries providers in order until one works:
+ *   Tier 1 — VS Code Language Model API (vscode.lm — any Copilot model: Gemini, Claude, GPT)
+ *   Tier 2 — Direct API: Anthropic, OpenAI, Google AI (Gemini), OpenRouter
+ *   Tier 3 — Ollama (local, free, offline)
+ *   Tier 4 — Prompt fallback (print prompt, no AI call)
+ *
+ * Config sources (in priority order):
+ *   1. Environment variables
+ *   2. inferno/integrations.json
+ *   3. Auto-detection (Ollama running locally, etc.)
+ */
 
-  if (providerRequested === "prompt") {
-    reasonCodes.push("PROMPT_PROVIDER_SELECTED");
-    return {
-      providerRequested,
-      providerResolved: "prompt",
-      ideDetected: ide.ideDetected,
-      agentAvailable: ide.agentAvailable,
-      reasonCodes,
-    };
-  }
+import * as fs   from "node:fs";
+import * as path from "node:path";
+import * as https from "node:https";
+import * as http  from "node:http";
+
+// ── Config reader ─────────────────────────────────────────────────────────────
+
+export function readAiConfig(cwd) {
+  const p = path.join(cwd, "inferno", "integrations.json");
+  if (!fs.existsSync(p)) return {};
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return {}; }
+}
+
+// ── HTTP helpers ──────────────────────────────────────────────────────────────
+
+function post(url, headers, body) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const lib    = parsed.protocol === "https:" ? https : http;
+    const data   = JSON.stringify(body);
+
+    const req = lib.request({
+      hostname: parsed.hostname,
+      port:     parsed.port || (parsed.protocol === "https:" ? 443 : 80),
+      path:     parsed.pathname + (parsed.search || ""),
+      method:   "POST",
+      headers:  { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(data), ...headers },
+    }, (res) => {
+      let raw = "";
+      res.on("data", d => (raw += d));
+      res.on("end", () => {
+        try { resolve({ status: res.statusCode, body: JSON.parse(raw) }); }
+        catch { resolve({ status: res.statusCode, body: raw }); }
+      });
+    });
+    req.on("error", reject);
+    req.write(data);
+    req.end();
+  });
+}
+
+// ── Tier 2: Direct API providers ─────────────────────────────────────────────
+
+async function callAnthropic(prompt, config) {
+  const apiKey = process.env.ANTHROPIC_API_KEY || config.anthropic?.apiKey;
+  if (!apiKey) return null;
 
-  if (providerRequested === "agent") {
-    if (!ide.agentAvailable) {
-      reasonCodes.push("EXPLICIT_AGENT_REQUIRED");
-      return {
-        providerRequested,
-        providerResolved: "none",
-        ideDetected: ide.ideDetected,
-        agentAvailable: ide.agentAvailable,
-        reasonCodes,
-        error: "agent_unavailable",
-      };
+  const model = config.anthropic?.model || process.env.ANTHROPIC_MODEL || "claude-sonnet-4-6";
+
+  try {
+    const res = await post(
+      "https://api.anthropic.com/v1/messages",
+      { "x-api-key": apiKey, "anthropic-version": "2023-06-01" },
+      {
+        model,
+        max_tokens: 1024,
+        messages: [{ role: "user", content: prompt }],
+      }
+    );
+    if (res.status === 200 && res.body?.content?.[0]?.text) {
+      return { text: res.body.content[0].text, provider: "anthropic", model };
     }
-    reasonCodes.push("IDE_AGENT_SELECTED");
-    return {
-      providerRequested,
-      providerResolved: "agent",
-      ideDetected: ide.ideDetected,
-      agentAvailable: ide.agentAvailable,
-      reasonCodes,
-    };
-  }
+  } catch {}
+  return null;
+}
+
+async function callOpenAI(prompt, config) {
+  const apiKey   = process.env.OPENAI_API_KEY || config.openai?.apiKey;
+  const endpoint = process.env.OPENAI_ENDPOINT || config.openai?.endpoint || "https://api.openai.com/v1/chat/completions";
+  if (!apiKey) return null;
+
+  const model = config.openai?.model || process.env.OPENAI_MODEL || "gpt-4o";
+
+  try {
+    const res = await post(
+      endpoint,
+      { "Authorization": `Bearer ${apiKey}` },
+      {
+        model,
+        max_tokens: 1024,
+        messages: [{ role: "user", content: prompt }],
+      }
+    );
+    if (res.status === 200 && res.body?.choices?.[0]?.message?.content) {
+      return { text: res.body.choices[0].message.content, provider: "openai", model };
+    }
+  } catch {}
+  return null;
+}
+
+async function callGemini(prompt, config) {
+  const apiKey = process.env.GOOGLE_AI_API_KEY || process.env.GEMINI_API_KEY || config.gemini?.apiKey;
+  if (!apiKey) return null;
+
+  const model = config.gemini?.model || process.env.GEMINI_MODEL || "gemini-2.0-flash";
 
-  // auto
-  if (ide.agentAvailable) {
-    reasonCodes.push("IDE_AGENT_SELECTED");
-    return {
-      providerRequested: "auto",
-      providerResolved: "agent",
-      ideDetected: ide.ideDetected,
-      agentAvailable: ide.agentAvailable,
-      reasonCodes,
-    };
+  try {
+    const res = await post(
+      `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${apiKey}`,
+      {},
+      { contents: [{ parts: [{ text: prompt }] }] }
+    );
+    const text = res.body?.candidates?.[0]?.content?.parts?.[0]?.text;
+    if (res.status === 200 && text) {
+      return { text, provider: "gemini", model };
+    }
+  } catch {}
+  return null;
+}
+
+async function callOpenRouter(prompt, config) {
+  const apiKey = process.env.OPENROUTER_API_KEY || config.openrouter?.apiKey;
+  if (!apiKey) return null;
+
+  const model = config.openrouter?.model || process.env.OPENROUTER_MODEL || "anthropic/claude-sonnet-4-6";
+
+  try {
+    const res = await post(
+      "https://openrouter.ai/api/v1/chat/completions",
+      { "Authorization": `Bearer ${apiKey}`, "HTTP-Referer": "https://infernoflow.dev" },
+      {
+        model,
+        messages: [{ role: "user", content: prompt }],
+        max_tokens: 1024,
+      }
+    );
+    if (res.status === 200 && res.body?.choices?.[0]?.message?.content) {
+      return { text: res.body.choices[0].message.content, provider: "openrouter", model };
+    }
+  } catch {}
+  return null;
+}
+
+// ── Tier 3: Ollama (local) ────────────────────────────────────────────────────
+
+async function callOllama(prompt, config) {
+  const host  = process.env.OLLAMA_HOST || config.ollama?.host || "http://localhost:11434";
+  const model = process.env.OLLAMA_MODEL || config.ollama?.model || "llama3";
+
+  // Quick liveness check
+  try {
+    await new Promise((res, rej) => {
+      const u = new URL(host);
+      http.get({ hostname: u.hostname, port: u.port || 11434, path: "/api/tags", timeout: 1500 },
+        r => res(r)).on("error", rej);
+    });
+  } catch { return null; }
+
+  try {
+    const res = await post(
+      `${host}/api/generate`,
+      {},
+      { model, prompt, stream: false }
+    );
+    if (res.status === 200 && res.body?.response) {
+      return { text: res.body.response, provider: "ollama", model };
+    }
+  } catch {}
+  return null;
+}
+
+// ── Main router ───────────────────────────────────────────────────────────────
+
+/**
+ * Call the best available AI provider with a prompt.
+ *
+ * @param {string} prompt  - The full prompt text
+ * @param {object} opts
+ *   opts.cwd      - Project root (for reading integrations.json)
+ *   opts.provider - Force a specific provider: anthropic|openai|gemini|openrouter|ollama|prompt
+ *   opts.silent   - Don't print "using provider X" message
+ * @returns {{ text: string, provider: string, model: string } | null}
+ *   null means no provider was available → caller should use prompt fallback
+ */
+export async function callAI(prompt, opts = {}) {
+  const cwd      = opts.cwd || process.cwd();
+  const config   = readAiConfig(cwd);
+  const forced   = (opts.provider || "auto").toLowerCase();
+  const silent   = opts.silent ?? true;
+
+  const providers = [
+    // Tier 2 — direct API (Tier 1 vscode.lm is handled in the VS Code extension)
+    ["anthropic",   () => callAnthropic(prompt, config)],
+    ["openai",      () => callOpenAI(prompt, config)],
+    ["gemini",      () => callGemini(prompt, config)],
+    ["openrouter",  () => callOpenRouter(prompt, config)],
+    // Tier 3 — local
+    ["ollama",      () => callOllama(prompt, config)],
+  ];
+
+  // If a specific provider is forced, only try that one
+  const toTry = forced === "auto" || forced === "prompt"
+    ? providers
+    : providers.filter(([name]) => name === forced);
+
+  for (const [name, fn] of toTry) {
+    try {
+      const result = await fn();
+      if (result) {
+        if (!silent) process.stderr.write(`  [infernoflow ai] using ${name}:${result.model}\n`);
+        return result;
+      }
+    } catch {}
   }
 
-  reasonCodes.push("FALLBACK_PROMPT_MODE");
+  return null; // No provider → fallback to prompt output
+}
+
+/**
+ * Detect which providers are configured (for doctor command).
+ */
+export function detectAvailableProviders(cwd) {
+  const config = readAiConfig(cwd);
   return {
-    providerRequested: "auto",
-    providerResolved: "prompt",
-    ideDetected: ide.ideDetected,
-    agentAvailable: ide.agentAvailable,
-    reasonCodes,
+    anthropic:  !!(process.env.ANTHROPIC_API_KEY  || config.anthropic?.apiKey),
+    openai:     !!(process.env.OPENAI_API_KEY      || config.openai?.apiKey),
+    gemini:     !!(process.env.GOOGLE_AI_API_KEY   || process.env.GEMINI_API_KEY || config.gemini?.apiKey),
+    openrouter: !!(process.env.OPENROUTER_API_KEY  || config.openrouter?.apiKey),
+    ollama:     false, // checked async — doctor runs its own check
   };
 }
-

package/dist/lib/commands/coverage.mjs

@@ -0,0 +1,282 @@
+/**
+ * infernoflow coverage
+ *
+ * Maps test files to capabilities via fuzzy name matching.
+ * Shows which capabilities have test coverage and which don't.
+ *
+ * Usage:
+ *   infernoflow coverage               Print coverage table
+ *   infernoflow coverage --json        Machine-readable output
+ *   infernoflow coverage --dir src/    Extra dirs to scan (default: project root)
+ *   infernoflow coverage --fail-below 50  Exit 1 if coverage < N%
+ */
+
+import * as fs   from "node:fs";
+import * as path from "node:path";
+import { bold, cyan, gray, green, yellow, red } from "../ui/output.mjs";
+
+// ─── test pattern extractors ─────────────────────────────────────────────────
+
+const TEST_PATTERNS = [
+  // Jest / Vitest  — it("...", …)  test("...", …)  describe("...", …)
+  { regex: /(?:it|test|describe)\s*\(\s*["'`]([^"'`]+)["'`]/g, lang: "js" },
+  // Pytest         — def test_something
+  { regex: /def\s+(test_[\w_]+)\s*\(/g, lang: "py" },
+  // RSpec          — describe/it "..."
+  { regex: /(?:describe|it)\s+["']([^"']+)["']/g, lang: "rb" },
+  // Go             — func TestXxx(
+  { regex: /func\s+(Test\w+)\s*\(/g, lang: "go" },
+  // Rust           — #[test] fn xxx
+  { regex: /#\[test\]\s*\n\s*(?:async\s+)?fn\s+(\w+)/g, lang: "rs" },
+];
+
+const TEST_FILE_GLOBS = [
+  /\.(test|spec)\.[jt]sx?$/,   // foo.test.ts
+  /__tests__/,                  // __tests__/foo.js
+  /\.test\.py$/,                // test_foo.py
+  /^test_.*\.py$/,              // test_foo.py (basename)
+  /_spec\.rb$/,                 // foo_spec.rb
+  /\/spec\//,                   // spec/ directory
+  /_test\.go$/,                 // foo_test.go
+  /_test\.rs$/,                 // foo_test.rs
+];
+
+const SKIP_DIRS = new Set([
+  "node_modules", ".git", "dist", "build", "out", ".next",
+  "coverage", ".nyc_output", "__pycache__", ".pytest_cache",
+  "vendor", "tmp", ".turbo",
+]);
+
+// ─── file walker ─────────────────────────────────────────────────────────────
+
+function* walkFiles(dir) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return; }
+
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      if (!SKIP_DIRS.has(e.name)) yield* walkFiles(path.join(dir, e.name));
+    } else if (e.isFile()) {
+      yield path.join(dir, e.name);
+    }
+  }
+}
+
+function isTestFile(filePath) {
+  const basename = path.basename(filePath);
+  return TEST_FILE_GLOBS.some(re => re.test(filePath) || re.test(basename));
+}
+
+// ─── test name extractor ─────────────────────────────────────────────────────
+
+function extractTestNames(filePath) {
+  let src;
+  try { src = fs.readFileSync(filePath, "utf8"); }
+  catch { return []; }
+
+  const names = new Set();
+  for (const { regex } of TEST_PATTERNS) {
+    const r = new RegExp(regex.source, regex.flags);
+    let m;
+    while ((m = r.exec(src)) !== null) {
+      names.add(m[1].trim());
+    }
+  }
+  return [...names];
+}
+
+// ─── fuzzy matcher ───────────────────────────────────────────────────────────
+
+/**
+ * Tokenise a string: split on spaces, hyphens, underscores, camelCase.
+ * Returns an array of lowercase tokens.
+ */
+function tokenise(str) {
+  return str
+    .replace(/([a-z])([A-Z])/g, "$1 $2")   // camelCase split
+    .toLowerCase()
+    .split(/[\s_\-/]+/)
+    .filter(Boolean);
+}
+
+/**
+ * Jaccard-like overlap score between two token sets.
+ * Returns a value in [0, 1].
+ */
+function overlapScore(a, b) {
+  const setA = new Set(a);
+  const setB = new Set(b);
+  let common = 0;
+  for (const t of setA) if (setB.has(t)) common++;
+  const union = setA.size + setB.size - common;
+  return union === 0 ? 0 : common / union;
+}
+
+/**
+ * Best match score between a test name and a capability (id + name).
+ */
+function matchScore(testName, cap) {
+  const testTokens = tokenise(testName);
+  const idTokens   = tokenise(cap.id   || "");
+  const nameTokens = tokenise(cap.name || "");
+  return Math.max(
+    overlapScore(testTokens, idTokens),
+    overlapScore(testTokens, nameTokens),
+  );
+}
+
+// ─── main scanner ─────────────────────────────────────────────────────────────
+
+function scanTestFiles(dirs) {
+  const testFiles = [];
+  for (const dir of dirs) {
+    for (const f of walkFiles(dir)) {
+      if (isTestFile(f)) testFiles.push(f);
+    }
+  }
+  return testFiles;
+}
+
+function buildTestIndex(testFiles) {
+  // Returns: Map<testName, filePath>
+  const index = new Map();
+  for (const f of testFiles) {
+    for (const name of extractTestNames(f)) {
+      if (!index.has(name)) index.set(name, f);
+    }
+  }
+  return index;
+}
+
+/** Returns: Map<capId, { matched: [{testName, file, score}], score: number }> */
+function mapTestsToCaps(capabilities, testIndex, threshold = 0.25) {
+  const result = new Map();
+
+  for (const cap of capabilities) {
+    const hits = [];
+    for (const [testName, file] of testIndex) {
+      const score = matchScore(testName, cap);
+      if (score >= threshold) {
+        hits.push({ testName, file: path.relative(process.cwd(), file), score });
+      }
+    }
+    hits.sort((a, b) => b.score - a.score);
+    result.set(cap.id, { cap, hits });
+  }
+  return result;
+}
+
+// ─── reporters ────────────────────────────────────────────────────────────────
+
+function bar(pct, width = 20) {
+  const filled = Math.round((pct / 100) * width);
+  const colour = pct >= 75 ? green : pct >= 40 ? yellow : red;
+  return colour("█".repeat(filled)) + gray("░".repeat(width - filled));
+}
+
+function printTable(coverageMap) {
+  const covered   = [...coverageMap.values()].filter(v => v.hits.length > 0).length;
+  const total     = coverageMap.size;
+  const pct       = total === 0 ? 0 : Math.round((covered / total) * 100);
+
+  console.log();
+  console.log(bold("  Capability Coverage"));
+  console.log(gray("  ─────────────────────────────────────────────────────────────"));
+  console.log(
+    gray("  ") +
+    bold(cyan("Capability".padEnd(32))) +
+    bold(cyan("Tests".padEnd(8))) +
+    bold(cyan("Top match"))
+  );
+  console.log(gray("  ─────────────────────────────────────────────────────────────"));
+
+  for (const [, { cap, hits }] of coverageMap) {
+    const status  = hits.length > 0 ? green("✔") : red("✗");
+    const topName = hits[0] ? gray(`  ${hits[0].testName.slice(0, 42)}`) : "";
+    const count   = hits.length === 0 ? red("0") : green(String(hits.length));
+    console.log(
+      `  ${status} ${cap.id.padEnd(30)} ${count.padEnd(6)} ${topName}`
+    );
+  }
+
+  console.log(gray("  ─────────────────────────────────────────────────────────────"));
+  console.log();
+  console.log(`  ${bar(pct)} ${bold(pct + "%")} (${covered}/${total} capabilities covered)`);
+  console.log();
+
+  if (total > 0 && covered < total) {
+    const uncovered = [...coverageMap.values()]
+      .filter(v => v.hits.length === 0)
+      .map(v => v.cap.id);
+    console.log(yellow(`  ⚠  Uncovered: ${uncovered.join(", ")}`));
+    console.log();
+  }
+}
+
+// ─── entry point ─────────────────────────────────────────────────────────────
+
+export async function coverageCommand(rawArgs) {
+  const args       = rawArgs || [];
+  const jsonMode   = args.includes("--json");
+  const dirIdx     = args.indexOf("--dir");
+  const extraDirs  = dirIdx !== -1 ? [args[dirIdx + 1]] : [];
+  const failIdx    = args.indexOf("--fail-below");
+  const failBelow  = failIdx !== -1 ? Number(args[failIdx + 1]) : null;
+  const threshold  = (() => {
+    const i = args.indexOf("--threshold");
+    return i !== -1 ? Number(args[i + 1]) : 0.25;
+  })();
+
+  const cwd       = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+
+  // Load capabilities
+  const capsPath = path.join(infernoDir, "capabilities.json");
+  if (!fs.existsSync(capsPath)) {
+    console.error(red("✗ inferno/capabilities.json not found — run `infernoflow init` first."));
+    process.exit(1);
+  }
+  let capabilities;
+  try { capabilities = JSON.parse(fs.readFileSync(capsPath, "utf8")); }
+  catch (e) { console.error(red("✗ Failed to parse capabilities.json: " + e.message)); process.exit(1); }
+
+  if (!Array.isArray(capabilities) || capabilities.length === 0) {
+    console.log(yellow("No capabilities found."));
+    process.exit(0);
+  }
+
+  // Scan test files
+  const scanDirs = [cwd, ...extraDirs];
+  if (!jsonMode) process.stdout.write(gray("  Scanning test files…"));
+  const testFiles = scanTestFiles(scanDirs);
+  if (!jsonMode) process.stdout.write(`\r  Found ${testFiles.length} test file(s).    \n`);
+
+  const testIndex   = buildTestIndex(testFiles);
+  const coverageMap = mapTestsToCaps(capabilities, testIndex, threshold);
+
+  const covered = [...coverageMap.values()].filter(v => v.hits.length > 0).length;
+  const total   = coverageMap.size;
+  const pct     = total === 0 ? 0 : Math.round((covered / total) * 100);
+
+  if (jsonMode) {
+    const out = {
+      summary: { covered, total, pct, testFiles: testFiles.length },
+      capabilities: [...coverageMap.entries()].map(([id, { cap, hits }]) => ({
+        id,
+        name: cap.name,
+        covered: hits.length > 0,
+        testCount: hits.length,
+        topTests: hits.slice(0, 3).map(h => ({ name: h.testName, file: h.file, score: +h.score.toFixed(3) })),
+      })),
+    };
+    console.log(JSON.stringify(out, null, 2));
+  } else {
+    printTable(coverageMap);
+  }
+
+  if (failBelow !== null && pct < failBelow) {
+    if (!jsonMode) console.error(red(`✗ Coverage ${pct}% is below threshold ${failBelow}%`));
+    process.exit(1);
+  }
+}

package/dist/lib/commands/doctor.mjs

@@ -0,0 +1,284 @@
+/**
+ * infernoflow doctor
+ *
+ * Comprehensive setup diagnostic — like `brew doctor`.
+ * Checks every component of the infernoflow setup and tells you
+ * exactly what's wrong and how to fix it.
+ *
+ * Usage:
+ *   infernoflow doctor         Print full diagnostic report
+ *   infernoflow doctor --fix   Auto-fix common issues
+ *   infernoflow doctor --json  Machine-readable output
+ */
+
+import * as fs        from "node:fs";
+import * as path      from "node:path";
+import * as os        from "node:os";
+import * as http      from "node:http";
+import { execSync, spawnSync } from "node:child_process";
+import { bold, cyan, gray, green, yellow, red } from "../ui/output.mjs";
+import { detectAvailableProviders } from "../ai/providerRouter.mjs";
+
+// ── Check runners ─────────────────────────────────────────────────────────────
+
+function check(label, fn) {
+  try {
+    const result = fn();
+    return { label, ...result };
+  } catch (err) {
+    return { label, status: "error", message: err.message, fix: null };
+  }
+}
+
+function pass(message, detail)  { return { status: "pass",  message, detail: detail || null, fix: null }; }
+function warn(message, fix)     { return { status: "warn",  message, detail: null, fix: fix || null }; }
+function fail(message, fix)     { return { status: "fail",  message, detail: null, fix: fix || null }; }
+
+// ── Individual checks ─────────────────────────────────────────────────────────
+
+function checkNodeVersion() {
+  const v     = process.version;
+  const major = parseInt(v.slice(1).split(".")[0], 10);
+  if (major >= 20) return pass(`Node.js ${v}`, "Node 20+ recommended");
+  if (major >= 18) return pass(`Node.js ${v}`);
+  return fail(`Node.js ${v} — infernoflow requires Node 18+`, "Install Node 20 from nodejs.org");
+}
+
+function checkCli() {
+  try {
+    const r = spawnSync("infernoflow", ["--version"], { encoding: "utf8", timeout: 5000 });
+    if (r.status === 0) return pass(`infernoflow v${r.stdout.trim()} installed`);
+    return fail("infernoflow CLI not found on PATH", "npm install -g infernoflow");
+  } catch {
+    return fail("infernoflow CLI not found on PATH", "npm install -g infernoflow");
+  }
+}
+
+function checkGitRepo(cwd) {
+  try {
+    execSync("git rev-parse --git-dir", { cwd, stdio: "ignore" });
+    return pass("Git repository detected");
+  } catch {
+    return fail("Not a git repository", "git init && git add . && git commit -m 'init'");
+  }
+}
+
+function checkInfernoDir(cwd) {
+  const infernoDir = path.join(cwd, "inferno");
+  if (!fs.existsSync(infernoDir)) return fail("inferno/ not found", "infernoflow init");
+  return pass("inferno/ directory exists");
+}
+
+function checkContract(cwd) {
+  const infernoDir = path.join(cwd, "inferno");
+  for (const f of ["contract.json", "capabilities.json"]) {
+    const p = path.join(infernoDir, f);
+    if (!fs.existsSync(p)) continue;
+    try {
+      const data = JSON.parse(fs.readFileSync(p, "utf8"));
+      const caps = (data.capabilities || []).length;
+      return pass(`${f} valid — ${caps} capabilities`);
+    } catch {
+      return fail(`${f} contains invalid JSON`, `Fix the JSON syntax in inferno/${f}`);
+    }
+  }
+  return fail("No contract.json or capabilities.json", "infernoflow init");
+}
+
+function checkScenarios(cwd) {
+  const scenDir = path.join(cwd, "inferno", "scenarios");
+  if (!fs.existsSync(scenDir)) return warn("No scenarios/ directory", "infernoflow init");
+  const files = fs.readdirSync(scenDir).filter(f => f.endsWith(".json"));
+  if (!files.length) return warn("scenarios/ is empty", "Add scenario files or run infernoflow suggest");
+  return pass(`${files.length} scenario file${files.length !== 1 ? "s" : ""} found`);
+}
+
+function checkChangelog(cwd) {
+  const p = path.join(cwd, "inferno", "CHANGELOG.md");
+  if (!fs.existsSync(p)) return warn("No inferno/CHANGELOG.md", "infernoflow init");
+  return pass("inferno/CHANGELOG.md exists");
+}
+
+function checkContextMd(cwd) {
+  const p = path.join(cwd, "inferno", "CONTEXT.md");
+  if (!fs.existsSync(p)) return warn("No CONTEXT.md generated", "infernoflow context");
+  const age = (Date.now() - fs.statSync(p).mtimeMs) / (1000 * 60 * 60 * 24);
+  if (age > 7) return warn(`CONTEXT.md is ${Math.round(age)} days old — may be stale`, "infernoflow context");
+  return pass(`CONTEXT.md present (${Math.round(age)}d old)`);
+}
+
+function checkGitHooks(cwd) {
+  const hooksDir  = path.join(cwd, ".git", "hooks");
+  const postCommit = path.join(hooksDir, "post-commit");
+  const prePush    = path.join(hooksDir, "pre-push");
+  const hasPost    = fs.existsSync(postCommit) && fs.readFileSync(postCommit, "utf8").includes("infernoflow");
+  const hasPre     = fs.existsSync(prePush)    && fs.readFileSync(prePush, "utf8").includes("infernoflow");
+  if (hasPost && hasPre) return pass("Git hooks installed (post-commit + pre-push)");
+  if (hasPost || hasPre) return warn("Partial git hooks installed", "infernoflow setup --yes");
+  return warn("Git hooks not installed", "infernoflow setup --yes");
+}
+
+function checkMcp(cwd) {
+  // Check for MCP server in cursor config or .mcp.json
+  const checks = [
+    path.join(cwd, ".cursor", "mcp.json"),
+    path.join(cwd, ".mcp.json"),
+    path.join(os.homedir(), ".cursor", "mcp.json"),
+    path.join(os.homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json"),
+    path.join(os.homedir(), "AppData", "Roaming", "Claude", "claude_desktop_config.json"),
+  ];
+  for (const p of checks) {
+    if (!fs.existsSync(p)) continue;
+    try {
+      const data = JSON.parse(fs.readFileSync(p, "utf8"));
+      const servers = data.mcpServers || data.mcp_servers || {};
+      if (Object.keys(servers).some(k => k.toLowerCase().includes("inferno"))) {
+        return pass(`MCP server configured in ${path.basename(p)}`);
+      }
+    } catch {}
+  }
+  return warn("MCP server not configured", "infernoflow setup --yes   (adds to Cursor/Claude config)");
+}
+
+function checkAiProviders(cwd) {
+  const providers = detectAvailableProviders(cwd);
+  const available = Object.entries(providers).filter(([, v]) => v).map(([k]) => k);
+
+  if (available.length) return pass(`AI provider${available.length !== 1 ? "s" : ""}: ${available.join(", ")}`);
+
+  return warn(
+    "No AI provider configured",
+    "Set ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_AI_API_KEY, or OPENROUTER_API_KEY\n" +
+    "     Or install Ollama (ollama.com) for free local AI\n" +
+    "     Or use VS Code with GitHub Copilot (zero config)"
+  );
+}
+
+async function checkOllama() {
+  return new Promise(resolve => {
+    const req = http.get({ hostname: "localhost", port: 11434, path: "/api/tags", timeout: 1500 }, res => {
+      resolve(pass("Ollama running on localhost:11434"));
+    });
+    req.on("error", () => resolve({ status: "info", message: "Ollama not running (optional)", fix: "ollama serve", detail: null }));
+    req.on("timeout", () => { req.destroy(); resolve({ status: "info", message: "Ollama not running (optional)", fix: null, detail: null }); });
+  });
+}
+
+function checkCloudToken(cwd) {
+  const p = path.join(cwd, "inferno", "integrations.json");
+  if (!fs.existsSync(p)) return { status: "info", message: "Cloud sync not configured (optional)", fix: "infernoflow cloud init", detail: null };
+  try {
+    const data = JSON.parse(fs.readFileSync(p, "utf8"));
+    if (data.cloud?.token) return pass("Cloud sync configured");
+    return { status: "info", message: "Cloud sync not configured (optional)", fix: "infernoflow cloud init", detail: null };
+  } catch {
+    return { status: "info", message: "Cloud sync not configured (optional)", fix: null, detail: null };
+  }
+}
+
+// ── Auto-fix ──────────────────────────────────────────────────────────────────
+
+function autoFix(results, cwd) {
+  const fixable = results.filter(r => r.status === "warn" && r.fix);
+  const fixed   = [];
+
+  for (const r of fixable) {
+    const fix = r.fix;
+    if (fix.startsWith("infernoflow ")) {
+      const args = fix.slice("infernoflow ".length).split(" ");
+      const res  = spawnSync("infernoflow", args, { cwd, encoding: "utf8", timeout: 30_000 });
+      if (res.status === 0) fixed.push(r.label);
+    }
+  }
+  return fixed;
+}
+
+// ── Renderer ──────────────────────────────────────────────────────────────────
+
+function icon(status) {
+  if (status === "pass") return green("✔");
+  if (status === "warn") return yellow("⚠");
+  if (status === "fail") return red("✗");
+  return gray("·");
+}
+
+function printReport(results, elapsed) {
+  const counts = { pass: 0, warn: 0, fail: 0, info: 0, error: 0 };
+  for (const r of results) counts[r.status] = (counts[r.status] || 0) + 1;
+
+  console.log();
+  console.log(`  ${bold("🔥 infernoflow doctor")}`);
+  console.log();
+
+  const w = Math.max(...results.map(r => r.label.length)) + 2;
+  for (const r of results) {
+    console.log(`  ${icon(r.status)}  ${bold(r.label.padEnd(w))} ${r.message}`);
+    if (r.detail) console.log(`     ${" ".repeat(w)} ${gray(r.detail)}`);
+    if (r.fix && (r.status === "warn" || r.status === "fail")) {
+      console.log(`     ${" ".repeat(w)} ${cyan("fix:")} ${gray(r.fix)}`);
+    }
+  }
+
+  console.log();
+  const overall = counts.fail > 0 ? red("issues found") : counts.warn > 0 ? yellow("warnings") : green("all good");
+  console.log(`  ${overall}  —  ${green(String(counts.pass))} pass · ${yellow(String(counts.warn))} warn · ${red(String(counts.fail))} fail  (${elapsed}ms)`);
+  console.log();
+
+  if (counts.warn > 0 || counts.fail > 0) {
+    console.log(`  Run ${cyan("infernoflow doctor --fix")} to auto-fix warnings`);
+    console.log();
+  }
+}
+
+// ── Entry ─────────────────────────────────────────────────────────────────────
+
+export async function doctorCommand(rawArgs) {
+  const args     = rawArgs.slice(1);
+  const jsonMode = args.includes("--json");
+  const fixMode  = args.includes("--fix");
+  const cwd      = process.cwd();
+  const start    = Date.now();
+
+  const results = [
+    check("Node.js version",   () => checkNodeVersion()),
+    check("infernoflow CLI",   () => checkCli()),
+    check("Git repository",    () => checkGitRepo(cwd)),
+    check("inferno/ directory",() => checkInfernoDir(cwd)),
+    check("Contract file",     () => checkContract(cwd)),
+    check("Scenarios",         () => checkScenarios(cwd)),
+    check("Changelog",         () => checkChangelog(cwd)),
+    check("CONTEXT.md",        () => checkContextMd(cwd)),
+    check("Git hooks",         () => checkGitHooks(cwd)),
+    check("MCP server",        () => checkMcp(cwd)),
+    check("AI providers",      () => checkAiProviders(cwd)),
+    check("Cloud sync",        () => checkCloudToken(cwd)),
+    await checkOllama().then(r => ({ label: "Ollama (local AI)", ...r })),
+  ];
+
+  const elapsed = Date.now() - start;
+
+  if (fixMode) {
+    const fixed = autoFix(results, cwd);
+    if (fixed.length) {
+      if (!jsonMode) {
+        console.log();
+        fixed.forEach(f => console.log(`  ${green("✔")} Fixed: ${f}`));
+        console.log();
+      }
+      // Re-run checks after fixing
+      return doctorCommand(["doctor", "--json"]);
+    }
+  }
+
+  if (jsonMode) {
+    const counts = { pass: 0, warn: 0, fail: 0, info: 0 };
+    results.forEach(r => counts[r.status] = (counts[r.status] || 0) + 1);
+    console.log(JSON.stringify({ ok: counts.fail === 0, counts, results, elapsed }));
+    return;
+  }
+
+  printReport(results, elapsed);
+
+  const hasFail = results.some(r => r.status === "fail");
+  if (hasFail) process.exit(1);
+}

package/dist/lib/commands/review.mjs

@@ -0,0 +1,238 @@
+/**
+ * infernoflow review
+ *
+ * AI-powered capability impact review for staged (or recent) git changes.
+ * Reads git diff, identifies which capabilities are affected, then asks
+ * your configured AI provider to write a capability impact summary.
+ *
+ * Usage:
+ *   infernoflow review              Review staged changes (git diff --staged)
+ *   infernoflow review --unstaged   Review all working-tree changes
+ *   infernoflow review --last       Review last commit (git diff HEAD~1)
+ *   infernoflow review --dry-run    Print the AI prompt only — no API call
+ *   infernoflow review --json       Machine-readable output
+ */
+
+import * as fs   from "node:fs";
+import * as path from "node:path";
+import { execSync } from "node:child_process";
+import { bold, cyan, gray, green, yellow, red } from "../ui/output.mjs";
+
+// ─── helpers ─────────────────────────────────────────────────────────────────
+
+function runGit(cmd, cwd) {
+  try {
+    return execSync(cmd, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+  } catch {
+    return "";
+  }
+}
+
+function loadJson(filePath) {
+  try { return JSON.parse(fs.readFileSync(filePath, "utf8")); }
+  catch { return null; }
+}
+
+/** Tokenise a string into lowercase words */
+function tokenise(str) {
+  return str
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .toLowerCase()
+    .split(/[\s_\-/.]+/)
+    .filter(t => t.length > 2);
+}
+
+/** Return capability IDs mentioned in or matched by the diff text */
+function findAffectedCaps(diff, capabilities) {
+  const diffLower = diff.toLowerCase();
+  const affected  = new Set();
+
+  for (const cap of capabilities) {
+    const tokens = [
+      ...tokenise(cap.id   || ""),
+      ...tokenise(cap.name || ""),
+      ...(cap.tags || []).flatMap(tokenise),
+    ];
+    // Direct ID mention (e.g. "auth-login" appears in diff)
+    if (diffLower.includes((cap.id || "").toLowerCase())) {
+      affected.add(cap.id);
+      continue;
+    }
+    // Token overlap — need ≥2 matching tokens to avoid false positives
+    const matches = tokens.filter(t => t.length > 3 && diffLower.includes(t));
+    if (matches.length >= 2) affected.add(cap.id);
+  }
+
+  return [...affected];
+}
+
+/** Trim diff to a reasonable size for the prompt */
+function trimDiff(diff, maxChars = 8000) {
+  if (diff.length <= maxChars) return diff;
+  const half = Math.floor(maxChars / 2);
+  return diff.slice(0, half) + "\n\n[… diff truncated …]\n\n" + diff.slice(-half);
+}
+
+// ─── prompt builder ───────────────────────────────────────────────────────────
+
+function buildPrompt(diff, affectedCaps, capabilities) {
+  const capDetails = capabilities
+    .filter(c => affectedCaps.includes(c.id))
+    .map(c => `  • ${c.id}: ${c.name}${c.description ? " — " + c.description : ""}`)
+    .join("\n");
+
+  const capList = affectedCaps.length > 0
+    ? `Affected capabilities detected:\n${capDetails}`
+    : "No specific capabilities were matched — review the entire contract.";
+
+  return `You are a senior software architect reviewing a code change for capability drift.
+
+${capList}
+
+Git diff:
+\`\`\`diff
+${trimDiff(diff)}
+\`\`\`
+
+Write a concise capability impact summary covering:
+1. Which capabilities are changed, added, or removed
+2. Whether the contract (capabilities.json) needs updating
+3. Any risks or side-effects (breaking changes, auth/security concerns, API contract violations)
+4. Recommended follow-up actions (one sentence each)
+
+Keep the tone professional and brief. Use bullet points only where genuinely helpful.
+Do NOT repeat the diff back.`;
+}
+
+// ─── reporters ────────────────────────────────────────────────────────────────
+
+function printReport(affectedCaps, summary, capabilities, source) {
+  console.log();
+  console.log(bold(cyan("  ✦ Capability Impact Review")));
+  console.log(gray(`  Source: ${source}`));
+  console.log();
+
+  if (affectedCaps.length === 0) {
+    console.log(yellow("  No capabilities directly matched — reviewing full diff."));
+  } else {
+    console.log(bold("  Affected capabilities:"));
+    for (const id of affectedCaps) {
+      const cap = capabilities.find(c => c.id === id);
+      console.log(`    ${green("▸")} ${id}${cap ? gray(" — " + cap.name) : ""}`);
+    }
+  }
+
+  console.log();
+  console.log(bold("  AI Impact Summary"));
+  console.log(gray("  ─────────────────────────────────────────────────────────────"));
+  // Indent each line
+  for (const line of summary.split("\n")) {
+    console.log("  " + line);
+  }
+  console.log();
+}
+
+// ─── entry point ─────────────────────────────────────────────────────────────
+
+export async function reviewCommand(rawArgs) {
+  const args      = rawArgs || [];
+  const dryRun    = args.includes("--dry-run");
+  const jsonMode  = args.includes("--json");
+  const unstaged  = args.includes("--unstaged");
+  const lastCommit = args.includes("--last");
+
+  const cwd        = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+
+  // Load capabilities
+  const capsPath = path.join(infernoDir, "capabilities.json");
+  if (!fs.existsSync(capsPath)) {
+    console.error(red("✗ inferno/capabilities.json not found — run `infernoflow init` first."));
+    process.exit(1);
+  }
+  const capabilities = loadJson(capsPath);
+  if (!Array.isArray(capabilities) || capabilities.length === 0) {
+    console.log(yellow("No capabilities found — nothing to review."));
+    process.exit(0);
+  }
+
+  // Get diff
+  let diffCmd, diffSource;
+  if (lastCommit) {
+    diffCmd    = "git diff HEAD~1";
+    diffSource = "last commit (HEAD~1)";
+  } else if (unstaged) {
+    diffCmd    = "git diff";
+    diffSource = "unstaged changes";
+  } else {
+    diffCmd    = "git diff --staged";
+    diffSource = "staged changes";
+  }
+
+  let diff = runGit(diffCmd, cwd);
+
+  // Fallback: if staged is empty, try unstaged
+  if (!diff && !lastCommit && !unstaged) {
+    diff       = runGit("git diff", cwd);
+    diffSource = "unstaged changes (no staged changes found)";
+  }
+
+  if (!diff) {
+    console.log(yellow("No changes found to review."));
+    console.log(gray("  Tip: stage some files first (`git add -p`) or use --last / --unstaged"));
+    process.exit(0);
+  }
+
+  // Identify affected capabilities
+  const affectedCaps = findAffectedCaps(diff, capabilities);
+
+  // Build prompt
+  const prompt = buildPrompt(diff, affectedCaps, capabilities);
+
+  if (dryRun) {
+    console.log(gray("── Prompt (--dry-run) ────────────────────────────────────────────────"));
+    console.log(prompt);
+    process.exit(0);
+  }
+
+  // Call AI
+  if (!jsonMode) process.stdout.write(gray("  Calling AI provider…"));
+
+  let aiResult = null;
+  try {
+    const { callAI } = await import("../ai/providerRouter.mjs");
+    aiResult = await callAI(prompt, { cwd, maxTokens: 600 });
+  } catch (e) {
+    // provider router import failure is non-fatal — we degrade gracefully
+  }
+
+  if (!jsonMode) process.stdout.write("\r" + " ".repeat(30) + "\r");
+
+  if (!aiResult) {
+    console.log();
+    console.log(yellow("  ⚠  No AI provider available."));
+    console.log(gray("  Set ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, or OPENROUTER_API_KEY,"));
+    console.log(gray("  or run Ollama locally. See `infernoflow doctor` for details."));
+    console.log();
+    console.log(bold("  Affected capabilities (unanswered):"));
+    for (const id of affectedCaps) console.log(`    ▸ ${id}`);
+    console.log();
+    process.exit(0);
+  }
+
+  const summary = aiResult.text || "(empty response)";
+
+  if (jsonMode) {
+    console.log(JSON.stringify({
+      source: diffSource,
+      provider: aiResult.provider,
+      model: aiResult.model,
+      affectedCapabilities: affectedCaps,
+      summary,
+    }, null, 2));
+  } else {
+    printReport(affectedCaps, summary, capabilities, diffSource);
+    console.log(gray(`  Provider: ${aiResult.provider}  Model: ${aiResult.model}`));
+    console.log();
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infernoflow",
-  "version": "0.21.0",
+  "version": "0.22.1",
   "description": "The forge for liquid code - keep capabilities, contracts, and docs in sync.",
   "type": "module",
   "bin": {