@intentius/chant-lexicon-github 0.124.54 → 0.124.56

package/src/components/generate-op-pipeline.ts

@@ -79,7 +79,7 @@ import {
   environmentDoc,
   fillCommand,
   GITHUB_JOB_TOKEN,
-  GITHUB_RUNNER,
+  githubRunsOn,
   mergePermissions,
   nonEmpty,
   permissionsFor,
@@ -97,6 +97,12 @@ import type {
 } from "@intentius/chant/lexicon";
 import { checkoutStep, concurrency, emitWorkflowYAML, jobTokenEnv, onTrigger, opConcurrencyGroup, runSteps } from "./ci-jobs";
 import { assertReviewSplit, reviewJobs, reviewNoteJobName } from "./review-jobs";
+import { resolveAgentSpec } from "@intentius/chant/ci-agent";
+import { activeProductWords } from "@intentius/chant/ci-product-words";
+import { agentJobName, agentPushJobName, driftRunOutputs, driftRunStep, githubAgentJobs } from "./agent-jobs";
+import { assertScheduledOpCloud, scheduledOpUpdateJobName, withoutTokenRequestLine } from "@intentius/chant/scheduled-op-cloud";
+import { TRADE_SPEC_ENV, tradeLine, type CloudTradeSpec } from "@intentius/chant/ci-identity";
+import { CHANT_EXIT } from "@intentius/chant/exit-codes";
 
 export type { GenerateGithubOpOptions, GenerateGithubOpResult };
 
@@ -162,6 +168,13 @@ export interface GithubOpPipelineDoc {
    * dialect transforms this job on its own terms.
    */
   reviewNoteDoc?: Record<string, unknown>;
+  /**
+   * The agent jobs (#4616), when the spec sets `agent`: the agent job and
+   * the push job. Kept out of {@link jobsDoc} so a member's
+   * `working-directory` default stays on the Op's own job: these check out
+   * at the repository root.
+   */
+  agentDoc?: Record<string, unknown>;
 }
 
 /** One generated file: a suggested name plus its pipeline document, pre-emission. */
@@ -361,12 +374,12 @@ function gateNoticeScript(version: string): string {
  * no branch and merges nothing. The Forgejo dialect drops them, as it drops
  * every scope but `id-token`.
  */
-function gateNoticeJob(applyJobName: string, image: string): Record<string, unknown> {
+function gateNoticeJob(applyJobName: string, image: string, runner?: ScheduledOpSpec["runner"]): Record<string, unknown> {
   const output = (name: string) => "${{ needs." + applyJobName + ".outputs." + name + ' }}';
   return {
     needs: applyJobName,
     if: `needs.${applyJobName}.outputs.gated == 'true'`,
-    "runs-on": GITHUB_RUNNER,
+    "runs-on": githubRunsOn(runner),
     container: image,
     permissions: { contents: "read", issues: "write", "pull-requests": "write" },
     steps: [
@@ -415,6 +428,7 @@ function assertTriggerSupportsMode(name: string, mode: OpFindingMode, trigger: O
 export function buildGithubOpPipelineDocs(
   ops: ScheduledOpSpec[],
   options: GenerateGithubOpOptions = {},
+  forge: "github" | "forgejo" = "github",
 ): { files: GithubOpPipelineFile[]; jobs: OpPipelineJob[] } {
   const image = options.image ?? CI_IMAGE;
   const runCommand = options.runCommand ?? ["chant", "run", "{name}"];
@@ -424,7 +438,43 @@ export function buildGithubOpPipelineDocs(
   const files: GithubOpPipelineFile[] = [];
   const jobs: OpPipelineJob[] = [];
 
+  const words = activeProductWords();
   for (const spec of ops) {
+    // #4631: the job's cloud identities and the update on drift, checked before anything renders.
+    assertScheduledOpCloud(spec);
+    // #4616: the comment agent is a workflow of its own, on pull request comments; the spec's trigger is not read.
+    if (spec.agent?.on === "comment") {
+      const settings = resolveAgentSpec(spec.name, spec.agent, words.product);
+      const jobName = ciJobName(spec.name);
+      const setup = spec.setup ?? [];
+      assertSetupSteps(spec.name, setup);
+      jobs.push({ jobName, op: spec.name, trigger: { kind: "pull_request" }, findingMode: "report" });
+      const { agent, push } = githubAgentJobs({
+        forge,
+        jobName,
+        image,
+        settings,
+        ...(spec.runner !== undefined ? { runner: spec.runner } : {}),
+        setup: setup.map(setupStepDoc),
+        beforeScript,
+        ...(spec.agent.tokenEnv ? { tokenEnv: spec.agent.tokenEnv } : {}),
+        ...(words.bin ? { bin: words.bin } : {}),
+      });
+      files.push({
+        name: `${spec.name}.yml`,
+        doc: {
+          name: spec.name,
+          on: { issue_comment: { types: ["created"] } },
+          ...nonEmpty("env", options.variables),
+          // One agent run at a time, so two asks never count the limit at once.
+          concurrency: concurrency(jobName),
+          permissions: { contents: "read" },
+          jobsDoc: {},
+          agentDoc: { [jobName]: agent, [agentPushJobName(jobName)]: push },
+        },
+      });
+      continue;
+    }
     const findingMode = spec.findingMode ?? "report";
     const trigger = resolveOpTrigger(spec);
     assertTriggerSupportsMode(spec.name, findingMode, trigger);
@@ -438,7 +488,14 @@ export function buildGithubOpPipelineDocs(
     // A split review (#4326) runs the change's code beside a model: no step of that job holds a forge token.
     const split = spec.reviewAgent === true;
     if (split) assertReviewSplit(spec.name, trigger, findingMode, spec.permissions);
+    // #4616: a drift agent follows the Op's job, which hands its output on and says whether it found drift.
+    const driftAgent = spec.agent?.on === "drift" ? resolveAgentSpec(spec.name, spec.agent, words.product) : undefined;
+    if (driftAgent && (split || trigger.kind === "push")) {
+      throw new Error(`Scheduled Op "${spec.name}" sets a drift agent, which follows a drift check's run; give it a cron or pull_request trigger and no reviewAgent.`);
+    }
     const stepEnv = split ? {} : jobTokenEnv(findingMode !== "report");
+    const cloud = spec.cloud;
+    const update = spec.update;
 
     const setup = spec.setup ?? [];
     assertSetupSteps(spec.name, setup);
@@ -453,13 +510,19 @@ export function buildGithubOpPipelineDocs(
       ? [...runParts, ...GATED_EXIT_FLAG, "--json"].join(" ")
       : runParts.join(" ");
 
-    const steps: Array<Record<string, unknown>> = [checkoutStep(), ...setup.map(setupStepDoc), ...runSteps(beforeScript)];
-    steps.push(
+    const later: Array<Record<string, unknown>> = [...setup.map(setupStepDoc), ...runSteps(beforeScript)];
+    later.push(
       gated
         ? gatedRunStep(RUN_STEP_ID, spec.name, invocation, stepEnv)
-        : { run: invocation, env: stepEnv },
+        : driftAgent
+          ? driftRunStep(invocation, stepEnv, forge)
+          : update
+            ? driftFlagStep(invocation, stepEnv)
+            : { run: invocation, env: stepEnv },
     );
-    steps.push(...runSteps(extraScript));
+    later.push(...runSteps(extraScript));
+    // #4631: the trade before the checkout, and every step after it without the token request variables.
+    const steps: Array<Record<string, unknown>> = cloud ? [tradeStep(cloud), checkoutStep(), ...later.map(withoutTokenRequest)] : [checkoutStep(), ...later];
 
     const review = split
       ? reviewJobs({
@@ -475,6 +538,12 @@ export function buildGithubOpPipelineDocs(
         })
       : undefined;
 
+    const workflowPermissions = mergePermissions(
+      spec.name,
+      permissionsFor(findingMode, trigger),
+      spec.permissions ?? {},
+      trigger,
+    );
     const doc: GithubOpPipelineDoc = {
       name: spec.name,
       on: onTrigger(trigger),
@@ -482,15 +551,10 @@ export function buildGithubOpPipelineDocs(
       // One run at a time per Op — a slow audit must not overlap its own next
       // scheduled trigger. A push Op's `build` (#4169) widens the group.
       concurrency: concurrency(opConcurrencyGroup(jobName, trigger)),
-      permissions: mergePermissions(
-        spec.name,
-        permissionsFor(findingMode, trigger),
-        spec.permissions ?? {},
-        trigger,
-      ),
+      permissions: workflowPermissions,
       jobsDoc: {
         [jobName]: {
-          "runs-on": GITHUB_RUNNER,
+          "runs-on": githubRunsOn(spec.runner),
           container: image,
           // Per-Op credentials (#2290): job-level `env:`, one level more
           // specific than `options.variables`'s workflow-level `env:` above,
@@ -502,6 +566,8 @@ export function buildGithubOpPipelineDocs(
           // behind the same reviewer would hold the message back until
           // somebody had already acted.
           ...(spec.environment ? { environment: environmentDoc(spec.environment) } : {}),
+          // #4631: the trade needs id-token: write, on this job alone; the finding-mode's scopes stay as they are.
+          ...(cloud ? { permissions: { ...workflowPermissions, "id-token": "write" } } : {}),
           ...(gated
             ? {
                 outputs: Object.fromEntries(
@@ -511,16 +577,47 @@ export function buildGithubOpPipelineDocs(
                   ]),
                 ),
               }
-            : {}),
+            : driftAgent
+              ? { outputs: driftRunOutputs(forge) }
+              : update
+                ? { outputs: { drift: `\${{ steps.${DRIFT_FLAG_STEP_ID}.outputs.drift }}` } }
+                : {}),
           steps,
         },
+        ...(update
+          ? {
+              [scheduledOpUpdateJobName(jobName)]: updateJob(jobName, update, {
+                image,
+                ...(spec.runner !== undefined ? { runner: spec.runner } : {}),
+                setup: setup.map(setupStepDoc),
+                beforeScript,
+              }),
+            }
+          : {}),
       },
-      ...(gated ? { gatedNoticeDoc: { [`${jobName}-gate-notice`]: gateNoticeJob(jobName, image) } } : {}),
+      ...(gated ? { gatedNoticeDoc: { [`${jobName}-gate-notice`]: gateNoticeJob(jobName, image, spec.runner) } } : {}),
     };
+    if (driftAgent) {
+      const name = agentJobName(jobName, "drift");
+      const { agent, push } = githubAgentJobs({
+        forge,
+        jobName: name,
+        image,
+        settings: driftAgent,
+        ...(spec.runner !== undefined ? { runner: spec.runner } : {}),
+        setup: setup.map(setupStepDoc),
+        beforeScript,
+        ...(spec.agent?.tokenEnv ? { tokenEnv: spec.agent.tokenEnv } : {}),
+        ...(words.bin ? { bin: words.bin } : {}),
+        after: jobName,
+      });
+      doc.agentDoc = { [name]: agent, [agentPushJobName(name)]: push };
+    }
     // A split review (#4326): the Op's job is the review job, and the note job rides beside it.
     if (review) {
-      doc.jobsDoc = { [jobName]: { ...review.review, ...(spec.environment ? { environment: environmentDoc(spec.environment) } : {}) } };
-      doc.reviewNoteDoc = { [reviewNoteJobName(jobName)]: review.note };
+      const runsOn = spec.runner !== undefined ? { "runs-on": githubRunsOn(spec.runner) } : {};
+      doc.jobsDoc = { [jobName]: { ...review.review, ...runsOn, ...(spec.environment ? { environment: environmentDoc(spec.environment) } : {}) } };
+      doc.reviewNoteDoc = { [reviewNoteJobName(jobName)]: { ...review.note, ...runsOn } };
     }
 
     files.push({ name: `${spec.name}.yml`, doc });
@@ -580,8 +677,8 @@ export function emitOpPipelineYAML(doc: GithubOpPipelineDoc): string {
   // The gated-apply notice job rides in `jobs:` beside the Op's own job; it
   // is carried separately on the doc so a dialect transforms it on its own.
   // A dialect's `header` note (#2257) is absent on github.
-  const { gatedNoticeDoc, reviewNoteDoc, ...workflow } = doc;
-  return emitWorkflowYAML({ ...workflow, jobsDoc: { ...doc.jobsDoc, ...(gatedNoticeDoc ?? {}), ...(reviewNoteDoc ?? {}) } });
+  const { gatedNoticeDoc, reviewNoteDoc, agentDoc, ...workflow } = doc;
+  return emitWorkflowYAML({ ...workflow, jobsDoc: { ...doc.jobsDoc, ...(gatedNoticeDoc ?? {}), ...(reviewNoteDoc ?? {}), ...(agentDoc ?? {}) } });
 }
 
 /**
@@ -600,3 +697,51 @@ export function generateGithubOpPipeline(
     jobs,
   };
 }
+
+/** The id of the run step that says whether an update's drift check found drift (#4631). */
+const DRIFT_FLAG_STEP_ID = "drift-check";
+
+/** The Op's run step when an update follows it (#4631): `drift=true` as an output on chant's drift code, and the run's own exit code. */
+function driftFlagStep(invocation: string, env: Record<string, string>): Record<string, unknown> {
+  return {
+    id: DRIFT_FLAG_STEP_ID,
+    env,
+    run: ["set +e", invocation, "code=$?", `if [ "$code" -eq ${CHANT_EXIT.drift} ]; then echo "drift=true" >>"$GITHUB_OUTPUT"; fi`, 'exit "$code"'].join("\n"),
+  };
+}
+
+/** The trade step (#4631), as an op wave job's (#4332): the job's OIDC token for `cloud`, written to GITHUB_ENV. */
+function tradeStep(cloud: CloudTradeSpec): Record<string, unknown> {
+  return { name: "Trade the job's OIDC token for its cloud identities", env: { [TRADE_SPEC_ENV]: JSON.stringify(cloud) }, run: tradeLine("$GITHUB_ENV", "github-env") };
+}
+
+/** A run step after the trade, with the token request variables unset first. A `uses:` step is left as it is. */
+function withoutTokenRequest(step: Record<string, unknown>): Record<string, unknown> {
+  return typeof step.run === "string" ? { ...step, run: withoutTokenRequestLine(step.run) } : step;
+}
+
+/**
+ * The update job (#4631): after the Op's job, only when its run found
+ * drift; its own trade for `update.cloud` before its checkout, then the
+ * update's command. Its permissions are `contents: read`, `id-token: write`
+ * with a cloud, and the update's own scopes, which may raise `contents` to
+ * `write` so the update records on `chant/lifecycle` (2026-10-28 ruling).
+ * The Op's own job keeps its scopes.
+ */
+function updateJob(
+  after: string,
+  update: NonNullable<ScheduledOpSpec["update"]>,
+  i: { image: string; runner?: ScheduledOpSpec["runner"]; setup: Array<Record<string, unknown>>; beforeScript: readonly string[] },
+): Record<string, unknown> {
+  const later: Array<Record<string, unknown>> = [...i.setup, ...runSteps(i.beforeScript), { name: "Update what drifted", run: update.command }];
+  return {
+    needs: after,
+    if: `always() && needs.${after}.outputs.drift == 'true'`,
+    "runs-on": githubRunsOn(i.runner),
+    container: i.image,
+    permissions: { contents: "read", ...(update.cloud ? { "id-token": "write" } : {}), ...(update.permissions ?? {}) },
+    ...nonEmpty("env", update.variables),
+    ...(update.environment ? { environment: environmentDoc(update.environment) } : {}),
+    steps: update.cloud ? [tradeStep(update.cloud), checkoutStep(), ...later.map(withoutTokenRequest)] : [checkoutStep(), ...later],
+  };
+}

package/src/components/generate-op-waves-pipeline.approval.test.ts

@@ -0,0 +1,46 @@
+/**
+ * #4630: a pr-review wave's plans workflow posts `<product>/approval` on the
+ * head after the plans are recorded and on every review, with a token that
+ * reads and writes statuses only.
+ */
+import { describe, expect, test } from "vitest";
+import type { OpWavesSpec } from "@intentius/chant/op/op-waves";
+import { generateGithubOpWavesPipeline } from "./generate-op-waves-pipeline";
+
+const spec: OpWavesSpec = {
+  name: "plywood-up",
+  op: "plywood-up",
+  plan: ["./bin/plan", "{target}", "{plan}"],
+  waves: [{ name: "prod", runs: [{ target: "app" }], approval: "pr-review" }],
+};
+
+describe("the approval status job (#4630)", () => {
+  test("runs after record-plans on a push and alone on a review, with a read token", () => {
+    const { files } = generateGithubOpWavesPipeline(spec, { specFile: ".chant/op-waves/plywood-up.spec.json", bin: "npx --no-install plywood" });
+    const plans = files.find((f) => f.name === "plywood-up-plans.yml")!.yaml;
+    expect(plans).toContain("pull_request_review:");
+    expect(plans).toMatch(/types:\n\s+- submitted\n\s+- dismissed/);
+    expect(plans).toContain("github.event_name == 'pull_request'");
+    expect(plans).toMatch(/approval-status:\n(.*\n)*?\s+needs:\n\s+- record-plans/);
+    expect(plans).toMatch(/permissions:\n\s+contents: read\n\s+pull-requests: read\n\s+statuses: write/);
+    expect(plans).toContain('npx --no-install plywood run wave --spec .chant/op-waves/plywood-up.spec.json --approval-status --pr "$PR_NUMBER" --head "$HEAD_SHA" --base "$BASE_SHA" --forge github');
+    expect(plans).toContain("HEAD_SHA: '${{ github.event.pull_request.head.sha }}'");
+    expect(plans).toContain("BASE_SHA: '${{ github.event.pull_request.base.sha }}'");
+  });
+
+  test("a spec with no pr-review wave has no plans workflow", () => {
+    const { files } = generateGithubOpWavesPipeline({ ...spec, waves: [{ name: "prod", runs: [{ target: "app" }] }] }, { specFile: "waves.json" });
+    expect(files.map((f) => f.name)).toEqual(["plywood-up.yml"]);
+  });
+
+  test("a pull-request wave gets the plans workflow and the status too (2026-10-28 ruling)", () => {
+    const pullRequest: OpWavesSpec = { ...spec, waves: [{ name: "prod", runs: [{ target: "app" }], approval: "pull-request" }], approvals: { pullRequest: { gate: "up" } } };
+    const { files } = generateGithubOpWavesPipeline(pullRequest, { specFile: "waves.json", bin: "npx --no-install plywood" });
+    expect(files.map((f) => f.name)).toEqual(["plywood-up.yml", "plywood-up-plans.yml"]);
+    const plans = files.find((f) => f.name === "plywood-up-plans.yml")!.yaml;
+    expect(plans).toContain("npx --no-install plywood run wave --spec waves.json --record-plans");
+    expect(plans).toContain("--approval-status --pr \"$PR_NUMBER\"");
+    // The waves read no review, so they ask for no pull-requests scope.
+    expect(files[0]!.yaml).not.toContain("pull-requests: read");
+  });
+});

package/src/components/generate-op-waves-pipeline.control.test.ts

@@ -0,0 +1,64 @@
+/**
+ * An Op waves spec's `control` (#4617): after the last wave, one job adds up
+ * the wave jobs' outcomes and tells the control repo how the waves ended.
+ * Written for the ci-products session; run at epic-ready.
+ */
+
+import { describe, expect, test } from "vitest";
+import type { OpWavesSpec } from "@intentius/chant/op/op-waves";
+import { generateGithubOpWavesPipeline } from "./generate-op-waves-pipeline";
+
+const spec: OpWavesSpec = {
+  name: "stacks",
+  op: "pulumi-up",
+  plan: ["./bin/plan", "{target}", "{plan}"],
+  waves: [
+    { name: "canary", runs: [{ target: "dev" }], gate: "never" },
+    { name: "rest", runs: [{ target: "a" }, { target: "b" }], shares: 2 },
+  ],
+  control: { repo: "github.com/acme/control", op: "deploy", member: "network", tokenSecret: "PLYWOOD_CONTROL_TOKEN" },
+};
+
+const options = { specFile: "waves.json", bin: "npx --no-install plywood", words: { product: "plywood" } };
+
+describe("the control dispatch after the last wave (#4617)", () => {
+  test("needs the last wave's share jobs and runs after a failure, unless the run was cancelled", () => {
+    const yaml = generateGithubOpWavesPipeline(spec, options).files[0]!.yaml;
+    expect(yaml).toMatch(/control-dispatch:\n\s+runs-on: ubuntu-latest\n\s+needs:\n\s+- wave-2-rest-share-1\n\s+- wave-2-rest-share-2\n\s+if: '!cancelled\(\)'/);
+  });
+
+  test("downloads every outcome file and adds them up through the product's bin", () => {
+    const yaml = generateGithubOpWavesPipeline(spec, options).files[0]!.yaml;
+    expect(yaml).toContain("name: Download the waves' outcomes");
+    expect(yaml).toContain("path: .chant/op-waves/stacks/outcomes");
+    expect(yaml).toContain('outcome="$(npx --no-install plywood run wave --spec waves.json --waves-outcome)" || exit 1');
+    expect(yaml).toContain('echo "CHANT_CONTROL_OUTCOME=$outcome" >> "$GITHUB_ENV"');
+  });
+
+  test("the dispatch step alone holds the token, maps it from the product's secret and pipes it to curl", () => {
+    const yaml = generateGithubOpWavesPipeline(spec, options).files[0]!.yaml;
+    expect(yaml.match(/secrets\.PLYWOOD_CONTROL_TOKEN/g)).toHaveLength(1);
+    expect(yaml).toContain("CHANT_CONTROL_TOKEN: '${{ secrets.PLYWOOD_CONTROL_TOKEN }}'");
+    expect(yaml).toContain("CHANT_CONTROL_SHA: '${{ github.sha }}'");
+    expect(yaml).toContain("-H @-");
+    expect(yaml).toContain('"event_type":"plywood-applied"');
+    expect(yaml).toContain(`"outcome":"'"$outcome"'"`);
+  });
+
+  test("markSent asks for statuses: write and hands the job token over", () => {
+    const yaml = generateGithubOpWavesPipeline({ ...spec, control: { ...spec.control!, markSent: "plywood post status control success" } }, options).files[0]!.yaml;
+    expect(yaml).toMatch(/control-dispatch:[\s\S]*permissions:\n\s+contents: write\n\s+statuses: write/);
+    expect(yaml).toContain("plywood post status control success");
+    expect(yaml).toContain("GITHUB_TOKEN: '${{ github.token }}'");
+  });
+
+  test("no control, no job", () => {
+    const { control: _drop, ...plain } = spec;
+    expect(generateGithubOpWavesPipeline(plain, options).files[0]!.yaml).not.toContain("control-dispatch");
+  });
+
+  test("a control without a member is refused, since a spec has no repository name to default it to", () => {
+    const { member: _m, ...noMember } = spec.control!;
+    expect(() => generateGithubOpWavesPipeline({ ...spec, control: noMember as never }, options)).toThrow(/control\.member/);
+  });
+});

package/src/components/generate-op-waves-pipeline.guard.test.ts

@@ -0,0 +1,57 @@
+/**
+ * The apply-job guard in GitHub op-wave jobs (#4624): the first step of
+ * every wave, deciding and share job, before the trade and the checkout,
+ * carrying the job's forge environment, branches and runner. Written for
+ * the ci-products post-merge pass.
+ */
+
+import { describe, expect, test } from "vitest";
+import type { OpWavesSpec } from "@intentius/chant/op/op-waves";
+import { JOB_GUARD_ENV, jobGuardLine } from "@intentius/chant/ci-job-guard";
+import { buildGithubOpWavesDoc } from "./generate-op-waves-pipeline";
+
+const spec: OpWavesSpec = {
+  name: "deploy",
+  op: "pulumi-up",
+  plan: ["./bin/plan", "{target}", "{plan}"],
+  branches: ["main", "release"],
+  runner: ["self-hosted", "linux"],
+  waves: [
+    { name: "dev", runs: [{ target: "dev" }], gate: "never" },
+    { name: "prod", runs: [{ target: "prod" }], environment: { name: "production" }, idTokens: { CLOUD_TOKEN: "sts.amazonaws.com" } },
+    { name: "wide", runs: [{ target: "a" }, { target: "b" }], shares: 2, environment: { name: "production" } },
+  ],
+};
+
+type Job = { steps: Array<{ name?: string; env?: Record<string, string>; run?: string; uses?: string }> };
+const jobsOf = (s: OpWavesSpec, words?: { product: string }) => buildGithubOpWavesDoc(s, { specFile: "waves.json", ...(words ? { words } : {}) }).doc.jobsDoc as Record<string, Job>;
+const guardOf = (job: Job) => JSON.parse(job.steps[0]!.env![JOB_GUARD_ENV]!) as Record<string, unknown>;
+
+describe("the apply-job guard on GitHub (#4624)", () => {
+  test("every wave job starts with it, before the checkout", () => {
+    const jobs = jobsOf(spec);
+    for (const [name, job] of Object.entries(jobs)) {
+      expect(job.steps[0]!.run, name).toBe(jobGuardLine());
+      expect(job.steps[1]!.uses, name).toMatch(/checkout/);
+    }
+  });
+
+  test("carries the branches, the runner and, where it can read it, the environment", () => {
+    const jobs = jobsOf(spec);
+    expect(guardOf(jobs["wave-1-dev"]!)).toEqual({ forge: "github", job: "wave 1 (dev) of deploy", branches: ["main", "release"], selfHosted: true });
+    // Its id tokens give the job id-token: write, so the guard reads the environment from a token.
+    expect(guardOf(jobs["wave-2-prod"]!)).toMatchObject({ forgeEnvironment: "production" });
+    // A job that may request no token cannot be checked for its environment on GitHub.
+    expect(guardOf(jobs["wave-3-wide-decide"]!)).not.toHaveProperty("forgeEnvironment");
+    expect(guardOf(jobs["wave-3-wide-share-2"]!)).toMatchObject({ job: "share 2 of wave 3 (wide) of deploy" });
+  });
+
+  test("names the product", () => {
+    expect(guardOf(jobsOf(spec, { product: "plywood" })["wave-1-dev"]!)).toMatchObject({ product: "plywood" });
+  });
+
+  test("the default branch when the spec names none", () => {
+    const { branches: _b, ...plain } = spec;
+    expect(guardOf(jobsOf(plain)["wave-1-dev"]!)).toMatchObject({ branches: ["main"] });
+  });
+});

package/src/components/generate-op-waves-pipeline.identity.test.ts

@@ -57,7 +57,7 @@ interface Job {
 }
 
 const jobsOf = (spec: OpWavesSpec): Record<string, Job> => (parseYAML(generateGithubOpWavesPipeline(spec, { specFile: ".chant/op-waves/tf-apply.spec.json", beforeScript: ["npm ci"] }).files[0]!.yaml) as { jobs: Record<string, Job> }).jobs;
-const tradeOf = (job: Job): unknown => JSON.parse(job.steps[0]!.env![TRADE_SPEC_ENV]!);
+const tradeOf = (job: Job): unknown => JSON.parse(job.steps[1]!.env![TRADE_SPEC_ENV]!);
 const UNSET = `unset ${OIDC_REQUEST_VARS.join(" ")}`;
 
 describe("an Op wave's jobs by cloud identity (#4332)", () => {
@@ -70,9 +70,9 @@ describe("an Op wave's jobs by cloud identity (#4332)", () => {
 
   test("the deciding job trades for every plan identity, before the checkout, and names no apply identity", () => {
     const decide = jobs["wave-1-wave-1-decide"]!;
-    expect(decide.steps[0]!.name).toBe("Trade the job's OIDC token for its cloud identities");
-    expect(decide.steps[0]!.run).toMatch(/^\(cd \/ && node -e '/);
-    expect(decide.steps[1]!.uses).toMatch(/^actions\/checkout@/);
+    expect(decide.steps[1]!.name).toBe("Trade the job's OIDC token for its cloud identities");
+    expect(decide.steps[1]!.run).toMatch(/^\(cd \/ && node -e '/);
+    expect(decide.steps[2]!.uses).toMatch(/^actions\/checkout@/);
     expect(tradeOf(decide)).toEqual(plan);
     expect(decide.permissions).toEqual({ contents: "write", "id-token": "write" });
     for (const id of [role("prod-apply"), role("staging-apply"), role("own-apply")]) expect(JSON.stringify(decide)).not.toContain(id);
@@ -83,14 +83,14 @@ describe("an Op wave's jobs by cloud identity (#4332)", () => {
     for (const [name, id] of Object.entries(want)) {
       const job = jobs[name]!;
       expect(tradeIdentities(tradeOf(job) as never)).toEqual([id]);
-      expect(job.steps[1]!.uses).toMatch(/^actions\/checkout@/);
+      expect(job.steps[2]!.uses).toMatch(/^actions\/checkout@/);
       for (const other of Object.values(want).filter((o) => o !== id)) expect(JSON.stringify(job)).not.toContain(other);
     }
   });
 
   test("every run step after the trade starts by unsetting the token request variables", () => {
     for (const job of Object.values(jobs)) {
-      const runs = job.steps.slice(1).filter((s) => s.run !== undefined);
+      const runs = job.steps.slice(2).filter((s) => s.run !== undefined);
       expect(runs.length).toBeGreaterThan(0);
       for (const s of runs) expect(s.run!.split("\n")[0]).toBe(UNSET);
     }
@@ -124,8 +124,8 @@ describe("the deciding job, run step by step against the emulator (#4332)", () =
     const githubEnv = join(temp, "github-env");
     writeFileSync(githubEnv, "");
     const base = { PATH: process.env.PATH ?? "/usr/bin:/bin", HOME: process.env.HOME ?? "/tmp", RUNNER_TEMP: temp, ...emu.requestEnv };
-    const spec = emu.pointAt(JSON.parse(decide.steps[0]!.env![TRADE_SPEC_ENV]!));
-    await run("sh", ["-c", decide.steps[0]!.run!.replace("$GITHUB_ENV", githubEnv)], { env: { ...base, [TRADE_SPEC_ENV]: JSON.stringify(spec) } });
+    const spec = emu.pointAt(JSON.parse(decide.steps[1]!.env![TRADE_SPEC_ENV]!));
+    await run("sh", ["-c", decide.steps[1]!.run!.replace("$GITHUB_ENV", githubEnv)], { env: { ...base, [TRADE_SPEC_ENV]: JSON.stringify(spec) } });
     const traded = Object.fromEntries(readFileSync(githubEnv, "utf-8").split("\n").filter(Boolean).map((l) => [l.slice(0, l.indexOf("=")), l.slice(l.indexOf("=") + 1)]));
     expect(traded.AWS_ACCESS_KEY_ID).toBe(emulatedCredentials(role("own-plan")).accessKeyId);
     const before = emu.log.minted.length;

package/src/components/generate-op-waves-pipeline.test.ts

@@ -121,4 +121,21 @@ describe("a runner per wave and job groups per wave (#3914)", () => {
     expect(files.map((f) => f.name)).toEqual(["migrations.yml", "migrations-resume.yml", "migrations-plans.yml"]);
     for (const f of files) expect(f.yaml).not.toContain("ubuntu-latest");
   });
+
+  test("words.bin is the command in every job line: the waves, resume and the plans job (#4607)", () => {
+    const bin = "npx --no-install plywood";
+    const withBin = { ...spec, resume: { schedule: "*/10 * * * *" }, waves: spec.waves.map((w, i) => (i === spec.waves.length - 1 ? { ...w, approval: "pr-review" as const } : w)) };
+    const { files, jobs } = generateGithubOpWavesPipeline(withBin, { specFile: "waves.json", bin });
+    expect(jobs.every((j) => j.command.slice(0, 3).join(" ") === bin)).toBe(true);
+    const yaml = files.map((f) => f.yaml).join("\n");
+    expect(yaml).toContain("run: npx --no-install plywood run wave --spec waves.json --wave 1");
+    expect(yaml).toContain("npx --no-install plywood run resume --op migrations");
+    expect(yaml).toContain("npx --no-install plywood run wave --spec waves.json --record-plans");
+    expect(yaml).not.toMatch(/(^|\s)chant run (wave|resume)/m);
+  });
+
+  test("no bin keeps chant (#4607)", () => {
+    const { jobs } = generateGithubOpWavesPipeline(spec, { specFile: "waves.json" });
+    expect(jobs.every((j) => j.command[0] === "chant")).toBe(true);
+  });
 });