argsbarg 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.0] - 2026-06-21
+
+
+## [3.3.0] - 2026-06-20
+
+### Added
+
+- **Headless helpers** — `shouldRunHeadless`, `shouldRunHeadlessWithPositionals`, `shouldRunHeadlessWithYes`, `wantsDryRun`, `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 +234,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.0...HEAD
+[3.3.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.0
+[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/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/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/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,80 @@ 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 `--dry-run` was passed. */
+export declare function wantsDryRun(hasDryRunFlag: boolean): boolean;
+/** 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.0",
   "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,86 @@
+import { expect, test } from "bun:test";
+import {
+  formatDryRunMessage,
+  requireYesInNonTty,
+  shouldRunHeadless,
+  shouldRunHeadlessWithPositionals,
+  shouldRunHeadlessWithYes,
+  wantsDryRun,
+  wantsExplicitJson,
+} from "./headless.ts";
+
+test("wantsDryRun detects flag", () => {
+  expect(wantsDryRun(true)).toBe(true);
+  expect(wantsDryRun(false)).toBe(false);
+});
+
+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,86 @@
+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 `--dry-run` was passed. */
+export function wantsDryRun(hasDryRunFlag: boolean): boolean {
+  return hasDryRunFlag;
+}
+
+/** 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,21 @@ export type {
   CliPositional,
 } from "./types.ts";
 export { isInteractiveTty } from "./utils.ts";
+export {
+  formatDryRunMessage,
+  requireYesInNonTty,
+  shouldRunHeadless,
+  shouldRunHeadlessWithPositionals,
+  shouldRunHeadlessWithYes,
+  wantsDryRun,
+  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));
+}