@intentius/chant-lexicon-github 0.124.31 → 0.124.32

package/dist/components/generate-op-waves-pipeline.js

@@ -0,0 +1,158 @@
+/**
+ * Op waves → GitHub Actions workflow (#3679).
+ *
+ * One workflow for the whole spec, on a push to its branches (and by hand),
+ * one run at a time. Each job is one of core's `opWaveJobs`: a wave, or a wide
+ * wave's deciding job and share jobs, chained by `needs:` so a wave that waits
+ * at its gate (exit 3) or fails stops every later wave. Re-running the failed
+ * jobs after `chant approve` carries on from that wave.
+ *
+ * Every job checks out the full history, because the runner reads the gate
+ * policy from the spec file at the base commit and records pending gates on
+ * `chant/lifecycle`, which is why the workflow asks for `contents: write`. A
+ * deciding job uploads its decision, even when it waits, and each share job
+ * downloads it. The forgejo generator reuses {@link buildGithubOpWavesDoc}
+ * and applies its dialect.
+ *
+ * With `resume` on the spec (#3683), a second workflow, `<name>-resume.yml`,
+ * runs `chant run resume --op <name>` on that schedule: it re-runs the failed
+ * jobs of a run whose waiting wave has been approved since, with the job's
+ * token and `actions: write`.
+ *
+ * When a wave's approval is `pr-review` (#3684), the workflow also asks for
+ * `pull-requests: read`, so a wave can read the merged pull request's
+ * reviews, and a second workflow, `<name>-plans.yml`, runs `chant run wave
+ * --record-plans` on each pull request to record the digests its head plans.
+ *
+ * With `notify` on the spec (#3761), the workflow maps each variable it names
+ * from the repository secret of the same name, so a wave job can post to
+ * Slack, Teams or a signed webhook. `options.variables` wins over the mapping.
+ *
+ * `runner` (on the spec, a wave or a job group, #3914) is the job's `runs-on`.
+ * A wave's `jobs` renders its deciding job with the wave's own settings and a
+ * job per group (per share of a group) with the group's: its runner,
+ * environment, variables over the wave's, setup after the wave's, and id
+ * tokens. A job with id tokens gets `permissions:` of its own, the
+ * workflow's plus `id-token: write`, and each audience as `<NAME>_AUDIENCE`.
+ */
+import { notifyVariables, opWaveGroupOf, opWaveJobs, opWavesResumeCommand } from "@intentius/chant/op/op-waves";
+import { assertEnvironment, assertSetupSteps, CI_IMAGE, dirnameOf, environmentDoc, GITHUB_JOB_TOKEN, githubRunsOn, githubSecretEnv, idTokenAudienceEnv, nonEmpty, pushBranches, setupStepDoc, } from "@intentius/chant/ci-jobs";
+import { checkoutStep, concurrency, downloadArtifactStep, keepRecordStep, runSteps } from "./ci-jobs.js";
+import { emitOpPipelineYAML } from "./generate-op-pipeline.js";
+/** The default image: it carries git, which the runner needs to read the base commit. */
+export const OP_WAVES_IMAGE = CI_IMAGE;
+/** The artifact a wide wave's deciding job hands its share jobs. */
+export function opWaveRecordArtifact(spec, wave) {
+    return `${spec.name}-wave-${wave}-decision`;
+}
+/** The workflow document, before emission, and the jobs it holds. */
+export function buildGithubOpWavesDoc(spec, options) {
+    const jobs = opWaveJobs(spec, options.specFile);
+    const image = options.image ?? OP_WAVES_IMAGE;
+    const byReview = spec.waves.some((w) => w.approval === "pr-review");
+    for (const wave of spec.waves) {
+        assertSetupSteps(`${spec.name}/${wave.name}`, wave.setup ?? []);
+        if (wave.environment)
+            assertEnvironment(`${spec.name}/${wave.name}`, wave.environment);
+        for (const group of wave.jobs ?? []) {
+            assertSetupSteps(`${spec.name}/${wave.name}/${group.name}`, group.setup ?? []);
+            if (group.environment)
+                assertEnvironment(`${spec.name}/${wave.name}/${group.name}`, group.environment);
+        }
+    }
+    const permissions = { contents: "write", ...(byReview ? { "pull-requests": "read" } : {}) };
+    const jobsDoc = {};
+    for (const job of jobs) {
+        const wave = spec.waves[job.wave - 1];
+        // #3914: a job group's job runs with the group's settings over the wave's.
+        const group = opWaveGroupOf(spec, job);
+        const steps = [checkoutStep(true)];
+        if (job.kind === "share") {
+            steps.push(downloadArtifactStep(`Download wave ${job.wave}'s decision`, opWaveRecordArtifact(spec, job.wave), dirnameOf(job.record)));
+        }
+        steps.push(...[...(wave.setup ?? []), ...(group?.setup ?? [])].map(setupStepDoc), ...runSteps(options.beforeScript ?? []));
+        steps.push({ name: describeJob(job.kind, job.wave, wave.name, job.share, job.group), run: job.command.join(" ") });
+        steps.push(...runSteps(options.extraScript ?? []));
+        if (job.kind === "decide") {
+            steps.push(keepRecordStep(`Keep wave ${job.wave}'s decision`, opWaveRecordArtifact(spec, job.wave), job.record));
+        }
+        const environment = group?.environment ?? wave.environment;
+        const idTokens = group?.idTokens ?? wave.idTokens;
+        jobsDoc[job.jobName] = {
+            "runs-on": githubRunsOn(group?.runner ?? wave.runner ?? spec.runner),
+            ...(job.needs.length > 0 ? { needs: job.needs } : {}),
+            container: image,
+            ...(environment ? { environment: environmentDoc(environment) } : {}),
+            // #3914: a job's own permissions replace the workflow's, so they repeat them.
+            ...(idTokens ? { permissions: { ...permissions, "id-token": "write" } } : {}),
+            ...nonEmpty("env", group || idTokens ? { ...wave.variables, ...group?.variables, ...idTokenAudienceEnv(idTokens) } : wave.variables),
+            steps,
+        };
+    }
+    // #3761: the notify variables come from the secrets of the same name.
+    const env = { ...githubSecretEnv(notifyVariables(spec.notify)), ...(options.variables ?? {}) };
+    const doc = {
+        name: spec.name,
+        on: { push: { branches: pushBranches(spec.branches) }, workflow_dispatch: {} },
+        ...nonEmpty("env", env),
+        concurrency: concurrency(spec.name),
+        permissions,
+        jobsDoc,
+    };
+    return {
+        doc,
+        jobs,
+        ...(spec.resume ? { resumeDoc: buildResumeDoc(spec, options) } : {}),
+        ...(byReview ? { plansDoc: buildPlansDoc(spec, options) } : {}),
+    };
+}
+/** The scheduled resume workflow (#3683). */
+function buildResumeDoc(spec, options) {
+    const steps = [checkoutStep(), ...runSteps(options.beforeScript ?? [])];
+    steps.push({
+        name: `Resume the waves of ${spec.name} whose approval arrived`,
+        run: opWavesResumeCommand(spec).join(" "),
+        env: { GITHUB_TOKEN: GITHUB_JOB_TOKEN },
+    });
+    return {
+        name: `${spec.name}-resume`,
+        on: { schedule: [{ cron: spec.resume.schedule }], workflow_dispatch: {} },
+        concurrency: concurrency(`${spec.name}-resume`, true),
+        // contents: read fetches chant/lifecycle; actions: write re-runs a waiting run.
+        permissions: { contents: "read", actions: "write" },
+        jobsDoc: { resume: { "runs-on": githubRunsOn(spec.runner), container: options.image ?? OP_WAVES_IMAGE, steps } },
+    };
+}
+/** The pull request workflow a `pr-review` wave needs (#3684): record the digests each head plans. */
+function buildPlansDoc(spec, options) {
+    const steps = [checkoutStep(true), ...(spec.waves[0]?.setup ?? []).map(setupStepDoc), ...runSteps(options.beforeScript ?? [])];
+    steps.push({ name: "Plan every wave at the head and record its digests", run: ["chant", "run", "wave", "--spec", options.specFile, "--record-plans"].join(" ") });
+    return {
+        name: `${spec.name}-plans`,
+        on: { pull_request: { branches: pushBranches(spec.branches) } },
+        ...nonEmpty("env", options.variables),
+        concurrency: concurrency(spec.name + "-plans-${{ github.event.number }}", true),
+        // contents: write pushes the record to chant/lifecycle.
+        permissions: { contents: "write" },
+        jobsDoc: { "record-plans": { "runs-on": githubRunsOn(spec.runner), container: options.image ?? OP_WAVES_IMAGE, steps } },
+    };
+}
+function describeJob(kind, wave, name, share, group) {
+    if (kind === "decide")
+        return `Plan wave ${wave} (${name}) and decide its gate`;
+    if (group !== undefined)
+        return `Apply ${share !== undefined ? `share ${share} of ` : ""}job group ${group} of wave ${wave} (${name})`;
+    if (kind === "share")
+        return `Apply share ${share} of wave ${wave} (${name})`;
+    return `Plan, gate and apply wave ${wave} (${name})`;
+}
+/** Render an Op waves spec as one GitHub Actions workflow, `<name>.yml`. */
+export function generateGithubOpWavesPipeline(spec, options) {
+    const { doc, jobs, resumeDoc, plansDoc } = buildGithubOpWavesDoc(spec, options);
+    const files = [{ name: `${spec.name}.yml`, yaml: emitOpPipelineYAML(doc) }];
+    if (resumeDoc)
+        files.push({ name: `${spec.name}-resume.yml`, yaml: emitOpPipelineYAML(resumeDoc) });
+    if (plansDoc)
+        files.push({ name: `${spec.name}-plans.yml`, yaml: emitOpPipelineYAML(plansDoc) });
+    return { files, jobs };
+}

package/dist/components/generate-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAMjG,OAAO,KAAK,EACV,oBAAoB,IAAI,YAAY,EACpC,wBAAwB,IAAI,qBAAqB,EACjD,uBAAuB,IAAI,oBAAoB,EAEhD,MAAM,0BAA0B,CAAC;AAGlC,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;AAE1E;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,mIAAmI;IACnI,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,uEAAuE;IACvE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,0DAA0D;IAC1D,IAAI,EAAE,YAAY,EAAE,CAAC;CACtB;AAuKD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAWpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,iBAAiB,CA+JnB;AA4CD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAGtB"}
+{"version":3,"file":"generate-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAgBjG,OAAO,KAAK,EACV,oBAAoB,IAAI,YAAY,EACpC,wBAAwB,IAAI,qBAAqB,EACjD,uBAAuB,IAAI,oBAAoB,EAEhD,MAAM,0BAA0B,CAAC;AAGlC,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;AAE1E;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,mIAAmI;IACnI,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,uEAAuE;IACvE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,0DAA0D;IAC1D,IAAI,EAAE,YAAY,EAAE,CAAC;CACtB;AAkMD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAWpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,iBAAiB,CA+JnB;AA4CD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAGtB"}

package/dist/components/generate-pipeline.js

@@ -0,0 +1,476 @@
+/**
+ * Generate mode — component → GitHub Actions workflow YAML (#891, epic #885).
+ *
+ * The github counterpart to the gitlab generator (`../../gitlab/src/components/generate-pipeline.ts`,
+ * #563/#688): the same `chant build --components --generate <lexicon>` seam,
+ * synthesizing a **thin** `.github/workflows/*.yml` from the discovered
+ * component graph instead of interpreting it directly.
+ *
+ * The generated workflow is a trigger, not the deploy logic:
+ *  - Ordering + parallel-safe waves are resolved once, generically, by
+ *    `resolveComponentGraph` (core's driver) — the exact function the local
+ *    interpret driver and the gitlab generator both use. This module does not
+ *    re-derive or duplicate that graph logic.
+ *  - GitHub Actions has no `stage` concept, so wave ordering is expressed
+ *    entirely through `needs:` edges between jobs: one job per component,
+ *    with `needs:` pointing at the jobs for its direct `dependsOn` entries.
+ *    Independent components therefore run in parallel, and dependents wait
+ *    on their dependencies via GitHub's own `needs:` scheduling.
+ *    `ComponentPipelineResult.stages` is still populated with the wave-ordered
+ *    names (one per wave) purely for parity with gitlab's machine-readable
+ *    `--format json` view — GitHub's YAML itself has no `stages:` section.
+ *  - Each job's trigger step is exactly one invocation that hands off to the
+ *    component's own composition (`chant run --components <name> ...` by
+ *    default) — never inlined build/publish/apply steps. The deploy logic
+ *    lives in the component's `deploy` phases and the capabilities they
+ *    reference, not in this YAML.
+ *  - A component that something else depends on can't hand its resolved
+ *    stack outputs to a dependent in-memory, since each job is a separate
+ *    GitHub Actions runner. It dumps its outputs to a file and uploads that
+ *    file as a workflow artifact (`actions/upload-artifact`); each direct
+ *    dependent downloads it (`actions/download-artifact`) and seeds from it,
+ *    so a `stackOutput()` / `@<dep>.publish.*` reference still resolves even
+ *    though the producer ran in a different job. This mirrors the dump/seed
+ *    model `cli-support.ts` (`runComponents`'s `componentOutputs`) already
+ *    uses, and matches gitlab's artifact-passing 1:1 in intent — only the
+ *    transport differs (explicit upload/download steps vs. GitLab's implicit
+ *    `needs:` artifact passing).
+ *  - With `options.promoteTo` (#2575), one more job needs every component
+ *    job and runs `chant components promote`. A promote publishes from the
+ *    build archive on disk, so each component job uploads the files its
+ *    build steps wrote and the promote job downloads them to the same paths.
+ *    Each component job with a publish step also writes the digest its run
+ *    recorded (`--digest-file`) to a job output, and the promote job passes
+ *    it back as `--digest <component>=<digest>` (#2602), so it promotes the
+ *    release this run built rather than whatever is latest in the source
+ *    environment.
+ *  - For a workspace member (`options.member`, #2542) the workflow keeps its
+ *    triggers, and its `run:` steps start in the member's directory. See
+ *    `scopeToMember`.
+ *
+ * Cross-cutting changes (e.g. "sign every image before deploy") are made by
+ * editing `GenerateGithubOptions.extraScript`/`beforeScript` (or the
+ * component's own composition) ONCE here — never per generated job. See
+ * `generate-pipeline.test.ts`'s "cross-cutting change" cases for a
+ * demonstration: one generator-option edit reflects in every job without
+ * touching the component declarations.
+ */
+import { resolveComponentGraph } from "@intentius/chant/components/driver";
+import { hasPublishStep, promoteArchivePaths } from "@intentius/chant/components/promote";
+import { GATED_WAVE_RECORD, gatedWaveJobs } from "@intentius/chant/components/gated-wave-pipeline";
+import { CI_IMAGE, ciJobName, dirnameOf, fillCommand, GITHUB_RUNNER } from "@intentius/chant/ci-jobs";
+import { PR_APPLY_RECORD, PR_LOOP_REPORT_DIR, prApplyGroup, prApplyRecordKey, prApplyWaveJobName, prLoopJobs, prLoopSetup, prLoopWaveJobs, prLoopWithWaves, } from "@intentius/chant/components/pr-pipeline";
+import { memberRepoPath } from "@intentius/chant/lexicon";
+import { checkoutStep, concurrency, downloadArtifactStep, emitWorkflowYAML, keepRecordStep, runSteps, UPLOAD_ARTIFACT } from "./ci-jobs.js";
+/** The workflow artifact the gated-wave jobs hand their attempt record through, one per wave. */
+function waveRecordArtifact(wave) {
+    return `fan-out-record-wave-${wave}`;
+}
+/**
+ * The gated-wave workflow (#3049): one job per wave, each running one wave of
+ * `chant components fan-out --wave-gate`, chained by `needs:`. Each job
+ * downloads the record the job before it uploaded and uploads its own, even
+ * when it stops at a gate (exit 3), so re-running it after `chant approve`
+ * reads the record. The checkout fetches full history for `--base`.
+ */
+function gatedWaveGithubDoc(components, env, image, beforeScript, extraScript, options) {
+    const waveJobs = gatedWaveJobs(components, env, options.gatedWaves);
+    const jobsDoc = {};
+    const jobs = [];
+    for (const job of waveJobs) {
+        jobs.push({ jobName: job.jobName, component: `wave ${job.wave}`, stage: job.jobName, needs: job.needs });
+        const steps = [checkoutStep(true)];
+        if (job.wave > 1) {
+            steps.push(downloadArtifactStep(`Download the record wave ${job.wave - 1} left`, waveRecordArtifact(job.wave - 1), dirnameOf(GATED_WAVE_RECORD)));
+        }
+        steps.push(...runSteps(prLoopSetup(image)), ...runSteps(beforeScript), { run: job.command.join(" ") }, ...runSteps(extraScript));
+        steps.push(keepRecordStep(`Upload the record for wave ${job.wave}`, waveRecordArtifact(job.wave), GATED_WAVE_RECORD));
+        jobsDoc[job.jobName] = {
+            "runs-on": GITHUB_RUNNER,
+            ...(job.needs.length > 0 ? { needs: job.needs } : {}),
+            container: image,
+            steps,
+        };
+    }
+    const doc = {
+        name: `chant-components-${env}`,
+        environment: env,
+        on: { workflow_dispatch: {} },
+        env: { ...options.variables, CHANT_ENV: env },
+        jobsDoc,
+        stages: waveJobs.map((j) => j.jobName),
+        jobs,
+    };
+    return options.member ? scopeToMember(doc, options.member) : doc;
+}
+/**
+ * The pull-request workflow (#3183): `plan` on each pull request into the
+ * target branch, `apply` on each push to it. The plan job can comment and set
+ * statuses but cannot push, since it runs the pull request's code; the apply
+ * job can push, to record a pending fact on `chant/lifecycle`, and runs one
+ * at a time per environment. Both keep their report as an artifact, and both
+ * check out the full history, since each measures the change with git.
+ * The apply job restores its attempt record from the cache before it runs
+ * and saves it afterwards, failed or not, so a re-run of a failed apply
+ * finishes it under the same approval (#3543).
+ *
+ * For a workspace member (#3465) the run steps start in the member's
+ * directory and the report artifact is kept from there. The triggers take no
+ * path filter, since a change outside the member can reach it; the plan
+ * selects from the whole change and passes `--member`, which keeps the
+ * member's gate, note and statuses apart from the other members'.
+ *
+ * With a gate per wave (`waveGate`, #4003) the one apply job becomes
+ * `apply-wave-1` to `apply-wave-<n>`, one per wave of the component graph,
+ * each needing the one before. Each saves the record under its own cache key
+ * (the run, the attempt and the wave), and each restores the newest record
+ * for the pushed commit, so wave k reads what wave k-1 left, and a re-run of
+ * a wave that stopped at its gate reads what it left itself. Each keeps its
+ * report as `chant-pr-apply-wave-<k>`.
+ */
+function prLoopGithubDoc(components, env, image, beforeScript, extraScript, options) {
+    const loop = options.prLoop;
+    const branch = loop.branch ?? "main";
+    const member = options.member;
+    const rooted = !member || member.dir === "." || member.dir === "";
+    const [plan, apply] = prLoopJobs(loop.forge ?? "github", env, loop, member?.name);
+    const reportPath = member ? memberRepoPath(member, PR_LOOP_REPORT_DIR) : PR_LOOP_REPORT_DIR;
+    // The apply's attempt record (#3543) lives in the cache under the pushed
+    // commit. Cache keys cannot be overwritten, so each attempt saves under
+    // its run and attempt, and a re-run restores the newest for the commit.
+    const recordPath = member ? memberRepoPath(member, PR_APPLY_RECORD) : PR_APPLY_RECORD;
+    const recordPrefix = `${prApplyRecordKey(env, "${{ github.sha }}", member?.name)}-`;
+    const recordKey = (wave) => `${recordPrefix}\${{ github.run_id }}-\${{ github.run_attempt }}${wave ? `-wave-${wave}` : ""}`;
+    const restoreRecord = (wave) => ({
+        name: wave ? "Restore the newest record of this commit's apply" : "Restore the record of an earlier attempt at this commit",
+        uses: "actions/cache/restore@v4",
+        with: { path: recordPath, key: recordKey(wave), "restore-keys": recordPrefix },
+    });
+    const saveRecord = (wave) => ({
+        name: wave ? "Keep the record for the next wave and a re-run" : "Keep the record for a re-run",
+        if: "always()",
+        uses: "actions/cache/save@v4",
+        with: { path: recordPath, key: recordKey(wave) },
+    });
+    const reportName = (job) => `chant-pr-${job.wave ? prApplyWaveJobName(job.wave) : job.jobName}`;
+    const steps = (job, name) => [
+        checkoutStep(true),
+        ...runSteps(prLoopSetup(image)),
+        ...runSteps(beforeScript),
+        ...(job.build ? [{ name: "Build the templates", run: job.build[0] }, { name: "Lint the project", run: job.build[1] }] : []),
+        ...(job.jobName === "apply" ? [restoreRecord(job.wave)] : []),
+        // The job's setup lines (#4004) run in the command's shell, so a value they settle reaches it.
+        // The command runs through chant ci run (#4156), which writes the job's run record, signed when the CHANT_RUNNER_KEY secret is set.
+        { name, env: job.run.env, run: [...(job.setup ?? []), job.run.command].join("\n") },
+        ...runSteps(extraScript),
+        ...(job.jobName === "apply" ? [saveRecord(job.wave)] : []),
+        {
+            name: `Keep the ${job.wave ? `wave ${job.wave} ` : ""}${job.jobName} report`,
+            if: "always()",
+            uses: UPLOAD_ARTIFACT,
+            with: { name: reportName(job), path: reportPath, "if-no-files-found": "ignore", "include-hidden-files": true },
+        },
+    ];
+    const applyJob = (job, needs, name) => ({
+        if: "github.event_name == 'push'",
+        "runs-on": GITHUB_RUNNER,
+        ...(needs.length > 0 ? { needs } : {}),
+        container: image,
+        concurrency: concurrency(prApplyGroup(env, member?.name)),
+        permissions: { contents: "write", "pull-requests": "write", statuses: "write" },
+        steps: steps(job, name),
+    });
+    const waveJobs = loop.waveGate ? prLoopWaveJobs(components, apply) : [];
+    const applyJobs = loop.waveGate
+        ? waveJobs.map((job) => [
+            prApplyWaveJobName(job.wave),
+            applyJob(job, job.wave > 1 ? [prApplyWaveJobName(job.wave - 1)] : [], `Apply wave ${job.wave}, under the approval its plan has`),
+        ])
+        : [["apply", applyJob(apply, [], "Apply the plan a reviewer approved")]];
+    const jobsDoc = {
+        plan: {
+            if: "github.event_name == 'pull_request'",
+            "runs-on": GITHUB_RUNNER,
+            container: image,
+            permissions: { contents: "read", "pull-requests": "write", statuses: "write" },
+            steps: steps(plan, "Plan the members this pull request reaches"),
+        },
+        ...Object.fromEntries(applyJobs),
+    };
+    const applyNames = applyJobs.map(([name]) => name);
+    return {
+        name: member ? `chant-pr.${member.name}.${env}` : `chant-pr-${env}`,
+        environment: env,
+        on: { pull_request: { branches: [branch] }, push: { branches: [branch] } },
+        ...(rooted ? {} : { defaults: { run: { "working-directory": member.dir } } }),
+        env: { ...options.variables, CHANT_ENV: env },
+        jobsDoc,
+        stages: ["plan", ...applyNames],
+        jobs: [
+            { jobName: "plan", component: "pull request plan", stage: "plan", needs: [] },
+            ...applyNames.map((name, i) => ({
+                jobName: name,
+                component: loop.waveGate ? `pull request apply, wave ${i + 1}` : "pull request apply",
+                stage: name,
+                needs: i > 0 ? [applyNames[i - 1]] : [],
+            })),
+        ],
+    };
+}
+/** The file a producer dumps its resolved outputs to, and a dependent seeds from — one per component, matching gitlab's naming so both generators produce interchangeable artifacts. */
+function outputsFile(name) {
+    return `${name}.outputs.json`;
+}
+/** The workflow artifact name a producer's dumped outputs are uploaded under. */
+function artifactName(name) {
+    return `${name}-outputs`;
+}
+/** The file a component job writes the digest its run recorded to, for the promote job (#2602). */
+function digestFile(name) {
+    return `${name}.digest`;
+}
+/** The workflow artifact name a component's build archive is uploaded under, for the promote job (#2575). */
+function archiveArtifactName(name) {
+    return `${name}-archive`;
+}
+/**
+ * The directory `actions/upload-artifact` roots a set of files at: the
+ * deepest directory that holds all of them. Downloading into it puts each
+ * file back at the path it was uploaded from.
+ */
+export function artifactRoot(paths) {
+    const dirs = paths.map((p) => {
+        const parts = p.replace(/\/+$/, "").split("/");
+        parts.pop();
+        return parts.filter((part) => part !== "" && part !== ".");
+    });
+    const common = [];
+    for (let i = 0; dirs.every((d) => i < d.length && d[i] === dirs[0][i]); i++)
+        common.push(dirs[0][i]);
+    const absolute = paths.every((p) => p.startsWith("/"));
+    if (common.length === 0)
+        return absolute ? "/" : ".";
+    return (absolute ? "/" : "") + common.join("/");
+}
+/**
+ * Synthesize a `.github/workflows/*.yml` pipeline from a set of components:
+ * one job per component, `needs:` expressing the wave-ordered dependency DAG
+ * from `resolveComponentGraph`. Throws `DependencyCycleError`/
+ * `UnknownDependencyError` (from core's driver) exactly like the interpret
+ * driver and the gitlab generator do, since all three consume the same graph
+ * resolution. Wired into core's generate mode via the github lexicon plugin's
+ * `generateComponentPipeline` (../plugin.ts).
+ */
+export function buildGithubPipelineDoc(components, options = {}) {
+    const env = options.env ?? "production";
+    const image = options.image ?? CI_IMAGE;
+    const runCommand = options.runCommand ?? ["chant", "run", "--components", "{name}", "--env", env];
+    const beforeScript = options.beforeScript ?? [];
+    const extraScript = options.extraScript ?? [];
+    const { waves } = resolveComponentGraph(components);
+    const byName = new Map(components.map((c) => [c.name, c]));
+    if (options.prLoop) {
+        if (options.promoteTo !== undefined)
+            throw new Error("a pull-request pipeline has no promote job; drop --promote-to or --pr-loop");
+        // #4003: --wave-gate beside --pr-loop gives the apply a gate per wave.
+        const prLoop = prLoopWithWaves(options.prLoop, options.gatedWaves);
+        return prLoopGithubDoc(components, env, image, beforeScript, extraScript, { ...options, prLoop });
+    }
+    if (options.gatedWaves) {
+        if (options.promoteTo !== undefined)
+            throw new Error("a gated-wave pipeline has no promote job; drop --promote-to or --wave-gate");
+        return gatedWaveGithubDoc(components, env, image, beforeScript, extraScript, options);
+    }
+    // Components that something else depends on must hand their resolved outputs
+    // (stack outputs, published artifact refs) to their dependents, which run as
+    // separate jobs on separate runners. Each such producer dumps its outputs to
+    // a file and uploads it as a workflow artifact; each dependent downloads that
+    // artifact and seeds from it, so a `stackOutput()` / `@<dep>.publish.*`
+    // reference resolves even though the producer ran in a different job.
+    // Without this, a single-component job has no in-memory outputs for its
+    // dependencies — see epic #551 / the adopt-alb-services example.
+    const dependedUpon = new Set();
+    for (const c of components)
+        for (const dep of c.dependsOn ?? [])
+            dependedUpon.add(dep);
+    // A promote job (#2575) runs on its own runner, and a promote publishes from
+    // the build archive on disk, so each component job uploads the files its
+    // build steps wrote and the promote job downloads them.
+    const promoteTo = options.promoteTo;
+    const archives = new Map();
+    // The components the promote job pins to this run's digest (#2602): those
+    // with a publish step, the only ones whose deploy records a release.
+    const pinned = new Set();
+    if (promoteTo !== undefined) {
+        for (const c of components) {
+            const paths = promoteArchivePaths(c);
+            if (paths.length > 0)
+                archives.set(c.name, paths);
+            if (hasPublishStep(c))
+                pinned.add(c.name);
+        }
+        if (pinned.size === 0) {
+            throw new Error("no component has a publish step, so no deploy records a release for the promote job to promote");
+        }
+    }
+    const stages = waves.map((_, i) => `wave-${i + 1}`);
+    const jobs = [];
+    const jobNameByComponent = new Map();
+    for (const wave of waves) {
+        for (const name of wave)
+            jobNameByComponent.set(name, ciJobName(name));
+    }
+    const jobsDoc = {};
+    waves.forEach((wave, waveIndex) => {
+        const stage = stages[waveIndex];
+        for (const name of wave) {
+            const component = byName.get(name);
+            const jobName = jobNameByComponent.get(name);
+            const needs = (component.dependsOn ?? []).map((dep) => jobNameByComponent.get(dep)).sort();
+            jobs.push({ jobName, component: name, stage, needs });
+            // Build the run invocation, then append output-threading flags: seed from
+            // each dependency's dumped outputs (downloaded as an artifact below), and
+            // dump this component's own outputs if a dependent will need them.
+            const runParts = fillCommand(runCommand, name);
+            for (const dep of component.dependsOn ?? [])
+                runParts.push("--seed-outputs", outputsFile(dep));
+            if (dependedUpon.has(name))
+                runParts.push("--dump-outputs", outputsFile(name));
+            if (pinned.has(name))
+                runParts.push("--digest-file", digestFile(name));
+            // One step per script line — mirrors gitlab's `script:` array of
+            // discrete shell lines, rather than a single multi-line `run:` block, so
+            // each line is independently inspectable (and machine-parseable).
+            const steps = [checkoutStep()];
+            for (const dep of component.dependsOn ?? [])
+                steps.push(downloadArtifactStep(`Download ${dep} outputs`, artifactName(dep), "."));
+            steps.push(...runSteps(beforeScript), { run: runParts.join(" ") }, ...runSteps(extraScript));
+            // The file holds `<component>=<digest>`; the job output holds the digest.
+            if (pinned.has(name)) {
+                steps.push({
+                    name: `Record ${name} digest`,
+                    id: "digest",
+                    run: `echo "digest=$(cut -d= -f2- ${digestFile(name)})" >> "$GITHUB_OUTPUT"`,
+                });
+            }
+            if (dependedUpon.has(name)) {
+                steps.push({
+                    name: `Upload ${name} outputs`,
+                    uses: UPLOAD_ARTIFACT,
+                    with: { name: artifactName(name), path: outputsFile(name) },
+                });
+            }
+            const archive = archives.get(name);
+            if (archive) {
+                steps.push({
+                    name: `Upload ${name} build archive`,
+                    uses: UPLOAD_ARTIFACT,
+                    with: {
+                        name: archiveArtifactName(name),
+                        path: archive.join("\n"),
+                        "if-no-files-found": "error",
+                        "include-hidden-files": true,
+                    },
+                });
+            }
+            const jobProps = {
+                "runs-on": GITHUB_RUNNER,
+                ...(needs.length > 0 ? { needs } : {}),
+                container: image,
+                ...(pinned.has(name) ? { outputs: { digest: "${{ steps.digest.outputs.digest }}" } } : {}),
+                steps,
+            };
+            jobsDoc[jobName] = jobProps;
+        }
+    });
+    if (promoteTo !== undefined) {
+        const promoteJob = `promote-${ciJobName(promoteTo)}`;
+        if (promoteJob in jobsDoc) {
+            throw new Error(`the promote job "${promoteJob}" has the same name as a component job; rename the component`);
+        }
+        const command = [...(options.promoteCommand ?? ["chant", "components", "promote", "--from", env, "--to", promoteTo])];
+        for (const name of [...pinned].sort()) {
+            command.push("--digest", `"${name}=\${{ needs.${jobNameByComponent.get(name)}.outputs.digest }}"`);
+        }
+        const steps = [checkoutStep()];
+        for (const [name, paths] of archives) {
+            steps.push(downloadArtifactStep(`Download ${name} build archive`, archiveArtifactName(name), artifactRoot(paths)));
+        }
+        steps.push(...runSteps(beforeScript), { run: command.join(" ") }, ...runSteps(extraScript));
+        jobsDoc[promoteJob] = {
+            "runs-on": GITHUB_RUNNER,
+            needs: [...jobNameByComponent.values()].sort(),
+            container: image,
+            steps,
+        };
+    }
+    const doc = {
+        name: `chant-components-${env}`,
+        environment: env,
+        on: { workflow_dispatch: {} },
+        env: { ...options.variables, CHANT_ENV: env },
+        jobsDoc,
+        stages,
+        jobs,
+    };
+    return options.member ? scopeToMember(doc, options.member) : doc;
+}
+/**
+ * Scope a pipeline to one workspace member (#2542, #2524 D19). Its name
+ * carries the member's name, and every `run:` step starts in the member's
+ * directory through `defaults.run.working-directory`.
+ *
+ * The triggers stay exactly the plain pipeline's. A deploy pipeline gains no
+ * `push` or `pull_request` trigger for a member, and its only trigger,
+ * `workflow_dispatch`, takes no `paths:` filter.
+ *
+ * `working-directory` applies to `run:` steps only. The artifact actions
+ * resolve `path` against the repository root, so each upload and download
+ * path moves under the member's directory, where the `run:` steps read and
+ * write the files.
+ */
+function scopeToMember(doc, member) {
+    const rooted = member.dir === "." || member.dir === "";
+    const jobsDoc = {};
+    for (const [name, job] of Object.entries(doc.jobsDoc)) {
+        const props = job;
+        jobsDoc[name] = rooted || !props.steps ? job : { ...props, steps: props.steps.map((step) => memberArtifactStep(step, member)) };
+    }
+    return {
+        ...doc,
+        name: `chant-components.${member.name}.${doc.environment}`,
+        ...(rooted ? {} : { defaults: { run: { "working-directory": member.dir } } }),
+        jobsDoc,
+    };
+}
+/** An `actions/upload-artifact` or `download-artifact` step with its `path` moved under the member's directory. */
+function memberArtifactStep(step, member) {
+    const uses = typeof step.uses === "string" ? step.uses : "";
+    if (!/^actions\/(upload|download)-artifact@/.test(uses))
+        return step;
+    const withProps = step.with;
+    if (!withProps || typeof withProps.path !== "string")
+        return step;
+    const path = withProps.path
+        .split("\n")
+        .map((line) => memberRepoPath(member, line))
+        .join("\n");
+    return { ...step, with: { ...withProps, path } };
+}
+/**
+ * Emit a `GithubPipelineDoc`'s `on`/`env`/`jobs` mappings as workflow YAML.
+ * Shared with the forgejo dialect (#969), which transforms the doc first.
+ */
+export function emitPipelineYAML(doc) {
+    return emitWorkflowYAML({ name: doc.name, on: doc.on, env: doc.env, defaults: doc.defaults, jobsDoc: doc.jobsDoc });
+}
+/**
+ * Synthesize a `.github/workflows/*.yml` pipeline from a set of components:
+ * one job per component, `needs:` expressing the wave-ordered dependency DAG
+ * from `resolveComponentGraph`. Thin wrapper over {@link buildGithubPipelineDoc}
+ * + {@link emitPipelineYAML}.
+ */
+export function generateGithubPipeline(components, options = {}) {
+    const doc = buildGithubPipelineDoc(components, options);
+    return { yaml: emitPipelineYAML(doc), stages: doc.stages, jobs: doc.jobs, env: doc.environment };
+}

package/dist/composites/cache.js

@@ -0,0 +1,17 @@
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { Step } from "../generated/index.js";
+export const CacheAction = Composite((props) => {
+    const { defaults } = props;
+    const withObj = {
+        path: props.path,
+        key: props.key,
+    };
+    if (props.restoreKeys !== undefined)
+        withObj["restore-keys"] = props.restoreKeys.join("\n");
+    const step = new Step(mergeDefaults({
+        name: "Cache",
+        uses: "actions/cache@v4",
+        with: withObj,
+    }, defaults?.step));
+    return { step };
+}, "Cache");