@sibylline-labs/eris 0.0.0-stage → 0.3.0

package/src/cli/compose.ts

@@ -0,0 +1,273 @@
+/**
+ * compose.ts — core rows plus plugin rows, merged once, before anything is
+ * derived from them.
+ *
+ * `composeCli` is called by a distribution's entry (src/main.ts composes the
+ * build's list, plugins/index.ts). Its result, a `Cli`, is what the router,
+ * the `--output json` allow-list, completion and the top-level help read, so a
+ * plugin's rows reach every plane a core row does with no core edit.
+ *
+ * A plugin that would break a plane is refused here, at composition, which
+ * runs when the build validates its plugin list (src/build.ts) and when the
+ * program starts:
+ *
+ *   - a group that collides with a built-in, an argv shape or another plugin;
+ *   - anything but a `ts` implementation (a row from untyped code can name
+ *     one the type does not allow, and no other runs);
+ *   - a sub row with no parent, a group with no handler, a handler with no group;
+ *   - `json: true` on a group that has subs: the allow-list would accept every
+ *     sub, including one added later with no machine rendering. Each sub that
+ *     renders JSON says so on its own row, so the allow-list fails closed;
+ *   - a completion slot the emitted script cannot hold (`complete` on a row, core's
+ *     or a plugin's): a word that is not shell-safe, a domain helper or library text that fails
+ *     src/cli/commands/completion/domain.ts, or one domain (or one helper
+ *     function) given two different texts across the build;
+ *   - a `menu` that is not a handler thunk, or a `completionNote` that is not
+ *     one or more non-empty lines of printable ASCII.
+ *
+ * A distribution may own the bare program (`eris` with no arguments): its
+ * `menu` handler replaces core's usage there; `-h` and `--help` stay the usage,
+ * and say that bare `eris` is interactive. It may also add a paragraph to
+ * `eris completion --help` (`completionNote`).
+ *
+ * Entitlements are not composition: a `Cli` says which product each plugin
+ * group belongs to, and `lockedProduct` checks a workspace's entitlements
+ * against it per command line.
+ */
+
+import type { VerbHandler } from "../main";
+import { helpText } from "./args";
+import { renderFailureBlock } from "../../ts/lib/eris-fail";
+import { domainFunction, helperTexts, scanHelper, slotWordRefusal } from "./commands/completion/domain";
+import { jsonFixLine, unsupportedFix } from "./output";
+import type { ErisPlugin } from "./plugin";
+import { ARGV_SHAPES, deriveJsonSurfaces, deriveTable, type Impl, type Row } from "./registry";
+
+type Rows = Readonly<Record<string, Row>>;
+type Handlers = Readonly<Record<string, () => Promise<VerbHandler>>>;
+
+export class PluginCompositionError extends Error {
+  override name = "PluginCompositionError";
+}
+
+export interface PluginGroup {
+  readonly group: string;
+  readonly summary: string;
+  readonly plugin: string;
+  readonly product?: string;
+}
+
+export interface Cli {
+  /** Core rows and every plugin's rows. */
+  readonly registry: Rows;
+  readonly table: Readonly<Record<string, Impl>>;
+  readonly handlers: Handlers;
+  readonly jsonSurfaces: Readonly<Record<string, true | readonly string[]>>;
+  /** The `output-json-unsupported` fix text: core's, with each plugin's `jsonFix`, or a line per json row, in its plugin slot. */
+  readonly jsonFix: string;
+  /** The plugin groups, in composition order. */
+  readonly groups: readonly PluginGroup[];
+  /** Whether the bare program is a distribution's menu: the top-level usage then points at it. */
+  readonly hasMenu: boolean;
+  /** The distribution's paragraph of `eris completion --help` (`ComposeOptions.completionNote`), or null. */
+  readonly completionNote: string | null;
+}
+
+/** A composed CLI and the workspace's entitlements: what one command line runs against. */
+export interface Session {
+  readonly cli: Cli;
+  readonly entitled: ReadonlySet<string>;
+}
+
+/** The entitlements a command line has when its caller supplies none: no
+ *  product, so every product-gated plugin group is locked. */
+export const NO_ENTITLEMENTS: ReadonlySet<string> = new Set();
+
+const COMMAND_NAME = /^[a-z][a-z0-9-]*$/;
+/** Lines of printable ASCII, none empty, as `eris completion --help` prints them. */
+const COMPLETION_NOTE = /^[\x20-\x7e]+(?:\n[\x20-\x7e]+)*$/;
+
+export interface ComposeOptions {
+  /** The bare program's handler (`eris` with no arguments); core's usage when absent.
+   *  The top-level usage then also says `Run 'eris' without arguments for interactive mode.` */
+  readonly menu?: () => Promise<VerbHandler>;
+  /** A paragraph `eris completion --help` prints after core's description: what
+   *  this distribution's completion domains offer. One or more lines of printable
+   *  ASCII, none empty, no trailing newline. */
+  readonly completionNote?: string;
+}
+
+/** The completion domains a build has seen, so one name or function keeps one text. */
+interface DomainLedger {
+  readonly domains: Map<string, { readonly texts: readonly string[]; readonly by: string }>;
+  readonly functions: Map<string, { readonly text: string; readonly by: string }>;
+}
+
+/** Refuses a row whose `complete` slots the emitted script cannot hold. `by` names the row's owner in a later refusal. */
+function checkSlots(path: string, row: Row, by: string, ledger: DomainLedger, refuse: (what: string) => never): void {
+  (row.complete ?? []).forEach((slot, n) => {
+    for (const word of slot) {
+      const why = slotWordRefusal(word);
+      if (why !== null) refuse(`row '${path}' slot ${n}: ${why}`);
+      if (typeof word === "string") continue;
+      const d = `domain '${word.domain}'`;
+      const texts = helperTexts(word);
+      const prior = ledger.domains.get(word.domain);
+      if (prior !== undefined) {
+        if (prior.texts.join("\0") !== texts.join("\0")) refuse(`${d}: it carries a different helper or library from ${prior.by}`);
+        continue;
+      }
+      const defined: string[] = [];
+      texts.forEach((text, k) => {
+        const what = k === texts.length - 1 ? "its helper" : `its library text ${k}`;
+        const scan = scanHelper(text);
+        if (!scan.ok) return refuse(`${d}: ${what} ${scan.why}`);
+        if (k === texts.length - 1 && scan.function !== domainFunction(word.domain)) refuse(`${d}: its helper defines ${scan.function}, not ${domainFunction(word.domain)}`);
+        if (k < texts.length - 1 && scan.function === domainFunction(word.domain)) refuse(`${d}: its library defines ${scan.function}, which is its helper's`);
+        const other = ledger.functions.get(scan.function);
+        if (other !== undefined && other.text !== text) refuse(`${d}: ${what} defines '${scan.function}', which ${other.by} defines with other text`);
+        defined.push(scan.function);
+      });
+      texts.forEach((text, k) => ledger.functions.set(defined[k]!, { text, by }));
+      ledger.domains.set(word.domain, { texts, by });
+    }
+  });
+}
+
+export function composeCli(coreRows: Rows, coreHandlers: Handlers, plugins: readonly ErisPlugin[], opts: ComposeOptions = {}): Cli {
+  const registry: Record<string, Row> = { ...coreRows };
+  const handlers: Record<string, () => Promise<VerbHandler>> = { ...coreHandlers };
+  if (opts.menu !== undefined) {
+    if (typeof opts.menu !== "function") throw new PluginCompositionError("menu must be a handler thunk, () => Promise<VerbHandler>");
+    handlers[""] = opts.menu;
+  }
+  if (opts.completionNote !== undefined && (typeof opts.completionNote !== "string" || !COMPLETION_NOTE.test(opts.completionNote))) {
+    throw new PluginCompositionError("completionNote must be one or more non-empty lines of printable ASCII");
+  }
+  const owner = new Map<string, string | null>();
+  for (const k of [...Object.keys(ARGV_SHAPES), ...Object.keys(coreRows).filter((k) => !k.includes(" "))]) owner.set(k, null);
+  const names = new Set<string>();
+  const groups: PluginGroup[] = [];
+  const fixLines: string[] = [];
+  const ledger: DomainLedger = { domains: new Map(), functions: new Map() };
+  const refuseCore = (what: string): never => {
+    throw new PluginCompositionError(`core: ${what}`);
+  };
+  for (const [path, row] of Object.entries(coreRows)) checkSlots(path, row, "core", ledger, refuseCore);
+
+  for (const p of plugins) {
+    const refuse = (what: string): never => {
+      throw new PluginCompositionError(`plugin '${p.name}': ${what}`);
+    };
+    if (names.has(p.name)) throw new PluginCompositionError(`plugin '${p.name}' is composed twice`);
+    names.add(p.name);
+    const paths = Object.keys(p.rows);
+    const own = paths.filter((k) => !k.includes(" "));
+    const generated: string[] = [];
+
+    for (const g of own) {
+      if (!COMMAND_NAME.test(g)) refuse(`group '${g}' is not a command name (lower-case letters, digits, '-')`);
+      if (owner.has(g)) {
+        const prior = owner.get(g);
+        refuse(`group '${g}' collides with ${prior === null ? "a built-in command" : `plugin '${prior}'`}`);
+      }
+      if (p.rows[g]!.impl !== "ts") refuse(`group '${g}' must be impl 'ts'`);
+      if (!Object.hasOwn(p.handlers, g)) refuse(`group '${g}' has no handler`);
+    }
+    for (const path of paths) {
+      const row = p.rows[path]!;
+      const words = path.split(" ");
+      if (words.length > 1) {
+        const parent = words.slice(0, -1).join(" ");
+        if (!Object.hasOwn(p.rows, parent)) refuse(`row '${path}' hangs off '${parent}', which the plugin does not declare`);
+        if (row.impl !== undefined && row.impl !== "ts") refuse(`row '${path}' must not name an impl other than 'ts'`);
+      }
+      checkSlots(path, row, `plugin '${p.name}'`, ledger, refuse);
+      if (row.json === true) {
+        if (paths.some((k) => k.startsWith(`${path} `))) refuse(`row '${path}' has subs, so json goes on each sub that renders it`);
+        generated.push(jsonFixLine(path, row.summary));
+      }
+    }
+    for (const h of Object.keys(p.handlers)) if (!own.includes(h)) refuse(`handler '${h}' has no group row`);
+    if (p.jsonFix !== undefined) {
+      if (generated.length === 0) refuse("jsonFix is set but no row says json: true");
+      if (!p.jsonFix.endsWith("\n")) refuse("jsonFix must end with a newline");
+      fixLines.push(p.jsonFix);
+    } else fixLines.push(...generated);
+
+    for (const g of own) {
+      owner.set(g, p.name);
+      groups.push({ group: g, summary: p.rows[g]!.summary, plugin: p.name, ...(p.product !== undefined ? { product: p.product } : {}) });
+    }
+    Object.assign(registry, p.rows);
+    Object.assign(handlers, p.handlers);
+  }
+
+  return {
+    registry,
+    table: deriveTable(registry),
+    handlers,
+    jsonSurfaces: deriveJsonSurfaces(registry),
+    jsonFix: unsupportedFix(fixLines),
+    groups,
+    hasMenu: opts.menu !== undefined,
+    completionNote: opts.completionNote ?? null,
+  };
+}
+
+/** The product `group` needs and the session has not bought, else undefined. */
+export function lockedProduct(session: Session, group: string): string | undefined {
+  const product = session.cli.groups.find((g) => g.group === group)?.product;
+  return product !== undefined && !session.entitled.has(product) ? product : undefined;
+}
+
+const lockedWhy = (product: string) => `part of the '${product}' product, which this workspace has not bought`;
+
+/** The top-level help's command lines: each core group, then each plugin
+ *  group (a locked one marked), every summary starting in one column. */
+export function commandLines(session: Session): string {
+  const { registry, groups } = session.cli;
+  const plugin = new Set(groups.map((g) => g.group));
+  const core = Object.keys(registry)
+    .filter((k) => !k.includes(" ") && !plugin.has(k))
+    .map((group) => ({ group, summary: registry[group]!.summary }));
+  const rows = [...core, ...groups];
+  const width = Math.max(...rows.map((r) => r.group.length));
+  return rows
+    .map((r) => {
+      const product = lockedProduct(session, r.group);
+      return `  ${r.group.padEnd(width)}  ${r.summary}${product !== undefined ? ` [locked: ${product}]` : ""}\n`;
+    })
+    .join("");
+}
+
+/**
+ * What a locked command line prints. Help (`--help` ahead of any `--`) is the
+ * deepest row's generated help plus why it is locked, on stdout, exit 0: it
+ * reads the rows only, never the plugin's handler. Anything else is the
+ * `command-locked` block on stderr, exit 1.
+ */
+export function lockedOutcome(session: Session, product: string, words: readonly string[], help: boolean, home: string): { stream: "stdout" | "stderr"; text: string; rc: number } {
+  const group = words[0]!;
+  if (help) {
+    let path = group;
+    for (const w of words.slice(1)) {
+      if (!Object.hasOwn(session.cli.registry, `${path} ${w}`)) break;
+      path = `${path} ${w}`;
+    }
+    return { stream: "stdout", text: `${helpText(path, session.cli.registry[path]!)}\nLocked: ${lockedWhy(product)}.\n`, rc: 0 };
+  }
+  return {
+    stream: "stderr",
+    rc: 1,
+    text: renderFailureBlock(
+      {
+        slug: "command-locked",
+        what: `'eris ${group}' is ${lockedWhy(product)}`,
+        fix: `add the '${product}' product to this workspace, then run the command again`,
+        docs: "docs/ERRORS.md#command-locked",
+      },
+      home,
+    ),
+  };
+}

package/src/cli/output.ts

@@ -0,0 +1,81 @@
+/**
+ * output.ts — the output contract's checks: which surfaces accept
+ * `--output json`, the refusal for one that does not, and how a value is
+ * echoed into a diagnostic. The global `--output` parse itself is argv
+ * parsing, in src/cli/args.ts.
+ *
+ * The refusal blocks are the contract in docs/OUTPUT-CONTRACT.md §2–§4;
+ * `tests/cli-router.test.ts` holds them against the earlier Bash
+ * implementation's answers, frozen in
+ * tests/fixtures/yaml-parity/oracle-goldens.json.
+ */
+
+import { renderFailureBlock } from "../../ts/lib/eris-fail";
+import { deriveJsonSurfaces } from "./registry";
+
+export type OutputFormat = "text" | "json";
+
+/** A value echoed into a diagnostic: C0 controls except tab and newline, plus
+ *  DEL, removed; then every trailing newline dropped. */
+export function sanitizeDisplay(s: string): string {
+  return s.replace(/[\x00-\x08\x0b-\x1f\x7f]/g, "").replace(/\n+$/, "");
+}
+
+/**
+ * The surfaces with a machine rendering: a group maps to `true` (every sub)
+ * or to the subs that qualify. Derived from the registry's `json` rows;
+ * `unsupportedJsonBlock` is its only reader.
+ */
+export const JSON_SURFACES: Readonly<Record<string, true | readonly string[]>> = deriveJsonSurfaces();
+
+/** The column a json surface's shape starts at in the refusal's fix text. */
+export const FIX_COLUMN = 43;
+
+/** One line of the refusal's fix text: `  eris <path>`, then from `FIX_COLUMN` what it prints. */
+export function jsonFixLine(path: string, shape: string): string {
+  const head = `  eris ${path}`;
+  return `${head}${" ".repeat(Math.max(1, FIX_COLUMN - head.length))}${shape}\n`;
+}
+
+/** The refusal's fix text: this header and core's own json surfaces, then each
+ *  plugin's lines (src/cli/compose.ts): the plugin's own `jsonFix`, else a
+ *  line per json row. A json row or argv shape added to core is named here too
+ *  (tests/cli-router.test.ts holds the two together). */
+export const UNSUPPORTED_FIX_SURFACES = `the surfaces that accept --output json are:
+${jsonFixLine("--version", "{version, release_repo, build_id, extra}")}${jsonFixLine("update", "{current, latest, update_available, updated}")}`;
+
+/** The fix text with `lines` (each ending in a newline) after the header. The
+ *  last newline is dropped: a trailing one renders as an empty `fix:` line. */
+export function unsupportedFix(lines: readonly string[] = []): string {
+  return `${UNSUPPORTED_FIX_SURFACES}${lines.join("")}`.replace(/\n$/, "");
+}
+
+export const UNSUPPORTED_FIX = unsupportedFix();
+
+/** `output::assert_supported`. Returns the refusal block, or null. A composed
+ *  build passes its own allow-list and fix text (src/cli/compose.ts). */
+export function unsupportedJsonBlock(
+  group: string | undefined,
+  sub: string | undefined,
+  format: OutputFormat,
+  home: string,
+  surfaces: Readonly<Record<string, true | readonly string[]>> = JSON_SURFACES,
+  fix: string = UNSUPPORTED_FIX,
+): string | null {
+  if (format !== "json") return null;
+  const g = group ?? "";
+  const s = sub ?? "";
+  const surface = Object.hasOwn(surfaces, g) ? surfaces[g] : undefined;
+  if (surface === true || (surface && surface.includes(s))) return null;
+  return renderFailureBlock(
+    {
+      slug: "output-json-unsupported",
+      what:
+        `'eris ${sanitizeDisplay(`${g}${s !== "" ? ` ${s}` : ""}`)}' has no JSON rendering — ` +
+        "refusing --output json rather than printing human text a parser would read as JSON",
+      fix,
+      docs: "docs/OUTPUT-CONTRACT.md#3-machine-surfaces",
+    },
+    home,
+  );
+}

package/src/cli/plugin.ts

@@ -0,0 +1,85 @@
+/**
+ * plugin.ts — the plugin SDK: the contract a plugin is written against, and
+ * the one eris module a plugin imports (the `plugin-imports-sdk-only`
+ * ast-grep rule in rules/ holds it).
+ *
+ * A plugin is a package exporting registry rows plus handlers:
+ *
+ *   - `rows`: pure data, the same `Row` shape as src/cli/registry.ts. A group
+ *     row (one word) says `impl: "ts"`; sub rows hang off it. The router table,
+ *     the argv parse, the `--output json` allow-list, completion and the
+ *     top-level help all derive from them once composed (src/cli/compose.ts).
+ *   - `handlers`: one thunk per group, `async () => (await import("./x")).run`.
+ *     The manifest is read on every command line, `eris completion` included,
+ *     and a thunk is called only on dispatch, so plugin code never loads at
+ *     shell start (`plugin-manifest-lazy-handlers`).
+ *   - `product`: absent for a plugin every workspace gets; else the product a
+ *     workspace must have bought, without which its commands render as locked.
+ *
+ * Composition is build-time: a distribution's entry composes core with its
+ * plugin list and hands the result to `runProgram` (src/main.ts). There is no
+ * runtime plugin loader. docs/dev/PLUGINS.md is the authoring guide.
+ *
+ * Everything here is on the completion path through the manifests: it imports
+ * only modules that path already loads.
+ */
+
+import type { CliContext, VerbContext, VerbHandler } from "../main";
+import { type ArgSinks, type GroupArgs, groupArgsIn, type ReadOptions, readRowArgs, type RowArgs } from "./args";
+import type { CompletionDomain, Flag, FlagName, Row, SlotWord } from "./registry";
+
+export { erisHome, renderFailureBlock, renderWarnLines } from "../../ts/lib/eris-fail";
+export { readEnv } from "../runtime/env";
+export { CliExit } from "./args";
+export type { ArgSinks, CliContext, CompletionDomain, Flag, FlagName, GroupArgs, ReadOptions, Row, RowArgs, SlotWord, VerbContext, VerbHandler };
+
+type Rows = Readonly<Record<string, Row>>;
+
+/** The one-word keys of a rows table: its groups. */
+export type GroupsOf<R> = { [K in keyof R & string]: K extends `${string} ${string}` ? never : K }[keyof R & string];
+
+export interface ErisPlugin<R extends Rows = Rows> {
+  /** Unique across a build; named in every composition refusal. */
+  readonly name: string;
+  readonly product?: string;
+  readonly rows: R;
+  readonly handlers: Readonly<Record<string, () => Promise<VerbHandler>>>;
+  /**
+   * The plugin's lines in the `output-json-unsupported` fix text, written
+   * like core's (src/cli/output.ts): `  eris <verb>`, then from column 43 the
+   * JSON shape it prints, each line ending in a newline. Absent, compose
+   * writes one line per json row from its summary.
+   */
+  readonly jsonFix?: string;
+}
+
+/** A plugin, with a handler required for each group its rows declare. */
+export function definePlugin<const R extends Rows>(plugin: {
+  readonly name: string;
+  readonly product?: string;
+  readonly rows: R;
+  readonly handlers: { readonly [G in GroupsOf<R>]: () => Promise<VerbHandler> };
+  readonly jsonFix?: string;
+}): ErisPlugin<R> {
+  return plugin;
+}
+
+/**
+ * A handler's argv, read from its row: the row's flags and operands exactly,
+ * typed from the row's literal declaration. Help goes to stdout and returns
+ * null (the handler returns 0); a refusal goes to stderr, then `CliExit(1)`.
+ */
+export function readArgs<R extends Rows, P extends keyof R & string>(
+  rows: R,
+  path: P,
+  argv: readonly string[],
+  io: ArgSinks,
+  opts: ReadOptions = {},
+): RowArgs<R[P]> | null {
+  return readRowArgs(path, rows[path]!, argv, io, opts);
+}
+
+/** A group handler's first word: `bare`, `help`, one of the group's subs, or `unknown`. */
+export function groupArgs<R extends Rows>(rows: R, group: GroupsOf<R>, argv: readonly string[]) {
+  return groupArgsIn(rows, group, argv);
+}

package/src/cli/registry.ts

@@ -0,0 +1,180 @@
+/**
+ * registry.ts — every eris verb, once.
+ *
+ * A row is keyed by its command path: a group (`"completion"`), a group and a
+ * sub (`"completion bash"`), or a nested sub (`"group sub nested"`). A group
+ * row names its implementation; a sub row inherits its parent's unless it names
+ * its own. The one implementation is `ts`, which runs in-process; a row from
+ * untyped code naming any other is refused at composition (src/cli/compose.ts).
+ * `flags` are the long flags the verb accepts, `--help`
+ * aside (every verb takes it); `pos` its positional operands. `json` marks a
+ * surface that accepts the global `--output json`.
+ *
+ * Read by: the argv parser (src/cli/args.ts — a TS verb's flags and operands
+ * are exactly its row's, and its handler's argument type is derived from the
+ * row), the router (`TABLE`, src/cli/router.ts), the `--output json`
+ * allow-list (src/cli/output.ts),
+ * and the completion emitter (src/cli/commands/completion/emit.ts), which
+ * generates the shell tab-completion tree from these rows.
+ *
+ * This module is on the path of every command line, the shell-start
+ * completion run included: it imports nothing.
+ */
+
+export type Impl = "ts";
+
+export type FlagName = `--${string}`;
+
+export interface Flag {
+  readonly name: FlagName;
+  readonly takesValue: boolean;
+  /** A value flag that may be given more than once; its values are kept in order. */
+  readonly repeatable?: boolean;
+  /** A one-letter spelling the parser also accepts (`-y` for `--yes`). */
+  readonly alias?: `-${string}`;
+  /** A value flag whose value is the next operand rather than the next word: a
+   *  declared flag may sit between (`--from --yes f`), and a dash-led word
+   *  directly after it is the value (`--from -f`). */
+  readonly deferredValue?: boolean;
+  /** A value flag whose value is a file name: tab completion offers file names
+   *  after it. Read from the composed rows, so a plugin declares its own. */
+  readonly file?: boolean;
+}
+
+export interface Row {
+  readonly summary: string;
+  /** Required on a group row; a sub row inherits its parent's. */
+  readonly impl?: Impl;
+  readonly flags?: readonly Flag[];
+  readonly json?: boolean;
+  /** The positional operands of a TS leaf, in order: `name`, `name?` (optional),
+   *  `name...` (every remaining word). A leaf without `pos` takes none, and a
+   *  word past the last is refused (src/cli/args.ts). */
+  readonly pos?: readonly string[];
+  /** The usage line after `eris <path> `, quoted in every argument refusal and
+   *  heading the generated help. Absent: generated from `pos` and `flags`. */
+  readonly usage?: string;
+  /** Said in the extra-word refusal, e.g. "quote the statement". */
+  readonly extraHint?: string;
+  /** Tab completion for the positional operands, one entry per slot, in
+   *  order: the words a slot offers. A word is a literal, `@file` (file
+   *  names: the slot offers nothing else), or a `CompletionDomain`. A slot
+   *  past the last entry completes nothing. Checked at composition. */
+  readonly complete?: readonly (readonly SlotWord[])[];
+}
+
+/**
+ * A slot whose words only a shell function can list at tab-press time: names
+ * the distribution keeps in a file, say. `helper` is shell text, bash-3.2
+ * clean (the zsh route loads the same body), holding exactly one function
+ * definition, `__eris_dom_<name>` for `@<name>`. That function is called with
+ * the words typed in the earlier positional slots and prints its words;
+ * `compgen -W` expands them, so it must print shell-safe words only. Functions
+ * it calls go in `library`, one definition per text, each `__eris_dom_…`;
+ * domains that share a library hand over the same texts, emitted once.
+ *
+ * The texts bypass the emitter's word checks, so composition checks them
+ * instead (src/cli/commands/completion/domain.ts). They are trusted like a
+ * plugin's handler code: the check keeps a mistake from breaking or running
+ * code in every shell that sources `eris completion`, not a hostile author out.
+ */
+export interface CompletionDomain {
+  /** `@` then lower-case letters, digits, `_`; `@file` is built in. */
+  readonly domain: `@${string}`;
+  readonly helper: string;
+  readonly library?: readonly string[];
+}
+
+export type SlotWord = string | CompletionDomain;
+
+/** Every verb, as declared: the literal types the parser derives a handler's
+ *  argument type from. `REGISTRY` is the same object for code that walks it.
+ *  Core declares `completion` and `update`; every other group is a plugin's
+ *  (plugins/index.ts, composed by src/cli/compose.ts). */
+export const VERBS = {
+  completion: { impl: "ts", summary: "Emit shell tab-completion script (bash, zsh)" },
+  "completion bash": { summary: "Emit the bash completion script" },
+  "completion zsh": { summary: "Emit the zsh completion script" },
+  update: { impl: "ts", summary: "Print how to get the latest eris release (npx, bunx)", json: true },
+} as const satisfies Readonly<Record<string, Row>>;
+
+export type VerbPath = keyof typeof VERBS;
+
+export const REGISTRY: Readonly<Record<string, Row>> = VERBS;
+
+/** The argv shapes that are not verbs: the bare program, the top-level
+ *  help and the version. */
+export const ARGV_SHAPES: Readonly<Record<string, Impl>> = { "": "ts", "-h": "ts", "--help": "ts", "--version": "ts" };
+
+/** The argv shapes that render JSON under the global `--output`. */
+export const ARGV_SHAPE_JSON: readonly string[] = ["--version"];
+
+/** The argv shapes, beyond a `--help`, that print from the binary alone and
+ *  read nothing from the install root. The bare program is not one: a
+ *  distribution's menu may read it. */
+export const ARGV_SHAPES_NO_ASSETS: readonly string[] = ["--version"];
+
+export function groupOf(path: string): string {
+  return path.split(" ")[0]!;
+}
+
+/** A row's implementation: its own, else its nearest ancestor's. */
+export function implOf(path: string, reg: Readonly<Record<string, Row>> = REGISTRY): Impl {
+  const words = path.split(" ");
+  for (let n = words.length; n > 0; n--) {
+    const impl = reg[words.slice(0, n).join(" ")]?.impl;
+    if (impl !== undefined) return impl;
+  }
+  throw new Error(`no implementation for '${path}'`);
+}
+
+/** The direct subs of a row, in key order. */
+export function subsOf(path: string, reg: Readonly<Record<string, Row>> = REGISTRY): string[] {
+  const depth = path.split(" ").length + 1;
+  return Object.keys(reg)
+    .filter((k) => k.startsWith(`${path} `) && k.split(" ").length === depth)
+    .map((k) => k.split(" ")[depth - 1]!);
+}
+
+/** The group row and every row under it. */
+export function rowsOfGroup(group: string, reg: Readonly<Record<string, Row>> = REGISTRY): string[] {
+  return Object.keys(reg).filter((k) => k === group || k.startsWith(`${group} `));
+}
+
+export function flagsOf(path: string, reg: Readonly<Record<string, Row>> = REGISTRY): readonly Flag[] {
+  return reg[path]?.flags ?? [];
+}
+
+/**
+ * The router's table. A row per group plus the argv shapes; a `"group sub"`
+ * row only where it changes the answer or names a TS sub: the router reads at
+ * most two words, so a nested row never reaches it.
+ */
+export function deriveTable(reg: Readonly<Record<string, Row>> = REGISTRY): Record<string, Impl> {
+  const table: Record<string, Impl> = { ...ARGV_SHAPES };
+  for (const path of Object.keys(reg)) {
+    const words = path.split(" ");
+    if (words.length === 1) table[path] = implOf(path, reg);
+    else if (words.length === 2) {
+      const impl = implOf(path, reg);
+      if (impl === "ts" || impl !== implOf(words[0]!, reg)) table[path] = impl;
+    }
+  }
+  return table;
+}
+
+/** The `--output json` allow-list: a group maps to `true` (every sub) or to
+ *  the subs that qualify. */
+export function deriveJsonSurfaces(reg: Readonly<Record<string, Row>> = REGISTRY): Record<string, true | readonly string[]> {
+  const out: Record<string, true | string[]> = Object.fromEntries(ARGV_SHAPE_JSON.map((shape) => [shape, true as const]));
+  for (const [path, row] of Object.entries(reg)) {
+    if (row.json !== true) continue;
+    const words = path.split(" ");
+    if (words.length === 1) out[path] = true;
+    else if (words.length === 2) {
+      const cur = out[words[0]!];
+      if (cur !== true) out[words[0]!] = [...(cur ?? []), words[1]!];
+    }
+  }
+  return out;
+}

package/src/cli/router.ts

@@ -0,0 +1,31 @@
+/**
+ * router.ts — which implementation runs a command line.
+ *
+ * `TABLE` is derived from src/cli/registry.ts: a row for every group, the
+ * three argv shapes that are not verbs (empty argv, `-h`, `--help`), and a
+ * `"group sub"` row where a sub's implementation differs from its group's.
+ *
+ * A `ts` row runs in this process. A key is a group (`"completion"`)
+ * or a group and its first argument (`"completion bash"`); the longer key wins. An
+ * argv whose verb is not in the table is `unknown`: the router owns the
+ * "Unknown command" refusal (src/main.ts).
+ */
+
+import { locateVerb } from "./args";
+import { deriveTable, type Impl } from "./registry";
+
+export type { Impl };
+
+export const TABLE: Readonly<Record<string, Impl>> = deriveTable();
+
+export type Route = { kind: "ts"; verb: string } | { kind: "unknown"; verb: string };
+
+/** Resolve one command line. */
+export function route(argv: readonly string[], table: Readonly<Record<string, Impl>> = TABLE): Route {
+  const [verb = "", sub] = locateVerb(argv);
+  const long = sub !== undefined ? `${verb} ${sub}` : undefined;
+  const hit =
+    long !== undefined && Object.hasOwn(table, long) ? table[long] : Object.hasOwn(table, verb) ? table[verb] : undefined;
+  if (hit === "ts") return { kind: hit, verb };
+  return { kind: "unknown", verb };
+}