argsbarg 1.4.1 → 1.4.2

package/.cursor/plans/v1.3_parser_ergonomics_b3e91f02.plan.md

@@ -0,0 +1,455 @@
+---
+name: v1.3 — parser ergonomics
+overview: "Four targeted parser and DX improvements: nested fallbackCommand on any routing node, varargs + trailing options interleaved (fixes --flag after positionals), ctx.positional(name) named accessor, and MCP string→array coercion for varargs positionals."
+todos:
+  - id: types-jsdoc
+    content: "Step 1: Update JSDoc on fallbackCommand/fallbackMode to remove 'root-only' / 'top-level' language; no type changes needed"
+    status: completed
+  - id: validate-fallback
+    content: "Step 2: Remove root-only restriction on fallbackCommand/fallbackMode in validate.ts; add validation that fallbackCommand names a valid child key on any routing node"
+    status: completed
+  - id: parser-fallback
+    content: "Step 3: Extend routing loop to apply fallbackCommand/fallbackMode at non-root routing nodes (mirrors existing root logic)"
+    status: completed
+  - id: parser-varargs-trailing
+    content: "Step 4: Fix finishLeaf varargs loop to interleave known-option scanning instead of greedy-consuming all remaining tokens"
+    status: completed
+  - id: ctx-positional
+    content: "Step 5: Add ctx.positional(name) accessor to CliContext — named positional lookup computed from schema + commandPath + args"
+    status: completed
+  - id: mcp-coerce
+    content: "Step 6: Coerce string → string[] in mcpToolCallToArgv for varargs positionals (comma-split or single-item)"
+    status: completed
+  - id: tests
+    content: "Step 7: Unit + integration tests for all four features"
+    status: completed
+  - id: docs-changelog
+    content: "Step 8: Update README, CHANGELOG, docs/mcp.md; run just typegen and just test"
+    status: completed
+isProject: false
+---
+
+# v1.3 — parser ergonomics
+
+Four parser and DX improvements. No new runtime dependencies, no public API removals, no MCP protocol changes. All four were explicitly deferred from v1.2 and follow directly from consumer app feedback.
+
+---
+
+## Background
+
+From reading the current source before writing this plan:
+
+- **`fallbackCommand` types already support non-root** — `CliCommand` union allows `fallbackCommand` on any router node. The restriction is purely in `validate.ts` lines 39–52 (`!isRoot && cmd.fallbackCommand !== undefined → throw`). Parser fix is in the routing `while(true)` loop.
+- **Trailing options are already partially wired** — `finishLeaf` calls `consumeOptions` on the tail for bounded-arity positionals (see `allowsTrailingOptions`). The gap is varargs (`argMax === 0`): the greedy loop at line 289–304 consumes all remaining tokens before any trailing option scan can happen.
+- **`ctx.positional(name)`** — `CliContext` has `args: string[]` and `schema: CliCommand`. Named positional access can be computed from those; no parser change required.
+- **MCP string→array coercion** — `mcpToolCallToArgv` currently requires `args[pos.name]` to be `string[]` for varargs. Accepts only arrays; agents passing `"a,b"` or `"a"` silently fail.
+
+---
+
+## Implementation order
+
+1. JSDoc cleanup (no logic)
+2. Validation: remove root-only fallback restriction
+3. Parser: nested fallback routing
+4. Parser: varargs + trailing options interleaved
+5. `ctx.positional(name)`
+6. MCP string→array coercion
+7. Tests
+8. Docs + changelog
+
+Do steps 3 and 4 independently — they touch different parts of `parse.ts`. Step 3 is the routing loop; step 4 is `finishLeaf`. Both must pass existing tests before moving on.
+
+---
+
+## Step 1: JSDoc ([`src/types.ts`](src/types.ts))
+
+No type changes. Update JSDoc on the router branch of `CliCommand`:
+
+- `fallbackCommand`: change "Default **top-level** subcommand" → "Default subcommand"
+- `fallbackMode`: change "How fallbackCommand is applied" — add note that both fields work on any routing node, not just root
+
+---
+
+## Step 2: Validation ([`src/validate.ts`](src/validate.ts))
+
+### Remove root-only restriction
+
+Delete lines 39–52 entirely:
+```typescript
+// DELETE:
+if (!isRoot && cmd.fallbackCommand !== undefined) {
+  throw new CliSchemaValidationError(
+    "Fallback is only supported on the program root (not on " + cmd.key + ")",
+  );
+}
+if (!isRoot && cmd.fallbackMode !== undefined && ...) {
+  throw new CliSchemaValidationError(
+    "fallbackMode may only be set on the program root (not on " + cmd.key + ")",
+  );
+}
+```
+
+### Add fallbackCommand child validation (apply to ALL routing nodes, not just root)
+
+After the duplicate child name check (the `seenNames` loop), add:
+
+```typescript
+// fallbackMode without fallbackCommand is always invalid — check unconditionally
+if (cmd.fallbackMode !== undefined && cmd.fallbackCommand === undefined) {
+  throw new CliSchemaValidationError(
+    `fallbackMode requires fallbackCommand on '${cmd.key}'`,
+  );
+}
+
+if (cmd.fallbackCommand !== undefined) {
+  const children = cmd.commands ?? [];
+  const valid = children.find((c) => c.key === cmd.fallbackCommand);
+  if (!valid) {
+    throw new CliSchemaValidationError(
+      `fallbackCommand '${cmd.fallbackCommand}' is not a child of '${cmd.key}'`,
+    );
+  }
+}
+```
+
+**Note:** The existing root-level validation already does the child-lookup check implicitly via the runtime. Moving it into schema validation means it's caught at startup, not at dispatch time.
+
+---
+
+## Step 3: Parser — nested `fallbackCommand` ([`src/parse.ts`](src/parse.ts))
+
+The routing `while(true)` loop (line ~459) has two places where non-root routing nodes currently error. Both need fallback logic inserted before the error return.
+
+### Place 1: End of argv, current node has children (line ~485)
+
+Currently: `return helpResult(path, false)` when `current.commands.length > 0` and argv is exhausted.
+
+Add before that return:
+```typescript
+if ((current.commands ?? []).length > 0) {
+  const fb = current.fallbackCommand;
+  const fm = current.fallbackMode ?? CliFallbackMode.MissingOnly;
+  if (
+    fb !== undefined &&
+    (fm === CliFallbackMode.MissingOnly || fm === CliFallbackMode.MissingOrUnknown)
+  ) {
+    const fbNode = findChild(current.commands ?? [], fb);
+    if (fbNode) {
+      path.push(fb);
+      current = fbNode;
+      continue;
+    }
+  }
+  return helpResult(path, false);
+}
+```
+
+### Place 2: Unknown subcommand token (line ~515–526)
+
+Currently: `return error "Unknown subcommand: tok"` when the token doesn't match any child.
+
+Add before that return:
+```typescript
+if ((current.commands ?? []).length > 0) {
+  const fb = current.fallbackCommand;
+  const fm = current.fallbackMode ?? CliFallbackMode.MissingOnly;
+  const canRouteUnknown =
+    fb !== undefined &&
+    (fm === CliFallbackMode.MissingOrUnknown || fm === CliFallbackMode.UnknownOnly);
+
+  if (canRouteUnknown) {
+    const fbNode = findChild(current.commands ?? [], fb!);
+    if (fbNode) {
+      // Do NOT advance i — the unrecognized token stays as argv for the fallback
+      path.push(fb!);
+      current = fbNode;
+      continue;
+    }
+  }
+  return { kind: ParseKind.Error, ..., errorMsg: `Unknown subcommand: ${tok}` };
+}
+```
+
+This mirrors the root-level fallback logic at lines 406–452 exactly. The same `CliFallbackMode` semantics apply at every routing level.
+
+---
+
+## Step 4: Parser — varargs + trailing options ([`src/parse.ts`](src/parse.ts) — `finishLeaf`)
+
+### The problem
+
+`finishLeaf`'s varargs branch (line ~289–304):
+```typescript
+if (argMax === 0) {
+  while (idx < argv.length) {
+    args.push(argv[idx]);   // ← greedy: swallows --json and all flags
+    idx += 1;
+    count += 1;
+  }
+}
+```
+
+All remaining tokens (including `--flag` tokens) are consumed as positionals. The trailing option scan at lines 307–325 never runs because `idx === argv.length` after the greedy loop.
+
+### The fix
+
+Replace the greedy varargs loop with an interleaved loop that recognizes known options:
+
+```typescript
+if (argMax === 0) {
+  while (idx < argv.length) {
+    const tok = argv[idx];
+
+    // -- separator: force remaining tokens as positionals
+    if (!forcePositionals && tok === "--") {
+      forcePositionals = true;
+      idx++;
+      continue;
+    }
+
+    // Scoped help inside varargs tail — mirrors bounded path at lines 312–314
+    if (!forcePositionals && isHelpTok(tok)) {
+      return helpResult(path, true);
+    }
+
+    // Possible option token: attempt to consume as a known flag
+    if (!forcePositionals && tok.startsWith("-")) {
+      // MUST be false — lenient mode swallows unknown flags as positionals silently
+      const tailRep = consumeOptions(optionDefs, false, argv, idx, opts);
+      if (tailRep.report.err) {
+        return errorResult(tailRep.report.err);
+      }
+      if (tailRep.report.sawDoubleDash) {
+        forcePositionals = true;
+      }
+      if (tailRep.nextIndex > idx) {
+        // Consumed one or more options — loop without pushing a positional
+        idx = tailRep.nextIndex;
+        continue;
+      }
+      // consumeOptions stopped without advancing (unknown token in lenient mode
+      // would return stoppedOnUnknown, but we pass lenientUnknown=false, so
+      // any unknown -flag is already an error above). Fallthrough to error.
+      return errorResult(`Unexpected option token: ${tok}`);
+    }
+
+    // Plain positional token
+    args.push(tok);
+    idx++;
+    count++;
+  }
+}
+```
+
+**Key rules:**
+- `consumeOptions` is called with `lenientUnknown: false` — unknown flags in varargs tails are still errors, not silently treated as positionals
+- `--` terminates option scanning exactly as before; tokens after it go straight to `args`
+- Bounded positionals are unchanged — their existing trailing option scan at lines 307–325 still runs and is unaffected
+
+**Remove `allowsTrailingOptions`** — it becomes dead code once varargs interleaves. Delete the function and its call site.
+
+---
+
+## Step 5: `ctx.positional(name)` ([`src/context.ts`](src/context.ts))
+
+### Accessor
+
+```typescript
+/**
+ * Returns the value(s) for a named positional slot.
+ * Varargs slots (argMax === 0) return string[]; single slots return string | undefined.
+ */
+positional(name: string): string | string[] | undefined {
+  return this._positionalMap()[name];
+}
+```
+
+### Implementation (`_positionalMap`)
+
+Compute lazily and cache. Walk `this.schema` along `this.commandPath` to find the leaf, then map positional definitions to slices of `this.args`:
+
+```typescript
+private _posMap: Record<string, string | string[]> | undefined;
+
+private _positionalMap(): Record<string, string | string[]> {
+  if (this._posMap) return this._posMap;
+
+  let node: CliCommand = this.schema;
+  for (const seg of this.commandPath) {
+    const child = (node.commands ?? []).find((c) => c.key === seg);
+    if (!child) { this._posMap = {}; return {}; }
+    node = child;
+  }
+
+  const map: Record<string, string | string[]> = {};
+  let argIdx = 0;
+  for (const p of node.positionals ?? []) {
+    const { argMax = 1 } = p;
+    if (argMax === 0) {
+      map[p.name] = this.args.slice(argIdx);
+      argIdx = this.args.length;
+    } else {
+      const val = this.args[argIdx];
+      if (val !== undefined) map[p.name] = val;
+      argIdx++;
+    }
+  }
+
+  this._posMap = map;
+  return map;
+}
+```
+
+**Return type semantics:**
+- Varargs (`argMax === 0`) → always `string[]` (may be empty)
+- Single slot (`argMax === 1`) → `string` if present, `undefined` if optional and absent
+- Always consistent with `ctx.args` — `ctx.positional` is a named view over the same data
+
+**No changes to `ctx.args`** — existing handlers continue to work; this is purely additive.
+
+### Export
+
+Add `positional` to the public method list in JSDoc. No changes to `src/index.ts` needed — `CliContext` is already exported and consumers get the new method automatically.
+
+---
+
+## Step 6: MCP string→array coercion ([`src/mcp/tools.ts`](src/mcp/tools.ts) — `mcpToolCallToArgv`)
+
+### Current behavior (varargs positional)
+
+```typescript
+// Current:
+const val = args[pos.name];
+// assumes val is string[] — agents passing "a,b" or "a" get undefined behavior
+argv.push(...(val as string[]));
+```
+
+### Fix
+
+```typescript
+const raw = args[pos.name];
+let items: string[];
+if (Array.isArray(raw)) {
+  items = raw.map(String);
+} else if (typeof raw === "string") {
+  // Coerce: comma-split or single item
+  items = raw.includes(",")
+    ? raw.split(",").map((s) => s.trim()).filter(Boolean)
+    : raw.trim() ? [raw.trim()] : [];
+} else {
+  items = [];
+}
+argv.push(...items);
+```
+
+**`inputSchema` stays `{ type: "array", items: { type: "string" } }`** — array is the correct type for well-behaved agents. The coercion is a silent recovery from agents that pass strings anyway. Do not change the schema to `oneOf` — that complicates the JSON Schema unnecessarily.
+
+**Single string `"a"` → `["a"]`** (not comma-split). Comma is the delimiter only when present.
+
+---
+
+## Step 7: Tests ([`src/index.test.ts`](src/index.test.ts))
+
+### Nested `fallbackCommand` — unit tests
+
+1. Router node with `fallbackCommand` and empty argv → routes to fallback leaf.
+2. Router node with `fallbackCommand` + `MissingOrUnknown` + unknown token → routes to fallback (token stays in argv for fallback leaf).
+3. Router node with `fallbackCommand` + `MissingOnly` + unknown token → error "Unknown subcommand".
+4. `cliValidateRoot` rejects `fallbackCommand` naming a non-existent child on a non-root node.
+5. `cliValidateRoot` accepts `fallbackCommand` on a non-root router node when child exists.
+6. Scoped help: `myapp docs --help` on a router with fallback → shows docs subcommands, not fallback content.
+
+### Varargs + trailing options — unit tests
+
+7. `cliInvoke(root, ["read", "file.txt", "--json"])` where `read` has varargs positional and `--json` is a known option → `kind: "ok"`, `args: ["file.txt"]`, `opts: { json: "1" }`.
+8. `cliInvoke(root, ["read", "--json", "file.txt"])` → same result (option before varargs).
+9. `cliInvoke(root, ["read", "a.txt", "b.txt", "--json"])` → `args: ["a.txt", "b.txt"]`, `opts: { json: "1" }`.
+10. `cliInvoke(root, ["read", "file.txt", "--", "--json"])` → `args: ["file.txt", "--json"]`, `opts: {}` (`--` forces positional).
+11. `cliInvoke(root, ["read", "--unknown"])` → `kind: "error"`, errorMsg mentions `--unknown`.
+12. `parse(root, ["read", "file.txt", "--help"])` on a varargs leaf → `kind: Help`, `helpPath` contains `"read"` (scoped help, not an error). This guards the `isHelpTok` insertion.
+
+**Regression test inversion:** The existing test `"varargs tail does not parse trailing options"` (approximately line 337 in `index.test.ts`) currently *asserts the broken behavior* — `--json` ends up in `args`. Invert it: after Step 4, assert `--json` is in `opts` and absent from `args`. Do this as part of Step 7, not before.
+
+### `ctx.positional(name)` — unit tests
+
+13. Handler reads `ctx.positional("path")` on single-slot positional — returns the string value.
+14. Handler reads `ctx.positional("files")` on varargs positional — returns `string[]`.
+15. Handler reads `ctx.positional("opt")` on absent optional positional — returns `undefined`.
+16. `ctx.positional("files")` consistent with `ctx.args`: `ctx.positional("files")` deep-equals `ctx.args` when there is one varargs positional.
+
+### MCP string→array coercion — unit tests
+
+17. `mcpToolCallToArgv` with varargs positional: `args: { files: "a,b" }` → argv includes `"a"`, `"b"` as separate tokens.
+18. `mcpToolCallToArgv` with varargs positional: `args: { files: "a" }` (no comma) → argv includes `"a"` once.
+19. `mcpToolCallToArgv` with varargs positional: `args: { files: ["a","b"] }` (array) → unchanged behavior.
+20. `mcpToolCallToArgv` with varargs positional: `args: { files: "" }` (empty string) → no tokens appended.
+
+---
+
+## Step 8: Docs + changelog
+
+### [`README.md`](README.md)
+
+- Update `fallbackCommand` / `fallbackMode` table to note they work on any routing node.
+- Add `ctx.positional(name)` to the Reading values section.
+
+### [`docs/mcp.md`](docs/mcp.md)
+
+- Note MCP string→array coercion under tool arguments: agents may pass a comma-separated string for varargs positionals.
+
+### [`CHANGELOG.md`](CHANGELOG.md) — `[Unreleased]` → Added / Fixed
+
+**Added:**
+- `fallbackCommand` / `fallbackMode` now work on any routing node, not just the program root
+- `ctx.positional(name)` — named positional lookup; varargs return `string[]`, single slots return `string | undefined`
+- MCP varargs coercion: agents may pass `"a,b"` or `"a"` where `string[]` is expected
+
+**Fixed:**
+- Known options (`--flag`) after varargs positionals now parse correctly instead of being consumed as positional tokens
+
+### Typegen
+
+```
+just typegen
+```
+
+Verify `index.d.ts` reflects the new `positional` method on `CliContext`. No other new public types in this release.
+
+---
+
+## Pitfalls (do NOT)
+
+- Change `inputSchema` for varargs from `array` to `oneOf` — coercion is silent, schema stays canonical
+- Remove `ctx.args` — additive only; existing handlers must continue to work
+- Apply nested fallback logic before the existing root fallback — the root-level fallback code (lines 406–452 in `parse.ts`) stays as-is; the new code mirrors it in the routing loop body
+- Use `lenientUnknown: true` in the varargs interleaved option scan — unknown flags in varargs tails must still error
+- Break `allowsTrailingOptions` callers before deleting it — verify it has only one call site (line 308) before removing
+
+---
+
+## File change summary
+
+| File | Action |
+|------|--------|
+| [`src/types.ts`](src/types.ts) | JSDoc updates only |
+| [`src/validate.ts`](src/validate.ts) | Remove root-only fallback restriction; add child-key validation for all routing nodes |
+| [`src/parse.ts`](src/parse.ts) | Nested fallback in routing loop; varargs interleaved option scan; remove `allowsTrailingOptions` |
+| [`src/context.ts`](src/context.ts) | `positional(name)` accessor + `_positionalMap` private helper |
+| [`src/mcp/tools.ts`](src/mcp/tools.ts) | String→array coercion in `mcpToolCallToArgv` |
+| [`src/index.test.ts`](src/index.test.ts) | All new tests |
+| [`README.md`](README.md) | fallback + ctx.positional docs |
+| [`docs/mcp.md`](docs/mcp.md) | MCP coercion note |
+| [`CHANGELOG.md`](CHANGELOG.md) | Unreleased entries |
+| [`index.d.ts`](index.d.ts) | Regenerated via `just typegen` |
+
+---
+
+## Out of scope (explicitly deferred)
+
+- `ctx.positional` type overloads by argMax — return type is `string | string[] | undefined` for all slots; narrowing by schema type is possible but requires conditional types and adds complexity without clear benefit
+- `mcpTool.group` / `risk` / `requiresTty` annotations
+- `structuredError` for JSON on exit(1)
+- Streaming tool calls
+- Shared option groups / `extends`
+- Output truncation in MCP results
+- GNU-style option parsing before command routing (options mixed with subcommand tokens at root level)

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.2] - 2026-06-19
+
+### Added
+
+- **`fallbackCommand` / `fallbackMode` on any routing node** — nested routers can define default subcommand routing, not just the program root.
+- **`ctx.positional(name)`** — named positional lookup; varargs return `string[]`, single slots return `string | undefined`.
+- **MCP varargs coercion** — agents may pass `"a,b"` or `"a"` where `string[]` is expected.
+
+### Fixed
+
+- **Known options after varargs positionals** — `--flag` tokens after a varargs tail parse as options instead of being consumed as positional arguments.
+
 ## [1.4.1] - 2026-06-19
 
 ### Added
@@ -111,7 +123,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.4.1...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v1.4.2...HEAD
+[1.4.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.4.2
 [1.4.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.4.1
 [1.4.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.4.0
 [1.3.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.3.1

package/README.md

@@ -132,7 +132,7 @@ bun add bun-argsbarg
 
 ## How it works
 
-1. Build a **program root** `CliCommand` using pure TypeScript objects: `key` is the app/binary name, `commands` are top-level subcommands, `options` are global flags. The root must not set `handler` or declare `positionals` (validated at startup). Use `fallbackCommand` / `fallbackMode` on the root only for default top-level routing.
+1. Build a **program root** `CliCommand` using pure TypeScript objects: `key` is the app/binary name, `commands` are top-level subcommands, `options` are global flags. The root must not set `handler` or declare `positionals` (validated at startup). Use `fallbackCommand` / `fallbackMode` on any **routing node** for default subcommand routing (not root-only).
 2. Call `await cliRun(root)` with that root — validates, parses argv, renders help or errors, invokes the leaf handler, and `process.exit`s with status **0** on success, **1** on implicit help or error (explicit `--help` → **0**).
 3. From a handler, `cliErrWithHelp(ctx, "message")` prints a red error line plus contextual help on stderr and exits **1**.
 
@@ -144,7 +144,9 @@ bun add bun-argsbarg
 | `MissingOrUnknown` | Default command | Default command (token becomes argv for the default) |
 | `UnknownOnly` | Root help (exit 1) | Default command |
 
-With `MissingOrUnknown` / `UnknownOnly`, unrecognized **root** flags stop root-flag consumption and the remainder is passed to the default command.
+With `MissingOrUnknown` / `UnknownOnly`, unrecognized flags at the **current routing node** stop option consumption and the remainder is passed to the default command.
+
+Set `fallbackCommand` / `fallbackMode` on nested routers too — e.g. `docs` with `fallbackCommand: "guide"` routes `myapp docs` to the guide leaf without requiring a root-level default.
 
 ### Positionals (help labels)
 
@@ -163,6 +165,7 @@ Add `CliPositional` entries to the command’s `positionals` list (separate from
 - `ctx.stringOpt("name")` / `ctx.numberOpt("count")` — `string | undefined` / `number | null`.
 - `ctx.typedOpt<T>("custom", parseFn)` — pass a custom parsing function for type-safe option resolution.
 - `ctx.args` — positional words in order as `string[]`.
+- `ctx.positional("name")` — named positional lookup; varargs slots return `string[]`, single slots return `string | undefined`.
 - `ctx.schema` — merged program root (`CliCommand`) for contextual help.
 
 

package/docs/mcp.md

@@ -138,7 +138,7 @@ mcpTool: {
 Each tool’s `inputSchema` is a JSON Schema object built from your CLI definition:
 
 - **Options** — parent-scoped flags are included (e.g. `stat`’s `--json` appears on `stat_owner_lookup`). Presence options are `boolean`; string, number, and **enum** options match their `CliOptionKind` (`Enum` uses JSON Schema `enum`). Required options are listed in `required`.
-- **Positionals** — one property per `CliPositional` on the leaf. Single-slot positionals are `string`; varargs tails (`argMax: 0`) are `string[]`. Required positionals are listed in `required`.
+- **Positionals** — one property per `CliPositional` on the leaf. Single-slot positionals are `string`; varargs tails (`argMax: 0`) are `string[]`. Required positionals are listed in `required`. For varargs, agents may also pass a comma-separated string (`"a,b"`) or a single string (`"a"`) — both are coerced to separate argv tokens at dispatch time.
 
 Arguments are a **flat JSON object** keyed by option and positional names (same names as in your schema, including hyphenated option names like `"user-name"`).
 

package/index.d.ts

@@ -23,6 +23,10 @@ export declare class CliContext {
 	 * This is the TypeScript-native advantage over the Swift version.
 	 */
 	typedOpt<T>(name: string, parse: (s: string) => T): T | null;
+	/** Returns the value(s) for a named positional slot. Varargs slots return string[]; single slots return string | undefined. */
+	positional(name: string): string | string[] | undefined;
+	private _posMap;
+	private _positionalMap;
 }
 /**
  * How a leaf handler was dispatched.
@@ -42,21 +46,20 @@ export declare enum CliOptionKind {
 	Enum = "enum"
 }
 /**
- * When fallbackCommand is used for missing or unknown top-level tokens.
- * Only the program root may set a non-default mode or a non-nil fallbackCommand.
+ * When `fallbackCommand` is used for missing or unknown subcommand tokens at a routing node.
  */
 export declare enum CliFallbackMode {
 	/**
-	 * If argv has no first subcommand, route to `fallbackCommand`; if the first token is unknown, error.
+	 * If argv has no next subcommand, route to `fallbackCommand`; if the token is unknown, error.
 	 */
 	MissingOnly = "missingOnly",
 	/**
-	 * If argv has no first subcommand or the first token is not a known child, route to `fallbackCommand`.
+	 * If argv has no next subcommand or the token is not a known child, route to `fallbackCommand`.
 	 */
 	MissingOrUnknown = "missingOrUnknown",
 	/**
-	 * If the first token is present but not a known child, route to `fallbackCommand`.
-	 * When the first subcommand token is missing (empty argv), do not use fallback (implicit root help).
+	 * If the next token is present but not a known child, route to `fallbackCommand`.
+	 * When the subcommand token is missing (exhausted argv), do not use fallback (implicit scoped help).
 	 */
 	UnknownOnly = "unknownOnly"
 }
@@ -192,16 +195,16 @@ export type CliCommand = (CliCommandBase & {
 	positionals?: CliPositional[];
 	/** Nested subcommands (empty for leaf commands). */
 	commands?: never;
-	/** Default top-level subcommand (routing commands only). */
+	/** Default subcommand (routing commands only). */
 	fallbackCommand?: never;
-	/** How fallbackCommand is applied (routing commands only). */
+	/** How fallbackCommand is applied at this routing node (routing commands only). */
 	fallbackMode?: never;
 }) | (CliCommandBase & {
 	/** Nested subcommands. */
 	commands: CliCommand[];
-	/** Default top-level subcommand when argv omits a command or uses an unknown first token. */
+	/** Default subcommand when argv omits a command or uses an unknown token at this routing node. */
 	fallbackCommand?: string;
-	/** How fallbackCommand is applied. */
+	/** How fallbackCommand is applied at this routing node (not root-only). */
 	fallbackMode?: CliFallbackMode;
 	/** Handler function (leaf commands only). */
 	handler?: never;

package/package.json

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

package/src/context.ts

@@ -68,4 +68,42 @@ export class CliContext {
       return null;
     }
   }
+
+  /** Returns the value(s) for a named positional slot. Varargs slots return string[]; single slots return string | undefined. */
+  positional(name: string): string | string[] | undefined {
+    return this._positionalMap()[name];
+  }
+
+  private _posMap: Record<string, string | string[]> | undefined;
+
+  private _positionalMap(): Record<string, string | string[]> {
+    if (this._posMap) return this._posMap;
+
+    let node: CliCommand = this.schema;
+    for (const seg of this.commandPath) {
+      const child = (node.commands ?? []).find((c) => c.key === seg);
+      if (!child) {
+        this._posMap = {};
+        return {};
+      }
+      node = child;
+    }
+
+    const map: Record<string, string | string[]> = {};
+    let argIdx = 0;
+    for (const p of node.positionals ?? []) {
+      const { argMax = 1 } = p;
+      if (argMax === 0) {
+        map[p.name] = this.args.slice(argIdx);
+        argIdx = this.args.length;
+      } else {
+        const val = this.args[argIdx];
+        if (val !== undefined) map[p.name] = val;
+        argIdx++;
+      }
+    }
+
+    this._posMap = map;
+    return map;
+  }
 }

package/src/index.test.ts

@@ -334,7 +334,7 @@ test("trailing options include parent-scoped flags", () => {
   expect(pr.opts["json"]).toBe("1");
 });
 
-test("varargs tail does not parse trailing options", () => {
+test("varargs tail parses trailing options", () => {
   const root: CliCommand = {
     key: "app",
     description: "",
@@ -365,8 +365,8 @@ test("varargs tail does not parse trailing options", () => {
   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();
+  expect(pr.args).toEqual(["./file"]);
+  expect(pr.opts["json"]).toBe("1");
 });
 
 test("stops parsing options at --", () => {
@@ -1330,4 +1330,308 @@ test("MCP envFile loads vars for tool handlers", async () => {
   const res = responses.get(15) as { result: { isError: boolean; content: { text: string }[] } };
   expect(res.result.isError).toBe(false);
   expect(res.result.content[0]!.text.trim()).toBe("file-value");
+});
+
+// ── v1.3 parser ergonomics ────────────────────────────────────────────────────
+
+function varargsReadFixture(): CliCommand {
+  return {
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "read",
+        description: "Read files.",
+        options: [
+          {
+            name: "json",
+            description: "",
+            kind: CliOptionKind.Presence,
+          },
+        ],
+        positionals: [
+          {
+            name: "files",
+            description: "",
+            kind: CliOptionKind.String,
+            argMin: 0,
+            argMax: 0,
+          },
+        ],
+        handler: () => {},
+      },
+    ],
+  };
+}
+
+function nestedDocsFallbackFixture(): CliCommand {
+  return {
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "docs",
+        description: "Documentation commands.",
+        fallbackCommand: "guide",
+        fallbackMode: CliFallbackMode.MissingOnly,
+        commands: [
+          {
+            key: "guide",
+            description: "User guide.",
+            handler: () => {},
+          },
+          {
+            key: "api",
+            description: "API reference.",
+            handler: () => {},
+          },
+        ],
+      },
+    ],
+  };
+}
+
+test("nested fallback routes to default when argv exhausted at router", () => {
+  const root = nestedDocsFallbackFixture();
+  cliValidateRoot(root);
+  const pr = postParseValidate(root, parse(root, ["docs"]));
+  expect(pr.kind).toBe(ParseKind.Ok);
+  expect(pr.path).toEqual(["docs", "guide"]);
+});
+
+test("nested fallback MissingOrUnknown routes unknown token to default", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "docs",
+        description: "Documentation commands.",
+        fallbackCommand: "guide",
+        fallbackMode: CliFallbackMode.MissingOrUnknown,
+        commands: [
+          {
+            key: "guide",
+            description: "User guide.",
+            positionals: [
+              {
+                name: "topic",
+                description: "",
+                kind: CliOptionKind.String,
+                argMin: 0,
+                argMax: 0,
+              },
+            ],
+            handler: () => {},
+          },
+          {
+            key: "api",
+            description: "API reference.",
+            handler: () => {},
+          },
+        ],
+      },
+    ],
+  };
+  cliValidateRoot(root);
+  const pr = postParseValidate(root, parse(root, ["docs", "extra-topic"]));
+  expect(pr.kind).toBe(ParseKind.Ok);
+  expect(pr.path).toEqual(["docs", "guide"]);
+  expect(pr.args).toEqual(["extra-topic"]);
+});
+
+test("nested fallback MissingOnly errors on unknown subcommand", () => {
+  const root = nestedDocsFallbackFixture();
+  cliValidateRoot(root);
+  const pr = parse(root, ["docs", "nope"]);
+  expect(pr.kind).toBe(ParseKind.Error);
+  expect(pr.errorMsg).toContain("Unknown subcommand");
+});
+
+test("cliValidateRoot rejects invalid nested fallbackCommand", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "docs",
+        description: "",
+        fallbackCommand: "missing",
+        commands: [
+          {
+            key: "guide",
+            description: "",
+            handler: () => {},
+          },
+        ],
+      },
+    ],
+  };
+  expect(() => cliValidateRoot(root)).toThrow(/fallbackCommand 'missing' is not a child of 'docs'/);
+});
+
+test("cliValidateRoot accepts nested fallbackCommand when child exists", () => {
+  const root = nestedDocsFallbackFixture();
+  expect(() => cliValidateRoot(root)).not.toThrow();
+});
+
+test("nested router scoped help does not route to fallback", () => {
+  const root = nestedDocsFallbackFixture();
+  cliValidateRoot(root);
+  const pr = parse(root, ["docs", "--help"]);
+  expect(pr.kind).toBe(ParseKind.Help);
+  expect(pr.helpPath).toEqual(["docs"]);
+  expect(pr.helpExplicit).toBe(true);
+  const help = cliHelpRender(root, pr.helpPath, false);
+  expect(help).toContain("api");
+  expect(help).toContain("guide");
+});
+
+test("varargs trailing option after positionals via cliInvoke", async () => {
+  const root = varargsReadFixture();
+  cliValidateRoot(root);
+  const pr = postParseValidate(root, parse(root, ["read", "file.txt", "--json"]));
+  expect(pr.kind).toBe(ParseKind.Ok);
+  expect(pr.args).toEqual(["file.txt"]);
+  expect(pr.opts["json"]).toBe("1");
+});
+
+test("varargs option before positionals", () => {
+  const root = varargsReadFixture();
+  cliValidateRoot(root);
+  const pr = postParseValidate(root, parse(root, ["read", "--json", "file.txt"]));
+  expect(pr.kind).toBe(ParseKind.Ok);
+  expect(pr.args).toEqual(["file.txt"]);
+  expect(pr.opts["json"]).toBe("1");
+});
+
+test("varargs multiple files then trailing option", () => {
+  const root = varargsReadFixture();
+  cliValidateRoot(root);
+  const pr = postParseValidate(root, parse(root, ["read", "a.txt", "b.txt", "--json"]));
+  expect(pr.kind).toBe(ParseKind.Ok);
+  expect(pr.args).toEqual(["a.txt", "b.txt"]);
+  expect(pr.opts["json"]).toBe("1");
+});
+
+test("varargs double dash forces positional", () => {
+  const root = varargsReadFixture();
+  cliValidateRoot(root);
+  const pr = postParseValidate(root, parse(root, ["read", "file.txt", "--", "--json"]));
+  expect(pr.kind).toBe(ParseKind.Ok);
+  expect(pr.args).toEqual(["file.txt", "--json"]);
+  expect(pr.opts["json"]).toBeUndefined();
+});
+
+test("varargs unknown flag errors", async () => {
+  const root = varargsReadFixture();
+  cliValidateRoot(root);
+  const result = await cliInvoke(root, ["read", "--unknown"]);
+  expect(result.kind).toBe("error");
+  expect(result.stderr).toContain("--unknown");
+});
+
+test("varargs scoped help in tail", () => {
+  const root = varargsReadFixture();
+  cliValidateRoot(root);
+  const pr = parse(root, ["read", "file.txt", "--help"]);
+  expect(pr.kind).toBe(ParseKind.Help);
+  expect(pr.helpPath).toContain("read");
+  expect(pr.helpExplicit).toBe(true);
+});
+
+test("ctx.positional returns single slot value", async () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "x",
+        description: "",
+        positionals: [{ name: "path", description: "", kind: CliOptionKind.String }],
+        handler: (ctx) => {
+          captured = ctx.positional("path");
+        },
+      },
+    ],
+  };
+  let captured: string | string[] | undefined;
+  cliValidateRoot(root);
+  await cliInvoke(root, ["x", "./file"]);
+  expect(captured).toBe("./file");
+});
+
+test("ctx.positional returns varargs array", async () => {
+  const root = varargsReadFixture();
+  let captured: string | string[] | undefined;
+  root.commands![0]!.handler = (ctx) => {
+    captured = ctx.positional("files");
+  };
+  cliValidateRoot(root);
+  await cliInvoke(root, ["read", "a.txt", "b.txt"]);
+  expect(captured).toEqual(["a.txt", "b.txt"]);
+});
+
+test("ctx.positional returns undefined for absent optional slot", async () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "x",
+        description: "",
+        positionals: [
+          { name: "opt", description: "", kind: CliOptionKind.String, argMin: 0, argMax: 1 },
+        ],
+        handler: (ctx) => {
+          captured = ctx.positional("opt");
+        },
+      },
+    ],
+  };
+  let captured: string | string[] | undefined;
+  cliValidateRoot(root);
+  await cliInvoke(root, ["x"]);
+  expect(captured).toBeUndefined();
+});
+
+test("ctx.positional varargs matches ctx.args", async () => {
+  const root = varargsReadFixture();
+  let positional: string | string[] | undefined;
+  let args: string[] = [];
+  root.commands![0]!.handler = (ctx) => {
+    positional = ctx.positional("files");
+    args = ctx.args;
+  };
+  cliValidateRoot(root);
+  await cliInvoke(root, ["read", "a.txt", "b.txt"]);
+  expect(positional).toEqual(args);
+});
+
+test("mcpToolCallToArgv coerces comma-separated string for varargs", () => {
+  const tools = collectMcpTools(nestedMcpFixture);
+  const read = tools.find((t) => t.name === "read")!;
+  const argv = mcpToolCallToArgv(nestedMcpFixture, read, { files: "a,b" });
+  expect(argv).toEqual(["read", "a", "b"]);
+});
+
+test("mcpToolCallToArgv coerces single string for varargs", () => {
+  const tools = collectMcpTools(nestedMcpFixture);
+  const read = tools.find((t) => t.name === "read")!;
+  const argv = mcpToolCallToArgv(nestedMcpFixture, read, { files: "a" });
+  expect(argv).toEqual(["read", "a"]);
+});
+
+test("mcpToolCallToArgv array varargs unchanged", () => {
+  const tools = collectMcpTools(nestedMcpFixture);
+  const read = tools.find((t) => t.name === "read")!;
+  const argv = mcpToolCallToArgv(nestedMcpFixture, read, { files: ["a", "b"] });
+  expect(argv).toEqual(["read", "a", "b"]);
+});
+
+test("mcpToolCallToArgv empty string varargs appends nothing", () => {
+  const tools = collectMcpTools(nestedMcpFixture);
+  const read = tools.find((t) => t.name === "read")!;
+  const argv = mcpToolCallToArgv(nestedMcpFixture, read, { files: "" });
+  expect(argv).toEqual(["read"]);
 });

package/src/mcp/tools.ts

@@ -232,12 +232,20 @@ export function mcpToolCallToArgv(
     const { argMin = 1, argMax = 1 } = p;
 
     if (argMax === 0) {
-      if (!Array.isArray(val)) {
-        return { error: `Missing argument: ${p.name}` };
-      }
-      for (const item of val) {
-        argv.push(String(item));
+      const raw = args[p.name];
+      let items: string[];
+      if (Array.isArray(raw)) {
+        items = raw.map(String);
+      } else if (typeof raw === "string") {
+        items = raw.includes(",")
+          ? raw.split(",").map((s) => s.trim()).filter(Boolean)
+          : raw.trim()
+            ? [raw.trim()]
+            : [];
+      } else {
+        items = [];
       }
+      argv.push(...items);
       continue;
     }
 

package/src/parse.ts

@@ -231,11 +231,6 @@ export function collectOptionDefs(root: CliCommand, path: string[]): CliOption[]
   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,
@@ -244,7 +239,7 @@ function finishLeaf(
   path: string[],
   opts: Record<string, string>,
   optionDefs: CliOption[],
-  forcePositionals: boolean,
+  forcePositionalsIn: boolean,
 ): ParseResult {
   /** Builds a parse error for positional consumption failures. */
   function errorResult(msg: string): ParseResult {
@@ -263,6 +258,7 @@ function finishLeaf(
 
   let idx = startIdx;
   const args: string[] = [];
+  let forcePositionals = forcePositionalsIn;
 
   for (const p of node.positionals ?? []) {
     const { argMin = 1, argMax = 1 } = p;
@@ -288,9 +284,37 @@ function finishLeaf(
     let count = 0;
     if (argMax === 0) {
       while (idx < argv.length) {
-        args.push(argv[idx]);
-        idx += 1;
-        count += 1;
+        const tok = argv[idx];
+
+        if (!forcePositionals && tok === "--") {
+          forcePositionals = true;
+          idx++;
+          continue;
+        }
+
+        if (!forcePositionals && isHelpTok(tok)) {
+          return helpResult(path, true);
+        }
+
+        if (!forcePositionals && tok.startsWith("-")) {
+          // MUST be false — lenient mode swallows unknown flags as positionals silently
+          const tailRep = consumeOptions(optionDefs, false, argv, idx, opts);
+          if (tailRep.report.err) {
+            return errorResult(tailRep.report.err);
+          }
+          if (tailRep.report.sawDoubleDash) {
+            forcePositionals = true;
+          }
+          if (tailRep.nextIndex > idx) {
+            idx = tailRep.nextIndex;
+            continue;
+          }
+          return errorResult(`Unexpected option token: ${tok}`);
+        }
+
+        args.push(tok);
+        idx++;
+        count++;
       }
     } else {
       while (count < argMax && idx < argv.length) {
@@ -305,7 +329,7 @@ function finishLeaf(
   }
 
   if (idx < argv.length) {
-    if (forcePositionals || !allowsTrailingOptions(node.positionals)) {
+    if (forcePositionals) {
       return errorResult("Unexpected extra arguments");
     }
 
@@ -483,6 +507,19 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
 
     if (i >= argv.length) {
       if ((current.commands ?? []).length > 0) {
+        const fb = current.fallbackCommand;
+        const fm = current.fallbackMode ?? CliFallbackMode.MissingOnly;
+        if (
+          fb !== undefined &&
+          (fm === CliFallbackMode.MissingOnly || fm === CliFallbackMode.MissingOrUnknown)
+        ) {
+          const fbNode = findChild(current.commands ?? [], fb);
+          if (fbNode) {
+            path.push(fb);
+            current = fbNode;
+            continue;
+          }
+        }
         return helpResult(path, false);
       }
       return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals);
@@ -513,6 +550,21 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
     }
 
     if ((current.commands ?? []).length > 0) {
+      const fb = current.fallbackCommand;
+      const fm = current.fallbackMode ?? CliFallbackMode.MissingOnly;
+      const canRouteUnknown =
+        fb !== undefined &&
+        (fm === CliFallbackMode.MissingOrUnknown || fm === CliFallbackMode.UnknownOnly);
+
+      if (canRouteUnknown) {
+        const fbNode = findChild(current.commands ?? [], fb!);
+        if (fbNode) {
+          path.push(fb!);
+          current = fbNode;
+          continue;
+        }
+      }
+
       return {
         kind: ParseKind.Error,
         path,

package/src/types.ts

@@ -28,21 +28,20 @@ export enum CliOptionKind {
 }
 
 /**
- * When fallbackCommand is used for missing or unknown top-level tokens.
- * Only the program root may set a non-default mode or a non-nil fallbackCommand.
+ * When `fallbackCommand` is used for missing or unknown subcommand tokens at a routing node.
  */
 export enum CliFallbackMode {
   /**
-   * If argv has no first subcommand, route to `fallbackCommand`; if the first token is unknown, error.
+   * If argv has no next subcommand, route to `fallbackCommand`; if the token is unknown, error.
    */
   MissingOnly = "missingOnly",
   /**
-   * If argv has no first subcommand or the first token is not a known child, route to `fallbackCommand`.
+   * If argv has no next subcommand or the token is not a known child, route to `fallbackCommand`.
    */
   MissingOrUnknown = "missingOrUnknown",
   /**
-   * If the first token is present but not a known child, route to `fallbackCommand`.
-   * When the first subcommand token is missing (empty argv), do not use fallback (implicit root help).
+   * If the next token is present but not a known child, route to `fallbackCommand`.
+   * When the subcommand token is missing (exhausted argv), do not use fallback (implicit scoped help).
    */
   UnknownOnly = "unknownOnly",
 }
@@ -186,17 +185,17 @@ export type CliCommand =
       positionals?: CliPositional[];
       /** Nested subcommands (empty for leaf commands). */
       commands?: never;
-      /** Default top-level subcommand (routing commands only). */
+      /** Default subcommand (routing commands only). */
       fallbackCommand?: never;
-      /** How fallbackCommand is applied (routing commands only). */
+      /** How fallbackCommand is applied at this routing node (routing commands only). */
       fallbackMode?: never;
     })
   | (CliCommandBase & {
       /** Nested subcommands. */
       commands: CliCommand[];
-      /** Default top-level subcommand when argv omits a command or uses an unknown first token. */
+      /** Default subcommand when argv omits a command or uses an unknown token at this routing node. */
       fallbackCommand?: string;
-      /** How fallbackCommand is applied. */
+      /** How fallbackCommand is applied at this routing node (not root-only). */
       fallbackMode?: CliFallbackMode;
       /** Handler function (leaf commands only). */
       handler?: never;

package/src/validate.ts

@@ -35,22 +35,6 @@ export function cliValidateRoot(root: CliCommand): void {
 
 /** Recursively validates a command node: handlers vs children, options, and positionals. */
 function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
-  // Fallback only on root
-  if (!isRoot && cmd.fallbackCommand !== undefined) {
-    throw new CliSchemaValidationError(
-      "Fallback is only supported on the program root (not on " + cmd.key + ")",
-    );
-  }
-  if (
-    !isRoot &&
-    cmd.fallbackMode !== undefined &&
-    cmd.fallbackMode !== CliFallbackMode.MissingOnly
-  ) {
-    throw new CliSchemaValidationError(
-      "fallbackMode may only be set on the program root (not on " + cmd.key + ")",
-    );
-  }
-
   if (!isRoot && cmd.mcpServer !== undefined) {
     throw new CliSchemaValidationError(
       "mcpServer is only supported on the program root (not on " + cmd.key + ")",
@@ -89,6 +73,22 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
     seenNames.add(child.key);
   }
 
+  if (cmd.fallbackMode !== undefined && cmd.fallbackCommand === undefined) {
+    throw new CliSchemaValidationError(
+      `fallbackMode requires fallbackCommand on '${cmd.key}'`,
+    );
+  }
+
+  if (cmd.fallbackCommand !== undefined) {
+    const children = cmd.commands ?? [];
+    const valid = children.find((c) => c.key === cmd.fallbackCommand);
+    if (!valid) {
+      throw new CliSchemaValidationError(
+        `fallbackCommand '${cmd.fallbackCommand}' is not a child of '${cmd.key}'`,
+      );
+    }
+  }
+
   // Validate options (short name uniqueness, reserved -h, required presence)
   const seenShorts = new Set<string>();
   for (const opt of cmd.options ?? []) {