toolroll 0.9.54 → 0.9.55

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;
+}

package/dist/release-gate.d.ts

@@ -0,0 +1,80 @@
+/**
+ * `toolroll release --release-gate <id>`: lift one update pause that a browser deployment (scripts/deploy-browser.mjs)
+ * left behind when it stopped before the swap and its own recovery could not tell. The typical case is a deployment
+ * killed between installing the pause and journaling that it had: the journal still says `preparing`, so
+ * `--phase recover` leaves the pause alone, and new work stays paused.
+ *
+ * The id alone proves nothing, and neither does the journal's phase. The pause is lifted only when every piece of
+ * evidence agrees that the service was never swapped:
+ *
+ *   - the live database's update pause is owned by exactly this id
+ *   - exactly one intact deployment journal names this id and this database, at a phase before the swap, with
+ *     nothing recorded that only the swap writes (stopping, migration, the new service), and no new service definition
+ *     staged
+ *   - the live database is still at the schema that journal recorded
+ *   - the service definition still names the runtime the journal started from (and is the one it saved), never the
+ *     staged one
+ *   - that runtime's service is running, nothing runs from the staged runtime, and no deployment is still running
+ *
+ * Anything missing, damaged or contradicting refuses and leaves the pause as it is. Without --yes it only shows the
+ * proof; with --yes it lifts that one pause (the owner is checked again inside the same write) and journals it.
+ */
+import type { Database } from "./store.js";
+/** The journal phases a deployment passes before it stops the old service (deploy-phases.mjs). */
+export declare const BEFORE_SWAP: readonly string[];
+export type GateReleaseWorld = {
+    /** The live database file. */
+    database: string;
+    /** The installation's state folder: deployments stage under staged-upgrades/ there. */
+    stateDir: string;
+    /** The live database, opened without migrating it. */
+    open(): Database;
+    /** The installed browser service definitions (LaunchAgents), path and text. */
+    servicePlists(): {
+        path: string;
+        text: string;
+    }[];
+    /** Every process on this machine: pid and full command line. */
+    processes(): {
+        pid: number;
+        command: string;
+    }[];
+    now(): Date;
+};
+type Journal = Record<string, unknown> & {
+    id: string;
+    phase: string;
+    database: string;
+    schema: number;
+    priorRuntime: string;
+    nextRuntime: string;
+};
+export type GateProof = {
+    ok: true;
+    id: string;
+    stage: string;
+    journal: Journal;
+    proof: string[];
+} | {
+    ok: false;
+    reason: string;
+    message: string;
+};
+/** The owner id written into the live pause's triggers, when there is one pause and it names one id. */
+export declare function gateOwner(db: Database): string | null;
+/** Whether the pause owned by `id` was left by a deployment that never began its swap, and the evidence that says so. */
+export declare function proveBeforeSwap(id: string, world: GateReleaseWorld): GateProof;
+export type GateReleaseOutcome = {
+    ok: true;
+    released: boolean;
+    id: string;
+    stage: string;
+    proof: string[];
+} | {
+    ok: false;
+    reason: string;
+    message: string;
+};
+/** Prove, then (with `yes`) lift exactly that pause and journal the release in the deployment's own journal. */
+export declare function releaseGate(id: string, world: GateReleaseWorld, yes: boolean): GateReleaseOutcome;
+export {};

package/dist/release-gate.js

@@ -0,0 +1,150 @@
+/**
+ * `toolroll release --release-gate <id>`: lift one update pause that a browser deployment (scripts/deploy-browser.mjs)
+ * left behind when it stopped before the swap and its own recovery could not tell. The typical case is a deployment
+ * killed between installing the pause and journaling that it had: the journal still says `preparing`, so
+ * `--phase recover` leaves the pause alone, and new work stays paused.
+ *
+ * The id alone proves nothing, and neither does the journal's phase. The pause is lifted only when every piece of
+ * evidence agrees that the service was never swapped:
+ *
+ *   - the live database's update pause is owned by exactly this id
+ *   - exactly one intact deployment journal names this id and this database, at a phase before the swap, with
+ *     nothing recorded that only the swap writes (stopping, migration, the new service), and no new service definition
+ *     staged
+ *   - the live database is still at the schema that journal recorded
+ *   - the service definition still names the runtime the journal started from (and is the one it saved), never the
+ *     staged one
+ *   - that runtime's service is running, nothing runs from the staged runtime, and no deployment is still running
+ *
+ * Anything missing, damaged or contradicting refuses and leaves the pause as it is. Without --yes it only shows the
+ * proof; with --yes it lifts that one pause (the owner is checked again inside the same write) and journals it.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { durableJson } from "./desktop-update.js";
+import { removeUpdateGate, updateGateOwned } from "./desktop-update-gate.js";
+/** The journal phases a deployment passes before it stops the old service (deploy-phases.mjs). */
+export const BEFORE_SWAP = Object.freeze(["preparing", "admission-paused", "frozen", "backup-verified", "rehearsed"]);
+/** Journal fields that only the swap and later phases write. */
+const SWAP_FIELDS = ["stoppingService", "codingBackupBeforeSwap", "migration", "newService", "deployedAt"];
+const GATE_ID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const refuse = (reason, message) => ({ ok: false, reason, message: `${message} The update pause was left as it is.` });
+/** The owner id written into the live pause's triggers, when there is one pause and it names one id. */
+export function gateOwner(db) {
+    const rows = db.prepare("SELECT sql FROM sqlite_master WHERE type='trigger' AND name GLOB 'so_desktop_update_*'").all();
+    const ids = new Set(rows.map(row => /\[([a-f0-9-]{36})\]'\)/.exec(String(row["sql"]))?.[1] ?? "?"));
+    return ids.size === 1 ? [...ids][0] : null;
+}
+/** Every deployment journal under staged-upgrades/: the stage it is in and what it holds, or why it can't be read. */
+function journals(stateDir) {
+    const root = join(stateDir, "staged-upgrades");
+    let stages = [];
+    try {
+        stages = readdirSync(root, { withFileTypes: true }).filter(one => one.isDirectory()).map(one => join(root, one.name));
+    }
+    catch {
+        return [];
+    }
+    return stages.filter(stage => existsSync(join(stage, "deployment.json"))).map(stage => {
+        try {
+            const parsed = JSON.parse(readFileSync(join(stage, "deployment.json"), "utf8"));
+            return { stage, journal: parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null };
+        }
+        catch {
+            return { stage, journal: null };
+        }
+    });
+}
+/** Whether the pause owned by `id` was left by a deployment that never began its swap, and the evidence that says so. */
+export function proveBeforeSwap(id, world) {
+    if (!GATE_ID.test(id))
+        return refuse("usage", `${id} is not an update id.`);
+    const proof = [];
+    let owner, owned, schema;
+    const db = world.open();
+    try {
+        owner = gateOwner(db);
+        owned = updateGateOwned(db, id);
+        schema = Number(db.prepare("SELECT version FROM schema_version").get()?.["version"]);
+    }
+    finally {
+        db.close();
+    }
+    if (owner === null)
+        return refuse("not-paused", "No single update pause is held on the live database.");
+    if (owner !== id || !owned)
+        return refuse("not-owner", `The live update pause belongs to ${owner}, not ${id}.`);
+    proof.push(`The live database's update pause belongs to ${id}.`);
+    const all = journals(world.stateDir);
+    const mine = all.filter(one => one.journal?.["id"] === id);
+    if (mine.length > 1)
+        return refuse("conflict", `${mine.length} deployment journals name ${id}: ${mine.map(one => one.stage).join(", ")}.`);
+    if (mine.length === 0) {
+        const damaged = all.filter(one => one.journal === null);
+        return refuse(damaged.length > 0 ? "damaged" : "no-journal", damaged.length > 0
+            ? `No readable deployment journal names ${id}, and ${damaged.map(one => join(one.stage, "deployment.json")).join(", ")} can't be read; it may be that deployment's.`
+            : `No deployment journal under ${join(world.stateDir, "staged-upgrades")} names ${id}; this pause was not left by a browser deployment.`);
+    }
+    const { stage, journal: raw } = mine[0];
+    const r = raw;
+    if (typeof r.phase !== "string" || typeof r.priorRuntime !== "string" || typeof r.nextRuntime !== "string" || typeof r.schema !== "number" || typeof r.database !== "string") {
+        return refuse("damaged", `${join(stage, "deployment.json")} is missing its phase, runtimes, schema or database.`);
+    }
+    if (r.database !== world.database)
+        return refuse("conflict", `That deployment ran on ${r.database}, not ${world.database}.`);
+    if (!BEFORE_SWAP.includes(r.phase))
+        return refuse("after-swap", `That deployment is at ${r.phase}, past the point where it stops the service. Recover it with \`node scripts/deploy-browser.mjs --stage ${stage} --phase recover\` from its checkout.`);
+    const swapped = SWAP_FIELDS.filter(field => r[field] !== undefined && r[field] !== null);
+    if (swapped.length > 0)
+        return refuse("conflict", `The journal says ${r.phase} but records ${swapped.join(", ")}, which only the swap writes.`);
+    if (existsSync(join(stage, "browser.next.plist")))
+        return refuse("conflict", `The journal says ${r.phase} but a new service definition was staged (${join(stage, "browser.next.plist")}).`);
+    proof.push(`Deployment journal ${join(stage, "deployment.json")} stopped at ${r.phase}, before the swap, and records nothing the swap writes.`);
+    if (!Number.isInteger(schema) || schema !== r.schema)
+        return refuse("conflict", `The live database is at schema ${schema}; the deployment started at ${r.schema}.`);
+    proof.push(`The live database is still at schema ${schema}.`);
+    const plists = world.servicePlists();
+    if (plists.length !== 1)
+        return refuse("conflict", plists.length === 0 ? "No browser service definition is installed." : `More than one browser service definition is installed: ${plists.map(one => one.path).join(", ")}.`);
+    const plist = plists[0];
+    if (!plist.text.includes(`<string>${r.priorRuntime}/cli.js</string>`) || plist.text.includes(r.nextRuntime))
+        return refuse("conflict", `${plist.path} does not name the runtime the deployment started from (${r.priorRuntime}).`);
+    const saved = join(stage, "browser.saved.plist");
+    if (existsSync(saved) && readFileSync(saved, "utf8") !== plist.text)
+        return refuse("conflict", `${plist.path} differs from the definition the deployment saved (${saved}).`);
+    proof.push(`${plist.path} still names ${r.priorRuntime}${existsSync(saved) ? " and matches the saved copy" : ""}.`);
+    const processes = world.processes();
+    const deploying = processes.filter(one => one.command.includes("deploy-browser.mjs"));
+    if (deploying.length > 0)
+        return refuse("deploying", `A deployment is still running (process ${deploying.map(one => one.pid).join(", ")}); let it finish or recover.`);
+    const staged = processes.filter(one => one.command.includes(r.nextRuntime));
+    if (staged.length > 0)
+        return refuse("after-swap", `Process ${staged.map(one => one.pid).join(", ")} runs from the staged runtime ${r.nextRuntime}.`);
+    const supervisor = processes.find(one => one.command.includes(`${r.priorRuntime}/controller-service.js`));
+    const worker = processes.find(one => one.command.includes(`${r.priorRuntime}/cli.js up --db ${world.database}`));
+    if (supervisor === undefined || worker === undefined)
+        return refuse("conflict", `The service is not running from ${r.priorRuntime}, so it can't be shown that the swap never began.`);
+    proof.push(`The service runs from ${r.priorRuntime} (process ${supervisor.pid}); nothing runs from the staged runtime, and no deployment is running.`);
+    return { ok: true, id, stage, journal: r, proof };
+}
+/** Prove, then (with `yes`) lift exactly that pause and journal the release in the deployment's own journal. */
+export function releaseGate(id, world, yes) {
+    const proved = proveBeforeSwap(id, world);
+    if (!proved.ok)
+        return proved;
+    if (!yes)
+        return { ok: true, released: false, id, stage: proved.stage, proof: proved.proof };
+    const db = world.open();
+    // removeUpdateGate checks the owner again inside its own write: a pause that changed hands is not touched.
+    try {
+        removeUpdateGate(db, id);
+    }
+    finally {
+        db.close();
+    }
+    durableJson(join(proved.stage, "deployment.json"), {
+        ...proved.journal, phase: "released", updatedAt: world.now().toISOString(),
+        releasedBeforeSwap: { at: world.now().toISOString(), by: "toolroll release --release-gate", from: proved.journal.phase, proof: proved.proof },
+    });
+    return { ok: true, released: true, id, stage: proved.stage, proof: proved.proof };
+}

package/dist/release-links.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Both CLI names, moved to a deployed runtime (release.ts, step `link`): `toolroll` and `standing-orders` are pointed
+ * at `<runtime>/bin.js`, each link replaced whole (a new link renamed over the old one). Each name must then resolve to
+ * that file and answer with the released version, or every link goes back to where it pointed before.
+ *
+ * The coordinator saves what `findCliLinks` saw before switching, so a release killed halfway through relinking still
+ * knows where to put each name back. A name on PATH that is a file rather than a link is someone else's and never
+ * replaced.
+ */
+export declare const CLI_NAMES: readonly ["toolroll", "standing-orders"];
+/** One name on PATH: where its link is and what it pointed at before the release (null: not there yet). */
+export type CliLink = {
+    name: string;
+    path: string;
+    before: string | null;
+    foreign?: true;
+};
+/** Where each name is on PATH. A missing name is made beside the other one; none on PATH at all is an empty list. */
+export declare function findCliLinks(path?: string, names?: readonly string[]): CliLink[];
+/** Point `link` at `target`, atomically: a new link beside it, renamed over it. */
+export declare function pointLink(link: string, target: string): void;
+/**
+ * Switch every link to `bin`. `answers(path)` says whether that name now answers as the released build. Any failure
+ * puts every link back where `links` says it was, and throws. Switching a link already at `bin` changes nothing, so a
+ * resumed relink repeats safely.
+ */
+export declare function switchCliLinks(links: readonly CliLink[], bin: string, answers: (path: string) => boolean): CliLink[];
+/** Each link where it pointed before; a link that wasn't there before is removed. */
+export declare function restoreCliLinks(links: readonly CliLink[]): void;

package/dist/release-links.js

@@ -0,0 +1,102 @@
+/**
+ * Both CLI names, moved to a deployed runtime (release.ts, step `link`): `toolroll` and `standing-orders` are pointed
+ * at `<runtime>/bin.js`, each link replaced whole (a new link renamed over the old one). Each name must then resolve to
+ * that file and answer with the released version, or every link goes back to where it pointed before.
+ *
+ * The coordinator saves what `findCliLinks` saw before switching, so a release killed halfway through relinking still
+ * knows where to put each name back. A name on PATH that is a file rather than a link is someone else's and never
+ * replaced.
+ */
+import { randomUUID } from "node:crypto";
+import { lstatSync, readlinkSync, realpathSync, renameSync, rmSync, symlinkSync } from "node:fs";
+import { delimiter, dirname, join, resolve } from "node:path";
+export const CLI_NAMES = Object.freeze(["toolroll", "standing-orders"]);
+/** Where each name is on PATH. A missing name is made beside the other one; none on PATH at all is an empty list. */
+export function findCliLinks(path = process.env["PATH"] ?? "", names = CLI_NAMES) {
+    const found = names.map((name) => {
+        for (const dir of path.split(delimiter).filter(Boolean)) {
+            const at = join(dir, name);
+            let entry;
+            try {
+                entry = lstatSync(at);
+            }
+            catch {
+                continue;
+            }
+            if (!entry.isSymbolicLink())
+                return { name, path: at, before: null, foreign: true };
+            return { name, path: at, before: resolve(dirname(at), readlinkSync(at)) };
+        }
+        return { name, path: null, before: null };
+    });
+    const home = found.find(one => one.path !== null && one.foreign === undefined);
+    if (home === undefined)
+        return found.filter((one) => one.path !== null);
+    return found.map(one => ({ ...one, path: one.path ?? join(dirname(home.path), one.name) }));
+}
+/** Point `link` at `target`, atomically: a new link beside it, renamed over it. */
+export function pointLink(link, target) {
+    const temp = `${link}.${randomUUID().slice(0, 8)}.link`;
+    symlinkSync(target, temp);
+    try {
+        renameSync(temp, link);
+    }
+    catch (error) {
+        rmSync(temp, { force: true });
+        throw error;
+    }
+}
+const target = (link) => { try {
+    return resolve(dirname(link), readlinkSync(link));
+}
+catch {
+    return null;
+} };
+const real = (path) => { try {
+    return realpathSync(path);
+}
+catch {
+    return null;
+} };
+/**
+ * Switch every link to `bin`. `answers(path)` says whether that name now answers as the released build. Any failure
+ * puts every link back where `links` says it was, and throws. Switching a link already at `bin` changes nothing, so a
+ * resumed relink repeats safely.
+ */
+export function switchCliLinks(links, bin, answers) {
+    const foreign = links.find(one => one.foreign === true);
+    if (foreign !== undefined)
+        throw new Error(`${foreign.path} is not a link; it was left as it is`);
+    if (links.length < CLI_NAMES.length)
+        throw new Error(`found ${links.length === 0 ? "no CLI name" : `only ${links.map(one => one.name).join(", ")}`} on PATH; link both with \`toolroll link\` first`);
+    const wanted = real(bin);
+    if (wanted === null)
+        throw new Error(`${bin} does not exist`);
+    try {
+        for (const link of links)
+            if (target(link.path) !== bin)
+                pointLink(link.path, bin);
+        for (const link of links) {
+            if (real(link.path) !== wanted)
+                throw new Error(`${link.path} does not resolve to ${bin}`);
+            if (!answers(link.path))
+                throw new Error(`${link.path} does not answer as the released build`);
+        }
+        return links.map(({ name, path, before }) => ({ name, path, before }));
+    }
+    catch (error) {
+        restoreCliLinks(links);
+        throw error;
+    }
+}
+/** Each link where it pointed before; a link that wasn't there before is removed. */
+export function restoreCliLinks(links) {
+    for (const link of links) {
+        if (link.foreign === true)
+            continue;
+        if (link.before === null)
+            rmSync(link.path, { force: true });
+        else if (target(link.path) !== link.before)
+            pointLink(link.path, link.before);
+    }
+}