@intentius/chant 0.124.44 → 0.124.46

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

@@ -25,17 +25,24 @@
  * `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`.
+ * exactly that one. The lexicons tear down what they own, and the command
+ * `ci.prEnvironment.teardown` names tears down the rest (#4330). No gate
+ * holds it: closing the pull request is the decision, as is the TTL the base
+ * set for `sweep`.
+ *
+ * The runs themselves are ../../components/pr-env-run.ts, which a product
+ * calls with an adapter of its own (#4330). This file supplies the
+ * components adapter and the CLI's ports.
  */
 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 { PR_ENV_EXIT, PR_ENV_GATE, PR_ENV_RECORD_FILE, PR_ENV_REPORT_DIR, acceptHandedRecord, handedPrEnvReport, PR_ENV_TEMPLATE_VAR, derivePrEnvironment, prEnvApproveCommand, prEnvStatusState, prEnvironmentName, prEnvironmentSite, renderPrEnvNote, ttlMs, } from "../../components/pr-environment.js";
+import { commandTeardownAdapter, prEnvDown as prEnvDownRun, prEnvOp, prEnvSweep as prEnvSweepRun, prEnvUp as prEnvUpRun, } from "../../components/pr-env-run.js";
+import { forgePrEnvPublisher, lifecyclePrEnvPorts } from "../../components/pr-env-ports.js";
+import { applyPrSet } from "../../components/pr-run.js";
 import { prOp } from "../../pr-loop.js";
 import { FORGE_KINDS, forgeFromEnv, forgePrincipalOf } from "../../pr-forge.js";
 import { formatError, formatInfo, formatWarning } from "../format.js";
@@ -77,36 +84,29 @@ function actor() {
 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));
-}
+// ── the ports ──────────────────────────────────────────────────────────────
+const log = (line) => console.error(formatInfo(line));
+const warn = (message) => console.error(formatWarning({ message }));
 /**
- * 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.
+ * The ports `pr-env` runs with (../../components/pr-env-run.ts): the records
+ * and the gate ledger on chant/lifecycle here, and the report written under
+ * `--output` and posted through `forge`. 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.
  */
-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)}` }));
-    }
+function cliPorts(ctx, forge) {
+    const lifecycle = lifecyclePrEnvPorts({ ...(forge ? { forge } : {}), log, warn });
+    return {
+        ...lifecycle,
+        async appendRecord(record) {
+            if (!ctx.args.noPush)
+                return lifecycle.appendRecord(record);
+            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");
+        },
+        publish: (report) => finish(ctx, forge, report),
+    };
 }
 // ── the report and the note ────────────────────────────────────────────────
 async function finish(ctx, forge, report) {
@@ -117,27 +117,8 @@ async function finish(ctx, forge, report) {
     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)}` }));
-    }
+    if (forge)
+        await forgePrEnvPublisher(forge, warn)(report);
 }
 // ── up ─────────────────────────────────────────────────────────────────────
 async function prEnvUp(ctx) {
@@ -159,7 +140,6 @@ async function prEnvUp(ctx) {
     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;
@@ -168,108 +148,77 @@ async function prEnvUp(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 });
+    return withComponentEndpoint(envCtx, () => up(envCtx, pr, derived, setting.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",
+    placeHooks(ctx, p, "apply", prEnvOp(pr, p.member));
+    const result = await prEnvUpRun({
         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 } : {}),
+        ttl,
+        stack: derived.stack,
+        ...(p.member ? { member: p.member } : {}),
+        ...(derived.endpoint ? { endpoint: derived.endpoint } : {}),
+        adapter: componentsPrEnvAdapter(p, { planAll, runStageHook }),
+        ports: cliPorts(ctx, p.forge),
+        actor: actor(),
+        ...(p.forge?.runUrl ? { runUrl: p.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." }),
+    if (result.report.status === "waiting" || result.report.status === "changed")
+        console.error(formatInfo(`approve : ${prEnvApproveCommand(result.report.op, result.report.digest)}`));
+    return result.exit;
+}
+/**
+ * The components as a pull request environment's adapter: the plan is
+ * `pr-plan`'s, with the plan-side hooks around it, and the apply is the
+ * fan-out's, with the apply-side hooks around it. Each row carries the
+ * component's site in `pr-<n>`, carried over from the template's (#4330,
+ * `prEnvironmentSite`).
+ */
+function componentsPrEnvAdapter(p, run) {
+    let set;
+    const rows = (target, 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);
+        const found = prEnvironmentSite(p.sites?.[component], target.template, target.env);
+        const site = found ? { ...(found.runtime ? { runtime: found.runtime } : {}), ...(found.url ? { url: found.url } : {}), ...(found.domain ? { domain: found.domain } : {}) } : undefined;
+        return { component, status: status(component), create: sum("create"), update: sum("update"), replace: sum("replace"), delete: sum("delete"), ...(site && Object.keys(site).length > 0 ? { site } : {}) };
     });
-    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;
+    return {
+        async plan(target) {
+            if (p.plan.order.length === 0)
+                return { digest: "", empty: true, rows: [], ...(p.routedAway ? { message: p.routedAway } : {}) };
+            set = await run.planAll(p);
+            const planned = set;
+            return {
+                digest: planned.doc.digest,
+                empty: isEmptyChangeSet(planned.doc),
+                ...(planned.failed ? { failed: true } : {}),
+                rows: rows(target, (c) => (planned.failed && planned.members.some((m) => m.component === c && m.status === "plan-failed") ? "plan failed" : "planned")),
+                ...(p.hookFailed ? { message: p.hookFailed } : {}),
+            };
+        },
+        async apply(target) {
+            const planned = set;
+            const hookStop = run.runStageHook(p, "before-apply", p.plan.order, planned);
+            if (hookStop)
+                return { status: "stopped", rows: rows(target, () => "planned"), message: hookStop };
+            const applied = await applyPrSet({ components: p.components, plan: p.plan, registry: p.registry, env: target.env, set: planned, gate: PR_ENV_GATE });
+            const afterHook = run.runStageHook(p, "after-apply", p.plan.order, planned, "the environment stands as applied");
+            const status = (component) => applied.members.find((m) => m.component === component)?.status ?? "planned";
+            return {
+                status: applied.status === "applied" ? "applied" : applied.status === "waiting" ? "waiting" : "failed",
+                rows: rows(target, status),
+                ...(afterHook ? { afterFailure: afterHook } : {}),
+            };
+        },
+    };
 }
 // ── post ───────────────────────────────────────────────────────────────────
 /**
@@ -319,7 +268,7 @@ async function prEnvPost(ctx) {
                 code = PR_ENV_EXIT.failed;
             }
             else {
-                await appendRecord({ ...ctx, args: { ...args, noPush: false } }, accepted.record);
+                await lifecyclePrEnvPorts({ warn }).appendRecord(accepted.record);
                 if (accepted.record.expiresAt)
                     report.expiresAt = accepted.record.expiresAt;
             }
@@ -329,6 +278,18 @@ async function prEnvPost(ctx) {
     return code;
 }
 // ── down ───────────────────────────────────────────────────────────────────
+/**
+ * What tears the environment down: the lexicons, and the command
+ * `ci.prEnvironment.teardown` names in the declaration at this commit
+ * (#4330), which the down and sweep jobs check out from the base branch.
+ */
+async function teardownSources() {
+    const projectPath = resolve(".");
+    const { config } = await loadChantConfig(projectPath).catch(() => ({ config: {} }));
+    const { scopeSource } = await import("../../workspace/write-scope.js");
+    const hook = scopeSource(projectPath, "HEAD").declaration?.ci?.prEnvironment?.teardown;
+    return { config, adapters: hook ? [commandTeardownAdapter(hook, { cwd: projectPath })] : [] };
+}
 async function prEnvDown(ctx) {
     const { args } = ctx;
     if (args.pr === undefined)
@@ -339,61 +300,21 @@ async function prEnvDown(ctx) {
     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(),
+    const result = await prEnvDownRun({
+        pr: args.pr,
         reason,
-        outcomes: counts,
-        releaseTarget: false,
+        ...(member ? { member } : {}),
+        ports: cliPorts(ctx, forge),
+        ...(await teardownSources()),
+        plugins: ctx.plugins,
+        commit: await headCommit(),
+        actor: actor(),
         ...(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;
+    if (result.report.status === "refused")
+        return fail(result.report.message ?? "refused");
+    return result.exit;
 }
 async function headCommit() {
     const { spawnSync } = await import("node:child_process");
@@ -405,32 +326,13 @@ 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;
+    const result = await prEnvSweepRun({
+        ports: cliPorts(ctx, forge),
+        ...(await teardownSources()),
+        plugins: ctx.plugins,
+        commit: await headCommit(),
+        actor: actor(),
+        ...(forge?.runUrl ? { runUrl: forge.runUrl } : {}),
+    });
+    return result.exit;
 }

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

@@ -72,6 +72,7 @@ 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 { ComponentEnvironmentDeclaration } from "../../components/component.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";
@@ -97,6 +98,8 @@ export interface Prepared {
     signal: ComponentChangeSignal;
     registry: CapabilityRegistry;
     seededOutputs: Record<string, Record<string, unknown>>;
+    /** Component name to the environments it declares (#3153), whose sites `pr-env up` carries over (#4330). */
+    sites?: Record<string, ComponentEnvironmentDeclaration[]>;
     /** `ci.hooks` from the declaration at base (#4288). */
     hooks: PrLoopHooks;
     /** Every hook the stage ran so far, for the report's `hooks`. */

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":"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"}
+{"version":3,"file":"pr.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/pr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAKH,OAAO,EAA+C,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAG7F,OAAO,EAYL,KAAK,SAAS,EACf,MAAM,yBAAyB,CAAC;AAQjC,OAAO,EAA0C,KAAK,YAAY,EAAuB,MAAM,wBAAwB,CAAC;AAIxH,OAAO,EAWL,KAAK,aAAa,EAElB,KAAK,cAAc,EAKpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAA+D,KAAK,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAU3G,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,KAAK,EAAE,qBAAqB,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAClF,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAClF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,4BAA4B,CAAC;AAClF,OAAO,EAA6B,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAC1G,OAAO,EAA8F,KAAK,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC3J,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGnD,qDAAqD;AACrD,eAAO,MAAM,aAAa,cAAc,CAAC;AAEzC,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,WAAW,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,qBAAqB,CAAC;IAC9B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACvD,4GAA4G;IAC5G,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,+BAA+B,EAAE,CAAC,CAAC;IAC1D,uDAAuD;IACvD,KAAK,EAAE,WAAW,CAAC;IACnB,iEAAiE;IACjE,YAAY,EAAE,aAAa,EAAE,CAAC;IAC9B,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,MAAM,EAAE,YAAY,CAAC;IACrB,sEAAsE;IACtE,YAAY,CAAC,EAAE,cAAc,CAAC;IAC9B,8FAA8F;IAC9F,WAAW,CAAC,EAAE,aAAa,CAAC;CAC7B;AAOD,uJAAuJ;AACvJ,wBAAsB,OAAO,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC,QAAQ,GAAG,MAAM,CAAC,CAwHjH;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,GAAG,EAAE,cAAc,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAE1G;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,gBAAgB,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,SAAS,EAAE,IAAI,SAAwB,GAAG,MAAM,GAAG,SAAS,CAQxK;AA+ED,qFAAqF;AACrF,wBAAgB,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC,CAElF;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC,CASnF;AAwND,mKAAmK;AACnK,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAGxE;AA8FD,yLAAyL;AACzL,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAYzE;AA+XD,uKAAuK;AACvK,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAG1E;AAs3BD;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8B9E"}

package/dist/cli/handlers/pr.js

@@ -218,6 +218,7 @@ export async function prepare(ctx, stage) {
         components: derived.components,
         plan: routedAway ? { ...derived.plan, order: [], waves: [], seeds: [], indeterminate: [] } : derived.plan,
         signal: derived.signal,
+        ...(derived.sites ? { sites: derived.sites } : {}),
         registry,
         seededOutputs,
         hooks,

package/dist/cli/handlers/search-count.d.ts

@@ -0,0 +1,89 @@
+import type { GraphIR, IRNode } from "../../graph-ir.js";
+import { terraformType } from "../../graph-effective.js";
+export { terraformType };
+/**
+ * `chant search --count-by <kind|module|attr:<name>>` (#4360): grouped counts
+ * over the matched set, one line per group, instead of one row per match.
+ *
+ * An agent asking "how many resources of each type does each module own" used
+ * to run one search per value, or read every row and count them itself. The
+ * second is the token cost `search` exists to avoid.
+ *
+ * Every matched node lands in exactly one group. A node with no value for the
+ * grouped dimension is counted under `(none)`, never dropped, so the groups
+ * always add up to the total line.
+ */
+export type CountBy = {
+    by: "kind";
+} | {
+    by: "module";
+} | {
+    by: "attr";
+    name: string;
+};
+/** The group a node with no value for the grouped dimension is counted under. */
+export declare const NONE_GROUP = "(none)";
+/** The module group of a Terraform block declared in the root module itself. */
+export declare const ROOT_MODULE_GROUP = "(root)";
+/** Parse a `--count-by` value, or say what the accepted spellings are. */
+export declare function parseCountBy(raw: string): CountBy | {
+    error: string;
+    hint: string;
+};
+/**
+ * The group one node belongs to.
+ *
+ * `module` on a Terraform node is its call chain. When the graph holds more
+ * than one Terraform root, the chain is prefixed with the root (`app/(root)`,
+ * `net/module.vpc`): `module.vpc` in two roots is two modules, applied
+ * separately, and counting them as one would add up resources that never sit
+ * in the same state. A node of another lexicon groups under the composite that
+ * expanded it, chant's own unit of reuse, or `(none)`.
+ */
+export declare function groupOf(n: IRNode, countBy: CountBy, multiRoot?: boolean): string;
+/** Whether the graph holds blocks from more than one Terraform root. */
+export declare function hasManyTerraformRoots(ir: GraphIR): boolean;
+/** Count `matches` per group, sorted by count (highest first) and then by name. */
+export declare function countGroups(matches: IRNode[], countBy: CountBy, multiRoot?: boolean): Array<{
+    group: string;
+    count: number;
+}>;
+/**
+ * The groups with the ids of the matches in each, in match order (#4382), in
+ * the order {@link countGroups} gives. `count` is always `ids.length`. A
+ * reader that draws the groups (behold#922) lights each group's nodes from
+ * `ids`, so it never has to read a node's group itself.
+ */
+export declare function groupMembers(matches: IRNode[], countBy: CountBy, multiRoot?: boolean): Array<{
+    group: string;
+    count: number;
+    ids: string[];
+}>;
+/** `--count-by` with `--json`: the groups, in printed order, each with its matched ids, and the total they add up to. */
+export interface CountsJson {
+    query: string;
+    source: unknown;
+    countBy: string;
+    groups: Array<{
+        group: string;
+        count: number;
+        ids: string[];
+    }>;
+    total: number;
+    liveFailures?: string[];
+}
+export declare function countsJson(query: string, source: unknown, groups: Array<{
+    group: string;
+    count: number;
+    ids: string[];
+}>, countBy: CountBy, liveFailures?: string[]): CountsJson;
+/**
+ * Render grouped counts: one `<count>  <group>` line per group, counts right
+ * aligned, then the total. The total is the number of matches, which is the
+ * sum of the group counts by construction.
+ */
+export declare function formatCounts(groups: Array<{
+    group: string;
+    count: number;
+}>, countBy: CountBy): string[];
+//# sourceMappingURL=search-count.d.ts.map

package/dist/cli/handlers/search-count.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-count.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/search-count.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAItD,OAAO,EAAE,aAAa,EAAE,CAAC;AAEzB;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,OAAO,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,QAAQ,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvF,iFAAiF;AACjF,eAAO,MAAM,UAAU,WAAW,CAAC;AACnC,gFAAgF;AAChF,eAAO,MAAM,iBAAiB,WAAW,CAAC;AAE1C,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAUnF;AAiCD;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,UAAQ,GAAG,MAAM,CAQ9E;AAED,wEAAwE;AACxE,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAI1D;AAED,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,UAAQ,GAAG,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAE3H;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,UAAQ,GAAG,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAW3I;AAED,yHAAyH;AACzH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,EAC9D,OAAO,EAAE,OAAO,EAChB,YAAY,GAAE,MAAM,EAAO,GAC1B,UAAU,CASZ;AAOD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,EAAE,CAMxG"}