infernoflow 0.27.0 → 0.29.0

package/dist/bin/infernoflow.mjs

@@ -61,6 +61,8 @@ const COMMAND_DESCRIPTIONS = {
   thaw:       "Reset a capability to experimental (liquid) — free to evolve",
   why:        "Given a file or function name — show which capability it serves, scenarios, stability, and git history",
   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",
 };
 
 const COMMAND_HANDLERS = {
@@ -115,6 +117,8 @@ const COMMAND_HANDLERS = {
   thaw:      async (args) => (await import("../lib/commands/stability.mjs")).thawCommand(args),
   why:       async (args) => (await import("../lib/commands/why.mjs")).whyCommand(args),
   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),
 };
 
 function formatCommandsHelp() {
@@ -405,6 +409,19 @@ ${formatCommandsHelp()}
     --check                              Exit 1 if risk level is HIGH or CRITICAL (CI gate)
     --json                               Machine-readable output
 
+  ${bold("scaffold options:")}
+    infernoflow scaffold <cap-id>        Generate a new capability skeleton
+    --dir <path>                         Output directory for the source file (default: auto-detected)
+    --lang ts|js|py|go                   Language override (default: auto-detected from project)
+    --description "..."                  Capability description to embed in the file
+    --dry-run                            Preview what would be generated without writing files
+    --json                               Machine-readable output including generated code
+
+  ${bold("explain options:")}
+    infernoflow explain <cap-id>         AI narrative: what it does, risk, what to test
+    --dry-run                            Print the AI prompt only — no API call made
+    --json                               Machine-readable output (narrative, stability, scenarios)
+
   ${bold("Machine output:")}
     ${gray("status --json")}
     ${gray("check --json")}

package/dist/lib/commands/explain.mjs

@@ -0,0 +1,373 @@
+/**
+ * infernoflow explain
+ *
+ * AI-generated narrative about a capability — what it does, why it exists,
+ * what's risky about it, and what to test before changing it.
+ *
+ * Synthesises: stability level, git history, scenarios, callers, services,
+ * source files — then calls the AI provider for a 3-5 sentence human narrative.
+ *
+ * Usage:
+ *   infernoflow explain user-auth
+ *   infernoflow explain payment-process --dry-run    (print prompt only)
+ *   infernoflow explain user-auth --json
+ */
+
+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 loadJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); }
+  catch { return null; }
+}
+
+function runGit(cmd, cwd) {
+  try {
+    return execSync(cmd, { cwd, encoding: "utf8", stdio: ["pipe","pipe","pipe"] }).trim();
+  } catch { return ""; }
+}
+
+const LEVEL_ICON  = { frozen: "🧊", stable: "〰️ ", experimental: "🌊" };
+const LEVEL_COLOR = { frozen: red, stable: yellow, experimental: green };
+
+function stability(cap) { return cap?.stability || "experimental"; }
+
+// ── git helpers ───────────────────────────────────────────────────────────────
+
+function getFirstCommit(filePath, cwd) {
+  if (!filePath) return null;
+  const rel = path.relative(cwd, path.resolve(cwd, filePath));
+  const log = runGit(
+    `git log --follow --format="%h|%aI|%ae|%s" -- ${JSON.stringify(rel)}`, cwd
+  );
+  if (!log) return null;
+  const lines = log.split("\n").filter(Boolean);
+  if (!lines.length) return null;
+  const [hash, date, author, ...subjectParts] = lines[lines.length - 1].split("|");
+  return {
+    hash:    hash?.trim(),
+    date:    date?.trim() ? new Date(date.trim()).toLocaleDateString() : "",
+    author:  author?.trim(),
+    subject: subjectParts.join("|").trim(),
+  };
+}
+
+function getRecentHistory(filePath, cwd, limit = 5) {
+  if (!filePath) return [];
+  const rel = path.relative(cwd, path.resolve(cwd, filePath));
+  const log = runGit(
+    `git log --follow --format="%h|%aI|%ae|%s" -${limit} -- ${JSON.stringify(rel)}`, cwd
+  );
+  if (!log) return [];
+  return log.split("\n").filter(Boolean).map(line => {
+    const [hash, date, author, ...subjectParts] = line.split("|");
+    return {
+      hash:    hash?.trim(),
+      date:    date?.trim() ? new Date(date.trim()).toLocaleDateString() : "",
+      author:  author?.trim(),
+      subject: subjectParts.join("|").trim(),
+    };
+  });
+}
+
+// ── scenario finder ───────────────────────────────────────────────────────────
+
+function findScenarios(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);
+      }
+    } catch {}
+  }
+  return found;
+}
+
+// ── prompt builder ────────────────────────────────────────────────────────────
+
+function buildPrompt(capId, cap, scanEntry, graph, allCaps, scenarios, firstCommit, recentHistory) {
+  const level      = stability(cap);
+  const files      = scanEntry?.codeAnalysis?.sourceFiles   || [];
+  const functions  = scanEntry?.codeAnalysis?.functions     || [];
+  const services   = scanEntry?.codeAnalysis?.services      || [];
+  const throws_    = scanEntry?.codeAnalysis?.throws        || [];
+  const calls      = scanEntry?.codeAnalysis?.calls         || [];
+  const deps       = graph?.deps?.[capId]       || [];
+  const dependents = graph?.dependents?.[capId] || [];
+
+  const lines = [
+    `You are a senior engineer writing a brief, plain-English explanation of a software capability for a teammate who is about to modify it.`,
+    ``,
+    `Write 3–5 sentences covering:`,
+    `  1. What this capability does and why it exists`,
+    `  2. The most important thing to know before changing it (stability, callers, risk)`,
+    `  3. What to test or verify after any modification`,
+    ``,
+    `Be concrete and direct. Do not use bullet points. Do not repeat the capability ID verbatim in every sentence.`,
+    ``,
+    `=== Capability: ${capId} ===`,
+    `Name:        ${cap.name || cap.title || capId}`,
+    `Description: ${cap.description || "(none provided)"}`,
+    `Stability:   ${level}`,
+  ];
+
+  if (files.length)     lines.push(`Source files: ${files.join(", ")}`);
+  if (functions.length) lines.push(`Functions:    ${functions.join(", ")}`);
+  if (services.length)  lines.push(`External services used: ${services.join(", ")}`);
+  if (throws_.length)   lines.push(`Can throw: ${throws_.join(", ")}`);
+  if (calls.length)     lines.push(`Internal calls: ${calls.join(", ")}`);
+
+  if (deps.length) {
+    const depDetails = deps.map(d => {
+      const dc = allCaps.find(c => c.id === d);
+      return `${d} (${stability(dc)})`;
+    });
+    lines.push(`Calls capabilities: ${depDetails.join(", ")}`);
+  }
+
+  if (dependents.length) {
+    const depDetails = dependents.map(d => {
+      const dc = allCaps.find(c => c.id === d);
+      return `${d} (${stability(dc)})`;
+    });
+    lines.push(`Called by capabilities: ${depDetails.join(", ")}`);
+  }
+
+  if (scenarios.length) {
+    lines.push(`Test scenarios: ${scenarios.map(s => s.scenarioId || s.description || "unnamed").join(", ")}`);
+  } else {
+    lines.push(`Test scenarios: none registered`);
+  }
+
+  if (firstCommit) {
+    lines.push(`First introduced: ${firstCommit.date} by ${firstCommit.author} — "${firstCommit.subject}"`);
+  }
+
+  if (recentHistory.length) {
+    lines.push(`Recent changes:`);
+    for (const h of recentHistory.slice(0, 3)) {
+      lines.push(`  ${h.date} — ${h.subject}`);
+    }
+  }
+
+  if (level === "frozen") {
+    lines.push(`IMPORTANT: This capability is FROZEN. Any modification requires explicit approval.`);
+  } else if (level === "stable") {
+    lines.push(`NOTE: This capability is STABLE. Prefer additive changes; avoid breaking the public API.`);
+  }
+
+  return lines.join("\n");
+}
+
+// ── AI caller ─────────────────────────────────────────────────────────────────
+
+async function callAI(prompt, cwd) {
+  try {
+    const { callAI: call } = await import("../ai/providerRouter.mjs");
+    return await call(prompt, cwd);
+  } catch {
+    // Provider not available — return a structured fallback
+    return null;
+  }
+}
+
+// ── fallback narrative (no AI) ────────────────────────────────────────────────
+
+function buildFallback(capId, cap, scanEntry, graph, allCaps, scenarios) {
+  const level      = stability(cap);
+  const name       = cap.name || cap.title || capId;
+  const services   = scanEntry?.codeAnalysis?.services || [];
+  const dependents = graph?.dependents?.[capId] || [];
+  const deps       = graph?.deps?.[capId]       || [];
+
+  const parts = [];
+
+  // What it does
+  if (cap.description && cap.description !== "(none provided)") {
+    parts.push(`${name} — ${cap.description}.`);
+  } else {
+    parts.push(`${name} handles the ${capId} flow within this system.`);
+  }
+
+  // External services
+  if (services.length) {
+    parts.push(`It integrates with ${services.join(" and ")}.`);
+  }
+
+  // Dependencies
+  if (deps.length) {
+    parts.push(`It depends on: ${deps.join(", ")}.`);
+  }
+  if (dependents.length) {
+    const frozenDeps = dependents.filter(d => stability(allCaps.find(c => c.id === d)) === "frozen");
+    if (frozenDeps.length) {
+      parts.push(`⚠️  ${frozenDeps.join(", ")} depend${frozenDeps.length === 1 ? "s" : ""} on this — changing it may break frozen capabilities.`);
+    } else {
+      parts.push(`${dependents.join(", ")} depend${dependents.length === 1 ? "s" : ""} on this capability.`);
+    }
+  }
+
+  // Stability advice
+  if (level === "frozen") {
+    parts.push(`This capability is FROZEN — do not modify without explicit instruction.`);
+  } else if (level === "stable") {
+    parts.push(`This capability is stable — prefer additive changes and avoid breaking the existing API surface.`);
+  } else {
+    parts.push(`This capability is experimental — free to refactor as needed.`);
+  }
+
+  // Test advice
+  if (scenarios.length) {
+    parts.push(`Before shipping changes, run the registered scenarios: ${scenarios.map(s => s.scenarioId || "unnamed").join(", ")}.`);
+  } else {
+    parts.push(`No test scenarios are registered — consider adding one before making changes.`);
+  }
+
+  return parts.join(" ");
+}
+
+// ── printer ───────────────────────────────────────────────────────────────────
+
+function printExplain(capId, cap, narrative, provider, dryRun) {
+  const level = stability(cap);
+  const icon  = LEVEL_ICON[level]  || "🌊";
+  const color = LEVEL_COLOR[level] || green;
+
+  console.log();
+  console.log(bold(`  ${icon} ${color(capId)}`));
+  if (cap.name || cap.title) console.log(gray(`     ${cap.name || cap.title}`));
+  console.log();
+
+  if (dryRun) {
+    console.log(yellow("  [dry-run] Prompt only — no AI call made"));
+    console.log();
+    return;
+  }
+
+  // Word-wrap narrative at ~80 chars
+  const words  = narrative.split(" ");
+  let   line   = "  ";
+  const lines  = [];
+  for (const word of words) {
+    if (line.length + word.length > 82) { lines.push(line); line = "  " + word; }
+    else line += (line === "  " ? "" : " ") + word;
+  }
+  if (line.trim()) lines.push(line);
+
+  for (const l of lines) console.log(l);
+  console.log();
+
+  if (provider) {
+    console.log(gray(`  ── via ${provider}`));
+  } else {
+    console.log(gray("  ── (AI provider not configured — showing structural summary)"));
+    console.log(gray("     Run: infernoflow setup  to connect an AI provider"));
+  }
+  console.log();
+}
+
+// ── entry point ───────────────────────────────────────────────────────────────
+
+export async function explainCommand(rawArgs) {
+  const args    = (rawArgs || []).slice(1);
+  const dryRun  = args.includes("--dry-run");
+  const jsonMode = args.includes("--json");
+
+  const capId = args.find(a => !a.startsWith("--"));
+
+  if (!capId) {
+    console.error(red("✗ Usage: infernoflow explain <capability-id> [--dry-run] [--json]"));
+    console.error(gray("  Example: infernoflow explain user-auth"));
+    process.exit(1);
+  }
+
+  const cwd        = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+
+  // Load capabilities
+  let allCaps = [];
+  const rawCaps = loadJson(path.join(infernoDir, "capabilities.json"));
+  if (rawCaps) allCaps = Array.isArray(rawCaps) ? rawCaps : (rawCaps.capabilities || []);
+
+  const cap = allCaps.find(c => c.id === capId);
+  if (!cap) {
+    console.error(red(`✗ Capability "${capId}" not found in capabilities.json`));
+    console.error(gray("  Run: infernoflow stability — to list all capability IDs"));
+    process.exit(1);
+  }
+
+  // Load scan + graph
+  const scanData  = loadJson(path.join(infernoDir, "scan.json"));
+  const graph     = loadJson(path.join(infernoDir, "graph.json"));
+  const scanEntry = scanData?.capabilities?.find(c => c.id === capId);
+
+  // Git history
+  const files       = scanEntry?.codeAnalysis?.sourceFiles || [];
+  const firstCommit = getFirstCommit(files[0], cwd);
+  const recentHistory = getRecentHistory(files[0], cwd);
+
+  // Scenarios
+  const scenarios = findScenarios(capId, infernoDir);
+
+  // Build prompt
+  const prompt = buildPrompt(capId, cap, scanEntry, graph, allCaps, scenarios, firstCommit, recentHistory);
+
+  if (dryRun && !jsonMode) {
+    console.log(gray(`\n  infernoflow explain  →  ${bold(capId)}`));
+    console.log(gray("  ──────────────────────────────────────────────────────────────"));
+    printExplain(capId, cap, "", null, true);
+    console.log(bold("  Prompt that would be sent to AI:"));
+    console.log();
+    console.log(prompt.split("\n").map(l => "    " + l).join("\n"));
+    console.log();
+    return;
+  }
+
+  // Call AI
+  let narrative = null;
+  let provider  = null;
+
+  if (!dryRun) {
+    try {
+      const result = await callAI(prompt, cwd);
+      if (result?.text) {
+        narrative = result.text.trim();
+        provider  = result.provider;
+      }
+    } catch {}
+  }
+
+  // Fallback if no AI
+  if (!narrative) {
+    narrative = buildFallback(capId, cap, scanEntry, graph, allCaps, scenarios);
+    provider  = null;
+  }
+
+  if (jsonMode) {
+    console.log(JSON.stringify({
+      capId,
+      name:      cap.name || cap.title,
+      stability: stability(cap),
+      narrative,
+      provider:  provider || "fallback",
+      sourceFiles: files,
+      scenarios:   scenarios.map(s => s.scenarioId || s.description),
+      firstCommit,
+    }, null, 2));
+    return;
+  }
+
+  console.log(gray(`\n  infernoflow explain  →  ${bold(capId)}`));
+  console.log(gray("  ──────────────────────────────────────────────────────────────"));
+  printExplain(capId, cap, narrative, provider, false);
+}

package/dist/lib/commands/scaffold.mjs

@@ -0,0 +1,489 @@
+/**
+ * infernoflow scaffold
+ *
+ * Generate a new capability — source file skeleton + contract registration
+ * + placeholder scenario — pre-wired to the project's detected patterns.
+ *
+ * Usage:
+ *   infernoflow scaffold payment-refund
+ *   infernoflow scaffold payment-refund --dir src/payments
+ *   infernoflow scaffold payment-refund --lang ts --dry-run
+ *   infernoflow scaffold payment-refund --json
+ */
+
+import * as fs   from "node:fs";
+import * as path from "node:path";
+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 saveJson(p, data) {
+  fs.writeFileSync(p, JSON.stringify(data, null, 2) + "\n");
+}
+
+// ── name derivers ─────────────────────────────────────────────────────────────
+
+/** payment-refund → PaymentRefund */
+function toPascalCase(id) {
+  return id.split(/[-_]/).map(w => w.charAt(0).toUpperCase() + w.slice(1)).join("");
+}
+
+/** payment-refund → paymentRefund */
+function toCamelCase(id) {
+  const p = toPascalCase(id);
+  return p.charAt(0).toLowerCase() + p.slice(1);
+}
+
+/** payment-refund → "Payment Refund" */
+function toTitle(id) {
+  return id.split(/[-_]/).map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+
+/**
+ * Derive a primary function name from the cap ID.
+ * payment-refund → refundPayment, user-auth → authenticateUser
+ */
+function primaryFnName(id) {
+  const parts = id.split(/[-_]/);
+  if (parts.length === 1) return toCamelCase(id);
+
+  // Common verb patterns: if second word is a verb-like term, flip order
+  const VERBS = ["auth", "login", "logout", "register", "refresh", "validate",
+                 "verify", "process", "refund", "charge", "send", "fetch",
+                 "create", "update", "delete", "get", "list", "search",
+                 "sync", "import", "export", "scan", "check", "notify"];
+
+  const last  = parts[parts.length - 1];
+  const first = parts[0];
+
+  // If last part looks like a noun and first part looks verb-like, use as-is
+  if (VERBS.includes(first)) {
+    // auth-user → authenticateUser style (expand verb)
+    const verbExpand = { auth: "authenticate", get: "get", list: "list",
+                         send: "send", check: "check", notify: "notify" };
+    const verb = verbExpand[first] || first;
+    const rest  = parts.slice(1).map((w, i) =>
+      i === 0 ? w.charAt(0).toUpperCase() + w.slice(1) : w
+    ).join("");
+    return verb + rest.charAt(0).toUpperCase() + rest.slice(1);
+  }
+
+  // Default: flip last+first — payment-refund → refundPayment
+  if (VERBS.includes(last)) {
+    const noun = parts.slice(0, -1).map((w, i) =>
+      i === 0 ? w.charAt(0).toUpperCase() + w.slice(1) : w
+    ).join("");
+    return last + noun;
+  }
+
+  return toCamelCase(id);
+}
+
+// ── language detector ─────────────────────────────────────────────────────────
+
+function detectLang(scan, profile, cwd) {
+  // 1. From scan source files
+  if (scan?.capabilities?.length) {
+    const files = scan.capabilities.flatMap(c => c.codeAnalysis?.sourceFiles || []);
+    const exts  = files.map(f => path.extname(f));
+    if (exts.filter(e => e === ".ts").length > exts.filter(e => e === ".js").length) return "ts";
+    if (exts.includes(".py")) return "py";
+    if (exts.includes(".go")) return "go";
+    if (exts.some(e => e === ".js" || e === ".mjs")) return "js";
+  }
+
+  // 2. From profile
+  const lang = profile?.language || profile?.lang;
+  if (lang) return lang.toLowerCase().replace("javascript", "js").replace("typescript", "ts");
+
+  // 3. From project files
+  if (fs.existsSync(path.join(cwd, "tsconfig.json")))  return "ts";
+  if (fs.existsSync(path.join(cwd, "pyproject.toml"))) return "py";
+  if (fs.existsSync(path.join(cwd, "go.mod")))         return "go";
+
+  return "js";
+}
+
+function detectSrcDir(scan, cwd) {
+  if (!scan?.capabilities?.length) return null;
+  const files = scan.capabilities.flatMap(c => c.codeAnalysis?.sourceFiles || []);
+  if (!files.length) return null;
+
+  // Count dir prefixes
+  const dirCount = {};
+  for (const f of files) {
+    const dir = path.dirname(f).split("/")[0];
+    dirCount[dir] = (dirCount[dir] || 0) + 1;
+  }
+  const top = Object.entries(dirCount).sort((a, b) => b[1] - a[1])[0];
+  return top ? top[0] : null;
+}
+
+function detectServices(scan) {
+  if (!scan?.capabilities?.length) return [];
+  const all = scan.capabilities.flatMap(c => c.codeAnalysis?.services || []);
+  return [...new Set(all)];
+}
+
+// ── code generators ───────────────────────────────────────────────────────────
+
+function generateTs(id, name, description, fn, services) {
+  const pascal    = toPascalCase(id);
+  const errorName = `${pascal}Error`;
+  const imports   = buildImports("ts", services);
+
+  return `/**
+ * ${name}
+ *
+ * ${description}
+ *
+ * @capability ${id}
+ * @stability  experimental
+ */
+${imports}
+
+// ── errors ────────────────────────────────────────────────────────────────────
+
+export class ${errorName} extends Error {
+  constructor(message: string, public readonly code?: string) {
+    super(message);
+    this.name = "${errorName}";
+  }
+}
+
+// ── types ─────────────────────────────────────────────────────────────────────
+
+export interface ${pascal}Input {
+  // TODO: define input fields
+}
+
+export interface ${pascal}Result {
+  // TODO: define result fields
+  success: boolean;
+}
+
+// ── implementation ────────────────────────────────────────────────────────────
+
+/**
+ * ${fn} — primary entry point for ${name}.
+ * TODO: implement this function.
+ */
+export async function ${fn}(input: ${pascal}Input): Promise<${pascal}Result> {
+  // TODO: implement
+  throw new ${errorName}("Not implemented yet");
+}
+`;
+}
+
+function generateJs(id, name, description, fn, services) {
+  const pascal    = toPascalCase(id);
+  const errorName = `${pascal}Error`;
+  const imports   = buildImports("js", services);
+
+  return `/**
+ * ${name}
+ *
+ * ${description}
+ *
+ * @capability ${id}
+ * @stability  experimental
+ */
+${imports}
+
+// ── errors ────────────────────────────────────────────────────────────────────
+
+export class ${errorName} extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name  = "${errorName}";
+    this.code  = code;
+  }
+}
+
+// ── implementation ────────────────────────────────────────────────────────────
+
+/**
+ * ${fn} — primary entry point for ${name}.
+ * TODO: implement this function.
+ *
+ * @param {object} input
+ * @returns {Promise<object>}
+ */
+export async function ${fn}(input = {}) {
+  // TODO: implement
+  throw new ${errorName}("Not implemented yet");
+}
+`;
+}
+
+function generatePy(id, name, description, fn) {
+  const cls = toPascalCase(id);
+
+  return `"""
+${name}
+
+${description}
+
+capability: ${id}
+stability:  experimental
+"""
+
+from typing import Any
+
+
+class ${cls}Error(Exception):
+    """Raised when ${name} operations fail."""
+    def __init__(self, message: str, code: str | None = None):
+        super().__init__(message)
+        self.code = code
+
+
+async def ${fn.replace(/([A-Z])/g, '_$1').toLowerCase().replace(/^_/, '')}(input: dict[str, Any]) -> dict[str, Any]:
+    """Primary entry point for ${name}.
+
+    TODO: implement this function.
+    """
+    raise ${cls}Error("Not implemented yet")
+`;
+}
+
+function generateGo(id, name, description, fn) {
+  const pkg = id.split("-")[0];
+
+  return `// Package ${pkg} implements ${name}.
+//
+// ${description}
+//
+// capability: ${id}
+// stability:  experimental
+package ${pkg}
+
+import "errors"
+
+// Err${toPascalCase(id)} is returned when ${name} operations fail.
+var Err${toPascalCase(id)} = errors.New("${id}: operation failed")
+
+// ${toPascalCase(fn)} is the primary entry point for ${name}.
+// TODO: implement this function.
+func ${toPascalCase(fn)}(input map[string]any) (map[string]any, error) {
+\treturn nil, Err${toPascalCase(id)}
+}
+`;
+}
+
+function buildImports(lang, services) {
+  if (!services.length) return "";
+  const lines = [];
+  if (lang === "ts" || lang === "js") {
+    // Suggest common client imports for detected services
+    const serviceImports = {
+      stripe:    `// import Stripe from 'stripe';`,
+      postgres:  `// import { Pool } from 'pg';`,
+      mysql:     `// import mysql from 'mysql2/promise';`,
+      redis:     `// import { createClient } from 'redis';`,
+      s3:        `// import { S3Client } from '@aws-sdk/client-s3';`,
+      sendgrid:  `// import sgMail from '@sendgrid/mail';`,
+      twilio:    `// import twilio from 'twilio';`,
+      openai:    `// import OpenAI from 'openai';`,
+    };
+    for (const svc of services) {
+      const imp = serviceImports[svc.toLowerCase()];
+      if (imp) lines.push(imp);
+    }
+  }
+  return lines.length ? lines.join("\n") + "\n" : "";
+}
+
+// ── scenario generator ────────────────────────────────────────────────────────
+
+function generateScenario(id, name, fn) {
+  return {
+    scenarioId:          `${id}-happy-path`,
+    description:         `Happy path for ${name}`,
+    capabilitiesCovered: [id],
+    createdAt:           new Date().toISOString(),
+    steps: [
+      { step: 1, action: `Call ${fn} with valid input`, expected: "Returns success result" },
+      { step: 2, action: `Call ${fn} with invalid input`, expected: "Throws appropriate error" },
+    ],
+  };
+}
+
+// ── printer ───────────────────────────────────────────────────────────────────
+
+function printResult({ id, filePath, scenarioPath, lang, fn, dryRun }) {
+  console.log();
+  console.log(bold(`  🌊 ${green(id)}`));
+  console.log(gray("     stability: experimental — free to evolve"));
+  console.log();
+  console.log(gray("  Generated:"));
+  console.log(`    ${green("+")}  ${cyan(filePath)}   ${gray(`(${lang} source skeleton)`)}`);
+  console.log(`    ${green("+")}  ${cyan("inferno/capabilities.json")}   ${gray("(capability registered)")}`);
+  console.log(`    ${green("+")}  ${cyan(scenarioPath)}   ${gray("(placeholder scenario)")}`);
+  console.log();
+  if (dryRun) {
+    console.log(yellow("  [dry-run] — no files were written"));
+  } else {
+    console.log(gray("  Next steps:"));
+    console.log(gray(`    1. Implement ${fn}() in ${filePath}`));
+    console.log(gray(`    2. Run: infernoflow scan    — to extract call graph`));
+    console.log(gray(`    3. Run: infernoflow graph   — to see dependencies`));
+    console.log(gray(`    4. Run: infernoflow check   — to validate contract`));
+  }
+  console.log();
+}
+
+// ── entry point ───────────────────────────────────────────────────────────────
+
+export async function scaffoldCommand(rawArgs) {
+  const args    = (rawArgs || []).slice(1);
+  const dryRun  = args.includes("--dry-run");
+  const jsonMode = args.includes("--json");
+
+  const langIdx = args.indexOf("--lang");
+  const langArg = langIdx !== -1 ? args[langIdx + 1] : null;
+
+  const dirIdx  = args.indexOf("--dir");
+  const dirArg  = dirIdx !== -1 ? args[dirIdx + 1] : null;
+
+  const descIdx = args.indexOf("--description");
+  const descArg = descIdx !== -1 ? args[descIdx + 1] : null;
+
+  // Cap ID: first non-flag arg (skip values after --lang, --dir, --description)
+  const skipIdxs = new Set([langIdx + 1, dirIdx + 1, descIdx + 1].filter(i => i > 0));
+  const capId = args.find((a, i) => !a.startsWith("--") && !skipIdxs.has(i));
+
+  if (!capId) {
+    console.error(red("✗ Usage: infernoflow scaffold <capability-id> [--dir <src>] [--lang ts|js|py|go] [--dry-run] [--json]"));
+    console.error(gray("  Example: infernoflow scaffold payment-refund"));
+    process.exit(1);
+  }
+
+  // Validate cap ID format
+  if (!/^[a-z][a-z0-9-]*$/.test(capId)) {
+    console.error(red(`✗ Invalid capability ID: "${capId}"`));
+    console.error(gray("  Use lowercase kebab-case: payment-refund, user-auth, etc."));
+    process.exit(1);
+  }
+
+  const cwd        = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+
+  // Load context
+  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 allCaps = [];
+  const rawCaps = loadJson(capsPath);
+  if (rawCaps) allCaps = Array.isArray(rawCaps) ? rawCaps : (rawCaps.capabilities || []);
+
+  // Check duplicate
+  if (allCaps.some(c => c.id === capId)) {
+    console.error(red(`✗ Capability "${capId}" already exists in capabilities.json`));
+    console.error(gray("  Use a different ID, or run: infernoflow why " + capId));
+    process.exit(1);
+  }
+
+  const scan    = loadJson(path.join(infernoDir, "scan.json"));
+  const profile = loadJson(path.join(infernoDir, "developer-profile.json"));
+
+  // Detect language
+  const lang = langArg || detectLang(scan, profile, cwd);
+
+  // Detect output directory
+  const srcDir = dirArg || detectSrcDir(scan, cwd) || "src";
+  const ext    = { ts: ".ts", js: ".js", py: ".py", go: ".go" }[lang] || ".js";
+
+  // Derive names
+  const name        = toTitle(capId);
+  const description = descArg || `TODO: describe ${name}`;
+  const fn          = primaryFnName(capId);
+  const services    = detectServices(scan);
+
+  // Generate code
+  let code;
+  if (lang === "ts") code = generateTs(capId, name, description, fn, services);
+  else if (lang === "py") code = generatePy(capId, name, description, fn);
+  else if (lang === "go") code = generateGo(capId, name, description, fn);
+  else code = generateJs(capId, name, description, fn, services);
+
+  // File path: srcDir/capId (replace dashes with nothing) + ext
+  // e.g. payment-refund → src/paymentRefund.ts
+  const fileName   = toCamelCase(capId) + ext;
+  const filePath   = path.join(srcDir, fileName);
+  const absFile    = path.join(cwd, filePath);
+
+  // Scenario path
+  const scenarioPath = path.join("inferno", "scenarios", `${capId}.json`);
+  const absScenario  = path.join(cwd, scenarioPath);
+  const scenario     = generateScenario(capId, name, fn);
+
+  // New capability entry
+  const newCap = {
+    id:          capId,
+    name,
+    description,
+    stability:   "experimental",
+    since:       new Date().toISOString().slice(0, 10),
+  };
+
+  if (jsonMode) {
+    const out = {
+      capId,
+      name,
+      stability:    "experimental",
+      lang,
+      filePath,
+      scenarioPath,
+      primaryFn:   fn,
+      dryRun,
+      code,
+    };
+    console.log(JSON.stringify(out, null, 2));
+    return;
+  }
+
+  console.log(gray(`\n  infernoflow scaffold  →  ${bold(capId)}`));
+  console.log(gray("  ──────────────────────────────────────────────────────────────"));
+
+  if (!dryRun) {
+    // Create source directory if needed
+    const absDir = path.dirname(absFile);
+    if (!fs.existsSync(absDir)) fs.mkdirSync(absDir, { recursive: true });
+
+    // Write source file
+    if (fs.existsSync(absFile)) {
+      console.error(red(`  ✗ File already exists: ${filePath}`));
+      console.error(gray("    Delete it first or choose a different --dir"));
+      process.exit(1);
+    }
+    fs.writeFileSync(absFile, code, "utf8");
+
+    // Register capability
+    allCaps.push(newCap);
+    saveJson(capsPath, allCaps);
+
+    // Write scenario
+    const scenDir = path.join(cwd, "inferno", "scenarios");
+    if (!fs.existsSync(scenDir)) fs.mkdirSync(scenDir, { recursive: true });
+    if (!fs.existsSync(absScenario)) {
+      saveJson(absScenario, scenario);
+    }
+  }
+
+  // Show code preview
+  const previewLines = code.split("\n").slice(0, 12).map(l => "    " + l).join("\n");
+  console.log(gray("\n  Preview:"));
+  console.log(gray(previewLines));
+  console.log(gray("    ..."));
+
+  printResult({ id: capId, filePath, scenarioPath, lang, fn, dryRun });
+}

package/package.json

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