@sibylline-labs/eris 0.0.0-stage → 0.3.0

package/src/cli/ts-verb.ts

@@ -0,0 +1,126 @@
+/**
+ * ts-verb.ts — the steps between argv and a verb's dispatcher, for a verb the
+ * router runs in TypeScript:
+ *
+ *   1. the global `--output` parse
+ *   2. the machine-surface allow-list
+ *   3. the entitlement lock, for a plugin group whose product is not bought
+ *   4. the verb, with the flag stripped
+ *
+ * A verb stops early by throwing `CliExit` after writing its diagnostic, the
+ * TS counterpart of `eris::die` / `eris::fail` exiting the shell.
+ *
+ * A `session` (src/cli/compose.ts) supplies the composed allow-list, its fix
+ * text and the locks, and is handed on to the verb; without one, steps 2 and 3
+ * read core's registry alone.
+ *
+ * Everything past step 3 is imported lazily, so a package the checkout's
+ * node_modules cannot resolve surfaces from inside step 4. It ends the command
+ * as the `eris-deps-not-installed` block, never a bare resolution
+ * error. Nothing on this path or above it may import a third-party package, or
+ * the block could not be reached.
+ */
+
+import { accessSync, constants } from "node:fs";
+import { delimiter, join, relative, sep } from "node:path";
+import { renderFailureBlock } from "../../ts/lib/eris-fail";
+import type { CliContext, VerbHandler } from "../main";
+import { asksForHelp, CliExit, GlobalFlagError, parseGlobal } from "./args";
+import { lockedOutcome, lockedProduct, type Session } from "./compose";
+import { sanitizeDisplay, unsupportedJsonBlock } from "./output";
+
+export { CliExit };
+
+/** `command -v <name>` over PATH, for an executable file. */
+export function onPath(name: string, env: Record<string, string | undefined>): string | undefined {
+  for (const dir of (env.PATH ?? "").split(delimiter)) {
+    if (dir === "") continue;
+    const p = join(dir, name);
+    try {
+      accessSync(p, constants.X_OK);
+      return p;
+    } catch {
+      // not here
+    }
+  }
+  return undefined;
+}
+
+/** What bun sets on the error for a module it could not find: `import` and
+ *  `require` use different codes, and neither error is an `Error` subclass. */
+const NOT_FOUND_CODES = new Set(["ERR_MODULE_NOT_FOUND", "MODULE_NOT_FOUND"]);
+
+/** A bare package name, as opposed to a path (`./x`, `/x`) or a scheme (`node:x`). */
+const NOT_A_PACKAGE = /^(\.|\/|[a-z][a-z0-9+.-]*:)/i;
+
+/**
+ * The failure block for a thrown value that is bun failing to resolve a
+ * PACKAGE, else null. A missing relative module is a defect in the checkout's
+ * own source and stays a crash: telling an operator to `bun install` for it
+ * would send them away from the bug. It reads the error's structured fields,
+ * never its message text.
+ *
+ * It names the fix and does not run it: an inline `bun install` is unbounded
+ * and reaches the network mid-command, the same reason `eris yak` refuses to
+ * run one.
+ */
+export function missingDependencyBlock(e: unknown, erisDir: string): string | null {
+  if (typeof e !== "object" || e === null) return null;
+  const { code, specifier, referrer } = e as Record<string, unknown>;
+  if (typeof code !== "string" || !NOT_FOUND_CODES.has(code)) return null;
+  if (typeof specifier !== "string" || NOT_A_PACKAGE.test(specifier)) return null;
+  const rel = typeof referrer === "string" && referrer.startsWith(`${erisDir}${sep}`) ? relative(erisDir, referrer) : referrer;
+  const by = typeof rel === "string" && rel !== "" ? ` (needed by ${sanitizeDisplay(rel)})` : "";
+  return renderFailureBlock(
+    {
+      slug: "eris-deps-not-installed",
+      what: `eris's node_modules is missing or out of date — cannot resolve '${sanitizeDisplay(specifier)}'${by}`,
+      fix: `from ${erisDir}, run: bun install --frozen-lockfile`,
+    },
+    erisDir,
+  );
+}
+
+export async function runTsVerb(
+  verb: string,
+  argv: readonly string[],
+  ctx: CliContext,
+  handlers: Readonly<Record<string, () => Promise<VerbHandler>>>,
+  session?: Session,
+): Promise<number> {
+  try {
+    let parsed: ReturnType<typeof parseGlobal>;
+    try {
+      parsed = parseGlobal(argv, ctx.erisDir, { keepTerminator: true });
+    } catch (e) {
+      if (e instanceof GlobalFlagError) {
+        ctx.stderr.write(e.block);
+        return 1;
+      }
+      throw e;
+    }
+    const refusal = unsupportedJsonBlock(parsed.argv[0], parsed.argv[1], parsed.format, ctx.erisDir, session?.cli.jsonSurfaces, session?.cli.jsonFix);
+    if (refusal !== null) {
+      ctx.stderr.write(refusal);
+      return 1;
+    }
+    if (session !== undefined) {
+      const product = lockedProduct(session, verb);
+      if (product !== undefined) {
+        const out = lockedOutcome(session, product, parsed.argv, asksForHelp(parsed.argv), ctx.erisDir);
+        ctx[out.stream].write(out.text);
+        return out.rc;
+      }
+    }
+    const load = handlers[verb];
+    if (!load) throw new Error(`no TypeScript handler for '${verb}'`);
+    const handler = await load();
+    return await handler(parsed.argv.slice(1), { ...ctx, format: parsed.format, ...(session !== undefined ? { session } : {}) });
+  } catch (e) {
+    if (e instanceof CliExit) return e.code;
+    const block = missingDependencyBlock(e, ctx.erisDir);
+    if (block === null) throw e;
+    ctx.stderr.write(block);
+    return 1;
+  }
+}

package/src/main.ts

@@ -0,0 +1,223 @@
+/**
+ * main.ts — the eris program, reached through the `eris` shim.
+ *
+ * One decision per command line (src/cli/router.ts): a TS-routed command runs
+ * in this process behind the global `--output` pre-pass; anything else is
+ * refused as an unknown command, behind the same pre-pass.
+ *
+ * The shim hands over its logical directory through a private variable,
+ * removed before anything is spawned. The shim has already removed
+ * BUN_CONFIG_VERBOSE_FETCH (see its header): it cannot be removed from here,
+ * because bun reads it from its own environment at fetch time and
+ * `delete process.env.X` does not reach that. Before any of that,
+ * `~/.eris/settings.json` fills unset variables in this process's environment
+ * (src/runtime/settings.ts). Everything past the router is imported lazily.
+ *
+ * The commands are core's registry composed with the build's plugin list,
+ * plugins/index.ts (src/cli/compose.ts). Another distribution composes its own
+ * list and calls `runProgram({ cli })` from its entry; a test hands `main` a
+ * composition directly.
+ *
+ * `erisDir` is the shim's directory when the shim ran, else the install root
+ * (src/runtime/home.ts): the checkout, a distribution's own root when its entry
+ * named one (`runProgram({ installRoot })`), or a compiled binary's asset home. A
+ * binary never reads `_ERIS_SHIM_DIR`: only the shim sets it, and a stray value
+ * in a caller's environment must not move the files the binary reads.
+ */
+
+import { PLUGINS } from "../plugins";
+import { asksForHelp, locateVerb } from "./cli/args";
+import { type Cli, composeCli, NO_ENTITLEMENTS, type Session } from "./cli/compose";
+import { sanitizeDisplay } from "./cli/output";
+import { ARGV_SHAPES_NO_ASSETS, REGISTRY } from "./cli/registry";
+import { route, type Impl } from "./cli/router";
+import { adoptSourceIdentity, adoptSourceRoot, adoptUnwrittenHome, type DistributionIdentity, HomeUnwritableError, isCompiled, resolveInstallRoot } from "./runtime/home";
+import { warn } from "./runtime/logging";
+import { applySettings } from "./runtime/settings";
+
+export const SHIM_ENV = ["_ERIS_SHIM_DIR"] as const;
+
+export interface Sink {
+  write(chunk: string): unknown;
+}
+
+export interface CliContext {
+  /** The logical install root: the shim's directory, a distribution's declared root, or a binary's asset home. */
+  erisDir: string;
+  /** The caller's environment, shim variables removed. */
+  env: Record<string, string | undefined>;
+  stdout: Sink;
+  stderr: Sink;
+}
+
+/** What a handler is called with: the command line's context, its output
+ *  format, and the session it runs in (absent when a test calls a handler directly). */
+export type VerbContext = CliContext & { format: "text" | "json"; session?: Session };
+
+export type VerbHandler = (args: string[], ctx: VerbContext) => Promise<number>;
+
+/** The TS implementation of each `ts` row in src/cli/registry.ts, plus the
+ *  argv shapes: the bare program and `-h`/`--help` print the top-level usage. */
+export const HANDLERS: Readonly<Record<string, () => Promise<VerbHandler>>> = {
+  "": async () => (await import("./cli/commands/usage")).runUsage,
+  "-h": async () => (await import("./cli/commands/usage")).runUsage,
+  "--help": async () => (await import("./cli/commands/usage")).runUsage,
+  "--version": async () => (await import("./cli/commands/version")).runVersion,
+  completion: async () => (await import("./cli/commands/completion")).runCompletion,
+  update: async () => (await import("./cli/commands/update")).runUpdate,
+};
+
+/** Core composed with the build's plugin list. */
+export const CLI: Cli = composeCli(REGISTRY, HANDLERS, PLUGINS);
+
+/** The handler an unknown verb reaches, after the global pre-pass. */
+export const UNKNOWN_VERB = "\0unknown";
+
+const unknownCommand =
+  (verb: string): VerbHandler =>
+  async (_args, ctx) => {
+    ctx.stderr.write(`ERROR Unknown command: ${sanitizeDisplay(verb)}. Run 'eris --help'\n`);
+    return 1;
+  };
+
+export interface MainOptions {
+  /** The composed commands; `CLI` when absent. */
+  cli?: Cli;
+  /** The products this workspace has bought; `NO_ENTITLEMENTS` when absent. */
+  entitlements?: ReadonlySet<string>;
+  /** Overrides the composition's router table. */
+  table?: Readonly<Record<string, Impl>>;
+  stdout?: Sink;
+  stderr?: Sink;
+}
+
+/**
+ * A command line that reads nothing from the install root: usage, a `--help`
+ * ahead of any `--`, `--version`, and `completion`. A binary whose asset home cannot be
+ * written still runs these, because they are what an operator reaches for to
+ * find out how to fix it (and `completion` runs on every shell start). Every
+ * other command line is refused with `eris-cache-unwritable`. Only consulted
+ * after the write failed, so a mistake here never reaches a writable cache: a
+ * command wrongly left out gets the block, and one wrongly put in fails on its
+ * own missing file instead of the block.
+ */
+export function readsNoAssets(argv: readonly string[]): boolean {
+  const verb = locateVerb(argv)[0];
+  return verb === "completion" || (verb !== undefined && ARGV_SHAPES_NO_ASSETS.includes(verb)) || asksForHelp(argv);
+}
+
+/**
+ * The command's `erisDir`, or null once `eris-cache-unwritable` has been
+ * written to `stderr` for a command line that needs the asset home.
+ */
+async function resolveErisDir(argv: readonly string[], rawEnv: Record<string, string | undefined>, stderr: Sink): Promise<string | null> {
+  if (!isCompiled && rawEnv._ERIS_SHIM_DIR) return rawEnv._ERIS_SHIM_DIR;
+  try {
+    return await resolveInstallRoot(rawEnv);
+  } catch (e) {
+    if (!(e instanceof HomeUnwritableError)) throw e;
+    if (readsNoAssets(argv)) {
+      adoptUnwrittenHome(e.home);
+      return e.home;
+    }
+    const { renderFailureBlock } = await import("../ts/lib/eris-fail");
+    stderr.write(
+      renderFailureBlock(
+        {
+          slug: "eris-cache-unwritable",
+          what: `eris cannot write its asset cache under ${sanitizeDisplay(e.base)}: ${sanitizeDisplay(e.reason)}`,
+          fix:
+            "set ERIS_CACHE_DIR to a directory eris can write (it keeps one copy of the files compiled into the binary there, per build)\n" +
+            "or set XDG_CACHE_HOME: eris uses $XDG_CACHE_HOME/eris, default ~/.cache/eris",
+        },
+        null,
+      ),
+    );
+    return null;
+  }
+}
+
+export async function main(
+  argv: readonly string[],
+  rawEnv: Record<string, string | undefined> = process.env,
+  opts: MainOptions = {},
+): Promise<number> {
+  const env: Record<string, string | undefined> = { ...rawEnv };
+  const stdout = opts.stdout ?? process.stdout;
+  const stderr = opts.stderr ?? process.stderr;
+  const erisDir = await resolveErisDir(argv, rawEnv, stderr);
+  if (erisDir === null) return 1;
+  for (const k of SHIM_ENV) delete env[k];
+
+  const cli = opts.cli ?? CLI;
+  const session: Session = { cli, entitled: opts.entitlements ?? NO_ENTITLEMENTS };
+  const r = route(argv, opts.table ?? cli.table);
+
+  const { runTsVerb } = await import("./cli/ts-verb");
+  if (r.kind === "unknown") {
+    return runTsVerb(UNKNOWN_VERB, argv, { erisDir, env, stdout, stderr }, { [UNKNOWN_VERB]: async () => unknownCommand(r.verb) }, session);
+  }
+  return runTsVerb(r.verb, argv, { erisDir, env, stdout, stderr }, cli.handlers, session);
+}
+
+/**
+ * End with `code` once both streams have drained, so a pipe reader gets every
+ * byte. The process is left to exit on its own: bun writes to a pipe
+ * asynchronously, and an explicit `process.exit` — even from an empty write's
+ * callback — dropped the tail of a large stdout under load (measured: 12
+ * concurrent `migrate pragma` dry runs, 38 KB each, cut at 21–37 KB).
+ * The unref'd timer only fires if something else is keeping the loop alive.
+ */
+function exitAfterFlush(code: number): void {
+  process.exitCode = code;
+  setTimeout(() => process.exit(code), 10_000).unref();
+}
+
+export interface ProgramOptions extends Pick<MainOptions, "cli" | "entitlements"> {
+  /**
+   * The distribution's root, an absolute path: what a run from source reads its
+   * files from and names its docs under (`ctx.erisDir`, a failure block's local
+   * `docs:` line), in place of this package's directory. Pass the directory
+   * `build()` takes as `root`, so a run from source and the binary read the
+   * same relative paths. A compiled binary ignores it (its asset home is its
+   * root), and the shim's `_ERIS_SHIM_DIR` wins over it.
+   */
+  installRoot?: string;
+  /**
+   * Who the distribution is (`releaseRepo`, `versionExtra`, `docsBase`), for a
+   * run from source: what `eris --version` prints, the repository `eris update`
+   * and `releaseRepo()` name, and the base of a failure block's second `docs:`
+   * line, in place of this repository's. Pass the values `build()` is given, so a
+   * run from source and the binary say the same. Checked as `build()` checks
+   * them. A compiled binary keeps the identity its build baked, whatever is
+   * passed here; no environment variable moves either.
+   */
+  identity?: DistributionIdentity;
+}
+
+/** The process entry: this file's own when run, and a distribution's. */
+export function runProgram(opts: ProgramOptions = {}): void {
+  const { installRoot: root, identity, ...mainOpts } = opts;
+  if (root !== undefined) adoptSourceRoot(root);
+  if (identity !== undefined) adoptSourceIdentity(identity);
+  // A compiled binary has no shim to unset BUN_CONFIG_VERBOSE_FETCH before bun
+  // starts, and `delete` does not reach bun's reader — but an assignment does:
+  // "0" turns verbose fetch off for this process (measured, bun 1.3.13).
+  // Pinned against the binary by tests/compiled-binary.test.ts under ERIS_BIN.
+  if (process.env.BUN_CONFIG_VERBOSE_FETCH !== undefined) process.env.BUN_CONFIG_VERBOSE_FETCH = "0";
+  // Into process.env itself, before routing: TS verbs and their spawns read it
+  // directly.
+  applySettings(process.env, (msg) => warn(msg));
+  // Held until `main` settles. Bun does not count every pending native
+  // operation as keeping the loop alive — an awaited `crypto.subtle.digest`
+  // is one (observed: `eris yak` under load ended at exit 0 with nothing
+  // written, mid idempotency-key digest) — and a loop that drains
+  // with `main` still pending ends the process as a silent success.
+  const hold = setInterval(() => {}, 1 << 30);
+  main(process.argv.slice(2), process.env, mainOpts).finally(() => clearInterval(hold)).then(exitAfterFlush, (e) => {
+    process.stderr.write(`ERROR ${e instanceof Error ? e.message : String(e)}\n`);
+    exitAfterFlush(1);
+  });
+}
+
+if (import.meta.main) runProgram();

package/src/runtime/env.ts

@@ -0,0 +1,16 @@
+/**
+ * env.ts — the ONE way to read an environment variable by a name you were
+ * handed (a `--token-env NAME`, a `${REF}` in a settings file).
+ *
+ * An env object is a plain object, so indexing it with `__proto__` or
+ * `constructor` returns an inherited value and a variable that is not set reads
+ * as set. Only an own property counts. The `env-read-own-property` ast-grep rule
+ * (rules/) keeps every other site off the raw index.
+ */
+
+export type EnvLike = Readonly<Record<string, string | undefined>>;
+
+/** `name`'s value in `env`, or `undefined` when it is not an own property. */
+export function readEnv(env: EnvLike, name: string): string | undefined {
+  return Object.hasOwn(env, name) ? env[name] : undefined;
+}

package/src/runtime/eris-assets.d.ts

@@ -0,0 +1,5 @@
+/** The repo files a compiled binary carries (relative path → text), generated by
+ *  `build()` (src/build.ts) and read only by `src/runtime/home.ts` inside a binary. */
+declare module "eris:assets" {
+  export const ASSETS: Readonly<Record<string, string>>;
+}

package/src/runtime/home.ts

@@ -0,0 +1,306 @@
+/**
+ * home.ts — the install root: the directory eris reads its own repo files from
+ * (the docs a failure block's `docs:` line names). `main.ts` makes it the
+ * command's `erisDir`; `erisHome()` (ts/lib/eris-fail.ts) falls back to it.
+ *
+ * Two ways to run, one answer each:
+ *
+ *   - From a checkout (the `eris` shim → `bun src/main.ts`): the checkout, two
+ *     directories above this file. A distribution run from source is a checkout
+ *     of its own: its entry names its root (`runProgram({ installRoot })`,
+ *     `adoptSourceRoot`), so the files it reads are its own, not those of the
+ *     eris package in its node_modules. A failure block's `docs:` line names a doc
+ *     under that root when it holds the doc, else under the eris package's (the
+ *     order `build()` takes docs in, `docsRoot`).
+ *   - As a compiled binary (`build()`, src/build.ts): the files ride inside the binary
+ *     as the build-generated `eris:assets` module, and are written once per build
+ *     to `${ERIS_CACHE_DIR:-${XDG_CACHE_HOME:-~/.cache}/eris}/<build id>/`, which is
+ *     the root. The build id is a content hash of the assets and the source, so a
+ *     build never reuses another build's files.
+ *
+ * The build's identity (release repository, `--version` line, docs base) follows
+ * the same split: a binary's is baked by `build()` and always wins; a run from
+ * source reports the one its entry adopted (`runProgram({ identity })`,
+ * `adoptSourceIdentity`), else this repository's.
+ *
+ * Only the build defines `__ERIS_BUILD_ID__`, so `typeof` tells the two apart; a
+ * plain `bun` run never reaches the `eris:assets` import, which only the build's
+ * plugin can resolve.
+ *
+ * The write is race-safe, because one binary can start many processes at once:
+ * a marker file names a finished home; otherwise the files go to a private
+ * `<home>.tmp-<pid>-<rand>` beside it, which is renamed into place. A rename
+ * that loses to a peer (EEXIST / ENOTEMPTY) removes its own temp dir and uses
+ * the winner's. Nothing is ever executed from the home.
+ *
+ * A cache base eris cannot write is `HomeUnwritableError`, which `main` turns
+ * into the `eris-cache-unwritable` block. It does not stop a command line that
+ * reads no file from the home (see `readsNoAssets` in main.ts): that one carries
+ * on with the home's path, which then names a directory that does not exist.
+ */
+
+/// <reference path="./eris-assets.d.ts" />
+// The `eris:assets` module `build()` supplies at bundle time: referenced here so a
+// program that imports this file (a distribution through eris/sdk) typechecks with
+// no `files` entry of its own for the declaration.
+
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import pkg from "../../package.json";
+
+declare const __ERIS_BUILD_ID__: string | undefined;
+declare const __ERIS_RELEASE_REPO__: string | undefined;
+declare const __ERIS_VERSION__: string | undefined;
+declare const __ERIS_VERSION_EXTRA__: string | null | undefined;
+declare const __ERIS_DOCS_BASE__: string | undefined;
+
+type Env = Record<string, string | undefined>;
+
+/** The compiled binary's build id; null when running from a checkout. */
+export const BUILD_ID: string | null = typeof __ERIS_BUILD_ID__ === "undefined" ? null : __ERIS_BUILD_ID__;
+
+/** The GitHub repository (`owner/name`) this repository's releases are published to: a build's or a run's, unless its distribution names its own. */
+export const DEFAULT_RELEASE_REPO = "sibylline-labs/eris";
+
+/**
+ * This build's version, from the first source that has one: the tag a build was
+ * given (`build({ tag })`); else the package's own version, which the release
+ * stamps into package.json before it publishes to npm, as `v<version>`; else
+ * `dev` (an untagged build, a checkout, and a git dependency, all `0.0.0`).
+ */
+export function versionOf(bakedTag: string | undefined, packageVersion: string | undefined): string {
+  if (bakedTag !== undefined) return bakedTag;
+  if (packageVersion !== undefined && packageVersion !== "0.0.0" && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(packageVersion)) return `v${packageVersion}`;
+  return "dev";
+}
+
+/** This build's version (`versionOf`): `eris --version` prints it and `eris update` compares releases with it. */
+export const VERSION: string = versionOf(typeof __ERIS_VERSION__ === "string" ? __ERIS_VERSION__ : undefined, BUILD_ID !== null ? undefined : pkg.version);
+
+/** Where a failure block's second `docs:` line points: this repository's public docs. */
+export const DEFAULT_DOCS_BASE = "https://github.com/sibylline-labs/eris/blob/main";
+
+/** True inside a binary built by `build()` (src/build.ts). */
+export const isCompiled = BUILD_ID !== null;
+
+/**
+ * Who a distribution is: what `build()` bakes into its binary (src/build.ts) and
+ * what its entry hands `runProgram({ identity })` for a run from source. Each
+ * field left out is this repository's.
+ */
+export interface DistributionIdentity {
+  /** `owner/name` the distribution's own releases are published to: `eris --version` names it and `eris update` reads it. */
+  readonly releaseRepo?: string;
+  /** One printable line `eris --version` prints after the version line: the core a distribution was built on, say. */
+  readonly versionExtra?: string;
+  /** An https URL (no query, fragment or space) a failure block's second `docs:` line appends the doc path to. */
+  readonly docsBase?: string;
+}
+
+/** A `DistributionIdentity` checked and filled in. */
+export interface Identity {
+  readonly releaseRepo: string;
+  readonly versionExtra: string | null;
+  readonly docsBase: string;
+}
+
+const RELEASE_REPO_SHAPE = /^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9._-]+$/;
+/** One line of printable ASCII, visible at both ends. */
+const VERSION_LINE = /^[\x21-\x7e](?:[\x20-\x7e]{0,118}[\x21-\x7e])?$/;
+/** An https URL with no query, fragment or space, whose trailing slashes are dropped. */
+const DOCS_BASE_URL = /^https:\/\/[A-Za-z0-9.-]+(?::\d+)?(?:\/[A-Za-z0-9._~%/-]*)?$/;
+
+/** `id` checked and filled in with this repository's defaults; the one rule `build()` and `runProgram` both apply. */
+export function resolveIdentity(id: DistributionIdentity = {}): Identity {
+  const releaseRepo = id.releaseRepo ?? DEFAULT_RELEASE_REPO;
+  if (!RELEASE_REPO_SHAPE.test(releaseRepo)) throw new Error(`releaseRepo must be owner/name: ${JSON.stringify(releaseRepo)}`);
+  const versionExtra = id.versionExtra ?? null;
+  if (versionExtra !== null && !VERSION_LINE.test(versionExtra)) {
+    throw new Error(`versionExtra must be one printable line of at most 120 characters: ${JSON.stringify(versionExtra)}`);
+  }
+  const docsBase = (id.docsBase ?? DEFAULT_DOCS_BASE).replace(/\/+$/, "");
+  if (!DOCS_BASE_URL.test(docsBase)) throw new Error(`docsBase must be an https URL with no query, fragment or space: ${JSON.stringify(id.docsBase)}`);
+  return { releaseRepo, versionExtra, docsBase };
+}
+
+/**
+ * The binary's identity, as its build baked it; null outside a binary. Baked
+ * values always win: a binary reports what it was built and released as, and
+ * nothing its entry, its caller or the environment says at run time moves it.
+ */
+const BAKED: Identity | null = isCompiled
+  ? {
+      releaseRepo: typeof __ERIS_RELEASE_REPO__ === "string" ? __ERIS_RELEASE_REPO__ : DEFAULT_RELEASE_REPO,
+      versionExtra: typeof __ERIS_VERSION_EXTRA__ === "string" ? __ERIS_VERSION_EXTRA__ : null,
+      docsBase: typeof __ERIS_DOCS_BASE__ === "string" ? __ERIS_DOCS_BASE__ : DEFAULT_DOCS_BASE,
+    }
+  : null;
+
+let sourceIdentity: Identity = resolveIdentity();
+
+/**
+ * A distribution's identity, for a run from source (`runProgram({ identity })`,
+ * src/main.ts): what `identity()` answers with in place of this repository's.
+ * Checked as `build()` checks it, so a source run never reports what its binary
+ * could not; a compiled binary checks it too, then keeps its baked identity.
+ */
+export function adoptSourceIdentity(id: DistributionIdentity): void {
+  sourceIdentity = resolveIdentity(id);
+}
+
+/** This process's identity: a binary's baked one, else the one its entry adopted, else this repository's. */
+export function identity(): Identity {
+  return BAKED ?? sourceIdentity;
+}
+
+/** Where this build's own releases are published (`identity().releaseRepo`): what `eris update` reads. */
+export function releaseRepo(): string {
+  return identity().releaseRepo;
+}
+
+/** The file whose presence marks a home as completely written. */
+export const HOME_MARKER = ".eris-home-complete";
+
+/** The checkout this source file sits in. Meaningless inside a binary. */
+export function checkoutRoot(): string {
+  return resolve(import.meta.dir, "..", "..");
+}
+
+/** `${ERIS_CACHE_DIR:-${XDG_CACHE_HOME:-~/.cache}/eris}` — the parent of every build's home. */
+export function cacheBase(env: Env): string {
+  if (env.ERIS_CACHE_DIR) return env.ERIS_CACHE_DIR;
+  const xdg = env.XDG_CACHE_HOME || join(env.HOME || homedir(), ".cache");
+  return join(xdg, "eris");
+}
+
+/** A relative path with no `..`, no empty and no absolute segment. */
+function safeRel(rel: string): boolean {
+  return rel !== "" && !rel.startsWith("/") && rel.split("/").every((s) => s !== "" && s !== "." && s !== "..");
+}
+
+const errCode = (e: unknown) => (typeof e === "object" && e !== null ? (e as { code?: unknown }).code : undefined);
+
+/**
+ * `<base>/<buildId>/`, holding `assets` (relative path → text) and the marker.
+ * Returns the home. Writes nothing when the marker is already there.
+ */
+export function materializeHome(base: string, buildId: string, assets: Readonly<Record<string, string>>): string {
+  const home = join(base, buildId);
+  const marker = join(home, HOME_MARKER);
+  if (existsSync(marker)) return home;
+  mkdirSync(base, { recursive: true });
+  const tmp = `${home}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
+  try {
+    for (const [rel, text] of Object.entries(assets)) {
+      if (!safeRel(rel)) throw new Error(`eris asset path is not a plain relative path: ${JSON.stringify(rel)}`);
+      const file = join(tmp, rel);
+      mkdirSync(dirname(file), { recursive: true });
+      writeFileSync(file, text);
+    }
+    writeFileSync(join(tmp, HOME_MARKER), `${buildId}\n`);
+    renameSync(tmp, home);
+    return home;
+  } catch (e) {
+    rmSync(tmp, { recursive: true, force: true });
+    const code = errCode(e);
+    if (code !== "EEXIST" && code !== "ENOTEMPTY") throw e;
+  }
+  // A peer renamed its copy into place first.
+  if (existsSync(marker)) return home;
+  throw new Error(`${home} exists but is not a complete eris asset home (no ${HOME_MARKER}) — remove it and run eris again`);
+}
+
+let compiledRoot: string | undefined;
+let sourceRoot: string | undefined;
+
+/**
+ * A distribution's own root, for a run from source (`runProgram({ installRoot })`,
+ * src/main.ts): `installRoot()` answers with it in place of `checkoutRoot()`.
+ * A compiled binary ignores it, because its asset home is its root.
+ */
+export function adoptSourceRoot(dir: string): void {
+  if (!isAbsolute(dir)) throw new Error(`installRoot must be an absolute path: ${JSON.stringify(dir)}`);
+  sourceRoot = dir;
+}
+
+/** The binary's asset home could not be written: the cache base is read-only, full, or not a directory. */
+export class HomeUnwritableError extends Error {
+  constructor(
+    /** The cache base, `${ERIS_CACHE_DIR:-${XDG_CACHE_HOME:-~/.cache}/eris}`. */
+    readonly base: string,
+    /** Where the home would have been: `<base>/<build id>`. */
+    readonly home: string,
+    readonly reason: string,
+  ) {
+    super(`cannot write eris's asset home ${home}: ${reason}`);
+  }
+}
+
+/**
+ * The install root for this process, materializing a binary's home on first
+ * call. Throws `HomeUnwritableError` when the home cannot be written.
+ */
+export async function resolveInstallRoot(env: Env): Promise<string> {
+  if (!isCompiled) return sourceRoot ?? checkoutRoot();
+  if (compiledRoot === undefined) {
+    const { ASSETS } = await import("eris:assets");
+    const base = cacheBase(env);
+    try {
+      compiledRoot = materializeHome(base, BUILD_ID as string, ASSETS);
+    } catch (e) {
+      throw new HomeUnwritableError(base, join(base, BUILD_ID as string), e instanceof Error ? e.message : String(e));
+    }
+  }
+  return compiledRoot;
+}
+
+/**
+ * Carry on without a written home: `installRoot()` answers with the path the
+ * home would have had, so a block rendered afterwards still names one. For a
+ * command line that reads nothing from it, after `resolveInstallRoot` threw.
+ */
+export function adoptUnwrittenHome(home: string): void {
+  compiledRoot = home;
+  homeUnwritten = true;
+}
+
+let homeUnwritten = false;
+
+/** Whether the install root was adopted without its files being written (`eris-cache-unwritable`). */
+export function installRootIsUnwritten(): boolean {
+  return homeUnwritten;
+}
+
+/** The install root without materializing: a binary's must already be resolved by `main`. */
+export function installRoot(): string {
+  if (!isCompiled) return sourceRoot ?? checkoutRoot();
+  if (compiledRoot === undefined) throw new Error("eris install root read before main() resolved it");
+  return compiledRoot;
+}
+
+/**
+ * The first of `roots` that holds the repo-relative doc `rel` (an `#anchor` is
+ * ignored) as a file. `build()` takes each doc the source names from its doc
+ * roots by this rule, and `docsRoot` names a run from source's by it, so a
+ * binary and the source run point at the same copy.
+ */
+export function firstDocRoot(roots: readonly string[], rel: string): string | undefined {
+  const file = rel.split("#")[0]!;
+  return roots.find((r) => existsSync(join(r, file)) && statSync(join(r, file)).isFile());
+}
+
+/**
+ * The root a failure block's local `docs:` line names `rel` under, given the
+ * `home` it was handed. When `home` is the install root of a run from source, that
+ * is the install root, then this package's root, as `build()` falls back for the
+ * binary: a distribution carries only the docs it owns, and a line naming a core
+ * doc under its root would name a file that is not there. A compiled binary's home
+ * already holds every doc its source names; an `ERIS_DIR` or any other `home` is
+ * the caller's say, and a doc that neither root holds keeps `home`.
+ */
+export function docsRoot(home: string, rel: string): string {
+  if (isCompiled || home !== installRoot()) return home;
+  return firstDocRoot([home, checkoutRoot()], rel) ?? home;
+}