argsbarg 1.4.3 → 2.0.0

package/docs/mcp.md

@@ -9,12 +9,12 @@ MCP is **opt-in**. Apps that do not set `mcpServer` on the program root behave e
 1. Add `mcpServer` to your program root:
 
 ```typescript
-const cli: CliCommand = {
+const cli = {
   key: "myapp",
   description: "My app.",
   mcpServer: { name: "myapp", version: "1.0.0" },
   commands: [/* ... */],
-};
+} satisfies CliProgram;
 ```
 
 `mcpServer: {}` is enough to enable the server. Optional fields override defaults (see [Configuration](#configuration)).
@@ -22,7 +22,7 @@ const cli: CliCommand = {
 2. Run the MCP server:
 
 ```bash
-myapp ai mcp
+myapp mcp
 ```
 
 The process reads NDJSON requests from stdin and writes NDJSON responses to stdout. It stays alive until stdin closes.
@@ -34,7 +34,7 @@ Optionally install an agent skill for discovery without MCP: see [docs/ai-skills
 The `examples/nested.ts` demo enables MCP — try:
 
 ```bash
-bun run examples/nested.ts ai mcp
+bun run examples/nested.ts mcp
 ```
 
 ## Client setup
@@ -58,11 +58,11 @@ Use your real binary or script path. For a compiled CLI, `command` can be the in
 
 ### Other MCP hosts
 
-Any host that spawns a subprocess and wires stdin/stdout works the same way: the **command** is your app, and **`ai mcp`** starts the server.
+Any host that spawns a subprocess and wires stdin/stdout works the same way: the **command** is your app, and **`mcp`** starts the server.
 
 ## Configuration
 
-Set `mcpServer` on the **program root only** (the `CliCommand` passed to `cliRun`). Validation rejects `mcpServer` on nested nodes.
+Set `mcpServer` on the **program root only** (the `CliProgram` passed to `cliRun`). Validation rejects `mcpServer` on nested nodes.
 
 | Field | Default | Purpose |
 | --- | --- | --- |
@@ -277,7 +277,7 @@ Requests without an `id` are treated as notifications and do not receive a respo
 ### Manual smoke test
 
 ```bash
-printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | bun run examples/nested.ts ai mcp
+printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | bun run examples/nested.ts mcp
 ```
 
 You should get one JSON line on stdout with `result.capabilities` and `result.serverInfo`.
@@ -290,7 +290,7 @@ When MCP is enabled:
 - Do not declare a top-level command named **`completion`** — reserved for shell completions.
 - Do not declare an option named **`schema`** — reserved for `--schema`.
 
-Running `myapp ai mcp` without `mcpServer` on the root fails with an error (exit 1).
+Running `myapp mcp` without `mcpServer` on the root fails with an error (exit 1).
 
 ## Design notes
 

package/examples/mcp-test.ts

@@ -3,11 +3,11 @@
 MCP test fixture for subprocess integration tests only.
 */
 
-import { cliRun, CliCommand, CliOptionKind } from "../src/index.ts";
+import { cliRun, CliProgram, CliOptionKind } from "../src/index.ts";
 
 const envFilePath = process.env.ARGS_TEST_ENV_FILE;
 
-const cli: CliCommand = {
+const cli = {
   key: "mcp-test",
   description: "MCP integration test fixture.",
   mcpServer: {
@@ -61,6 +61,6 @@ const cli: CliCommand = {
       },
     },
   ],
-};
+} satisfies CliProgram;
 
 await cliRun(cli);

package/examples/minimal.ts

@@ -7,9 +7,9 @@ readers can copy the pattern into their own scripts quickly.
 It demonstrates the minimal Bun integration path.
 */
 
-import { cliRun, CliCommand, CliOptionKind } from "../src/index.ts";
+import { cliRun, CliProgram, CliOptionKind } from "../src/index.ts";
 
-const cli: CliCommand = {
+const cli = {
   key: "minimal.ts",
   description: "Tiny demo.",
   positionals: [
@@ -36,6 +36,6 @@ const cli: CliCommand = {
     }
     console.log(`hello ${name}`);
   },
-};
+} satisfies CliProgram;
 
 await cliRun(cli);

package/examples/nested.ts

@@ -7,9 +7,9 @@ and fallback commands fit together in one schema.
 It demonstrates how the schema scales beyond one command.
 */
 
-import { cliRun, CliCommand, CliOptionKind, CliFallbackMode } from "../src/index.ts";
+import { cliRun, CliProgram, CliOptionKind, CliFallbackMode } from "../src/index.ts";
 
-const cli: CliCommand = {
+const cli = {
   key: "nested.ts",
   description: "Nested groups demo.",
   mcpServer: { name: "nested-demo", version: "1.0.0" },
@@ -97,6 +97,6 @@ const cli: CliCommand = {
   ],
   fallbackCommand: "read",
   fallbackMode: CliFallbackMode.MissingOrUnknown,
-};
+} satisfies CliProgram;
 
 await cliRun(cli);

package/examples/option-required.ts

@@ -7,9 +7,9 @@ readers can copy the pattern into their own scripts quickly.
 It demonstrates the minimal Bun integration path.
 */
 
-import { cliRun, CliCommand, CliOptionKind, CliFallbackMode, isInteractiveTty } from "../src/index.ts";
+import { cliRun, CliProgram, CliOptionKind, CliFallbackMode, isInteractiveTty } from "../src/index.ts";
 
-const cli: CliCommand = {
+const cli = {
   key: "option-required.ts",
   description: "Demo of a required option.",
   options: [
@@ -42,6 +42,6 @@ const cli: CliCommand = {
     console.log(`requiredNonTty: ${requiredNonTty}`);
     console.log(`optional: ${optional}`);
   },
-};
+} satisfies CliProgram;
 
 await cliRun(cli);

package/index.d.ts

@@ -7,11 +7,13 @@ export declare class CliContext {
 	readonly appName: string;
 	readonly commandPath: string[];
 	readonly args: string[];
-	readonly schema: CliCommand;
+	readonly schema: CliProgram;
 	readonly opts: Record<string, string>;
 	readonly invocation: CliInvocation;
-	/** Captures the merged program root, routed path, positional words, and option map for a leaf handler. */
-	constructor(appName: string, commandPath: string[], args: string[], opts: Record<string, string>, schema: CliCommand, invocation?: CliInvocation);
+	/** Program root schema (same as {@link schema}). */
+	get program(): CliProgram;
+	/** Captures the program root, routed path, positional words, and option map for a leaf handler. */
+	constructor(appName: string, commandPath: string[], args: string[], opts: Record<string, string>, schema: CliProgram, invocation?: CliInvocation);
 	/** Returns whether a presence flag was set (including implicit "1" for boolean options). */
 	hasFlag(name: string): boolean;
 	/** Returns the string value for a string-valued option, if present. */
@@ -64,7 +66,7 @@ export declare enum CliFallbackMode {
 	UnknownOnly = "unknownOnly"
 }
 /**
- * A named flag or value option (`--long`, `-short`), listed on `CliCommand.options`.
+ * A named flag or value option (`--long`, `-short`), listed on command `options`.
  */
 export interface CliOption {
 	/** Option name (e.g., "name", "verbose"). */
@@ -84,7 +86,7 @@ export interface CliOption {
 	choices?: string[];
 }
 /**
- * An ordered positional argument slot, listed on `CliCommand.positionals`.
+ * An ordered positional argument slot, listed on leaf `positionals`.
  */
 export interface CliPositional {
 	/** Positional name (used in help and error messages). */
@@ -105,7 +107,7 @@ export interface CliPositional {
 	argMax?: number;
 }
 /**
- * Root-only. Enables `myapp ai mcp` and MCP stdio server metadata.
+ * Enables `myapp mcp` and MCP stdio server metadata (program root only).
  */
 export interface CliMcpServerConfig {
 	/** `initialize` serverInfo.name (default: root `key`). */
@@ -166,18 +168,18 @@ export interface CliMcpToolConfig {
 	requiresEnv?: string[];
 }
 /**
- * Root-only. Opt out of `ai skill` install commands with `{ enabled: false }`.
+ * Opt-out and defaults for the `install` built-in (compiled binaries only; program root only).
  */
-export interface CliAiSkillConfig {
-	/** When `false`, disable `ai skill *` install commands (default: enabled). */
+export interface CliInstallConfig {
+	/** When `false`, hide/disable `install` (default: enabled). */
 	enabled?: boolean;
-	/** Skill directory name (default: sanitized root `key`). */
-	name?: string;
+	/** Default bin directory (default: `~/.local/bin`). Overridden by `INSTALL_PREFIX` env and `--prefix`. */
+	prefix?: string;
 }
 /**
- * Base properties shared by all command nodes.
+ * Base properties shared by all nodes in the user command tree.
  */
-export interface CliCommandBase {
+export interface CliNodeBase {
 	/** Program or command key (e.g., "myapp", "stat", "owner"). */
 	key: string;
 	/** Short description shown in help. */
@@ -186,49 +188,50 @@ export interface CliCommandBase {
 	notes?: string;
 	/** Global or command-level flags/options. */
 	options?: CliOption[];
-	/** Root-only. When set, enables the `ai mcp` built-in subcommand. */
-	mcpServer?: CliMcpServerConfig;
-	/** Root-only. Opt out of `ai skill` install with `{ enabled: false }`. */
-	aiSkill?: CliAiSkillConfig;
-	/** Leaf-only. Per-tool MCP exposure and metadata. */
-	mcpTool?: CliMcpToolConfig;
 }
 /**
- * A command node: either a routing group (has commands) or a leaf (has handler).
- *
- * The value passed to cliRun is the program root: name is the app/binary name.
- * The root may be a routing group or a leaf command.
+ * A leaf command node with a handler and optional positionals.
  */
-export type CliCommand = (CliCommandBase & {
+export type CliLeaf = CliNodeBase & {
 	/** Handler function for leaf commands. */
 	handler: CliHandler;
 	/** Positional argument definitions. */
 	positionals?: CliPositional[];
-	/** Nested subcommands (empty for leaf commands). */
-	commands?: never;
-	/** Default subcommand (routing commands only). */
-	fallbackCommand?: never;
-	/** How fallbackCommand is applied at this routing node (routing commands only). */
-	fallbackMode?: never;
-}) | (CliCommandBase & {
+	/** Per-tool MCP exposure and metadata. */
+	mcpTool?: CliMcpToolConfig;
+};
+/**
+ * A routing command node with nested subcommands.
+ */
+export type CliRouter = CliNodeBase & {
 	/** Nested subcommands. */
-	commands: CliCommand[];
+	commands: CliNode[];
 	/** Default subcommand when argv omits a command or uses an unknown token at this routing node. */
 	fallbackCommand?: string;
-	/** How fallbackCommand is applied at this routing node (not root-only). */
+	/** How fallbackCommand is applied at this routing node. */
 	fallbackMode?: CliFallbackMode;
-	/** Handler function (leaf commands only). */
-	handler?: never;
-	/** Positional argument definitions (leaf commands only). */
-	positionals?: never;
-});
+};
+/**
+ * A node in the user-defined command tree (router or leaf).
+ */
+export type CliNode = CliLeaf | CliRouter;
+/**
+ * Program root passed to `cliRun` / `cliInvoke`.
+ * May be a leaf or router, plus optional program-level MCP and install config.
+ */
+export type CliProgram = CliNode & {
+	/** When set, enables the `mcp` built-in subcommand. */
+	mcpServer?: CliMcpServerConfig;
+	/** Opt-out and defaults for `install` (compiled binaries only). */
+	install?: CliInstallConfig;
+};
 /**
  * Handler closure type for leaf commands.
  * Supports both sync and async handlers.
  */
 export type CliHandler = (ctx: CliContext) => void | Promise<void>;
 /**
- * Error thrown when the static CliCommand tree violates ArgsBarg rules.
+ * Error thrown when the static CLI tree violates ArgsBarg rules.
  */
 export declare class CliSchemaValidationError extends Error {
 	/** Creates a schema validation error with a human-readable rule violation. */
@@ -253,17 +256,8 @@ export interface CliInvokeResult {
  * Parses argv against the user root, runs the leaf handler, and returns captured output.
  * Never calls process.exit.
  */
-export declare function cliInvoke(root: CliCommand, argv: string[]): Promise<CliInvokeResult>;
-/**
- * Validates the schema, parses argv, prints help or errors, runs completion or the leaf handler, then exits.
- *
- * @param root The root CliCommand.
- * @param argv Override the default argv (process.argv.slice(2)).
- */
-export declare function cliRun(root: CliCommand, argv?: string[]): Promise<never>;
-/**
- * Prints a red error line and contextual help on stderr, then exits with status 1.
- */
+export declare function cliInvoke(root: CliProgram, argv: string[]): Promise<CliInvokeResult>;
+export declare function cliRun(program: CliProgram, argv?: string[]): Promise<never>;
 export declare function cliErrWithHelp(ctx: CliContext, msg: string): never;
 /** True when stdin is a TTY. */
 export declare const isInteractiveTty: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "1.4.3",
+  "version": "2.0.0",
   "type": "module",
   "scripts": {
     "//just": "echo this app uses justfile for development tasks"

package/src/builtins/builtins.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, test, afterEach } from "bun:test";
+import { cliBuiltinInstallCommand, installBuiltinOptions } from "./install.ts";
+import { cliBuiltinMcpCommand } from "./mcp.ts";
+import { cliPresentationRoot } from "./presentation.ts";
+import { completionBashScript, completionFishScript, completionZshScript } from "./index.ts";
+import { exportPresentationBuiltins } from "./export.ts";
+import { CliProgram } from "../types.ts";
+import { setCompiledExecutableOverride } from "../install/compiled.ts";
+
+const fixture: CliProgram = {
+  key: "myapp",
+  description: "Demo app.",
+  mcpServer: { name: "myapp" },
+  commands: [
+    {
+      key: "hello",
+      description: "Say hello.",
+      handler: () => {},
+    },
+  ],
+};
+
+afterEach(() => {
+  setCompiledExecutableOverride(null);
+});
+
+describe("builtins help copy", () => {
+  test("install command includes description and option text when compiled", () => {
+    setCompiledExecutableOverride(true);
+    const install = cliBuiltinInstallCommand(fixture);
+    expect(install.description).toContain("Install the binary");
+    expect(install.notes).toContain("bun build --compile");
+    const names = installBuiltinOptions(fixture).map((o) => o.name);
+    expect(names).toContain("all");
+    expect(names).toContain("mcp");
+    expect(names).toContain("prefix");
+  });
+
+  test("install omits --mcp option when mcpServer unset", () => {
+    setCompiledExecutableOverride(true);
+    const noMcp: CliProgram = { key: "x", description: "x", handler: () => {} };
+    const names = installBuiltinOptions(noMcp).map((o) => o.name);
+    expect(names).not.toContain("mcp");
+  });
+
+  test("mcp builtin description is user-facing", () => {
+    const mcp = cliBuiltinMcpCommand();
+    expect(mcp.description).toContain("MCP server");
+    expect(mcp.notes).toContain('["mcp"]');
+  });
+});
+
+describe("presentation root", () => {
+  test("includes mcp when mcpServer set", () => {
+    setCompiledExecutableOverride(false);
+    const root = cliPresentationRoot(fixture);
+    expect(root.commands?.map((c) => c.key)).toContain("mcp");
+    expect(root.commands?.map((c) => c.key)).not.toContain("install");
+  });
+
+  test("includes install when compiled", () => {
+    setCompiledExecutableOverride(true);
+    const root = cliPresentationRoot(fixture);
+    expect(root.commands?.map((c) => c.key)).toContain("install");
+  });
+});
+
+describe("completion emitters", () => {
+  test("fish script references app key and subcommands", () => {
+    setCompiledExecutableOverride(true);
+    const schema = cliPresentationRoot(fixture);
+    const fish = completionFishScript(schema);
+    expect(fish).toContain("complete -c myapp");
+    expect(fish).toContain("hello");
+    expect(fish).toContain("install");
+  });
+
+  test("bash script includes install flags when compiled", () => {
+    setCompiledExecutableOverride(true);
+    const schema = cliPresentationRoot(fixture);
+    const bash = completionBashScript(schema);
+    expect(bash).toContain("--all");
+    expect(bash).toContain("install");
+  });
+
+  test("zsh script registers compdef", () => {
+    const schema = cliPresentationRoot({ key: "zapp", description: "z", handler: () => {} });
+    const zsh = completionZshScript(schema);
+    expect(zsh).toContain("#compdef zapp");
+    expect(zsh).toContain("compdef _zapp zapp");
+  });
+});
+
+describe("schema export builtins", () => {
+  test("exportPresentationBuiltins includes install options when compiled", () => {
+    setCompiledExecutableOverride(true);
+    const builtins = exportPresentationBuiltins(fixture);
+    const install = builtins.find((b) => b.key === "install");
+    expect(install?.options?.find((o) => o.name === "all")?.description).toContain("binary");
+  });
+});

package/src/builtins/completion-bash.ts

@@ -0,0 +1,240 @@
+import { CliNode, CliRouter, CliOptionKind } from "../types.ts";
+import { collectScopes, type ScopeRec } from "./scopes.ts";
+import {
+  escShellSingleQuoted,
+  identToken,
+  kHelpLong,
+  kHelpShort,
+  kSchemaLong,
+  mainName,
+} from "./shell-helpers.ts";
+
+function emitConsumeLong(ident: string, scopes: ScopeRec[]): string {
+  let o = "_${ident}_nac_consume_long() {\n".replace("${ident}", ident);
+  o += "  local sid=\"$1\" w=\"$2\" nw=\"$3\"\n";
+  o += "  case $sid in\n";
+  for (const [i, sc] of scopes.entries()) {
+    o += "    " + i + ")\n";
+    o += "      case $w in\n";
+    o += "        " + kHelpLong + "|${kHelpLong}=*|${kHelpShort}) echo 1 ;;\n".replace(/\$\{kHelpLong\}/g, kHelpLong).replace(/\$\{kHelpShort\}/g, kHelpShort);
+    if (sc.path === "") {
+      o += "        " + kSchemaLong + ") echo 1 ;;\n";
+    }
+    for (const op of sc.opts) {
+      const base = "--" + op.name;
+      if (op.kind === "presence") {
+        o += "        " + base + "|${base}=*) echo 1 ;;\n".replace(/\$\{base\}/g, base);
+      } else {
+        o += "        " + base + "=*) echo 1 ;;\n";
+        o += "        " + base + ") echo 2 ;;\n";
+      }
+    }
+    o += "        *) echo 0 ;;\n";
+    o += "      esac\n";
+    o += "      ;;\n";
+  }
+  o += "    *) echo 0 ;;\n";
+  o += "  esac\n";
+  o += "}\n";
+  return o;
+}
+
+function emitConsumeShort(ident: string, scopes: ScopeRec[]): string {
+  let o = "_${ident}_nac_consume_short() {\n".replace("${ident}", ident);
+  o += "  local sid=\"$1\" w=\"$2\"\n";
+  o += "  case $sid in\n";
+  for (const [i, sc] of scopes.entries()) {
+    o += "    " + i + ")\n";
+    o += "      local rest=${w#-}\n";
+    o += "      local ch\n";
+    o += "      local saw=0\n";
+    o += "      while [[ -n $rest ]]; do\n";
+    o += "        ch=${rest:0:1}\n";
+    o += "        rest=${rest:1}\n";
+    o += "        case $ch in\n";
+    let boolChars = "";
+    for (const op of sc.opts) {
+      if (!op.shortName) continue;
+      if (op.kind === "presence") {
+        boolChars += op.shortName + "|";
+      } else {
+        o += "          " + op.shortName + ")\n";
+        o += "            if [[ $saw -ne 0 || -n $rest ]]; then echo 0; return; fi\n";
+        o += "            echo 2; return ;;\n";
+      }
+    }
+    if (boolChars.length > 0) {
+      boolChars = boolChars.slice(0, -1);
+      o += "          " + boolChars + ") ;;\n";
+    }
+    o += "          *) echo 0; return ;;\n";
+    o += "        esac\n";
+    o += "        saw=1\n";
+    o += "      done\n";
+    o += "      echo 1\n";
+    o += "      ;;\n";
+  }
+  o += "    *) echo 0 ;;\n";
+  o += "  esac\n";
+  o += "}\n";
+  return o;
+}
+
+function emitMatchChild(ident: string, scopes: ScopeRec[], pathIndex: Record<string, number>): string {
+  let o = "_${ident}_nac_match_child() {\n".replace("${ident}", ident);
+  o += "  local sid=\"$1\" w=\"$2\"\n";
+  o += "  case $sid in\n";
+  for (const [sid, sc] of scopes.entries()) {
+    if (sc.kids.length === 0) continue;
+    o += "    " + sid + ")\n";
+    o += "      case $w in\n";
+    for (const ch of sc.kids) {
+      const childPath = sc.path === "" ? ch.key : sc.path + "/" + ch.key;
+      const cid = pathIndex[childPath] ?? 0;
+      o += "        " + ch.key + ") echo " + cid + "; return 0 ;;\n";
+    }
+    o += "      esac\n";
+    o += "      ;;\n";
+  }
+  o += "  esac\n";
+  o += "  return 1\n";
+  o += "}\n";
+  return o;
+}
+
+function emitSimulate(ident: string): string {
+  let o = "_${ident}_nac_simulate() {\n".replace("${ident}", ident);
+  o += "  local i=1 sid=0 w steps next\n";
+  o += "  while (( i < COMP_CWORD )); do\n";
+  o += "    w=\"${COMP_WORDS[i]}\"\n";
+  o += "    if [[ $w == " + kHelpShort + " || $w == " + kHelpLong + " || $w == " + kSchemaLong + " ]]; then\n";
+  o += "      ((i++)); continue\n";
+  o += "    fi\n";
+  o += "    if [[ $w == --* ]]; then\n";
+  o += "      steps=$(_${ident}_nac_consume_long \"$sid\" \"$w\" \"${COMP_WORDS[i+1]}\")\n".replace("${ident}", ident);
+  o += "      case $steps in\n";
+  o += "        0) break ;;\n";
+  o += "        1) ((i++)) ;;\n";
+  o += "        2) ((i+=2)) ;;\n";
+  o += "        *) break ;;\n";
+  o += "      esac\n";
+  o += "      continue\n";
+  o += "    fi\n";
+  o += "    if [[ $w == -* ]]; then\n";
+  o += "      steps=$(_${ident}_nac_consume_short \"$sid\" \"$w\")\n".replace("${ident}", ident);
+  o += "      case $steps in\n";
+  o += "        0) break ;;\n";
+  o += "        1) ((i++)) ;;\n";
+  o += "        2) ((i++)); break ;;\n";
+  o += "        *) break ;;\n";
+  o += "      esac\n";
+  o += "      continue\n";
+  o += "    fi\n";
+  o += "    next=$(_${ident}_nac_match_child \"$sid\" \"$w\") || break\n".replace("${ident}", ident);
+  o += "    sid=$next\n";
+  o += "    ((i++))\n";
+  o += "  done\n";
+  o += "  REPLY_SID=$sid\n";
+  o += "}\n";
+  return o;
+}
+
+function emitEnumReplyBash(ident: string, scopes: ScopeRec[]): string {
+  let o = "_${ident}_nac_enum_reply() {\n".replace("${ident}", ident);
+  o += "  local sid=\"$1\" prev=\"$2\" cur=\"$3\"\n";
+  o += "  case $sid in\n";
+  for (const [i, sc] of scopes.entries()) {
+    const enumOpts = sc.opts.filter((op) => op.kind === CliOptionKind.Enum && (op.choices?.length ?? 0) > 0);
+    if (enumOpts.length === 0) continue;
+    o += "    " + i + ")\n";
+    o += "      case $prev in\n";
+    for (const op of enumOpts) {
+      const words = (op.choices ?? []).map((c) => escShellSingleQuoted(c)).join(" ");
+      o += "        --" + op.name + ") COMPREPLY=( $(compgen -W '" + words + "' -- \"$cur\") ); return 0 ;;\n";
+    }
+    o += "      esac\n";
+    o += "      ;;\n";
+  }
+  o += "  esac\n";
+  o += "  return 1\n";
+  o += "}\n";
+  return o;
+}
+
+function emitMainBodyBash(schema: CliRouter, ident: string): string {
+  const main = mainName(schema.key);
+  let o = "_${main}() {\n".replace("${main}", main);
+  o += "  local cur=\"${COMP_WORDS[COMP_CWORD]}\"\n";
+  o += "  local prev=\"${COMP_WORDS[COMP_CWORD-1]:-}\"\n";
+  o += "  _${ident}_nac_simulate\n".replace("${ident}", ident);
+  o += "  local sid=$REPLY_SID\n";
+  o += "  if _${ident}_nac_enum_reply \"$sid\" \"$prev\" \"$cur\"; then return; fi\n".replace("${ident}", ident);
+  o += "  if [[ $cur == -* ]]; then\n";
+  o += "    local oname=\"A_${ident}_${sid}_opts\"\n".replace("${ident}", ident);
+  o += "    local -a optsarr\n";
+  o += "    local -n optsref=\"$oname\"\n";
+  o += "    COMPREPLY=( $(compgen -W \"${optsref[*]}\" -- \"$cur\") )\n";
+  o += "  else\n";
+  o += "    local lname=\"A_${ident}_${sid}_leaf\"\n".replace("${ident}", ident);
+  o += "    local -n leafref=\"$lname\"\n";
+  o += "    if [[ $leafref -eq 0 ]]; then\n";
+  o += "      local cname=\"A_${ident}_${sid}_cmds\"\n".replace("${ident}", ident);
+  o += "      local -a cmdsarr\n";
+  o += "      local -n cmdsref=\"$cname\"\n";
+  o += "      COMPREPLY=( $(compgen -W \"${cmdsref[*]}\" -- \"$cur\") )\n";
+  o += "    else\n";
+  o += "      local pname=\"A_${ident}_${sid}_pos\"\n".replace("${ident}", ident);
+  o += "      local -n posref=\"$pname\"\n";
+  o += "      if [[ $posref -eq 1 ]]; then\n";
+  o += "        compopt -o filenames\n";
+  o += "      fi\n";
+  o += "    fi\n";
+  o += "  fi\n";
+  o += "}\n\n";
+  o += "complete -F _${main} ${schema.key}\n".replace("${main}", main).replace("${schema.key}", schema.key);
+  return o;
+}
+
+/** Returns a self-contained bash `complete` script for the given program schema. */
+export function completionBashScript(schema: CliRouter): string {
+  const ident = identToken(schema.key);
+  const scopes = collectScopes(schema);
+  const pathIndex: Record<string, number> = {};
+  for (const [i, s] of scopes.entries()) {
+    pathIndex[s.path] = i;
+  }
+
+  let out = "# Generated bash completion for " + schema.key + ".\n\n";
+
+  for (const [i, sc] of scopes.entries()) {
+    out += "A_" + ident + "_" + i + "_opts=()\n";
+    out += "A_" + ident + "_" + i + "_opts+=('" + kHelpLong + "' '" + kHelpShort + "')\n";
+    if (sc.path === "") {
+      out += "A_" + ident + "_" + i + "_opts+=('" + kSchemaLong + "')\n";
+    }
+    for (const o of sc.opts) {
+      out += "A_" + ident + "_" + i + "_opts+=('--" + o.name + "')\n";
+      if (o.shortName) {
+        out += "A_" + ident + "_" + i + "_opts+=('-" + o.shortName + "')\n";
+      }
+    }
+    out += "A_" + ident + "_" + i + "_leaf=" + (sc.kids.length === 0 ? "1" : "0") + "\n";
+    out += "A_" + ident + "_" + i + "_pos=" + (sc.wantsFiles ? "1" : "0") + "\n";
+    if (sc.kids.length > 0) {
+      out += "A_" + ident + "_" + i + "_cmds=(";
+      for (const ch of sc.kids) {
+        out += " '" + ch.key + "'";
+      }
+      out += ")\n";
+    }
+  }
+
+  out += emitConsumeLong(ident, scopes);
+  out += emitConsumeShort(ident, scopes);
+  out += emitMatchChild(ident, scopes, pathIndex);
+  out += emitSimulate(ident);
+  out += emitEnumReplyBash(ident, scopes);
+  out += emitMainBodyBash(schema, ident);
+
+  return out;
+}