@intentius/chant 0.124.28 → 0.124.30

package/dist/workspace/ci-run.js

@@ -0,0 +1,464 @@
+/**
+ * `chant ci run plan|apply` (#4094, epic #4101): run one pull-request job as
+ * a pipeline Op, the first slice of the chant runner.
+ *
+ * The job is the typed value `prLoopJobs` (../components/pr-pipeline.ts)
+ * returns, the one the github, gitlab and forgejo generators wrap in a
+ * workflow, so the runner and a generated workflow run the same command with
+ * the same values. Nothing reads generated YAML.
+ *
+ * The job runs as an Op on the local executor (../op/local-executor.ts):
+ *
+ * - a `setup` phase with the setup lines the default image needs,
+ * - a `build` phase with the lines given to run before the command
+ *   (`--before-script`, which a generated workflow runs in the same place),
+ *   then the job's build and lint lines with `--pr-build` (#4088),
+ * - and a phase named for the job, `plan` or `apply`, with the job's own
+ *   setup lines and its command in one shell.
+ *
+ * Each line is one shell step with a clean environment: a short list of the
+ * runner's variables (PATH, HOME and the like), the forge's connection and
+ * token variables the commands read, any `--pass-env` names, and the job's
+ * own variables. The forge values a generated job reads from `${{ ... }}`
+ * expressions or GitLab's predefined variables come from flags here:
+ * `BASE_SHA` from `--base`, `PR_NUMBER` from `--pr`, and the commit from
+ * `--commit`.
+ *
+ * The steps run in a fresh checkout of the commit: a detached `git worktree`
+ * in a temporary directory outside the repository, removed when the run
+ * ends. A worktree shares the repository's refs, so what the job records on
+ * `chant/lifecycle` (pr-apply's pending gate facts) and the remote it pushes
+ * to are the repository's own, as in a forge job's checkout. The report the
+ * job writes under `.chant/pr` is copied out of the worktree before it goes,
+ * where a forge would keep it as an artifact.
+ *
+ * The run is recorded as Op `pr-plan` or `pr-apply` in the run ledger
+ * (`<env>/runs__<op>.jsonl` on `chant/lifecycle`), and signed when a runner
+ * key is given, so `chant ci tick --source runs` (#4044) judges the commit
+ * from it. Its events are `kind: "pipeline"` and `runtime: "ci"`, and the
+ * record and the events carry `runOrigin: { forge: "chant" }`.
+ */
+import { execFileSync } from "node:child_process";
+import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { PR_APPLY_RECORD, PR_LOOP_REPORT_DIR, prLoopJobs, prLoopSetup, PR_LOOP_IMAGE } from "../components/pr-pipeline.js";
+import { detectForge, FORGE_KINDS } from "../pr-forge.js";
+import { formatError, formatWarning } from "../cli/format.js";
+import { pushLifecycleReport } from "../lifecycle/git.js";
+import { ACTIVITY_PROFILES } from "../op/activity-profiles.js";
+import { shellCmd } from "../op/activities/shell.js";
+import { OpRunFailure, runOpLocally } from "../op/local-executor.js";
+import { findWorkspaceRoot } from "../project-root.js";
+import { ciTagSigner, RUNNER_KEY_ENV } from "./ci-green.js";
+import { resolveMemberContext } from "./member-pipeline.js";
+import { signOpRunRecord } from "./trust/op-run-statement.js";
+import { gitTop } from "./tree.js";
+export const CI_JOB_NAMES = ["plan", "apply"];
+/** The Op each job is recorded as, which `ci.green` phases match. */
+export const CI_JOB_OPS = { plan: "pr-plan", apply: "pr-apply" };
+/** Where a job the chant runner ran says it ran (#4094). */
+export const CHANT_RUNNER_ORIGIN = { forge: "chant" };
+/** The runner's variables every job gets, when the runner has them. */
+export const CI_RUN_BASE_ENV = ["PATH", "HOME", "USER", "LOGNAME", "SHELL", "LANG", "LC_ALL", "LC_CTYPE", "TMPDIR", "TZ"];
+/**
+ * The forge's connection and token variables the pull-request commands read
+ * (`forgeFromEnv` in ../pr-forge.ts), which a forge job gets from the forge
+ * and a job here gets from the runner's environment.
+ */
+export const CI_RUN_FORGE_ENV = [
+    "CHANT_FORGE_TOKEN",
+    "GITHUB_TOKEN",
+    "GH_TOKEN",
+    "GITHUB_REPOSITORY",
+    "GITHUB_SERVER_URL",
+    "GITHUB_API_URL",
+    "GITLAB_TOKEN",
+    "CI_API_V4_URL",
+    "CI_PROJECT_ID",
+    "CI_SERVER_HOST",
+    "CI_SERVER_URL",
+];
+/** How long one step may run: a forge job's own limit, six hours. */
+const STEP_TIMEOUT = "6h";
+export class CiRunError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CiRunError";
+    }
+}
+/**
+ * The job's environment: the runner's base variables, the forge variables
+ * and `passEnv` names it has, `CHANT_ENV` as a generated workflow sets it,
+ * the commit as the forge spells it, and the job's own variables. A job
+ * variable the forge fills from an expression comes from a flag, or from
+ * the runner's environment for a token such as `GITHUB_TOKEN`; a literal
+ * one, such as `CHANT_RUN_EVENTS_DIR`, is kept as it is.
+ */
+export function ciJobEnv(job, input) {
+    const out = {};
+    for (const name of [...CI_RUN_BASE_ENV, ...CI_RUN_FORGE_ENV, ...(input.passEnv ?? [])]) {
+        const value = input.hostEnv[name];
+        if (value !== undefined)
+            out[name] = value;
+    }
+    out.CHANT_ENV = input.env;
+    out[input.forge === "gitlab" ? "CI_COMMIT_SHA" : "GITHUB_SHA"] = input.values.commit;
+    const flags = {
+        BASE_SHA: { value: input.values.base, flag: "--base <sha>" },
+        PR_NUMBER: { value: input.values.pr !== undefined ? String(input.values.pr) : undefined, flag: "--pr <number>" },
+    };
+    for (const [name, value] of Object.entries(job.env)) {
+        const given = flags[name];
+        if (given) {
+            if (given.value === undefined)
+                throw new CiRunError(`the ${job.jobName} job reads ${name}, which a forge fills from the event; pass ${given.flag}`);
+            out[name] = given.value;
+        }
+        else if (!value.includes("$")) {
+            out[name] = value;
+        }
+        else if (input.hostEnv[name] !== undefined) {
+            out[name] = input.hostEnv[name];
+        }
+    }
+    return out;
+}
+/** `line` with a `chant` at its start replaced by the command the caller names, when it names one. */
+export function withChant(line, chant) {
+    return chant && line.startsWith("chant ") ? `${chant}${line.slice("chant".length)}` : line;
+}
+/** The job's own setup lines and its command, as one shell script, with `chant` at its start replaced by the command the caller names. */
+export function ciJobCommand(job, chant) {
+    return [...(job.setup ?? []), withChant(job.command, chant)].join("\n");
+}
+/**
+ * The job as an Op: `setup`, `build` and the job's own phase, each line one
+ * shell step in `cwd` with the job's environment and nothing else. A phase
+ * with no lines is left out.
+ */
+export function ciJobOp(input) {
+    const step = (cmd) => ({
+        kind: "activity",
+        fn: "shellCmd",
+        args: { cmd, cwd: input.cwd, env: input.jobEnv, inheritEnv: false },
+        profile: "atMostOnce",
+        timeout: STEP_TIMEOUT,
+    });
+    const phases = [
+        { name: "setup", steps: input.setup.map(step) },
+        { name: "build", steps: input.build.map((line) => step(withChant(line, input.chant))) },
+        { name: input.job.jobName, steps: [step(ciJobCommand(input.job, input.chant))] },
+    ].filter((p) => p.steps.length > 0);
+    const op = CI_JOB_OPS[input.job.jobName];
+    return {
+        name: op,
+        overview: input.job.jobName === "plan" ? "Plan the members this pull request reaches" : "Apply the plan a reviewer approved",
+        labels: { Env: input.env, Pipeline: "pr", Job: input.job.jobName },
+        phases,
+    };
+}
+/** The pull-request report statuses that mean the job did not do its work, which a failed job's `failure.code` takes. */
+const FAILED_REPORT_STATUSES = new Set(["plan-failed", "failed", "refused"]);
+/** The exit code a failed shell step's error names (`command exited <n>`), when it names one. */
+function exitCodeOf(error) {
+    const m = /command exited (\d+)/.exec(error ?? "");
+    return m ? Number(m[1]) : undefined;
+}
+/** The first line of a step's error, for a reason. */
+const firstLine = (text) => text.split("\n").find((l) => l.trim() !== "")?.trim() ?? text;
+/**
+ * Why a failed job failed (#4094), from its step records and, when the
+ * command wrote one, its pull-request report (`pr-plan.json` or
+ * `pr-apply.json` under `reportDir`):
+ *
+ * - a failed setup or build line: `setup-failed` or `build-failed`, the line
+ *   and its exit code as the reason, and the phase;
+ * - a failed command with a report: the report's `refusal`, else its
+ *   `status`, with its `message` as the reason, else the members that failed;
+ * - a failed command with no report: `command-failed` and the step's error.
+ *
+ * Undefined when no step failed, such as a run that stopped on an error of
+ * its own before any step ran.
+ */
+export function ciJobFailure(input) {
+    const failed = input.records.find((r) => r.status === "fail");
+    if (!failed)
+        return undefined;
+    const exitCode = exitCodeOf(failed.error);
+    const exit = exitCode !== undefined ? { exitCode } : {};
+    if (failed.phase === "setup" || failed.phase === "build") {
+        const at = input.records.filter((r) => r.phase === failed.phase).indexOf(failed);
+        const step = input.op.phases.find((p) => p.name === failed.phase)?.steps[at];
+        const line = typeof step?.args?.cmd === "string" ? step.args.cmd : undefined;
+        const reason = line !== undefined
+            ? `${line} ${exitCode !== undefined ? `exited ${exitCode}` : `failed: ${firstLine(failed.error ?? "")}`}`
+            : firstLine(failed.error ?? "the step failed");
+        return { code: `${failed.phase}-failed`, reason, phase: failed.phase, ...exit };
+    }
+    const file = join(input.reportDir, `${CI_JOB_OPS[input.job]}.json`);
+    let report;
+    try {
+        if (existsSync(file))
+            report = JSON.parse(readFileSync(file, "utf-8"));
+    }
+    catch {
+        report = undefined;
+    }
+    const status = typeof report?.status === "string" ? report.status : undefined;
+    if (report && status && (FAILED_REPORT_STATUSES.has(status) || typeof report.refusal === "string")) {
+        const code = typeof report.refusal === "string" ? report.refusal : status;
+        let reason = typeof report.message === "string" && report.message.trim() !== "" ? firstLine(report.message) : undefined;
+        if (reason === undefined) {
+            const members = Array.isArray(report.members) ? report.members : [];
+            const bad = members.filter((m) => m.status === "failed" || m.status === "plan-failed");
+            reason = bad.length > 0
+                ? `${bad.length === 1 ? "member" : "members"} ${bad.map((m) => `${String(m.member)} ${String(m.status)}${typeof m.error === "string" ? ` (${firstLine(m.error)})` : ""}`).join(", ")}`
+                : `the ${CI_JOB_OPS[input.job]} report says ${status}`;
+        }
+        return { code, reason, phase: failed.phase, ...exit };
+    }
+    return { code: "command-failed", reason: firstLine(failed.error ?? "the command failed"), phase: failed.phase, ...exit };
+}
+const message = (err) => (err instanceof Error ? err.message : String(err));
+function git(cwd, args) {
+    return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+function tryGit(cwd, args) {
+    try {
+        return git(cwd, args);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The full commit `rev` names, fetched from `origin` when the repository lacks it. */
+function resolveJobCommit(top, rev) {
+    if (rev.startsWith("-"))
+        throw new CiRunError(`--commit takes a commit, not ${JSON.stringify(rev)}`);
+    const local = tryGit(top, ["rev-parse", "--verify", "--quiet", `${rev}^{commit}`]);
+    if (local)
+        return local;
+    if (tryGit(top, ["fetch", "--quiet", "--no-tags", "origin", rev]) !== undefined) {
+        const fetched = tryGit(top, ["rev-parse", "--verify", "--quiet", "FETCH_HEAD^{commit}"]);
+        if (fetched && (fetched === rev || fetched.startsWith(rev)))
+            return fetched;
+    }
+    throw new CiRunError(`${rev} names no commit here or on origin`);
+}
+/** The member a job runs for, and its directory from the repository root, as the generator decides it. */
+export function ciJobPlace(cwd, top) {
+    const found = findWorkspaceRoot(cwd);
+    const member = found ? resolveMemberContext(cwd, found) : undefined;
+    const at = member ? member.memberRoot : cwd;
+    const dir = relative(top, realpathSync(at)).split(sep).join("/");
+    return { ...(member ? { member: member.member.name } : {}), dir: dir === "" ? "." : dir };
+}
+/** A detached worktree of `commit` in a new temporary directory, and how to remove it. */
+function freshCheckout(top, commit) {
+    const holder = mkdtempSync(join(realpathSync(tmpdir()), "chant-ci-run-"));
+    const dir = join(holder, "checkout");
+    try {
+        git(top, ["worktree", "add", "--quiet", "--detach", dir, commit]);
+    }
+    catch (err) {
+        rmSync(holder, { recursive: true, force: true });
+        const stderr = err.stderr;
+        throw new CiRunError(`could not check out ${commit.slice(0, 12)} in a fresh worktree: ${String(stderr ?? err).trim()}`);
+    }
+    return {
+        dir,
+        remove() {
+            tryGit(top, ["worktree", "remove", "--force", dir]);
+            rmSync(holder, { recursive: true, force: true });
+            tryGit(top, ["worktree", "prune"]);
+        },
+    };
+}
+const ACTIVITIES = new Map([["shellCmd", shellCmd]]);
+/**
+ * Run one pull-request job as a pipeline Op in a fresh checkout of the
+ * commit, record it, and copy its report out. Throws {@link CiRunError}
+ * before anything runs when the request can't be run.
+ */
+export async function ciRun(req) {
+    const hostEnv = req.hostEnv ?? process.env;
+    const cwd = realpathSync(resolve(req.cwd));
+    const top = gitTop(cwd);
+    if (!top)
+        throw new CiRunError("a job runs in a fresh checkout of a commit, and this directory is not in a git repository");
+    const commit = resolveJobCommit(top, req.commit ?? "HEAD");
+    const place = ciJobPlace(cwd, top);
+    const jobs = prLoopJobs(req.forge, req.env, req.loop ?? {}, place.member);
+    const job = jobs.find((j) => j.jobName === req.job);
+    if (!job)
+        throw new CiRunError(`the pull-request pipeline has no ${req.job} job; it has ${jobs.map((j) => j.jobName).join(" and ")}`);
+    const jobEnv = ciJobEnv(job, { forge: req.forge, env: req.env, values: { base: req.base, pr: req.pr, commit }, hostEnv, passEnv: req.passEnv });
+    // The record is signed against .chant/trust.json at the commit the job runs, so a key that commit does not list is refused before anything runs.
+    let signer;
+    const early = [];
+    if (req.runnerKey !== undefined) {
+        try {
+            signer = ciTagSigner(top, commit, req.runnerKey, "the runs it signed");
+        }
+        catch (err) {
+            if (!req.runnerKeyFromEnv)
+                throw new CiRunError(`the run would not be signed: ${message(err)}`);
+            early.push(`${RUNNER_KEY_ENV} is set, and the run will not be signed: ${message(err)}`);
+        }
+    }
+    const checkout = freshCheckout(top, commit);
+    try {
+        const jobDir = place.dir === "." ? checkout.dir : join(checkout.dir, place.dir);
+        const op = ciJobOp({
+            job,
+            env: req.env,
+            cwd: jobDir,
+            jobEnv,
+            setup: prLoopSetup(req.image ?? PR_LOOP_IMAGE),
+            build: [...(req.beforeScript ?? []), ...(job.build ?? [])],
+            ...(req.chant ? { chant: req.chant } : {}),
+        });
+        const runId = req.runId ?? `chant-${Date.now()}`;
+        const warnings = [...early];
+        const resume = req.job === "apply" && req.resumeRecord ? { host: resolve(req.resumeRecord), job: join(jobDir, PR_APPLY_RECORD) } : undefined;
+        if (resume && existsSync(resume.host)) {
+            mkdirSync(dirname(resume.job), { recursive: true });
+            copyFileSync(resume.host, resume.job);
+        }
+        let ledgerError;
+        let result;
+        try {
+            result = await runOpLocally(op, ACTIVITIES, ACTIVITY_PROFILES, req.signal, {
+                runId,
+                env: req.env,
+                cwd: jobDir,
+                commit,
+                ledger: { cwd: jobDir },
+                runner: { kind: "pipeline", runtime: "ci", runOrigin: CHANT_RUNNER_ORIGIN },
+                describeFailure: (records) => ciJobFailure({ job: req.job, op, records, reportDir: join(jobDir, PR_LOOP_REPORT_DIR) }),
+                ...(req.runEvents ? { runEvents: { write: req.runEvents } } : {}),
+                ...(req.stepOutput ? { stepOutput: req.stepOutput } : {}),
+                ...(signer ? { signRecord: (record) => signOpRunRecord(record, signer) } : {}),
+                onSignError: (err) => warnings.push(`the run was not signed: ${message(err)}`),
+                onLedgerError: (err) => {
+                    ledgerError = `the job ran, and its record could not be written to chant/lifecycle: ${message(err)}`;
+                },
+            });
+        }
+        catch (err) {
+            if (!(err instanceof OpRunFailure))
+                throw err;
+            result = err.result;
+        }
+        if (resume && existsSync(resume.job)) {
+            try {
+                mkdirSync(dirname(resume.host), { recursive: true });
+                copyFileSync(resume.job, resume.host);
+            }
+            catch (err) {
+                warnings.push(`the resume record could not be kept at ${resume.host}: ${message(err)}`);
+            }
+        }
+        const written = join(jobDir, PR_LOOP_REPORT_DIR);
+        let report = null;
+        if (existsSync(written)) {
+            report = resolve(cwd, req.output ?? PR_LOOP_REPORT_DIR);
+            cpSync(written, report, { recursive: true });
+        }
+        if (ledgerError)
+            throw new CiRunError(ledgerError);
+        const pushed = req.push === false ? { pushed: false, pushWarning: "chant/lifecycle was not pushed" } : await pushLifecycleReport({ cwd: top });
+        const failed = result.records.find((r) => r.status === "fail");
+        return {
+            op: op.name,
+            status: result.status,
+            record: result.record,
+            ...(failed ? { failure: { phase: failed.phase, error: failed.error ?? "the step failed" } } : {}),
+            report,
+            signer: signer?.principal ?? null,
+            pushed: pushed.pushed,
+            ...(pushed.pushWarning ? { pushWarning: pushed.pushWarning } : {}),
+            warnings,
+            checkout: checkout.dir,
+        };
+    }
+    finally {
+        checkout.remove();
+    }
+}
+/** The text `chant ci run` prints when the run settles. */
+export function formatCiRun(r) {
+    const lines = [`${r.op} ${r.status === "ok" ? "passed" : r.status === "fail" ? "failed" : r.status} at ${r.record.gitSha?.slice(0, 12) ?? "an unknown commit"}, run ${r.record.id} in ${r.record.env}`];
+    const why = r.record.failure;
+    if (why)
+        lines.push(`  failure: ${why.code}${why.phase ? ` in ${why.phase}` : ""}${why.exitCode !== undefined ? `, exit ${why.exitCode}` : ""}: ${why.reason}`);
+    else if (r.failure)
+        lines.push(`  ${r.failure.phase}: ${r.failure.error}`);
+    lines.push(`  record: ${r.record.env}/runs__${r.op}.jsonl on chant/lifecycle, ${r.signer ? `signed by ${r.signer}` : "unsigned, so ci tick from runs does not count it"}`);
+    if (r.report)
+        lines.push(`  report: ${r.report}`);
+    if (!r.pushed)
+        lines.push(`  ${r.pushWarning ?? "chant/lifecycle was not pushed"}`);
+    return lines.join("\n");
+}
+// ── The command ──────────────────────────────────────────────────────────────
+const USAGE = "chant ci run plan|apply --env <env> --base <sha> [--pr <n>] [--commit <sha>] [--forge github|gitlab|forgejo] " +
+    "[--gate <name>] [--branch <name>] [--events-json] [--report-url <url>] [--image <image>] [--before-script <line>]... " +
+    "[--pr-build] [--pr-build-command <line>] " +
+    "[--chant <command>] [--pass-env <NAME>]... [--key <runner key.pem>] [-o <dir>]";
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** `chant ci run plan|apply` (#4094). */
+export async function runCiRun(ctx) {
+    const { args } = ctx;
+    try {
+        const job = args.extraPositional;
+        if (job !== "plan" && job !== "apply")
+            throw new CiRunError(`ci run takes the job to run, plan or apply${job ? `, not ${JSON.stringify(job)}` : ""}`);
+        if (!args.env)
+            throw new CiRunError("--env names the environment the pipeline is for, as chant build --components --generate <lexicon> --pr-loop took it: --env <env>");
+        const forge = args.forge ?? detectForge(process.env);
+        if (!forge)
+            throw new CiRunError("--forge names the forge the job posts to: --forge github|gitlab|forgejo");
+        if (!FORGE_KINDS.includes(forge))
+            throw new CiRunError(`--forge takes github, gitlab or forgejo, not ${JSON.stringify(forge)}`);
+        for (const name of args.passEnv ?? [])
+            if (!ENV_NAME.test(name))
+                throw new CiRunError(`--pass-env takes a variable's name, not ${JSON.stringify(name)}`);
+        const fromFlag = args.key !== undefined;
+        const runnerKey = fromFlag ? readFileSync(resolve(args.key), "utf-8") : process.env[RUNNER_KEY_ENV] || undefined;
+        const result = await ciRun({
+            cwd: process.cwd(),
+            job,
+            env: args.env,
+            forge: forge,
+            ...(args.base ? { base: args.base } : {}),
+            ...(args.pr !== undefined ? { pr: args.pr } : {}),
+            ...(args.commit ? { commit: args.commit } : {}),
+            loop: {
+                ...(args.gate ? { gate: args.gate } : {}),
+                ...(args.branch ? { branch: args.branch } : {}),
+                ...(args.eventsJson ? { events: true } : {}),
+                ...(args.reportUrl ? { reportUrl: args.reportUrl } : {}),
+                ...(args.prBuild ? { build: true } : {}),
+                ...(args.prBuildCommand ? { buildCommand: args.prBuildCommand } : {}),
+            },
+            ...(args.image ? { image: args.image } : {}),
+            ...(args.beforeScript?.length ? { beforeScript: args.beforeScript } : {}),
+            ...(args.ciChant ? { chant: args.ciChant } : {}),
+            ...(args.passEnv?.length ? { passEnv: args.passEnv } : {}),
+            ...(args.output ? { output: args.output } : {}),
+            ...(runnerKey !== undefined ? { runnerKey, runnerKeyFromEnv: !fromFlag } : {}),
+            ...(args.eventsJson ? { runEvents: (line) => void process.stdout.write(line) } : {}),
+            stepOutput: (line) => void process.stderr.write(`${line}\n`),
+        });
+        for (const w of result.warnings)
+            console.error(formatWarning({ message: w }));
+        console.error(formatCiRun(result));
+        return result.status === "ok" ? 0 : 1;
+    }
+    catch (err) {
+        console.error(formatError({ message: `chant ci run: ${message(err)}`, hint: USAGE }));
+        return 1;
+    }
+}

package/dist/workspace/ci-serve.d.ts

@@ -0,0 +1,214 @@
+/**
+ * `chant ci serve` (#4095, epic #4101): the chant runner's trigger loop on one
+ * host. It polls the forge for the open pull requests into the target branch
+ * and for the branch's head, and runs the pull-request jobs with
+ * {@link ciRun} (./ci-run.ts): `plan` for each new pull request head, and
+ * `apply` for each new commit on the target branch, measured from the head
+ * the previous poll saw (the push's `before`).
+ *
+ * - Dedupe. A state file in the state directory keeps every job it started,
+ *   keyed by job and commit (`plan:<pr>:<sha>`, `apply:<sha>`), with how it
+ *   ended, and the target head the last apply was measured to. A job already
+ *   in it is not started again, unless it failed and `rerunFailed` asks for
+ *   it: the forge's "re-run failed jobs".
+ * - One apply per group. An apply takes the git-ref lease (../lifecycle/lease.ts,
+ *   the one `chant operator` holds) named for `prApplyGroup`, renews it while
+ *   it runs and releases it after. An apply that finds it held waits for a
+ *   later poll, as a forge's concurrency group queues it.
+ * - Resume records. Each apply gets `<state>/resume/<prApplyRecordKey>.json`
+ *   as its `--resume` record, so a re-run of a failed apply at the same
+ *   commit finishes under the approval it has. This replaces the forge's CI
+ *   cache.
+ * - Capacity. At most `maxJobs` jobs run at once. A job over the limit is not
+ *   recorded, so a later poll starts it.
+ *
+ * Host mode only: each job runs in a fresh worktree on this host as this
+ * user, with the clean environment `ciRun` gives it. A pull request from a
+ * fork is never planned, and with `authors` only those people's pull requests
+ * are. Container isolation is #4015.
+ *
+ * A webhook is not here yet. {@link ciServeSchedule} takes triggers, and
+ * {@link ciServeObserve} is the poll that makes them; a webhook handler would
+ * turn a checked payload into the same triggers and schedule them.
+ */
+import { type OpenPullRequest } from "../pr-forge.js";
+import type { CommandContext } from "../cli/registry.js";
+import { type CiJobName, type CiRunRequest, type CiRunResult } from "./ci-run.js";
+/** The forges `ci serve` polls. GitLab is later. */
+export type CiServeForgeKind = "github" | "forgejo";
+/** What `ci serve` reads from the forge: the two calls GitHub's and Forgejo's clients have (../pr-forge.ts). */
+export interface CiServeForge {
+    openPullRequests(base: string): Promise<OpenPullRequest[]>;
+    branchHead(branch: string): Promise<string | undefined>;
+}
+/** A job the forge's state calls for: the plan of a pull request's head, or the apply of a target-branch commit. */
+export type CiServeTrigger = {
+    job: "plan";
+    commit: string;
+    base: string;
+    pr: number;
+    rerun?: boolean;
+} | {
+    job: "apply";
+    commit: string;
+    base: string;
+    rerun?: boolean;
+};
+/** One job in the state file. */
+export interface CiServeJobState {
+    job: CiJobName;
+    commit: string;
+    base: string;
+    pr?: number;
+    /** `running` while it runs; a `running` entry no live process holds is taken as failed. */
+    status: "running" | "ok" | "fail";
+    runId: string;
+    attempts: number;
+    startedAt: string;
+    settledAt?: string;
+    /** Why it failed, in a line. */
+    failure?: string;
+    /** Where its report was copied. */
+    report?: string;
+}
+/** The state file, `<state>/<prApplyGroup>.json`. */
+export interface CiServeState {
+    schema: 1;
+    forge: CiServeForgeKind;
+    repo: string;
+    env: string;
+    branch: string;
+    member?: string;
+    /** The target branch's head the last apply was measured to, or the head the first poll found. */
+    target?: string;
+    jobs: Record<string, CiServeJobState>;
+}
+/** What a pass did, in order, for the log. */
+export type CiServeEvent = {
+    type: "baseline";
+    commit: string;
+} | {
+    type: "no-branch";
+    branch: string;
+} | {
+    type: "skipped";
+    pr: number;
+    reason: "fork" | "author";
+    author?: string;
+} | {
+    type: "held";
+    job: CiJobName;
+    commit: string;
+    pr?: number;
+    reason: "capacity" | "lease";
+    heldBy?: string;
+} | {
+    type: "started";
+    job: CiJobName;
+    commit: string;
+    pr?: number;
+    base: string;
+    runId: string;
+    attempt: number;
+    resume?: string;
+} | {
+    type: "settled";
+    job: CiJobName;
+    commit: string;
+    pr?: number;
+    status: "ok" | "fail";
+    failure?: string;
+    report?: string;
+} | {
+    type: "error";
+    message: string;
+};
+/** The `ciRun` request fields `ci serve` passes through to every job: the generator's options and the runner's. */
+export type CiServeJobOptions = Omit<CiRunRequest, "cwd" | "job" | "env" | "forge" | "base" | "pr" | "commit" | "output" | "resumeRecord" | "runId">;
+export interface CiServeOptions {
+    /** The host's clone, or a workspace member's directory in it. */
+    cwd: string;
+    forge: CiServeForgeKind;
+    /** `owner/name`. */
+    repo: string;
+    env: string;
+    client: CiServeForge;
+    /** Default `<git common dir>/chant/ci-serve`. */
+    stateDir?: string;
+    /** Default 1. */
+    maxJobs?: number;
+    /** Plan only pull requests these logins opened, without case. Default anyone with a branch in the repository. */
+    authors?: readonly string[];
+    /** Run again the failed apply at the target's head, and the failed plans of open heads. */
+    rerunFailed?: boolean;
+    /** Passed to each job. `job.hostEnv` gets `GITHUB_REPOSITORY` set to `repo`. */
+    job?: CiServeJobOptions;
+    /** This process's lease identity. Default `currentHolderId()`. */
+    holder?: string;
+    leaseTtlMs?: number;
+    log?: (event: CiServeEvent) => void;
+    now?: () => Date;
+    /** Runs a job. Default {@link ciRun}. */
+    run?: (req: CiRunRequest) => Promise<CiRunResult>;
+}
+/** The jobs this process runs now, by state key, shared by every pass of one loop. */
+export interface CiServeRuntime {
+    inflight: Map<string, Promise<CiServeJobState>>;
+}
+export declare const newCiServeRuntime: () => CiServeRuntime;
+/** The state key of a job. */
+export declare function ciServeKey(t: {
+    job: CiJobName;
+    commit: string;
+    pr?: number;
+}): string;
+/** Where a serve keeps its state when `--state` names nowhere: beside the run events, in the repository's common git directory. */
+export declare function defaultCiServeStateDir(cwd: string): string;
+/** The state file, or a new one. */
+export declare function readCiServeState(file: string, fresh: Omit<CiServeState, "schema" | "jobs">): CiServeState;
+/**
+ * One poll of the forge, as triggers: an apply when the target's head moved
+ * since the last apply (none on the first poll, which only notes the head),
+ * then a plan for each open pull request head not yet planned, oldest pull
+ * request first. A job already in the state file is left out unless it
+ * failed and `rerunFailed` is set. The first poll's head is written to the
+ * state file.
+ */
+export declare function ciServeObserve(opts: CiServeOptions, rt?: CiServeRuntime): Promise<{
+    triggers: CiServeTrigger[];
+    events: CiServeEvent[];
+}>;
+/** What {@link ciServeSchedule} did with the triggers. */
+export interface CiServeScheduled {
+    /** Each job started, settling to its state entry. */
+    started: Promise<CiServeJobState>[];
+    events: CiServeEvent[];
+}
+/**
+ * Start the triggers' jobs, at most `maxJobs` at once with the jobs this
+ * process already runs. An apply first takes its group's lease. A trigger
+ * that can't start (over capacity, lease held, or already running here) is
+ * reported and not recorded, so the next poll finds it again.
+ */
+export declare function ciServeSchedule(opts: CiServeOptions, triggers: readonly CiServeTrigger[], rt?: CiServeRuntime): Promise<CiServeScheduled>;
+/** One pass: observe, schedule, and with `wait` wait for the jobs it started. */
+export declare function ciServePass(opts: CiServeOptions, rt?: CiServeRuntime, wait?: boolean): Promise<{
+    events: CiServeEvent[];
+    jobs: CiServeJobState[];
+}>;
+/**
+ * The loop: a pass every `intervalMs` until `signal` aborts, jobs running
+ * across passes up to `maxJobs`. A pass the forge fails is logged and the
+ * loop goes on. On abort it waits for the jobs that run.
+ */
+export declare function ciServeLoop(opts: CiServeOptions & {
+    intervalMs: number;
+    signal?: AbortSignal;
+}): Promise<void>;
+/** One line for an event, as `ci serve` prints it. */
+export declare function formatCiServeEvent(e: CiServeEvent): string;
+/** `--interval`: seconds, or a duration such as `30s` or `2m`. Default 30 seconds. */
+export declare function ciServeInterval(value: string | undefined): number;
+/** `chant ci serve` (#4095). */
+export declare function runCiServe(ctx: CommandContext): Promise<number>;
+//# sourceMappingURL=ci-serve.d.ts.map