infernoflow 0.29.0 → 0.30.0

package/dist/bin/infernoflow.mjs

@@ -63,6 +63,8 @@ const COMMAND_DESCRIPTIONS = {
   impact:     "Blast radius analysis — see every cap, scenario, and risk level affected before you change anything",
   scaffold:   "Generate a new capability — source skeleton, contract registration, and placeholder scenario in one command",
   explain:    "AI narrative about a capability — what it does, why it exists, what's risky, and what to test",
+  test:       "Run registered scenarios for a capability — auto-generates a smoke harness if no test runner is configured",
+  ai:         "Manage AI providers — setup, status, test connection (subcommands: setup | status | test | clear)",
 };
 
 const COMMAND_HANDLERS = {
@@ -119,6 +121,8 @@ const COMMAND_HANDLERS = {
   impact:    async (args) => (await import("../lib/commands/impact.mjs")).impactCommand(args),
   scaffold:  async (args) => (await import("../lib/commands/scaffold.mjs")).scaffoldCommand(args),
   explain:   async (args) => (await import("../lib/commands/explain.mjs")).explainCommand(args),
+  test:      async (args) => (await import("../lib/commands/test.mjs")).testCommand(args),
+  ai:        async (args) => (await import("../lib/commands/ai.mjs")).aiCommand(args),
 };
 
 function formatCommandsHelp() {
@@ -422,6 +426,22 @@ ${formatCommandsHelp()}
     --dry-run                            Print the AI prompt only — no API call made
     --json                               Machine-readable output (narrative, stability, scenarios)
 
+  ${bold("test options:")}
+    infernoflow test                     Run all caps that have registered scenarios
+    infernoflow test <cap-id>            Run scenarios for a specific capability
+    infernoflow test --all               Run every capability (including those without scenarios)
+    --generate                           Print generated ad-hoc test file without running
+    --bail                               Stop on first failure
+    --verbose, -v                        Show runner output for each scenario
+    --json                               Machine-readable output (passed/failed/skipped counts)
+
+  ${bold("ai options:")}
+    infernoflow ai setup                 Interactive wizard — pick provider, enter API key, verify
+    infernoflow ai status                Show all providers and which are configured
+    infernoflow ai test [provider]       Send a test prompt and verify the connection
+    infernoflow ai clear <provider>      Remove a provider's config from integrations.json
+    Supported providers: anthropic  openai  gemini  openrouter  ollama
+
   ${bold("Machine output:")}
     ${gray("status --json")}
     ${gray("check --json")}

package/dist/lib/commands/ai.mjs

@@ -0,0 +1,370 @@
+/**
+ * infernoflow ai
+ *
+ * Manage AI provider configuration for infernoflow commands
+ * (explain, why, review, changelog, etc.)
+ *
+ * Subcommands:
+ *   infernoflow ai setup               Interactive guided setup
+ *   infernoflow ai status              Show configured providers and which is active
+ *   infernoflow ai test [provider]     Send a test prompt and show response
+ *   infernoflow ai clear [provider]    Remove a provider's API key from config
+ *
+ * Config is stored in inferno/integrations.json (project-scoped).
+ * API keys can also come from environment variables (checked first).
+ *
+ * Supported providers:
+ *   anthropic   ANTHROPIC_API_KEY   claude-sonnet-4-6
+ *   openai      OPENAI_API_KEY      gpt-4o
+ *   gemini      GOOGLE_AI_API_KEY   gemini-2.0-flash
+ *   openrouter  OPENROUTER_API_KEY  (any model)
+ *   ollama      (local, no key)     llama3.2
+ */
+
+import * as fs       from "node:fs";
+import * as path     from "node:path";
+import * as https    from "node:https";
+import * as http     from "node:http";
+import * as readline from "node:readline";
+import { bold, cyan, gray, green, yellow, red } from "../ui/output.mjs";
+
+// ── config helpers ────────────────────────────────────────────────────────────
+
+function infernoDir(cwd) { return path.join(cwd, "inferno"); }
+
+function loadConfig(cwd) {
+  const p = path.join(infernoDir(cwd), "integrations.json");
+  if (!fs.existsSync(p)) return {};
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return {}; }
+}
+
+function saveConfig(cwd, config) {
+  const dir = infernoDir(cwd);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, "integrations.json"), JSON.stringify(config, null, 2) + "\n");
+}
+
+// ── provider definitions ──────────────────────────────────────────────────────
+
+const PROVIDERS = [
+  {
+    id:      "anthropic",
+    name:    "Anthropic (Claude)",
+    envKey:  "ANTHROPIC_API_KEY",
+    models:  ["claude-sonnet-4-6", "claude-opus-4-6", "claude-haiku-4-5-20251001"],
+    default: "claude-sonnet-4-6",
+    keyHint: "sk-ant-api03-…",
+    docsUrl: "https://console.anthropic.com/settings/keys",
+  },
+  {
+    id:      "openai",
+    name:    "OpenAI (GPT)",
+    envKey:  "OPENAI_API_KEY",
+    models:  ["gpt-4o", "gpt-4o-mini", "gpt-4-turbo"],
+    default: "gpt-4o",
+    keyHint: "sk-…",
+    docsUrl: "https://platform.openai.com/api-keys",
+  },
+  {
+    id:      "gemini",
+    name:    "Google Gemini",
+    envKey:  "GOOGLE_AI_API_KEY",
+    models:  ["gemini-2.0-flash", "gemini-1.5-pro", "gemini-1.5-flash"],
+    default: "gemini-2.0-flash",
+    keyHint: "AIza…",
+    docsUrl: "https://aistudio.google.com/app/apikey",
+  },
+  {
+    id:      "openrouter",
+    name:    "OpenRouter",
+    envKey:  "OPENROUTER_API_KEY",
+    models:  ["anthropic/claude-sonnet-4-6", "openai/gpt-4o", "meta-llama/llama-3.1-8b-instruct:free"],
+    default: "anthropic/claude-sonnet-4-6",
+    keyHint: "sk-or-…",
+    docsUrl: "https://openrouter.ai/keys",
+  },
+  {
+    id:      "ollama",
+    name:    "Ollama (local)",
+    envKey:  null,
+    models:  ["llama3.2", "mistral", "codellama", "phi3"],
+    default: "llama3.2",
+    keyHint: null,
+    docsUrl: "https://ollama.com",
+  },
+];
+
+// ── HTTP probe ────────────────────────────────────────────────────────────────
+
+function httpGet(url) {
+  return new Promise((resolve) => {
+    const parsed = new URL(url);
+    const lib    = parsed.protocol === "https:" ? https : http;
+    const req    = lib.request({ hostname: parsed.hostname, port: parsed.port || (parsed.protocol === "https:" ? 443 : 80), path: parsed.pathname + (parsed.search || ""), method: "GET", timeout: 5000 }, (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", () => resolve(null));
+    req.on("timeout", () => { req.destroy(); resolve(null); });
+    req.end();
+  });
+}
+
+// ── provider status check ─────────────────────────────────────────────────────
+
+async function checkProviderStatus(providerId, config) {
+  const envMap = {
+    anthropic:  process.env.ANTHROPIC_API_KEY,
+    openai:     process.env.OPENAI_API_KEY,
+    gemini:     process.env.GOOGLE_AI_API_KEY || process.env.GEMINI_API_KEY,
+    openrouter: process.env.OPENROUTER_API_KEY,
+  };
+
+  const fromEnv    = envMap[providerId];
+  const fromConfig = config[providerId]?.apiKey;
+  const key        = fromEnv || fromConfig;
+  const source     = fromEnv ? "env" : fromConfig ? "integrations.json" : null;
+  const model      = config[providerId]?.model || PROVIDERS.find(p => p.id === providerId)?.default;
+
+  if (providerId === "ollama") {
+    // Check if Ollama is running
+    const probe = await httpGet("http://localhost:11434/api/tags").catch(() => null);
+    if (probe?.status === 200) {
+      const models = probe.body?.models?.map(m => m.name) || [];
+      return { configured: true, source: "local", model: config.ollama?.model || "llama3.2", available: true, models };
+    }
+    return { configured: false, source: null, model: null, available: false };
+  }
+
+  return { configured: !!key, source, model, available: null, masked: key ? key.slice(0, 8) + "…" : null };
+}
+
+// ── ai test prompt ────────────────────────────────────────────────────────────
+
+async function testProvider(providerId, config, cwd) {
+  try {
+    const { callAI } = await import("../ai/providerRouter.mjs");
+    const testPrompt = `Reply with exactly: "infernoflow AI test OK — ${providerId}"`;
+    const result = await callAI(testPrompt, cwd, providerId);
+    return result;
+  } catch {
+    return null;
+  }
+}
+
+// ── readline helper ───────────────────────────────────────────────────────────
+
+function prompt(rl, question) {
+  return new Promise(resolve => rl.question(question, resolve));
+}
+
+// ── subcommands ───────────────────────────────────────────────────────────────
+
+async function cmdStatus(cwd) {
+  const config = loadConfig(cwd);
+
+  console.log();
+  console.log(`  ${bold("infernoflow ai")}  ${gray("— provider status")}`);
+  console.log();
+
+  let anyConfigured = false;
+
+  for (const p of PROVIDERS) {
+    const status = await checkProviderStatus(p.id, config);
+    if (status.configured) anyConfigured = true;
+
+    const icon  = status.configured ? green("✓") : gray("○");
+    const label = bold(p.name.padEnd(22));
+    const info  = status.configured
+      ? `${green("configured")}  ${gray(status.source)}  ${gray("model: " + status.model)}${status.masked ? "  " + gray(status.masked) : ""}`
+      : gray("not configured");
+    console.log(`  ${icon}  ${label}  ${info}`);
+  }
+
+  console.log();
+
+  if (!anyConfigured) {
+    console.log(`  ${yellow("No AI providers configured.")}  Run: ${cyan("infernoflow ai setup")}`);
+    console.log(`  ${gray("Without a provider, explain/why/review use structural fallbacks.")}`);
+  } else {
+    console.log(`  ${gray("Run")} ${cyan("infernoflow ai test")} ${gray("to verify the active provider.")}`);
+  }
+  console.log();
+}
+
+async function cmdSetup(cwd) {
+  const config = loadConfig(cwd);
+
+  console.log();
+  console.log(`  ${bold("🔥 infernoflow ai setup")}`);
+  console.log(`  ${gray("Connect an AI provider for explain, why, review, and changelog.")}`);
+  console.log();
+  console.log(`  Providers: ${PROVIDERS.map(p => bold(p.id)).join("  ")}`);
+  console.log();
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  try {
+    // Pick provider
+    const providerInput = await prompt(rl, `  Provider [anthropic]: `);
+    const providerId    = providerInput.trim().toLowerCase() || "anthropic";
+    const provider      = PROVIDERS.find(p => p.id === providerId);
+
+    if (!provider) {
+      console.log(red(`  Unknown provider "${providerId}". Options: ${PROVIDERS.map(p => p.id).join(", ")}`));
+      return;
+    }
+
+    console.log();
+    console.log(`  ${bold(provider.name)}`);
+
+    if (provider.docsUrl) {
+      console.log(`  ${gray("Get API key:")} ${cyan(provider.docsUrl)}`);
+    }
+
+    if (providerId === "ollama") {
+      // Ollama — no key, just model + host
+      const hostInput  = await prompt(rl, `  Ollama host [http://localhost:11434]: `);
+      const modelInput = await prompt(rl, `  Model [${provider.default}]: `);
+
+      config.ollama = {
+        host:  hostInput.trim()  || "http://localhost:11434",
+        model: modelInput.trim() || provider.default,
+      };
+      saveConfig(cwd, config);
+
+      console.log();
+      console.log(`  ${green("✓")} Ollama configured. Testing connection…`);
+      const probe = await httpGet(`${config.ollama.host}/api/tags`).catch(() => null);
+      if (probe?.status === 200) {
+        console.log(`  ${green("✓")} Ollama is running. You're all set.`);
+      } else {
+        console.log(`  ${yellow("⚠")}  Could not reach Ollama. Make sure it's running: ${cyan("ollama serve")}`);
+      }
+    } else {
+      // API key provider
+      const existingKey = process.env[provider.envKey] || config[providerId]?.apiKey;
+      const keyHint     = existingKey ? `[${existingKey.slice(0, 8)}… (existing)] ` : `[${provider.keyHint}] `;
+      const keyInput    = await prompt(rl, `  API key ${keyHint}: `);
+      const apiKey      = keyInput.trim() || existingKey;
+
+      if (!apiKey) {
+        console.log(red("  No API key provided. Exiting."));
+        return;
+      }
+
+      const modelInput = await prompt(rl, `  Model [${provider.default}]: `);
+      const model      = modelInput.trim() || provider.default;
+
+      config[providerId] = { apiKey, model };
+      saveConfig(cwd, config);
+
+      console.log();
+      console.log(`  ${green("✓")} Saved to inferno/integrations.json`);
+      console.log();
+      process.stdout.write(`  Testing connection…  `);
+
+      const result = await testProvider(providerId, config, cwd);
+      if (result?.text) {
+        console.log(green("OK"));
+        console.log(`  ${gray(result.text.trim().slice(0, 80))}`);
+      } else {
+        console.log(yellow("no response"));
+        console.log(`  ${yellow("⚠")}  Could not get a test response. Check your API key.`);
+      }
+    }
+
+    console.log();
+    console.log(`  ${green("✓")} ${bold(provider.name)} is ready.`);
+    console.log(`  ${gray("Commands that now use AI:")} explain  why  review  changelog`);
+    console.log();
+
+    // gitignore reminder
+    const gitignorePath = path.join(cwd, ".gitignore");
+    if (fs.existsSync(gitignorePath)) {
+      const content = fs.readFileSync(gitignorePath, "utf8");
+      if (!content.includes("integrations.json")) {
+        console.log(`  ${yellow("⚠")}  Your API key is in inferno/integrations.json.`);
+        console.log(`     ${gray("Add")} ${cyan("inferno/integrations.json")} ${gray("to .gitignore to avoid committing it.")}`);
+        console.log();
+      }
+    }
+
+  } finally {
+    rl.close();
+  }
+}
+
+async function cmdTest(args, cwd) {
+  const config     = loadConfig(cwd);
+  const providerId = args.find(a => !a.startsWith("--")) || null;
+
+  console.log();
+  console.log(`  ${bold("infernoflow ai test")}`);
+  console.log();
+
+  const toTest = providerId
+    ? PROVIDERS.filter(p => p.id === providerId)
+    : PROVIDERS;
+
+  for (const p of toTest) {
+    const status = await checkProviderStatus(p.id, config);
+    if (!status.configured) {
+      console.log(`  ${gray("○")}  ${bold(p.name.padEnd(22))}  ${gray("not configured — skipping")}`);
+      continue;
+    }
+
+    process.stdout.write(`  ${yellow("…")}  ${bold(p.name.padEnd(22))}  testing…  `);
+    const result = await testProvider(p.id, config, cwd);
+    if (result?.text) {
+      console.log(green("OK") + gray(` (${result.model || p.id})`));
+      console.log(`     ${gray(result.text.trim().slice(0, 80))}`);
+    } else {
+      console.log(red("FAIL"));
+      console.log(`     ${red("No response — check API key or model name")}`);
+    }
+  }
+
+  console.log();
+}
+
+async function cmdClear(args, cwd) {
+  const config     = loadConfig(cwd);
+  const providerId = args.find(a => !a.startsWith("--"));
+
+  if (!providerId) {
+    console.error(red("✗ Usage: infernoflow ai clear <provider>"));
+    console.error(gray("  Example: infernoflow ai clear openai"));
+    process.exit(1);
+  }
+
+  if (!config[providerId]) {
+    console.log(gray(`  No config found for "${providerId}"`));
+    return;
+  }
+
+  delete config[providerId];
+  saveConfig(cwd, config);
+  console.log(green(`  ✓ Cleared config for ${providerId}`));
+}
+
+// ── entry point ───────────────────────────────────────────────────────────────
+
+export async function aiCommand(rawArgs) {
+  const args    = (rawArgs || []).slice(1);
+  const sub     = args.find(a => !a.startsWith("--")) || "status";
+  const subArgs = args.filter(a => a !== sub);
+  const cwd     = process.cwd();
+
+  switch (sub) {
+    case "setup":   return cmdSetup(cwd);
+    case "status":  return cmdStatus(cwd);
+    case "test":    return cmdTest(subArgs, cwd);
+    case "clear":   return cmdClear(subArgs, cwd);
+    default:
+      console.error(red(`✗ Unknown subcommand: "${sub}"`));
+      console.error(gray("  Usage: infernoflow ai <setup|status|test|clear>"));
+      process.exit(1);
+  }
+}

package/dist/lib/commands/test.mjs

@@ -0,0 +1,363 @@
+/**
+ * infernoflow test
+ *
+ * Run registered scenarios for a capability and report pass/fail.
+ * When no test runner is configured, generates a minimal ad-hoc harness
+ * from the scenario + source file and runs it with Node.
+ *
+ * Usage:
+ *   infernoflow test                          Run all caps with scenarios
+ *   infernoflow test user-auth                Run scenarios for one cap
+ *   infernoflow test user-auth payment-process  Run multiple caps
+ *   infernoflow test --all                    Run every cap (including no-scenario)
+ *   infernoflow test --generate user-auth     Print generated test file, don't run
+ *   infernoflow test --json                   Machine-readable output
+ *   infernoflow test --bail                   Stop on first failure
+ */
+
+import * as fs      from "node:fs";
+import * as path    from "node:path";
+import * as os      from "node:os";
+import { execSync, spawnSync } from "node:child_process";
+import { bold, cyan, gray, green, yellow, red } from "../ui/output.mjs";
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function loadJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); }
+  catch { return null; }
+}
+
+function stability(cap) { return cap?.stability || "experimental"; }
+
+const PASS_ICON = green("✓");
+const FAIL_ICON = red("✗");
+const SKIP_ICON = gray("○");
+
+// ── scenario loader ───────────────────────────────────────────────────────────
+
+function loadScenarios(capId, infernoDir) {
+  const dir = path.join(infernoDir, "scenarios");
+  if (!fs.existsSync(dir)) return [];
+  const found = [];
+  for (const f of fs.readdirSync(dir)) {
+    if (!f.endsWith(".json")) continue;
+    try {
+      const s = JSON.parse(fs.readFileSync(path.join(dir, f), "utf8"));
+      const covered = s.capabilitiesCovered || s.capabilities || [];
+      if (covered.some(c => c.toLowerCase() === capId.toLowerCase())) {
+        found.push({ ...s, _file: f });
+      }
+    } catch {}
+  }
+  return found;
+}
+
+// ── test runner detection ─────────────────────────────────────────────────────
+
+function detectTestRunner(cwd) {
+  const pkg = loadJson(path.join(cwd, "package.json"));
+  if (!pkg) return null;
+
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  if (deps?.vitest)  return "vitest";
+  if (deps?.jest)    return "jest";
+  if (deps?.mocha)   return "mocha";
+  if (pkg.scripts?.test && !pkg.scripts.test.includes("no test")) {
+    return { custom: pkg.scripts.test };
+  }
+  return null;
+}
+
+// ── ad-hoc test generator ─────────────────────────────────────────────────────
+
+function generateAdHocTest(capId, cap, scenario, scanEntry) {
+  const name    = cap.name || cap.title || capId;
+  const desc    = cap.description || "(no description)";
+  const files   = scanEntry?.codeAnalysis?.sourceFiles || [];
+  const fns     = scanEntry?.codeAnalysis?.functions   || [];
+  const steps   = scenario?.steps   || scenario?.actions || [];
+  const expects = scenario?.expects || scenario?.assertions || [];
+
+  const lines = [
+    `// Auto-generated smoke test for: ${capId}`,
+    `// Generated by infernoflow test — edit as needed`,
+    ``,
+    `import { strict as assert } from "node:assert";`,
+    ``,
+    `// Capability: ${name}`,
+    `// ${desc}`,
+    ``,
+  ];
+
+  // Import source if we know the file
+  if (files.length) {
+    lines.push(`// Source: ${files[0]}`);
+    lines.push(`// import { ${fns[0] || capId} } from "./${path.basename(files[0])}";`);
+    lines.push(``);
+  }
+
+  lines.push(`async function run() {`);
+  lines.push(`  const results = [];`);
+  lines.push(``);
+
+  // Generate test cases from scenario steps
+  if (steps.length) {
+    steps.forEach((step, i) => {
+      const desc = typeof step === "string" ? step : (step.action || step.description || `step ${i + 1}`);
+      lines.push(`  // Step ${i + 1}: ${desc}`);
+      lines.push(`  results.push({ step: ${JSON.stringify(desc)}, status: "manual" });`);
+      lines.push(``);
+    });
+  } else {
+    lines.push(`  // No explicit steps — running basic smoke test`);
+    lines.push(`  results.push({ step: "capability exists", status: "pass" });`);
+    lines.push(``);
+  }
+
+  // Add assertion checks
+  if (expects.length) {
+    expects.forEach((exp, i) => {
+      const desc = typeof exp === "string" ? exp : (exp.condition || exp.description || `assertion ${i + 1}`);
+      lines.push(`  // Assert: ${desc}`);
+      lines.push(`  // assert(condition, ${JSON.stringify(desc)});`);
+    });
+    lines.push(``);
+  }
+
+  lines.push(`  return results;`);
+  lines.push(`}`);
+  lines.push(``);
+  lines.push(`run().then(results => {`);
+  lines.push(`  const failed = results.filter(r => r.status === "fail");`);
+  lines.push(`  results.forEach(r => {`);
+  lines.push(`    const icon = r.status === "pass" ? "✓" : r.status === "fail" ? "✗" : "○";`);
+  lines.push(`    console.log(\`  \${icon}  \${r.step}\`);`);
+  lines.push(`  });`);
+  lines.push(`  if (failed.length) { console.error(\`\\n  \${failed.length} failed\`); process.exit(1); }`);
+  lines.push(`  else console.log(\`\\n  All steps passed\`);`);
+  lines.push(`}).catch(err => { console.error(err); process.exit(1); });`);
+
+  return lines.join("\n");
+}
+
+// ── run a single scenario ─────────────────────────────────────────────────────
+
+function runScenario(capId, cap, scenario, scanEntry, cwd) {
+  const scenarioId = scenario?.scenarioId || scenario?.id || scenario?._file?.replace(".json", "") || "unnamed";
+  const runner     = detectTestRunner(cwd);
+
+  // If there are testFiles registered in the scenario, run those
+  const testFiles = scenario?.testFiles || scenario?.testFile ? [scenario.testFile].flat().filter(Boolean) : [];
+  if (testFiles.length) {
+    for (const tf of testFiles) {
+      const absPath = path.resolve(cwd, tf);
+      if (!fs.existsSync(absPath)) {
+        return { scenarioId, status: "skip", reason: `test file not found: ${tf}` };
+      }
+    }
+
+    // Run with detected test runner
+    if (runner && typeof runner === "string") {
+      const cmd = runner === "vitest"
+        ? `npx vitest run ${testFiles.join(" ")} --reporter verbose`
+        : runner === "jest"
+        ? `npx jest ${testFiles.join(" ")} --no-coverage`
+        : runner === "mocha"
+        ? `npx mocha ${testFiles.join(" ")}`
+        : null;
+
+      if (cmd) {
+        const result = spawnSync(cmd, { shell: true, cwd, encoding: "utf8", timeout: 60_000 });
+        const passed = result.status === 0;
+        return {
+          scenarioId,
+          status:   passed ? "pass" : "fail",
+          output:   (result.stdout || "") + (result.stderr || ""),
+          runner,
+        };
+      }
+    }
+
+    // Custom script runner
+    if (runner?.custom) {
+      const result = spawnSync(runner.custom, { shell: true, cwd, encoding: "utf8", timeout: 60_000 });
+      return {
+        scenarioId,
+        status: result.status === 0 ? "pass" : "fail",
+        output: (result.stdout || "") + (result.stderr || ""),
+        runner: "npm test",
+      };
+    }
+  }
+
+  // No test files — generate and run ad-hoc test
+  const testSrc = generateAdHocTest(capId, cap, scenario, scanEntry);
+  const tmpFile = path.join(os.tmpdir(), `infernoflow-test-${capId}-${Date.now()}.mjs`);
+
+  try {
+    fs.writeFileSync(tmpFile, testSrc);
+    const result = spawnSync(process.execPath, ["--input-type=module", tmpFile], {
+      cwd,
+      encoding: "utf8",
+      timeout:  30_000,
+    });
+    const passed = result.status === 0;
+    return {
+      scenarioId,
+      status:  passed ? "pass" : "fail",
+      output:  (result.stdout || "") + (result.stderr || ""),
+      runner:  "ad-hoc",
+      generated: true,
+    };
+  } finally {
+    try { fs.unlinkSync(tmpFile); } catch {}
+  }
+}
+
+// ── print result ──────────────────────────────────────────────────────────────
+
+function printCapResult(capId, cap, results, verbose) {
+  const level  = stability(cap);
+  const badge  = level === "frozen" ? red("frozen") : level === "stable" ? yellow("stable") : gray("experimental");
+  const total  = results.length;
+  const passed = results.filter(r => r.status === "pass").length;
+  const failed = results.filter(r => r.status === "fail").length;
+  const skipped = results.filter(r => r.status === "skip").length;
+
+  const statusIcon = failed > 0 ? red("✗") : passed > 0 ? green("✓") : gray("○");
+  console.log(`  ${statusIcon}  ${bold(capId)}  ${gray(`[${badge}]`)}`);
+
+  for (const r of results) {
+    const icon = r.status === "pass" ? PASS_ICON : r.status === "fail" ? FAIL_ICON : SKIP_ICON;
+    const note = r.generated ? gray(" (generated)") : r.runner ? gray(` (${r.runner})`) : "";
+    console.log(`       ${icon}  ${gray(r.scenarioId)}${note}`);
+    if (r.reason) console.log(`          ${gray(r.reason)}`);
+    if (verbose && r.output) {
+      const trimmed = r.output.trim().split("\n").slice(0, 10).join("\n");
+      console.log(trimmed.split("\n").map(l => `          ${gray(l)}`).join("\n"));
+    }
+  }
+
+  return { total, passed, failed, skipped };
+}
+
+// ── entry point ───────────────────────────────────────────────────────────────
+
+export async function testCommand(rawArgs) {
+  const args       = (rawArgs || []).slice(1);
+  const jsonMode   = args.includes("--json");
+  const bail       = args.includes("--bail");
+  const generateMode = args.includes("--generate");
+  const runAll     = args.includes("--all");
+  const verbose    = args.includes("--verbose") || args.includes("-v");
+
+  const capArgs    = args.filter(a => !a.startsWith("--") && a !== "-v");
+
+  const cwd        = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+
+  if (!fs.existsSync(infernoDir)) {
+    if (!jsonMode) console.error(red("✗ inferno/ not found. Run: infernoflow init"));
+    process.exit(1);
+  }
+
+  // Load capabilities
+  let allCaps = [];
+  const rawCaps = loadJson(path.join(infernoDir, "capabilities.json"));
+  if (rawCaps) allCaps = Array.isArray(rawCaps) ? rawCaps : (rawCaps.capabilities || []);
+
+  const scanData = loadJson(path.join(infernoDir, "scan.json"));
+
+  // Determine which caps to test
+  let targetCaps;
+  if (capArgs.length) {
+    targetCaps = capArgs.map(id => {
+      const cap = allCaps.find(c => c.id === id);
+      if (!cap) {
+        if (!jsonMode) console.error(red(`✗ Capability "${id}" not found in capabilities.json`));
+        process.exit(1);
+      }
+      return cap;
+    });
+  } else if (runAll) {
+    targetCaps = allCaps;
+  } else {
+    // Default: caps that have scenarios registered
+    targetCaps = allCaps.filter(cap => loadScenarios(cap.id, infernoDir).length > 0);
+    if (!targetCaps.length) {
+      if (!jsonMode) {
+        console.log();
+        console.log(`  ${gray("No scenarios registered. Use --all to test all capabilities, or")} `);
+        console.log(`  ${gray("add scenarios to inferno/scenarios/ first.")}`);
+        console.log();
+      }
+      process.exit(0);
+    }
+  }
+
+  if (!jsonMode) {
+    console.log();
+    console.log(`  ${bold("🧪 infernoflow test")}`);
+    console.log();
+  }
+
+  // --generate mode: print generated test for first cap
+  if (generateMode) {
+    const cap     = targetCaps[0];
+    const scenarios = loadScenarios(cap.id, infernoDir);
+    const scenario  = scenarios[0] || {};
+    const scanEntry = scanData?.capabilities?.find(c => c.id === cap.id);
+    const src = generateAdHocTest(cap.id, cap, scenario, scanEntry);
+    console.log(src);
+    return;
+  }
+
+  // Run tests
+  const summary = { total: 0, passed: 0, failed: 0, skipped: 0, caps: [] };
+  let bailed = false;
+
+  for (const cap of targetCaps) {
+    const scenarios = loadScenarios(cap.id, infernoDir);
+    const scanEntry = scanData?.capabilities?.find(c => c.id === cap.id);
+
+    let capResults = [];
+
+    if (!scenarios.length) {
+      capResults = [{ scenarioId: "(no scenarios)", status: "skip", reason: "register scenarios in inferno/scenarios/" }];
+    } else {
+      for (const scenario of scenarios) {
+        const r = runScenario(cap.id, cap, scenario, scanEntry, cwd);
+        capResults.push(r);
+        if (bail && r.status === "fail") { bailed = true; break; }
+      }
+    }
+
+    const counts = printCapResult(cap.id, cap, capResults, verbose);
+    summary.total   += counts.total;
+    summary.passed  += counts.passed;
+    summary.failed  += counts.failed;
+    summary.skipped += counts.skipped;
+    summary.caps.push({ id: cap.id, stability: stability(cap), results: capResults });
+
+    if (bailed) break;
+  }
+
+  if (!jsonMode) {
+    console.log();
+    const statusColor = summary.failed > 0 ? red : summary.passed > 0 ? green : gray;
+    console.log(`  ${statusColor(bold(String(summary.passed)))} passed  ${summary.failed > 0 ? red(bold(String(summary.failed))) : gray("0")} failed  ${gray(String(summary.skipped))} skipped`);
+    if (bailed) console.log(`  ${yellow("(bailed on first failure)")}`);
+    console.log();
+    if (!summary.failed) {
+      console.log(gray("  ── infernoflow test complete"));
+    }
+    console.log();
+  }
+
+  if (jsonMode) {
+    console.log(JSON.stringify(summary, null, 2));
+  }
+
+  process.exit(summary.failed > 0 ? 1 : 0);
+}

package/package.json

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