toolroll 0.9.74 → 0.9.76

package/dist/release-authority.js

@@ -133,3 +133,67 @@ export function releaseSealProblem(store, terms) {
     }
     return null;
 }
+// ------------------------------------------------------------------ automatic release approval (auto-approve-green.md)
+/** "Release approval: Ask me / Approve automatically when checks pass": a project setting, newest choice wins (a ledger
+ * row each); `ask` by default. Turning it on is a person's credential act (a password typed now); off is one click. */
+export const RELEASE_APPROVAL_ACTION = "release approval changed";
+/** The plane's record of what proved an automatic seal (`auto-check` or `auto-green`): one ledger row per seal, its
+ * id named by the seal's `mode_digest` as `auto:<id>`. Only release-auto.ts writes it. */
+export const AUTO_EVIDENCE_ACTION = "release auto-approved";
+/** An automatic seal taken back for good (the setting lowered, a refusal): its outcome names the seal's `auto:<id>`, and
+ * that evidence never stands again. */
+export const AUTO_WITHDRAWN_ACTION = "release auto-approval withdrawn";
+/** Read live at every use. Fail closed: a missing, unreadable or unknown row is `ask`. */
+export function releaseApprovalSetting(store, repo) {
+    let row;
+    try {
+        row = store.handle.prepare("SELECT actor, at, outcome FROM action_ledger WHERE repo = ? AND task_id IS NULL AND action = ? ORDER BY id DESC LIMIT 1").get(repo, RELEASE_APPROVAL_ACTION);
+    }
+    catch {
+        return { auto: false, setBy: null, at: null };
+    }
+    if (row === undefined || (row["outcome"] !== "auto" && row["outcome"] !== "ask"))
+        return { auto: false, setBy: null, at: null };
+    return { auto: row["outcome"] === "auto", setBy: String(row["actor"]), at: String(row["at"]) };
+}
+export const releaseAutoApproves = (store, repo) => releaseApprovalSetting(store, repo).auto;
+/** SQL: the newest setting row for `repo` (an SQL expression) says `auto`. */
+export const releaseAutoSql = (repo) => `COALESCE((SELECT ra_set.outcome = 'auto' FROM action_ledger ra_set WHERE ra_set.repo = ${repo} AND ra_set.task_id IS NULL
+      AND ra_set.action = '${RELEASE_APPROVAL_ACTION}' ORDER BY ra_set.id DESC LIMIT 1), 0)`;
+/**
+ * SQL over a `task_scope` alias: its automatic seal (`auto-check` or `auto-green`) stands on its own evidence row — this
+ * task, this kind, `mode_digest = 'auto:<row id>'`, the row's digest and candidate exactly the sealed ones — on a release
+ * task (a candidate and release terms signed in), while the project's setting is on. The approver's standing is read
+ * beside it (approval-authority.ts).
+ */
+export const autoSealSql = (scope, repo) => `(${scope}.candidate IS NOT NULL AND ${scope}.release_terms_json IS NOT NULL AND ${releaseAutoSql(repo)}
+    AND EXISTS (SELECT 1 FROM action_ledger ae WHERE ae.task_id = ${scope}.task_id AND ae.action = '${AUTO_EVIDENCE_ACTION}'
+        AND ae.outcome = ${scope}.approval_basis AND ${scope}.mode_digest = 'auto:' || ae.id AND json_valid(ae.detail)
+        AND json_extract(ae.detail, '$.v') = 1 AND json_extract(ae.detail, '$.digest') = ${scope}.approved_digest
+        AND json_extract(ae.detail, '$.candidate') = ${scope}.candidate)
+    AND NOT EXISTS (SELECT 1 FROM action_ledger aw WHERE aw.task_id = ${scope}.task_id AND aw.action = '${AUTO_WITHDRAWN_ACTION}' AND aw.outcome = ${scope}.mode_digest))`;
+export function autoEvidenceOf(store, taskId, modeDigest, kind) {
+    const match = /^auto:([1-9][0-9]{0,15})$/.exec(modeDigest ?? "");
+    if (match === null)
+        return null;
+    const row = store.handle.prepare("SELECT id, at, actor, task_id, outcome, detail FROM action_ledger WHERE id = ? AND action = ?").get(Number(match[1]), AUTO_EVIDENCE_ACTION);
+    if (row === undefined || row["task_id"] !== taskId || row["outcome"] !== kind)
+        return null;
+    if (store.handle.prepare("SELECT 1 AS hit FROM action_ledger WHERE task_id = ? AND action = ? AND outcome = ?").get(taskId, AUTO_WITHDRAWN_ACTION, `auto:${match[1]}`) !== undefined)
+        return null;
+    let detail;
+    try {
+        detail = JSON.parse(String(row["detail"]));
+    }
+    catch {
+        return null;
+    }
+    if (detail === null || typeof detail !== "object" || detail["v"] !== 1 || typeof detail["digest"] !== "string" || typeof detail["candidate"] !== "string")
+        return null;
+    const ci = Array.isArray(detail["ci"]) ? detail["ci"].filter((one) => one !== null && typeof one === "object" && Number.isSafeInteger(one.id) && typeof one.name === "string") : [];
+    const textOr = (value) => typeof value === "string" ? value : null;
+    return {
+        id: Number(row["id"]), kind, taskId, digest: detail["digest"], candidate: detail["candidate"], at: String(row["at"]), by: String(detail["by"] ?? row["actor"]),
+        run: Number.isSafeInteger(detail["run"]) ? Number(detail["run"]) : null, receipt: textOr(detail["receipt"]), ci, observedAt: textOr(detail["observedAt"]), base: textOr(detail["base"]),
+    };
+}

package/dist/release-auto.d.ts

@@ -0,0 +1,153 @@
+import { type CheckFailure } from "./release.js";
+import { RELEASE_APPROVAL_ACTION, releaseAutoApproves, type ReleaseApprovalSetting, releaseApprovalSetting } from "./release-authority.js";
+import { type Store } from "./store.js";
+export { RELEASE_APPROVAL_ACTION, releaseApprovalSetting, releaseAutoApproves, type ReleaseApprovalSetting };
+/** The setting's words, one place. */
+export declare const RELEASE_APPROVAL_WORDS: {
+    readonly ask: "Ask me";
+    readonly auto: "Approve automatically when checks pass";
+};
+/** How old the plane's own CI observation may be when it seals. */
+export declare const CI_OBSERVATION_MS: number;
+/** One check run on the candidate as the plane's own `gh` reported it (oldest first). */
+export type ObservedCheckRun = {
+    id: number | null;
+    name: string;
+    status: string;
+    conclusion: string | null;
+    app: string | null;
+    suite?: number | null;
+    head?: string | null;
+    workflow?: number | null;
+};
+/** The plane's own look at GitHub CI for one commit (release-adapters.ts makes it, right before the seal). */
+export type CiObservation = {
+    head: string;
+    observedAt: string;
+    runs: readonly ObservedCheckRun[];
+    /** Whether the history is whole (fewer check suites than GitHub's check-runs ceiling): false or absent refuses. */
+    complete?: boolean;
+};
+type Refusal = {
+    ok: false;
+    why: string;
+};
+/**
+ * Change the setting: an approver's act, proven by the caller (on: a password typed now; off: one click). Lowering it,
+ * in the same transaction, unseals every automatic seal of the project whose release hasn't started merging and stops
+ * their live releases, so nothing approves — or goes on — on the old setting.
+ */
+export declare function setReleaseApproval(store: Store, repo: string, auto: boolean, by: string, now: Date): {
+    changed: boolean;
+    withdrawn: string[];
+};
+/**
+ * The approval step with the setting on: seal `auto-check`, so the release task's build runs its check before anyone
+ * approves it. Idempotent: an `auto-check` already standing on this digest is the answer. A person's own approval
+ * already there is left alone (the coordinator then takes the person's road).
+ */
+export declare function authorizeAutoCheck(store: Store, input: {
+    taskId: string;
+    digest: string;
+    candidate: string;
+    /** Where the candidate left its release's base branch, as the plane read it from GitHub (release-adapters.ts
+     * readMergeBase): the one comparison base every check of this commit is judged against. Never a task branch. */
+    base: string;
+    now: Date;
+}): {
+    ok: true;
+    already: boolean;
+} | Refusal;
+/**
+ * What an automatic approval may ship without a person, as an allowlist over each changed path (auto-approve-green.md):
+ * product code under `src/` (its tests included; never its test helpers or fixtures, nor build configuration), test files
+ * under `test/` (only `*.test.ts`: never a helper, fixture or setup file; deleting any test needs a person), docs
+ * (never the testing policy or plans, never agent or security policy), the changelog and README, and a version bump of
+ * package.json and package-lock.json. Everything else — CI, scripts (the check, the build, the harness), test/,
+ * dependencies, the lockfile beyond its version, config — and every path the release carry rules never carry, needs a
+ * person. Null when the path may ship.
+ */
+export declare function autoPathProblem(path: string): string | null;
+/** Flakes: how many failed attempts one CI job, and how many unsuccessful release-check runs, may have before a person
+ * decides. The head and digest are pinned, so between attempts only nondeterminism differs. */
+export declare const MAX_FAILED_ATTEMPTS = 2;
+/** One CI attempt that failed before its job's latest attempt passed, as the evidence records it. */
+export type CiFailure = CheckFailure;
+/**
+ * GitHub CI on the exact head, as the plane read it (every attempt): fresh, every run GitHub Actions, and the same
+ * verdict every later release boundary uses (release.ts prChecksVerdict: exact head, each job by its latest attempt,
+ * every required check present), with the flake cap. The tolerated failures are returned for the evidence.
+ */
+export declare function ciVerdict(observation: CiObservation, candidate: string, now: Date): {
+    ok: true;
+    failures: CiFailure[];
+} | {
+    ok: false;
+    problem: string;
+};
+/** ciVerdict's problem, or null when CI passes. */
+export declare function ciProblem(observation: CiObservation, candidate: string, now: Date): string | null;
+/**
+ * The release approval, once the check passed: seal `auto-green` over the standing `auto-check`, or refuse in words —
+ * and on any refusal take the `auto-check` back, so a person decides. Everything is proven again in this one write
+ * transaction (docs/plans/auto-approve-green.md, "What auto-green proves").
+ */
+export declare function sealAutoGreen(store: Store, input: {
+    taskId: string;
+    digest: string;
+    candidate: string;
+    run: number;
+    receipt: string;
+    ci: CiObservation;
+    evidenceRoot: string;
+    now: Date;
+}): {
+    ok: true;
+    by: string;
+    at: string;
+    ci: {
+        id: number;
+        name: string;
+    }[];
+} | Refusal;
+/** The automatic road ended without an approval (a refusal, a failed check, a CI failure after the deploy): take the
+ * `auto-check` back so the task asks a person, and tell the owner why. Idempotent. */
+export declare function giveUpAutoApproval(store: Store, input: {
+    taskId: string;
+    why: string;
+    now: Date;
+}): void;
+/** A release check failed while checking automatically: tell the owner. The `auto-check` stays, so a regate of the same
+ * commit and digest (a flake) may still approve itself, within MAX_FAILED_ATTEMPTS failed runs. */
+export declare function noteAutoCheckFailed(store: Store, input: {
+    taskId: string;
+    why: string;
+    now: Date;
+}): void;
+/** "Released 0.9.x automatically": the release that approved itself finished. */
+export declare function noteAutoRelease(store: Store, input: {
+    taskId: string;
+    tag: string;
+    now: Date;
+}): void;
+/** Whether a task carries an automatic release seal (any state): it never merges or deploys outside `toolroll release`. */
+export declare function autoReleaseSealed(store: Store, taskId: string): boolean;
+/** The plane's record that an automatic release's publication waits for a person (CI stopped passing after its merge),
+ * and a person's answer. The newest row for the task wins. */
+export declare const PUBLISH_HELD_ACTION = "release publish held";
+export declare const PUBLISH_ALLOWED_ACTION = "release publish allowed";
+export declare function holdAutoPublish(store: Store, input: {
+    taskId: string;
+    why: string;
+    now: Date;
+}): void;
+/** Why the release's tag, publication and Homebrew wait for a person, or null. */
+export declare function autoPublishHeld(store: Store, taskId: string): string | null;
+/** A person lets a held publication go on: the caller proved a person (never the lead, a token or a mode). */
+export declare function allowAutoPublish(store: Store, input: {
+    taskId: string;
+    by: string;
+    now: Date;
+}): {
+    ok: true;
+} | Refusal;