@intentius/chant 0.124.41 → 0.124.43

package/src/cli/handlers/pr-before-merge.test.ts

@@ -0,0 +1,276 @@
+/**
+ * `chant components pr-apply --before-merge` (#4301, ws-106): the workflow
+ * read at base and the four requires checks, asked of a fake GitHub before
+ * any of the head's code loads, then the pull request's own gate, and the
+ * apply locks under ci.locks. Git, the change signal, the derivation and the
+ * gate ledger are fakes, as in pr.test.ts.
+ */
+
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import type { DriverComponent } from "../../components/driver";
+import type { DeployContext } from "../../components/capability";
+import type { ParsedArgs } from "../registry";
+
+const HEAD = "a".repeat(40);
+const BASE = "b".repeat(40);
+
+/** The security groups pr-apply reads from the declaration (#4168); none unless a test sets them. */
+let groups: string[] = [];
+vi.mock("../../workspace/security", async (original) => ({
+  ...(await original<typeof import("../../workspace/security")>()),
+  securityGroupsAt: () => new Set(groups),
+}));
+
+/** The ci.hooks pr-plan and pr-apply read at base (#4288); none unless a test sets them. */
+let hooksAtBase: Record<string, unknown> = {};
+vi.mock("../../components/pr-hooks", async (original) => ({
+  ...(await original<typeof import("../../components/pr-hooks")>()),
+  prLoopHooksAt: (_cwd: string, base: string) => ({ hooks: hooksAtBase, base }),
+}));
+/** `ci.locks` pr-apply reads at base (#4293), and the locks other pull requests hold; none unless a test sets them. */
+let locksMode: "apply" | "plan" | null = null;
+let heldLocks: (gate: string, targets: readonly string[], pr: number | null) => Promise<unknown[]> = async () => [];
+vi.mock("../../workspace/ci-locks", () => ({ ciLocksAt: () => locksMode }));
+let taken: unknown[] = [];
+vi.mock("../../lifecycle/target-lock", async (original) => ({
+  ...(await original<typeof import("../../lifecycle/target-lock")>()),
+  heldTargetLocks: (gate: string, targets: readonly string[], pr: number | null) => heldLocks(gate, targets, pr),
+  takeTargetLocks: async (gate: string, targets: readonly string[], holder: unknown) => {
+    taken.push({ gate, targets, holder });
+    return { ok: true, taken: [...targets].sort(), released: [], expired: [], pushed: false };
+  },
+}));
+/** The ci.workflow pr-apply --before-merge reads at base (#4301). */
+let workflowAtBase: string | null = "apply-before-merge";
+vi.mock("../../workspace/ci-workflow-at", () => ({ ciWorkflowAt: () => workflowAtBase }));
+/** Whether the head's code was loaded: the config read and the derivation. */
+let loaded: string[] = [];
+
+/** What ci.policy at base says (#4294): no policy unless a test sets a verdict. The engine itself is gate-policy.test.ts's. */
+let policyVerdict: import("../../gate-policy").GatePolicyVerdict | undefined;
+vi.mock("../../components/pr-policy", async (original) => ({
+  ...(await original<typeof import("../../components/pr-policy")>()),
+  prLoopPolicyAt: (_cwd: string, base: string) => ({ base }),
+  runPrPolicy: () => policyVerdict,
+}));
+vi.mock("../../override-gate", async (original) => ({
+  ...(await original<typeof import("../../override-gate")>()),
+  overridersAt: (_repo: string, base: string) => ({ base, path: ".chant/overriders", active: true, principals: ["github:carol"] }),
+}));
+
+vi.mock("../../components/changed-files", () => ({
+  resolveCommit: async () => HEAD,
+  resolveMergeBase: async () => BASE,
+}));
+
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return { ...actual, loadChantConfig: async () => { loaded.push("config"); return { config: {} }; } };
+});
+
+vi.mock("./fan-out", () => ({
+  resolveChangedUnits: async () => ({ units: { changed: ["net"], indeterminate: [] } }),
+}));
+
+// #4022: pr-apply stores the change set its gate binds on chant/lifecycle and
+// pushes it. These tests run in the chant checkout, so the store is replaced:
+// it must never write or push the real repository's lifecycle branch.
+vi.mock("../../lifecycle/gate-change-set", () => ({
+  storeGateChangeSet: async () => ({ written: false }),
+  readGraphIds: async () => ({ ids: [] }),
+  setGraphIdReader: () => {},
+  gateGraphReader: () => async () => ({ ids: [] }),
+}));
+vi.mock("../../lifecycle/git", async () => {
+  const actual = await vi.importActual<typeof import("../../lifecycle/git")>("../../lifecycle/git");
+  return { ...actual, pushLifecycleReport: async () => { throw new Error("pr.test must not push chant/lifecycle"); } };
+});
+
+vi.mock("./run", () => ({
+  GATED_EXIT_CODE: 3,
+  autoReleaseRun: (id: string) => ({ runId: id, runOrigin: { forge: "local" } }),
+  recordAutoReleasesForRun: async () => [],
+}));
+
+let gateLedger: ReturnType<typeof import("../../op/gate").memoryGateLedgerPort>;
+vi.mock("../../op/gate", async () => {
+  const actual = await vi.importActual<typeof import("../../op/gate")>("../../op/gate");
+  return { ...actual, gitGateLedgerPort: () => gateLedger, gateIsSealed: async () => false };
+});
+
+const failing = new Set<string>();
+/** The error a root's apply throws, in place of applying (#3997). */
+const refusal = new Map<string, Error>();
+/** Called as a component's apply starts, before it can fail. */
+let onRun: (root: string) => void = () => {};
+vi.mock("../../components/fan-out-support", async () => {
+  const { CapabilityRegistry } = await import("../../components/capability");
+  const { planFanOut } = await import("../../components/fan-out");
+  const { computePlanDigest } = await import("../../lifecycle/plan-digest");
+  const registry = new CapabilityRegistry();
+  registry.register({
+    kind: "fake-root",
+    async plan(_ctx: DeployContext, input: { root: string }) {
+      const planDigest = computePlanDigest("fake-root", { root: input.root });
+      return {
+        member: input.root,
+        planDigest,
+        artifact: { planDigest },
+        changeSet: { member: { member: input.root, lexicon: "terraform", planner: "tofu", status: "planned", planDigest, holes: [] }, entries: [] },
+      };
+    },
+    async outputs() {
+      return {};
+    },
+    async run(_ctx: DeployContext, input: { root: string }) {
+      onRun(input.root);
+      if (refusal.has(input.root)) throw refusal.get(input.root);
+      if (failing.has(input.root)) throw new Error(`${input.root} failed`);
+      return { outputs: {} };
+    },
+  } as never);
+  return {
+    fanOutRegistry: async () => registry,
+    deriveFanOut: async () => (loaded.push("derive"), {
+      success: true,
+      components: ESTATE,
+      plan: planFanOut({ components: ESTATE, changed: ["net"] }),
+      signal: { changed: ["net"], indeterminate: [], unclaimed: [] },
+    }),
+  };
+});
+
+const root = (name: string, dependsOn: string[] = []): DriverComponent => ({
+  name,
+  dependsOn,
+  deploy: [{ phase: "Apply", steps: [{ kind: "fake-root", root: name }] }],
+});
+const ESTATE: DriverComponent[] = [root("net"), root("app", ["net"])];
+
+const { memoryGateLedgerPort } = await import("../../op/gate");
+const { runComponentsPrApply, runComponentsPrPlan } = await import("./pr");
+
+let dir: string;
+let out: string[];
+let errors: string[];
+
+const ctx = (a: Partial<ParsedArgs>) =>
+  ({ args: { command: "components", path: "pr-apply", format: "", fix: false, watch: false, verbose: false, help: false, live: false, base: "main", env: "prod", output: dir, pr: 12, forge: "github", beforeMerge: true, ...a } as ParsedArgs, plugins: [] }) as never;
+
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), "pr-before-merge-"));
+  taken = [];
+  workflowAtBase = "apply-before-merge";
+  loaded = [];
+  out = [];
+  errors = [];
+  failing.clear();
+  refusal.clear();
+  onRun = () => {};
+  groups = [];
+  hooksAtBase = {};
+  locksMode = null;
+  heldLocks = async () => [];
+  policyVerdict = undefined;
+  gateLedger = memoryGateLedgerPort();
+  vi.spyOn(process.stdout, "write").mockImplementation((chunk: string | Uint8Array) => { out.push(String(chunk)); return true; });
+  vi.spyOn(console, "error").mockImplementation((...m: unknown[]) => { errors.push(m.map(String).join(" ")); });
+  vi.spyOn(console, "log").mockImplementation(() => {});
+});
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+  vi.unstubAllEnvs();
+  await rm(dir, { recursive: true, force: true });
+});
+
+/** The digest pr-plan printed, read back from its report. */
+async function plannedDigest(): Promise<string> {
+  const { readFile } = await import("node:fs/promises");
+  return JSON.parse(await readFile(join(dir, "pr-plan.json"), "utf8")).digest as string;
+}
+
+/** Pull request 12 on a fake GitHub, its head HEAD unless `over` says otherwise. */
+function serveGithub(over: { head?: string; reviews?: unknown[]; mergeable?: boolean | null; behind?: number; statuses?: unknown[] } = {}): void {
+  const ok = (value: unknown) => ({ ok: true, status: 200, text: async () => JSON.stringify(value) });
+  vi.stubEnv("GITHUB_REPOSITORY", "acme/infra");
+  vi.stubEnv("GITHUB_TOKEN", "t0k");
+  vi.stubEnv("GITHUB_API_URL", "https://api.github.test");
+  vi.stubEnv("GITHUB_SERVER_URL", "https://github.com");
+  vi.stubGlobal("fetch", async (url: string, init: { method: string }) => {
+    const { pathname } = new URL(url);
+    if (init.method !== "GET") return ok({ id: 1 });
+    const pull = "/repos/acme/infra/pulls/12";
+    if (pathname === pull) return ok({ number: 12, state: "open", user: { login: "carol" }, head: { ref: "f", sha: over.head ?? HEAD }, base: { ref: "main" }, mergeable: over.mergeable === undefined ? true : over.mergeable, mergeable_state: "clean" });
+    if (pathname === `${pull}/reviews`) return ok(over.reviews ?? [{ user: { login: "bob" }, state: "APPROVED", commit_id: HEAD }]);
+    if (pathname === `${pull}/commits`) return ok([{ author: { login: "carol" }, committer: { login: "carol" } }]);
+    if (pathname === `/repos/acme/infra/compare/main...${HEAD}`) return ok({ behind_by: over.behind ?? 0 });
+    if (pathname === `/repos/acme/infra/commits/${HEAD}/status`) return ok({ statuses: over.statuses ?? [{ context: "chant/plan", state: "success" }, { context: "chant/apply", state: "failure" }] });
+    if (pathname === `/repos/acme/infra/commits/${HEAD}/check-runs`) return ok({ check_runs: [] });
+    return ok([]);
+  });
+}
+
+const applyReport = async () => {
+  const { readFile } = await import("node:fs/promises");
+  return JSON.parse(await readFile(join(dir, "pr-apply.json"), "utf8")) as Record<string, unknown> & { beforeMerge?: { requires: Array<{ name: string; passed: boolean; reason: string }> } };
+};
+
+describe("pr-apply --before-merge (#4301)", () => {
+  test("without apply-before-merge at base it refuses before-merge-off, and none of the head's code loads", async () => {
+    workflowAtBase = "trunk-curated";
+    serveGithub();
+    expect(await runComponentsPrApply(ctx({}))).toBe(1);
+    const report = await applyReport();
+    expect(report).toMatchObject({ stage: "apply", pr: 12, status: "refused", refusal: "before-merge-off", beforeMerge: { requires: [] } });
+    expect(report.message).toContain("sets ci.workflow to trunk-curated");
+    expect(loaded).toEqual([]);
+  });
+
+  test("an unmet require refuses requires-unmet with each check in the report, and none of the head's code loads", async () => {
+    serveGithub({ behind: 2, reviews: [{ user: { login: "carol" }, state: "APPROVED", commit_id: HEAD }] });
+    expect(await runComponentsPrApply(ctx({}))).toBe(3);
+    const report = await applyReport();
+    expect(report).toMatchObject({ status: "refused", refusal: "requires-unmet" });
+    expect(report.beforeMerge!.requires.map((r) => [r.name, r.passed])).toEqual([["approved", false], ["mergeable", true], ["undiverged", false], ["checks", true]]);
+    expect(report.message).toContain("undiverged: aaaaaaaa is 2 commits behind main");
+    expect(loaded).toEqual([]);
+  });
+
+  test("it needs --pr and --forge, and takes no --green", async () => {
+    expect(await runComponentsPrApply(ctx({ pr: undefined }))).toBe(1);
+    expect(await runComponentsPrApply(ctx({ forge: undefined }))).toBe(1);
+    expect(await runComponentsPrApply(ctx({ green: true }))).toBe(1);
+    expect(loaded).toEqual([]);
+  });
+
+  test("all four passed: the pull request's own gate decides, and an unapproved plan applies nothing", async () => {
+    serveGithub();
+    expect(await runComponentsPrApply(ctx({}))).toBe(3);
+    const report = await applyReport();
+    expect(report).toMatchObject({ status: "refused", refusal: "not-approved", op: "pr-12" });
+    expect(report.beforeMerge!.requires.every((r) => r.passed)).toBe(true);
+  });
+
+  test("approved: it applies at the head, and under ci.locks holds apply locks on what it reaches", async () => {
+    serveGithub();
+    await runComponentsPrPlan(ctx({ beforeMerge: false, forge: undefined, noStatus: true }));
+    const { readFile } = await import("node:fs/promises");
+    const digest = JSON.parse(await readFile(join(dir, "pr-plan.json"), "utf8")).digest as string;
+    gateLedger = memoryGateLedgerPort({
+      resolutions: [{ version: 1, kind: "resolution", op: "pr-12", gate: "pr-apply", resolvedBy: "github:bob", timestamp: new Date().toISOString(), planDigest: digest }],
+    });
+    locksMode = "apply";
+    const ran: string[] = [];
+    onRun = (r) => void ran.push(r);
+    expect(await runComponentsPrApply(ctx({}))).toBe(0);
+    expect(ran).toEqual(["net", "app"]);
+    expect(taken).toEqual([{ gate: "pr-apply", targets: ["net", "app"], holder: expect.objectContaining({ pr: 12, stage: "apply", head: HEAD }) }]);
+    expect(await applyReport()).toMatchObject({ status: "applied", beforeMerge: { requires: expect.any(Array) } });
+  });
+});

package/src/cli/handlers/pr.ts

@@ -106,6 +106,7 @@ import {
   prStatusState,
   renderPrNote,
   type PrApproval,
+  type PrBeforeMerge,
   type PrMember,
   type PrPolicyReport,
   type PrReport,
@@ -173,6 +174,8 @@ export interface Prepared {
   policy: PrLoopPolicy;
   /** What the policy said about the plan, for the report's `policy`. */
   policyReport?: PrPolicyReport;
+  /** `pr-apply --before-merge` (#4301): the requires checks, for the report's `beforeMerge`. */
+  beforeMerge?: PrBeforeMerge;
 }
 
 const fail = (message: string, hint?: string): number => {
@@ -495,6 +498,7 @@ async function finish(ctx: CommandContext, p: Prepared, report: PrReport, upload
   if (p.hookFailed) report = { ...report, message: p.hookFailed };
   if (p.routedAway && report.status === "nothing" && !report.message) report = { ...report, message: p.routedAway };
   if (p.policyReport) report = { ...report, policy: p.policyReport };
+  if (p.beforeMerge) report = { ...report, beforeMerge: p.beforeMerge };
   const note = noteFor(report, p.forge);
   writeOutputs(ctx, report, note, upload);
   if (!ctx.args.noStatus) await publish(p.forge, report, note);
@@ -730,10 +734,19 @@ async function overdueOps(forge: PrForge | undefined, member: string | undefined
 /** chant components pr-apply --base <ref> [--pr <n>] [--env <env>] [--gate <name>] [--forge <kind>] [--require-review] [--output <dir>] [--json] [--events-json] [--report-url <url>] */
 export function runComponentsPrApply(ctx: CommandContext): Promise<number> {
   if (refusesEventsWithJson(ctx.args, "the stage's report")) return Promise.resolve(1);
-  return withStageEvents("pr-apply", ctx, (events) => withComponentEndpoint(ctx, () => prApply(ctx, events)));
+  return withStageEvents("pr-apply", ctx, async (events) => {
+    // #4301: an apply before merge asks the forge its requires checks before any of the head's code loads, the config included.
+    let beforeMerge: PrBeforeMerge | undefined;
+    if (ctx.args.beforeMerge) {
+      const checked = await beforeMergeChecks(ctx);
+      if (typeof checked === "number") return checked;
+      beforeMerge = checked;
+    }
+    return withComponentEndpoint(ctx, () => prApply(ctx, events, beforeMerge));
+  });
 }
 
-async function prApply(ctx: CommandContext, stage: StageEvents): Promise<number> {
+async function prApply(ctx: CommandContext, stage: StageEvents, beforeMerge?: PrBeforeMerge): Promise<number> {
   // #4168: the review-rules security group turns --require-review on, read from the declaration at base.
   const { securityGroupsAt } = await import("../../workspace/security");
   const reviewRules = !ctx.args.requireReview && securityGroupsAt(process.cwd(), ctx.args.base).has("review-rules");
@@ -756,6 +769,7 @@ async function prApply(ctx: CommandContext, stage: StageEvents): Promise<number>
   }
   const p = await prepare(ctx, "apply");
   if (typeof p === "number") return p;
+  if (beforeMerge) p.beforeMerge = beforeMerge;
 
   let pr: number | null = args.pr ?? null;
   if (pr === null && !green && p.forge && p.plan.order.length > 0) {
@@ -876,6 +890,12 @@ async function prApply(ctx: CommandContext, stage: StageEvents): Promise<number>
   }
   const unspent = await spendPolicy(op, judged, p.head);
   if (unspent) return stop(prReport({ ...base, approval, status: "refused", refusal: "policy-denied", message: unspent }), 1);
+  // #4293, #4301: under ci.locks an apply before merge holds its targets until the pull request merges or closes.
+  if (locks && beforeMerge && pr !== null) {
+    const taken = await takeApplyLocks(p, pr);
+    if (typeof taken === "number") return taken;
+    if (taken) return stop(prReport({ ...base, approval, status: "refused", refusal: "locked", message: taken }), GATED_EXIT_CODE);
+  }
 
   // The record is written before the first component runs and again as each
   // one settles, so a run killed partway still knows what applied.
@@ -1014,6 +1034,94 @@ async function heldLocksOf(p: Prepared, pr: number | null): Promise<string | nul
   return `${describeHeldTargetLocks(held, name)}, so nothing was applied. Apply again once ${holders.length === 1 ? "it merges or closes" : "they merge or close"}, or after \`chant unlock --pr ${holders[0]}${p.gate === PR_APPLY_GATE ? "" : ` --gate ${p.gate}`}\`${isOpen ? "" : ". Without --forge every lock counts as held"}.`;
 }
 
+/**
+ * `pr-apply --before-merge` (#4301, ws-106), before any of the head's code
+ * loads: the declaration at base must set `ci.workflow: "apply-before-merge"`
+ * for the member, and the forge must say the pull request is approved,
+ * mergeable, undiverged and green at the commit checked out. Returns the
+ * checks for the report, or the exit code once it wrote a refusal.
+ */
+async function beforeMergeChecks(ctx: CommandContext): Promise<PrBeforeMerge | number> {
+  const { args } = ctx;
+  if (args.green) return fail("--before-merge applies an open pull request's head and --green a green commit; pass one of them");
+  if (args.waveGate) return fail("--before-merge applies the pull request's plan in one run, so it takes no --wave-gate");
+  if (args.pr === undefined) return fail("--before-merge applies an open pull request, so it needs --pr <n>");
+  if (!args.forge || !(FORGE_KINDS as readonly string[]).includes(args.forge)) return fail("--before-merge asks the forge whether the pull request is ready, so it needs --forge github|gitlab|forgejo");
+  if (!args.base) return fail("pr-apply needs the commit the change is measured from: --base <ref>", "Before merge, the target branch's commit.");
+  const cwd = resolve(".");
+  let forge: PrForge;
+  let head: string;
+  let base: string;
+  try {
+    forge = forgeFromEnv(args.forge as ForgeKind);
+    head = await resolveCommit(cwd, args.head ?? "HEAD");
+    base = await resolveMergeBase(cwd, args.base, head);
+  } catch (err) {
+    return fail(err instanceof Error ? err.message : String(err));
+  }
+  const member = args.members?.[0];
+  const gate = args.gate ?? PR_APPLY_GATE;
+  const { ciWorkflowAt } = await import("../../workspace/ci-workflow-at");
+  const { appliesBeforeMerge } = await import("../../workspace/ci-workflow");
+  const { checkPrRequires, unmetRequires } = await import("../../pr-requires");
+  const workflow = ciWorkflowAt(cwd, args.base, member);
+  const early = earlyStop(ctx, forge, { pr: args.pr, base, head, gate, ...(member ? { member } : {}) });
+  if (!appliesBeforeMerge(workflow)) {
+    return early(
+      { requires: [] },
+      "before-merge-off",
+      `The declaration at base sets ci.workflow to ${workflow ?? "nothing"}${member ? ` for ${member}` : ""}, and only apply-before-merge applies a pull request before it merges (ws-106). Nothing was applied.`,
+      1,
+    );
+  }
+  // The apply's own statuses never hold it back: chant ci run's, and the report's.
+  const ignore = [`chant/${gate}`, `chant/${PR_APPLY_GATE}`, prStatusContext("apply", member)];
+  // No `only`: ws-106 gives the declaration no way to leave a check out, so all four are asked (#4336).
+  const requires = await checkPrRequires(forge, args.pr, head, { ignore });
+  for (const r of requires) console.error(formatInfo(`${r.name}: ${r.passed ? "passed" : r.pending ? "pending" : "unmet"}, ${r.reason}`));
+  const unmet = unmetRequires(requires);
+  if (unmet) {
+    return early({ requires }, "requires-unmet", `${forge.kind === "gitlab" ? `Merge request !${args.pr}` : `Pull request ${args.pr}`} is not ready to apply before merge: ${unmet}. Nothing was applied.`, GATED_EXIT_CODE);
+  }
+  return { requires };
+}
+
+/** The refusal report of an apply before merge stopped before it planned (#4301): nothing selected, nothing planned. */
+function earlyStop(ctx: CommandContext, forge: PrForge, at: { pr: number; base: string; head: string; gate: string; member?: string }) {
+  return async (beforeMerge: PrBeforeMerge, refusal: "requires-unmet" | "before-merge-off", message: string, code: number): Promise<number> => {
+    const plan = { order: [], waves: [], skipped: [], seeds: [], indeterminate: [] } as unknown as FanOutPlan;
+    const signal = { changed: [], indeterminate: [], unclaimed: [] } as unknown as ComponentChangeSignal;
+    const p = { env: ctx.args.env ?? "local", base: at.base, head: at.head, gate: at.gate, forge, hookOutcomes: [], beforeMerge, ...(at.member ? { member: at.member } : {}) } as unknown as Prepared;
+    const set: PrPlanSet = { doc: composeChangeSet([]), members: [], plans: {}, outputs: {}, failed: false };
+    const report = prReport({ stage: "apply", pr: at.pr, env: p.env, ...(at.member ? { member: at.member } : {}), base: at.base, head: at.head, op: prOp(at.pr, at.member), gate: at.gate, plan, signal, set, approval: { status: "pending" }, status: "refused", refusal, message });
+    return stopper(ctx, p, undefined, undefined)(report, code);
+  };
+}
+
+/**
+ * Take `apply` locks on the targets an apply before merge reaches (#4293,
+ * #4301), held for pull request `pr` until it merges or closes. Returns the
+ * refusal when another open pull request holds one, null once taken, or the
+ * exit code when the locks could not be written.
+ */
+async function takeApplyLocks(p: Prepared, pr: number): Promise<string | null | number> {
+  const { takeTargetLocks, describeHeldTargetLocks } = await import("../../lifecycle/target-lock");
+  const isOpen = p.forge?.pullRequestOpen?.bind(p.forge);
+  const by = process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER ?? "unknown";
+  let result;
+  try {
+    result = await takeTargetLocks(p.gate, p.plan.order, { pr, by, at: new Date().toISOString(), stage: "apply", head: p.head }, { ...(isOpen ? { isOpen } : {}) });
+  } catch (err) {
+    return fail(`could not take the target locks of ${p.gate}, so nothing was applied: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (result.ok) {
+    if (result.taken.length > 0) console.error(formatInfo(`pull request ${pr} holds ${result.taken.join(", ")} on ${p.gate} until it merges or closes`));
+    return null;
+  }
+  const name = (n: number) => (p.forge?.kind === "gitlab" ? `merge request !${n}` : `pull request ${n}`);
+  return `${describeHeldTargetLocks(result.held, name)}, so nothing was applied.`;
+}
+
 /** #4274: a component that published nothing is recorded by the plan digest its approval bound. */
 function prAppliedDigests(p: Prepared, members: PrMember[]) {
   return appliedDigestOf({ components: p.components, env: p.env, projectRoot: resolve("."), members });

package/src/cli/handlers/run.ts

@@ -34,6 +34,7 @@ import { appliedDigestOf, extractRunDigest, maybeRecordAutoRelease, type Applied
 import { maybePersistBuildManifest } from "../../components/manifest-persistence";
 import { failedRunExitCode, type DriverComponentResult } from "../../components/driver";
 import { isComponentList, type ComponentRunPlan, type RunComponentsResult } from "../../components/cli-support";
+import { parseComponentTargets } from "../../components/capability";
 import { isApplyRecord, resolveCiRun, type ReleaseRecord, type RunOrigin } from "../../lifecycle/release-ledger";
 import { gateAdmission, gateApprover } from "../../components/promote";
 import { runOpGenerate } from "./run-generate";
@@ -1202,10 +1203,19 @@ async function runComponentSelection(ctx: CommandContext): Promise<number> {
         if (plan.added.length > 0) console.error(formatInfo(`added as dependencies: ${plan.added.join(", ")}`));
       }
     : undefined;
+  // #4300: `--target <component>:<address>`, the addresses a component's steps narrow to.
+  let targets: Record<string, string[]> | undefined;
+  try {
+    targets = ctx.args.targets && ctx.args.targets.length > 0 ? parseComponentTargets(ctx.args.targets) : undefined;
+  } catch (err) {
+    console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    return 1;
+  }
   let result: RunComponentsResult;
   try {
     result = await runtime.runComponents(projectPath, selector, {
       env: ctx.args.env,
+      ...(targets ? { targets } : {}),
       componentOutputs: seededOutputs,
       onProgress,
       ...(events ? { onRunEvent: events.emit } : {}),

package/src/cli/main.ts

@@ -347,7 +347,7 @@ CI:
                         key. --trust commits its runner entry on a branch of its
                         own and pushes it for review; the target branch is never
                         written
-  ci init --workflow trunk-curated|trunk-curated+apply-on-merge
+  ci init --workflow trunk-curated|trunk-curated+apply-on-merge|apply-before-merge
               [--forge github|gitlab|forgejo] [--security <group>]... [--yes]
                         Set the workspace up for a prescribed delivery workflow:
                         print what it would write as a diff, then write it on
@@ -1011,7 +1011,8 @@ Component release ledger + status:
                              when the wave is reached, with --canary <name>
                              for wave 1 and --wave <n> for one wave per CI
                              job; --resume <file> finishes an attempt that
-                             stopped)
+                             stopped; --target <component>:<address> plans
+                             and applies only that address)
   components pr-plan       Plan the components a pull request reaches and
                             the ones that depend on them, and write the
                             report and note (--base <ref> --pr <n>
@@ -1055,6 +1056,11 @@ Component release ledger + status:
                             from the one last applied to --env, under the
                             approved plans of the merges since, else at gate
                             op green-<sha>;
+                            --before-merge --pr <n>: apply the open pull
+                            request's head under its gate, once the
+                            declaration at base sets ci.workflow to
+                            apply-before-merge and the forge says it is
+                            approved, mergeable, undiverged and green;
                             --events-json, both commands: the run-event
                             stream on stdout; --report-url <s3 or file URL>,
                             both commands: copy the report, the change set

package/src/cli/parse-args.ts

@@ -378,6 +378,11 @@ export function parseArgs(args: string[]): ParsedArgs {
       const share = Number(raw);
       if (!Number.isInteger(share) || share < 1) throw new Error(`--share needs a share number from 1: got "${raw ?? ""}"`);
       result.share = share;
+    } else if (arg === "--target") {
+      // `chant components fan-out|run --components --target <component>:<address>` (#4300), repeatable.
+      const raw = args[++i];
+      if (!raw || raw.startsWith("-") || !raw.includes(":")) throw new Error("--target needs a component and an address: --target <component>:<address>");
+      (result.targets ??= []).push(raw);
     } else if (arg === "--canary") {
       const raw = args[++i];
       if (!raw || raw.startsWith("-")) throw new Error("--canary needs a component name: --canary <name>[,<name>...]");
@@ -436,6 +441,12 @@ export function parseArgs(args: string[]): ParsedArgs {
     } else if (arg === "--green") {
       // `chant components pr-apply --green` (#4168 step 9): apply the green commit at HEAD.
       result.green = true;
+    } else if (arg === "--before-merge") {
+      // `chant components pr-apply --before-merge` (#4301, ws-106): apply an open pull request's plan from its head.
+      result.beforeMerge = true;
+    } else if (arg === "--apply-before-merge") {
+      // `chant build --pr-loop --apply-before-merge` and `chant ci run apply --apply-before-merge` (#4301): the job that applies before merge.
+      result.applyBeforeMerge = true;
     } else if (arg === "--apply-on-merge") {
       // `chant build --pr-loop --apply-on-merge` and `chant ci serve --apply-on-merge` (#4168): opt into applying on merge.
       result.applyOnMerge = true;

package/src/cli/registry.ts

@@ -294,6 +294,12 @@ export interface ParsedArgs {
   share?: number;
   /** `chant run wave --group <name>` (#3914) — apply one job group's runs of a decided wave. */
   group?: string;
+  /**
+   * `chant components fan-out --target <component>:<address>` and `chant run
+   * --components --target ...` (#4300), repeatable: the addresses a
+   * component's steps narrow to. Raw values; `parseComponentTargets` groups them.
+   */
+  targets?: string[];
   /** `chant components fan-out --canary <component>` (#3049), repeatable — components that form wave 1. */
   canary?: string[];
   /**
@@ -353,6 +359,19 @@ export interface ParsedArgs {
   green?: boolean;
   /** `chant build --pr-loop --pr-env` (#4298) — add the env-up, env-down and env-sweep jobs of a pull request's environment. */
   prEnv?: boolean;
+  /**
+   * `chant components pr-apply --before-merge` (#4301, ws-106): apply an open
+   * pull request's plan from its head, once the declaration at base sets
+   * `ci.workflow: "apply-before-merge"` and the pull request is approved,
+   * mergeable, undiverged and green.
+   */
+  beforeMerge?: boolean;
+  /**
+   * `chant build --pr-loop --apply-before-merge` and `chant ci run apply
+   * --apply-before-merge` (#4301): the pipeline's apply job applies an open
+   * pull request before it merges, and a merge records.
+   */
+  applyBeforeMerge?: boolean;
   /** `chant build --pr-loop --pr-build` (#4088) — build and lint before pr-plan and pr-apply. */
   prBuild?: boolean;
   /** `chant ci serve --build-command <line>` (#4169) — the line that builds a commit a `ci/build/<sha>` tag asks for, in a worktree of it. */