infernoflow 0.16.0 → 0.17.0

package/dist/bin/infernoflow.mjs

@@ -37,6 +37,9 @@ const COMMAND_DESCRIPTIONS = {
   "team-sync": "Sync capability contract across a team via a shared git branch (push | pull | status | init)",
   onboard: "Interactive onboarding wizard for new developers — explains infernoflow in 5 minutes",
   cloud:   "Sync capability contracts via infernoflow cloud (init | push | pull | status | dashboard)",
+  share:   "Generate a public read-only HTML snapshot of your capability contract",
+  watch:   "Watch source files and run suggest automatically on save",
+  ci:      "CI-native check: GitHub Actions annotations, GitLab code quality, exit codes",
 };
 
 const COMMAND_HANDLERS = {
@@ -67,6 +70,9 @@ const COMMAND_HANDLERS = {
   "team-sync": async (args) => (await import("../lib/commands/teamSync.mjs")).teamSyncCommand(args),
   onboard: async (args) => (await import("../lib/commands/onboard.mjs")).onboardCommand(args),
   cloud:   async (args) => (await import("../lib/commands/cloud.mjs")).cloudCommand(args),
+  share:   async (args) => (await import("../lib/commands/share.mjs")).shareCommand(args),
+  watch:   async (args) => (await import("../lib/commands/watch.mjs")).watchCommand(args),
+  ci:      async (args) => (await import("../lib/commands/ci.mjs")).ciCommand(args),
 };
 
 function formatCommandsHelp() {
@@ -201,6 +207,24 @@ ${formatCommandsHelp()}
     --dry-run                 Print what would happen without sending
     --json                    Machine-readable output
 
+  ${bold("share options:")}
+    --upload                  Upload to dpaste.com and print a public URL
+    --open                    Open the snapshot in your browser immediately
+    --copy                    Copy HTML to clipboard
+    --out <path>              Custom output path (default: inferno/share.html)
+    --json                    Machine-readable: { ok, file, url }
+
+  ${bold("watch options:")}
+    [dirs...]                 Directories to watch (default: src/, lib/, app/)
+    --interval <secs>         Debounce interval in seconds (default: 3)
+    --dry-run                 Print what would run without executing
+    --silent                  No output (for git hook use)
+
+  ${bold("ci options:")}
+    --platform <name>         github | gitlab | bitbucket | generic (auto-detected)
+    --fail-on <level>         error | warning (default: error)
+    --json                    Machine-readable result + exit code
+
   ${bold("Machine output:")}
     ${gray("status --json")}
     ${gray("check --json")}

package/dist/lib/commands/ci.mjs

@@ -0,0 +1,207 @@
+/**
+ * infernoflow ci
+ *
+ * Auto-detect the CI environment and output structured annotations that
+ * integrate natively with each platform's UI.
+ *
+ * Supported platforms:
+ *   GitHub Actions   → ::error:: / ::warning:: / step summary (GITHUB_STEP_SUMMARY)
+ *   GitLab CI        → gl-code-quality.json artifact
+ *   Bitbucket        → annotations API via curl
+ *   Generic          → exit code + JSON output (for any CI)
+ *
+ * Usage:
+ *   infernoflow ci                     Auto-detect platform, run check + diff
+ *   infernoflow ci --platform github   Force a platform
+ *   infernoflow ci --fail-on warning   Fail on warning or higher (default: error)
+ *   infernoflow ci --json              Machine-readable result
+ *
+ * Exits 0 on success, 1 on error/warning (based on --fail-on).
+ */
+
+import * as fs   from "node:fs";
+import * as path from "node:path";
+import { spawnSync } from "node:child_process";
+import { header, ok, warn, info, done, bold, cyan, gray, green, red, yellow } from "../ui/output.mjs";
+
+// ── Platform detection ────────────────────────────────────────────────────────
+
+function detectPlatform() {
+  if (process.env.GITHUB_ACTIONS === "true")       return "github";
+  if (process.env.GITLAB_CI === "true")            return "gitlab";
+  if (process.env.BITBUCKET_BUILD_NUMBER)          return "bitbucket";
+  if (process.env.CIRCLECI === "true")             return "circleci";
+  if (process.env.JENKINS_URL)                     return "jenkins";
+  if (process.env.CI === "true")                   return "generic";
+  return "local";
+}
+
+// ── CLI runner ────────────────────────────────────────────────────────────────
+
+function runJson(command, cwd) {
+  try {
+    const [bin, ...args] = command.split(" ");
+    const result = spawnSync(process.execPath, [
+      path.join(path.dirname(path.dirname(new URL(import.meta.url).pathname)), "..", "bin", "infernoflow.mjs"),
+      ...command.split(" ").slice(1)
+    ], { cwd, encoding: "utf8", timeout: 30_000 });
+    const out = result.stdout?.trim();
+    if (out) return JSON.parse(out);
+  } catch {}
+  return null;
+}
+
+function runCli(args, cwd) {
+  try {
+    const result = spawnSync(process.execPath, [
+      path.join(path.dirname(path.dirname(new URL(import.meta.url).pathname)), "..", "bin", "infernoflow.mjs"),
+      ...args
+    ], { cwd, encoding: "utf8", timeout: 30_000 });
+    return result.stdout?.trim() || "";
+  } catch { return ""; }
+}
+
+// ── GitHub Actions output ─────────────────────────────────────────────────────
+
+function emitGithub(checkResult, diffResult, failOn) {
+  const status = checkResult?.status || "unknown";
+  const issues = checkResult?.issues || [];
+  const caps   = checkResult?.capabilities || 0;
+  const added  = diffResult?.added?.length || 0;
+  const removed = diffResult?.removed?.length || 0;
+  const changed = diffResult?.changed?.length || 0;
+
+  // GitHub workflow commands
+  if (status === "error") {
+    issues.filter(i => i.severity === "error").forEach(i => {
+      console.log(`::error::infernoflow: ${i.message}`);
+    });
+  } else if (status === "warning") {
+    issues.filter(i => i.severity === "warning").forEach(i => {
+      console.log(`::warning::infernoflow: ${i.message}`);
+    });
+  }
+
+  if (added > 0)   console.log(`::notice::infernoflow: ${added} new capability${added !== 1 ? "ies" : "y"} added`);
+  if (removed > 0) console.log(`::warning::infernoflow: ${removed} capability${removed !== 1 ? "ies" : "y"} removed`);
+
+  // Step summary
+  const summaryPath = process.env.GITHUB_STEP_SUMMARY;
+  if (summaryPath) {
+    const statusIcon = status === "ok" ? "✅" : status === "warning" ? "⚠️" : "❌";
+    const lines = [
+      `## 🔥 infernoflow CI report`,
+      "",
+      `${statusIcon} **Status:** ${status.toUpperCase()}  ·  **Capabilities:** ${caps}`,
+      "",
+    ];
+    if (added || removed || changed) {
+      lines.push("### Capability changes");
+      if (added)   lines.push(`- ✅ **${added}** added`);
+      if (removed) lines.push(`- ❌ **${removed}** removed`);
+      if (changed) lines.push(`- 📝 **${changed}** changed`);
+      lines.push("");
+    }
+    if (issues.length) {
+      lines.push("### Issues");
+      issues.forEach(i => lines.push(`- **${i.severity?.toUpperCase() || "INFO"}**: ${i.message}`));
+      lines.push("");
+    }
+    lines.push("---");
+    lines.push("*Generated by [infernoflow](https://github.com/ronmiz/infernoflow)*");
+    try { fs.appendFileSync(summaryPath, lines.join("\n") + "\n"); } catch {}
+  }
+}
+
+// ── GitLab code quality report ────────────────────────────────────────────────
+
+function emitGitlab(checkResult, cwd) {
+  const issues = checkResult?.issues || [];
+  const report = issues.map((issue, i) => ({
+    description:      issue.message || "infernoflow issue",
+    fingerprint:      Buffer.from(`infernoflow-${i}-${issue.message}`).toString("hex").slice(0, 40),
+    severity:         issue.severity === "error" ? "critical" : "minor",
+    location: {
+      path:       "inferno/contract.json",
+      lines:      { begin: 1 },
+    },
+  }));
+  const reportPath = path.join(cwd, "gl-code-quality-report.json");
+  fs.writeFileSync(reportPath, JSON.stringify(report, null, 2));
+  console.log(`infernoflow: GitLab code quality report written → gl-code-quality-report.json`);
+}
+
+// ── Generic CI output ─────────────────────────────────────────────────────────
+
+function emitGeneric(checkResult, diffResult, platform) {
+  const status = checkResult?.status || "unknown";
+  const caps   = checkResult?.capabilities || 0;
+  const added  = diffResult?.added?.length || 0;
+  const removed = diffResult?.removed?.length || 0;
+
+  console.log(`[infernoflow] platform=${platform} status=${status} capabilities=${caps} added=${added} removed=${removed}`);
+  if (checkResult?.issues?.length) {
+    checkResult.issues.forEach(i => {
+      console.log(`[infernoflow] ${(i.severity || "info").toUpperCase()}: ${i.message}`);
+    });
+  }
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+export async function ciCommand(rawArgs) {
+  const args        = rawArgs.slice(1);
+  const jsonMode    = args.includes("--json");
+  const platformArg = args.includes("--platform") ? args[args.indexOf("--platform") + 1] : null;
+  const failOn      = args.includes("--fail-on") ? args[args.indexOf("--fail-on") + 1] : "error";
+  const cwd         = process.cwd();
+  const infernoDir  = path.join(cwd, "inferno");
+
+  if (!fs.existsSync(infernoDir)) {
+    if (jsonMode) { console.log(JSON.stringify({ ok: false, error: "inferno/ not found" })); }
+    else { console.log("[infernoflow] inferno/ not found — skipping CI check"); }
+    process.exit(0); // Don't block CI if infernoflow isn't set up
+  }
+
+  const platform = platformArg || detectPlatform();
+
+  if (!jsonMode) {
+    console.log(`[infernoflow] running CI check (platform: ${platform})`);
+  }
+
+  // Run check + diff
+  const checkResult = runJson("check --json", cwd);
+  const diffResult  = runJson("diff --json", cwd);
+  const status      = checkResult?.status || "unknown";
+
+  // Platform-specific output
+  switch (platform) {
+    case "github":
+      emitGithub(checkResult, diffResult, failOn);
+      break;
+    case "gitlab":
+      emitGitlab(checkResult, cwd);
+      emitGeneric(checkResult, diffResult, platform);
+      break;
+    default:
+      emitGeneric(checkResult, diffResult, platform);
+  }
+
+  if (jsonMode) {
+    console.log(JSON.stringify({
+      ok:       status === "ok" || status === "warning",
+      platform,
+      status,
+      capabilities: checkResult?.capabilities || 0,
+      issues:   checkResult?.issues || [],
+      diff:     { added: diffResult?.added || [], removed: diffResult?.removed || [], changed: diffResult?.changed || [] },
+    }));
+  }
+
+  // Exit code
+  const shouldFail = failOn === "warning"
+    ? (status === "error" || status === "warning")
+    : (status === "error");
+
+  process.exit(shouldFail ? 1 : 0);
+}

package/dist/lib/commands/share.mjs

@@ -0,0 +1,236 @@
+/**
+ * infernoflow share
+ *
+ * Generate a public read-only snapshot of your capability contract — no cloud
+ * account needed. Creates a self-contained HTML file you can host anywhere,
+ * or uploads to a paste service and prints a short link.
+ *
+ * Usage:
+ *   infernoflow share                  Generate share.html locally
+ *   infernoflow share --open           Open in browser immediately
+ *   infernoflow share --upload         Upload to dpaste.com and print URL
+ *   infernoflow share --copy           Copy HTML to clipboard
+ *   infernoflow share --json           Machine-readable: { ok, file, url }
+ *   infernoflow share --out <path>     Custom output path
+ */
+
+import * as fs    from "node:fs";
+import * as path  from "node:path";
+import * as https from "node:https";
+import { execSync } from "node:child_process";
+import { done, warn, info, bold, cyan, gray, green } from "../ui/output.mjs";
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function readContract(infernoDir) {
+  for (const f of ["contract.json", "capabilities.json"]) {
+    const p = path.join(infernoDir, f);
+    if (fs.existsSync(p)) {
+      try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch {}
+    }
+  }
+  return null;
+}
+
+function readChangelog(cwd) {
+  const p = path.join(cwd, "CHANGELOG.md");
+  if (!fs.existsSync(p)) return null;
+  try {
+    const lines = fs.readFileSync(p, "utf8").split("\n");
+    const start = lines.findIndex(l => l.startsWith("## "));
+    if (start === -1) return null;
+    const end   = lines.findIndex((l, i) => i > start && l.startsWith("## "));
+    return lines.slice(start, end === -1 ? start + 30 : end).join("\n");
+  } catch { return null; }
+}
+
+// ── HTML generator ────────────────────────────────────────────────────────────
+
+function buildHtml(contract, changelog, generatedAt) {
+  const caps     = contract.capabilities || [];
+  const policyId = contract.policyId || "project";
+  const version  = contract.policyVersion || "?";
+
+  const capRows = caps.map(c => {
+    const id    = typeof c === "string" ? c : c.id;
+    const title = typeof c === "string" ? c : (c.title || c.id);
+    const cov   = typeof c === "object" ? c.covered : undefined;
+    const badge = cov === true  ? `<span class="cov yes">✔</span>`
+                : cov === false ? `<span class="cov no">✗</span>`
+                : `<span class="cov uk">·</span>`;
+    const desc  = typeof c === "object" && c.description ? `<div class="cap-desc">${c.description}</div>` : "";
+    return `<div class="cap-row">${badge}<div class="cap-body"><div class="cap-id">${id}</div><div class="cap-title">${title !== id ? title : ""}</div>${desc}</div></div>`;
+  }).join("");
+
+  const changelogHtml = changelog
+    ? `<section><h2>Latest changes</h2><pre class="changelog">${changelog.replace(/</g, "&lt;")}</pre></section>`
+    : "";
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${policyId} v${version} — infernoflow snapshot</title>
+<style>
+  *{box-sizing:border-box;margin:0;padding:0}
+  body{background:#0f0f1a;color:#e2e8f0;font-family:'Segoe UI',system-ui,sans-serif;line-height:1.5;padding:0 0 3rem}
+  header{background:#1a1a2e;border-bottom:2px solid #f97316;padding:1.5rem 2rem}
+  header h1{font-size:1.5rem;font-weight:700;color:#f97316}
+  header .meta{color:#64748b;font-size:0.85rem;margin-top:0.25rem}
+  main{max-width:860px;margin:2rem auto;padding:0 1.5rem}
+  section{margin-bottom:2rem}
+  h2{font-size:0.8rem;text-transform:uppercase;letter-spacing:0.08em;color:#64748b;margin-bottom:0.75rem;padding-bottom:0.4rem;border-bottom:1px solid #2d2d4e}
+  .stats{display:flex;gap:1rem;flex-wrap:wrap;margin-bottom:2rem}
+  .stat{background:#1a1a2e;border:1px solid #2d2d4e;border-radius:8px;padding:1rem 1.5rem;min-width:130px}
+  .stat .n{font-size:2rem;font-weight:700;color:#f97316}
+  .stat .l{font-size:0.75rem;color:#64748b;margin-top:2px}
+  .cap-row{display:flex;align-items:flex-start;gap:0.75rem;padding:0.6rem 0;border-bottom:1px solid #1e1e30}
+  .cap-row:last-child{border-bottom:none}
+  .cov{font-size:0.9rem;min-width:18px;text-align:center;margin-top:2px}
+  .cov.yes{color:#4ade80}.cov.no{color:#f87171}.cov.uk{color:#475569}
+  .cap-id{font-weight:600;font-size:0.9rem}
+  .cap-title{color:#94a3b8;font-size:0.8rem}
+  .cap-desc{color:#64748b;font-size:0.78rem;margin-top:2px}
+  .changelog{background:#1a1a2e;border:1px solid #2d2d4e;border-radius:6px;padding:1rem;font-size:0.8rem;white-space:pre-wrap;color:#94a3b8;overflow-x:auto}
+  footer{text-align:center;color:#334155;font-size:0.75rem;margin-top:3rem}
+  footer a{color:#f97316;text-decoration:none}
+</style>
+</head>
+<body>
+<header>
+  <h1>🔥 ${policyId}</h1>
+  <div class="meta">v${version} · ${caps.length} capabilities · snapshot ${generatedAt}</div>
+</header>
+<main>
+  <div class="stats">
+    <div class="stat"><div class="n">${caps.length}</div><div class="l">capabilities</div></div>
+    <div class="stat"><div class="n">${caps.filter(c => typeof c === "object" && c.covered).length || "—"}</div><div class="l">covered</div></div>
+    <div class="stat"><div class="n">v${version}</div><div class="l">version</div></div>
+  </div>
+  <section>
+    <h2>Capabilities</h2>
+    <div>${capRows || '<p style="color:#475569">No capabilities yet.</p>'}</div>
+  </section>
+  ${changelogHtml}
+</main>
+<footer>Generated by <a href="https://github.com/ronmiz/infernoflow">infernoflow</a> on ${generatedAt}</footer>
+</body>
+</html>`;
+}
+
+// ── Upload to dpaste ──────────────────────────────────────────────────────────
+
+function uploadToDpaste(content) {
+  return new Promise((resolve, reject) => {
+    const body = `content=${encodeURIComponent(content)}&syntax=html&expiry_days=365`;
+    const req  = https.request({
+      hostname: "dpaste.com",
+      path:     "/api/v2/",
+      method:   "POST",
+      headers: {
+        "Content-Type":   "application/x-www-form-urlencoded",
+        "Content-Length": Buffer.byteLength(body),
+        "User-Agent":     "infernoflow-cli",
+      },
+    }, (res) => {
+      let data = "";
+      res.on("data", d => (data += d));
+      res.on("end", () => {
+        const url = data.trim();
+        if (url.startsWith("http")) resolve(url + ".html");
+        else reject(new Error("Unexpected response: " + data));
+      });
+    });
+    req.on("error", reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+export async function shareCommand(rawArgs) {
+  const args       = rawArgs.slice(1);
+  const jsonMode   = args.includes("--json");
+  const openBrowser = args.includes("--open");
+  const upload     = args.includes("--upload");
+  const copyToClip = args.includes("--copy");
+  const outIdx     = args.indexOf("--out");
+  const cwd        = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+
+  if (!fs.existsSync(infernoDir)) {
+    const msg = "inferno/ not found. Run: infernoflow init";
+    if (jsonMode) { console.log(JSON.stringify({ ok: false, error: msg })); } else { warn(msg); }
+    process.exit(1);
+  }
+
+  const contract = readContract(infernoDir);
+  if (!contract) {
+    const msg = "No contract.json found. Run: infernoflow init";
+    if (jsonMode) { console.log(JSON.stringify({ ok: false, error: msg })); } else { warn(msg); }
+    process.exit(1);
+  }
+
+  const changelog   = readChangelog(cwd);
+  const generatedAt = new Date().toLocaleString();
+  const htmlContent = buildHtml(contract, changelog, generatedAt);
+
+  const outPath = outIdx !== -1 ? args[outIdx + 1] : path.join(cwd, "inferno", "share.html");
+  fs.writeFileSync(outPath, htmlContent, "utf8");
+
+  let url = null;
+
+  if (upload) {
+    if (!jsonMode) info("Uploading to dpaste.com…");
+    try {
+      url = await uploadToDpaste(htmlContent);
+    } catch (err) {
+      if (!jsonMode) warn(`Upload failed: ${err.message}`);
+    }
+  }
+
+  if (copyToClip) {
+    try {
+      const cmd = process.platform === "win32" ? `echo ${JSON.stringify(htmlContent)} | clip`
+                : process.platform === "darwin" ? `pbcopy`
+                : `xclip -selection clipboard`;
+      if (process.platform === "darwin") {
+        const { execSync: ex } = await import("node:child_process");
+        const proc = ex;
+        require("child_process").execSync("pbcopy", { input: htmlContent });
+      } else {
+        execSync(cmd, { input: htmlContent });
+      }
+      if (!jsonMode) info("HTML copied to clipboard");
+    } catch {}
+  }
+
+  if (openBrowser) {
+    try {
+      const target = url || outPath;
+      const cmd = process.platform === "win32" ? `start "" "${target}"`
+                : process.platform === "darwin" ? `open "${target}"`
+                : `xdg-open "${target}"`;
+      execSync(cmd, { stdio: "ignore" });
+    } catch {}
+  }
+
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: true, file: outPath, url }));
+    return;
+  }
+
+  const caps = (contract.capabilities || []).length;
+  done(`Snapshot created — ${bold(String(caps))} capabilities`);
+  console.log();
+  console.log(`  File: ${cyan(outPath)}`);
+  if (url) console.log(`  URL:  ${cyan(url)}`);
+  console.log();
+  if (!url) {
+    console.log(`  ${gray("Share the file or run with --upload to get a public URL:")}`);
+    console.log(`  ${cyan("infernoflow share --upload --open")}`);
+  }
+  console.log();
+}

package/dist/lib/commands/watch.mjs

@@ -0,0 +1,203 @@
+/**
+ * infernoflow watch
+ *
+ * File-system watcher that runs `infernoflow suggest` automatically whenever
+ * source files are saved. Zero manual steps — just code, save, and the
+ * contract stays in sync.
+ *
+ * Usage:
+ *   infernoflow watch                  Watch src/ (or auto-detected root)
+ *   infernoflow watch src lib          Watch specific directories
+ *   infernoflow watch --interval 5     Debounce interval in seconds (default: 3)
+ *   infernoflow watch --dry-run        Print what would run, don't actually run
+ *   infernoflow watch --silent         No output (git-hook friendly)
+ *
+ * What it does on each save:
+ *   1. Debounce (3 s default) — batches rapid multi-file saves
+ *   2. Diff changed files against capability-map.json
+ *   3. If relevant capabilities may be affected → run suggest
+ *   4. Run check silently — log issues to inferno/WATCH.log
+ */
+
+import * as fs   from "node:fs";
+import * as path from "node:path";
+import { execSync, spawnSync } from "node:child_process";
+import { ok, warn, info, bold, cyan, gray, green, yellow } from "../ui/output.mjs";
+
+// ── Source file detection ─────────────────────────────────────────────────────
+
+const SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py", ".go", ".java", ".cs", ".rb", ".swift"]);
+const SKIP_DIRS   = new Set(["node_modules", ".git", "dist", "build", "out", ".next", ".angular", "vendor", "coverage", "__pycache__"]);
+
+function defaultWatchDirs(cwd) {
+  const candidates = ["src", "lib", "app", "pages", "components", "server", "api"];
+  const found = candidates.filter(d => fs.existsSync(path.join(cwd, d)));
+  return found.length ? found.map(d => path.join(cwd, d)) : [cwd];
+}
+
+function isSourceFile(filePath) {
+  return SOURCE_EXTS.has(path.extname(filePath).toLowerCase());
+}
+
+// ── Capability relevance check ────────────────────────────────────────────────
+
+function capabilityRelevance(changedFiles, infernoDir) {
+  const mapPath = path.join(infernoDir, "capability-map.json");
+  if (!fs.existsSync(mapPath)) return { relevant: true, reason: "no cap-map — suggesting broadly" };
+
+  let capMap;
+  try { capMap = JSON.parse(fs.readFileSync(mapPath, "utf8")); } catch { return { relevant: true, reason: "cap-map unreadable" }; }
+
+  const hits = [];
+  for (const file of changedFiles) {
+    const rel = path.relative(process.cwd(), file).replace(/\\/g, "/");
+    for (const [prefix, capIds] of Object.entries(capMap)) {
+      if (rel.startsWith(prefix.replace(/\\/g, "/"))) {
+        hits.push(...capIds);
+      }
+    }
+  }
+
+  if (hits.length > 0) return { relevant: true, reason: `touches: ${[...new Set(hits)].slice(0,3).join(", ")}` };
+  return { relevant: false, reason: "no mapped capabilities affected" };
+}
+
+// ── Run suggest + check ───────────────────────────────────────────────────────
+
+function runSuggest(changedFiles, cwd, infernoDir, dryRun, silent) {
+  const names = changedFiles.map(f => path.basename(f, path.extname(f))).slice(0, 3).join(", ");
+  const desc  = `code changes in ${names}`;
+
+  if (!silent) {
+    process.stdout.write(`  ${yellow("⟳")}  suggesting from ${bold(String(changedFiles.length))} changed file${changedFiles.length !== 1 ? "s" : ""}… `);
+  }
+
+  if (dryRun) {
+    if (!silent) console.log(gray("(dry run)"));
+    return;
+  }
+
+  try {
+    spawnSync(process.execPath, [
+      path.join(path.dirname(path.dirname(path.dirname(new URL(import.meta.url).pathname))), "bin", "infernoflow.mjs"),
+      "suggest", desc, "--json"
+    ], { cwd, encoding: "utf8", timeout: 30_000, stdio: "ignore" });
+
+    if (!silent) console.log(green("done"));
+  } catch {
+    if (!silent) console.log(gray("skipped (no changes)"));
+  }
+
+  // Silent check — write issues to WATCH.log
+  try {
+    const result = spawnSync(process.execPath, [
+      path.join(path.dirname(path.dirname(path.dirname(new URL(import.meta.url).pathname))), "bin", "infernoflow.mjs"),
+      "check", "--json"
+    ], { cwd, encoding: "utf8", timeout: 15_000 });
+
+    const out = result.stdout?.trim();
+    if (out) {
+      const data = JSON.parse(out);
+      if (data.status === "error" || data.status === "warning") {
+        fs.writeFileSync(path.join(infernoDir, "WATCH.log"), out + "\n");
+        if (!silent) warn(`Contract issues detected — see inferno/WATCH.log`);
+      } else {
+        const logPath = path.join(infernoDir, "WATCH.log");
+        if (fs.existsSync(logPath)) fs.unlinkSync(logPath);
+      }
+    }
+  } catch {}
+}
+
+// ── Watcher ───────────────────────────────────────────────────────────────────
+
+export async function watchCommand(rawArgs) {
+  const args       = rawArgs.slice(1);
+  const dryRun     = args.includes("--dry-run");
+  const silent     = args.includes("--silent");
+  const intervalIdx = args.indexOf("--interval");
+  const debounceMs = ((intervalIdx !== -1 ? parseFloat(args[intervalIdx + 1]) : 3) || 3) * 1000;
+  const cwd        = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+
+  if (!fs.existsSync(infernoDir)) {
+    warn("inferno/ not found. Run: infernoflow init");
+    process.exit(1);
+  }
+
+  // Collect directories to watch
+  const dirArgs  = args.filter(a => !a.startsWith("-") && a !== String(args[intervalIdx + 1]));
+  const watchDirs = dirArgs.length
+    ? dirArgs.map(d => path.resolve(cwd, d))
+    : defaultWatchDirs(cwd);
+
+  const validDirs = watchDirs.filter(d => fs.existsSync(d));
+  if (!validDirs.length) {
+    warn("No valid directories to watch.");
+    process.exit(1);
+  }
+
+  if (!silent) {
+    console.log();
+    console.log(`  ${bold("🔥 infernoflow watch")}  ${gray("(Ctrl+C to stop)")}`);
+    console.log();
+    validDirs.forEach(d => console.log(`  ${cyan("watching")} ${gray(path.relative(cwd, d) || ".")}`));
+    console.log(`  ${gray(`debounce: ${debounceMs / 1000}s`)}`);
+    console.log();
+  }
+
+  let debounceTimer = null;
+  const pendingFiles = new Set();
+
+  const handleChange = (filePath) => {
+    if (!isSourceFile(filePath)) return;
+    pendingFiles.add(filePath);
+
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+      const changed = Array.from(pendingFiles);
+      pendingFiles.clear();
+
+      if (!silent) {
+        const names = changed.map(f => path.relative(cwd, f)).slice(0, 3).join(", ");
+        process.stdout.write(`\n  ${gray(new Date().toLocaleTimeString())}  ${bold(names)}${changed.length > 3 ? ` +${changed.length - 3} more` : ""}  `);
+      }
+
+      const { relevant, reason } = capabilityRelevance(changed, infernoDir);
+      if (!relevant) {
+        if (!silent) console.log(gray(`skip (${reason})`));
+        return;
+      }
+
+      runSuggest(changed, cwd, infernoDir, dryRun, silent);
+    }, debounceMs);
+  };
+
+  // Start watchers on each directory
+  const watchers = [];
+  for (const dir of validDirs) {
+    try {
+      const watcher = fs.watch(dir, { recursive: true }, (event, filename) => {
+        if (filename) handleChange(path.join(dir, filename));
+      });
+      watchers.push(watcher);
+    } catch (err) {
+      if (!silent) warn(`Cannot watch ${dir}: ${err.message}`);
+    }
+  }
+
+  if (!watchers.length) {
+    warn("No directories could be watched.");
+    process.exit(1);
+  }
+
+  // Keep alive
+  process.on("SIGINT", () => {
+    watchers.forEach(w => w.close());
+    if (!silent) { console.log("\n\n  Stopped."); console.log(); }
+    process.exit(0);
+  });
+
+  // Block forever
+  await new Promise(() => {});
+}

package/package.json

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