argsbarg 1.2.1 → 1.3.1

package/.private/scratch.md

@@ -0,0 +1 @@
+- [x] --schema feature for ai agents

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.1] - 2026-06-19
+
+### Fixed
+
+- **`--schema` discoverability** — list the flag in root help and offer it in shell completions at the program root (same pattern as `--help`).
+- **Leaf root help** — show the reserved `completion` command in root help and `--schema` output (routing CLIs already did).
+
+## [1.3.0] - 2026-06-18
+
+### Added
+
+- **`--schema`** — prints the full CLI tree as JSON to stdout (exit 0). Handlers are omitted; the injected `completion` subtree is excluded. Option name `schema` is reserved.
+
 ## [1.2.1] - 2026-06-18
 
 ### Changed
@@ -71,7 +84,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v1.2.1...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v1.3.1...HEAD
+[1.3.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.3.1
+[1.3.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.3.0
 [1.2.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.2.1
 [1.2.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.2.0
 [1.1.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.1.1

package/README.md

@@ -88,9 +88,11 @@ Everything you need for a first-class CLI:
 Every app gets:
 
 - `-h` / `--help` at any routing depth (scoped help).
+- **`--schema`** at the program root — print the full command tree as JSON (for tooling and agents).
 - **`completion bash` / `completion zsh`** — print shell completion scripts to stdout (injected by `cliRun`).
 
 Do not declare a top-level command named **`completion`** — it is reserved for this built-in.
+Do not declare an option named **`schema`** — it is reserved for `--schema`.
 
 
 ### Shell completions

package/justfile

@@ -8,12 +8,12 @@ check-types:
     bun x tsc
 
 # run the minimal example
-example:
-    bun ./examples/minimal.ts
+example *ARGS:
+    bun ./examples/minimal.ts {{ARGS}}
 
 # run the minimal example and watch for changes
-example-watch:
-    bun --watch ./examples/minimal.ts
+example-watch *ARGS:
+    bun --watch ./examples/minimal.ts {{ARGS}}
 
 # format the codebase
 format:

package/package.json

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

package/src/completion.ts

@@ -77,6 +77,8 @@ function mainName(schemaName: string): string {
 
 const kHelpLong = "--help";
 const kHelpShort = "-h";
+const kSchemaLong = "--schema";
+const kSchemaDesc = "Print the full command tree as JSON.";
 
 // ── Bash Completion ────────────────────────────────────────────────────────────
 
@@ -89,6 +91,9 @@ function emitConsumeLong(ident: string, scopes: ScopeRec[]): string {
     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") {
@@ -179,7 +184,7 @@ function emitSimulate(ident: string): string {
   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 + " ]]; then\n";
+    o += "    if [[ $w == " + kHelpShort + " || $w == " + kHelpLong + " || $w == " + kSchemaLong + " ]]; then\n";
   o += "      ((i++)); continue\n";
   o += "    fi\n";
   o += "    if [[ $w == --* ]]; then\n";
@@ -260,6 +265,9 @@ export function completionBashScript(schema: CliCommand): string {
   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) {
@@ -295,6 +303,14 @@ function emitScopeArraysZsh(ident: string, scopes: ScopeRec[]): string {
     out += "typeset -g A_" + ident + "_" + i + "_opts\n";
     out += "A_" + ident + "_" + i + "_opts=(";
     out += "'" + escShellSingleQuoted(kHelpLong) + ":" + escShellSingleQuoted("Show help for this command.") + "' '" + escShellSingleQuoted(kHelpShort) + ":" + escShellSingleQuoted("Show help for this command.") + "'";
+    if (sc.path === "") {
+      out +=
+        " '" +
+        escShellSingleQuoted(kSchemaLong) +
+        ":" +
+        escShellSingleQuoted(kSchemaDesc) +
+        "'";
+    }
     for (const o of sc.opts) {
       out += " '" + escShellSingleQuoted("--" + o.name) + ":" + escShellSingleQuoted(o.description) + "'";
       if (o.shortName) {
@@ -329,6 +345,9 @@ function emitConsumeLongZsh(ident: string, scopes: ScopeRec[]): string {
     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") {
@@ -419,7 +438,7 @@ function emitSimulateZsh(ident: string): string {
   o += "  local i=2 sid=0 w steps next\n";
   o += "  while (( i < CURRENT )); do\n";
   o += "    w=$words[i]\n";
-  o += "    if [[ $w == " + kHelpShort + " || $w == " + kHelpLong + " ]]; then\n";
+    o += "    if [[ $w == " + kHelpShort + " || $w == " + kHelpLong + " || $w == " + kSchemaLong + " ]]; then\n";
   o += "      ((i++)); continue\n";
   o += "    fi\n";
   o += "    if [[ $w == --* ]]; then\n";
@@ -502,6 +521,28 @@ export function completionZshScript(schema: CliCommand): string {
   return out;
 }
 
+/**
+ * Returns a schema suitable for help display, including the reserved `completion` subtree.
+ * Routing roots get `completion` merged; leaf roots are wrapped as a tiny router.
+ */
+export function cliPresentationRoot(root: CliCommand): CliCommand {
+  if ((root.commands ?? []).some((c) => c.key === "completion")) {
+    return root;
+  }
+  if ("handler" in root && root.handler) {
+    return {
+      key: root.key,
+      description: root.description,
+      options: root.options,
+      commands: [cliBuiltinCompletionGroup(root.key)],
+    } as CliCommand;
+  }
+  return {
+    ...root,
+    commands: [...(root.commands ?? []), cliBuiltinCompletionGroup(root.key)],
+  } as CliCommand;
+}
+
 /**
  * Builds the static `completion` / `bash` / `zsh` command subtree (merged into the program root at runtime).
  */

package/src/help.ts

@@ -335,13 +335,17 @@ function usageLines(
   return out;
 }
 
-/** Table rows for named options, including a synthetic `--help, -h` row. */
-function rowsForOptions(defs: CliOption[], color: boolean): HelpRow[] {
+/** Table rows for named options, including synthetic built-in rows. */
+function rowsForOptions(defs: CliOption[], color: boolean, isRoot: boolean): HelpRow[] {
   const rows: HelpRow[] = [];
   const helpLabel = color
     ? style.aquaBold("--help, ") + style.greenBright("-h")
     : "--help, -h";
   rows.push({ label: helpLabel, description: "Show help for this command." });
+  if (isRoot) {
+    const schemaLabel = color ? style.aquaBold("--schema") : "--schema";
+    rows.push({ label: schemaLabel, description: "Print the full command tree as JSON." });
+  }
   for (const o of defs) {
     const desc = o.required ? "(required) " + o.description : o.description;
     rows.push({ label: cliOptionLabel(o, color), description: desc });
@@ -387,7 +391,7 @@ export function cliHelpRender(schema: CliCommand, helpPath: string[], useStderr:
       ).join("\n"),
     );
 
-    const optBox = renderTableBox("Options", rowsForOptions(schema.options ?? [], color), hw, color);
+    const optBox = renderTableBox("Options", rowsForOptions(schema.options ?? [], color, true), hw, color);
     if (optBox.length > 0) {
       lines.push("");
       lines.push(optBox.join("\n"));
@@ -430,7 +434,7 @@ export function cliHelpRender(schema: CliCommand, helpPath: string[], useStderr:
     ).join("\n"),
   );
 
-  const optBox = renderTableBox("Options", rowsForOptions(node.options ?? [], color), hw, color);
+  const optBox = renderTableBox("Options", rowsForOptions(node.options ?? [], color, false), hw, color);
   if (optBox.length > 0) {
     lines.push("");
     lines.push(optBox.join("\n"));

package/src/index.test.ts

@@ -8,8 +8,10 @@ shell output regressions.
 */
 
 import { completionBashScript, completionZshScript } from "./completion.ts";
+import { cliHelpRender } from "./help.ts";
 import { CliCommand, CliFallbackMode, CliOptionKind } from "./index.ts";
 import { ParseKind, parse, postParseValidate } from "./parse.ts";
+import { cliSchemaJson } from "./schema.ts";
 import { cliValidateRoot } from "./validate.ts";
 import { expect, test } from "bun:test";
 import { $ } from "bun";
@@ -474,4 +476,167 @@ test("leaf completion help prints correctly", async () => {
   expect(out).toContain("Show help for this command.");
   expect(out).toContain("Output is the whole script.");
   expect(stderr.toString()).toBe("");
+});
+
+test("--schema exports JSON for nested CLIs", async () => {
+  const { stdout, stderr, exitCode } = await $`bun run examples/nested.ts --schema`.nothrow().quiet();
+  expect(exitCode).toBe(0);
+  expect(stderr.toString()).toBe("");
+
+  const schema = JSON.parse(stdout.toString());
+  expect(schema.key).toBe("nested.ts");
+  expect(schema.fallbackCommand).toBe("read");
+  expect(schema.commands.map((c: { key: string }) => c.key)).toEqual(["stat", "read"]);
+  expect(schema.commands).not.toContainEqual(expect.objectContaining({ key: "completion" }));
+
+  const lookup = schema.commands[0].commands[0].commands[0];
+  expect(lookup.key).toBe("lookup");
+  expect(lookup.positionals[0].name).toBe("path");
+});
+
+test("--schema exports JSON for leaf roots", async () => {
+  const { stdout, exitCode } = await $`bun run examples/minimal.ts --schema`.nothrow().quiet();
+  expect(exitCode).toBe(0);
+
+  const schema = JSON.parse(stdout.toString());
+  expect(schema.key).toBe("minimal.ts");
+  expect(schema.positionals[0].name).toBe("name");
+  expect(schema.options[0].name).toBe("verbose");
+  expect(schema.commands.map((c: { key: string }) => c.key)).toEqual(["completion"]);
+});
+
+test("leaf root help lists completion built-in", async () => {
+  const { stdout, exitCode } = await $`bun run examples/minimal.ts -h`.nothrow().quiet();
+  expect(exitCode).toBe(0);
+  expect(stdout.toString()).toContain("completion");
+  expect(stdout.toString()).toContain("Generate the autocompletion script for shells.");
+});
+
+test("parse recognizes --schema at the program root", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "demo",
+    commands: [
+      {
+        key: "x",
+        description: "cmd",
+        handler: () => {},
+      },
+    ],
+  };
+  cliValidateRoot(root);
+  const pr = parse(root, ["--schema"]);
+  expect(pr.kind).toBe(ParseKind.Schema);
+});
+
+test("cliSchemaJson omits handlers and completion built-ins", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "demo",
+    commands: [
+      {
+        key: "x",
+        description: "cmd",
+        handler: () => {},
+      },
+      {
+        key: "completion",
+        description: "should not appear",
+        commands: [
+          {
+            key: "bash",
+            description: "",
+            handler: () => {},
+          },
+        ],
+      },
+    ],
+  };
+
+  const schema = JSON.parse(cliSchemaJson(root));
+  expect(schema.commands).toHaveLength(1);
+  expect(schema.commands[0].key).toBe("x");
+  expect(schema).not.toHaveProperty("handler");
+});
+
+test("reserved option name schema is rejected", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "x",
+        description: "cmd",
+        options: [
+          {
+            name: "schema",
+            description: "",
+            kind: CliOptionKind.String,
+          },
+        ],
+        handler: () => {},
+      },
+    ],
+  };
+  expect(() => cliValidateRoot(root)).toThrow(/reserved for --schema/);
+});
+
+test("root help lists --schema built-in", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "demo",
+    commands: [
+      {
+        key: "x",
+        description: "cmd",
+        handler: () => {},
+      },
+    ],
+  };
+  const help = cliHelpRender(root, [], false);
+  expect(help).toContain("--schema");
+  expect(help).toContain("Print the full command tree as JSON.");
+});
+
+test("nested help omits --schema built-in", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "demo",
+    commands: [
+      {
+        key: "x",
+        description: "cmd",
+        handler: () => {},
+      },
+    ],
+  };
+  const help = cliHelpRender(root, ["x"], false);
+  expect(help).not.toContain("--schema");
+});
+
+test("completion scripts offer --schema at the program root only", () => {
+  const root: CliCommand = {
+    key: "myapp",
+    description: "",
+    commands: [
+      {
+        key: "stat",
+        description: "stats",
+        commands: [
+          {
+            key: "show",
+            description: "show",
+            handler: () => {},
+          },
+        ],
+      },
+    ],
+  };
+
+  const bash = completionBashScript(root);
+  expect(bash).toContain("A_myapp_0_opts+=('--schema')");
+  expect(bash).not.toContain("A_myapp_1_opts+=('--schema')");
+
+  const zsh = completionZshScript(root);
+  expect(zsh).toContain("'--schema:Print the full command tree as JSON.'");
 });

package/src/parse.ts

@@ -26,6 +26,8 @@ export enum ParseKind {
   Ok = "ok",
   /** User requested help (explicit or implicit). */
   Help = "help",
+  /** User requested machine-readable schema export (`--schema`). */
+  Schema = "schema",
   /** User error (unknown command, bad option, etc.). */
   Error = "error",
 }
@@ -54,12 +56,18 @@ export interface ParseResult {
 
 const helpShort = "-h";
 const helpLong = "--help";
+const schemaLong = "--schema";
 
 /** Returns true if the argv token is `-h` or `--help`. */
 function isHelpTok(tok: string): boolean {
   return tok === helpShort || tok === helpLong;
 }
 
+/** Returns true if the argv token is `--schema`. */
+function isSchemaTok(tok: string): boolean {
+  return tok === schemaLong;
+}
+
 /** Looks up a subcommand or routing node by `key`. */
 function findChild(cmds: CliCommand[], name: string): CliCommand | undefined {
   return cmds.find((c) => c.key === name);
@@ -184,6 +192,7 @@ function consumeOptions(
     const tok = argv[idx];
 
     if (isHelpTok(tok)) break;
+    if (isSchemaTok(tok)) break;
     if (!tok.startsWith("-")) break;
 
     if (tok === "--") {
@@ -334,6 +343,20 @@ function helpResult(p: string[], explicit: boolean): ParseResult {
   };
 }
 
+/** Builds a schema-export result for the program root. */
+function schemaResult(): ParseResult {
+  return {
+    kind: ParseKind.Schema,
+    path: [],
+    opts: {},
+    args: [],
+    helpExplicit: false,
+    helpPath: [],
+    errorMsg: "",
+    errorHelpPath: [],
+  };
+}
+
 /**
  * Parses `argv` against the program root, routing into subcommands and filling `opts` / `args`.
  */
@@ -367,6 +390,10 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
     return helpResult([], true);
   }
 
+  if (i < argv.length && !forcePositionals && isSchemaTok(argv[i])) {
+    return schemaResult();
+  }
+
   // Determine which subcommand to route to
   let cmdName: string;
   let node: CliCommand | undefined;

package/src/runtime.ts

@@ -7,10 +7,11 @@ It keeps execution flow out of the public barrel so the exported API stays small
 the runtime responsibilities remain easy to reason about.
 */
 
-import { cliBuiltinCompletionGroup, completionBashScript, completionZshScript } from "./completion.ts";
+import { cliBuiltinCompletionGroup, cliPresentationRoot, completionBashScript, completionZshScript } from "./completion.ts";
 import { CliContext } from "./context.ts";
 import { cliHelpRender } from "./help.ts";
-import { parse, postParseValidate } from "./parse.ts";
+import { parse, postParseValidate, ParseKind } from "./parse.ts";
+import { cliSchemaJson } from "./schema.ts";
 import { CliCommand } from "./types.ts";
 import { cliValidateRoot } from "./validate.ts";
 
@@ -21,9 +22,7 @@ function cliRootMergedWithBuiltins(root: CliCommand): CliCommand {
   if (root.handler) {
     return root;
   }
-  const merged = { ...root } as any;
-  merged.commands = [...(root.commands ?? []), cliBuiltinCompletionGroup(root.key)];
-  return merged as CliCommand;
+  return cliPresentationRoot(root);
 }
 
 /**
@@ -63,16 +62,21 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
   let pr = parse(parseRoot, argv);
   pr = postParseValidate(parseRoot, pr);
 
-  if (pr.kind === "help") {
-    process.stdout.write(cliHelpRender(parseRoot, pr.helpPath, false));
+  if (pr.kind === ParseKind.Help) {
+    process.stdout.write(cliHelpRender(cliPresentationRoot(root), pr.helpPath, false));
     process.exit(pr.helpExplicit ? 0 : 1);
   }
 
+  if (pr.kind === ParseKind.Schema) {
+    process.stdout.write(cliSchemaJson(root));
+    process.exit(0);
+  }
+
   if (pr.kind === "error") {
     const color = process.stderr.isTTY;
     const msg = color ? `\u001B[31m${pr.errorMsg}\u001B[0m` : pr.errorMsg;
     process.stderr.write(msg + "\n");
-    process.stderr.write(cliHelpRender(parseRoot, pr.errorHelpPath, true));
+    process.stderr.write(cliHelpRender(cliPresentationRoot(root), pr.errorHelpPath, true));
     process.exit(1);
   }
 
@@ -127,6 +131,6 @@ export function cliErrWithHelp(ctx: CliContext, msg: string): never {
   const color = process.stderr.isTTY;
   const line = color ? `\u001B[31m${msg}\u001B[0m` : msg;
   process.stderr.write(line + "\n");
-  process.stderr.write(cliHelpRender(ctx.schema, ctx.commandPath, true));
+  process.stderr.write(cliHelpRender(cliPresentationRoot(ctx.schema), ctx.commandPath, true));
   process.exit(1);
 }

package/src/schema.ts

@@ -0,0 +1,93 @@
+/*
+This module serializes the CLI schema tree to JSON for machine-readable introspection.
+It strips handlers and runtime-only nodes so agents can discover commands, options,
+and positionals in one shot.
+
+It keeps schema export aligned with the declarative CliCommand model that drives help
+and completion.
+*/
+
+import {
+  CliCommand,
+  CliFallbackMode,
+  CliOption,
+  CliPositional,
+} from "./types.ts";
+import { cliBuiltinCompletionGroup } from "./completion.ts";
+
+/** JSON-safe command node (no handlers). */
+export interface CliSchemaExport {
+  /** Program or command key. */
+  key: string;
+  /** Short description shown in help. */
+  description: string;
+  /** Additional notes shown in help (supports {app} placeholder). */
+  notes?: string;
+  /** Global or command-level flags/options. */
+  options?: CliOption[];
+  /** Default top-level subcommand (program root only). */
+  fallbackCommand?: string;
+  /** How fallbackCommand is applied (program root only). */
+  fallbackMode?: CliFallbackMode;
+  /** Nested subcommands (routing nodes only). */
+  commands?: CliSchemaExport[];
+  /** Positional argument definitions (leaf nodes only). */
+  positionals?: CliPositional[];
+}
+
+/** JSON-safe export of the reserved `completion` subtree (no handler recursion). */
+function exportBuiltinCompletionGroup(appName: string): CliSchemaExport {
+  const group = cliBuiltinCompletionGroup(appName);
+  return {
+    key: group.key,
+    description: group.description,
+    commands: (group.commands ?? []).map((ch) => ({
+      key: ch.key,
+      description: ch.description,
+      ...((ch.notes ?? "").length > 0 ? { notes: ch.notes } : {}),
+    })),
+  };
+}
+
+/** Converts one `CliCommand` node into a JSON-safe export (handlers omitted). */
+function exportCommand(cmd: CliCommand): CliSchemaExport {
+  const out: CliSchemaExport = {
+    key: cmd.key,
+    description: cmd.description,
+  };
+
+  if ((cmd.notes ?? "").length > 0) {
+    out.notes = cmd.notes;
+  }
+
+  if ((cmd.options ?? []).length > 0) {
+    out.options = cmd.options;
+  }
+
+  if ("handler" in cmd && cmd.handler) {
+    if ((cmd.positionals ?? []).length > 0) {
+      out.positionals = cmd.positionals;
+    }
+    out.commands = [exportBuiltinCompletionGroup(cmd.key)];
+    return out;
+  }
+
+  if (cmd.fallbackCommand !== undefined) {
+    out.fallbackCommand = cmd.fallbackCommand;
+  }
+  if (cmd.fallbackMode !== undefined) {
+    out.fallbackMode = cmd.fallbackMode;
+  }
+
+  const children = (cmd.commands ?? []).filter((ch) => ch.key !== "completion");
+  if (children.length > 0) {
+    out.commands = children.map(exportCommand);
+  }
+
+  return out;
+}
+
+/** Returns pretty-printed JSON for the full program schema (trailing newline). */
+export function cliSchemaJson(root: CliCommand): string {
+  return JSON.stringify(exportCommand(root), null, 2) + "\n";
+}

package/src/validate.ts

@@ -69,6 +69,12 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
       );
     }
 
+    if (opt.name === "schema") {
+      throw new CliSchemaValidationError(
+        `Option name "schema" is reserved for --schema: ${cmd.key}/${opt.name}`,
+      );
+    }
+
     if (opt.shortName !== undefined) {
       if (opt.shortName === "h") {
         throw new CliSchemaValidationError(