toolroll 0.9.71 → 0.9.73

package/dist/release-view.d.ts

@@ -0,0 +1,34 @@
+import { type Store } from "./store.js";
+export type LandedView = {
+    sha: string;
+    task: string;
+    files: {
+        path: string;
+        added: number;
+        deleted: number;
+    }[];
+};
+export type ReleaseView = {
+    kind: "anchor" | "carried";
+    authority: number;
+    version: string;
+    pr: number;
+    state: string;
+    /** Whether the release still carries later commits, and why not. */
+    carrying: boolean;
+    why: string | null;
+    approver: string | null;
+    anchorTask: string;
+    tipTask: string;
+    expiresAt: string;
+    landed: LandedView[];
+    /** Identities a later check of this release must run again and pass (release-recheck.ts). */
+    obligations: string[];
+    nightly: {
+        at: string;
+        sha: string;
+        outcome: string | null;
+    } | null;
+    openMainFailures: number;
+};
+export declare function releaseViewOf(store: Store, taskId: string, now: Date, obligations?: (authority: number) => string[]): ReleaseView | null;

package/dist/release-view.js

@@ -0,0 +1,27 @@
+/**
+ * What a release task's page shows (docs/plans/release-once.md, "What people see"): for the approved task, the release
+ * it's approved for, every later commit carried under it, the open check obligations and the last nightly result for
+ * main; for a carried task, whose release approval it was carried from. Read-only, from the store.
+ */
+import { liveReleaseOf } from "./scope.js";
+import { releaseAuthorityOfTask, releaseCarries } from "./store.js";
+export function releaseViewOf(store, taskId, now, obligations = () => []) {
+    const found = releaseAuthorityOfTask(store, taskId);
+    if (found === null)
+        return null;
+    const a = found.authority;
+    const live = liveReleaseOf(store, a.tipTask, "dispatch", now);
+    const anchor = store.getScope(a.anchorTask);
+    const nightly = store.handle.prepare("SELECT sha, outcome, at FROM nightly_check WHERE repo = ? ORDER BY id DESC LIMIT 1").get(a.repo);
+    const open = Number(store.handle.prepare("SELECT COUNT(*) AS n FROM main_check_failure WHERE repo = ? AND cleared_at IS NULL").get(a.repo)?.["n"] ?? 0);
+    return {
+        kind: found.carry === null ? "anchor" : "carried",
+        authority: a.id, version: a.version, pr: a.pr, state: a.state,
+        carrying: a.state === "open" && live.applies && live.ok, why: live.applies && !live.ok ? live.why : null,
+        approver: anchor?.approvedBy ?? null, anchorTask: a.anchorTask, tipTask: a.tipTask, expiresAt: a.expiresAt,
+        landed: releaseCarries(store, a.id).flatMap(carry => carry.commits.map(commit => ({ sha: commit.sha, task: carry.taskId, files: commit.files }))),
+        obligations: obligations(a.id),
+        nightly: nightly === undefined ? null : { at: String(nightly["at"]), sha: String(nightly["sha"]), outcome: nightly["outcome"] == null ? null : String(nightly["outcome"]) },
+        openMainFailures: open,
+    };
+}

package/dist/release.d.ts

@@ -5,7 +5,11 @@
  *
  *   gate → approval → check → complete → quiet → deploy → link → ci → merge → tree → tag → publish → homebrew → done
  *
- * gate files a prepared-candidate task pinned to the branch's exact commit, with the full release check. approval
+ * gate, before filing a task for that commit, looks at the pull request's required checks on it: one that failed stops
+ * the release before anything is filed or sent for approval; it waits, naming them, for checks not started or still
+ * running, and stops if they don't finish within its limit (a task already filed is not looked at again; ci checks
+ * once more before merging). It then files a prepared-candidate task pinned to the branch's exact commit, with the full
+ * release check. approval
  * waits for an active approver's yes to that exact scope (never a mode's, an AI's or the lead's). check requires a Full
  * result of that commit: a failed check stops the release and stays visible, nothing reruns it. complete marks that
  * exact result Complete through the task's own authorization. quiet waits until nothing builds. deploy runs the
@@ -35,7 +39,7 @@ export declare const REQUIRED_PR_CHECKS: readonly ["node 22 · ubuntu-latest", "
 export declare const RELEASE_TAG_CHECKS: readonly ["node 22 · macos-latest", "node 24 · macos-latest", "publish"];
 export declare const RELEASE_STEPS: readonly ["gate", "approval", "check", "complete", "quiet", "deploy", "link", "ci", "merge", "tree", "tag", "publish", "homebrew", "done"];
 export type ReleaseStep = typeof RELEASE_STEPS[number];
-type WaitingStep = "approval" | "check" | "quiet" | "deploy" | "ci" | "publish" | "homebrew";
+type WaitingStep = "gate" | "approval" | "check" | "quiet" | "deploy" | "ci" | "publish" | "homebrew";
 /** How long each waiting step may take, in minutes, before the release stops there (rerunning continues from it). */
 export declare const RELEASE_LIMITS: Readonly<Record<WaitingStep, number>>;
 /** One check attempt; `app` is the GitHub App that made it (github-actions for a workflow), when known. */
@@ -65,6 +69,15 @@ export type GateState = {
         basis: string | null;
         role: string | null;
         active: boolean;
+        /** The plane's own answer to "did a person give this approval, with a person's proof recorded?" (approval policy
+         * §1.5). Absent from a plane too old to say, which is no person's approval. */
+        person?: {
+            ok: true;
+            method: string;
+        } | {
+            ok: false;
+            why: string;
+        };
     } | null;
     /** The newest finished build of the task: its sealed result and check. */
     result: {
@@ -115,7 +128,94 @@ export type HomebrewState = {
 } | {
     kind: "missing";
 };
+/** One commit that landed after the approval, with its files and line counts (release_carry). */
+export type LandedCommit = {
+    sha: string;
+    files: {
+        path: string;
+        added: number;
+        deleted: number;
+    }[];
+};
+/** A release's authority record as the coordinator reads it (store.ts release_authority). */
+export type AuthorityView = {
+    id: number;
+    generation: number;
+    state: string;
+    tipSha: string;
+    tipTask: string;
+    version: string;
+    pr: number;
+    landed: LandedCommit[];
+};
+export type ReleaseAction = "dispatch" | "deploy" | "merge" | "complete";
+export type OperationView = {
+    id: string;
+    kind: "deploy" | "merge";
+    state: "reserved" | "running" | "succeeded" | "failed" | "unknown";
+    candidate: string;
+    externalRef: string | null;
+    reservedAt: string;
+    /** Reserved by a person's own deploy run (deploy-browser.mjs), not a coordinator. */
+    direct: boolean;
+    /** Whether the process that issued it is proven gone (store.ts releaseIssuerGone): read when the view is made. */
+    issuerGone: boolean;
+    /** A direct deploy's staging folder. */
+    stage: string | null;
+};
+/** The release's authority record, through the plane's store (release-once.md). Absent: a plane too old to carry, and
+ * every commit asks for a person as before. */
+export type ReleaseAuthorityAdapter = {
+    authority(taskId: string): Promise<AuthorityView | null>;
+    live(taskId: string, action: ReleaseAction): Promise<{
+        applies: boolean;
+        ok: boolean;
+        why: string | null;
+    }>;
+    lease(authority: number, owner: string): Promise<{
+        ok: true;
+        epoch: number;
+    } | {
+        ok: false;
+        why: string;
+    }>;
+    renew(authority: number, owner: string, epoch: number): Promise<boolean>;
+    carry(authority: number, to: string, requestId: string, epoch: number): Promise<{
+        ok: true;
+        taskId: string;
+    } | {
+        ok: false;
+        message: string;
+    }>;
+    /** `secret`: proves a deploy run is this reservation's (handed to deploy-browser on stdin). */
+    reserve(input: {
+        authority: number;
+        kind: "deploy" | "merge";
+        taskId: string;
+        candidate: string;
+        epoch: number;
+    }): Promise<{
+        ok: true;
+        operation: string;
+        secret?: string;
+    } | {
+        ok: false;
+        why: string;
+    }>;
+    start(operation: string, epoch: number): Promise<boolean>;
+    /** Settle an operation at the epoch this coordinator holds; false: it no longer holds the release. */
+    finish(operation: string, outcome: "succeeded" | "failed" | "unknown", facts: {
+        detail?: string | null;
+        externalRef?: string | null;
+    }, epoch: number): Promise<boolean>;
+    /** A CI failure after the deploy (Alex's decision): the release stops and needs a person's fresh approval. False when
+     * the authority could not be stopped (a stale epoch, a merge already reserved): the coordinator fails closed. */
+    needsApproval(authority: number, reason: string, epoch: number): Promise<boolean>;
+    operations(authority: number): Promise<OperationView[]>;
+};
 export type ReleaseAdapters = {
+    /** One approval per release (release-once.md); absent on a plane that can't carry. */
+    release?: ReleaseAuthorityAdapter;
     now(): Date;
     sleep(ms: number): Promise<void>;
     say(line: string): void;
@@ -147,6 +247,13 @@ export type ReleaseAdapters = {
             candidate: string;
             goal: string;
             acceptance: string;
+            /** Release terms to file with the scope (task scope --release): the version, pull request and branch. */
+            release?: {
+                version: string;
+                pr: number;
+                branch: string;
+                noCarry: boolean;
+            };
         }): Promise<{
             scopeDigest: string;
         }>;
@@ -165,6 +272,10 @@ export type ReleaseAdapters = {
             run: number;
             worktree: string;
             stage: string;
+            operation?: {
+                id: string;
+                secret: string;
+            };
         }): Promise<{
             ok: true;
             runtime: string;
@@ -177,6 +288,9 @@ export type ReleaseAdapters = {
         }): Promise<{
             ok: true;
         } | DeployStop>;
+        /** Whether no deployment is at work or half done: no deploy-browser process, no update pause held, and `stage`'s
+         * journal (when given) unlocked and at a phase that changed nothing or finished. Null stage: unknown, so false. */
+        deploymentIdle(stage: string | null): Promise<boolean>;
         /** Where both CLI names are on PATH now. */
         cliLinks(): Promise<SavedLink[]>;
         /** Point every saved link at `bin` and check each answers `version`; on any failure every link goes back to its
@@ -187,7 +301,7 @@ export type ReleaseAdapters = {
         authenticated(): Promise<boolean>;
         pullRequest(repo: string, branch: string): Promise<PullRequest | null>;
         checks(repo: string, sha: string): Promise<CheckRun[]>;
-        merge(repo: string, pr: number, head: string): Promise<string>;
+        merge(repo: string, pr: number, head: string, message?: string): Promise<string>;
         tag(repo: string, tag: string): Promise<string | null>;
         createTag(repo: string, tag: string, sha: string): Promise<void>;
         release(repo: string, tag: string): Promise<boolean>;
@@ -273,6 +387,22 @@ export type ReleaseJournal = {
         head: string | null;
         merged: boolean;
     } | null;
+    /** The release's authority record (release-once.md), once a person approved terms: the id and generation. */
+    authority?: {
+        id: number;
+        generation: number;
+    } | null;
+    /** Commits that landed after the approval, carried under it: each with its files and line counts. */
+    landed?: LandedCommit[];
+    /** The deploy and merge operations this coordinator reserved (store.ts release_operation). */
+    operations?: {
+        deploy?: string;
+        merge?: string;
+    };
+    /** A pull request check failed after the deploy: nothing continues until a person approves again (--new). */
+    needsApproval?: boolean;
+    /** This journal's task was picked fresh after a CI failure after the deploy: an id that never existed, never another. */
+    freshTask?: boolean;
     /** When each step was about to change something outside this machine: what a resume must look for before acting. */
     intents: Partial<Record<ReleaseStep, string>>;
     stopped: {
@@ -307,7 +437,11 @@ export type ReleaseOptions = {
     /** Start over for a new commit on the branch, keeping the old journal aside. Refused once merging began. */
     fresh?: boolean;
     pollMs?: number;
+    /** File the release without carrying later commits: each one asks again. */
+    noCarry?: boolean;
 };
+/** Every commit that landed after the approval, in words: the summary and the merge message list them all. */
+export declare function landedWords(landed: readonly LandedCommit[]): string[];
 export declare const journalFile: (stateDir: string, branch: string) => string;
 export declare const resumeCommand: (branch: string, checkout: string) => string;
 /** Whole or not at all: a private temp file, synced, renamed into place, its folder synced. */
@@ -337,4 +471,6 @@ export declare function checksVerdict(runs: readonly CheckRun[], required: reado
 };
 /** Run the release from wherever its journal stopped. */
 export declare function runRelease(options: ReleaseOptions, adapters: ReleaseAdapters): Promise<ReleaseOutcome>;
+/** A probe's failure that is only the network to GitHub being slow, never a decision (a Stop) or another error. */
+export declare function transientNetworkError(error: unknown): boolean;
 export {};