argsbarg 0.1.0

package/.cursor/rules/code.mdc

@@ -0,0 +1,9 @@
+---
+description: Code quality and style rules for TypeScript files
+globs: **/*.ts
+---
+
+# TypeScript Coding Standards
+
+- 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.

package/README.md

@@ -0,0 +1,188 @@
+![Logo](logo.png)
+<!-- Big money NE - https://patorjk.com/software/taag/#p=testall&f=Bulbhead&t=shebangsy&x=none&v=4&h=4&w=80&we=false> -->
+
+[![GitHub](https://img.shields.io/badge/GitHub-bdombro%2Fbun--argsbarg-181717?logo=github)](https://github.com/bdombro/bun-argsbarg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/bun-argsbarg.svg)](https://www.npmjs.com/package/argsbarg)
+[![Bun](https://img.shields.io/badge/Bun-%23000000.svg?logo=bun&logoColor=white)](https://bun.sh)
+
+Build beautiful, well-behaved CLI apps with Bun — **no third-party runtime dependencies**. 
+
+Why another CLI parser?
+
+*Schema-first* -- define your entire CLI’s structure, commands, options, and help in a single, explicit data model, making the command-line interface centralized, clear, and self-describing upfront.
+
+*Bun-optimized* -- built from the ground up for Bun and TypeScript, leveraging Bun’s performance and modern JavaScript features without any extra dependencies.
+
+Also checkout ArgsBarg for [cpp](https://github.com/bdombro/cpp-argsbarg), [nim](https://github.com/bdombro/nim-argsbarg), and [swift](https://github.com/bdombro/swift-argsbarg)!
+
+Halps! -->
+![help-preview.png](docs/help-preview.png)
+
+Sub-level Halps! -->
+![help-l2-preview.png](docs/help-l2-preview.png)
+
+Shell completions! -->
+![completions-preview.png](docs/completions-preview.png)
+
+
+## Usage
+
+```typescript
+import { cliRun, CliCommand, createOption, CliOptionKind, CliFallbackMode } from "argsbarg";
+
+const cli: CliCommand = {
+  key: "helloapp",
+  description: "Tiny demo.",
+  children: [
+    {
+      key: "hello",
+      description: "Say hello.",
+      options: [
+        createOption("name", "Who to greet.", {
+          kind: CliOptionKind.String,
+          shortName: "n",
+        }),
+        createOption("verbose", "Enable extra logging.", {
+          shortName: "v",
+        }),
+      ],
+      handler: async (ctx) => {
+        const name = ctx.stringOpt("name") ?? "world";
+        if (ctx.flag("verbose")) { 
+          console.log("verbose mode"); 
+        }
+        console.log(`hello ${name}`);
+      },
+    },
+  ],
+  fallbackCommand: "hello",
+  fallbackMode: CliFallbackMode.MissingOrUnknown,
+};
+
+await cliRun(cli);
+```
+
+`cliRun` parses `process.argv`, prints help or errors, dispatches the leaf handler, and **exits the process**.
+
+
+
+## What is it?
+
+Everything you need for a first-class CLI:
+
+- **Nested subcommands** (`CliCommand` with `children` for groups, `handler` for leaves)
+- **POSIX-style options** (`-x`, `--long`, `--long=value`)
+- **Bundled presence flags** (`-abc`)
+- **Positional arguments and varargs tails** (`CliOptionDef` with `positional: true`)
+- **Scoped help** at any routing depth (`-h` / `--help`)
+- **Default-command fallback** (`CliFallbackMode`)
+- **Option separator** (`--` to stop option parsing)
+- **Rich help**: rounded UTF-8 boxes, tables, terminal width detection (`process.stdout.columns`), colors when stdout/stderr is a TTY
+- **TypeScript-native**: Typed option accessors (`ctx.typedOpt<T>`) and `async/await` handler support.
+
+
+
+## Built-ins
+
+Every app gets:
+
+- `-h` / `--help` at any routing depth (scoped help).
+- **`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.
+
+
+### Shell completions
+
+```bash
+myapp completion bash > ~/.bash_completion.d/myapp
+# or: source <(myapp completion bash)
+
+myapp completion zsh > ~/.zsh/completions/_myapp   
+# then: fpath+=(~/.zsh/completions); autoload -Uz compinit && compinit
+# or, for a one-off test in the current shell: eval "$(myapp completion zsh)"
+```
+
+
+
+## Install
+
+```bash
+bun add bun-argsbarg
+```
+
+
+## How it works
+
+1. Build a **program root** `CliCommand` using pure TypeScript objects: `key` is the app/binary name, `children` 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.
+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**.
+
+### Fallback modes (`CliFallbackMode`)
+
+| Mode | Empty argv | Unknown first token |
+| --- | --- | --- |
+| `MissingOnly` | Default command | Error |
+| `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.
+
+### Positionals (help labels)
+
+Use `createOption` with `positional: true`. With `argMax: 0`, the tail accepts at least `argMin` tokens and has no upper bound unless you set `argMax` > 0.
+
+| Fields | Label |
+| --- | --- |
+| `positional: true`, default `argMin`/`argMax` | `<n>` |
+| `positional: true`, `argMin: 0`, `argMax: 1` | `[n]` |
+| `positional: true`, `argMin: 0`, `argMax: 0` | `[n...]` |
+| `positional: true`, `argMin: 1`, `argMax: 0` | `<n...>` |
+
+### Reading values (`CliContext`)
+
+- `ctx.flag("verbose")` — presence options (`boolean`).
+- `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.schema` — merged program root (`CliCommand`) for contextual help.
+
+
+
+## Examples
+
+Check the `examples/` directory for full working scripts:
+
+| Example | File | Shows |
+| --- | --- | --- |
+| `ArgsBargMinimal` | `examples/minimal.ts` | String + presence flags, `MissingOrUnknown` fallback. |
+| `ArgsBargNested` | `examples/nested.ts` | Nested `CliCommand` tree, positional tails, async handlers. |
+
+```bash
+bun examples/minimal.ts --help
+bun examples/minimal.ts hello --name world
+bun examples/nested.ts stat owner lookup -u alice ./README.md
+bun examples/nested.ts read ./README.md
+```
+
+
+
+## Public API overview
+
+| Symbol | Role |
+| --- | --- |
+| `CliCommand`, `CliOptionDef`, `CliOptionKind`, `CliFallbackMode` | Schema types. |
+| `createOption()` | Factory helper for options with sensible defaults. |
+| `CliContext`, `CliHandler` | Handler context and async-compatible closure type. |
+| `cliRun(root, [argv])` | Parse argv, dispatch, exit. |
+| `cliErrWithHelp(ctx, msg)` | Error + scoped help, exit 1. |
+| `cliHelpRender(schema, helpPath, useStderr)` | Render help (`schema` is the program root `CliCommand`). |
+
+Reserved identifier (validated at startup): root command **`completion`**.
+
+---
+
+## License
+
+MIT

package/biome.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.8.3/schema.json",
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "lineWidth": 100
+  }
+}

package/bun.lock

@@ -0,0 +1,21 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "bun-argsbarg",
+      "devDependencies": {
+        "@types/bun": "^1.3.12",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.12", "", { "dependencies": { "bun-types": "1.3.12" } }, "sha512-DBv81elK+/VSwXHDlnH3Qduw+KxkTIWi7TXkAeh24zpi5l0B2kUg9Ga3tb4nJaPcOFswflgi/yAvMVBPrxMB+A=="],
+
+    "@types/node": ["@types/node@25.6.0", "", { "dependencies": { "undici-types": "~7.19.0" } }, "sha512-+qIYRKdNYJwY3vRCZMdJbPLJAtGjQBudzZzdzwQYkEPQd+PJGixUL5QfvCLDaULoLv+RhT3LDkwEfKaAkgSmNQ=="],
+
+    "bun-types": ["bun-types@1.3.12", "", { "dependencies": { "@types/node": "*" } }, "sha512-HqOLj5PoFajAQciOMRiIZGNoKxDJSr6qigAttOX40vJuSp6DN/CxWp9s3C1Xwm4oH7ybueITwiaOcWXoYVoRkA=="],
+
+    "undici-types": ["undici-types@7.19.2", "", {}, "sha512-qYVnV5OEm2AW8cJMCpdV20CDyaN3g0AjDlOGf1OW4iaDEx8MwdtChUp4zu4H0VP3nDRF/8RKWH+IPp9uW0YGZg=="],
+  }
+}

package/examples/minimal.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env bun
+/*
+This example shows the smallest end-to-end CLI setup.
+It includes one command, a couple of options, and a direct call to the runtime so
+readers can copy the pattern into their own scripts quickly.
+
+It demonstrates the minimal Bun integration path.
+*/
+
+import { cliRun, CliCommand, createOption, CliOptionKind, CliFallbackMode } from "../src/index.ts";
+
+const cli: CliCommand = {
+  key: "minimal.ts",
+  description: "Tiny demo.",
+  children: [
+    {
+      key: "hello",
+      description: "Say hello.",
+      options: [
+        createOption("name", "Who to greet.", {
+          kind: CliOptionKind.String,
+          shortName: "n",
+        }),
+        createOption("verbose", "Enable extra logging.", {
+          shortName: "v",
+        }),
+      ],
+      handler: (ctx) => {
+        const name = ctx.stringOpt("name") ?? "world";
+        if (ctx.flag("verbose")) {
+          console.log("verbose mode");
+        }
+        console.log(`hello ${name}`);
+      },
+    },
+  ],
+  fallbackCommand: "hello",
+  fallbackMode: CliFallbackMode.MissingOrUnknown,
+};
+
+await cliRun(cli);

package/examples/nested.ts

@@ -0,0 +1,87 @@
+#!/usr/bin/env bun
+/*
+This example shows nested routing with groups and fallback behavior.
+It adds a deeper command tree so readers can see how grouped routing, leaf handlers,
+and fallback commands fit together in one schema.
+
+It demonstrates how the schema scales beyond one command.
+*/
+
+import { cliRun, CliCommand, createOption, CliOptionKind, CliFallbackMode } from "../src/index.ts";
+
+const cli: CliCommand = {
+  key: "nested.ts",
+  description: "Nested groups demo.",
+  children: [
+    {
+      key: "stat",
+      description: "File metadata.",
+      children: [
+        {
+          key: "owner",
+          description: "Ownership helpers.",
+          children: [
+            {
+              key: "lookup",
+              description: "Resolve owner info.",
+              options: [
+                createOption("user-name", "User to look up.", {
+                  kind: CliOptionKind.String,
+                  shortName: "u",
+                }),
+              ],
+              positionals: [
+                createOption("path", "File or directory.", {
+                  kind: CliOptionKind.String,
+                  positional: true,
+                }),
+              ],
+              handler: (ctx) => {
+                const user = ctx.stringOpt("user-name") ?? "?";
+                const path = ctx.args[0];
+                if (!path) {
+                  console.error("Missing path.");
+                  process.exit(1);
+                }
+                console.log(`lookup user=${user} path=${path}`);
+              },
+            },
+          ],
+        },
+      ],
+    },
+    {
+      key: "read",
+      description: "Print the first line of each file.",
+      notes: "Pass one or more file paths. {app} prints the first line of each.",
+      positionals: [
+        createOption("files", "Paths to read.", {
+          kind: CliOptionKind.String,
+          positional: true,
+          argMin: 1,
+          argMax: 0,
+        }),
+      ],
+      handler: async (ctx) => {
+        if (ctx.args.length === 0) {
+          console.error("Missing file path.");
+          process.exit(1);
+        }
+        for (const path of ctx.args) {
+          try {
+            const file = Bun.file(path);
+            const text = await file.text();
+            const firstLine = text.split("\n")[0];
+            console.log(`${path}: ${firstLine}`);
+          } catch (err) {
+            console.error(`Cannot open: ${path}`);
+          }
+        }
+      },
+    },
+  ],
+  fallbackCommand: "read",
+  fallbackMode: CliFallbackMode.MissingOrUnknown,
+};
+
+await cliRun(cli);

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "argsbarg",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "bin": {
+    "argsbarg": "./src/index.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun check-types && bun lint && bun test",
+    "dev": "bun --watch ./examples/minimal.ts",
+    "lint": "bun x biome check ./src",
+    "format": "bun x biome format ./src --write",
+    "check-types": "bun x tsc",
+    "release": "bun x npm publish"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.12"
+  }
+}

package/plan.md

@@ -0,0 +1,194 @@
+# bun-argsbarg Plan
+
+## Plan: bun-argsbarg — Bun CLI Argument Parser
+
+**TL;DR**: Convert the Swift `argsbarg` declarative CLI framework into a TypeScript/Bun library with the same CLI features (schema-driven parsing, help rendering, shell completion, subcommand routing, fallback commands) while leveraging TypeScript's type system for compile-time schema safety.
+
+## Current Status
+
+**Overall**: Phases 1–5 (95%) complete; Phases 6–8 in progress.
+
+### ✅ Completed
+
+- **Phase 1**: Core Schema Types (`src/types.ts`)
+  - `CliOptionKind` enum (Presence, String, Number)
+  - `CliFallbackMode` enum (MissingOnly, MissingOrUnknown, UnknownOnly)
+  - `CliCommand`, `CliOptionDef`, `CliHandler`, `CliContext` interfaces
+  - `CliSchemaValidationError` class
+  - Helper factories: `createOption()`, `createCommand()`
+
+- **Phase 2**: Argument Parser (`src/parse.ts`)
+  - `parse(root, argv)` with long/short options, bundling, equals syntax
+  - Option consumption logic with strict number validation
+  - Subcommand routing and positional argument collection
+  - Help token detection (`-h`, `--help`)
+  - `postParseValidate()` for strict option validation
+  - `cliValidateRoot()` for schema validation (root rules, child uniqueness, reserved names, positional ordering)
+  - Support for all fallback modes
+
+- **Phase 3**: Runtime Context (`src/context.ts`)
+  - `CliContext` class with typed accessors
+  - `flag(name)` — boolean presence check
+  - `stringOpt(name)` — string value or undefined
+  - `numberOpt(name)` — strict double parsing or null
+  - `typedOpt<T>(name, parse)` — generic typed accessor (TypeScript advantage)
+
+- **Phase 4**: Help Rendering (`src/help.ts`)
+  - `cliHelpRender()` for formatted help output
+  - TTY-aware ANSI colors (red, aqua, gray, bold)
+  - Unicode box drawing (╭╮├┤╰╯)
+  - Terminal width detection (`process.stdout.columns`)
+  - Text wrapping with visible width calculation (strips ANSI)
+  - Help sections: usage box, options table, positionals table, subcommands table, notes box
+  - `cliOptionLabel()` for formatted option display
+
+- **Phase 5**: Shell Completion (`src/completion.ts`)
+  - `completionBashScript(schema)` — bash tab-completion generator
+  - `completionZshScript(schema)` — zsh tab-completion generator
+  - Scope walking for command tree traversal
+  - Option/command/positional matching logic for both shells
+
+### 🚧 In Progress
+
+- **Phase 6**: Main Entry Point (`src/index.ts`)
+  - **Status**: Placeholder `hello()` function remains
+  - **Needs**: Implement `cliRun(root: CliCommand): Promise<void>`
+    - Validate schema via `cliValidateRoot()`
+    - Auto-merge built-in `completion` command with `bash`/`zsh` subcommands
+    - Call `parse()` on `process.argv.slice(2)`
+    - Call `postParseValidate()`
+    - Handle `ParseKind.Help` → render via `cliHelpRender()` → exit(0)
+    - Handle `ParseKind.Error` → render red error + contextual help → exit(1)
+    - Route to handler function with `CliContext`
+    - Support async handlers with `await`
+
+- **Phase 7**: Examples & Tests (`src/index.test.ts`, `examples/`)
+  - **Status**: Only placeholder tests exist
+  - **Needs**: 
+    - Replace `src/index.test.ts` with comprehensive test suite covering:
+      - Option parsing (long, short, bundled, equals syntax)
+      - Help detection and rendering
+      - Subcommand routing and fallback modes
+      - Positional argument collection and arity validation
+      - Unknown options/commands
+      - Schema validation errors
+      - Async handler support
+      - Typed option accessors
+    - Create `examples/minimal.ts` — hello with `--name` and `--verbose`
+    - Create `examples/nested.ts` — nested subcommands with positionals (mirroring Swift examples)
+
+### ❌ Not Started
+
+- **Phase 8**: Project Polish
+  - Add `biome.json` for linting/formatting
+  - Add CLI binary entry point (`bin/argsbarg`)
+  - Create `README.md` with API docs and usage examples
+  - Update `package.json` scripts and bin entry
+  - Verify all verification steps pass
+
+## Next Immediate Steps
+
+1. Implement `cliRun()` in `src/index.ts`
+2. Rewrite `src/index.test.ts` with actual test coverage
+3. Create working examples in `examples/`
+4. Run `bun test` and verify all tests pass
+5. Run examples and verify output matches expectations
+
+**Steps**
+
+### Phase 1: Core Schema Types (types.ts)
+- Define TypeScript equivalents of Swift's `CliOptionKind`, `CliOption`, `CliCommand`, `CliFallbackMode`
+- Leverage TypeScript generics/union types for compile-time safety (e.g., typed option values instead of string-only)
+- Add `CliHandler` type as `(ctx: CliContext) => void | Promise<void>` (support async handlers)
+- Add `CliSchemaValidationError` enum/class
+- **Parallel with Phase 2**
+
+### Phase 2: Argument Parser (parse.ts)
+- Implement `parse(root: CliCommand, argv: string[]): ParseResult` — same logic as Swift
+  - Long options (`--name`, `--name=value`)
+  - Short options (`-n`, bundled `-abc`)
+  - Subcommand routing through nested `CliCommand` tree
+  - Positional argument collection with arity validation (argMin/argMax)
+  - Help token detection (`-h`/`--help`)
+  - Root-level `fallbackCommand`/`fallbackMode` support
+- Implement `postParseValidate()` — strict number validation, option key verification
+- Implement `cliValidateRoot()` — schema validation (no handler on routing nodes, no positionals on root, unique short names, reserved `-h`, etc.)
+- **Depends on Phase 1**
+
+### Phase 3: Context & Runtime (context.ts)
+- Implement `CliContext` class with typed accessors:
+  - `flag(name)` — boolean presence check
+  - `stringOpt(name)` — string value
+  - `numberOpt(name)` — strict double parse
+  - **TypeScript enhancement**: `typedOpt<T>(name, parseFn)` — generic typed accessor
+- Implement `cliErrWithHelp(ctx, msg)` — red error + contextual help on stderr
+- **Depends on Phase 1**
+
+### Phase 4: Help Rendering (help.ts)
+- Terminal-aware help with rounded box drawing (same Unicode box chars as Swift)
+- TTY detection (Node's `process.stdout.isTTY` instead of Swift's `isatty`)
+- Terminal width detection (`TIOCGWINSZ` via `ioctl` or fallback to `process.stdout.columns`)
+- ANSI color support (TTY-aware, same palette: red/green/aqua/gray/bold)
+- Help sections: Usage box, Options table, Arguments table, Subcommands table, Notes box
+- `cliHelpRender(schema, helpPath, useStderr)` — full help for root or nested command
+- **Depends on Phase 1**
+
+### Phase 5: Shell Completion (completion.ts)
+- `completionBashScript(schema)` — generate bash tab-completion script
+- `completionZshScript(schema)` — generate zsh tab-completion script
+- Same scope-walking algorithm as Swift (depth-first, per-node arrays)
+- **Depends on Phase 1**
+
+### Phase 6: Main Entry Point (index.ts)
+- `cliRun(root: CliCommand)` — orchestrates: validate → merge builtins → parse → validate → dispatch
+- Auto-merge `completion`/`bash`/`zsh` reserved commands
+- Exit code handling (0 for help/success, 1 for errors)
+- **Depends on Phases 2-5**
+
+### Phase 7: Examples & Tests
+- `examples/minimal.ts` — hello world with options (like Swift's Minimal example)
+- `examples/nested.ts` — deeply nested subcommands with positionals (like Swift's Nested example)
+- `src/index.test.ts` — comprehensive tests mirroring Swift's ParseTests
+  - Bundled short flags, long option equals, fallback modes
+  - Unknown command, implicit help, invalid number validation
+  - Completion script generation verification
+  - Schema validation (root handler, root positionals, nested fallback, reserved names)
+  - **TypeScript-specific**: async handler support, typed option accessors
+
+### Phase 8: Project Polish
+- Add `biome.json` config (lint/format)
+- Add `bin/` entry in `package.json` for CLI executable
+- Add `README.md` with API docs and usage examples
+- Update `package.json` scripts
+- **Parallel with Phase 7**
+
+**Relevant files**
+- `/Users/briandombrowski/dev/bdombro/bun-argsbarg/src/index.ts` — replace placeholder `hello()` with `cliRun` + schema types
+- `/Users/briandombrowski/dev/bdombro/bun-argsbarg/src/index.test.ts` — replace with comprehensive test suite
+- `/Users/briandombrowski/dev/bdombro/bun-argsbarg/package.json` — add bin entry, biome config, README
+- `/Users/briandombrowski/dev/bdombro/bun-argsbarg/tsconfig.json` — keep as-is (already correct for Bun)
+- `/Users/briandombrowski/dev/bdombro/bun-argsbarg/examples/local-check.ts` — replace with minimal/nested examples
+
+**Verification**
+1. `bun test` — all tests pass
+2. `bun ./examples/minimal.ts hello --name World --verbose` — outputs "hello World" with verbose mode
+3. `bun ./examples/minimal.ts hello --help` — shows formatted help with options table
+4. `bun ./examples/nested.ts stat owner lookup --user-name bob /etc/passwd` — outputs "lookup user=bob path=/etc/passwd"
+5. `bun ./examples/minimal.ts completion bash` — outputs valid bash completion script
+6. `bun ./examples/minimal.ts completion zsh` — outputs valid zsh completion script
+7. `bun lint` and `bun check-types` — no errors
+8. `bun ./examples/minimal.ts unknown-cmd` — shows fallback command help with red error
+
+**Decisions**
+- **Single-file vs multi-file**: Multi-file (types/parse/context/help/completion) to match Swift's modular structure and keep files manageable
+- **Typed options**: Add `typedOpt<T>(name, parse: (s: string) => T)` to leverage TypeScript's type system — this is the key TypeScript advantage over Swift's string-only approach
+- **Async handlers**: Support `async (ctx) => Promise<void>` handlers — Bun/Node advantage over Swift's synchronous-only
+- **TTY detection**: Use `process.stdout.isTTY` and `process.stdout.columns` (Node built-in) instead of `ioctl`/`isatty` FFI
+- **No runtime dependencies**: Keep zero runtime deps, only `@types/bun` as dev dep
+- **CLI binary**: Add `bin/argsbarg` entry point so the library can also be used as a CLI tool
+- **Schema validation**: Same rules as Swift — root can't have handler/positionals, no duplicate shorts, `-h` reserved, etc.
+
+**Further Considerations**
+1. Should we add a `@argsbarg()` decorator pattern for declarative schema definition (like Python's argparse decorators)? This would be a TypeScript-native enhancement.
+2. Should the CLI binary (`bin/argsbarg`) support loading schema from a config file (JSON/YAML) for dynamic CLIs?
+3. Error exit codes: Swift uses exit(1) for help (implicit) and exit(0) for explicit help. Should we match this or use more conventional exit codes?