@intentius/chant 0.105.1 → 0.106.3

package/src/cli/handlers/pr.ts

@@ -5,7 +5,7 @@
  * ```
  * chant components pr-plan  --base <ref> --pr <n> --env <env> [--forge github|gitlab|forgejo]
  * chant approve pr-<n> pr-apply --plan <digest> --approver github:<login> --sign
- * chant components pr-apply --base <ref> --env <env> [--pr <n>] [--forge <kind>] [--require-review]
+ * chant components pr-apply --base <ref> --env <env> [--pr <n>] [--forge <kind>] [--require-review] [--resume <file>]
  * ```
  *
  * Both measure the change from the merge base of `--base` and `HEAD`, select
@@ -18,8 +18,22 @@
  * applies only when an approval stands for that digest. A moved plan stops
  * it with both digests named and nothing applied (exit 3).
  *
+ * `--resume <file>` (#3464) finishes an apply that failed partway, the way
+ * `components fan-out --resume` does (#2417, #3049). The apply writes the
+ * attempt record as each component settles: the change set the gate
+ * approved and the components that applied. Repeated on the same commit
+ * with the same record, it plans only what is left, checks each member
+ * against the approved set (`resumePrSet`) and, when all are covered and the
+ * approval still stands, applies the rest without a fresh approval. When
+ * they are not covered it says why and runs as it would without a record.
+ *
  * Every run writes `pr-plan.json` or `pr-apply.json` (`pr-report.schema.json`),
- * `change-set.json` and `pr-note.md` under `--output` (default `.chant/pr`).
+ * `change-set.json` and `pr-note.md` under `--output` (default `.chant/pr`). *
+ * `--member <name>` (#3465) runs a workspace member's loop: the member's
+ * generated pipeline passes it from the member's directory. The gate is
+ * recorded under `pr-<n>-<member>`, and the note and the statuses carry the
+ * member's name, so each member's loop on one pull request stands apart.
+ * The name must be the member that owns the current directory.
  */
 
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -35,17 +49,20 @@ import {
   planPrSet,
   prReport,
   readOnlyLedger,
+  resumePrSet,
   type PrPlanSet,
 } from "../../components/pr-run";
+import { readFanOutAttempt, writeFanOutAttempt, type FanOutAttempt, type PrApplyRecord } from "../../components/fan-out-record";
+import { samePlanDigest } from "../../lifecycle/plan-digest";
 import { gitGateLedgerPort } from "../../op/gate";
 import {
   describePlanChanged,
   PR_APPLY_GATE,
-  PR_STATUS_CONTEXTS,
   prApproveCommand,
   prNoteMarker,
   prOp,
   prStatusDescription,
+  prStatusContext,
   prStatusState,
   renderPrNote,
   type PrApproval,
@@ -55,6 +72,7 @@ import { FORGE_KINDS, forgeFromEnv, forgePrincipalOf, type ForgeKind, type PrFor
 import { GITHUB_COMMENT_LIMIT, GITLAB_NOTE_LIMIT } from "../../plan-summary";
 import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
 import { formatError, formatInfo, formatSuccess, formatWarning } from "../format";
+import { findWorkspaceRoot } from "../../project-root";
 import { resolveChangedUnits } from "./fan-out";
 import { GATED_EXIT_CODE, recordAutoReleasesForRun } from "./run";
 import type { CommandContext } from "../registry";
@@ -69,6 +87,8 @@ export const PR_REPORT_DIR = ".chant/pr";
 interface Prepared {
   config: ChantConfig;
   env: string;
+  /** The workspace member, with `--member` (#3465). */
+  member?: string;
   base: string;
   head: string;
   gate: string;
@@ -77,7 +97,7 @@ interface Prepared {
   plan: FanOutPlan;
   signal: ComponentChangeSignal;
   registry: CapabilityRegistry;
-  set: PrPlanSet;
+  seededOutputs: Record<string, Record<string, unknown>>;
 }
 
 const fail = (message: string, hint?: string): number => {
@@ -85,7 +105,7 @@ const fail = (message: string, hint?: string): number => {
   return 1;
 };
 
-/** Everything both stages share: the change, the derivation and the plan of every member. */
+/** Everything both stages share: the change and the derivation. Each stage plans the members itself. */
 async function prepare(ctx: CommandContext, stage: "plan" | "apply"): Promise<Prepared | number> {
   const { args } = ctx;
   const projectPath = resolve(".");
@@ -106,6 +126,12 @@ async function prepare(ctx: CommandContext, stage: "plan" | "apply"): Promise<Pr
     );
   }
   if (args.fromAffected) return fail(`pr-${stage} derives the change itself; drop --from-affected`);
+  let member: string | undefined;
+  if (args.members?.length) {
+    const checked = await checkMember(projectPath, args.members);
+    if (typeof checked !== "string") return fail(checked.error, checked.hint);
+    member = checked;
+  }
   if (args.forge !== undefined && !(FORGE_KINDS as readonly string[]).includes(args.forge)) {
     return fail(`--forge ${args.forge} is not one of ${FORGE_KINDS.join(", ")}`);
   }
@@ -156,10 +182,10 @@ async function prepare(ctx: CommandContext, stage: "plan" | "apply"): Promise<Pr
 
   const env = args.env ?? "local";
   const registry = await fanOutRegistry(projectPath, config);
-  const set = await planPrSet({ components: derived.components, plan: derived.plan, registry, env, seededOutputs });
   return {
     config,
     env,
+    ...(member ? { member } : {}),
     base,
     head,
     gate: args.gate ?? PR_APPLY_GATE,
@@ -168,10 +194,41 @@ async function prepare(ctx: CommandContext, stage: "plan" | "apply"): Promise<Pr
     plan: derived.plan,
     signal: derived.signal,
     registry,
-    set,
+    seededOutputs,
   };
 }
 
+/**
+ * The one `--member` name, checked against the workspace member that owns
+ * `projectPath`: a pipeline copied into another member would otherwise
+ * record its gate under the wrong name.
+ */
+async function checkMember(projectPath: string, names: string[]): Promise<string | { error: string; hint?: string }> {
+  if (names.length !== 1) return { error: `pr-plan and pr-apply take one --member, not ${names.join(", ")}` };
+  const name = names[0];
+  const found = findWorkspaceRoot(projectPath);
+  if (!found) return { error: `--member ${name}: no chant.workspace.json above ${projectPath}`, hint: "Drop --member outside a workspace." };
+  const { resolveMemberContext } = await import("../../workspace/member-pipeline");
+  let owner: string | undefined;
+  try {
+    owner = resolveMemberContext(projectPath, found)?.member.name;
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : String(err) };
+  }
+  if (owner !== name) {
+    return {
+      error: `--member ${name}: ${owner ? `this directory belongs to member ${owner}` : "no workspace member owns this directory"}`,
+      hint: "Run the command in the member's directory, the way its generated pipeline does.",
+    };
+  }
+  return name;
+}
+
+/** Plan every member the derivation selects. */
+function planAll(p: Prepared): Promise<PrPlanSet> {
+  return planPrSet({ components: p.components, plan: p.plan, registry: p.registry, env: p.env, seededOutputs: p.seededOutputs });
+}
+
 /** Write the report, the change set and the note; print the note's path. */
 function writeOutputs(ctx: CommandContext, report: PrReport, note: string): void {
   const dir = resolve(ctx.args.output ?? PR_REPORT_DIR);
@@ -185,7 +242,7 @@ function writeOutputs(ctx: CommandContext, report: PrReport, note: string): void
 async function publish(forge: PrForge | undefined, report: PrReport, note: string): Promise<void> {
   if (!forge) return;
   const status = {
-    context: PR_STATUS_CONTEXTS[report.stage],
+    context: prStatusContext(report.stage, report.member),
     state: prStatusState(report),
     description: prStatusDescription(report),
     ...(forge.runUrl ? { url: forge.runUrl } : {}),
@@ -196,8 +253,11 @@ async function publish(forge: PrForge | undefined, report: PrReport, note: strin
     console.error(formatWarning({ message: `could not set the ${status.context} status: ${err instanceof Error ? err.message : String(err)}` }));
   }
   if (report.pr === null) return;
+  // A member the change does not reach has nothing to say: one note per
+  // member would put a line on every pull request for each member it skips.
+  if (report.member && report.status === "nothing") return;
   try {
-    await forge.upsertNote(report.pr, prNoteMarker(report.env), note);
+    await forge.upsertNote(report.pr, prNoteMarker(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)}` }));
   }
@@ -231,28 +291,30 @@ export async function runComponentsPrPlan(ctx: CommandContext): Promise<number>
   }
   const p = await prepare(ctx, "plan");
   if (typeof p === "number") return p;
-  const op = prOp(ctx.args.pr);
+  const set = await planAll(p);
+  const op = prOp(ctx.args.pr, p.member);
 
   let approval: PrApproval = { status: "pending" };
   if (p.plan.order.length > 0) {
     try {
-      approval = approvalOf(await decidePrGate(readOnlyLedger(gitGateLedgerPort()), { op, gate: p.gate, digest: p.set.doc.digest }));
+      approval = approvalOf(await decidePrGate(readOnlyLedger(gitGateLedgerPort()), { op, gate: p.gate, digest: set.doc.digest }));
     } catch (err) {
       console.error(formatWarning({ message: `could not read the gate ledger, so the approval reads as pending: ${err instanceof Error ? err.message : String(err)}` }));
     }
   }
-  const status = p.plan.order.length === 0 ? "nothing" : p.set.failed ? "plan-failed" : "planned";
+  const status = p.plan.order.length === 0 ? "nothing" : set.failed ? "plan-failed" : "planned";
   const report = prReport({
     stage: "plan",
     pr: ctx.args.pr,
     env: p.env,
+    ...(p.member ? { member: p.member } : {}),
     base: p.base,
     head: p.head,
     op,
     gate: p.gate,
     plan: p.plan,
     signal: p.signal,
-    set: p.set,
+    set,
     approval,
     status,
   });
@@ -282,8 +344,24 @@ export async function runComponentsPrApply(ctx: CommandContext): Promise<number>
       return fail(`could not ask ${p.forge.kind} which pull request merged ${p.head}: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
-  const op = pr === null ? "pr-unknown" : prOp(pr);
-  const base = { stage: "apply" as const, pr, env: p.env, base: p.base, head: p.head, op, gate: p.gate, plan: p.plan, signal: p.signal, set: p.set };
+  const op = pr === null ? "pr-unknown" : prOp(pr, p.member);
+
+  // `--resume` (#3464): an earlier attempt at this change on this commit
+  // applied part of an approved set. When the members left are covered by
+  // it and its approval still stands, finish it under that approval.
+  const resumePath = args.resume ? resolve(args.resume) : undefined;
+  let attempt: FanOutAttempt | undefined;
+  if (resumePath) {
+    try {
+      attempt = readFanOutAttempt(resumePath);
+    } catch (err) {
+      return fail(`--resume: could not read "${args.resume}": ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  const resumed = pr !== null && p.plan.order.length > 0 && attempt ? await tryResume(p, attempt, args.resume!, op) : undefined;
+
+  const set = resumed?.set ?? (await planAll(p));
+  const base = { stage: "apply" as const, pr, env: p.env, ...(p.member ? { member: p.member } : {}), base: p.base, head: p.head, op, gate: p.gate, plan: p.plan, signal: p.signal, set };
 
   const stop = async (report: PrReport, code: number): Promise<number> => {
     await finish(ctx, p, report);
@@ -308,7 +386,7 @@ export async function runComponentsPrApply(ctx: CommandContext): Promise<number>
       GATED_EXIT_CODE,
     );
   }
-  if (p.set.failed) {
+  if (set.failed) {
     return stop(
       prReport({
         ...base,
@@ -320,23 +398,28 @@ export async function runComponentsPrApply(ctx: CommandContext): Promise<number>
     );
   }
 
-  const check = await decidePrGate(gitGateLedgerPort(), {
-    op,
-    gate: p.gate,
-    digest: p.set.doc.digest,
-    description: `pull request #${pr}: ${p.plan.order.join(", ")}`,
-  });
-  const approval = approvalOf(check);
-  if (!check.satisfied) {
-    const partial = { ...base, approval, status: "refused" as const };
-    const report = approval.status === "changed"
-      ? prReport({ ...partial, refusal: "plan-changed", message: describePlanChanged({ op, gate: p.gate, digest: p.set.doc.digest, approval }) })
-      : prReport({
-          ...partial,
-          refusal: "not-approved",
-          message: `No approval stands for this plan, so nothing was applied. Approve it: ${prApproveCommand({ op, gate: p.gate, digest: p.set.doc.digest })}; then run the apply again.`,
-        });
-    return stop(report, GATED_EXIT_CODE);
+  let approval: PrApproval;
+  if (resumed) {
+    approval = resumed.approval;
+  } else {
+    const check = await decidePrGate(gitGateLedgerPort(), {
+      op,
+      gate: p.gate,
+      digest: set.doc.digest,
+      description: `pull request #${pr}: ${p.plan.order.join(", ")}`,
+    });
+    approval = approvalOf(check);
+    if (!check.satisfied) {
+      const partial = { ...base, approval, status: "refused" as const };
+      const report = approval.status === "changed"
+        ? prReport({ ...partial, refusal: "plan-changed", message: describePlanChanged({ op, gate: p.gate, digest: set.doc.digest, approval }) })
+        : prReport({
+            ...partial,
+            refusal: "not-approved",
+            message: `No approval stands for this plan, so nothing was applied. Approve it: ${prApproveCommand({ op, gate: p.gate, digest: set.doc.digest })}; then run the apply again.`,
+          });
+      return stop(report, GATED_EXIT_CODE);
+    }
   }
 
   if (args.requireReview && p.forge) {
@@ -364,10 +447,115 @@ export async function runComponentsPrApply(ctx: CommandContext): Promise<number>
     }
   }
 
-  const applied = await applyPrSet({ components: p.components, plan: p.plan, registry: p.registry, env: p.env, set: p.set });
+  // The record is written before the first component runs and again as each
+  // one settles, so a run killed partway still knows what applied.
+  const prior = resumed ? { completed: resumed.completed, outputs: resumed.outputs } : { completed: [], outputs: {} };
+  const completedSoFar = new Set<string>(prior.completed);
+  const failedSoFar: string[] = [];
+  const outputsSoFar: Record<string, Record<string, unknown>> = { ...prior.outputs };
+  const record: PrApplyRecord = {
+    op,
+    gate: p.gate,
+    head: p.head,
+    digest: set.doc.digest,
+    approvedBy: approval.approvedBy ?? [],
+    members: set.members,
+    changeSet: set.doc,
+    planOutputs: set.outputs,
+  };
+  const recordAttempt = (): void => {
+    if (!resumePath) return;
+    writeFanOutAttempt(resumePath, {
+      digest: p.plan.digest,
+      completed: [...completedSoFar].sort(),
+      failed: [...failedSoFar].sort(),
+      outputs: outputsSoFar,
+      prApply: record,
+    });
+  };
+  recordAttempt();
+
+  const applied = await applyPrSet({
+    components: p.components,
+    plan: resumed?.plan ?? p.plan,
+    registry: p.registry,
+    env: p.env,
+    set,
+    ...(resumed ? { resumed: prior } : {}),
+    ...(resumePath
+      ? {
+          onComponentSettled: (settled, outputs) => {
+            if (settled.status === "ok") {
+              completedSoFar.add(settled.component);
+              if (outputs) outputsSoFar[settled.component] = outputs;
+            } else if (settled.status === "fail") {
+              failedSoFar.push(settled.component);
+            }
+            recordAttempt();
+          },
+        }
+      : {}),
+  });
+  recordAttempt();
   await recordAutoReleasesForRun(applied.run.results, p.env, `${op}-${Date.now()}`, resolveAutoReleaseDisabled(p.config, args.noReleaseRecord));
-  const report = prReport({ ...base, approval, status: applied.status, members: applied.members });
+  const report = prReport({
+    ...base,
+    approval,
+    status: applied.status,
+    members: applied.members,
+    ...(resumed ? { resumed: resumed.completed } : {}),
+  });
   const code = await stop(report, applied.status === "applied" ? 0 : 1);
   if (applied.status === "applied") console.error(formatSuccess(`applied the plan ${report.digest} approved by ${(approval.approvedBy ?? []).join(", ")}`));
   return code;
 }
+
+interface Resumed {
+  plan: FanOutPlan;
+  set: PrPlanSet;
+  approval: PrApproval;
+  completed: string[];
+  outputs: Record<string, Record<string, unknown>>;
+}
+
+/**
+ * Whether `attempt` finishes here (#3464). It carries only when it was made
+ * by an apply of this pull request's gate, on this commit, for this
+ * derivation; when its approval still stands; and when every member left is
+ * covered by the approved set. Otherwise it says why on stderr and the apply
+ * runs as it would with no record.
+ */
+async function tryResume(p: Prepared, attempt: FanOutAttempt, file: string, op: string): Promise<Resumed | undefined> {
+  const skip = (why: string): undefined => {
+    console.error(formatWarning({ message: `--resume: "${file}" does not carry: ${why}`, hint: "Every member is planned again, and the plan needs an approval of its own." }));
+    return undefined;
+  };
+  const record = attempt.prApply;
+  if (!record) return skip("it was not written by pr-apply");
+  if (record.op !== op || record.gate !== p.gate) return skip(`it records ${record.op} ${record.gate}, not ${op} ${p.gate}`);
+  if (record.head !== p.head) return skip(`it records an apply of ${record.head.slice(0, 12)}, not ${p.head.slice(0, 12)}`);
+  if (!samePlanDigest(attempt.digest, p.plan.digest)) return skip("the change selects other components than it did");
+  if (attempt.completed.length === 0) return undefined;
+
+  let check;
+  try {
+    check = await decidePrGate(readOnlyLedger(gitGateLedgerPort()), { op, gate: p.gate, digest: record.digest });
+  } catch (err) {
+    return skip(`could not read the gate ledger: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (!check.satisfied) return skip(`no approval stands for the plan it applied (${record.digest}) any more`);
+
+  const outputs = Object.fromEntries(Object.entries(attempt.outputs).filter(([name]) => attempt.completed.includes(name)));
+  const resumed = await resumePrSet({
+    components: p.components,
+    plan: p.plan,
+    registry: p.registry,
+    env: p.env,
+    seededOutputs: p.seededOutputs,
+    record,
+    completed: attempt.completed,
+  });
+  if (!resumed.ok) return skip(`what is left is not what was approved. ${resumed.reasons.join("; ")}`);
+  console.error(formatInfo(`resume  : ${attempt.completed.join(", ")} applied in an earlier attempt; applying ${resumed.plan.order.join(", ") || "nothing more"} under the approval of ${record.digest}`));
+  return { plan: resumed.plan, set: resumed.set, approval: approvalOf(check), completed: attempt.completed, outputs };
+}

package/src/cli/handlers/promote.test.ts

@@ -61,8 +61,9 @@ vi.mock("../../components/fan-out-support", () => ({
 vi.mock("../../op/gate", async () => {
   const actual = await vi.importActual<typeof import("../../op/gate")>("../../op/gate");
   const port = actual.memoryGateLedgerPort();
-  return { ...actual, gitGateLedgerPort: () => port };
+  return { ...actual, gitGateLedgerPort: () => port, gateIsSealed: async (gate: string) => sealedGates.has(gate) };
 });
+const sealedGates = new Set<string>();
 
 // The run handler pulls in every runtime; the promote needs only its exit code.
 vi.mock("./run", () => ({ GATED_EXIT_CODE: 3 }));
@@ -113,6 +114,7 @@ let errors: string[];
 let logs: string[];
 
 beforeEach(() => {
+  sealedGates.clear();
   ran.length = 0;
   publishedDigest = "sha256:api";
   failApplyFor = undefined;
@@ -186,6 +188,18 @@ describe("chant components promote", () => {
     expect(ran).not.toContain("prod:apply");
     expect(appendReleaseRecordMock).not.toHaveBeenCalled();
     expect(errors.join("\n")).toMatch(/chant approve api prod-release/);
+    expect(errors.join("\n")).not.toContain("--sign");
+  });
+
+  test("a sealed gate's approve line carries --sign (#3521)", async () => {
+    sealedGates.add("prod-release");
+    const gated: DriverComponent = {
+      ...api,
+      deploy: [...api.deploy.slice(0, 2), { phase: "Apply", steps: [{ kind: "gate", gate: "prod-release" }, { kind: "apply" }] }],
+    };
+    resolveTargetsMock.mockResolvedValue({ success: true, targets: [gated] });
+    expect(await runComponentsPromote(ctx({}))).toBe(3);
+    expect(errors.join("\n")).toMatch(/approve : chant approve api prod-release.* --sign/);
   });
 
   test("a component that deployed is recorded even when another one failed", async () => {

package/src/cli/handlers/promote.ts

@@ -47,7 +47,7 @@ import {
 } from "../../components/promote";
 import type { DriverComponent } from "../../components/driver";
 import { summaryLedgerPrefix, writeGatedRunSummary } from "../../op/gate-summary";
-import { approveCommand, describeGateMismatch } from "../../op/gate";
+import { approveCommand, describeGateMismatch, gateIsSealed } from "../../op/gate";
 import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
 import { GATED_EXIT_CODE } from "./run";
@@ -248,12 +248,14 @@ async function deployPlan(
     const pending = run.gate;
     console.error(formatWarning({ message: `component "${run.gatedComponent}" is gated on "${pending.gate}" — pending approval` }));
     // #2574: an approval stands, but for another environment, plan or none.
+    const sealed = await gateIsSealed(pending.gate);
     if (run.gateMismatch) {
-      console.error(formatWarning({ message: describeGateMismatch(pending.op, pending.gate, run.gateMismatch) }));
+      console.error(formatWarning({ message: describeGateMismatch(pending.op, pending.gate, run.gateMismatch, sealed) }));
     }
-    console.error(formatInfo(`approve : ${approveCommand(pending.op, pending.gate, pending.environment)}`));
+    console.error(formatInfo(`approve : ${approveCommand(pending.op, pending.gate, pending.environment, undefined, sealed)}`));
     console.error(formatInfo(`then run the same ${verb} again`));
     writeGatedRunSummary({
+      sealed,
       op: pending.op,
       gate: pending.gate,
       ...(pending.description ? { description: pending.description } : {}),