argsbarg 3.6.0 → 3.6.2

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

@@ -1,455 +0,0 @@
----
-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/.cursor/rules/code.mdc

@@ -1,9 +0,0 @@
----
-description: Code quality and style rules for TypeScript files
-globs: **/*.ts
----
-
-- Changes must be summarized in CHANGELOG.md under the UNRELEASED section
-- All imports must be ordered alphabetically by their source module path (the `from` clause).
-- Explicit exports using the `export { ... } from "..."` or `export type { ... } from "..."` syntax must be ordered alphabetically by their source module path and placed at the top of the file, immediately below the imports.
-- Types, Interfaces, Functions must have a docstring

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

@@ -1,8 +0,0 @@
----
-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

@@ -1,13 +0,0 @@
-## 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

@@ -1,4 +0,0 @@
-- [x] --schema feature for ai agents
-- [x] opt-out install feature?
-- [x] outputSchema
-- [x] mcpb bundle

package/CLAUDE.md

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

package/biome.json

@@ -1,40 +0,0 @@
-{
-  "$schema": "https://biomejs.dev/schemas/2.5.0/schema.json",
-  "assist": { "actions": { "source": { "organizeImports": "on" } } },
-  "linter": {
-    "enabled": true,
-    "rules": {
-      "preset": "recommended"
-    }
-  },
-  "formatter": {
-    "enabled": true,
-    "indentStyle": "space",
-    "lineWidth": 100
-  },
-  "overrides": [
-    {
-      "includes": ["**/completion-bash.ts", "**/completion-zsh.ts"],
-      "linter": {
-        "rules": {
-          "suspicious": {
-            "noTemplateCurlyInString": "off"
-          }
-        }
-      }
-    },
-    {
-      "includes": ["**/*.test.ts"],
-      "linter": {
-        "rules": {
-          "style": {
-            "noNonNullAssertion": "off"
-          },
-          "suspicious": {
-            "noTemplateCurlyInString": "off"
-          }
-        }
-      }
-    }
-  ]
-}

package/bun.lock

@@ -1,43 +0,0 @@
-{
-  "lockfileVersion": 1,
-  "configVersion": 1,
-  "workspaces": {
-    "": {
-      "name": "argsbarg",
-      "devDependencies": {
-        "@biomejs/biome": "^2.5.0",
-        "@types/bun": "^1.3.12",
-        "typescript": "^5.9.3",
-      },
-    },
-  },
-  "packages": {
-    "@biomejs/biome": ["@biomejs/biome@2.5.0", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.5.0", "@biomejs/cli-darwin-x64": "2.5.0", "@biomejs/cli-linux-arm64": "2.5.0", "@biomejs/cli-linux-arm64-musl": "2.5.0", "@biomejs/cli-linux-x64": "2.5.0", "@biomejs/cli-linux-x64-musl": "2.5.0", "@biomejs/cli-win32-arm64": "2.5.0", "@biomejs/cli-win32-x64": "2.5.0" }, "bin": { "biome": "bin/biome" } }, "sha512-4kURkd9hAPrdDM3C9n82ycYgx8hvQcW6MjKTEejruj8rK0N8P3OPpdy8BvI8kt3KWY4ycF5XtDOrktetEfhfuw=="],
-
-    "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.5.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-Mn3Fwi3SA5fgmfCPqmzpWF2DLZnms3BVAhM088nTnGrTZmHS3wwIjcoZPqpXeNgd3DrrLH6xp8vTLIBuJoZiXw=="],
-
-    "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.5.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-rg3VPL5P8mYro6pqlXYXuJWph21slVp3SZtAqWSrkZs40d2gTzYmHF8E/X1iTID25btmNKltNDJ926sqVBp7DQ=="],
-
-    "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.5.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-tl+LW8fdD96/xdeWtWwc82LIOc5CoY7N2AsogLTp5R4ECErYt+8Jl/N68ezN9vzSiqPTxw6vjcihoLPYKZHrlw=="],
-
-    "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.5.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-vQdM4oSGaf7ZNeGO9w5+Y8SBtyser9M6znxYbm7Ec8wInxJu1WiKxFYZW5Auj2d80bcVvefuGGRxoFOE0eee8g=="],
-
-    "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.5.0", "", { "os": "linux", "cpu": "x64" }, "sha512-zpEGf4RQbFEh8Vt7OmavLyyOzRbtcE9osCqrS1kfvt8jDvxwhKXLSf7n0ebr/ov0RJ9ssP+lhs6C8a9WwFvrQA=="],
-
-    "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.5.0", "", { "os": "linux", "cpu": "x64" }, "sha512-+9hIcMngJ+yGUahXqZuZ8CoWKJE9SAZsFsM3QDvXpNsLbXZ9lqVzgBhOk/jTSYkOA0GLP9eu3teukqpLUojHMg=="],
-
-    "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.5.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-jB0wAvTLI4itx5VidqVUejPQFhRUxiZ9l9FvZ26D5fl6t3qme+ZB4PD3bTSeL1vZ8NI2Rx/zj6H9zcESuGHKGw=="],
-
-    "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.5.0", "", { "os": "win32", "cpu": "x64" }, "sha512-VT/lF+GId+67j8aDfLkxdxNoVApsPSTbyAtB3jJq0IWTrY77WXfbPfpngxq0bA6JCEv/7k8C9qWjDRKRznDlyw=="],
-
-    "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
-
-    "@types/node": ["@types/node@26.0.0", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-vf2YFi1iY9lHGwNJMs01biZFbKJkrZR1T6/MlzjhJLPdntOHLhTrDSnSVcdtvjihi4VQNlrFRIxLsDBlQpAipA=="],
-
-    "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
-
-    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
-
-    "undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],
-  }
-}

package/justfile

@@ -1,54 +0,0 @@
-# https://github.com/casey/just — run `just` to list recipes.
-
-set shell := ["bash", "-eu", "-o", "pipefail", "-c"]
-
-_:
-    @just --list
-
-# check the codebase
-check: typecheck format
-
-# Update local consumer apps: npm i argsbarg@latest, build, docgen
-consumers-sync *apps:
-    #!/usr/bin/env bash
-    root="$(cd "{{justfile_directory()}}" && pwd)"
-    ss="$root/../../ss"
-    apps=(idp-trees sqsp-qa-tools sqsp-i18n-tools)
-    for app in "${apps[@]}"; do
-      dir="$(cd "$ss/$app" && pwd)"
-      echo "==> $app ($dir)"
-      (cd "$dir" && bun i argsbarg@latest && just build && just docgen && just install)
-    done
-
-# run the minimal example
-example *ARGS:
-    bun ./examples/minimal.ts {{ARGS}}
-
-# run the minimal example and watch for changes
-example-watch *ARGS:
-    bun --watch ./examples/minimal.ts {{ARGS}}
-
-# format the codebase
-format:
-    bun run biome check ./src ./scripts --write
-
-# lint the codebase
-lint:
-    bun run biome check ./src ./scripts
-
-# Typecheck, lint, then run the test suite.
-test: check
-    bun test
-
-# typecheck the codebase
-typecheck:
-    bun run tsc --noEmit
-
-# generate type declarations for the package
-typegen:
-    bunx dts-bundle-generator --out-file index.d.ts src/index.ts
-
-# publish to github and npm
-release bump: test typegen
-    bun scripts/release.ts {{bump}}
-

package/plan.md

@@ -1,19 +0,0 @@
-# bun-argsbarg Plan
-
-## Current Status
-
-**Overall**: Core CLI, MCP, install, docs, and `install --update` are complete. Public API is stable at **3.x**.
-
-### Shipped
-
-- Schema-driven parsing, help, completions, subcommand routing, fallback commands
-- MCP server (`mcpServer: { enabled: true }`), `ctx.invocation`, `cliInvoke`
-- `install` built-in (`install --update` when `updateGetLatest` is set), agent skills, bundled `docs` (topics, schema, api, skill, mcp)
-- Headless helpers and `ghReleaseUpdateGetLatest` for GitHub release consumers
-
-### Consumers
-
-- **qa-cli** — argsbarg program with Ink UI; commands under `src/commands/`
-- **idp-trees** — argsbarg program with headless JSON ops; `cli/dispatch.ts` pattern
-
-See [README.md](README.md) and [CHANGELOG.md](CHANGELOG.md) for release history.