argsbarg 3.4.1 → 3.5.0

package/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.5.0] - 2026-06-22
+
+### Added
+
+- **`install --mcp`** — OpenCode: merges local MCP entry into `~/.config/opencode` config (`mcp` key, OpenCode `type: "local"` format).
+- **`install --mcp`** — Codex: runs `codex mcp add` when `codex` is on PATH.
+- **`install --mcp`** — ChatGPT desktop: merges into `chatgpt_mcp_config.json` when ChatGPT app data exists.
+
+### Changed
+
+- **`docs mcp`** — Codex/ChatGPT guidance: Connectors for web (remote MCP); gated desktop JSON auto-install.
+
+## [3.4.2] - 2026-06-22
+
+### Added
+
+- **`install --mcp`** — also merges into Claude Desktop `claude_desktop_config.json` when Claude Desktop app data is present (macOS, Windows, Linux paths).
+
+### Changed
+
+- **`docs mcp`** — generated guide documents Cursor, Claude Code, and Claude Desktop install targets and platform config paths.
+- **`mcp bundle`** — no longer macOS-only; packs `.mcpb` on any platform when the compiled binary exists.
+
 ## [3.4.1] - 2026-06-22
 
 
@@ -348,7 +371,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.4.1...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.5.0...HEAD
+[3.5.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.5.0
+[3.4.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.4.2
 [3.4.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.4.1
 [3.4.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.4.0
 [3.3.14]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.14

package/biome.json

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

package/bun.lock

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

package/docs/install.md

@@ -31,7 +31,7 @@ myapp install --uninstall --all --yes
 | Fish completion | `--completions` | `~/.config/fish/completions/<key>.fish` |
 | Cursor skill | `--skill` | `~/.cursor/skills/<dir>/` when `~/.cursor` exists |
 | Claude skill | `--skill` | `~/.claude/skills/<dir>/` when `~/.claude` exists |
-| MCP config | `--mcp` | `~/.cursor/mcp.json` and `~/.claude.json` when MCP is enabled |
+| MCP config | `--mcp` | Cursor, Claude Code/Desktop, OpenCode (`~/.config/opencode`), Codex (`codex` on PATH), ChatGPT desktop (when app data exists). ChatGPT web uses Connectors — see `docs mcp` |
 
 `--all` expands to `--bin`, `--completions`, `--skill`, and `--mcp` (when `mcpServer.enabled` is `true`) for both install and uninstall. Missing targets are skipped silently (no error if nothing is on disk or a shell/agent directory does not exist).
 

package/docs/mcp.md

@@ -57,7 +57,67 @@ Add a server entry under `mcpServers` in your Cursor MCP config:
 }
 ```
 
-Use your real binary or script path. For a compiled CLI, `command` can be the installed binary and `args` can be `["ai", "mcp"]`.
+Use your real binary or script path. For a compiled CLI, `command` can be the installed binary and `args` can be `["mcp"]`.
+
+### Claude Code
+
+`install --mcp` merges into `~/.claude.json` under `mcpServers`.
+
+### Claude Desktop
+
+`install --mcp` also merges into Claude Desktop config when app data is present:
+
+| Platform | Path |
+| --- | --- |
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Linux | `~/.config/Claude/claude_desktop_config.json` |
+
+Restart Claude Desktop after config changes. You can also install a **`.mcpb`** bundle via **`mcp bundle`** (see [MCP Bundle](#mcp-bundle-mcp-bundle)).
+
+### OpenCode
+
+When `~/.config/opencode` exists, **`install --mcp`** merges a local server under the top-level **`mcp`** key (not `mcpServers`):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "myapp": {
+      "type": "local",
+      "command": ["myapp", "mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+OpenCode reads `opencode.jsonc`, `opencode.json`, or `config.json` in that directory. Argsbarg updates the first existing file, or creates `config.json`. JSON-with-comments (`.jsonc`) is not auto-edited — add the block manually or use a `.json` config file.
+
+### OpenAI Codex
+
+When **`codex`** is on PATH, **`install --mcp`** runs `codex mcp add <server> -- <binary> mcp`, which writes **`~/.codex/config.toml`**. Otherwise add manually:
+
+```toml
+[mcp_servers.myapp]
+command = "myapp"
+args = ["mcp"]
+```
+
+Use **`codex mcp`** to list/add/remove servers, or **Settings → MCP → Open config.toml** in the Codex app. CLI and IDE extension share the same file.
+
+### ChatGPT
+
+**Web / Connectors (OpenAI’s documented path)** — **Settings → Connectors → Developer mode** with a **remote HTTPS MCP URL**. ChatGPT does not spawn local stdio binaries; bridge and tunnel local servers when needed.
+
+**Desktop JSON (gated auto-install)** — when ChatGPT app data exists, **`install --mcp`** also merges `mcpServers` into:
+
+| Platform | Path |
+| --- | --- |
+| macOS | `~/Library/Application Support/ChatGPT/chatgpt_mcp_config.json` |
+| Windows | `%APPDATA%\OpenAI\ChatGPT\chatgpt_mcp_config.json` |
+
+Local JSON support varies by desktop build. Prefer **Connectors** for ChatGPT web or when tools do not appear after install.
 
 ### Other MCP hosts
 
@@ -295,7 +355,7 @@ You should get one JSON line on stdout with `result.capabilities` and `result.se
 
 ## MCP Bundle (`mcp bundle`)
 
-When `mcpServer.enabled` is true, **`mcp bundle`** packs a Claude Desktop **`.mcpb`** bundle (macOS-only v1):
+When `mcpServer.enabled` is true, **`mcp bundle`** packs a Claude Desktop **`.mcpb`** bundle:
 
 ```bash
 just build
@@ -305,7 +365,7 @@ just build
 
 Expects the compiled binary at **`dist/<program.key>`** and writes **`dist/<program.key>.mcpb`**. Manifest metadata is generated from your schema (`mcpServerId`, tools, `requiresEnv`). Optional pack-time fields live under **`mcpServer.bundle`** (`author`, `icon`, `longDescription`).
 
-Bare **`myapp mcp`** still runs the stdio MCP server (unchanged for `install --mcp` and MCP hosts). Use **`install --mcp`** for Cursor / Claude Code JSON config.
+Bare **`myapp mcp`** still runs the stdio MCP server (unchanged for `install --mcp` and MCP hosts). Use **`install --mcp`** for Cursor, Claude Code, Claude Desktop, and OpenCode JSON config.
 
 ## Hidden commands and options
 

package/index.d.ts

@@ -1,33 +1,5 @@
 // Generated by dts-bundle-generator v9.5.1
 
-/**
- * Values passed to a leaf command handler after parsing: app name, routed path, args, and merged options.
- */
-export declare class CliContext {
-	readonly appName: string;
-	readonly commandPath: string[];
-	readonly args: string[];
-	readonly program: CliProgram;
-	readonly opts: Record<string, string>;
-	readonly invocation: CliInvocation;
-	/** Captures the program root, routed path, positional words, and option map for a leaf handler. */
-	constructor(appName: string, commandPath: string[], args: string[], opts: Record<string, string>, program: CliProgram, invocation?: CliInvocation);
-	/** Returns whether a presence flag was set (including implicit "1" for boolean options). */
-	hasFlag(name: string): boolean;
-	/** Returns the string value for a string-valued option, if present. */
-	stringOpt(name: string): string | undefined;
-	/** Parses a stored string as a number; returns null if missing or not a strict double string. */
-	numberOpt(name: string): number | null;
-	/**
-	 * Generic typed accessor: parses a stored string using the provided parse function.
-	 * This is the TypeScript-native advantage over the Swift version.
-	 */
-	typedOpt<T>(name: string, parse: (s: string) => T): T | null;
-	/** Returns the value(s) for a named positional slot. Varargs slots return string[]; single slots return string | undefined. */
-	positional(name: string): string | string[] | undefined;
-	private _posMap;
-	private _positionalMap;
-}
 /**
  * How a leaf handler was dispatched.
  */
@@ -308,30 +280,34 @@ export declare class CliSchemaValidationError extends Error {
 	/** Creates a schema validation error with a human-readable rule violation. */
 	constructor(message: string);
 }
-/** Outcome of a non-exiting CLI invocation. */
-export type CliInvokeKind = "ok" | "help" | "error";
-/** Result of cliInvoke: captured output and exit metadata without process.exit. */
-export interface CliInvokeResult {
-	/** Invocation outcome. */
-	kind: CliInvokeKind;
-	/** Simulated exit code. */
-	exitCode: number;
-	/** Captured stdout during handler execution. */
-	stdout: string;
-	/** Captured stderr during handler execution. */
-	stderr: string;
-	/** Set when kind === "error" (parse/validation message). */
-	errorMsg?: string;
-}
 /**
- * Parses argv against the user root, runs the leaf handler, and returns captured output.
- * Never calls process.exit.
+ * Values passed to a leaf command handler after parsing: app name, routed path, args, and merged options.
  */
-export declare function cliInvoke(root: CliProgram, argv: string[]): Promise<CliInvokeResult>;
-export declare function cliRun(program: CliProgram, argv?: string[]): Promise<never>;
-export declare function cliErrWithHelp(ctx: CliContext, msg: string): never;
-/** True when stdin is a TTY. */
-export declare const isInteractiveTty: boolean;
+export declare class CliContext {
+	readonly appName: string;
+	readonly commandPath: string[];
+	readonly args: string[];
+	readonly program: CliProgram;
+	readonly opts: Record<string, string>;
+	readonly invocation: CliInvocation;
+	/** Captures the program root, routed path, positional words, and option map for a leaf handler. */
+	constructor(appName: string, commandPath: string[], args: string[], opts: Record<string, string>, program: CliProgram, invocation?: CliInvocation);
+	/** Returns whether a presence flag was set (including implicit "1" for boolean options). */
+	hasFlag(name: string): boolean;
+	/** Returns the string value for a string-valued option, if present. */
+	stringOpt(name: string): string | undefined;
+	/** Parses a stored string as a number; returns null if missing or not a strict double string. */
+	numberOpt(name: string): number | null;
+	/**
+	 * Generic typed accessor: parses a stored string using the provided parse function.
+	 * This is the TypeScript-native advantage over the Swift version.
+	 */
+	typedOpt<T>(name: string, parse: (s: string) => T): T | null;
+	/** Returns the value(s) for a named positional slot. Varargs slots return string[]; single slots return string | undefined. */
+	positional(name: string): string | string[] | undefined;
+	private _posMap;
+	private _positionalMap;
+}
 /** Minimal context for headless routing helpers. */
 export type HeadlessContext = Pick<CliContext, "invocation">;
 /** True when `--json` was passed or the handler was invoked via MCP. */
@@ -405,6 +381,26 @@ export declare function createGhVersionCheck(config: GhVersionCheckConfig): {
 };
 /** Shared `gh release view` fetcher for hooks and version-check refresh. */
 export declare function createGhFetchLatest(config: Pick<GhReleaseUpdateConfig, "repo" | "repoEnvHint">): () => Promise<string>;
+/** Outcome of a non-exiting CLI invocation. */
+export type CliInvokeKind = "ok" | "help" | "error";
+/** Result of cliInvoke: captured output and exit metadata without process.exit. */
+export interface CliInvokeResult {
+	/** Invocation outcome. */
+	kind: CliInvokeKind;
+	/** Simulated exit code. */
+	exitCode: number;
+	/** Captured stdout during handler execution. */
+	stdout: string;
+	/** Captured stderr during handler execution. */
+	stderr: string;
+	/** Set when kind === "error" (parse/validation message). */
+	errorMsg?: string;
+}
+/**
+ * Parses argv against the user root, runs the leaf handler, and returns captured output.
+ * Never calls process.exit.
+ */
+export declare function cliInvoke(root: CliProgram, argv: string[]): Promise<CliInvokeResult>;
 /** Resolved paths for `mcp bundle`. */
 export interface McpBundlePaths {
 	binaryPath: string;
@@ -422,8 +418,12 @@ export interface PackMcpBundleOpts {
 }
 /**
  * Stages manifest + binary (+ optional icon) and writes a `.mcpb` ZIP.
- * macOS-only v1; requires the compiled binary to exist.
+ * Requires the compiled binary to exist.
  */
 export declare function packMcpBundle(program: CliProgram, opts?: PackMcpBundleOpts): string;
+export declare function cliRun(program: CliProgram, argv?: string[]): Promise<never>;
+export declare function cliErrWithHelp(ctx: CliContext, msg: string): never;
+/** True when stdin is a TTY. */
+export declare const isInteractiveTty: boolean;
 
 export {};

package/justfile

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "3.4.1",
+  "version": "3.5.0",
   "type": "module",
   "engines": {
     "bun": ">=1.3"
@@ -21,6 +21,8 @@
     }
   },
   "devDependencies": {
-    "@types/bun": "^1.3.12"
+    "@biomejs/biome": "^2.5.0",
+    "@types/bun": "^1.3.12",
+    "typescript": "^5.9.3"
   }
 }

package/scripts/release.ts

@@ -12,7 +12,7 @@
  * repo changes (`git add -A`), not only the version and CHANGELOG edits from this script.
  */
 
-import { unlink } from "fs/promises";
+import { unlink } from "node:fs/promises";
 
 /** Returns the parent directory of an absolute file path. */
 function parentDir(absolute: string): string {
@@ -96,9 +96,13 @@ function githubRepoBaseFromOrigin(origin: string): string | null {
 function releasedSemverVersionsFromChangelog(md: string): string[] {
   const re = /^## \[(\d+\.\d+\.\d+)\] /gm;
   const out: string[] = [];
-  let m: RegExpExecArray | null;
-  while ((m = re.exec(md)) !== null) {
-    out.push(m[1]!);
+  let m = re.exec(md);
+  while (m !== null) {
+    const version = m[1];
+    if (version !== undefined) {
+      out.push(version);
+    }
+    m = re.exec(md);
   }
   return out;
 }
@@ -108,14 +112,18 @@ function releasedSemverVersionsFromChangelog(md: string): string[] {
  * (`[...]: http...`) at the end of the file.
  */
 function stripChangelogLinkDefinitions(md: string): string {
-  let s = md.replace(/\r?\n## Links\r?\n/, "\n");
+  const s = md.replace(/\r?\n## Links\r?\n/, "\n");
   const lines = s.split(/\r?\n/);
   let i = lines.length;
   while (i > 0 && lines[i - 1] === "") {
     i -= 1;
   }
   const refLine = /^\[[^\]]+\]: .+$/;
-  while (i > 0 && refLine.test(lines[i - 1]!)) {
+  while (i > 0) {
+    const line = lines[i - 1];
+    if (line === undefined || !refLine.test(line)) {
+      break;
+    }
     i -= 1;
   }
   while (i > 0 && lines[i - 1] === "") {
@@ -143,7 +151,10 @@ function appendChangelogLinkDefinitions(md: string, repoBase: string): string {
   if (versions.length === 0) {
     return `${body}\n`;
   }
-  const newest = versions[0]!;
+  const newest = versions[0];
+  if (newest === undefined) {
+    return `${body}\n`;
+  }
   const lines = [
     "",
     "",
@@ -178,7 +189,9 @@ function promoteChangelog(content: string, version: string, date: string): strin
   const bodyStart = lineEnd + 1;
   const nextIdx = content.indexOf("\n## [", bodyStart);
   const body =
-    nextIdx === -1 ? content.slice(bodyStart).trimEnd() : content.slice(bodyStart, nextIdx).trimEnd();
+    nextIdx === -1
+      ? content.slice(bodyStart).trimEnd()
+      : content.slice(bodyStart, nextIdx).trimEnd();
   const tail = nextIdx === -1 ? "" : content.slice(nextIdx + 1);
   const before = content.slice(0, idx);
   const newBlock = `${header}\n\n## [${version}] - ${date}\n${body}\n\n`;
@@ -240,7 +253,11 @@ try {
   run("git tag", ["git", "tag", "-a", tag, "-m", msg], repoRoot);
   run("git push", ["git", "push"], repoRoot);
   run("git push tags", ["git", "push", "--tags"], repoRoot);
-  run("gh release", ["gh", "release", "create", tag, "--title", tag, "--notes-file", notesPath], repoRoot);
+  run(
+    "gh release",
+    ["gh", "release", "create", tag, "--title", tag, "--notes-file", notesPath],
+    repoRoot,
+  );
   run("npm publish", ["npm", "publish"], repoRoot);
 } finally {
   await unlink(notesPath).catch(() => {});

package/src/builtins/builtins.test.ts

@@ -1,10 +1,10 @@
 import { describe, expect, test } from "bun:test";
+import type { CliProgram } from "../types.ts";
+import { exportPresentationBuiltins } from "./export.ts";
+import { completionBashScript, completionFishScript, completionZshScript } from "./index.ts";
 import { cliBuiltinInstallCommand, installBuiltinOptions } from "./install.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
 import { cliPresentationRoot } from "./presentation.ts";
-import { completionBashScript, completionFishScript, completionZshScript } from "./index.ts";
-import { exportPresentationBuiltins } from "./export.ts";
-import { CliProgram } from "../types.ts";
 
 const fixture: CliProgram = {
   key: "myapp",
@@ -114,7 +114,12 @@ describe("completion emitters", () => {
   });
 
   test("zsh script registers compdef", () => {
-    const schema = cliPresentationRoot({ key: "zapp", version: "0.0.0", description: "z", handler: () => {} });
+    const schema = cliPresentationRoot({
+      key: "zapp",
+      version: "0.0.0",
+      description: "z",
+      handler: () => {},
+    });
     const zsh = completionZshScript(schema);
     expect(zsh).toContain("#compdef zapp");
     expect(zsh).toContain("compdef _zapp zapp");