toolroll 0.9.54 → 0.9.56

package/dist/release-adapters.js

@@ -0,0 +1,435 @@
+/**
+ * The world `toolroll release` acts on (release.ts): the gate checkout through git, GitHub through the signed-in `gh`,
+ * the npm registry over HTTPS, the installed Toolroll through its own CLI (`--json`) and launchd definitions, and the
+ * Homebrew tap through `gh`. Each call is bounded; none asks for or stores a credential — `gh`, npm and Toolroll use
+ * the sign-ins this machine already has.
+ */
+import { execFile, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, delimiter, dirname, join } from "node:path";
+import { createRequire } from "node:module";
+// Loaded on first use, like the store: a static import prints Node's SQLite warning before the CLI can quiet it.
+const sqlite = () => createRequire(import.meta.url)("node:sqlite");
+import { activeUpdateWork } from "./desktop-update-gate.js";
+import { BEFORE_SWAP, gateOwner } from "./release-gate.js";
+import { findCliLinks, switchCliLinks } from "./release-links.js";
+import { databasePath } from "./store.js";
+/** A child process, its output kept whole; a missing program or a time limit is exit 127 or 124, never a throw. */
+export const exec = (command, args, options = {}) => new Promise(done => {
+    execFile(command, [...args], { cwd: options.cwd, env: options.env ?? process.env, timeout: options.timeoutMs ?? 120_000, maxBuffer: 64 * 1024 * 1024, encoding: "utf8" }, (error, stdout, stderr) => {
+        const failure = error;
+        const code = failure === null ? 0 : failure.code === "ENOENT" ? 127 : failure.killed === true ? 124 : typeof failure.code === "number" ? failure.code : 1;
+        done({ code, stdout: String(stdout ?? ""), stderr: String(stderr ?? "") });
+    });
+});
+/** Without NODE_OPTIONS, which a test runner or debugger may have left for this process. */
+const cleanEnv = (extra = {}) => {
+    const env = { ...process.env, ...extra };
+    delete env["NODE_OPTIONS"];
+    return env;
+};
+const must = async (run, what) => {
+    const result = await run;
+    if (result.code !== 0)
+        throw new Error(`${what} failed (exit ${result.code}): ${(result.stderr || result.stdout).trim().split("\n").slice(-3).join(" ")}`);
+    return result.stdout;
+};
+/** owner/name from an https or ssh GitHub remote. */
+export function githubSlug(url) {
+    const match = /github\.com[:/]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/.exec(url.trim());
+    return match === null ? null : `${match[1]}/${match[2]}`;
+}
+/** The runtime (a `dist` folder, resolved) each launchd service of Toolroll runs: its definition names `<dist>/cli.js`. */
+export function serviceRuntimes(agents = join(homedir(), "Library", "LaunchAgents")) {
+    let names = [];
+    try {
+        names = readdirSync(agents).filter(one => /^com\.(toolroll|standing-orders)\..+\.plist$/.test(one));
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const name of names) {
+        const text = readFileSync(join(agents, name), "utf8");
+        for (const match of text.matchAll(/<string>([^<]*\/dist)\/cli\.js<\/string>/g))
+            found.push(resolved(match[1]));
+    }
+    return [...new Set(found)];
+}
+/** The runtime each CLI name resolves to on PATH: the `dist` folder its `bin.js` sits in, or null when not linked there. */
+export function cliRuntimes(path = process.env["PATH"] ?? "", names = ["toolroll", "standing-orders"]) {
+    return names.map(name => {
+        for (const dir of path.split(delimiter).filter(Boolean)) {
+            const candidate = join(dir, name);
+            if (!existsSync(candidate))
+                continue;
+            const real = resolved(candidate);
+            return { name, runtime: basename(real) === "bin.js" && basename(dirname(real)) === "dist" ? dirname(real) : null };
+        }
+        return { name, runtime: null };
+    });
+}
+const resolved = (path) => { try {
+    return realpathSync(path);
+}
+catch {
+    return path;
+} };
+const object = (value) => (value !== null && typeof value === "object" && !Array.isArray(value) ? value : {});
+const textOr = (value) => (typeof value === "string" && value !== "" ? value : null);
+/** `task show --json`, read as the release needs it. */
+export function gateStateOf(answer, accounts = []) {
+    if (answer["ok"] !== true)
+        return { exists: false, candidate: null, scopeDigest: null, approval: null, result: null, failed: null, completion: null };
+    const scope = object(answer["scope"]);
+    const assignment = object(answer["assignment"]);
+    const result = object(assignment["result"]);
+    const checks = object(result["checks"]);
+    const runs = Array.isArray(answer["runs"]) ? answer["runs"].map(object) : [];
+    const builders = runs.filter(run => run["role"] === "builder");
+    const newest = builders.sort((a, b) => Number(b["id"]) - Number(a["id"]))[0];
+    const resultRun = typeof result["runId"] === "number" ? result["runId"] : null;
+    const completion = object(assignment["completion"]);
+    const approvedAt = textOr(scope["approvedAt"]), approvedBy = textOr(scope["approvedBy"]), approvedDigest = textOr(scope["approvedDigest"]);
+    const account = accounts.map(object).find(one => one["name"] === approvedBy);
+    // A newer finished build than the result, with no result of its own, failed before its check could seal one.
+    const failed = newest !== undefined && newest["finishedAt"] != null && newest["outcome"] !== "built" && newest["outcome"] !== "no-change" && Number(newest["id"]) !== resultRun
+        ? `run ${String(newest["id"])} ended ${String(newest["outcome"] ?? "without an outcome")}` : null;
+    const worktree = runs.find(run => run["id"] === resultRun)?.["worktree"];
+    return {
+        exists: true,
+        candidate: textOr(scope["candidate"]),
+        scopeDigest: textOr(scope["digest"]),
+        approval: approvedAt === null || approvedBy === null || approvedDigest === null ? null : {
+            by: approvedBy, at: approvedAt, digest: approvedDigest, basis: textOr(scope["approvalBasis"]),
+            role: textOr(account?.["role"]), active: account?.["revokedAt"] === null,
+        },
+        result: resultRun === null || textOr(result["digest"]) === null ? null : {
+            run: resultRun, head: textOr(result["head"]), receipt: String(result["digest"]), worktree: textOr(worktree),
+            level: textOr(checks["level"]),
+            check: textOr(checks["running"]) !== null ? "running"
+                : checks["status"] === "passed" && checks["level"] !== "full" ? "not-full" : String(checks["status"] ?? "not-run"),
+        },
+        failed,
+        completion: textOr(completion["digest"]) === null ? null : { actor: String(completion["actor"]), at: String(completion["at"]), digest: String(completion["digest"]) },
+    };
+}
+/** Every process on this machine (`ps`): pid and full command line. */
+export function processes() {
+    const listed = spawnSync("/bin/ps", ["-axww", "-o", "pid=,command="], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    if (listed.status !== 0)
+        throw new Error(`ps failed: ${listed.stderr.trim()}`);
+    return listed.stdout.split("\n").map(line => /^\s*(\d+)\s+(.*)$/.exec(line)).filter(match => match !== null).map(match => ({ pid: Number(match[1]), command: match[2] }));
+}
+/** The final line of deploy-browser's output that is a JSON object: its `runtime` (a dist folder), when it has one. */
+export function deployedRuntime(stdout) {
+    const last = stdout.trim().split("\n").reverse().find(line => line.startsWith("{"));
+    try {
+        const runtime = object(JSON.parse(last ?? ""))["runtime"];
+        return typeof runtime === "string" && /[\\/]dist$/.test(runtime) ? runtime : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** What a deployment's stage says about the update pause: its id and phase when the journal is before the swap and the
+ * live database's pause is that deployment's. `owner` reads the live pause's owner. */
+export function stageGate(stage, owner) {
+    let journal;
+    try {
+        journal = object(JSON.parse(readFileSync(join(stage, "deployment.json"), "utf8")));
+    }
+    catch {
+        return null;
+    }
+    const id = textOr(journal["id"]), phase = textOr(journal["phase"]);
+    return id !== null && phase !== null && BEFORE_SWAP.includes(phase) && owner() === id ? { id, phase } : null;
+}
+export function releaseAdapters(options) {
+    const run = options.run ?? exec;
+    const get = options.fetch ?? fetch;
+    const { checkout } = options;
+    const tap = options.tap ?? "ap9000/homebrew-toolroll";
+    const formula = options.formula ?? "Formula/toolroll.rb";
+    const git = (...args) => run("git", ["-C", checkout, ...args]);
+    const gh = (...args) => run("gh", args);
+    const ghJson = async (what, ...args) => JSON.parse(await must(gh(...args), what));
+    const toolroll = async (...args) => {
+        const result = await run("toolroll", [...args, "--json"], { env: cleanEnv(), timeoutMs: 120_000 });
+        try {
+            return object(JSON.parse(result.stdout));
+        }
+        catch {
+            throw new Error(`toolroll ${args[0]} ${args[1] ?? ""} answered no JSON (exit ${result.code}): ${(result.stderr || result.stdout).trim().slice(0, 300)}`);
+        }
+    };
+    const refused = (answer) => `${String(answer["message"] ?? answer["reason"] ?? "refused")}`;
+    const database = options.database ?? databasePath(process.env, homedir());
+    const liveOwner = () => {
+        if (!existsSync(database))
+            return null;
+        const db = new (sqlite().DatabaseSync)(database, { readOnly: true });
+        try {
+            return gateOwner(db);
+        }
+        finally {
+            db.close();
+        }
+    };
+    const tail = (result) => (result.stderr || result.stdout).trim().split("\n").slice(-4).join(" ") || `exit ${result.code}`;
+    /** A deployment that stopped: in words, with the pause it left when that pause is before the swap. */
+    const stopped = (stage, message) => {
+        const gate = stageGate(stage, liveOwner);
+        return gate === null ? { ok: false, message } : { ok: false, message, gate };
+    };
+    const deployScript = (worktree, stage, runId, extra) => run(process.execPath, ["scripts/deploy-browser.mjs", "--run", String(runId), "--stage", stage, ...extra], {
+        cwd: worktree, env: cleanEnv({ TMPDIR: resolved(process.env["TMPDIR"] ?? "/tmp") }), timeoutMs: (options.deployMinutes ?? 30) * 60_000,
+    });
+    return {
+        now: options.now ?? (() => new Date()),
+        sleep: options.sleep ?? (ms => new Promise(done => setTimeout(done, ms))),
+        say: options.say ?? (line => process.stdout.write(`${line}\n`)),
+        repo: {
+            async github() {
+                const slug = githubSlug(await must(git("remote", "get-url", "origin"), "git remote get-url origin"));
+                if (slug === null)
+                    throw new Error(`${checkout}'s origin is not a GitHub repository`);
+                return slug;
+            },
+            async sync(branch) {
+                await must(git("fetch", "--quiet", "origin", "+refs/heads/main:refs/remotes/origin/main"), "git fetch origin main");
+                // A merged branch may be gone from GitHub; its commit is already here.
+                await git("fetch", "--quiet", "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`);
+                const current = (await git("symbolic-ref", "--quiet", "--short", "HEAD")).stdout.trim();
+                if (current === "main") {
+                    await must(git("merge", "--ff-only", "--quiet", "origin/main"), "git merge --ff-only origin/main");
+                    return;
+                }
+                const local = (await git("rev-parse", "--verify", "--quiet", "refs/heads/main")).stdout.trim();
+                if (local === "" || (await git("merge-base", "--is-ancestor", local, "origin/main")).code === 0) {
+                    await must(git("update-ref", "refs/heads/main", "origin/main", ...(local === "" ? [] : [local])), "git update-ref main");
+                }
+                else
+                    throw new Error(`${checkout}'s local main has commits origin/main doesn't; the gate diffs from it, so fix it first`);
+            },
+            async remoteHead(branch) {
+                const out = await must(git("ls-remote", "origin", `refs/heads/${branch}`), "git ls-remote");
+                return out.trim().split(/\s+/)[0] || null;
+            },
+            async deleteBranch(branch, head) {
+                const ref = `refs/heads/${branch}`;
+                const current = (await must(git("ls-remote", "origin", ref), "git ls-remote")).trim().split(/\s+/)[0] || null;
+                if (current === null)
+                    return;
+                if (current !== head)
+                    throw new Error(`${branch} moved after merging; its new head was not deleted.`);
+                await must(git("push", `--force-with-lease=${ref}:${head}`, "origin", `:${ref}`), `deleting merged branch ${branch}`);
+            },
+            async tree(sha) { return (await must(git("rev-parse", `${sha}^{tree}`), `git rev-parse ${sha.slice(0, 7)}^{tree}`)).trim(); },
+            async fileAt(sha, path) {
+                const result = await git("show", `${sha}:${path}`);
+                return result.code === 0 ? result.stdout : null;
+            },
+            async mainHead() { return (await must(git("rev-parse", "refs/remotes/origin/main"), "git rev-parse origin/main")).trim(); },
+            async contains(sha, ancestor) { return (await git("merge-base", "--is-ancestor", ancestor, sha)).code === 0; },
+        },
+        toolroll: {
+            async installed() { return { services: serviceRuntimes(), clis: cliRuntimes() }; },
+            async runtimeCommit(runtime) {
+                // deploy-browser writes this beside node_modules, not in the package's own manifest (whose version can repeat).
+                try {
+                    const candidate = object(JSON.parse(readFileSync(join(runtime, "..", "..", "..", "package.json"), "utf8")))["candidate"];
+                    return typeof candidate === "string" && /^[0-9a-f]{40}$/.test(candidate) ? candidate : null;
+                }
+                catch {
+                    return null;
+                }
+            },
+            async gate(taskId) {
+                const answer = await toolroll("task", "show", taskId);
+                if (textOr(object(answer["scope"])["approvedBy"]) === null)
+                    return gateStateOf(answer);
+                const people = await toolroll("people", "list");
+                if (people["ok"] !== true || !Array.isArray(people["accounts"]))
+                    throw new Error(`Cannot verify the release approver: ${refused(people)}`);
+                return gateStateOf(answer, people["accounts"]);
+            },
+            async fileGate(input) {
+                const added = await toolroll("task", "add", input.title, "--id", input.taskId, "--repo", input.checkout, "--checks", "full");
+                if (added["ok"] !== true)
+                    throw new Error(`task add: ${refused(added)}`);
+                const scoped = await toolroll("task", "scope", input.taskId, "--candidate", input.candidate, "--goal", input.goal, "--acceptance", input.acceptance);
+                if (scoped["ok"] !== true)
+                    throw new Error(`task scope: ${refused(scoped)}`);
+                const digest = gateStateOf(await toolroll("task", "show", input.taskId)).scopeDigest;
+                if (digest === null)
+                    throw new Error(`task ${input.taskId} has no scope after filing it`);
+                return { scopeDigest: digest };
+            },
+            async complete(taskId, receipt) {
+                const answer = await toolroll("task", "complete", taskId, "--digest", receipt);
+                return answer["ok"] === true ? { ok: true } : { ok: false, message: refused(answer) };
+            },
+            async busy() {
+                const db = new (sqlite().DatabaseSync)(database, { readOnly: true });
+                try {
+                    // Match the deploy guard, including unfinished runs whose claim is gone. Keep one read snapshot.
+                    db.exec("BEGIN");
+                    const work = activeUpdateWork(db);
+                    const tasks = db.prepare(`SELECT DISTINCT external_id FROM task_ref WHERE id IN (
+            SELECT task_ref FROM run WHERE outcome IS NULL
+            UNION SELECT task_ref FROM claim WHERE released_at IS NULL
+            UNION SELECT task_ref FROM run_stop WHERE settled_at IS NULL
+          ) ORDER BY external_id`).all().map(row => String(row["external_id"]));
+                    db.exec("COMMIT");
+                    return { running: Object.values(work).reduce((total, count) => total + count, 0), tasks };
+                }
+                finally {
+                    db.close();
+                }
+            },
+            async deploy({ run: runId, worktree, stage }) {
+                // The candidate's own deployment, from its own checkout: drain, backup, rehearsal, swap, health. Its last JSON
+                // line names the runtime it installed; the CLI names are moved to it by the release's link step.
+                const result = await deployScript(worktree, stage, runId, ["--yes"]);
+                const runtime = deployedRuntime(result.stdout);
+                if (result.code !== 0 || runtime === null)
+                    return stopped(stage, tail(result));
+                return { ok: true, runtime };
+            },
+            async recoverDeploy({ run: runId, worktree, stage }) {
+                // Before prepare saves deployment.json, staging has not touched the service or admission gate.
+                if (!existsSync(join(stage, "deployment.json")))
+                    return { ok: true };
+                // A deployment that outlived a killed release is still at work: recovering under it would race it.
+                const running = (options.processes ?? processes)().filter(one => one.command.includes("deploy-browser.mjs") && one.command.includes(stage));
+                if (running.length > 0)
+                    return { ok: false, message: `the deployment is still running (process ${running.map(one => one.pid).join(", ")}); let it finish, then rerun` };
+                const result = await deployScript(worktree, stage, runId, ["--phase", "recover"]);
+                if (result.code === 0)
+                    return { ok: true };
+                // Killed while preparing, before it paused anything: nothing to undo (its journal is kept).
+                const journal = (() => { try {
+                    return object(JSON.parse(readFileSync(join(stage, "deployment.json"), "utf8")));
+                }
+                catch {
+                    return {};
+                } })();
+                if (journal["phase"] === "preparing" && liveOwner() !== journal["id"])
+                    return { ok: true };
+                return stopped(stage, `${tail(result)} (the deployment journal is at ${String(journal["phase"] ?? "an unreadable phase")}; ${join(stage, "deployment.json")})`);
+            },
+            async cliLinks() { return findCliLinks(); },
+            async switchLinks(links, bin, version) {
+                const answers = (path) => spawnSync(path, ["--version"], { encoding: "utf8", env: cleanEnv(), timeout: 30_000 }).stdout?.trim() === version;
+                switchCliLinks(links, bin, answers);
+            },
+        },
+        github: {
+            async authenticated() { return (await gh("auth", "status")).code === 0; },
+            async pullRequest(repo, branch) {
+                const rows = (await ghJson("gh pr list", "pr", "list", "--repo", repo, "--head", branch, "--state", "all", "--limit", "10", "--json", "number,state,headRefOid,baseRefName,mergeCommit"));
+                const prs = rows.map(row => ({
+                    number: Number(row["number"]), state: row["state"] === "MERGED" ? "merged" : row["state"] === "OPEN" ? "open" : "closed",
+                    head: String(row["headRefOid"]), base: String(row["baseRefName"]), mergeCommit: textOr(object(row["mergeCommit"])["oid"]),
+                }));
+                return prs.find(one => one.state === "open") ?? prs.filter(one => one.state === "merged").sort((a, b) => b.number - a.number)[0] ?? null;
+            },
+            async checks(repo, sha) {
+                const out = await must(gh("api", "--paginate", `repos/${repo}/commits/${sha}/check-runs?per_page=100`, "--jq", ".check_runs[] | {id, name, status, conclusion}"), "gh api check-runs");
+                const runs = out.split("\n").filter(Boolean).map(line => object(JSON.parse(line)));
+                // Oldest first, so a rerun's attempt is the last one listed for its name.
+                return runs.sort((a, b) => Number(a["id"]) - Number(b["id"])).map((one) => ({ name: String(one["name"]), status: String(one["status"]), conclusion: textOr(one["conclusion"]) }));
+            },
+            async merge(repo, pr, head) {
+                const merged = object(await ghJson("gh api pulls merge", "api", "-X", "PUT", `repos/${repo}/pulls/${pr}/merge`, "-f", "merge_method=squash", "-f", `sha=${head}`));
+                if (typeof merged["sha"] !== "string")
+                    throw new Error(`GitHub did not merge #${pr}: ${String(merged["message"] ?? "no merge commit")}`);
+                return merged["sha"];
+            },
+            async tag(repo, tag) {
+                const result = await gh("api", `repos/${repo}/git/ref/tags/${tag}`);
+                if (result.code !== 0) {
+                    if (/Not Found|HTTP 404/.test(result.stderr + result.stdout))
+                        return null;
+                    throw new Error(`gh api git/ref/tags/${tag} failed: ${result.stderr.trim()}`);
+                }
+                const target = object(object(JSON.parse(result.stdout))["object"]);
+                if (target["type"] !== "tag")
+                    return String(target["sha"]);
+                // An annotated tag: the commit it names.
+                return String(object(object(await ghJson("gh api git/tags", "api", `repos/${repo}/git/tags/${String(target["sha"])}`))["object"])["sha"]);
+            },
+            async createTag(repo, tag, sha) {
+                await must(gh("api", "-X", "POST", `repos/${repo}/git/refs`, "-f", `ref=refs/tags/${tag}`, "-f", `sha=${sha}`), `creating ${tag}`);
+            },
+            async release(repo, tag) { return (await gh("release", "view", tag, "--repo", repo, "--json", "tagName")).code === 0; },
+        },
+        registry: {
+            async published(name, version) {
+                const response = await get(`https://registry.npmjs.org/${encodeURIComponent(name)}/${encodeURIComponent(version)}`, { signal: AbortSignal.timeout(20_000) });
+                if (response.status === 404)
+                    return false;
+                if (!response.ok)
+                    throw new Error(`the npm registry answered ${response.status} for ${name}@${version}`);
+                return object(await response.json())["version"] === version;
+            },
+        },
+        homebrew: {
+            repo: tap,
+            async state(version) {
+                const branch = await defaultBranch();
+                const current = await formulaAt(branch);
+                if (current.text.includes(`-${version}.tgz`))
+                    return { kind: "current" };
+                const open = (await ghJson("gh pr list", "pr", "list", "--repo", tap, "--head", brewBranch(version), "--state", "open", "--json", "number,headRefOid"));
+                const pr = open[0];
+                return pr === undefined ? { kind: "missing" } : { kind: "proposed", pr: Number(pr["number"]), head: String(pr["headRefOid"]) };
+            },
+            async propose(version) {
+                const tarball = `https://registry.npmjs.org/toolroll/-/toolroll-${version}.tgz`;
+                const response = await get(tarball, { signal: AbortSignal.timeout(60_000) });
+                if (!response.ok)
+                    throw new Error(`downloading ${tarball} answered ${response.status}`);
+                const sha256 = createHash("sha256").update(Buffer.from(await response.arrayBuffer())).digest("hex");
+                const base = await defaultBranch();
+                const current = await formulaAt(base);
+                const next = bumpFormula(current.text, tarball, sha256);
+                const branch = brewBranch(version);
+                const baseSha = String(object(object(await ghJson("gh api git/ref", "api", `repos/${tap}/git/ref/heads/${base}`))["object"])["sha"]);
+                // A branch left by an earlier attempt is reused.
+                const made = await gh("api", "-X", "POST", `repos/${tap}/git/refs`, "-f", `ref=refs/heads/${branch}`, "-f", `sha=${baseSha}`);
+                if (made.code !== 0 && !/Reference already exists/.test(made.stderr + made.stdout))
+                    throw new Error(`creating ${tap} ${branch}: ${made.stderr.trim()}`);
+                const onBranch = await formulaAt(branch);
+                if (onBranch.text !== next) {
+                    await must(gh("api", "-X", "PUT", `repos/${tap}/contents/${formula}`, "-f", `message=toolroll ${version}`, "-f", `branch=${branch}`, "-f", `sha=${onBranch.sha}`, "-f", `content=${Buffer.from(next).toString("base64")}`), `updating ${formula}`);
+                }
+                await must(gh("pr", "create", "--repo", tap, "--head", branch, "--base", base, "--title", `toolroll ${version}`, "--body", `Bumps the formula to toolroll ${version} (${tarball}, sha256 ${sha256}).`), "gh pr create");
+                const opened = (await ghJson("gh pr view", "pr", "view", branch, "--repo", tap, "--json", "number,headRefOid"));
+                return { pr: Number(opened["number"]), head: String(opened["headRefOid"]) };
+            },
+            async merge(pr, head) {
+                const merged = object(await ghJson(`merging ${tap} #${pr}`, "api", "-X", "PUT", `repos/${tap}/pulls/${pr}/merge`, "-f", "merge_method=squash", "-f", `sha=${head}`));
+                if (merged["merged"] !== true || typeof merged["sha"] !== "string")
+                    throw new Error(`GitHub did not merge ${tap} #${pr}: ${String(merged["message"] ?? "no merge commit")}`);
+            },
+        },
+    };
+    async function defaultBranch() {
+        return (await must(gh("api", `repos/${tap}`, "--jq", ".default_branch"), `gh api repos/${tap}`)).trim();
+    }
+    async function formulaAt(ref) {
+        const file = object(await ghJson(`reading ${formula}`, "api", `repos/${tap}/contents/${formula}?ref=${encodeURIComponent(ref)}`));
+        return { text: Buffer.from(String(file["content"] ?? ""), "base64").toString("utf8"), sha: String(file["sha"]) };
+    }
+}
+const brewBranch = (version) => `toolroll-${version}`;
+/** The formula with its first `url` and `sha256` replaced; anything else is left exactly as it was. */
+export function bumpFormula(text, url, sha256) {
+    if (!/^\s*url "[^"]*"/m.test(text) || !/^\s*sha256 "[0-9a-f]{64}"/m.test(text))
+        throw new Error("the formula has no url and sha256 lines to update");
+    return text.replace(/^(\s*url ")[^"]*(")/m, `$1${url}$2`).replace(/^(\s*sha256 ")[0-9a-f]{64}(")/m, `$1${sha256}$2`);
+}

package/dist/release-cli.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `toolroll release <branch>` (release.ts): the command line around the release coordinator.
+ *
+ * `release <lease>` used to return a runner's lease; that is `toolroll worker release <lease>` now. The old form still
+ * works for a value shaped like a lease id (a UUID), with a one-line warning, until the next minor version. A
+ * UUID-shaped value given with release options is refused rather than guessed at.
+ */
+import { type ReleaseAdapters } from "./release.js";
+import { type GateReleaseWorld } from "./release-gate.js";
+export declare const RELEASE_HELP: string;
+/** A runner lease id (claim.ts mints randomUUID()). */
+export declare const LEASE_SHAPED: RegExp;
+export declare const LEASE_DEPRECATION = "`toolroll release <lease>` is now `toolroll worker release <lease>`; the old form goes in the next minor version.";
+export type ReleaseCliDeps = {
+    adapters?: ReleaseAdapters;
+    stateDir?: string;
+    cwd?: string;
+    /** The deprecated lease form, handed to the worker command. */
+    releaseLease?: (args: readonly string[]) => Promise<number>;
+    warn?: (line: string) => void;
+    /** What --release-gate reads and changes (release-gate.ts); the installation's own by default. */
+    gateWorld?: GateReleaseWorld;
+};
+export declare function runReleaseCommand(args: readonly string[], write: (line: string) => void, deps?: ReleaseCliDeps): Promise<number>;

package/dist/release-cli.js

@@ -0,0 +1,181 @@
+/**
+ * `toolroll release <branch>` (release.ts): the command line around the release coordinator.
+ *
+ * `release <lease>` used to return a runner's lease; that is `toolroll worker release <lease>` now. The old form still
+ * works for a value shaped like a lease id (a UUID), with a one-line warning, until the next minor version. A
+ * UUID-shaped value given with release options is refused rather than guessed at.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { createRequire } from "node:module";
+// Loaded on first use, like the store: a static import prints Node's SQLite warning before the CLI can quiet it.
+const sqlite = () => createRequire(import.meta.url)("node:sqlite");
+import { checkedEnvelopeJson } from "./contracts/cli.js";
+import { RELEASE_LIMITS, runRelease } from "./release.js";
+import { processes, releaseAdapters } from "./release-adapters.js";
+import { releaseGate } from "./release-gate.js";
+import { databasePath } from "./store.js";
+export const RELEASE_HELP = `toolroll release <branch> — release Toolroll itself, from a pushed branch with an open pull request
+
+  Requires an active approver's scope approval (the only human step) and a passing Full check on the exact commit.
+  Completes that result, drains, backs up, deploys and relinks both CLI names to that commit. After PR checks pass,
+  squash-merges, deletes the matching remote branch, verifies the merged tree and tags. Both macOS legs gate npm
+  publication; Homebrew waits for its checks to register and all pass before merging.
+
+  Run the same command to resume after a stop. Interrupted deployments recover their saved stage before retrying.
+
+toolroll release --release-gate <id> [--yes] — lift the update pause a deployment left before its swap
+
+  Shows why it is safe first: the pause is that deployment's, its journal stopped before the swap, and the
+  database, service definition and running service are all still the previous build's. --yes lifts that one pause.
+  Any missing or contradicting evidence refuses and leaves the pause in place.
+
+Options
+  --repo <path>          the gate checkout the release check runs in (default: this checkout)
+  --new                  release a new commit on the branch, setting the earlier unfinished release aside
+  --limit <step>=<min>   change one step's time limit (${Object.entries(RELEASE_LIMITS).map(([step, minutes]) => `${step} ${minutes}`).join(", ")})
+  --tap <owner/name>     the Homebrew tap (default ap9000/homebrew-toolroll)
+  --release-gate <id>    check (and with --yes, lift) one update pause left before a deployment's swap
+  --yes                  with --release-gate: lift the pause once it is proved safe
+  --json                 answer with one machine envelope
+
+A runner's lease is returned with \`toolroll worker release <lease>\`.`;
+/** A runner lease id (claim.ts mints randomUUID()). */
+export const LEASE_SHAPED = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const LEASE_DEPRECATION = "`toolroll release <lease>` is now `toolroll worker release <lease>`; the old form goes in the next minor version.";
+const VALUE_FLAGS = new Set(["--repo", "--limit", "--tap", "--release-gate"]);
+const BARE_FLAGS = new Set(["--new", "--json", "--help", "--yes"]);
+export async function runReleaseCommand(args, write, deps = {}) {
+    const json = args.includes("--json");
+    const refuse = (reason, message, code) => {
+        write(json ? checkedEnvelopeJson({ ok: false, command: "release", reason, message }) : message);
+        return code;
+    };
+    const positional = [];
+    const limits = {};
+    let repo, tap, gate;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (BARE_FLAGS.has(arg))
+            continue;
+        if (VALUE_FLAGS.has(arg)) {
+            const value = args[i + 1];
+            if (value === undefined || value.startsWith("--"))
+                return refuse("usage", `${arg} takes a value.`, 2);
+            i += 1;
+            if (arg === "--repo")
+                repo = value;
+            else if (arg === "--tap")
+                tap = value;
+            else if (arg === "--release-gate")
+                gate = value;
+            else {
+                const match = /^([a-z]+)=([0-9]+)$/.exec(value);
+                if (match === null || !(match[1] in RELEASE_LIMITS) || Number(match[2]) < 1)
+                    return refuse("usage", `--limit takes <step>=<minutes> for one of: ${Object.keys(RELEASE_LIMITS).join(", ")}.`, 2);
+                limits[match[1]] = Number(match[2]);
+            }
+            continue;
+        }
+        if (arg.startsWith("--"))
+            return refuse("usage", `Unknown option ${arg}.\n${RELEASE_HELP}`, 2);
+        positional.push(arg);
+    }
+    if (args.includes("--help")) {
+        write(RELEASE_HELP);
+        return 0;
+    }
+    if (gate !== undefined) {
+        if (positional.length > 0 || args.some(arg => ["--repo", "--limit", "--tap", "--new"].includes(arg)))
+            return refuse("usage", "--release-gate <id> takes no branch or release options.", 2);
+        return runGateRelease(gate, args.includes("--yes"), write, json, deps.gateWorld ?? installedGateWorld());
+    }
+    if (args.includes("--yes"))
+        return refuse("usage", "--yes goes with --release-gate <id>; a release needs no confirmation beyond the owner's approval.", 2);
+    if (positional.length !== 1)
+        return refuse("usage", `Which branch? \`toolroll release <branch>\`.\n${RELEASE_HELP}`, 2);
+    const branch = positional[0];
+    if (LEASE_SHAPED.test(branch)) {
+        const releaseOptions = args.filter(arg => VALUE_FLAGS.has(arg) || arg === "--new");
+        if (releaseOptions.length > 0)
+            return refuse("ambiguous", `${branch} looks like a lease id, but ${releaseOptions[0]} is a release option. Return a lease with \`toolroll worker release <lease>\`; a branch shaped like a lease id can't be released.`, 2);
+        (deps.warn ?? (line => process.stderr.write(`${line}\n`)))(LEASE_DEPRECATION);
+        if (deps.releaseLease === undefined)
+            return refuse("usage", "This build can't return leases from here: use `toolroll worker release <lease>`.", 2);
+        return deps.releaseLease(args);
+    }
+    if (!/^[A-Za-z0-9._/-]+$/.test(branch) || branch.startsWith("-") || branch.includes(".."))
+        return refuse("usage", `${branch} is not a branch name this command takes.`, 2);
+    const checkout = resolve(deps.cwd ?? process.cwd(), repo ?? ".");
+    const stateDir = deps.stateDir ?? dirname(databasePath(process.env, homedir()));
+    const lines = [];
+    const say = (line) => { if (json)
+        lines.push(line);
+    else
+        write(line); };
+    const adapters = deps.adapters === undefined
+        ? releaseAdapters({ checkout, say, ...(tap === undefined ? {} : { tap }), ...(limits["deploy"] === undefined ? {} : { deployMinutes: limits["deploy"] }) })
+        : { ...deps.adapters, say };
+    const outcome = await runRelease({ branch, checkout, stateDir, limits, fresh: args.includes("--new") }, adapters);
+    return report(outcome, write, json, lines);
+}
+function report(outcome, write, json, lines) {
+    const release = outcome.journal === null ? null : {
+        branch: outcome.journal.branch, candidate: outcome.journal.candidate.sha, tree: outcome.journal.candidate.tree, version: outcome.journal.packageVersion,
+        tag: outcome.journal.tag, pullRequest: outcome.journal.pr, task: outcome.journal.task.id, step: outcome.journal.step,
+        merge: outcome.journal.merge?.sha ?? null, runtime: outcome.journal.deploy?.runtime ?? null,
+    };
+    if (outcome.ok) {
+        if (json)
+            write(checkedEnvelopeJson({ ok: true, command: "release", release, journal: outcome.file, said: lines }));
+        return 0;
+    }
+    if (json) {
+        write(checkedEnvelopeJson({ ok: false, command: "release", reason: outcome.reason, message: outcome.message, step: outcome.step, release, journal: outcome.file, resume: outcome.resume, said: lines }));
+    }
+    else {
+        write(`✗ Stopped at ${outcome.step}: ${outcome.message}`);
+        write(`  Continue from there: ${outcome.resume}`);
+    }
+    // A usage slip or refusal before anything began is 2; a stop along the way is 3 ("no", not "broken"), as elsewhere.
+    return outcome.reason === "usage" ? 2 : 3;
+}
+/** The installation's live database, LaunchAgents and processes, for --release-gate. */
+function installedGateWorld() {
+    const database = databasePath(process.env, homedir());
+    const agents = join(homedir(), "Library", "LaunchAgents");
+    return {
+        database, stateDir: dirname(database), now: () => new Date(), processes,
+        open: () => {
+            const db = new (sqlite().DatabaseSync)(database);
+            db.exec("PRAGMA busy_timeout=5000");
+            return db;
+        },
+        servicePlists: () => ["com.toolroll.browser", "com.standing-orders.browser"].map(label => join(agents, `${label}.plist`))
+            .filter(path => existsSync(path)).map(path => ({ path, text: readFileSync(path, "utf8") })),
+    };
+}
+function runGateRelease(id, yes, write, json, world) {
+    let outcome;
+    try {
+        outcome = releaseGate(id, world, yes);
+    }
+    catch (error) {
+        outcome = { ok: false, reason: "error", message: `${error.message} The update pause was left as it is.` };
+    }
+    if (!outcome.ok) {
+        write(json ? checkedEnvelopeJson({ ok: false, command: "release", reason: outcome.reason, message: outcome.message }) : `✗ ${outcome.message}`);
+        return outcome.reason === "usage" ? 2 : 3;
+    }
+    if (json) {
+        write(checkedEnvelopeJson({ ok: true, command: "release", gate: { id: outcome.id, released: outcome.released, stage: outcome.stage, proof: outcome.proof } }));
+        return 0;
+    }
+    write(outcome.released ? `✓ Lifted update pause ${outcome.id}: new work can start again.` : `Update pause ${outcome.id} was left before its deployment's swap:`);
+    for (const line of outcome.proof)
+        write(`  • ${line}`);
+    if (!outcome.released)
+        write(`Lift it: toolroll release --release-gate ${outcome.id} --yes`);
+    return 0;
+}