argsbarg 3.2.0 → 3.3.1

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.1] - 2026-06-21
+
+### Added
+
+- **`docs/cli-program.md`** — authoring guide for `CliProgram` and leaves (MCP-free defaults); **headless-capable handlers** and **inline schema by default**.
+- **`docs/templates/cursor/rules/cli-program.mdc`** — concise copy-paste Cursor rule for consumer apps.
+
+### Removed
+
+- **`mcpToolSchemaHints`** — redundant with MCP `inputSchema` option descriptions.
+- **`wantsDryRun`** — use `ctx.hasFlag("dry-run")` instead.
+
+## [3.3.0] - 2026-06-21
+
+### Added
+
+- **Headless helpers** — `shouldRunHeadless`, `shouldRunHeadlessWithPositionals`, `shouldRunHeadlessWithYes`, `wantsExplicitJson`, `requireYesInNonTty`, `formatDryRunMessage` for Ink/MCP CLIs.
+- **`ghReleaseUpdateGetLatest`** — optional `install.updateGetLatest` factory for GitHub releases via `gh`.
+- **`createGhVersionCheck`** — version-check cache, update notices, and background refresh helpers.
+
 ## [3.2.0] - 2026-06-20
 
 ### Added
@@ -223,7 +243,9 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - 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/v3.2.0...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.3.1...HEAD
+[3.3.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.1
+[3.3.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.0
 [3.2.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.2.0
 [3.1.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.1.0
 [3.0.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.0.0

package/README.md

@@ -110,7 +110,7 @@ When **`docs.enabled`** is `true`, do not declare a top-level command named **`d
 
 Opt in on the program root with `mcpServer: { enabled: true }`, then run `myapp mcp` for a stdio MCP server. Each leaf command becomes a tool; the CLI tree is available as resource `<sanitized-key>://schema` (same as `myapp docs schema`). Handlers can read `ctx.invocation` and use `cliInvoke` for headless testing.
 
-See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom resources, Cursor setup, and protocol details.
+See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom resources, Cursor setup, and protocol details. See **[docs/cli-program.md](docs/cli-program.md)** for schema authoring (consumer apps: copy **`docs/templates/cursor/rules/cli-program.mdc`** to **`.cursor/rules/cli-program.mdc`**).
 
 ### Install
 

package/docs/ai-skills.md

@@ -44,6 +44,8 @@ Skills describe **shell invocation only** — no MCP setup, `mcp.json`, or `tool
 | **`myapp install --skill`** | Static shell command catalog for agents |
 | **`myapp docs`** (requires `docs`) | Bundled markdown on stdout (`docs mcp` when MCP enabled) |
 
+Command catalog lines reuse MCP tool descriptions. See [cli-program.md](cli-program.md).
+
 See also:
 
 - [Bundled docs](bundled-docs.md) — `docs` config and compile-time imports

package/docs/bundled-docs.md

@@ -57,7 +57,7 @@ import readmeText from "../README.md" with { type: "text" };
 
 Bun embeds the file when you `bun build --compile`. ArgsBarg does not read the filesystem at runtime.
 
-For several topics, use a barrel file (e.g. `src/docs/topics.ts`) so `index.tsx` stays small.
+Inline topics in your program root when the set is small; use a separate module only if the import map grows enough to clutter `index.tsx`.
 
 ## Schema, API, and skill (`docs schema`, `docs api`, `docs skill`)
 

package/docs/cli-program.md

@@ -0,0 +1,194 @@
+# Writing `CliProgram` and leaf commands
+
+ArgsBarg turns your schema into help, shell completions, MCP tools, and agent skills. **The same `description` fields you write for humans are the agent contract** for basic apps.
+
+## Minimal app (MCP is free)
+
+```typescript
+const cli = {
+  key: "myapp",
+  version: "1.0.0",
+  description: "One-line summary of what the CLI does.",
+  mcpServer: { enabled: true },
+  commands: [
+    {
+      key: "greet",
+      description: "Greet someone by name.",
+      positionals: [
+        { name: "name", description: "Who to greet.", kind: CliOptionKind.String },
+      ],
+      handler: async (ctx) => { /* ... */ },
+    },
+  ],
+} satisfies CliProgram;
+```
+
+No `mcpTool` blocks required. Every leaf becomes an MCP tool; `inputSchema` comes from options and positionals.
+
+## Inline schema by default
+
+ArgsBarg is **schema-first** — the program tree is the product. **Keep `CliProgram` and leaf fields inline** (`key`, `description`, `options`, `positionals`, `handler`) so a reader sees the full command contract in one place.
+
+**Inline by default:**
+
+```typescript
+{
+  key: "reserve",
+  description: "Reserve a QA environment.",
+  options: [
+    { name: "yes", description: "Skip confirmation; use for non-interactive runs.", kind: CliOptionKind.Presence },
+    { name: "dry-run", description: "Preview without mutating.", kind: CliOptionKind.Presence },
+  ],
+  positionals: [
+    { name: "env", description: "Environment name.", kind: CliOptionKind.String, argMin: 0, argMax: 1 },
+  ],
+  handler: async (ctx) => { /* … */ },
+}
+```
+
+**Extract only when well justified:**
+
+| Extract | When |
+| --- | --- |
+| Shared option objects (`DRY_RUN_OPTION`, `JSON_OPTION`) | Identical flag reused on many leaves |
+| Shared spreads (`...MCP_TOOL_MUTATOR`) | Same `mcpTool` metadata on a family of commands |
+| `somethingCommand()` factory | Entry file is large; handler/body is substantial (Ink page, headless dispatch) |
+| `docs.topics` text imports | Compile-time markdown bundling — not schema shape |
+
+**Avoid extracting** thin indirection: a file that only re-exports `{ key, description, options }` with no logic, or splitting every leaf into its own module when the handler is a few lines. If extraction does not reduce duplication or file size materially, keep it inline.
+
+**`satisfies CliProgram`** on the root (or on extracted command factories) preserves type-checking whether inline or not.
+
+## Descriptions
+
+Write for **what the command does**, not how the UI works:
+
+- **Good:** `Reserve a QA environment.`
+- **Weak:** `Opens the reservation wizard.`
+
+Option and positional `description` strings appear in `-h`, MCP `inputSchema`, and generated skills — keep them concrete (`Environment name (e.g. qa2).`).
+
+Use root **`notes`** for cross-cutting hints shown in help (install commands, docs topics, VPN requirements).
+
+## Well-known option names
+
+Prefer **`yes`**, **`dry-run`**, and **`json`** when semantics match. They appear in `-h`, MCP `inputSchema`, and generated skills — write clear option `description` strings (e.g. "Skip confirmation; use for non-interactive runs.").
+
+## When to use `mcpTool` (escape hatches only)
+
+**Omit `mcpTool` unless you have a specific reason.**
+
+### Fix the CLI first
+
+Many "MCP problems" are schema or handler gaps. Prefer these over escape hatches:
+
+| Problem | Fix (not `mcpTool`) |
+| --- | --- |
+| Agents don't know which flags to pass | Use standard option names (`yes`, `dry-run`, `json`); improve option `description` strings |
+| MCP calls hang on prompts | Add `--yes` and a headless code path; use `shouldRunHeadlessWithYes` |
+| Help text describes Ink UI | Rewrite leaf `description` as the action ("Reserve an environment.") |
+| MCP needs different args than humans | Expose the same flags; resolve defaults in the handler for both `cli` and `mcp` |
+| Command "doesn't work" over MCP | Branch on `ctx.invocation === "mcp"` in the handler (stdio is the wire) |
+
+### When escape hatches are appropriate
+
+| Field | Use when |
+| --- | --- |
+| `enabled: false` | Command is **genuinely** CLI-only (open browser, Ink-only flow with no scriptable equivalent) |
+| `requiresEnv: [...]` | Runtime secrets; appended to MCP description and enforced at `tools/call` |
+| `description: "..."` | **Irreducible** MCP limitation (e.g. live tail / `--watch` cannot be streamed on the MCP wire yet) |
+
+Do **not** use `mcpTool.description` to paper over missing `--yes`, non-standard flag names, or handlers that only work interactively — fix those instead.
+
+If help text and MCP behavior match after your fixes, **omit `mcpTool` entirely**.
+
+## Headless-capable handlers
+
+Simple leaves (read args, print stdout) are already headless — no extra work. **Any handler that might mount Ink, prompt, or open a browser should also implement a scriptable fast path** for:
+
+- **MCP** (`ctx.invocation === "mcp"` — always non-interactive)
+- **Non-TTY CLI** (pipes, CI, `myapp cmd --yes` in a script)
+- **Explicit flags** (`--json`, `--dry-run`)
+
+Use **one headless implementation** for all three; do not fork separate "MCP handlers."
+
+### When to branch
+
+| Command kind | Headless trigger | Helpers |
+| --- | --- | --- |
+| Read / query | MCP, `--json`, or non-TTY | `shouldRunHeadless`, `wantsExplicitJson` |
+| Mutate | MCP with args + `yes`/`dry-run`, or non-TTY with `--yes` | `shouldRunHeadlessWithYes`, `requireYesInNonTty` |
+| Mutate with positionals | Same, but avoid auto-headless on empty argv | `shouldRunHeadlessWithPositionals` |
+
+### Recommended handler shape
+
+**Mutating command** (wizard optional, script path required):
+
+```typescript
+import {
+  requireYesInNonTty,
+  shouldRunHeadlessWithYes,
+} from "argsbarg";
+
+handler: async (ctx) => {
+  const dryRun = ctx.hasFlag("dry-run");
+  const yes = ctx.hasFlag("yes");
+  const env = ctx.args[0];
+
+  requireYesInNonTty(yes, "Example: myapp reserve qa2 --yes", dryRun);
+
+  if (shouldRunHeadlessWithYes(ctx, { yes, hasRequiredArgs: !!env, dryRun })) {
+    const result = await executeReserve({ dryRun, env, yes });
+    process.stdout.write(`${result.message}\n`);
+    return;
+  }
+
+  await renderInteractiveWizard({ env, yes, dryRun });
+};
+```
+
+**Read / query command** (optional `--json`):
+
+```typescript
+import { shouldRunHeadless, wantsExplicitJson } from "argsbarg";
+
+handler: async (ctx) => {
+  const json = ctx.hasFlag("json");
+
+  if (shouldRunHeadless(ctx, json)) {
+    const data = await fetchStatus(ctx.args[0]);
+    if (wantsExplicitJson(ctx, json)) {
+      process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    } else {
+      process.stdout.write(formatStatusHuman(data));
+    }
+    return;
+  }
+
+  await renderPage(<StatusPage env={ctx.args[0]} />);
+};
+```
+
+### Rules of thumb
+
+1. **Resolvable from flags** — if a human can complete the action with flags, an agent can too (`--env qa2 --yes`). Wizards are optional sugar on TTY.
+2. **`--yes` on mutators** — required for non-TTY CLI scripts; MCP should pass `yes: true` in tool arguments when the schema exposes `yes`.
+3. **Stdout is the contract** — headless paths write results to stdout (or JSON with `--json`); stderr for errors. No Ink on the MCP wire.
+4. **`ctx.invocation === "mcp"`** — use only for wire-specific behavior (pipe child stdout, reject `--watch`, etc.), not to duplicate business logic.
+5. **Hide only when impossible** — `mcpTool.enabled: false` after confirming no headless path exists (browser-only, irreducible streaming).
+
+Basic synchronous handlers do not need this structure — only commands with an interactive branch.
+
+## Reserved names
+
+Do not declare user commands named `completion`, `install`, `mcp`, `version`, `docs`, or `update` at the root — ArgsBarg injects these when configured.
+
+## Cursor rule for consumer repos
+
+Copy `node_modules/argsbarg/docs/templates/cursor/rules/cli-program.mdc` to `.cursor/rules/cli-program.mdc` so agents editing your CLI schema follow these conventions.
+
+## See also
+
+- [MCP server](mcp.md) — tools, schema resource, env bootstrapping
+- [Agent skills](ai-skills.md) — `install --skill`
+- [Bundled docs](bundled-docs.md) — `docs` topics and `docs mcp`

package/docs/install.md

@@ -54,6 +54,41 @@ install: {
 
 When `updateGetLatest` is set, ArgsBarg also registers the **`update`** built-in (`myapp update`).
 
+### GitHub releases (`ghReleaseUpdateGetLatest`)
+
+For compiled binaries published via `gh release`, wire a hook without hand-rolling download logic:
+
+```typescript
+import {
+  createGhFetchLatest,
+  createGhVersionCheck,
+  ghReleaseUpdateGetLatest,
+} from "argsbarg";
+
+const cachePath = path.join(configDir, "version-check.json");
+
+install: {
+  updateGetLatest: ghReleaseUpdateGetLatest({
+    repo: "owner/repo",
+    asset: "myapp",
+    tempPrefix: "myapp-update.",
+    cachePath,
+  }),
+}
+
+// Optional: summary notice + background refresh
+const versionCheck = createGhVersionCheck({
+  currentVersion: "1.0.0",
+  commandName: "myapp",
+  cachePath,
+  fetchLatest: createGhFetchLatest({ repo: "owner/repo" }),
+});
+versionCheck.getUpdateNotice();
+versionCheck.refreshIfStale();
+```
+
+Requires `gh` on PATH and `gh auth login`. Consumers keep app-specific config only (~15 lines).
+
 Environment:
 
 - `INSTALL_PREFIX` — same as `install.prefix` / `--prefix`

package/docs/mcp.md

@@ -103,9 +103,9 @@ Tool names are derived from the command path, with each segment sanitized (non-a
 
 ### Tool descriptions
 
-Each tool’s `description` includes the human CLI path and the leaf’s help text, separated by an em dash:
+Each tool’s `description` includes the human CLI path and the leaf’s help text, separated by an em dash. Tool arguments are defined in `inputSchema` (options and positionals with their descriptions). `mcpTool.requiresEnv` is appended as `[requires env: …]`.
 
-| CLI path | MCP `description` |
+| CLI path | MCP `description` (example) |
 | --- | --- |
 | `stat owner lookup` | `stat owner lookup — Resolve owner info.` |
 | `read` | `read — Print the first line of each file.` |
@@ -126,6 +126,8 @@ Set `mcpTool: { enabled: false }` on a **leaf command** to hide it from `tools/l
 
 Omitted or `enabled: true` exposes the command (default). `mcpTool` is only valid on leaves — not on the program root or routing groups.
 
+**Prefer fixing schema and handlers over `mcpTool` overrides** — standard option names (`yes`, `dry-run`, `json`), headless paths, and clear descriptions usually make MCP work without per-leaf config. See [cli-program.md](cli-program.md).
+
 ### Per-leaf tool metadata
 
 ```typescript
@@ -207,7 +209,9 @@ URIs must be unique and must not equal `schemaResourceUri`. `load()` runs synchr
 
 Handlers receive `ctx.invocation`: `"cli"` for normal `cliRun` dispatch, `"mcp"` for MCP `tools/call`.
 
-Use this to branch subprocess behavior — MCP stdout is the JSON-RPC wire, so child processes must not inherit it:
+MCP is always non-interactive. Commands that can mount Ink or prompts should implement a **headless fast path** (same path as non-TTY CLI with `--yes` / `--json`) — see [cli-program.md — Headless-capable handlers](cli-program.md#headless-capable-handlers).
+
+Use `ctx.invocation` to branch subprocess behavior — MCP stdout is the JSON-RPC wire, so child processes must not inherit it:
 
 ```typescript
 handler: async (ctx) => {

package/docs/templates/cursor/rules/cli-program.mdc

@@ -0,0 +1,29 @@
+---
+description: Argsbarg CliProgram authoring; copy to .cursor/rules/cli-program.mdc
+globs: "**/*.{ts,tsx}"
+alwaysApply: false
+---
+
+**argsbarg** — `CliProgram` drives help, MCP, and skills. Full guide: `node_modules/argsbarg/docs/cli-program.md`.
+
+## Defaults
+- `mcpServer: { enabled: true }` for MCP; **omit `mcpTool`** unless an escape hatch is required
+- `description` on root, commands, options, and positionals (→ `-h`, MCP `inputSchema`, skills)
+- `satisfies CliProgram`; root: `key`, `version`, `description`
+- Reserved root commands (do not declare): `completion`, `install`, `mcp`, `version`, `docs`, `update`
+
+## Schema
+- **Inline** options, positionals, and handler schema; extract only for shared flags, `mcpTool` spreads, or large handlers (Ink/dispatch)
+- Leaf descriptions: action-oriented, not UI jargon
+- Prefer option names `yes`, `dry-run`, `json` when semantics match; describe non-interactive use on the option
+
+## `mcpTool` (rare)
+Fix schema/handler first — not for missing `--yes`, wrong flag names, or unfinished headless paths.
+Only: `enabled: false` (CLI-only), `requiresEnv`, or irreducible limits (e.g. streaming `--watch`). Comment why if used.
+
+## Headless
+Interactive commands need one fast path for MCP, non-TTY CLI, and `--yes` / `--dry-run` / `--json`.
+- Mutators: `requireYesInNonTty`, `shouldRunHeadlessWithYes`
+- Queries: `shouldRunHeadless`, `wantsExplicitJson`
+- Varargs/positionals: `shouldRunHeadlessWithPositionals`
+- `ctx.invocation === "mcp"` only for subprocess/TTY wire behavior; use argsbarg headless helpers, not raw `isTTY`

package/examples/nested.ts

@@ -21,6 +21,9 @@ const cli = {
       readme: { text: "# nested.ts\n\nNested groups demo.\n" },
     },
   },
+  install: {
+    updateGetLatest: async () => ({ path: process.execPath, version: pkg.version }),
+  },
   commands: [
     {
       key: "stat",

package/index.d.ts

@@ -305,5 +305,78 @@ export declare function cliRun(program: CliProgram, argv?: string[]): Promise<ne
 export declare function cliErrWithHelp(ctx: CliContext, msg: string): never;
 /** True when stdin is a TTY. */
 export declare const isInteractiveTty: boolean;
+/** Minimal context for headless routing helpers. */
+export type HeadlessContext = Pick<CliContext, "invocation">;
+/** True when `--json` was passed or the handler was invoked via MCP. */
+export declare function wantsExplicitJson(ctx: HeadlessContext, hasJsonFlag: boolean): boolean;
+/**
+ * Headless when MCP, `--json`, `--dry-run`, or stdin is not a TTY.
+ * Use for commands that should auto-emit JSON in pipelines.
+ */
+export declare function shouldRunHeadless(ctx: HeadlessContext, hasJsonFlag: boolean, hasDryRunFlag?: boolean, interactive?: boolean): boolean;
+/**
+ * Like {@link shouldRunHeadless}, but only auto-headless in non-TTY when positionals are present.
+ * Avoids turning empty invocations into JSON errors.
+ */
+export declare function shouldRunHeadlessWithPositionals(ctx: HeadlessContext, hasJsonFlag: boolean, positionals: string[], hasDryRunFlag?: boolean, interactive?: boolean): boolean;
+/**
+ * Headless when MCP, `--dry-run` with required args, or non-TTY with `--yes` and required args.
+ * Use for mutating commands that require explicit `--yes` in scripts.
+ */
+export declare function shouldRunHeadlessWithYes(ctx: HeadlessContext, opts: {
+	yes: boolean;
+	hasRequiredArgs: boolean;
+	dryRun?: boolean;
+}, interactive?: boolean): boolean;
+/**
+ * Exits when non-interactive mode is used without `--yes`.
+ * @param hint - Command-specific guidance appended to the error
+ */
+export declare function requireYesInNonTty(yes: boolean, hint: string, dryRun?: boolean, interactive?: boolean): void;
+/** Prefixes a success message when running in dry-run mode. */
+export declare function formatDryRunMessage(message: string, dryRun: boolean): string;
+/** Config for {@link ghReleaseUpdateGetLatest}. */
+export interface GhReleaseUpdateConfig {
+	/** GitHub `owner/repo` slug. */
+	repo: string;
+	/** Release asset filename (e.g. `myapp`). */
+	asset: string;
+	/** Temp directory name prefix for downloads. */
+	tempPrefix: string;
+	/** Path to the on-disk version-check cache JSON file. */
+	cachePath: string;
+	/** Optional hint when `gh auth` fails or no releases exist. */
+	repoEnvHint?: string;
+}
+/** Config for {@link createGhVersionCheck}. */
+export interface GhVersionCheckConfig {
+	/** Installed semver string. */
+	currentVersion: string;
+	/** CLI command name for update notices (e.g. `qa`). */
+	commandName: string;
+	/** Path to the on-disk version-check cache JSON file. */
+	cachePath: string;
+	/** Cache TTL in milliseconds (default 24h). */
+	ttlMs?: number;
+	/** When true, skip background refresh (e.g. test subprocess). */
+	skipRefresh?: () => boolean;
+	/** When true, skip refresh because `gh` is unavailable. */
+	ghAvailable?: () => boolean;
+	/** Fetches latest release version via `gh`. */
+	fetchLatest: () => Promise<string>;
+}
+/** Returns whether the installed version matches the latest release. */
+export declare function isAlreadyCurrent(current: string, latest: string): boolean;
+/** Strips a leading `v` from a release tag. */
+export declare function parseReleaseTag(tag: string): string;
+/** Builds a `CliUpdateGetLatest` hook that downloads a release via `gh`. */
+export declare function ghReleaseUpdateGetLatest(config: GhReleaseUpdateConfig): CliUpdateGetLatest;
+/** Version-check cache helpers for summary notices and background refresh. */
+export declare function createGhVersionCheck(config: GhVersionCheckConfig): {
+	getUpdateNotice: () => string | null;
+	refreshIfStale: () => void;
+};
+/** Shared `gh release view` fetcher for hooks and version-check refresh. */
+export declare function createGhFetchLatest(config: Pick<GhReleaseUpdateConfig, "repo" | "repoEnvHint">): () => Promise<string>;
 
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "3.2.0",
+  "version": "3.3.1",
   "type": "module",
   "engines": {
     "bun": ">=1.3"

package/plan.md

@@ -1,194 +1,19 @@
 # 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`, `CliOption`, `CliPositional`, `CliHandler`, `CliContext` interfaces
-  - `CliSchemaValidationError` class
-  - `CliOption` on `options`, `CliPositional` on `positionals`, nested routes under `commands`
-
-- **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
+**Overall**: Core CLI, MCP, install, docs, and update built-ins are complete. Public API is stable at **3.x**.
 
-### 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**
+### Shipped
 
-**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
+- Schema-driven parsing, help, completions, subcommand routing, fallback commands
+- MCP server (`mcpServer: { enabled: true }`), `ctx.invocation`, `cliInvoke`
+- `install` / `update` built-ins, agent skills, bundled `docs` (topics, schema, api, skill, mcp)
+- Headless helpers and `ghReleaseUpdateGetLatest` for GitHub release consumers
 
-**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
+### Consumers
 
-**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.
+- **qa-cli** — argsbarg program with Ink UI; commands under `src/commands/`
+- **idp-trees** — argsbarg program with headless JSON ops; `cli/dispatch.ts` pattern
 
-**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?
+See [README.md](README.md) and [CHANGELOG.md](CHANGELOG.md) for release history.

package/src/headless.test.ts

@@ -0,0 +1,80 @@
+import { expect, test } from "bun:test";
+import {
+  formatDryRunMessage,
+  requireYesInNonTty,
+  shouldRunHeadless,
+  shouldRunHeadlessWithPositionals,
+  shouldRunHeadlessWithYes,
+  wantsExplicitJson,
+} from "./headless.ts";
+
+test("wantsExplicitJson includes MCP invocation", () => {
+  expect(wantsExplicitJson({ invocation: "cli" }, false)).toBe(false);
+  expect(wantsExplicitJson({ invocation: "mcp" }, false)).toBe(true);
+  expect(wantsExplicitJson({ invocation: "cli" }, true)).toBe(true);
+});
+
+test("shouldRunHeadless is true for MCP and json", () => {
+  expect(shouldRunHeadless({ invocation: "mcp" }, false)).toBe(true);
+  expect(shouldRunHeadless({ invocation: "cli" }, true)).toBe(true);
+  expect(shouldRunHeadless({ invocation: "cli" }, false, true)).toBe(true);
+  expect(shouldRunHeadless({ invocation: "cli" }, false, false, false)).toBe(true);
+});
+
+test("shouldRunHeadlessWithPositionals requires positionals in non-tty", () => {
+  expect(
+    shouldRunHeadlessWithPositionals({ invocation: "cli" }, false, [], false, false),
+  ).toBe(false);
+  expect(
+    shouldRunHeadlessWithPositionals({ invocation: "cli" }, false, ["a"], false, false),
+  ).toBe(true);
+});
+
+test("shouldRunHeadlessWithYes requires yes in non-tty", () => {
+  expect(
+    shouldRunHeadlessWithYes(
+      { invocation: "cli" },
+      { yes: true, hasRequiredArgs: true },
+      false,
+    ),
+  ).toBe(true);
+  expect(
+    shouldRunHeadlessWithYes(
+      { invocation: "cli" },
+      { yes: false, hasRequiredArgs: true },
+      false,
+    ),
+  ).toBe(false);
+  expect(
+    shouldRunHeadlessWithYes(
+      { invocation: "cli" },
+      { yes: false, hasRequiredArgs: true, dryRun: true },
+      false,
+    ),
+  ).toBe(true);
+});
+
+test("formatDryRunMessage prefixes dry-run output", () => {
+  expect(formatDryRunMessage("hello", false)).toBe("hello");
+  expect(formatDryRunMessage("hello", true)).toBe("[DRY RUN] hello");
+});
+
+test("requireYesInNonTty exits without yes in non-tty", () => {
+  const originalExit = process.exit;
+  let code: number | undefined;
+  process.exit = ((c?: number) => {
+    code = c ?? 0;
+    throw new Error("exit");
+  }) as typeof process.exit;
+
+  try {
+    expect(() => {
+      requireYesInNonTty(false, "hint", false, false);
+    }).toThrow("exit");
+    expect(code).toBe(1);
+    requireYesInNonTty(false, "hint", true, false);
+    requireYesInNonTty(true, "hint", false, false);
+  } finally {
+    process.exit = originalExit;
+  }
+});

package/src/headless.ts

@@ -0,0 +1,81 @@
+import type { CliContext } from "./context.ts";
+import { isInteractiveTty } from "./utils.ts";
+
+/** Minimal context for headless routing helpers. */
+export type HeadlessContext = Pick<CliContext, "invocation">;
+
+/** True when `--json` was passed or the handler was invoked via MCP. */
+export function wantsExplicitJson(ctx: HeadlessContext, hasJsonFlag: boolean): boolean {
+  return hasJsonFlag || ctx.invocation === "mcp";
+}
+
+/**
+ * Headless when MCP, `--json`, `--dry-run`, or stdin is not a TTY.
+ * Use for commands that should auto-emit JSON in pipelines.
+ */
+export function shouldRunHeadless(
+  ctx: HeadlessContext,
+  hasJsonFlag: boolean,
+  hasDryRunFlag = false,
+  interactive: boolean = isInteractiveTty,
+): boolean {
+  if (ctx.invocation === "mcp") return true;
+  if (hasJsonFlag || hasDryRunFlag) return true;
+  return !interactive;
+}
+
+/**
+ * Like {@link shouldRunHeadless}, but only auto-headless in non-TTY when positionals are present.
+ * Avoids turning empty invocations into JSON errors.
+ */
+export function shouldRunHeadlessWithPositionals(
+  ctx: HeadlessContext,
+  hasJsonFlag: boolean,
+  positionals: string[],
+  hasDryRunFlag = false,
+  interactive: boolean = isInteractiveTty,
+): boolean {
+  if (ctx.invocation === "mcp") return true;
+  if (hasJsonFlag || hasDryRunFlag) return true;
+  return !interactive && positionals.length > 0;
+}
+
+/**
+ * Headless when MCP, `--dry-run` with required args, or non-TTY with `--yes` and required args.
+ * Use for mutating commands that require explicit `--yes` in scripts.
+ */
+export function shouldRunHeadlessWithYes(
+  ctx: HeadlessContext,
+  opts: { yes: boolean; hasRequiredArgs: boolean; dryRun?: boolean },
+  interactive: boolean = isInteractiveTty,
+): boolean {
+  if (ctx.invocation === "mcp") {
+    return opts.hasRequiredArgs && (opts.yes || Boolean(opts.dryRun));
+  }
+  if (opts.dryRun && opts.hasRequiredArgs) return true;
+  if (!interactive) return opts.yes && opts.hasRequiredArgs;
+  return opts.yes && opts.hasRequiredArgs;
+}
+
+/**
+ * Exits when non-interactive mode is used without `--yes`.
+ * @param hint - Command-specific guidance appended to the error
+ */
+export function requireYesInNonTty(
+  yes: boolean,
+  hint: string,
+  dryRun = false,
+  interactive: boolean = isInteractiveTty,
+): void {
+  if (dryRun) return;
+  if (!interactive && !yes) {
+    process.stderr.write(`Error: non-interactive mode requires --yes. ${hint}\n`);
+    process.exit(1);
+  }
+}
+
+/** Prefixes a success message when running in dry-run mode. */
+export function formatDryRunMessage(message: string, dryRun: boolean): string {
+  if (!dryRun) return message;
+  return `[DRY RUN] ${message}`;
+}

package/src/index.ts

@@ -28,3 +28,20 @@ export type {
   CliPositional,
 } from "./types.ts";
 export { isInteractiveTty } from "./utils.ts";
+export {
+  formatDryRunMessage,
+  requireYesInNonTty,
+  shouldRunHeadless,
+  shouldRunHeadlessWithPositionals,
+  shouldRunHeadlessWithYes,
+  wantsExplicitJson,
+} from "./headless.ts";
+export type { HeadlessContext } from "./headless.ts";
+export {
+  createGhFetchLatest,
+  createGhVersionCheck,
+  ghReleaseUpdateGetLatest,
+  isAlreadyCurrent,
+  parseReleaseTag,
+} from "./install/gh-release-update.ts";
+export type { GhReleaseUpdateConfig, GhVersionCheckConfig } from "./install/gh-release-update.ts";

package/src/install/gh-release-update.test.ts

@@ -0,0 +1,22 @@
+import { expect, test } from "bun:test";
+import { isAlreadyCurrent, parseReleaseTag } from "./gh-release-update.ts";
+
+test("parseReleaseTag strips leading v", () => {
+  expect(parseReleaseTag("v1.4.3")).toBe("1.4.3");
+});
+
+test("parseReleaseTag leaves bare semver unchanged", () => {
+  expect(parseReleaseTag("1.4.3")).toBe("1.4.3");
+});
+
+test("parseReleaseTag throws on empty tag", () => {
+  expect(() => parseReleaseTag("")).toThrow("Release tag is empty");
+});
+
+test("isAlreadyCurrent returns true when versions match", () => {
+  expect(isAlreadyCurrent("1.4.3", "1.4.3")).toBe(true);
+});
+
+test("isAlreadyCurrent returns false when versions differ", () => {
+  expect(isAlreadyCurrent("1.4.2", "1.4.3")).toBe(false);
+});

package/src/install/gh-release-update.ts

@@ -0,0 +1,229 @@
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import type { CliUpdateGetLatest } from "../types.ts";
+
+/** Config for {@link ghReleaseUpdateGetLatest}. */
+export interface GhReleaseUpdateConfig {
+  /** GitHub `owner/repo` slug. */
+  repo: string;
+  /** Release asset filename (e.g. `myapp`). */
+  asset: string;
+  /** Temp directory name prefix for downloads. */
+  tempPrefix: string;
+  /** Path to the on-disk version-check cache JSON file. */
+  cachePath: string;
+  /** Optional hint when `gh auth` fails or no releases exist. */
+  repoEnvHint?: string;
+}
+
+/** Config for {@link createGhVersionCheck}. */
+export interface GhVersionCheckConfig {
+  /** Installed semver string. */
+  currentVersion: string;
+  /** CLI command name for update notices (e.g. `qa`). */
+  commandName: string;
+  /** Path to the on-disk version-check cache JSON file. */
+  cachePath: string;
+  /** Cache TTL in milliseconds (default 24h). */
+  ttlMs?: number;
+  /** When true, skip background refresh (e.g. test subprocess). */
+  skipRefresh?: () => boolean;
+  /** When true, skip refresh because `gh` is unavailable. */
+  ghAvailable?: () => boolean;
+  /** Fetches latest release version via `gh`. */
+  fetchLatest: () => Promise<string>;
+}
+
+type VersionCheckCache = {
+  fetchedAt: number;
+  latest: string;
+};
+
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** Returns whether the installed version matches the latest release. */
+export function isAlreadyCurrent(current: string, latest: string): boolean {
+  return current === latest;
+}
+
+/** Strips a leading `v` from a release tag. */
+export function parseReleaseTag(tag: string): string {
+  const trimmed = tag.trim();
+  if (!trimmed) {
+    throw new Error("Release tag is empty");
+  }
+  return trimmed.startsWith("v") ? trimmed.slice(1) : trimmed;
+}
+
+/** Builds a `CliUpdateGetLatest` hook that downloads a release via `gh`. */
+export function ghReleaseUpdateGetLatest(config: GhReleaseUpdateConfig): CliUpdateGetLatest {
+  const fetchLatest = createGhFetchLatest(config);
+
+  return async ({ version }) => {
+    ensureGhAvailable();
+
+    const latestVersion = await fetchLatest();
+    if (isAlreadyCurrent(version, latestVersion)) {
+      return { path: process.execPath, version: latestVersion };
+    }
+
+    const tempDir = mkdtempSync(join(tmpdir(), config.tempPrefix));
+    try {
+      const downloadedPath = await downloadReleaseAsset(config, tempDir);
+      chmodSync(downloadedPath, 0o755);
+      writeVersionCheckCache(config.cachePath, { fetchedAt: Date.now(), latest: latestVersion });
+      return {
+        path: downloadedPath,
+        version: latestVersion,
+        cleanup: () => {
+          rmSync(tempDir, { recursive: true, force: true });
+        },
+      };
+    } catch (err) {
+      rmSync(tempDir, { recursive: true, force: true });
+      throw err;
+    }
+  };
+}
+
+/** Version-check cache helpers for summary notices and background refresh. */
+export function createGhVersionCheck(config: GhVersionCheckConfig): {
+  getUpdateNotice: () => string | null;
+  refreshIfStale: () => void;
+} {
+  const ttlMs = config.ttlMs ?? DEFAULT_TTL_MS;
+  const ghAvailable = config.ghAvailable ?? (() => Bun.which("gh") !== null);
+
+  return {
+    getUpdateNotice(): string | null {
+      const cached = readVersionCheckCache(config.cachePath);
+      if (cached === null || isAlreadyCurrent(config.currentVersion, cached.latest)) {
+        return null;
+      }
+      return `Update available: v${cached.latest} (you have v${config.currentVersion}). Run \`${config.commandName} update\``;
+    },
+
+    refreshIfStale(): void {
+      if (config.skipRefresh?.()) return;
+      if (!ghAvailable()) return;
+
+      const cached = readVersionCheckCache(config.cachePath);
+      if (cached !== null && Date.now() - cached.fetchedAt < ttlMs) {
+        return;
+      }
+
+      void config.fetchLatest()
+        .then((latest) => {
+          writeVersionCheckCache(config.cachePath, { fetchedAt: Date.now(), latest });
+        })
+        .catch(() => {
+          // Best-effort; summary must never fail because of a version check.
+        });
+    },
+  };
+}
+
+/** Shared `gh release view` fetcher for hooks and version-check refresh. */
+export function createGhFetchLatest(config: Pick<GhReleaseUpdateConfig, "repo" | "repoEnvHint">): () => Promise<string> {
+  return async () => {
+    const result = await runGh([
+      "release",
+      "view",
+      "--repo",
+      config.repo,
+      "--json",
+      "tagName",
+    ]);
+
+    if (result.exitCode !== 0) {
+      const detail = result.stderr.trim() || result.stdout.trim();
+      const hint = detail.includes("auth") || detail.includes("401")
+        ? " Run `gh auth login` and try again."
+        : detail.includes("release not found") || detail.includes("Not Found")
+          ? config.repoEnvHint
+            ? ` ${config.repoEnvHint}`
+            : ` No releases found for ${config.repo}.`
+          : "";
+      throw new Error(
+        `Failed to fetch latest release from ${config.repo}: ${detail || "unknown error"}.${hint}`,
+      );
+    }
+
+    let parsed: { tagName?: string };
+    try {
+      parsed = JSON.parse(result.stdout) as { tagName?: string };
+    } catch {
+      throw new Error("Failed to parse release metadata from gh");
+    }
+
+    if (!parsed.tagName) {
+      throw new Error("No release tag found for this repository");
+    }
+
+    return parseReleaseTag(parsed.tagName);
+  };
+}
+
+function ensureGhAvailable(): void {
+  if (Bun.which("gh") === null) {
+    throw new Error(
+      "GitHub CLI (gh) is required. Install from https://cli.github.com/ and run `gh auth login`.",
+    );
+  }
+}
+
+async function downloadReleaseAsset(config: GhReleaseUpdateConfig, tempDir: string): Promise<string> {
+  const result = await runGh([
+    "release",
+    "download",
+    "--repo",
+    config.repo,
+    "--pattern",
+    config.asset,
+    "--dir",
+    tempDir,
+  ]);
+
+  if (result.exitCode !== 0) {
+    const detail = result.stderr.trim() || result.stdout.trim();
+    throw new Error(
+      `Failed to download release from ${config.repo}: ${detail || "unknown error"}`,
+    );
+  }
+
+  const downloadedPath = join(tempDir, config.asset);
+  if (!existsSync(downloadedPath)) {
+    throw new Error(`Release asset "${config.asset}" was not found in the download`);
+  }
+
+  return downloadedPath;
+}
+
+async function runGh(args: string[]): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  const proc = Bun.spawn(["gh", ...args], { stdout: "pipe", stderr: "pipe" });
+  const [exitCode, stdout, stderr] = await Promise.all([
+    proc.exited,
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  return { exitCode, stdout, stderr };
+}
+
+function readVersionCheckCache(cachePath: string): VersionCheckCache | null {
+  try {
+    const raw = readFileSync(cachePath, "utf8");
+    const parsed = JSON.parse(raw) as VersionCheckCache;
+    if (typeof parsed.fetchedAt !== "number" || typeof parsed.latest !== "string") {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function writeVersionCheckCache(cachePath: string, cache: VersionCheckCache): void {
+  mkdirSync(dirname(cachePath), { recursive: true });
+  writeFileSync(cachePath, JSON.stringify(cache));
+}