@intentius/chant-lexicon-github 0.124.54 → 0.124.55

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;AAgCjG,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;AAgfD;;;;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;AAuCjG,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;AAsmBD;;;;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

@@ -61,11 +61,16 @@ import { GATED_WAVE_RECORD, gatedWaveJobs } from "@intentius/chant/components/ga
 import { CI_IMAGE, ciJobName, dirnameOf, fillCommand, GITHUB_JOB_TOKEN, GITHUB_RUNNER } from "@intentius/chant/ci-jobs";
 import { CHECKOUT_TOKEN_ENV, checkoutScript, dropForgeTokens, handoverOutputs, handoverTrap, takeOverScript } from "@intentius/chant/ci-handover";
 import { OIDC_REQUEST_VARS, TRADE_SPEC_ENV, tradeLine } from "@intentius/chant/ci-identity";
-import { APPLY_COMMENT, GREEN_TAG_PATTERN, GREEN_TICK_WORKFLOW, PR_APPLY_RECORD, PR_LOOP_REPORT_DIR, prApplyGroup, prRecordGroup, prApplyRecordKey, prApplyWaveJobName, prLoopJobs, prLoopPostJob, prLoopSetup, PR_PLAN_NOTE_JOB, PR_LOCK_JOB, PR_UNLOCK_JOB, PR_UNLOCK_COMMAND, prLockCommand, prLoopWaveJobs, prLoopWithWaves, prEnvJobs, PR_ENV_REPORT_DIR, PR_ENV_SWEEP_CRON, PR_ENV_POST_JOB, } from "@intentius/chant/components/pr-pipeline";
+import { prApplyComment, GREEN_TAG_PATTERN, GREEN_TICK_WORKFLOW, PR_APPLY_RECORD, PR_LOOP_REPORT_DIR, prApplyGroup, prRecordGroup, prApplyRecordKey, prApplyWaveJobName, prLoopJobs, prLoopPostJob, prLoopSetup, PR_PLAN_NOTE_JOB, PR_LOCK_JOB, PR_UNLOCK_JOB, PR_UNLOCK_COMMAND, prLockCommand, prCommentLockJobs, prCommentPreviewJob, PREVIEW_REF_ENV, PREVIEW_HEAD_OUTPUT, prLoopWaveJobs, prLoopWithWaves, prEnvJobs, PR_ENV_REPORT_DIR, PR_ENV_SWEEP_CRON, PR_ENV_POST_JOB, } from "@intentius/chant/components/pr-pipeline";
+import { forgejoRepoLockLines, REPO_APPLY_GROUP } from "@intentius/chant/components/repo-lock";
 import { memberRepoPath } from "@intentius/chant/lexicon";
+import { productStatusContext, resolveProductWords } from "@intentius/chant/ci-product-words";
+import { controlDispatchJob, controlNoteCheckout } from "@intentius/chant/control/dispatch";
 import { afterEarlierWave, CACHE_RESTORE, CACHE_SAVE, CHECKOUT, checkoutStep, concurrency, downloadArtifactStep, emitWorkflowYAML, keepRecordStep, runSteps, UPLOAD_ARTIFACT } from "./ci-jobs.js";
 /** The plan job's last step, whose outputs carry its report to the plan-note job (#4295). */
 const PLAN_STEP_ID = "plan";
+/** The comment preview's checkout step (#4620), whose output names the head it checked out. */
+const PREVIEW_HEAD_STEP_ID = "head";
 /** The output a gated apply wave hands the green commit it applies through, and the step that sets it (#4221). */
 const WAVE_GREEN_OUTPUT = "green-sha";
 const WAVE_STEP_ID = "apply";
@@ -203,10 +208,12 @@ function prLoopGithubDoc(components, env, image, beforeScript, extraScript, opti
     });
     const withIdToken = (permissions) => (identity ? { ...permissions, "id-token": "write" } : permissions);
     const reportName = (job) => `chant-pr-${job.wave ? prApplyWaveJobName(job.wave) : job.jobName}`;
+    // #4552: on the repo grain a Forgejo apply takes the lock tag in its own step, before the command, since the runner does not queue on a concurrency group.
+    const repoLock = (job) => (loop.lockGrain === "repo" && loop.forge === "forgejo" && job.jobName !== "record" ? forgejoRepoLockLines() : []);
     const steps = (job, name) => [
         ...(identity ? [tradeStep(job.jobName === "record" ? identity.plan : identity.apply, job.jobName === "record" ? "plan" : "apply")] : []),
         checkoutStep(true),
-        ...runSteps(prLoopSetup(image)),
+        ...runSteps(prLoopSetup(image, loop.engineSetup)),
         ...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)] : []),
@@ -218,9 +225,9 @@ function prLoopGithubDoc(components, env, image, beforeScript, extraScript, opti
                 name,
                 id: WAVE_STEP_ID,
                 env: { ...job.run.env, ...(job.wave > 1 ? { GREEN_SHA: `\${{ needs.${prApplyWaveJobName(job.wave - 1)}.outputs.${WAVE_GREEN_OUTPUT} }}` } : {}) },
-                run: [...(job.checkout ?? []), `echo "${WAVE_GREEN_OUTPUT}=$GREEN_SHA" >> "$GITHUB_OUTPUT"`, ...(job.setup ?? []), job.run.command].join("\n"),
+                run: [...(job.checkout ?? []), `echo "${WAVE_GREEN_OUTPUT}=$GREEN_SHA" >> "$GITHUB_OUTPUT"`, ...(job.setup ?? []), ...repoLock(job), job.run.command].join("\n"),
             }
-            : { name, env: job.run.env, run: [...(job.checkout ?? []), ...(job.setup ?? []), job.run.command].join("\n") },
+            : { name, env: job.run.env, run: [...(job.checkout ?? []), ...(job.setup ?? []), ...repoLock(job), job.run.command].join("\n") },
         ...runSteps(extraScript),
         ...(job.jobName === "apply" ? [saveRecord(job.wave)] : []),
         {
@@ -239,7 +246,7 @@ function prLoopGithubDoc(components, env, image, beforeScript, extraScript, opti
         "github.event_name == 'issue_comment'",
         // Forgejo's payload says so with is_pull (terragucci comment-apply.ts:129 at e6cb431).
         forgejo ? "(github.event.issue.pull_request || github.event.is_pull)" : "github.event.issue.pull_request",
-        `startsWith(github.event.comment.body, '${APPLY_COMMENT}')`,
+        `startsWith(github.event.comment.body, '${prApplyComment(loop)}')`,
         ...(forgejo ? [] : ["contains(fromJSON('[\"OWNER\",\"MEMBER\",\"COLLABORATOR\"]'), github.event.comment.author_association)"]),
     ].join(" && ");
     const applyJob = (job, needs, name) => ({
@@ -248,7 +255,8 @@ function prLoopGithubDoc(components, env, image, beforeScript, extraScript, opti
         "runs-on": GITHUB_RUNNER,
         ...(needs.length > 0 ? { needs } : {}),
         container: image,
-        concurrency: concurrency(prApplyGroup(env, member?.name)),
+        // #4552: on the repo grain every apply of the repository shares one group.
+        concurrency: concurrency(loop.lockGrain === "repo" ? REPO_APPLY_GROUP : prApplyGroup(env, member?.name)),
         permissions: withIdToken({ contents: "write", "pull-requests": "write", statuses: "write" }),
         ...(job.wave ? { outputs: { [WAVE_GREEN_OUTPUT]: `\${{ steps.${WAVE_STEP_ID}.outputs.${WAVE_GREEN_OUTPUT} }}` } } : {}),
         steps: steps(job, name),
@@ -281,7 +289,7 @@ function prLoopGithubDoc(components, env, image, beforeScript, extraScript, opti
             env: { [CHECKOUT_TOKEN_ENV]: GITHUB_JOB_TOKEN },
             run: checkoutScript(true, true),
         },
-        ...[...prLoopSetup(image), ...beforeScript].map((line) => headStep(line)),
+        ...[...prLoopSetup(image, loop.engineSetup), ...beforeScript].map((line) => headStep(line)),
         ...(plan.build ? [headStep(plan.build[0], "Build the templates"), headStep(plan.build[1], "Lint the project")] : []),
         // The job's last step: a step after it would start beside whatever the change's code left running.
         {
@@ -291,14 +299,40 @@ function prLoopGithubDoc(components, env, image, beforeScript, extraScript, opti
             run: [drop, ...handoverTrap(PR_LOOP_REPORT_DIR, forgeName), ...(plan.checkout ?? []), ...(plan.setup ?? []), plan.run.command, ...extraScript].join("\n"),
         },
     ];
-    const post = prLoopPostJob(forgeName, env, member?.name);
+    // #4568: once the last apply on merge succeeded, one job tells the control repo this member applied.
+    const lastGreen = loop.control && !loop.applyBeforeMerge && greenJobs.length > 0 ? greenJobs[greenJobs.length - 1][0] : undefined;
+    const controlJobs = [];
+    if (loop.control && lastGreen) {
+        // A wave job hands on the commit it applied; a single apply job applies the green commit its trigger names.
+        const sha = loop.waveGate ? `\${{ needs.${lastGreen}.outputs.${WAVE_GREEN_OUTPUT} }}` : forgejo ? "${{ github.sha }}" : "${{ github.event.workflow_run.head_sha || github.sha }}";
+        const dispatch = controlDispatchJob(forgeName, loop.control.target, sha, {
+            ...(loop.words ? { words: loop.words } : {}),
+            ...(loop.control.sentCheck ? { sentCheck: loop.control.sentCheck } : {}),
+            ...(loop.control.markSent ? { markSent: loop.control.markSent } : {}),
+        });
+        controlJobs.push([
+            dispatch.name,
+            {
+                needs: [lastGreen],
+                if: `success() && (${onGreen})`,
+                "runs-on": GITHUB_RUNNER,
+                container: image,
+                permissions: loop.control.markSent ? { contents: "read", statuses: "write" } : { contents: "read" },
+                steps: [{ name: dispatch.stepName, ...(rooted ? {} : { "working-directory": "." }), env: { ...dispatch.env, ...(loop.control.sentCheck || loop.control.markSent ? { GITHUB_TOKEN: GITHUB_JOB_TOKEN } : {}) }, run: dispatch.script }],
+            },
+        ]);
+    }
+    const post = prLoopPostJob(forgeName, env, member?.name, loop.words ? resolveProductWords(loop.words) : undefined);
+    // #4619: with a control repo named, the note job reads its chant/lifecycle, read-only, so pr-post marks the cross-stack edges.
+    const controlRead = loop.control ? controlNoteCheckout(forgeName, loop.control.target, loop.words ?? {}) : undefined;
     const noteSteps = [
         // The target branch's commit: the chant this job runs is the target branch's, and none of the change's code is here.
         { name: "Check out the target branch's commit", uses: CHECKOUT, with: { ref: "${{ github.event.pull_request.base.sha }}" } },
         ...runSteps(beforeScript),
         { name: "Take the plan report from the plan job", run: takeOverScript("plan", PR_LOOP_REPORT_DIR, forgeName) },
         { name: "Keep the plan report", if: "always()", uses: UPLOAD_ARTIFACT, with: { name: reportName(plan), path: reportPath, "if-no-files-found": "ignore", "include-hidden-files": true } },
-        { name: "Post the plan note and chant/plan", if: "always()", env: post.env, run: post.command },
+        ...(controlRead ? [{ name: controlRead.stepName, if: "always()", env: controlRead.env, run: controlRead.script }] : []),
+        { name: `Post the plan note and ${productStatusContext(resolveProductWords(loop.words), "plan")}`, if: "always()", env: post.env, run: post.command },
     ];
     // #4298: with a pull request environment the pull_request trigger fires on close too, and the plan skips that event.
     const prEnv = loop.prEnvironment ? prEnvGithubJobs(loop.forge ?? "github", image, beforeScript, extraScript, loop, member) : undefined;
@@ -339,6 +373,80 @@ function prLoopGithubDoc(components, env, image, beforeScript, extraScript, opti
             },
         }
         : {};
+    // #4588: `/<product> lock` and `/<product> unlock` comments, at the target branch's commit, so none of the change's code runs.
+    const commentLocks = prCommentLockJobs(forgeName, loop);
+    const commentLockJobs = Object.fromEntries(commentLocks.map((job) => [
+        job.jobName,
+        {
+            if: [
+                "github.event_name == 'issue_comment'",
+                forgejo ? "(github.event.issue.pull_request || github.event.is_pull)" : "github.event.issue.pull_request",
+                `startsWith(github.event.comment.body, '${job.comment}')`,
+                ...(forgejo ? [] : ["contains(fromJSON('[\"OWNER\",\"MEMBER\",\"COLLABORATOR\"]'), github.event.comment.author_association)"]),
+            ].join(" && "),
+            "runs-on": GITHUB_RUNNER,
+            container: image,
+            permissions: { contents: "write", "pull-requests": "read", statuses: "write" },
+            steps: [
+                { name: "Check out the target branch's commit", uses: CHECKOUT, with: { "fetch-depth": 0 } },
+                ...runSteps(beforeScript),
+                { name: job.command === "lock" ? "Keep the locks the pull request's plan took" : "Release the pull request's locks", env: job.env, run: job.line },
+            ],
+        },
+    ]));
+    // #4620: `/<product> <plan word>` plans the pull request's head again with a read token; the job after it posts the note.
+    const preview = prCommentPreviewJob(forgeName, env, loop, member?.name);
+    const previewJobs = preview
+        ? {
+            [preview.jobName]: {
+                if: [
+                    "github.event_name == 'issue_comment'",
+                    forgejo ? "(github.event.issue.pull_request || github.event.is_pull)" : "github.event.issue.pull_request",
+                    `startsWith(github.event.comment.body, '${preview.comment}')`,
+                    ...(forgejo ? [] : ["contains(fromJSON('[\"OWNER\",\"MEMBER\",\"COLLABORATOR\"]'), github.event.comment.author_association)"]),
+                ].join(" && "),
+                "runs-on": GITHUB_RUNNER,
+                container: image,
+                permissions: withIdToken({ contents: "read" }),
+                outputs: { ...handoverOutputs(PLAN_STEP_ID, forgeName), [PREVIEW_HEAD_OUTPUT]: `\${{ steps.${PREVIEW_HEAD_STEP_ID}.outputs.${PREVIEW_HEAD_OUTPUT} }}` },
+                steps: [
+                    ...(identity ? [tradeStep(identity.plan, "plan")] : []),
+                    // The head is read here, before any of the change's code runs, so the post job names the commit this job planned.
+                    {
+                        name: "Check out the pull request's head",
+                        id: PREVIEW_HEAD_STEP_ID,
+                        ...(rooted ? {} : { "working-directory": "." }),
+                        env: { [CHECKOUT_TOKEN_ENV]: GITHUB_JOB_TOKEN, [PREVIEW_REF_ENV]: "ref" in preview.head ? preview.head.ref : "" },
+                        run: [checkoutScript(true, true, { refEnv: PREVIEW_REF_ENV }), `echo "${PREVIEW_HEAD_OUTPUT}=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"`].join("\n"),
+                    },
+                    ...[...prLoopSetup(image, loop.engineSetup), ...beforeScript].map((line) => headStep(line)),
+                    ...(preview.plan.build ? [headStep(preview.plan.build[0], "Build the templates"), headStep(preview.plan.build[1], "Lint the project")] : []),
+                    {
+                        name: "Preview the members this pull request reaches",
+                        id: PLAN_STEP_ID,
+                        env: preview.plan.run.env,
+                        run: [drop, ...handoverTrap(PR_LOOP_REPORT_DIR, forgeName), preview.base, ...(preview.plan.setup ?? []), preview.plan.run.command, ...extraScript].join("\n"),
+                    },
+                ],
+            },
+            [preview.noteJobName]: {
+                needs: [preview.jobName],
+                if: `always() && github.event_name == 'issue_comment' && (needs.${preview.jobName}.result == 'success' || needs.${preview.jobName}.result == 'failure')`,
+                "runs-on": GITHUB_RUNNER,
+                container: image,
+                permissions: { actions: "read", contents: "read", "pull-requests": "write", statuses: "write" },
+                steps: [
+                    // The target branch's commit, which an issue_comment run checks out: none of the change's code is here.
+                    { name: "Check out the target branch's commit", uses: CHECKOUT },
+                    ...runSteps(beforeScript),
+                    { name: "Take the preview report from the preview job", run: takeOverScript(preview.jobName, PR_LOOP_REPORT_DIR, forgeName) },
+                    { name: "Keep the preview report", if: "always()", uses: UPLOAD_ARTIFACT, with: { name: `chant-pr-${preview.jobName}`, path: reportPath, "if-no-files-found": "ignore", "include-hidden-files": true } },
+                    ...(controlRead ? [{ name: controlRead.stepName, if: "always()", env: controlRead.env, run: controlRead.script }] : []),
+                    { name: `Post the preview note and ${productStatusContext(resolveProductWords(loop.words), "plan")}`, if: "always()", env: preview.post.env, run: preview.post.command },
+                ],
+            },
+        }
+        : {};
     const jobsDoc = {
         plan: {
             if: closes ? "github.event_name == 'pull_request' && github.event.action != 'closed'" : "github.event_name == 'pull_request'",
@@ -358,7 +466,10 @@ function prLoopGithubDoc(components, env, image, beforeScript, extraScript, opti
             steps: noteSteps,
         },
         ...lockJobs,
+        ...commentLockJobs,
+        ...previewJobs,
         ...Object.fromEntries(applyJobs),
+        ...Object.fromEntries(controlJobs),
         ...(prEnv ? prEnv.jobs : {}),
     };
     const applyNames = applyJobs.map(([name]) => name);
@@ -373,8 +484,8 @@ function prLoopGithubDoc(components, env, image, beforeScript, extraScript, opti
         on.pull_request = { branches: [branch], types: ["opened", "synchronize", "reopened", "closed"] };
         on.schedule = [{ cron: PR_ENV_SWEEP_CRON }];
     }
-    // #4301: a /chant apply comment starts the apply before merge.
-    if (loop.applyBeforeMerge)
+    // #4301: a /chant apply comment starts the apply before merge. #4588: and a lock or unlock comment its job.
+    if (loop.applyBeforeMerge || commentLocks.length > 0 || preview)
         on.issue_comment = { types: ["created"] };
     return {
         name: member ? `chant-pr.${member.name}.${env}` : `chant-pr-${env}`,
@@ -383,7 +494,7 @@ function prLoopGithubDoc(components, env, image, beforeScript, extraScript, opti
         ...(rooted ? {} : { defaults: { run: { "working-directory": member.dir } } }),
         env: { ...options.variables, CHANT_ENV: env },
         jobsDoc,
-        stages: ["plan", PR_PLAN_NOTE_JOB, ...(locks ? [PR_LOCK_JOB, PR_UNLOCK_JOB] : []), ...applyNames, ...(prEnv ? ["env-up", PR_ENV_POST_JOB, "env-down", "env-sweep"] : [])],
+        stages: ["plan", PR_PLAN_NOTE_JOB, ...(locks ? [PR_LOCK_JOB, PR_UNLOCK_JOB] : []), ...commentLocks.map((j) => j.jobName), ...(preview ? [preview.jobName, preview.noteJobName] : []), ...applyNames, ...controlJobs.map(([name]) => name), ...(prEnv ? ["env-up", PR_ENV_POST_JOB, "env-down", "env-sweep"] : [])],
         jobs: [
             { jobName: "plan", component: "pull request plan", stage: "plan", needs: [] },
             { jobName: PR_PLAN_NOTE_JOB, component: "pull request plan note", stage: PR_PLAN_NOTE_JOB, needs: ["plan"] },
@@ -393,6 +504,13 @@ function prLoopGithubDoc(components, env, image, beforeScript, extraScript, opti
                     { jobName: PR_UNLOCK_JOB, component: "pull request unlock", stage: PR_UNLOCK_JOB, needs: [] },
                 ]
                 : []),
+            ...commentLocks.map((j) => ({ jobName: j.jobName, component: `pull request ${j.command} comment`, stage: j.jobName, needs: [] })),
+            ...(preview
+                ? [
+                    { jobName: preview.jobName, component: "pull request preview comment", stage: preview.jobName, needs: [] },
+                    { jobName: preview.noteJobName, component: "pull request preview comment note", stage: preview.noteJobName, needs: [preview.jobName] },
+                ]
+                : []),
             ...applyNames.map((name, i) => ({
                 jobName: name,
                 component: name === "record" ? "merge record" : loop.applyBeforeMerge ? "apply before merge" : loop.waveGate ? `green apply, wave ${i}` : "green apply",
@@ -400,6 +518,7 @@ function prLoopGithubDoc(components, env, image, beforeScript, extraScript, opti
                 // The record runs on a push and the apply on a green commit, so only the waves need each other.
                 needs: i > 1 ? [applyNames[i - 1]] : [],
             })),
+            ...controlJobs.map(([name]) => ({ jobName: name, component: "control repo dispatch", stage: name, needs: [lastGreen] })),
             ...(prEnv ? prEnv.listed : []),
         ],
     };
@@ -451,7 +570,7 @@ function prEnvGithubJobs(forge, image, beforeScript, extraScript, loop, member)
                 env: { [CHECKOUT_TOKEN_ENV]: GITHUB_JOB_TOKEN },
                 run: checkoutScript(true, true),
             },
-            ...[...prLoopSetup(image), ...beforeScript].map((line) => headStep(line)),
+            ...[...prLoopSetup(image, loop.engineSetup), ...beforeScript].map((line) => headStep(line)),
             ...(up.build ? [headStep(up.build[0], "Build the templates", { CHANT_ENV: up.env.CHANT_ENV }), headStep(up.build[1], "Lint the project")] : []),
             // The job's last step: a step after it would start beside whatever the change's code left running.
             {
@@ -487,7 +606,7 @@ function prEnvGithubJobs(forge, image, beforeScript, extraScript, loop, member)
         steps: [
             ...tradeStep,
             { uses: CHECKOUT, with: { "fetch-depth": 0, ...(ref ? { ref } : {}) } },
-            ...runSteps(prLoopSetup(image)),
+            ...runSteps(prLoopSetup(image, loop.engineSetup)),
             ...runSteps(beforeScript),
             { name, env: j.env, run: j.command },
             ...runSteps(extraScript),

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "4e53c568b6c55a08741d8b4f83c7965d1b0d710e540b4efb66ac88735de02380",
+    "manifest.json": "3513bb8a86e9d8cf394877a70b42741598681301a7c892fa94a65856cd1742ac",
     "meta.json": "c50e0ef3845c370c3ad2210b8bba455980417c0f818aa6ed46e06d4fb8b1b9f9",
     "types/index.d.ts": "0ead95536e947ddfb98a5acf0ddb88547913b5a53a342df67711c59266f84b3e",
     "rules/deprecated-action-version.ts": "a9ba7cc924ff1c7055110416d8989273690415bfb5e8dcc32dc9431b9351f5ca",
@@ -78,5 +78,5 @@
     "skills/chant-github-patterns.md": "bb3abef289a8fdfcf07d6bb2d7289dcb2f38bc0cb0321ea320b78b45a6f548c0",
     "skills/chant-github-security.md": "aab111cb0871cad30281ce48d7da23663689619351029219e2be019a1a61e394"
   },
-  "composite": "63d4e69414d1e6bfbf5968e7fcdcc1930ecca6d07b3915bdd013f9d39f77d2d6"
+  "composite": "d2ef289d1dabdd39c05090b1dc9e881fa69fd0934c0cb3a197d8ca9abb4f5a45"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "github",
-  "version": "0.124.54",
+  "version": "0.124.55",
   "chantVersion": ">=0.1.0",
   "namespace": "GitHub",
   "intrinsics": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-github",
-  "version": "0.124.54",
+  "version": "0.124.55",
   "description": "GitHub Actions lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -61,6 +61,6 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.54"
+    "@intentius/chant": "^0.124.55"
   }
 }

package/src/components/agent-jobs.ts

@@ -0,0 +1,177 @@
+/**
+ * The agent jobs on GitHub and Forgejo (#4616): `ScheduledOpSpec.agent`.
+ * What each job does is @intentius/chant/ci-agent's; this file lays them
+ * out so the model never shares a job with a write token:
+ *
+ * - the agent job holds `contents: read` and `pull-requests: read`. Its
+ *   checkout script alone sees the job token, for the fetches (the target
+ *   branch's commit, chant/lifecycle for the run count, and for a comment
+ *   the pull request's head). `chant agent prepare` reads with the job
+ *   token; `chant agent run` is the last step and starts without any forge
+ *   token, with the model's key from its secret, and hands the agent
+ *   directory on as the job's outputs (`handoverTrap`).
+ * - the push job checks out the target branch's commit, takes the agent
+ *   directory back as data and runs `chant agent land` with the push token:
+ *   `tokenEnv`'s secret, else the job token. A push made with the job token
+ *   starts no workflow on GitHub, so the pull request is planned again only
+ *   with a token of a user or an app.
+ *
+ * Forgejo's runner ignores `permissions:` and has no author association, so
+ * there `chant agent prepare` asks the forge whether the commenter can write,
+ * and both jobs drop the token variables before any step that does not need
+ * them.
+ */
+
+import { CHECKOUT_TOKEN_ENV, checkoutScript, dropForgeTokens, handoverOutputs, handoverTrap, takeOverScript } from "@intentius/chant/ci-handover";
+import { githubRunsOn, GITHUB_JOB_TOKEN, githubSecret, githubSecretOrJobToken, type CiRunner } from "@intentius/chant/ci-jobs";
+import {
+  AGENT_DECISION_FILE,
+  AGENT_DIR,
+  AGENT_DRIFT_FILE,
+  AGENT_PATCH_FILE,
+  AGENT_RC_FILE,
+  agentCommandLines,
+  agentGitAuthLines,
+  agentHeadFetchLine,
+  agentSettingsEnv,
+  type AgentSettings,
+} from "@intentius/chant/ci-agent";
+import { CHANT_EXIT } from "@intentius/chant/exit-codes";
+
+/** The agent step's id, which the agent job's outputs come from. */
+export const AGENT_STEP_ID = "chant-agent";
+/** The drift Op's run step id, whose outputs carry the drift and the code. */
+export const AGENT_DRIFT_STEP_ID = "chant-run";
+/** The variable the push step holds its token in, for git's header and the forge client. */
+const PUSH_TOKEN_ENV = "CHANT_AGENT_TOKEN";
+
+/** The files the handover keeps when the agent directory is too large to hand on whole. */
+const HANDED = { label: "chant-agent", noteFiles: [AGENT_DECISION_FILE, AGENT_RC_FILE, AGENT_PATCH_FILE, "prompt.sha256"] } as const;
+const DRIFT_HANDED = { label: "chant-agent", noteFiles: [AGENT_DRIFT_FILE] } as const;
+
+/** The name of the push job beside the agent job. */
+export function agentPushJobName(jobName: string): string {
+  return `${jobName}-push`;
+}
+
+/** The agent job's name for a drift Op's job. */
+export function agentJobName(jobName: string, on: AgentSettings["on"]): string {
+  return on === "drift" ? `${jobName}-agent` : jobName;
+}
+
+export interface GithubAgentJobsInput {
+  forge: "github" | "forgejo";
+  /** The agent job's name. */
+  jobName: string;
+  image: string;
+  settings: AgentSettings;
+  runner?: CiRunner;
+  /** Setup steps, as built by `setupStepDoc`. */
+  setup: Array<Record<string, unknown>>;
+  beforeScript: readonly string[];
+  /** The secret holding the push token; absent: the job token. */
+  tokenEnv?: string;
+  /** The command in place of `chant`: the product's bin. */
+  bin?: string;
+  /** For a drift agent: the Op's job, which handed the drift on. */
+  after?: string;
+}
+
+/** The comment condition of the agent job: a pull request comment that starts with the agent's line, from a writer on GitHub. */
+export function agentCommentIf(forge: "github" | "forgejo", comment: string): string {
+  return [
+    "github.event_name == 'issue_comment'",
+    forge === "forgejo" ? "(github.event.issue.pull_request || github.event.is_pull)" : "github.event.issue.pull_request",
+    `startsWith(github.event.comment.body, '${comment.replace(/'/g, "''")} ')`,
+    ...(forge === "forgejo" ? [] : ["contains(fromJSON('[\"OWNER\",\"MEMBER\",\"COLLABORATOR\"]'), github.event.comment.author_association)"]),
+  ].join(" && ");
+}
+
+/**
+ * The drift Op's run step (#4616): the run with its output kept as the
+ * drift for the agent, `drift=true` among the step's outputs when it exits
+ * with chant's `drift` code, and the output handed on. The step still exits
+ * with the run's code.
+ */
+export function driftRunStep(invocation: string, env: Record<string, string>, forge: "github" | "forgejo"): Record<string, unknown> {
+  return {
+    id: AGENT_DRIFT_STEP_ID,
+    env,
+    run: [
+      "set +e",
+      `mkdir -p ${AGENT_DIR}`,
+      ...handoverTrap(AGENT_DIR, forge, DRIFT_HANDED),
+      `{ ${invocation}; echo "$?" >"\${RUNNER_TEMP:-/tmp}/chant-run.code"; } 2>&1 | tee ${AGENT_DIR}/${AGENT_DRIFT_FILE}`,
+      'code=$(cat "${RUNNER_TEMP:-/tmp}/chant-run.code")',
+      `if [ "$code" -eq ${CHANT_EXIT.drift} ]; then echo "drift=true" >>"$GITHUB_OUTPUT"; fi`,
+      'exit "$code"',
+    ].join("\n"),
+  };
+}
+
+/** The drift Op job's outputs: the handed-on drift and the drift flag. */
+export function driftRunOutputs(forge: "github" | "forgejo"): Record<string, string> {
+  return { ...handoverOutputs(AGENT_DRIFT_STEP_ID, forge), drift: `\${{ steps.${AGENT_DRIFT_STEP_ID}.outputs.drift }}` };
+}
+
+/** The agent job and the push job. */
+export function githubAgentJobs(i: GithubAgentJobsInput): { agent: Record<string, unknown>; push: Record<string, unknown> } {
+  const s = i.settings;
+  const lines = agentCommandLines(i.forge, i.bin);
+  const drop = dropForgeTokens("sh");
+  const comment = s.on === "comment";
+  const settingsEnv = agentSettingsEnv(s);
+  const checkout = (head: boolean): Record<string, unknown> => ({
+    name: head ? "Check out the target branch's commit and the pull request's head" : "Check out the commit the drift check ran on",
+    env: { [CHECKOUT_TOKEN_ENV]: GITHUB_JOB_TOKEN, ...(head ? { PR_NUMBER: "${{ github.event.issue.number }}" } : {}) },
+    // The ledger branch too: prepare counts the agent's runs on it, and land appends to it.
+    run: [checkoutScript(true, true), ...(head ? [agentHeadFetchLine(i.forge, "PR_NUMBER")] : [])].join("\n"),
+  });
+  const before = i.beforeScript.map((line) => ({ run: `${drop}\n${line}` }));
+  const timeout = s.timeout + 15;
+  const agent: Record<string, unknown> = {
+    ...(comment ? { if: agentCommentIf(i.forge, s.comment!) } : { needs: i.after, if: `always() && needs.${i.after}.outputs.drift == 'true'` }),
+    "runs-on": githubRunsOn(i.runner),
+    container: i.image,
+    "timeout-minutes": timeout,
+    permissions: { contents: "read", "pull-requests": "read" },
+    env: settingsEnv,
+    outputs: handoverOutputs(AGENT_STEP_ID, i.forge),
+    steps: [
+      checkout(comment),
+      ...(comment ? [] : [{ name: "Take the drift from the drift check", run: takeOverScript(i.after!, AGENT_DIR, i.forge) }]),
+      ...i.setup,
+      ...before,
+      // Reads only: the comment, the commenter's access, the pull request's head and the ledger.
+      { name: "Decide whether the agent runs", env: { GITHUB_TOKEN: GITHUB_JOB_TOKEN }, run: lines.prepare },
+      // The job's last step: the model's key and no forge token, and the agent directory handed on however it ends.
+      {
+        id: AGENT_STEP_ID,
+        name: "Run the agent",
+        env: { [s.keyEnv]: githubSecret(s.keyEnv) },
+        run: [drop, ...handoverTrap(AGENT_DIR, i.forge, HANDED), lines.run].join("\n"),
+      },
+    ],
+  };
+  const token = i.tokenEnv ? githubSecretOrJobToken(i.tokenEnv) : GITHUB_JOB_TOKEN;
+  const push: Record<string, unknown> = {
+    needs: i.jobName,
+    if: `always() && needs.${i.jobName}.result == 'success'`,
+    "runs-on": githubRunsOn(i.runner),
+    container: i.image,
+    permissions: { contents: "write", "pull-requests": "write", issues: "write" },
+    env: settingsEnv,
+    steps: [
+      checkout(comment),
+      { name: "Take the change from the agent job", run: takeOverScript(i.jobName, AGENT_DIR, i.forge) },
+      ...i.setup,
+      ...before,
+      {
+        name: comment ? "Push the change to the pull request" : "Open or update the agent's pull request",
+        env: { [PUSH_TOKEN_ENV]: token, GITHUB_TOKEN: token, ...(i.forge === "forgejo" ? { CHANT_FORGEJO_TOKEN: token } : {}) },
+        run: [...agentGitAuthLines(PUSH_TOKEN_ENV, "x-access-token"), lines.land].join("\n"),
+      },
+    ],
+  };
+  return { agent, push };
+}

package/src/components/control-pipeline.ts

@@ -0,0 +1,65 @@
+/**
+ * The control repo's own workflow (#4568) on GitHub, and on Forgejo through
+ * its dialect: a member's dispatch starts it, and it runs the member's
+ * dependents with `chant workspace run --dependents-of`. The pieces are
+ * core's (`controlPipelineSpec` in `@intentius/chant/control/dispatch`);
+ * this file writes them as a workflow. The member's side, the
+ * `control-dispatch` job, comes from the pull request loop's `control`
+ * option (./generate-pipeline.ts).
+ */
+
+import { CI_IMAGE, GITHUB_RUNNER } from "@intentius/chant/ci-jobs";
+import { controlPipelineSpec } from "@intentius/chant/control/dispatch";
+import type { CiProductWords, CiProductWordsInput } from "@intentius/chant/ci-product-words";
+import { CHECKOUT, concurrency, emitWorkflowYAML, type GithubWorkflowDoc } from "./ci-jobs";
+
+/** A control repo's pipeline file: where it goes, its text, and what a person still sets up. */
+export interface ControlPipelineFile {
+  path: string;
+  content: string;
+  notes: string[];
+}
+
+/** What {@link controlGithubDoc} and the generators take. */
+export interface ControlPipelineOptions {
+  words?: CiProductWordsInput | CiProductWords;
+  /** The image the job runs in. Default chant's CI image. */
+  image?: string;
+  /** The command the job runs chant with. Default `npx --no-install chant`. */
+  command?: string;
+}
+
+/** The control repo's workflow document for a GitHub-shaped forge, before emission. Forgejo transforms it first. */
+export function controlGithubDoc(forge: "github" | "forgejo", options: ControlPipelineOptions = {}): { doc: GithubWorkflowDoc; path: string; notes: string[] } {
+  const spec = controlPipelineSpec(forge, options.words ?? {}, options.command ? { command: options.command } : {});
+  const doc: GithubWorkflowDoc = {
+    header: spec.header,
+    name: spec.path.split("/").pop()!.replace(/\.yml$/, ""),
+    on: {
+      ...(forge === "github" ? { repository_dispatch: { types: [spec.event] } } : {}),
+      workflow_dispatch: { inputs: spec.inputs },
+    },
+    // #4617: contents: write pushes the record of each dispatch that carries an outcome to chant/lifecycle.
+    permissions: { contents: "write" },
+    // One run per member at a time, and none cancelled: a later apply of the same member waits for the one running.
+    concurrency: concurrency(spec.group),
+    jobsDoc: {
+      dependents: {
+        "runs-on": GITHUB_RUNNER,
+        container: options.image ?? CI_IMAGE,
+        steps: [
+          // The full history, so the job reads and appends to chant/lifecycle (#4617).
+          { uses: CHECKOUT, with: { "fetch-depth": 0 } },
+          { name: "Run the dependents of the member that applied", shell: "bash", env: spec.env, run: spec.script },
+        ],
+      },
+    },
+  };
+  return { doc, path: spec.path, notes: spec.notes };
+}
+
+/** The control repo's workflow on GitHub: `.github/workflows/<product>-dependents.yml`. */
+export function generateControlPipeline(options: ControlPipelineOptions = {}): ControlPipelineFile {
+  const { doc, path, notes } = controlGithubDoc("github", options);
+  return { path, content: emitWorkflowYAML(doc), notes };
+}