faberun 0.3.0

package/src/cli/setup.mjs

@@ -0,0 +1,294 @@
+/**
+ * `faberun setup [--yes] [--harnesses a,b] [--worker <id>] [--judge <id>]
+ * [--json]`: onboard a fresh machine.
+ *
+ * It checks the two host prerequisites, discovers the catalogue runtimes
+ * through the same `discoverRuntimes` the engine uses, asks which harnesses to
+ * enable and which runtime is the default worker and judge, and writes the user
+ * config at `$FABERUN_HOME/config.json`. The judge must resolve to a vendor
+ * other than the worker's; the prompt refuses a same-vendor answer once and the
+ * command fails on the second.
+ *
+ * Discovery and the question function are injected so tests never touch a real
+ * binary or a terminal. `--json` never asks: it reports the same facts as one
+ * object and takes the defaults or the flags.
+ */
+import { createInterface } from "node:readline/promises";
+import {
+  DISCOVERY_RUNTIME_DEFINITIONS,
+  availableCandidates,
+  cheapest,
+  discoverRuntimes,
+  strongest,
+} from "../engine/runtime-discovery.mjs";
+import { boundedGitSync } from "../repo/worktree.mjs";
+import { colorLevel, renderBanner, statusToken } from "./brand.mjs";
+import { packageVersion } from "../host/package.mjs";
+import { configPath, faberunHome } from "../host/home.mjs";
+import { writeUserConfig } from "../host/config.mjs";
+
+/** @typedef {import("../engine/runtime-discovery.mjs").RuntimeAvailability} RuntimeAvailability */
+/** @typedef {import("../host/config.mjs").UserConfig} UserConfig */
+/** @typedef {(text: string) => void} Writer */
+/** @typedef {(question: string) => Promise<string>} Asker */
+/** @typedef {{id: string, harness: string, model: string, available: boolean, status: string, missing: string[]}} RuntimeView */
+/** @typedef {{ask: Asker, close: () => void}} AskerHandle */
+/**
+ * @typedef {object} SetupOptions
+ * @property {boolean} [yes]
+ * @property {string} [harnesses]
+ * @property {string} [worker]
+ * @property {string} [judge]
+ * @property {boolean} [json]
+ * @property {NodeJS.ProcessEnv} [env]
+ * @property {() => Promise<Record<string, RuntimeAvailability>>} [discover]
+ * @property {Asker} [ask]
+ * @property {Writer} [stdout]
+ * @property {Writer} [stderr]
+ * @property {boolean} [isTTY]
+ */
+
+/** Node major version the tool requires; `package.json#engines` says the same. */
+const MIN_NODE_MAJOR = 22;
+
+/** The harnesses a fresh machine can install, named in the failure hint. */
+const INSTALL_HARNESSES = ["claude", "codex", "agy", "dsh", "zcode"];
+
+/**
+ * @param {SetupOptions} [options]
+ * @returns {Promise<number>} the process exit code
+ */
+export async function setupCommand(options = {}) {
+  const env = options.env ?? process.env;
+  const stdout = options.stdout ?? ((text) => process.stdout.write(text));
+  const stderr = options.stderr ?? ((text) => process.stderr.write(text));
+  const json = options.json === true;
+  const yes = options.yes === true;
+  const isTTY = options.isTTY ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const level = colorLevel(env, isTTY);
+  const discover = options.discover ?? (() => discoverRuntimes(DISCOVERY_RUNTIME_DEFINITIONS));
+
+  const availability = await discover();
+  const runtimes = runtimeViews(availability, env);
+  const availableHarnesses = [...new Set(runtimes.filter((view) => view.available).map((view) => view.harness))];
+  const requirements = [nodeRequirement(), gitRequirement()];
+
+  if (isTTY && !json) {
+    stdout(renderBanner({
+      version: packageVersion(),
+      // DESIGN.md draws `node 26.8.1`; `process.version` is `v26.8.1`.
+      nodeVersion: process.version.replace(/^v/u, ""),
+      harnessCount: availableHarnesses.length,
+      level,
+      env,
+    }));
+  }
+
+  if (json) {
+    // `--json` never asks and never paints; the object below is the whole
+    // report, whether setup succeeds or stops at a check.
+  } else {
+    for (const requirement of requirements) {
+      stdout(`${statusToken(requirement.ok ? "ok" : "fail", level)} ${requirement.name} · ${requirement.detail}\n`);
+    }
+  }
+
+  if (requirements.some((requirement) => !requirement.ok)) {
+    if (json) stdout(`${JSON.stringify({ requirements, runtimes, config: null }, null, 2)}\n`);
+    return 1;
+  }
+
+  if (!json) {
+    for (const view of runtimes) {
+      const missing = view.missing.length ? ` · set ${view.missing.join(", ")}` : "";
+      stdout(`${statusToken(runtimeToken(view), level)} ${view.id} · ${view.status} · ${view.harness} · ${view.model}${missing}\n`);
+    }
+  }
+
+  if (availableHarnesses.length === 0) {
+    if (json) {
+      stdout(`${JSON.stringify({ requirements, runtimes, config: null }, null, 2)}\n`);
+    } else {
+      stdout(`${statusToken("fail", level)} harnesses · none available · install one of: ${INSTALL_HARNESSES.join(", ")}\n`);
+    }
+    return 1;
+  }
+
+  const candidates = availableCandidates(DISCOVERY_RUNTIME_DEFINITIONS, availability);
+  const defaultWorker = cheapest(candidates)?.id ?? "";
+  const interactive = isTTY && !json && !yes
+    && options.harnesses === undefined && options.worker === undefined && options.judge === undefined;
+
+  /** @type {string[]} */
+  let selectedHarnesses;
+  let selectedWorker;
+  let selectedJudge;
+  const asker = makeAsker(options.ask);
+  try {
+    if (interactive) {
+      const harnessAnswer = (await asker.ask(`Enable which harnesses? [${availableHarnesses.join(", ")}] `)).trim();
+      selectedHarnesses = splitHarnesses(harnessAnswer).length ? splitHarnesses(harnessAnswer) : availableHarnesses;
+
+      const workerAnswer = (await asker.ask(`Default worker runtime? [${defaultWorker}] `)).trim();
+      selectedWorker = workerAnswer || defaultWorker;
+
+      let judgeAnswer = (await asker.ask(`Default judge runtime? [${defaultJudge(selectedWorker, candidates)}] `)).trim();
+      let judge = judgeAnswer || defaultJudge(selectedWorker, candidates);
+      if (!crossVendor(judge, selectedWorker)) {
+        stderr("the judge must come from a different vendor than the worker\n");
+        judgeAnswer = (await asker.ask(`Default judge runtime? [${defaultJudge(selectedWorker, candidates)}] `)).trim();
+        judge = judgeAnswer || defaultJudge(selectedWorker, candidates);
+        if (!crossVendor(judge, selectedWorker)) return 1;
+      }
+      selectedJudge = judge;
+    } else {
+      selectedHarnesses = splitHarnesses(options.harnesses ?? "").length ? splitHarnesses(options.harnesses ?? "") : availableHarnesses;
+      selectedWorker = options.worker ?? defaultWorker;
+      selectedJudge = options.judge ?? defaultJudge(selectedWorker, candidates);
+      if (!crossVendor(selectedJudge, selectedWorker)) {
+        if (json) stdout(`${JSON.stringify({ requirements, runtimes, config: null }, null, 2)}\n`);
+        else stdout(`${statusToken("fail", level)} judge · the judge must come from a different vendor than the worker\n`);
+        return 1;
+      }
+    }
+  } finally {
+    asker.close();
+  }
+
+  const config = {
+    schemaVersion: /** @type {1} */ (1),
+    harnesses: selectedHarnesses,
+    worker: selectedWorker,
+    judge: selectedJudge,
+    updatedAt: new Date().toISOString(),
+  };
+  writeUserConfig(env, config);
+
+  if (json) {
+    stdout(`${JSON.stringify({ requirements, runtimes, config }, null, 2)}\n`);
+    return 0;
+  }
+  stdout(`${statusToken("ok", level)} config · ${configPath(faberunHome(env))}\n`);
+  stdout("next · faberun init in a repository · faberun doctor\n");
+  return 0;
+}
+
+/**
+ * One discovery line's token: an available runtime is a pass, a binary that is
+ * absent is a failure, and every other reason (quota, balance, auth, provider
+ * error) is a warning.
+ *
+ * @param {RuntimeView} view
+ * @returns {"ok"|"warn"|"fail"}
+ */
+function runtimeToken(view) {
+  if (view.available) return "ok";
+  return view.status === "not_found" ? "fail" : "warn";
+}
+
+/**
+ * @param {Record<string, RuntimeAvailability>} availability
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {RuntimeView[]}
+ */
+function runtimeViews(availability, env) {
+  return Object.entries(DISCOVERY_RUNTIME_DEFINITIONS).map(([id, definition]) => {
+    const state = availability[id];
+    const available = state?.available === true;
+    return {
+      id,
+      harness: definition.harness,
+      model: definition.model,
+      available,
+      status: available ? "available" : (state?.reason ?? "provider_unavailable"),
+      missing: missingEnvKeys(definition, env),
+    };
+  });
+}
+
+/**
+ * The env var names a runtime's own config declares through an `*.env_key` and
+ * the process environment does not set. Discovery already reports the
+ * authentication reason; naming the variable is what makes it fixable.
+ *
+ * @param {import("../engine/runtime-discovery.mjs").DiscoveryRuntime} runtime
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string[]}
+ */
+function missingEnvKeys(runtime, env) {
+  /** @type {string[]} */
+  const names = [];
+  for (const [key, value] of Object.entries(runtime.config ?? {})) {
+    if (!key.endsWith(".env_key")) continue;
+    if (typeof value === "string" && value.length > 0 && !env[value]) names.push(value);
+  }
+  return [...new Set(names)];
+}
+
+/**
+ * The strongest available runtime whose vendor differs from the worker's. An
+ * empty string means no cross-vendor runtime is available, which the caller
+ * turns into a refusal.
+ *
+ * @param {string} workerId
+ * @param {import("../engine/runtime-discovery.mjs").RuntimeCandidate[]} candidates
+ * @returns {string}
+ */
+function defaultJudge(workerId, candidates) {
+  const vendor = DISCOVERY_RUNTIME_DEFINITIONS[workerId]?.vendor;
+  if (vendor === undefined) return "";
+  return strongest(candidates, vendor)?.id ?? "";
+}
+
+/**
+ * Whether `judgeId` is a known runtime whose vendor differs from the known
+ * vendor of `workerId`. An unknown id on either side is not cross-vendor.
+ *
+ * @param {string} judgeId
+ * @param {string} workerId
+ * @returns {boolean}
+ */
+function crossVendor(judgeId, workerId) {
+  const judgeVendor = DISCOVERY_RUNTIME_DEFINITIONS[judgeId]?.vendor;
+  const workerVendor = DISCOVERY_RUNTIME_DEFINITIONS[workerId]?.vendor;
+  return Boolean(judgeVendor && workerVendor && judgeVendor !== workerVendor);
+}
+
+/**
+ * @param {string} text
+ * @returns {string[]}
+ */
+function splitHarnesses(text) {
+  return [...new Set(String(text).split(",").map((name) => name.trim()).filter(Boolean))];
+}
+
+/** @returns {{name: string, ok: boolean, detail: string}} */
+function nodeRequirement() {
+  const major = Number(process.versions.node.split(".")[0]);
+  const ok = Number.isFinite(major) && major >= MIN_NODE_MAJOR;
+  return {
+    name: "node",
+    ok,
+    detail: ok ? `${process.version} (${MIN_NODE_MAJOR} or newer required)` : `${process.version} · ${MIN_NODE_MAJOR} or newer required`,
+  };
+}
+
+/** @returns {{name: string, ok: boolean, detail: string}} */
+function gitRequirement() {
+  const probe = boundedGitSync(["--version"], { encoding: "utf8" });
+  if (probe.error || probe.status !== 0) return { name: "git", ok: false, detail: "not found on PATH" };
+  return { name: "git", ok: true, detail: String(probe.stdout ?? "").trim() };
+}
+
+/**
+ * A question function, real or injected. The real one reads one shared readline
+ * interface for the whole command and closes it when setup is done.
+ *
+ * @param {Asker|undefined} injected
+ * @returns {AskerHandle}
+ */
+function makeAsker(injected) {
+  if (injected) return { ask: injected, close: () => {} };
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return { ask: (question) => rl.question(question), close: () => rl.close() };
+}

package/src/cli/skills.mjs

@@ -0,0 +1,105 @@
+/**
+ * `skills` argv: list, install.
+ *
+ * Per-operation options only, so `--force` is rejected by `list`. The
+ * behavior lives in `installSkills`, exported because `faberun init` installs
+ * the same catalogue into a target repository; this file owns the wire, the
+ * same split `seat.mjs` uses.
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs as parseFlags } from "node:util";
+
+const SKILLS_DIR = fileURLToPath(new URL("../../skills", import.meta.url));
+
+/** Flags are scoped to the operation that declares them; all others are rejected. */
+/** @type {Record<string, import("node:util").ParseArgsOptionsConfig>} */
+const OPERATION_OPTIONS = {
+  list: {},
+  install: {
+    target: { type: "string" },
+    global: { type: "boolean" },
+    force: { type: "boolean" },
+  },
+};
+
+/**
+ * @param {string[]} args
+ * @returns {void}
+ */
+export function skillsCli(args) {
+  const operation = args[0];
+  if (!operation || !Object.hasOwn(OPERATION_OPTIONS, operation)) return usage();
+  let parsed;
+  try {
+    parsed = parseFlags({ args: args.slice(1), options: OPERATION_OPTIONS[operation], allowPositionals: true, strict: true });
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    return usage();
+  }
+  const values = /** @type {{target?: string, global?: boolean, force?: boolean}} */ (parsed.values);
+  if (operation === "list") {
+    if (parsed.positionals.length) return usage();
+    for (const name of catalog()) process.stdout.write(`${name}\n`);
+    return;
+  }
+  const skillsDir = values.global
+    ? join(homedir(), ".claude", "skills")
+    : join(values.target ? resolve(values.target) : process.cwd(), ".claude", "skills");
+  try {
+    installSkills({ names: parsed.positionals, skillsDir, force: values.force === true, stdout: process.stdout });
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    return usage();
+  }
+}
+
+/**
+ * Copy catalogue skills into `skillsDir`. A skill that is already installed is
+ * kept unless `force`; the caller owns the wire and the target directory.
+ *
+ * @param {{names: string[], skillsDir: string, force: boolean, stdout: {write(text: string): unknown}}} options
+ * @returns {{installed: number, skipped: number}}
+ */
+export function installSkills({ names, skillsDir, force, stdout }) {
+  const available = catalog();
+  const selected = names.length ? names : available;
+  for (const name of selected) {
+    if (!available.includes(name)) throw new Error(`no skill named "${name}" (run \`faberun skills list\`)`);
+  }
+  mkdirSync(skillsDir, { recursive: true });
+  let installed = 0;
+  let skipped = 0;
+  for (const name of selected) {
+    const destination = join(skillsDir, name);
+    if (existsSync(destination) && !force) {
+      stdout.write(`skipped ${name} · exists, use --force\n`);
+      skipped++;
+      continue;
+    }
+    rmSync(destination, { recursive: true, force: true });
+    cpSync(join(SKILLS_DIR, name), destination, { recursive: true });
+    stdout.write(`installed ${name} · ${skillsDir}\n`);
+    installed++;
+  }
+  stdout.write(`${installed} installed · ${skipped} skipped\n`);
+  return { installed, skipped };
+}
+
+/**
+ * @returns {string[]} catalogue entries that carry a SKILL.md
+ */
+function catalog() {
+  return readdirSync(SKILLS_DIR, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(join(SKILLS_DIR, entry.name, "SKILL.md")))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+/** @returns {void} */
+function usage() {
+  process.stderr.write("usage: faberun skills <list|install> [<name>...] [--target <dir>] [--global] [--force]\n");
+  process.exitCode = 2;
+}

package/src/cli/update.mjs

@@ -0,0 +1,216 @@
+/**
+ * `faberun update [--check] [--json]`: fetch the latest GitHub release and
+ * install it into the versioned home layout.
+ *
+ * The only command that reaches the network. The release is the channel (tags
+ * `vX.Y.Z`), and the tarball is the release's `tarball_url`. A new version
+ * proves it runs by printing its own `--version` *before* `current` moves, so a
+ * broken release can never take the working install down with it: any failure
+ * removes the partial directory and leaves `current` untouched.
+ *
+ * Version comparison is numeric on the three parts only. Prereleases are out of
+ * scope here: `v1.2.3-rc.1` does not parse, and an unparseable tag is an error
+ * rather than something to compare as if it were a release.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdirSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { compareVersions, currentLink, faberunHome, installedVersionDir, tmpDir, versionsDir, writeUpdateCheck } from "../host/home.mjs";
+import { packageVersion } from "../host/package.mjs";
+import { errorMessage } from "../util.mjs";
+
+/** @typedef {{tag: string, version: string, tarballUrl: string}} Release */
+/** @typedef {(text: string) => void} Writer */
+/**
+ * @typedef {object} UpdateOptions
+ * @property {boolean} [check]
+ * @property {boolean} [json]
+ * @property {NodeJS.ProcessEnv} [env]
+ * @property {typeof fetch} [fetchImpl]
+ * @property {string} [entryPath]
+ * @property {Writer} [stdout]
+ * @property {Writer} [stderr]
+ */
+
+const RELEASES_URL = "https://api.github.com/repos/feliperun/faberun/releases/latest";
+const REQUEST_TIMEOUT_MS = 10_000;
+
+/**
+ * @param {UpdateOptions} [options]
+ * @returns {Promise<number>} the process exit code
+ */
+export async function updateCommand(options = {}) {
+  const check = options.check === true;
+  const json = options.json === true;
+  const env = options.env ?? process.env;
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  const entryPath = options.entryPath ?? process.argv[1];
+  const stdout = options.stdout ?? ((text) => process.stdout.write(text));
+  const stderr = options.stderr ?? ((text) => process.stderr.write(text));
+  const home = faberunHome(env);
+  const current = packageVersion();
+  const installed = installedVersionDir(entryPath, home);
+
+  if (!check && !installed) {
+    stderr(`faberun is not installed under ${home}; update it the way it was installed (git pull, or re-run install.sh)\n`);
+    return 1;
+  }
+
+  /** @type {Release} */
+  let release;
+  try {
+    release = await fetchLatestRelease(fetchImpl, env);
+  } catch (error) {
+    stderr(`${errorMessage(error)}\n`);
+    return 1;
+  }
+
+  if (check) {
+    writeUpdateCheck(home, { checkedAt: new Date().toISOString(), current, latest: release.version });
+    if (json) {
+      stdout(`${JSON.stringify({ current, latest: release.version, updated: false, installedUnderHome: installed !== null, home })}\n`);
+    } else {
+      stdout(`faberun ${current} · latest ${release.version}\n`);
+      stdout(compareVersions(release.version, current) > 0 ? "update available · run faberun update\n" : "up to date\n");
+    }
+    return 0;
+  }
+
+  if (compareVersions(release.version, current) <= 0) {
+    if (json) stdout(`${JSON.stringify({ current, latest: release.version, updated: false, installedUnderHome: true, home })}\n`);
+    else stdout("up to date\n");
+    return 0;
+  }
+
+  try {
+    await installRelease(fetchImpl, home, release);
+    writeUpdateCheck(home, { checkedAt: new Date().toISOString(), current: release.version, latest: release.version });
+  } catch (error) {
+    stderr(`${errorMessage(error)}\n`);
+    return 1;
+  }
+
+  if (json) stdout(`${JSON.stringify({ current: release.version, latest: release.version, updated: true, installedUnderHome: true, home })}\n`);
+  else stdout(`updated · ${current} to ${release.version}\n`);
+  return 0;
+}
+
+/**
+ * The latest release's tag, version and tarball URL. A non-2xx response or a
+ * tag that is not `vX.Y.Z` is an error, reported as one line by the caller.
+ *
+ * @param {typeof fetch} fetchImpl
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {Promise<Release>}
+ */
+async function fetchLatestRelease(fetchImpl, env) {
+  const url = typeof env.FABERUN_RELEASES_URL === "string" && env.FABERUN_RELEASES_URL ? env.FABERUN_RELEASES_URL : RELEASES_URL;
+  const response = await fetchImpl(url, { headers: releaseHeaders(), signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+  if (!response.ok) throw new Error(`release lookup failed: HTTP ${response.status}`);
+  const body = /** @type {Record<string, unknown>} */ (await response.json());
+  const parsed = parseTag(body.tag_name);
+  if (typeof body.tarball_url !== "string" || !body.tarball_url) throw new Error(`release ${parsed.tag} has no tarball_url`);
+  return { tag: parsed.tag, version: parsed.version, tarballUrl: body.tarball_url };
+}
+
+/**
+ * Parse `vX.Y.Z`. Prerelease and build metadata are deliberately not accepted;
+ * the caller reports the tag as an error.
+ *
+ * @param {unknown} tagName
+ * @returns {{tag: string, version: string}}
+ */
+function parseTag(tagName) {
+  if (typeof tagName !== "string") throw new Error("release has no tag_name");
+  if (!/^v\d+\.\d+\.\d+$/u.test(tagName)) throw new Error(`release tag is not vX.Y.Z: ${tagName}`);
+  return { tag: tagName, version: tagName.slice(1) };
+}
+
+/**
+ * @param {typeof fetch} fetchImpl
+ * @param {string} home
+ * @param {Release} release
+ * @returns {Promise<void>}
+ */
+async function installRelease(fetchImpl, home, release) {
+  const partial = join(versionsDir(home), `${release.tag}.partial`);
+  const destination = join(versionsDir(home), release.version);
+  const tarball = join(tmpDir(home), `${release.tag}.tgz`);
+  try {
+    mkdirSync(tmpDir(home), { recursive: true });
+    mkdirSync(partial, { recursive: true });
+    await downloadTarball(fetchImpl, release.tarballUrl, tarball);
+    extractTarball(tarball, partial);
+    verifyVersion(partial, release.version);
+    rmSync(destination, { recursive: true, force: true });
+    renameSync(partial, destination);
+    repointCurrent(home, release.version);
+  } catch (error) {
+    rmSync(partial, { recursive: true, force: true });
+    rmSync(tarball, { force: true });
+    throw error;
+  }
+}
+
+/**
+ * @param {typeof fetch} fetchImpl
+ * @param {string} url
+ * @param {string} destination
+ * @returns {Promise<void>}
+ */
+async function downloadTarball(fetchImpl, url, destination) {
+  const response = await fetchImpl(url, { headers: releaseHeaders(), signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+  if (!response.ok) throw new Error(`tarball download failed: HTTP ${response.status}`);
+  writeFileSync(destination, Buffer.from(await response.arrayBuffer()));
+}
+
+/**
+ * @param {string} tarball
+ * @param {string} destination
+ * @returns {void}
+ */
+function extractTarball(tarball, destination) {
+  const result = spawnSync("tar", ["-xzf", tarball, "--strip-components=1", "-C", destination], { encoding: "utf8" });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`tar failed: ${String(result.stderr ?? "").trim() || `exit ${result.status}`}`);
+}
+
+/**
+ * Run the candidate before it can become `current`: it must exit 0 and print
+ * exactly `faberun <version>`.
+ *
+ * @param {string} partial
+ * @param {string} version
+ * @returns {void}
+ */
+function verifyVersion(partial, version) {
+  const binary = join(partial, "bin", "faberun.mjs");
+  const result = spawnSync(process.execPath, [binary, "--version"], { encoding: "utf8" });
+  if (result.error) throw result.error;
+  const printed = String(result.stdout ?? "").trim();
+  if (result.status !== 0) throw new Error(`new version failed to run: ${printed || `exit ${result.status}`}`);
+  if (printed !== `faberun ${version}`) throw new Error(`new version printed ${printed || "nothing"}; expected faberun ${version}`);
+}
+
+/**
+ * Point `current` at the new version atomically: a `current.tmp` symlink then a
+ * rename over `current`, so a concurrent reader sees either the old target or
+ * the new one, never a missing link.
+ *
+ * @param {string} home
+ * @param {string} version
+ * @returns {void}
+ */
+function repointCurrent(home, version) {
+  const link = currentLink(home);
+  const temporary = `${link}.tmp`;
+  rmSync(temporary, { force: true });
+  // SPEC.md's layout: `current -> versions/<v>`, relative to the home.
+  symlinkSync(join("versions", version), temporary);
+  renameSync(temporary, link);
+}
+
+/** @returns {Record<string, string>} */
+function releaseHeaders() {
+  return { Accept: "application/vnd.github+json", "User-Agent": `faberun/${packageVersion()}` };
+}