toolroll 0.9.103 → 0.9.105

package/dist/release-cli.js

@@ -1,15 +1,7 @@
-/**
- * `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";
@@ -94,14 +86,11 @@ Options
   --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", "--to", "--request", "--as", "--token", "--schedule", "--stage", "--lane-retire", "--branch"]);
 const BARE_FLAGS = new Set(["--new", "--json", "--help", "--yes", "--no-carry", "--start", "--recover-deploy", "--github"]);
 export async function runReleaseCommand(args, write, deps = {}) {
-    // The flag, not a secret's value that happens to read "--json".
-    // A secret is never exactly one of these names (the loop below refuses that as a missing value).
     const bare = new Set(args.filter(one => BARE_FLAGS.has(one)));
     const json = bare.has("--json");
     const refuse = (reason, message, code) => {
@@ -111,15 +100,11 @@ export async function runReleaseCommand(args, write, deps = {}) {
     const positional = [];
     const limits = {};
     let stage, laneRetire, laneAlias;
-    // `--branch <name>` (or `-- <name>`) names the branch outright, so a branch called "status", "nightly" or "carry" is
-    // still a branch and never one of this command's own words.
     let branchFlag, literal = false, branchFlags = 0;
-    // Only what follows `--` is literal: it never changes how the words before it read.
     const literalArgs = [];
     let repo, tap, gate, to, request, as, token, scheduleFlag;
     for (let i = 0; i < args.length; i += 1) {
         const raw = args[i];
-        // After `--`, every argument is a branch name, never a flag or a subcommand.
         if (raw === "--" && !literal) {
             literal = true;
             continue;
@@ -130,7 +115,6 @@ export async function runReleaseCommand(args, write, deps = {}) {
         }
         if (BARE_FLAGS.has(raw))
             continue;
-        // `--lane-alias <lane-id> <new name>`: two values, neither a flag of this command.
         if (raw === "--lane-alias") {
             const [id, name] = [args[i + 1], args[i + 2]];
             if (id === undefined || name === undefined || id.startsWith("--") || name.startsWith("--"))
@@ -139,12 +123,10 @@ export async function runReleaseCommand(args, write, deps = {}) {
             i += 2;
             continue;
         }
-        // `--flag=value` for every value flag; a secret (--token) is also the next argument even when it starts with "--".
         const equals = raw.startsWith("--") ? raw.indexOf("=") : -1;
         const arg = equals === -1 ? raw : raw.slice(0, equals);
         if (VALUE_FLAGS.has(arg)) {
             const value = equals === -1 ? args[i + 1] : raw.slice(equals + 1);
-            // A secret may start with "--"; it is the value unless it is exactly one of this command's flags (never swallowed).
             const namesFlag = value !== undefined && (BARE_FLAGS.has(value) || VALUE_FLAGS.has(value.split("=")[0]));
             if (value === undefined || (equals === -1 && value.startsWith("--") && (arg !== "--token" || namesFlag)))
                 return refuse("usage", `${arg} takes a value.`, 2);
@@ -212,20 +194,16 @@ export async function runReleaseCommand(args, write, deps = {}) {
         return runGithubNightlyCommand({ repo: repo === undefined ? undefined : resolve(deps.cwd ?? process.cwd(), repo), as, token, alias: laneAlias, retire: laneRetire }, write, json, deps);
     }
     const named = branchFlag !== undefined || literalArgs.length > 0;
-    // One branch, named one way: never a guess between two.
     if (branchFlags > 1 || literalArgs.length > 1 || (branchFlag !== undefined && (positional.length > 0 || literalArgs.length > 0)) || (literalArgs.length > 0 && positional.length > 0)) {
         return refuse("usage", "Name the branch once: `toolroll release <branch>`, `--branch <name>` or `-- <name>`, never two of them.", 2);
     }
     if (branchFlag !== undefined && branchFlag === "")
         return refuse("usage", "--branch takes a branch name.", 2);
-    // `release status [<task>]`: the steps recorded for a release. A branch named "status" is released with
-    // `--branch status` (or `-- status`).
     if (!named && positional[0] === "status" && positional.length <= 2) {
         if (args.some(arg => VALUE_FLAGS.has(arg.split("=")[0]) || ["--new", "--no-carry", "--start"].includes(arg)))
             return refuse("usage", "`toolroll release status [<task>]` takes only --json.", 2);
         return runStatusCommand(positional[1], write, json, deps);
     }
-    // `release approve` is the toolroll command's own (cli.ts routes it to the operate commands); never a branch here.
     if (!named && positional[0] === "approve")
         return refuse("usage", "Run `toolroll release approve [<branch>]`. A branch named approve is released with `--branch approve`.", 2);
     if (!named && positional[0] === "nightly" && positional.length === 1)
@@ -257,7 +235,6 @@ export async function runReleaseCommand(args, write, deps = {}) {
     const adapters = deps.adapters === undefined
         ? releaseAdapters({ checkout, say, ...(tap === undefined ? {} : { tap }), ...(limits["deploy"] === undefined ? {} : { deployMinutes: limits["deploy"] }) })
         : { ...deps.adapters, say };
-    // One command: wait out another run of this release, settle what a stopped deployment left, then go on from the journal.
     const taken = await takeReleaseRun(stateDir, branch, say, deps.runLock);
     if (!taken.ok)
         return refuse("running", `Another release of ${branch} is still running on ${taken.holder.host} (process ${taken.holder.pid}). Nothing was changed.`, 3);
@@ -293,10 +270,8 @@ function report(outcome, write, json, lines) {
         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");
@@ -307,12 +282,10 @@ function installedGateWorld() {
             db.exec("PRAGMA busy_timeout=5000");
             return db;
         },
-        // The laptop service too: two services on one database is a conflict the gate names, never one it skips.
         servicePlists: () => ["com.toolroll.browser", "com.standing-orders.browser", "com.toolroll.up"].map(label => join(agents, `${label}.plist`))
             .filter(path => existsSync(path)).map(path => ({ path, text: readFileSync(path, "utf8") })),
     };
 }
-/** The installation's deployments, its plane's records and the release's own recovery road, for --recover-deploy. */
 function installedRescueWorld(cwd) {
     const database = databasePath(process.env, homedir());
     const stateDir = dirname(database);
@@ -384,11 +357,6 @@ function runGateRelease(id, yes, write, json, world) {
         write(`Lift it: toolroll release --release-gate ${outcome.id} --yes`);
     return 0;
 }
-/**
- * The release's authority from the command line (release-once.md): ask for a carry (anyone may ask, the lead
- * included; only the rules decide), stop carrying (only ever stricter), or change the project's carry setting
- * (turning carrying back on is a person's own command, never the lead's or a remote token's).
- */
 async function runAuthorityCommand(command, target, flags, write, json, deps) {
     const name = `release ${command}`;
     const answer = (ok, fields, words, code) => {
@@ -406,8 +374,6 @@ async function runAuthorityCommand(command, target, flags, write, json, deps) {
                 return answer(false, { reason: "usage", message: "ask-every-commit takes on or off." }, "ask-every-commit takes on or off.", 2);
             if (flags.repo === undefined)
                 return answer(false, { reason: "usage", message: "Name the project with --repo <path>." }, "Name the project with --repo <path>.", 2);
-            // Turning carrying back on relaxes a release's rules: a person's own ceremony, as an approval needs (a password
-            // typed now, a re-check, or their own session), never a lead or remote token. Turning it off is only stricter.
             let actor = "cli";
             if (target === "off") {
                 const refused = (message) => answer(false, { reason: "person-only", message }, message, 1);
@@ -425,8 +391,6 @@ async function runAuthorityCommand(command, target, flags, write, json, deps) {
             return answer(true, { repo: flags.repo, ask: target === "on" }, words, 0);
         }
         if (command === "publish-ok") {
-            // A person's own decision to go on after an automatic release's checks stopped passing past its merge: never the
-            // lead, a remote token or a mode.
             const refused = (message) => answer(false, { reason: "person-only", message }, message, 1);
             if (machineActing() || process.env["TOOLROLL_LEAD_TOKEN"] !== undefined || process.env["TOOLROLL_REMOTE_TOKEN"] !== undefined)
                 return refused("Only a person lets a held release go on, never the lead or a remote token.");
@@ -449,9 +413,6 @@ async function runAuthorityCommand(command, target, flags, write, json, deps) {
             const repo = store.listProjects().map(one => one.path).find(path => path === flags.repo) ?? null;
             if (repo === null)
                 return answer(false, { reason: "not-found", message: "That isn't a project Toolroll knows." }, "That isn't a project Toolroll knows.", 1);
-            // Turning it on lets releases approve themselves: a credential act (docs/plans/passwordless.md), only a password
-            // typed now by an approver of this project — never the lead's token, an API token, a remembered login or a session.
-            // Turning it off only asks a person again, so it needs no password.
             let actor = flags.as ?? "cli";
             if (target === "on") {
                 const refused = (message) => answer(false, { reason: "person-only", message }, message, 1);
@@ -475,8 +436,6 @@ async function runAuthorityCommand(command, target, flags, write, json, deps) {
                 return answer(false, { reason: "usage", message: "unsandboxed-carry takes on or off." }, "unsandboxed-carry takes on or off.", 2);
             if (flags.repo === undefined)
                 return answer(false, { reason: "usage", message: "Name the project with --repo <path>." }, "Name the project with --repo <path>.", 2);
-            // Turning it on relaxes a release's rules: a person's own ceremony, as an approval needs, never a lead or remote
-            // token. Turning it off is only stricter.
             let actor = "cli";
             if (target === "on") {
                 const refused = (message) => answer(false, { reason: "person-only", message }, message, 1);
@@ -513,7 +472,6 @@ async function runAuthorityCommand(command, target, flags, write, json, deps) {
         store.close();
     }
 }
-/** `toolroll release nightly`: the nightly full check on main, approved with a person's password (nightly-check.ts). */
 async function runNightlyCommand(flags, write, json, deps) {
     const answer = (ok, fields, words, code) => { write(json ? checkedEnvelopeJson({ ok, command: "release nightly", ...fields }) : words); return code; };
     if (flags.repo === undefined)
@@ -538,8 +496,6 @@ async function runNightlyCommand(flags, write, json, deps) {
         store.close();
     }
 }
-/** `toolroll release nightly --github | --lane-alias | --lane-retire`: GitHub's nightly as release debt
- * (nightly-github.ts), each a person's step proved with their password now. */
 async function runGithubNightlyCommand(flags, write, json, deps) {
     const answer = (ok, fields, words, code) => { write(json ? checkedEnvelopeJson({ ok, command: "release nightly", ...fields }) : words); return code; };
     if (flags.repo === undefined)
@@ -569,7 +525,6 @@ async function runGithubNightlyCommand(flags, write, json, deps) {
         store.close();
     }
 }
-/** `toolroll release status [<task>]` (read-only): the release's recorded steps (store.ts release_step, v146). */
 async function runStatusCommand(task, write, json, deps) {
     const command = "release status";
     const refuse = (reason, message, code) => { write(json ? checkedEnvelopeJson({ ok: false, command, reason, message }) : message); return code; };
@@ -593,7 +548,6 @@ async function runStatusCommand(task, write, json, deps) {
         const word = { running: "running", waiting: "waiting", done: "done", failed: "failed" };
         write(`Release ${progress.version} (${progress.tag})${progress.pr === null ? "" : ` · pull request #${progress.pr}`} · task ${taskId}`);
         for (const one of steps) {
-            // A failure the release has gone on from is history, as on the task page.
             const passed = one.state === "failed" && progress.stopped === null;
             write(`  ${one.step.padEnd(9)} ${(passed ? "went on" : word[one.state]).padEnd(8)} ${one.seconds === null ? "–" : dur(one.seconds)}${one.detail === null ? "" : `  ${one.detail}`}`);
         }

package/dist/release-coverage.js

@@ -1,19 +1,10 @@
-/** Whether a release check already covers a result whose checks were Off: a
- * passing FULL release check (run_check.release) on the same project whose
- * checked commit contains the result's commit. Read at read time from the
- * existing records and Git; nothing is written back, so no proof, receipt,
- * scope digest or schema changes. Fails closed: a receipt that can't be read,
- * a missing commit or any Git error leaves the result uncovered. */
 import { viewedGitSync } from "./teardown-git.js";
 import { verificationEvidence } from "./verification-evidence.js";
 import { runCheckLevel } from "./check-levels.js";
-/** How many of the newest passing release checks one read considers. */
 export const RELEASE_SCAN_LIMIT = 20;
 const SHA = /^[a-f0-9]{40}$/;
-/** Ancestry between two fixed commits never changes, so a settled answer is kept; errors are not. */
 const ancestry = new Map();
 const ANCESTRY_LIMIT = 4096;
-/** `git merge-base --is-ancestor`: true, false, or null when Git couldn't say. */
 export const gitIsAncestor = (repo, ancestor, descendant) => {
     if (!SHA.test(ancestor) || !SHA.test(descendant))
         return null;
@@ -25,14 +16,12 @@ export const gitIsAncestor = (repo, ancestor, descendant) => {
         return known;
     let answer;
     try {
-        // Every git version through a frozen read view, bounded (eval-harness review 1, finding 7).
         const status = viewedGitSync(repo, ["merge-base", "--is-ancestor", ancestor, descendant], { timeoutMs: 5_000, binding: { repo } }).status;
         if (status !== 0)
             throw Object.assign(new Error("git merge-base"), { status });
         answer = true;
     }
     catch (error) {
-        // Exit 1 is Git's "no"; anything else (a missing object, no repository, a timeout) is no answer.
         answer = error.status === 1 ? false : null;
     }
     if (answer !== null) {
@@ -42,8 +31,6 @@ export const gitIsAncestor = (repo, ancestor, descendant) => {
     }
     return answer;
 };
-/** The newest passing full release checks of one project, each with its sealed, verified commit. Read once per
- * caller-held memo, so a list of results reads the receipts once. */
 function passingReleases(store, root, repo) {
     let rows;
     try {
@@ -58,7 +45,6 @@ function passingReleases(store, root, repo) {
     return rows.flatMap(row => {
         const run = Number(row["run"]);
         try {
-            // Full only: a quick or Off release check covers nothing.
             const level = runCheckLevel(store, run);
             if (level !== null && level !== "full")
                 return [];
@@ -66,7 +52,6 @@ function passingReleases(store, root, repo) {
             if (!gate.ok || gate.bytes === null)
                 return [];
             const receipt = JSON.parse(gate.bytes);
-            // A release check whose coverage is partial or lost a required test covers nothing.
             if (receipt.coverage !== undefined && receipt.coverage !== "full" && receipt.coverage !== "composed")
                 return [];
             const head = store.getRun(run)?.headRevision ?? null;
@@ -83,7 +68,6 @@ function passingReleases(store, root, repo) {
         }
     });
 }
-/** The release check covering `head` in `repo`, or null. `memo` keeps one read's receipts. */
 export function releaseCoverageOf(store, root, repo, head, options = {}) {
     if (root === undefined || repo === null || head === null || !SHA.test(head))
         return null;

package/dist/release-gate.js

@@ -1,42 +1,18 @@
-/**
- * `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 exit recovery never ran. The typical case is a deployment
- * killed outright (SIGKILL, a crash or power loss) while paused: nothing lifted the pause, 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";
 import { acquireDeploymentLock } from "./deploy-lock.js";
 import { BEFORE_SWAP, RELEASED } from "./deploy-phase.js";
-/** The journal phases a deployment passes before it stops the old service (deploy-phase.ts, the one table). */
 export { BEFORE_SWAP };
-/** Journal fields that only the swap and later phases write. */
 const SWAP_FIELDS = ["stoppingService", "codingBackupBeforeSwap", "migration", "newService", "deployedAt", "launchd", "newServiceStop"];
 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. */
 export function journals(stateDir) {
     const root = join(stateDir, "staged-upgrades");
     let stages = [];
@@ -56,7 +32,6 @@ export function journals(stateDir) {
         }
     });
 }
-/** 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.`);
@@ -122,7 +97,6 @@ export function proveBeforeSwap(id, world) {
     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`));
-    // The database as a whole argument: an `up` on a path that only begins with this database's is another service's.
     const upHere = `${r.priorRuntime}/cli.js up --db ${world.database}`;
     const worker = processes.find(one => one.command.split(upHere).slice(1).some(rest => rest === "" || /^\s/.test(rest)));
     if (supervisor === undefined || worker === undefined)
@@ -130,9 +104,7 @@ export function proveBeforeSwap(id, world) {
     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) {
-    // Discovery is not authority to remove anything. Dry-run remains read-only, even for legacy stages.
     const discovered = proveBeforeSwap(id, world);
     if (!discovered.ok)
         return discovered;
@@ -154,7 +126,6 @@ export function releaseGate(id, world, yes) {
             return refuse("conflict", "The deployment stage changed during release.");
         const db = world.open();
         try {
-            // Repeat the entire proof at the mutation boundary, under the same exclusion as deploy/resume/recover.
             const fresh = proveBeforeSwap(id, world);
             if (!fresh.ok)
                 return fresh;
@@ -163,7 +134,6 @@ export function releaseGate(id, world, yes) {
                 return refuse("conflict", "The deployment journal changed during release.");
             }
             lock.assertHeld(journalFile);
-            // The owner is checked again within removeUpdateGate's short write transaction.
             removeUpdateGate(db, id);
             durableJson(journalFile, {
                 ...fresh.journal, phase: RELEASED, updatedAt: world.now().toISOString(),

package/dist/release-git.js

@@ -1,14 +1,7 @@
-/**
- * The release coordinator's Git, as one hardened runner's pieces (docs/plans/chat-management.md §0a.2): the recorded
- * repository's shape, the programs by absolute path, the allowlisted environment, the fixed settings and the checkout
- * config allowlist. Kept apart from release-adapters.ts so the release card (release-card.ts) reads Git the same way
- * without loading the coordinator.
- */
 import { accessSync, constants as fsConstants, statSync } from "node:fs";
 import { delimiter, isAbsolute, join } from "node:path";
 import { HARDENED_GIT_ARGS } from "./agent-fence.js";
 import { TEARDOWN_FLAGS } from "./teardown-git.js";
-/** owner/name and transport of a recorded GitHub remote, read strictly (https or ssh to github.com, nothing else). */
 export function releaseRemote(url) {
     const part = "([A-Za-z0-9_.-]+)";
     const https = new RegExp(`^https://github\\.com/${part}/${part}?(?:\\.git)?/?$`).exec(url);
@@ -25,10 +18,7 @@ const executable = (path) => { try {
 catch {
     return false;
 } };
-/** Fixed system folders: the only PATH the coordinator's Git and gh run with. */
 export const RELEASE_PATH = "/usr/bin:/bin:/usr/sbin:/sbin";
-/** Git, gh and ssh by absolute path: the system's Git (or the first in the fixed system folders), the installed gh as
- * this process's PATH finds it now, and the system ssh. Resolved once; never looked up again. */
 export function releaseTools(path = process.env["PATH"] ?? "") {
     const find = (name, dirs) => {
         for (const dir of dirs) {
@@ -47,7 +37,6 @@ export function releaseTools(path = process.env["PATH"] ?? "") {
         ssh: find("ssh", ["/usr/bin", "/bin"]) ?? "/usr/bin/ssh",
     };
 }
-/** The coordinator's Git and gh environment: an allowlist, a fixed PATH, no system or global Git config, no prompts. */
 export function releaseGitEnv(base = process.env) {
     const kept = ["HOME", "LANG", "LC_ALL", "LC_CTYPE", "TMPDIR", "USER", "LOGNAME", "SSH_AUTH_SOCK", "GH_CONFIG_DIR", "XDG_CONFIG_HOME", "GH_TOKEN", "GITHUB_TOKEN", "GH_HOST"];
     return {
@@ -55,25 +44,15 @@ export function releaseGitEnv(base = process.env) {
         PATH: RELEASE_PATH, GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", GIT_TERMINAL_PROMPT: "0", GH_PROMPT_DISABLED: "1", GIT_ASKPASS: "", SSH_ASKPASS: "",
     };
 }
-/** Every coordinator Git command's fixed settings, ahead of its own arguments: the recorded Git directory and checkout,
- * no hooks, fsmonitor, replacement objects, pager or submodule recursion, only https (and ssh for an ssh remote), the
- * system ssh, and gh as the only credential helper. */
 export function releaseGitArgs(repo, tools) {
     return [`--git-dir=${repo.gitDir}`, `--work-tree=${repo.checkout}`, "--no-replace-objects", "--no-pager", ...HARDENED_GIT_ARGS, ...TEARDOWN_FLAGS,
         "-c", "protocol.allow=never", "-c", "protocol.https.allow=always", ...(repo.ssh ? ["-c", "protocol.ssh.allow=always"] : []),
         "-c", `core.sshCommand=${tools.ssh}`, "-c", "core.askPass=", "-c", "fetch.recurseSubmodules=false", "-c", "core.pager=cat",
-        // Where it connects and what it sends: verified TLS, no proxy, no extra header or cookie file. (An empty CA file
-        // or path can't be given here, Git then trusts nothing; a checkout setting either stops the release instead.)
         "-c", "http.sslVerify=true", "-c", "http.proxy=", "-c", "http.extraHeader=", "-c", "http.cookieFile=",
-        // The recorded URL, as a remote that exists only here.
         "-c", `remote.${RELEASE_REMOTE}.url=${repo.remote}`, "-c", `remote.${RELEASE_REMOTE}.pushurl=${repo.remote}`, "-c", `remote.${RELEASE_REMOTE}.proxy=`,
         ...(repo.ssh ? [] : ["-c", `credential.helper=!'${tools.gh.replace(/'/g, "'\\''")}' auth git-credential`])];
 }
-/** The named remote the coordinator fetches, looks and pushes through: defined only on its own command line (`-c`), so
- * no checkout setting names or rewrites it. */
 export const RELEASE_REMOTE = "toolroll-release";
-/** The local and worktree settings a gate checkout may hold for a release (an allowlist): plain values Git writes
- * itself and that never decide where it connects, what it sends or what it runs. Anything else stops the release. */
 const RELEASE_KEYS = [
     /^core\.(repositoryformatversion|filemode|bare|logallrefupdates|ignorecase|precomposeunicode|symlinks|autocrlf|eol|safecrlf|quotepath|longpaths|checkstat|trustctime)$/,
     /^extensions\.(worktreeconfig|objectformat|refstorage)$/,
@@ -81,9 +60,6 @@ const RELEASE_KEYS = [
     /^branch\..+\.(remote|merge|rebase|pushremote|description|vscode-merge-base)$/,
     /^(user\.(name|email)|pull\.(rebase|ff)|init\.defaultbranch|lfs\.repositoryformatversion)$/,
 ];
-/** The first local or worktree setting a gate checkout's config holds that a release won't run with, or null: one
- * outside the allowlist (an include, a command, a proxy, TLS or header setting, a credential helper, a URL rewrite, a
- * hooks folder), a remote named like a URL or after the coordinator's own, or a remote over a transport helper. */
 export function releaseConfigProblem(listing) {
     const fields = listing.split("\0");
     for (let at = 0; at + 1 < fields.length; at += 2) {

package/dist/release-links.js

@@ -1,17 +1,7 @@
-/**
- * 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)) {
@@ -34,7 +24,6 @@ export function findCliLinks(path = process.env["PATH"] ?? "", names = CLI_NAMES
         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);
@@ -58,11 +47,6 @@ const real = (path) => { try {
 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)
@@ -89,7 +73,6 @@ export function switchCliLinks(links, bin, answers) {
         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)

package/dist/release-net.js

@@ -1,4 +1,3 @@
-/** How long one call may keep asking, and how far apart. */
 export const NET_RETRY_BUDGET_MS = 180_000;
 export const NET_RETRY_MAX_ATTEMPTS = 12;
 const BACKOFF_MS = [2_000, 4_000, 8_000, 16_000, 30_000];
@@ -18,17 +17,13 @@ function retryBudget(options) {
     return { remaining, sleep: async (ms) => {
             const before = remaining();
             await options.sleep(ms);
-            // A frozen/backward fake clock must not grant more backoff than a real clock.
             const elapsed = before - remaining();
             left = Math.max(0, left - Math.max(0, ms - elapsed));
         } };
 }
 const exhausted = () => ({ code: 124, stdout: "", stderr: "the network retry budget ran out" });
-/** Secondary rate limit or 429: transient, and GitHub may say how long to wait. */
 const RATE_LIMITED = /secondary rate limit|abuse detection|HTTP 429|Too Many Requests/i;
-/** A definitive answer: GitHub (or git) answered, and the answer is no. Checked before the transient phrases. */
 const DEFINITIVE = /Toolroll won't run Git|Not Found|Unauthorized|Forbidden|Bad Request|Bad credentials|Requires authentication|authentication required|Authentication failed|Permission denied|Repository not found|Resource not accessible|Must have admin rights|could not read Username|not protected|not enabled|Reference already exists|Validation Failed|Head branch was modified|not mergeable|API rate limit exceeded|GH00[136]|protected branch update failed|\[rejected\]|updates were rejected|stale info|required status check|repository rule violations/i;
-/** Transport failures and server-side trouble: nothing was answered yet. */
 const TRANSIENT = new RegExp([
     "error connecting to", "Could not resolve host", "no such host", "Temporary failure in name resolution", "nodename nor servname",
     "Connection refused", "Connection reset", "connection reset by peer", "Failed to connect to", "Couldn't connect to server", "Network is unreachable", "No route to host",
@@ -37,19 +32,12 @@ const TRANSIENT = new RegExp([
     "unexpected end of JSON input", "invalid character .{1,12} looking for beginning of value", "Unexpected end of JSON input",
     "HTTP 5\\d\\d", "returned error: 5\\d\\d", "\\b50[0234] (?:Internal Server Error|Bad Gateway|Service Unavailable|Gateway Timeout)", "Server Error", "Bad Gateway", "Service Unavailable", "Gateway Timeout",
 ].join("|"), "i");
-/**
- * Whether a failure (its words, and the exit code when it came from a program) is transient: the phrase worth saying,
- * and how long GitHub asked to wait (Retry-After) when it said. Null for a definitive answer or anything unknown —
- * an unknown failure is never retried.
- */
 export function transientFailure(text, code) {
     if (code === 127)
         return null;
     if (DEFINITIVE.test(text))
         return null;
     const limited = RATE_LIMITED.exec(text);
-    // A rate-limit hint never overrides an independent refusal. Only 403/429 may
-    // describe a secondary limit; git prints HTTP errors differently from gh.
     const statuses = [...text.matchAll(/(?:HTTP(?:\/[\d.]+)?\s+|returned error:\s*)(4\d\d)\b/gi)].map(match => Number(match[1]));
     if (statuses.some(status => limited === null || (status !== 403 && status !== 429)))
         return null;
@@ -58,20 +46,16 @@ export function transientFailure(text, code) {
         return { words: limited[0], retryAfterMs: after === null ? null : Number(after[1]) * 1000 };
     }
     const found = TRANSIENT.exec(text);
-    // The phrase and the rest of its line ("Could not resolve host: github.com"), kept short.
     if (found !== null)
         return { words: text.slice(found.index).split("\n")[0].trim().slice(0, 80), retryAfterMs: null };
-    // The coordinator's own time limit on the child (exec answers 124 when it killed it).
     if (code === 124)
         return { words: "the call timed out", retryAfterMs: null };
     return null;
 }
 const failureText = (result) => `${result.stderr}\n${result.stdout}`;
-/** Whether one exec result failed transiently (exit 0 never did, unless its answer doesn't parse; see readOnlyCall). */
 export function transientResult(result) {
     return result.code === 0 ? null : transientFailure(failureText(result), result.code);
 }
-/** The git subcommand among the arguments: the first that isn't an option or an option's value. */
 function gitSubcommand(args) {
     for (let at = 0; at < args.length; at++) {
         const arg = args[at];
@@ -90,12 +74,6 @@ function gitSubcommand(args) {
     }
     return null;
 }
-/**
- * Whether a call only reads (and so may be asked again blindly): `git ls-remote` and `git fetch` (which only moves the
- * coordinator's own remote-tracking refs); REST repository `gh api` reads with only the flags below (gh turns
- * fields or input into a POST); `gh pr list|view|checks`, `gh release view`, `gh repo view`. Anything else is a write, or
- * unknown, and is never retried by `retryingExec`.
- */
 export function readOnlyCall(command, args) {
     const name = command.split("/").pop() ?? command;
     if (name === "git") {
@@ -108,8 +86,6 @@ export function readOnlyCall(command, args) {
         let endpoint = null, shaped = false;
         for (let at = 1; at < args.length; at++) {
             const arg = args[at];
-            // Parse only spellings we know. In particular, pflag accepts -iXPOST and -ifbody=...;
-            // a blacklist of tokens beginning with -X/-f cannot prove those calls read-only.
             if (arg === "--paginate" || arg === "--slurp") {
                 shaped = true;
                 continue;
@@ -139,7 +115,6 @@ export function readOnlyCall(command, args) {
     const shaped = args.some(arg => arg === "--jq" || arg === "-q" || arg === "--template" || arg === "-t" || /^--(?:jq|template)=/.test(arg));
     return { kind: "gh", jsonBody: !shaped && args.some(arg => arg === "--json" || arg.startsWith("--json=")) };
 }
-/** A short name for a call, said once when it is asked again: `gh api repos/…/check-runs`, `git ls-remote`. */
 export function callLabel(command, args) {
     const name = command.split("/").pop() ?? command;
     if (name === "git")
@@ -150,12 +125,6 @@ export function callLabel(command, args) {
     }
     return `gh ${args.slice(0, 2).join(" ")}`;
 }
-/**
- * An Exec that asks a read again after a transient failure, with backoff, for up to `budgetMs` (about three minutes)
- * and `maxAttempts` calls; it says why once per call. When the budget runs out it answers the FIRST failure, exactly as
- * the program gave it, so the caller stops with the original error. A definitive answer or a success is returned at
- * once. A call that isn't provably a read (readOnlyCall) is passed straight through, never retried.
- */
 export function retryingExec(run, options) {
     return async (command, args, execOptions) => {
         const read = readOnlyCall(command, args);
@@ -166,7 +135,6 @@ export function retryingExec(run, options) {
         }), callLabel(command, args), options, read.jsonBody);
     };
 }
-/** Whether a 0-exit plain JSON body parses; a truncated one is a transient failure. */
 const bodyParses = (stdout) => { try {
     JSON.parse(stdout);
     return true;
@@ -174,8 +142,6 @@ const bodyParses = (stdout) => { try {
 catch {
     return false;
 } };
-/** One read, asked again as retryingExec describes. `call` may do more than the read itself (the release's Git
- * re-checks the checkout's config first); anything it throws ends the read at once. */
 export async function retryCall(call, label, options, jsonBody = false) {
     const budget = retryBudget(options);
     const maxAttempts = options.maxAttempts ?? NET_RETRY_MAX_ATTEMPTS;
@@ -190,7 +156,6 @@ export async function retryCall(call, label, options, jsonBody = false) {
             why = { words: "an answer cut short", retryAfterMs: null };
         if (why === null)
             return result;
-        // The original failure is what the caller sees; a truncated 0-exit body becomes an explicit failure.
         first ??= result.code !== 0 ? result : { code: 1, stdout: result.stdout, stderr: "unexpected end of JSON input (GitHub's answer was cut short)" };
         const wait = why.retryAfterMs ?? netBackoff(attempt);
         if (attempt + 1 >= maxAttempts || wait >= budget.remaining())
@@ -200,13 +165,6 @@ export async function retryCall(call, label, options, jsonBody = false) {
         await budget.sleep(wait);
     }
 }
-/**
- * A write that may be asked again only once GitHub says it didn't happen (idempotency). `write` makes the call;
- * `accept` reads a successful answer into the value (a SyntaxError there is an answer cut short: transient);
- * `refuse` throws for a failure. After a transient failure, `recheck` reads the state (its own reads retried): `done`
- * with the value when the write happened, `not-done` when it provably didn't (only then is it asked again), and
- * anything else — or a recheck that can't read — stops with the write's original error.
- */
 export async function writeWithRecheck(label, options, steps) {
     const budget = retryBudget(options);
     const maxAttempts = options.maxAttempts ?? NET_RETRY_MAX_ATTEMPTS;