@rafinery/cli 0.11.0 → 0.12.0

package/lib/audit.mjs

@@ -0,0 +1,279 @@
+// rafa audit — the deterministic security engine (finding shape rafa.audit/v1).
+//
+// SELF-CONTAINED (owner, 2026-07-26: "rafa audit should already have what it
+// needs — it should just run"): dependency CVEs via the built-in pnpm-lock v9
+// parser + the free keyless OSV.dev API (merged with `pnpm audit --json` as a
+// secondary source), secrets via the built-in curated ruleset over TRACKED
+// files only (`.env*` never opened; fingerprints, never secret bytes). semgrep
+// is the ONE optional external (SAST, pinned config) — used if present,
+// honestly absent otherwise; gitleaks enhances the secrets tier the same way.
+// NO binaries are installed by this command, ever.
+//
+// Exit codes: 0 clean · 1 findings present · 2 engine error.
+
+import { execSync, execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  AUDIT_SCHEMA,
+  SECRET_PATTERNS,
+  buildOsvQueries,
+  buildReport,
+  classifyReachability,
+  dedupeFindings,
+  entropyOf,
+  fromGitleaks,
+  fromOsvBatch,
+  fromPnpmAudit,
+  fromRegexSecrets,
+  fromSemgrepSarif,
+  mapConcurrent,
+  parsePnpmLock,
+} from "./audit/core.mjs";
+
+const OSV_BATCH = "https://api.osv.dev/v1/querybatch";
+const OSV_VULN = "https://api.osv.dev/v1/vulns/";
+const SEMGREP_CONFIG = "p/security-audit"; // pinned — never `--config auto` (it phones home to pick rules)
+
+export const hasBinary = (name) => {
+  try {
+    execSync(`command -v ${name}`, { stdio: "ignore", shell: "/bin/sh" });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+async function osvFetch(url, body) {
+  const res = await fetch(url, {
+    method: body ? "POST" : "GET",
+    headers: body ? { "content-type": "application/json" } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!res.ok) throw new Error(`OSV ${res.status} on ${url}`);
+  return res.json();
+}
+
+// Tier a — dependency CVEs. Built-in OSV primary; `pnpm audit` secondary.
+async function dependencyTier(root) {
+  const lockPath = join(root, "pnpm-lock.yaml");
+  if (!existsSync(lockPath))
+    return { tier: { ran: false, tool: null, reason: "no pnpm-lock.yaml here" }, findings: [] };
+
+  const parsed = parsePnpmLock(readFileSync(lockPath, "utf8"));
+  const reachability = classifyReachability(parsed);
+  const findings = [];
+  let osvOk = false;
+  let reason = null;
+
+  try {
+    const chunks = buildOsvQueries(parsed.packages);
+    const results = [];
+    for (const chunk of chunks) {
+      const res = await osvFetch(OSV_BATCH, { queries: chunk });
+      results.push(...(res.results ?? []));
+    }
+    const ids = [...new Set(results.flatMap((r) => (r?.vulns ?? []).map((v) => v.id)))];
+    const details = new Map();
+    await mapConcurrent(ids, 8, async (id) => {
+      try {
+        details.set(id, await osvFetch(OSV_VULN + id));
+      } catch {
+        /* a detail we cannot fetch yields a shallower finding, never a guessed one */
+      }
+    });
+    findings.push(...fromOsvBatch(results, parsed.packages, details, reachability));
+    osvOk = true;
+  } catch (e) {
+    reason = `OSV unreachable (${e.message})`;
+  }
+
+  // Secondary source — pnpm audit builds its tree from the lockfile and asks
+  // the registry; it exits non-zero WHEN VULNS EXIST, so parse stdout
+  // regardless of exit code. Run without --prod: dev deps ride with dev:true
+  // and the priority map downgrades them — never silent omission.
+  let pnpmOk = false;
+  if (hasBinary("pnpm")) {
+    try {
+      let stdout;
+      try {
+        stdout = execSync("pnpm audit --json", { cwd: root, maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] });
+      } catch (e) {
+        stdout = e.stdout; // non-zero exit = findings, not failure
+      }
+      const json = JSON.parse(String(stdout));
+      findings.push(...fromPnpmAudit(json, reachability));
+      pnpmOk = true;
+    } catch {
+      /* unparseable output = tool failure; OSV may still have run */
+    }
+  }
+
+  if (!osvOk && !pnpmOk)
+    return { tier: { ran: false, tool: null, reason: reason ?? "registry unreachable" }, findings: [] };
+  const tool = osvOk && pnpmOk ? "osv-api+pnpm-audit" : osvOk ? "osv-api" : "pnpm-audit";
+  return { tier: { ran: true, tool }, findings: dedupeFindings(findings) };
+}
+
+const isEnvFile = (p) => /(^|\/)\.env(\.|$)/.test(p);
+const looksBinary = (buf) => buf.includes(0);
+
+// Tier b — secrets over tracked files only. The matched text NEVER leaves the
+// process: findings carry a sha256 fingerprint of (file:line:rule:match).
+function secretsTier(root) {
+  let files;
+  try {
+    files = execSync("git ls-files", { cwd: root, maxBuffer: 64 * 1024 * 1024 })
+      .toString()
+      .split("\n")
+      .filter(Boolean)
+      .filter((f) => !isEnvFile(f));
+  } catch {
+    return { tier: { ran: false, tool: null, reason: "not a git repository" }, findings: [] };
+  }
+
+  const rows = [];
+  for (const file of files) {
+    const abs = join(root, file);
+    let buf;
+    try {
+      if (statSync(abs).size > 1024 * 1024) continue; // generated/vendored blobs
+      buf = readFileSync(abs);
+    } catch {
+      continue;
+    }
+    if (looksBinary(buf)) continue;
+    const lines = buf.toString("utf8").split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      for (const p of SECRET_PATTERNS) {
+        const m = lines[i].match(p.re);
+        if (!m) continue;
+        if (p.entropy && entropyOf(m[1] ?? m[0]) < p.entropy) continue;
+        rows.push({
+          rule: p.rule,
+          title: p.title,
+          severity: p.severity,
+          file,
+          line: i + 1,
+          fingerprint: createHash("sha256").update(`${file}:${i + 1}:${p.rule}:${m[0]}`).digest("hex").slice(0, 16),
+        });
+      }
+    }
+  }
+  let findings = fromRegexSecrets(rows);
+  let tool = "regex-fallback";
+
+  // gitleaks enhancer — merged in when present, keyed off its own report file.
+  if (hasBinary("gitleaks")) {
+    const report = join(tmpdir(), `rafa-gitleaks-${process.pid}.json`);
+    try {
+      try {
+        execFileSync("gitleaks", ["detect", "--source", root, "--no-banner", "--report-format", "json", "--report-path", report], { stdio: "ignore" });
+      } catch {
+        /* gitleaks exits 1 when it finds leaks — the report still writes */
+      }
+      if (existsSync(report)) {
+        const rowsGl = JSON.parse(readFileSync(report, "utf8"));
+        findings = dedupeFindings([...findings, ...fromGitleaks(Array.isArray(rowsGl) ? rowsGl.filter((r) => !isEnvFile(r.File ?? "")) : [])]);
+        tool = "regex-fallback+gitleaks";
+      }
+    } catch {
+      /* enhancer failure never fails the built-in tier */
+    }
+  }
+  return { tier: { ran: true, tool }, findings };
+}
+
+// Tier c — SAST via semgrep, the one optional external.
+function sastTier(root) {
+  if (!hasBinary("semgrep"))
+    return { tier: { ran: false, tool: null, reason: "semgrep not installed (optional — `brew install semgrep`)" }, findings: [] };
+  try {
+    let stdout;
+    try {
+      stdout = execFileSync("semgrep", ["scan", "--config", SEMGREP_CONFIG, "--sarif", "--quiet"], { cwd: root, maxBuffer: 256 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] });
+    } catch (e) {
+      stdout = e.stdout; // semgrep exits non-zero on findings with some flags
+    }
+    const findings = fromSemgrepSarif(JSON.parse(String(stdout)));
+    return { tier: { ran: true, tool: "semgrep" }, findings };
+  } catch (e) {
+    return { tier: { ran: false, tool: "semgrep", reason: `semgrep failed (${e.message})` }, findings: [] };
+  }
+}
+
+const SEV_ICON = { critical: "✗", high: "✗", moderate: "~", low: "·", info: "·" };
+
+function renderHuman(report) {
+  const lines = [`rafa audit — ${report.summary.total} finding(s)`, ""];
+  for (const [t, s] of Object.entries(report.tiers)) {
+    lines.push(s.ran ? `  ✓ ${t} ran (${s.tool})` : `  ○ ${t} did not run — ${s.reason}`);
+  }
+  lines.push("", `  critical ${report.summary.critical} · high ${report.summary.high} · moderate ${report.summary.moderate} · low ${report.summary.low} · info ${report.summary.info}`, "");
+  for (const f of report.findings.slice(0, 20)) {
+    const where = f.package ? `${f.package.name}@${f.package.version}${f.chain?.direct ? "" : " (transitive)"}${f.dev ? " [dev]" : ""}` : f.location ? `${f.location.file}:${f.location.line ?? "?"}` : "";
+    lines.push(`  ${SEV_ICON[f.severity]} [${f.severity}] ${f.title}${where ? ` — ${where}` : ""}${f.fixedIn ? ` → fixed in ${f.fixedIn}` : ""}`);
+  }
+  if (report.findings.length > 20) lines.push(`  … ${report.findings.length - 20} more in security-audit.json`);
+  return lines.join("\n");
+}
+
+function renderRecord(report) {
+  const md = [
+    "---",
+    'type: "Security Audit"',
+    `title: Security audit — ${report.summary.total} finding(s)`,
+    `description: "critical ${report.summary.critical} · high ${report.summary.high} · moderate ${report.summary.moderate} · low ${report.summary.low}"`,
+    "---",
+    "",
+    "# Security audit",
+    "",
+    `Generated by \`rafa audit\` (${AUDIT_SCHEMA}). Machine record: \`security-audit.json\`.`,
+    "",
+    "| severity | tier | finding | subject | fixed in |",
+    "|---|---|---|---|---|",
+    ...report.findings.map((f) => {
+      const subject = f.package ? `${f.package.name}@${f.package.version}` : f.location ? `${f.location.file}:${f.location.line ?? "?"}` : "—";
+      return `| ${f.severity} | ${f.tier} | ${f.vulnId ?? f.ruleId ?? f.id} | ${subject} | ${f.fixedIn ?? "—"} |`;
+    }),
+    "",
+  ];
+  return md.join("\n");
+}
+
+export async function runAudit(args = []) {
+  const rootArg = args.find((a) => a.startsWith("--root="));
+  const root = rootArg ? rootArg.slice("--root=".length) : process.cwd();
+  const json = args.includes("--json");
+
+  try {
+    const [dep, sec, sast] = [await dependencyTier(root), secretsTier(root), sastTier(root)];
+    const report = buildReport({
+      at: new Date().toISOString(),
+      ref: null,
+      tiers: { dependency: dep.tier, secrets: sec.tier, sast: sast.tier },
+      findings: dedupeFindings([...dep.findings, ...sec.findings, ...sast.findings]),
+    });
+
+    // Dual record beside the ledger (the verify-citations convention) — only
+    // when a .rafa/ bundle exists; a bare repo still gets the stdout report.
+    const improveDir = join(root, ".rafa", "improve");
+    if (existsSync(join(root, ".rafa"))) {
+      mkdirSync(improveDir, { recursive: true });
+      writeFileSync(join(improveDir, "security-audit.json"), JSON.stringify(report, null, 2) + "\n");
+      writeFileSync(join(improveDir, "security-audit.md"), renderRecord(report));
+    }
+
+    console.log(json ? JSON.stringify(report, null, 2) : renderHuman(report));
+    return report.summary.total > 0 ? 1 : 0;
+  } catch (e) {
+    console.error(`✗ rafa audit: ${e.message}`);
+    return 2;
+  }
+}
+
+export default async function audit(args = []) {
+  process.exit(await runAudit(args));
+}

package/lib/blueprint.mjs

@@ -46,6 +46,7 @@ export const BLUEPRINT = {
     ".claude/skills/rafa-leverage",
     ".claude/skills/rafa-sage",
     ".claude/skills/rafa-okf",
+    ".claude/skills/rafa-security",
   ],
   lockstep: [".claude/rafa/contract.md"],
   // The M5 sensor hooks — deterministic protocol machinery (like the contract):

package/lib/distiller/doctrine.mjs

@@ -275,7 +275,7 @@ export function mergeRangeSweep({ changedFiles, orgNotes, cwd = process.cwd() })
 
 // ── failure classification (case 3) ─────────────────────────────────────────────
 // Deterministic (config / gate rejection / schema): retrying only burns spend →
-// reconcile_report failure class "deterministic" → needs-attention immediately.
+// terminal-report failure class "deterministic" → needs-attention immediately.
 // Transient (network / boot / OOM / clone / timeout): backoff retry while a later
 // branch proceeds. An error may carry an explicit `errorClass`; else heuristics.
 const TRANSIENT_RE =
@@ -288,7 +288,7 @@ export function classifyError(err) {
 }
 
 // Tagged-error helpers so the loop can raise a failure of a known class and the
-// reconcile_report path carries it verbatim (never a re-guess at the boundary).
+// terminal-report path (reconciliations.recordResult) carries it verbatim (never a re-guess at the boundary).
 export function deterministicFailure(message) {
   const e = new Error(message);
   e.errorClass = "deterministic";
@@ -314,7 +314,7 @@ export function outcomeRow({ candidate, outcome, detail, reconciliationId, super
   };
 }
 
-// The reconcile_report `delta` shape (knowledgeGraph.deltaValidator): four buckets
+// The terminal report’s `delta` shape (knowledgeGraph.deltaValidator): four buckets
 // of { noteId, cites }. Built from the run's dispositions so the node the pointer
 // advance mints carries exactly what this run refined. `folded` losers do not
 // enter the delta (they were superseded, not banked) but ARE in the outcomes.
@@ -339,7 +339,7 @@ function toWireCites(cites = []) {
   }));
 }
 
-// Per-branch outcome rows for reconcile_report (perBranchOutcomeValidator:
+// Per-branch outcome rows for the terminal report (perBranchOutcomeValidator:
 // { branch, capturedAtSha, verdict }). One row per source branch, the verdict a
 // short mechanical summary of that branch's fate in the fold.
 export function perBranchOutcomes(branchSets, outcomeRows) {

package/lib/doctor.mjs

@@ -97,6 +97,22 @@ export async function runDoctor(ROOT = process.cwd()) {
     }
   }
 
+  // 3b · security tools — the audit engine's core (lockfile parser + OSV +
+  // secrets ruleset) is BUILT IN and always on; gitleaks/semgrep are optional
+  // enhancers. Detection only — rafa never installs binaries.
+  {
+    const { hasBinary } = await import("./audit.mjs");
+    console.log("• security tools (rafa audit)");
+    ok("core engine built in (dep CVEs via OSV · secrets ruleset)");
+    for (const [name, hint] of [
+      ["gitleaks", "brew install gitleaks"],
+      ["semgrep", "brew install semgrep"],
+    ]) {
+      if (hasBinary(name)) ok(`${name} present (optional enhancer)`);
+      else console.log(`  · ${name} not installed — optional enhancer (\`${hint}\`)`);
+    }
+  }
+
   // 4 · the round-trip — the heartbeat must LAND, not just send. A recorded
   // response proves key + url + repo scoping + the platform handler, end to end.
   console.log("• platform round-trip");

package/lib/gate/compile.mjs

@@ -268,22 +268,26 @@ export function runCompile(argv = []) {
           "leverage",
           "required · { impact, effort } ∈ low|medium|high",
         );
+      // `category` is canonical; `lens` is the pre-2026-07-26 name, accepted
+      // as a deprecated alias so already-authored ledgers keep compiling.
+      const category = reqEnum(
+        { category: data.category ?? data.lens },
+        "category",
+        [
+          "security",
+          "correctness",
+          "performance",
+          "architecture",
+          "product",
+          "ops",
+        ],
+        path,
+      );
       out.push({
         id,
         priority: reqEnum(data, "priority", ["P0", "P1", "P2", "P3"], path),
-        lens: reqEnum(
-          data,
-          "lens",
-          [
-            "security",
-            "correctness",
-            "performance",
-            "architecture",
-            "product",
-            "ops",
-          ],
-          path,
-        ),
+        category,
+        lens: category, // transitional dual-key — dropped with the backfill arc
         status: reqEnum(
           data,
           "status",

package/lib/init.mjs

@@ -183,8 +183,9 @@ export default async function init(args) {
     );
   }
 
-  // Reconciliation runs on the PLATFORM (App-only era, owner call 2026-07-18):
-  // merged PRs are detected and distilled by the platform's own sandbox — no
+  // Reconciliation runs on the PLATFORM (App-only era, owner call 2026-07-18;
+  // agent-native since 2026-07-21): merged PRs are detected and reconciled by
+  // the server-side LangGraph agent — no
   // CI workflow, no repo secrets, nothing to wire here. The org-CI adapter
   // stays available as an explicit opt-out for teams that want the compute in
   // their own CI: `rafa ci-setup`. Init no longer asks — one fewer question,

package/lib/manifest.mjs

@@ -165,7 +165,8 @@ export default async function manifest() {
     return {
       id,
       priority: PRIORITIES.has(d.priority) ? d.priority : "P2",
-      lens: str(d.lens, "general"),
+      category: str(d.category ?? d.lens, "general"),
+      lens: str(d.category ?? d.lens, "general"), // transitional mirror of category
       status: IMP_STATUSES.has(d.status) ? d.status : "open",
       title: str(d.title, id),
       summary: str(d.summary),

package/lib/mcp-client.mjs

@@ -19,8 +19,9 @@ import { CLI_VERSION } from "./releases.mjs";
 // The CLI's own actor envelope for state-plane writes (wave 5: REQUIRED on every
 // loop event — strict, no legacy path). model is the explicit "mechanical"
 // sentinel: no LLM ruled here, and the split stays grep-able for sage. The
-// runner honors RAFA_ACTOR_RUNNER first (the platform's sandbox distiller and
-// other tiers export it — sandbox|ci|session), else CI env, else session.
+// runner honors RAFA_ACTOR_RUNNER first (platform tiers export it —
+// sandbox|ci|session; "sandbox" is a legacy wire value kept for historical
+// rows), else CI env, else session.
 export function cliActorMeta() {
   const declared = process.env.RAFA_ACTOR_RUNNER;
   return {

package/lib/working-set.mjs

@@ -160,15 +160,16 @@ export function materializeImprovement(cwd, data, brainForSha) {
 }
 
 // Deterministic ledger-file writer for hydrated improvements — mirrors the shape
-// bloom authors (see any improve/improvements/*.md): priority · lens · status ·
+// bloom authors (see any improve/improvements/*.md): priority · category · status ·
 // fix · leverage · blast_radius · cites, then the prose body.
 export function renderImprovement(d) {
+  const category = d.category ?? d.lens;
   const lines = [
     "---",
     "schemaVersion: 1",
     `id: ${d.id}`,
     `priority: ${d.priority}`,
-    ...(d.lens ? [`lens: ${d.lens}`] : []),
+    ...(category ? [`category: ${category}`] : []),
     `status: ${d.status}`,
     `title: ${q(d.title)}`,
     ...(d.summary ? [`summary: ${q(d.summary)}`] : []),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafinery/cli",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "rafa — the AI engineer CLI. Vendors the rafa blueprint into your repo (shadcn-style) and runs the deterministic contract gates.",
   "type": "module",
   "bin": {

package/skills-bundle/skills-manifest.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-07-25T21:14:46.864Z",
+  "generatedAt": "2026-07-26T15:51:05.847Z",
   "skills": {
     "tdd": {
       "version": "1.0.0",