@haiyangbg/buildbeat 2.0.0-beta.2 → 2.0.0-beta.4

package/src/v2/runtime/envelope.js

@@ -0,0 +1,183 @@
+// Envelope as a first-class run-config section (iteration 08, C6). The deploy
+// campaign paid for every Run with a 34-line yaml, a 10 KB worker.sh and four
+// prompt files, and each worker line was a `git show <meta sha>:path | bash`
+// incantation. The kernel now does that part: it reads the prompt for the
+// step's worker (optionally pinned to a commit), substitutes declared vars,
+// materialises it into the run directory and hands the path to the worker as
+// BUILDBEAT_PROMPT. The envelope digest is recorded on RUN_CREATED so "which
+// prompts did this run see" is answerable from the ledger.
+//
+//   envelope:
+//     prompts: run-envelope/prompts     # dir, relative to the run config
+//     pin: <commit sha>                 # optional: read prompts from that commit
+//     vars:
+//       component: auth                 # {vars.component} in prompts and args
+//
+// Prompt lookup per worker: <component>-<worker>.md (when vars.component is
+// set) then <worker>.md. Missing prompt for a configured worker is not an
+// error — that worker simply gets no BUILDBEAT_PROMPT.
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+
+import { canonicalJson } from "../storage/event-ledger.js";
+
+export class EnvelopeError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EnvelopeError";
+  }
+}
+
+function gitToplevel(dir) {
+  try {
+    return execFileSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function readPinned(toplevel, pin, relPath) {
+  try {
+    return execFileSync("git", ["-C", toplevel, "show", `${pin}:${relPath}`], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+  } catch {
+    return null;
+  }
+}
+
+export function substituteVars(text, vars) {
+  let out = String(text);
+  for (const [key, value] of Object.entries(vars ?? {})) {
+    out = out.replaceAll(`{vars.${key}}`, String(value));
+  }
+  return out;
+}
+
+// Loads every prompt the configured workers could use. Returns null when the
+// run config declares no envelope.
+export function loadEnvelope(config, configDir, workerNames) {
+  const spec = config.envelope;
+  if (spec === undefined) {
+    return null;
+  }
+  if (!spec || typeof spec !== "object" || Array.isArray(spec)) {
+    throw new EnvelopeError("envelope must be a map");
+  }
+  if (typeof spec.prompts !== "string" || spec.prompts.length === 0) {
+    throw new EnvelopeError("envelope.prompts (a directory) is required");
+  }
+  const vars = spec.vars ?? {};
+  if (!vars || typeof vars !== "object" || Array.isArray(vars)) {
+    throw new EnvelopeError("envelope.vars must be a map");
+  }
+  for (const [key, value] of Object.entries(vars)) {
+    if (!/^[A-Za-z0-9_.-]+$/.test(key) || (typeof value !== "string" && typeof value !== "number")) {
+      throw new EnvelopeError(`envelope.vars.${key} must be a scalar`);
+    }
+  }
+  const pin = spec.pin ?? null;
+  if (pin !== null && !/^[0-9a-f]{7,40}$/.test(String(pin))) {
+    throw new EnvelopeError(`envelope.pin must be a commit sha, got: ${pin}`);
+  }
+  // realpath: git reports the toplevel through resolved symlinks (macOS
+  // /var → /private/var), so the config dir must be resolved the same way
+  // before a repository-relative prompt path can be computed.
+  const configReal = existsSync(configDir) ? realpathSync(configDir) : resolve(configDir);
+  const promptsDir = resolve(configReal, spec.prompts);
+  let toplevel = null;
+  let promptsRel = null;
+  if (pin) {
+    toplevel = gitToplevel(configReal);
+    if (!toplevel) {
+      throw new EnvelopeError("envelope.pin needs the run config to live inside a git repository");
+    }
+    promptsRel = relative(toplevel, promptsDir).split("\\").join("/");
+    if (promptsRel.startsWith("..")) {
+      throw new EnvelopeError("envelope.prompts must be inside the repository that holds the run config when pinned");
+    }
+  }
+  const component = vars.component !== undefined ? String(vars.component) : null;
+  const prompts = {};
+  for (const worker of workerNames) {
+    const candidates = [];
+    if (component) {
+      candidates.push(`${component}-${worker}.md`);
+    }
+    candidates.push(`${worker}.md`);
+    for (const name of candidates) {
+      let text = null;
+      if (pin) {
+        text = readPinned(toplevel, String(pin), `${promptsRel}/${name}`);
+      } else if (existsSync(join(promptsDir, name))) {
+        text = readFileSync(join(promptsDir, name), "utf8");
+      }
+      if (text !== null) {
+        prompts[worker] = { file: name, text: substituteVars(text, vars) };
+        break;
+      }
+    }
+  }
+  if (Object.keys(prompts).length === 0) {
+    throw new EnvelopeError(
+      `envelope.prompts ${spec.prompts} holds no prompt for any configured worker (${workerNames.join(", ") || "none"})${pin ? ` at ${pin}` : ""}`,
+    );
+  }
+  const digest = `sha256:${createHash("sha256")
+    .update(canonicalJson({ prompts, vars, pin }), "utf8")
+    .digest("hex")}`;
+  return { prompts, vars, pin: pin ? String(pin) : null, digest, source: pin ? `${promptsRel}@${pin}` : spec.prompts };
+}
+
+// Writes the step's prompt into the run directory and returns its absolute
+// path plus the repository-relative reference for the worker input.
+export function materialisePrompt({ envelope, worker, runtimeDir, runId, step, attempt, repoRoot }) {
+  const prompt = envelope?.prompts?.[worker];
+  if (!prompt) {
+    return null;
+  }
+  const dir = join(runtimeDir, "runs", runId, "prompts");
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, `${step}-${attempt}.md`);
+  writeFileSync(path, prompt.text, "utf8");
+  return { path, ref: relative(repoRoot, path).split("\\").join("/"), file: prompt.file };
+}
+
+// Next attempt id for a run family: RUN-X → RUN-X-01, RUN-X-02, ... scanning
+// both the runtime plane and the Git plane (run-records survive a runtime
+// wipe, so numbering never collides with a compacted run).
+export function nextAttemptId(repoRoot, workId, family) {
+  const pattern = new RegExp(`^${family.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}-(\\d{2,})$`);
+  let max = 0;
+  const dirs = [
+    join(repoRoot, ".buildbeat", "runtime", "runs"),
+    join(repoRoot, "delivery", "work", workId, "runs"),
+  ];
+  for (const dir of dirs) {
+    if (!existsSync(dir)) {
+      continue;
+    }
+    for (const entry of readdirSafe(dir)) {
+      const match = entry.match(pattern);
+      if (match) {
+        max = Math.max(max, Number(match[1]));
+      }
+    }
+  }
+  return `${family}-${String(max + 1).padStart(2, "0")}`;
+}
+
+function readdirSafe(dir) {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}

package/src/v2/runtime/findings.js

@@ -0,0 +1,158 @@
+// Review findings account per Work (Git plane, invariant 23: runtime stays
+// deletable). Every reviewer finding lands as a row keyed by a fingerprint;
+// human adjudications (accept/dismiss) append rows bound to that fingerprint.
+// A dismissed fingerprint no longer blocks and later reviewers receive the
+// adjudicated history as an anchor — re-litigating a settled verdict takes a
+// human decision, not a louder fresh reviewer. (Absorbed from the 30-run
+// deploy campaign: memoryless fresh reviewers oscillated between mutually
+// exclusive prescriptions and re-litigated accepted designs.)
+
+import { createHash } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const ADJUDICATION_ACTIONS = ["accept", "dismiss"];
+
+export class FindingsError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FindingsError";
+  }
+}
+
+export function findingsAccountRef(workId) {
+  return `delivery/work/${workId}/review-findings.jsonl`;
+}
+
+function accountPath(repoRoot, workId) {
+  return join(repoRoot, "delivery", "work", workId, "review-findings.jsonl");
+}
+
+// Same-text findings from different fresh reviewers must collide; severity is
+// part of the identity so an escalation (P2 -> P0) reopens on its own.
+export function fingerprintFinding(finding) {
+  const normalized = `${finding.severity}|${finding.summary}`
+    .toLowerCase()
+    .replace(/\s+/g, " ")
+    .trim();
+  return createHash("sha256").update(normalized, "utf8").digest("hex").slice(0, 16);
+}
+
+export function readFindingsAccount(repoRoot, workId) {
+  const filePath = accountPath(repoRoot, workId);
+  if (!existsSync(filePath)) {
+    return [];
+  }
+  const rows = [];
+  for (const line of readFileSync(filePath, "utf8").split("\n")) {
+    if (line.length === 0) {
+      continue;
+    }
+    try {
+      rows.push(JSON.parse(line));
+    } catch {
+      throw new FindingsError(`findings account has an invalid line: ${filePath}`);
+    }
+  }
+  return rows;
+}
+
+function appendRow(repoRoot, workId, row) {
+  const dir = join(repoRoot, "delivery", "work", workId);
+  mkdirSync(dir, { recursive: true });
+  appendFileSync(join(dir, "review-findings.jsonl"), `${JSON.stringify(row)}\n`, "utf8");
+}
+
+// Latest adjudication wins per fingerprint.
+export function latestAdjudications(rows) {
+  const map = new Map();
+  for (const row of rows) {
+    if (row.kind === "adjudication") {
+      map.set(row.fingerprint, row);
+    }
+  }
+  return map;
+}
+
+// Records one review attempt's findings into the account. Fingerprints that
+// already have a finding row are not duplicated; a finding whose fingerprint
+// a human dismissed is recorded as a re-raise attempt so the oscillation is
+// visible in the account, not just absent from the routing.
+export function recordReviewFindings(repoRoot, workId, { run, step, attempt, findings, ts }) {
+  const rows = readFindingsAccount(repoRoot, workId);
+  const adjudicated = latestAdjudications(rows);
+  const known = new Set(rows.filter((row) => row.kind === "finding").map((row) => row.fingerprint));
+  const recorded = [];
+  for (const [index, finding] of findings.entries()) {
+    const fingerprint = fingerprintFinding(finding);
+    const dismissed = adjudicated.get(fingerprint)?.action === "dismiss";
+    if (known.has(fingerprint) && !dismissed) {
+      continue;
+    }
+    const row = {
+      ts,
+      kind: "finding",
+      run,
+      step,
+      attempt,
+      id: `F-${run}-${step}-${attempt}-${index + 1}`,
+      severity: finding.severity,
+      summary: finding.summary,
+      fingerprint,
+      ...(dismissed ? { reRaised: true } : {}),
+    };
+    appendRow(repoRoot, workId, row);
+    known.add(fingerprint);
+    recorded.push(row);
+  }
+  return recorded;
+}
+
+export function adjudicateFinding(repoRoot, workId, { fingerprint, action, by, note, ts }) {
+  if (!ADJUDICATION_ACTIONS.includes(action)) {
+    throw new FindingsError(`action must be one of ${ADJUDICATION_ACTIONS.join("|")}, got: ${action}`);
+  }
+  const rows = readFindingsAccount(repoRoot, workId);
+  const finding = rows.find((row) => row.kind === "finding" && row.fingerprint === fingerprint);
+  if (!finding) {
+    throw new FindingsError(
+      `no recorded finding with fingerprint ${fingerprint}; adjudications bind to recorded findings only`,
+    );
+  }
+  const row = {
+    ts: ts ?? new Date().toISOString(),
+    kind: "adjudication",
+    fingerprint,
+    action,
+    by: by ?? "human",
+    ...(note ? { note } : {}),
+  };
+  appendRow(repoRoot, workId, row);
+  return { ...row, summary: finding.summary, severity: finding.severity };
+}
+
+// Compact anchor for worker input (BUILDBEAT_INPUT): the full adjudicated
+// history plus open findings, capped so the env payload stays small.
+const ANCHOR_CAP = 50;
+const SUMMARY_CAP = 300;
+
+export function buildAnchor(repoRoot, workId) {
+  const rows = readFindingsAccount(repoRoot, workId);
+  if (rows.length === 0) {
+    return null;
+  }
+  const adjudicated = latestAdjudications(rows);
+  const entries = rows
+    .filter((row) => row.kind === "finding")
+    .map((row) => ({
+      fingerprint: row.fingerprint,
+      severity: row.severity,
+      summary:
+        row.summary.length > SUMMARY_CAP ? `${row.summary.slice(0, SUMMARY_CAP)}…` : row.summary,
+      adjudication: adjudicated.get(row.fingerprint)?.action ?? "open",
+    }));
+  return {
+    account: findingsAccountRef(workId),
+    findings: entries.slice(-ANCHOR_CAP),
+  };
+}

package/src/v2/runtime/gc.js

@@ -0,0 +1,182 @@
+// Runtime garbage collection (iteration 08, C3): terminal runs leave a
+// worktree, a run/* branch and sometimes a lock behind. Sixteen of them had
+// piled up in the deploy campaign before the owner asked for "打扫卫生".
+//
+// Rules (fail-closed toward keeping things):
+//   - only terminal AND compacted runs are candidates; a run-record in the Git
+//     plane must exist before anything in the runtime plane goes;
+//   - the worktree is removable (commits live on the branch);
+//   - the branch goes only when its candidate is reachable from some other
+//     ref (merged, tagged, on a remote) or the run produced no candidate;
+//     otherwise the branch is the only thing keeping evidence reachable and
+//     stays, listed as such;
+//   - a dirty worktree is never removed without --force.
+// The ledger is not touched: after RUN_COMPACTED nothing may be appended.
+
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+
+import { EventLedger } from "../storage/event-ledger.js";
+import { readback } from "../workspace/workspace-manager.js";
+import { resolveRepoRef } from "./repo-ref.js";
+
+function git(cwd, args) {
+  return execFileSync("git", ["-C", cwd, ...args], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  }).trimEnd();
+}
+
+function branchExists(repoRoot, branch) {
+  try {
+    git(repoRoot, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function worktreeRegistered(repoRoot, worktreePath) {
+  try {
+    const listing = git(repoRoot, ["worktree", "list", "--porcelain"]);
+    return listing.split("\n").some((line) => line === `worktree ${worktreePath}`);
+  } catch {
+    return false;
+  }
+}
+
+// Refs (other than the run's own branch and other run/* branches) that
+// already contain the candidate commit.
+function otherRefsContaining(repoRoot, sha, ownBranch) {
+  try {
+    const out = git(repoRoot, ["for-each-ref", "--contains", sha, "--format=%(refname)"]);
+    return out
+      .split("\n")
+      .filter(Boolean)
+      .filter((ref) => ref !== `refs/heads/${ownBranch}` && !ref.startsWith("refs/heads/run/"));
+  } catch {
+    return [];
+  }
+}
+
+export function planGc(repoRoot) {
+  const runsDir = join(repoRoot, ".buildbeat", "runtime", "runs");
+  const locksDir = join(repoRoot, ".buildbeat", "runtime", "locks");
+  const rows = [];
+  if (!existsSync(runsDir)) {
+    return rows;
+  }
+  for (const entry of readdirSync(runsDir).sort()) {
+    const ledgerPath = join(runsDir, entry, "events.jsonl");
+    if (!existsSync(ledgerPath)) {
+      continue;
+    }
+    const ledger = EventLedger.open(ledgerPath);
+    const state = ledger.state;
+    const row = { run: entry, status: state.run?.status ?? "(no run)", actions: [], keep: [] };
+    rows.push(row);
+    if (ledger.corruption) {
+      row.keep.push(`ledger corrupted after seq=${ledger.corruption.afterSeq}; human decision required`);
+      continue;
+    }
+    if (!state.run) {
+      row.keep.push("ledger has no run");
+      continue;
+    }
+    if (!state.terminal) {
+      row.keep.push(`run not terminal (${state.run.status})`);
+      continue;
+    }
+    if (!state.compacted) {
+      row.keep.push("terminal but not compacted (no run-record in the Git plane)");
+      continue;
+    }
+    const lockPath = join(locksDir, `${entry}.lock`);
+    if (existsSync(lockPath)) {
+      row.actions.push({ kind: "remove-lock", path: lockPath });
+    }
+    const workspace = state.workspaces[entry];
+    if (!workspace) {
+      continue;
+    }
+    const worktreePath = resolveRepoRef(repoRoot, workspace.worktreePath);
+    const registered = worktreeRegistered(repoRoot, worktreePath);
+    const present = existsSync(worktreePath);
+    row.candidate = workspace.candidate;
+    row.branch = workspace.branch;
+    if (present || registered) {
+      let dirty = false;
+      if (present) {
+        try {
+          dirty = readback(worktreePath).dirty;
+        } catch {
+          dirty = false;
+        }
+      }
+      row.actions.push({ kind: "remove-worktree", path: worktreePath, dirty, registered, present });
+    }
+    if (workspace.branch && branchExists(repoRoot, workspace.branch)) {
+      if (!workspace.candidate) {
+        row.actions.push({ kind: "delete-branch", branch: workspace.branch, reason: "run produced no candidate" });
+      } else {
+        const elsewhere = otherRefsContaining(repoRoot, workspace.candidate, workspace.branch);
+        if (elsewhere.length > 0) {
+          row.actions.push({
+            kind: "delete-branch",
+            branch: workspace.branch,
+            reason: `candidate ${workspace.candidate.slice(0, 7)} also on ${elsewhere.slice(0, 3).join(", ")}`,
+          });
+        } else {
+          row.keep.push(
+            `branch ${workspace.branch} kept: candidate ${workspace.candidate.slice(0, 7)} is reachable only there (evidence)`,
+          );
+        }
+      }
+    }
+  }
+  return rows;
+}
+
+export function applyGc(repoRoot, rows, { force = false } = {}) {
+  const results = [];
+  for (const row of rows) {
+    for (const action of row.actions) {
+      const result = { run: row.run, ...action, done: false, error: null };
+      results.push(result);
+      try {
+        if (action.kind === "remove-lock") {
+          rmSync(action.path, { recursive: true, force: true });
+          result.done = true;
+        } else if (action.kind === "remove-worktree") {
+          if (action.dirty && !force) {
+            result.error = "worktree dirty; rerun with --force true to discard";
+            continue;
+          }
+          if (action.registered) {
+            const args = ["worktree", "remove"];
+            if (force || action.dirty) {
+              args.push("--force");
+            }
+            args.push(action.path);
+            git(repoRoot, args);
+          } else if (action.present) {
+            rmSync(action.path, { recursive: true, force: true });
+          }
+          try {
+            git(repoRoot, ["worktree", "prune"]);
+          } catch {
+            // prune is best-effort
+          }
+          result.done = true;
+        } else if (action.kind === "delete-branch") {
+          git(repoRoot, ["branch", "-D", action.branch]);
+          result.done = true;
+        }
+      } catch (error) {
+        result.error = error.stderr ? String(error.stderr).trim() : error.message;
+      }
+    }
+  }
+  return results;
+}