@sibylline-labs/eris 0.0.0-stage → 0.3.0

package/src/cli/commands/update/release.ts

@@ -0,0 +1,351 @@
+/**
+ * release.ts — `eris update [--check] [--to <tag>]` for a distribution that
+ * publishes compiled binaries to GitHub releases: replace this binary with a
+ * release of the repository it was built from (`releaseRepo()`, baked in by
+ * `build()`), so a distribution's binary never takes another's for its own.
+ * Core's own `update` only prints the npm commands (../update.ts); a
+ * distribution opts into this verb with `RELEASE_UPDATE` (./opt-in.ts).
+ *
+ *   1. Refuse, before any request, what cannot be updated in place: a source
+ *      checkout, a platform with no release binary, a bad `ERIS_UPDATE_API`, a
+ *      directory that cannot be written.
+ *   2. Ask the releases API for the latest release (or `--to`'s tag). A
+ *      prerelease is installed only when named; `--to` may also go backwards.
+ *   3. Read the release's `SHA256SUMS`, download this platform's `eris-<os>-<arch>`
+ *      into a temp file beside the binary, hash it as it streams, and refuse a
+ *      mismatch.
+ *   4. Rename it over the binary (keeping `<binary>.old`), run it once
+ *      (`--output json --version` must report the release's tag) and restore the
+ *      old one if it does not. Success removes `.old`.
+ *
+ * Exit codes: 0 done or already current; 1 refused (a failure block). With
+ * `--check`, 0 current, 10 an update is available, 1 could not tell. The record
+ * under `--output json` is `{current, latest, update_available, updated}`.
+ *
+ * The network and the file work are in ./update/. Everything the verb learns
+ * about its surroundings comes from an `UpdateHost`, so a test runs the real
+ * thing against a loopback server and a stand-in binary.
+ */
+
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { renderFailureBlock } from "../../../../ts/lib/eris-fail";
+import type { VerbContext, VerbHandler } from "../../../main";
+import { isCompiled, releaseRepo, VERSION } from "../../../runtime/home";
+import { readEnv } from "../../../runtime/env";
+import { info, ok } from "../../../runtime/logging";
+import { nodeRunner, type Runner } from "../../../runtime/process";
+import { readRowArgs, usageLine } from "../../args";
+import { sanitizeDisplay } from "../../output";
+import { GitHub, MAX_BINARY_BYTES, notFound, parseApiBase, sendsToken, TAG } from "./github";
+import { checkWritable, discard, forgetOld, oldPath, onInterrupt, replace, restore, stage } from "./replace";
+import { Refusal } from "./refusal";
+import { RELEASE_UPDATE_ROW } from "./opt-in";
+import { compareVersions } from "./semver";
+
+export { allowedRedirect, parseApiBase } from "./github";
+export { compareVersions } from "./semver";
+
+const USAGE = `Usage: eris update [--check] [--to <tag>]
+
+Replace this eris binary with a release of the repository it was built from.
+With no flag, install the latest release when it is newer than this build.
+
+Flags:
+  --check       Say whether an update is available and change nothing.
+                Exit 0: up to date. Exit 10: an update is available.
+                Exit 1: could not tell.
+  --to <tag>    Install that release instead, a prerelease or an older one
+                included.
+  --help, -h    Print this usage text
+
+The binary is checked against the release's SHA256SUMS, run once before the old
+one is dropped, and the old one is put back if the new one does not answer.
+A source checkout is refused: update it with git pull.
+
+Environment:
+  GH_TOKEN, GITHUB_TOKEN   A GitHub token (GH_TOKEN first). Needed for a private
+                           repository; raises the anonymous rate limit. Sent to
+                           api.github.com only (or a loopback test server),
+                           never to the download host.
+  ERIS_UPDATE_API          Another API base, for a GitHub Enterprise host or a
+                           test server: https, or http on a loopback host. A
+                           host other than api.github.com or loopback is sent
+                           no token.
+
+--output json prints {current, latest, update_available, updated}.
+Refusals are explained in docs/ERRORS.md.
+`;
+
+/** The platforms releases publish a binary for. */
+const SUPPORTED = new Set(["darwin-arm64", "linux-x64"]);
+
+/** How long the new binary has to answer `--version`. */
+const SMOKE_TIMEOUT_MS = 20_000;
+
+export interface UpdateHost {
+  /** Whether this is a binary `build()` compiled, as opposed to a source checkout. */
+  readonly compiled: boolean;
+  /** The running binary's path. */
+  readonly execPath: string;
+  readonly platform: string;
+  readonly arch: string;
+  /** This build's tag (`dev` when it has none). */
+  readonly version: string;
+  /** `owner/name` of the repository its releases are published to. */
+  readonly releaseRepo: string;
+  /** Runs the new binary. */
+  readonly runner: Runner;
+  /** How long the API may stay silent, in ms. */
+  readonly apiTimeoutMs: number;
+  /** How long a download may stay silent between two chunks, in ms. */
+  readonly downloadTimeoutMs: number;
+}
+
+/** This process. */
+export function defaultHost(): UpdateHost {
+  return {
+    compiled: isCompiled,
+    execPath: process.execPath,
+    platform: process.platform,
+    arch: process.arch,
+    version: VERSION,
+    releaseRepo: releaseRepo(),
+    runner: nodeRunner,
+    apiTimeoutMs: 30_000,
+    downloadTimeoutMs: 60_000,
+  };
+}
+
+/** The checksum SHA256SUMS lists for `name` (`<hex>  <name>`, or `<hex> *<name>`), lower-case. */
+function checksumOf(sums: string, name: string): string | undefined {
+  for (const line of sums.split("\n")) {
+    const m = /^([0-9a-fA-F]{64}) [ *](.+?)\r?$/.exec(line);
+    if (m !== null && m[2] === name) return m[1]!.toLowerCase();
+  }
+  return undefined;
+}
+
+/**
+ * The token from `GH_TOKEN`, else `GITHUB_TOKEN`: trimmed, and a blank one is skipped.
+ * A token holds visible ASCII only; anything else is refused here, by variable name,
+ * because a header value with a line break makes `fetch` throw an error that quotes
+ * the whole value, and the failure block would print the secret.
+ */
+function tokenFrom(env: VerbContext["env"]): string | undefined {
+  for (const name of ["GH_TOKEN", "GITHUB_TOKEN"]) {
+    const value = readEnv(env, name)?.trim();
+    if (value === undefined || value === "") continue;
+    if (!/^[\x21-\x7e]+$/.test(value)) {
+      throw new Refusal({
+        slug: "update-token-invalid",
+        what: `${name} is not a usable token: it holds a space, a line break or another character a token cannot (its value is not shown)`,
+        fix: `set ${name} to the token alone, or unset it`,
+      });
+    }
+    return value;
+  }
+  return undefined;
+}
+
+/** `ERIS_UPDATE_API` as it may be shown: scheme and host only, so a credential in it is never echoed. */
+function shownApi(raw: string | undefined): string {
+  try {
+    const url = new URL(raw ?? "");
+    return `${url.protocol}//${url.host}`;
+  } catch {
+    return "(not a URL)";
+  }
+}
+
+interface Target {
+  readonly path: string;
+  readonly api: URL;
+  readonly token: string | undefined;
+}
+
+/** Everything that can be refused without a request. */
+function preflight(host: UpdateHost, ctx: VerbContext, check: boolean): Target {
+  if (!host.compiled) {
+    throw new Refusal({
+      slug: "update-not-compiled",
+      what: "this eris runs from a source checkout, which eris update does not replace",
+      fix: `update the checkout instead: cd ${sanitizeDisplay(ctx.erisDir)} && git pull && bun install --frozen-lockfile`,
+    });
+  }
+  const platform = `${host.platform}-${host.arch}`;
+  if (!SUPPORTED.has(platform)) {
+    throw new Refusal({
+      slug: "update-unsupported-platform",
+      what: `releases carry no eris binary for ${sanitizeDisplay(platform)} (darwin-arm64 and linux-x64 only)`,
+      fix: "build eris from source for this platform: see 'From source' in the README",
+    });
+  }
+  let path = host.execPath;
+  try {
+    path = realpathSync(host.execPath);
+  } catch {
+    // Keep the path as given; writing beside it fails with its own reason below.
+  }
+  const raw = readEnv(ctx.env, "ERIS_UPDATE_API");
+  const api = parseApiBase(raw);
+  if (api === null) {
+    throw new Refusal({
+      slug: "update-api-invalid",
+      what: `ERIS_UPDATE_API is not an API base eris will use: ${shownApi(raw)}`,
+      fix: "set it to an https URL with no credentials, query or fragment (http only for a loopback host), or unset it to use https://api.github.com",
+    });
+  }
+  // Another host gets no token: the variable may be stray or planted.
+  const token = sendsToken(api) ? tokenFrom(ctx.env) : undefined;
+  if (!check) checkWritable(path);
+  return { path, api, token };
+}
+
+/** Why the new binary is not good, or null when it answered with the release's tag. */
+async function smoke(host: UpdateHost, path: string, tag: string, env: VerbContext["env"]): Promise<string | null> {
+  // The new binary needs no token; it is not handed one.
+  const { GH_TOKEN: _gh, GITHUB_TOKEN: _github, ...rest } = env;
+  const r = await host.runner.run([path, "--output", "json", "--version"], { timeoutMs: SMOKE_TIMEOUT_MS, env: rest });
+  if (r.kind === "spawn-failed") return `it did not start (${sanitizeDisplay(r.errno)})`;
+  if (r.kind === "timeout") return `it did not answer within ${SMOKE_TIMEOUT_MS / 1000}s`;
+  if (r.kind === "signal") return `it was killed by ${sanitizeDisplay(r.signal)}`;
+  if (r.kind === "exit") {
+    const said = sanitizeDisplay(r.stderr.toString("utf8").split("\n")[0] ?? "").slice(0, 120);
+    return `it exited ${r.code}${said !== "" ? `: ${said}` : ""}`;
+  }
+  let reported: unknown;
+  try {
+    reported = (JSON.parse(r.stdout.toString("utf8")) as { version?: unknown }).version;
+  } catch {
+    return "it did not print a version record";
+  }
+  if (reported !== tag) return `it reports ${typeof reported === "string" ? sanitizeDisplay(reported).slice(0, 60) : "no version"}, not ${tag}`;
+  return null;
+}
+
+export interface UpdateRecord {
+  current: string;
+  latest: string;
+  update_available: boolean;
+  updated: boolean;
+}
+
+async function update(host: UpdateHost, ctx: VerbContext, check: boolean, to: string | undefined): Promise<number> {
+  const target = preflight(host, ctx, check);
+  const repo = host.releaseRepo;
+  const gh = new GitHub({
+    base: target.api,
+    token: target.token,
+    repo,
+    userAgent: `eris-update/${host.version}`,
+    apiTimeoutMs: host.apiTimeoutMs,
+    downloadTimeoutMs: host.downloadTimeoutMs,
+  });
+
+  if (!check) info(`checking ${repo} for ${to ?? "the latest release"}`, ctx.stderr);
+  const release = await gh.release(to);
+  if (release.draft || (release.prerelease && to === undefined)) {
+    throw notFound(repo, to ?? release.tag, release.draft ? ` (${release.tag} is a draft)` : ` (${release.tag} is a prerelease; name it with --to)`);
+  }
+  const order = compareVersions(release.tag, host.version);
+  const newer = order === null ? release.tag !== host.version : order > 0;
+  const emit = (updated: boolean) => {
+    const record: UpdateRecord = { current: host.version, latest: release.tag, update_available: newer, updated };
+    if (ctx.format === "json") ctx.stdout.write(`${JSON.stringify(record)}\n`);
+  };
+
+  if (check) {
+    if (ctx.format !== "json") ctx.stdout.write(newer ? `update available: ${host.version} -> ${release.tag}\n` : `up to date: ${host.version}\n`);
+    emit(false);
+    return newer ? 10 : 0;
+  }
+  if (to === undefined ? !newer : release.tag === host.version) {
+    ok(`eris ${host.version} is up to date`, ctx.stderr);
+    emit(false);
+    return 0;
+  }
+
+  const name = `eris-${host.platform}-${host.arch}`;
+  const missing = (what: string) =>
+    new Refusal({ slug: "update-asset-missing", what, fix: `choose another release with eris update --to <tag>: see https://github.com/${repo}/releases` });
+  const binary = release.assets.find((a) => a.name === name);
+  const sumsAsset = release.assets.find((a) => a.name === "SHA256SUMS");
+  if (binary === undefined) throw missing(`${repo}'s release ${release.tag} has no ${name}`);
+  if (sumsAsset === undefined) throw missing(`${repo}'s release ${release.tag} has no SHA256SUMS`);
+
+  info(`downloading ${name} ${release.tag}`, ctx.stderr);
+  const expected = checksumOf(await gh.downloadText(sumsAsset), name);
+  if (expected === undefined) throw missing(`SHA256SUMS in ${repo}'s release ${release.tag} lists no checksum for ${name}`);
+  const hash = createHash("sha256");
+  // One guard from the first byte staged until the new binary has answered, so
+  // no signal lands between two guards with no listener and kills by default:
+  // before the rename an interrupt removes the staged file, after it puts the
+  // old binary back. (stage() also removes a partial file on its own.)
+  let staged: string | undefined;
+  let replaced = false;
+  const stand = onInterrupt(() => {
+    if (replaced) void restore(target.path);
+    else if (staged !== undefined) discard(staged);
+  });
+  let why: string | null;
+  try {
+    staged = await stage(target.path, (write) =>
+      gh.download(binary, MAX_BINARY_BYTES, (chunk) => {
+        hash.update(chunk);
+        write(chunk);
+      }),
+    );
+    const got = hash.digest("hex");
+    if (got !== expected) {
+      discard(staged);
+      throw new Refusal({
+        slug: "update-checksum-mismatch",
+        what: `${name} does not match its checksum in SHA256SUMS (expected ${expected}, got ${got})`,
+        fix: "nothing was changed\nretry; if it repeats, the release is corrupt or has been tampered with, so do not install it",
+      });
+    }
+    replace(target.path, staged);
+    replaced = true;
+    why = await smoke(host, target.path, release.tag, ctx.env);
+  } finally {
+    stand();
+  }
+  if (why !== null) {
+    const stuck = restore(target.path);
+    throw new Refusal({
+      slug: "update-smoke-failed",
+      what: `the new eris ${release.tag} failed its check: ${why}; ${stuck === null ? `the previous eris ${host.version} is restored` : `the previous eris could not be put back (${stuck})`}`,
+      fix:
+        stuck === null
+          ? `the release may be broken: retry later, or install another with eris update --to <tag> (see https://github.com/${repo}/releases)`
+          : `put the previous eris back by hand: mv ${oldPath(target.path)} ${target.path}`,
+    });
+  }
+  forgetOld(target.path);
+  ok(`updated eris ${host.version} -> ${release.tag} (${target.path})`, ctx.stderr);
+  emit(true);
+  return 0;
+}
+
+/** The verb on a given host. */
+export function createUpdateHandler(host: UpdateHost): VerbHandler {
+  return async (args, ctx) => {
+    const a = readRowArgs("update", RELEASE_UPDATE_ROW, args, ctx, { help: USAGE });
+    if (a === null) return 0;
+    const to = a.flags["--to"];
+    if (to !== undefined && !TAG.test(to)) {
+      ctx.stderr.write(`ERROR --to takes a release tag such as v0.2.1, got '${sanitizeDisplay(to)}' (usage: ${usageLine("update", RELEASE_UPDATE_ROW)})\n`);
+      return 1;
+    }
+    try {
+      return await update(host, ctx, a.flags["--check"], to);
+    } catch (e) {
+      if (!(e instanceof Refusal)) throw e;
+      ctx.stderr.write(renderFailureBlock(e.input, ctx.erisDir));
+      return 1;
+    }
+  };
+}
+
+export const runReleaseUpdate: VerbHandler = createUpdateHandler(defaultHost());

package/src/cli/commands/update/replace.ts

@@ -0,0 +1,143 @@
+/**
+ * replace.ts — put a new binary where the running one is, and take it back if
+ * the new one does not run.
+ *
+ * Every file it makes sits in the target's own directory, never a system temp
+ * dir: a rename is only atomic inside one filesystem, and a binary that is
+ * about to be executed should not be staged in a directory anyone can write.
+ *
+ *   1. `stage`: the download streams into `.eris-update-<pid>-<random>` beside the
+ *      target, with the target's mode, and is removed if anything fails.
+ *   2. `replace`: hard-links the target to `<target>.old` (a copy where the
+ *      filesystem has no links), then renames the staged file over the target.
+ *      The rename is atomic, so the target path names a whole binary at every
+ *      moment, and replacing the file a process is running from is safe on
+ *      macOS and Linux (the running image keeps its inode).
+ *   3. The caller runs the new binary (`smoke`). If it fails, `<target>.old` is
+ *      renamed back; if it passes, `.old` is removed.
+ *
+ * An interrupt (Ctrl-C, a TERM, a hangup) in step 1 removes the partial file, and
+ * in steps 2-3 puts the old binary back (`onInterrupt`), so a killed update never
+ * leaves a stray file or a binary nobody has run.
+ */
+
+import { accessSync, chmodSync, closeSync, constants, copyFileSync, linkSync, openSync, renameSync, rmSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { Refusal, reasonOf } from "./refusal";
+
+export const oldPath = (target: string): string => `${target}.old`;
+
+/**
+ * Run `cleanup` if this process is interrupted, then die by that signal as it
+ * would have without us. Returns the function that stands the guard down.
+ */
+export function onInterrupt(cleanup: () => void): () => void {
+  const handlers = new Map<NodeJS.Signals, () => void>();
+  const dispose = () => {
+    for (const [sig, handler] of handlers) process.removeListener(sig, handler);
+    handlers.clear();
+  };
+  for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
+    const handler = () => {
+      try {
+        cleanup();
+      } finally {
+        dispose();
+        process.kill(process.pid, sig);
+      }
+    };
+    handlers.set(sig, handler);
+    process.on(sig, handler);
+  }
+  return dispose;
+}
+
+function unwritable(dir: string, e: unknown): Refusal {
+  return new Refusal({
+    slug: "update-target-unwritable",
+    what: `eris cannot write to ${dir}: ${reasonOf(e)}`,
+    fix: `run eris update as a user who can write to ${dir}\nor reinstall eris into a directory you own`,
+  });
+}
+
+/** Refuse now, before any download, when the target's directory cannot be written. */
+export function checkWritable(target: string): void {
+  const dir = dirname(target);
+  try {
+    accessSync(dir, constants.W_OK);
+  } catch (e) {
+    throw unwritable(dir, e);
+  }
+}
+
+/** The staged file's path, once `fill` has written all of it through `write`. */
+export async function stage(target: string, fill: (write: (chunk: Uint8Array) => void) => Promise<void>): Promise<string> {
+  const dir = dirname(target);
+  const path = join(dir, `.eris-update-${process.pid}-${randomBytes(4).toString("hex")}`);
+  let fd: number;
+  try {
+    fd = openSync(path, "wx", 0o700);
+  } catch (e) {
+    throw unwritable(dir, e);
+  }
+  const stand = onInterrupt(() => rmSync(path, { force: true }));
+  try {
+    try {
+      await fill((chunk) => {
+        for (let at = 0; at < chunk.length; ) at += writeSync(fd, chunk, at);
+      });
+    } finally {
+      closeSync(fd);
+    }
+    chmodSync(path, statSync(target).mode & 0o777);
+    return path;
+  } catch (e) {
+    rmSync(path, { force: true });
+    if (e instanceof Refusal) throw e;
+    throw unwritable(dir, e);
+  } finally {
+    stand();
+  }
+}
+
+/** Remove a staged file that will not be used. */
+export function discard(path: string): void {
+  rmSync(path, { force: true });
+}
+
+/** Keep the running binary as `<target>.old`, and rename `staged` over `target`. */
+export function replace(target: string, staged: string): void {
+  const old = oldPath(target);
+  try {
+    rmSync(old, { force: true });
+    try {
+      linkSync(target, old);
+    } catch {
+      copyFileSync(target, old);
+    }
+    renameSync(staged, target);
+  } catch (e) {
+    rmSync(old, { force: true });
+    throw unwritable(dirname(target), e);
+  }
+}
+
+/** Remove `<target>.old` once the new binary has answered. */
+export function forgetOld(target: string): void {
+  try {
+    unlinkSync(oldPath(target));
+  } catch {
+    // Nothing to remove, or it cannot be: the update itself succeeded.
+  }
+}
+
+/** Put `<target>.old` back. Returns the reason it could not, else null. */
+export function restore(target: string): string | null {
+  try {
+    renameSync(oldPath(target), target);
+    return null;
+  } catch (e) {
+    return reasonOf(e);
+  }
+}

package/src/cli/commands/update/semver.ts

@@ -0,0 +1,48 @@
+/**
+ * semver.ts — the order `eris update` puts release tags in. A tag is
+ * `[v]MAJOR.MINOR.PATCH[-prerelease]`, ordered as semver.org defines: the
+ * numbers first, a prerelease before its release, prerelease identifiers
+ * compared one by one (numbers numerically, below words).
+ */
+
+const SEMVER = /^v?(\d{1,9})\.(\d{1,9})\.(\d{1,9})(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+
+/**
+ * A release tag: `vMAJOR.MINOR.PATCH[-prerelease]`, exactly the tags
+ * `compareVersions` orders, with the `v`. The release workflow's tag check
+ * (.github/workflows/release.yml) holds the same grammar;
+ * tests/workflows.test.ts runs both on one table.
+ */
+export const RELEASE_TAG = /^v[0-9]{1,9}\.[0-9]{1,9}\.[0-9]{1,9}(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$/;
+
+const sign = (n: number): -1 | 0 | 1 => (n < 0 ? -1 : n > 0 ? 1 : 0);
+
+/** -1, 0 or 1 for `a` before, equal to or after `b`; null when either is not a version (`dev`, a typo). */
+export function compareVersions(a: string, b: string): -1 | 0 | 1 | null {
+  const pa = SEMVER.exec(a);
+  const pb = SEMVER.exec(b);
+  if (pa === null || pb === null) return null;
+  for (const i of [1, 2, 3]) {
+    const d = sign(Number(pa[i]) - Number(pb[i]));
+    if (d !== 0) return d;
+  }
+  const ra = pa[4];
+  const rb = pb[4];
+  if (ra === undefined || rb === undefined) return ra === rb ? 0 : ra === undefined ? 1 : -1;
+  const ia = ra.split(".");
+  const ib = rb.split(".");
+  for (let i = 0; i < Math.max(ia.length, ib.length); i++) {
+    const x = ia[i];
+    const y = ib[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    const nx = /^\d+$/.test(x);
+    const ny = /^\d+$/.test(y);
+    if (nx && ny) {
+      const d = sign(Number(x) - Number(y));
+      if (d !== 0) return d;
+    } else if (nx !== ny) return nx ? -1 : 1;
+    else if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}

package/src/cli/commands/update.ts

@@ -0,0 +1,47 @@
+/**
+ * update.ts — `eris update`: say how to get the latest release. eris ships as
+ * an npm package, run by bun (docs/UPDATE.md), so there is nothing to replace in
+ * place: the package manager that installed it is what updates it. The verb
+ * reads nothing and fetches nothing; it prints the commands and exits 0.
+ *
+ * `--output json` prints `{current, commands}`: this build's version (`dev` in
+ * a checkout) and the same commands, in the same order.
+ *
+ * A distribution that publishes compiled binaries swaps in the in-place verb,
+ * `RELEASE_UPDATE` (./update/opt-in.ts).
+ */
+
+import type { VerbHandler } from "../../main";
+import { VERSION } from "../../runtime/home";
+import { readVerbArgs } from "../args";
+
+/** The package's npm name: what every command below installs or runs. */
+export const PACKAGE = "@sibylline-labs/eris";
+
+/** How to get the latest release, in the order they are printed. */
+export const UPDATE_COMMANDS: readonly string[] = [`npx ${PACKAGE}@latest <command>`, `bunx ${PACKAGE}@latest <command>`, `bun add -g ${PACKAGE}@latest`];
+
+const USAGE = `Usage: eris update
+
+Print how to get the latest eris release. eris is an npm package run by bun;
+the package manager that installed it updates it, so this command changes
+nothing.
+
+Flags:
+  --help, -h    Print this usage text
+
+--output json prints {current, commands}.
+`;
+
+export const runUpdate: VerbHandler = async (args, ctx) => {
+  if (readVerbArgs("update", args, ctx, { help: USAGE }) === null) return 0;
+  if (ctx.format === "json") {
+    ctx.stdout.write(`${JSON.stringify({ current: VERSION, commands: UPDATE_COMMANDS })}\n`);
+    return 0;
+  }
+  const [npx, bunx, global] = UPDATE_COMMANDS;
+  ctx.stdout.write(
+    `eris ${VERSION}. Run the latest release with:\n  ${npx}\n  ${bunx}\nor install it globally (bun runs it, so bun must be on PATH):\n  ${global}\n`,
+  );
+  return 0;
+};

package/src/cli/commands/usage.ts

@@ -0,0 +1,68 @@
+/**
+ * usage.ts — bare `eris`, `eris -h` and `eris --help`: the top-level usage (the
+ * former Bash entrypoint's `_eris_usage`).
+ *
+ * A composed build lists each plugin group after the built-in commands, a
+ * locked one marked, every summary in one column (src/cli/compose.ts). The `--output` paragraph names every
+ * json surface of the composed CLI, plugin rows included;
+ * tests/cli-router.test.ts holds it against the `json` rows. A build whose bare
+ * program is a distribution's menu says so in the last line.
+ */
+
+import { CLI, type CliContext } from "../../main";
+import { type Cli, commandLines, NO_ENTITLEMENTS, type Session } from "../compose";
+
+const HEADER = `Usage: eris <command> [args]
+
+Commands:
+`;
+
+const FLAG_COLUMN = " ".repeat(23);
+/** The widest line of the `--output` paragraph. */
+const WIDTH = 78;
+
+/** Words filled greedily into lines of at most `WIDTH`; a word never breaks. */
+function fill(words: readonly string[]): string {
+  const lines: string[] = [];
+  let line = "  --output text|json   ";
+  let fresh = true;
+  for (const w of words) {
+    if (!fresh && line.length + 1 + w.length > WIDTH) {
+      lines.push(line);
+      line = FLAG_COLUMN;
+      fresh = true;
+    }
+    line += fresh ? w : ` ${w}`;
+    fresh = false;
+  }
+  return [...lines, line].map((l) => `${l}\n`).join("");
+}
+
+/** The global flags, the `--output` paragraph naming each json surface `cli` composes. */
+function globals(cli: Cli): string {
+  const surfaces = Object.entries(cli.jsonSurfaces).map(([g, s]) => (s === true ? g : `${g} ${s.join("|")}`));
+  const words = [
+    ..."Output format. 'json' is the machine rendering, accepted by:".split(" "),
+    ...surfaces.map((s, i) => `${s}${i === surfaces.length - 1 ? "." : ","}`),
+    ..."Any other verb refuses the flag (docs/OUTPUT-CONTRACT.md). Default: text.".split(" "),
+  ];
+  return `
+Global flags:
+${fill(words)}  --version            Print this build's version and release repository.
+
+Run 'eris <command> --help' for command-specific usage.
+${cli.hasMenu ? "Run 'eris' without arguments for interactive mode.\n" : ""}`;
+}
+
+/** The top-level usage of one session's composed CLI. */
+export function usageText(session: Session): string {
+  return `${HEADER}${commandLines(session)}${globals(session.cli)}`;
+}
+
+/** This build's top-level usage (core plus plugins/index.ts), default entitlements. */
+export const ERIS_USAGE = usageText({ cli: CLI, entitled: NO_ENTITLEMENTS });
+
+export async function runUsage(_args: string[], ctx: CliContext & { session?: Session }): Promise<number> {
+  ctx.stdout.write(ctx.session === undefined ? ERIS_USAGE : usageText(ctx.session));
+  return 0;
+}

package/src/cli/commands/version.ts

@@ -0,0 +1,29 @@
+/**
+ * version.ts — `eris --version`: what this build is.
+ *
+ *   eris v0.2.0 (sibylline-labs/eris)
+ *   <the line a distribution added, if any>
+ *
+ * `--output json` prints the same facts as one record:
+ * `{version, release_repo, build_id, extra}`. `version` is the tag the build was
+ * given (`dev` for an untagged build and for a checkout), `release_repo` the
+ * repository `eris update` reads releases from, `build_id` the compiled
+ * binary's id (null in a checkout) and `extra` the distribution's line (null
+ * when it adds none). All four are baked at build time (src/build.ts); a run
+ * from source reports the identity its entry handed `runProgram` (`identity()`,
+ * src/runtime/home.ts). Nothing here reads a file, the network or the
+ * environment, so it answers in a binary whose asset home cannot be written.
+ */
+
+import type { VerbHandler } from "../../main";
+import { BUILD_ID, identity, VERSION } from "../../runtime/home";
+
+export const runVersion: VerbHandler = async (_args, ctx) => {
+  const { releaseRepo, versionExtra } = identity();
+  if (ctx.format === "json") {
+    ctx.stdout.write(`${JSON.stringify({ version: VERSION, release_repo: releaseRepo, build_id: BUILD_ID, extra: versionExtra })}\n`);
+  } else {
+    ctx.stdout.write(`eris ${VERSION} (${releaseRepo})\n${versionExtra !== null ? `${versionExtra}\n` : ""}`);
+  }
+  return 0;
+};