infernoflow 0.18.0 → 0.20.0

package/dist/bin/infernoflow.mjs

@@ -42,6 +42,13 @@ const COMMAND_DESCRIPTIONS = {
   ci:      "CI-native check: GitHub Actions annotations, GitLab code quality, exit codes",
   notify:  "Post capability drift summary to Slack or Discord",
   report:  "Generate a weekly/monthly HTML or Markdown report of capability activity",
+  monorepo: "Manage infernoflow across monorepo packages (init | list | status | diff | sync)",
+  link:    "Link capabilities to Jira, Linear, or GitHub Issues tickets",
+  audit:   "Classify capabilities by sensitivity (auth, payment, PII, admin) and generate security surface map",
+  scout:   "Scan source files for undocumented capabilities not yet in the contract",
+  export:  "Export contract to OpenAPI, Backstage catalog-info.yaml, CSV, or Markdown",
+  snapshot: "Save/diff/restore named snapshots of the capability contract",
+  health:  "Compute a 0–100 health score across coverage, docs, freshness, completeness, drift",
 };
 
 const COMMAND_HANDLERS = {
@@ -77,6 +84,13 @@ const COMMAND_HANDLERS = {
   ci:      async (args) => (await import("../lib/commands/ci.mjs")).ciCommand(args),
   notify:  async (args) => (await import("../lib/commands/notify.mjs")).notifyCommand(args),
   report:  async (args) => (await import("../lib/commands/report.mjs")).reportCommand(args),
+  monorepo: async (args) => (await import("../lib/commands/monorepo.mjs")).monorepoCommand(args),
+  link:    async (args) => (await import("../lib/commands/link.mjs")).linkCommand(args),
+  audit:    async (args) => (await import("../lib/commands/audit.mjs")).auditCommand(args),
+  scout:    async (args) => (await import("../lib/commands/scout.mjs")).scoutCommand(args),
+  export:   async (args) => (await import("../lib/commands/export.mjs")).exportCommand(args),
+  snapshot: async (args) => (await import("../lib/commands/snapshot.mjs")).snapshotCommand(args),
+  health:   async (args) => (await import("../lib/commands/health.mjs")).healthCommand(args),
 };
 
 function formatCommandsHelp() {
@@ -243,6 +257,64 @@ ${formatCommandsHelp()}
     --fail-on <level>         error | warning (default: error)
     --json                    Machine-readable result + exit code
 
+  ${bold("monorepo sub-commands:")}
+    init                      Run infernoflow init --adopt in every package
+    list                      List detected packages with their capability counts
+    status                    Show contract health across all packages
+    diff                      Show capability changes across packages (--package to filter)
+    sync                      Aggregate all contracts into inferno-monorepo.json
+
+  ${bold("monorepo options:")}
+    --package <name>          Filter to a specific package
+    --json                    Machine-readable output
+
+  ${bold("link sub-commands:")}
+    (default)                 Link a capability to a ticket
+    list                      Show all capability→ticket links
+    status                    Show linked and unlinked capabilities
+    remove                    Remove a link by capability ID
+
+  ${bold("link options:")}
+    --capability <id>         Capability to link
+    --jira <TICKET>           Jira ticket ID (e.g. PROJ-123)
+    --linear <ID>             Linear issue ID
+    --github <NUM>            GitHub issue number
+    --json                    Machine-readable output
+
+  ${bold("audit options:")}
+    --format text|json|html   Output format (default: text)
+    --out <path>              Save to file (default: prints to stdout)
+    --fail-on high|medium     Exit 1 if unreviewed caps at given severity exist
+    --json                    Machine-readable output
+
+  ${bold("scout options:")}
+    --dir <dirs>              Comma-separated directories to scan (default: src,lib,app,api,routes)
+    --apply                   Write discovered capabilities to the contract file
+    --min-confidence <0-1>    Minimum confidence threshold (default: 0.6)
+    --json                    Machine-readable output
+
+  ${bold("export options:")}
+    --format openapi|backstage|csv|markdown|json   Output format (required)
+    --out <path>              Output file path (default: project root, auto-named)
+    --json                    Machine-readable summary
+
+  ${bold("snapshot sub-commands:")}
+    save <name>               Save current contract as a named snapshot
+    list                      List all snapshots
+    show <name>               Print a snapshot's capabilities
+    diff <name1> [<name2>]    Diff two snapshots (omit name2 to diff against current)
+    restore <name>            Overwrite contract with snapshot contents
+    delete <name>             Delete a snapshot
+
+  ${bold("snapshot options:")}
+    --json                    Machine-readable output
+
+  ${bold("health options:")}
+    --fail-below <score>      Exit 1 if health score is below this threshold (CI gate)
+    --watch                   Re-run every 30s (live terminal view)
+    --interval <secs>         Watch interval in seconds (default: 30)
+    --json                    Machine-readable score + breakdown
+
   ${bold("Machine output:")}
     ${gray("status --json")}
     ${gray("check --json")}

package/dist/lib/commands/audit.mjs

@@ -0,0 +1,335 @@
+/**
+ * infernoflow audit
+ *
+ * Classify capabilities by security sensitivity and generate a surface map.
+ * Tags each capability with one or more sensitivity labels:
+ *   auth      — authentication / authorization / sessions / tokens
+ *   payment   — billing, subscriptions, pricing, invoices
+ *   pii       — personal data, email, address, phone, GDPR scope
+ *   admin     — privileged operations, configuration, user management
+ *   public    — read-only, no auth required
+ *
+ * Stores results in inferno/audit.json (git-trackable).
+ *
+ * Usage:
+ *   infernoflow audit                   Run audit, print summary
+ *   infernoflow audit --format json     Machine-readable JSON to stdout
+ *   infernoflow audit --format html     Write HTML report
+ *   infernoflow audit --out audit.html  Custom output path
+ *   infernoflow audit --fail-on high    Exit 1 if any HIGH caps are unreviewed
+ *   infernoflow audit --json            Alias for --format json
+ */
+
+import * as fs   from "node:fs";
+import * as path from "node:path";
+import { done, warn, info, bold, cyan, gray, green, yellow, red } from "../ui/output.mjs";
+
+const AUDIT_FILE = "audit.json";
+
+// ── Sensitivity keyword maps ──────────────────────────────────────────────────
+
+const SENSITIVITY_RULES = [
+  {
+    tag:      "auth",
+    severity: "high",
+    label:    "Authentication / Authorization",
+    keywords: [
+      "auth", "login", "logout", "signin", "signout", "signup",
+      "password", "credential", "token", "session", "oauth",
+      "jwt", "permission", "role", "access", "privilege", "2fa",
+      "mfa", "sso", "saml", "openid", "verify", "authenticate",
+    ],
+  },
+  {
+    tag:      "payment",
+    severity: "high",
+    label:    "Payment / Billing",
+    keywords: [
+      "payment", "billing", "invoice", "charge", "subscription",
+      "checkout", "stripe", "card", "credit", "debit", "price",
+      "plan", "tier", "coupon", "refund", "transaction", "purchase",
+      "order", "cart", "paypal", "wallet",
+    ],
+  },
+  {
+    tag:      "pii",
+    severity: "high",
+    label:    "Personal / PII Data",
+    keywords: [
+      "pii", "personal", "profile", "email", "phone", "address",
+      "name", "user", "account", "gdpr", "privacy", "data",
+      "export", "download", "delete account", "identity", "dob",
+      "birthday", "ssn", "passport", "tax",
+    ],
+  },
+  {
+    tag:      "admin",
+    severity: "medium",
+    label:    "Admin / Privileged",
+    keywords: [
+      "admin", "manage", "config", "setting", "system", "deploy",
+      "migration", "seed", "reset", "purge", "archive", "batch",
+      "bulk", "impersonate", "override", "feature flag",
+    ],
+  },
+  {
+    tag:      "public",
+    severity: "low",
+    label:    "Public / Read-only",
+    keywords: [
+      "list", "search", "view", "read", "fetch", "get", "show",
+      "display", "browse", "filter", "sort", "paginate",
+    ],
+  },
+];
+
+const SEVERITY_ORDER = { high: 3, medium: 2, low: 1, unknown: 0 };
+
+// ── Classification ────────────────────────────────────────────────────────────
+
+function classifyCapability(cap) {
+  const text = [
+    typeof cap === "string" ? cap : "",
+    cap?.id     || "",
+    cap?.name   || "",
+    cap?.description || "",
+    (cap?.tags  || []).join(" "),
+  ].join(" ").toLowerCase();
+
+  const matched = [];
+  for (const rule of SENSITIVITY_RULES) {
+    if (rule.keywords.some(kw => text.includes(kw))) {
+      matched.push(rule);
+    }
+  }
+
+  // Remove "public" if any higher-severity tag also matched
+  const hasHigher = matched.some(r => r.tag !== "public" && r.severity !== "low");
+  const filtered  = hasHigher ? matched.filter(r => r.tag !== "public") : matched;
+
+  if (!filtered.length) {
+    return { tags: ["unknown"], severity: "unknown", labels: ["Unclassified"] };
+  }
+
+  const severity = filtered.reduce((best, r) => {
+    return SEVERITY_ORDER[r.severity] > SEVERITY_ORDER[best] ? r.severity : best;
+  }, "low");
+
+  return {
+    tags:     filtered.map(r => r.tag),
+    severity,
+    labels:   filtered.map(r => r.label),
+  };
+}
+
+// ── Storage ───────────────────────────────────────────────────────────────────
+
+function readAudit(infernoDir) {
+  const p = path.join(infernoDir, AUDIT_FILE);
+  if (!fs.existsSync(p)) return {};
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return {}; }
+}
+
+function writeAudit(infernoDir, data) {
+  fs.writeFileSync(path.join(infernoDir, AUDIT_FILE), JSON.stringify(data, null, 2) + "\n");
+}
+
+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;
+}
+
+// ── Formatters ────────────────────────────────────────────────────────────────
+
+function severityColor(sev) {
+  if (sev === "high")    return red;
+  if (sev === "medium")  return yellow;
+  if (sev === "low")     return green;
+  return gray;
+}
+
+function severityIcon(sev) {
+  if (sev === "high")   return "🔴";
+  if (sev === "medium") return "🟡";
+  if (sev === "low")    return "🟢";
+  return "⚪";
+}
+
+function printTextReport(results, stats) {
+  const bySeverity = { high: [], medium: [], low: [], unknown: [] };
+  for (const r of results) (bySeverity[r.severity] || bySeverity.unknown).push(r);
+
+  console.log();
+  console.log(`  ${bold("🔥 infernoflow audit — Security Surface Map")}`);
+  console.log();
+  console.log(`  ${bold(String(results.length))} capabilities scanned`);
+  console.log(`  ${red(String(stats.high))} high · ${yellow(String(stats.medium))} medium · ${green(String(stats.low))} low · ${gray(String(stats.unknown))} unclassified`);
+  console.log();
+
+  for (const [sev, items] of Object.entries(bySeverity)) {
+    if (!items.length) continue;
+    const col = severityColor(sev);
+    console.log(`  ${col(bold(`${sev.toUpperCase()} (${items.length})`))}`);
+    for (const item of items) {
+      const tagStr = item.tags.join(", ");
+      console.log(`  ${col("▸")} ${bold(item.id.padEnd(30))} ${gray(tagStr)}`);
+      if (item.description) console.log(`    ${gray(item.description.slice(0, 72))}`);
+    }
+    console.log();
+  }
+
+  if (stats.unknown > 0) {
+    console.log(`  ${gray("Tip: Add descriptions to unclassified capabilities for better detection.")}`);
+    console.log();
+  }
+}
+
+function buildHtmlReport(results, stats, runAt) {
+  const rows = results.map(r => {
+    const sev  = r.severity;
+    const cls  = sev === "high" ? "high" : sev === "medium" ? "med" : sev === "low" ? "low" : "unk";
+    const tags = r.tags.join(", ");
+    const icon = severityIcon(sev);
+    return `<tr class="${cls}"><td>${icon} ${sev}</td><td><strong>${escHtml(r.id)}</strong></td><td>${escHtml(tags)}</td><td>${escHtml(r.description || "")}</td></tr>`;
+  }).join("\n");
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>infernoflow audit</title>
+<style>
+  body { font-family: system-ui, sans-serif; background: #0d0d0d; color: #e0e0e0; margin: 0; padding: 24px; }
+  h1 { color: #ff4500; margin-bottom: 4px; }
+  .meta { color: #888; font-size: 13px; margin-bottom: 24px; }
+  .stats { display: flex; gap: 16px; margin-bottom: 24px; }
+  .stat { background: #1a1a1a; border-radius: 8px; padding: 12px 20px; text-align: center; }
+  .stat .n { font-size: 28px; font-weight: bold; }
+  .stat .l { font-size: 12px; color: #888; }
+  .high .n { color: #f55; }
+  .med .n  { color: #fa0; }
+  .low .n  { color: #4c4; }
+  .unk .n  { color: #888; }
+  table { width: 100%; border-collapse: collapse; font-size: 14px; }
+  th { background: #1a1a1a; padding: 8px 12px; text-align: left; color: #aaa; font-weight: 500; }
+  td { padding: 8px 12px; border-bottom: 1px solid #1e1e1e; vertical-align: top; }
+  tr.high td:first-child { color: #f55; }
+  tr.med  td:first-child { color: #fa0; }
+  tr.low  td:first-child { color: #4c4; }
+  tr.unk  td:first-child { color: #888; }
+  tr:hover td { background: #181818; }
+</style>
+</head>
+<body>
+<h1>🔥 infernoflow audit</h1>
+<p class="meta">Generated ${runAt}</p>
+<div class="stats">
+  <div class="stat high"><div class="n">${stats.high}</div><div class="l">HIGH</div></div>
+  <div class="stat med"><div class="n">${stats.medium}</div><div class="l">MEDIUM</div></div>
+  <div class="stat low"><div class="n">${stats.low}</div><div class="l">LOW</div></div>
+  <div class="stat unk"><div class="n">${stats.unknown}</div><div class="l">UNKNOWN</div></div>
+</div>
+<table>
+<thead><tr><th>Severity</th><th>Capability</th><th>Tags</th><th>Description</th></tr></thead>
+<tbody>
+${rows}
+</tbody>
+</table>
+</body>
+</html>`;
+}
+
+function escHtml(str) {
+  return String(str).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+// ── Entry ─────────────────────────────────────────────────────────────────────
+
+export async function auditCommand(rawArgs) {
+  const args      = rawArgs.slice(1);
+  const jsonMode  = args.includes("--json") || args.includes("--format") && args[args.indexOf("--format") + 1] === "json";
+  const cwd       = process.cwd();
+  const infernoDir = path.join(cwd, "inferno");
+
+  if (!fs.existsSync(infernoDir)) {
+    const msg = "inferno/ not found. Run: infernoflow init";
+    if (jsonMode) { console.log(JSON.stringify({ ok: false, error: msg })); }
+    else { warn(msg); }
+    process.exit(1);
+  }
+
+  // Parse flags
+  const fmtIdx    = args.indexOf("--format");
+  const format    = fmtIdx !== -1 ? args[fmtIdx + 1] : (jsonMode ? "json" : "text");
+  const outIdx    = args.indexOf("--out");
+  const outPath   = outIdx !== -1 ? args[outIdx + 1] : null;
+  const failOnIdx = args.indexOf("--fail-on");
+  const failOn    = failOnIdx !== -1 ? args[failOnIdx + 1] : null;
+
+  const contract = readContract(infernoDir);
+  if (!contract) {
+    const msg = "No contract.json or capabilities.json found.";
+    if (jsonMode) { console.log(JSON.stringify({ ok: false, error: msg })); }
+    else { warn(msg); }
+    process.exit(1);
+  }
+
+  const rawCaps = contract.capabilities || [];
+  const runAt   = new Date().toISOString();
+
+  // Classify every capability
+  const results = rawCaps.map(cap => {
+    const id          = typeof cap === "string" ? cap : (cap.id || cap.name || "unknown");
+    const description = typeof cap === "string" ? "" : (cap.description || "");
+    const cls         = classifyCapability(cap);
+    return { id, description, ...cls };
+  });
+
+  // Sort by severity descending
+  results.sort((a, b) => (SEVERITY_ORDER[b.severity] || 0) - (SEVERITY_ORDER[a.severity] || 0));
+
+  // Stats
+  const stats = { high: 0, medium: 0, low: 0, unknown: 0 };
+  for (const r of results) {
+    const key = r.severity in stats ? r.severity : "unknown";
+    stats[key]++;
+  }
+
+  // Persist to audit.json
+  const auditData = {
+    runAt,
+    stats,
+    capabilities: results,
+  };
+  writeAudit(infernoDir, auditData);
+
+  // Output
+  if (format === "json" || jsonMode) {
+    console.log(JSON.stringify({ ok: true, ...auditData }));
+  } else if (format === "html") {
+    const html = buildHtmlReport(results, stats, runAt);
+    const dest = outPath || path.join(infernoDir, "audit.html");
+    fs.writeFileSync(dest, html);
+    if (!jsonMode) done(`HTML audit report written to ${bold(dest)}`);
+  } else {
+    printTextReport(results, stats);
+    if (!jsonMode) done(`Saved to ${bold(path.join(infernoDir, AUDIT_FILE))}`);
+  }
+
+  // Exit code enforcement
+  if (failOn) {
+    const threshold = SEVERITY_ORDER[failOn] || 0;
+    const violations = results.filter(r => (SEVERITY_ORDER[r.severity] || 0) >= threshold);
+    if (violations.length > 0) {
+      if (!jsonMode) {
+        console.error(red(`\n  ✗  ${violations.length} capability/capabilities at or above "${failOn}" severity — review required.\n`));
+      }
+      process.exit(1);
+    }
+  }
+}