@intentius/chant-lexicon-github 0.124.31 → 0.124.33

package/dist/components/ci-jobs.js

@@ -0,0 +1,98 @@
+/**
+ * The GitHub Actions job pieces the three generators share (#3765): the Op
+ * pipeline (`./generate-op-pipeline.ts`), the Op waves pipeline
+ * (`./generate-op-waves-pipeline.ts`) and the component pipeline
+ * (`./generate-pipeline.ts`). The forgejo lexicon builds on the same
+ * documents and applies its dialect. The forge-neutral rules (image default,
+ * branch defaults, tokens, permissions, setup and environment checks) are
+ * core's, in `@intentius/chant/ci-jobs`.
+ */
+import { emitYAML, emitYAMLEntry } from "@intentius/chant/yaml";
+import { BUILD_REQUEST_TAGS, GITHUB_JOB_TOKEN, pushBranches } from "@intentius/chant/ci-jobs";
+import { actionRef } from "../action-pins.js";
+/** The artifact actions every generated job uses, at the major the generators have always pinned. */
+export const UPLOAD_ARTIFACT = "actions/upload-artifact@v4";
+export const DOWNLOAD_ARTIFACT = "actions/download-artifact@v4";
+/** The checkout step; `fullHistory` fetches every commit, for a job that reads the base commit or measures a change with git. */
+export function checkoutStep(fullHistory = false) {
+    return fullHistory ? { uses: actionRef("actions/checkout"), with: { "fetch-depth": 0 } } : { uses: actionRef("actions/checkout") };
+}
+/** One `run:` step per line, so each line is its own step in the log. */
+export function runSteps(lines) {
+    return lines.map((line) => ({ run: line }));
+}
+/** A step that downloads `artifact` into `path`. */
+export function downloadArtifactStep(name, artifact, path) {
+    return { name, uses: DOWNLOAD_ARTIFACT, with: { name: artifact, path } };
+}
+/**
+ * A step that keeps a record as an artifact whatever the job's outcome, so a
+ * job that stops at a gate (exit 3) still hands its record on, and a re-run
+ * replaces it. Nothing to keep is not an error.
+ */
+export function keepRecordStep(name, artifact, path) {
+    return {
+        name,
+        if: "always()",
+        uses: UPLOAD_ARTIFACT,
+        with: { name: artifact, path, "if-no-files-found": "ignore", "include-hidden-files": true, overwrite: true },
+    };
+}
+/** A `concurrency:` mapping: one run at a time per group. */
+export function concurrency(group, cancelInProgress = false) {
+    return { group, "cancel-in-progress": cancelInProgress };
+}
+/** The job token, as a step's `GITHUB_TOKEN`; `gh` reads `GH_TOKEN` too, for a step that writes. */
+export function jobTokenEnv(gh = false) {
+    return gh ? { GITHUB_TOKEN: GITHUB_JOB_TOKEN, GH_TOKEN: GITHUB_JOB_TOKEN } : { GITHUB_TOKEN: GITHUB_JOB_TOKEN };
+}
+/**
+ * A trigger's `on:` mapping (#2084): `cron` runs on its schedule and by hand,
+ * `pull_request` on pull requests into its branches (every branch when it
+ * names none; no `workflow_dispatch`, since a PR event needs no manual
+ * escape hatch), `push` on pushes to its branches (core's default when it
+ * names none).
+ */
+export function onTrigger(trigger) {
+    switch (trigger.kind) {
+        case "cron":
+            return { schedule: [{ cron: trigger.schedule }], workflow_dispatch: {} };
+        case "pull_request":
+            return { pull_request: trigger.branches && trigger.branches.length > 0 ? { branches: trigger.branches } : {} };
+        case "push":
+            // #4169: a newest build runs at each build request's tag too, and by hand.
+            return trigger.build === "newest"
+                ? { push: { branches: pushBranches(trigger.branches), tags: [BUILD_REQUEST_TAGS] }, workflow_dispatch: {} }
+                : { push: { branches: pushBranches(trigger.branches) } };
+    }
+}
+/**
+ * A push Op's concurrency group (#4169): one per commit under `build:
+ * "every"`, so no push cancels or replaces another's run; one per ref under
+ * `newest`, so the newest push waits and each build request's tag runs on its
+ * own; and the Op's own name otherwise, one run at a time.
+ */
+export function opConcurrencyGroup(jobName, trigger) {
+    if (trigger.kind !== "push" || !trigger.build)
+        return jobName;
+    return trigger.build === "every" ? `${jobName}-\${{ github.sha }}` : `${jobName}-\${{ github.ref }}`;
+}
+/** Emit a workflow document as YAML, its sections in GitHub's customary order. */
+export function emitWorkflowYAML(doc) {
+    const sections = [];
+    if (doc.header && doc.header.length > 0)
+        sections.push(doc.header.join("\n"));
+    if (doc.name)
+        sections.push("name: " + emitYAML(doc.name, 0));
+    sections.push(emitYAMLEntry("on", doc.on));
+    if (doc.env && Object.keys(doc.env).length > 0)
+        sections.push(emitYAMLEntry("env", doc.env));
+    if (doc.defaults)
+        sections.push(emitYAMLEntry("defaults", doc.defaults));
+    if (doc.concurrency)
+        sections.push(emitYAMLEntry("concurrency", doc.concurrency));
+    if (doc.permissions && Object.keys(doc.permissions).length > 0)
+        sections.push(emitYAMLEntry("permissions", doc.permissions));
+    sections.push(emitYAMLEntry("jobs", doc.jobsDoc));
+    return sections.join("\n\n") + "\n";
+}

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

@@ -0,0 +1,440 @@
+/**
+ * Generate mode — scheduled Op → GitHub Actions workflow YAML (#927).
+ *
+ * The Op counterpart to `./generate-pipeline.ts` (#891): that module
+ * synthesizes a `workflow_dispatch`-triggered pipeline from a deploy-time
+ * component graph, this one synthesizes a cron-triggered workflow per
+ * stateless Op. An Op's cadence is an `OpSchedule` on the Op itself
+ * (`packages/core/src/op/types.ts`), runtime-neutral data each reader
+ * interprets; this module is the reader that turns it into a cron a GitHub
+ * runner fires (`WorkflowAuditOp`, `PipelineAuditOp`, `ReconcileOp`, … all
+ * accept an optional `schedule` precisely for this).
+ *
+ * GitHub Actions' `on.schedule` is workflow-scoped, not job-scoped, so unlike
+ * the component generator (one combined pipeline for the whole graph) this
+ * emits one workflow file per `ScheduledOpSpec`. Each workflow:
+ *  - triggers on its `ScheduledOpSpec`'s trigger (#2084): `cron` (the Op's
+ *    schedule, plus `workflow_dispatch` so manual runs stay available for
+ *    testing/dry-runs), `pull_request` (optionally filtered to `branches`,
+ *    no `workflow_dispatch` — a PR event needs no manual escape hatch), or
+ *    `push` (filtered to `branches`, defaulting to the repository's default
+ *    branch);
+ *  - declares only the `permissions:` its `findingMode` (and, for a
+ *    `pull_request` trigger, whether that mode posts a comment) needs —
+ *    `report` stays read-only, `issue`/`comment`/`pull-request` add the write
+ *    scope the Op's own activity uses (`gh issue create` / a comment on the
+ *    triggering PR / `gh pr create`, see `@intentius/chant/op`'s
+ *    `reconcilePr` activity) — never a blanket `write-all`. `comment` is the
+ *    one mode that constrains the trigger rather than only the scope: it
+ *    needs a pull request to post onto, so this generator refuses it by name
+ *    on any other trigger (#2231);
+ *  - runs exactly one invocation, `chant run <name>` by default — never
+ *    inlined audit/reconcile logic. The finding-mode itself is already baked
+ *    into the Op's own activity args at build time by the composite that
+ *    created it; this workflow only supplies the token the mode needs to act;
+ *  - on a `push` trigger only, runs that invocation with `--gated-exit 0`
+ *    and adds a follow-up job that says where the approval is pending
+ *    (#2243). See {@link GATED_EXIT_FLAG} and {@link gateNoticeJob}.
+ *
+ * Two per-Op options widen that shape without loosening it (#2242). A spec's
+ * `setup` list emits steps between the checkout and the `beforeScript` lines,
+ * `uses:` steps included, which is the only way a generated job can reach an
+ * action like `aws-actions/configure-aws-credentials`; {@link
+ * assertSetupSteps} refuses an unpinned or default-branch ref at build time.
+ * A spec's `permissions` map is merged over {@link permissionsFor}, adding
+ * scopes the finding-mode never grants (`id-token: write` is the whole
+ * reason) and never touching one it does; {@link mergePermissions} refuses a
+ * blanket grant, an overlap with the mode's own set, an unknown scope name,
+ * and pull-request write on a trigger that has no pull request.
+ *
+ * A third widens it the other way (#2257): a spec's `environment` emits
+ * `environment:` on the Op's own job, which is how a GitHub environment's
+ * protection rules — required reviewers above all — come to hold a generated
+ * apply. That is a second gate beside chant's own, not a replacement for it:
+ * the reviewer stops the job before any step runs, chant's gate ledger
+ * (#2119) stops the apply inside a run that already started, and the two
+ * compose in either combination. It costs {@link permissionsFor} nothing —
+ * environment protection is repository configuration, not a token scope — and
+ * {@link assertEnvironment} refuses only what would emit as configured and
+ * bind nothing.
+ *
+ * A fourth is per-Op credentials (#2290): a spec's `variables` emits the Op's
+ * own job-level `env:`, beside (and layered over, on a key collision)
+ * `options.variables`'s workflow-level `env:`. `options.variables` keeps
+ * meaning what it always has — set once, landing on every generated file — so
+ * a caller who declares nothing per-Op sees byte-identical output; a spec's
+ * own `variables` is the way one Op's job can hold a credential no other Op's
+ * job receives, which a workflow-level declaration can never express because
+ * every generated file here has exactly the one Op job (plus, on a `push`
+ * trigger, the gate-notice job beside it — job-level `env:` does not reach
+ * that job either, same as `environment:` above does not).
+ */
+import { readFileSync } from "node:fs";
+import { assertEnvironment, assertSetupSteps, CI_IMAGE, ciJobName, environmentDoc, fillCommand, GITHUB_JOB_TOKEN, GITHUB_RUNNER, mergePermissions, nonEmpty, permissionsFor, setupStepDoc, } from "@intentius/chant/ci-jobs";
+import { memberPathFilter, resolveOpTrigger } from "@intentius/chant/lexicon";
+import { checkoutStep, concurrency, emitWorkflowYAML, jobTokenEnv, onTrigger, opConcurrencyGroup, runSteps } from "./ci-jobs.js";
+// The setup, environment and permission checks are shared with the Op waves
+// generator and the forgejo lexicon (#3765); they stay importable from here.
+export { assertEnvironment, assertSetupSteps, mergePermissions };
+// ── The gated apply (#2243) ─────────────────────────────────────────────────
+/**
+ * `chant run` returns 3 when a run stops at an unapproved gate. GitHub Actions
+ * has no neutral conclusion for a `run:` step, so a push-to-main apply that
+ * gates paints the branch red on every merge until someone approves. This maps
+ * that one outcome to success, in chant rather than in a shell wrapper
+ * (#2243); a failed run still returns 1 and is still red.
+ *
+ * `push` only. A cron watch and a `pull_request` plan are never gated in a way
+ * that should be hidden: nobody is waiting on a merge for either, and a gated
+ * one there is a signal, not noise.
+ */
+const GATED_EXIT_FLAG = ["--gated-exit", "0"];
+/** The id of the `chant run` step on a `push` job, so the job can publish its outputs. */
+const RUN_STEP_ID = "chant-run";
+/**
+ * Turn the run's `--json` record into step outputs, so the notice job below
+ * has a condition to test and a gate to name. Runs in node, which is already
+ * on any machine `chant` runs on — unlike `jq`, which the Op's own container
+ * image need not carry.
+ *
+ * Nothing is written for a run that completed, so `gated` is either the string
+ * `true` or absent, and the notice job's `if:` is a plain equality.
+ */
+const GATE_OUTPUT_SCRIPT = 'const fs=require("fs");' +
+    'const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));' +
+    'if(r.status!=="gated"||!process.env.GITHUB_OUTPUT)process.exit(0);' +
+    "fs.appendFileSync(process.env.GITHUB_OUTPUT," +
+    '`gated=true\\nop=${r.op}\\ngate=${(r.gate&&r.gate.name)||""}\\napprove=${r.approve||""}\\n`)';
+/**
+ * The `push` job's run step: the invocation with {@link GATED_EXIT_FLAG} and
+ * `--json`, tee'd so the record is both in the log and on disk, then read for
+ * the job's outputs.
+ *
+ * The exit-code capture below is not decoration. Piping straight into `tee`
+ * — `chant run ... | tee "$json"` — reports `tee`'s own zero as the step's
+ * result no matter what `chant run` exited with, and turns a broken apply
+ * green, which is the exact thing this step must not do. bash's fix for that
+ * is `set -o pipefail`, but `pipefail` is a bash-ism, and this generator's
+ * own Op job always sets `container:` (see {@link buildGithubOpPipelineDocs}'s
+ * `container: image`) — GitHub's (and Forgejo's) default shell for a
+ * `container:` job is plain `sh`, which rejects `set -o pipefail` outright
+ * (`Illegal option -o pipefail`) and fails the step before `chant` ever runs
+ * (#2299). #2307 first fixed that by pairing the `pipefail` line with an
+ * unconditional `shell: "bash"` on the step — which then broke every
+ * consumer whose `options.image` has no bash on it at all, e.g. an
+ * `alpine:*` or distroless image (#2321): busybox `ash` ran the old
+ * plain-pipe script fine, so pinning `shell: bash` regressed exactly the
+ * images that never needed pipefail's workaround in the first place.
+ *
+ * So this step needs no shell declaration and runs under whatever `sh` the
+ * consumer's image provides. It gets the same failure-cannot-hide guarantee
+ * `pipefail` gave, without the bash-ism, by capturing the invocation's own
+ * exit code into a file from *inside* the pipeline's first stage — where
+ * `tee` can never see it — and checking that file once the pipe finishes:
+ * `{ invocation; echo "$?" >status; } | tee "$json"` followed by `exit
+ * "$(cat "$status")"` when that is non-zero. `set +e` up front makes this
+ * work under any default shell a container job might get, `-e` included:
+ * GitHub's documented `sh` template is `sh -e {0}`, and without `set +e`
+ * `-e` would abort the brace group at the first failing command — before
+ * `echo "$?"` ever runs — which was verified by running both this script and
+ * that failure mode under bash and dash directly, `-e` on. Everything past
+ * that point (`set +e`, `{ }`, `$(...)`, `[ ]`) is POSIX `sh`, so it needs no
+ * `shell:` field to run correctly under `ash`, `dash`, or bash alike, and
+ * #2299 does not reopen: nothing here is a bash-only construct.
+ *
+ * The `node -e` line and the job's own `outputs:` mapping exist for exactly
+ * one reader: the gate-notice job beside it, which is `needs:`-only readable
+ * through `steps.<id>.outputs`/`needs.<job>.outputs`. Forgejo dropped both
+ * while it had no notice job (#2294) and carries them again since #3773. The
+ * tee'd invocation is what puts the run's own JSON record in the log.
+ */
+function gatedRunStep(id, op, invocation, env) {
+    const lines = [
+        "set +e",
+        'json="${RUNNER_TEMP:-/tmp}/chant-run-' + op + '.json"',
+        'status="${RUNNER_TEMP:-/tmp}/chant-run-' + op + '.status"',
+        `{ ${invocation}; echo "$?" >"$status"; } | tee "$json"`,
+        'code=$(cat "$status")',
+        '[ "$code" -eq 0 ] || exit "$code"',
+    ];
+    lines.push(`node -e '${GATE_OUTPUT_SCRIPT}' "$json"`);
+    return { id, run: lines.join("\n"), env };
+}
+/**
+ * The chant release the notice job installs: this lexicon's own version.
+ * The github lexicon and `@intentius/chant` release in lockstep, so the pr-forge
+ * a generated workflow runs is the one this generator was built against, and
+ * it changes only when the workflow is regenerated, the same as a pinned
+ * action ref.
+ */
+function chantVersion() {
+    const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+    if (typeof pkg.version !== "string" || pkg.version === "") {
+        throw new Error("the github lexicon's package.json has no version to pin the gate-notice job's chant to");
+    }
+    return pkg.version;
+}
+/**
+ * What the notice job runs under node (#3773): the sticky-comment recipe
+ * `reconcilePr`'s `comment` mode uses, through the same
+ * `@intentius/chant/pr-forge` clients, so it posts on GitHub, GitHub
+ * Enterprise Server and Forgejo alike. `forgeTargetFromEnv` reads the forge,
+ * the REST base, the repository, the commit and the token off the job's
+ * environment (`FORGE_TOKEN_ORDER`: `CHANT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` on
+ * GitHub; `CHANT_FORGEJO_TOKEN` first on Forgejo), the order `reconcilePr` reads too (#3807),
+ * and `pullRequestFor` is the commit-to-pull-request lookup each forge spells
+ * its own way (`commits/{sha}/pulls` on GitHub, `commits/{sha}/pull` on
+ * Forgejo). A commit with no pull request, a direct push, gets a tracking
+ * issue keyed on the same marker, so a second gated push edits it rather
+ * than opening another.
+ *
+ * Plain JavaScript in double-quoted strings, so the markdown backticks need
+ * no escaping and nothing in it reads as a `${{ }}` expression.
+ */
+const NOTICE_SCRIPT = [
+    'import { forgeClient, forgeTargetFromEnv } from "@intentius/chant/pr-forge";',
+    "const { CHANT_OP: op, CHANT_GATE: gate, CHANT_APPROVE: approve } = process.env;",
+    "const target = forgeTargetFromEnv(process.env);",
+    "const forge = forgeClient(target);",
+    'const marker = "<!-- chant-gate:" + op + " -->";',
+    'const fence = "```";',
+    "const body = [",
+    "  marker,",
+    '  "",',
+    '  "The `" + op + "` apply for " + target.sha + " stopped at gate `" + gate + "` and is waiting for an approval. Nothing was applied.",',
+    '  "",',
+    "  fence,",
+    '  approve + " --approver <you>",',
+    "  fence,",
+    '  "",',
+    '  "The pending fact is on `_gates/" + op + ".jsonl` on the `chant/lifecycle` branch. Approving is a commit: push it and this workflow runs again and applies.",',
+    '].join("\\n") + "\\n";',
+    "const pr = target.sha ? await forge.pullRequestFor(target.sha) : null;",
+    "const url = pr",
+    "  ? await forge.upsertNote(pr, marker, body)",
+    '  : await forge.upsertIssue(marker, op + " is waiting on gate " + gate, body);',
+    'console.log(url ?? (pr ? "commented on #" + pr : "kept the tracking issue"));',
+].join("\n");
+/**
+ * The notice step's shell (#3773). It installs the pinned chant into the
+ * runner's temp directory and runs {@link NOTICE_SCRIPT} with tsx, which
+ * chant depends on and which is how `chant` itself runs its TypeScript.
+ * `--omit=peer` keeps chant's optional vitest peer out: about 17 packages,
+ * a few seconds. The `package.json` written first stops npm from walking up
+ * to some other project root. No checkout and no `beforeScript`: the job
+ * reads nothing out of the repository.
+ */
+function gateNoticeScript(version) {
+    return [
+        'dir="${RUNNER_TEMP:-/tmp}/chant-gate-notice"',
+        'mkdir -p "$dir"',
+        'cd "$dir"',
+        "echo '{\"private\":true}' > package.json",
+        `npm install --omit=peer --no-audit --no-fund --loglevel=error @intentius/chant@${version}`,
+        "cat > notice.mjs <<'NOTICE'",
+        NOTICE_SCRIPT,
+        "NOTICE",
+        "node --import tsx notice.mjs",
+    ].join("\n");
+}
+/**
+ * The follow-up job: `needs:` the apply, runs only when the apply reported
+ * gated, and puts the pending state somewhere other than the Actions log.
+ *
+ * It runs in the Op's own image, which carries node and npm by construction
+ * (the apply's `node -e` output step needs them too), so it runs the same on
+ * GitHub's hosted runners and on a Forgejo runner. It checks nothing out.
+ *
+ * Its `permissions:` are its own, replacing the workflow-level set for this
+ * job alone: `contents: read` for the commit-to-pull-request lookup,
+ * `pull-requests: write` for the sticky comment, `issues: write` for the
+ * tracking issue when the push has no pull request. Nothing wider: it opens
+ * no branch and merges nothing. The Forgejo dialect drops them, as it drops
+ * every scope but `id-token`.
+ */
+function gateNoticeJob(applyJobName, image) {
+    const output = (name) => "${{ needs." + applyJobName + ".outputs." + name + ' }}';
+    return {
+        needs: applyJobName,
+        if: `needs.${applyJobName}.outputs.gated == 'true'`,
+        "runs-on": GITHUB_RUNNER,
+        container: image,
+        permissions: { contents: "read", issues: "write", "pull-requests": "write" },
+        steps: [
+            {
+                name: "Report the pending gate",
+                env: {
+                    GITHUB_TOKEN: GITHUB_JOB_TOKEN,
+                    CHANT_OP: output("op"),
+                    CHANT_GATE: output("gate"),
+                    CHANT_APPROVE: output("approve"),
+                },
+                run: gateNoticeScript(chantVersion()),
+            },
+        ],
+    };
+}
+/**
+ * Refuse `findingMode: "comment"` on a trigger that has no pull request
+ * (#2231). The mode's activity reads the triggering PR out of the event
+ * payload at run time, so a cron- or push-triggered job carrying it would
+ * generate fine and then fail on every run. Refusing here names the Op, the
+ * mode and the trigger at build time instead.
+ */
+function assertTriggerSupportsMode(name, mode, trigger) {
+    if (mode !== "comment" || trigger.kind === "pull_request")
+        return;
+    throw new Error(`Scheduled Op "${name}" has findingMode "comment", which posts its finding on the pull request that ` +
+        `triggered the run, but its trigger is "${trigger.kind}". A ${trigger.kind} run has no pull request ` +
+        `to comment on. Give it a { kind: "pull_request" } trigger, or use findingMode "issue".`);
+}
+/**
+ * Build one `GithubOpPipelineDoc` per scheduled Op: its trigger, its `setup`
+ * steps, least-privilege `permissions:` for its finding-mode plus whatever
+ * the spec adds, one job that runs `chant run <name>`. Every
+ * `ScheduledOpSpec` is independent — unlike the component generator there is
+ * no shared graph to resolve — so the only thing this refuses is a spec that
+ * contradicts itself: no trigger at all (`resolveOpTrigger`), `findingMode:
+ * "comment"` on a trigger that has no pull request ({@link
+ * assertTriggerSupportsMode}), an unpinned `setup` action ({@link
+ * assertSetupSteps}), or a `permissions` entry that is not additive ({@link
+ * mergePermissions}).
+ */
+export function buildGithubOpPipelineDocs(ops, options = {}) {
+    const image = options.image ?? CI_IMAGE;
+    const runCommand = options.runCommand ?? ["chant", "run", "{name}"];
+    const beforeScript = options.beforeScript ?? [];
+    const extraScript = options.extraScript ?? [];
+    const files = [];
+    const jobs = [];
+    for (const spec of ops) {
+        const findingMode = spec.findingMode ?? "report";
+        const trigger = resolveOpTrigger(spec);
+        assertTriggerSupportsMode(spec.name, findingMode, trigger);
+        const jobName = ciJobName(spec.name);
+        jobs.push({ jobName, op: spec.name, trigger, findingMode });
+        const runParts = fillCommand(runCommand, spec.name);
+        // A live-resolution read (rate limits) always benefits from a token;
+        // creating an issue/PR additionally needs `gh` CLI's own token variable.
+        const stepEnv = jobTokenEnv(findingMode !== "report");
+        const setup = spec.setup ?? [];
+        assertSetupSteps(spec.name, setup);
+        if (spec.environment)
+            assertEnvironment(spec.name, spec.environment);
+        // A `push` job is the one that has to survive a gate (#2243): the apply
+        // runs with `--gated-exit 0` so a pending approval is a green run, and
+        // publishes what it stopped on as job outputs for the notice job below.
+        // Every other trigger keeps the plain one-line invocation it always had.
+        const gated = trigger.kind === "push";
+        const invocation = gated
+            ? [...runParts, ...GATED_EXIT_FLAG, "--json"].join(" ")
+            : runParts.join(" ");
+        const steps = [checkoutStep(), ...setup.map(setupStepDoc), ...runSteps(beforeScript)];
+        steps.push(gated
+            ? gatedRunStep(RUN_STEP_ID, spec.name, invocation, stepEnv)
+            : { run: invocation, env: stepEnv });
+        steps.push(...runSteps(extraScript));
+        const doc = {
+            name: spec.name,
+            on: onTrigger(trigger),
+            ...nonEmpty("env", options.variables),
+            // 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),
+            jobsDoc: {
+                [jobName]: {
+                    "runs-on": GITHUB_RUNNER,
+                    container: image,
+                    // Per-Op credentials (#2290): job-level `env:`, one level more
+                    // specific than `options.variables`'s workflow-level `env:` above,
+                    // and never on the notice job beside it — same reason `environment:`
+                    // isn't either, it's this Op's own job alone.
+                    ...nonEmpty("env", spec.variables),
+                    // On this Op's own job and never on the notice job beside it: the
+                    // notice exists to say a chant gate is pending, and putting it
+                    // behind the same reviewer would hold the message back until
+                    // somebody had already acted.
+                    ...(spec.environment ? { environment: environmentDoc(spec.environment) } : {}),
+                    ...(gated
+                        ? {
+                            outputs: Object.fromEntries(["gated", "op", "gate", "approve"].map((name) => [
+                                name,
+                                `\${{ steps.${RUN_STEP_ID}.outputs.${name} }}`,
+                            ])),
+                        }
+                        : {}),
+                    steps,
+                },
+            },
+            ...(gated ? { gatedNoticeDoc: { [`${jobName}-gate-notice`]: gateNoticeJob(jobName, image) } } : {}),
+        };
+        files.push({ name: `${spec.name}.yml`, doc });
+    }
+    if (options.member) {
+        const member = options.member;
+        return { files: files.map((f) => scopeOpFileToMember(f, member)), jobs };
+    }
+    return { files, jobs };
+}
+/**
+ * Scope one Op's workflow to a workspace member (#2542, #2524 D19). The file
+ * and the workflow take the member's name (`<member>-<op>.yml`, `<member>/<op>`)
+ * and so does the concurrency group, which GitHub keys across the whole
+ * repository. A `push` or `pull_request` trigger is filtered to the member's
+ * paths and this file; a cron trigger has no paths to filter. The Op's own
+ * job starts its `run:` steps in the member's directory. The gate-notice job
+ * checks nothing out and keeps the default.
+ */
+function scopeOpFileToMember(file, member) {
+    const name = `${member.name}-${file.name}`;
+    const paths = memberPathFilter(member, member.fileDir ? `${member.fileDir}/${name}` : undefined);
+    const on = { ...file.doc.on };
+    for (const event of ["push", "pull_request"]) {
+        if (event in on)
+            on[event] = { ...on[event], paths };
+    }
+    const rooted = member.dir === "." || member.dir === "";
+    const jobsDoc = rooted
+        ? file.doc.jobsDoc
+        : Object.fromEntries(Object.entries(file.doc.jobsDoc).map(([job, props]) => {
+            const { steps, ...rest } = props;
+            return [job, { ...rest, defaults: { run: { "working-directory": member.dir } }, steps }];
+        }));
+    const group = file.doc.concurrency.group;
+    return {
+        name,
+        doc: {
+            ...file.doc,
+            ...(file.doc.name ? { name: `${member.name}/${file.doc.name}` } : {}),
+            on,
+            concurrency: { ...file.doc.concurrency, ...(typeof group === "string" ? { group: `${member.name}-${group}` } : {}) },
+            jobsDoc,
+        },
+    };
+}
+/**
+ * Emit a `GithubOpPipelineDoc`'s `on`/`env`/`concurrency`/`permissions`/`jobs`
+ * mappings as workflow YAML. Shared with the forgejo dialect (#969), which
+ * transforms the doc first (and drops `permissions`, which it ignores).
+ */
+export function emitOpPipelineYAML(doc) {
+    // 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, ...workflow } = doc;
+    return emitWorkflowYAML({ ...workflow, jobsDoc: { ...doc.jobsDoc, ...(gatedNoticeDoc ?? {}) } });
+}
+/**
+ * Synthesize one `.github/workflows/*.yml` per scheduled Op. Thin wrapper
+ * over {@link buildGithubOpPipelineDocs} + {@link emitOpPipelineYAML}. Wired
+ * into core's Op generate mode via the github lexicon plugin's
+ * `generateOpPipeline` (../plugin.ts).
+ */
+export function generateGithubOpPipeline(ops, options = {}) {
+    const { files, jobs } = buildGithubOpPipelineDocs(ops, options);
+    return {
+        files: files.map((f) => ({ name: f.name, yaml: emitOpPipelineYAML(f.doc) })),
+        jobs,
+    };
+}