toolroll 0.7.0 → 0.8.0

package/dist/toolroll-update-cli.js

@@ -0,0 +1,155 @@
+/**
+ * `toolroll update`: preview first, `--yes` to act (toolroll-update.ts does
+ * the work). `--now` refuses while work runs; `--when-idle` (the default)
+ * pauses new work and waits for running work; `--at HH:MM` waits for that
+ * time first. `--rollback` returns to the previous runtime and its backup.
+ */
+import { homedir, userInfo } from "node:os";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+import { installMethod } from "./install-method.js";
+import { isNewer, latestVersionNow } from "./releases.js";
+import { databasePath } from "./store.js";
+import { PACKAGE_VERSION } from "./version.js";
+import { currentRuntime, machineSystem, readRuntimeUpdate, requestRuntimeUpdateCancel, resumeRuntimeUpdate, retireUpdateJob, runtimeUpdateTerminal, startRuntimeRollback, startRuntimeUpdate, } from "./toolroll-update.js";
+/** Loaded on first use (as backup.ts and store.ts do), so modules that only import this one (the console,
+ * and tests that load it in a browser-like environment) never need `node:sqlite` itself. */
+function sqlite() {
+    return createRequire(import.meta.url)("node:sqlite");
+}
+export const UPDATE_HELP = `toolroll update                 preview updating to the latest release
+toolroll update --yes           update: verify, let running work finish, back up, rehearse, switch, restart, check
+  --version X                   a specific release instead of the latest
+  --when-idle                   pause new work and wait for running work (the default)
+  --now                         refuse if any work is running
+  --at HH:MM                    wait until then (e.g. --at 03:00)
+  --allow-downgrade             with --version, go back to an older release
+toolroll update --rollback [--yes]   return to the previous version and its database backup
+toolroll update --status | --resume | --cancel`;
+export async function runUpdateCommand(args, write, deps = {}) {
+    const has = (name) => args.includes(`--${name}`);
+    const value = (name) => { const at = args.indexOf(`--${name}`); return at >= 0 ? args[at + 1] : undefined; };
+    const known = new Set(["--yes", "--now", "--when-idle", "--at", "--version", "--rollback", "--resume", "--cancel", "--status", "--by", "--db", "--id", "--allow-downgrade", "--help"]);
+    const unknown = args.filter((arg, i) => arg.startsWith("--") && !known.has(arg) && !["--at", "--version", "--by", "--db", "--id"].includes(args[i - 1] ?? ""));
+    if (has("help")) {
+        write(UPDATE_HELP);
+        return 0;
+    }
+    if (unknown.length > 0) {
+        write(`Unknown option ${unknown[0]}.\n${UPDATE_HELP}`);
+        return 2;
+    }
+    const modes = ["now", "when-idle", "at"].filter(has);
+    if (modes.length > 1) {
+        write("Choose one of --now, --when-idle or --at.");
+        return 2;
+    }
+    const at = value("at");
+    if (has("at") && !/^([01]\d|2[0-3]):[0-5]\d$/.test(at ?? "")) {
+        write("--at takes a time like 03:00.");
+        return 2;
+    }
+    const when = has("now") ? "now" : has("at") ? "at" : "when-idle";
+    const databaseFile = deps.databaseFile ?? value("db") ?? databasePath(process.env, homedir());
+    const stateDir = dirname(databaseFile);
+    const actor = value("by") ?? userInfo().username;
+    const current = deps.current ?? currentRuntime(PACKAGE_VERSION);
+    const system = () => deps.system ?? machineSystem();
+    if (has("status")) {
+        const j = readRuntimeUpdate(stateDir);
+        write(j ? `${j.kind === "update" ? "Update" : "Rollback"} ${j.from.version} → ${j.to.version}: ${j.phase}. ${j.detail}` : "No update has run here.");
+        return 0;
+    }
+    if (has("cancel")) {
+        write(requestRuntimeUpdateCancel(stateDir));
+        return 0;
+    }
+    if (has("resume")) {
+        // The console's job names its journal: it resumes that update or nothing, then removes its own definition.
+        const id = value("id");
+        if (has("id") && !/^[a-f0-9-]{36}$/.test(id ?? "")) {
+            write("--id takes the update's id.");
+            return 2;
+        }
+        try {
+            const outcome = await resumeRuntimeUpdate(stateDir, system(), id);
+            write(outcome.message);
+            return outcome.ok ? 0 : 1;
+        }
+        finally {
+            if (id !== undefined)
+                retireUpdateJob(id, deps.home);
+        }
+    }
+    const method = deps.method ?? installMethod(join(current.dist, "bin.js"));
+    if (method.kind === "npx") {
+        write("npx runs the latest Toolroll each time, so this one is current. Nothing to update.");
+        return 0;
+    }
+    if (method.kind === "source") {
+        write("This Toolroll runs from a source checkout. Update it with git; toolroll update replaces installed releases only.");
+        return 1;
+    }
+    if (has("rollback")) {
+        const last = readRuntimeUpdate(stateDir);
+        if (!last || last.kind !== "update" || last.phase !== "complete" || !runtimeUpdateTerminal(last.phase)) {
+            write("There is no completed update to roll back.");
+            return 1;
+        }
+        if (!has("yes")) {
+            write(`Roll back ${last.to.version} → ${last.from.version}, with the database as it was before the update (${last.finishedAt?.slice(0, 16).replace("T", " ") ?? "unknown"} UTC).`);
+            const since = recordsSince(databaseFile, last.finishedAt ?? last.updatedAt);
+            if (since > 0)
+                write(`${since} ledger ${since === 1 ? "entry was" : "entries were"} recorded since then. They are set aside in a backup of the current database, not merged back.`);
+            write("New work pauses and running work finishes first. Add --yes to roll back.");
+            return 0;
+        }
+        const outcome = await startRuntimeRollback({ stateDir, databaseFile, current, actor, when }, system());
+        write(outcome.message);
+        return outcome.ok ? 0 : 1;
+    }
+    let version = value("version");
+    if (version === undefined) {
+        try {
+            version = (await (deps.latest ?? latestVersionNow)()).version;
+        }
+        catch (error) {
+            write(`Could not read the latest release: ${error.message}`);
+            return 1;
+        }
+    }
+    if (version === current.version) {
+        write(`Toolroll ${version} is current.`);
+        return 0;
+    }
+    const downgrade = !isNewer(version, current.version);
+    if (downgrade && !has("allow-downgrade")) {
+        write(`Toolroll ${version} is older than ${current.version}. Add --allow-downgrade to go back to it.`);
+        return 1;
+    }
+    if (!has("yes")) {
+        write(`Update Toolroll ${current.version} → ${version}.`);
+        write(`${when === "now" ? "Refuses if any work is running" : when === "at" ? `Waits until ${at}, then pauses new work and lets running work finish` : "Pauses new work and lets running work finish"}; verifies the package came from ap9000/toolroll's publish workflow; backs up and rehearses the database; keeps ${current.version} for toolroll update --rollback.`);
+        write("Add --yes to update.");
+        return 0;
+    }
+    if (when === "at")
+        write(`Waiting until ${at}. Keep this running, or schedule it from Settings → Updates in the console.`);
+    const outcome = await startRuntimeUpdate({ stateDir, databaseFile, current, actor, version, when, at: at ?? null, allowDowngrade: downgrade }, system());
+    write(outcome.message);
+    return outcome.ok ? 0 : 1;
+}
+function recordsSince(databaseFile, since) {
+    try {
+        const db = new (sqlite().DatabaseSync)(databaseFile, { readOnly: true });
+        try {
+            return Number(db.prepare("SELECT count(*) n FROM action_ledger WHERE at > ? AND action NOT LIKE 'toolroll %'").get(since)?.["n"] ?? 0);
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch {
+        return 0;
+    }
+}

package/dist/toolroll-update-ui.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Settings → Updates: the installed version, one of three ways to update
+ * (behind the operator's password), the update's steps live while it runs,
+ * and a one-time "What's new" card afterwards. The work itself is the
+ * `toolroll update` command (toolroll-update.ts), started as its own job.
+ */
+import type { InstallMethod } from "./install-method.js";
+import { type RuntimeUpdateJournal } from "./toolroll-update.js";
+export declare const UPDATES_CSS: string;
+export type UpdatesView = {
+    current: string;
+    /** The newest release, why it is unknown, or not asked because update checks are off. */
+    latest: {
+        version: string;
+    } | {
+        problem: string;
+    } | {
+        off: true;
+    };
+    method: InstallMethod;
+    journal: RuntimeUpdateJournal | null;
+    running: boolean;
+    whatsNew: {
+        version: string;
+        notes: string[];
+    } | null;
+    csrf: string;
+};
+/** The steps, each done, current, failed or waiting. Also the live region's fragment. */
+export declare function updateStepsHtml(j: RuntimeUpdateJournal, running: boolean): string;
+export declare function updatesHtml(view: UpdatesView, notice: {
+    said?: string | null;
+    problem?: string | null;
+}): string;
+export declare function newerThan(a: string, b: string): boolean;
+/** Polls the steps every two seconds, keeps trying while the console
+ * restarts, and reloads once the update has finished. */
+export declare function updatesScript(): string;

package/dist/toolroll-update-ui.js

@@ -0,0 +1,89 @@
+import { STEP_WORDS, UPDATE_STEPS, runtimeUpdateTerminal } from "./toolroll-update.js";
+const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+const clock = (iso) => { const d = new Date(iso); return `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`; };
+export const UPDATES_CSS = `.updates{max-width:640px;min-width:0;overflow-wrap:anywhere}.updates .card{margin:0 0 16px}.updates h2{margin:0;font-size:1.0625rem}.updates .card>p{margin:4px 0 0}` +
+    `.updates .update-actions{display:flex;flex-wrap:wrap;gap:8px;margin:16px 0 0}.updates .update-actions button{white-space:nowrap}` +
+    `.updates button.primary{background:var(--primary);color:var(--primary-foreground);border-color:var(--primary);font-weight:600}` +
+    `.updates .step-up{display:grid;gap:4px;font-size:.8125rem;margin:16px 0 0;max-width:20rem}.updates .step-up input{min-height:40px}` +
+    `.updates ol.update-steps{list-style:none;padding:0;margin:14px 0 0;display:grid;gap:2px}.updates ol.update-steps li{display:grid;grid-template-columns:18px minmax(0,1fr);gap:0 10px;align-items:baseline;padding:5px 0;font-size:.875rem;color:var(--so-muted)}` +
+    `.updates ol.update-steps li::before{content:"";width:8px;height:8px;border-radius:50%;border:1.5px solid var(--so-input-line);justify-self:center;transform:translateY(-1px)}` +
+    `.updates ol.update-steps li[data-state=done]{color:var(--so-ink)}.updates ol.update-steps li[data-state=done]::before{background:var(--so-success);border-color:var(--so-success)}` +
+    `.updates ol.update-steps li[data-state=now]{color:var(--so-ink);font-weight:600}.updates ol.update-steps li[data-state=now]::before{background:var(--so-info);border-color:var(--so-info);box-shadow:0 0 0 4px color-mix(in srgb,var(--so-info) 16%,transparent)}` +
+    `.updates ol.update-steps li[data-state=failed]{color:var(--so-danger);font-weight:600}.updates ol.update-steps li[data-state=failed]::before{background:var(--so-danger);border-color:var(--so-danger)}` +
+    `.updates ol.update-steps .step-detail{grid-column:2;font-weight:400;color:var(--so-muted);font-size:.8125rem;margin-top:2px}` +
+    `.updates .whats-new ul{margin:10px 0 0;padding-left:18px}.updates .whats-new li{margin:4px 0}.updates .whats-new form{margin:14px 0 0}` +
+    `.updates .update-problem{color:var(--so-danger)}.updates .stamp{margin:10px 0 0}.updates code{white-space:nowrap}` +
+    `@media (prefers-reduced-motion:no-preference){.updates ol.update-steps li[data-state=now]::before{animation:update-pulse 1.6s ease-in-out infinite}}@keyframes update-pulse{50%{box-shadow:0 0 0 7px color-mix(in srgb,var(--so-info) 6%,transparent)}}` +
+    `@media (max-width:600px){.updates .update-actions{display:grid}.updates .update-actions button{width:100%;min-height:44px}.updates .step-up{max-width:none}.updates .step-up input{min-height:44px}}`;
+/** The steps, each done, current, failed or waiting. Also the live region's fragment. */
+export function updateStepsHtml(j, running) {
+    const finished = runtimeUpdateTerminal(j.phase);
+    const failed = ["restored", "refused", "needs-attention", "rolling-back"].includes(j.phase);
+    const last = UPDATE_STEPS.indexOf([...j.steps].reverse().find(s => UPDATE_STEPS.includes(s.phase))?.phase);
+    const items = UPDATE_STEPS.map((step, i) => {
+        const state = j.phase === "complete" || i < last ? "done" : i > last ? "waiting" : failed ? "failed" : finished ? "waiting" : "now";
+        // Only where it adds something: which work it waits for, or what went wrong.
+        const detail = (state === "now" && step === "draining") || (state === "failed" && j.phase === "rolling-back") ? `<span class="step-detail">${e(j.detail)}</span>` : "";
+        return `<li data-step="${step}" data-state="${state}">${e(STEP_WORDS[step])}${detail}</li>`;
+    }).join("");
+    const title = j.phase === "scheduled" ? `Update to ${e(j.to.version)} scheduled for ${e(clock(j.at ?? j.startedAt))}`
+        : j.phase === "rolling-back" ? `Restoring ${e(j.from.version)}`
+            : j.kind === "rollback" ? `Rolling back to ${e(j.to.version)}` : `Updating to ${e(j.to.version)}`;
+    const stalled = !running && !finished ? `<p class="update-problem" role="alert">The updater stopped. Run <code>toolroll update --resume</code> to continue it.</p>` : "";
+    return `<div id="update-live" data-phase="${e(j.phase)}" data-done="${finished ? 1 : 0}"><h2>${title}</h2>` +
+        (j.phase === "scheduled" ? `<p class="meta">Running work finishes first. You can close this page.</p>` : `<ol class="update-steps" aria-label="Update steps">${items}</ol>`) + stalled + `</div>`;
+}
+function outcomeHtml(j) {
+    if (j.phase === "complete")
+        return j.kind === "rollback" ? `<div class="card" data-update-outcome="rolled-back"><h2>Back on ${e(j.to.version)}</h2><p class="meta">${e(j.detail)}</p></div>` : "";
+    if (j.phase === "cancelled")
+        return `<div class="card" data-update-outcome="cancelled"><h2>Update cancelled</h2><p class="meta">Nothing changed.</p></div>`;
+    const title = j.phase === "refused" ? `Didn't update to ${e(j.to.version)}` : j.phase === "restored" ? `Update to ${e(j.to.version)} didn't finish` : "The update needs attention";
+    return `<div class="card" data-update-outcome="${e(j.phase)}"><h2>${title}</h2><p class="${j.phase === "needs-attention" ? "update-problem" : ""}" role="alert">${e(j.detail)}</p>` +
+        `<details><summary>Steps</summary>${updateStepsHtml(j, false).replace(/<h2>.*?<\/h2>/, "")}</details></div>`;
+}
+export function updatesHtml(view, notice) {
+    const note = notice.problem ? `<p class="update-problem" role="alert">${e(notice.problem)}</p>` : notice.said ? `<p role="status">${e(notice.said)}</p>` : "";
+    const j = view.journal;
+    const active = j !== null && !runtimeUpdateTerminal(j.phase);
+    const csrf = `<input type="hidden" name="csrf" value="${e(view.csrf)}">`;
+    const whatsNew = view.whatsNew === null ? "" : `<div class="card whats-new" data-whats-new="${e(view.whatsNew.version)}"><h2>What’s new in ${e(view.whatsNew.version)}</h2>` +
+        (view.whatsNew.notes.length > 0 ? `<ul>${view.whatsNew.notes.map(line => `<li>${e(line)}</li>`).join("")}</ul>` : "") +
+        `<p class="meta"><a href="https://github.com/ap9000/toolroll/releases/tag/v${e(view.whatsNew.version)}" rel="noreferrer">Full release notes</a></p>` +
+        `<form method="post" action="/settings/updates/seen">${csrf}<button type="submit">Got it</button></form></div>`;
+    if (active) {
+        const cancel = ["scheduled", "draining"].includes(j.phase) ? `<form method="post" action="/settings/updates/cancel" class="update-actions">${csrf}<button type="submit">Cancel update</button></form>` : "";
+        return `<section class="updates">${note}<div class="card" id="update-region">${updateStepsHtml(j, view.running)}${cancel}</div><p class="meta stamp" id="update-region-stamp"></p></section>`;
+    }
+    const latest = "version" in view.latest ? view.latest.version : null;
+    const newer = latest !== null && newerThan(latest, view.current);
+    const state = view.method.kind === "npx" ? `<h2>Toolroll ${e(view.current)}</h2><p class="meta">npx runs the latest release each time, so this is current.</p>`
+        : view.method.kind === "source" ? `<h2>Toolroll ${e(view.current)}</h2><p class="meta">This runs from a source checkout. Update it with git.</p>`
+            : newer ? `<h2>Toolroll ${e(latest)} is available</h2><p class="meta">You have ${e(view.current)}. Running work finishes first, and your current version is kept so you can go back.</p>`
+                : "off" in view.latest ? `<h2>Toolroll ${e(view.current)}</h2><p class="meta">Update checks are off.</p><form method="get" action="/settings/updates" class="update-actions"><input type="hidden" name="check" value="now"><button type="submit">Check now</button></form>`
+                    : latest === null ? `<h2>Toolroll ${e(view.current)}</h2><p class="meta">Couldn’t check for a newer release: ${e("problem" in view.latest ? view.latest.problem : "")}</p>`
+                        : `<h2>Toolroll ${e(view.current)} is up to date</h2>`;
+    const form = newer && !["npx", "source"].includes(view.method.kind)
+        ? `<form method="post" action="/settings/updates">${csrf}<input type="hidden" name="version" value="${e(latest)}">` +
+            `<label class="step-up">Your Toolroll password<input type="password" name="password" autocomplete="current-password" required></label>` +
+            `<div class="update-actions"><button type="submit" name="when" value="now" class="primary">Update now</button>` +
+            `<button type="submit" name="when" value="when-idle">When idle</button><button type="submit" name="when" value="tonight">Tonight (03:00)</button></div></form>`
+        : "";
+    const rollback = j?.kind === "update" && j.phase === "complete" ? `<p class="meta">To go back to ${e(j.from.version)}: <code>toolroll update --rollback</code></p>` : "";
+    return `<section class="updates">${note}${whatsNew}${j ? outcomeHtml(j) : ""}<div class="card" data-update-state="${newer ? "available" : "current"}">${state}${form}${rollback}</div></section>`;
+}
+export function newerThan(a, b) {
+    const [x, y] = [a, b].map(v => v.split(".").map(Number));
+    for (let i = 0; i < 3; i++)
+        if ((x[i] ?? 0) !== (y[i] ?? 0))
+            return (x[i] ?? 0) > (y[i] ?? 0);
+    return false;
+}
+/** Polls the steps every two seconds, keeps trying while the console
+ * restarts, and reloads once the update has finished. */
+export function updatesScript() {
+    return `(function(){var region=document.getElementById("update-region");if(!region)return;var stamp=document.getElementById("update-region-stamp");var misses=0;` +
+        `function tick(){if(document.hidden){setTimeout(tick,2000);return;}fetch("/settings/updates?fragment=steps",{credentials:"same-origin",cache:"no-store"}).then(function(r){if(!r.ok)throw 0;return r.text();}).then(function(html){misses=0;if(stamp)stamp.textContent="";` +
+        `var live=region.querySelector("#update-live");if(live)live.outerHTML=html;var now=region.querySelector("#update-live");if(now&&now.getAttribute("data-done")==="1"){location.reload();return;}setTimeout(tick,2000);})` +
+        `.catch(function(){misses++;if(stamp)stamp.textContent=misses>2?"Reconnecting while Toolroll restarts…":"";setTimeout(tick,Math.min(10000,2000*misses));});}setTimeout(tick,2000);})();`;
+}

package/dist/toolroll-update.d.ts

@@ -0,0 +1,235 @@
+import type { DatabaseSync } from "node:sqlite";
+import { type SupervisorRunner } from "./daemon.js";
+export declare const PROVENANCE_REPOSITORY = "https://github.com/ap9000/toolroll";
+export declare const PROVENANCE_WORKFLOW = ".github/workflows/publish.yml";
+/** The steps a person sees, in order. */
+export declare const UPDATE_STEPS: readonly ["verifying", "draining", "backing-up", "rehearsing", "switching", "restarting", "health"];
+export type UpdateStep = typeof UPDATE_STEPS[number];
+export type RuntimePhase = "scheduled" | UpdateStep | "complete" | "rolling-back" | "restored" | "refused" | "cancelled" | "needs-attention";
+export declare const STEP_WORDS: Record<UpdateStep, string>;
+export type When = "now" | "when-idle" | "at";
+export type RuntimeRef = {
+    version: string;
+    dist: string;
+};
+/** How many release-* runtimes stay on disk: the running one and the one before it. */
+export declare const KEEP_RUNTIMES = 2;
+/** The one-off launchd job the console starts the updater as. */
+export declare const UPDATE_JOB_LABEL = "com.toolroll.update";
+export type RuntimeUpdateJournal = {
+    version: 1;
+    id: string;
+    kind: "update" | "rollback";
+    stateDir: string;
+    databaseFile: string;
+    stageDir: string;
+    from: RuntimeRef;
+    to: RuntimeRef;
+    when: When;
+    at: string | null;
+    actor: string;
+    phase: RuntimePhase;
+    detail: string;
+    error?: string;
+    steps: {
+        phase: RuntimePhase;
+        at: string;
+    }[];
+    startedAt: string;
+    updatedAt: string;
+    finishedAt?: string;
+    package?: {
+        sha512: string;
+        repository: string;
+        workflow: string;
+    };
+    notes?: string[];
+    /** This run's own verified copies of the live database and coding catalog: what a failure restores. */
+    backupPath?: string;
+    backupHash?: string;
+    codingBackupPath?: string;
+    codingBackupHash?: string;
+    /** A rollback installs the update's earlier backups (checked against their recorded hashes). */
+    restoreFrom?: {
+        path: string;
+        hash: string;
+        updateId: string;
+        codingPath?: string;
+        codingHash?: string;
+    };
+    rehearsal?: {
+        tables: number;
+        rows: number;
+    };
+    /** The background service, recorded before it is stopped: its definition and the processes that must be gone. */
+    service?: {
+        unit: string;
+        pids: number[];
+    };
+    /** Recorded before each change so a resumed or failed run knows what to put back. */
+    switched?: {
+        links: {
+            path: string;
+            previous: string;
+        }[];
+        unit: {
+            path: string;
+            saved: string;
+        } | null;
+        databaseRestored?: boolean;
+    };
+    /** What the live database held when a failed run restored its backup: nothing written is lost. */
+    keptAside?: string;
+    /** The restore put the backup back: a retried restore never puts it back again (what was written since belongs to
+     * the restored version and would be lost), and it keeps a fresh copy aside before every attempt until then. */
+    restoredDatabase?: boolean;
+    seen?: boolean;
+};
+export type PackageRelease = {
+    version: string;
+    tarball: string;
+    integrity: string;
+    attestations: string | null;
+};
+export type UpdateSystem = {
+    now: () => Date;
+    sleep: (ms: number) => Promise<void>;
+    release: (version: string) => Promise<PackageRelease>;
+    download: (url: string) => Promise<Uint8Array>;
+    attestations: (url: string) => Promise<unknown>;
+    /** Installs `release` from the registry into `runtimeDir`, has npm verify its
+     * registry signature and attestation there, checks the installed bytes are
+     * `release.integrity`, and returns the package's dist. */
+    install: (runtimeDir: string, release: PackageRelease) => Promise<string>;
+    /** Opens `copy` with the runtime at `dist`, which migrates it as that build would. */
+    rehearse: (dist: string, copy: string) => Promise<void>;
+    /** Every `toolroll` and `standing-orders` command on PATH: each must be a link into `from` to be switched. */
+    commands: (from: RuntimeRef) => string[];
+    /** The background service's definition, when one runs `from`. */
+    serviceUnit: (from: RuntimeRef) => string | null;
+    /** The processes the service runs now. */
+    servicePids: (unit: string) => Promise<number[]>;
+    /** Unload the service; resolves once launchd no longer has it. */
+    stopService: (unit: string) => Promise<void>;
+    /** Load and start the service from its definition on disk. */
+    restartService: (unit: string) => Promise<void>;
+    processAlive: (pid: number) => boolean;
+    healthy: (j: RuntimeUpdateJournal) => Promise<boolean>;
+    healthTimeoutMs?: number;
+    /** How long stopped service processes may take to exit. */
+    exitTimeoutMs?: number;
+    /** Fault injection for state-machine tests, never selectable by a flag. */
+    checkpoint?: (phase: RuntimePhase) => void;
+};
+export type UpdateOutcome = {
+    ok: boolean;
+    phase: RuntimePhase;
+    message: string;
+    journal: RuntimeUpdateJournal | null;
+};
+export declare const runtimeUpdateTerminal: (phase: RuntimePhase) => boolean;
+export declare function readRuntimeUpdate(stateDir: string): RuntimeUpdateJournal | null;
+/** Running work by name, for a refusal a person can act on. */
+export declare function runningWorkWords(db: DatabaseSync): string | null;
+/** The npm provenance statement for exactly these bytes must name the
+ * Toolroll repository and its publish workflow. Anything else is refused.
+ * npm's own check (UpdateSystem.install) verifies the statement's signature. */
+export declare function checkProvenance(attestations: unknown, version: string, sha512Hex: string): {
+    repository: string;
+    workflow: string;
+};
+/** Headlines of this version's changelog section: its bold lead phrases. */
+export declare function releaseNotes(changelog: string, version: string): string[];
+/** Every rename here: what is renamed is flushed first (a file itself, a link
+ * by its directory), and the directory after, so a crash never leaves a torn
+ * database, catalog or command. */
+export declare function durableRename(temp: string, target: string): void;
+type TableDigest = {
+    name: string;
+    columns: string[];
+    count: number;
+    hash: string;
+};
+/** Every historical row, table by table (deploy-browser's rehearsal check). */
+export declare function historySnapshot(db: DatabaseSync): TableDigest[];
+export declare function changedHistory(db: DatabaseSync, before: TableDigest[]): string[];
+export type StartOptions = {
+    stateDir: string;
+    databaseFile: string;
+    current: RuntimeRef;
+    actor: string;
+    version: string;
+    when: When;
+    at?: string | null;
+    /** An older version replaces the current one only when asked for by name. */
+    allowDowngrade?: boolean;
+};
+declare function nextAt(hhmm: string, now: Date): Date;
+/** Record an update without running it: the console's job resumes exactly this journal id. */
+export declare function prepareRuntimeUpdate(o: StartOptions, now: Date): RuntimeUpdateJournal | {
+    refused: string;
+};
+/** Start an update: stage, verify, then run the journaled steps. */
+export declare function startRuntimeUpdate(o: StartOptions, system: UpdateSystem): Promise<UpdateOutcome>;
+/** Return to the runtime and database backup an update replaced. */
+export declare function startRuntimeRollback(o: {
+    stateDir: string;
+    databaseFile: string;
+    current: RuntimeRef;
+    actor: string;
+    when: When;
+}, system: UpdateSystem): Promise<UpdateOutcome>;
+/** Continue a saved update after a crash, where it left off. With `id` (the console's job), only that update:
+ * a job never starts a fresh one, and a finished, replaced or rolled-back one is left alone. */
+export declare function resumeRuntimeUpdate(stateDir: string, system: UpdateSystem, id?: string): Promise<UpdateOutcome>;
+/** A prepared update whose job could not start. */
+export declare function abandonRuntimeUpdate(stateDir: string, id: string, why: string, now: Date): void;
+export declare function requestRuntimeUpdateCancel(stateDir: string): string;
+/** Keep the newest release-* runtimes (and any in `keep`), at most KEEP_RUNTIMES; deploy-browser's browser-* and
+ * the rollback-* records are not this updater's to remove. */
+export declare function pruneRuntimes(stateDir: string, keep: readonly string[]): string[];
+export type RuntimeUpdateStatus = {
+    journal: RuntimeUpdateJournal | null;
+    running: boolean;
+    /** A completed update whose What's new card has not been dismissed. */
+    whatsNew: {
+        version: string;
+        notes: string[];
+    } | null;
+};
+export declare function runtimeUpdateStatus(stateDir: string): RuntimeUpdateStatus;
+export declare function markWhatsNewSeen(stateDir: string): void;
+type Exec = (command: string, args: string[], options?: {
+    cwd?: string;
+    timeout?: number;
+}) => {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+};
+export declare function currentRuntime(version: string): RuntimeRef;
+/** Seams for tests: npm and ps (`exec`), launchctl (`run`), and process liveness. */
+export type MachineSeams = {
+    exec?: Exec;
+    run?: SupervisorRunner;
+    alive?: (pid: number) => boolean;
+};
+export declare function machineSystem(home?: string, env?: Record<string, string | undefined>, seams?: MachineSeams): UpdateSystem;
+/** The console starts the updater for one prepared journal as its own one-off
+ * launchd job, so the service it restarts is not its parent. The job resumes
+ * that id only; it does not run at login (no RunAtLoad: launchd starts it
+ * with a kickstart) and removes its definition when it finishes. Elsewhere it
+ * is a detached process. */
+export declare function launchRuntimeUpdate(args: {
+    databaseFile: string;
+    id: string;
+    dist?: string;
+}, seams?: {
+    home?: string;
+    run?: SupervisorRunner;
+    platform?: NodeJS.Platform;
+}): Promise<void>;
+/** The job's last act: its definition goes, so nothing can start it again. Only the definition for this id. */
+export declare function retireUpdateJob(id: string, home?: string): void;
+export declare const nextScheduledAt: typeof nextAt;
+export {};