@feigi/fleet-ctl 3.82.12 → 3.82.14

package/scripts/recipe-check.mjs

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+// Run the Recipe's Check step and the Test entrypoint against the staged tree,
+// and record that both passed — the record `ledger.mjs settle --from-report`
+// requires before it settles an implementer's or a fix-applier's report.
+//
+//   recipe-check.mjs --member <name> --testCmd <command> [--reports <dir>]
+//
+// Run from the member's worktree, after `git add` and before the commit and
+// push, and again after any content change or rebase. Reached through the
+// Resolver: `~/.fleet/bin/fleet-run recipe-check.mjs ...`.
+//
+// `--member` is the `impl-<N>[-x]` or `fix-pr-<M>[-x]` name the member was
+// dispatched as. `--testCmd` is the Test entrypoint exactly as the member was
+// handed it, a shell command run from the worktree root: the member's runner
+// already goes through the suite-slot wrapper, so this script adds none of its
+// own and never runs the suite a second time. The Check step is not an
+// argument: it is read off the repository's Recipe cache, through
+// derive-testcmd.sh, the one reader of it. `--reports` is the directory the
+// member's report is written to, `<scratch>/reports`; omitted, the default
+// scratch root's.
+//
+// Steps, in this order:
+//
+//   1  read the Check step and the Test entrypoint off the Recipe cache. A
+//      worktree with no usable Recipe has no Check step to run: exit 2,
+//      nothing run, nothing written. Settle reads the same cache from the
+//      ledger's repository, where derive-testcmd.sh's probes of the Test
+//      entrypoint can answer otherwise, so it skips its gate only where its
+//      own read refuses.
+//   2  `git write-tree`: the tree id of the staged index. The commands run in
+//      the working tree, so it must hold exactly that tree: an unstaged change
+//      to a tracked file, or an untracked file no ignore rule covers, is a
+//      refusal, exit 2 — a green record would otherwise name a tree that never
+//      ran. Then the reports directory is created, before anything runs.
+//   3  the Check step, `sh -c` from the worktree root. A Check step of
+//      `true` is recorded as green without being run.
+//   4  the Test entrypoint, the same way — only when the Check step passed.
+//
+// The commands' own output passes through on stdout and stderr as it arrives.
+//
+// THE RECORD is `<reports>/<member>.check.json`, beside the member's report
+// (report-files.mjs names the path and reads it back), written whole and
+// atomically once both commands have settled:
+//
+//   { member, tree, check: {command, ran, exitCode, pass, fail},
+//                   test:  {command, ran, exitCode, pass, fail} }
+//
+//   tree       the `git write-tree` of step 2. Settle compares it with the
+//              reported head's own tree, so a message-only amend keeps the
+//              record valid and a rebase onto a moved base, or any content
+//              change, does not.
+//   ran        false for a Check step of `true`, and for a command skipped
+//              because the Check step failed (its exitCode is then null).
+//   exitCode   the command's status, a signal's number plus 128.
+//   pass, fail the counts the runner's summary printed — a `# pass N` /
+//              `ℹ fail N` line, or `N passed`/`N failed`/`N passing`/`N
+//              failing` — null where it printed none.
+//
+// A record is written whenever a command ran and failed, so a red run
+// replaces an older record rather than leaving it standing; it records the
+// failure, and settle refuses on it. A record is a claim, no attestation: the
+// member produces it, and nothing here stops a forged one.
+//
+// Exit status: 0 both commands passed and the record is written; 1 a command
+// failed — the record says which, and the script's stderr names it; 2 a
+// refusal that ran nothing and wrote nothing (usage, no usable Recipe, git
+// could not be read, a working tree that is not the staged tree, a reports
+// directory that could not be created); 75 the Test entrypoint printed exit
+// 75 — the suite wrapper found no slot and launched nothing, which is no test
+// result — so no record is written, and the same command is to be run again.
+
+import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { constants as osConstants } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { makeDie, defineFlags, writeAll } from "./arg.mjs";
+import { FleetDirUnresolvable } from "./fleet-dir.mjs";
+import { gitEnv } from "./git-env.mjs";
+import { isCLI } from "./is-cli.mjs";
+import { parseMember } from "./ledger-grammar.mjs";
+import { checkRecordPathIn, defaultScratch, reportsDir } from "./report-files.mjs";
+
+const NAME = "recipe-check";
+const USAGE = "usage: recipe-check.mjs --member <name> --testCmd <command> [--reports <dir>]";
+const DERIVE = join(dirname(fileURLToPath(import.meta.url)), "derive-testcmd.sh");
+const GIT_TIMEOUT_MS = 30_000;
+// What the suite wrapper exits with when it found no slot and launched nothing.
+const NO_SLOT = 75;
+// The tail of a command's output kept for the counts: a runner prints its
+// summary last.
+const TAIL_BYTES = 256 * 1024;
+
+const ANSI = /\x1b\[[0-9;]*[A-Za-z]/g;
+
+/** `{pass, fail}` the output's summary printed, each null where it printed no
+ * count. The last count of a kind wins: a summary follows the lines it sums. */
+export function parseCounts(output) {
+  const text = output.replace(ANSI, "");
+  const last = (patterns) => {
+    for (const re of patterns) {
+      const all = [...text.matchAll(re)];
+      if (all.length > 0) return Number(all.at(-1)[1]);
+    }
+    return null;
+  };
+  const count = (word, loose) => last([new RegExp(`^[ \\t]*(?:#|ℹ)[ \\t]+${word}[ \\t]+(\\d+)[ \\t]*$`, "gm"), loose]);
+  return {
+    pass: count("pass", /\b(\d+)[ \t]+(?:passed|passing)\b/g),
+    fail: count("fail", /\b(\d+)[ \t]+(?:failed|failing)\b/g),
+  };
+}
+
+async function cli() {
+  const die = makeDie(NAME);
+  const { arg, sweep, stray } = defineFlags(die, { flags: { member: "value", testCmd: "value", reports: "value" } });
+  sweep();
+  stray();
+  const member = arg("member");
+  const testCmd = arg("testCmd");
+  let reports = arg("reports");
+  if (member === null || testCmd === null) die(USAGE);
+  const parsed = parseMember(member);
+  if (parsed === null || (parsed.family !== "impl" && parsed.family !== "fix-pr")) {
+    die(`--member '${member}' is not an impl-<N>[-x] or fix-pr-<M>[-x] name — ${USAGE}`);
+  }
+  if (testCmd.trim() === "") die(`--testCmd is empty — ${USAGE}`);
+  if (reports === null) {
+    try {
+      reports = reportsDir(defaultScratch());
+    } catch (e) {
+      if (!(e instanceof FleetDirUnresolvable)) throw e;
+      die(`no --reports, and the scratch root could not be resolved — ${e.message}`);
+    }
+  }
+
+  const env = gitEnv();
+  // A reader that did not answer: the refusal names it, its exit status and
+  // its own reason.
+  const noAnswer = (what, r) => {
+    const why = (r.error?.message ?? r.stderr ?? "").trim();
+    die(`${what} did not answer${r.status === null ? "" : ` (exit ${r.status})`}${why ? `: ${why}` : ""}; nothing run, nothing written`);
+  };
+  const gitOut = (what, args) => {
+    const r = spawnSync("git", args, { encoding: "utf8", env, timeout: GIT_TIMEOUT_MS });
+    if (r.status !== 0) noAnswer(what, r);
+    return r.stdout.trim();
+  };
+  const top = gitOut("git rev-parse --show-toplevel", ["rev-parse", "--show-toplevel"]);
+
+  // 1: the Recipe. Exit 1 is derive-testcmd.sh's refusal about the cache; any
+  // other failure is a reader that could not run.
+  const field = (name) => {
+    const r = spawnSync("sh", [DERIVE, top, name], { encoding: "utf8", env, timeout: GIT_TIMEOUT_MS });
+    if (r.status === 0) return r.stdout.replace(/\n$/, "");
+    if (r.status === 1) {
+      die(`this worktree has no usable Recipe, so there is no Check step to run; settle reads the Recipe from the ledger's repository and gates the report wherever that read finds one; nothing run, nothing written — ${(r.stderr ?? "").trim()}`);
+    }
+    noAnswer(`derive-testcmd.sh ${name}`, r);
+  };
+  const checkCmd = field("check");
+  field("test");
+
+  // 2: the staged tree, and a working tree that holds exactly it.
+  const tree = gitOut("git write-tree", ["write-tree"]);
+  const strays = [
+    ...gitOut("git diff --name-only", ["-C", top, "diff", "--name-only"]).split("\n"),
+    ...gitOut("git ls-files --others --exclude-standard", ["-C", top, "ls-files", "--others", "--exclude-standard", "--directory"]).split("\n"),
+  ].filter((p) => p !== "");
+  if (strays.length > 0) {
+    const shown = strays.slice(0, 10).join(", ") + (strays.length > 10 ? `, and ${strays.length - 10} more` : "");
+    die(`the working tree is not the staged tree — unstaged or untracked: ${shown}. The commands run in the working tree and the record names the staged tree, so stage, remove or ignore these first; nothing run, nothing written`);
+  }
+  try {
+    mkdirSync(reports, { recursive: true });
+  } catch (e) {
+    die(`could not create ${reports}: ${e.code ?? e.message}; nothing run, nothing written`);
+  }
+
+  // 3 and 4: the commands. A reader that closes this script's stdout or
+  // stderr early stops only the passthrough: the commands still run to their
+  // end and the record is still written. Any other stream error stays fatal.
+  for (const stream of [process.stdout, process.stderr]) {
+    stream.on("error", (e) => {
+      if (e.code !== "EPIPE") throw e;
+    });
+  }
+  const check = checkCmd.trim() === "true"
+    ? { command: checkCmd, ran: false, exitCode: 0, pass: null, fail: null }
+    : await runCommand(checkCmd, top, env);
+  const test = check.exitCode === 0
+    ? await runCommand(testCmd, top, env)
+    : { command: testCmd, ran: false, exitCode: null, pass: null, fail: null };
+
+  // process.exitCode, never process.exit(): the command's own output is still
+  // draining through async pipe writes, and exit discards what is queued.
+  const say = (line) => writeAll(2, `\n${NAME}: ${line}\n`);
+  if (test.exitCode === NO_SLOT) {
+    say(`the Test entrypoint exited ${NO_SLOT}: no suite slot was free and nothing was launched — run the same command again; no record written`);
+    process.exitCode = NO_SLOT;
+    return;
+  }
+
+  const path = checkRecordPathIn(reports, member);
+  const tmp = `${path}.${process.pid}.tmp`;
+  try {
+    writeFileSync(tmp, `${JSON.stringify({ member, tree, check, test })}\n`);
+    renameSync(tmp, path);
+  } catch (e) {
+    rmSync(tmp, { force: true });
+    die(`could not write ${path}: ${e.code ?? e.message}`);
+  }
+
+  if (check.exitCode !== 0) {
+    say(`the Check step exited ${check.exitCode}; red record written to ${path}, so settle refuses it — fix the cause and run again`);
+    process.exitCode = 1;
+  } else if (test.exitCode !== 0) {
+    say(`the Test entrypoint exited ${test.exitCode}; red record written to ${path}, so settle refuses it — fix the cause and run again`);
+    process.exitCode = 1;
+  } else {
+    say(`green on tree ${tree}; record written to ${path}`);
+  }
+}
+
+if (isCLI(import.meta.url)) await cli();
+
+// One command, `sh -c` from `cwd`, its output passed through and its tail kept
+// for the counts. A signal that stops it is its number plus 128.
+function runCommand(command, cwd, env) {
+  return new Promise((resolve) => {
+    let tail = "";
+    const keep = (chunk) => {
+      tail = (tail + chunk).slice(-TAIL_BYTES);
+    };
+    const child = spawn("sh", ["-c", command], { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+    const handlers = ["SIGTERM", "SIGINT", "SIGHUP"].map((sig) => [sig, () => child.kill(sig)]);
+    for (const [sig, h] of handlers) process.on(sig, h);
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (d) => {
+      keep(d);
+      process.stdout.write(d);
+    });
+    child.stderr.on("data", (d) => {
+      keep(d);
+      process.stderr.write(d);
+    });
+    const done = (exitCode) => {
+      for (const [sig, h] of handlers) process.off(sig, h);
+      const { pass, fail } = parseCounts(tail);
+      resolve({ command, ran: true, exitCode, pass, fail });
+    };
+    // A spawn that never started (a missing `sh`) is the command not passing.
+    child.on("error", (e) => {
+      process.stderr.write(`${NAME}: could not start sh: ${e.message}\n`);
+      done(127);
+    });
+    child.on("close", (code, signal) => done(code ?? 128 + (osConstants.signals[signal] ?? 0)));
+  });
+}

package/scripts/report-files.mjs

@@ -9,6 +9,10 @@
 // SCHEMAS. The review runner and every member outside those four families
 // have no schema, so no file to look up.
 //
+// The Check-step record beside a report, `<reports>/<member>.check.json`, is
+// looked up here the same way: recipe-check.mjs writes it, and this module
+// only names where it lives and reads it back.
+//
 // This module only looks files up: it writes none, and creates no scratch
 // root.
 
@@ -32,6 +36,66 @@ export const reportsDir = (scratch) => join(scratch, "reports");
 
 export const reportPath = (scratch, member) => join(reportsDir(scratch), `${member}.json`);
 
+/** Where `member`'s Check-step record sits in reports directory `dir`: the
+ * sibling of its report, `<dir>/<member>.check.json`. recipe-check.mjs writes
+ * it, `ledger.mjs settle --from-report` reads it. */
+export const checkRecordPathIn = (dir, member) => join(dir, `${member}.check.json`);
+
+const HEX_TREE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+// One command's half of a record: the command string, whether it ran (a Check
+// step of `true` is recorded as green without running), the exit status it
+// ended with — null when it never ran because an earlier one failed — and
+// the pass/fail counts its output printed, null where the runner printed none.
+function commandViolation(path, c) {
+  if (!isObject(c)) return `${path}: not an object`;
+  if (typeof c.command !== "string" || c.command === "") return `${path}.command: not a non-empty string`;
+  if (typeof c.ran !== "boolean") return `${path}.ran: not a boolean`;
+  if (c.exitCode !== null && !Number.isInteger(c.exitCode)) return `${path}.exitCode: not an integer or null`;
+  for (const k of ["pass", "fail"]) {
+    if (c[k] !== null && !(Number.isInteger(c[k]) && c[k] >= 0)) return `${path}.${k}: not a non-negative integer or null`;
+  }
+  return null;
+}
+
+// A file's text as `{text}`, or the answer both readers below give for a file
+// that is not there (`absent`) or cannot be read (`invalid`).
+function readAt(path) {
+  try {
+    return { text: readFileSync(path, "utf8") };
+  } catch (e) {
+    if (e.code === "ENOENT" || e.code === "ENOTDIR") return { state: "absent", path };
+    return { state: "invalid", path, violation: `$: unreadable (${e.code ?? e.message})` };
+  }
+}
+
+/** The Check-step record of `member` in reports directory `dir`, the way
+ * readReportIn() answers for a report: `{state: "ok", path, record}`,
+ * `{state: "invalid", path, violation}` for a file that exists and is
+ * unreadable, not JSON, or the wrong shape, or `{state: "absent", path}`.
+ * The record is `{member, tree, check, test}`, `tree` the `git write-tree`
+ * of the index the two commands ran against and `check`/`test` each
+ * `{command, ran, exitCode, pass, fail}`. */
+export function readCheckRecordIn(dir, member) {
+  const path = checkRecordPathIn(dir, member);
+  const read = readAt(path);
+  if (read.text === undefined) return read;
+  let record;
+  try {
+    record = JSON.parse(read.text);
+  } catch (e) {
+    return { state: "invalid", path, violation: `$: not JSON (${e.message})` };
+  }
+  if (!isObject(record)) return { state: "invalid", path, violation: "$: not an object" };
+  if (record.member !== member) return { state: "invalid", path, violation: `$.member: ${JSON.stringify(record.member)} is not ${member}` };
+  if (typeof record.tree !== "string" || !HEX_TREE.test(record.tree)) {
+    return { state: "invalid", path, violation: "$.tree: not a full lowercase hex tree id" };
+  }
+  const violation = commandViolation("$.check", record.check) ?? commandViolation("$.test", record.test);
+  return violation === null ? { state: "ok", path, record } : { state: "invalid", path, violation };
+}
+
 /** The report file of `member` under `scratch`, read and checked against its
  * family's schema: `{state: "ok", path, report}`, `{state: "invalid", path,
  * violation}` for a file that exists and is unreadable, not JSON, or the
@@ -46,14 +110,9 @@ export function readReportIn(dir, member) {
   const family = reportFamily(member);
   if (family === null) throw new Error(`no report schema for '${member}'`);
   const path = join(dir, `${member}.json`);
-  let text;
-  try {
-    text = readFileSync(path, "utf8");
-  } catch (e) {
-    if (e.code === "ENOENT" || e.code === "ENOTDIR") return { state: "absent", path };
-    return { state: "invalid", path, violation: `$: unreadable (${e.code ?? e.message})` };
-  }
-  const parsed = parseReport(text);
+  const read = readAt(path);
+  if (read.text === undefined) return read;
+  const parsed = parseReport(read.text);
   const violation = parsed.violation ?? validate(SCHEMAS[family], parsed.value);
   return violation === null ? { state: "ok", path, report: parsed.value } : { state: "invalid", path, violation };
 }

package/skills/next-ticket/SKILL.md

@@ -94,8 +94,7 @@ Come back here. The sizing path hands off; this step always follows.
 
 ```bash
 git fetch origin && git rebase origin/main   # rebase, never merge main in
-<test command>                              # the Recipe's Test entrypoint; re-run after rebasing
-<check command>                             # the Recipe's Check step; re-run after rebasing
+~/.fleet/bin/fleet-run recipe-check.mjs --member <your name> --testCmd "<test command>" --reports <scratch>/reports   # re-run after any content change or rebase
 git push --force-with-lease -u origin HEAD
 gh pr create --base main --body "…
 
@@ -103,6 +102,17 @@ Closes #N"
 gh pr edit --add-label <patch|minor|major>   # own command, own exit status
 ```
 
+`recipe-check.mjs` runs the Recipe's Check step, then `<test command>` — the
+Recipe's Test entrypoint, as you were handed it, which runs through the suite
+slot already — against the staged tree, and records both results beside your
+report; the controller refuses a report whose head's tree has no green record.
+`<your name>` is the `impl-<N>[-x]` you were dispatched as. The record is keyed
+to the tree, so run it after `git add` and before you commit, and again after
+any content change or rebase: a message-only amend keeps it valid, a changed
+tree does not. A non-zero exit is not a pass, and exit 75 is no test result —
+no slot was free and nothing ran, so run it again. A solo session has no report
+to settle against: it runs the Check step and the Test entrypoint themselves.
+
 **A red Check step is yours to judge.** Read what it reports and fix every
 finding in a file the PR changes, including lines you did not edit — CI checks
 whole files. Never edit a file the PR does not otherwise change: a finding there