@intentius/chant-lexicon-gitlab 0.124.54 → 0.124.55

package/dist/components/generate-pipeline.js

@@ -35,9 +35,11 @@ import { assertGitlabBranch, CI_IMAGE, ciJobName, fillCommand, GITLAB_FULL_HISTO
 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 { PR_APPLY_RECORD, PR_LOOP_REPORT_DIR, prApplyGroup, prRecordGroup, prApplyRecordKey, prApplyWaveJobName, prLoopJobs, GITLAB_APPLY_PR_VAR, GITLAB_PLAN_NOTES_VAR, gitlabPlanJobName, prLoopPostJob, prLoopSetup, PR_PLAN_NOTE_JOB, prLoopWaveJobs, prLoopWithWaves, prEnvJobs, PR_ENV_REPORT_DIR, PR_ENV_POST_JOB, } from "@intentius/chant/components/pr-pipeline";
+import { PR_APPLY_RECORD, PR_LOOP_REPORT_DIR, prApplyGroup, prRecordGroup, prApplyRecordKey, prApplyWaveJobName, prLoopJobs, GITLAB_APPLY_PR_VAR, GITLAB_PLAN_NOTES_VAR, gitlabPlanJobName, prLoopPostJob, prLoopSetup, PR_PLAN_NOTE_JOB, prLoopWaveJobs, prLoopWithWaves, prEnvJobs, prCommentLockJobs, prCommentPreviewJob, PR_ENV_REPORT_DIR, PR_ENV_POST_JOB, } from "@intentius/chant/components/pr-pipeline";
+import { REPO_APPLY_GROUP } from "@intentius/chant/components/repo-lock";
 import { memberGitlabChanges, memberRepoPath, memberShellDir } from "@intentius/chant/lexicon";
 import { FORGE_TOKEN_VARS, GITLAB_DROP_FORGE_TOKENS } from "@intentius/chant/ci-handover";
+import { CONTROL_TOKEN_VARS, controlDispatchJob, controlNoteCheckout } from "@intentius/chant/control/dispatch";
 import { gitlabTradeIdTokens, gitlabTradeLines, TRADE_SPEC_ENV } from "@intentius/chant/ci-identity";
 import { emitGitlabFile } from "./ci-jobs.js";
 /**
@@ -303,6 +305,8 @@ function gitlabApplyPrRule(branch) {
 function gitlabPlanNotesRule(branch) {
     return `$CI_PIPELINE_SOURCE =~ /^(schedule|web|api|trigger)$/ && $${GITLAB_PLAN_NOTES_VAR} == "1" && $CI_COMMIT_BRANCH == ${branch}`;
 }
+/** Drops the credentials GitLab's runner writes into origin's URL (#4620), before a merge request's code runs in a pipeline of the target branch. */
+const GITLAB_SCRUB_ORIGIN = `git remote set-url origin "$(git remote get-url origin | sed -E 's#//[^@/]*@#//#')"`;
 /** The rule of a pipeline for a pushed `ci/green/` tag (#4168 step 9), which runs the apply under apply on merge. */
 const GITLAB_GREEN_TAG_RULE = '$CI_COMMIT_TAG =~ /^ci\\/green\\//';
 function prLoopGitlabPipeline(components, env, image, beforeScript, extraScript, options) {
@@ -335,7 +339,7 @@ function prLoopGitlabPipeline(components, env, image, beforeScript, extraScript,
     // The command runs through chant ci run (#4156), which writes the job's run record, signed when the CHANT_RUNNER_KEY variable is set.
     // #4221: a wave job hands the commit it applies to the next wave as GREEN_SHA, through a dotenv report.
     const handOff = (job) => (job.wave ? [`echo "GREEN_SHA=$GREEN_SHA" > "$CI_PROJECT_DIR/${WAVE_GREEN_DOTENV}"`] : []);
-    const script = (job) => [...prLoopSetup(image), ...enter, ...beforeScript, ...(job.checkout ?? []), ...handOff(job), ...(job.setup ?? []), ...(job.build ?? []), job.run.command, ...extraScript];
+    const script = (job) => [...prLoopSetup(image, loop.engineSetup), ...enter, ...beforeScript, ...(job.checkout ?? []), ...handOff(job), ...(job.setup ?? []), ...(job.build ?? []), job.run.command, ...extraScript];
     // #4296: each job trades its OIDC token for its cloud identity before anything else in its script.
     const identity = loop.identity;
     const trading = (spec) => spec ? { id_tokens: gitlabTradeIdTokens(spec) } : {};
@@ -343,13 +347,42 @@ function prLoopGitlabPipeline(components, env, image, beforeScript, extraScript,
     const applySpec = (job) => (identity ? (job.jobName === "record" ? identity.plan : identity.apply) : undefined);
     // #4298: a pull request environment's jobs, in a stage of their own after the plan.
     const prEnv = loop.prEnvironment ? prEnvGitlabJobs(image, beforeScript, extraScript, enter, loop, member, named, onMergeRequest) : undefined;
-    const stages = ["plan", PR_PLAN_NOTE_JOB, ...applies.map((a) => a.stage), ...(prEnv ? [PR_ENV_STAGE, PR_ENV_POST_STAGE] : [])];
+    // #4568: once the last apply on merge succeeded, one job tells the control repo this member applied.
+    const lastGreen = loop.control && !loop.applyBeforeMerge && greens.length > 0 ? greens[greens.length - 1].name : undefined;
+    const control = loop.control && lastGreen
+        ? controlDispatchJob("gitlab", loop.control.target, loop.waveGate ? "$GREEN_SHA" : "$CI_COMMIT_SHA", {
+            ...(loop.words ? { words: loop.words } : {}),
+            ...(loop.control.sentCheck ? { sentCheck: loop.control.sentCheck } : {}),
+            ...(loop.control.markSent ? { markSent: loop.control.markSent } : {}),
+        })
+        : undefined;
+    const controlJob = control ? named(control.name) : undefined;
+    // A CI/CD variable reaches every job, so the plan job drops the control repo's tokens with the forge tokens.
+    const dropControl = loop.control
+        ? [`unset ${[...new Set([...CONTROL_TOKEN_VARS, loop.control.target.tokenSecret, loop.control.target.readTokenSecret])].join(" ")}`]
+        : [];
+    // #4588: `/<product> lock` and `/<product> unlock`: GitLab starts no pipeline on a note, so each runs in a
+    // pipeline of the target branch started with CHANT_LOCK_PR or CHANT_UNLOCK_PR set, as the apply before merge does.
+    const targetBranch = loop.branch ? JSON.stringify(loop.branch) : "$CI_DEFAULT_BRANCH";
+    const commentLocks = prCommentLockJobs("gitlab", loop).map((job) => ({
+        job,
+        name: named(job.jobName),
+        rule: `$CI_PIPELINE_SOURCE =~ /^(web|api|trigger)$/ && $${job.gitlabVar} =~ /^[0-9]+$/ && $CI_COMMIT_BRANCH == ${targetBranch}`,
+    }));
+    // #4620: `/<product> <plan word>`: a pipeline of the target branch started with CHANT_PREVIEW_PR set previews the merge request's head again.
+    const preview = prCommentPreviewJob("gitlab", env, loop, member?.name);
+    const previewRule = preview ? `$CI_PIPELINE_SOURCE =~ /^(web|api|trigger)$/ && $${preview.gitlabVar} =~ /^[0-9]+$/ && $CI_COMMIT_BRANCH == ${targetBranch}` : undefined;
+    const previewName = preview ? named(preview.jobName) : undefined;
+    const previewNoteName = preview ? named(preview.noteJobName) : undefined;
+    const stages = ["plan", PR_PLAN_NOTE_JOB, ...commentLocks.map((c) => c.job.jobName), ...(preview ? [preview.jobName, preview.noteJobName] : []), ...applies.map((a) => a.stage), ...(control ? [control.name] : []), ...(prEnv ? [PR_ENV_STAGE, PR_ENV_POST_STAGE] : [])];
     const noteJob = named(PR_PLAN_NOTE_JOB);
-    const post = prLoopPostJob("gitlab", env, member?.name);
+    const post = prLoopPostJob("gitlab", env, member?.name, loop.words ? { ...(loop.words.bin ? { bin: loop.words.bin } : {}) } : 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("gitlab", loop.control.target, loop.words ?? {}) : undefined;
     const doc = {
         // Included files merge their top-level keys, so a member's file carries
         // the rules every member shares and no name: two names would collide.
-        workflow: { ...(member ? {} : { name: `chant-pr-${env}` }), rules: [{ if: onMergeRequest }, { if: onMerge }, { if: onPlanNotes }, ...(greens.length > 0 ? [{ if: onGreen }] : []), ...(prEnv ? [{ if: GITLAB_SCHEDULE_RULE }] : [])] },
+        workflow: { ...(member ? {} : { name: `chant-pr-${env}` }), rules: [{ if: onMergeRequest }, { if: onMerge }, { if: onPlanNotes }, ...(greens.length > 0 ? [{ if: onGreen }] : []), ...commentLocks.map((c) => ({ if: c.rule })), ...(previewRule ? [{ if: previewRule }] : []), ...(prEnv ? [{ if: GITLAB_SCHEDULE_RULE }] : [])] },
         stages,
         variables: { ...options.variables, CHANT_ENV: env, ...GITLAB_FULL_HISTORY },
         [planJob]: {
@@ -360,7 +393,7 @@ function prLoopGitlabPipeline(components, env, image, beforeScript, extraScript,
             variables: { ...plan.run.env, ...tradeVars(identity?.plan) },
             // #4295: the merge request's code runs in this job, so the job's shell drops the forge tokens first.
             // #4296: with identity, the trade runs before that, and the same unset drops the token variables too.
-            script: [...(identity ? gitlabTradeLines(FORGE_TOKEN_VARS) : [GITLAB_DROP_FORGE_TOKENS]), ...script(plan)],
+            script: [...(identity ? gitlabTradeLines(FORGE_TOKEN_VARS) : [GITLAB_DROP_FORGE_TOKENS]), ...dropControl, ...script(plan)],
             artifacts: { when: "always", paths: [reportPath] },
         },
         // #4295, #4328: a job of the target branch's pipeline posts each open merge request's note and status from its plan job's report.
@@ -368,15 +401,61 @@ function prLoopGitlabPipeline(components, env, image, beforeScript, extraScript,
             stage: PR_PLAN_NOTE_JOB,
             image,
             rules: [{ if: onPlanNotes }],
-            script: [...enter, ...beforeScript, post.command],
+            script: [...enter, ...beforeScript, ...(controlRead ? [controlRead.script] : []), post.command],
         },
+        ...Object.fromEntries(commentLocks.map(({ job, name, rule }) => [
+            name,
+            // The target branch's commit, so none of the merge request's code runs here.
+            { stage: job.jobName, image, rules: [{ if: rule }], variables: job.env, script: [...enter, ...beforeScript, job.line] },
+        ])),
+        ...(preview && previewName && previewNoteName && previewRule
+            ? {
+                [previewName]: {
+                    stage: preview.jobName,
+                    image,
+                    rules: [{ if: previewRule }],
+                    ...trading(identity?.plan),
+                    variables: { ...preview.plan.run.env, ...tradeVars(identity?.plan) },
+                    // A pipeline of the target branch holds the protected tokens, so the job drops them before it checks out the merge request's head.
+                    script: [
+                        ...(identity ? gitlabTradeLines(FORGE_TOKEN_VARS) : [GITLAB_DROP_FORGE_TOKENS]),
+                        ...dropControl,
+                        "unset CHANT_RUNNER_KEY",
+                        ...("line" in preview.head ? [preview.head.line] : []),
+                        // The ledger while the clone can still fetch it: the plan reads the gate ledger from the local branch.
+                        "git fetch -q --no-tags origin '+refs/heads/chant/lifecycle:refs/heads/chant/lifecycle' 2>/dev/null || true",
+                        // The runner's clone keeps the job token in origin's URL; the merge request's code never sees it.
+                        GITLAB_SCRUB_ORIGIN,
+                        preview.base,
+                        ...prLoopSetup(image, loop.engineSetup),
+                        ...enter,
+                        ...beforeScript,
+                        ...(preview.plan.setup ?? []),
+                        ...(preview.plan.build ?? []),
+                        preview.plan.run.command,
+                        ...extraScript,
+                    ],
+                    artifacts: { when: "always", paths: [reportPath] },
+                },
+                [previewNoteName]: {
+                    stage: preview.noteJobName,
+                    image,
+                    needs: [{ job: previewName, artifacts: true }],
+                    rules: [{ if: previewRule, when: "always" }],
+                    variables: preview.post.env,
+                    // The target branch's commit: the job's own clone, where none of the merge request's code runs.
+                    script: [...enter, ...beforeScript, ...(controlRead ? [controlRead.script] : []), ...(preview.post.setup ?? []), preview.post.command],
+                },
+            }
+            : {}),
         ...Object.fromEntries(applies.map(({ job, name, stage }, i) => [
             name,
             {
                 stage,
                 image,
                 ...(i > 1 ? { needs: [applies[i - 1].name] } : {}),
-                resource_group: job.jobName === "record" ? prRecordGroup(env, member?.name) : prApplyGroup(env, member?.name),
+                // #4552: on the repo grain every apply of the repository shares one resource group.
+                resource_group: job.jobName === "record" ? prRecordGroup(env, member?.name) : loop.lockGrain === "repo" ? REPO_APPLY_GROUP : prApplyGroup(env, member?.name),
                 // #4291: a wave after the first runs after one that failed, and blocks only what depends on the failure.
                 rules: [{ if: job.jobName === "record" ? onMerge : onGreen, ...(job.wave && i > 1 ? { when: "always" } : {}) }],
                 ...trading(applySpec(job)),
@@ -397,20 +476,43 @@ function prLoopGitlabPipeline(components, env, image, beforeScript, extraScript,
                 artifacts: { when: "always", paths: [reportPath], ...(job.wave ? { reports: { dotenv: WAVE_GREEN_DOTENV } } : {}) },
             },
         ])),
+        ...(control && controlJob
+            ? {
+                [controlJob]: {
+                    stage: control.name,
+                    image,
+                    needs: [lastGreen],
+                    rules: [{ if: onGreen }],
+                    // The runner sets a needed job's dotenv values when the script starts, so the commit is read there.
+                    script: [
+                        ...Object.entries(control.env).map(([k, v]) => `export ${k}="${v}"`),
+                        `bash <<'CONTROL_DISPATCH' || exit $?\n${control.script}\nCONTROL_DISPATCH`,
+                    ],
+                },
+            }
+            : {}),
         ...(prEnv ? prEnv.jobs : {}),
     };
     const jobs = [
         { jobName: planJob, component: "merge request plan", stage: "plan", needs: [] },
         { jobName: noteJob, component: "merge request plan note", stage: PR_PLAN_NOTE_JOB, needs: [] },
+        ...commentLocks.map(({ job, name }) => ({ jobName: name, component: `merge request ${job.command} comment`, stage: job.jobName, needs: [] })),
+        ...(preview && previewName && previewNoteName
+            ? [
+                { jobName: previewName, component: "merge request preview comment", stage: preview.jobName, needs: [] },
+                { jobName: previewNoteName, component: "merge request preview comment note", stage: preview.noteJobName, needs: [previewName] },
+            ]
+            : []),
         ...applies.map(({ job, name, stage }, i) => ({
             jobName: name,
             component: job.wave ? `green apply, wave ${job.wave}` : job.jobName === "record" ? "merge record" : loop.applyBeforeMerge ? "apply before merge" : "green apply",
             stage,
             needs: i > 1 ? [applies[i - 1].name] : [],
         })),
+        ...(controlJob ? [{ jobName: controlJob, component: "control repo dispatch", stage: control.name, needs: [lastGreen] }] : []),
         ...(prEnv ? prEnv.listed : []),
     ];
-    const yaml = emitGitlabFile(["workflow", "stages", "variables", planJob, noteJob, ...applies.map((a) => a.name), ...Object.keys(prEnv?.jobs ?? {})].map((key) => [key, doc[key]]));
+    const yaml = emitGitlabFile(["workflow", "stages", "variables", planJob, noteJob, ...commentLocks.map((c) => c.name), ...(previewName && previewNoteName ? [previewName, previewNoteName] : []), ...applies.map((a) => a.name), ...(controlJob ? [controlJob] : []), ...Object.keys(prEnv?.jobs ?? {})].map((key) => [key, doc[key]]));
     return { yaml, stages, jobs, env };
 }
 /** The stage a pull request environment's jobs run in (#4298). */
@@ -434,7 +536,7 @@ function prEnvGitlabJobs(image, beforeScript, extraScript, enter, loop, member,
     const reportPath = member ? memberRepoPath(member, PR_ENV_REPORT_DIR) : PR_ENV_REPORT_DIR;
     const environment = "pr-$CI_MERGE_REQUEST_IID";
     const group = `chant-pr-env-${member ? `${member.name}-` : ""}$CI_MERGE_REQUEST_IID`;
-    const script = (j) => [...prLoopSetup(image), ...enter, ...beforeScript, ...(j.build ?? []), j.command, ...extraScript];
+    const script = (j) => [...prLoopSetup(image, loop.engineSetup), ...enter, ...beforeScript, ...(j.build ?? []), j.command, ...extraScript];
     const artifacts = { when: "always", paths: [reportPath] };
     // #4330: env-up, env-down and env-sweep trade the job's OIDC token for the pull request environments' identity first.
     const identity = loop.prEnvIdentity;

package/dist/components/review-jobs.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The two jobs of a split review on GitLab (#4544): `ScheduledOpSpec.reviewAgent`.
+ *
+ * An Op that runs a `reviewAgent` step in `handoff` mode runs the change's
+ * code (`chant run` loads the merge request's Op files) beside a model.
+ * GitHub and Forgejo keep the write token out of that job with per-job
+ * permissions (`lexicons/github/src/components/review-jobs.ts`). GitLab has
+ * none: a merge request pipeline is built from the merge request's own files
+ * and every job in it gets the project's unprotected variables. So the token
+ * stays out of that pipeline altogether, the way the plan note does (#4328):
+ *
+ * - the review job runs in the merge request pipeline. Its script starts by
+ *   unsetting every forge token variable (`GITLAB_DROP_FORGE_TOKENS`), and it
+ *   keeps the review directory as its artifact. `CHANT_FORGE_TOKEN` is a
+ *   protected variable, which a merge request pipeline never gets.
+ * - the note job runs in a pipeline of the default branch, built from that
+ *   branch's files, that a pipeline schedule (or a person, the API or a
+ *   trigger) starts with `CHANT_REVIEW_NOTES` set to `1`. It checks nothing
+ *   out (`GIT_STRATEGY: none`), installs the chant release this lexicon
+ *   belongs to, and runs `postOpenReviewNotes` with the protected token: for
+ *   each open merge request whose newest pipeline's review job succeeded it
+ *   reads `review.json` from that job's artifacts as data and posts the note.
+ *   The Op's name, the review job's name and the branches come from this
+ *   file, never from the artifact.
+ */
+import type { OpTrigger } from "@intentius/chant/lexicon";
+/** The variable `reviewAgent` reads its handoff directory from (`REVIEW_DIR_ENV`, review-agent.ts). */
+export declare const REVIEW_DIR_ENV = "CHANT_REVIEW_DIR";
+/** Where the review job writes the review, from the directory its script runs in. */
+export declare const REVIEW_DIR = ".chant/review";
+/** The variable a pipeline of the default branch is started with to run the note jobs. */
+export declare const GITLAB_REVIEW_NOTES_VAR = "CHANT_REVIEW_NOTES";
+/** The name of the note job beside the Op's own job. */
+export declare function reviewNoteJobName(jobName: string): string;
+/**
+ * The note job's rule: a pipeline of the default branch that a pipeline
+ * schedule, a person, the API or a trigger started with `CHANT_REVIEW_NOTES`
+ * set to `1`. A merge request pipeline's own trigger job starts a pipeline
+ * whose source is `pipeline`, which this rule leaves out.
+ */
+export declare const GITLAB_REVIEW_NOTES_RULE = "$CI_PIPELINE_SOURCE =~ /^(schedule|web|api|trigger)$/ && $CHANT_REVIEW_NOTES == \"1\" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH";
+/**
+ * Refuse a spec whose review cannot be split the way this shape needs: a
+ * trigger with no merge request, a finding-mode that would post from the
+ * review job, or an additive scope other than `id-token: write`.
+ */
+export declare function assertReviewSplit(name: string, trigger: OpTrigger, findingMode: string, permissions: Record<string, string> | undefined): void;
+export interface GitlabReviewJobsInput {
+    /** The Op's name: what `chant run` targets and what keys the note. */
+    name: string;
+    /** The review job's name: the Op's job name. */
+    jobName: string;
+    stage: string;
+    image: string;
+    /** The review job's `rules:`, the Op's merge request rules. */
+    rules: unknown[];
+    /** The review job's script after the token unset: cd, setup, before-script, the invocation and the extra script. */
+    script: string[];
+    /** The Op's own per-job environment (`ScheduledOpSpec.variables`). */
+    variables?: Record<string, string>;
+    idTokens?: Record<string, unknown>;
+    /** The review directory from the repository root: `.chant/review`, under a workspace member's directory for a member. */
+    artifactDir: string;
+    /** The branches the merge requests merge into, from the trigger; the default branch when absent. */
+    branches?: readonly string[];
+}
+/** The review job and the note job of one split review. */
+export declare function gitlabReviewJobs(i: GitlabReviewJobsInput): {
+    review: Record<string, unknown>;
+    note: Record<string, unknown>;
+};
+//# sourceMappingURL=review-jobs.d.ts.map

package/dist/components/review-jobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-jobs.d.ts","sourceRoot":"","sources":["../../src/components/review-jobs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D,uGAAuG;AACvG,eAAO,MAAM,cAAc,qBAAqB,CAAC;AAEjD,qFAAqF;AACrF,eAAO,MAAM,UAAU,kBAAkB,CAAC;AAE1C,0FAA0F;AAC1F,eAAO,MAAM,uBAAuB,uBAAuB,CAAC;AAK5D,wDAAwD;AACxD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,qIAA2I,CAAC;AAEjL;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAAG,IAAI,CAkB9I;AAyCD,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,oHAAoH;IACpH,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,yHAAyH;IACzH,WAAW,EAAE,MAAM,CAAC;IACpB,oGAAoG;IACpG,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AAED,2DAA2D;AAC3D,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,qBAAqB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAsB7H"}

package/dist/components/review-jobs.js

@@ -0,0 +1,124 @@
+/**
+ * The two jobs of a split review on GitLab (#4544): `ScheduledOpSpec.reviewAgent`.
+ *
+ * An Op that runs a `reviewAgent` step in `handoff` mode runs the change's
+ * code (`chant run` loads the merge request's Op files) beside a model.
+ * GitHub and Forgejo keep the write token out of that job with per-job
+ * permissions (`lexicons/github/src/components/review-jobs.ts`). GitLab has
+ * none: a merge request pipeline is built from the merge request's own files
+ * and every job in it gets the project's unprotected variables. So the token
+ * stays out of that pipeline altogether, the way the plan note does (#4328):
+ *
+ * - the review job runs in the merge request pipeline. Its script starts by
+ *   unsetting every forge token variable (`GITLAB_DROP_FORGE_TOKENS`), and it
+ *   keeps the review directory as its artifact. `CHANT_FORGE_TOKEN` is a
+ *   protected variable, which a merge request pipeline never gets.
+ * - the note job runs in a pipeline of the default branch, built from that
+ *   branch's files, that a pipeline schedule (or a person, the API or a
+ *   trigger) starts with `CHANT_REVIEW_NOTES` set to `1`. It checks nothing
+ *   out (`GIT_STRATEGY: none`), installs the chant release this lexicon
+ *   belongs to, and runs `postOpenReviewNotes` with the protected token: for
+ *   each open merge request whose newest pipeline's review job succeeded it
+ *   reads `review.json` from that job's artifacts as data and posts the note.
+ *   The Op's name, the review job's name and the branches come from this
+ *   file, never from the artifact.
+ */
+import { readFileSync } from "node:fs";
+import { GITLAB_DROP_FORGE_TOKENS } from "@intentius/chant/ci-handover";
+/** The variable `reviewAgent` reads its handoff directory from (`REVIEW_DIR_ENV`, review-agent.ts). */
+export const REVIEW_DIR_ENV = "CHANT_REVIEW_DIR";
+/** Where the review job writes the review, from the directory its script runs in. */
+export const REVIEW_DIR = ".chant/review";
+/** The variable a pipeline of the default branch is started with to run the note jobs. */
+export const GITLAB_REVIEW_NOTES_VAR = "CHANT_REVIEW_NOTES";
+/** How long a review artifact is kept: long enough for a schedule to come round and post it. */
+const REVIEW_ARTIFACT_EXPIRY = "7 days";
+/** The name of the note job beside the Op's own job. */
+export function reviewNoteJobName(jobName) {
+    return `${jobName}-note`;
+}
+/**
+ * The note job's rule: a pipeline of the default branch that a pipeline
+ * schedule, a person, the API or a trigger started with `CHANT_REVIEW_NOTES`
+ * set to `1`. A merge request pipeline's own trigger job starts a pipeline
+ * whose source is `pipeline`, which this rule leaves out.
+ */
+export const GITLAB_REVIEW_NOTES_RULE = `$CI_PIPELINE_SOURCE =~ /^(schedule|web|api|trigger)$/ && $${GITLAB_REVIEW_NOTES_VAR} == "1" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH`;
+/**
+ * Refuse a spec whose review cannot be split the way this shape needs: a
+ * trigger with no merge request, a finding-mode that would post from the
+ * review job, or an additive scope other than `id-token: write`.
+ */
+export function assertReviewSplit(name, trigger, findingMode, permissions) {
+    if (trigger.kind !== "pull_request") {
+        throw new Error(`Scheduled Op "${name}" sets reviewAgent, which posts the review as a note on the merge request that triggered the run, but its trigger is "${trigger.kind}". Give it a { kind: "pull_request" } trigger.`);
+    }
+    if (findingMode !== "report") {
+        throw new Error(`Scheduled Op "${name}" sets reviewAgent with findingMode "${findingMode}". The review job holds no forge token, and the note job posts from a pipeline of the default branch instead, so the Op's own finding-mode must be "report".`);
+    }
+    for (const [scope, level] of Object.entries(permissions ?? {})) {
+        if (level === "write" && scope !== "id-token") {
+            throw new Error(`Scheduled Op "${name}" sets reviewAgent and adds the permission "${scope}: write". The review job runs the change's code and may hold only "id-token: write".`);
+        }
+    }
+}
+/** The chant release the note job installs: this lexicon's own, which releases in lockstep with `@intentius/chant`. */
+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 gitlab lexicon's package.json has no version to pin the review note job's chant to");
+    }
+    return pkg.version;
+}
+/** What the note job runs under node. The inputs are JSON literals from this file; nothing comes from the merge request. */
+function noteModule(op, job, artifactDir, branches) {
+    return [
+        'import { forgeFromEnv } from "@intentius/chant/pr-forge";',
+        'import { postOpenReviewNotes } from "@intentius/chant/op/activities/review-agent";',
+        `const branches = ${JSON.stringify(branches ?? null)} ?? [process.env.CI_DEFAULT_BRANCH];`,
+        "const forge = forgeFromEnv(\"gitlab\");",
+        "let failed = false;",
+        "for (const branch of branches) {",
+        `  const { posts, warnings } = await postOpenReviewNotes({ forge, branch, job: ${JSON.stringify(job)}, artifactDir: ${JSON.stringify(artifactDir)}, op: ${JSON.stringify(op)} });`,
+        "  for (const p of posts) console.log(`!${p.pr} at ${p.head.slice(0, 12)}: ${p.skipped ?? `posted, risk ${p.risk}`}`);",
+        "  for (const w of warnings) { console.error(w); failed = true; }",
+        "}",
+        "if (failed) process.exitCode = 1;",
+    ].join("\n");
+}
+/** The note job's script: install the pinned chant outside any checkout and run {@link noteModule} with tsx. */
+function noteScript(version, module) {
+    return [
+        'dir="${TMPDIR:-/tmp}/chant-review-note"',
+        'mkdir -p "$dir"',
+        'cd "$dir"',
+        "echo '{\"private\":true}' > package.json",
+        `npm install --omit=peer --no-audit --no-fund --loglevel=error @intentius/chant@${version}`,
+        ["cat > note.mjs <<'NOTE'", module, "NOTE"].join("\n"),
+        "node --import tsx note.mjs",
+    ];
+}
+/** The review job and the note job of one split review. */
+export function gitlabReviewJobs(i) {
+    const review = {
+        stage: i.stage,
+        image: i.image,
+        resource_group: i.jobName,
+        ...(i.idTokens ? { id_tokens: i.idTokens } : {}),
+        variables: { ...(i.variables ?? {}), [REVIEW_DIR_ENV]: REVIEW_DIR },
+        rules: i.rules,
+        // The merge request's code runs in this job, so its shell drops every forge token first.
+        script: [GITLAB_DROP_FORGE_TOKENS, ...i.script],
+        artifacts: { paths: [i.artifactDir], expire_in: REVIEW_ARTIFACT_EXPIRY },
+    };
+    const note = {
+        stage: i.stage,
+        image: i.image,
+        resource_group: reviewNoteJobName(i.jobName),
+        // Nothing of the repository is needed: the review is read from the review job's artifacts through the API.
+        variables: { GIT_STRATEGY: "none" },
+        rules: [{ if: GITLAB_REVIEW_NOTES_RULE }],
+        script: noteScript(chantVersion(), noteModule(i.name, i.jobName, i.artifactDir, i.branches)),
+    };
+    return { review, note };
+}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "c8ef64c664ec8553272336feca077fab045ddab3d6c84cc50180ff99e603526d",
+    "manifest.json": "f5a242ce00bc716bcb44314a1301000b9ecad9187d4591c776829885535369e2",
     "meta.json": "db082fbf90c5941c498b2bee0f106103449c1a4c257716ca2220f0dd490450b2",
     "types/index.d.ts": "a048a66ebe20da0cb5fc889054cac69044d9bf882e2c56b5c5bf113d1f3ba57c",
     "rules/artifact-no-expiry.ts": "0ca5bb972d4a542126e8a0229d43b55658394cb7dd9b9923b2c590bec1c2ad7d",
@@ -55,5 +55,5 @@
     "skills/chant-gitlab-migrate.md": "4853d04980560b379e5b0f7267dcb0a1e5d5879cb9e9931681ce76b2a5fe69d8",
     "skills/chant-gitlab-patterns.md": "6d9a44e9e8de4c3820be9d65381b0d2ede4cb3626aaaf0011e21838a9fbf556e"
   },
-  "composite": "91961711687524b02f38e71c0e81e7ee5a06fed36d763fa9b1296184fc0be51f"
+  "composite": "91aa3c4a176252cd5cd8ab7f02ecef7274e79a95aa85a1bfc31270ef32021897"
 }

package/dist/manifest.json

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

package/package.json

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

package/src/components/agent-jobs.ts

@@ -0,0 +1,176 @@
+/**
+ * The agent jobs on GitLab (#4616): `ScheduledOpSpec.agent`. What each job
+ * does is @intentius/chant/ci-agent's; this file lays them out in GitLab's
+ * terms.
+ *
+ * GitLab starts no pipeline on a note, and every job in a pipeline gets the
+ * same protected variables. So:
+ *
+ * - a comment agent runs in a pipeline of the default branch that the API, a
+ *   trigger or a person starts with `CHANT_AGENT_PR` (the merge request's
+ *   iid) and `CHANT_AGENT_ASK` (the ask). Whoever starts that pipeline is
+ *   who asked. A drift agent follows the drift Op's job in its scheduled
+ *   pipeline and runs when that job's run exited with chant's `drift` code.
+ * - the agent job unsets every forge token variable and drops the job token
+ *   from the remote before the model runs, and keeps the agent directory as
+ *   an artifact. It holds the model's key.
+ * - the push job runs in the same pipeline under environment
+ *   `<agent>-push`, takes the artifact, and pushes with `tokenEnv`
+ *   (`CHANT_FORGE_TOKEN` by default). Scope that variable to the
+ *   `<agent>-push` environment, protected and masked, so the agent job never
+ *   holds it.
+ *
+ * A workspace member's drift Op runs in the member's directory, so its
+ * artifact holds `<member>/.chant/agent` (#4619). Both agent jobs run at
+ * the repository root and take `dir`, that path, as their agent directory.
+ */
+
+import { GITLAB_DROP_FORGE_TOKENS } from "@intentius/chant/ci-handover";
+import { gitlabTags, type CiRunner } from "@intentius/chant/ci-jobs";
+import {
+  AGENT_DECISION_FILE,
+  AGENT_DIR,
+  AGENT_DRIFT_FILE,
+  AGENT_GITLAB_TOKEN_ENV,
+  AGENT_HEAD_REF,
+  agentCommandLines,
+  agentGitAuthLines,
+  agentHeadFetchLine,
+  agentSettingsEnv,
+  GITLAB_AGENT_ASK_VAR,
+  GITLAB_AGENT_PR_VAR,
+  type AgentSettings,
+} from "@intentius/chant/ci-agent";
+import { CHANT_EXIT } from "@intentius/chant/exit-codes";
+
+/** The dotenv the drift Op's job leaves, which says whether it found drift. */
+const DRIFT_DOTENV = `${AGENT_DIR}/drift.env`;
+const AGENT_ARTIFACT_EXPIRY = "7 days";
+
+/** The comment agent's rule: a pipeline of the default branch started with the merge request and the ask. */
+export const GITLAB_AGENT_RULE = `$CI_PIPELINE_SOURCE =~ /^(web|api|trigger|chat)$/ && $${GITLAB_AGENT_PR_VAR} =~ /^[0-9]+$/ && $${GITLAB_AGENT_ASK_VAR} && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH`;
+
+export function gitlabAgentPushJobName(jobName: string): string {
+  return `${jobName}-push`;
+}
+
+/** The environment the push job runs under, which the push token is scoped to. */
+export function gitlabAgentEnvironment(jobName: string): string {
+  return `${jobName}-push`;
+}
+
+/** The remote without the job token GitLab put in its URL. */
+const PLAIN_REMOTE = 'git remote set-url origin "$CI_SERVER_URL/$CI_PROJECT_PATH.git"';
+/** The ledger branch, for the run count and the record. */
+const LEDGER_FETCH = "git fetch -q --no-tags origin '+refs/heads/chant/lifecycle:refs/heads/chant/lifecycle' 2>/dev/null || true";
+
+/**
+ * The drift Op's script lines (#4616): the run with its output kept for the
+ * agent, and `CHANT_AGENT_DRIFT=1` in a dotenv when it exits with chant's
+ * `drift` code. The job still exits with the run's code.
+ */
+export function gitlabDriftRunLines(invocation: string): string[] {
+  return [
+    `mkdir -p ${AGENT_DIR}`,
+    `set +e; { ${invocation}; echo "$?" > ${AGENT_DIR}/code; } 2>&1 | tee ${AGENT_DIR}/${AGENT_DRIFT_FILE}; code=$(cat ${AGENT_DIR}/code); set -e`,
+    `if [ "$code" -eq ${CHANT_EXIT.drift} ]; then echo "CHANT_AGENT_DRIFT=1" > ${DRIFT_DOTENV}; else echo "CHANT_AGENT_DRIFT=0" > ${DRIFT_DOTENV}; fi`,
+    'exit "$code"',
+  ];
+}
+
+/** The drift Op job's artifacts: the output for the agent and the dotenv. */
+export function gitlabDriftArtifacts(dir: string): Record<string, unknown> {
+  return { when: "always", paths: [dir], reports: { dotenv: `${dir}/drift.env` }, expire_in: AGENT_ARTIFACT_EXPIRY };
+}
+
+export interface GitlabAgentJobsInput {
+  jobName: string;
+  stage: string;
+  image: string;
+  settings: AgentSettings;
+  runner?: CiRunner;
+  /** Setup and before-script lines, run before chant in both jobs. */
+  script: readonly string[];
+  /** The variable holding the push token. Default {@link AGENT_GITLAB_TOKEN_ENV}. */
+  tokenEnv?: string;
+  bin?: string;
+  /** For a drift agent: the Op's job and its rules. */
+  after?: { job: string; rules: unknown[] };
+  /** The agent directory from the repository root: where the drift Op's artifact put the drift. Default {@link AGENT_DIR}. */
+  dir?: string;
+}
+
+/** The agent job and the push job. */
+export function gitlabAgentJobs(i: GitlabAgentJobsInput): { agent: Record<string, unknown>; push: Record<string, unknown> } {
+  const s = i.settings;
+  const dir = i.dir ?? AGENT_DIR;
+  const lines = agentCommandLines("gitlab", i.bin, dir);
+  const comment = s.on === "comment";
+  const tags = gitlabTags(i.runner);
+  const variables = { ...agentSettingsEnv(s), GIT_DEPTH: "0" };
+  const rules = comment ? [{ if: GITLAB_AGENT_RULE }] : i.after!.rules.map((r) => ({ ...(r as Record<string, unknown>), when: "always" }));
+  const head = comment ? [agentHeadFetchLine("gitlab", GITLAB_AGENT_PR_VAR)] : [];
+  // A drift agent's job runs whatever the drift check found, and stops here when it found none.
+  const driftGate = comment ? [] : [`if [ "\${CHANT_AGENT_DRIFT:-0}" != "1" ]; then echo "no drift, so the agent does not run"; exit 0; fi`];
+  const agent: Record<string, unknown> = {
+    stage: i.stage,
+    image: i.image,
+    ...(tags ? { tags } : {}),
+    resource_group: i.jobName,
+    timeout: `${s.timeout + 15} minutes`,
+    variables,
+    rules,
+    ...(comment ? {} : { needs: [{ job: i.after!.job, artifacts: true }] }),
+    script: [
+      ...driftGate,
+      ...head,
+      LEDGER_FETCH,
+      PLAIN_REMOTE,
+      ...i.script,
+      // No forge token reaches the model: the decision needs none on GitLab, and the push job checks the merge request.
+      GITLAB_DROP_FORGE_TOKENS,
+      lines.prepare,
+      lines.run,
+    ],
+    artifacts: { when: "always", paths: [dir], expire_in: AGENT_ARTIFACT_EXPIRY },
+  };
+  const tokenVar = i.tokenEnv ?? AGENT_GITLAB_TOKEN_ENV;
+  const push: Record<string, unknown> = {
+    stage: i.stage,
+    image: i.image,
+    ...(tags ? { tags } : {}),
+    resource_group: gitlabAgentPushJobName(i.jobName),
+    environment: { name: gitlabAgentEnvironment(i.jobName), action: "access" },
+    variables,
+    rules,
+    needs: [{ job: i.jobName, artifacts: true }],
+    script: [
+      // The agent job leaves a decision whenever it ran; with none, the drift check found nothing.
+      ...(comment ? [] : [`if [ ! -f ${dir}/${AGENT_DECISION_FILE} ]; then echo "the agent did not run"; exit 0; fi`]),
+      ...head,
+      LEDGER_FETCH,
+      PLAIN_REMOTE,
+      ...i.script,
+      `export CHANT_GITLAB_TOKEN="$${tokenVar}"`,
+      ...agentGitAuthLines(tokenVar, "oauth2"),
+      lines.land,
+    ],
+  };
+  return { agent, push };
+}
+
+/** The header lines a file with agent jobs carries: how to start a comment agent and where the token goes. */
+export function gitlabAgentHeader(jobName: string, s: AgentSettings, tokenVar = AGENT_GITLAB_TOKEN_ENV): string[] {
+  return [
+    comment(s)
+      ? `#   ${jobName}: answers ${s.comment} from a pipeline of the default branch started with ${GITLAB_AGENT_PR_VAR}=<iid> and ${GITLAB_AGENT_ASK_VAR}=<ask>`
+      : `#   ${jobName}: after the drift check exits ${CHANT_EXIT.drift}, opens or updates a merge request from ${s.branch}`,
+    `#     ${gitlabAgentPushJobName(jobName)} pushes with ${tokenVar}: scope it to environment ${gitlabAgentEnvironment(jobName)}, protected and masked; the model's key is ${s.keyEnv}`,
+    `#     the fetched head is ${AGENT_HEAD_REF}; runs are limited to ${s.maxRuns ?? "no fixed number of"} a day on the ledger` +
+      (s.maxCostUsd !== undefined ? `, and to $${s.maxCostUsd} a day of recorded cost` : ""),
+  ];
+}
+
+function comment(s: AgentSettings): boolean {
+  return s.on === "comment";
+}