@intentius/chant 0.124.32 → 0.124.34

package/src/workspace/ci-list.schema.json

@@ -284,9 +284,10 @@
                         "pass",
                         "fail",
                         "pending",
+                        "unbuilt",
                         "unrecorded"
                       ],
-                      "description": "pass and fail come from the tags (a green tag records the phases that passed, a revoked tag the one that failed) or, for an undecided commit, from the forge under --forge, or from the signed Op runs on the local chant/lifecycle when the source is chant runs (#4044). pending is such a read with runs still going or not yet reported. unrecorded means no tag holds the result and nothing was read."
+                      "description": "pass and fail come from the tags (a green tag records the phases that passed, a revoked tag the one that failed) or, for an undecided commit, from the forge under --forge, or from the signed Op runs on the local chant/lifecycle when the source is chant runs (#4044). pending is such a read with runs still going or not yet reported. unbuilt (#4169, chant 0.124.33 and newer) is such a read whose runs were cancelled. unrecorded means no tag holds the result and nothing was read."
                     },
                     "runs": {
                       "type": "array",
@@ -406,6 +407,39 @@
                   }
                 ]
               },
+              "record": {
+                "description": "Added within contract version 1 by #4169, written by chant 0.124.33 and newer. What the commit's _ci/<sha>.json record on the local chant/lifecycle says, the tick's last word on it, or null when it has none. state is green, red, unbuilt or pending. reason, coveredBy and culprit come from the required phases: why a phase is unbuilt or still pending (cancelled, superseded, retrying, requested, request-unserved or aged-out), the newer commit whose run covers a superseded phase, and the commit a bisect found broke a phase. Each is absent when no phase has one.",
+                "oneOf": [
+                  {
+                    "type": "null"
+                  },
+                  {
+                    "type": "object",
+                    "required": [
+                      "state"
+                    ],
+                    "properties": {
+                      "state": {
+                        "enum": [
+                          "green",
+                          "red",
+                          "unbuilt",
+                          "pending"
+                        ]
+                      },
+                      "reason": {
+                        "type": "string"
+                      },
+                      "coveredBy": {
+                        "type": "string"
+                      },
+                      "culprit": {
+                        "type": "string"
+                      }
+                    }
+                  }
+                ]
+              },
               "ignored": {
                 "type": "array",
                 "description": "Added within contract version 1 by #4031, written by chant 0.124.28 and newer. The commit's ci tags that do not count for want of a valid statement signed by a runner key. A tag on any commit that is not a strict first-parent ancestor of ci.green.signedSince needs one; empty when signedSince is not set. state, green and revoked count only the tags that are not ignored.",

package/src/workspace/ci-report-url.test.ts

@@ -44,6 +44,8 @@ const repoTemplate = repoFixture(() => {
   git(root, "symbolic-ref", "HEAD", "refs/heads/main");
   git(root, "config", "user.name", "t");
   git(root, "config", "user.email", "t@example.com");
+  git(root, "config", "gc.auto", "0");
+  git(root, "config", "maintenance.auto", "false");
   writeFiles(root, { "chant.workspace.json": declaration(MEMBERS), ".gitignore": ".chant/pr/\n", "app/a.txt": "a\n" });
   const commit = (msg: string) => {
     execFileSync("git", ["-c", "commit.gpgsign=false", "add", "-A"], { cwd: root, stdio: "ignore" });
@@ -77,10 +79,13 @@ async function cli(cwd: string, argv: string[], run: (ctx: CommandContext) => Pr
   return { code, out: out.join("\n"), err: err.join("\n") };
 }
 
+// A job image of its own, so the job gets no setup lines: the default image's
+// OpenTofu install downloads from the network on a runner without tofu, as
+// in ci-run.test.ts.
 const runPlan = (w: ReturnType<typeof workspace>, extra: string[] = []) =>
   cli(
     w.app,
-    ["ci", "run", "plan", "--env", "prod", "--base", w.base, "--pr", "7", "--forge", "forgejo", "--no-status", "--chant", w.chant, "-o", join(scratchDir("chant-report-url-out-"), "pr"), ...extra],
+    ["ci", "run", "plan", "--image", "chant-ci-report-url-test:local", "--env", "prod", "--base", w.base, "--pr", "7", "--forge", "forgejo", "--no-status", "--chant", w.chant, "-o", join(scratchDir("chant-report-url-out-"), "pr"), ...extra],
     runCiRun,
   );
 

package/src/workspace/ci-run-index.schema.json

@@ -23,7 +23,7 @@
       "if": { "properties": { "status": { "const": "fail" } } },
       "then": { "required": ["failure"], "properties": { "failure": { "type": "object" } } },
       "properties": {
-        "job": { "enum": ["plan", "apply"] },
+        "job": { "enum": ["plan", "apply", "record"], "description": "record (#4168, chant 0.124.33 and newer): the merge record job." },
         "pr": { "type": ["integer", "null"], "minimum": 1, "description": "The pull or merge request number: the one the job's report names, else --pr. null when neither has one." },
         "commit": { "type": "string", "pattern": "^[0-9a-f]{40,64}$", "description": "The full commit the job ran at." },
         "status": { "enum": ["ok", "fail"] },

package/src/workspace/ci-run-index.ts

@@ -44,7 +44,7 @@ export const CI_RUN_INDEX_LIMIT = 200;
 
 /** One job the runner ran. */
 export interface CiRunIndexEntry {
-  job: "plan" | "apply";
+  job: "plan" | "apply" | "record";
   /** The pull request, or null when the job found none. */
   pr: number | null;
   commit: string;

package/src/workspace/ci-run.test.ts

@@ -206,7 +206,11 @@ describe("the job as an Op (#4094)", () => {
       expect(ciLoopOptions(args)).toEqual({ gate: "infra", waveGate: "release" });
     }
     const [plan, apply] = prLoopJobs("forgejo", "prod", ciLoopOptions(parseArgs(["ci", "run", "apply", "--env", "prod", "--wave-gate", "release"])));
-    expect(apply!.command).toContain("--require-review --wave-gate release --resume .chant/pr-resume/pr-apply.json");
+    // #4168: no --require-review unless asked for.
+    expect(apply!.command).toContain(" --wave-gate release --resume .chant/pr-resume/pr-apply.json");
+    expect(apply!.command).not.toContain("--require-review");
+    const reviewed = prLoopJobs("forgejo", "prod", ciLoopOptions(parseArgs(["ci", "run", "apply", "--env", "prod", "--wave-gate", "release", "--require-review"])))[1]!;
+    expect(reviewed.command).toContain("--require-review --wave-gate release --resume .chant/pr-resume/pr-apply.json");
     expect(apply!.command).not.toContain("--wave ");
     expect(plan!.command).toContain("--wave-gate release");
     expect(plan!.command).not.toContain("--wave ");
@@ -294,7 +298,7 @@ describe("chant ci run, then ci tick from runs (#4094)", () => {
 
     expect(apply.status).toBe("ok");
     const applyArgs = readFileSync(join(reports, "apply", "pr-apply.args"), "utf-8").trimEnd().split("\n");
-    expect(applyArgs).toEqual(["components", "pr-apply", "--base", base, "--env", "prod", "--gate", "pr-apply", "--output", ".chant/pr", "--forge", "forgejo", "--member", "app", "--require-review", "--resume", ".chant/pr-resume/pr-apply.json"]);
+    expect(applyArgs).toEqual(["components", "pr-apply", "--base", base, "--env", "prod", "--gate", "pr-apply", "--output", ".chant/pr", "--forge", "forgejo", "--member", "app", "--resume", ".chant/pr-resume/pr-apply.json"]);
     expect(formatCiRun(apply)).toContain("signed by chant-runner");
   });
 
@@ -310,6 +314,17 @@ describe("chant ci run, then ci tick from runs (#4094)", () => {
     expect(record.phases.apply![0]).toMatchObject({ name: "pr-apply", opRun: { id: apply.record.id, signer: "chant-runner" } });
   });
 
+  test("under the isolated-runners security group an apply job requires a runner-start statement, and a plan job does not (#4168)", async () => {
+    const { root, app, base } = workspace();
+    writeFiles(root, { "chant.workspace.json": declaration([{ name: "app", dir: "app", kind: "other", because: "the app", security: ["isolated-runners"] }], { ci: { green: GREEN } }) });
+    git(root, "commit", "-qam", "isolated-runners");
+    git(root, "push", "-q", "origin", "main");
+    const job = (j: "plan" | "apply") =>
+      ciRun({ image: JOB_IMAGE, cwd: app, job: j, env: "prod", forge: "github", base, ...(j === "plan" ? { pr: 7 } : {}), chant: fakeChant(), hostEnv: HOST, output: join(scratchDir("chant-ci-run-out-"), "pr"), push: false });
+    await expect(job("apply")).rejects.toThrow(/--require-runner-start needs a forge job to check/);
+    expect((await job("plan")).status).toBe("ok");
+  });
+
   test("a failing job is recorded failed, and a key from the environment that trust.json does not list leaves it unsigned, quietly", async () => {
     const { root, app, base } = workspace();
     const stranger = runnerKey();
@@ -746,12 +761,14 @@ describe("a generated forge job runs ci run --in-place (#4156)", () => {
   // What a GitHub or Forgejo job has in its environment: the forge's run, job and attempt, and the secret.
   const FORGE = { GITHUB_RUN_ID: "4242", GITHUB_RUN_ATTEMPT: "2", GITHUB_JOB: "apply", GITHUB_REPOSITORY: "acme/estate", GITHUB_SERVER_URL: "http://forgejo.localhost" };
 
-  test("the generated job's line parses to the same job, and --in-place, --no-push, --no-require-review and --wave reach it", () => {
-    const [plan, apply] = prLoopJobs("forgejo", "prod", { events: true, reportUrl: "s3://b/p", requireReview: false, waveGate: "release", branch: "trunk" });
+  test("the generated job's line parses to the same job, and --in-place, --no-push, --require-review and --wave reach it", () => {
+    const [plan, apply] = prLoopJobs("forgejo", "prod", { events: true, reportUrl: "s3://b/p", requireReview: true, waveGate: "release", branch: "trunk" });
     expect(plan!.run.command).toBe('chant ci run plan --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge forgejo --wave-gate release --events-json --report-url "s3://b/p"');
     const args = parseArgs(apply!.run.command.replace(/"\$BASE_SHA"/, "b".repeat(40)).replace(/"/g, "").split(" ").slice(1).concat(["--wave", "2"]));
-    expect(args).toMatchObject({ ciInPlace: true, requireReview: false, wave: 2, waveGate: "release", branch: "trunk", eventsJson: true, reportUrl: "s3://b/p" });
-    expect(ciLoopOptions(args)).toEqual({ gate: "pr-apply", branch: "trunk", events: true, reportUrl: "s3://b/p", waveGate: "release", requireReview: false });
+    expect(args).toMatchObject({ ciInPlace: true, requireReview: true, wave: 2, waveGate: "release", branch: "trunk", eventsJson: true, reportUrl: "s3://b/p" });
+    expect(ciLoopOptions(args)).toEqual({ gate: "pr-apply", branch: "trunk", events: true, reportUrl: "s3://b/p", waveGate: "release", requireReview: true });
+    // --no-require-review, which pipelines generated before #4168 pass, is the default now.
+    expect(ciLoopOptions(parseArgs(["ci", "run", "apply", "--no-require-review"]))).toEqual({});
     expect(parseArgs(["ci", "run", "plan", "--no-push"]).noPush).toBe(true);
     // ci run rebuilds pr-apply from those options: the very command the job ran before #4156.
     expect(prLoopJobs("forgejo", "prod", ciLoopOptions(args))[1]!.command).toBe(apply!.command);
@@ -774,7 +791,7 @@ describe("a generated forge job runs ci run --in-place (#4156)", () => {
     expect(r.report).toBe(join(realpathSync(app), ".chant/pr"));
     expect(r.record.phases.map((p) => p.name)).toEqual(["apply"]);
     const argv = readFileSync(join(app, ".chant/pr/pr-apply.args"), "utf-8").trimEnd().split("\n");
-    expect(argv).toEqual(["components", "pr-apply", "--base", base, "--env", "prod", "--gate", "pr-apply", "--output", ".chant/pr", "--forge", "forgejo", "--member", "app", "--require-review", "--resume", ".chant/pr-resume/pr-apply.json"]);
+    expect(argv).toEqual(["components", "pr-apply", "--base", base, "--env", "prod", "--gate", "pr-apply", "--output", ".chant/pr", "--forge", "forgejo", "--member", "app", "--resume", ".chant/pr-resume/pr-apply.json"]);
     // The forge job's whole environment reaches the step, but never the runner key.
     const env = envFile(join(app, ".chant/pr"), "pr-apply");
     expect(env).toMatchObject({ NOT_FOR_JOBS: "leak", GITHUB_RUN_ID: "4242", BASE_SHA: base, GITHUB_SHA: sha });

package/src/workspace/ci-run.ts

@@ -1,5 +1,5 @@
 /**
- * `chant ci run plan|apply` (#4094, epic #4101): run one pull-request job as
+ * `chant ci run plan|record|apply` (#4094, epic #4101, record #4168): run one pull-request job as
  * a pipeline Op, the first slice of the chant runner.
  *
  * The job is the typed value `prLoopJobs` (../components/pr-pipeline.ts)
@@ -99,13 +99,22 @@ import { resolveMemberContext } from "./member-pipeline";
 import { signOpRunRecord } from "./trust/op-run-statement";
 import { gitTop } from "./tree";
 import { hostRunnerKey } from "./ci-runner-key";
+import { requireRunnerStart } from "./ci-runner-start";
+import { securityGroupsAt } from "./security";
 
-/** The two jobs a pull-request pipeline has. */
+/** The jobs a pull-request pipeline has: plan, and on merge record (#4168) or, opted in, apply. */
 export type CiJobName = PrLoopJob["jobName"];
-export const CI_JOB_NAMES: readonly CiJobName[] = ["plan", "apply"];
+export const CI_JOB_NAMES: readonly CiJobName[] = ["plan", "apply", "record"];
 
 /** The Op each job is recorded as, which `ci.green` phases match. */
-export const CI_JOB_OPS: Record<CiJobName, string> = { plan: "pr-plan", apply: "pr-apply" };
+export const CI_JOB_OPS: Record<CiJobName, string> = { plan: "pr-plan", apply: "pr-apply", record: "pr-record" };
+
+/** What each job's Op says it does. */
+const CI_JOB_OVERVIEWS: Record<CiJobName, string> = {
+  plan: "Plan the members this pull request reaches",
+  apply: "Apply the plan a reviewer approved",
+  record: "Record the plan on the merged commit; nothing applies",
+};
 
 /** Where a job the chant runner ran says it ran (#4094). */
 export const CHANT_RUNNER_ORIGIN: RunOrigin = { forge: "chant" };
@@ -255,7 +264,7 @@ export function ciJobOp(input: CiJobOpInput): OpConfig {
   const op = CI_JOB_OPS[input.job.jobName];
   return {
     name: op,
-    overview: input.job.jobName === "plan" ? "Plan the members this pull request reaches" : "Apply the plan a reviewer approved",
+    overview: CI_JOB_OVERVIEWS[input.job.jobName],
     labels: { Env: input.env, Pipeline: "pr", Job: input.job.jobName },
     phases,
   };
@@ -353,12 +362,12 @@ const STATUS_DESCRIPTION = 140;
 const cut = (text: string, max = STATUS_DESCRIPTION): string => (text.length > max ? `${text.slice(0, max - 3)}...` : text);
 
 /**
- * A job's status context: `chant/pr-plan` for the plan, and for the apply
+ * A job's status context: `chant/pr-plan` for the plan, `chant/pr-record` for the record (#4168), and for the apply
  * `chant/<gate>`, which is `chant/pr-apply` unless `--gate` renamed the gate.
  * pr-plan's own status is `chant/plan` (../pr-loop.ts), a different context.
  */
 export function ciStatusContext(job: CiJobName, gate?: string): string {
-  return job === "apply" ? `chant/${gate ?? PR_APPLY_GATE}` : `chant/${CI_JOB_OPS.plan}`;
+  return job === "apply" ? `chant/${gate ?? PR_APPLY_GATE}` : `chant/${CI_JOB_OPS[job]}`;
 }
 
 /**
@@ -483,6 +492,12 @@ export interface CiRunRequest {
    * `runOrigin: { forge: "local" }` and `runtime: "local"`.
    */
   local?: boolean;
+  /**
+   * `--require-runner-start` (#4147): refuse the job before its first step
+   * unless a runner-start statement, signed by a runner key
+   * `.chant/trust.json` at `base` lists, names this forge job.
+   */
+  requireRunnerStart?: boolean;
   /**
    * `--wave <k>` (#4003, #4156): the one wave a generated apply job runs, as
    * `pr-apply --wave <k>`. Needs `--wave-gate`.
@@ -648,6 +663,10 @@ export async function ciRun(req: CiRunRequest): Promise<CiRunResult> {
   const found = jobs.find((j) => j.jobName === req.job);
   if (!found) throw new CiRunError(`the pull-request pipeline has no ${req.job} job; it has ${jobs.map((j) => j.jobName).join(" and ")}`);
   if (req.wave !== undefined && (req.job !== "apply" || !req.loop?.waveGate)) throw new CiRunError("--wave names the one wave an apply runs, and takes --wave-gate: ci run apply --wave-gate <gate> --wave <k>");
+  // #4147: before anything runs or any secret reaches a step, the provisioner's word that this runner was started for this job.
+  // #4168: under the isolated-runners security group an apply job requires the statement too, unless it runs on this machine.
+  const isolated = !req.requireRunnerStart && !req.local && req.job === "apply" && securityGroupsAt(cwd).has("isolated-runners");
+  const started = req.requireRunnerStart || isolated ? runnerStartFor(req, { top, commit, hostEnv }) : undefined;
   // A generated wave job's command, as prLoopWaveJobs writes it. #4161: a local job's command posts no status or note.
   const command = `${found.command}${req.wave !== undefined ? ` --wave ${req.wave}` : ""}${req.local ? " --no-status" : ""}`;
   const job = { ...found, command, ...(req.wave !== undefined ? { wave: req.wave } : {}) };
@@ -666,7 +685,8 @@ export async function ciRun(req: CiRunRequest): Promise<CiRunResult> {
   // In place the forge's own variables come too; one whose value is short, such as a flag, is left out, so it can't blank common words.
   const redact = ciRedactor(req.inPlace ? { ...longValues(jobEnv), ...own } : jobEnv, req.secrets);
   try {
-    const result = await runCiJob(req, { cwd, top, commit, place, job, jobEnv, ...(redact ? { redact } : {}) });
+    const ran = await runCiJob(req, { cwd, top, commit, place, job, jobEnv, ...(redact ? { redact } : {}) });
+    const result = started ? { ...ran, notes: [started, ...ran.notes] } : ran;
     return redact ? { ...result, warnings: result.warnings.map(redact), notes: result.notes.map(redact), ...(result.pushWarning ? { pushWarning: redact(result.pushWarning) } : {}) } : result;
   } catch (err) {
     if (redact && err instanceof Error) err.message = redact(err.message);
@@ -674,6 +694,22 @@ export async function ciRun(req: CiRunRequest): Promise<CiRunResult> {
   }
 }
 
+/**
+ * `--require-runner-start` (#4147): the runner-start statement for this
+ * forge job, checked against `.chant/trust.json` at `--base` (the commit
+ * before the change, as a push's `before` is), or at the job's commit
+ * without one. Throws {@link CiRunError} unless it verifies.
+ */
+function runnerStartFor(req: CiRunRequest, at: { top: string; commit: string; hostEnv: Record<string, string | undefined> }): string {
+  if (req.local) throw new CiRunError("--require-runner-start checks a forge job's runner, and --local runs the job on this machine");
+  const base = req.base ? resolveJobCommit(at.top, req.base) : at.commit;
+  try {
+    return requireRunnerStart({ top: at.top, base, commit: at.commit, env: at.hostEnv }).reason;
+  } catch (err) {
+    throw new CiRunError(message(err));
+  }
+}
+
 /** The generator's options for a `--local` job (#4161): the same, with no report URL. */
 function localLoop(loop: PrLoopPipelineOptions | undefined): PrLoopPipelineOptions {
   const { reportUrl: _dropped, ...rest } = loop ?? {};
@@ -899,8 +935,8 @@ export function formatCiRun(r: CiRunResult): string {
  * The generator's options from `ci run`'s and `ci serve`'s flags, as `chant
  * build --components --generate <lexicon> --pr-loop` takes them: `--gate`,
  * `--branch`, `--events-json`, `--report-url`, `--pr-build`,
- * `--pr-build-command`, `--wave-gate` (#4003) and `--no-require-review`
- * (#4156).
+ * `--pr-build-command`, `--wave-gate` (#4003) and `--require-review`
+ * (#4168; `--no-require-review`, the default, is still accepted).
  */
 export function ciLoopOptions(args: CommandContext["args"]): PrLoopPipelineOptions {
   return {
@@ -911,15 +947,15 @@ export function ciLoopOptions(args: CommandContext["args"]): PrLoopPipelineOptio
     ...(args.prBuild ? { build: true } : {}),
     ...(args.prBuildCommand ? { buildCommand: args.prBuildCommand } : {}),
     ...(args.waveGate ? { waveGate: args.waveGate } : {}),
-    ...(args.requireReview === false ? { requireReview: false } : {}),
+    ...(args.requireReview === true ? { requireReview: true } : {}),
   };
 }
 
 const USAGE =
-  "chant ci run plan|apply --env <env> --base <sha> [--pr <n>] [--commit <sha>] [--forge github|gitlab|forgejo] " +
+  "chant ci run plan|record|apply --env <env> --base <sha> [--pr <n>] [--commit <sha>] [--forge github|gitlab|forgejo] " +
   "[--gate <name>] [--wave-gate <name>] [--wave <k>] [--branch <name>] [--events-json] [--report-url <url>] [--run-index-limit <n>] [--image <image>] [--before-script <line>]... " +
-  "[--pr-build] [--pr-build-command <line>] [--no-require-review] [--no-status] [--status-url <url template>] " +
-  "[--chant <command>] [--pass-env <NAME>]... [--secrets <file>] [--key <runner key.pem>] [-o <dir>] [--in-place | --local] [--no-push] [--verbose] | chant ci run --setup-key [--trust [--principal <name>]] [--state <dir>] [--branch <name>]";
+  "[--pr-build] [--pr-build-command <line>] [--require-review] [--no-status] [--status-url <url template>] " +
+  "[--chant <command>] [--pass-env <NAME>]... [--secrets <file>] [--key <runner key.pem>] [-o <dir>] [--in-place | --local] [--no-push] [--verbose] | chant ci run --at <sha> | chant ci run --setup-key [--trust [--principal <name>]] [--state <dir>] [--branch <name>]";
 
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
@@ -942,13 +978,38 @@ export function ciSecretsOf(flag: string | undefined, env: Record<string, string
   return file === undefined ? undefined : readCiSecrets(resolve(file));
 }
 
-/** `chant ci run plan|apply` (#4094). */
+/**
+ * `chant ci run --at <sha>` (#4169): ask for every required phase to be built
+ * at a commit of the green branch. On GitHub, with a token in the
+ * environment, the workflows holding the phases start at once.
+ */
+async function requestBuildCommand(at: string): Promise<number> {
+  const { requestBuild } = await import("./ci-green");
+  const { ciForgeFromEnv } = await import("./ci-green-forge");
+  let forge: Awaited<ReturnType<typeof ciForgeFromEnv>> | undefined;
+  try {
+    forge = process.env.GITHUB_REPOSITORY ? ciForgeFromEnv("github") : undefined;
+  } catch {
+    forge = undefined;
+  }
+  const r = await requestBuild({ cwd: process.cwd(), at, ...(forge ? { forge } : {}) });
+  for (const w of r.warnings) console.error(formatWarning({ message: w }));
+  const what = `${r.request.phases.join(", ")} at ${r.request.commit.slice(0, 12)}`;
+  console.log(
+    `${r.existed ? `${r.request.tag} already asks for a build` : `Asked for ${what}: ${r.request.tag}`}. ` +
+      (r.dispatched.length > 0 ? `Started ${r.dispatched.join(", ")}.` : "The next ci tick starts it on GitHub, and ci serve --build-command serves it for chant runs."),
+  );
+  return 0;
+}
+
+/** `chant ci run plan|record|apply` (#4094, #4168). */
 export async function runCiRun(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   try {
     if (args.setupKey) return (await import("./ci-serve")).runnerKeySetupCommand(ctx);
+    if (args.at !== undefined && args.extraPositional === undefined) return await requestBuildCommand(args.at);
     const job = args.extraPositional;
-    if (job !== "plan" && job !== "apply") throw new CiRunError(`ci run takes the job to run, plan or apply${job ? `, not ${JSON.stringify(job)}` : ""}`);
+    if (job !== "plan" && job !== "apply" && job !== "record") throw new CiRunError(`ci run takes the job to run, plan, record or apply${job ? `, not ${JSON.stringify(job)}` : ""}`);
     if (!args.env) throw new CiRunError("--env names the environment the pipeline is for, as chant build --components --generate <lexicon> --pr-loop took it: --env <env>");
     const forge = args.forge ?? detectForge(process.env);
     if (!forge) throw new CiRunError("--forge names the forge the job posts to: --forge github|gitlab|forgejo");
@@ -980,6 +1041,7 @@ export async function runCiRun(ctx: CommandContext): Promise<number> {
       ...(args.local ? { local: true } : {}),
       ...(args.noPush ? { push: false } : {}),
       ...(args.wave !== undefined ? { wave: args.wave } : {}),
+      ...(args.requireRunnerStart ? { requireRunnerStart: true } : {}),
       ...(args.runIndexLimit ? { runIndexLimit: args.runIndexLimit } : {}),
       ...(args.image ? { image: args.image } : {}),
       ...(args.beforeScript?.length ? { beforeScript: args.beforeScript } : {}),

package/src/workspace/ci-runner-start.test.ts

@@ -0,0 +1,151 @@
+/**
+ * `chant ci runner-start` and `chant ci run --require-runner-start` (#4147):
+ * the statement checked against `.chant/trust.json` at base, and the
+ * readiness the isolated-runners security group reads (#4168).
+ */
+
+import { createPublicKey, generateKeyPairSync } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test, vi } from "vitest";
+import { parseArgs } from "../cli/parse-args";
+import type { CommandContext } from "../cli/registry";
+import { signRunnerStart, type CiJobIdentity } from "../runner-start";
+import { cleanScratch, git, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
+import { checkRunnerStart, parseJobSpec, requireRunnerStart, runCiRunnerStart, runnerStartReadiness, runnerStartReadinessAt } from "./ci-runner-start";
+import { ciRun, CiRunError } from "./ci-run";
+import { sshFromEd25519 } from "./trust/dsse";
+import { emptyPolicy } from "./trust/policy";
+
+afterAll(cleanScratch);
+
+function key(principal: string): { principal: string; pem: string; ssh: string; signer: Parameters<typeof signRunnerStart>[1] } {
+  const { privateKey } = generateKeyPairSync("ed25519");
+  const jwk = createPublicKey(privateKey).export({ format: "jwk" }) as { x: string };
+  const ssh = sshFromEd25519(Buffer.from(jwk.x, "base64url"));
+  return { principal, pem: privateKey.export({ type: "pkcs8", format: "pem" }).toString(), ssh, signer: { principal, key: privateKey, publicKey: ssh } };
+}
+
+const PROVISIONER = key("provisioner");
+const LATER = key("late-provisioner");
+
+/** A repository whose first commit lists PROVISIONER as a runner, and whose second adds LATER. */
+function repo(): { root: string; base: string; head: string } {
+  const root = scratchDir("chant-runner-start-");
+  git(root, "init", "-q", "-b", "main");
+  git(root, "config", "user.name", "t");
+  git(root, "config", "user.email", "t@example.com");
+  git(root, "config", "commit.gpgsign", "false");
+  const trust = (runners: Array<{ principal: string; ssh: string }>) =>
+    JSON.stringify({ schema: 1, runners: runners.map((r) => ({ principal: r.principal, class: "runner", key: r.ssh })), roles: { runner: runners.map((r) => r.principal) } });
+  writeFiles(root, { ".chant/trust.json": trust([PROVISIONER]) });
+  git(root, "add", "-A");
+  git(root, "commit", "-q", "-m", "trust");
+  const base = git(root, "rev-parse", "HEAD");
+  writeFiles(root, { ".chant/trust.json": trust([PROVISIONER, LATER]) });
+  git(root, "add", "-A");
+  git(root, "commit", "-q", "-m", "a pull request adds its own provisioner");
+  return { root, base, head: git(root, "rev-parse", "HEAD") };
+}
+
+const R = repo();
+
+const job = (commit: string): CiJobIdentity => ({ system: "github", repo: "acme/infra", run: "4242", attempt: "1", job: "apply", commit, runner: "jit-1" });
+const env = (commit: string, statement?: unknown): Record<string, string> => ({
+  GITHUB_ACTIONS: "true",
+  GITHUB_REPOSITORY: "acme/infra",
+  GITHUB_RUN_ID: "4242",
+  GITHUB_RUN_ATTEMPT: "1",
+  GITHUB_JOB: "apply",
+  GITHUB_SHA: commit,
+  RUNNER_NAME: "jit-1",
+  CHANT_RUNNER_START_FILE: "/nonexistent/runner-start.json",
+  ...(statement ? { CHANT_RUNNER_START: JSON.stringify(statement) } : {}),
+});
+
+describe("checkRunnerStart reads the runner keys at base", () => {
+  test("a statement by a provisioner listed at base verifies", () => {
+    const v = checkRunnerStart({ top: R.root, base: R.base, env: env(R.head, signRunnerStart(job(R.head), PROVISIONER.signer)) });
+    expect(v).toMatchObject({ status: "verified", signer: "provisioner" });
+  });
+
+  test("a provisioner the change itself lists does not count at the base before it", () => {
+    const statement = signRunnerStart(job(R.head), LATER.signer);
+    expect(checkRunnerStart({ top: R.root, base: R.base, env: env(R.head, statement) }).status).toBe("untrusted");
+    expect(checkRunnerStart({ top: R.root, base: R.head, env: env(R.head, statement) }).status).toBe("verified");
+  });
+
+  test("the job's commit stands in for the forge's variable, so a statement for another commit is refused", () => {
+    const statement = signRunnerStart(job(R.head), PROVISIONER.signer);
+    expect(checkRunnerStart({ top: R.root, base: R.base, env: env(R.head, statement), commit: R.base }).status).toBe("mismatch");
+  });
+
+  test("requireRunnerStart throws with the reason, and a missing statement is named", () => {
+    expect(() => requireRunnerStart({ top: R.root, base: R.base, commit: R.head, env: env(R.head) })).toThrow(/--require-runner-start: missing: .*has no runner-start statement/);
+    expect(() => requireRunnerStart({ top: R.root, base: R.base, commit: R.head, env: {} })).toThrow(/needs a forge job to check/);
+    expect(requireRunnerStart({ top: R.root, base: R.base, commit: R.head, env: env(R.head, signRunnerStart(job(R.head), PROVISIONER.signer)) }).signer).toBe("provisioner");
+  });
+});
+
+describe("runnerStartReadiness, for the isolated-runners group", () => {
+  test("a policy with a runner key whose principal holds the runner role is configured", () => {
+    expect(runnerStartReadinessAt(R.root, R.base)).toEqual({ configured: true, gaps: [] });
+  });
+
+  test("no runner key, a key with no runner role, and an unreadable policy each name their gap", () => {
+    expect(runnerStartReadiness(emptyPolicy("x")).gaps.map((g) => g.gap)).toEqual(["no-runner-key"]);
+    const noRole = { ...emptyPolicy("x"), runners: [{ principal: "p", class: "runner" as const, key: PROVISIONER.ssh }] };
+    expect(runnerStartReadiness(noRole)).toMatchObject({ configured: false, gaps: [{ gap: "no-runner-role" }] });
+    expect(runnerStartReadiness(emptyPolicy("x", ["bad json"])).gaps.map((g) => g.gap)).toEqual(["trust-unreadable"]);
+  });
+});
+
+describe("chant ci runner-start sign and verify", () => {
+  test("--job takes JSON or @file, and refuses fields chant does not know", () => {
+    const dir = scratchDir("chant-runner-start-job-");
+    writeFiles(dir, { "job.json": JSON.stringify(job(R.head)) });
+    expect(parseJobSpec(`@${join(dir, "job.json")}`)).toEqual(job(R.head));
+    expect(parseJobSpec('{"system":"gitlab","repo":"g/s/p","run":9,"job":77,"commit":"x"}')).toEqual({ system: "gitlab", repo: "g/s/p", run: "9", attempt: "1", job: "77", commit: "x" });
+    expect(() => parseJobSpec('{"system":"github","pr":7}')).toThrow(/fields chant does not know: pr/);
+    expect(parseArgs(["ci", "runner-start", "sign", "--key", "k.pem", "--principal", "provisioner", "--job", "@job.json"])).toMatchObject({ path: "runner-start", extraPositional: "sign", key: "k.pem", ciPrincipal: "provisioner", ciJob: "@job.json" });
+    expect(parseArgs(["ci", "run", "apply", "--env", "prod", "--require-runner-start"])).toMatchObject({ requireRunnerStart: true });
+  });
+
+  test("sign writes an envelope the job then verifies, and verify exits 1 for another attempt", async () => {
+    const dir = scratchDir("chant-runner-start-cli-");
+    writeFiles(dir, { "key.pem": PROVISIONER.pem, "job.json": JSON.stringify(job(R.head)) });
+    const out = join(dir, "runner-start.json");
+    const ctx = (argv: string[]) => ({ args: parseArgs(argv) }) as unknown as CommandContext;
+    const quiet = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      expect(await runCiRunnerStart(ctx(["ci", "runner-start", "sign", "--key", join(dir, "key.pem"), "--principal", "provisioner", "--job", `@${join(dir, "job.json")}`, "-o", out]))).toBe(0);
+      const statement = JSON.parse(readFileSync(out, "utf8"));
+      const cwd = process.cwd();
+      process.chdir(R.root);
+      try {
+        vi.stubEnv("GITHUB_ACTIONS", "true");
+        for (const [k, v] of Object.entries(env(R.head))) vi.stubEnv(k, v);
+        vi.stubEnv("CHANT_RUNNER_START_FILE", out);
+        expect(await runCiRunnerStart(ctx(["ci", "runner-start", "verify", "--base", R.base]))).toBe(0);
+        vi.stubEnv("GITHUB_RUN_ATTEMPT", "2");
+        expect(await runCiRunnerStart(ctx(["ci", "runner-start", "verify", "--base", R.base]))).toBe(1);
+      } finally {
+        vi.unstubAllEnvs();
+        process.chdir(cwd);
+      }
+      expect(statement.payloadType).toBe("application/vnd.in-toto+json");
+      expect(await runCiRunnerStart(ctx(["ci", "runner-start", "nope"]))).toBe(1);
+    } finally {
+      quiet.mockRestore();
+    }
+  });
+});
+
+describe("ci run --require-runner-start", () => {
+  test("a job with no statement is refused before anything runs, and --local is refused with it", async () => {
+    const run = (extra: Partial<Parameters<typeof ciRun>[0]>) => ciRun({ cwd: R.root, job: "apply", env: "prod", forge: "github", base: R.base, hostEnv: env(R.head), push: false, requireRunnerStart: true, ...extra });
+    await expect(run({})).rejects.toThrow(CiRunError);
+    await expect(run({})).rejects.toThrow(/has no runner-start statement/);
+    await expect(run({ local: true, hostEnv: {} })).rejects.toThrow(/--local runs the job on this machine/);
+  });
+});