argsbarg 1.2.0 → 1.2.1

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/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +71,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.0...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v1.2.1...HEAD
+[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/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.2.1",
   "type": "module",
   "scripts": {
     "//just": "echo this app uses justfile for development tasks"

package/src/index.test.ts

@@ -238,6 +238,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",

package/src/parse.ts

@@ -207,6 +207,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 +234,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 +265,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 +296,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: [] };
@@ -329,7 +372,7 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
   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 +458,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 +498,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);
   }
 }