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

package/src/v2/evidence/collector.js

@@ -17,21 +17,32 @@ export function collectCommandEvidence({
   kind = "command",
   grade = "L2",
   coverage = null,
+  redact = [],
 }) {
   const logsDir = join(runtimeDir, "runs", runId, "logs");
   mkdirSync(logsDir, { recursive: true });
   const logName = `${step}-${attempt}.log`;
   const logPath = join(logsDir, logName);
+  // Redaction (iteration 08, C6): patterns from the run config are applied
+  // to worker output before it becomes evidence. The digest binds the
+  // redacted text — what is on disk is what was hashed.
+  const scrub = (text) => {
+    let out = String(text ?? "");
+    for (const pattern of redact) {
+      out = out.replace(pattern, "<REDACTED>");
+    }
+    return out;
+  };
   const logBody = [
-    `command: ${execResult.command}`,
+    `command: ${scrub(execResult.command)}`,
     `exitCode: ${execResult.exitCode}`,
     `signal: ${execResult.signal}`,
     `timedOut: ${execResult.timedOut}`,
     `spawnError: ${execResult.spawnError}`,
     "--- stdout ---",
-    execResult.stdout,
+    scrub(execResult.stdout),
     "--- stderr ---",
-    execResult.stderr,
+    scrub(execResult.stderr),
   ].join("\n");
   writeFileSync(logPath, logBody, "utf8");
   const digest = `sha256:${createHash("sha256").update(logBody, "utf8").digest("hex")}`;

package/src/v2/presets/release-readback.yaml

@@ -0,0 +1,36 @@
+# Release readback lane (iteration 08, C8). The kernel still has no deploy
+# capability (invariant 20): every production action stays a human's. What
+# this lane fixes is the bookkeeping around it — a pilot go-live was
+# ledgered by hand as forty "step N readback" commits. Here each step is a
+# read-only command that proves the world is in the expected state; every
+# failure stops for a human (maxAttempts 1, no fix edge), and evidence is
+# graded L4 because it was read from the real environment.
+#
+# Shape: preflight (before the action) → [human performs the action; the
+# risk preset "release" stops here] → apply-readback (proves it happened) →
+# observe (proves it is healthy) → wait-close (human closes the window).
+kind: workflow
+version: 1
+name: release-readback
+entry: preflight
+steps:
+  - id: preflight
+    worker: readback
+    readonly: true
+    grade: L4
+  - id: apply-readback
+    worker: readback
+    readonly: true
+    grade: L4
+  - id: observe
+    worker: observe
+    readonly: true
+    grade: L4
+  - id: wait-close
+terminal:
+  - wait-close
+budgets:
+  maxAttempts:
+    preflight: 1
+    apply-readback: 1
+    observe: 1

package/src/v2/presets/risk/release.yaml

@@ -0,0 +1,21 @@
+# Release lane (iteration 08, C8): pairs with the release-readback workflow.
+# Automation stops before apply-readback — that pause is where the human
+# performs the production action — and the window may only close behind L4
+# evidence read from the real environment. (No finding floor: the lane has
+# no reviewer step, and a rule that cannot be satisfied is not a gate.)
+kind: risk-preset
+version: 1
+name: release
+stopAt:
+  - apply-readback
+policies:
+  - kind: policy
+    version: 1
+    name: close-evidence-floor
+    type: transition
+    appliesTo: enter-wait-close
+    enforcement: LOCAL_ENFORCED
+    rule:
+      evidence.exists:
+        kind: command
+        minGrade: L4

package/src/v2/runtime/cache.js

@@ -0,0 +1,124 @@
+// Verification reuse and incremental review (iteration 08, C7).
+//
+// Reuse: a verify step whose input is byte-identical to one that already
+// passed — same tree, same worker command, same envelope — is not re-run; the
+// earlier evidence is referenced and the reuse is visible in the ledger
+// (`reused`) and in status. Only *passed* results are ever reused; a failure
+// always runs again. Real number: the deploy campaign's envelope-side cache
+// cut verify from 25 to 13 minutes per round.
+//
+// Incremental review: a reviewer is told which candidate the last review
+// looked at (when it is an ancestor of the current one) so it can focus on
+// the delta instead of re-reading the whole change every round.
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { EventLedger } from "../storage/event-ledger.js";
+import { canonicalJson } from "../storage/event-ledger.js";
+
+function git(cwd, args) {
+  return execFileSync("git", ["-C", cwd, ...args], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  }).trim();
+}
+
+export function treeHash(worktreePath) {
+  return git(worktreePath, ["rev-parse", "HEAD^{tree}"]);
+}
+
+export function cacheKey({ tree, worker, adapterSpec, adapterName, envelopeDigest }) {
+  const body = canonicalJson({
+    tree,
+    worker,
+    adapter: adapterSpec ?? adapterName ?? null,
+    envelope: envelopeDigest ?? null,
+  });
+  return `sha256:${createHash("sha256").update(body, "utf8").digest("hex")}`;
+}
+
+function eachLedger(repoRoot, { excludeRun = null } = {}) {
+  const runsDir = join(repoRoot, ".buildbeat", "runtime", "runs");
+  const out = [];
+  if (!existsSync(runsDir)) {
+    return out;
+  }
+  for (const entry of readdirSync(runsDir).sort()) {
+    if (entry === excludeRun) {
+      continue;
+    }
+    const path = join(runsDir, entry, "events.jsonl");
+    if (!existsSync(path)) {
+      continue;
+    }
+    const ledger = EventLedger.open(path);
+    if (ledger.state.run) {
+      out.push(ledger);
+    }
+  }
+  return out;
+}
+
+// Latest passed command evidence carrying this cache key, across the
+// repository's runs (the current run included: a re-verify after an
+// unrelated fix step on the same tree is the common case).
+export function findReusableEvidence(repoRoot, key) {
+  let best = null;
+  for (const ledger of eachLedger(repoRoot)) {
+    for (const event of ledger.events) {
+      if (
+        event.type === "EVIDENCE_RECORDED" &&
+        event.data.cacheKey === key &&
+        event.data.status === "passed" &&
+        event.data.kind === "command" &&
+        !event.data.reused
+      ) {
+        if (!best || event.ts > best.ts) {
+          best = { run: ledger.state.run.id, evidenceRef: event.data.evidenceRef, digest: event.data.digest, grade: event.data.grade, ts: event.ts };
+        }
+      }
+    }
+  }
+  return best;
+}
+
+// The most recent review evidence for this work whose subject is an ancestor
+// of (and not equal to) the current head — the anchor for an incremental
+// review. Null when there is no such review.
+export function lastReviewedCandidate(repoRoot, workId, worktreePath, head) {
+  let best = null;
+  for (const ledger of eachLedger(repoRoot)) {
+    if (ledger.state.run.work !== workId) {
+      continue;
+    }
+    for (const event of ledger.events) {
+      if (event.type !== "EVIDENCE_RECORDED" || event.data.kind !== "review") {
+        continue;
+      }
+      const subject = event.data.subject;
+      if (!subject || subject === head) {
+        continue;
+      }
+      if (best && event.ts <= best.ts) {
+        continue;
+      }
+      let ancestor = false;
+      try {
+        execFileSync("git", ["-C", worktreePath, "merge-base", "--is-ancestor", subject, head], { stdio: "ignore" });
+        ancestor = true;
+      } catch {
+        ancestor = false;
+      }
+      if (ancestor) {
+        best = { candidate: subject, run: ledger.state.run.id, evidenceRef: event.data.evidenceRef, ts: event.ts };
+      }
+    }
+  }
+  if (!best) {
+    return null;
+  }
+  return { candidate: best.candidate, run: best.run, evidenceRef: best.evidenceRef, range: `${best.candidate}..${head}` };
+}

package/src/v2/runtime/env-contract.js

@@ -49,8 +49,42 @@ export function checkRequires(requires) {
   const problems = [];
   const checked = [];
   for (const entry of requires ?? []) {
+    // Probe entries (iteration 08, C10): an environment fact that is not a
+    // binary version — "Redis answers PING on the target", "python on the
+    // host is >= 3.9" — expressed as a shell command whose exit code (and
+    // optionally output) must match. Absorbed from the first-proof rerun:
+    // Redis < 7 and Python 3.6 on the target burned a window each because
+    // nothing checked them before the run.
+    if (entry && typeof entry === "object" && typeof entry.probe === "string" && entry.probe.length > 0) {
+      const label = entry.name ?? entry.probe;
+      const run = spawnSync("bash", ["-lc", entry.probe], { encoding: "utf8", timeout: entry.timeoutMs ?? 30_000 });
+      if (run.error) {
+        problems.push(`${label}: probe could not run (${run.error.code ?? run.error.message})`);
+        continue;
+      }
+      const output = `${run.stdout ?? ""}\n${run.stderr ?? ""}`;
+      if (run.status !== 0) {
+        problems.push(`${label}: probe exited ${run.status}${output.trim() ? ` — ${output.trim().split("\n").slice(-1)[0].slice(0, 160)}` : ""}`);
+        continue;
+      }
+      if (entry.expect !== undefined) {
+        let matcher;
+        try {
+          matcher = new RegExp(String(entry.expect));
+        } catch {
+          problems.push(`${label}: expect ${JSON.stringify(entry.expect)} is not a valid regular expression`);
+          continue;
+        }
+        if (!matcher.test(output)) {
+          problems.push(`${label}: probe output does not match expect ${JSON.stringify(entry.expect)}`);
+          continue;
+        }
+      }
+      checked.push({ command: label, version: null, probe: true });
+      continue;
+    }
     if (!entry || typeof entry !== "object" || typeof entry.command !== "string" || entry.command.length === 0) {
-      problems.push(`requires entries need a command name, got: ${JSON.stringify(entry)}`);
+      problems.push(`requires entries need a command name or a probe, got: ${JSON.stringify(entry)}`);
       continue;
     }
     // A generous timeout: a missing binary fails instantly (ENOENT), while a

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/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;
+}