@intentius/chant 0.124.40 → 0.124.42

package/dist/op/op-waves.js

@@ -43,6 +43,14 @@
  * `chant/lifecycle`, as terragucci's wave gate does, and that approval is
  * spent: the same digest needs a new approval to apply again.
  *
+ * ## Approval rules (#4290)
+ *
+ * With `approvals: { quorum: [...] }` (read at base), a wave takes each rule
+ * whose `targets` glob matches one of its runs' targets and waits until each
+ * is met: `count` distinct people, from `roles` when it names them (granted
+ * in `.chant/trust.json` at base), one of them not the author with
+ * `notAuthor`. See `./gate-quorum.ts`.
+ *
  * ## Wave-level commands and hooks (#3762)
  *
  * A product whose tool plans a whole wave in one call (Terragrunt's `run
@@ -66,6 +74,7 @@
  * the wave (exit 8). See `./op-waves-run.ts`.
  */
 import { gatePointProblems } from "./gate-point.js";
+import { quorumProblems } from "./gate-quorum.js";
 import { notifyConfigProblem } from "../notify.js";
 import { WAVE_GATE_NAME_PATTERN, waveGateNameFrom, waveShare } from "../wave-layout.js";
 /**
@@ -102,11 +111,13 @@ export function opWavePointAt(spec, name) {
 }
 export const OP_WAVE_HOOK_FAILURES = ["fail", "approve"];
 /**
- * Every moment, in the order a wave reaches them. `after-gate` (#3821) runs
+ * Every moment, in the order a wave reaches them. `before-observe` (#4288)
+ * runs before anything reads live state: ahead of `before-plan` in every job
+ * that plans, the deciding job's and each share's. `after-gate` (#3821) runs
  * once the gate decided, whatever it decided: approved, let through,
  * waiting, or refused by a policy denial.
  */
-export const OP_WAVE_HOOK_MOMENTS = ["before-plan", "after-plan", "after-gate", "before-apply", "after-apply"];
+export const OP_WAVE_HOOK_MOMENTS = ["before-observe", "before-plan", "after-plan", "after-gate", "before-apply", "after-apply"];
 export const OP_WAVE_APPLY_HOOKS_RUNNERS = ["chant", "apply"];
 export const OP_WAVES_DIGEST_OVER = ["all", "changing"];
 /** The default gate name pattern. */
@@ -171,13 +182,25 @@ export function assertOpWavesSpec(spec) {
     if (spec.approvals !== undefined) {
         const a = spec.approvals;
         if (a === null || typeof a !== "object" || Array.isArray(a))
-            throw new Error(`${where}: \`approvals\` must be { "spend"?: true | false }.`);
+            throw new Error(`${where}: \`approvals\` must be { "spend"?: true | false, "quorum"?: [...] }.`);
         for (const [key, value] of Object.entries(a)) {
+            if (key === "quorum") {
+                // #4290: approval rules, read at base like the policy.
+                if (!Array.isArray(value))
+                    throw new Error(`${where}: approvals.quorum must be a list of rules, each { "targets"?, "count", "roles"?, "notAuthor"? }.`);
+                const problems = quorumProblems(value, "approvals.quorum", { notAuthor: true });
+                if (problems.length > 0)
+                    throw new Error(`${where}: ${problems.join("; ")}.`);
+                continue;
+            }
             if (key !== "spend")
-                throw new Error(`${where}: approvals.${key} is not a setting; the one there is approvals.spend.`);
+                throw new Error(`${where}: approvals.${key} is not a setting; the ones there are approvals.spend and approvals.quorum.`);
             if (typeof value !== "boolean")
                 throw new Error(`${where}: approvals.spend must be true or false.`);
         }
+        if (a.quorum?.length && (spec.point !== undefined || spec.waves.some((w) => w.point !== undefined))) {
+            throw new Error(`${where}: approvals.quorum and a decision point are both set; a gate that asks a point takes its deciders and quorum from the point, so drop one of them.`);
+        }
     }
     if (spec.gateName !== undefined) {
         if (typeof spec.gateName !== "string" || !spec.gateName.includes("{k}") || /\s/.test(spec.gateName)) {
@@ -394,6 +417,15 @@ export function opWaveRunMatches(pattern, target) {
     }
     return new RegExp(`^${re}$`).test(target);
 }
+/**
+ * The runs of `runs` hook `hook` is for (#4288): those its `targets` match,
+ * or every run when it names none.
+ */
+export function opWaveHookRuns(hook, runs) {
+    if (!hook.targets)
+        return [...runs];
+    return runs.filter((run) => hook.targets.some((pattern) => opWaveRunMatches(pattern, run.target)));
+}
 /** The runs of `runs` that job group `group` holds (#3914). */
 export function opWaveGroupRuns(group, runs) {
     return runs.filter((run) => group.runs.some((pattern) => opWaveRunMatches(pattern, run.target)));
@@ -422,7 +454,7 @@ export function assertOpWaveHooks(where, hooks) {
     if (hooks === undefined)
         return;
     if (hooks === null || typeof hooks !== "object" || Array.isArray(hooks)) {
-        throw new Error(`${where}: \`hooks\` must be { "before"?: { "plan"?, "apply"? }, "after"?: { "plan"?, "apply"? } }.`);
+        throw new Error(`${where}: \`hooks\` must be { "before"?: { "observe"?, "plan"?, "apply"? }, "after"?: { "plan"?, "gate"?, "apply"? } }.`);
     }
     for (const [side, stages] of Object.entries(hooks)) {
         if (side === "apply") {
@@ -443,8 +475,10 @@ export function assertOpWaveHooks(where, hooks) {
             const at = `hooks.${side}.${stage}`;
             if (stage === "gate" && side === "before")
                 throw new Error(`${where}: ${at} is not a moment; a hook runs after the gate (hooks.after.gate), or before the plan or the apply.`);
-            if (stage !== "plan" && stage !== "apply" && stage !== "gate")
-                throw new Error(`${where}: ${at} is not a stage; a hook runs before or after plan or apply, or after the gate.`);
+            if (stage === "observe" && side === "after")
+                throw new Error(`${where}: ${at} is not a moment; a hook runs before the observe (hooks.before.observe), or after the plan, which reads what the observe saw.`);
+            if (stage !== "observe" && stage !== "plan" && stage !== "apply" && stage !== "gate")
+                throw new Error(`${where}: ${at} is not a stage; a hook runs before the observe, before or after plan or apply, or after the gate.`);
             if (!Array.isArray(list))
                 throw new Error(`${where}: ${at} must be a list of hooks.`);
             list.forEach((hook, i) => {
@@ -463,18 +497,39 @@ export function assertOpWaveHooks(where, hooks) {
                 }
                 if (hook.perRun !== undefined && typeof hook.perRun !== "boolean")
                     throw new Error(`${where}: ${which}.perRun must be true or false.`);
+                if (hook.targets !== undefined && (!Array.isArray(hook.targets) || hook.targets.length === 0 || !hook.targets.every((t) => typeof t === "string" && t !== ""))) {
+                    throw new Error(`${where}: ${which}.targets must be a non-empty list of targets or patterns, such as ["prod/*"].`);
+                }
                 if (!hook.perRun) {
                     const named = hook.command.find((part) => part.includes("{target}") || part.includes("{plan}"));
                     if (named)
                         throw new Error(`${where}: ${which} runs once for the wave, so it has no {target} or {plan} ("${named}"). Set "perRun": true, or read the runs from {runs}.`);
                 }
-                else if (side === "before" && stage === "plan" && hook.command.some((part) => part.includes("{plan}"))) {
+                else if (side === "before" && (stage === "plan" || stage === "observe") && hook.command.some((part) => part.includes("{plan}"))) {
                     throw new Error(`${where}: ${which} runs before the plan, so it has no {plan} yet.`);
                 }
             });
         }
     }
 }
+/**
+ * The moments a pull-request job runs hooks at (#4288): `pr-plan` and
+ * `pr-record` run the observe and plan moments, and `pr-apply` the apply
+ * moments too. The pull request's gate has no `after-gate` moment.
+ */
+export const PR_LOOP_HOOK_MOMENTS = ["before-observe", "before-plan", "after-plan", "before-apply", "after-apply"];
+/**
+ * Refuse `ci.hooks` a pull-request job could not run (#4288): what
+ * {@link assertOpWaveHooks} refuses, plus `after.gate` and `apply.runBy`,
+ * since chant itself runs a pull request's apply.
+ */
+export function assertPrLoopHooks(where, hooks) {
+    assertOpWaveHooks(where, hooks);
+    if (hooks?.after?.gate !== undefined)
+        throw new Error(`${where}: hooks.after.gate runs in an Op waves job only; a pull-request job runs hooks before the observe, before and after the plan, and before and after the apply.`);
+    if (hooks?.apply !== undefined)
+        throw new Error(`${where}: hooks.apply.runBy is for an Op waves spec; chant runs a pull request's apply, so it runs the apply-stage hooks itself.`);
+}
 /** The hooks of each moment for wave `name`: the spec's, then the wave's own. */
 export function opWaveHooksAt(spec, name) {
     const wave = spec.waves.find((w) => w.name === name);

package/dist/op/schedule-overdue.d.ts

@@ -0,0 +1,57 @@
+import type { OpConfig } from "./types.js";
+import type { ForgeKind, PrForge, ScheduledRuns } from "../pr-forge.js";
+/** One scheduled watch or reconcile Op the plan job checks. */
+export interface ScheduledWatch {
+    op: string;
+    cron: string;
+}
+/** An Op the plan note warns about. */
+export interface OverdueOp {
+    op: string;
+    cron: string;
+    /** The time the count starts from: the job's last run, or the pipeline file's first commit (ISO 8601). */
+    since: string;
+    /** True when no run is on record and `since` is the pipeline file's first commit. */
+    neverRan?: boolean;
+    /** The line for the job log and the plan note. */
+    message: string;
+}
+/**
+ * The discovered Ops that are scheduled watch or reconcile Ops: a
+ * `schedule`, and the `Watch` label `WatchOp` sets (./composites/watch-op.ts)
+ * or the `Reconcile` label `ReconcileOp` sets (./composites/reconcile-op.ts).
+ * Sorted by name.
+ */
+export declare function scheduledWatches(ops: Iterable<OpConfig>): ScheduledWatch[];
+/**
+ * The file `chant run --generate <forge>` writes for an Op, relative to the
+ * repository root: `<dir>/<op>.yml` on GitHub and Forgejo, `<member>-<op>.yml`
+ * in a workspace member. GitLab puts every Op in one file, so the root's
+ * `*.gitlab-ci.yml` files are read for the one whose rules select the Op.
+ * Undefined when the checkout has no such file, so an Op that some other
+ * scheduler runs is never checked.
+ */
+export declare function opPipelineFile(repoRoot: string, forge: ForgeKind, op: string, member?: string): string | undefined;
+/** When `path` was first committed (ISO 8601), if the checkout's history has it. */
+export declare function fileAdded(repoRoot: string, path: string): string | undefined;
+/**
+ * Whether one Op is overdue: its cron has fired at least twice since its
+ * last run, or since `added` when no run is on record. Undefined when it is
+ * on time, or when nothing says when it should have run.
+ */
+export declare function overdueVerdict(watch: ScheduledWatch, forge: ForgeKind, runs: ScheduledRuns, added: string | undefined, now: Date): OverdueOp | undefined;
+/**
+ * The plan job's check over every scheduled watch or reconcile Op that has a
+ * generated pipeline file. Each Op the forge will not answer for is a line
+ * in `log` and no verdict. A forge client with no `scheduledRuns` checks
+ * nothing.
+ */
+export declare function checkOverdueOps(input: {
+    watches: readonly ScheduledWatch[];
+    forge: PrForge;
+    repoRoot: string;
+    member?: string;
+    now: Date;
+    log: (line: string) => void;
+}): Promise<OverdueOp[]>;
+//# sourceMappingURL=schedule-overdue.d.ts.map

package/dist/op/schedule-overdue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule-overdue.d.ts","sourceRoot":"","sources":["../../src/op/schedule-overdue.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAErE,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AAED,uCAAuC;AACvC,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,0GAA0G;IAC1G,KAAK,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,cAAc,EAAE,CAQ1E;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAqBlH;AAED,oFAAoF;AACpF,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI5E;AAQD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,IAAI,GAAG,SAAS,GAAG,SAAS,CAkBxJ;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE;IAC3C,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,IAAI,CAAC;IACV,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBvB"}

package/dist/op/schedule-overdue.js

@@ -0,0 +1,138 @@
+/**
+ * Scheduled watch and reconcile Ops that stopped running (#4289).
+ *
+ * A schedule can stop with no error anywhere. GitHub turns a scheduled
+ * workflow off after 60 days with no activity in the repository and drops
+ * scheduled runs under load. A GitLab schedule exists only once someone
+ * creates it. A watch Op cannot report its own absence, so the pull-request
+ * plan job does. For each discovered Op with a `schedule` and the `Watch` or
+ * `Reconcile` label, whose generated pipeline file is in the checkout, it
+ * asks the forge when the Op's job last ran. When the cron has fired at
+ * least twice since then, or since the pipeline file was added for a job
+ * that never ran, the job log and the plan note say the Op is overdue.
+ *
+ * One late or dropped run is not enough: two fires are. A forge that will
+ * not answer is a line in the log and no verdict.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { cronFiresUtc } from "./cron.js";
+/**
+ * The discovered Ops that are scheduled watch or reconcile Ops: a
+ * `schedule`, and the `Watch` label `WatchOp` sets (./composites/watch-op.ts)
+ * or the `Reconcile` label `ReconcileOp` sets (./composites/reconcile-op.ts).
+ * Sorted by name.
+ */
+export function scheduledWatches(ops) {
+    const out = [];
+    for (const op of ops) {
+        if (!op.schedule?.cron)
+            continue;
+        if (op.labels?.Watch !== "true" && op.labels?.Reconcile !== "true")
+            continue;
+        out.push({ op: op.name, cron: op.schedule.cron });
+    }
+    return out.sort((a, b) => a.op.localeCompare(b.op));
+}
+/**
+ * The file `chant run --generate <forge>` writes for an Op, relative to the
+ * repository root: `<dir>/<op>.yml` on GitHub and Forgejo, `<member>-<op>.yml`
+ * in a workspace member. GitLab puts every Op in one file, so the root's
+ * `*.gitlab-ci.yml` files are read for the one whose rules select the Op.
+ * Undefined when the checkout has no such file, so an Op that some other
+ * scheduler runs is never checked.
+ */
+export function opPipelineFile(repoRoot, forge, op, member) {
+    const base = member ? `${member}-${op}` : op;
+    if (forge === "github" || forge === "forgejo") {
+        const path = `.${forge}/workflows/${base}.yml`;
+        return existsSync(join(repoRoot, path)) ? path : undefined;
+    }
+    // The gitlab lexicon's cron rule: `$CHANT_SCHEDULED_OP == "<op>"`.
+    const selector = `$CHANT_SCHEDULED_OP == "${op}"`;
+    let names;
+    try {
+        names = readdirSync(repoRoot).filter((n) => n.endsWith(".gitlab-ci.yml")).sort();
+    }
+    catch {
+        return undefined;
+    }
+    return names.find((n) => {
+        try {
+            return readFileSync(join(repoRoot, n), "utf8").includes(selector);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** When `path` was first committed (ISO 8601), if the checkout's history has it. */
+export function fileAdded(repoRoot, path) {
+    const r = spawnSync("git", ["-C", repoRoot, "log", "--format=%cI", "--diff-filter=A", "--", path], { encoding: "utf-8" });
+    if (r.status !== 0)
+        return undefined;
+    return r.stdout.trim().split("\n").filter(Boolean).pop();
+}
+const HINT = {
+    github: "GitHub turns a scheduled workflow off after 60 days with no activity in the repository. Turn the workflow on again under Actions, or run it by hand",
+    gitlab: "A GitLab project runs a scheduled Op only from a pipeline schedule. Check its schedule under CI/CD > Schedules",
+    forgejo: "Check that Actions is on for the repository and a runner is up, or run the workflow by hand",
+};
+/**
+ * Whether one Op is overdue: its cron has fired at least twice since its
+ * last run, or since `added` when no run is on record. Undefined when it is
+ * on time, or when nothing says when it should have run.
+ */
+export function overdueVerdict(watch, forge, runs, added, now) {
+    const since = runs.last ?? added;
+    if (!since)
+        return undefined;
+    if (cronFiresUtc(watch.cron, new Date(since), now, 2).length < 2)
+        return undefined;
+    const day = since.slice(0, 10);
+    const what = runs.last ? `its last run was on ${day}` : `no run is on record since its pipeline was added on ${day}`;
+    const why = runs.disabled
+        ? `GitHub has turned the workflow off (${runs.disabled}). Turn it on again under Actions`
+        : forge === "gitlab" && runs.noSchedule
+            ? `No active pipeline schedule sets CHANT_SCHEDULED_OP to ${watch.op}. Add one with the cron \`${watch.cron}\` under CI/CD > Schedules`
+            : HINT[forge];
+    return {
+        op: watch.op,
+        cron: watch.cron,
+        since,
+        ...(runs.last ? {} : { neverRan: true }),
+        message: `Op \`${watch.op}\` is overdue: its schedule \`${watch.cron}\` has fired at least twice and ${what}. ${why}.`,
+    };
+}
+/**
+ * The plan job's check over every scheduled watch or reconcile Op that has a
+ * generated pipeline file. Each Op the forge will not answer for is a line
+ * in `log` and no verdict. A forge client with no `scheduledRuns` checks
+ * nothing.
+ */
+export async function checkOverdueOps(input) {
+    const { forge } = input;
+    if (!forge.scheduledRuns)
+        return [];
+    const out = [];
+    for (const watch of input.watches) {
+        const file = opPipelineFile(input.repoRoot, forge.kind, watch.op, input.member);
+        if (!file)
+            continue;
+        let runs;
+        try {
+            runs = await forge.scheduledRuns({ op: watch.op, workflow: file.split("/").pop() });
+        }
+        catch (err) {
+            input.log(`schedule check: ${forge.kind} did not say when Op ${watch.op} last ran, so it is not checked: ${(err instanceof Error ? err.message : String(err)).split("\n")[0]}`);
+            continue;
+        }
+        const found = overdueVerdict(watch, forge.kind, runs, runs.last ? undefined : fileAdded(input.repoRoot, file), input.now);
+        if (found) {
+            input.log(found.message);
+            out.push(found);
+        }
+    }
+    return out;
+}

package/dist/op/stage-hooks.d.ts

@@ -0,0 +1,132 @@
+/**
+ * The stage-hook runner (#4288): one moment's hooks, with the `targets`,
+ * `perRun`, `onFailure` and argv filling a wave job uses. Its own module so
+ * a product that runs hooks around its own stages (terragucci) bundles it
+ * without the wave loop, the gate or the ledger. `op-waves-run.ts` runs
+ * the same hooks inside a wave job.
+ */
+import { type OpWaveHook, type OpWaveHookMoment } from "./op-waves.js";
+/** What one moment's hooks came to, before any hold on another gate is settled. */
+export interface HookListOutcome {
+    /** Set when a hook with `onFailure: fail` failed; the hooks after it did not run. */
+    failed?: string;
+    /** The `onFailure: approve` hooks that failed. */
+    holds: string[];
+    outcomes: OpWaveHookOutcome[];
+    /** The hook calls that held the wave on another gate. */
+    otherGates: OtherGateHold[];
+}
+/** Pending-fact keys chant writes itself, which a plans file's `pending` may not set (#3821). */
+export declare const OP_WAVE_PENDING_RESERVED: readonly ["version", "kind", "op", "gate", "timestamp", "expiresAt", "planDigest", "runId", "url", "resume", "environment", "origin", "neverOverMcp", "approval", "approvalMode", "answer", "wave", "heldBy"];
+/** What a hook asks for when it holds a wave on another gate (#3821): it writes this to `CHANT_HOLD` and exits non-zero. */
+export interface OpWaveHoldRequest {
+    /** The op the gate is recorded under. Default: the spec's name. */
+    op?: string;
+    gate: string;
+    /** The digest an approval binds. */
+    digest: string;
+    description?: string;
+    /** Fields for the pending fact, as a plans file's `pending`. */
+    pending?: Record<string, unknown>;
+}
+/** One hook's run (#3762). */
+export interface OpWaveHookOutcome {
+    moment: OpWaveHookMoment;
+    name: string;
+    /** The run, for a `perRun` hook. */
+    target?: string;
+    exit: number;
+    outcome: "passed" | "failed" | "held" | "skipped";
+    /** Why the moment was skipped, for `skipped` (#3811). */
+    reason?: string;
+}
+/** One run as a hook sees it (#3804). */
+export interface OpWaveHookRun {
+    target: string;
+    op: string;
+    /** The run's plan file, once planned. */
+    plan?: string;
+}
+/** Runs one argv; returns its exit code. `env` is added to the job's environment. Injected so tests run no processes. */
+export type OpWaveExec = (argv: string[], cwd: string, env?: Record<string, string>) => number;
+export declare const spawnExec: OpWaveExec;
+/** Fill one argv template. A placeholder whose value is not given is left as it is. */
+export declare function opWaveArgv(template: readonly string[], values: {
+    op: string;
+    wave: string;
+    target?: string;
+    plan?: string;
+    runs?: string;
+    plans?: string;
+}): string[];
+/** A plans file's `pending` (#3821): an object whose keys chant does not write itself, `description` aside. Undefined when absent or empty. */
+export declare function pendingFields(value: unknown, where: string): Record<string, unknown> | undefined;
+/** A hook call that held the wave on another gate (#3821), kept so it can run again once that gate is approved. */
+export interface OtherGateHold {
+    label: string;
+    name: string;
+    moment: OpWaveHookMoment;
+    target?: string;
+    argv: string[];
+    env: Record<string, string>;
+    request: OpWaveHoldRequest;
+}
+/** Read the hold file a hook wrote (#3821), or undefined when it wrote none or one that names no gate and digest. */
+export declare function readHoldRequest(path: string, log: (line: string) => void, label: string): OpWaveHoldRequest | undefined;
+/** Where hooks run: the wave they belong to and the job's tools. */
+export interface HookPlace {
+    /** The spec's name and `op`. */
+    name: string;
+    op: string;
+    waveName: string;
+    k: number;
+    cwd: string;
+    exec: OpWaveExec;
+    log: (line: string) => void;
+    /** Where a hook writes a hold on another gate (`CHANT_HOLD`). Default: under the wave's directory. */
+    holdPath?: string;
+}
+/**
+ * Run one moment's hooks, in order: each once for the wave, or once per run
+ * for a `perRun` hook. A hook that fails stops the rest, unless its
+ * `onFailure` is `approve`: then it holds the wave and the hooks after it run.
+ */
+export declare function runHookList(at: HookPlace, moment: OpWaveHookMoment, hooks: readonly OpWaveHook[] | undefined, runs: readonly OpWaveHookRun[], runsPath: string, extraEnv?: Record<string, string>): HookListOutcome;
+/** The options of {@link runStageHooks} (#4288). */
+export interface RunStageHooksOptions {
+    /** What the hooks belong to: `CHANT_OP_WAVES`, and the `{op}` of a hook that runs once. */
+    name: string;
+    op: string;
+    /** `{wave}` and `CHANT_WAVE`. */
+    wave: string;
+    /** `CHANT_WAVE_NUMBER`. Default 0. */
+    k?: number;
+    /** The runs a `perRun` hook runs for and `targets` match against. */
+    runs: readonly OpWaveHookRun[];
+    /** `{runs}` and `CHANT_RUNS`, relative to `cwd`; the caller writes it. */
+    runsFile: string;
+    /** `CHANT_HOLD`, relative to `cwd`. */
+    holdFile: string;
+    /** Added to every hook's environment. */
+    env?: Record<string, string>;
+    cwd?: string;
+    exec?: OpWaveExec;
+    log?: (line: string) => void;
+}
+/** What {@link runStageHooks} gave. */
+export interface StageHooksRun {
+    outcomes: OpWaveHookOutcome[];
+    /** Set when a hook with `onFailure: fail` failed; the hooks after it did not run. */
+    failed?: string;
+    /** The `onFailure: approve` hooks that failed. A hold on another gate counts as one here. */
+    holds: string[];
+}
+/**
+ * Run one moment's hooks outside an Op waves job (#4288): the pull-request
+ * jobs, or a product's own stage, with the same `targets`, `perRun`,
+ * `onFailure` and argv filling a wave job uses. A hook that holds on another
+ * gate (`CHANT_HOLD`) is counted as a plain hold; settling that gate is the
+ * caller's.
+ */
+export declare function runStageHooks(moment: OpWaveHookMoment, hooks: readonly OpWaveHook[] | undefined, options: RunStageHooksOptions): StageHooksRun;
+//# sourceMappingURL=stage-hooks.d.ts.map

package/dist/op/stage-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-hooks.d.ts","sourceRoot":"","sources":["../../src/op/stage-hooks.ts"],"names":[],"mappings":"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"}

package/dist/op/stage-hooks.js

@@ -0,0 +1,142 @@
+/**
+ * The stage-hook runner (#4288): one moment's hooks, with the `targets`,
+ * `perRun`, `onFailure` and argv filling a wave job uses. Its own module so
+ * a product that runs hooks around its own stages (terragucci) bundles it
+ * without the wave loop, the gate or the ledger. `op-waves-run.ts` runs
+ * the same hooks inside a wave job.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { opWaveHookRuns } from "./op-waves.js";
+/** Pending-fact keys chant writes itself, which a plans file's `pending` may not set (#3821). */
+export const OP_WAVE_PENDING_RESERVED = [
+    "version", "kind", "op", "gate", "timestamp", "expiresAt", "planDigest", "runId", "url", "resume",
+    "environment", "origin", "neverOverMcp", "approval", "approvalMode", "answer", "wave", "heldBy",
+];
+export const spawnExec = (argv, cwd, env) => {
+    const result = spawnSync(argv[0], argv.slice(1), { cwd, stdio: "inherit", ...(env ? { env: { ...process.env, ...env } } : {}) });
+    if (result.error)
+        throw result.error;
+    return result.status ?? 1;
+};
+/** Fill one argv template. A placeholder whose value is not given is left as it is. */
+export function opWaveArgv(template, values) {
+    const pairs = [
+        ["{op}", values.op],
+        ["{target}", values.target],
+        ["{wave}", values.wave],
+        ["{plans}", values.plans],
+        ["{plan}", values.plan],
+        ["{runs}", values.runs],
+    ];
+    return template.map((part) => pairs.reduce((out, [key, value]) => (value === undefined ? out : out.replaceAll(key, value)), part));
+}
+/** A plans file's `pending` (#3821): an object whose keys chant does not write itself, `description` aside. Undefined when absent or empty. */
+export function pendingFields(value, where) {
+    if (value === undefined)
+        return undefined;
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${where}: \`pending\` must be an object of fields for the pending fact`);
+    const reserved = Object.keys(value).filter((key) => OP_WAVE_PENDING_RESERVED.includes(key));
+    if (reserved.length > 0)
+        throw new Error(`${where}: \`pending\` sets ${reserved.join(", ")}, which chant writes itself`);
+    if ("description" in value && typeof value.description !== "string")
+        throw new Error(`${where}: pending.description must be a string`);
+    return Object.keys(value).length > 0 ? value : undefined;
+}
+/** Read the hold file a hook wrote (#3821), or undefined when it wrote none or one that names no gate and digest. */
+export function readHoldRequest(path, log, label) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const r = JSON.parse(readFileSync(path, "utf-8"));
+        if (typeof r.gate !== "string" || r.gate === "" || typeof r.digest !== "string" || r.digest === "")
+            throw new Error("it names no gate and digest");
+        if (r.op !== undefined && (typeof r.op !== "string" || r.op === ""))
+            throw new Error("its op is not a name");
+        return { gate: r.gate, digest: r.digest, ...(r.op ? { op: r.op } : {}), ...(typeof r.description === "string" ? { description: r.description } : {}), ...(r.pending ? { pending: pendingFields(r.pending, `the hold ${label} wrote`) ?? {} } : {}) };
+    }
+    catch (err) {
+        log(`${label} wrote a hold file that cannot be read (${err instanceof Error ? err.message : String(err)}), so it holds the wave on its set digest`);
+        return undefined;
+    }
+}
+/**
+ * Run one moment's hooks, in order: each once for the wave, or once per run
+ * for a `perRun` hook. A hook that fails stops the rest, unless its
+ * `onFailure` is `approve`: then it holds the wave and the hooks after it run.
+ */
+export function runHookList(at, moment, hooks, runs, runsPath, extraEnv = {}) {
+    const out = { holds: [], outcomes: [], otherGates: [] };
+    if (!hooks || hooks.length === 0)
+        return out;
+    const { name: specName, op, waveName, k, cwd, exec, log } = at;
+    // #3821: a hook that holds the wave on another gate names it in this file.
+    const holdPath = at.holdPath ?? `.chant/op-waves/${specName}/wave-${k}/hold.json`;
+    const env = { CHANT_OP_WAVES: specName, CHANT_WAVE: waveName, CHANT_WAVE_NUMBER: String(k), CHANT_HOOK: moment, CHANT_RUNS: runsPath, CHANT_HOLD: holdPath, ...extraEnv };
+    for (const hook of hooks) {
+        const name = hook.name ?? (hook.command.join(" ").length > 60 ? `${hook.command.join(" ").slice(0, 57)}...` : hook.command.join(" "));
+        // #4288: a hook with `targets` is for the runs they match. Once for the wave, it runs when one matches or no run is known yet.
+        const mine = opWaveHookRuns(hook, runs);
+        if (hook.targets && (hook.perRun ? mine.length === 0 : mine.length === 0 && runs.length > 0)) {
+            log(`${moment} hook ${name}: no run matches its targets (${hook.targets.join(", ")}), so it did not run`);
+            continue;
+        }
+        const calls = hook.perRun
+            ? mine.map((run) => ({
+                target: run.target,
+                argv: opWaveArgv(hook.command, { op: run.op, wave: waveName, target: run.target, runs: runsPath, ...(run.plan ? { plan: run.plan } : {}) }),
+                env: { ...env, CHANT_TARGET: run.target, ...(run.plan ? { CHANT_PLAN: run.plan } : {}) },
+            }))
+            : [{ target: undefined, argv: opWaveArgv(hook.command, { op, wave: waveName, runs: runsPath }), env: env }];
+        for (const call of calls) {
+            const label = `${moment} hook ${name}${call.target ? ` (${call.target})` : ""}`;
+            let code;
+            rmSync(join(cwd, holdPath), { force: true });
+            try {
+                code = exec(call.argv, cwd, call.env);
+            }
+            catch (err) {
+                log(`${label} did not run: ${err instanceof Error ? err.message : String(err)}`);
+                code = 127;
+            }
+            const base = { moment, name, ...(call.target ? { target: call.target } : {}), exit: code };
+            if (code === 0) {
+                out.outcomes.push({ ...base, outcome: "passed" });
+                continue;
+            }
+            if (hook.onFailure === "approve") {
+                out.outcomes.push({ ...base, outcome: "held" });
+                const request = readHoldRequest(join(cwd, holdPath), log, label);
+                if (request) {
+                    out.otherGates.push({ label, name, moment, ...(call.target ? { target: call.target } : {}), argv: call.argv, env: call.env, request });
+                    log(`${label} exited ${code} and holds wave ${k} (${waveName}) on gate ${request.op ?? specName} / ${request.gate}, digest ${request.digest}`);
+                    continue;
+                }
+                out.holds.push(label);
+                log(`${label} exited ${code}, so wave ${k} (${waveName}) waits for an approval of its set digest`);
+                continue;
+            }
+            out.outcomes.push({ ...base, outcome: "failed" });
+            out.failed = `${label} exited ${code}`;
+            log(out.failed);
+            return out;
+        }
+    }
+    return out;
+}
+/**
+ * Run one moment's hooks outside an Op waves job (#4288): the pull-request
+ * jobs, or a product's own stage, with the same `targets`, `perRun`,
+ * `onFailure` and argv filling a wave job uses. A hook that holds on another
+ * gate (`CHANT_HOLD`) is counted as a plain hold; settling that gate is the
+ * caller's.
+ */
+export function runStageHooks(moment, hooks, options) {
+    const cwd = options.cwd ?? process.cwd();
+    const log = options.log ?? ((line) => console.error(line));
+    const place = { name: options.name, op: options.op, waveName: options.wave, k: options.k ?? 0, cwd, exec: options.exec ?? spawnExec, log, holdPath: options.holdFile };
+    const out = runHookList(place, moment, hooks, options.runs, options.runsFile, options.env);
+    return { outcomes: out.outcomes, ...(out.failed ? { failed: out.failed } : {}), holds: [...out.holds, ...out.otherGates.map((g) => `${g.label} (on ${g.request.op ?? options.name} / ${g.request.gate})`)] };
+}

package/dist/override-gate.d.ts

@@ -32,12 +32,12 @@
  * nothing; `override-gate-bundle.test.ts` holds its import graph to the
  * same bundle. chant's own writers are in `./lifecycle/override-ledger.ts`.
  */
-import { type GateSigners } from "./workspace/trust/gate-seal.js";
+import { type GateSigners } from "./lifecycle/gate-seal.js";
 import type { GateResolutionRecord, PendingGateRecord } from "./lifecycle/gate-ledger.js";
 import type { GateApprovalSource } from "./op/op-waves.js";
 import type { GateAuditApply } from "./lifecycle/gate-audit.js";
 export type { GateResolutionRecord, PendingGateRecord } from "./lifecycle/gate-ledger.js";
-export type { GateSigners } from "./workspace/trust/gate-seal.js";
+export type { GateSigners } from "./lifecycle/gate-seal.js";
 /** The op every override and denial is recorded under. `./lifecycle/gate-audit.ts` reads this op as overrides by default. */
 export declare const OVERRIDE_OP = "policy-override";
 /** The ledger file on `chant/lifecycle` that holds denials and overrides. */