toolroll 0.9.54 → 0.9.56

package/dist/release.js

@@ -0,0 +1,550 @@
+/**
+ * `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.
+ */
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+/** 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 const REQUIRED_PR_CHECKS = [
+    "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 const RELEASE_TAG_CHECKS = ["node 22 · macos-latest", "node 24 · macos-latest", "publish"];
+export const RELEASE_STEPS = ["gate", "approval", "check", "complete", "quiet", "deploy", "link", "ci", "merge", "tree", "tag", "publish", "homebrew", "done"];
+/** How long each waiting step may take, in minutes, before the release stops there (rerunning continues from it). */
+export const RELEASE_LIMITS = { approval: 24 * 60, check: 120, quiet: 60, deploy: 30, ci: 60, publish: 45, homebrew: 45 };
+const POLL_MS = 15_000;
+/** A stop the release reports: the step it stopped at and why, in words. */
+class Stop extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+    }
+}
+const branchFile = (branch) => branch.replace(/[^A-Za-z0-9._-]+/g, "_");
+export const journalFile = (stateDir, branch) => join(stateDir, "releases", `${branchFile(branch)}.json`);
+export const resumeCommand = (branch, checkout) => `toolroll release ${branch} --repo ${checkout}`;
+/** Whole or not at all: a private temp file, synced, renamed into place, its folder synced. */
+export function writeJournal(file, journal) {
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    const temp = `${file}.${randomUUID()}.tmp`;
+    const fd = openSync(temp, "wx", 0o600);
+    try {
+        writeFileSync(fd, `${JSON.stringify(journal, null, 2)}\n`);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(temp, file);
+    if (process.platform !== "win32") {
+        const folder = openSync(dirname(file), "r");
+        try {
+            fsyncSync(folder);
+        }
+        finally {
+            closeSync(folder);
+        }
+    }
+}
+export function readJournal(file) {
+    if (!existsSync(file))
+        return null;
+    const parsed = JSON.parse(readFileSync(file, "utf8"));
+    if (parsed.version !== 1 || !RELEASE_STEPS.includes(parsed.step))
+        throw new Error(`${file} is not a release journal this version reads`);
+    return parsed;
+}
+/** The release task's id: one per exact commit, so a rerun finds the task it filed instead of filing another. */
+export const gateTaskId = (version, sha) => `release-${version.replace(/[^0-9A-Za-z.-]/g, "-")}-${sha.slice(0, 7)}`;
+/** 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 function ownerApproval(gate, digest) {
+    const approval = gate.approval;
+    if (approval === null)
+        return { ok: false, why: "not approved yet" };
+    if (digest === null || approval.digest !== digest)
+        return { ok: false, why: "the approval is for different scope text" };
+    if (approval.basis !== "password" && approval.basis !== "chat")
+        return { ok: false, why: `approved by ${approval.basis ?? "an unknown road"}, not by a person` };
+    if (/ \(AI\)$/.test(approval.by) || /^mode /.test(approval.by) || /^lead\b/.test(approval.by) || approval.by === "routine")
+        return { ok: false, why: `approved as ${approval.by}, not by a person` };
+    if (approval.role !== "approver" || !approval.active)
+        return { ok: false, why: `approved by ${approval.by}, who is not an active approver` };
+    return { ok: true, by: approval.by, at: approval.at };
+}
+/** Every required check present, and every reported check's newest attempt completed successfully. */
+export function checksVerdict(runs, required) {
+    const failed = [], waiting = [];
+    // The adapter orders attempts oldest first, so the last attempt for each name is authoritative.
+    const latest = new Map(runs.map(run => [run.name, run]));
+    for (const name of new Set([...required, ...latest.keys()])) {
+        const run = latest.get(name);
+        if (run === undefined || run.status !== "completed") {
+            waiting.push(run === undefined ? `${name} (not started)` : `${name} (${run.status})`);
+            continue;
+        }
+        if (run.conclusion !== "success")
+            failed.push(`${name} (${run.conclusion ?? "no conclusion"})`);
+    }
+    if (failed.length > 0)
+        return { state: "failed", failed };
+    return waiting.length > 0 ? { state: "pending", waiting } : { state: "passed" };
+}
+/** Run the release from wherever its journal stopped. */
+export async function runRelease(options, adapters) {
+    const file = journalFile(options.stateDir, options.branch);
+    const resume = resumeCommand(options.branch, options.checkout);
+    const limits = { ...RELEASE_LIMITS, ...options.limits };
+    const pollMs = options.pollMs ?? POLL_MS;
+    const say = adapters.say;
+    let journal = null;
+    let step = "preflight";
+    const save = () => { journal.updatedAt = adapters.now().toISOString(); writeJournal(file, journal); };
+    const advance = (next) => { journal.step = next; journal.stopped = null; save(); };
+    const intend = (at) => { journal.intents[at] = adapters.now().toISOString(); save(); };
+    const recoverDeploy = async () => {
+        const j = journal;
+        if (j.step !== "deploy" || j.intents.deploy === undefined)
+            return;
+        if (!j.deployAttempt)
+            throw new Stop("deploy-recovery", "The interrupted deployment has no saved staging path. Recover it with the deployment journal before starting another release.");
+        const recovered = await adapters.toolroll.recoverDeploy({ ...j.check, stage: j.deployAttempt.stage });
+        if (!recovered.ok)
+            throw deployStop("deploy-recovery", `Deployment recovery stopped: ${recovered.message}`, recovered);
+        j.deployAttempt = null;
+        delete j.intents.deploy;
+        save();
+    };
+    /** Ask `probe` until it answers, within this step's limit. */
+    const waitFor = async (at, what, probe) => {
+        const deadline = adapters.now().getTime() + limits[at] * 60_000;
+        let said = false;
+        for (;;) {
+            const answer = await probe();
+            if (answer !== null)
+                return answer;
+            if (adapters.now().getTime() >= deadline)
+                throw new Stop("timeout", `Still waiting for ${what} after ${limits[at]} minutes.`);
+            if (!said) {
+                say(`  waiting for ${what} (up to ${limits[at]} min)`);
+                said = true;
+            }
+            await adapters.sleep(pollMs);
+        }
+    };
+    try {
+        journal = readJournal(file);
+        if (journal !== null && options.fresh === true && journal.step !== "done") {
+            if (journal.intents.merge !== undefined)
+                throw new Stop("merging", `The release of ${journal.candidate.sha.slice(0, 7)} already began merging; finish it with \`${resume}\` instead of starting over.`);
+            await recoverDeploy();
+            const aside = file.replace(/\.json$/, `.superseded-${adapters.now().toISOString().replace(/[:.]/g, "-")}.json`);
+            renameSync(file, aside);
+            say(`Kept the earlier release journal at ${aside}.`);
+            journal = null;
+        }
+        if (journal?.step === "done") {
+            say(`Released ${journal.tag} (${journal.candidate.sha.slice(0, 7)}) — nothing left to do.`);
+            return { ok: true, journal, file };
+        }
+        if (!await adapters.github.authenticated())
+            throw new Stop("github-auth", "GitHub CLI is not signed in: run `gh auth login`, then rerun.");
+        if (journal === null)
+            journal = await begin(options, adapters, adapters.now());
+        else
+            say(`Resuming the release of ${journal.tag} (${journal.candidate.sha.slice(0, 7)}) at ${journal.step}.`);
+        const j = journal;
+        if (j.checkout !== options.checkout)
+            throw new Stop("checkout", `This release runs in ${j.checkout}; rerun with --repo ${j.checkout}.`);
+        save();
+        // Before anything merges, the branch and its pull request must still be the gated commit.
+        const pinned = async () => {
+            const head = await adapters.repo.remoteHead(j.branch);
+            if (head !== j.candidate.sha)
+                throw new Stop("drift", `${j.branch} moved from ${j.candidate.sha.slice(0, 7)} to ${head?.slice(0, 7) ?? "nothing"} after it was gated. Run \`toolroll release ${j.branch} --repo ${j.checkout} --new\` to release the new commit.`);
+            const pr = await adapters.github.pullRequest(j.github, j.branch);
+            if (pr === null || pr.number !== j.pr || (pr.state === "open" && pr.head !== j.candidate.sha))
+                throw new Stop("drift", `Pull request #${j.pr} no longer has ${j.candidate.sha.slice(0, 7)} at its head.`);
+            return pr;
+        };
+        const approved = (gate) => {
+            if (gate.candidate !== j.candidate.sha || gate.scopeDigest !== j.task.scopeDigest)
+                throw new Stop("scope-changed", `Task ${j.task.id}'s candidate or scope changed after approval.`);
+            const owner = ownerApproval(gate, j.task.scopeDigest);
+            if (!owner.ok)
+                throw new Stop("approval", `Task ${j.task.id}: ${owner.why}. An active approver must approve the release scope.`);
+        };
+        const fullCheck = (gate) => {
+            if (gate.result?.level !== "full")
+                throw new Stop("check-level", `A Full check is required for this release (run ${gate.result?.run ?? "unknown"}: ${gate.result?.level ?? "unknown"}). Quick and Off checks cannot release a build.`);
+            if (gate.result.check !== "passed")
+                throw new Stop("check-failed", `The Full release check of ${j.candidate.sha.slice(0, 7)} did not pass (run ${gate.result.run}: ${gate.result.check}). It stays as it is: fix the branch and release the new commit with --new.`);
+        };
+        const checked = (gate) => {
+            approved(gate);
+            if (gate.result?.head !== j.candidate.sha || gate.result?.receipt !== j.check?.receipt)
+                throw new Stop("drift", `Task ${j.task.id}'s result changed since its check passed.`);
+            fullCheck(gate);
+        };
+        while (j.step !== "done") {
+            step = j.step;
+            say(`• ${j.step}`);
+            switch (j.step) {
+                case "gate": {
+                    await pinned();
+                    const existing = await adapters.toolroll.gate(j.task.id);
+                    if (existing.exists) {
+                        if (existing.candidate !== j.candidate.sha)
+                            throw new Stop("conflict", `Task ${j.task.id} exists for a different commit (${existing.candidate?.slice(0, 7) ?? "none"}).`);
+                        j.task.scopeDigest = existing.scopeDigest;
+                    }
+                    else {
+                        intend("gate");
+                        await adapters.repo.sync(j.branch);
+                        const filed = await adapters.toolroll.fileGate({
+                            taskId: j.task.id, title: `Release ${j.packageVersion}`, checkout: j.checkout, candidate: j.candidate.sha,
+                            goal: `Verify ${j.packageName} ${j.packageVersion} (${j.branch} at ${j.candidate.sha}) passes the approved release check before it is deployed, merged, tagged and published.`,
+                            acceptance: "The approved release check passes on the candidate commit|check",
+                        });
+                        j.task.scopeDigest = filed.scopeDigest;
+                    }
+                    advance("approval");
+                    break;
+                }
+                case "approval": {
+                    say(`  The release scope needs your approval: \`toolroll task approve ${j.task.id} --digest ${j.task.scopeDigest}\`, or open the task in the console.`);
+                    const approved = await waitFor("approval", `a person to approve task ${j.task.id}`, async () => {
+                        const gate = await adapters.toolroll.gate(j.task.id);
+                        if (gate.scopeDigest !== j.task.scopeDigest)
+                            throw new Stop("scope-changed", `The scope of ${j.task.id} changed after it was filed; the release only runs on the scope it filed.`);
+                        const owner = ownerApproval(gate, j.task.scopeDigest);
+                        if (!owner.ok && gate.approval !== null && owner.why !== "the approval is for different scope text")
+                            throw new Stop("approval", `Task ${j.task.id} was ${owner.why}; the release needs a person to approve it.`);
+                        return owner.ok ? owner : null;
+                    });
+                    j.approval = { by: approved.by, at: approved.at };
+                    say(`  approved by ${approved.by}`);
+                    advance("check");
+                    break;
+                }
+                case "check": {
+                    const result = await waitFor("check", `the release check of ${j.candidate.sha.slice(0, 7)}`, async () => {
+                        const gate = await adapters.toolroll.gate(j.task.id);
+                        approved(gate);
+                        if (gate.failed !== null)
+                            throw new Stop("check-failed", `The release build of ${j.task.id} failed: ${gate.failed}. Fix it and release the new commit with --new.`);
+                        if (gate.result === null || gate.result.check === "running" || gate.result.check === "pending")
+                            return null;
+                        if (gate.result.head !== j.candidate.sha)
+                            throw new Stop("drift", `The release result is for ${gate.result.head?.slice(0, 7) ?? "no commit"}, not ${j.candidate.sha.slice(0, 7)}.`);
+                        fullCheck(gate);
+                        if (gate.result.worktree === null)
+                            throw new Stop("worktree", `Run ${gate.result.run} names no checkout to deploy from.`);
+                        return { run: gate.result.run, receipt: gate.result.receipt, worktree: gate.result.worktree };
+                    });
+                    j.check = result;
+                    say(`  run ${result.run} passed on ${j.candidate.sha.slice(0, 7)}`);
+                    advance("complete");
+                    break;
+                }
+                case "complete": {
+                    const check = j.check;
+                    const gate = await adapters.toolroll.gate(j.task.id);
+                    checked(gate);
+                    if (gate.completion?.digest !== check.receipt) {
+                        intend("complete");
+                        const done = await adapters.toolroll.complete(j.task.id, check.receipt);
+                        if (!done.ok)
+                            throw new Stop("complete", `Couldn't mark task ${j.task.id} complete: ${done.message} Mark that exact result complete in the console, then rerun.`);
+                    }
+                    const after = await adapters.toolroll.gate(j.task.id);
+                    if (after.completion?.digest !== check.receipt)
+                        throw new Stop("complete", `Task ${j.task.id} is not marked complete for result ${check.receipt.slice(0, 12)}.`);
+                    j.completion = { actor: after.completion.actor, at: after.completion.at };
+                    advance("quiet");
+                    break;
+                }
+                case "quiet": {
+                    await waitFor("quiet", "running work to finish", async () => {
+                        const busy = await adapters.toolroll.busy();
+                        return busy.running === 0 ? true : null;
+                    });
+                    advance("deploy");
+                    break;
+                }
+                case "deploy": {
+                    const check = j.check;
+                    await recoverDeploy();
+                    checked(await adapters.toolroll.gate(j.task.id));
+                    // A deployment that finished but whose answer was lost: the services already run a runtime of this commit.
+                    let runtime = await served(adapters, j.candidate.sha);
+                    if (runtime === null) {
+                        await pinned();
+                        j.deployAttempt = { stage: join(options.stateDir, "staged-upgrades", `browser-${j.candidate.sha.slice(0, 7)}-${randomUUID()}`) };
+                        intend("deploy");
+                        const result = await adapters.toolroll.deploy({ run: check.run, worktree: check.worktree, stage: j.deployAttempt.stage });
+                        if (!result.ok)
+                            throw deployStop("deploy", `The deployment of run ${check.run} stopped: ${result.message}`, result);
+                        if (!/[\\/]dist$/.test(result.runtime))
+                            throw new Stop("deploy", `The deployment named ${result.runtime} as its runtime, which is not a dist folder.`);
+                        runtime = result.runtime;
+                        // Saved at once: everything after this (relinking, a rerun) uses the runtime the deployer named.
+                        j.deploy = { runtime, at: adapters.now().toISOString() };
+                        save();
+                    }
+                    const want = runtime;
+                    await waitFor("deploy", `the console and worker to run the gated commit from ${want}`, async () => (await served(adapters, j.candidate.sha)) === want ? true : null);
+                    j.deploy = { runtime: want, at: j.deploy?.runtime === want ? j.deploy.at : adapters.now().toISOString() };
+                    j.deployAttempt = null;
+                    delete j.intents.deploy;
+                    say(`  the service runs ${j.packageVersion} from ${want}`);
+                    advance("link");
+                    break;
+                }
+                case "link": {
+                    const runtime = j.deploy.runtime;
+                    if (await served(adapters, j.candidate.sha) !== runtime)
+                        throw new Stop("drift", `The console and worker no longer run ${runtime}; the CLI names were not moved.`);
+                    if (j.links === undefined || j.links === null) {
+                        j.links = await adapters.toolroll.cliLinks();
+                        intend("link");
+                    }
+                    try {
+                        await adapters.toolroll.switchLinks(j.links, join(runtime, "bin.js"), j.packageVersion);
+                    }
+                    catch (error) {
+                        throw new Stop("link", `The CLI names were not moved to ${runtime} (they point where they did): ${error.message}. The service already runs the new build; rerun to try again.`);
+                    }
+                    const everywhere = await deployed(adapters, j.candidate.sha);
+                    if (everywhere !== runtime)
+                        throw new Stop("mixed-runtime", `After relinking, the console, worker and both CLI names don't all run ${runtime} at ${j.candidate.sha.slice(0, 7)}.`);
+                    say(`  toolroll and standing-orders run ${join(runtime, "bin.js")}`);
+                    advance("ci");
+                    break;
+                }
+                case "ci": {
+                    await waitFor("ci", `the pull request checks on ${j.candidate.sha.slice(0, 7)}`, async () => {
+                        await pinned();
+                        const verdict = checksVerdict(await adapters.github.checks(j.github, j.candidate.sha), REQUIRED_PR_CHECKS);
+                        if (verdict.state === "failed")
+                            throw new Stop("ci-failed", `Pull request checks failed on ${j.candidate.sha.slice(0, 7)}: ${verdict.failed.join(", ")}. Nothing was merged. Rerun the failed job on GitHub, then rerun this command.`);
+                        return verdict.state === "passed" ? true : null;
+                    });
+                    j.ci = { checks: [...REQUIRED_PR_CHECKS], at: adapters.now().toISOString() };
+                    advance("merge");
+                    break;
+                }
+                case "merge": {
+                    const pr = await adapters.github.pullRequest(j.github, j.branch);
+                    if (pr?.state === "merged" && pr.number === j.pr && pr.mergeCommit !== null) {
+                        if (pr.head !== j.candidate.sha || pr.base !== "main")
+                            throw new Stop("drift", `Merged pull request #${j.pr} does not match the gated commit and base.`);
+                        if (j.intents.merge === undefined)
+                            intend("merge");
+                        j.merge = { sha: pr.mergeCommit, tree: null };
+                    }
+                    else {
+                        await pinned();
+                        // A squash merge only reproduces the gated tree when main hasn't moved past the branch's base.
+                        await adapters.repo.sync(j.branch);
+                        const main = await adapters.repo.mainHead();
+                        if (!await adapters.repo.contains(j.candidate.sha, main))
+                            throw new Stop("base-moved", `main moved to ${main.slice(0, 7)}, which ${j.branch} doesn't contain, so the merge wouldn't be the gated tree. Nothing was merged: update the branch and release the new commit with --new.`);
+                        // The checks again, at the moment of merging: a rerun that failed since must not merge.
+                        const verdict = checksVerdict(await adapters.github.checks(j.github, j.candidate.sha), REQUIRED_PR_CHECKS);
+                        if (verdict.state !== "passed")
+                            throw new Stop("ci-failed", `Pull request checks are no longer all passing on ${j.candidate.sha.slice(0, 7)}; nothing was merged.`);
+                        intend("merge");
+                        j.merge = { sha: await adapters.github.merge(j.github, j.pr, j.candidate.sha), tree: null };
+                    }
+                    save();
+                    // This also runs after discovering a merge whose response was lost. Never delete a reused branch.
+                    await adapters.repo.deleteBranch(j.branch, j.candidate.sha);
+                    advance("tree");
+                    break;
+                }
+                case "tree": {
+                    const merge = j.merge;
+                    await adapters.repo.sync(j.branch);
+                    const tree = await adapters.repo.tree(merge.sha);
+                    merge.tree = tree;
+                    if (tree !== j.candidate.tree)
+                        throw new Stop("tree-mismatch", `Main's merge commit ${merge.sha.slice(0, 7)} has tree ${tree.slice(0, 12)}, not the gated ${j.candidate.tree.slice(0, 12)}: main changed what was checked. Nothing was tagged; the deployed build stays as it is.`);
+                    advance("tag");
+                    break;
+                }
+                case "tag": {
+                    const merge = j.merge;
+                    const at = await adapters.github.tag(j.github, j.tag);
+                    if (at !== null && at !== merge.sha)
+                        throw new Stop("conflict", `${j.tag} already points at ${at.slice(0, 7)}, not the merge ${merge.sha.slice(0, 7)}.`);
+                    if (at === null) {
+                        intend("tag");
+                        await adapters.github.createTag(j.github, j.tag, merge.sha);
+                    }
+                    j.tagged = { sha: merge.sha };
+                    advance("publish");
+                    break;
+                }
+                case "publish": {
+                    if (j.intents.publish === undefined)
+                        intend("publish");
+                    await waitFor("publish", `npm, the GitHub release and the tag's checks for ${j.tag}`, async () => {
+                        if (await adapters.github.tag(j.github, j.tag) !== j.tagged.sha)
+                            throw new Stop("conflict", `${j.tag} no longer points at the verified merge commit. Homebrew was not updated.`);
+                        const verdict = checksVerdict(await adapters.github.checks(j.github, j.tagged.sha), RELEASE_TAG_CHECKS);
+                        if (verdict.state === "failed")
+                            throw new Stop("publish-failed", `The release tag's checks failed: ${verdict.failed.join(", ")}. Homebrew was not updated.`);
+                        if (verdict.state === "pending")
+                            return null;
+                        return await adapters.registry.published(j.packageName, j.packageVersion) && await adapters.github.release(j.github, j.tag) ? true : null;
+                    });
+                    j.published = { at: adapters.now().toISOString() };
+                    advance("homebrew");
+                    break;
+                }
+                case "homebrew": {
+                    const brew = adapters.homebrew;
+                    let state = await brew.state(j.packageVersion);
+                    if (state.kind === "missing") {
+                        intend("homebrew");
+                        const proposed = await brew.propose(j.packageVersion);
+                        state = { kind: "proposed", ...proposed };
+                    }
+                    if (state.kind === "proposed") {
+                        const proposed = state;
+                        j.homebrew = { pr: proposed.pr, head: proposed.head, merged: false };
+                        save();
+                        await waitFor("homebrew", `the Homebrew change's checks (${brew.repo} #${proposed.pr})`, async () => {
+                            const runs = await adapters.github.checks(brew.repo, proposed.head);
+                            // GitHub registers checks asynchronously; an empty set says nothing about success.
+                            if (runs.length === 0)
+                                return null;
+                            const verdict = checksVerdict(runs, [...new Set(runs.map(one => one.name))]);
+                            if (verdict.state === "failed")
+                                throw new Stop("homebrew-failed", `The Homebrew change's checks failed: ${verdict.failed.join(", ")}.`);
+                            return verdict.state === "passed" ? true : null;
+                        });
+                        await brew.merge(proposed.pr, proposed.head);
+                    }
+                    j.homebrew = { pr: j.homebrew?.pr ?? null, head: j.homebrew?.head ?? null, merged: true };
+                    advance("done");
+                    break;
+                }
+            }
+        }
+        say(`Released ${j.tag}: deployed, merged as ${j.merge.sha.slice(0, 7)}, tagged, published and on Homebrew.`);
+        return { ok: true, journal: j, file };
+    }
+    catch (error) {
+        const stop = error instanceof Stop ? error : new Stop("error", String(error?.message ?? error));
+        if (journal !== null) {
+            journal.stopped = { step: journal.step, reason: stop.reason, message: stop.message, at: adapters.now().toISOString() };
+            try {
+                save();
+            }
+            catch { /* the stop is still reported */ }
+        }
+        return { ok: false, reason: stop.reason, message: stop.message, step: journal?.step ?? step, journal, file, resume };
+    }
+}
+/** The first run: everything checked before anything changes. */
+async function begin(options, adapters, now) {
+    const { branch, checkout } = options;
+    if (["main", "master"].includes(branch))
+        throw new Stop("usage", "Release a branch with an open pull request, not main.");
+    const installed = await adapters.toolroll.installed();
+    const runtimes = new Set([...installed.services, ...installed.clis.map(one => one.runtime ?? "(not linked)")]);
+    if (installed.services.length === 0 || runtimes.size !== 1) {
+        throw new Stop("mixed-runtime", `The console, worker and CLI names don't run one build (${[...installed.services.map(one => `service ${one}`), ...installed.clis.map(one => `${one.name} ${one.runtime ?? "not linked"}`)].join("; ")}). Update them to one verified build first.`);
+    }
+    const github = await adapters.repo.github();
+    await adapters.repo.sync(branch);
+    const sha = await adapters.repo.remoteHead(branch);
+    if (sha === null)
+        throw new Stop("no-branch", `${branch} is not on ${github}: push it first.`);
+    const pr = await adapters.github.pullRequest(github, branch);
+    if (pr === null || pr.state !== "open")
+        throw new Stop("no-pull-request", `${branch} has no open pull request: open one first.`);
+    if (pr.head !== sha)
+        throw new Stop("drift", `Pull request #${pr.number} is at ${pr.head.slice(0, 7)}, the branch at ${sha.slice(0, 7)}.`);
+    if (pr.base !== "main")
+        throw new Stop("base", `Pull request #${pr.number} merges into ${pr.base}, not main.`);
+    const manifest = await adapters.repo.fileAt(sha, "package.json");
+    const pkg = manifest === null ? null : JSON.parse(manifest);
+    if (typeof pkg?.name !== "string" || typeof pkg.version !== "string")
+        throw new Stop("version", `package.json at ${sha.slice(0, 7)} names no package version.`);
+    const tag = `v${pkg.version}`;
+    const changelog = await adapters.repo.fileAt(sha, "CHANGELOG.md") ?? "";
+    if (!new RegExp(`^## ${pkg.version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}( |$)`, "m").test(changelog))
+        throw new Stop("changelog", `CHANGELOG.md at ${sha.slice(0, 7)} has no "## ${pkg.version}" entry; the lead writes it before the release.`);
+    if (await adapters.github.tag(github, tag) !== null)
+        throw new Stop("version", `${tag} already exists: bump the version first.`);
+    if (await adapters.registry.published(pkg.name, pkg.version))
+        throw new Stop("version", `${pkg.name}@${pkg.version} is already on npm: bump the version first.`);
+    const tree = await adapters.repo.tree(sha);
+    const at = now.toISOString();
+    adapters.say(`Releasing ${pkg.name} ${pkg.version}: ${branch} at ${sha.slice(0, 7)}, pull request #${pr.number}.`);
+    return {
+        version: 1, id: randomUUID(), github, checkout, branch, candidate: { sha, tree }, packageName: pkg.name, packageVersion: pkg.version, tag, pr: pr.number,
+        step: "gate", task: { id: gateTaskId(pkg.version, sha), scopeDigest: null }, approval: null, check: null, completion: null, deploy: null, ci: null,
+        merge: null, tagged: null, published: null, homebrew: null, intents: {}, stopped: null, createdAt: at, updatedAt: at,
+    };
+}
+/** A deployment stop; when it left an update pause before the swap, the guided way to lift it. */
+function deployStop(reason, message, stop) {
+    if (stop.gate === undefined)
+        return new Stop(reason, message);
+    return new Stop("gate-held", `${message} New work is still paused by update ${stop.gate.id} (its journal stopped at ${stop.gate.phase}, before the swap). Check and lift that pause with \`toolroll release --release-gate ${stop.gate.id}\`, then rerun.`);
+}
+/** The one runtime the launchd services run, when it records the gated commit; otherwise null. */
+async function served(adapters, candidate) {
+    const installed = await adapters.toolroll.installed();
+    const runtimes = new Set(installed.services);
+    if (runtimes.size !== 1)
+        return null;
+    const [runtime] = runtimes;
+    return runtime !== undefined && await adapters.toolroll.runtimeCommit(runtime) === candidate ? runtime : null;
+}
+/** The one runtime the services and both CLI names run, when it records the gated commit; otherwise null. */
+async function deployed(adapters, candidate) {
+    const installed = await adapters.toolroll.installed();
+    const runtimes = new Set([...installed.services, ...installed.clis.map(one => one.runtime ?? "")]);
+    if (installed.services.length === 0 || installed.clis.length < 2 || runtimes.size !== 1)
+        return null;
+    const [runtime] = runtimes;
+    return runtime !== undefined && runtime !== "" && await adapters.toolroll.runtimeCommit(runtime) === candidate ? runtime : null;
+}

package/dist/reply-shape.d.ts

@@ -12,6 +12,7 @@
  * - Runs of blank lines collapse to one.
  * Code (inline or fenced) is left exactly as written.
  */
+import { type Html } from "./html.js";
 export type ReplyChannel = "console" | "terminal" | "telegram" | "slack" | "discord" | "teams";
 export type ShapeOptions = {
     /** The owner's message this reply answers: when it asks for ids, the ids stay. */
@@ -61,7 +62,7 @@ export declare function replyPieces(shaped: string): ReplyPiece[];
 /** Discord's presentation syntax, escaped; mentions are broken so nothing pings. */
 export declare const discordPlain: (text: string) => string;
 /** One line of a shaped reply as console HTML (the console lays out paragraphs and lists itself). */
-export declare function replyHtmlInline(shapedLine: string): string;
+export declare function replyHtmlInline(shapedLine: string): Html;
 /** A shaped reply in a channel's own text format (Telegram's formatting rides entities: see `telegramReply`). */
 export declare function renderReply(shaped: string, channel: ReplyChannel): string;
 export type TelegramEntity = {

package/dist/reply-shape.js

@@ -12,6 +12,7 @@
  * - Runs of blank lines collapse to one.
  * Code (inline or fenced) is left exactly as written.
  */
+import { html, joinHtml } from "./html.js";
 export const BOLD_ANCHORS = 3;
 /** A bold anchor is a few words, not a sentence. */
 export const BOLD_ANCHOR_CHARS = 40;
@@ -293,17 +294,16 @@ export function replyPieces(shaped) {
         pieces.push({ kind: "text", text: shaped.slice(at) });
     return pieces;
 }
-const html = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
 const slack = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
 /** Discord's presentation syntax, escaped; mentions are broken so nothing pings. */
 export const discordPlain = (text) => text.replace(/([\\`*_~|>#\[\]])/g, "\\$1").replace(/@/g, "@\u200b");
 const teams = (value) => value.replace(/([\\`*_\[\]<>#])/g, "\\$1");
 /** One line of a shaped reply as console HTML (the console lays out paragraphs and lists itself). */
 export function replyHtmlInline(shapedLine) {
-    return replyPieces(shapedLine).map(piece => piece.kind === "text" ? html(piece.text)
-        : piece.kind === "bold" ? `<strong>${html(piece.text)}</strong>`
-            : piece.kind === "code" ? `<code>${html(piece.text)}</code>`
-                : `<a href="${html(piece.url)}" rel="noopener noreferrer" target="_blank">${html(piece.label)}</a>`).join("");
+    return joinHtml(replyPieces(shapedLine).map(piece => piece.kind === "text" ? piece.text
+        : piece.kind === "bold" ? html `<strong>${piece.text}</strong>`
+            : piece.kind === "code" ? html `<code>${piece.text}</code>`
+                : html `<a href="${piece.url}" rel="noopener noreferrer" target="_blank">${piece.label}</a>`));
 }
 /** A shaped reply in a channel's own text format (Telegram's formatting rides entities: see `telegramReply`). */
 export function renderReply(shaped, channel) {

package/dist/repository-context-ui.d.ts

@@ -1,2 +1,3 @@
+import { type Html } from "./html.js";
 import type { RepositoryContext } from './repository-context.js';
-export declare function repositoryContextHtml(repo: string, query: string, result: RepositoryContext | null, csrf: string): string;
+export declare function repositoryContextHtml(repo: string, query: string, result: RepositoryContext | null, csrf: string): Html;

package/dist/repository-context-ui.js

@@ -1,10 +1,5 @@
-const escape = (value) => value.replace(/[&<>"']/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[char]);
+import { html, postForm } from "./html.js";
 export function repositoryContextHtml(repo, query, result, csrf) {
     const root = `/settings/knowledge?repo=${encodeURIComponent(repo)}`;
-    return `<section class="knowledge repository-context"><h2>Relevant code</h2><form method="get" action="/settings/knowledge"><input type="hidden" name="repo" value="${escape(repo)}"><label>Find code<input name="q" value="${escape(query)}" maxlength="1000" placeholder="A feature, file or symbol"></label><button type="submit">Search</button></form>` +
-        (result === null ? '' : `<p class="meta">${result.index.engine === 'typescript-ast' ? 'Code relationships' : 'Source search'}${result.mode === 'impact' ? ' · possible change impact' : ''}</p>` +
-            (result.excerpts.length ? result.excerpts.map(one => `<details><summary>${escape(one.file)}:${one.line}${one.symbol ? ` · ${escape(one.symbol)}` : ''}</summary><p class="meta">${escape(one.reason)}</p><pre>${escape(one.text)}</pre><a href="${root}&mode=impact&q=${encodeURIComponent(one.file)}">What this may affect</a></details>`).join('') : '<p>No matching source was found in this bounded search.</p>') +
-            (result.relationships.length ? `<details><summary>Related files</summary><ul>${result.relationships.map(one => `<li>${escape(one.from)} → ${escape(one.to)} · ${escape(one.kind)}</li>`).join('')}</ul></details>` : '') +
-            `<details><summary>Context details</summary><p>${escape(result.index.status)}${result.checkout ? ` · checkout ${escape(result.checkout.head.slice(0, 8))}` : ''}</p>${result.warnings.map(one => `<p>${escape(one)}</p>`).join('')}</details>`) +
-        (csrf ? `<details><summary>Refresh code index</summary><form method="post" action="/settings/knowledge/refresh"><input type="hidden" name="csrf" value="${escape(csrf)}"><input type="hidden" name="repo" value="${escape(repo)}"><p>Builds a local map of TypeScript and JavaScript imports. Uses no model.</p><button type="submit">Refresh index</button></form></details>` : '') + `</section>`;
+    return html `<section class="knowledge repository-context"><h2>Relevant code</h2><form method="get" action="/settings/knowledge"><input type="hidden" name="repo" value="${repo}"><label>Find code<input name="q" value="${query}" maxlength="1000" placeholder="A feature, file or symbol"></label><button type="submit">Search</button></form>${result === null ? '' : html `<p class="meta">${result.index.engine === 'typescript-ast' ? 'Code relationships' : 'Source search'}${result.mode === 'impact' ? ' · possible change impact' : ''}</p>${result.excerpts.length ? result.excerpts.map(one => html `<details><summary>${one.file}:${one.line}${one.symbol ? ` · ${one.symbol}` : ''}</summary><p class="meta">${one.reason}</p><pre>${one.text}</pre><a href="${root}&mode=impact&q=${encodeURIComponent(one.file)}">What this may affect</a></details>`) : html `<p>No matching source was found in this bounded search.</p>`}${result.relationships.length ? html `<details><summary>Related files</summary><ul>${result.relationships.map(one => html `<li>${one.from} → ${one.to} · ${one.kind}</li>`)}</ul></details>` : ''}<details><summary>Context details</summary><p>${result.index.status}${result.checkout ? ` · checkout ${result.checkout.head.slice(0, 8)}` : ''}</p>${result.warnings.map(one => html `<p>${one}</p>`)}</details>`}${csrf ? html `<details><summary>Refresh code index</summary>${postForm("/settings/knowledge/refresh", html `<p>Builds a local map of TypeScript and JavaScript imports. Uses no model.</p><button type="submit">Refresh index</button>`, { hidden: { repo } })}</details>` : ''}</section>`;
 }

package/dist/request-budget-ui.d.ts

@@ -4,8 +4,9 @@
  * password (or a fresh identity-provider sign-in), in a browser only.
  */
 import type { ApiTokenRow, Database } from "./store.js";
+import { type Html } from "./html.js";
 export declare const REQUEST_LIMITS_CSS: string;
 /** "120 requests a minute · 10,000 a day" for one token's line. */
 export declare function tokenLimitWords(db: Database, token: ApiTokenRow): string;
 /** The operator's disclosure: everyone's tokens, or one token. Blank fields use the default shown. */
-export declare function requestLimitsHtml(db: Database, tokens: readonly ApiTokenRow[], csrf: string, now: number): string;
+export declare function requestLimitsHtml(db: Database, tokens: readonly ApiTokenRow[], now: number): Html;