@rafinery/cli 0.3.0 → 0.4.0

package/blueprint/.rafa/bin/rafa-compile.mjs

@@ -1,478 +0,0 @@
-#!/usr/bin/env node
-/**
- * rafa compile — the deterministic gate between the agents' markdown and the
- * platform. Reads every brain file, parses its frontmatter with a STRICT grammar
- * (see .rafa/contract.md §0), validates it against the contract, and on success
- * emits .rafa/manifest.json — the exact JSON the platform ingests.
- *
- * NO ASSUMPTIONS: a missing required field, a bad enum, or a malformed cite is a
- * hard error (path · field · rule). It never fills a default for a required field.
- * Exits 1 with a structured error list so the authoring agent can correct + retry.
- *
- * Usage:  node .rafa/bin/rafa-compile.mjs [--repo=owner/repo] [--branch=main] [--codeSha=<sha>]
- */
-import {
-  readFileSync,
-  writeFileSync,
-  readdirSync,
-  existsSync,
-  statSync,
-} from "node:fs";
-import { join } from "node:path";
-import { execSync } from "node:child_process";
-
-const SCHEMA_VERSION = 1;
-const arg = (k, d) => {
-  const m = process.argv.find((a) => a.startsWith(`--${k}=`));
-  return m ? m.slice(k.length + 3) : d;
-};
-const ROOT = arg("root", ".rafa");
-// Paths in the manifest are relative to the brain-repo root (`.rafa/` IS the root),
-// so the platform can fetch a prose body straight from the brain repo.
-const rel = (p) => (p.startsWith(ROOT + "/") ? p.slice(ROOT.length + 1) : p);
-
-const errors = [];
-const fail = (path, field, rule) => errors.push({ path, field, rule });
-
-// ── strict frontmatter parser (contract §0 grammar) ─────────────────────────
-// Legal value forms only: scalar | "quoted" | [flow,list] | { flow: map }.
-// Plus `key:` followed by `  - item` block lists. Anything else → error.
-function parseScalar(raw) {
-  const s = raw.trim();
-  if (s === "") return "";
-  if (/^".*"$/.test(s) || /^'.*'$/.test(s)) return s.slice(1, -1);
-  if (s === "true") return true;
-  if (s === "false") return false;
-  if (/^-?\d+$/.test(s)) return Number(s);
-  return s;
-}
-// Strip a trailing YAML comment ( whitespace + # … ) from an UNQUOTED top-level
-// scalar. Not applied to block-list items (cites/links are exact strings that may
-// legitimately contain `#`).
-function stripComment(s) {
-  if (/^["']/.test(s.trim())) return s;
-  const i = s.search(/\s#/);
-  return i === -1 ? s : s.slice(0, i);
-}
-function parseFlowList(raw) {
-  const inner = raw.trim().slice(1, -1).trim();
-  if (inner === "") return [];
-  return inner.split(",").map((x) => parseScalar(x));
-}
-function parseFlowMap(raw) {
-  const inner = raw.trim().slice(1, -1).trim();
-  const out = {};
-  if (inner === "") return out;
-  for (const pair of inner.split(",")) {
-    const i = pair.indexOf(":");
-    if (i === -1) return null; // malformed
-    out[pair.slice(0, i).trim()] = parseScalar(pair.slice(i + 1));
-  }
-  return out;
-}
-// Returns { data } or { error: "reason" }.
-function parseFrontmatter(text) {
-  if (!text.startsWith("---")) return { error: "no frontmatter block" };
-  const end = text.indexOf("\n---", text.indexOf("\n"));
-  if (end === -1) return { error: "unterminated frontmatter" };
-  const lines = text.slice(text.indexOf("\n") + 1, end).split("\n");
-  const data = {};
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    if (line.trim() === "" || line.trimStart().startsWith("#")) continue;
-    const m = line.match(/^([A-Za-z_][A-Za-z0-9_]*):(.*)$/);
-    if (!m) return { error: `illegal line: ${JSON.stringify(line)}` };
-    const key = m[1];
-    // Strip a trailing comment first, so `cites:   # note` reads as an empty value
-    // (block list follows), not as the comment being the value.
-    const rest = stripComment(m[2]).trim();
-    if (rest === "") {
-      // block list follows
-      const items = [];
-      while (i + 1 < lines.length && /^\s*-\s+/.test(lines[i + 1])) {
-        items.push(parseScalar(lines[++i].replace(/^\s*-\s+/, "")));
-      }
-      data[key] = items;
-    } else if (rest.startsWith("[")) {
-      const close = rest.lastIndexOf("]"); // ignore any trailing comment after ]
-      if (close === -1) return { error: `unclosed flow list at ${key}` };
-      data[key] = parseFlowList(rest.slice(0, close + 1));
-    } else if (rest.startsWith("{")) {
-      const close = rest.lastIndexOf("}");
-      if (close === -1) return { error: `unclosed flow map at ${key}` };
-      const fm = parseFlowMap(rest.slice(0, close + 1));
-      if (fm === null) return { error: `malformed flow map at ${key}` };
-      data[key] = fm;
-    } else {
-      data[key] = parseScalar(rest);
-    }
-  }
-  return { data };
-}
-
-// ── validators (contract §2–§6) ──────────────────────────────────────────────
-const CITE_RE = /^(.+):(\d+(?:-\d+)?)\s*::\s*(.+)$/;
-function parseCites(list, path) {
-  if (!Array.isArray(list) || list.length === 0) {
-    fail(path, "cites", "required · ≥ 1");
-    return [];
-  }
-  const out = [];
-  for (const c of list) {
-    const m = String(c).match(CITE_RE);
-    if (!m) {
-      fail(path, "cites", `malformed cite: ${JSON.stringify(c)}`);
-      continue;
-    }
-    out.push({ file: m[1].trim(), line: m[2], token: m[3].trim() });
-  }
-  return out;
-}
-const isEnum = (v, allowed) => allowed.includes(v);
-function reqStr(d, key, path) {
-  const v = d[key];
-  if (typeof v !== "string" || v.trim() === "") {
-    fail(path, key, "required · non-empty string");
-    return "";
-  }
-  return v;
-}
-function reqEnum(d, key, allowed, path) {
-  const v = d[key];
-  if (!isEnum(v, allowed)) {
-    fail(path, key, `required · one of ${allowed.join("|")}`);
-    return allowed[0];
-  }
-  return v;
-}
-function checkVersion(d, path) {
-  if (d.schemaVersion !== SCHEMA_VERSION)
-    fail(path, "schemaVersion", `must be ${SCHEMA_VERSION}`);
-}
-function checkId(d, path, name) {
-  const stem = name.replace(/\.md$/, "");
-  if (d.id !== stem) fail(path, "id", `must equal filename stem "${stem}"`);
-  return stem;
-}
-
-function walk(dir) {
-  if (!existsSync(dir)) return [];
-  return readdirSync(dir).flatMap((e) => {
-    const p = join(dir, e);
-    return statSync(p).isDirectory()
-      ? walk(p)
-      : e.endsWith(".md") && !e.startsWith("_")
-        ? [p]
-        : [];
-  });
-}
-const read = (p) => readFileSync(p, "utf8");
-
-function compileNotes(kind, dir) {
-  const notes = [];
-  for (const path of walk(dir)) {
-    const name = path.split("/").pop();
-    const { data, error } = parseFrontmatter(read(path));
-    if (error) {
-      fail(path, "frontmatter", error);
-      continue;
-    }
-    checkVersion(data, path);
-    const id = checkId(data, path, name);
-    notes.push({
-      id,
-      kind,
-      type: reqEnum(data, "type", ["contract", "convention", "flow", "how-to"], path),
-      domain: reqStr(data, "domain", path),
-      title: reqStr(data, "title", path),
-      summary: reqStr(data, "summary", path),
-      links: Array.isArray(data.links) ? data.links.map(String) : [],
-      ...(data.failure === "silent" || data.failure === "loud"
-        ? { failure: data.failure }
-        : {}),
-      cites: parseCites(data.cites, path),
-      path: rel(path),
-    });
-  }
-  return notes;
-}
-
-function compileImprovements(dir) {
-  const out = [];
-  for (const path of walk(dir)) {
-    const name = path.split("/").pop();
-    const { data, error } = parseFrontmatter(read(path));
-    if (error) {
-      fail(path, "frontmatter", error);
-      continue;
-    }
-    checkVersion(data, path);
-    const id = checkId(data, path, name);
-    const lev = data.leverage;
-    if (
-      typeof lev !== "object" ||
-      !isEnum(lev?.impact, ["low", "medium", "high"]) ||
-      !isEnum(lev?.effort, ["low", "medium", "high"])
-    )
-      fail(path, "leverage", "required · { impact, effort } ∈ low|medium|high");
-    out.push({
-      id,
-      priority: reqEnum(data, "priority", ["P0", "P1", "P2", "P3"], path),
-      lens: reqEnum(
-        data,
-        "lens",
-        ["security", "correctness", "performance", "architecture", "product", "ops"],
-        path,
-      ),
-      status: reqEnum(data, "status", ["open", "backlog", "fixed", "wontfix"], path),
-      title: reqStr(data, "title", path),
-      summary: reqStr(data, "summary", path),
-      fix: reqStr(data, "fix", path),
-      leverage: {
-        impact: lev?.impact ?? "low",
-        effort: lev?.effort ?? "low",
-      },
-      blastRadius: Array.isArray(data.blast_radius)
-        ? data.blast_radius.map(String)
-        : [],
-      cites: parseCites(data.cites, path),
-      path: rel(path),
-    });
-  }
-  return out;
-}
-
-function compileHealth() {
-  const path = join(ROOT, "brain", "checklist.md");
-  if (!existsSync(path)) return null;
-  const { data, error } = parseFrontmatter(read(path));
-  if (error) {
-    fail(path, "frontmatter", error);
-    return null;
-  }
-  checkVersion(data, path);
-  const g = data.gates,
-    c = data.counts;
-  if (!isEnum(g?.fidelity, ["pass", "fail"]) || !isEnum(g?.coverage, ["pass", "fail"]))
-    fail(path, "gates", "required · { fidelity, coverage } ∈ pass|fail");
-  if (
-    typeof c?.blockers !== "number" ||
-    typeof c?.majors !== "number" ||
-    typeof c?.minors !== "number"
-  )
-    fail(path, "counts", "required · { blockers, majors, minors } ints");
-  if (typeof data.score !== "number") fail(path, "score", "required · 0–100 int");
-  return {
-    verdict: reqEnum(data, "verdict", ["PASS", "ITERATE"], path),
-    score: typeof data.score === "number" ? data.score : 0,
-    gates: { fidelity: g?.fidelity ?? "fail", coverage: g?.coverage ?? "fail" },
-    counts: {
-      blockers: c?.blockers ?? 0,
-      majors: c?.majors ?? 0,
-      minors: c?.minors ?? 0,
-    },
-  };
-}
-
-function compileLedger() {
-  const path = join(ROOT, "improve", "ledger.md");
-  if (!existsSync(path)) return null;
-  const { data, error } = parseFrontmatter(read(path));
-  if (error) {
-    fail(path, "frontmatter", error);
-    return null;
-  }
-  checkVersion(data, path);
-  const bp = data.by_priority;
-  const okBp =
-    bp &&
-    ["P0", "P1", "P2", "P3"].every((k) => typeof bp[k] === "number");
-  if (!okBp) fail(path, "by_priority", "required · { P0, P1, P2, P3 } ints");
-  if (typeof data.open !== "number") fail(path, "open", "required · int");
-  if (typeof data.debt_score !== "number")
-    fail(path, "debt_score", "required · int");
-  return {
-    open: typeof data.open === "number" ? data.open : 0,
-    debtScore: typeof data.debt_score === "number" ? data.debt_score : 0,
-    byPriority: okBp
-      ? { P0: bp.P0, P1: bp.P1, P2: bp.P2, P3: bp.P3 }
-      : { P0: 0, P1: 0, P2: 0, P3: 0 },
-  };
-}
-
-function compileCoverage() {
-  const path = join(ROOT, "brain", "coverage.md");
-  if (!existsSync(path)) return null;
-  const { data, error } = parseFrontmatter(read(path));
-  if (error) {
-    fail(path, "frontmatter", error);
-    return null;
-  }
-  checkVersion(data, path);
-  const d = data.domains;
-  if (typeof d !== "object" || Array.isArray(d)) {
-    fail(path, "domains", "required · { domain: status } flow map");
-    return { domains: [] };
-  }
-  const STATUS = ["mapped", "thin", "stubbed", "empty"];
-  const domains = [];
-  for (const [domain, status] of Object.entries(d)) {
-    if (!STATUS.includes(status))
-      fail(path, `domains.${domain}`, `status ∈ ${STATUS.join("|")}`);
-    domains.push({ domain, status: String(status) });
-  }
-  return { domains };
-}
-
-// Plans (contract §7): parent+child files under plans/**. Global id uniqueness,
-// parent/child cross-checks, progress never stored, active.md → activePlanId.
-function compilePlans() {
-  const plans = [];
-  const seen = new Map(); // id → path (global uniqueness across plans/**)
-  for (const path of walk(join(ROOT, "plans"))) {
-    const name = path.split("/").pop();
-    const { data, error } = parseFrontmatter(read(path));
-    if (error) {
-      fail(path, "frontmatter", error);
-      continue;
-    }
-    checkVersion(data, path);
-    const id = checkId(data, path, name);
-    if (seen.has(id))
-      fail(path, "id", `duplicate plan id "${id}" (also ${seen.get(id)}) · ids are globally unique across plans/**`);
-    seen.set(id, path);
-    if ("progress" in data)
-      fail(path, "progress", "never stored · parent progress is derived by counting children");
-    const kind = reqEnum(data, "kind", ["parent", "child"], path);
-    const plan = reqStr(data, "plan", path);
-    const status = data.status;
-    if (kind === "child") {
-      if (!isEnum(status, ["todo", "in-progress", "done", "blocked"]))
-        fail(path, "status", "required (child) · todo|in-progress|done|blocked");
-      if (data.parent !== plan)
-        fail(path, "parent", `must equal plan "${plan}" for a child (flat v1)`);
-    } else {
-      if (data.parent !== null && data.parent !== "null")
-        fail(path, "parent", "must be null for kind: parent");
-      if (plan !== id) fail(path, "plan", `must equal id "${id}" for kind: parent`);
-      if (
-        status !== undefined &&
-        !isEnum(status, ["todo", "in-progress", "done", "blocked"])
-      )
-        fail(path, "status", "optional (parent) · todo|in-progress|done|blocked");
-    }
-    plans.push({
-      id,
-      plan,
-      parent: kind === "parent" ? null : plan,
-      kind,
-      title: reqStr(data, "title", path),
-      ...(isEnum(status, ["todo", "in-progress", "done", "blocked"])
-        ? { status }
-        : {}),
-      ...(typeof data.branch === "string" && data.branch !== ""
-        ? { branch: data.branch }
-        : {}),
-      ...(typeof data.baseSha === "string" && data.baseSha !== ""
-        ? { baseSha: String(data.baseSha) }
-        : {}),
-      path: rel(path),
-    });
-  }
-  // Cross-check: every child's plan resolves to a kind:parent in this compile.
-  const parents = new Set(plans.filter((p) => p.kind === "parent").map((p) => p.id));
-  for (const p of plans)
-    if (p.kind === "child" && !parents.has(p.plan))
-      fail(p.path, "plan", `no parent plan "${p.plan}" in this compile (dangling child)`);
-  return plans;
-}
-
-// active.md (generated pointer) → activePlanId. First line `# <plan-id>` must
-// resolve to a kind:parent plan; `# No active plan` or a missing file → null
-// (documented default: the pointer is generated, absence means "none").
-function compileActivePlanId(plans) {
-  const path = join(ROOT, "active.md");
-  if (!existsSync(path)) return null;
-  const first = read(path).split("\n")[0].trim();
-  const m = first.match(/^#\s+(.+)$/);
-  if (!m) {
-    fail(path, "pointer", 'first line must be "# <plan-id>" or "# No active plan"');
-    return null;
-  }
-  const val = m[1].trim();
-  if (/^no active plan$/i.test(val)) return null;
-  if (!plans.some((p) => p.kind === "parent" && p.id === val)) {
-    fail(path, "pointer", `active plan "${val}" is not a kind:parent plan in this compile`);
-    return null;
-  }
-  return val;
-}
-
-// ── assemble ─────────────────────────────────────────────────────────────────
-const gitOpts = { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }; // no stderr leak
-function gitSha() {
-  try {
-    return execSync("git rev-parse HEAD", gitOpts).trim();
-  } catch {
-    return arg("codeSha", "");
-  }
-}
-function gitBranch() {
-  try {
-    return execSync("git rev-parse --abbrev-ref HEAD", gitOpts).trim();
-  } catch {
-    return arg("branch", "main");
-  }
-}
-
-const notes = [
-  ...compileNotes("rule", join(ROOT, "brain", "rules")),
-  ...compileNotes("playbook", join(ROOT, "brain", "playbooks")),
-];
-const improvements = compileImprovements(join(ROOT, "improve", "improvements"));
-const health = compileHealth();
-const ledger = compileLedger();
-const coverage = compileCoverage();
-const plans = compilePlans();
-const activePlanId = compileActivePlanId(plans);
-
-// Cross-check: ledger.open / by_priority must match the actual open improvements.
-if (ledger) {
-  const open = improvements.filter((i) => i.status === "open");
-  const bp = { P0: 0, P1: 0, P2: 0, P3: 0 };
-  for (const i of open) bp[i.priority]++;
-  if (ledger.open !== open.length)
-    fail("improve/ledger.md", "open", `says ${ledger.open}, rows have ${open.length}`);
-  for (const k of ["P0", "P1", "P2", "P3"])
-    if (ledger.byPriority[k] !== bp[k])
-      fail("improve/ledger.md", `by_priority.${k}`, `says ${ledger.byPriority[k]}, rows have ${bp[k]}`);
-}
-
-if (errors.length) {
-  console.error(`✗ rafa compile: ${errors.length} contract violation(s)\n`);
-  for (const e of errors) console.error(`  ${e.path}  ·  ${e.field}  ·  ${e.rule}`);
-  console.error(`\nFix these files to match .rafa/contract.md, then re-run compile.`);
-  process.exit(1);
-}
-
-const manifest = {
-  schemaVersion: SCHEMA_VERSION,
-  generatedAt: new Date().toISOString(),
-  repo: arg("repo", ""),
-  branch: gitBranch(),
-  codeSha: gitSha(),
-  health,
-  ledger,
-  coverage,
-  notes,
-  improvements,
-  activePlanId,
-  plans,
-};
-writeFileSync(join(ROOT, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
-console.log(
-  `✓ rafa compile: ${notes.length} notes · ${improvements.length} improvements · ` +
-    `${plans.length} plans${activePlanId ? ` (active: ${activePlanId})` : ""} · ` +
-    `health ${health ? "ok" : "—"} · ledger ${ledger ? "ok" : "—"} · ` +
-    `coverage ${coverage ? `${coverage.domains.length} domains` : "—"} → .rafa/manifest.json`,
-);

package/blueprint/.rafa/bin/rafa-push.mjs

@@ -1,75 +0,0 @@
-#!/usr/bin/env node
-/**
- * rafa push — commit `.rafa/` and push it to the brain remote.
- *
- * `.rafa/` is its own git repo (set up by `rafa init`, remote `origin` = your brain
- * repo). This commits the current brain/improve state and pushes it, stamped
- * `brain-for: <code HEAD sha>` so the brain stays anchored to the code it describes.
- * Uses YOUR git auth — no credential passes through rafa. Run from the code repo root.
- */
-import { execSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-
-const die = (m) => {
-  console.error(`✗ ${m}`);
-  process.exit(1);
-};
-
-const ROOT = process.cwd();
-const RAFA = join(ROOT, ".rafa");
-if (!existsSync(join(RAFA, ".git")))
-  die("No `.rafa/` git repo here — run `rafa init` first, from your code repo root.");
-
-const inRafa = (cmd) =>
-  execSync(cmd, { cwd: RAFA, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" }).trim();
-
-try {
-  inRafa("git remote get-url origin");
-} catch {
-  die("`.rafa/` has no `origin` remote (the brain repo). Re-run `rafa init`.");
-}
-
-// Anchor the brain to the current code HEAD.
-let codeSha = "unknown";
-try {
-  codeSha = execSync("git rev-parse --short HEAD", { cwd: ROOT, encoding: "utf8" }).trim();
-} catch {
-  /* code repo may have no commits yet — fine */
-}
-
-// The CODE repo's full_name — stamped into the manifest as its identity.
-let repoFull = "";
-try {
-  const origin = execSync("git remote get-url origin", { cwd: ROOT, encoding: "utf8" }).trim();
-  const m = origin.match(/[/:]([^/:]+)\/([^/]+?)(?:\.git)?\/?$/);
-  if (m) repoFull = `${m[1]}/${m[2]}`;
-} catch {
-  /* no origin — manifest.repo stays "" */
-}
-
-// ── contract gate ──
-// Compile + validate the brain. A schema-invalid brain NEVER leaves the machine —
-// the platform ingests JSON, so what we push must already conform to the contract.
-console.log("• rafa compile — validating against .rafa/contract.md …");
-try {
-  execSync(`node ${join(RAFA, "bin", "rafa-compile.mjs")} --repo=${repoFull}`, {
-    cwd: ROOT,
-    stdio: "inherit",
-  });
-} catch {
-  die(
-    "brain failed the contract (see errors above). Fix the files, or have the " +
-      "authoring agent (atlas/bloom/prism) correct them, then re-push.",
-  );
-}
-
-inRafa("git add -A");
-try {
-  inRafa(`git commit -m "brain: scan" -m "brain-for: ${codeSha}"`);
-} catch {
-  console.log("• nothing new to commit — pushing current state");
-}
-inRafa("git branch -M main");
-inRafa("git push -u origin main");
-console.log(`✓ Pushed .rafa/ → brain remote (brain-for: ${codeSha})`);