argsbarg 1.3.0 → 1.3.1

package/.private/scratch.md

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

package/CHANGELOG.md

@@ -7,6 +7,13 @@ 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
@@ -77,7 +84,8 @@ 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.3.0...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

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.3.0",
+  "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,6 +8,7 @@ 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";
@@ -501,6 +502,14 @@ test("--schema exports JSON for leaf roots", async () => {
   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", () => {
@@ -570,4 +579,64 @@ test("reserved option name schema is rejected", () => {
     ],
   };
   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/runtime.ts

@@ -7,7 +7,7 @@ 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, ParseKind } from "./parse.ts";
@@ -22,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);
 }
 
 /**
@@ -65,7 +63,7 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
   pr = postParseValidate(parseRoot, pr);
 
   if (pr.kind === ParseKind.Help) {
-    process.stdout.write(cliHelpRender(parseRoot, pr.helpPath, false));
+    process.stdout.write(cliHelpRender(cliPresentationRoot(root), pr.helpPath, false));
     process.exit(pr.helpExplicit ? 0 : 1);
   }
 
@@ -78,7 +76,7 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     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);
   }
 
@@ -133,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

@@ -13,6 +13,7 @@ import {
   CliOption,
   CliPositional,
 } from "./types.ts";
+import { cliBuiltinCompletionGroup } from "./completion.ts";
 
 /** JSON-safe command node (no handlers). */
 export interface CliSchemaExport {
@@ -34,6 +35,20 @@ export interface CliSchemaExport {
   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 = {
@@ -53,6 +68,7 @@ function exportCommand(cmd: CliCommand): CliSchemaExport {
     if ((cmd.positionals ?? []).length > 0) {
       out.positionals = cmd.positionals;
     }
+    out.commands = [exportBuiltinCompletionGroup(cmd.key)];
     return out;
   }