toolroll 0.9.103 → 0.9.105

package/dist/tool-secret-store.js

@@ -1,32 +1,3 @@
-/**
- * Where the secrets Toolroll holds rest — project tools' keys and sign-ins,
- * and the credentials it keeps for integrations (Linear, Google mail, flow
- * webhooks): the operating system's keychain where this computer has one,
- * otherwise owner-only files.
- *
- * - macOS: the Keychain, through `/usr/bin/security -i`. Every command, the
- *   value included, is written to its stdin, so no secret is ever in a
- *   process's arguments. A line there holds about 4 KB, so a value is split
- *   into chunks: a head item names the chunks' generation and checksum, and is
- *   written last, so a reader sees the old value or the new one, never half.
- * - Linux: the Secret Service, through `secret-tool` (found in the system's
- *   own folders, never on a PATH), which reads the value from stdin. One that
- *   is installed but doesn't answer (no session bus) means files, said so.
- * - Anywhere else (or with TOOLROLL_SECRET_STORE=files): owner-only files, as
- *   before. Settings and `toolroll integrations` say so plainly.
- *
- * A keychain that is present but fails (locked, refused) is an error, never a
- * quiet fall back to files: what can't be read leaves the tool out of a run.
- *
- * Everything here lives in Toolroll's own folder for secrets: `tool-secrets`
- * beside the database, made when Toolroll starts (before any build can run),
- * never found by looking for a folder that happens to exist. A build is the
- * same user and can reach the keychain too (the fence can't deny it), so what
- * Toolroll keeps there is sealed (AES-256-GCM) with a key in that folder,
- * which every build's fence denies, and bound to its item's address. The
- * database records which key Toolroll made: a folder, key, link or lock that
- * something else put there first is refused, never used.
- */
 import { inReadOnlyRequest } from "./read-only-request.js";
 import { spawnSync } from "node:child_process";
 import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
@@ -36,30 +7,25 @@ import { envValue } from "./names.js";
 import { sleep } from "./sleep.js";
 export class SecretStoreError extends Error {
 }
-/** The words Settings and `toolroll integrations` use for where secrets rest. */
 export const STORE_WORDS = {
     "macos-keychain": "Secrets are kept in the macOS Keychain.",
     "secret-service": "Secrets are kept in this computer's keyring (Secret Service).",
     files: "Secrets are protected by owner-only files on this computer.",
 };
-/** Said instead when a keyring is installed but doesn't answer, so files are all there is. */
 export const UNANSWERED_WORDS = "Secrets are protected by owner-only files on this computer: its keyring isn't answering.";
 const SAFE = /^[A-Za-z0-9._-]+$/;
 const LABEL = "Toolroll tool secret";
-/** What the store's own program gets: enough to find the user's keychain or session bus, nothing else. */
 const STORE_ENV = ["PATH", "HOME", "USER", "LOGNAME", "TMPDIR", "DBUS_SESSION_BUS_ADDRESS", "XDG_RUNTIME_DIR"];
 const storeEnv = () => Object.fromEntries(STORE_ENV.flatMap(name => process.env[name] === undefined ? [] : [[name, process.env[name]]]));
 const checked = (item) => {
     if (!SAFE.test(item.service) || !SAFE.test(item.account))
         throw new SecretStoreError("A secret's address can't be used.");
 };
-/** The macOS Keychain, through `security -i` (`keychain`: a keychain file instead of the user's own, for tests). */
 export function macosKeychain(options = {}) {
     const binary = options.binary ?? "/usr/bin/security";
     if (options.keychain !== undefined && !/^\/[A-Za-z0-9._/-]+$/.test(options.keychain))
         throw new SecretStoreError("That keychain path can't be used.");
     const where = options.keychain === undefined ? "" : ` ${options.keychain}`;
-    /** One command on stdin; `security -i` exits with that command's status. */
     const run = (command) => {
         const done = spawnSync(binary, ["-i"], { input: `${command}\n`, encoding: "utf8", timeout: 20_000, env: storeEnv(), stdio: ["pipe", "pipe", "pipe"] });
         if (done.error !== undefined)
@@ -95,7 +61,6 @@ export function macosKeychain(options = {}) {
         },
     };
 }
-/** The Secret Service (GNOME Keyring, KWallet), through `secret-tool` at `binary`, an absolute path; the value goes on its stdin. */
 export function secretService(options) {
     const binary = options.binary;
     if (!binary.startsWith("/"))
@@ -136,12 +101,7 @@ export function secretService(options) {
     return backend;
 }
 const myUid = () => process.getuid?.() ?? null;
-/** Writable by someone other than its owner, and not a shared sticky folder like /tmp. */
 const othersWrite = (info) => (info.mode & 0o022) !== 0 && (info.mode & 0o1000) === 0;
-/**
- * `path` when it is a program only the system (or, for a test's stand-in, one of `owners`) can have put there: a real
- * executable file nobody else can change, in folders nobody else can either. Null otherwise.
- */
 export function trustedProgram(path, owners = [0]) {
     try {
         const real = realpathSync(path);
@@ -161,13 +121,7 @@ export function trustedProgram(path, owners = [0]) {
         return null;
     }
 }
-/** Where `secret-tool` may be: the system's own folders, never the PATH a process was given. */
 export const SECRET_TOOL_PATHS = ["/usr/bin/secret-tool", "/bin/secret-tool", "/usr/local/bin/secret-tool"];
-/**
- * Find this computer's store: the macOS Keychain where the system's `security` is; a Secret Service where the system's
- * `secret-tool` is and answers; else none (files). A `secret-tool` that is there but can't reach a keyring (no session
- * bus) is none too, and says so.
- */
 export function detectSecretStore(options = {}) {
     const platform = options.platform ?? process.platform, owners = options.owners ?? [0];
     if (platform === "darwin") {
@@ -179,14 +133,12 @@ export function detectSecretStore(options = {}) {
     const tool = (options.secretTools ?? SECRET_TOOL_PATHS).map(path => trustedProgram(path, owners)).find((one) => one !== null);
     if (tool === undefined)
         return { backend: null, unanswered: false };
-    // Answering: a lookup of nothing says "not found" quietly; no session bus says why on stderr, or hangs.
     const probe = spawnSync(tool, ["lookup", "service", "toolroll-probe", "account", "probe"], { encoding: "utf8", timeout: 5_000, env: storeEnv(), stdio: ["ignore", "pipe", "pipe"] });
     const answers = probe.error === undefined && (probe.status === 0 || (probe.status === 1 && probe.stderr.trim() === ""));
     return answers ? { backend: secretService({ binary: tool }), unanswered: false } : { backend: null, unanswered: true };
 }
 let detected;
 let chosen = null;
-/** Tests choose the store (a keychain file of their own, files, or what detection found); null goes back to this computer's. */
 export function chooseSecretStore(store) { chosen = store; }
 function currentStore(env) {
     if (chosen === "files")
@@ -198,18 +150,15 @@ function currentStore(env) {
     detected ??= detectSecretStore();
     return detected;
 }
-/** This computer's store (found once), or null for owner-only files. */
 export function secretBackend(env = process.env) {
     return currentStore(env).backend;
 }
-/** Where secrets rest, in the words Settings and `toolroll integrations` share; `problem` when Toolroll's folder can't be used. */
 export function secretStorage() {
     const found = currentStore(process.env);
     const kind = found.backend?.kind ?? "files";
     const problem = standing === null ? standingProblem : refusedRoots.get(standing) ?? null;
     return { kind, words: found.unanswered ? UNANSWERED_WORDS : STORE_WORDS[kind], filesOnly: kind === "files", ...(problem === null ? {} : { problem }) };
 }
-// ---- a value, in chunks the store can hold ------------------------------------------------------------------------
 const HEAD = /^v1\.([0-9a-f]{8})\.([1-9][0-9]?)\.([0-9a-f]{16})\.([A-Za-z0-9_-]*)$/;
 const digestOf = (text) => createHash("sha256").update(text).digest("hex").slice(0, 16);
 const chunkItem = (item, generation, index) => ({ service: item.service, account: `${item.account}.${generation}.${index}` });
@@ -222,14 +171,12 @@ function readHead(backend, item) {
         throw new SecretStoreError("A tool's stored secrets are damaged.");
     return { generation: parts[1], count: Number(parts[2]), digest: parts[3], first: parts[4] };
 }
-/** The text stored at `item`, or null when nothing is. A head read while a writer replaces it is read again. */
 export function readValue(backend, item) {
     for (let attempt = 0;; attempt++) {
         const head = readHead(backend, item);
         if (head === null)
             return null;
         const chunks = [head.first];
-        // Each chunk starts "c." so none begins with "-" and reads as an option.
         for (let index = 1; index < head.count; index++)
             chunks.push(/^c\.([A-Za-z0-9_-]+)$/.exec(backend.get(chunkItem(item, head.generation, index)) ?? "")?.[1] ?? "\u0000");
         const text = chunks.join("");
@@ -239,10 +186,6 @@ export function readValue(backend, item) {
             throw new SecretStoreError("A tool's stored secrets are damaged.");
     }
 }
-/**
- * Store `text` at `item`: the chunks of a new generation first, then the head that names them, then the old
- * generation's chunks are removed. `create`: only when nothing is stored there yet.
- */
 export function writeValue(backend, item, text, options = {}) {
     const encoded = Buffer.from(text, "utf8").toString("base64url");
     const generation = randomBytes(4).toString("hex");
@@ -260,7 +203,6 @@ export function writeValue(backend, item, text, options = {}) {
             backend.remove(chunkItem(item, stale.generation, index));
     return placed;
 }
-/** Remove what is stored at `item`, every chunk with it. */
 export function removeValue(backend, item) {
     let head = null;
     try {
@@ -274,18 +216,14 @@ export function removeValue(backend, item) {
         for (let index = 1; index < head.count; index++)
             backend.remove(chunkItem(item, head.generation, index));
 }
-// ---- Toolroll's own folder for secrets ----------------------------------------------------------------------------
-/** The folder's name, beside the database. */
 export const SECRET_FOLDER = "tool-secrets";
 const KEY_FILE = ".keychain-key";
-/** An anchor kept in this process alone: a test's own folder. */
 export function memoryAnchor() {
     let held = null;
     return { read: () => held, swap: (expected, next) => { if (held !== expected)
             return false; held = next; return true; } };
 }
 const folders = new Map();
-/** Roots whose folder was refused when Toolroll started: never prepared again in this process. */
 const refusedRoots = new Map();
 let standing = null;
 let standingProblem = null;
@@ -295,7 +233,6 @@ const mine = (info) => { const uid = myUid(); return uid === null || info.uid ==
 const pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 const codeOf = (error) => error.code;
 const refuse = (path, why, fix = "Remove it and restart Toolroll.") => { throw new SecretStoreError(`Secrets are switched off: ${path} ${why}. ${fix}`); };
-/** Every folder from `root` up: real folders, this user's or the system's, that nobody else can write. */
 function checkAncestors(root) {
     for (let folder = root;; folder = dirname(folder)) {
         const info = lstatSync(folder);
@@ -307,14 +244,12 @@ function checkAncestors(root) {
             return;
     }
 }
-/** A folder of Toolroll's own: a real folder (never a link), this user's, owner-only. */
 function checkOwnFolder(path, info) {
     if (info.isSymbolicLink() || !info.isDirectory())
         refuse(path, "isn't a folder Toolroll made");
     if (!mine(info) || (info.mode & 0o077) !== 0)
         refuse(path, "isn't owner-only");
 }
-/** `path` opened without following a link, as a plain owner-only file with one name; null when there is none. */
 function openOwnFile(path, flags) {
     let fd;
     try {
@@ -336,7 +271,6 @@ function openOwnFile(path, flags) {
     }
     return { fd, info };
 }
-/** The key in `file`: 32 bytes, read through openOwnFile; null when there is none. */
 function readKey(file) {
     const opened = openOwnFile(file, constants.O_RDONLY);
     if (opened === null)
@@ -351,7 +285,6 @@ function readKey(file) {
         closeSync(opened.fd);
     }
 }
-/** One preparer at a time, across processes: a lock file beside the folder, taken over when a dead one left it. */
 function withRootLock(root, work) {
     const lock = join(root, `.${SECRET_FOLDER}.lock`);
     for (let tries = 0;; tries++) {
@@ -412,14 +345,12 @@ function openFolder(stateDir, anchor, create, legacy) {
             info = lstatSync(dir);
         }
         else if (recorded === null && known === undefined && readdirSync(dir).length > 0) {
-            // Toolroll never made a key here, yet the folder holds something: put there by something else.
             refuse(dir, "wasn't made by Toolroll");
         }
         checkOwnFolder(dir, info);
         let key = readKey(keyFile);
         if (key !== null) {
             const digest = keyDigest(key);
-            // This process made it (a test's own folder, then Toolroll's start): recorded now.
             if (recorded === null && known?.digest === digest)
                 anchor.swap(null, digest);
             else if (digest !== recorded)
@@ -428,7 +359,6 @@ function openFolder(stateDir, anchor, create, legacy) {
         else {
             if (!create)
                 throw new SecretStoreError(NOT_READY);
-            // A new key: recorded first, then put in place whole (a crash in between leaves no key, and the next start makes one).
             key = randomBytes(32);
             if (!anchor.swap(recorded, keyDigest(key)))
                 throw new SecretStoreError("Toolroll's folder for secrets is being prepared elsewhere. Try again in a moment.");
@@ -453,11 +383,6 @@ function openFolder(stateDir, anchor, create, legacy) {
         return { root, dir, legacy, dev: info.dev, ino: info.ino, key, digest: keyDigest(key), anchor };
     });
 }
-/**
- * Prepare Toolroll's folder for secrets beside `stateDir` (the folder holding the database), checked against what
- * `anchor` recorded: made with its sealing key when it isn't there yet (`create`), refused when something else put a
- * folder, key or link there. `standing`: the folder this process uses by default (Toolroll's own start).
- */
 export function prepareSecretFolder(stateDir, anchor, options = {}) {
     let root = null;
     try {
@@ -484,12 +409,7 @@ export function prepareSecretFolder(stateDir, anchor, options = {}) {
         return { ok: false, problem };
     }
 }
-/** What a folder beside a database will be checked against, before it is first used (registerSecretFolder). */
 const pending = new Map();
-/**
- * Name Toolroll's folder for secrets (beside `stateDir`, the database's folder) and the record to check it against,
- * without touching it yet: it is prepared the first time a secret is used. `standing`: this process's default.
- */
 export function registerSecretFolder(stateDir, anchor, options = {}) {
     let root;
     try {
@@ -504,7 +424,6 @@ export function registerSecretFolder(stateDir, anchor, options = {}) {
     standing = root;
     standingProblem = null;
 }
-/** Still the folder that was checked: the same folder, still owner-only, its key unchanged. */
 function unchanged(folder) {
     try {
         const info = lstatSync(folder.dir);
@@ -517,10 +436,6 @@ function unchanged(folder) {
         return false;
     }
 }
-/**
- * Toolroll's folder for secrets, checked again now: the one prepared at start when `state` is absent, else the one
- * beside `state` (a test's own folder is prepared the first time it is used, against an anchor in this process).
- */
 export function secretFolder(state) {
     let root;
     if (state === undefined) {
@@ -542,28 +457,16 @@ export function secretFolder(state) {
     const known = folders.get(root);
     if (known !== undefined && unchanged(known))
         return known;
-    // A page visit prepares nothing (docs/plans/get-side-effects.md): the console prepares its folder as it starts, and
-    // an action checks a changed one again. Until then the page says secrets can't be read right now.
     if (inReadOnlyRequest())
         throw new SecretStoreError(NOT_READY);
-    // Changed since it was checked (or never seen): checked against the same record (the database's, for Toolroll's
-    // own folder; this process's, for a test's), and refused if it doesn't match.
     const named = pending.get(root);
     const again = prepareSecretFolder(root, known?.anchor ?? named?.anchor ?? memoryAnchor(), { create: true, legacy: known?.legacy ?? named?.legacy ?? null, standing: root === standing });
     if (!again.ok)
         throw new SecretStoreError(again.problem);
     return folders.get(root);
 }
-/** Forget every prepared folder (tests). */
 export function forgetSecretFolders() { folders.clear(); refusedRoots.clear(); pending.clear(); standing = null; standingProblem = null; }
-/** The keychain service for everything kept for this folder's Toolroll: its folder, hashed. Never a secret. */
 export const serviceOf = (folder) => `toolroll-tool-secrets.${createHash("sha256").update(folder.root).digest("hex").slice(0, 12)}`;
-// ---- files inside it ---------------------------------------------------------------------------------------------
-/**
- * A path inside `base` (the folder, or Toolroll's own folder above it), each folder on the way checked: a real folder
- * of this user's that nobody else can write, never a link. Made owner-only when `make` (else a missing one ends the
- * walk: nothing is there).
- */
 export function pathIn(base, parts, options = {}) {
     for (const part of parts)
         if (!SAFE.test(part) || part === "." || part === "..")
@@ -598,7 +501,6 @@ export function pathIn(base, parts, options = {}) {
     }
     return join(base, ...parts);
 }
-/** A file's text, read without following a link; null when there is none. Anything not plainly Toolroll's is refused. */
 export function readOwnFile(path) {
     const opened = openOwnFile(path, constants.O_RDONLY);
     if (opened === null)
@@ -618,7 +520,6 @@ export function readOwnFile(path) {
         closeSync(opened.fd);
     }
 }
-/** Write a file whole and owner-only: a new file beside it, then renamed over it, so a link or second name planted there is replaced, never written through. */
 export function writeOwnFile(path, text) {
     const staged = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.new`;
     const fd = openSync(staged, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
@@ -631,7 +532,6 @@ export function writeOwnFile(path, text) {
     }
     renameSync(staged, path);
 }
-/** A file's bytes overwritten, then the file removed (a link is only removed, never followed). */
 export function destroyOwnFile(path) {
     try {
         const opened = openOwnFile(path, constants.O_WRONLY);
@@ -644,7 +544,7 @@ export function destroyOwnFile(path) {
                 closeSync(opened.fd);
             }
     }
-    catch { /* removed below either way */ }
+    catch { }
     rmSync(path, { force: true });
     try {
         lstatSync(path);
@@ -664,17 +564,15 @@ const takeLock = (lock, staleMs) => {
     catch (error) {
         if (codeOf(error) !== "EEXIST")
             throw new SecretStoreError("A lock for Toolroll's secrets can't be made.");
-        // A lock left by a process that died is old: taken over.
         try {
             if (Date.now() - lstatSync(lock).mtimeMs > staleMs)
                 unlinkSync(lock);
         }
-        catch { /* gone already */ }
+        catch { }
         return false;
     }
 };
 const held = new Map();
-/** One change at a time to what `name` keeps, across Toolroll's processes (a lock file in the folder), re-entrant within one. */
 export function withSecretLock(folder, name, work) {
     const lock = lockFile(folder, name);
     if ((held.get(lock) ?? 0) > 0) {
@@ -700,7 +598,6 @@ export function withSecretLock(folder, name, work) {
         rmSync(lock, { force: true });
     }
 }
-/** The same, for work that waits on the network (renewing a sign-in): other processes wait for it, up to `waitMs`. */
 export async function withSecretLockAsync(folder, name, work, options = {}) {
     const lock = lockFile(folder, name), started = Date.now();
     while (!takeLock(lock, options.staleMs ?? 120_000)) {
@@ -715,17 +612,14 @@ export async function withSecretLockAsync(folder, name, work, options = {}) {
         rmSync(lock, { force: true });
     }
 }
-// ---- sealed with the folder's key ----------------------------------------------------------------------------------
 const SEALED = /^w1\.([A-Za-z0-9_-]+)$/;
 const aad = (item) => Buffer.from(`toolroll:tool-secret:v1:${item.service}/${item.account}`);
-/** `text` sealed for `item` with the folder's key. */
 export function seal(text, item, folder) {
     const iv = randomBytes(12);
     const cipher = createCipheriv("aes-256-gcm", folder.key, iv).setAAD(aad(item));
     const body = Buffer.concat([cipher.update(text, "utf8"), cipher.final()]);
     return `w1.${Buffer.concat([iv, cipher.getAuthTag(), body]).toString("base64url")}`;
 }
-/** What `seal` sealed for `item`; refused when it was sealed for another item, with another key, or changed. */
 export function unseal(sealed, item, folder) {
     const raw = SEALED.exec(sealed)?.[1];
     if (raw === undefined)
@@ -740,29 +634,20 @@ export function unseal(sealed, item, folder) {
         throw new SecretStoreError("A tool's stored secrets can't be opened; set them again on the Tools page.");
     }
 }
-/** The sealed text kept at `item`, opened; null when nothing is. */
 export function readSealed(backend, folder, item) {
     const text = readValue(backend, item);
     return text === null ? null : unseal(text, item, folder);
 }
-/** Keep `text` at `item`, sealed. */
 export function writeSealed(backend, folder, item, text, options = {}) {
     return writeValue(backend, item, seal(text, item, folder), options);
 }
-// ---- what Toolroll holds for integrations -------------------------------------------------------------------------
 const HELD_NAME = /^[a-z][a-z0-9-]{0,40}(\.[0-9]{1,12})?$/;
 const heldItem = (folder, name) => {
     if (!HELD_NAME.test(name))
         throw new SecretStoreError("A secret's address can't be used.");
     return { service: serviceOf(folder), account: `held.${name}` };
 };
-/**
- * A secret's file, as it was kept before the keychain, moved in: stored, read back and compared, and only then is the
- * file destroyed. What the keychain already holds (an earlier move, or a change since) wins over the file. A failure
- * leaves the file as it was, and says so.
- */
 function moveHeldIn(backend, folder, name, file) {
-    // A link, or a file not plainly Toolroll's, put where the old file was: kept as it is, and never used.
     let before;
     try {
         before = readOwnFile(file);
@@ -785,24 +670,18 @@ function moveHeldIn(backend, folder, name, file) {
             try {
                 removeValue(backend, item);
             }
-            catch { /* the file stays the copy that counts */ }
+            catch { }
             throw new SecretStoreError("A secret couldn't be moved to the keychain; it stays in its file until it can.");
         }
     }
     destroyOwnFile(file);
 }
-/**
- * A secret Toolroll holds for an integration, by `name` ("linear-key", "google-mail", "flow-hook.12"), for the
- * Toolroll whose folder is `state`. `file` (inside `state`) is where it was kept before, and still is where there's no
- * keychain. The first read or write with a keychain moves the file in.
- */
 export function readHeldSecret(state, name, file) {
     const folder = secretFolder(state);
     const path = pathIn(folder.root, file);
     const backend = secretBackend();
     if (backend === null)
         return readOwnFile(path);
-    // A page visit moves nothing and takes no lock (docs/plans/get-side-effects.md): the keychain, else the old file.
     if (inReadOnlyRequest())
         return readSealed(backend, folder, heldItem(folder, name)) ?? readOwnFile(path);
     return withSecretLock(folder, `held.${name}`, () => {
@@ -810,7 +689,6 @@ export function readHeldSecret(state, name, file) {
         return readSealed(backend, folder, heldItem(folder, name));
     });
 }
-/** Keep (or, with null, remove) a held secret: see readHeldSecret. */
 export function writeHeldSecret(state, name, file, value) {
     const folder = secretFolder(state);
     const path = pathIn(folder.root, file, { make: true });

package/dist/toolroll-update-cli.js

@@ -1,9 +1,3 @@
-/**
- * `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";
@@ -12,8 +6,6 @@ import { isNewer, latestVersionNow } from "./releases.js";
 import { databasePath } from "./store.js";
 import { PACKAGE_VERSION } from "./version.js";
 import { currentRuntime, lastCompletedUpdate, machineSystem, readRuntimeUpdate, requestRuntimeUpdateCancel, resumeRuntimeUpdate, retireUpdateJob, 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");
 }
@@ -65,7 +57,6 @@ export async function runUpdateCommand(args, write, deps = {}) {
         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.");

package/dist/toolroll-update-ui.js

@@ -1,29 +1,18 @@
-/**
- * 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" section afterwards. The work itself is the
- * `toolroll update` command (toolroll-update.ts), started as its own job.
- * Built from the revamp kit; the Settings frame adds the title.
- */
 import { html, joinHtml, postForm } from "./html.js";
 import { STEP_WORDS, UPDATE_STEPS, runtimeUpdateTerminal } from "./toolroll-update.js";
 import { btn, chip, codeLine, disclose, formRow, infoLine, note, notice, radios, settingsRecord, settingsSection } from "./server/kit.js";
 import { kitSectionForm } from "./settings-kit.js";
 const clock = (iso) => { const d = new Date(iso); return `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`; };
-/** The page is kit pieces now; nothing of the old look is left. Kept as an export for the shared stylesheet. */
 export const UPDATES_CSS = "";
-/** A step's state as one of the kit's status words. */
 const STEP_CHIP = {
     done: chip("Finished", "done"), now: chip("Running", "live"), failed: chip("Failed", "failed"), waiting: chip("Queued", ""),
 };
-/** The steps, each done, current, failed or waiting. Also the live region's fragment. */
 export function updateStepsHtml(j, running, options = {}) {
     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" && j.waiting ? html `${j.waiting.on}.${j.waiting.action ? html ` To have Toolroll check again, run <code class="k-mono">${j.waiting.action}</code>.` : ""}`
             : (state === "now" && step === "draining") || (state === "failed" && j.phase === "rolling-back") ? html `${j.detail}` : "";
         return settingsRecord({ title: STEP_WORDS[step], sub: detail, when: STEP_CHIP[state], attrs: { "data-step": step, "data-state": state } });
@@ -40,7 +29,6 @@ function outcomeHtml(j) {
     }
     if (j.phase === "cancelled")
         return settingsSection({ id: "update-outcome", title: "Update cancelled", body: html `<div data-update-outcome="cancelled">${note("Nothing changed.")}</div>` });
-    // Stopped on a finished run it can't show has ended: what is in the way and the one command, nothing more.
     if (j.phase === "refused" && j.waiting) {
         return settingsSection({ id: "update-outcome", title: `Update to ${j.to.version} stopped: run #${j.waiting.run} is in the way`,
             body: html `<div data-update-outcome="stopped">${infoLine(`${j.waiting.on}. New work resumed.`)}${j.waiting.action ? note(html `To have Toolroll check again, run <code class="k-mono">${j.waiting.action}</code>, then update again.`) : note("Update again once it has stopped.")}</div>` });
@@ -92,8 +80,6 @@ export function newerThan(a, b) {
             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="";` +