argsbarg 1.2.1 → 1.3.0

package/.private/scratch.md

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

package/CHANGELOG.md

@@ -7,6 +7,12 @@ 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
@@ -71,7 +77,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.2.1...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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "1.2.1",
+  "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";
@@ -474,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 === "--") {
@@ -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

@@ -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(