@intentius/chant 0.124.44 → 0.124.46

package/src/workspace/ci-run.ts

@@ -84,7 +84,7 @@ import { execFileSync } from "node:child_process";
 import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, relative, resolve, sep } from "node:path";
-import { PR_APPLY_RECORD, PR_LOOP_REPORT_DIR, prLoopJobs, prLoopSetup, PR_LOOP_IMAGE, type PrLoopJob, type PrLoopPipelineOptions } from "../components/pr-pipeline";
+import { PR_APPLY_RECORD, PR_ENV_POST_JOB, PR_ENV_REPORT_DIR, PR_LOOP_REPORT_DIR, prEnvJobs, prLoopJobs, prLoopSetup, PR_LOOP_IMAGE, type PrEnvJob, type PrLoopJob, type PrLoopPipelineOptions } from "../components/pr-pipeline";
 import { detectForge, ForgeEnvironmentError, forgeFromEnv, FORGE_KINDS, type CommitStatus, type ForgeKind, type PrForge } from "../pr-forge";
 import { holdsForgeToken, withoutForgeTokens } from "../ci-handover";
 import { postPlanReport } from "../pr-post";
@@ -114,20 +114,42 @@ import { hostRunnerKey } from "./ci-runner-key";
 import { requireRunnerStart } from "./ci-runner-start";
 import { securityGroupsAt } from "./security";
 
-/** The jobs a pull-request pipeline has: plan, and on merge record (#4168) or, opted in, apply. */
-export type CiJobName = PrLoopJob["jobName"];
-export const CI_JOB_NAMES: readonly CiJobName[] = ["plan", "apply", "record"];
+/**
+ * The jobs a pull-request pipeline has: plan, and on merge record (#4168) or,
+ * opted in, apply; and with `--pr-env` (#4298, #4330) the jobs of a pull
+ * request's environment.
+ */
+export type CiJobName = PrLoopJob["jobName"] | PrEnvJob["jobName"];
+export const CI_JOB_NAMES: readonly CiJobName[] = ["plan", "apply", "record", "env-up", "env-post", "env-down", "env-sweep"];
+
+/** The jobs of a pull request's environment (#4330). */
+export const CI_ENV_JOB_NAMES: readonly PrEnvJob["jobName"][] = ["env-up", "env-post", "env-down", "env-sweep"];
 
-/** The Op each job is recorded as, which `ci.green` phases match. */
-export const CI_JOB_OPS: Record<CiJobName, string> = { plan: "pr-plan", apply: "pr-apply", record: "pr-record" };
+/** Whether `job` is one of a pull request environment's jobs. */
+export const isCiEnvJob = (job: CiJobName): job is PrEnvJob["jobName"] => (CI_ENV_JOB_NAMES as readonly string[]).includes(job);
+
+/** The Op each job is recorded as, which `ci.green` phases match. An environment job's is its report's stem too. */
+export const CI_JOB_OPS: Record<CiJobName, string> = { plan: "pr-plan", apply: "pr-apply", record: "pr-record", "env-up": "pr-env-up", "env-post": "pr-env-post", "env-down": "pr-env-down", "env-sweep": "pr-env-sweep" };
 
 /** What each job's Op says it does. */
 const CI_JOB_OVERVIEWS: Record<CiJobName, string> = {
   plan: "Plan the members this pull request reaches",
   apply: "Apply the plan a reviewer approved",
   record: "Record the plan on the merged commit; nothing applies",
+  "env-up": "Plan this pull request's environment and apply it once its plan is approved",
+  "env-post": "Keep the environment's record and post its note",
+  "env-down": "Tear down what this pull request's environment owns",
+  "env-sweep": "Tear down the environments whose TTL passed or whose pull request closed",
 };
 
+/** One job as `ci run` runs it: a pull-request job, or an environment job (#4330). */
+export type CiJob = Pick<PrLoopJob, "command" | "env" | "setup" | "build" | "wave"> & { jobName: CiJobName };
+
+/** Where a job writes its report, inside its checkout. */
+export function ciJobReportDir(job: CiJobName): string {
+  return isCiEnvJob(job) ? PR_ENV_REPORT_DIR : PR_LOOP_REPORT_DIR;
+}
+
 /** Where a job the chant runner ran says it ran (#4094). */
 export const CHANT_RUNNER_ORIGIN: RunOrigin = { forge: "chant" };
 
@@ -167,6 +189,10 @@ export interface CiRunValues {
   pr?: number;
   /** The full commit the job runs at. */
   commit: string;
+  /** `--head`: the pull request's head, `HEAD_SHA`, which `env-post` reads (#4330). */
+  head?: string;
+  /** `--result`: the env-up job's result, `UP_RESULT`, which `env-post` reads on GitHub and Forgejo (#4330). */
+  upResult?: string;
 }
 
 export class CiRunError extends Error {
@@ -188,7 +214,7 @@ export class CiRunError extends Error {
  * runner sets for the job. `CHANT_RUNNER_KEY` is never in it.
  */
 export function ciJobEnv(
-  job: PrLoopJob,
+  job: CiJob,
   input: {
     forge: ForgeKind;
     env: string;
@@ -211,12 +237,18 @@ export function ciJobEnv(
   const flags: Record<string, { value: string | undefined; flag: string }> = {
     BASE_SHA: { value: input.values.base, flag: "--base <sha>" },
     PR_NUMBER: { value: input.values.pr !== undefined ? String(input.values.pr) : undefined, flag: "--pr <number>" },
+    HEAD_SHA: { value: input.values.head, flag: "--head <sha>" },
+    UP_RESULT: { value: input.values.upResult, flag: "--result success|failure" },
   };
+  // #4330: an environment job's CHANT_ENV is pr-<n>, which a forge fills from the event.
+  const prEnv = isCiEnvJob(job.jobName) && input.values.pr !== undefined ? `pr-${input.values.pr}` : undefined;
   for (const [name, value] of Object.entries(job.env)) {
     const given = flags[name];
     if (given) {
       if (given.value === undefined) throw new CiRunError(`the ${job.jobName} job reads ${name}, which a forge fills from the event; pass ${given.flag}`);
       out[name] = given.value;
+    } else if (name === "CHANT_ENV" && prEnv) {
+      out[name] = prEnv;
     } else if (!value.includes("$")) {
       out[name] = value;
     } else if (input.secrets?.[name] !== undefined) {
@@ -231,7 +263,7 @@ export function ciJobEnv(
 
 /** What {@link ciJobOp} builds the Op from. */
 export interface CiJobOpInput {
-  job: PrLoopJob;
+  job: CiJob;
   env: string;
   /** The directory the steps run in, inside the fresh checkout. */
   cwd: string;
@@ -251,7 +283,7 @@ export function withChant(line: string, chant?: string): string {
 }
 
 /** The job's own setup lines and its command, as one shell script, with `chant` at its start replaced by the command the caller names. */
-export function ciJobCommand(job: PrLoopJob, chant?: string): string {
+export function ciJobCommand(job: CiJob, chant?: string): string {
   return [...(job.setup ?? []), withChant(job.command, chant)].join("\n");
 }
 
@@ -283,7 +315,7 @@ export function ciJobOp(input: CiJobOpInput): OpConfig {
 }
 
 /** The pull-request report statuses that mean the job did not do its work, which a failed job's `failure.code` takes. */
-const FAILED_REPORT_STATUSES = new Set(["plan-failed", "failed", "refused"]);
+const FAILED_REPORT_STATUSES = new Set(["plan-failed", "failed", "refused", "incomplete"]);
 
 /** The exit code a failed shell step's error names (`command exited <n>`), when it names one. */
 function exitCodeOf(error: string | undefined): number | undefined {
@@ -441,10 +473,14 @@ export interface CiRunRequest {
    * `forge` then only shapes the job's variables.
    */
   noForge?: boolean;
-  /** `--base`, `--pr` and `--commit` (default `HEAD`). */
+  /** `--base`, `--pr` and `--commit` (default `HEAD`; for `env-post`, `--base`). */
   base?: string;
   pr?: number;
   commit?: string;
+  /** `--head`: for `env-post` (#4330), the pull request's head its environment was applied from. */
+  head?: string;
+  /** `--result`: for `env-post` (#4330), the env-up job's result. */
+  upResult?: string;
   /**
    * The generator's options: `--gate`, `--branch`, `--events-json`,
    * `--report-url`, `--pr-build` and `--pr-build-command`, and `--wave-gate`
@@ -553,6 +589,11 @@ export interface CiRunResult {
   checkout: string;
   /** The job ran with `local` (#4161): its record stays on this machine. */
   local?: true;
+  /**
+   * For `env-up` (#4330): the `env-post` job the runner ran after it at
+   * `--base`, with its own token, which kept the record and posted the note.
+   */
+  post?: CiRunResult;
 }
 
 const message = (err: unknown): string => (err instanceof Error ? err.message : String(err));
@@ -619,7 +660,7 @@ function freshCheckout(top: string, commit: string): { dir: string; remove(): vo
  */
 async function recordInIndex(input: {
   url: string;
-  job: CiJobName;
+  job: PrLoopJob["jobName"];
   commit: string;
   member?: string;
   pr?: number;
@@ -679,11 +720,14 @@ export async function ciRun(req: CiRunRequest): Promise<CiRunResult> {
   const cwd = realpathSync(resolve(req.cwd));
   const top = gitTop(cwd);
   if (!top) throw new CiRunError("a job runs in a fresh checkout of a commit, and this directory is not in a git repository");
-  const commit = resolveJobCommit(top, req.commit ?? "HEAD");
+  // #4330: env-post runs at the target branch's commit, none of the change's code.
+  const commit = resolveJobCommit(top, req.commit ?? (req.job === PR_ENV_POST_JOB && req.base ? req.base : "HEAD"));
   if (req.inPlace && commit !== resolveJobCommit(top, "HEAD")) throw new CiRunError(`--in-place runs the checkout's HEAD, and --commit names ${commit.slice(0, 12)}`);
   if (req.local && req.inPlace) throw new CiRunError("--in-place runs a forge job in the forge's checkout, and --local runs one on this machine; pass one of them");
   const place = ciJobPlace(cwd, top);
-  const jobs = prLoopJobs(req.forge, req.env, req.local ? localLoop(req.loop) : (req.loop ?? {}), place.member);
+  const loop = req.local ? localLoop(req.loop) : (req.loop ?? {});
+  // #4330: the jobs of a pull request's environment, as the generators wrap them with --pr-env.
+  const jobs: CiJob[] = isCiEnvJob(req.job) ? prEnvJobs(req.forge, loop, place.member) : prLoopJobs(req.forge, req.env, loop, place.member);
   const found = jobs.find((j) => j.jobName === req.job);
   if (!found) throw new CiRunError(`the pull-request pipeline has no ${req.job} job; it has ${jobs.map((j) => j.jobName).join(" and ")}`);
   if (req.wave !== undefined && (req.job !== "apply" || !req.loop?.waveGate)) throw new CiRunError("--wave names the one wave an apply runs, and takes --wave-gate: ci run apply --wave-gate <gate> --wave <k>");
@@ -699,15 +743,15 @@ export async function ciRun(req: CiRunRequest): Promise<CiRunResult> {
   const own = ciJobEnv(job, {
     forge: req.forge,
     env: req.env,
-    values: { base: req.base, pr: req.pr, commit },
+    values: { base: req.base, pr: req.pr, commit, ...(req.head ? { head: req.head } : {}), ...(req.upResult ? { upResult: req.upResult } : {}) },
     hostEnv,
     passEnv: req.passEnv,
     secrets: ciSecretsFor(req.secrets, req.job),
   });
   // #4156: in place, the forge job's environment is the job's, less the runner key.
-  // #4295: the plan runs the pull request's code, so no step of it gets a forge token, whatever gave it one.
+  // #4295: the plan and env-up run the pull request's code, so no step of them gets a forge token, whatever gave it one.
   const merged = req.inPlace ? { ...definedEnv(hostEnv), ...own } : own;
-  const jobEnv = req.job === "plan" ? withoutForgeTokens(merged) : merged;
+  const jobEnv = req.job === "plan" || req.job === "env-up" ? withoutForgeTokens(merged) : merged;
   delete jobEnv[RUNNER_KEY_ENV];
   const poster = req.job === "plan" ? planPoster(req, hostEnv) : undefined;
   // #4096: the secrets and the job's secret-looking variables, redacted from everything the run writes and returns.
@@ -716,7 +760,9 @@ export async function ciRun(req: CiRunRequest): Promise<CiRunResult> {
   try {
     const ran = await runCiJob(req, { cwd, top, commit, place, job, jobEnv, ...(redact ? { redact } : {}) });
     const posted = poster ? await postFromReport(req, poster, ran, { commit, ...(place.member ? { member: place.member } : {}) }) : [];
-    const withPosts = posted.length > 0 ? { ...ran, warnings: [...ran.warnings, ...posted] } : ran;
+    const envPost = req.job === "env-up" ? await envPostAfterUp(req, { cwd, top, head: commit, place, jobs, hostEnv, ran }) : undefined;
+    const withPost = envPost ? ("result" in envPost ? { ...ran, post: envPost.result } : { ...ran, warnings: [...ran.warnings, envPost.warning] }) : ran;
+    const withPosts = posted.length > 0 ? { ...withPost, warnings: [...withPost.warnings, ...posted] } : withPost;
     const result = started ? { ...withPosts, notes: [started, ...withPosts.notes] } : withPosts;
     return redact ? { ...result, warnings: result.warnings.map(redact), notes: result.notes.map(redact), ...(result.pushWarning ? { pushWarning: redact(result.pushWarning) } : {}) } : result;
   } catch (err) {
@@ -725,6 +771,40 @@ export async function ciRun(req: CiRunRequest): Promise<CiRunResult> {
   }
 }
 
+/**
+ * The env-post job after an env-up (#4330), as a generated pipeline runs it
+ * in a job of its own: at `--base`, the target branch's commit, with the
+ * forge token env-up's steps never got, taking the report and record env-up
+ * handed on. None on `--local`, in place (the forge's env-post job posts),
+ * for a plain git server, without `--base` and `--pr`, or without a token.
+ */
+async function envPostAfterUp(
+  req: CiRunRequest,
+  at: { cwd: string; top: string; head: string; place: { member?: string; dir: string }; jobs: CiJob[]; hostEnv: Record<string, string | undefined>; ran: CiRunResult },
+): Promise<{ result: CiRunResult } | { warning: string } | undefined> {
+  if (req.local || req.inPlace || req.noForge || req.pr === undefined) return undefined;
+  if (!req.base) return { warning: "env-post did not run: it runs at the target branch's commit, so pass --base <sha>" };
+  if (!holdsForgeToken(at.hostEnv)) return { warning: "env-post did not run: there is no forge token, so the environment's record is in the report and nothing kept it" };
+  const found = at.jobs.find((j) => j.jobName === PR_ENV_POST_JOB);
+  if (!found) return undefined;
+  const base = resolveJobCommit(at.top, req.base);
+  const job = { ...found, command: req.noForge ? found.command.replace(` --forge ${req.forge}`, "") : found.command };
+  const postReq: CiRunRequest = { ...req, job: PR_ENV_POST_JOB, commit: base, head: at.head, upResult: at.ran.status === "ok" ? "success" : "failure" };
+  delete postReq.status;
+  delete postReq.resumeRecord;
+  delete postReq.wave;
+  const jobEnv = ciJobEnv(job, { forge: req.forge, env: req.env, values: { base: req.base, pr: req.pr, commit: base, head: at.head, upResult: postReq.upResult! }, hostEnv: at.hostEnv, passEnv: req.passEnv, secrets: ciSecretsFor(req.secrets, PR_ENV_POST_JOB) });
+  delete jobEnv[RUNNER_KEY_ENV];
+  // Its own redactor: env-post holds the token env-up's steps never got.
+  const redact = ciRedactor(jobEnv, req.secrets);
+  try {
+    const result = await runCiJob(postReq, { cwd: at.cwd, top: at.top, commit: base, place: at.place, job, jobEnv, ...(redact ? { redact } : {}), ...(at.ran.report ? { seed: at.ran.report } : {}) });
+    return { result: redact ? { ...result, warnings: result.warnings.map(redact), notes: result.notes.map(redact), ...(result.pushWarning ? { pushWarning: redact(result.pushWarning) } : {}) } : result };
+  } catch (err) {
+    return { warning: `env-post did not run: ${message(err)}` };
+  }
+}
+
 /**
  * Who posts the plan's note and `chant/plan` status (#4295): the runner,
  * from the report, once the plan's steps settled, with the forge token the
@@ -854,7 +934,7 @@ function jobCheckout(top: string, commit: string, inPlace?: boolean): { dir: str
 /** {@link ciRun} once the job and its environment are known. */
 async function runCiJob(
   req: CiRunRequest,
-  at: { cwd: string; top: string; commit: string; place: { member?: string; dir: string }; job: PrLoopJob; jobEnv: Record<string, string>; redact?: Redact },
+  at: { cwd: string; top: string; commit: string; place: { member?: string; dir: string }; job: CiJob; jobEnv: Record<string, string>; redact?: Redact; seed?: string },
 ): Promise<CiRunResult> {
   const { cwd, top, commit, place, job, jobEnv, redact } = at;
   const local = req.local === true;
@@ -884,6 +964,8 @@ async function runCiJob(
       ...(req.chant ? { chant: req.chant } : {}),
     });
     const warnings: string[] = [...early];
+    // #4330: env-post takes the report env-up wrote, as a forge job takes it from the up job's outputs.
+    if (at.seed && existsSync(at.seed)) cpSync(at.seed, join(jobDir, ciJobReportDir(req.job)), { recursive: true });
     const resume = req.job === "apply" && req.resumeRecord ? { host: resolve(req.resumeRecord), job: join(jobDir, PR_APPLY_RECORD) } : undefined;
     if (resume && existsSync(resume.host)) {
       mkdirSync(dirname(resume.job), { recursive: true });
@@ -913,7 +995,7 @@ async function runCiJob(
         commit,
         ledger: { cwd: jobDir },
         runner: { kind: "pipeline", runtime: local ? "local" : "ci", runOrigin: origin },
-        describeFailure: (records) => ciJobFailure({ job: req.job, op, records, reportDir: join(jobDir, PR_LOOP_REPORT_DIR) }),
+        describeFailure: (records) => ciJobFailure({ job: req.job, op, records, reportDir: join(jobDir, ciJobReportDir(req.job)) }),
         ...(req.runEvents ? { runEvents: { write: req.runEvents } } : {}),
         ...(req.stepOutput ? { stepOutput: req.stepOutput } : {}),
         ...(signer ? { signRecord: (record: OpRunRecord) => signOpRunRecord(record, signer!) } : {}),
@@ -946,10 +1028,10 @@ async function runCiJob(
         warnings.push(`the resume record could not be kept at ${resume.host}: ${message(err)}`);
       }
     }
-    const written = join(jobDir, PR_LOOP_REPORT_DIR);
+    const written = join(jobDir, ciJobReportDir(req.job));
     let report: string | null = null;
     if (existsSync(written)) {
-      report = resolve(cwd, req.output ?? PR_LOOP_REPORT_DIR);
+      report = resolve(cwd, req.output ?? ciJobReportDir(req.job));
       // In place the report is already where the forge keeps it, and stays as the command wrote it.
       if (!(existsSync(report) && realpathSync(report) === realpathSync(written))) {
         cpSync(written, report, { recursive: true });
@@ -958,7 +1040,8 @@ async function runCiJob(
     }
     const failed = result.records.find((r) => r.status === "fail");
     const exitCode = failed?.phase === req.job ? exitCodeOf(failed.error) : undefined;
-    if (reportUrl) {
+    // The run index lists the pull-request jobs; an environment job's run is in its record only (#4330).
+    if (reportUrl && !isCiEnvJob(req.job)) {
       await recordInIndex({ url: reportUrl, job: req.job, commit, member: place.member, pr: req.pr, record: result.record, runOrigin: origin, signer: result.record.statement && signer ? signer.principal : null, exitCode: ciJobExitCode({ status: result.status, ...(exitCode !== undefined ? { exitCode } : {}) }), reportDir: written, limit: req.runIndexLimit, ...(redact ? { redact } : {}), warn: (w) => warnings.push(w) });
     }
     // In place the forge job's outcome is the command's, so a record that could not be written is a warning there.
@@ -1045,7 +1128,7 @@ export function ciLoopOptions(args: CommandContext["args"]): PrLoopPipelineOptio
 }
 
 const USAGE =
-  "chant ci run plan|record|apply --env <env> --base <sha> [--pr <n>] [--commit <sha>] [--forge github|gitlab|forgejo] " +
+  "chant ci run plan|record|apply|env-up|env-post|env-down|env-sweep --env <env> --base <sha> [--pr <n>] [--commit <sha>] [--head <sha>] [--result <r>] [--forge github|gitlab|forgejo] " +
   "[--gate <name>] [--wave-gate <name>] [--wave <k>] [--branch <name>] [--events-json] [--report-url <url>] [--run-index-limit <n>] [--image <image>] [--before-script <line>]... " +
   "[--pr-build] [--pr-build-command <line>] [--require-review] [--apply-before-merge] [--no-status] [--status-url <url template>] " +
   "[--chant <command>] [--pass-env <NAME>]... [--secrets <file>] [--key <runner key.pem>] [-o <dir>] [--in-place | --local] [--no-push] [--verbose] | chant ci run --at <sha> | chant ci run --setup-key [--trust [--principal <name>]] [--state <dir>] [--branch <name>]";
@@ -1101,9 +1184,11 @@ export async function runCiRun(ctx: CommandContext): Promise<number> {
   try {
     if (args.setupKey) return (await import("./ci-serve")).runnerKeySetupCommand(ctx);
     if (args.at !== undefined && args.extraPositional === undefined) return await requestBuildCommand(args.at);
-    const job = args.extraPositional;
-    if (job !== "plan" && job !== "apply" && job !== "record") throw new CiRunError(`ci run takes the job to run, plan, record or apply${job ? `, not ${JSON.stringify(job)}` : ""}`);
-    if (!args.env) throw new CiRunError("--env names the environment the pipeline is for, as chant build --components --generate <lexicon> --pr-loop took it: --env <env>");
+    const job = args.extraPositional as CiJobName | undefined;
+    if (!job || !CI_JOB_NAMES.includes(job)) throw new CiRunError(`ci run takes the job to run, ${CI_JOB_NAMES.join(", ")}${job ? `, not ${JSON.stringify(job)}` : ""}`);
+    // #4330: an environment job's environment is pr-<n>; the sweep's run is recorded under --env, else local.
+    const env = args.env ?? (isCiEnvJob(job) ? (args.pr !== undefined && job !== "env-sweep" ? `pr-${args.pr}` : "local") : undefined);
+    if (!env) throw new CiRunError("--env names the environment the pipeline is for, as chant build --components --generate <lexicon> --pr-loop took it: --env <env>");
     const forge = args.forge ?? detectForge(process.env);
     if (!forge) throw new CiRunError("--forge names the forge the job posts to: --forge github|gitlab|forgejo");
     if (!(FORGE_KINDS as readonly string[]).includes(forge)) throw new CiRunError(`--forge takes github, gitlab or forgejo, not ${JSON.stringify(forge)}`);
@@ -1124,11 +1209,13 @@ export async function runCiRun(ctx: CommandContext): Promise<number> {
       cwd: process.cwd(),
       ...(status ? { status } : {}),
       job,
-      env: args.env,
+      env,
       forge: forge as ForgeKind,
       ...(args.base ? { base: args.base } : {}),
       ...(args.pr !== undefined ? { pr: args.pr } : {}),
       ...(args.commit ? { commit: args.commit } : {}),
+      ...(args.head ? { head: args.head } : {}),
+      ...(args.planResult ? { upResult: args.planResult } : {}),
       loop: ciLoopOptions(reportUrl ? { ...args, reportUrl } : args),
       ...(args.ciInPlace ? { inPlace: true } : {}),
       ...(args.local ? { local: true } : {}),
@@ -1149,8 +1236,14 @@ export async function runCiRun(ctx: CommandContext): Promise<number> {
     for (const w of result.warnings) console.error(formatWarning({ message: w }));
     if (args.verbose) for (const n of result.notes) console.error(`ci run: ${n}`);
     console.error(formatCiRun(result));
+    if (result.post) {
+      for (const w of result.post.warnings) console.error(formatWarning({ message: w }));
+      console.error(formatCiRun(result.post));
+    }
     // #4156: a failed command's own exit code, such as 3 for a moved plan, is the job's, as it was before the job ran through ci run.
-    return ciJobExitCode(result);
+    // #4330: an env-up whose env-post failed fails too, since its record was not kept.
+    const code = ciJobExitCode(result);
+    return code === 0 && result.post ? ciJobExitCode(result.post) : code;
   } catch (err) {
     console.error(formatError({ message: `chant ci run: ${message(err)}`, hint: USAGE }));
     return 1;

package/src/workspace/ci-secrets.test.ts

@@ -69,7 +69,7 @@ describe("the secrets file (#4096)", () => {
     expect(ciSecretsFor(undefined, "plan")).toEqual({});
     expect(ciSecretsFor({ ...s, jobs: { plan: [] } }, "plan")).toEqual({});
     expect(() => parseCiSecrets(JSON.stringify({ secrets: { A: "aaaa" }, jobs: { plan: ["C"] } }), "s.json")).toThrow(/jobs\.plan names C, which the file does not set/);
-    expect(() => parseCiSecrets(JSON.stringify({ secrets: { A: "aaaa" }, jobs: { deploy: [] } }), "s.json")).toThrow(/the jobs are plan and apply/);
+    expect(() => parseCiSecrets(JSON.stringify({ secrets: { A: "aaaa" }, jobs: { deploy: [] } }), "s.json")).toThrow(/the jobs are plan, apply, env-up/);
     expect(() => parseCiSecrets('{ "A": 1 }', "s.json")).toThrow(/must be a string/);
     // A parse error does not quote the text, which may hold a secret.
     expect(() => parseCiSecrets('{ "A": "hunter2', "s.json")).toThrow(/^s\.json starts with \{, and is not valid JSON$/);

package/src/workspace/ci-secrets.ts

@@ -37,7 +37,8 @@ export const SECRET_NAME = /TOKEN|SECRET|KEY|PASSWORD/i;
 
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
-const JOBS: readonly CiJobName[] = ["plan", "apply"];
+/** The jobs a secrets file can give a list of its own: the pull-request jobs, and a pull request environment's (#4330). */
+const JOBS: readonly CiJobName[] = ["plan", "apply", "env-up", "env-post", "env-down", "env-sweep"];
 
 /** The secrets file, read. */
 export interface CiSecrets {
@@ -176,9 +177,9 @@ export function parseCiSecrets(text: string, file: string): Omit<CiSecrets, "fil
   if (structured) {
     for (const key of Object.keys(doc)) if (key !== "secrets" && key !== "jobs") throw new CiSecretsError(`${file} has ${JSON.stringify(key)} beside secrets and jobs`);
     const given = doc.jobs ?? {};
-    if (given === null || typeof given !== "object" || Array.isArray(given)) throw new CiSecretsError(`${file}: jobs must map plan and apply to lists of secret names`);
+    if (given === null || typeof given !== "object" || Array.isArray(given)) throw new CiSecretsError(`${file}: jobs must map ${JOBS.join(", ")} to lists of secret names`);
     for (const [job, names] of Object.entries(given as Record<string, unknown>)) {
-      if (!(JOBS as readonly string[]).includes(job)) throw new CiSecretsError(`${file}: jobs names ${JSON.stringify(job)}, and the jobs are plan and apply`);
+      if (!(JOBS as readonly string[]).includes(job)) throw new CiSecretsError(`${file}: jobs names ${JSON.stringify(job)}, and the jobs are ${JOBS.join(", ")}`);
       if (!Array.isArray(names) || names.some((n) => typeof n !== "string")) throw new CiSecretsError(`${file}: jobs.${job} must be a list of secret names`);
       for (const n of names as string[]) if (!Object.prototype.hasOwnProperty.call(values, n)) throw new CiSecretsError(`${file}: jobs.${job} names ${n}, which the file does not set`);
       jobs[job as CiJobName] = [...(names as string[])];

package/src/workspace/compose-graph.ts

@@ -41,6 +41,7 @@ import type { KindLinkRead } from "./kind-link-readers";
 import type { RecordLinkRow } from "./record-assets";
 import type { ReasonCode } from "./reason-codes";
 import { GRAPH_IR_VERSION, type GraphIR, type IRExport, type IRDanglingRef, type IRGroups, type IRImport, type IREdge, type IRNode } from "../graph-ir";
+import type { ViewDocument } from "../capabilities/view";
 
 /** The version of the composed document `chant workspace graph` writes. */
 export const WORKSPACE_GRAPH_VERSION = 1;
@@ -105,6 +106,12 @@ export interface ComposedMember {
    * `chant workspace graph` on every member; null when the box declares neither.
    */
   box?: { factory: FactoryView | null; listing: ListingView | null } | null;
+  /**
+   * With `--capability-view` (#4378): the lexicon-neutral view the member's
+   * own chant mapped through its own lexicons, with `<member>/<id>` ids. null
+   * when the member's chant predates the view and printed none.
+   */
+  capabilityView?: ViewDocument | null;
   /** Whole-read facts the member's IR carried (`meta`, `pipeline`), kept apart from the composed sections. */
   meta?: Record<string, unknown>;
   pipeline?: unknown;
@@ -249,7 +256,9 @@ export interface ComposeInput {
   ir?: GraphIR;
 }
 
-const prefix = (member: string, id: string): string => `${member}/${id}`;
+/** A member's node id as the composed workspace documents give it: `<member>/<id>`. `workspace search` uses the same rule (#4374). */
+export const composedId = (member: string, id: string): string => `${member}/${id}`;
+const prefix = composedId;
 
 const strings = (v: unknown): string[] => (Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : []);
 const records = (v: unknown): Record<string, unknown>[] =>

package/src/workspace/conformance/conformance.e2e.test.ts

@@ -39,6 +39,8 @@ const JSON_FLAG: Record<ReadContractCommand, string[]> = {
   "graph --composites": ["--json"],
   runs: ["--json"],
   wip: ["--json"],
+  search: ["--json"],
+  "search --capabilities": ["--json"],
 };
 
 /** The smallest reader that conforms, with a hook to misbehave. */
@@ -65,6 +67,17 @@ describe("the generated conformance workspace (#2679)", () => {
     expect(report.skipped).toEqual([]);
   }, 300_000);
 
+  test("search answers over the chant member with workspace graph's ids, and lists the others (#4374)", async () => {
+    const docs: Record<string, unknown>[] = [];
+    const report = await runWorkspaceReaderConformance(reader((doc) => (docs.push(doc), doc)), { workspaceDir: ws.dir, commands: ["search"] });
+    expect(report.problems).toEqual([]);
+    const doc = docs[0] as { at: null; matches: { id: string; member: string }[]; members: { name: string; status: string; alone?: boolean }[] };
+    expect(doc.at).toBeNull();
+    expect(doc.matches.length).toBeGreaterThan(0);
+    for (const m of doc.matches) expect(m.id.startsWith(`${m.member}/`), m.id).toBe(true);
+    expect(doc.members.find((m) => m.name === "delivery")).toMatchObject({ status: "searched", alone: true });
+  }, 300_000);
+
   test("graph --composites joins the fixture's composite to its component", async () => {
     const docs: Record<string, unknown>[] = [];
     await runWorkspaceReaderConformance(reader((doc) => (docs.push(doc), doc)), { workspaceDir: ws.dir, commands: ["graph --composites"] });
@@ -120,7 +133,7 @@ describe("commands (#2679)", () => {
     expect(report.problems).toEqual([]);
     expect(read).toEqual(["ls", "status", "graph --composites"]);
     expect(report.checked).toEqual(["ls", "status", "graph --composites"]);
-    expect(report.skipped).toEqual(["graph", "check", "records", "records --uncommitted", "graph --intent", "runs", "wip"]);
+    expect(report.skipped).toEqual(["graph", "check", "records", "records --uncommitted", "graph --intent", "runs", "wip", "search", "search --capabilities"]);
   }, 300_000);
 
   test("a name that is not a contract command, or an empty list, is refused", () => {

package/src/workspace/conformance/index.ts

@@ -56,7 +56,7 @@ import { isDeepStrictEqual } from "node:util";
 import { READ_CONTRACT_VERSION } from "../reason-codes";
 
 /** The read-contract commands, as a reader names them. */
-export const READ_CONTRACT_COMMANDS = ["ls", "graph", "check", "status", "records", "records --uncommitted", "graph --intent", "graph --composites", "runs", "wip"] as const;
+export const READ_CONTRACT_COMMANDS = ["ls", "graph", "check", "status", "records", "records --uncommitted", "graph --intent", "graph --composites", "runs", "wip", "search", "search --capabilities"] as const;
 export type ReadContractCommand = (typeof READ_CONTRACT_COMMANDS)[number];
 
 /**
@@ -75,6 +75,10 @@ export const READ_CONTRACT_SCHEMAS: Record<ReadContractCommand, string> = {
   "graph --composites": "composites.schema.json",
   runs: "runs.schema.json",
   wip: "wip.schema.json",
+  // `workspace search` (#4374). Plain `chant search --json` prints the same document for one project.
+  search: "search.schema.json",
+  // The capability catalog (#4375), from the workspace's chant.
+  "search --capabilities": "capabilities.schema.json",
 };
 
 /** The flags that ask each command for its JSON document. A reader adds one of these and nothing else. */
@@ -89,6 +93,8 @@ export const READ_CONTRACT_JSON_FLAGS: Record<ReadContractCommand, readonly (rea
   "graph --composites": [[], ["--json"]],
   runs: [["--json"]],
   wip: [["--json"]],
+  search: [["--json"]],
+  "search --capabilities": [["--json"]],
 };
 
 /** The arguments the suite passes each read, on the reference workspace or the generated one. */
@@ -103,6 +109,9 @@ export const REFERENCE_READS: Record<ReadContractCommand, string[]> = {
   "graph --composites": [],
   runs: [],
   wip: [],
+  // A bare word: on either workspace it searches the chant member, delivery, and lists the others.
+  search: ["app"],
+  "search --capabilities": [],
 };
 
 /** One chant run: the arguments after `chant`, what it was given on stdin, and what it printed. */
@@ -344,6 +353,8 @@ export const MCP_READ_TOOLS: Partial<Record<ReadContractCommand, string>> = {
   "graph --intent": "workspace-graph",
   "graph --composites": "workspace-graph",
   runs: "workspace-runs",
+  search: "workspace-search",
+  "search --capabilities": "capabilities",
 };
 
 /**
@@ -359,9 +370,14 @@ export function mcpToolCall(argv: readonly string[]): { name: string; arguments:
   const args: Record<string, unknown> = {};
   const positional: string[] = [];
   const kinds: string[] = [];
+  const members: string[] = [];
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     const value = (): string | undefined => rest[++i];
+    if (a === "--") {
+      positional.push(...rest.slice(i + 1));
+      break;
+    }
     if (a === "--json") continue;
     if (a === "--format" && rest[i + 1] === "json") {
       i++;
@@ -381,7 +397,14 @@ export function mcpToolCall(argv: readonly string[]): { name: string; arguments:
     else if (a === "--by") args.by = value();
     else if (a === "--uncommitted") args.uncommitted = true;
     else if (a === "--composites") args.composites = true;
-    else if (a.startsWith("-")) return undefined;
+    else if (verb === "search" && a === "--member") members.push(value() ?? "");
+    else if (verb === "search" && a === "--env") args.env = value();
+    else if (verb === "search" && a === "--snapshot") args.snapshot = value();
+    else if (verb === "search" && a === "--count-by") args.countBy = value();
+    else if (verb === "search" && a === "--show") args.show = value();
+    else if (verb === "search" && a === "--explain") args.explain = true;
+    else if (verb === "search" && a === "--capabilities") args.capabilities = true;
+    else if (/^-[A-Za-z-]/.test(a)) return undefined;
     else positional.push(a);
   }
   switch (verb) {
@@ -397,6 +420,12 @@ export function mcpToolCall(argv: readonly string[]): { name: string; arguments:
       return positional.length === 0 ? { name: "workspace-graph", arguments: { ...args, ...(kinds.length ? { kind: kinds } : {}) } } : undefined;
     case "runs":
       return positional.length === 0 && kinds.length === 0 ? { name: "workspace-runs", arguments: args } : undefined;
+    case "search":
+      // The catalog (#4375) is its own tool, and takes nothing.
+      if (args.capabilities) return positional.length === 0 && Object.keys(args).length === 1 && kinds.length === 0 && members.length === 0 ? { name: "capabilities", arguments: {} } : undefined;
+      return positional.length <= 1 && kinds.length === 0
+        ? { name: "workspace-search", arguments: { ...args, query: positional[0] ?? "", ...(members.length ? { member: members } : {}) } }
+        : undefined;
     default:
       return undefined;
   }

package/src/workspace/declaration.schema.json

@@ -289,6 +289,33 @@
               "type": "string",
               "pattern": "^[1-9][0-9]*(m|h|d)$",
               "description": "How long a pull request's environment lives after its last apply, such as 72h, 90m or 7d. chant components pr-env sweep tears down one whose TTL passed. 72h when absent."
+            },
+            "teardown": {
+              "type": "object",
+              "description": "A command that tears down what no lexicon does, such as a Terraform root's copy of the environment (#4330). pr-env down and pr-env sweep run it after the ownership check, twice: CHANT_PR_ENV_STAGE=owned writes the candidates with their read-back markers to CHANT_PR_ENV_RESULT, and CHANT_PR_ENV_STAGE=teardown deletes the candidates in CHANT_PR_ENV_CANDIDATES and writes their outcomes. It runs without the forge token variables. Added in schema 1 by chant 0.124.45, so a declaration that uses it sets minReader to 0.124.45 or newer.",
+              "required": ["command"],
+              "additionalProperties": false,
+              "patternProperties": {
+                "^x-": true
+              },
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "pattern": "^[a-z0-9][a-z0-9-]*$",
+                  "description": "The name the teardown's outcomes are attributed to, as a lexicon's are. teardown when absent."
+                },
+                "command": {
+                  "type": "array",
+                  "minItems": 1,
+                  "items": { "type": "string", "minLength": 1 },
+                  "description": "Argv, run in the member's directory at the commit the job runs at. {env}, {pr} and {stage} are filled in."
+                },
+                "lexicons": {
+                  "type": "array",
+                  "items": { "type": "string", "minLength": 1 },
+                  "description": "The lexicons the command tears down in place of, such as terraform. Their own teardown is left out, so one with no teardown execution does not leave the environment incomplete."
+                }
+              }
             }
           }
         }
@@ -363,7 +390,7 @@
     "ciCloudIdentityRules": {
       "type": "array",
       "minItems": 1,
-      "description": "Rules, first match wins: a rule matches a pipeline when its environments match the pipeline's environment and its members match the pipeline's member. A rule with no environments matches every environment, and one with no members every member and a pipeline outside a member.",
+      "description": "Rules, first match wins: a rule matches a pipeline when its environments match the pipeline's environment and its members match the pipeline's member, and a target inside the member when its targets match the target too. A rule with no environments matches every environment, one with no members every member and a pipeline outside a member, and one with no targets every target.",
       "items": {
         "type": "object",
         "additionalProperties": false,
@@ -378,6 +405,14 @@
             "description": "Environment-name globs, such as prod or staging-*."
           },
           "members": { "$ref": "#/$defs/ciMemberGlobs" },
+          "targets": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1 },
+            "description": "Target globs inside the member (#4332), such as Terraform roots or Op wave run targets: * within one / segment, ** across segments, ? one character. The plan job trades for every plan identity the member's targets take, and an apply splits into one job per apply identity. Added in schema 1 by chant 0.124.45, so a declaration that uses it sets minReader to 0.124.45 or newer."
+          },
+          "name": { "type": "string", "pattern": "^[a-z0-9_-]+$", "description": "The name of the apply job group the rule's targets form (#4332). Default: from its first target glob. Added by chant 0.124.45." },
           "plan": { "type": "string", "minLength": 1, "description": "The identity the plan and record jobs take: a role ARN, a service account email or a client id." },
           "apply": { "type": "string", "minLength": 1, "description": "The identity the apply jobs take." }
         }

package/src/workspace/declaration.test.ts

@@ -564,4 +564,11 @@ describe("ci.prEnvironment (#4298)", () => {
     expect(failure(base(members, { ci: { prEnvironment: {} } })).code).toBe("declaration-invalid");
     expect(failure(base(members, { ci: { prEnvironment: { template: "staging", ttl: "1w" } } })).code).toBe("declaration-invalid");
   });
+
+  test("a teardown command is read with its argv and the lexicons it covers (#4330)", () => {
+    const teardown = { name: "terragucci", command: ["terragucci", "pr-env", "teardown", "{stage}"], lexicons: ["terraform"] };
+    expect(parse(base(members, { ci: { prEnvironment: { template: "staging", teardown } } })).ci?.prEnvironment).toEqual({ template: "staging", ttl: "72h", teardown });
+    expect(failure(base(members, { ci: { prEnvironment: { template: "staging", teardown: { command: [] } } } })).code).toBe("declaration-invalid");
+    expect(failure(base(members, { ci: { prEnvironment: { template: "staging", teardown: { command: ["x"], runs: "y" } } } })).code).toBe("declaration-invalid");
+  });
 });