@intentius/chant 0.124.40 → 0.124.41

package/dist/components/pr-environment.js

@@ -0,0 +1,406 @@
+/**
+ * An environment per open pull request (#4298): `ci.prEnvironment` in the
+ * workspace declaration names a template environment, and each open pull
+ * request gets `pr-<number>`, derived from it.
+ *
+ *   chant components pr-env up --base <ref> --pr <n>
+ *       From the pull request's job. Plans the components the change reaches
+ *       into `pr-<n>` and applies them once an approval stands for that plan
+ *       (`chant approve pr-<n> pr-env --plan <digest>`). The environment
+ *       takes the template's declared endpoint unless a `pr-*` entry declares
+ *       its own. Every resource it creates carries the ownership marker
+ *       `{ stack, env: "pr-<n>" }`, since the build parameter that
+ *       `ownership.env` reads is set to the environment's name. The record
+ *       of the apply goes to `_pr-envs/records.jsonl` on chant/lifecycle.
+ *   chant components pr-env down --pr <n> [--reason closed|expired]
+ *       From the job a closed pull request starts. Tears down what carries
+ *       the marker the record names, and nothing else (the ownership check,
+ *       {@link teardownRefusal} and {@link ownedEntries}).
+ *   chant components pr-env sweep
+ *       From a schedule. Tears down each live environment whose TTL passed,
+ *       or whose pull request the forge says is closed or merged. GitLab
+ *       starts no pipeline when a merge request closes, so there the sweep is
+ *       how a closed merge request loses its environment.
+ *
+ * The settings are read from the declaration at base, never from the pull
+ * request, so a change cannot name another template or a longer TTL.
+ *
+ * A pull request's environment is not a release target (ws-104, ws-105):
+ * releases come from green commits, and `components promote` refuses to
+ * promote to or from one ({@link releaseTargetRefusal}). Its record says
+ * `releaseTarget: false`.
+ *
+ * terragucci's `ephemeral.ts` gives each copy a suffixed Terraform state key.
+ * That part is Terraform's own and stays there; chant keys ownership on the
+ * marker its lexicons stamp and read back (`../lifecycle/teardown.ts`).
+ */
+import { environmentEndpoint, environmentName, isEnvironmentPattern, isOwnershipParamRef, matchesDeclaredEnvironment, resolveOwnershipStack } from "../config.js";
+import { executeTeardown, planTeardown } from "../lifecycle/teardown.js";
+import { applyLiveEndpoint } from "../live-endpoint.js";
+/** The gate a pull request's environment waits on, under the pull request's op `pr-<n>`. */
+export const PR_ENV_GATE = "pr-env";
+/** Where the records live on chant/lifecycle, under the member's ledger prefix. */
+export const PR_ENV_LEDGER_DIR = "_pr-envs";
+export const PR_ENV_LEDGER_FILE = "records.jsonl";
+/** Where `pr-env` writes its report and note unless `--output` says. */
+export { PR_ENV_REPORT_DIR } from "./pr-pipeline.js";
+/** The file `pr-env up --no-push` writes its record to under `--output`, for `pr-env post` (#4295). */
+export const PR_ENV_RECORD_FILE = "pr-env-record.json";
+/** The commit status context the up and down jobs set. */
+export const PR_ENV_STATUS_CONTEXT = "chant/pr-env";
+/** The variable a component's build reads the template's name from. */
+export const PR_ENV_TEMPLATE_VAR = "CHANT_ENV_TEMPLATE";
+/** Exit codes: done, failed or refused, and waiting on an approval. */
+export const PR_ENV_EXIT = { done: 0, failed: 1, waiting: 3 };
+/** The environment of pull request `pr`. */
+export function prEnvironmentName(pr) {
+    return `pr-${pr}`;
+}
+const PR_ENV_NAME = /^pr-[1-9][0-9]*$/;
+/** Whether `name` is a pull request's environment name, `pr-<n>`. */
+export function isPrEnvironmentName(name) {
+    return PR_ENV_NAME.test(name);
+}
+/** The hidden line that marks the environment's note on the pull request. */
+export function prEnvNoteMarker(env, member) {
+    return member ? `<!-- chant-pr-env:${env}:${member} -->` : `<!-- chant-pr-env:${env} -->`;
+}
+/** The status context, per member in a workspace. */
+export function prEnvStatusContext(member) {
+    return member ? `${PR_ENV_STATUS_CONTEXT}/${member}` : PR_ENV_STATUS_CONTEXT;
+}
+/** The approve command for an environment's plan. */
+export function prEnvApproveCommand(op, digest, approver = "<you>") {
+    return `chant approve ${op} ${PR_ENV_GATE} --plan ${digest} --approver ${approver} --sign`;
+}
+/**
+ * Why `env` cannot be a release's source or target, or undefined when it
+ * can. A pull request's environment never is (ws-104: releases come from
+ * green commits).
+ */
+export function releaseTargetRefusal(env) {
+    if (!isPrEnvironmentName(env))
+        return undefined;
+    return `${env} is a pull request's environment (ci.prEnvironment), which is never a release target: releases come from green commits (ws-104), and pr-env down removes it when the pull request closes`;
+}
+/** A TTL of the form `90m`, `72h` or `7d`, in milliseconds. Undefined for any other form. */
+export function ttlMs(ttl) {
+    const m = /^([1-9][0-9]*)(m|h|d)$/.exec(ttl);
+    if (!m)
+        return undefined;
+    const unit = m[2] === "m" ? 60000 : m[2] === "h" ? 3600000 : 86400000;
+    return Number(m[1]) * unit;
+}
+/**
+ * Derive pull request `pr`'s environment from `template` and the project's
+ * config. Refused when the resources it creates could not be told apart
+ * from the template's: marking is off, or `ownership.env` is a literal (every
+ * resource would carry that literal) or unset. Refused too when the config
+ * would not take the name, or does not declare the template.
+ */
+export function derivePrEnvironment(config, template, pr) {
+    const env = prEnvironmentName(pr);
+    const stack = resolveOwnershipStack(config);
+    if (stack === undefined) {
+        return { refusal: `${env}: the project declares no ownership.stack, so nothing it creates would carry a marker, and pr-env down could not tell its resources from any other; set ownership: { stack: "<name>", env: { param: "env" } } in chant.config.ts` };
+    }
+    const own = config.ownership?.env;
+    if (!isOwnershipParamRef(own)) {
+        return {
+            refusal: own === undefined
+                ? `${env}: ownership.env is unset, so the marker would name no environment and pr-env down could not select ${env}'s resources; set ownership.env to { param: "env" }`
+                : `${env}: ownership.env is the literal ${JSON.stringify(own)}, so ${env}'s resources would carry ${JSON.stringify(own)}'s marker; set ownership.env to { param: "env" } so the marker follows the environment`,
+        };
+    }
+    if (!config.buildParams?.[own.param]) {
+        return { refusal: `${env}: ownership.env reads build parameter "${own.param}", which chant.config.ts's buildParams does not declare` };
+    }
+    const declared = config.environments;
+    if (declared && declared.length > 0) {
+        if (!declared.some((e) => environmentName(e) === template)) {
+            return { refusal: `${env}: ci.prEnvironment.template is ${template}, which chant.config.ts's environments do not declare` };
+        }
+        if (!matchesDeclaredEnvironment(declared, env)) {
+            return { refusal: `${env}: chant.config.ts's environments do not cover ${env}; add "pr-*" to environments` };
+        }
+        // A literal pr-<n> is a declared environment of its own, maybe one a release targets.
+        if (declared.some((e) => environmentName(e) === env)) {
+            return { refusal: `${env} is declared outright in chant.config.ts's environments, so it is not a pull request's to create or tear down; declare "pr-*" instead` };
+        }
+    }
+    const endpoint = environmentEndpoint(declared, env) ?? environmentEndpoint(declared, template);
+    const environments = declared ? [endpoint ? { name: env, endpoint } : env, ...declared] : undefined;
+    return { env, template, stack, param: own.param, environments, ...(endpoint ? { endpoint } : {}) };
+}
+/** The records of a records.jsonl text, oldest first. Malformed lines are skipped. */
+export function parsePrEnvRecords(text) {
+    const out = [];
+    for (const line of (text ?? "").split("\n").map((l) => l.trim()).filter(Boolean)) {
+        try {
+            const r = JSON.parse(line);
+            if (r.version === 1 && (r.kind === "up" || r.kind === "down") && typeof r.pr === "number" && typeof r.env === "string" && r.marker && typeof r.marker.stack === "string")
+                out.push(r);
+        }
+        catch {
+            continue;
+        }
+    }
+    return out;
+}
+/**
+ * The environments that stand, by name, from the records in order: an up
+ * (applied or failed part way) makes or refreshes one, a down that
+ * destroyed everything ends it, and any other down leaves it live.
+ */
+export function livePrEnvironments(records) {
+    const live = new Map();
+    for (const r of records) {
+        if (r.kind === "up") {
+            const was = live.get(r.env);
+            live.set(r.env, {
+                pr: r.pr,
+                env: r.env,
+                ...(r.member ? { member: r.member } : {}),
+                template: r.template,
+                marker: { ...r.marker },
+                commit: r.commit,
+                components: [...new Set([...(was?.components ?? []), ...r.components])],
+                applied: r.timestamp,
+                expiresAt: r.expiresAt ?? r.timestamp,
+            });
+        }
+        else if (r.result === "destroyed") {
+            live.delete(r.env);
+        }
+        else {
+            const was = live.get(r.env);
+            if (was)
+                live.set(r.env, { ...was, teardownIncomplete: true });
+        }
+    }
+    return live;
+}
+/** Whether a live environment's TTL passed at `now`. */
+export function expired(env, now) {
+    return Date.parse(env.expiresAt) <= now.getTime();
+}
+// ── the ownership check ────────────────────────────────────────────────────
+/**
+ * Why pull request `pr`'s environment must not be torn down as `live`
+ * says, or undefined when it may. The record must name `pr-<n>` for this
+ * pull request, its marker's env must be that name, and the config must not
+ * declare the name outright (a declared environment belongs to the project,
+ * not to a pull request).
+ */
+export function teardownRefusal(pr, live, declared) {
+    const env = prEnvironmentName(pr);
+    if (live.env !== env || live.pr !== pr)
+        return `the record for ${live.env} names pull request ${live.pr}, not ${pr}, so pr-env down --pr ${pr} does not tear it down`;
+    if (!isPrEnvironmentName(live.marker.env) || live.marker.env !== env) {
+        return `the record for ${env} names the marker env ${JSON.stringify(live.marker.env)}, which is not ${env}, so its teardown would select another environment's resources; nothing was torn down`;
+    }
+    const literal = (declared ?? []).find((e) => !isEnvironmentPattern(environmentName(e)) && environmentName(e) === env);
+    if (literal)
+        return `${env} is declared outright in chant.config.ts's environments, so it is not a pull request's to tear down; nothing was torn down`;
+    return undefined;
+}
+/**
+ * The entries of a teardown plan the environment owns: those whose marker
+ * is exactly `marker`. `planTeardown` already selects on the marker; this
+ * is the second check, so a lexicon that returned another's resources cannot
+ * widen what pr-env down deletes. `dropped` counts what was left out.
+ */
+export function ownedEntries(plan, marker) {
+    const owns = (e) => e.marker?.stack === marker.stack && e.marker?.env === marker.env;
+    return { plan: { ...plan, entries: plan.entries.filter(owns) }, dropped: plan.entries.filter((e) => !owns(e)) };
+}
+/**
+ * Tear down pull request `pr`'s environment with the ownership check: refused
+ * before any read when {@link teardownRefusal} says so; otherwise the live
+ * resources under the record's marker are planned, every entry whose marker
+ * is not exactly `{ stack, env: "pr-<n>" }` is dropped ({@link ownedEntries}),
+ * and only the rest go to each lexicon's teardown. The endpoint is the one
+ * the environment was applied at: its own `pr-*` entry's, else the template's.
+ */
+export async function tearDownPrEnvironment(input) {
+    const { pr, live, config, plugins } = input;
+    const refusal = teardownRefusal(pr, live, config.environments);
+    if (refusal)
+        return { refusal };
+    const env = prEnvironmentName(pr);
+    const marker = { stack: live.marker.stack, env };
+    const endpoint = environmentEndpoint(config.environments, env) ?? environmentEndpoint(config.environments, live.template);
+    const applied = applyLiveEndpoint(endpoint ? [{ name: env, endpoint }] : [], env, plugins.filter((x) => x.teardownOwned || x.describeResources || x.executeTeardown));
+    if (applied.notice)
+        input.warn?.(applied.notice);
+    const deployedStacks = (config.stacks ?? []).map((s) => ({ name: s.name, ...(s.region ? { region: s.region } : {}) }));
+    try {
+        const planned = await planTeardown({ environment: env, stack: marker.stack, plugins, ...(deployedStacks.length > 0 ? { deployedStacks } : {}) });
+        const owned = ownedEntries(planned, marker);
+        const report = await executeTeardown({ environment: env, stack: marker.stack, plugins, plan: owned.plan, ...(deployedStacks.length > 0 ? { deployedStacks } : {}) });
+        return { report, dropped: owned.dropped.length, marker };
+    }
+    finally {
+        applied.restore();
+    }
+}
+/** A teardown report's counts for the record. */
+export function teardownCounts(report) {
+    const n = (o) => report.outcomes.filter((x) => x.outcome === o).length;
+    return { deleted: n("deleted"), failed: n("failed"), retained: n("retained"), notPrunable: n("not-prunable"), skipped: n("skipped"), holes: report.plan.holes.length };
+}
+/**
+ * Whether a teardown left the environment clean: nothing failed, nothing was
+ * skipped for a lexicon with no teardown execution, and the plan had no
+ * holes. A retained resource (a lexicon's deliberate keep) does not count
+ * against it.
+ */
+export function teardownComplete(report) {
+    const c = teardownCounts(report);
+    return c.failed === 0 && c.skipped === 0 && c.holes === 0;
+}
+/**
+ * The record `pr-env up --no-push` handed on, checked as data: the up job ran
+ * the change's code, so what it wrote is the change's. It must be an `up`
+ * line for this pull request's `pr-<n>`, with that marker env, the template
+ * the base declares, and string components. The commit, the actor, the run
+ * and the expiry are the post job's own, so a change cannot keep its
+ * environment past the TTL its base set. Refused otherwise, and kept nowhere.
+ */
+export function acceptHandedRecord(raw, check) {
+    const env = prEnvironmentName(check.pr);
+    const [r] = parsePrEnvRecords(typeof raw === "object" && raw !== null ? JSON.stringify(raw) : "");
+    if (!r)
+        return { refusal: "The env-up job handed on a record that does not read, so it was not kept." };
+    const why = r.kind !== "up" ? `is a ${r.kind} record`
+        : r.pr !== check.pr || r.env !== env ? `names ${r.env} of pull request ${r.pr}, not ${env}`
+            : r.marker.env !== env ? `names the marker env ${JSON.stringify(r.marker.env)}, not ${env}`
+                : r.template !== check.template ? `names the template ${r.template}, and the base declares ${check.template}`
+                    : (r.member ?? undefined) !== check.member ? `names the member ${r.member ?? "(none)"}`
+                        : !Array.isArray(r.components) || r.components.some((c) => typeof c !== "string") ? "lists components that are not names"
+                            : r.result !== "applied" && r.result !== "failed" ? `has the result ${r.result}`
+                                : undefined;
+    if (why)
+        return { refusal: `The env-up job handed on a record that ${why}, so it was not kept.` };
+    return {
+        record: {
+            version: 1,
+            kind: "up",
+            pr: check.pr,
+            env,
+            ...(check.member ? { member: check.member } : {}),
+            template: check.template,
+            marker: { stack: r.marker.stack, env },
+            commit: check.head,
+            components: [...r.components],
+            planDigest: typeof r.planDigest === "string" ? r.planDigest : "",
+            result: r.result,
+            by: check.by,
+            timestamp: check.now.toISOString(),
+            expiresAt: new Date(check.now.getTime() + check.ttlMs).toISOString(),
+            ...(Array.isArray(r.approvedBy) ? { approvedBy: r.approvedBy.filter((a) => typeof a === "string") } : {}),
+            releaseTarget: false,
+            ...(check.runUrl ? { runUrl: check.runUrl } : {}),
+        },
+    };
+}
+/**
+ * The report `pr-env up` handed on, checked as data before the post job
+ * renders a note from it: an `up` report for this pull request's `pr-<n>`.
+ * Its head is the post job's own.
+ */
+export function handedPrEnvReport(raw, check) {
+    const env = prEnvironmentName(check.pr);
+    if (typeof raw !== "object" || raw === null)
+        return { refusal: "The env-up job handed on no report." };
+    const r = raw;
+    if (r.stage !== "up" || r.pr !== check.pr || r.env !== env)
+        return { refusal: `The env-up job handed on a report that is not ${env}'s.` };
+    const statuses = ["applied", "nothing", "waiting", "changed", "plan-failed", "failed", "refused"];
+    if (!r.status || !statuses.includes(r.status))
+        return { refusal: "The env-up job handed on a report with no status it could have." };
+    const str = (v) => (typeof v === "string" ? v : "");
+    const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+    return {
+        report: {
+            stage: "up",
+            pr: check.pr,
+            env,
+            ...(check.member ? { member: check.member } : {}),
+            template: str(r.template),
+            head: check.head,
+            op: check.member ? `pr-${check.pr}-${check.member}` : `pr-${check.pr}`,
+            gate: PR_ENV_GATE,
+            digest: str(r.digest),
+            status: r.status,
+            ...(typeof r.message === "string" ? { message: r.message } : {}),
+            ...(typeof r.endpoint === "string" ? { endpoint: r.endpoint } : {}),
+            components: (Array.isArray(r.components) ? r.components : []).map((c) => ({ component: str(c?.component), status: str(c?.status), create: num(c?.create), update: num(c?.update), replace: num(c?.replace), delete: num(c?.delete) })),
+            ...(Array.isArray(r.approvedBy) ? { approvedBy: r.approvedBy.filter((a) => typeof a === "string") } : {}),
+        },
+    };
+}
+const code = (s) => "`" + s.replaceAll("`", "'") + "`";
+/** The environment's note on the pull request: one per environment, updated in place. */
+export function renderPrEnvNote(r, approver = "<you>") {
+    const out = [prEnvNoteMarker(r.env, r.member), `### chant pull request environment ${code(r.env)}${r.member ? ` in member ${code(r.member)}` : ""}`, ""];
+    const from = `derived from ${code(r.template)}${r.endpoint ? ` at ${code(r.endpoint)}` : ""}`;
+    switch (r.status) {
+        case "applied":
+            out.push(`Applied ${r.components.length} component${r.components.length === 1 ? "" : "s"} at ${code(r.head.slice(0, 12))}, ${from}. It expires ${r.expiresAt ?? "?"}, and closing the pull request tears it down before then.`);
+            break;
+        case "nothing":
+            out.push(`Nothing this change touches is deployed by a component, so ${code(r.env)} gets nothing.`);
+            break;
+        case "waiting":
+        case "changed":
+            out.push(r.status === "changed" ? `An approval stands for another plan of ${code(r.env)}; the plan changed since, so nothing applied.` : `Planned ${code(r.env)}, ${from}. It waits for an approval of its plan; nothing applied.`);
+            out.push("", "A reviewer who read the plan approves it with:", "", "```", prEnvApproveCommand(r.op, r.digest, approver), "```", "", "Then run the job again, or push to the pull request.");
+            break;
+        case "destroyed":
+            out.push(`Torn down: ${r.outcomes?.deleted ?? 0} resource${r.outcomes?.deleted === 1 ? "" : "s"} carrying the marker of ${code(r.env)} deleted.`);
+            break;
+        case "incomplete":
+            out.push(`The teardown of ${code(r.env)} left something (${r.outcomes?.failed ?? 0} failed, ${r.outcomes?.skipped ?? 0} skipped, ${r.outcomes?.holes ?? 0} unread). It stays live, and the next sweep tries again.`);
+            break;
+        case "absent":
+            out.push(`${code(r.env)} has no live record, so there is nothing to tear down.`);
+            break;
+        default:
+            out.push(`The ${r.stage} of ${code(r.env)} ${r.status === "plan-failed" ? "failed to plan" : r.status === "refused" ? "was refused" : "failed"}.`);
+    }
+    if (r.message)
+        out.push("", `> ${r.message.split("\n").join("\n> ")}`);
+    if (r.components.length > 0) {
+        out.push("", "| Component | Status | Create | Update | Replace | Delete |", "|---|---|---:|---:|---:|---:|");
+        for (const c of r.components)
+            out.push(`| ${code(c.component)} | ${c.status} | ${c.create} | ${c.update} | ${c.replace} | ${c.delete} |`);
+    }
+    if (r.digest)
+        out.push("", `Plan digest: ${code(r.digest)}${r.approvedBy?.length ? `, approved by ${r.approvedBy.map(code).join(", ")}` : ""}`);
+    out.push("", `${code(r.env)} is not a release target: releases come from green commits.`);
+    return out.join("\n") + "\n";
+}
+/** The commit status a report sets: success, failure, or pending while it waits on an approval. */
+export function prEnvStatusState(r) {
+    if (r.status === "waiting")
+        return "pending";
+    return r.status === "applied" || r.status === "nothing" || r.status === "destroyed" || r.status === "absent" ? "success" : "failure";
+}
+/** A commit status description, at most 140 characters. */
+export function prEnvStatusDescription(r) {
+    const what = {
+        applied: `${r.env} applied, expires ${r.expiresAt ?? "?"}`,
+        nothing: `${r.env}: nothing to deploy`,
+        waiting: `${r.env} waits for an approval of its plan`,
+        changed: `${r.env}: the plan changed after its approval`,
+        "plan-failed": `${r.env}: a component failed to plan`,
+        failed: `${r.env}: the ${r.stage} failed`,
+        refused: `${r.env}: refused`,
+        destroyed: `${r.env} torn down`,
+        incomplete: `${r.env}: the teardown left something; the sweep tries again`,
+        absent: `${r.env}: nothing to tear down`,
+    };
+    const text = what[r.status];
+    return text.length > 140 ? text.slice(0, 137) + "..." : text;
+}

package/dist/components/pr-hooks.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Stage hooks on the pull-request path (#4288): `ci.hooks` in the workspace
+ * declaration, run by `chant components pr-plan`, `pr-record` and
+ * `pr-apply` with the runner an Op waves job uses (`runStageHooks`).
+ *
+ * The hooks are read from the declaration at the base the job measures the
+ * change from, never from the change itself, so a pull request cannot add,
+ * edit or remove a hook its own jobs run. The top level's hooks run first,
+ * then those of the member the job runs in. When the base has no workspace
+ * declaration no hook runs. When the declaration at base cannot be read and
+ * the working tree's names hooks, the job refuses to run rather than guess.
+ *
+ * The runs a hook sees are the components the change selects, in apply
+ * order: `{target}` and `CHANT_TARGET` name one, and `targets` match their
+ * names. After the plan, a `perRun` hook's `{plan}` is a JSON file with that
+ * component's members and the plans its steps hand the apply.
+ */
+import type { OpWaveHook, OpWaveHookMoment } from "../op/op-waves.js";
+import { type OpWaveExec } from "../op/op-waves-run.js";
+import { type Declaration } from "../workspace/declaration.js";
+import type { PrHookOutcome, PrMember } from "../pr-loop.js";
+/** The hooks a pull-request job runs, by moment, and where they were read. */
+export interface PrLoopHooks {
+    hooks: Partial<Record<OpWaveHookMoment, OpWaveHook[]>>;
+    /** The commit they were read at. */
+    base: string;
+    /** A line for the log when none run because the base has no declaration, or could not be read. */
+    note?: string;
+}
+/** The hooks `declaration` gives a job run in `cwd`: the top level's, then the member's. */
+export declare function prLoopHooksOf(declaration: Pick<Declaration, "ci" | "members">, member: string | null): Partial<Record<OpWaveHookMoment, OpWaveHook[]>>;
+/**
+ * The hooks a pull-request job in `cwd` runs, read from the workspace
+ * declaration at `base`. Throws when the declaration at base cannot be read
+ * and the working tree's names hooks.
+ */
+export declare function prLoopHooksAt(cwd: string, base: string): PrLoopHooks;
+/** Where a pull-request job's hooks run, and what they are told. */
+export interface PrHookPlace {
+    /** The gate's op, `pr-<n>`: `{op}` and `CHANT_OP_WAVES`. */
+    op: string;
+    /** The environment: `{wave}`, `CHANT_WAVE` and `CHANT_ENV`. */
+    env: string;
+    stage: "plan" | "apply" | "record";
+    /** The report directory, relative to `cwd`; the runs and plan files go under `<dir>/hooks`. */
+    dir: string;
+    cwd: string;
+    exec?: OpWaveExec;
+    log?: (line: string) => void;
+}
+/** What one moment's hooks came to on the pull-request path. */
+export interface PrHooksRun {
+    outcomes: PrHookOutcome[];
+    failed?: string;
+    holds: string[];
+}
+/**
+ * Run the hooks of `moment` for `components` (#4288). `plans`, after the
+ * plan, gives each component's members and step plans, written where a
+ * `perRun` hook's `{plan}` points.
+ */
+export declare function runPrHooks(read: PrLoopHooks, moment: OpWaveHookMoment, place: PrHookPlace, components: readonly string[], planned?: {
+    members: readonly PrMember[];
+    plans: Record<string, Record<string, unknown>>;
+}): PrHooksRun;
+//# sourceMappingURL=pr-hooks.d.ts.map

package/dist/components/pr-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pr-hooks.d.ts","sourceRoot":"","sources":["../../src/components/pr-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAe,MAAM,gBAAgB,CAAC;AAEhF,OAAO,EAAiB,KAAK,UAAU,EAA0C,MAAM,oBAAoB,CAAC;AAC5G,OAAO,EAAuC,KAAK,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGjG,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE1D,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC;IACvD,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,kGAAkG;IAClG,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAQD,4FAA4F;AAC5F,wBAAgB,aAAa,CAAC,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,UAAU,EAAE,CAAC,CAAC,CAQtJ;AAaD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAiBpE;AAED,oEAAoE;AACpE,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAC;IACX,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IACnC,+FAA+F;IAC/F,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED,gEAAgE;AAChE,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,OAAO,CAAC,EAAE;IAAE,OAAO,EAAE,SAAS,QAAQ,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAAE,GACzF,UAAU,CAmCZ"}

package/dist/components/pr-hooks.js

@@ -0,0 +1,119 @@
+/**
+ * Stage hooks on the pull-request path (#4288): `ci.hooks` in the workspace
+ * declaration, run by `chant components pr-plan`, `pr-record` and
+ * `pr-apply` with the runner an Op waves job uses (`runStageHooks`).
+ *
+ * The hooks are read from the declaration at the base the job measures the
+ * change from, never from the change itself, so a pull request cannot add,
+ * edit or remove a hook its own jobs run. The top level's hooks run first,
+ * then those of the member the job runs in. When the base has no workspace
+ * declaration no hook runs. When the declaration at base cannot be read and
+ * the working tree's names hooks, the job refuses to run rather than guess.
+ *
+ * The runs a hook sees are the components the change selects, in apply
+ * order: `{target}` and `CHANT_TARGET` name one, and `targets` match their
+ * names. After the plan, a `perRun` hook's `{plan}` is a JSON file with that
+ * component's members and the plans its steps hand the apply.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { PR_LOOP_HOOK_MOMENTS } from "../op/op-waves.js";
+import { runStageHooks } from "../op/op-waves-run.js";
+import { readDeclaration, WorkspaceReadError } from "../workspace/declaration.js";
+import { memberAtCwd } from "../workspace/security.js";
+import { locateWorkspace } from "../workspace/which-chant.js";
+/** The hooks of one `ci.hooks` block at `moment`. */
+function at(hooks, moment) {
+    const [side, stage] = moment.split("-");
+    return (hooks?.[side]?.[stage]) ?? [];
+}
+/** The hooks `declaration` gives a job run in `cwd`: the top level's, then the member's. */
+export function prLoopHooksOf(declaration, member) {
+    const own = member === null ? null : (declaration.members.find((m) => m.name === member)?.ciHooks ?? null);
+    const out = {};
+    for (const moment of PR_LOOP_HOOK_MOMENTS) {
+        const list = [...at(declaration.ci?.hooks, moment), ...at(own, moment)];
+        if (list.length > 0)
+            out[moment] = list;
+    }
+    return out;
+}
+/** Whether the working tree's declaration names any `ci.hooks`. */
+function checkoutNamesHooks(cwd) {
+    try {
+        const located = locateWorkspace(cwd);
+        const d = readDeclaration(located.tree);
+        return Object.keys(prLoopHooksOf(d, memberAtCwd({ declaration: d, rootOnDisk: located.rootOnDisk }, cwd))).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The hooks a pull-request job in `cwd` runs, read from the workspace
+ * declaration at `base`. Throws when the declaration at base cannot be read
+ * and the working tree's names hooks.
+ */
+export function prLoopHooksAt(cwd, base) {
+    let declaration;
+    let rootOnDisk;
+    try {
+        const located = locateWorkspace(cwd, base);
+        declaration = readDeclaration(located.tree);
+        rootOnDisk = located.rootOnDisk;
+    }
+    catch (err) {
+        const missing = err instanceof WorkspaceReadError && (err.code === "declaration-missing" || err.code === "not-a-git-repository");
+        const why = err instanceof Error ? err.message : String(err);
+        if (checkoutNamesHooks(cwd)) {
+            if (missing)
+                return { hooks: {}, base, note: `ci.hooks: the base ${base.slice(0, 12)} has no workspace declaration, so the hooks this change declares do not run until it merges` };
+            throw new Error(`ci.hooks are read from the workspace declaration at ${base.slice(0, 12)}, and it could not be read (${why}), so no hook can be trusted to run`);
+        }
+        return missing ? { hooks: {}, base } : { hooks: {}, base, note: `ci.hooks: the declaration at ${base.slice(0, 12)} could not be read (${why}); this checkout names no hooks, so none run` };
+    }
+    return { hooks: prLoopHooksOf(declaration, memberAtCwd({ declaration, rootOnDisk }, cwd)), base };
+}
+/**
+ * Run the hooks of `moment` for `components` (#4288). `plans`, after the
+ * plan, gives each component's members and step plans, written where a
+ * `perRun` hook's `{plan}` points.
+ */
+export function runPrHooks(read, moment, place, components, planned) {
+    const hooks = read.hooks[moment];
+    if (!hooks || hooks.length === 0)
+        return { outcomes: [], holds: [] };
+    // Relative to cwd, as an Op waves job's paths are, whether --output was given relative or absolute.
+    const dir = relative(place.cwd, resolve(place.cwd, place.dir, "hooks")) || ".";
+    mkdirSync(join(place.cwd, dir, "plans"), { recursive: true });
+    const runs = components.map((component) => {
+        if (!planned)
+            return { target: component, op: place.op };
+        const plan = join(dir, "plans", `${component.replace(/[^A-Za-z0-9._-]/g, "_")}.json`);
+        const body = { component, members: planned.members.filter((m) => m.component === component), plans: planned.plans[component] ?? {} };
+        writeFileSync(join(place.cwd, plan), JSON.stringify(body, null, 2) + "\n");
+        return { target: component, op: place.op, plan };
+    });
+    const runsFile = join(dir, "runs.json");
+    writeFileSync(join(place.cwd, runsFile), JSON.stringify({ version: 1, op: place.op, env: place.env, stage: place.stage, base: read.base, hook: moment, runs }, null, 2) + "\n");
+    const ran = runStageHooks(moment, hooks, {
+        name: place.op,
+        op: place.op,
+        wave: place.env,
+        runs,
+        runsFile,
+        holdFile: join(dir, "hold.json"),
+        env: { CHANT_ENV: place.env, CHANT_PR_STAGE: place.stage, CHANT_HOOKS_BASE: read.base },
+        cwd: place.cwd,
+        ...(place.exec ? { exec: place.exec } : {}),
+        ...(place.log ? { log: place.log } : {}),
+    });
+    const outcomes = ran.outcomes.map((o) => ({
+        moment: o.moment,
+        name: o.name,
+        ...(o.target ? { target: o.target } : {}),
+        exit: o.exit,
+        outcome: o.outcome === "failed" ? "failed" : o.outcome === "held" ? "held" : "passed",
+    }));
+    return { outcomes, ...(ran.failed ? { failed: ran.failed } : {}), holds: ran.holds };
+}