@intentius/sql-yodeler 0.2.0 → 0.3.0

package/dist/ci/render.js

@@ -0,0 +1,688 @@
+/**
+ * `yodel ci` (#65): a project's CI for GitHub Actions, GitLab CI and Forgejo
+ * Actions, rendered by the installed package, so a fix to the pipelines
+ * reaches a project when it upgrades yodel and renders again. Until #65 the
+ * templates carried this as scripts/ci.ts.
+ *
+ *   yodel ci            write the files
+ *   yodel ci --check    exit 1 when a file differs from what this renders
+ *   yodel ci --replay   the lint job's replay check on this machine (./replay.ts)
+ *
+ * yodel.config.ts `ci` picks the forges (default all three) and names the
+ * module that declares the project's own jobs, which are merged after
+ * yodel's into the pull request pipeline and kept on every render
+ * ({@link ProjectJobs}).
+ *
+ * Environments are the keys of `sql.profiles` in chant.config.ts, in order,
+ * but `replay`, which is the lint job's throwaway server.
+ * Each one needs ops/migrate-<env>.op.ts and ops/watch-<env>.op.ts.
+ * The apply pipeline's waves are yodel.config.ts `waves`, in order; without
+ * it, one wave per environment in profile order, each with gate `always`.
+ *
+ * Three pipelines per forge, each declared with chant: yodel-pr with the
+ * github lexicon's Workflow, Job and Step (Forgejo renders the same
+ * declaration through the forgejo lexicon's dialect) and the gitlab
+ * lexicon's Workflow and Job; yodel-apply with chant's
+ * generateOpWavesPipeline, from the waves spec this writes
+ * (yodel-waves.json); the watch with generateOpsPipeline.
+ *
+ * - yodel-pr: on a pull (merge) request, `yodel ci --check` (these files are
+ *   what yodel ci renders), `yodel lint`, and the replay check into a
+ *   throwaway server the job starts (the `replay` profile), then for each
+ *   environment `yodel plan <env> --comment`, which posts the pending
+ *   migrations and the digest to approve. One job per environment, holding
+ *   that environment's reader credentials and nothing else.
+ * - yodel-apply: on a push to main, one job per wave, each needing the one
+ *   before, running `chant run wave`: it plans the environment (`yodel apply
+ *   <env> --wave-plan`), reads the wave's gate policy from yodel-waves.json
+ *   as the commit before the push has it, waits for an approval when that
+ *   policy asks for one (exit 3, and the waves after it do not run), and
+ *   applies (`yodel apply <env> --wave-apply`). The only jobs that hold a
+ *   writer's credentials, one environment's each, with
+ *   YODEL_CREDENTIALS=writer. Two merges in quick succession do not fail the
+ *   second apply: it waits for the first's lock (YODEL_LOCK_WAIT), and an
+ *   apply whose commit is no longer main's tip stands down
+ *   (YODEL_STAND_DOWN), since the newer commit's waves apply the same
+ *   environments.
+ * - watch-<env>: the environment's WatchOp on its own schedule, rendered by
+ *   chant's generateOpsPipeline, with the reader's credentials. After the
+ *   Op, `yodel drift <env> --issue` compares the server with the schema the
+ *   newest applied migration records (so a migration waiting at its gate is
+ *   not drift), keeps one tracking issue for the environment (opened on
+ *   drift, updated while it changes, closed when it is gone), and fails the
+ *   job on drift. The issue is written with the job's token on GitHub
+ *   (issues: write) and Forgejo, and with GITLAB_TOKEN on GitLab.
+ *
+ * The scheduled watch never pushes. Its first phase (chant lifecycle
+ * snapshot) commits a snapshot to chant/lifecycle and tries to push it; the
+ * drift it reports comes from `chant lifecycle diff --live`, declared against
+ * live, which needs no snapshot on the remote. So the job sets a push URL
+ * that cannot be pushed to: the push fails, chant carries on, and the job
+ * works the same with a read-only token (GitHub `contents: read`, GitLab's
+ * CI_JOB_TOKEN) as with Forgejo's token, which can write. A push that could
+ * land would race the approvals people push to chant/lifecycle.
+ *
+ * Every job installs @intentius/sql-yodeler from npm with `npm ci`, which
+ * needs no token, in IMAGE. With yodel.config.ts `ci.image` (#66), the CI
+ * image ghcr.io/intentius/sql-yodeler pinned by its digest, every job runs
+ * in that image instead, which carries node, yodel, chant and the lexicons
+ * on PATH, and no job runs `npm ci` ({@link Toolchain}).
+ */
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { loadYodelConfig } from "../config/load.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 { 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. */
+export const IMAGE = "node:22-bookworm";
+/** The CI image (#66): yodel, chant and the sql lexicon, published for each release. */
+export const YODEL_IMAGE = "ghcr.io/intentius/sql-yodeler";
+export const toolchainOf = (envs) => (envs.image ? { image: envs.image, yodelImage: true } : { image: IMAGE, yodelImage: false });
+/** The steps that install the project's packages and put their bins on PATH, as each forge writes them. */
+const installLines = (tc, forge) => tc.yodelImage ? [] : ["npm ci", forge === "gitlab" ? 'export PATH="$PWD/node_modules/.bin:$PATH"' : 'echo "$PWD/node_modules/.bin" >> "$GITHUB_PATH"'];
+export const MAIN = "main";
+/** The forgejo lexicon rewrites it to https://code.forgejo.org/actions/checkout@v7 on Forgejo. */
+const CHECKOUT = "actions/checkout@v7";
+const SETUP_NODE = "actions/setup-node@v7";
+/** DEV for dev: the prefix of an environment's variables. */
+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) => {
+    const p = variablePrefix(env, dialect);
+    return [`${p}_URL`, `${p}_READER_USER`, `${p}_READER_PASSWORD`];
+};
+/** The variables the apply job for `env` holds: the URL and the writer. */
+export const writerVariables = (env, dialect) => {
+    const p = variablePrefix(env, dialect);
+    return [`${p}_URL`, `${p}_WRITER_USER`, `${p}_WRITER_PASSWORD`];
+};
+const secret = (name) => `\${{ secrets.${name} }}`;
+const secrets = (names) => Object.fromEntries(names.map((n) => [n, secret(n)]));
+/**
+ * The approvals: `chant approve` records them on the chant/lifecycle branch,
+ * and approvers push it. A CI checkout fetches one ref, so fetch this one too.
+ * The remote-tracking ref is what chant's push lease reads.
+ */
+export const FETCH_APPROVALS = "git fetch --no-tags origin '+refs/heads/chant/lifecycle:refs/remotes/origin/chant/lifecycle' && git branch -f chant/lifecycle origin/chant/lifecycle || echo 'no chant/lifecycle branch yet, so nothing is approved'";
+/** The apply jobs' lock settings: wait for another apply's lock, and stand down for a newer commit on main. */
+export const APPLY_LOCK = { YODEL_LOCK_WAIT: "10m", YODEL_STAND_DOWN: "1" };
+/** The watch reads; it never pushes. See the comment at the top. */
+export const NO_PUSH = "git remote set-url --push origin no-push://the-drift-watch-only-reads";
+/** After the watch's `chant run`: drift against the history, the environment's tracking issue, and exit 2 on drift. */
+export const watchDrift = (env) => `yodel drift ${env} --issue`;
+/**
+ * The replay check: `yodel lint --replay replay --reset` replays every
+ * migration, in order, into a fresh database on the `replay` profile's
+ * server and fails when one does not give the schema it recorded. That
+ * server is a throwaway container the lint job starts as a service, the
+ * image chant's emulator runs, which the job (in IMAGE, on every forge)
+ * reaches by the service's name; never a server whose data matters, since
+ * --reset drops what the history names there first.
+ */
+export const REPLAY_PROFILE = "replay";
+export const REPLAY_SERVICE = {
+    clickhouse: {
+        name: "replay-clickhouse",
+        image: "clickhouse/clickhouse-server:26.8.15.10",
+        port: 8123,
+        // The default user, with no password, from outside the container.
+        env: { CLICKHOUSE_SKIP_USER_SETUP: "1" },
+        health: "clickhouse-client --query 'SELECT 1'",
+        url: (host, port = 8123) => `http://${host}:${String(port)}`,
+        jobEnv: {},
+    },
+    postgres: {
+        name: "replay-postgres",
+        image: "postgres:18.6",
+        port: 5432,
+        env: { POSTGRES_PASSWORD: "replay" },
+        // Over TCP: during its first start the image runs a server on the socket only, then restarts.
+        health: "pg_isready -h 127.0.0.1 -U postgres",
+        url: (host, port = 5432) => `postgres://${host}:${String(port)}/postgres`,
+        jobEnv: { REPLAY_POSTGRES_USER: "postgres", REPLAY_POSTGRES_PASSWORD: "replay" },
+    },
+};
+/** 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";
+export const REPLAY = `yodel lint --replay ${REPLAY_PROFILE} --reset`;
+/** Fails a pull request whose pipelines differ from what yodel ci renders. */
+export const CI_CHECK = "yodel ci --check";
+/**
+ * Webhook events (yodel.config.ts `notify`): the variables the apply, plan
+ * and watch jobs pass from the forge's secrets. yodel sends nothing while
+ * they are unset (empty), so an unconfigured repository needs neither.
+ * GitLab jobs have the project's variables already.
+ */
+export const WEBHOOK_VARIABLES = ["YODEL_WEBHOOK_URL", "YODEL_WEBHOOK_KEY"];
+/** Where the plan and apply jobs write `yodel report`, kept as the job's artifact. */
+export const REPORT_DIR = "yodel-report";
+/**
+ * `yodel report <env>` as JSON and as the HTML run view, into REPORT_DIR.
+ * It runs whatever the job's outcome, and a gap it reports (exit 4) does not
+ * fail the job: the report is for reading. `yodel` is the project's, named
+ * by path, since GitLab's after_script does not keep before_script's PATH;
+ * in the yodel image, the image's, which is on PATH.
+ */
+export const reportCommand = (env, tc = { image: IMAGE, yodelImage: false }) => {
+    const yodel = tc.yodelImage ? "yodel" : "./node_modules/.bin/yodel";
+    return `mkdir -p ${REPORT_DIR}; ${yodel} report ${env} --json > ${REPORT_DIR}/${env}.json || true; ${yodel} report ${env} --html ${REPORT_DIR}/${env}.html || true`;
+};
+/** The artifact a job keeps its report in. */
+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).
+ */
+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}`;
+/** 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")
+        return out;
+    const extra = [...Object.keys(out.files ?? {}), ...(out.warnings ?? [])];
+    if (extra.length > 0)
+        throw new Error(`${forge}: expected one file and no warnings, got ${extra.join("; ")}`);
+    return out.primary;
+}
+function renderActions(forge, workflow) {
+    const serializer = forge === "github" ? githubSerializer : forgejoSerializer;
+    return oneFile(forge, serializer.serialize(new Map([["workflow", workflow]])));
+}
+/** The report steps of a job: `yodel report` into REPORT_DIR and the artifact, whatever the job's outcome. */
+function reportSteps(env, job, tc) {
+    return [
+        new Step({ name: `yodel report ${env}`, if: "always()", run: reportCommand(env, tc) }),
+        new Step({ name: "Keep the report", if: "always()", uses: UPLOAD_ARTIFACT, with: { name: reportArtifact(job), path: REPORT_DIR, "if-no-files-found": "ignore" } }),
+    ];
+}
+/** `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" } })];
+    if (!inContainer)
+        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;
+}
+/** Forgejo runs every job in the image; GitHub on the runner's VM, unless the job asks for the container or the image is yodel's. */
+const inContainer = (forge, tc) => forge === "forgejo" || tc.yodelImage;
+const runner = (container, tc) => ({ "runs-on": "ubuntu-latest", ...(container ? { container: tc.image } : {}) });
+/** The token `yodel plan --comment` posts with: the job's own. */
+function commentToken(forge) {
+    return forge === "github" ? { GITHUB_TOKEN: "${{ github.token }}" } : { FORGEJO_TOKEN: "${{ github.token }}" };
+}
+function lintJob(forge, dialect, replay, tc) {
+    // 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,
+    // which collides with any database already on that port (act, a
+    // self-hosted runner).
+    const container = replay || inContainer(forge, 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 }),
+    ];
+    if (!replay)
+        return new ActionsJob({ ...runner(container, tc), steps });
+    const svc = REPLAY_SERVICE[dialect];
+    return new ActionsJob({
+        ...runner(container, tc),
+        services: {
+            [svc.name]: new ActionsService({
+                image: svc.image,
+                env: svc.env,
+                options: `--health-cmd "${svc.health}" --health-interval 2s --health-timeout 5s --health-retries 45`,
+            }),
+        },
+        env: { [`${variablePrefix(REPLAY_PROFILE, dialect)}_URL`]: svc.url(svc.name), ...svc.jobEnv },
+        steps: [
+            ...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 }),
+        ],
+    });
+}
+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) };
+    for (const env of envs) {
+        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]),
+            steps: [
+                // The plan explains what moved since an approval from git's history of migrations/.
+                ...setupSteps(inContainer(forge, tc), tc),
+                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 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.",
+        ...(forge === "forgejo"
+            ? ["# The comment is posted with the job's own token (Forgejo gives a same-repository", "# pull request one that can comment)."]
+            : []),
+    ];
+    return {
+        path: `${forge === "github" ? ".github" : ".forgejo"}/workflows/yodel-pr.yml`,
+        content: withHeader(header, 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 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_) {
+    const { dialect, names: envs, replay, waves, jobs: own } = envs_;
+    const tc = toolchainOf(envs_);
+    const mr = () => [new Rule({ if: '$CI_PIPELINE_SOURCE == "merge_request_event"' })];
+    const workflow = new GitLabWorkflow({
+        rules: [
+            new WorkflowRule({ if: '$CI_PIPELINE_SOURCE == "merge_request_event"' }),
+            new WorkflowRule({ if: "$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS", when: "never" }),
+            new WorkflowRule({ if: "$CI_COMMIT_BRANCH" }),
+        ],
+    });
+    const jobs = new Map();
+    jobs.set(".yodel", new GitLabJob({
+        image: new Image({ name: tc.image }),
+        before_script: [...installLines(tc, "gitlab"), FETCH_APPROVALS],
+    }));
+    const svc = REPLAY_SERVICE[dialect];
+    jobs.set("lint", new GitLabJob({
+        extends: ".yodel",
+        stage: "review",
+        rules: mr(),
+        ...(replay
+            ? {
+                script: [CI_CHECK, LINT, waitFor(svc.name, svc.port), REPLAY],
+                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] }),
+    }));
+    for (const env of envs) {
+        jobs.set(`plan-${env}`, new GitLabJob({
+            extends: ".yodel",
+            stage: "review",
+            rules: mr(),
+            script: [`yodel plan ${env} --comment`],
+            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 header = [
+        ...HEADER,
+        "#",
+        "# Merge requests: lint and the plan comment (stage review). A push to the",
+        `# default branch: the apply waves, one stage each, in ${GITLAB_APPLY_FILE}.`,
+        `# The drift watches are in ${GITLAB_WATCH_FILE} (stage ops).`,
+        "#",
+        "# GitLab gives every job the project's CI/CD variables unless a variable is",
+        "# 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.",
+        "# 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.",
+    ];
+    return { path: ".gitlab-ci.yml", content: withHeader(header, yaml) };
+}
+const WAVE_GATES = ["always", "on-destructive", "never"];
+/** The environment `env`'s wave requires, as a list. */
+const requiredOf = (waves, env) => {
+    const r = waves.find((w) => w.env === env)?.requires;
+    return r ? [r] : [];
+};
+/** The waves spec: committed, and read by every wave job (its gate policy at the commit before the push). */
+export const WAVES_SPEC = "yodel-waves.json";
+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) {
+    const first = waves[0];
+    if (!first)
+        throw new Error("no waves to render");
+    return {
+        name: APPLY_PIPELINE,
+        op: `migrate-${first.env}`,
+        plan: ["yodel", "apply", "{target}", "--wave-plan", "{plan}", "--spec", WAVES_SPEC],
+        apply: ["yodel", "apply", "{target}", "--wave-apply", "{plan}", "--spec", WAVES_SPEC],
+        branches: [MAIN],
+        waves: waves.map((w) => ({
+            name: w.env,
+            runs: (w.targets ?? [w.env]).map((target) => ({ target, op: `migrate-${w.env}` })),
+            gate: w.gate,
+            ...(w.shares !== undefined && w.shares > 1 ? { shares: w.shares } : {}),
+            ...(variables ? { environment: { name: w.env }, variables: variables(w.env) } : {}),
+        })),
+    };
+}
+/** The waves spec file and the apply pipeline on each forge. */
+export async function applyPipelines(dir, envs) {
+    const { dialect, waves } = envs;
+    const tc = toolchainOf(envs);
+    const { generateOpWavesPipeline } = (await import("@intentius/chant/op"));
+    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;
+        return {
+            YODEL_CREDENTIALS: `writer:${env}`,
+            ...APPLY_LOCK,
+            ...(forge === "gitlab"
+                ? {}
+                : { ...secrets([...writerVariables(env, dialect), ...WEBHOOK_VARIABLES]), ...(required ? secrets(readerVariables(required, dialect)) : {}) }),
+        };
+    };
+    const header = [
+        ...HEADER,
+        "#",
+        "# A push to main: one job per wave, each needing the one before. Each runs",
+        "# chant run wave: yodel apply <env> --wave-plan plans the environment, the",
+        `# 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",
+        "# the reader of the environment before (waves[].requires): yodel apply refuses",
+        "# a migration that environment's history does not record as applied.",
+    ];
+    for (const forge of FORGES) {
+        const result = await generateOpWavesPipeline(wavesSpec(waves, variables(forge)), forge, {
+            specFile: WAVES_SPEC,
+            image: tc.image,
+            beforeScript: [...installLines(tc, forge), FETCH_APPROVALS],
+            ...(forge === "gitlab" ? { opsFileName: GITLAB_APPLY_FILE } : {}),
+        }, dir);
+        if (!result.success || !result.files)
+            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)) });
+        }
+    }
+    return out;
+}
+/**
+ * The wave jobs' report: chant's generateOpWavesPipeline takes run lines
+ * after the wave's command but no step that runs when it fails (a wave that
+ * waits exits 3), and no artifact, so they are added to its output here.
+ * The output is parsed and emitted again; the emitter is checked to give
+ * 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) {
+    // 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);
+    const header = yaml.slice(0, body);
+    const doc = parseYAMLDocument(yaml);
+    if (forge === "gitlab") {
+        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");
+        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}/`] } });
+        }
+        return emit(doc);
+    }
+    const at = yaml.indexOf("\njobs:\n");
+    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)
+        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;
+        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();
+}
+/** yodel.config.ts `waves`, checked against the environments; one wave per environment, gate `always`, without it. */
+export async function readWaves(dir, envs) {
+    const declared = (await readConfig(dir))?.waves;
+    if (declared === undefined)
+        return envs.map((env, i) => ({ env, gate: "always", ...(i > 0 ? { requires: envs[i - 1] } : {}) }));
+    if (!Array.isArray(declared) || declared.length === 0)
+        throw new Error("yodel.config.ts: waves must list at least one { env, gate }");
+    return declared.map((w, i, all) => {
+        const env = String(w.env);
+        if (!envs.includes(env))
+            throw new Error(`yodel.config.ts: waves[${String(i)}].env ${env} is not an environment (${envs.join(", ")})`);
+        const gate = (w.gate ?? "always");
+        if (!WAVE_GATES.includes(gate))
+            throw new Error(`yodel.config.ts: waves[${String(i)}].gate ${String(w.gate)} is not ${WAVE_GATES.join(", ")}`);
+        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 } : {}) };
+    });
+}
+/**
+ * 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.
+ */
+export async function withTenants(dir, waves) {
+    const { loadProject } = await import("../project.js");
+    const { listTenants, tenantTarget } = await import("../tenants/index.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)) });
+    }
+    return out;
+}
+/**
+ * The watch's spec for one environment: the Op, and on GitHub and Forgejo the
+ * reader's secrets. A GitLab job already has the project's variables (a
+ * 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) {
+    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" } } : {}),
+    };
+}
+export async function watchPipelines(dir, envs_) {
+    const { dialect, names: envs } = envs_;
+    const tc = toolchainOf(envs_);
+    const { generateOpsPipeline } = (await import("@intentius/chant/op"));
+    const out = [];
+    const emit = async (forge, specs, extraScript) => {
+        const result = await generateOpsPipeline(specs, forge, {
+            image: tc.image,
+            beforeScript: [...installLines(tc, forge), FETCH_APPROVALS, NO_PUSH],
+            extraScript,
+            ...(forge === "gitlab" ? { opsStage: "ops", opsFileName: GITLAB_WATCH_FILE } : {}),
+        }, dir);
+        if (!result.success || !result.files)
+            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`}` });
+        }
+    };
+    // `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)]);
+    }
+    // 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 ─────────────────────────────────────────────────────────────
+/** The dialect and the environments chant.config.ts declares, in order. */
+export async function environments(dir) {
+    const { loadChantConfig } = await import("@intentius/chant/config");
+    const { config } = await loadChantConfig(dir);
+    const sql = config.sql;
+    const dialect = sql?.dialect;
+    if (dialect !== "clickhouse" && dialect !== "postgres")
+        throw new Error(`chant.config.ts: sql.dialect must be clickhouse or postgres, got ${String(dialect)}`);
+    const all = Object.keys(sql?.profiles ?? {});
+    const replay = all.includes(REPLAY_PROFILE);
+    const envs = all.filter((name) => name !== REPLAY_PROFILE);
+    if (envs.length === 0)
+        throw new Error("chant.config.ts declares no sql.profiles");
+    for (const env of envs) {
+        for (const op of [`migrate-${env}`, `watch-${env}`]) {
+            if (!existsSync(join(dir, "ops", `${op}.op.ts`)))
+                throw new Error(`sql.profiles.${env} has no ops/${op}.op.ts`);
+        }
+    }
+    const ci = (await readConfig(dir))?.ci;
+    return {
+        dialect,
+        names: envs,
+        replay,
+        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 } : {}),
+    };
+}
+/** yodel.config.ts, checked; undefined when the project has none. */
+async function readConfig(dir) {
+    return (await loadYodelConfig(dir))?.config;
+}
+/** Loads the module `ci.jobs` names. */
+export async function loadProjectJobs(dir, file) {
+    const path = resolve(dir, file);
+    if (!existsSync(path))
+        throw new Error(`yodel.config.ts: ci.jobs names ${file}, which is not there`);
+    const mod = (await import(pathToFileURL(path).href));
+    const out = {};
+    for (const key of Object.keys(mod)) {
+        if (key !== "actions" && key !== "gitlab" && key !== "default")
+            throw new Error(`${file}: export ${key} is not actions or gitlab`);
+    }
+    for (const key of ["actions", "gitlab"]) {
+        const v = mod[key];
+        if (v === undefined)
+            continue;
+        if (typeof v !== "object" || v === null || Array.isArray(v))
+            throw new Error(`${file}: ${key} must be an object of jobs, keyed by the job's name`);
+        out[key] = v;
+    }
+    return out;
+}
+/** The project's jobs for one pipeline, refusing a name yodel's jobs already use. */
+function ownJobs(own, yodels, what) {
+    if (!own)
+        return {};
+    for (const name of Object.keys(own)) {
+        if (name in yodels)
+            throw new Error(`ci.jobs: ${what} job ${name} has the name of one of yodel's jobs; name it something else`);
+    }
+    return own;
+}
+/** The pipelines that need no Op discovery: pull requests, and GitLab's main file. */
+export function review(envs) {
+    return [actionsReview("github", envs), actionsReview("forgejo", envs), gitlabPipeline(envs)];
+}
+/** The forge a rendered file is for; undefined for the waves spec, which every forge's apply reads. */
+export function forgeOf(path) {
+    if (path.startsWith(".github/"))
+        return "github";
+    if (path.startsWith(".forgejo/"))
+        return "forgejo";
+    if (path.startsWith(".gitlab"))
+        return "gitlab";
+    return undefined;
+}
+export async function render(dir) {
+    const envs = await environments(dir);
+    const forges = envs.forges ?? FORGES;
+    const files = [...review(envs), ...(await applyPipelines(dir, envs)), ...(await watchPipelines(dir, envs))];
+    return files.filter((f) => {
+        const forge = forgeOf(f.path);
+        return forge === undefined || forges.includes(forge);
+    });
+}
+//# sourceMappingURL=render.js.map