argsbarg 1.2.0 → 1.3.0

package/.github/copilot-instructions.md.md

@@ -0,0 +1,8 @@
+---
+description: Project context for AI agents
+---
+
+Always include in context before answering or making changes in this repository:
+
+- `README.md`
+- `.cursor/rules/*`

package/.github/pull_request_template.md

@@ -0,0 +1,13 @@
+## Summary
+
+<!-- What does this PR change and why? -->
+
+## Changelog
+
+**Every PR must update `CHANGELOG.md` under `## [Unreleased]`**: use `### Added`, `### Changed`, `### Fixed`, or `### Removed` as appropriate; one idea per bullet.
+
+<!-- If you claimed no-op above, briefly say why no changelog entry is warranted. -->
+
+## Testing
+
+<!-- How did you verify this (local build, tests, manual run, etc.)? -->

package/.private/scratch.md

@@ -0,0 +1 @@
+- [ ] --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.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
+
+- **Trailing options** — when a leaf command has only bounded positionals (`argMax !== 0`), options may appear after positional arguments (e.g. `cmd ./file --verbose`). Commands with a varargs tail (`argMax: 0`) keep the previous behavior.
+- **`examples/nested.ts`** — `stat` accepts `--json`; `stat owner lookup` prints JSON when the flag is set.
+
 ## [1.2.0] - 2026-04-24
 
 ### Added
@@ -64,7 +77,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.0...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v1.3.0...HEAD
+[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
 [1.1.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.1.0

package/CLAUDE.md

@@ -0,0 +1,8 @@
+---
+description: Project context for AI agents
+---
+
+Always include in context before answering or making changes in this repository:
+
+- `./README.md`
+- .cursor/rules/*

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/examples/nested.ts

@@ -16,6 +16,13 @@ const cli: CliCommand = {
     {
       key: "stat",
       description: "File metadata.",
+      options: [
+        {
+          name: "json",
+          description: "Emit handler output as JSON.",
+          kind: CliOptionKind.Presence,
+        },
+      ],
       commands: [
         {
           key: "owner",
@@ -46,7 +53,11 @@ const cli: CliCommand = {
                   console.error("Missing path.");
                   process.exit(1);
                 }
-                console.log(`lookup user=${user} path=${path}`);
+                if (ctx.hasFlag("json")) {
+                  console.log(JSON.stringify({ user, path }));
+                } else {
+                  console.log(`lookup user=${user} path=${path}`);
+                }
               },
             },
           ],

package/package.json

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

package/src/index.test.ts

@@ -10,6 +10,7 @@ shell output regressions.
 import { completionBashScript, completionZshScript } from "./completion.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";
@@ -238,6 +239,123 @@ test("completion scripts keep dotted app names in registration names", () => {
   expect(zsh).toContain("compdef _minimal_ts minimal.ts");
 });
 
+test("trailing options after bounded positionals", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "x",
+        description: "cmd",
+        options: [
+          {
+            name: "verbose",
+            description: "",
+            kind: CliOptionKind.Presence,
+          },
+        ],
+        positionals: [
+          {
+            name: "path",
+            description: "",
+            kind: CliOptionKind.String,
+          },
+        ],
+        handler: () => {},
+      },
+    ],
+  };
+  cliValidateRoot(root);
+  const pr = postParseValidate(root, parse(root, ["x", "./file", "--verbose"]));
+  expect(pr.kind).toBe(ParseKind.Ok);
+  expect(pr.args).toEqual(["./file"]);
+  expect(pr.opts["verbose"]).toBe("1");
+});
+
+test("trailing options include parent-scoped flags", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "group",
+        description: "group",
+        options: [
+          {
+            name: "json",
+            description: "",
+            kind: CliOptionKind.Presence,
+          },
+        ],
+        commands: [
+          {
+            key: "leaf",
+            description: "leaf",
+            options: [
+              {
+                name: "user",
+                description: "",
+                kind: CliOptionKind.String,
+                shortName: "u",
+              },
+            ],
+            positionals: [
+              {
+                name: "path",
+                description: "",
+                kind: CliOptionKind.String,
+              },
+            ],
+            handler: () => {},
+          },
+        ],
+      },
+    ],
+  };
+  cliValidateRoot(root);
+  const pr = postParseValidate(root, parse(root, ["group", "leaf", "-u", "alice", "./file", "--json"]));
+  expect(pr.kind).toBe(ParseKind.Ok);
+  expect(pr.path).toEqual(["group", "leaf"]);
+  expect(pr.args).toEqual(["./file"]);
+  expect(pr.opts["user"]).toBe("alice");
+  expect(pr.opts["json"]).toBe("1");
+});
+
+test("varargs tail does not parse trailing options", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "x",
+        description: "cmd",
+        options: [
+          {
+            name: "json",
+            description: "",
+            kind: CliOptionKind.Presence,
+          },
+        ],
+        positionals: [
+          {
+            name: "files",
+            description: "",
+            kind: CliOptionKind.String,
+            argMin: 0,
+            argMax: 0,
+          },
+        ],
+        handler: () => {},
+      },
+    ],
+  };
+  cliValidateRoot(root);
+  const pr = postParseValidate(root, parse(root, ["x", "./file", "--json"]));
+  expect(pr.kind).toBe(ParseKind.Ok);
+  expect(pr.args).toEqual(["./file", "--json"]);
+  expect(pr.opts["json"]).toBeUndefined();
+});
+
 test("stops parsing options at --", () => {
   const root: CliCommand = {
     key: "app",
@@ -357,4 +475,99 @@ 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");
+});
+
+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/);
 });

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 === "--") {
@@ -207,6 +216,26 @@ function consumeOptions(
 
 // ── Positional Collection ─────────────────────────────────────────────────────
 
+/** Merges option defs from the program root along the routed command path. */
+function collectOptionDefs(root: CliCommand, path: string[]): CliOption[] {
+  let defs = [...(root.options ?? [])];
+  let cmds = root.commands ?? [];
+
+  for (const seg of path) {
+    const ch = findChild(cmds, seg);
+    if (!ch) break;
+    defs.push(...(ch.options ?? []));
+    cmds = ch.commands ?? [];
+  }
+
+  return defs;
+}
+
+/** True when every positional slot has bounded arity (no `argMax: 0` varargs tail). */
+function allowsTrailingOptions(positionals: CliCommand["positionals"]): boolean {
+  return (positionals ?? []).every((p) => (p.argMax ?? 1) !== 0);
+}
+
 /** Fills `args` for a leaf from `startIdx` according to `node.positionals`. */
 function finishLeaf(
   node: CliCommand,
@@ -214,6 +243,8 @@ function finishLeaf(
   argv: string[],
   path: string[],
   opts: Record<string, string>,
+  optionDefs: CliOption[],
+  forcePositionals: boolean,
 ): ParseResult {
   /** Builds a parse error for positional consumption failures. */
   function errorResult(msg: string): ParseResult {
@@ -243,8 +274,13 @@ function finishLeaf(
         args.push(argv[idx]);
         idx += 1;
       } else if (idx < argv.length) {
-        args.push(argv[idx]);
-        idx += 1;
+        const tok = argv[idx];
+        if (argMin < 1 && tok.startsWith("-")) {
+          // Optional slot: leave `-` tokens for trailing option parsing.
+        } else {
+          args.push(tok);
+          idx += 1;
+        }
       }
       continue;
     }
@@ -269,7 +305,23 @@ function finishLeaf(
   }
 
   if (idx < argv.length) {
-    return errorResult("Unexpected extra arguments");
+    if (forcePositionals || !allowsTrailingOptions(node.positionals)) {
+      return errorResult("Unexpected extra arguments");
+    }
+
+    if (isHelpTok(argv[idx])) {
+      return helpResult(path, true);
+    }
+
+    const tailRep = consumeOptions(optionDefs, false, argv, idx, opts);
+    if (tailRep.report.err) {
+      return errorResult(tailRep.report.err);
+    }
+    idx = tailRep.nextIndex;
+
+    if (idx < argv.length) {
+      return errorResult("Unexpected extra arguments");
+    }
   }
 
   return { kind: ParseKind.Ok, path, opts, args, helpExplicit: false, helpPath: [], errorMsg: "", errorHelpPath: [] };
@@ -291,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`.
  */
@@ -324,12 +390,16 @@ 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;
 
   if (root.handler) {
-    return finishLeaf(root as any, i, argv, path, opts);
+    return finishLeaf(root as CliCommand, i, argv, path, opts, root.options ?? [], forcePositionals);
   }
 
   if (i >= argv.length) {
@@ -415,7 +485,7 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
       if ((current.commands ?? []).length > 0) {
         return helpResult(path, false);
       }
-      return finishLeaf(current, i, argv, path, opts);
+      return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals);
     }
 
     const tok = argv[i];
@@ -455,7 +525,7 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
       };
     }
 
-    return finishLeaf(current, i, argv, path, opts);
+    return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals);
   }
 }
 

package/src/runtime.ts

@@ -10,7 +10,8 @@ the runtime responsibilities remain easy to reason about.
 import { cliBuiltinCompletionGroup, 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";
 
@@ -63,11 +64,16 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
   let pr = parse(parseRoot, argv);
   pr = postParseValidate(parseRoot, pr);
 
-  if (pr.kind === "help") {
+  if (pr.kind === ParseKind.Help) {
     process.stdout.write(cliHelpRender(parseRoot, 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;

package/src/schema.ts

@@ -0,0 +1,77 @@
+/*
+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";
+
+/** 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[];
+}
+
+/** 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;
+    }
+    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(