@intentius/chant 0.124.29 → 0.124.31

package/src/op/local-executor.ts

@@ -56,7 +56,8 @@ import { LiveRun, currentLiveRun, withLiveRun } from "./run-live";
 import { runEnvOf } from "../lifecycle/run-ledger";
 import { resolveCommitSha } from "../lifecycle/commit-sha";
 import { resolveCiRun, type RunOrigin } from "../lifecycle/release-ledger";
-import { runEventsOfStepRecord, type RunEventRuntime, type RunEventSkipReason } from "../run-event";
+import { redactDeep, redactText, type Redact } from "./redact";
+import { runEventsOfStepRecord, type RunEventKind, type RunEventRuntime, type RunEventSkipReason } from "../run-event";
 import { openRunEventStore, teeLines } from "../run-event-store";
 import { openRunEventStream, runEventRunOf, type RunEventSink, type RunEventStream } from "../run-event-stream";
 import { describePlanDigest, samePlanDigest } from "../lifecycle/plan-digest";
@@ -1300,6 +1301,24 @@ export interface RunOpOptions {
    * turn and `local` otherwise. Omitted, nothing is written.
    */
   runEvents?: { write: (line: string) => void; runtime?: RunEventRuntime; runOrigin?: RunOrigin };
+  /**
+   * What ran the Op, when a runner says so itself (#4094): `chant ci run`
+   * runs a pull-request job as an Op and passes `kind: "pipeline"`,
+   * `runtime: "ci"` and `runOrigin: { forge: "chant" }`. The run's events
+   * carry all three, kept on this host as well as written to
+   * {@link runEvents}, and the run record carries `runOrigin` in place of
+   * the CI run the environment names. Omitted, the run is an `op` run named
+   * as described on {@link runEvents}.
+   */
+  runner?: { kind: RunEventKind; runtime: RunEventRuntime; runOrigin: RunOrigin };
+  /**
+   * Says why a failed run failed (#4094), given the run's step records once
+   * it has settled `fail`. What it returns is stored on the record as
+   * `failure`, before the record is signed, and carried on the `run-settle`
+   * event. `chant ci run` reads the job's pull-request report here, while
+   * the checkout it ran in still exists.
+   */
+  describeFailure?: (records: readonly StepRecord[]) => OpRunRecord["failure"];
   /**
    * Append the run's {@link OpRunRecord} to the run ledger
    * (`../lifecycle/run-ledger.ts`) when the run settles (#2118). Opt-in on
@@ -1359,6 +1378,17 @@ export interface RunOpOptions {
    * needs one. The local runtime passes the configured lexicons' contracts.
    */
   contracts?: ReadonlyMap<string, ActivityContract>;
+  /**
+   * Redacts secret values (#4096) from what the run writes about itself:
+   * each {@link runEvents} line and each line kept on this host, each
+   * {@link stepOutput} line and step label, and the run record, its step
+   * records and its `failure`, before {@link signRecord} signs it and the
+   * ledger stores it. The step records on the result are redacted too. This
+   * is the one place a run's writes pass through, so a writer added here
+   * later is redacted with the rest. `chant ci run` passes one built from
+   * the host's secrets file (../workspace/ci-secrets.ts).
+   */
+  redact?: Redact;
 }
 
 /**
@@ -1419,7 +1449,11 @@ export async function runOpLocally(
   const events: { stream?: RunEventStream } = {};
   try {
     const stepConsole = options.stepOutput
-      ? { write: options.stepOutput, ...(options.stepHeartbeatMs !== undefined ? { heartbeatMs: options.stepHeartbeatMs } : {}) }
+      ? {
+          write: options.stepOutput,
+          ...(options.stepHeartbeatMs !== undefined ? { heartbeatMs: options.stepHeartbeatMs } : {}),
+          ...(options.redact ? { redact: options.redact } : {}),
+        }
       : undefined;
     return await withLiveRun(live, () =>
       withRunConsole(stepConsole, () =>
@@ -1460,11 +1494,14 @@ async function runOpInTurn(
   const store = options.ledger
     ? await openRunEventStore(options.ledger.cwd ?? options.cwd ?? process.cwd(), runId)
     : undefined;
-  const eventsWrite = teeLines(options.runEvents?.write, store?.write.bind(store));
+  const teed = teeLines(options.runEvents?.write, store?.write.bind(store));
+  // #4096: every event line, to the caller and to this host's store alike, is redacted once, here.
+  const redact = options.redact;
+  const eventsWrite = teed && redact ? (line: string) => teed(redactText(line, redact)) : teed;
   const stream = eventsWrite
     ? openRunEventStream(
         runEventRunOf({
-          kind: "op",
+          kind: options.runner?.kind ?? "op",
           name: config.name,
           runId,
           ...(commit ? { gitSha: commit } : {}),
@@ -1472,6 +1509,7 @@ async function runOpInTurn(
           steward: options.steward !== undefined,
           ...(options.runEvents?.runtime ? { runtime: options.runEvents.runtime } : {}),
           ...(options.runEvents?.runOrigin ? { runOrigin: options.runEvents.runOrigin } : {}),
+          ...(options.runner ? { runtime: options.runner.runtime, runOrigin: options.runner.runOrigin } : {}),
         }),
         eventsWrite,
       )
@@ -1601,7 +1639,7 @@ async function runOpInTurn(
     point?: WaitingPoint,
   ): Promise<OpRunRecord> => {
     const ended = options.now ?? new Date().toISOString();
-    const input = buildRunRecord(config, settled, {
+    let input = buildRunRecord(config, settled, {
       started: startedAt,
       ended,
       status,
@@ -1612,9 +1650,22 @@ async function runOpInTurn(
       ...(options.steward ? { steward: options.steward } : {}),
       ...(resumed ? { resumed } : {}),
       ...(commit ? { gitSha: commit } : {}),
-      ...(ciRun ? { runOrigin: ciRun.runOrigin } : {}),
+      ...(options.runner ? { runOrigin: options.runner.runOrigin } : ciRun ? { runOrigin: ciRun.runOrigin } : {}),
       phaseDurations,
     });
+    if (status === "fail" && options.describeFailure) {
+      const failure = options.describeFailure(settled);
+      if (failure) input.failure = failure;
+    }
+    // #4096: the record is redacted before it is signed, so the stored record is the one the statement covers.
+    // The step records on the result are redacted in place, so a caller printing them prints no secret.
+    if (redact) {
+      input = redactDeep(input, redact);
+      for (const r of settled) {
+        if (r.error !== undefined) r.error = redact(r.error);
+        if (r.args) r.args = redactDeep(r.args, redact);
+      }
+    }
     let record: OpRunRecord = { version: 1, ...input, id: runId };
     if (options.signRecord) {
       try {
@@ -1627,7 +1678,7 @@ async function runOpInTurn(
     }
     // The stream settles as the run does, with the first failing step's error.
     const firstError = status === "fail" ? settled.find((r) => r.status === "fail")?.error : undefined;
-    stream?.settle(status === "fail" ? "failed" : status, firstError);
+    stream?.settle(status === "fail" ? "failed" : status, firstError, input.failure);
     if (!options.ledger) return record;
     try {
       return (await appendRunRecord(input, options.ledger)).record;

package/src/op/redact.ts

@@ -0,0 +1,93 @@
+/**
+ * Redaction of secret values (#4096): what a run writes about itself, with
+ * each secret value replaced by `***`.
+ *
+ * The executor (./local-executor.ts) takes a {@link Redact} and applies it
+ * where a run writes: each run-event line, each line a step prints, and the
+ * run record before it is signed and stored. `chant ci run` builds one from
+ * the host's secrets file and the job's secret-looking variables
+ * (../workspace/ci-secrets.ts).
+ *
+ * A value shorter than {@link REDACT_MIN_LENGTH} characters is not
+ * redacted: a two- or three-character value matches too much ordinary text.
+ */
+
+/** What every redacted value is replaced with. */
+export const REDACTED = "***";
+
+/** The shortest value redacted. Shorter values are left as they are. */
+export const REDACT_MIN_LENGTH = 4;
+
+/** A text with every secret value it contains replaced by {@link REDACTED}. */
+export type Redact = (text: string) => string;
+
+const escapeRegExp = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * The redactor for `values`, or undefined when none is long enough to
+ * redact. A value that spans lines is also redacted line by line, since
+ * step output reaches a reader one line at a time.
+ */
+export function redactorOf(values: Iterable<string>): Redact | undefined {
+  const all = new Set<string>();
+  const add = (v: string): void => {
+    if (v.length < REDACT_MIN_LENGTH) return;
+    all.add(v);
+    // As a JSON string spells it, for a value with a quote, a backslash or a control character in it.
+    all.add(JSON.stringify(v).slice(1, -1));
+  };
+  for (const value of values) {
+    add(value);
+    if (value.includes("\n")) for (const line of value.split(/\r?\n/)) add(line.trim());
+  }
+  if (all.size === 0) return undefined;
+  // Longest first, so a value that contains another is replaced whole.
+  const pattern = new RegExp([...all].sort((a, b) => b.length - a.length).map(escapeRegExp).join("|"), "g");
+  return (text) => (typeof text === "string" && text.length >= REDACT_MIN_LENGTH ? text.replace(pattern, REDACTED) : text);
+}
+
+/** `value` with `redact` applied to every string in it, keys included. Numbers, booleans and nulls are kept. */
+export function redactDeep<T>(value: T, redact: Redact): T {
+  if (typeof value === "string") return redact(value) as T;
+  if (Array.isArray(value)) return value.map((v) => redactDeep(v, redact)) as T;
+  if (value !== null && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) out[redact(k)] = redactDeep(v, redact);
+    return out as T;
+  }
+  return value;
+}
+
+/**
+ * A JSON value's text, as `JSON.stringify` wrote it, with `redact` applied to
+ * its strings: parsed, redacted and written again, so a short value such as
+ * `true` that is also a secret doesn't break the document. Undefined when
+ * `text` is not JSON.
+ */
+function redactJsonText(text: string, redact: Redact): string | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+  if (parsed === null || typeof parsed !== "object") return undefined;
+  const indent = /^[[{]\r?\n(\s+)/.exec(text)?.[1]?.length;
+  const trailing = /\s*$/.exec(text)?.[0] ?? "";
+  return `${JSON.stringify(redactDeep(parsed, redact), null, indent)}${trailing}`;
+}
+
+/**
+ * A file's or line's text redacted: a JSON document as JSON, each line of a
+ * JSON Lines text as JSON, and any other text, or line, as text. The text
+ * comes back unchanged when it holds no secret.
+ */
+export function redactText(text: string, redact: Redact): string {
+  if (redact(text) === text) return text;
+  const whole = redactJsonText(text, redact);
+  if (whole !== undefined) return whole;
+  return text
+    .split("\n")
+    .map((line) => (redact(line) === line ? line : (redactJsonText(line, redact) ?? redact(line))))
+    .join("\n");
+}

package/src/op/runtime.ts

@@ -183,6 +183,48 @@ export interface OpRunRecord {
    * written before 0.124.28.
    */
   statement?: { payloadType: string; payload: string; signatures: { keyid: string; sig: string }[] };
+  /**
+   * Why a failed run failed (#4094), for a reader that acts on it without
+   * reading the log: a short `code`, a one-line `reason`, the phase that
+   * failed and the exit code of the command that failed. `chant ci run`
+   * writes it on every failed job, from the job's pull-request report when
+   * it wrote one (`not-a-reviewer`, `plan-failed`, `failed` and the other
+   * refusals and statuses), else `command-failed`, `setup-failed` or
+   * `build-failed`. Optional within contract 1, written by chant
+   * {@link OP_RUN_FAILURE_FLOOR} and newer; absent on a run that passed and
+   * on a run nothing explained.
+   */
+  failure?: OpRunFailureReason;
+}
+
+/** Why a run failed, on {@link OpRunRecord.failure} and on the run's `run-settle` event (#4094). */
+export interface OpRunFailureReason {
+  /** A short code: a pull-request report's refusal or status, or `command-failed`, `setup-failed`, `build-failed`. */
+  code: string;
+  /** One line a person reads. */
+  reason: string;
+  /** The phase that failed, when one did. */
+  phase?: string;
+  /** The exit code of the command that failed, when it exited with one. */
+  exitCode?: number;
+}
+
+/** The first chant that writes {@link OpRunRecord.failure} and `failure` on `run-settle` (#4094). */
+export const OP_RUN_FAILURE_FLOOR = "0.124.30";
+
+/** `value` as an {@link OpRunFailureReason}, or undefined when it is not one, so a reader drops a malformed field and keeps the record. */
+export function opRunFailureOf(value: unknown): OpRunFailureReason | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  const v = value as Record<string, unknown>;
+  if (typeof v.code !== "string" || v.code === "" || typeof v.reason !== "string") return undefined;
+  if (v.phase !== undefined && typeof v.phase !== "string") return undefined;
+  if (v.exitCode !== undefined && !Number.isInteger(v.exitCode)) return undefined;
+  return {
+    code: v.code,
+    reason: v.reason,
+    ...(typeof v.phase === "string" ? { phase: v.phase } : {}),
+    ...(typeof v.exitCode === "number" ? { exitCode: v.exitCode } : {}),
+  };
 }
 
 /** An {@link OpRunRecord} before the ledger stamps its version and mints an id. */

package/src/op/step-console.ts

@@ -41,6 +41,8 @@ interface StepConsole {
 export interface RunConsole {
   write: (line: string) => void;
   heartbeatMs?: number;
+  /** Applied to each line before it is written, and to a step's call before it is cut to a label (#4096). */
+  redact?: (text: string) => string;
 }
 
 const store = new AsyncLocalStorage<StepConsole>();
@@ -60,7 +62,10 @@ function formatArgs(args: Record<string, unknown>): string {
 /** The name a step's lines carry: its id, else `fn(args)` on one line, cut to {@link MAX_LABEL}. */
 export function stepLabel(fn: string, args: Record<string, unknown>, id?: string): string {
   if (id) return id;
-  const call = `${fn}(${formatArgs(args)})`.replace(/\s+/g, " ");
+  // A secret in the call is redacted before the label is cut, so a cut never leaves part of one.
+  const redact = runStore.getStore()?.redact;
+  const raw = `${fn}(${formatArgs(args)})`;
+  const call = (redact ? redact(raw) : raw).replace(/\s+/g, " ");
   return call.length > MAX_LABEL ? `${call.slice(0, MAX_LABEL - 4)}...)` : call;
 }
 
@@ -72,7 +77,7 @@ export function stepLabel(fn: string, args: Record<string, unknown>, id?: string
 export async function withStepConsole<T>(opts: { phase: string; label: string }, fn: () => Promise<T>): Promise<T> {
   const run = runStore.getStore();
   if (!run) return fn();
-  const { write } = run;
+  const write = run.redact ? (line: string) => run.write(run.redact!(line)) : run.write;
   const prefix = `[${opts.phase}] ${opts.label}`;
   const started = Date.now();
   let spoke = false;

package/src/pr-forge.test.ts

@@ -782,6 +782,31 @@ describe("pull requests over REST (#3798)", () => {
     expect((calls[1].body as { target_branch: string }).target_branch).toBe("main");
   });
 
+  test("openPullRequests lists the heads into a base and marks forks; branchHead reads a branch's commit (#4095)", async () => {
+    const f = fakeFetch({
+      "GET /api/v1/repos/acme/infra/pulls": [
+        { number: 12, head: { ref: "x", sha: "c".repeat(40), repo: { full_name: "mallory/infra" } }, base: { ref: "main", sha: "b".repeat(40) }, user: { login: "mallory" } },
+        { number: 4, head: { ref: "y", sha: "d".repeat(40), repo: { full_name: "acme/infra" } }, base: { ref: "main", sha: "b".repeat(40) }, user: { login: "driver" } },
+        { number: 5, head: { ref: "z", sha: "e".repeat(40) }, base: { ref: "release" } },
+      ],
+      "GET /api/v1/repos/acme/infra/branches/main": { name: "main", commit: { id: "f".repeat(40) } },
+    });
+    const forge = forgejoForge({ ...fjOpts, fetch: f.fetch });
+    expect(await forge.openPullRequests!("main")).toEqual([
+      { number: 4, head: "y", headSha: "d".repeat(40), base: "main", baseSha: "b".repeat(40), author: "driver", fork: false },
+      { number: 12, head: "x", headSha: "c".repeat(40), base: "main", baseSha: "b".repeat(40), author: "mallory", fork: true },
+    ]);
+    expect(f.calls[0].url).toBe("https://forge.example/api/v1/repos/acme/infra/pulls?state=open&limit=50&page=1");
+    expect(await forge.branchHead!("main")).toBe("f".repeat(40));
+    expect(await forge.branchHead!("gone")).toBeUndefined();
+
+    const g = fakeFetch({ "GET /repos/acme/infra/pulls": [], "GET /repos/acme/infra/branches/main": { commit: { sha: SHA } } });
+    const github = githubForge({ ...gh, fetch: g.fetch });
+    expect(await github.openPullRequests!("main")).toEqual([]);
+    expect(g.calls[0].url).toBe("https://api.github.com/repos/acme/infra/pulls?state=open&base=main&per_page=100&page=1");
+    expect(await github.branchHead!("main")).toBe(SHA);
+  });
+
   test("findPullRequest takes the oldest open one from this repository, not a fork's", async () => {
     const f = fakeFetch({
       "GET /api/v1/repos/acme/infra/pulls": [
@@ -887,3 +912,32 @@ describe("pull requests over REST (#3798)", () => {
     await expect(forgejoForge({ ...fjOpts, fetch }).openPullRequest({ head: "h", title: "t", body: "b" })).rejects.toThrow(/no default branch.*pass base/);
   });
 });
+
+describe("setCommitStatus, a runner job's status (#4097)", () => {
+  const long = "x".repeat(300);
+
+  test("GitHub posts state, context, a description cut to 140 and target_url", async () => {
+    const { fetch, calls } = fakeFetch({ [`POST /repos/acme/infra/statuses/${SHA}`]: {} });
+    const forge = githubForge({ apiBase: "https://api.github.com", repo: "acme/infra", token: "t0k", fetch });
+    await forge.setCommitStatus!(SHA, { context: "chant/pr-plan", state: "failure", description: long, targetUrl: "https://host/reports/7/abc/" });
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toMatchObject({ method: "POST", url: `https://api.github.com/repos/acme/infra/statuses/${SHA}` });
+    expect(calls[0].headers.Authorization).toBe("Bearer t0k");
+    expect(calls[0].body).toEqual({ state: "failure", context: "chant/pr-plan", description: "x".repeat(140), target_url: "https://host/reports/7/abc/" });
+  });
+
+  test("Forgejo posts to /repos/{owner}/{repo}/statuses/{sha} under /api/v1, and omits target_url when there is none", async () => {
+    const { fetch, calls } = fakeFetch({ [`POST /api/v1/repos/acme/infra/statuses/${SHA}`]: {} });
+    const forge = forgejoForge({ apiBase: "https://codeberg.org/api/v1", repo: "acme/infra", token: "t0k", host: "codeberg.org", fetch });
+    await forge.setCommitStatus!(SHA, { context: "chant/pr-apply", state: "pending", description: "pr-apply running" });
+    expect(calls[0]).toMatchObject({ method: "POST", url: `https://codeberg.org/api/v1/repos/acme/infra/statuses/${SHA}` });
+    expect(calls[0].headers.Authorization).toBe("token t0k");
+    expect(calls[0].body).toEqual({ state: "pending", context: "chant/pr-apply", description: "pr-apply running" });
+  });
+
+  test("a refusal throws, and GitLab's client has none", async () => {
+    const { fetch } = fakeFetch({ [`POST /repos/acme/infra/statuses/${SHA}`]: 403 });
+    await expect(githubForge({ apiBase: "https://api.github.com", repo: "acme/infra", token: "t", fetch }).setCommitStatus!(SHA, { context: "c", state: "success", description: "d" })).rejects.toBeInstanceOf(ForgeApiError);
+    expect(gitlabForge({ apiBase: "https://gl/api/v4", project: "42", token: "t", fetch }).setCommitStatus).toBeUndefined();
+  });
+});

package/src/pr-forge.ts

@@ -61,6 +61,16 @@ export interface ForgeStatus {
   pipelineId?: number;
 }
 
+/** A runner job's commit status (#4097): the states GitHub and Forgejo both keep. */
+export interface CommitStatus {
+  context: string;
+  state: "pending" | "success" | "failure" | "error";
+  /** Cut to 140 characters. */
+  description: string;
+  /** Where the status links to. Omitted from the request when absent. */
+  targetUrl?: string;
+}
+
 /** A commit status's state, as a caller names it. */
 export type ForgeStatusState = "pending" | "running" | "success" | "failed" | "failure" | "canceled" | "error";
 
@@ -212,6 +222,23 @@ export interface PullRequest {
   base?: string;
 }
 
+/** An open pull request as `chant ci serve` polls it (#4095). */
+export interface OpenPullRequest {
+  number: number;
+  /** Its head branch. */
+  head: string;
+  /** The commit its head branch points at. */
+  headSha: string;
+  /** The branch it merges into. */
+  base: string;
+  /** The base branch's commit as the forge last measured the pull request against it. */
+  baseSha?: string;
+  /** Who opened it. */
+  author?: string;
+  /** Its head branch lives in another repository, a fork. */
+  fork: boolean;
+}
+
 /** What {@link PrForge.mergePullRequest} merges, and how. */
 export interface MergeOptions {
   /** The head commit the caller reviewed. The merge happens only while the pull request's head is still this commit. */
@@ -292,6 +319,14 @@ export interface PrForge {
    */
   addComment(pr: number, body: string): Promise<AddedComment>;
   setStatus(sha: string, status: ForgeStatus): Promise<void>;
+  /**
+   * GitHub and Forgejo (#4097): set a commit status from a runner's job, one
+   * of `pending`, `success`, `failure` or `error`. The request is the one
+   * {@link setStatus} sends (`POST /repos/{owner}/{repo}/statuses/{sha}`), with
+   * the description cut to 140 characters and `target_url` only when given.
+   * `chant ci run` posts a job's progress through it.
+   */
+  setCommitStatus?(sha: string, status: CommitStatus): Promise<void>;
   /**
    * Keep one OPEN tracking issue for `marker` in line with `finding`: open
    * it, update its title and body, or, when `finding` is `null` and
@@ -339,6 +374,13 @@ export interface PrForge {
    * still throw.
    */
   mergePullRequest(pr: number, opts: MergeOptions): Promise<MergeResult>;
+  /**
+   * GitHub and Forgejo (#4095): every open pull request into `base`, with
+   * its head commit, oldest first. `chant ci serve` polls it.
+   */
+  openPullRequests?(base: string): Promise<OpenPullRequest[]>;
+  /** GitHub and Forgejo (#4095): the commit `branch` points at, or undefined when there is no such branch. */
+  branchHead?(branch: string): Promise<string | undefined>;
 }
 
 /** A GitHub or Forgejo client. */
@@ -590,6 +632,14 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
       await api.call("PATCH", `${repo}/issues/${n}`, { state: "closed" });
     },
   };
+  const postStatus = async (sha: string, state: ForgeStatusState, context: string, description: string, url?: string): Promise<void> => {
+    await api.call("POST", `${repo}/statuses/${sha}`, {
+      state: statusStateFor(kind, state),
+      context,
+      description: description.slice(0, GITHUB_DESCRIPTION),
+      ...(url ? { target_url: url } : {}),
+    });
+  };
   return {
     kind,
     host,
@@ -597,12 +647,10 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
     principalOf: (login) => forgePrincipalOf(kind, host, login),
     ...threadCalls(t),
     async setStatus(sha, status) {
-      await api.call("POST", `${repo}/statuses/${sha}`, {
-        state: statusStateFor(kind, status.state),
-        context: status.context,
-        description: status.description.slice(0, GITHUB_DESCRIPTION),
-        ...(status.url ? { target_url: status.url } : {}),
-      });
+      await postStatus(sha, status.state, status.context, status.description, status.url);
+    },
+    async setCommitStatus(sha, status) {
+      await postStatus(sha, status.state, status.context, status.description, status.targetUrl);
     },
     async approvers(pr) {
       // A reviewer's newest deciding review is their standing one. A comment
@@ -667,6 +715,44 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
       const open = listed.filter((p) => fromHere(p, head));
       return open.map(pull).filter((p): p is PullRequest => p !== undefined).sort((a, b) => a.number - b.number)[0];
     },
+    async openPullRequests(base) {
+      // GitHub filters by base server-side; Forgejo's list is matched here.
+      const query = kind === "github" ? `?state=open&base=${encodeURIComponent(base)}` : "?state=open";
+      let listed: unknown[];
+      try {
+        listed = await api.list(`${repo}/pulls${query}`, pageParams, pageSize);
+      } catch (err) {
+        // Forgejo answers 404 while it counts the repository as empty, as findPullRequest notes.
+        if (kind !== "forgejo" || !(err instanceof ForgeApiError) || err.status !== 404) throw err;
+        await api.call("GET", repo);
+        return [];
+      }
+      const out: OpenPullRequest[] = [];
+      for (const v of listed) {
+        if (!isObject(v) || !isObject(v.head) || !isObject(v.base)) continue;
+        const number = num(v.number);
+        const head = str(v.head.ref);
+        const headSha = str(v.head.sha);
+        const into = str(v.base.ref);
+        if (number === undefined || !head || !headSha || into !== base) continue;
+        const baseSha = str(v.base.sha);
+        const author = isObject(v.user) ? str(v.user.login) : undefined;
+        out.push({ number, head, headSha, base: into, ...(baseSha ? { baseSha } : {}), ...(author ? { author } : {}), fork: !fromHere(v, head) });
+      }
+      return out.sort((a, b) => a.number - b.number);
+    },
+    async branchHead(branch) {
+      let b: unknown;
+      try {
+        b = await api.call("GET", `${repo}/branches/${branch.split("/").map(encodeURIComponent).join("/")}`);
+      } catch (err) {
+        if (err instanceof ForgeApiError && err.status === 404) return undefined;
+        throw err;
+      }
+      // GitHub names the commit `sha`, Forgejo `id`.
+      const commit = isObject(b) && isObject(b.commit) ? b.commit : undefined;
+      return commit ? str(commit.sha) ?? str(commit.id) : undefined;
+    },
     async editPullRequest(pr, change) {
       return pull(await api.call("PATCH", `${repo}/pulls/${pr}`, { ...(change.title !== undefined ? { title: change.title } : {}), ...(change.body !== undefined ? { body: change.body } : {}) }));
     },

package/src/pr-loop.test.ts

@@ -13,6 +13,7 @@ import { composeChangeSet, type ChangeSetPart } from "./change-set";
 import {
   describePlanChanged,
   memberCounts,
+  PR_REPORT_DEPLOYED_OUTPUTS_FLOOR,
   PR_REPORT_SCHEMA_ID,
   prApproveCommand,
   prNoteMarker,
@@ -109,6 +110,9 @@ const resumedReport: PrReport = {
   resumed: { applied: ["a"] },
 };
 
+/** A plan whose members read `net` and `a` from the deployed estate (#4104). */
+const deployedReport: PrReport = { ...planReport, deployedOutputs: { a: ["id"], net: ["cidr"], dns: [] } };
+
 describe("the pr-report schema", () => {
   test("is a valid schema and names this module's id", () => {
     expect(validSchema(schema)).toBe(true);
@@ -116,7 +120,7 @@ describe("the pr-report schema", () => {
   });
 
   test("every stage's report validates, and its change set validates against the change-set schema", () => {
-    for (const report of [planReport, refusedReport, appliedReport, resumedReport]) {
+    for (const report of [planReport, refusedReport, appliedReport, resumedReport, deployedReport]) {
       expectValid(report);
       expectValidChangeSet(report.changeSet);
       expect(report.changeSet.digest).toBe(report.digest);
@@ -158,6 +162,14 @@ describe("the note", () => {
     expect(renderPrNote(appliedReport)).not.toContain("Resumed");
   });
 
+  test("a plan that read dependencies from the deployed estate names each and its outputs (#4104)", () => {
+    const note = renderPrNote(deployedReport);
+    expect(note).toContain("Planned against outputs read from the deployed estate: `a` (`id`); `net` (`cidr`); `dns` (none yet).");
+    expect(renderPrNote(planReport)).not.toContain("deployed estate");
+    expect(PR_REPORT_DEPLOYED_OUTPUTS_FLOOR).toBe("0.124.30");
+    expect(schema.required).not.toContain("deployedOutputs");
+  });
+
   test("a small limit leaves the summary out rather than cutting the table", () => {
     const note = renderPrNote(planReport, { limit: 800 });
     expect(note).toContain("| `app` |");

package/src/pr-loop.ts

@@ -46,6 +46,9 @@ export const PR_REPORT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace
 /** The read-contract version the report follows. */
 export const PR_REPORT_CONTRACT = 1;
 
+/** The first chant whose report can carry `deployedOutputs` (#4104). */
+export const PR_REPORT_DEPLOYED_OUTPUTS_FLOOR = "0.124.30";
+
 /** The gate a pull request's apply waits on, unless the pipeline names another. */
 export const PR_APPLY_GATE = "pr-apply";
 
@@ -183,6 +186,14 @@ export interface PrReport {
    * the rest under the same approval and did not run them again.
    */
   resumed?: { applied: string[] };
+  /**
+   * Per dependency a member was planned against, the names of the outputs
+   * read from the deployed estate (#4104), sorted. A dependency outside the
+   * change is here too. Seeded outputs (`--seed-outputs`, a resume record)
+   * are not. Absent when nothing was read. Added within contract 1 by chant
+   * {@link PR_REPORT_DEPLOYED_OUTPUTS_FLOOR}.
+   */
+  deployedOutputs?: Record<string, string[]>;
   approval: PrApproval;
   /** Component names: which changed, which run because they depend on one, and what the change touched that no component deploys. */
   selection: {
@@ -324,6 +335,11 @@ export function renderPrNote(report: PrReport, options: { limit?: number; approv
   if (report.selection.unclaimed.length > 0) {
     out.push("", `Changed, and deployed by no component: ${report.selection.unclaimed.map(code).join(", ")}.`);
   }
+  const deployed = Object.entries(report.deployedOutputs ?? {});
+  if (deployed.length > 0) {
+    const each = deployed.map(([dep, names]) => `${code(dep)} (${names.length > 0 ? names.map(code).join(", ") : "none yet"})`);
+    out.push("", `Planned against outputs read from the deployed estate: ${each.join("; ")}.`);
+  }
   if (report.status !== "nothing") {
     out.push("", `Plan digest: ${code(report.digest)}`, "", ...approvalLines(report, options.approver ?? "<you>"));
   }

package/src/pr-report-url.ts

@@ -35,7 +35,7 @@
  */
 
 import { spawn } from "node:child_process";
-import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -120,6 +120,58 @@ export function reportPut(target: ReportTarget, aws: AwsCli = realAwsCli): Repor
   };
 }
 
+/** Reads one object: `key` below the URL. Resolves null for an object that is not there, and rejects with a line a person can read for any other failure. */
+export type ReportGet = (key: string) => Promise<string | null>;
+
+/** Runs the AWS CLI with `args` and resolves its stdout, rejecting with its error line on a non-zero exit. */
+export type AwsRead = (args: string[]) => Promise<string>;
+
+/** The AWS CLI on PATH, read for the body `aws s3 cp <s3 url> -` prints. */
+export const realAwsRead: AwsRead = (args) =>
+  new Promise((resolveRead, reject) => {
+    const child = spawn(AWS_BINARY, args, { stdio: ["ignore", "pipe", "pipe"] });
+    const out: Buffer[] = [];
+    let stderr = "";
+    child.stdout.on("data", (chunk: Buffer) => out.push(chunk));
+    child.stderr.on("data", (chunk: Buffer) => {
+      if (stderr.length < 4096) stderr += chunk.toString("utf8");
+    });
+    child.on("error", (err: NodeJS.ErrnoException) =>
+      reject(new Error(err.code === "ENOENT" ? "the AWS CLI (aws) is not on PATH; an s3 report URL is read with it" : err.message)),
+    );
+    child.on("close", (code) => {
+      if (code === 0) return resolveRead(Buffer.concat(out).toString("utf8"));
+      const line = stderr.trim().split("\n").filter(Boolean).at(-1) ?? "";
+      reject(new Error(`aws s3 cp exited ${code}${line ? `: ${line.slice(0, 300)}` : ""}`));
+    });
+  });
+
+/** What the AWS CLI says about an object that does not exist. */
+const S3_ABSENT = /\(404\)|Not Found|NoSuchKey|does not exist/i;
+
+/** A get for `target`. `aws` replaces the AWS CLI in a test. */
+export function reportGet(target: ReportTarget, aws: AwsRead = realAwsRead): ReportGet {
+  if (target.scheme === "file") {
+    return async (key) => {
+      try {
+        return readFileSync(join(target.dir, ...key.split("/")), "utf-8");
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+        throw err;
+      }
+    };
+  }
+  return async (key) => {
+    const object = `s3://${target.bucket}/${target.prefix ? `${target.prefix}/` : ""}${key}`;
+    try {
+      return await aws(["s3", "cp", object, "-", "--only-show-errors"]);
+    } catch (err) {
+      if (S3_ABSENT.test(messageOf(err))) return null;
+      throw err;
+    }
+  };
+}
+
 /** A stage's upload: its events as they are written, and its files at the end. */
 export interface PrReportUpload {
   /** The folder the stage's files go to: `<url>/<key>`. */