@sibylline-labs/eris 0.0.0-stage → 0.3.1

package/src/cli/commands/completion/bash.ts

@@ -0,0 +1,24 @@
+/**
+ * bash.ts — `eris completion bash`: the bash completion script on stdout.
+ */
+
+import type { CliContext } from "../../../main";
+import type { Session } from "../../compose";
+import { runShell } from "./shell";
+
+const USAGE = `Usage: eris completion bash
+
+Emit the bash completion script to stdout. Load it into the current shell
+or make it permanent:
+
+  source <(eris completion bash)                          # this shell only
+  echo 'source <(eris completion bash)' >> ~/.bashrc      # every shell
+
+The emitted script embeds a snapshot of the eris command tree, generated from
+the verb registry; sourcing via process substitution (as above) keeps it
+current automatically. See docs/COMPLETION.md.
+`;
+
+export function runBash(args: string[], ctx: CliContext & { session?: Session }): number {
+  return runShell("bash", USAGE, args, ctx);
+}

package/src/cli/commands/completion/domain.ts

@@ -0,0 +1,203 @@
+/**
+ * domain.ts — the completion domains a row's slots carry (`CompletionDomain`,
+ * src/cli/registry.ts): the function a domain names, and the check composition
+ * (src/cli/compose.ts) runs on a slot's words and on every helper text before
+ * the emitter (./emit.ts) writes them into the script.
+ *
+ * The script is sourced by every shell that loads eris completion (bash, and
+ * zsh through bashcompinit), and a helper sits between core's own definitions
+ * in it. Sourcing must define the helper's one function and run nothing, so the
+ * check must find where that function ends exactly as both shells do. It does
+ * not model shell quoting: it accepts a subset whose framing bash and zsh agree
+ * on and refuses everything else, naming the line:
+ *
+ *   - the text is exactly one definition, `__eris_dom_<name>() {`, whose body
+ *     closes at its final `}`, then a newline: nothing before it, nothing after;
+ *   - printable ASCII, tab and newline only; no comment, no backtick, no heredoc
+ *     or here-string, no `$'…'`, `$"…"` or `$[…]`, no function defined inside;
+ *   - a backslash only inside quotes, and only before a letter or digit;
+ *   - `${ }` holds a name and its operators only (no quote, nesting or `( )`);
+ *   - `{` and `}` as words only where both shells read them as a group's braces:
+ *     `{` in command position, `}` after `;` or a newline, closing one the scan
+ *     opened (zsh reads a lone `}` as a closing brace anywhere on a line);
+ *   - inside `$( )`, no `case` and no unbalanced parenthesis inside a quote,
+ *     which older bash can read as the substitution's end.
+ *
+ * A helper that is valid shell may still be refused; rewrite it into the
+ * subset. Pure and import-free, because composition runs on every command line.
+ */
+
+import type { CompletionDomain, SlotWord } from "../../registry";
+
+/** A literal slot word: the emitted script embeds it inside double quotes and a case label. */
+export const WORD = /^[A-Za-z0-9_][A-Za-z0-9_?-]*$/;
+
+const DOMAIN_NAME = /^@[a-z][a-z0-9_]*$/;
+const PREFIX = "__eris_dom_";
+/** The one header a helper starts with: `name() {`, then a blank or newline. */
+const HEADER = /^(__eris_dom_[A-Za-z0-9_]+)\(\)[ \t]*\{(?=[ \t\n])/;
+/** Anything but printable ASCII, tab and newline. */
+const OUTSIDE_ASCII = /[^\t\n\x20-\x7e]/;
+/** Characters that end a shell word. */
+const META = new Set([" ", "\t", "\n", ";", "&", "|", "(", ")", "<", ">"]);
+/** What `${` … `}` may hold: a name, `$name`, and the operators on it. */
+const PARAM_CHAR = /[A-Za-z0-9_:=+?#%/*@!.,~^\-[\] \t]/;
+/** What may follow `$` inside `${ }`: a name or a special parameter. */
+const PARAM_DOLLAR = /[A-Za-z0-9_@*#?!$-]/;
+
+/** The function the emitted slot calls for `domain`. */
+export function domainFunction(domain: string): string {
+  return `${PREFIX}${domain.slice(1)}`;
+}
+
+/** Every helper text a domain carries: its library, then its own function. */
+export function helperTexts(d: CompletionDomain): readonly string[] {
+  return [...(d.library ?? []), d.helper];
+}
+
+/** Why `word` cannot stand in a slot, else null. Its helper texts are `scanHelper`'s. */
+export function slotWordRefusal(word: SlotWord): string | null {
+  if (typeof word === "string") {
+    return word === "@file" || WORD.test(word) ? null : `'${word}' is not a completion word (letters, digits, '_', '?', '-'), '@file' or a domain`;
+  }
+  const d = word as Partial<CompletionDomain> | null;
+  if (typeof d !== "object" || d === null || typeof d.domain !== "string" || typeof d.helper !== "string") {
+    return `${JSON.stringify(word)} is neither a completion word nor a domain ({ domain, helper })`;
+  }
+  if (d.library !== undefined && (!Array.isArray(d.library) || !d.library.every((t) => typeof t === "string"))) {
+    return `domain '${d.domain}': library must be a list of helper texts`;
+  }
+  if (d.domain === "@file") return "'@file' is built in: write it as the word '@file'";
+  if (!DOMAIN_NAME.test(d.domain)) return `domain '${d.domain}' is not a domain name ('@', then lower-case letters, digits, '_')`;
+  return null;
+}
+
+/** The one function a helper text defines, or why it cannot be emitted. */
+export type HelperScan = { readonly ok: true; readonly function: string } | { readonly ok: false; readonly why: string };
+
+const lineAt = (text: string, at: number): number => text.slice(0, at).split("\n").length;
+
+/** Where the scan is: code (the body, or inside `$( )`), `${ }`, or a double or single quote. */
+type Frame =
+  | { kind: "code"; readonly sub: boolean; readonly start: number; braces: number; parens: number }
+  | { kind: "param" }
+  | { kind: "dq" | "sq"; readonly inSub: boolean; parens: number };
+
+class Refusal extends Error {}
+
+/** The body from just after its opening `{`: the index just past its closing `}`. Throws a Refusal. */
+function scanBody(text: string, start: number): number {
+  const stack: Frame[] = [{ kind: "code", sub: false, start, braces: 1, parens: 0 }];
+  const inSub = () => stack.some((f) => f.kind === "code" && f.sub);
+  const refuse = (j: number, why: string): never => {
+    throw new Refusal(`${why} (line ${lineAt(text, j)})`);
+  };
+  /** The last non-blank character before `j` in a code frame starting at `from`; "" at the frame's start. */
+  const prevWord = (j: number, from: number): string => {
+    let k = j - 1;
+    while (k >= from && (text[k] === " " || text[k] === "\t")) k--;
+    return k >= from ? text[k]! : "";
+  };
+  const backslash = (j: number) => {
+    if (!/[A-Za-z0-9]/.test(text[j + 1] ?? "")) refuse(j, "has a backslash before something other than a letter or digit");
+  };
+  for (let j = start; j < text.length; j++) {
+    const c = text[j]!;
+    const next = text[j + 1];
+    const top = stack[stack.length - 1]!;
+    if (c === "`") refuse(j, "uses a backtick: use $( ) instead");
+    if (top.kind === "sq") {
+      if (c === "'") {
+        if (top.parens !== 0) refuse(j, "has an unbalanced parenthesis in a quote inside $( )");
+        stack.pop();
+      } else if (c === "\\") backslash(j);
+      else if (top.inSub && (c === "(" || c === ")")) top.parens += c === "(" ? 1 : -1;
+      continue;
+    }
+    if (top.kind === "param") {
+      if (c === "}") stack.pop();
+      else if (c === "$" && PARAM_DOLLAR.test(next ?? "")) j++;
+      else if (!PARAM_CHAR.test(c)) refuse(j, "has a ${ } holding more than a name and its operators");
+      continue;
+    }
+    if (c === "$" && next === "$") {
+      j++;
+      continue;
+    }
+    if (c === "$" && (next === "'"|| next === '"' || next === "[")) refuse(j, `uses $${next}, which the shells read differently`);
+    if (c === "$" && next === "(") {
+      stack.push({ kind: "code", sub: true, start: j + 2, braces: 0, parens: 0 });
+      j++;
+      continue;
+    }
+    if (c === "$" && next === "{") {
+      stack.push({ kind: "param" });
+      j++;
+      continue;
+    }
+    if (top.kind === "dq") {
+      if (c === '"') {
+        if (top.parens !== 0) refuse(j, "has an unbalanced parenthesis in a quote inside $( )");
+        stack.pop();
+      } else if (c === "\\") backslash(j);
+      else if (top.inSub && (c === "(" || c === ")")) top.parens += c === "(" ? 1 : -1;
+      continue;
+    }
+    // Code: the body, or the inside of a `$( )`.
+    const code = top as Extract<Frame, { kind: "code" }>;
+    if (c === "\\") refuse(j, "has a backslash outside quotes");
+    if (c === "'" || c === '"') {
+      stack.push({ kind: c === "'" ? "sq" : "dq", inSub: inSub(), parens: 0 });
+      continue;
+    }
+    if (c === "#" && text[j - 1] !== "$") refuse(j, "has a comment or a bare '#': keep comments in the TypeScript beside it");
+    if (c === "<" && next === "<") refuse(j, "uses a heredoc or here-string");
+    const wordStart = j === code.start || META.has(text[j - 1]!);
+    const wordEnd = (k: number) => k >= text.length || META.has(text[k]!);
+    if (wordStart && /^function[ \t]/.test(text.slice(j, j + 9))) refuse(j, "defines a function inside a function");
+    if (wordStart && code.sub && /^case\b/.test(text.slice(j, j + 5))) refuse(j, "uses case inside $( )");
+    if (c === "(") {
+      if (/^\([ \t]*\)/.test(text.slice(j))) refuse(j, "defines a function inside a function");
+      code.parens++;
+    } else if (c === ")") {
+      if (code.parens > 0) code.parens--;
+      else if (code.sub) stack.pop();
+    } else if (c === "{" && wordStart && wordEnd(j + 1)) {
+      const before = prevWord(j, code.start);
+      const twoBefore = text.slice(0, j).trimEnd();
+      if (!/[ \t\n]/.test(next ?? "") || !["", "\n", ";", "&", "|", "("].includes(before) || twoBefore.endsWith(";;")) {
+        refuse(j, "has a '{' word outside command position");
+      }
+      code.braces++;
+    } else if (c === "}" && wordStart && wordEnd(j + 1)) {
+      const before = prevWord(j, code.start);
+      const twoBefore = text.slice(0, j).trimEnd();
+      if (!["\n", ";"].includes(before) || twoBefore.endsWith(";;") || !/[ \t\n;]/.test(next ?? "") || code.braces === 0) {
+        refuse(j, "has a '}' word that does not close a group after ';' or a newline");
+      }
+      code.braces--;
+      if (!code.sub && code.braces === 0) return j + 1;
+    }
+  }
+  return refuse(text.length - 1, stack.length > 1 ? "ends inside a quote, expansion or substitution" : "ends inside the function body");
+}
+
+/** The one function `text` defines, or why it cannot be emitted as a helper. */
+export function scanHelper(text: string): HelperScan {
+  const fail = (why: string): HelperScan => ({ ok: false, why });
+  if (!text.endsWith("\n")) return fail("does not end with a newline");
+  const odd = OUTSIDE_ASCII.exec(text);
+  if (odd !== null) return fail(`carries a character outside printable ASCII (line ${lineAt(text, odd.index)})`);
+  const head = HEADER.exec(text);
+  if (head === null) {
+    return fail(`must be exactly one definition, starting at its first character with '${PREFIX}<name>() {'`);
+  }
+  try {
+    const end = scanBody(text, head[0].length);
+    if (end !== text.length - 1) return fail(`puts text after the function's closing brace (line ${lineAt(text, end)}): one function per helper text`);
+  } catch (e) {
+    if (e instanceof Refusal) return fail(e.message);
+    throw e;
+  }
+  return { ok: true, function: head[1]! };
+}

package/src/cli/commands/completion/emit.ts

@@ -0,0 +1,246 @@
+/**
+ * emit.ts — the bash and zsh completion scripts.
+ *
+ * The command tree is generated from the registry it is handed: groups,
+ * subs, nested subs, each path's long flags, which flags take a value and
+ * which of those values are file names (`file` on the flag's row), and each
+ * row's positional slots (`complete`): literal words, file names, or a
+ * completion domain, whose helper text is emitted once and whose function the
+ * slot calls with the words typed in the earlier slots. A verb added to
+ * src/cli/registry.ts, or declared by a plugin, completes with no other edit.
+ * Composition has checked every slot word and helper (./domain.ts).
+ *
+ * The rest is the tab-press engine, which is shell by nature and is emitted
+ * as text. Its contract (docs/COMPLETION.md):
+ *   - a tab press never runs eris and never touches the network;
+ *   - bash-3.2-clean (macOS /bin/bash) and shared verbatim by the zsh route,
+ *     which loads it through bashcompinit.
+ *
+ * This runs on every shell start (`source <(eris completion bash)`): it
+ * imports the registry and nothing else, so no other verb's source, Bash or
+ * TS, is on its path.
+ */
+
+import { REGISTRY, type Row } from "../../registry";
+import { domainFunction, helperTexts, WORD } from "./domain";
+
+export type Shell = "bash" | "zsh";
+type Registry = Readonly<Record<string, Row>>;
+
+const FLAG = /^--[a-z][a-z0-9-]*$/;
+
+function safe(word: string, re: RegExp, what: string): string {
+  if (!re.test(word)) throw new Error(`completion: ${what} '${word}' is not shell-safe`);
+  return word;
+}
+
+const byCodePoint = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+const uniqSorted = (xs: Iterable<string>): string[] => [...new Set(xs)].sort(byCodePoint);
+
+/** The lookup key the engine builds for a command path: words joined by `__`. */
+const keyOf = (path: string): string => path.split(" ").join("__");
+
+function subsIn(reg: Registry, path: string): string[] {
+  const depth = path.split(" ").length + 1;
+  return Object.keys(reg)
+    .filter((k) => k.startsWith(`${path} `) && k.split(" ").length === depth)
+    .map((k) => safe(k.split(" ")[depth - 1]!, WORD, "verb"));
+}
+
+function flagNames(row: Row | undefined): string[] {
+  return (row?.flags ?? []).map((f) => safe(f.name, FLAG, "flag"));
+}
+
+function caseFn(name: string, arms: readonly [string, string][], fallback: string): string {
+  const body = arms.map(([label, action]) => `    ${label}) ${action} ;;\n`).join("");
+  return `${name}() {\n  case "$1" in\n${body}    *) ${fallback} ;;\n  esac\n}\n`;
+}
+
+function predicateFn(name: string, subject: string, labels: readonly string[]): string {
+  const arm = labels.length > 0 ? `    ${labels.join("|")}) return 0 ;;\n` : "";
+  return `${name}() {\n  case ${subject} in\n${arm}  esac\n  return 1\n}\n`;
+}
+
+/** The generated half: the tree, the domain helpers, the flags and the positional slots. */
+function generated(reg: Registry): { tree: string; helpers: string; argv: string } {
+  const paths = Object.keys(reg);
+  const groups = uniqSorted(paths.filter((p) => !p.includes(" ")).map((g) => safe(g, WORD, "group")));
+
+  const verbArms: [string, string][] = [];
+  for (const path of [...paths].sort(byCodePoint)) {
+    const subs = subsIn(reg, path);
+    if (subs.length > 0) verbArms.push([keyOf(path), `echo "${uniqSorted(subs).join(" ")}"`]);
+  }
+
+  // A path offers its own flags; a group's own key, used before a verb is
+  // typed (and for a verb the registry does not know), offers the union of
+  // every row under it.
+  const flagArms: [string, string][] = [];
+  for (const path of [...paths].sort(byCodePoint)) {
+    const own = path.includes(" ") ? flagNames(reg[path]) : paths.filter((p) => p === path || p.startsWith(`${path} `)).flatMap((p) => flagNames(reg[p]));
+    flagArms.push([keyOf(path), `echo "${uniqSorted([...own, "--help"]).join(" ")}"`]);
+  }
+
+  const valueFlags = uniqSorted(paths.flatMap((p) => (reg[p]!.flags ?? []).filter((f) => f.takesValue).map((f) => safe(f.name, FLAG, "flag"))));
+  // Registry order, first seen: core's rows precede a plugin's, and the emitted
+  // case arm lists them in that order.
+  const fileFlags = [...new Set(paths.flatMap((p) => (reg[p]!.flags ?? []).filter((f) => f.takesValue && f.file === true).map((f) => safe(f.name, FLAG, "flag"))))];
+
+  const slotArms: [string, string][] = [];
+  const fileSlots: string[] = [];
+  // Each distinct helper and library text once, in the order its first slot is emitted.
+  const texts = new Set<string>();
+  for (const path of [...paths].sort(byCodePoint)) {
+    reg[path]!.complete?.forEach((slot, n) => {
+      const label = `"${keyOf(path)} ${n}"`;
+      if (slot.includes("@file")) {
+        fileSlots.push(label);
+        return;
+      }
+      const words = slot.map((t) => {
+        if (typeof t === "string") return safe(t, WORD, "slot word");
+        for (const text of helperTexts(t)) texts.add(text);
+        return `$(${domainFunction(t.domain)} "$@")`;
+      });
+      slotArms.push([label, `echo "${words.join(" ")}"`]);
+    });
+  }
+  const helpers = texts.size === 0 ? "" : `# Completion domains: the helpers the rows carry.\n${[...texts].join("\n")}\n`;
+
+  const tree =
+    `__eris_comp_groups() {\n  echo "${groups.join(" ")}"\n}\n\n` +
+    `${caseFn("__eris_comp_verbs", verbArms, 'echo ""')}\n` +
+    `${caseFn("__eris_comp_flags", flagArms, 'echo ""')}\n`;
+  const argv =
+    "# Flags whose next word is a user-supplied value (never completed as a\n# positional), and the ones whose value is a file name.\n" +
+    `${predicateFn("__eris_comp_valflag", '"$1"', valueFlags)}\n` +
+    `${predicateFn("__eris_comp_fileflag", '"$1"', fileFlags)}\n` +
+    '# The positional slots: __eris_comp_slot <key> <n> [<word>...] prints the\n# words for slot n of the command <key>, given the words typed in the earlier\n# slots; __eris_comp_fileslot says it is a file.\n' +
+    `__eris_comp_slot() {\n  local slot="$1 $2"\n  shift 2\n  case "$slot" in\n${slotArms.map(([l, a]) => `    ${l}) ${a} ;;\n`).join("")}  esac\n  return 0\n}\n\n` +
+    `${predicateFn("__eris_comp_fileslot", '"$1 $2"', fileSlots)}\n`;
+  return { tree, helpers, argv };
+}
+
+const BASH_HEADER = `# eris bash completion — generated by 'eris completion bash'.
+# The command tree below is a snapshot of the eris verb registry
+# (src/cli/registry.ts) at emission time; re-emit after upgrading eris, or
+# source via process substitution so it regenerates at shell startup. Works on
+# bash 3.2+ (macOS /bin/bash). See docs/COMPLETION.md.
+`;
+
+const ZSH_HEADER = `# eris zsh completion — generated by 'eris completion zsh'.
+# Route: bashcompinit wrapping the shared bash completion body (the engine
+# sets the ksharrays localoption so COMP_WORDS indexing matches bash). The
+# command tree below is a snapshot of the eris verb registry at emission
+# time; source via process substitution so it regenerates at shell startup.
+# See docs/COMPLETION.md.
+if [ -z "\${ZSH_VERSION:-}" ]; then
+  echo "eris: this completion script is for zsh — use 'eris completion bash' for bash" >&2
+  return 1 2>/dev/null || exit 1
+fi
+if ! command -v compdef >/dev/null 2>&1; then
+  autoload -U +X compinit && compinit
+fi
+autoload -U +X bashcompinit && bashcompinit
+`;
+
+/** The tab-press entry point. */
+const ENGINE = `_eris_completions() {
+  # Under zsh/bashcompinit, give this function bash's 0-based array
+  # indexing; under bash the command doesn't exist and is silenced.
+  setopt localoptions ksharrays 2>/dev/null || :
+
+  local cur prev group verb sub key words
+  local i w p np pw
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev=""
+  [ "$COMP_CWORD" -ge 1 ] && prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+  # A value-taking flag right before the cursor: complete files for the
+  # file-valued ones, otherwise stay silent while the user types the value.
+  if __eris_comp_valflag "$prev"; then
+    __eris_comp_fileflag "$prev" && COMPREPLY=( $(compgen -f -- "$cur") )
+    return 0
+  fi
+
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "$(__eris_comp_groups) --help --version" -- "$cur") )
+    return 0
+  fi
+
+  group="\${COMP_WORDS[1]}"
+
+  # Walk the words after the group (before the cursor): the first positional
+  # is the verb (verb-ful groups only), the next is the nested sub when the
+  # verb is itself a group, the rest are counted as arguments. Flags and the
+  # values of value-taking flags are skipped.
+  verb=""; sub=""; np=0; pw=()
+  i=2
+  while [ "$i" -lt "$COMP_CWORD" ]; do
+    w="\${COMP_WORDS[i]}"
+    p="\${COMP_WORDS[i-1]}"
+    if __eris_comp_valflag "$p"; then i=$((i + 1)); continue; fi
+    case "$w" in
+      -*) i=$((i + 1)); continue ;;
+    esac
+    if [ -z "$verb" ] && [ -n "$(__eris_comp_verbs "$group")" ]; then
+      verb="$w"
+    elif [ -n "$verb" ] && [ -z "$sub" ] && [ "$np" -eq 0 ] && [ -n "$(__eris_comp_verbs "\${group}__\${verb}")" ]; then
+      sub="$w"
+    else
+      pw[np]="$w"
+      np=$((np + 1))
+    fi
+    i=$((i + 1))
+  done
+  key="$group"
+  [ -n "$verb" ] && key="\${key}__\${verb}"
+  [ -n "$sub" ] && key="\${key}__\${sub}"
+
+  # Flags of the deepest known path; else the group's whole set.
+  case "$cur" in
+    -*)
+      words=$(__eris_comp_flags "$key")
+      [ -n "$words" ] || words=$(__eris_comp_flags "$group")
+      [ -n "$words" ] || words="--help"
+      COMPREPLY=( $(compgen -W "$words" -- "$cur") )
+      return 0
+      ;;
+  esac
+
+  # Verb position of a verb-ful group.
+  if [ -z "$verb" ] && [ -n "$(__eris_comp_verbs "$group")" ]; then
+    COMPREPLY=( $(compgen -W "$(__eris_comp_verbs "$group")" -- "$cur") )
+    return 0
+  fi
+
+  # Nested sub position (\`eris <group> <verb> <TAB>\`).
+  if [ -n "$verb" ] && [ -z "$sub" ]; then
+    words=$(__eris_comp_verbs "\${group}__\${verb}")
+    if [ -n "$words" ]; then
+      COMPREPLY=( $(compgen -W "$words" -- "$cur") )
+      return 0
+    fi
+  fi
+
+  # Positional slots with a known domain, handed the earlier slots' words.
+  # Everything else intentionally offers nothing (silent degradation).
+  if __eris_comp_fileslot "$key" "$np"; then
+    COMPREPLY=( $(compgen -f -- "$cur") )
+    return 0
+  fi
+  words=$(__eris_comp_slot "$key" "$np" \${pw[@]+"\${pw[@]}"})
+  [ -n "$words" ] && COMPREPLY=( $(compgen -W "$words" -- "$cur") )
+  return 0
+}
+
+complete -F _eris_completions eris
+`;
+
+/** The full script for `shell`, generated from `reg`. Deterministic: the
+ *  same registry emits the same bytes. */
+export function emitScript(shell: Shell, reg: Registry = REGISTRY): string {
+  const { tree, helpers, argv } = generated(reg);
+  return `${shell === "zsh" ? ZSH_HEADER : BASH_HEADER}${tree}${helpers}${argv}${ENGINE}`;
+}

package/src/cli/commands/completion/shell.ts

@@ -0,0 +1,24 @@
+/**
+ * shell.ts — the one body behind `eris completion bash` and `eris completion
+ * zsh`: `--help` prints the verb's usage, no argument prints the script, and
+ * anything else is refused with nothing on stdout (a shell rc sources stdout).
+ *
+ * The tree is the session's composed registry (src/cli/compose.ts): core rows
+ * plus plugin rows. Rows are data, so no plugin handler loads here.
+ */
+
+import { CliExit, readVerbArgs } from "../../args";
+import type { CliContext } from "../../../main";
+import type { Session } from "../../compose";
+import { emitScript, type Shell } from "./emit";
+
+export function runShell(shell: Shell, usage: string, args: string[], ctx: CliContext & { session?: Session }): number {
+  try {
+    if (readVerbArgs(`completion ${shell}`, args, ctx, { help: usage }) === null) return 0;
+  } catch (e) {
+    if (e instanceof CliExit) return e.code;
+    throw e;
+  }
+  ctx.stdout.write(emitScript(shell, ctx.session?.cli.registry));
+  return 0;
+}

package/src/cli/commands/completion/zsh.ts

@@ -0,0 +1,24 @@
+/**
+ * zsh.ts — `eris completion zsh`: the zsh completion script on stdout.
+ */
+
+import type { CliContext } from "../../../main";
+import type { Session } from "../../compose";
+import { runShell } from "./shell";
+
+const USAGE = `Usage: eris completion zsh
+
+Emit the zsh completion script to stdout. Load it into the current shell
+or make it permanent:
+
+  source <(eris completion zsh)                           # this shell only
+  echo 'source <(eris completion zsh)' >> ~/.zshrc        # every shell
+
+Implementation: zsh loads the same completion body as bash through
+bashcompinit (one body, two thin wrappers — the lower-maintenance route).
+See docs/COMPLETION.md.
+`;
+
+export function runZsh(args: string[], ctx: CliContext & { session?: Session }): number {
+  return runShell("zsh", USAGE, args, ctx);
+}

package/src/cli/commands/completion.ts

@@ -0,0 +1,48 @@
+/**
+ * completion.ts — `eris completion <shell>`: emit a shell tab-completion
+ * script. The script is generated from the verb registry
+ * (./completion/emit.ts); `bash` is ./completion/bash.ts, `zsh`
+ * ./completion/zsh.ts.
+ *
+ * It runs on every shell start (`source <(eris completion bash)`), so its
+ * import graph is the registry and nothing else: no other verb, and no Bash.
+ */
+
+import { groupArgs } from "../args";
+import type { CliContext } from "../../main";
+import type { Session } from "../compose";
+import { runBash } from "./completion/bash";
+import { runZsh } from "./completion/zsh";
+
+const USAGE_HEAD = `Usage: eris completion <shell>
+
+Shells:
+  bash    Emit the bash completion script (bash 3.2+ clean)
+  zsh     Emit the zsh completion script (bashcompinit route)
+
+Load into the current shell:  source <(eris completion bash)
+Make permanent:               echo 'source <(eris completion bash)' >> ~/.bashrc
+                              echo 'source <(eris completion zsh)'  >> ~/.zshrc
+
+Completes command groups, verbs, flags and file-valued flags. A tab press
+never runs eris and never touches the network.
+`;
+
+const USAGE_TAIL = `See docs/COMPLETION.md.
+`;
+
+/** Core's text, with a distribution's paragraph (`composeCli`'s `completionNote`) between the two halves. */
+function usageText(note: string | null): string {
+  return `${USAGE_HEAD}${note === null ? "" : `${note}\n`}${USAGE_TAIL}`;
+}
+
+export async function runCompletion(args: string[], ctx: CliContext & { session?: Session }): Promise<number> {
+  const g = groupArgs("completion", args);
+  if (g.kind === "sub") return (g.sub === "bash" ? runBash : runZsh)(g.rest, ctx);
+  if (g.kind === "bare" || g.kind === "help") {
+    ctx.stdout.write(usageText(ctx.session?.cli.completionNote ?? null));
+    return 0;
+  }
+  ctx.stderr.write(`ERROR Unknown completion shell: ${g.sub} (supported: bash, zsh)\n`);
+  return 1;
+}