@intentius/chant 0.124.39 → 0.124.41

package/dist/cli/handlers/pr-env.js

@@ -0,0 +1,436 @@
+/**
+ * `chant components pr-env up|down|sweep` (#4298): an environment per open
+ * pull request, `pr-<n>`, derived from `ci.prEnvironment.template`
+ * (../../components/pr-environment.ts says what each does and why).
+ *
+ * ```
+ * chant components pr-env up    --base <ref> --pr <n> [--forge <kind>] [--member <name>] [--output <dir>] [--no-push]
+ * chant approve pr-<n> pr-env --plan <digest> --approver <you> --sign
+ * chant components pr-env down  --pr <n> [--reason closed|expired] [--forge <kind>] [--member <name>]
+ * chant components pr-env post  --pr <n> --head <sha> [--result <r>] --forge <kind>
+ * chant components pr-env sweep [--forge <kind>]
+ * ```
+ *
+ * In the generated jobs (#4295) `up` runs the change's code with no forge
+ * token, so it passes `--no-push` and hands its report and record on, and
+ * `post` runs in a fresh job at the target branch's commit, appends the
+ * record and posts the note.
+ *
+ * `up` prepares the change as `pr-plan` does, with `--env pr-<n>` and the
+ * build parameter `ownership.env` reads set to `pr-<n>`, so every resource
+ * the apply creates carries that environment's marker. It applies only when
+ * the plan is empty or an approval of its digest stands under gate `pr-env`,
+ * since a non-empty plan never applies with no person approving (ws-080).
+ *
+ * `down` reads the environment's record on chant/lifecycle, checks it names
+ * this pull request's environment, and tears down what `planTeardown` finds
+ * under the record's marker, after dropping any entry whose marker is not
+ * exactly that one. No gate holds it: closing the pull request is the
+ * decision, as is the TTL the base set for `sweep`.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { loadChantConfig } from "../../config.js";
+import { ENV_VAR } from "../../env.js";
+import { isEmptyChangeSet } from "../../change-set.js";
+import { PR_ENV_EXIT, PR_ENV_GATE, PR_ENV_LEDGER_DIR, PR_ENV_LEDGER_FILE, PR_ENV_RECORD_FILE, PR_ENV_REPORT_DIR, acceptHandedRecord, handedPrEnvReport, PR_ENV_TEMPLATE_VAR, derivePrEnvironment, expired, livePrEnvironments, parsePrEnvRecords, prEnvApproveCommand, prEnvNoteMarker, prEnvStatusContext, prEnvStatusDescription, prEnvStatusState, prEnvironmentName, renderPrEnvNote, teardownComplete, teardownCounts, tearDownPrEnvironment, ttlMs, } from "../../components/pr-environment.js";
+import { applyPrSet, approvalOf, decidePrGate, readOnlyLedger } from "../../components/pr-run.js";
+import { gitGateLedgerPort } from "../../op/gate.js";
+import { prOp } from "../../pr-loop.js";
+import { FORGE_KINDS, forgeFromEnv, forgePrincipalOf } from "../../pr-forge.js";
+import { formatError, formatInfo, formatWarning } from "../format.js";
+import { withComponentEndpoint } from "../component-endpoint.js";
+const USAGE = "chant components pr-env up --base <ref> --pr <n> [--no-push] | post --pr <n> --head <sha> | down --pr <n> [--reason closed|expired] | sweep";
+const fail = (message, hint) => {
+    console.error(formatError({ message, ...(hint ? { hint } : {}) }));
+    return PR_ENV_EXIT.failed;
+};
+/** chant components pr-env <up|down|sweep> */
+export async function runComponentsPrEnv(ctx) {
+    const action = ctx.args.extraPositional;
+    if (action === "up")
+        return prEnvUp(ctx);
+    if (action === "down")
+        return prEnvDown(ctx);
+    if (action === "sweep")
+        return prEnvSweep(ctx);
+    if (action === "post")
+        return prEnvPost(ctx);
+    return fail(action ? `pr-env ${action} is not one of up, post, down or sweep` : "pr-env needs an action: up, post, down or sweep", USAGE);
+}
+function forgeOf(ctx) {
+    const kind = ctx.args.forge;
+    if (kind === undefined || ctx.args.noStatus)
+        return undefined;
+    if (!FORGE_KINDS.includes(kind))
+        return fail(`--forge ${kind} is not one of ${FORGE_KINDS.join(", ")}`);
+    try {
+        return forgeFromEnv(kind);
+    }
+    catch (err) {
+        return fail(err instanceof Error ? err.message : String(err));
+    }
+}
+function actor() {
+    return process.env.GITHUB_ACTOR || process.env.GITLAB_USER_LOGIN || process.env.USER || "chant";
+}
+function memberOf(ctx) {
+    return ctx.args.members?.length === 1 ? ctx.args.members[0] : undefined;
+}
+// ── the ledger ─────────────────────────────────────────────────────────────
+async function readRecords() {
+    const { fetchLifecycle, readBlobFromPath } = await import("../../lifecycle/git.js");
+    await fetchLifecycle().catch(() => false);
+    return parsePrEnvRecords(await readBlobFromPath(PR_ENV_LEDGER_DIR, PR_ENV_LEDGER_FILE));
+}
+/**
+ * Append `record` to chant/lifecycle and push it. With `--no-push` (#4295)
+ * the record is written to `pr-env-record.json` under `--output` instead,
+ * for `pr-env post` to append from a job that runs none of the change's
+ * code. A failure warns: what was applied or torn down stands.
+ */
+async function appendRecord(ctx, record) {
+    if (ctx.args.noPush) {
+        const dir = resolve(ctx.args.output ?? PR_ENV_REPORT_DIR);
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, PR_ENV_RECORD_FILE), JSON.stringify(record, null, 2) + "\n");
+        return;
+    }
+    const { appendLedgerLine, fetchLifecycle, pushLifecycleReport } = await import("../../lifecycle/git.js");
+    try {
+        await fetchLifecycle().catch(() => false);
+        await appendLedgerLine(PR_ENV_LEDGER_DIR, PR_ENV_LEDGER_FILE, JSON.stringify(record), `Pull request environment ${record.env} ${record.kind} (${record.result})`);
+        const pushed = await pushLifecycleReport();
+        if (pushed.pushWarning)
+            console.error(formatWarning({ message: pushed.pushWarning }));
+    }
+    catch (err) {
+        console.error(formatWarning({ message: `could not record ${record.env}'s ${record.kind} on chant/lifecycle: ${err instanceof Error ? err.message : String(err)}` }));
+    }
+}
+// ── the report and the note ────────────────────────────────────────────────
+async function finish(ctx, forge, report) {
+    const dir = resolve(ctx.args.output ?? PR_ENV_REPORT_DIR);
+    mkdirSync(dir, { recursive: true });
+    const note = renderPrEnvNote(report, forge ? forgePrincipalOf(forge.kind, forge.host, "<your-login>") : "<you>");
+    writeFileSync(join(dir, `pr-env-${report.stage}.json`), JSON.stringify(report, null, 2) + "\n");
+    writeFileSync(join(dir, "pr-env-note.md"), note);
+    if (ctx.args.json)
+        console.log(JSON.stringify(report, null, 2));
+    if (!forge)
+        return;
+    if (report.head) {
+        try {
+            await forge.setStatus(report.head, {
+                context: prEnvStatusContext(report.member),
+                state: prEnvStatusState(report),
+                description: prEnvStatusDescription(report),
+                ...(forge.runUrl ? { url: forge.runUrl } : {}),
+            });
+        }
+        catch (err) {
+            console.error(formatWarning({ message: `could not set the ${prEnvStatusContext(report.member)} status: ${err instanceof Error ? err.message : String(err)}` }));
+        }
+    }
+    try {
+        await forge.upsertNote(report.pr, prEnvNoteMarker(report.env, report.member), note);
+    }
+    catch (err) {
+        console.error(formatWarning({ message: `could not post the note on #${report.pr}: ${err instanceof Error ? err.message : String(err)}` }));
+    }
+}
+// ── up ─────────────────────────────────────────────────────────────────────
+async function prEnvUp(ctx) {
+    const { args } = ctx;
+    if (args.pr === undefined)
+        return fail("pr-env up needs the pull or merge request: --pr <n>", "The environment is pr-<n>, and its approval is recorded under op pr-<n>.");
+    if (!args.base)
+        return fail("pr-env up needs the commit the change is measured from: --base <ref>", "On a pull request, the target branch's commit. ci.prEnvironment is read from the declaration there.");
+    const pr = args.pr;
+    const projectPath = resolve(".");
+    // The settings at base, never the pull request's own: a change cannot name another template or a longer TTL.
+    const { scopeSource } = await import("../../workspace/write-scope.js");
+    const source = scopeSource(projectPath, args.base);
+    const setting = source.from === "base" ? source.declaration?.ci?.prEnvironment : undefined;
+    if (!setting) {
+        return fail(`the workspace declaration at ${args.base.slice(0, 12)} names no ci.prEnvironment, so pull request ${pr} gets no environment`, 'Declare ci.prEnvironment: { "template": "<env>" } in chant.workspace.json and merge it first.');
+    }
+    const { config } = await loadChantConfig(projectPath).catch(() => ({ config: {} }));
+    const derived = derivePrEnvironment(config, setting.template, pr);
+    if ("refusal" in derived)
+        return fail(derived.refusal);
+    const ttl = ttlMs(setting.ttl) ?? ttlMs("72h");
+    // The build sees pr-<n> as its environment and the template's name beside it.
+    process.env[ENV_VAR] = derived.env;
+    process.env[PR_ENV_TEMPLATE_VAR] = derived.template;
+    const envCtx = {
+        ...ctx,
+        args: { ...args, env: derived.env, param: [...(args.param ?? []).filter((p) => !p.startsWith(`${derived.param}=`)), `${derived.param}=${derived.env}`] },
+    };
+    console.error(formatInfo(`pr-env up: ${derived.env}, derived from ${derived.template}${derived.endpoint ? ` at ${derived.endpoint}` : ""}, marker ${derived.stack}/${derived.env}`));
+    return withComponentEndpoint(envCtx, () => up(envCtx, pr, derived, ttl), { config: { ...config, environments: derived.environments }, environment: derived.env });
+}
+async function up(ctx, pr, derived, ttl) {
+    const { prepare, planAll, placeHooks, runStageHook } = await import("./pr.js");
+    const p = await prepare(ctx, "plan");
+    if (typeof p === "number")
+        return p;
+    const forge = p.forge;
+    const op = prOp(pr, p.member);
+    // ci.hooks (#4288), read at base as the other pull-request jobs read them, around the plan and the apply.
+    placeHooks(ctx, p, "apply", op);
+    const base = {
+        stage: "up",
+        pr,
+        env: derived.env,
+        ...(p.member ? { member: p.member } : {}),
+        template: derived.template,
+        head: p.head,
+        op,
+        gate: PR_ENV_GATE,
+        digest: "",
+        status: "nothing",
+        ...(derived.endpoint ? { endpoint: derived.endpoint } : {}),
+        components: [],
+    };
+    if (p.plan.order.length === 0) {
+        await finish(ctx, forge, { ...base, ...(p.routedAway ? { message: p.routedAway } : {}) });
+        console.error(formatInfo(`pr-env up: nothing this change touches is deployed by a component, so ${derived.env} gets nothing`));
+        return PR_ENV_EXIT.done;
+    }
+    const set = await planAll(p);
+    const rows = (status) => p.plan.order.map((component) => {
+        const ms = set.members.filter((m) => m.component === component);
+        const sum = (k) => ms.reduce((n, m) => n + m.counts[k], 0);
+        return { component, status: status(component), create: sum("create"), update: sum("update"), replace: sum("replace"), delete: sum("delete") };
+    });
+    const digest = set.doc.digest;
+    if (set.failed) {
+        await finish(ctx, forge, { ...base, digest, status: "plan-failed", ...(p.hookFailed ? { message: p.hookFailed } : {}), components: rows((c) => (set.members.some((m) => m.component === c && m.status === "plan-failed") ? "plan failed" : "planned")) });
+        return PR_ENV_EXIT.failed;
+    }
+    // ws-080, ws-104: a non-empty plan applies only under a person's approval of its digest. An empty one passes.
+    let approvedBy;
+    if (!isEmptyChangeSet(set.doc)) {
+        let approval;
+        try {
+            approval = approvalOf(await decidePrGate(readOnlyLedger(gitGateLedgerPort()), { op, gate: PR_ENV_GATE, digest, description: `${derived.env}: ${p.plan.order.join(", ")}` }));
+        }
+        catch (err) {
+            return fail(`could not read the gate ledger, so ${derived.env} does not apply: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (approval.status !== "approved") {
+            const status = approval.status === "changed" ? "changed" : "waiting";
+            await finish(ctx, forge, { ...base, digest, status, components: rows(() => "planned") });
+            console.error(formatInfo(`pr-env up: ${derived.env} waits for an approval of ${digest}`));
+            console.error(formatInfo(`approve : ${prEnvApproveCommand(op, digest)}`));
+            return PR_ENV_EXIT.waiting;
+        }
+        approvedBy = approval.approvedBy ?? [];
+    }
+    const hookStop = runStageHook(p, "before-apply", p.plan.order, set);
+    if (hookStop) {
+        await finish(ctx, forge, { ...base, digest, status: "failed", message: hookStop, components: rows(() => "planned"), ...(approvedBy ? { approvedBy } : {}) });
+        return PR_ENV_EXIT.failed;
+    }
+    const applied = await applyPrSet({ components: p.components, plan: p.plan, registry: p.registry, env: derived.env, set, gate: PR_ENV_GATE });
+    const afterHook = runStageHook(p, "after-apply", p.plan.order, set, "the environment stands as applied");
+    const status = (component) => applied.members.find((m) => m.component === component)?.status ?? "planned";
+    const ok = applied.status === "applied";
+    const now = new Date();
+    const expiresAt = new Date(now.getTime() + ttl).toISOString();
+    // A copy that failed part way is live too: what applied is torn down on close or at expiry like the rest.
+    await appendRecord(ctx, {
+        version: 1,
+        kind: "up",
+        pr,
+        env: derived.env,
+        ...(p.member ? { member: p.member } : {}),
+        template: derived.template,
+        marker: { stack: derived.stack, env: derived.env },
+        commit: p.head,
+        components: p.plan.order,
+        planDigest: digest,
+        result: ok ? "applied" : "failed",
+        by: actor(),
+        timestamp: now.toISOString(),
+        expiresAt,
+        ...(approvedBy ? { approvedBy } : {}),
+        releaseTarget: false,
+        ...(forge?.runUrl ? { runUrl: forge.runUrl } : {}),
+    });
+    await finish(ctx, forge, {
+        ...base,
+        digest,
+        status: ok ? "applied" : "failed",
+        components: rows(status),
+        ...(approvedBy ? { approvedBy } : {}),
+        expiresAt,
+        ...(ok ? (afterHook ? { message: afterHook } : {}) : { message: applied.status === "waiting" ? "A component read an upstream output that moved when it applied; run the job again to plan it against the new value." : "A component failed to apply; what applied stays in the environment and is torn down with it." }),
+    });
+    console.error((ok ? formatInfo : (m) => formatWarning({ message: m }))(`pr-env up: ${derived.env} ${ok ? "applied" : applied.status}; it expires ${expiresAt}`));
+    return ok && !afterHook ? PR_ENV_EXIT.done : PR_ENV_EXIT.failed;
+}
+// ── post ───────────────────────────────────────────────────────────────────
+/**
+ * `pr-env post --pr <n> --head <sha> [--result <r>]` (#4295): from a job at
+ * the target branch's commit that runs none of the change's code, take the
+ * report and the record `pr-env up --no-push` handed on, check the record
+ * as data against the settings at this commit, append it to chant/lifecycle,
+ * and post the note and the `chant/pr-env` status with the forge token the
+ * up job never held.
+ */
+async function prEnvPost(ctx) {
+    const { args } = ctx;
+    if (args.pr === undefined || !args.head)
+        return fail("pr-env post needs the pull request and the commit its environment was applied from: --pr <n> --head <sha>");
+    const forge = forgeOf(ctx);
+    if (typeof forge === "number")
+        return forge;
+    const pr = args.pr;
+    const env = prEnvironmentName(pr);
+    const member = memberOf(ctx);
+    const dir = resolve(args.output ?? PR_ENV_REPORT_DIR);
+    const read = (name) => {
+        try {
+            return JSON.parse(readFileSync(join(dir, name), "utf-8"));
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const { scopeSource } = await import("../../workspace/write-scope.js");
+    const setting = scopeSource(resolve("."), "HEAD").declaration?.ci?.prEnvironment;
+    const handed = handedPrEnvReport(read("pr-env-up.json"), { pr, head: args.head, ...(member ? { member } : {}) });
+    const report = "report" in handed
+        ? handed.report
+        : { stage: "up", pr, env, ...(member ? { member } : {}), template: setting?.template ?? "", head: args.head, op: prOp(pr, member), gate: PR_ENV_GATE, digest: "", status: "failed", components: [], message: handed.refusal + (args.planResult && args.planResult !== "success" ? ` The env-up job's result is ${args.planResult}.` : "") };
+    const raw = read(PR_ENV_RECORD_FILE);
+    let code = "report" in handed ? (report.status === "waiting" || report.status === "changed" ? PR_ENV_EXIT.waiting : prEnvStatusState(report) === "failure" ? PR_ENV_EXIT.failed : PR_ENV_EXIT.done) : PR_ENV_EXIT.failed;
+    if (raw !== undefined) {
+        if (!setting) {
+            report.message = `${report.message ? `${report.message} ` : ""}The declaration here names no ci.prEnvironment, so the record was not kept.`;
+            code = PR_ENV_EXIT.failed;
+        }
+        else {
+            const accepted = acceptHandedRecord(raw, { pr, head: args.head, template: setting.template, ttlMs: ttlMs(setting.ttl) ?? ttlMs("72h"), now: new Date(), by: actor(), ...(member ? { member } : {}), ...(forge?.runUrl ? { runUrl: forge.runUrl } : {}) });
+            if ("refusal" in accepted) {
+                report.message = `${report.message ? `${report.message} ` : ""}${accepted.refusal}`;
+                code = PR_ENV_EXIT.failed;
+            }
+            else {
+                await appendRecord({ ...ctx, args: { ...args, noPush: false } }, accepted.record);
+                if (accepted.record.expiresAt)
+                    report.expiresAt = accepted.record.expiresAt;
+            }
+        }
+    }
+    await finish(ctx, forge, report);
+    return code;
+}
+// ── down ───────────────────────────────────────────────────────────────────
+async function prEnvDown(ctx) {
+    const { args } = ctx;
+    if (args.pr === undefined)
+        return fail("pr-env down needs the pull or merge request: --pr <n>");
+    const reason = args.reason ?? "closed";
+    if (reason !== "closed" && reason !== "expired")
+        return fail(`--reason ${reason} is not closed or expired`);
+    const forge = forgeOf(ctx);
+    if (typeof forge === "number")
+        return forge;
+    const live = livePrEnvironments(await readRecords()).get(prEnvironmentName(args.pr));
+    return teardown(ctx, forge, args.pr, live, reason);
+}
+async function teardown(ctx, forge, pr, live, reason) {
+    const env = prEnvironmentName(pr);
+    const member = memberOf(ctx);
+    const report = { stage: "down", pr, env, ...(member ? { member } : {}), template: live?.template ?? "", head: "", op: prOp(pr, member), gate: PR_ENV_GATE, digest: "", status: "absent", components: [] };
+    if (!live) {
+        console.error(formatInfo(`pr-env down: ${env} has no live record, so there is nothing to tear down`));
+        if (forge)
+            await finish(ctx, forge, report);
+        return PR_ENV_EXIT.done;
+    }
+    const { config } = await loadChantConfig(resolve(".")).catch(() => ({ config: {} }));
+    const torn = await tearDownPrEnvironment({ pr, live, config, plugins: ctx.plugins, warn: (message) => console.error(formatWarning({ message })) });
+    if ("refusal" in torn) {
+        await finish(ctx, forge, { ...report, template: live.template, status: "refused", message: torn.refusal });
+        return fail(torn.refusal);
+    }
+    const { report: result, dropped, marker } = torn;
+    const counts = teardownCounts(result);
+    const complete = teardownComplete(result);
+    const lexicons = [...new Set(result.outcomes.map((o) => o.lexicon))].sort();
+    const head = await headCommit();
+    await appendRecord(ctx, {
+        version: 1,
+        kind: "down",
+        pr,
+        env,
+        ...(live.member ? { member: live.member } : {}),
+        template: live.template,
+        marker,
+        commit: head,
+        components: lexicons,
+        planDigest: "",
+        result: complete ? "destroyed" : "incomplete",
+        by: actor(),
+        timestamp: new Date().toISOString(),
+        reason,
+        outcomes: counts,
+        releaseTarget: false,
+        ...(forge?.runUrl ? { runUrl: forge.runUrl } : {}),
+    });
+    const why = [];
+    if (dropped > 0)
+        why.push(`${dropped} candidate${dropped === 1 ? "" : "s"} whose marker was not ${marker.stack}/${env} left alone`);
+    if (result.unimplemented.length > 0)
+        why.push(`no teardown execution in ${result.unimplemented.join(", ")}`);
+    if (result.plan.holes.length > 0)
+        why.push(`${result.plan.holes.length} part${result.plan.holes.length === 1 ? "" : "s"} could not be read`);
+    for (const o of result.outcomes.filter((x) => x.outcome === "failed"))
+        why.push(`${o.lexicon} ${o.name}: ${o.detail ?? "failed"}`);
+    await finish(ctx, forge, { ...report, template: live.template, status: complete ? "destroyed" : "incomplete", outcomes: counts, ...(why.length > 0 ? { message: why.join("; ") } : {}) });
+    console.error((complete ? formatInfo : (m) => formatWarning({ message: m }))(`pr-env down: ${env} ${complete ? "torn down" : "not wholly torn down; it stays live and the sweep tries again"} (${counts.deleted} deleted, ${counts.failed} failed, ${counts.skipped} skipped)`));
+    return complete ? PR_ENV_EXIT.done : PR_ENV_EXIT.failed;
+}
+async function headCommit() {
+    const { spawnSync } = await import("node:child_process");
+    const r = spawnSync("git", ["rev-parse", "HEAD"], { encoding: "utf-8" });
+    return r.status === 0 ? r.stdout.trim() : "";
+}
+// ── sweep ──────────────────────────────────────────────────────────────────
+async function prEnvSweep(ctx) {
+    const forge = forgeOf(ctx);
+    if (typeof forge === "number")
+        return forge;
+    const live = [...livePrEnvironments(await readRecords()).values()];
+    if (live.length === 0) {
+        console.error(formatInfo("pr-env sweep: no pull request environment is live"));
+        return PR_ENV_EXIT.done;
+    }
+    const now = new Date();
+    let code = PR_ENV_EXIT.done;
+    for (const e of live) {
+        let reason = expired(e, now) ? "expired" : undefined;
+        if (!reason && forge?.pullRequestState) {
+            try {
+                const state = await forge.pullRequestState(e.pr);
+                if (state !== "open")
+                    reason = "closed";
+            }
+            catch (err) {
+                console.error(formatWarning({ message: `could not read whether #${e.pr} is open (${err instanceof Error ? err.message : String(err)}); its TTL still holds` }));
+            }
+        }
+        if (!reason) {
+            console.error(formatInfo(`pr-env sweep: ${e.env} stays; it expires ${e.expiresAt}`));
+            continue;
+        }
+        const c = await teardown(ctx, forge, e.pr, e, reason);
+        if (c !== PR_ENV_EXIT.done)
+            code = PR_ENV_EXIT.failed;
+    }
+    return code;
+}

package/dist/cli/handlers/pr.d.ts

@@ -63,13 +63,87 @@
  * all it uses one for; pr-apply still reads the pull request and its reviews
  * through `--forge`.
  */
+import { type ChantConfig } from "../../config.js";
+import { type PrPlanSet } from "../../components/pr-run.js";
+import { type RunEventSink } from "../../run-event-stream.js";
+import { type PrPolicyReport } from "../../pr-loop.js";
+import { type PrForge } from "../../pr-forge.js";
 import type { CommandContext } from "../registry.js";
+import type { ComponentChangeSignal, FanOutPlan } from "../../components/fan-out.js";
+import { type DriverComponent } from "../../components/driver.js";
+import type { CapabilityRegistry } from "../../components/capability.js";
+import { type PrHookPlace, type PrLoopHooks } from "../../components/pr-hooks.js";
+import { type PrLoopPolicy } from "../../components/pr-policy.js";
+import type { OpWaveHookMoment } from "../../op/op-waves.js";
+import type { PrHookOutcome } from "../../pr-loop.js";
 /** Where the reports land unless `--output` says. */
 export declare const PR_REPORT_DIR = ".chant/pr";
+export interface Prepared {
+    config: ChantConfig;
+    env: string;
+    /** The workspace member, with `--member` (#3465). */
+    member?: string;
+    base: string;
+    head: string;
+    gate: string;
+    forge?: PrForge;
+    /**
+     * Every component in the project, not the selection (`deriveFanOut`), so
+     * the plan reads the deployed outputs of a dependency the change did not
+     * select (#4104).
+     */
+    components: DriverComponent[];
+    plan: FanOutPlan;
+    signal: ComponentChangeSignal;
+    registry: CapabilityRegistry;
+    seededOutputs: Record<string, Record<string, unknown>>;
+    /** `ci.hooks` from the declaration at base (#4288). */
+    hooks: PrLoopHooks;
+    /** Every hook the stage ran so far, for the report's `hooks`. */
+    hookOutcomes: PrHookOutcome[];
+    /** Set when a hook failed: the report's message. */
+    hookFailed?: string;
+    /** Where the stage's hooks run, once its op is known. */
+    hookPlace?: PrHookPlace;
+    /**
+     * Set when `ci.branches` or `ci.labels` (#4292) leave the member out of this
+     * stage: why. The plan is then empty, so the stage reports `nothing`.
+     */
+    routedAway?: string;
+    /** `ci.policy` from the declaration at base (#4294). */
+    policy: PrLoopPolicy;
+    /** What the policy said about the plan, for the report's `policy`. */
+    policyReport?: PrPolicyReport;
+}
+/** Everything both stages share: the change and the derivation. Each stage plans the members itself. `pr-env up` (#4298) prepares as the plan does. */
+export declare function prepare(ctx: CommandContext, stage: "plan" | "apply" | "record"): Promise<Prepared | number>;
+/** Set where `p`'s hooks run, once the stage knows its op (#4288). */
+export declare function placeHooks(ctx: CommandContext, p: Prepared, stage: PrHookPlace["stage"], op: string): void;
+/**
+ * Run one moment's hooks for `components` (#4288), keeping their outcomes
+ * for the report. Returns the failure as the report's message, or undefined
+ * when no hook failed. A hold is logged: the pull request's gate already
+ * waits for a person's approval of the digest.
+ */
+export declare function runStageHook(p: Prepared, moment: OpWaveHookMoment, components: readonly string[], planned?: PrPlanSet, what?: string): string | undefined;
+/** Plan every member the derivation selects, between the plan-side hooks (#4288). */
+export declare function planAll(p: Prepared, onRunEvent?: RunEventSink): Promise<PrPlanSet>;
+export declare function planBare(p: Prepared, onRunEvent?: RunEventSink): Promise<PrPlanSet>;
 /** chant components pr-plan --base <ref> --pr <n> [--env <env>] [--gate <name>] [--forge <kind>] [--output <dir>] [--json] [--events-json] [--report-url <url>] */
 export declare function runComponentsPrPlan(ctx: CommandContext): Promise<number>;
 /** chant components pr-apply --base <ref> [--pr <n>] [--env <env>] [--gate <name>] [--forge <kind>] [--require-review] [--output <dir>] [--json] [--events-json] [--report-url <url>] */
 export declare function runComponentsPrApply(ctx: CommandContext): Promise<number>;
 /** chant components pr-record --base <ref> [--pr <n>] [--env <env>] [--gate <name>] [--forge <kind>] [--output <dir>] [--json] [--events-json] [--report-url <url>] */
 export declare function runComponentsPrRecord(ctx: CommandContext): Promise<number>;
+/**
+ * chant components pr-post --pr <n> --head <sha> --env <env> --forge <kind> [--member <name>] [--output <dir>] [--result <result>] (#4295)
+ *
+ * Post the plan note and the `chant/plan` status from the report a plan job
+ * wrote with `pr-plan --no-status`, in a job that runs none of the change's
+ * code. The pull request, the head, the environment and the member come from
+ * the flags, and a report that names others is refused (`../../pr-post.ts`).
+ * It exits 0 once it has posted, whatever the plan said, so the plan job's
+ * own result stays the one that fails the run.
+ */
+export declare function runComponentsPrPost(ctx: CommandContext): Promise<number>;
 //# sourceMappingURL=pr.d.ts.map

package/dist/cli/handlers/pr.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pr.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/pr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAwDH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAMlD,qDAAqD;AACrD,eAAO,MAAM,aAAa,cAAc,CAAC;AAqSzC,mKAAmK;AACnK,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAGxE;AAyDD,yLAAyL;AACzL,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAGzE;AAwOD,uKAAuK;AACvK,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAG1E"}
+{"version":3,"file":"pr.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/pr.ts"],"names":[],"mappings":"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"}