toolroll 0.9.53 → 0.9.55

package/dist/release.d.ts

@@ -0,0 +1,331 @@
+/**
+ * `toolroll release <branch>` (D10): the whole release of Toolroll itself as one resumable command. The owner's
+ * approval of the release scope is the only human step; everything else runs headless, each waiting step with a time
+ * limit:
+ *
+ *   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
+ * 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
+ * candidate's own deploy (scripts/deploy-browser.mjs: drain, backup, rehearsal, swap, health) and keeps the runtime its
+ * final JSON names; an interrupted one is recovered from its saved stage (--phase recover) before anything else. link
+ * points both CLI names at that runtime's bin.js, putting them back if either doesn't answer, and goes on only when
+ * the console, worker and both names run the gated commit. ci waits for every
+ * reported pull-request check on that same commit to pass, with every required check present: pending, missing,
+ * skipped or failed never merges. merge
+ * squash-merges with the head pinned to the gated commit, tree proves main's new commit has exactly the gated tree,
+ * and only then tag pushes the version tag, whose macOS matrix must pass before npm publication (publish.yml). publish
+ * waits for npm, the GitHub release and the macOS checks; homebrew updates the tap's formula and merges it.
+ *
+ * A private journal (mode 0600, written whole then renamed) records what each step is about to do before it does
+ * anything outside this machine, and what it saw after. A stop — a time limit, a failure, a crash, Ctrl-C — leaves the
+ * journal at its step; running the same command again finds what already happened (the task, the completion, the
+ * merge, the tag, the package, the tap change) instead of doing it twice, and continues from the first unfinished
+ * step. A branch, pull request or tag that no longer matches what was gated stops the release rather than guess.
+ *
+ * Everything outside this module is an adapter (release-adapters.ts), so the state machine is tested without git,
+ * GitHub, npm or a running Toolroll.
+ */
+/** The pull-request checks a release waits for, by exact job name (.github/workflows/ci.yml). Every one must have
+ * concluded `success` on the gated commit; src/ci-workflow.test.ts holds the workflow to this list. */
+export declare const REQUIRED_PR_CHECKS: readonly ["node 22 · ubuntu-latest", "node 24 · ubuntu-latest", "linux native containment · delegated cgroup v2", "Windows Job Object containment"];
+/** The checks a release tag runs (.github/workflows/publish.yml), awaited before Homebrew moves. */
+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";
+/** 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>>;
+export type CheckRun = {
+    name: string;
+    status: string;
+    conclusion: string | null;
+};
+export type PullRequest = {
+    number: number;
+    state: "open" | "closed" | "merged";
+    head: string;
+    base: string;
+    mergeCommit: string | null;
+};
+/** The release task as Toolroll records it (`task show --json`). */
+export type GateState = {
+    exists: boolean;
+    candidate: string | null;
+    scopeDigest: string | null;
+    /** The current approval of the scope: by whom, of which digest, and how (`password` or `chat` is a person's yes). */
+    approval: {
+        by: string;
+        at: string;
+        digest: string;
+        basis: string | null;
+        role: string | null;
+        active: boolean;
+    } | null;
+    /** The newest finished build of the task: its sealed result and check. */
+    result: {
+        run: number;
+        head: string | null;
+        check: string;
+        level: string | null;
+        receipt: string;
+        worktree: string | null;
+    } | null;
+    /** A finished build that left no result to complete (it failed before the check), in words. */
+    failed: string | null;
+    completion: {
+        actor: string;
+        at: string;
+        digest: string;
+    } | null;
+};
+export type Installed = {
+    services: string[];
+    clis: {
+        name: string;
+        runtime: string | null;
+    }[];
+};
+/** A CLI name's link on PATH and where it pointed before the release moved it (release-links.ts). */
+export type SavedLink = {
+    name: string;
+    path: string;
+    before: string | null;
+    foreign?: true;
+};
+/** A deployment that stopped and couldn't recover. `gate`: the update pause it left, when its journal is before the swap. */
+export type DeployStop = {
+    ok: false;
+    message: string;
+    gate?: {
+        id: string;
+        phase: string;
+    };
+};
+export type HomebrewState = {
+    kind: "current";
+} | {
+    kind: "proposed";
+    pr: number;
+    head: string;
+} | {
+    kind: "missing";
+};
+export type ReleaseAdapters = {
+    now(): Date;
+    sleep(ms: number): Promise<void>;
+    say(line: string): void;
+    repo: {
+        /** owner/name of the gate checkout's origin. */
+        github(): Promise<string>;
+        /** Fetch the branch and main into the gate checkout (main fast-forwarded), so the gate diffs from today's main. */
+        sync(branch: string): Promise<void>;
+        remoteHead(branch: string): Promise<string | null>;
+        /** Delete only this exact branch head, with a lease; an already absent branch is finished. */
+        deleteBranch(branch: string, head: string): Promise<void>;
+        tree(sha: string): Promise<string>;
+        fileAt(sha: string, path: string): Promise<string | null>;
+        /** origin/main as the last sync fetched it. */
+        mainHead(): Promise<string>;
+        /** Whether `ancestor` is in `sha`'s history. */
+        contains(sha: string, ancestor: string): Promise<boolean>;
+    };
+    toolroll: {
+        /** Which runtime each launchd service and each CLI name (`toolroll`, `standing-orders`) runs from. */
+        installed(): Promise<Installed>;
+        /** The exact commit recorded in the deployment's runtime/package.json. */
+        runtimeCommit(runtime: string): Promise<string | null>;
+        gate(taskId: string): Promise<GateState>;
+        fileGate(input: {
+            taskId: string;
+            title: string;
+            checkout: string;
+            candidate: string;
+            goal: string;
+            acceptance: string;
+        }): Promise<{
+            scopeDigest: string;
+        }>;
+        complete(taskId: string, receipt: string): Promise<{
+            ok: true;
+        } | {
+            ok: false;
+            message: string;
+        }>;
+        busy(): Promise<{
+            running: number;
+            tasks: string[];
+        }>;
+        /** scripts/deploy-browser.mjs --run --stage --yes from the builder's checkout; runtime is its final JSON's `runtime`. */
+        deploy(input: {
+            run: number;
+            worktree: string;
+            stage: string;
+        }): Promise<{
+            ok: true;
+            runtime: string;
+        } | DeployStop>;
+        /** scripts/deploy-browser.mjs --stage --phase recover for a stage that was launched; a stage never prepared is ok. */
+        recoverDeploy(input: {
+            run: number;
+            worktree: string;
+            stage: string;
+        }): Promise<{
+            ok: true;
+        } | DeployStop>;
+        /** 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
+         * saved `before` and this throws. */
+        switchLinks(links: readonly SavedLink[], bin: string, version: string): Promise<void>;
+    };
+    github: {
+        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>;
+        tag(repo: string, tag: string): Promise<string | null>;
+        createTag(repo: string, tag: string, sha: string): Promise<void>;
+        release(repo: string, tag: string): Promise<boolean>;
+    };
+    registry: {
+        published(name: string, version: string): Promise<boolean>;
+    };
+    homebrew: {
+        repo: string;
+        state(version: string): Promise<HomebrewState>;
+        propose(version: string): Promise<{
+            pr: number;
+            head: string;
+        }>;
+        merge(pr: number, head: string): Promise<void>;
+    };
+};
+export type ReleaseJournal = {
+    version: 1;
+    id: string;
+    github: string;
+    checkout: string;
+    branch: string;
+    candidate: {
+        sha: string;
+        tree: string;
+    };
+    packageName: string;
+    packageVersion: string;
+    tag: string;
+    pr: number;
+    step: ReleaseStep;
+    task: {
+        id: string;
+        scopeDigest: string | null;
+    };
+    approval: {
+        by: string;
+        at: string;
+    } | null;
+    check: {
+        run: number;
+        receipt: string;
+        worktree: string;
+    } | null;
+    completion: {
+        actor: string;
+        at: string;
+    } | null;
+    deploy: {
+        runtime: string;
+        at: string;
+    } | null;
+    /** Saved before launching deploy, so a killed coordinator can recover that exact attempt first. */
+    deployAttempt?: {
+        stage: string;
+    } | null;
+    /** Where both CLI names pointed before link moved them: saved first, so a resumed or failed relink can put them back. */
+    links?: SavedLink[] | null;
+    ci: {
+        checks: string[];
+        at: string;
+    } | null;
+    merge: {
+        sha: string;
+        tree: string | null;
+    } | null;
+    tagged: {
+        sha: string;
+    } | null;
+    published: {
+        at: string;
+    } | null;
+    homebrew: {
+        pr: number | null;
+        head: string | null;
+        merged: boolean;
+    } | null;
+    /** 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: {
+        step: ReleaseStep;
+        reason: string;
+        message: string;
+        at: string;
+    } | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type ReleaseOutcome = {
+    ok: true;
+    journal: ReleaseJournal;
+    file: string;
+} | {
+    ok: false;
+    reason: string;
+    message: string;
+    step: ReleaseStep | "preflight";
+    journal: ReleaseJournal | null;
+    file: string;
+    resume: string;
+};
+export type ReleaseOptions = {
+    branch: string;
+    /** The gate checkout: a clone of the repository the release check runs in. */
+    checkout: string;
+    /** Where journals live (the installation's state folder). */
+    stateDir: string;
+    limits?: Partial<Record<WaitingStep, number>>;
+    /** Start over for a new commit on the branch, keeping the old journal aside. Refused once merging began. */
+    fresh?: boolean;
+    pollMs?: number;
+};
+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. */
+export declare function writeJournal(file: string, journal: ReleaseJournal): void;
+export declare function readJournal(file: string): ReleaseJournal | null;
+/** The release task's id: one per exact commit, so a rerun finds the task it filed instead of filing another. */
+export declare const gateTaskId: (version: string, sha: string) => string;
+/** Whether the scope's approval is the owner's own yes to these exact bytes: a person through the password (or
+ * identity) ceremony or a chat confirmation — never a mode's coverage, an AI teammate, a routine or the lead. */
+export declare function ownerApproval(gate: GateState, digest: string | null): {
+    ok: true;
+    by: string;
+    at: string;
+} | {
+    ok: false;
+    why: string;
+};
+/** Every required check present, and every reported check's newest attempt completed successfully. */
+export declare function checksVerdict(runs: readonly CheckRun[], required: readonly string[]): {
+    state: "passed";
+} | {
+    state: "pending";
+    waiting: string[];
+} | {
+    state: "failed";
+    failed: string[];
+};
+/** Run the release from wherever its journal stopped. */
+export declare function runRelease(options: ReleaseOptions, adapters: ReleaseAdapters): Promise<ReleaseOutcome>;
+export {};