@intentius/chant-lexicon-gitlab 0.124.54 → 0.124.55

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

@@ -0,0 +1,68 @@
+/**
+ * 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 { type CiRunner } from "@intentius/chant/ci-jobs";
+import { type AgentSettings } from "@intentius/chant/ci-agent";
+/** The comment agent's rule: a pipeline of the default branch started with the merge request and the ask. */
+export declare const GITLAB_AGENT_RULE = "$CI_PIPELINE_SOURCE =~ /^(web|api|trigger|chat)$/ && $CHANT_AGENT_PR =~ /^[0-9]+$/ && $CHANT_AGENT_ASK && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH";
+export declare function gitlabAgentPushJobName(jobName: string): string;
+/** The environment the push job runs under, which the push token is scoped to. */
+export declare function gitlabAgentEnvironment(jobName: string): string;
+/**
+ * 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 declare function gitlabDriftRunLines(invocation: string): string[];
+/** The drift Op job's artifacts: the output for the agent and the dotenv. */
+export declare function gitlabDriftArtifacts(dir: string): Record<string, unknown>;
+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 declare function gitlabAgentJobs(i: GitlabAgentJobsInput): {
+    agent: Record<string, unknown>;
+    push: Record<string, unknown>;
+};
+/** The header lines a file with agent jobs carries: how to start a comment agent and where the token goes. */
+export declare function gitlabAgentHeader(jobName: string, s: AgentSettings, tokenVar?: string): string[];
+//# sourceMappingURL=agent-jobs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-jobs.d.ts","sourceRoot":"","sources":["../../src/components/agent-jobs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAYL,KAAK,aAAa,EACnB,MAAM,2BAA2B,CAAC;AAOnC,6GAA6G;AAC7G,eAAO,MAAM,iBAAiB,sJAAsK,CAAC;AAErM,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,kFAAkF;AAClF,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9D;AAOD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAOhE;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,aAAa,CAAC;IACxB,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,oEAAoE;IACpE,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,KAAK,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC;IAC1C,4HAA4H;IAC5H,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,sCAAsC;AACtC,wBAAgB,eAAe,CAAC,CAAC,EAAE,oBAAoB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAwD1H;AAED,8GAA8G;AAC9G,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,aAAa,EAAE,QAAQ,SAAyB,GAAG,MAAM,EAAE,CAShH"}

package/dist/components/agent-jobs.js

@@ -0,0 +1,135 @@
+/**
+ * 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 } 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, } 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) {
+    return `${jobName}-push`;
+}
+/** The environment the push job runs under, which the push token is scoped to. */
+export function gitlabAgentEnvironment(jobName) {
+    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) {
+    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) {
+    return { when: "always", paths: [dir], reports: { dotenv: `${dir}/drift.env` }, expire_in: AGENT_ARTIFACT_EXPIRY };
+}
+/** The agent job and the push job. */
+export function gitlabAgentJobs(i) {
+    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, 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 = {
+        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 = {
+        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, s, tokenVar = AGENT_GITLAB_TOKEN_ENV) {
+    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) {
+    return s.on === "comment";
+}

package/dist/components/control-pipeline.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The control repo's own pipeline (#4568) on GitLab: a member's pipeline
+ * trigger starts it with `CHANT_CONTROL_MEMBER` and `CHANT_CONTROL_OP` set,
+ * and its one job runs the member's dependents with `chant workspace run
+ * --dependents-of`. The pieces are core's (`controlPipelineSpec` in
+ * `@intentius/chant/control/dispatch`); the file is one the control repo's
+ * `.gitlab-ci.yml` includes. The member's side, the `control-dispatch` job,
+ * comes from the pull request loop's `control` option
+ * (./generate-pipeline.ts).
+ */
+import type { CiProductWords, CiProductWordsInput } from "@intentius/chant/ci-product-words";
+/** 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[];
+}
+/** The control repo's pipeline on GitLab: `.gitlab/<product>-dependents.yml`. */
+export declare function generateControlPipeline(options?: {
+    words?: CiProductWordsInput | CiProductWords;
+    image?: string;
+    command?: string;
+}): ControlPipelineFile;
+//# sourceMappingURL=control-pipeline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"control-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/control-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAG7F,gGAAgG;AAChG,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,iFAAiF;AACjF,wBAAgB,uBAAuB,CAAC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,mBAAmB,GAAG,cAAc,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,mBAAmB,CAa7J"}

package/dist/components/control-pipeline.js

@@ -0,0 +1,28 @@
+/**
+ * The control repo's own pipeline (#4568) on GitLab: a member's pipeline
+ * trigger starts it with `CHANT_CONTROL_MEMBER` and `CHANT_CONTROL_OP` set,
+ * and its one job runs the member's dependents with `chant workspace run
+ * --dependents-of`. The pieces are core's (`controlPipelineSpec` in
+ * `@intentius/chant/control/dispatch`); the file is one the control repo's
+ * `.gitlab-ci.yml` includes. The member's side, the `control-dispatch` job,
+ * comes from the pull request loop's `control` option
+ * (./generate-pipeline.ts).
+ */
+import { CI_IMAGE, GITLAB_FULL_HISTORY } from "@intentius/chant/ci-jobs";
+import { controlPipelineSpec } from "@intentius/chant/control/dispatch";
+import { emitGitlabFile } from "./ci-jobs.js";
+/** The control repo's pipeline on GitLab: `.gitlab/<product>-dependents.yml`. */
+export function generateControlPipeline(options = {}) {
+    const spec = controlPipelineSpec("gitlab", options.words ?? {}, options.command ? { command: options.command } : {});
+    const job = {
+        stage: "deploy",
+        image: options.image ?? CI_IMAGE,
+        // The full history, so the job reads and appends to chant/lifecycle (#4617).
+        variables: { ...GITLAB_FULL_HISTORY },
+        rules: [{ if: spec.rule }],
+        // One member at a time: two applies upstream should not run the same dependents side by side.
+        resource_group: spec.group,
+        script: [`bash <<'DEPENDENTS' || exit $?\n${spec.script}\nDEPENDENTS`],
+    };
+    return { path: spec.path, content: emitGitlabFile([["dependents", job]], spec.header), notes: spec.notes };
+}

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

@@ -103,6 +103,15 @@
  * internal and always wins at the job over a same-named spec entry, so a
  * caller cannot point the gate block somewhere the `artifacts:` declaration
  * beside it does not also point.
+ *
+ * `reviewAgent` (#4544) splits the review in two, as on GitHub and Forgejo,
+ * with GitLab's own shape (`./review-jobs.ts`). The review job runs in the
+ * merge request pipeline, unsets every forge token variable and keeps the
+ * review as its artifact. Its note job runs in a pipeline of the default
+ * branch that a schedule starts with `CHANT_REVIEW_NOTES` set to `1`, checks
+ * nothing out and posts each open merge request's review with the protected
+ * `CHANT_FORGE_TOKEN`. The header says to create that schedule and protect
+ * the token.
  */
 import type { ComponentPipelineOptions as GenerateGitlabOpOptions, OpPipelineResult as GenerateGitlabOpResult, ScheduledOpSpec } from "@intentius/chant/lexicon";
 export type { GenerateGitlabOpOptions, GenerateGitlabOpResult };

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

@@ -1 +1 @@
-{"version":3,"file":"generate-op-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyGG;AAeH,OAAO,KAAK,EACV,wBAAwB,IAAI,uBAAuB,EAInD,gBAAgB,IAAI,sBAAsB,EAE1C,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAIlC,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,CAAC;AA8IhE;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAuGxB"}
+{"version":3,"file":"generate-op-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkHG;AAiBH,OAAO,KAAK,EACV,wBAAwB,IAAI,uBAAuB,EAInD,gBAAgB,IAAI,sBAAsB,EAE1C,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAQlC,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,CAAC;AA4HhE;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAwMxB"}

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

@@ -103,10 +103,23 @@
  * internal and always wins at the job over a same-named spec entry, so a
  * caller cannot point the gate block somewhere the `artifacts:` declaration
  * beside it does not also point.
+ *
+ * `reviewAgent` (#4544) splits the review in two, as on GitHub and Forgejo,
+ * with GitLab's own shape (`./review-jobs.ts`). The review job runs in the
+ * merge request pipeline, unsets every forge token variable and keeps the
+ * review as its artifact. Its note job runs in a pipeline of the default
+ * branch that a schedule starts with `CHANT_REVIEW_NOTES` set to `1`, checks
+ * nothing out and posts each open merge request's review with the protected
+ * `CHANT_FORGE_TOKEN`. The header says to create that schedule and protect
+ * the token.
  */
-import { assertGitlabEnvironment, CI_IMAGE, ciJobName, environmentDoc, fillCommand, gitlabIdTokens, gitlabRules, gitlabSetupScript, nonEmpty, pushBranches, } from "@intentius/chant/ci-jobs";
+import { assertGitlabEnvironment, CI_IMAGE, ciJobName, environmentDoc, fillCommand, gitlabIdTokens, gitlabRules, gitlabSetupScript, gitlabTags, assertRunnerLabels, nonEmpty, pushBranches, } from "@intentius/chant/ci-jobs";
 import { memberGitlabChanges, memberRepoPath, memberShellDir, resolveOpTrigger } from "@intentius/chant/lexicon";
 import { emitGitlabFile } from "./ci-jobs.js";
+import { assertReviewSplit, GITLAB_REVIEW_NOTES_VAR, gitlabReviewJobs, REVIEW_DIR, reviewNoteJobName } from "./review-jobs.js";
+import { AGENT_DIR, resolveAgentSpec } from "@intentius/chant/ci-agent";
+import { activeProductWords } from "@intentius/chant/ci-product-words";
+import { gitlabAgentHeader, gitlabAgentJobs, gitlabAgentPushJobName, gitlabDriftArtifacts, gitlabDriftRunLines } from "./agent-jobs.js";
 /**
  * Default stage every generated job runs in, and the default base of the
  * generated file's name (#2293). Overridable via `options.opsStage` (and the
@@ -164,22 +177,6 @@ function assertTriggerSupportsMode(name, mode, trigger) {
         `no merge request to post on. Give it a { kind: "pull_request" } trigger, or use findingMode "issue" ` +
         `or "merge-request".`);
 }
-/**
- * Refuse `reviewAgent` (#4326). The split posts the review from a second job
- * that holds the forge write token, and a GitLab merge request pipeline hands
- * every job the project's unprotected CI/CD variables, the review job's
- * included. A token protected enough to stay out of it is not available to a
- * job of that pipeline either, so the post has to start from a pipeline of
- * the default branch, which this generator does not build. The refusal names
- * the Op and the way out rather than emitting a review job that holds the token.
- */
-function assertNoReviewSplit(spec) {
-    if (!spec.reviewAgent)
-        return;
-    throw new Error(`Scheduled Op "${spec.name}" sets reviewAgent, which keeps the model's job free of the forge write token and posts the note from a second job. ` +
-        `A GitLab merge request pipeline hands every job the project's unprotected variables, so the gitlab generator does not build that split. ` +
-        `Drop reviewAgent and run the review with findingMode "comment" (the model command still runs with a cleared environment), or generate this Op for GitHub or Forgejo.`);
-}
 /**
  * The follow-up line an Op with an `environment` adds under its own header
  * line (#2257). The `environment:` key on the job binds it to the
@@ -244,19 +241,60 @@ export function generateGitlabOpPipeline(ops, options = {}) {
     const doc = { stages: [stage], ...nonEmpty("variables", options.variables) };
     const opLines = [];
     let anyCron = false;
+    let anyReview = false;
+    // The note job of each split review (#4544), emitted after the Op jobs.
+    const noteJobs = [];
+    const words = activeProductWords();
     for (const spec of ops) {
         const subject = `Scheduled Op "${spec.name}"`;
+        // #4616: GitLab picks a runner by tags.
+        assertRunnerLabels(subject, "runner", spec.runner, "GitLab");
+        const tags = gitlabTags(spec.runner);
         const setupScript = gitlabSetupScript(subject, spec.setup);
+        // #4616: the comment agent is its own pair of jobs, in a pipeline of the default branch; the spec's trigger is not read.
+        if (spec.agent?.on === "comment") {
+            const settings = resolveAgentSpec(spec.name, spec.agent, words.product);
+            const jobName = jobPrefix + ciJobName(spec.name);
+            jobs.push({ jobName, op: spec.name, trigger: { kind: "pull_request" }, findingMode: "report" });
+            opLines.push(...gitlabAgentHeader(jobName, settings, spec.agent.tokenEnv));
+            const { agent, push } = gitlabAgentJobs({
+                jobName,
+                stage,
+                image,
+                settings,
+                ...(spec.runner !== undefined ? { runner: spec.runner } : {}),
+                script: [...setupScript, ...beforeScript],
+                ...(spec.agent.tokenEnv ? { tokenEnv: spec.agent.tokenEnv } : {}),
+                ...(words.bin ? { bin: words.bin } : {}),
+            });
+            doc[jobName] = agent;
+            const pushName = gitlabAgentPushJobName(jobName);
+            doc[pushName] = push;
+            noteJobs.push(pushName);
+            continue;
+        }
         const idTokens = gitlabIdTokens(spec.name, spec.permissions);
         const findingMode = spec.findingMode ?? "report";
         const trigger = resolveOpTrigger(spec);
         assertTriggerSupportsMode(spec.name, findingMode, trigger);
-        assertNoReviewSplit(spec);
+        // A split review (#4544): the merge request pipeline runs the model with no forge token, and a pipeline of the default branch posts.
+        const split = spec.reviewAgent === true;
+        if (split)
+            assertReviewSplit(spec.name, trigger, findingMode, spec.permissions);
         if (trigger.kind === "cron")
             anyCron = true;
+        const driftAgent = spec.agent?.on === "drift" ? resolveAgentSpec(spec.name, spec.agent, words.product) : undefined;
+        if (driftAgent && (split || trigger.kind === "push")) {
+            throw new Error(`${subject} sets a drift agent, which follows a drift check's run; give it a cron or pull_request trigger and no reviewAgent.`);
+        }
         const jobName = jobPrefix + ciJobName(spec.name);
         jobs.push({ jobName, op: spec.name, trigger, findingMode });
         opLines.push(headerLineFor(spec, trigger, jobName, findingMode));
+        if (split) {
+            anyReview = true;
+            opLines.push(`#     reviewAgent: the review job holds no forge token and keeps its review as an artifact; ${reviewNoteJobName(jobName)} posts it` +
+                ` from a pipeline of the default branch started with ${GITLAB_REVIEW_NOTES_VAR}="1"`);
+        }
         if (spec.environment) {
             assertGitlabEnvironment(spec.name, spec.environment);
             opLines.push(environmentLine(spec.environment));
@@ -277,25 +315,69 @@ export function generateGitlabOpPipeline(ops, options = {}) {
             ...(spec.variables ?? {}),
             ...(gated ? { [GATE_SUMMARY_VAR]: gateSummary } : {}),
         };
+        const rulesFor = changes && trigger.kind !== "cron" ? rules.map((r) => ({ ...r, changes })) : rules;
+        if (split) {
+            const { review, note } = gitlabReviewJobs({
+                name: spec.name,
+                jobName,
+                stage,
+                image,
+                rules: rulesFor,
+                script: [...cdLine, ...setupScript, ...beforeScript, invocation.join(" "), ...extraScript],
+                ...(spec.variables ? { variables: spec.variables } : {}),
+                ...(idTokens ? { idTokens } : {}),
+                artifactDir: member ? memberRepoPath(member, REVIEW_DIR) : REVIEW_DIR,
+                ...(trigger.kind === "pull_request" && trigger.branches?.length ? { branches: trigger.branches } : {}),
+            });
+            doc[jobName] = { ...review, ...(tags ? { tags } : {}), ...(spec.environment ? { environment: environmentDoc(spec.environment) } : {}) };
+            const noteName = reviewNoteJobName(jobName);
+            doc[noteName] = { ...note, ...(tags ? { tags } : {}) };
+            noteJobs.push(noteName);
+            continue;
+        }
+        const runLines = driftAgent ? gitlabDriftRunLines(invocation.join(" ")) : [invocation.join(" ")];
         doc[jobName] = {
             stage,
             image,
+            ...(tags ? { tags } : {}),
             // GitLab's stand-in for github's per-Op concurrency group: queue the
             // next run rather than cancel the current one.
             resource_group: jobName,
             ...(idTokens ? { id_tokens: idTokens } : {}),
             ...(spec.environment ? { environment: environmentDoc(spec.environment) } : {}),
             ...nonEmpty("variables", jobVariables),
-            rules: changes && trigger.kind !== "cron" ? rules.map((r) => ({ ...r, changes })) : rules,
-            script: [...cdLine, ...setupScript, ...beforeScript, invocation.join(" "), ...extraScript],
+            rules: rulesFor,
+            script: [...cdLine, ...setupScript, ...beforeScript, ...runLines, ...extraScript],
             // `when: always` because the run this publishes for is the green one: a
             // gated apply succeeds, and the block is the only thing that says a
             // human still has to act. A run that walked through its gate writes no
             // block, and GitLab reports the empty upload as a warning, not a failure.
             ...(gated
                 ? { artifacts: { when: "always", paths: [member ? memberRepoPath(member, gateSummary) : gateSummary], expire_in: GATE_ARTIFACT_EXPIRY } }
-                : {}),
+                : driftAgent
+                    ? { artifacts: gitlabDriftArtifacts(member ? memberRepoPath(member, AGENT_DIR) : AGENT_DIR) }
+                    : {}),
         };
+        if (driftAgent) {
+            const name = `${jobName}-agent`;
+            opLines.push(...gitlabAgentHeader(name, driftAgent, spec.agent?.tokenEnv));
+            const { agent, push } = gitlabAgentJobs({
+                jobName: name,
+                stage,
+                image,
+                settings: driftAgent,
+                ...(spec.runner !== undefined ? { runner: spec.runner } : {}),
+                script: [...setupScript, ...beforeScript],
+                ...(spec.agent?.tokenEnv ? { tokenEnv: spec.agent.tokenEnv } : {}),
+                ...(words.bin ? { bin: words.bin } : {}),
+                after: { job: jobName, rules: rulesFor },
+                // #4619: a member's drift Op left the drift under the member's directory.
+                ...(member ? { dir: memberRepoPath(member, AGENT_DIR) } : {}),
+            });
+            doc[name] = agent;
+            doc[gitlabAgentPushJobName(name)] = push;
+            noteJobs.push(name, gitlabAgentPushJobName(name));
+        }
     }
     const headerLines = [
         `# chant Ops — one job per Op under stage "${stage}", each`,
@@ -305,7 +387,10 @@ export function generateGitlabOpPipeline(ops, options = {}) {
     if (anyCron) {
         headerLines.push("#", "# GitLab has no in-file cron. Create one Pipeline Schedule per cron Op", "# below (Settings > CI/CD > Schedules): set its cron to the value noted", `# here and its ${SELECTOR_VAR} CI/CD variable to the Op's name, so only`, "# that job runs on that schedule.");
     }
+    if (anyReview) {
+        headerLines.push("#", "# A reviewAgent Op's note job posts from a pipeline of the default branch,", `# never from the merge request's own. Create a Pipeline Schedule on the`, `# default branch with ${GITLAB_REVIEW_NOTES_VAR}="1", and make CHANT_FORGE_TOKEN`, "# (a token with the api scope) a protected, masked CI/CD variable so no", "# merge request pipeline gets it.");
+    }
     headerLines.push("#", ...opLines);
-    const yaml = emitGitlabFile([["stages", doc.stages], ...(doc.variables ? [["variables", doc.variables]] : []), ...jobs.map(({ jobName }) => [jobName, doc[jobName]])], headerLines);
+    const yaml = emitGitlabFile([["stages", doc.stages], ...(doc.variables ? [["variables", doc.variables]] : []), ...jobs.map(({ jobName }) => [jobName, doc[jobName]]), ...noteJobs.map((name) => [name, doc[name]])], headerLines);
     return { files: [{ name: fileName, yaml }], jobs };
 }

package/dist/components/generate-op-waves-pipeline.d.ts

@@ -37,6 +37,18 @@
  * entry per cloud, and its script starts by trading them for those
  * identities and unsetting the token variables, before any line of the
  * checkout runs.
+ *
+ * With `control` on the spec (#4617), a `control-dispatch` job in a
+ * `control` stage needs the last wave's jobs, whose artifacts hold every
+ * job's outcome file. It adds them up with `chant run wave --waves-outcome`
+ * (through the product's bin) into `CHANT_CONTROL_OUTCOME` and sends the
+ * control repo one dispatch carrying it and `$CI_COMMIT_SHA`. A last wave
+ * whose runs failed (exit 1) still lets it run; a wave that waits at its
+ * gate stops it with the waves, and it runs once the retried job carries
+ * on. A CI/CD variable reaches every job, so every other job starts by
+ * unsetting the control repo's token variables and the product's two
+ * secret names; the dispatch step reads the token from the product's
+ * variable alone and hands it to curl on its stdin (#4568).
  */
 import { type OpWavesSpec } from "@intentius/chant/op/op-waves";
 import type { OpWavesPipelineOptions, OpWavesPipelineResult } from "@intentius/chant/lexicon";

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

@@ -1 +1 @@
-{"version":3,"file":"generate-op-waves-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-waves-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAkBH,OAAO,EAAqE,KAAK,WAAW,EAAE,MAAM,8BAA8B,CAAC;AACnI,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAI9F,gHAAgH;AAChH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CA+FvH"}
+{"version":3,"file":"generate-op-waves-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-waves-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAkBH,OAAO,EASL,KAAK,WAAW,EACjB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAI9F,gHAAgH;AAChH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAuIvH"}

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

@@ -37,14 +37,27 @@
  * entry per cloud, and its script starts by trading them for those
  * identities and unsetting the token variables, before any line of the
  * checkout runs.
+ *
+ * With `control` on the spec (#4617), a `control-dispatch` job in a
+ * `control` stage needs the last wave's jobs, whose artifacts hold every
+ * job's outcome file. It adds them up with `chant run wave --waves-outcome`
+ * (through the product's bin) into `CHANT_CONTROL_OUTCOME` and sends the
+ * control repo one dispatch carrying it and `$CI_COMMIT_SHA`. A last wave
+ * whose runs failed (exit 1) still lets it run; a wave that waits at its
+ * gate stops it with the waves, and it runs once the retried job carries
+ * on. A CI/CD variable reaches every job, so every other job starts by
+ * unsetting the control repo's token variables and the product's two
+ * secret names; the dispatch step reads the token from the product's
+ * variable alone and hands it to curl on its stdin (#4568).
  */
 import { assertGitlabBranch, assertGitlabEnvironment, assertRunnerLabels, CI_IMAGE, environmentDoc, GITLAB_FULL_HISTORY, GITLAB_MERGE_REQUEST_SOURCE, GITLAB_SCHEDULE_SOURCE, gitlabIdTokensDoc, gitlabPushRule, gitlabSetupScript, gitlabTags, nonEmpty, pushBranches, } from "@intentius/chant/ci-jobs";
-import { opWaveGroupOf, opWaveJobs, opWaveOutcomeDir, opWavesResumeCommand } from "@intentius/chant/op/op-waves";
+import { opWaveGroupOf, opWaveJobs, opWaveOutcomeDir, opWavesControlTarget, opWavesLastJobs, opWavesOutcomeCommand, opWavesRecordPlansCommand, opWavesResumeCommand, } from "@intentius/chant/op/op-waves";
+import { CONTROL_OUTCOME_VAR, CONTROL_TOKEN_VARS, controlDispatchJob } from "@intentius/chant/control/dispatch";
 import { gitlabTradeIdTokens, gitlabTradeLines, TRADE_SPEC_ENV } from "@intentius/chant/ci-identity";
 import { emitGitlabFile } from "./ci-jobs.js";
 /** Render an Op waves spec as one GitLab CI file, `<name>.gitlab-ci.yml` unless `opsFileName` names another. */
 export function generateGitlabOpWavesPipeline(spec, options) {
-    const jobs = opWaveJobs(spec, options.specFile);
+    const jobs = opWaveJobs(spec, options.specFile, { bin: options.bin });
     const image = options.image ?? CI_IMAGE;
     const subject = `Op waves "${spec.name}"`;
     const rules = pushBranches(spec.branches).map((branch) => {
@@ -71,6 +84,11 @@ export function generateGitlabOpWavesPipeline(spec, options) {
     const specTags = gitlabTags(spec.runner);
     const byReview = spec.waves.some((w) => w.approval === "pr-review");
     const stages = [...(byReview ? ["plans"] : []), ...spec.waves.map((wave, i) => `wave-${i + 1}-${wave.name}`)];
+    // #4617: the control repo's token variables, which every job but the dispatch drops first.
+    const control = spec.control ? opWavesControlTarget(spec.control) : undefined;
+    const dropControl = control ? [`unset ${[...new Set([...CONTROL_TOKEN_VARS, control.tokenSecret, control.readTokenSecret])].join(" ")}`] : [];
+    if (control)
+        stages.push("control");
     if (spec.resume)
         stages.push("resume");
     const entries = [["stages", stages]];
@@ -86,7 +104,7 @@ export function generateGitlabOpWavesPipeline(spec, options) {
                 ...(specTags ? { tags: specTags } : {}),
                 variables: { ...GITLAB_FULL_HISTORY },
                 rules: [{ if: GITLAB_MERGE_REQUEST_SOURCE }],
-                script: [...(options.beforeScript ?? []), ["chant", "run", "wave", "--spec", options.specFile, "--record-plans"].join(" ")],
+                script: [...dropControl, ...(options.beforeScript ?? []), opWavesRecordPlansCommand(options.specFile, options.bin).join(" ")],
             },
         ]);
     }
@@ -112,13 +130,48 @@ export function generateGitlabOpWavesPipeline(spec, options) {
                 variables: { ...GITLAB_FULL_HISTORY, ...(wave.variables ?? {}), ...(group?.variables ?? {}), ...(cloud ? { [TRADE_SPEC_ENV]: JSON.stringify(cloud) } : {}) },
                 rules,
                 ...(job.needs.length > 0 ? { needs: job.needs } : {}),
-                script: [...(cloud ? gitlabTradeLines() : []), ...setup, ...(options.beforeScript ?? []), job.command.join(" "), ...(options.extraScript ?? [])],
+                script: [...(cloud ? gitlabTradeLines() : []), ...dropControl, ...setup, ...(options.beforeScript ?? []), job.command.join(" "), ...(options.extraScript ?? [])],
                 // #4322: a run that failed, or was blocked, lets the next wave run; any other failure stops it.
                 allow_failure: { exit_codes: [1] },
                 artifacts: { when: "always", paths: [...(job.kind === "decide" ? [job.record] : []), `${opWaveOutcomeDir(spec)}/`], expire_in: "30 days" },
             },
         ]);
     }
+    if (control) {
+        const dispatch = controlDispatchJob("gitlab", control, "$CI_COMMIT_SHA", {
+            ...(options.words ? { words: options.words } : {}),
+            ...(spec.control.sentCheck ? { sentCheck: spec.control.sentCheck } : {}),
+            ...(spec.control.markSent ? { markSent: spec.control.markSent } : {}),
+            outcome: true,
+        });
+        entries.push([
+            dispatch.name,
+            {
+                stage: "control",
+                image,
+                ...(specTags ? { tags: specTags } : {}),
+                rules,
+                // The last wave's jobs hand on every job's outcome file through their artifacts.
+                needs: opWavesLastJobs(jobs),
+                // The setup and the outcome run in a subshell without the control token, and only the outcome reaches stdout.
+                script: [
+                    [
+                        'outcome="$(',
+                        ...dropControl,
+                        "{ :",
+                        ...setupOf[0],
+                        ...(options.beforeScript ?? []),
+                        "} 1>&2",
+                        opWavesOutcomeCommand(options.specFile, options.bin).join(" "),
+                        ')" || exit 1',
+                    ].join("\n"),
+                    `export ${CONTROL_OUTCOME_VAR}="$outcome"`,
+                    ...Object.entries(dispatch.env).map(([k, v]) => `export ${k}="${v}"`),
+                    `bash <<'CONTROL_DISPATCH' || exit $?\n${dispatch.script}\nCONTROL_DISPATCH`,
+                ],
+            },
+        ]);
+    }
     if (spec.resume) {
         entries.push([
             `${spec.name}-resume`,
@@ -127,7 +180,7 @@ export function generateGitlabOpWavesPipeline(spec, options) {
                 image,
                 ...(specTags ? { tags: specTags } : {}),
                 rules: [{ if: GITLAB_SCHEDULE_SOURCE }],
-                script: [...(options.beforeScript ?? []), opWavesResumeCommand(spec).join(" ")],
+                script: [...dropControl, ...(options.beforeScript ?? []), opWavesResumeCommand(spec, options.bin).join(" ")],
             },
         ]);
     }
@@ -139,6 +192,7 @@ export function generateGitlabOpWavesPipeline(spec, options) {
         ...(spec.resume
             ? [`# The ${spec.name}-resume job retries it for you in a pipeline schedule; give the schedule the cron "${spec.resume.schedule}".`]
             : []),
+        ...(control ? [`# After the last wave, the control-dispatch job tells ${control.repo} how the waves ended.`] : []),
     ];
     const name = options.opsFileName ?? `${spec.name}.gitlab-ci.yml`;
     return { files: [{ name, yaml: emitGitlabFile(entries, header) }], jobs };

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

@@ -1 +1 @@
-{"version":3,"file":"generate-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAWH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,oCAAoC,CAAC;AA0BjG,OAAO,KAAK,EACV,oBAAoB,IAAI,YAAY,EACpC,wBAAwB,IAAI,qBAAqB,EACjD,uBAAuB,IAAI,oBAAoB,EAEhD,MAAM,0BAA0B,CAAC;AAIlC,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;AAE1E;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAkJtB"}
+{"version":3,"file":"generate-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAWH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,oCAAoC,CAAC;AA8BjG,OAAO,KAAK,EACV,oBAAoB,IAAI,YAAY,EACpC,wBAAwB,IAAI,qBAAqB,EACjD,uBAAuB,IAAI,oBAAoB,EAEhD,MAAM,0BAA0B,CAAC;AAIlC,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;AAE1E;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAkJtB"}