@intentius/sql-yodeler 0.3.0 → 0.5.0

package/dist/ci/render.js

@@ -71,12 +71,18 @@
 import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { APPROVAL_MODES } from "../config/define.js";
+import { audience, CLOUD_OF, jobLogins, loginSteps } from "./login.js";
+import { RECORD_PLANS_ENV } from "../approval-mode/index.js";
+import { cloudToken, credentialsOf, roleVariables } from "../credentials.js";
 import { loadYodelConfig } from "../config/load.js";
+import { testFiles } from "../testing/files.js";
+import { CODE_QUALITY_FILE } from "../lint/annotations.js";
 import { emitYAMLEntry, parseYAMLDocument } from "@intentius/chant/yaml";
 import { Concurrency, Job as ActionsJob, Permissions, Service as ActionsService, Step, Workflow as ActionsWorkflow, } from "@intentius/chant-lexicon-github";
 import { githubSerializer } from "@intentius/chant-lexicon-github/serializer";
 import { forgejoSerializer } from "@intentius/chant-lexicon-forgejo/serializer";
-import { Artifacts as GitLabArtifacts, Image, Job as GitLabJob, Rule, Service as GitLabService, Workflow as GitLabWorkflow, WorkflowRule, } from "@intentius/chant-lexicon-gitlab";
+import { Artifacts as GitLabArtifacts, Image, Job as GitLabJob, Pipeline as GitLabPipeline, Rule, Service as GitLabService, Workflow as GitLabWorkflow, WorkflowRule, } from "@intentius/chant-lexicon-gitlab";
 import { gitlabSerializer } from "@intentius/chant-lexicon-gitlab/serializer";
 export const FORGES = ["github", "gitlab", "forgejo"];
 /** The image every job runs in, where the forge runs jobs in a container. It needs git, so not -slim. */
@@ -94,16 +100,87 @@ const SETUP_NODE = "actions/setup-node@v7";
 export const prefixOf = (env) => env.toUpperCase().replace(/[^A-Z0-9]/g, "_");
 /** DEV_CLICKHOUSE for dev on ClickHouse: what an environment's variables start with. */
 export const variablePrefix = (env, dialect) => `${prefixOf(env)}_${dialect.toUpperCase()}`;
-/** The variables a job reading `env` holds: the URL and the reader. */
-export const readerVariables = (env, dialect) => {
+/** The variables a job reading `env` holds: the URL and the reader (the variables credentials() names; none for a token-minted password). */
+export const readerVariables = (env, dialect, creds) => {
     const p = variablePrefix(env, dialect);
-    return [`${p}_URL`, `${p}_READER_USER`, `${p}_READER_PASSWORD`];
+    return [`${p}_URL`, ...(creds?.reader.variables ?? [`${p}_READER_USER`, `${p}_READER_PASSWORD`])];
 };
 /** The variables the apply job for `env` holds: the URL and the writer. */
-export const writerVariables = (env, dialect) => {
+export const writerVariables = (env, dialect, creds) => {
     const p = variablePrefix(env, dialect);
-    return [`${p}_URL`, `${p}_WRITER_USER`, `${p}_WRITER_PASSWORD`];
+    return [`${p}_URL`, ...(creds?.writer.variables ?? [`${p}_WRITER_USER`, `${p}_WRITER_PASSWORD`])];
 };
+// ── Cloud identity (#50) ────────────────────────────────────────────────────
+//
+// A role whose password is minted by a cloud token source (rds-iam,
+// cloud-sql-iam, entra) mints it with the cloud's command line, from the
+// job's identity. A job holding one gets an OIDC token from the forge: on
+// GitHub the workflow grants `id-token: write`; on GitLab the job declares
+// an ID token for the cloud's audience. Forgejo issues no OIDC token to a
+// job (its dialect drops `permissions:`), so there the runner's own cloud
+// identity mints.
+/** The GitLab ID token per cloud: its variable and its audience. */
+export const ID_TOKENS = {
+    "rds-iam": { variable: "AWS_ID_TOKEN", aud: "sts.amazonaws.com" },
+    "cloud-sql-iam": { variable: "GCP_ID_TOKEN", aud: "https://iam.googleapis.com/" },
+    entra: { variable: "AZURE_ID_TOKEN", aud: "api://AzureADTokenExchange" },
+};
+/** The cloud token sources the roles `held` mint from, each once, in order. */
+const cloudsOf = (envs, held) => [
+    ...new Set(held.map(([env, role]) => envs.credentials?.[env]?.[role].cloud).filter((c) => c !== undefined)),
+];
+/** A GitLab job's `id_tokens` for `clouds`, each for its login's audience when the job logs in (#132): GCP's is the workload identity provider's own. */
+const idTokens = (clouds, logins = []) => Object.fromEntries(clouds.map((c) => {
+    const login = logins.find((l) => l.cloud === CLOUD_OF[c]);
+    return [ID_TOKENS[c].variable, { aud: login ? audience(login) : ID_TOKENS[c].aud }];
+}));
+/** The cloud logins (#132) of a job holding the roles `held`, from yodel.config.ts `ci.login`. */
+const loginsOf = (envs, held) => jobLogins(envs.login, held, (env, role) => envs.credentials?.[env]?.[role].cloud);
+/** A job's login steps as the github lexicon's Steps. */
+const actionsLogin = (forge, logins) => loginSteps(forge, logins).steps.map((st) => new Step({ name: st.name, run: st.lines.join("\n") }));
+/** A job's login steps as plain step objects, for YAML chant rendered and yodel edits. */
+const rawLogin = (forge, logins) => loginSteps(forge, logins).steps.map((st) => ({ name: st.name, run: st.lines.join("\n") }));
+/** A GitLab job's login: its script lines and its variables. */
+const gitlabLogin = (logins) => {
+    const out = loginSteps("gitlab", logins);
+    return { lines: out.steps.flatMap((st) => st.lines), variables: out.variables };
+};
+/** Puts `steps` before the first step `at` picks (refusing a job without one). */
+function insertSteps(steps, add, at, what) {
+    if (add.length === 0)
+        return;
+    const i = steps.findIndex(at);
+    if (i < 0)
+        throw new Error(`${what}: no step to log in before`);
+    steps.splice(i, 0, ...add);
+}
+/** Puts `lines` before the first script line `at` picks (refusing a job without one). */
+function insertLines(script, add, at, what) {
+    if (add.length === 0)
+        return;
+    const i = script?.findIndex(at) ?? -1;
+    if (!script || i < 0)
+        throw new Error(`${what}: no script line to log in before`);
+    script.splice(i, 0, ...add);
+}
+const runsChant = (st) => typeof st.run === "string" && st.run.startsWith("chant run ");
+/** The roles a pull request's plan job for `env` holds: the environment's reader and the reader of the one it requires. */
+const planRoles = (waves, env) => [env, ...requiredOf(waves, env)].map((e) => [e, "reader"]);
+/** The roles a wave job for `env` holds: the writer, and the reader of the environment it requires. */
+const waveRoles = (waves, env) => [[env, "writer"], ...requiredOf(waves, env).map((e) => [e, "reader"])];
+/** The header lines saying what the cloud identity is for, when a job here holds a cloud-minted role. */
+function identityHeader(forge, clouds) {
+    if (clouds.length === 0)
+        return [];
+    const names = clouds.join(", ");
+    if (forge === "github")
+        return [`# Cloud identity: a password here is a ${names} token, minted from the job's`, "# identity, so the workflow grants id-token: write (an OIDC token)."];
+    if (forge === "gitlab")
+        return [`# Cloud identity: a password here is a ${names} token, minted from the job's`, `# identity: the jobs that hold one declare id_tokens (${clouds.map((c) => ID_TOKENS[c].variable).join(", ")}).`];
+    return [`# Cloud identity: a password here is a ${names} token. Forgejo gives a job no`, "# OIDC token, so the runner's own cloud identity mints it."];
+}
+/** The write probe a pull request job runs before its plan: it holds no writer for `envs`. */
+export const writeProbe = (envs) => `yodel config check ${envs.join(" ")} --write-probe`;
 const secret = (name) => `\${{ secrets.${name} }}`;
 const secrets = (names) => Object.fromEntries(names.map((n) => [n, secret(n)]));
 /**
@@ -153,7 +230,17 @@ export const REPLAY_SERVICE = {
 /** Waits up to 90 s for the replay server's port; a shell-free one-liner, so every forge runs it the same. */
 export const waitFor = (host, port) => `node -e 'const net = require("net"); let n = 0; (function t() { const s = net.connect(${String(port)}, "${host}", () => { s.end(); process.exit(0); }); s.on("error", () => { if (++n > 90) { console.error("${host}:${String(port)} did not answer"); process.exit(1); } setTimeout(t, 1000); }); })()'`;
 export const LINT = "yodel lint";
+/**
+ * The lint job's `yodel lint`, with its findings where the forge shows them
+ * (#129): workflow commands on GitHub and Forgejo, which annotate the
+ * migration files in the pull request; on GitLab the code quality report,
+ * which the job keeps as its `artifacts:reports:codequality`
+ * ({@link CODE_QUALITY_FILE}) and the merge request shows.
+ */
+export const lintCommand = (forge) => (forge === "gitlab" ? `${LINT} --format gitlab --output ${CODE_QUALITY_FILE}` : `${LINT} --format github`);
 export const REPLAY = `yodel lint --replay ${REPLAY_PROFILE} --reset`;
+/** yodel test (#54), after the replay check on the same throwaway server, its outcome as JUnit XML. */
+export const TEST = `yodel test --env ${REPLAY_PROFILE} --reset --junit yodel-test.xml`;
 /** Fails a pull request whose pipelines differ from what yodel ci renders. */
 export const CI_CHECK = "yodel ci --check";
 /**
@@ -180,15 +267,19 @@ export const reportCommand = (env, tc = { image: IMAGE, yodelImage: false }) =>
 export const reportArtifact = (job) => `yodel-report-${job}`;
 const UPLOAD_ARTIFACT = "actions/upload-artifact@v4";
 /**
- * The comment at the top of every file. Added here, not by chant: neither the
- * github nor the gitlab lexicon's serializer writes YAML comments
- * (INTENTIUS/chant#3667, INTENTIUS/chant#3669).
+ * The comment at the top of every file, as `#` lines. The files declared here
+ * (the review workflows and .gitlab-ci.yml) take theirs as the Workflow's or
+ * Pipeline's `comment`, which chant writes. The files chant's
+ * generateOpWavesPipeline and generateOpsPipeline write take no comment, so
+ * withHeader puts it above their YAML.
  */
 const HEADER = [
     "# Rendered by yodel ci from chant.config.ts, yodel.config.ts and ops/.",
     "# Edit those and render again; yodel ci --check says when this file is stale.",
 ];
 const withHeader = (header, yaml) => `${[...header, ""].join("\n")}${yaml}`;
+/** `#` lines as a declaration's `comment`: the text without its `# `, which the serializer writes back. */
+const asComment = (header) => header.map((l) => l.replace(/^# ?/, "")).join("\n");
 /** A serializer's output for one file: its YAML, refusing anything else (a second file, a warning). */
 function oneFile(forge, out) {
     if (typeof out === "string")
@@ -211,10 +302,9 @@ function reportSteps(env, job, tc) {
 }
 /** `inContainer`: the job runs in the toolchain's image, which has node, so it needs no setup-node. */
 function setupSteps(inContainer, tc) {
-    // Step inputs are strings in the lexicon's schema (INTENTIUS/chant#3670); the actions read them as strings either way.
-    const steps = [new Step({ uses: CHECKOUT, with: { "fetch-depth": "0" } })];
+    const steps = [new Step({ uses: CHECKOUT, with: { "fetch-depth": 0 } })];
     if (!inContainer)
-        steps.push(new Step({ uses: SETUP_NODE, with: { "node-version": "22", cache: "npm" } }));
+        steps.push(new Step({ uses: SETUP_NODE, with: { "node-version": 22, cache: "npm" } }));
     steps.push(...installLines(tc, "github").map((run) => new Step({ run })), new Step({ name: "Fetch the approvals (chant/lifecycle)", run: FETCH_APPROVALS }));
     return steps;
 }
@@ -225,7 +315,7 @@ const runner = (container, tc) => ({ "runs-on": "ubuntu-latest", ...(container ?
 function commentToken(forge) {
     return forge === "github" ? { GITHUB_TOKEN: "${{ github.token }}" } : { FORGEJO_TOKEN: "${{ github.token }}" };
 }
-function lintJob(forge, dialect, replay, tc) {
+function lintJob(forge, dialect, replay, tc, tests = false) {
     // With the replay check, the job runs in IMAGE on every forge and reaches
     // its replay server by the service's name on the job's own network. On
     // GitHub's VM the service would be on localhost through a published port,
@@ -235,7 +325,7 @@ function lintJob(forge, dialect, replay, tc) {
     const steps = [
         ...setupSteps(container, tc),
         new Step({ name: "The pipelines are up to date", run: CI_CHECK }),
-        new Step({ name: "yodel lint", run: LINT }),
+        new Step({ name: "yodel lint", run: lintCommand(forge) }),
     ];
     if (!replay)
         return new ActionsJob({ ...runner(container, tc), steps });
@@ -254,52 +344,66 @@ function lintJob(forge, dialect, replay, tc) {
             ...steps,
             new Step({ name: `Wait for the replay server (${svc.name})`, run: waitFor(svc.name, svc.port) }),
             new Step({ name: "yodel lint --replay", run: REPLAY }),
+            ...(tests ? [new Step({ name: "yodel test", run: TEST })] : []),
         ],
     });
 }
 export function actionsReview(forge, envs_) {
     const { dialect, names: envs, replay, waves, jobs: own } = envs_;
     const tc = toolchainOf(envs_);
-    const jobs = { lint: lintJob(forge, dialect, replay, tc) };
+    const jobs = { lint: lintJob(forge, dialect, replay, tc, envs_.tests === true) };
     for (const env of envs) {
+        const read = [env, ...requiredOf(waves, env)];
         jobs[`plan-${env}`] = new ActionsJob({
             ...runner(inContainer(forge, tc), tc),
             // The plan shows where each migration has run: the required environment's reader too.
-            env: secrets([...[env, ...requiredOf(waves, env)].flatMap((e) => readerVariables(e, dialect)), ...WEBHOOK_VARIABLES]),
+            env: secrets([...read.flatMap((e) => readerVariables(e, dialect, envs_.credentials?.[e])), ...WEBHOOK_VARIABLES]),
             steps: [
                 // The plan explains what moved since an approval from git's history of migrations/.
                 ...setupSteps(inContainer(forge, tc), tc),
+                // The cloud login (#132), when a reader here is cloud-minted.
+                ...actionsLogin(forge, loginsOf(envs_, planRoles(waves, env))),
+                new Step({ name: "This job cannot write", run: writeProbe(read) }),
                 new Step({ name: `yodel plan ${env} --comment`, run: `yodel plan ${env} --comment`, env: commentToken(forge) }),
                 ...reportSteps(env, `plan-${env}`, tc),
             ],
         });
     }
     Object.assign(jobs, ownJobs(own?.actions, jobs, "actions"));
-    const workflow = new ActionsWorkflow({
-        name: "yodel-pr",
-        on: { pull_request: { branches: [MAIN] } },
-        permissions: new Permissions({ contents: "read", "pull-requests": "write" }),
-        concurrency: new Concurrency({ group: "yodel-pr-${{ github.event.pull_request.number }}", "cancel-in-progress": true }),
-        jobs,
-    });
+    const clouds = cloudsOf(envs_, envs.flatMap((env) => planRoles(waves, env)));
     const header = [
         ...HEADER,
         "#",
         "# Pull requests: yodel lint and the replay check (into a throwaway server the",
         "# lint job starts), and the plan comment per environment with the",
-        "# environment's reader credentials. No job here holds a writer.",
+        "# environment's reader credentials. No job here holds a writer, and each plan",
+        "# job shows it first: yodel config check --write-probe tries a write and",
+        "# fails the job when the server lets it through.",
         ...(forge === "forgejo"
             ? ["# The comment is posted with the job's own token (Forgejo gives a same-repository", "# pull request one that can comment)."]
             : []),
+        ...identityHeader(forge, clouds),
     ];
+    const workflow = new ActionsWorkflow({
+        comment: asComment(header),
+        name: "yodel-pr",
+        on: { pull_request: { branches: [MAIN] } },
+        permissions: new Permissions({ contents: "read", "pull-requests": "write", ...(clouds.length > 0 ? { "id-token": "write" } : {}) }),
+        concurrency: new Concurrency({ group: "yodel-pr-${{ github.event.pull_request.number }}", "cancel-in-progress": true }),
+        jobs,
+    });
     return {
         path: `${forge === "github" ? ".github" : ".forgejo"}/workflows/yodel-pr.yml`,
-        content: withHeader(header, renderActions(forge, workflow)),
+        content: renderActions(forge, workflow),
     };
 }
 // ── GitLab CI ───────────────────────────────────────────────────────────────
 export const GITLAB_WATCH_FILE = ".gitlab/yodel-watch.gitlab-ci.yml";
 export const GITLAB_APPLY_FILE = ".gitlab/yodel-apply.gitlab-ci.yml";
+/** The stage of the scheduled resume job in GITLAB_APPLY_FILE, as chant names it. */
+const RESUME_STAGE = "resume";
+/** The stage of the merge request job that records the plans a pr-review wave's review approves (#48), as chant names it. */
+const PLANS_STAGE = "plans";
 /** The stage of each wave's job in GITLAB_APPLY_FILE, as chant names it. */
 const waveStages = (waves) => waves.map((w, i) => `wave-${String(i + 1)}-${w.env}`);
 export function gitlabPipeline(envs_) {
@@ -325,50 +429,42 @@ export function gitlabPipeline(envs_) {
         rules: mr(),
         ...(replay
             ? {
-                script: [CI_CHECK, LINT, waitFor(svc.name, svc.port), REPLAY],
+                script: [CI_CHECK, lintCommand("gitlab"), waitFor(svc.name, svc.port), REPLAY, ...(envs_.tests === true ? [TEST] : [])],
                 services: [new GitLabService({ name: svc.image, alias: svc.name, variables: svc.env })],
                 variables: { [`${variablePrefix(REPLAY_PROFILE, dialect)}_URL`]: svc.url(svc.name), ...svc.jobEnv },
             }
-            : { script: [CI_CHECK, LINT] }),
+            : { script: [CI_CHECK, lintCommand("gitlab")] }),
+        // The code quality report, kept when lint fails too: that is when it has something to show.
+        artifacts: new GitLabArtifacts({ when: "always", reports: { codequality: CODE_QUALITY_FILE } }),
     }));
     for (const env of envs) {
+        const clouds = cloudsOf(envs_, planRoles(waves, env));
+        const logins = loginsOf(envs_, planRoles(waves, env));
+        const login = gitlabLogin(logins);
         jobs.set(`plan-${env}`, new GitLabJob({
             extends: ".yodel",
             stage: "review",
             rules: mr(),
-            script: [`yodel plan ${env} --comment`],
+            ...(Object.keys(login.variables).length > 0 ? { variables: login.variables } : {}),
+            script: [...login.lines, writeProbe([env, ...requiredOf(waves, env)]), `yodel plan ${env} --comment`],
+            ...(clouds.length > 0 ? { id_tokens: idTokens(clouds, logins) } : {}),
             after_script: [reportCommand(env, tc)],
             artifacts: new GitLabArtifacts({ name: reportArtifact(`plan-${env}`), when: "always", paths: [`${REPORT_DIR}/`] }),
         }));
     }
     for (const [name, job] of Object.entries(ownJobs(own?.gitlab, Object.fromEntries(jobs), "gitlab")))
         jobs.set(name, job);
-    const serialize = (entities) => oneFile("gitlab", gitlabSerializer.serialize(entities));
-    // Exception (INTENTIUS/chant#3669): the gitlab serializer writes no
-    // top-level include or variables, and its stages are only the ones the
-    // declared jobs name, so not the watch file's ops. It writes those stages
-    // first; they are replaced by GITLAB_STAGES, and include and variables are
-    // written beside them.
-    const jobsYaml = serialize(jobs);
-    const end = jobsYaml.indexOf("\n\n");
-    const derivedStages = parseYAMLDocument(jobsYaml.slice(0, end + 1)).stages;
-    if (!jobsYaml.startsWith("stages:\n") || !Array.isArray(derivedStages) || derivedStages[0] !== "review")
-        throw new Error("gitlab: expected the jobs' YAML to start with their stages, review first");
-    const derived = jobsYaml.slice(0, end + 2);
-    // The stages this file's jobs use (review, then any the project's own jobs add), then the apply file's waves and the watch file's ops.
-    const stages = [...new Set([...derivedStages.map(String), ...waveStages(waves), "ops"])];
-    const topLevel = [
-        emitYAMLEntry("include", [{ local: GITLAB_APPLY_FILE }, { local: GITLAB_WATCH_FILE }]),
-        emitYAMLEntry("stages", stages),
-        emitYAMLEntry("variables", { GIT_DEPTH: "0" }),
-    ];
-    const yaml = `${serialize(new Map([["workflow", workflow]]))}\n${topLevel.join("\n\n")}\n\n${jobsYaml.slice(derived.length)}`;
-    const variables = envs.flatMap((env) => [
-        `#   ${readerVariables(env, dialect).join(", ")}: not protected (merge request`,
-        "#     pipelines run on unprotected branches), masked; no environment scope.",
-        `#   ${writerVariables(env, dialect).slice(1).join(", ")}: protected, masked,`,
-        `#     environment scope "${env}": only ${env}'s wave job declares that environment.`,
-    ]);
+    const variables = envs.flatMap((env) => {
+        const creds = envs_.credentials?.[env];
+        const writer = writerVariables(env, dialect, creds).slice(1);
+        return [
+            `#   ${readerVariables(env, dialect, creds).join(", ")}: not protected (merge request`,
+            "#     pipelines run on unprotected branches), masked; no environment scope.",
+            ...(writer.length > 0
+                ? [`#   ${writer.join(", ")}: protected, masked,`, `#     environment scope "${env}": only ${env}'s wave job declares that environment.`]
+                : []),
+        ];
+    });
     const header = [
         ...HEADER,
         "#",
@@ -380,14 +476,35 @@ export function gitlabPipeline(envs_) {
         "# protected or scoped to an environment, so the split between reader and",
         "# writer is in the variables' settings (Settings > CI/CD > Variables):",
         ...variables,
-        "#   GITLAB_TOKEN: a project access token with the api scope (Reporter), for",
-        "#     the plan comment and the drift watch's tracking issue; CI_JOB_TOKEN",
-        "#     cannot write merge request notes or issues.",
+        ...(envs_.resume
+            ? [
+                "#   GITLAB_TOKEN: a project access token with the api scope (Developer), for",
+                "#     the plan comment, the drift watch's tracking issue and the resume job's",
+                "#     retry of a wave whose approval arrived; CI_JOB_TOKEN cannot write merge",
+                "#     request notes or issues, or retry a job.",
+            ]
+            : [
+                "#   GITLAB_TOKEN: a project access token with the api scope (Reporter), for",
+                "#     the plan comment and the drift watch's tracking issue; CI_JOB_TOKEN",
+                "#     cannot write merge request notes or issues.",
+            ]),
         "# The jobs that hold no writer read with the reader: chant.config.ts picks an",
         "# environment's writer only under YODEL_CREDENTIALS=writer:<env>, which only",
         "# that environment's wave job sets.",
+        ...identityHeader("gitlab", cloudsOf(envs_, envs.flatMap((env) => [...planRoles(waves, env), ...waveRoles(waves, env), [env, "reader"]]))),
     ];
-    return { path: ".gitlab-ci.yml", content: withHeader(header, yaml) };
+    // The stages this file's jobs use (review, then any the project's own jobs add), then the apply file's waves and the watch file's ops.
+    // A pr-review wave (#48) adds the merge request job that records the plans, in chant's stage "plans".
+    const jobStages = [...jobs.values()].map((job) => job.props?.stage).filter((stage) => typeof stage === "string");
+    const plans = waves.some((w) => w.approval === "pr-review") ? [PLANS_STAGE] : [];
+    const pipeline = new GitLabPipeline({
+        comment: asComment(header),
+        include: [{ local: GITLAB_APPLY_FILE }, { local: GITLAB_WATCH_FILE }],
+        stages: [...new Set([...jobStages, ...plans, ...waveStages(waves), ...(envs_.resume ? [RESUME_STAGE] : []), "ops"])],
+        variables: { GIT_DEPTH: "0" },
+    });
+    const entities = new Map([["pipeline", pipeline], ["workflow", workflow], ...jobs]);
+    return { path: ".gitlab-ci.yml", content: oneFile("gitlab", gitlabSerializer.serialize(entities)) };
 }
 const WAVE_GATES = ["always", "on-destructive", "never"];
 /** The environment `env`'s wave requires, as a list. */
@@ -402,7 +519,7 @@ export const APPLY_PIPELINE = "yodel-apply";
  * The waves spec. What the file holds is the same for every forge; each
  * forge's jobs get their own variables on top (`variables`).
  */
-export function wavesSpec(waves, variables) {
+export function wavesSpec(waves, variables, resume) {
     const first = waves[0];
     if (!first)
         throw new Error("no waves to render");
@@ -417,8 +534,10 @@ export function wavesSpec(waves, variables) {
             runs: (w.targets ?? [w.env]).map((target) => ({ target, op: `migrate-${w.env}` })),
             gate: w.gate,
             ...(w.shares !== undefined && w.shares > 1 ? { shares: w.shares } : {}),
+            ...(w.approval !== undefined && w.approval !== "ledger" ? { approval: w.approval } : {}),
             ...(variables ? { environment: { name: w.env }, variables: variables(w.env) } : {}),
         })),
+        ...(resume ? { resume } : {}),
     };
 }
 /** The waves spec file and the apply pipeline on each forge. */
@@ -429,13 +548,19 @@ export async function applyPipelines(dir, envs) {
     const out = [{ path: WAVES_SPEC, content: `${JSON.stringify(wavesSpec(waves), null, 2)}\n` }];
     // A GitLab job already has the project's variables, a writer's only under its environment.
     const variables = (forge) => (env) => {
-        const required = waves.find((w) => w.env === env)?.requires;
+        const wave = waves.find((w) => w.env === env);
+        const required = wave?.requires;
         return {
             YODEL_CREDENTIALS: `writer:${env}`,
             ...APPLY_LOCK,
             ...(forge === "gitlab"
                 ? {}
-                : { ...secrets([...writerVariables(env, dialect), ...WEBHOOK_VARIABLES]), ...(required ? secrets(readerVariables(required, dialect)) : {}) }),
+                : {
+                    ...secrets([...writerVariables(env, dialect, envs.credentials?.[env]), ...WEBHOOK_VARIABLES]),
+                    ...(required ? secrets(readerVariables(required, dialect, envs.credentials?.[required])) : {}),
+                    // A pr-review wave (#48) reads the merged pull request's reviews with the job's token.
+                    ...(wave?.approval === "pr-review" ? { GITHUB_TOKEN: "${{ github.token }}" } : {}),
+                }),
         };
     };
     const header = [
@@ -446,13 +571,35 @@ export async function applyPipelines(dir, envs) {
         `# wave's gate policy is read from ${WAVES_SPEC} as the commit before the push`,
         "# has it (yodel.config.ts waves, rendered), and a wave that needs an approval",
         "# exits 3 with the chant approve command, so the waves after it do not run.",
-        "# Approve, push chant/lifecycle, and run the failed job again. These are the",
-        "# only jobs that hold a writer's credentials, one environment's each, with",
+        "# yodel approve <env> records the approval and starts the waiting job again",
+        "# (or approve, push chant/lifecycle, and run the failed job again). These are",
+        "# the only jobs that hold a writer's credentials, one environment's each, with",
         "# the reader of the environment before (waves[].requires): yodel apply refuses",
         "# a migration that environment's history does not record as applied.",
     ];
+    const resumeHeader = (forge) => [
+        ...HEADER,
+        "#",
+        `# On its schedule: chant run resume --op ${APPLY_PIPELINE} starts again each apply wave`,
+        "# that waits at its gate and whose approval has arrived since. It approves",
+        "# nothing; a wave whose approval does not count waits again.",
+        ...(forge === "github"
+            ? ["# It re-runs the run's failed jobs with the job's token (actions: write)."]
+            : ["# Forgejo has no re-run: it dispatches yodel-apply.yml again on main, with the", "# CHANT_FORGE_TOKEN secret, a token with the write:repository scope."]),
+    ];
+    const waveClouds = cloudsOf(envs, waves.flatMap((w) => waveRoles(waves, w.env)));
+    const plansHeader = [
+        ...HEADER,
+        "#",
+        "# A pull request into main, when a wave's approval is pr-review (yodel.config.ts",
+        "# waves[].approval): chant run wave --record-plans plans every wave at the pull",
+        "# request's head, as it will be after the merge, and records the digests on",
+        "# chant/lifecycle. After the merge, an approving review of that head by a writer",
+        "# other than its author approves the digest it recorded, and only that one. It",
+        "# holds no writer's credentials: it plans with each environment's reader.",
+    ];
     for (const forge of FORGES) {
-        const result = await generateOpWavesPipeline(wavesSpec(waves, variables(forge)), forge, {
+        const result = await generateOpWavesPipeline(wavesSpec(waves, variables(forge), envs.resume), forge, {
             specFile: WAVES_SPEC,
             image: tc.image,
             beforeScript: [...installLines(tc, forge), FETCH_APPROVALS],
@@ -462,7 +609,15 @@ export async function applyPipelines(dir, envs) {
             throw new Error(`${forge}: ${result.error ?? "generateOpWavesPipeline rendered nothing"}`);
         for (const file of result.files) {
             const at = forge === "gitlab" ? GITLAB_APPLY_FILE : `${forge === "github" ? ".github" : ".forgejo"}/workflows/${file.name}`;
-            out.push({ path: at, content: withHeader(header, withWaveReports(forge, file.yaml.endsWith("\n") ? file.yaml : `${file.yaml}\n`, waves, tc)) });
+            const yaml = file.yaml.endsWith("\n") ? file.yaml : `${file.yaml}\n`;
+            // The resume workflow (GitHub, Forgejo) has no wave job to report on.
+            if (forge !== "gitlab" && file.name === `${APPLY_PIPELINE}-resume.yml`)
+                out.push({ path: at, content: withHeader(resumeHeader(forge), yaml) });
+            // The pull request workflow that records the plans a review approves (#48).
+            else if (forge !== "gitlab" && file.name === `${APPLY_PIPELINE}-plans.yml`)
+                out.push({ path: at, content: withHeader(plansHeader, withPlansReaders(forge, yaml, waves, dialect, envs)) });
+            else
+                out.push({ path: at, content: withHeader([...header, ...identityHeader(forge, waveClouds)], withWaveReports(forge, yaml, waves, tc, envs)) });
         }
     }
     return out;
@@ -475,7 +630,7 @@ export async function applyPipelines(dir, envs) {
  * back chant's text unchanged before anything is added, so a change in
  * chant's emitter fails here instead of rendering something else.
  */
-function withWaveReports(forge, yaml, waves, tc) {
+function withWaveReports(forge, yaml, waves, tc, envs = {}) {
     // A wide wave's jobs are wave-<k>-<env>-decide and -share-<i>.
     const envOf = (job) => waves.find((w, i) => new RegExp(`^wave-${String(i + 1)}-${w.env.replace(/[^A-Za-z0-9]/g, "\\$&")}(-decide|-share-\\d+)?$`).test(job))?.env;
     const body = yaml.search(/^[^#\n]/m);
@@ -485,11 +640,38 @@ function withWaveReports(forge, yaml, waves, tc) {
         const emit = (d) => `${header}${Object.entries(d).map(([k, v]) => emitYAMLEntry(k, v)).join("\n\n")}\n`;
         if (emit(doc) !== yaml)
             throw new Error("gitlab: the apply waves do not emit back to chant's text");
+        // The merge request job that records the plans a review approves (#48): the waves as after the merge.
+        const record = doc[`${APPLY_PIPELINE}-record-plans`];
+        if (record) {
+            record.variables = { ...(record.variables ?? {}), [RECORD_PLANS_ENV]: "1" };
+            // It holds readers only, and shows it first, as every merge request job does (#50, #130).
+            const waveEnvs = [...new Set(waves.map((w) => w.env))];
+            const at = record.script?.findIndex((l) => l.includes("--record-plans")) ?? -1;
+            if (!record.script || at < 0)
+                throw new Error("gitlab: the record-plans job has no chant run wave --record-plans line");
+            record.script.splice(at, 0, writeProbe(waveEnvs));
+            const readerRoles = waveEnvs.map((e) => [e, "reader"]);
+            const readers = cloudsOf(envs, readerRoles);
+            const logins = loginsOf(envs, readerRoles);
+            if (readers.length > 0)
+                record.id_tokens = idTokens(readers, logins);
+            const login = gitlabLogin(logins);
+            insertLines(record.script, login.lines, (l) => l === writeProbe(waveEnvs), "gitlab: the record-plans job");
+            if (Object.keys(login.variables).length > 0)
+                record.variables = { ...record.variables, ...login.variables };
+        }
         for (const [name, job] of Object.entries(doc)) {
             const env = envOf(name);
             if (!env || typeof job !== "object" || job === null)
                 continue;
-            Object.assign(job, { after_script: [reportCommand(env, tc)], artifacts: { name: reportArtifact(name), when: "always", paths: [`${REPORT_DIR}/`] } });
+            const clouds = cloudsOf(envs, waveRoles(waves, env));
+            const logins = loginsOf(envs, waveRoles(waves, env));
+            const login = gitlabLogin(logins);
+            const w = job;
+            insertLines(w.script, login.lines, (l) => l.startsWith("chant run "), `gitlab: ${name}`);
+            if (Object.keys(login.variables).length > 0)
+                w.variables = { ...w.variables, ...login.variables };
+            Object.assign(job, { after_script: [reportCommand(env, tc)], artifacts: { name: reportArtifact(name), when: "always", paths: [`${REPORT_DIR}/`] }, ...(clouds.length > 0 ? { id_tokens: idTokens(clouds, logins) } : {}) });
         }
         return emit(doc);
     }
@@ -497,18 +679,52 @@ function withWaveReports(forge, yaml, waves, tc) {
     if (at < 0)
         throw new Error(`${forge}: the apply waves have no jobs`);
     const jobs = doc.jobs;
-    const emit = () => `${yaml.slice(0, at + 1)}${emitYAMLEntry("jobs", jobs)}\n`;
-    if (emit() !== yaml)
+    const top = yaml.slice(0, at + 1);
+    const emitJobs = () => `${emitYAMLEntry("jobs", jobs)}\n`;
+    if (`${top}${emitJobs()}` !== yaml)
         throw new Error(`${forge}: the apply waves do not emit back to chant's text`);
     for (const [name, job] of Object.entries(jobs)) {
         const env = envOf(name);
         if (!env)
             continue;
+        // The cloud login (#132) before the wave's chant run, when a role it holds is cloud-minted.
+        insertSteps(job.steps, rawLogin(forge, loginsOf(envs, waveRoles(waves, env))), runsChant, `${forge}: ${name}`);
         job.steps.push({ name: `yodel report ${env}`, if: "always()", run: reportCommand(env, tc) }, 
         // chant's forgejo output is already in Forgejo's dialect, so the action is named as the forgejo lexicon names it.
         { name: "Keep the report", if: "always()", uses: forge === "forgejo" ? `https://code.forgejo.org/${UPLOAD_ARTIFACT}` : UPLOAD_ARTIFACT, with: { name: reportArtifact(name), path: REPORT_DIR, "if-no-files-found": "ignore" } });
     }
-    return emit();
+    return `${withIdToken(forge, top, cloudsOf(envs, waves.flatMap((w) => waveRoles(waves, w.env))))}${emitJobs()}`;
+}
+/**
+ * The plans workflow (GitHub, Forgejo) for a pr-review wave (#48): chant's,
+ * with each environment's reader (the waves are planned on every one, and a
+ * wave reads the history of the one it requires) and {@link RECORD_PLANS_ENV}
+ * on its job. The output is parsed and emitted again, checked first to give
+ * back chant's text unchanged.
+ */
+function withPlansReaders(forge, yaml, waves, dialect, creds = {}) {
+    const at = yaml.indexOf("\njobs:\n");
+    if (at < 0)
+        throw new Error(`${forge}: the plans workflow has no jobs`);
+    const doc = parseYAMLDocument(yaml);
+    const top = yaml.slice(0, at + 1);
+    const emitJobs = () => `${emitYAMLEntry("jobs", doc.jobs)}\n`;
+    if (`${top}${emitJobs()}` !== yaml)
+        throw new Error(`${forge}: the plans workflow does not emit back to chant's text`);
+    const job = doc.jobs["record-plans"];
+    if (!job)
+        throw new Error(`${forge}: the plans workflow has no record-plans job`);
+    const envs = [...new Set(waves.map((w) => w.env))];
+    const steps = job.steps;
+    // It holds readers only, and shows it before it plans, as every pull request job does (#50, #130).
+    const recordAt = steps.findIndex((st) => typeof st.run === "string" && st.run.includes("--record-plans"));
+    if (recordAt < 0)
+        throw new Error(`${forge}: the record-plans job has no chant run wave --record-plans step`);
+    steps.splice(recordAt, 0, ...(forge === "gitlab" ? [] : rawLogin(forge, loginsOf(creds, envs.map((e) => [e, "reader"])))), { name: "This job cannot write", run: writeProbe(envs) });
+    delete job.steps;
+    Object.assign(job, { env: { [RECORD_PLANS_ENV]: "1", ...secrets(envs.flatMap((e) => readerVariables(e, dialect, creds.credentials?.[e]))) }, steps });
+    // A reader whose password is a cloud token (#50) is minted from the job's identity.
+    return `${withIdToken(forge, top, cloudsOf(creds, envs.map((e) => [e, "reader"])))}${emitJobs()}`;
 }
 /** yodel.config.ts `waves`, checked against the environments; one wave per environment, gate `always`, without it. */
 export async function readWaves(dir, envs) {
@@ -527,28 +743,28 @@ export async function readWaves(dir, envs) {
         const requires = w.requires === false ? undefined : w.requires === undefined ? (i > 0 ? String(all[i - 1]?.env) : undefined) : typeof w.requires === "string" ? w.requires : JSON.stringify(w.requires);
         if (requires !== undefined && !envs.includes(requires))
             throw new Error(`yodel.config.ts: waves[${String(i)}].requires ${requires} is not an environment (${envs.join(", ")})`);
-        return { env, gate, ...(requires ? { requires } : {}), ...(typeof w.shares === "number" && w.shares > 1 ? { shares: w.shares } : {}) };
+        const approval = w.approval;
+        if (approval !== undefined && !APPROVAL_MODES.includes(approval))
+            throw new Error(`yodel.config.ts: waves[${String(i)}].approval ${String(w.approval)} is not ${APPROVAL_MODES.join(", ")}`);
+        return { env, gate, ...(requires ? { requires } : {}), ...(typeof w.shares === "number" && w.shares > 1 ? { shares: w.shares } : {}), ...(approval && approval !== "ledger" ? { approval } : {}) };
     });
 }
 /**
- * Each wave of an environment with a tenant set (#56), with a run per
- * tenant. A set given by a query is read from the server now, with the
- * environment's profile: run yodel ci again when the tenants change.
+ * Each wave of an environment with a tenant set (#56), with its runs: a
+ * run per tenant of a list or a file, or for a set given by a query,
+ * `shares` slots (one without) that read the tenants when the wave runs.
+ * The query is not run here, so the pipeline stays the same as tenants come
+ * and go; a list or a file is in the repository, and changing it is
+ * rendering again.
  */
 export async function withTenants(dir, waves) {
     const { loadProject } = await import("../project.js");
-    const { listTenants, tenantTarget } = await import("../tenants/index.js");
+    const { waveTargets } = await import("../tenants/wave.js");
     const project = await loadProject(dir);
     const out = [];
     for (const w of waves) {
-        const tenants = await listTenants(project, w.env);
-        if (tenants === undefined) {
-            out.push(w);
-            continue;
-        }
-        if (tenants.length === 0)
-            throw new Error(`${w.env}'s tenant set lists no tenant, so its wave would apply nothing`);
-        out.push({ ...w, targets: tenants.map((t) => tenantTarget(w.env, t)) });
+        const targets = await waveTargets(project, w.env, w.shares);
+        out.push(targets === undefined ? w : { ...w, targets });
     }
     return out;
 }
@@ -558,16 +774,72 @@ export async function withTenants(dir, waves) {
  * writer's only under its environment, which the watch does not declare), and
  * `NAME: $NAME` there would refer to itself.
  */
-export function watchSpec(env, dialect, forge) {
+export function watchSpec(env, dialect, forge, creds) {
     if (forge === "gitlab")
         return { name: `watch-${env}` };
     // The job's token, for the tracking issue: GitHub grants it issues: write here, Forgejo's can write already.
     return {
         name: `watch-${env}`,
-        variables: { ...secrets([...readerVariables(env, dialect), ...WEBHOOK_VARIABLES]), GITHUB_TOKEN: "${{ github.token }}" },
-        ...(forge === "github" ? { permissions: { issues: "write" } } : {}),
+        variables: { ...secrets([...readerVariables(env, dialect, creds), ...WEBHOOK_VARIABLES]), GITHUB_TOKEN: "${{ github.token }}" },
+        ...(forge === "github" ? { permissions: { issues: "write", ...(creds?.reader.cloud ? { "id-token": "write" } : {}) } } : {}),
     };
 }
+/** A GitHub workflow's top-level `permissions:` with `id-token: write` added, when a job holds a cloud-minted role. */
+function withIdToken(forge, top, clouds) {
+    if (forge !== "github" || clouds.length === 0)
+        return top;
+    const added = top.replace(/^permissions:\n((?: {2}\S.*\n)*)/m, (_m, scopes) => `permissions:\n${scopes}  id-token: write\n`);
+    if (added === top)
+        throw new Error("github: the apply waves have no top-level permissions to add id-token: write to");
+    return added;
+}
+/**
+ * A GitHub or Forgejo watch file with the cloud login (#132) before the
+ * job's chant run, when its reader is cloud-minted and logs in. Parsed and
+ * emitted again, checked against chant's text first.
+ */
+function withWatchLogin(forge, yaml, env, envs) {
+    const login = rawLogin(forge, loginsOf(envs, [[env, "reader"]]));
+    if (login.length === 0)
+        return yaml;
+    const at = yaml.indexOf("\njobs:\n");
+    if (at < 0)
+        throw new Error(`${forge}: the watch for ${env} has no jobs`);
+    const doc = parseYAMLDocument(yaml);
+    const top = yaml.slice(0, at + 1);
+    const emitJobs = () => `${emitYAMLEntry("jobs", doc.jobs)}\n`;
+    if (`${top}${emitJobs()}` !== yaml)
+        throw new Error(`${forge}: the watch for ${env} does not emit back to chant's text`);
+    const job = doc.jobs[`watch-${env}`];
+    if (!job)
+        throw new Error(`${forge}: the watch for ${env} has no watch-${env} job`);
+    insertSteps(job.steps, login, runsChant, `${forge}: watch-${env}`);
+    return `${top}${emitJobs()}`;
+}
+/** The GitLab watch file with `id_tokens` (and the cloud login, #132) on each watch job whose reader is cloud-minted. Parsed and emitted again, checked against chant's text first. */
+function withWatchIdTokens(yaml, envs) {
+    const clouds = (env) => cloudsOf(envs, [[env, "reader"]]);
+    if (!envs.names.some((env) => clouds(env).length > 0))
+        return yaml;
+    const body = yaml.search(/^[^#\n]/m);
+    const header = yaml.slice(0, body);
+    const doc = parseYAMLDocument(yaml);
+    const emit = (d) => `${header}${Object.entries(d).map(([k, v]) => emitYAMLEntry(k, v)).join("\n\n")}\n`;
+    if (emit(doc) !== yaml)
+        throw new Error("gitlab: the watch file does not emit back to chant's text");
+    for (const env of envs.names) {
+        const job = doc[`watch-${env}`];
+        if (clouds(env).length === 0 || job === undefined)
+            continue;
+        const logins = loginsOf(envs, [[env, "reader"]]);
+        const login = gitlabLogin(logins);
+        insertLines(job.script, login.lines, (l) => l.startsWith("chant run "), `gitlab: watch-${env}`);
+        if (Object.keys(login.variables).length > 0)
+            job.variables = { ...job.variables, ...login.variables };
+        Object.assign(job, { id_tokens: idTokens(clouds(env), logins) });
+    }
+    return emit(doc);
+}
 export async function watchPipelines(dir, envs_) {
     const { dialect, names: envs } = envs_;
     const tc = toolchainOf(envs_);
@@ -584,19 +856,24 @@ export async function watchPipelines(dir, envs_) {
             throw new Error(`${forge}: ${result.error ?? "generateOpsPipeline rendered nothing"}`);
         for (const file of result.files) {
             const at = forge === "gitlab" ? GITLAB_WATCH_FILE : `${forge === "github" ? ".github" : ".forgejo"}/workflows/${file.name}`;
-            out.push({ path: at, content: `${HEADER.join("\n")}\n${file.yaml.endsWith("\n") ? file.yaml : `${file.yaml}\n`}` });
+            const yaml = file.yaml.endsWith("\n") ? file.yaml : `${file.yaml}\n`;
+            // A GitHub or Forgejo file is one environment's watch: its name is watch-<env>.yml.
+            const env = file.name.replace(/^watch-|\.yml$/g, "");
+            out.push({ path: at, content: `${HEADER.join("\n")}\n${forge === "gitlab" ? withWatchIdTokens(yaml, envs_) : withWatchLogin(forge, yaml, env, envs_)}` });
         }
     };
     // `chant run` exits 0 when a watch finds drift; the last line, yodel drift, fails the job then.
     for (const forge of ["github", "forgejo"]) {
         for (const env of envs)
-            await emit(forge, [watchSpec(env, dialect, forge)], [watchDrift(env)]);
+            await emit(forge, [watchSpec(env, dialect, forge, envs_.credentials?.[env])], [watchDrift(env)]);
     }
     // GitLab: one file for every watch, so the last line takes the environment from the job's own name.
     await emit("gitlab", envs.map((env) => watchSpec(env, dialect, "gitlab")), [watchDrift('"${CI_JOB_NAME#watch-}"')]);
     return out;
 }
 // ── The project ─────────────────────────────────────────────────────────────
+/** Whether the project has a test file for yodel test (tests/*.test.ts). */
+const hasTests = (dir) => testFiles(dir).length > 0;
 /** The dialect and the environments chant.config.ts declares, in order. */
 export async function environments(dir) {
     const { loadChantConfig } = await import("@intentius/chant/config");
@@ -617,16 +894,36 @@ export async function environments(dir) {
         }
     }
     const ci = (await readConfig(dir))?.ci;
+    const credentials = credentialsIn(sql?.profiles ?? {}, envs);
     return {
         dialect,
         names: envs,
+        ...(Object.keys(credentials).length > 0 ? { credentials } : {}),
         replay,
+        ...(hasTests(dir) ? { tests: true } : {}),
         waves: await withTenants(dir, await readWaves(dir, envs)),
         forges: ci?.forges ?? FORGES,
         ...(ci?.jobs ? { jobs: await loadProjectJobs(dir, ci.jobs) } : {}),
         ...(ci?.image ? { image: ci.image } : {}),
+        ...(ci?.resume ? { resume: { schedule: ci.resume.schedule } } : {}),
+        ...(ci?.login ? { login: ci.login } : {}),
     };
 }
+/** The roles of each environment whose profile is made with credentials(). */
+export function credentialsIn(profiles, envs) {
+    const out = {};
+    for (const env of envs) {
+        const c = credentialsOf(profiles[env]);
+        if (!c)
+            continue;
+        const needs = (role) => {
+            const cloud = cloudToken(c, role);
+            return { variables: roleVariables(c, role), ...(cloud ? { cloud } : {}) };
+        };
+        out[env] = { reader: needs("reader"), writer: needs("writer") };
+    }
+    return out;
+}
 /** yodel.config.ts, checked; undefined when the project has none. */
 async function readConfig(dir) {
     return (await loadYodelConfig(dir))?.config;