@intentius/chant 0.124.40 → 0.124.41

package/dist/cli/handlers/gate-resume.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gate-resume.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/gate-resume.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gate-resume.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/gate-resume.ts"],"names":[],"mappings":"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"}

package/dist/cli/handlers/gate-resume.js

@@ -21,9 +21,20 @@ import { GATES_DIR, readGateLedger, } from "../../lifecycle/gate-ledger.js";
 import { appliedGatePath, parseAppliedGateFile } from "../../lifecycle/gate-applied.js";
 import { listFilesInDir, pushLifecycleStatus, readBlobFromPath, requireLifecycleLedger } from "../../lifecycle/git.js";
 import { parseGateSubject } from "../../op/gate-point.js";
+import { quorumRules, ruleNeedsProof, trustQuorumJudge } from "../../op/gate-quorum.js";
 import { resolutionAnswering, resumeGateRun, resumeTokenFromEnv, } from "../../op/gate-resume.js";
 import { planGateResumes } from "../../op/gate-resume-plan.js";
 import { formatError, formatInfo, formatSuccess, formatWarning } from "../format.js";
+/** The judge a fact's approval rules are met by (#4290): the trust policy at base, read only when a rule names roles or notAuthor. */
+async function judgeFor(pending, opts) {
+    if (opts.judge)
+        return opts.judge;
+    if (!pending.some((p) => quorumRules(p.approval?.quorum).some(ruleNeedsProof)))
+        return undefined;
+    const { scopeSource } = await import("../../workspace/write-scope.js");
+    const { policy } = scopeSource(process.cwd());
+    return trustQuorumJudge({ signers: policy, roles: policy.roles });
+}
 /** Every question the workspace at `cwd` lists, by id, the lifecycle ledger's included. Empty when the workspace can't be read. */
 export async function workspaceQuestions(cwd) {
     const { workspacePoints } = await import("../../workspace/points-cli.js");
@@ -34,6 +45,7 @@ export async function workspaceQuestions(cwd) {
 }
 /** Resume the job behind one standing pending fact, when an approval answers it and is not spent. */
 export async function resumeStanding(standing, resolutions, opts = {}, pending = [standing]) {
+    const judge = await judgeFor([standing], opts);
     const [candidate] = planGateResumes({
         op: standing.op,
         pending: [standing],
@@ -41,7 +53,7 @@ export async function resumeStanding(standing, resolutions, opts = {}, pending =
         applied: opts.applied ?? [],
         now: standing.timestamp,
         ...(opts.questions ? { questions: opts.questions } : {}),
-        answering: (r, s) => resolutionAnswering(r, s, pending),
+        answering: (r, s) => resolutionAnswering(r, s, pending, judge),
     });
     return resumeCandidate(candidate, opts);
 }
@@ -127,6 +139,7 @@ export async function resumeOpGates(op, gate, opts = {}) {
     const now = opts.now ?? new Date().toISOString();
     // Read the workspace's questions once, and only when a fact waits on one (#3835).
     const questions = opts.questions ?? (ledger.pending.some((p) => p.answer) ? await workspaceQuestions(process.cwd()) : undefined);
+    const judge = await judgeFor(ledger.pending, opts);
     const candidates = planGateResumes({
         op,
         pending: ledger.pending,
@@ -136,7 +149,7 @@ export async function resumeOpGates(op, gate, opts = {}) {
         now,
         ...(gate !== undefined ? { gate } : {}),
         ...(questions ? { questions } : {}),
-        answering: resolutionAnswering,
+        answering: (r, s, p) => resolutionAnswering(r, s, p, judge),
     });
     const reports = [];
     for (const c of candidates)

package/dist/cli/handlers/lock.d.ts

@@ -0,0 +1,8 @@
+import type { CommandContext } from "../registry.js";
+/** The status `chant lock --head <sha> --forge <kind>` posts. */
+export declare const LOCK_STATUS_CONTEXT = "chant/lock";
+/** chant lock */
+export declare function runLock(ctx: CommandContext): Promise<number>;
+/** chant unlock */
+export declare function runUnlock(ctx: CommandContext): Promise<number>;
+//# sourceMappingURL=lock.d.ts.map

package/dist/cli/handlers/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/lock.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAkBlD,iEAAiE;AACjE,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAwDhD,iBAAiB;AACjB,wBAAsB,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA6ElE;AAED,mBAAmB;AACnB,wBAAsB,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBpE"}

package/dist/cli/handlers/lock.js

@@ -0,0 +1,197 @@
+/**
+ * `chant lock` and `chant unlock` (#4293): take, list and release the target
+ * locks a pull request holds (../../lifecycle/target-lock.ts).
+ *
+ * ```
+ * chant lock <target>... --pr <n> [--stage plan|apply|lock] [--head <sha>] [--by <who>] [--gate <name>] [--forge <kind>] [--json]
+ * chant lock --from-report <pr-plan.json> --pr <n> [--stage plan] [--forge <kind>] [--json]
+ * chant lock --list [--gate <name>] [--json]
+ * chant unlock --pr <n> [<target>...] [--gate <name>] [--json]
+ * ```
+ *
+ * The targets are names: the components `chant components pr-plan` selects,
+ * which are what `pr-apply` checks under `ci.locks`, or any other name a
+ * pipeline locks by. `--from-report` reads them from a pull-request report
+ * (`selection.waves`), so a lock job that runs the target branch's code can
+ * lock what the plan job, which ran the pull request's code, selected.
+ *
+ * `--forge` reads which holders are still open, so a lock whose pull
+ * request merged or closed is taken over, and, with `--head`, posts the
+ * `chant/lock` status on that commit. Without it every lock counts as held.
+ *
+ * Exit 0 when the locks are taken or released, 3 when another open pull
+ * request holds a target (nothing is locked), 1 on an error.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { formatError, formatInfo, formatSuccess, formatWarning } from "../format.js";
+import { FORGE_KINDS, forgeFromEnv } from "../../pr-forge.js";
+import { PR_APPLY_GATE } from "../../pr-loop.js";
+import { describeHeldTargetLocks, readTargetLocks, releaseTargetLocks, takeTargetLocks, targetLockGateProblem, targetLockPathAt, TARGET_LOCK_STAGES, } from "../../lifecycle/target-lock.js";
+/** The exit for a target another open pull request holds: 3, as a run stopped at a gate exits (`GATED_EXIT_CODE` in ./run.ts). */
+const HELD_EXIT_CODE = 3;
+/** The status `chant lock --head <sha> --forge <kind>` posts. */
+export const LOCK_STATUS_CONTEXT = "chant/lock";
+const fail = (message, hint) => {
+    console.error(formatError({ message, ...(hint ? { hint } : {}) }));
+    return 1;
+};
+/** The targets named after the command word. */
+function targetsOf(ctx) {
+    return (ctx.args.positionals ?? []).filter((t) => t !== "");
+}
+function gateOf(ctx) {
+    const gate = ctx.args.gate ?? PR_APPLY_GATE;
+    const problem = targetLockGateProblem(gate);
+    return problem ? { error: problem } : gate;
+}
+function forgeOf(ctx) {
+    const kind = ctx.args.forge;
+    if (kind === undefined)
+        return undefined;
+    if (!FORGE_KINDS.includes(kind))
+        return { error: `--forge ${kind} is not one of ${FORGE_KINDS.join(", ")}` };
+    try {
+        return forgeFromEnv(kind);
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+}
+const prName = (forge) => (n) => (forge?.kind === "gitlab" ? `merge request !${n}` : `pull request ${n}`);
+/** The components a `pr-plan.json` selected, and the head it planned, checked against `--pr`. */
+function fromReport(file, pr) {
+    let doc;
+    try {
+        doc = JSON.parse(readFileSync(resolve(file), "utf8"));
+    }
+    catch (err) {
+        return { error: `--from-report: could not read "${file}": ${err instanceof Error ? err.message : String(err)}` };
+    }
+    if (doc.pr !== pr)
+        return { error: `--from-report: "${file}" is the report of ${doc.pr === null || doc.pr === undefined ? "no pull request" : `pull request ${String(doc.pr)}`}, not ${pr}` };
+    const waves = doc.selection?.waves;
+    if (!Array.isArray(waves) || !waves.every((w) => Array.isArray(w) && w.every((n) => typeof n === "string"))) {
+        return { error: `--from-report: "${file}" has no selection.waves; pass a pr-plan.json that chant components pr-plan wrote` };
+    }
+    return { targets: waves.flat(), ...(typeof doc.head === "string" ? { head: doc.head } : {}) };
+}
+async function postStatus(forge, head, state, description) {
+    if (!forge || !head)
+        return;
+    try {
+        await forge.setStatus(head, { context: LOCK_STATUS_CONTEXT, state, description: description.length > 140 ? `${description.slice(0, 137)}...` : description, ...(forge.runUrl ? { url: forge.runUrl } : {}) });
+    }
+    catch (err) {
+        console.error(formatWarning({ message: `could not post ${LOCK_STATUS_CONTEXT} on ${head}: ${err instanceof Error ? err.message : String(err)}` }));
+    }
+}
+/** chant lock */
+export async function runLock(ctx) {
+    const { args } = ctx;
+    const gate = gateOf(ctx);
+    if (typeof gate !== "string")
+        return fail(gate.error);
+    if (args.list) {
+        if (targetsOf(ctx).length > 0 || args.pr !== undefined)
+            return fail("--list prints every lock; drop the targets and --pr");
+        let file;
+        try {
+            file = await readTargetLocks(gate);
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : String(err));
+        }
+        const rows = Object.entries(file.locks).sort(([a], [b]) => a.localeCompare(b));
+        if (args.json) {
+            console.log(JSON.stringify({ gate, path: await targetLockPathAt(gate), locks: Object.fromEntries(rows) }, null, 2));
+            return 0;
+        }
+        if (rows.length === 0)
+            console.error(formatInfo(`no target locks on ${gate}`));
+        for (const [target, l] of rows)
+            console.log(`${target}\tpull request ${l.pr}\t${l.stage}\t${l.by}\t${l.at}`);
+        return 0;
+    }
+    if (args.pr === undefined)
+        return fail("chant lock needs the pull or merge request that holds the locks: --pr <n>", "chant lock --list prints the locks held now.");
+    const stage = (args.lockStage ?? "lock");
+    if (!TARGET_LOCK_STAGES.includes(stage))
+        return fail(`--stage ${args.lockStage} is not one of ${TARGET_LOCK_STAGES.join(", ")}`);
+    let targets = targetsOf(ctx);
+    let head = args.head;
+    if (args.fromReport) {
+        if (targets.length > 0)
+            return fail("--from-report reads the targets from the report; drop the names");
+        const read = fromReport(args.fromReport, args.pr);
+        if ("error" in read)
+            return fail(read.error);
+        targets = read.targets;
+        head ?? (head = read.head);
+    }
+    else if (targets.length === 0 && stage !== "plan") {
+        return fail("chant lock needs the targets to lock: chant lock <target>... --pr <n>", "Or --from-report <pr-plan.json> to lock what a plan selected.");
+    }
+    const forge = forgeOf(ctx);
+    if (forge && "error" in forge)
+        return fail(forge.error);
+    const isOpen = forge?.pullRequestOpen?.bind(forge);
+    const by = args.by ?? process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER ?? "unknown";
+    const name = prName(forge);
+    let result;
+    try {
+        result = await takeTargetLocks(gate, targets, { pr: args.pr, by, at: new Date().toISOString(), stage, ...(head ? { head } : {}) }, { ...(isOpen ? { isOpen } : {}), releaseStalePlan: stage === "plan" });
+    }
+    catch (err) {
+        return fail(`could not take the locks of ${gate}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!result.ok) {
+        const holders = [...new Set(result.held.map((h) => h.pr))].sort((a, b) => a - b);
+        const text = `${describeHeldTargetLocks(result.held, name)}, so ${name(args.pr)} is not locked`;
+        await postStatus(forge, head, "failure", `locked by ${holders.map(name).join(", ")}: ${result.held.map((h) => h.target).join(", ")}`);
+        if (args.json)
+            console.log(JSON.stringify({ gate, pr: args.pr, ok: false, held: result.held }, null, 2));
+        console.error(formatError({ message: text, hint: `Lock again once ${holders.length === 1 ? "it merges or closes" : "they merge or close"}, or after chant unlock --pr ${holders[0]}.${isOpen ? "" : " Without --forge every lock counts as held."}` }));
+        return HELD_EXIT_CODE;
+    }
+    const holds = result.taken.length > 0 ? `holds ${result.taken.join(", ")}` : "reaches no target";
+    await postStatus(forge, head, "success", holds);
+    if (args.json) {
+        console.log(JSON.stringify({ gate, pr: args.pr, ok: true, stage, taken: result.taken, released: result.released, expired: result.expired, pushed: result.pushed }, null, 2));
+        return 0;
+    }
+    console.error(formatSuccess(`${name(args.pr)} ${holds} on ${gate}`));
+    if (result.released.length > 0)
+        console.error(formatInfo(`released ${result.released.join(", ")}, which it no longer reaches`));
+    if (result.expired.length > 0)
+        console.error(formatInfo(`took over ${result.expired.join(", ")} from pull requests that merged or closed`));
+    if (!result.pushed && (result.taken.length > 0 || result.released.length > 0))
+        console.error(formatInfo("chant/lifecycle was not pushed: this repository has no remote, or recording is off"));
+    return 0;
+}
+/** chant unlock */
+export async function runUnlock(ctx) {
+    const { args } = ctx;
+    const gate = gateOf(ctx);
+    if (typeof gate !== "string")
+        return fail(gate.error);
+    if (args.pr === undefined)
+        return fail("chant unlock needs the pull or merge request whose locks it releases: --pr <n>");
+    const targets = targetsOf(ctx);
+    let result;
+    try {
+        result = await releaseTargetLocks(gate, args.pr, targets.length > 0 ? { targets } : {});
+    }
+    catch (err) {
+        return fail(`could not release the locks of ${gate}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (args.json) {
+        console.log(JSON.stringify({ gate, pr: args.pr, released: result.released, pushed: result.pushed }, null, 2));
+        return 0;
+    }
+    if (result.released.length === 0)
+        console.error(formatInfo(`pull request ${args.pr} holds no lock${targets.length > 0 ? ` on ${targets.join(", ")}` : ""} on ${gate}`));
+    else
+        console.error(formatSuccess(`released the locks pull request ${args.pr} held on ${result.released.join(", ")}`));
+    return 0;
+}

package/dist/cli/handlers/pr-env.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `chant components pr-env up|down|sweep` (#4298): an environment per open
+ * pull request, `pr-<n>`, derived from `ci.prEnvironment.template`
+ * (../../components/pr-environment.ts says what each does and why).
+ *
+ * ```
+ * chant components pr-env up    --base <ref> --pr <n> [--forge <kind>] [--member <name>] [--output <dir>] [--no-push]
+ * chant approve pr-<n> pr-env --plan <digest> --approver <you> --sign
+ * chant components pr-env down  --pr <n> [--reason closed|expired] [--forge <kind>] [--member <name>]
+ * chant components pr-env post  --pr <n> --head <sha> [--result <r>] --forge <kind>
+ * chant components pr-env sweep [--forge <kind>]
+ * ```
+ *
+ * In the generated jobs (#4295) `up` runs the change's code with no forge
+ * token, so it passes `--no-push` and hands its report and record on, and
+ * `post` runs in a fresh job at the target branch's commit, appends the
+ * record and posts the note.
+ *
+ * `up` prepares the change as `pr-plan` does, with `--env pr-<n>` and the
+ * build parameter `ownership.env` reads set to `pr-<n>`, so every resource
+ * the apply creates carries that environment's marker. It applies only when
+ * the plan is empty or an approval of its digest stands under gate `pr-env`,
+ * since a non-empty plan never applies with no person approving (ws-080).
+ *
+ * `down` reads the environment's record on chant/lifecycle, checks it names
+ * this pull request's environment, and tears down what `planTeardown` finds
+ * under the record's marker, after dropping any entry whose marker is not
+ * exactly that one. No gate holds it: closing the pull request is the
+ * decision, as is the TTL the base set for `sweep`.
+ */
+import type { CommandContext } from "../registry.js";
+/** chant components pr-env <up|down|sweep> */
+export declare function runComponentsPrEnv(ctx: CommandContext): Promise<number>;
+//# sourceMappingURL=pr-env.d.ts.map

package/dist/cli/handlers/pr-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pr-env.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/pr-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AA0CH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AASlD,8CAA8C;AAC9C,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAO7E"}