argsbarg 5.1.8 → 5.1.10

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.1.10] - 2026-07-05
+
+### Added
+
+- **Zip release assets** — Homebrew formulae download `{key}.zip` from GitHub Releases; `buildReleaseArchive` in `formula-shared.ts`; `just release --purge` to delete stale releases.
+
+### Changed
+
+- **Release workflow** — `scripts/release.ts` uploads a zip archive (smaller download) instead of a bare Mach-O binary; formula `sha256` pins the archive.
+
+## [5.1.9] - 2026-07-05
+
+### Added
+
+- **`configure --sync` config bootstrap** — creates `~/.local/lib/<key>/config.json` as `{}` when missing (all apps; Homebrew `post_install`).
+- **`_bindings` metadata** — per-key intent (`env` | `file` | `skip`) in config file; wizard persists env/skip choices; `configure set --from-env`.
+- **`ctx.appConfig` unsafe I/O** — `getUnsafe`, `setUnsafe`, `readUnsafe` for raw file access (works without `program.appConfig`).
+
+### Changed
+
+- **App config detection** — `appConfigInstalled` / `--status` use file existence only (not directory-only).
+- **Configure wizard** — skips addressed keys; Enter at env prompt persists `_bindings`; accurate write messaging.
+- **`configure --status`** — binding hints on required keys (`set (env)`, etc.).
+- **Partial config validation** — single-key / bindings-only writes skip required-property checks.
+- biome lineLength=120
+
 ## [5.1.8] - 2026-07-05
 
 
@@ -630,7 +656,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/v5.1.8...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v5.1.10...HEAD
+[5.1.10]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.10
+[5.1.9]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.9
 [5.1.8]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.8
 [5.1.7]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.7
 [5.1.6]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.6

package/docs/cli-program.md

@@ -432,7 +432,9 @@ await cli.run();
 
 See [config-schema.md](config-schema.md) for codegen, [configure.md](configure.md) (`configure.targets`), and [mcp.md](mcp.md).
 
-**Handler access (`ctx.appConfig`):** `get`, `require`, `set`, `read`, `path`, `dir` — prefer over `process.env` in handlers; env export remains for subprocess inheritance. `path` is the resolved absolute config file path (`~/.local/lib/<key>/config`); `dir` is its parent directory.
+**Handler access (`ctx.appConfig`):** `get`, `require`, `set`, `read` (schema-aware, resolved values); `getUnsafe`, `setUnsafe`, `readUnsafe` (raw file, works without `program.appConfig`); `path`, `dir`. Prefer `get`/`set` when `appConfig` is declared. Env export remains for subprocess inheritance. `path` is `~/.local/lib/<key>/config.json`; `dir` is its parent.
+
+**`_bindings`:** reserved metadata for per-key intent (`env`, `file`, `skip`). Set by the wizard, `configure set --from-env`, or `ctx.appConfig.set`. Does not change resolve order (env still wins when set).
 
 ## Reserved names
 

package/docs/config-schema.md

@@ -42,11 +42,13 @@ await cli.run();
 | Interactive `configure` / `--status` | Auto-runs config wizard when `entries` is non-empty; `--status` for read-only inventory |
 | Built-in `configure get` / `configure set` | Read/write resolved values (opt-out via `commands: false`) |
 | MCP bundle / Claude plugin | `userConfig` for entries with `env` set |
-| `ctx.appConfig` in handlers | `get`, `require`, `set`, `read`, `path`, `dir` — prefer over `process.env` |
+| `ctx.appConfig` in handlers | `get`, `require`, `set`, `read`, `getUnsafe`, `setUnsafe`, `readUnsafe`, `path`, `dir` — prefer `get`/`set` when `appConfig` is set |
 
-**Validation at runtime** — argsbarg validates the config file and `config set` / `ctx.appConfig.set` against the effective JSON Schema (block `jsonSchema` or synthesized all-string schema).
+**Handler access** — with `program.appConfig`: `get` / `set` / `require` use schema validation and resolved values. `getUnsafe` / `setUnsafe` / `readUnsafe` read and write the raw file (for `_bindings` and ad-hoc keys). Without `program.appConfig`, only `path`, `dir`, and the `*Unsafe` methods work.
 
-**No public config I/O exports** — consumers use `program.appConfig` for authoring and `ctx.appConfig` in handlers.
+**`_bindings`** — reserved top-level metadata: `{ "_bindings": { "apiToken": "env" } }`. Set via wizard (Enter to use env), `configure set --from-env`, or `ctx.appConfig.set` (marks `file`). Optional keys can be bound to `skip`.
+
+**Validation at runtime** — argsbarg validates the config file and `configure set` / `ctx.appConfig.set` against the effective JSON Schema. Partial writes (bindings only, single-key updates) skip required-property checks.
 
 See [cli-program.md — Configuration](cli-program.md#configuration-programappconfig) for resolution order, bootstrap timing, and `configure get`/`set`.
 

package/docs/configure.md

@@ -54,7 +54,7 @@ Dev flow matches release: formula `install` copies the binary and generates comp
 
 # Read or write app config (non-interactive; when program.appConfig is set)
 <key> configure get [key] [--json] [--pretty]
-<key> configure set <key> <value> [--json]
+<key> configure set <key> <value> [--json] [--from-env]
 ```
 
 Non-interactive / CI: pass **`--yes`** (or **`--json`**, **`--sync`**, **`--remove-all`**, **`--remove-config`**) — see [Confirmation](#confirmation).
@@ -69,14 +69,14 @@ Non-interactive / CI: pass **`--yes`** (or **`--json`**, **`--sync`**, **`--remo
 | Claude skill | Y/n prompt | `~/.claude/skills/<dir>/` when `~/.claude` exists |
 | Codex / OpenCode / OpenClaw skills | Y/n prompt | Agent-specific dirs when available |
 | MCP config | Y/n prompt when `mcpServer.enabled` | Cursor, Claude Code/Desktop, OpenCode, Codex, OpenClaw, ChatGPT desktop |
-| App config | auto-runs wizard | Interactive wizard writes `~/.local/lib/<key>/config.json` (schema-aware: comma-separated or JSON for primitive arrays) |
+| App config | auto-runs wizard | Interactive wizard may update `~/.local/lib/<key>/config.json` when values change; `--sync` bootstraps an empty file on install |
 
 ### Externally managed binary (Homebrew)
 
 When **`PATH`** resolves the program key to the **running executable** (e.g. after `brew install`):
 
 - **`configure --status`** shows `app: system (PATH)`
-- **`--sync`** refreshes skills and MCP only — not the binary or completions
+- **`--sync`** refreshes skills and MCP; also creates `~/.local/lib/<key>/config.json` as `{}` when missing (all apps)
 
 MCP config uses the command name on **`PATH`**, not a Cellar path.
 
@@ -110,13 +110,19 @@ Artifact keys: `chatgptMcp`, `claudeCodeMcp`, `claudeDesktopMcp`, `claudeSkill`,
 
 ## App config (`program.appConfig`)
 
-When `program.appConfig` is set, ArgsBarg manages a flat JSON config file at `~/.local/lib/<sanitized-key>/config.json`.
+Every app gets `~/.local/lib/<sanitized-key>/config.json` on first **`configure --sync`** (Homebrew `post_install`), even without `program.appConfig`.
+
+When `program.appConfig` is set, ArgsBarg manages schema-driven values in that file.
 
 | Mode | Description |
 | --- | --- |
-| Interactive `configure` | Config wizard when you accept the configure target |
-| `--status` | Shows config path and which required keys are set or missing |
+| `configure --sync` | Bootstraps `config.json` as `{}` when missing |
+| Interactive `configure` | Config wizard when `entries` is non-empty; writes only when values or `_bindings` change |
+| `--status` | Shows config path, required keys (`set` / `missing`), and binding hints (`env`, `file`, `skip`) |
 | `--remove-config --yes` | Removes the config directory |
+| `configure set --from-env` | Bind a key to its mapped env var (stores `_bindings`, no literal secret) |
+
+Per-key intent is stored under the reserved `_bindings` object (e.g. `"apiToken": "env"`). Env still wins at resolve time when set; bindings record user choice and suppress re-prompts.
 
 Export helpers from `argsbarg`: `resolveAppConfigPath`, `displayAppConfigPath`.
 
@@ -127,7 +133,7 @@ Export helpers from `argsbarg`: `resolveAppConfigPath`, `displayAppConfigPath`.
 | Flag | Description |
 | --- | --- |
 | `--status` | Read-only inventory |
-| `--sync` | Refresh installed agent artifacts (Homebrew `post_install`; greenfield → full sync plan) |
+| `--sync` | Refresh installed agent artifacts; bootstrap `config.json` when missing (Homebrew `post_install`; greenfield → full sync plan) |
 | `--remove-all` | Remove all detected agent artifacts |
 | `--remove-config` | Remove app config directory only |
 

package/docs/distribution-homebrew.md

@@ -8,7 +8,8 @@ Argsbarg apps distribute the **binary and shell completions** through Homebrew,
 | --- | --- |
 | Binary + completions | Formula `install` block |
 | Skills + MCP | Formula `post_install` → `{key} configure --sync --yes` |
-| App config | User opt-in: `{key} configure` (interactive; not run from formula `post_install`) |
+| App config file | Bootstrapped as `{}` on `post_install` via `--sync` (`~/.local/lib/<key>/config.json`) |
+| App config values | User opt-in: `{key} configure` (interactive wizard when `program.appConfig` has entries) |
 | App config cleanup | Formula `uninstall` → `{key} configure --remove-config --yes` |
 
 **Only tap-from-repo** — in-repo `Formula/` or GitHub tap. Not Homebrew core.
@@ -89,7 +90,7 @@ Local dev formulae (`just install-local`) use a plain `file://` URL and do not n
 
 Completions require users to configure their shell per [Homebrew Shell Completion](https://docs.brew.sh/Shell-Completion).
 
-**Why configure is separate from `post_install`:** the wizard is interactive (TTY + prompts for secrets). Formula `post_install` runs non-interactively during `brew install` and in CI (`brew test`). Apps with `appConfig` print a one-line configure hint in formula `caveats` instead.
+**Why the wizard is separate from `post_install`:** prompting for secrets requires a TTY. `post_install` only bootstraps an empty `config.json` and refreshes skills/MCP. Apps with `appConfig` print a one-line configure hint in formula `caveats` for the interactive wizard.
 
 **MCP hosts:** when `mcpServer.enabled` is true, add a caveats line that chat apps (Cursor, Claude Desktop, etc.) must be **restarted** after `brew install` / `brew upgrade` — `post_install` updates MCP config on disk, but hosts typically load it only at startup.
 
@@ -117,9 +118,22 @@ Template source: [`examples/full-example/`](../examples/full-example/) in the ar
 ## Release workflow
 
 1. `just build` → `dist/{key}`
-2. `scripts/release.ts` → writes `Formula/{key}.rb` (GitHub URL + sha256), commits, tags, uploads `dist/{key}` to GitHub Releases
+2. `scripts/release.ts` → zips `dist/{key}` to `dist/{key}.zip`, writes `Formula/{key}.rb` (GitHub zip URL + archive sha256), commits, tags, uploads `dist/{key}.zip` to GitHub Releases
 3. Users `brew upgrade {key}` from the tap
 
+Requires the `zip` CLI on the release machine. `just install-local` still stages the bare binary via `file://` (no zip).
+
+### Stale release cleanup
+
+```bash
+just release --purge              # delete all GitHub releases except the newest (confirm on TTY)
+just release --purge --yes        # skip confirmation
+just release --purge --dry-run    # list tags that would be deleted
+just release patch --purge        # release, then purge older releases
+```
+
+`--purge` removes GitHub Release records and attached assets only — git tags remain on the remote. Old formula pins that reference deleted release URLs will fail until users upgrade.
+
 ## Removed (breaking)
 
 - Self-install to `~/.local/bin`

package/examples/full-example/justfile

@@ -20,10 +20,8 @@ build:
     @rm -f .*.bun-build
 
 # Run schemagen, git diff check, typecheck, and format
-check: schemagen
+check: schemagen format typecheck
     git diff --exit-code schemas/
-    just typecheck
-    just format
 
 # Run the CLI from source with optional args; restarts on file changes
 dev *ARGS:
@@ -38,7 +36,7 @@ alias fmt := format
 
 # Format and lint sources (auto-fix)
 format:
-    bun run biome check ./src ./scripts --write
+    bun run biome check ./src ./scripts --write --unsafe
 
 # Alias for backward compatibility
 install: install-local
@@ -81,7 +79,6 @@ run *ARGS:
 # Generate JSON Schema artifacts from TypeScript types
 schemagen:
     bun run schemagen
-    just format
 
 # Install bun/npm dependencies
 setup:
@@ -91,6 +88,10 @@ setup:
 test: check
     bun test .
 
+# Bump version, build, publish; or pass --purge to delete stale GitHub releases
+release *ARGS:
+    bun scripts/release.ts {{ARGS}}
+
 # Install release formula from tap and run formula test
 test-release:
     brew untap {{tap}} 2>/dev/null || true

package/examples/full-example/scripts/formula-shared.test.ts

@@ -0,0 +1,68 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  buildReleaseArchive,
+  releaseArchiveName,
+  releaseFormulaUrl,
+  selectStaleReleaseTags,
+} from "./formula-shared.ts";
+
+describe("releaseArchiveName", () => {
+  test("returns key.zip", () => {
+    expect(releaseArchiveName()).toBe("full-example.zip");
+  });
+});
+
+describe("releaseFormulaUrl", () => {
+  test("points at zip asset on GitHub releases", () => {
+    expect(releaseFormulaUrl("1.2.3")).toBe(
+      "https://github.com/bdombro/bun-argsbarg/releases/download/v1.2.3/full-example.zip",
+    );
+  });
+});
+
+describe("selectStaleReleaseTags", () => {
+  test("returns empty for zero or one release", () => {
+    expect(selectStaleReleaseTags([])).toEqual([]);
+    expect(selectStaleReleaseTags([{ tagName: "v1.0.0", publishedAt: "2026-01-01T00:00:00Z" }])).toEqual([]);
+  });
+
+  test("keeps newest by publishedAt and returns the rest", () => {
+    const releases = [
+      { tagName: "v1.0.0", publishedAt: "2026-01-01T00:00:00Z" },
+      { tagName: "v1.1.0", publishedAt: "2026-02-01T00:00:00Z" },
+      { tagName: "v1.0.1", publishedAt: "2026-01-15T00:00:00Z" },
+    ];
+    expect(selectStaleReleaseTags(releases)).toEqual(["v1.0.1", "v1.0.0"]);
+  });
+});
+
+describe("buildReleaseArchive", () => {
+  const workDirs: string[] = [];
+
+  afterEach(() => {
+    for (const dir of workDirs.splice(0)) {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("creates zip with binary at archive root and matching sha256", async () => {
+    const work = mkdtempSync(join(tmpdir(), "argsbarg-release-zip-"));
+    workDirs.push(work);
+    const binaryPath = join(work, "full-example");
+    writeFileSync(binaryPath, "#!/bin/sh\necho hi\n", { mode: 0o755 });
+
+    const { archivePath, sha256 } = await buildReleaseArchive(binaryPath);
+
+    expect(archivePath).toBe(`${binaryPath}.zip`);
+    const onDisk = createHash("sha256").update(readFileSync(archivePath)).digest("hex");
+    expect(sha256).toBe(onDisk);
+
+    const listing = execFileSync("unzip", ["-l", archivePath], { encoding: "utf8" });
+    expect(listing).toContain("full-example");
+  });
+});

package/examples/full-example/scripts/formula-shared.ts

@@ -1,9 +1,18 @@
 /** Shared Ruby fragments embedded in Homebrew formulae. */
 
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { $ } from "bun";
 import { createIdentity } from "./create-identity.ts";
 
 const { key, className, desc, homepage, releaseRepo } = createIdentity;
 
+/** GitHub release row used by {@link selectStaleReleaseTags}. */
+export interface ReleaseTag {
+  tagName: string;
+  publishedAt: string;
+}
+
 export const formulaInstallRuby = `def install
     bin.install "${key}"
     chmod 0755, bin/"${key}"
@@ -36,11 +45,40 @@ export interface FormulaCoords {
   url: string;
   urlStanza: string;
   version: string;
+  /** SHA-256 hex digest of the release archive at `url` (zip for GitHub releases). */
   sha256: string;
   /** When true, embed {@link githubPrivateReleaseDownloadStrategyRuby} in the formula class. */
   privateRelease?: boolean;
 }
 
+/** Release asset filename on GitHub (zip containing the bare binary at archive root). */
+export function releaseArchiveName(): string {
+  return `${key}.zip`;
+}
+
+/** Build `{binaryPath}.zip` from a compiled binary; return archive path and sha256 of the zip. */
+export async function buildReleaseArchive(binaryPath: string): Promise<{ archivePath: string; sha256: string }> {
+  const archivePath = `${binaryPath}.zip`;
+  const result = await $`zip -j -9 ${archivePath} ${binaryPath}`.nothrow();
+  if (result.exitCode !== 0) {
+    throw new Error(`zip failed: ${result.stderr}`);
+  }
+  const sha256 = createHash("sha256").update(readFileSync(archivePath)).digest("hex");
+  return { archivePath, sha256 };
+}
+
+/** Tags to delete when keeping only the newest release (sorted by `publishedAt` desc). */
+export function selectStaleReleaseTags(releases: ReleaseTag[]): string[] {
+  if (releases.length <= 1) {
+    return [];
+  }
+  const sorted = [...releases].sort((a, b) => b.publishedAt.localeCompare(a.publishedAt));
+  return sorted.slice(1).map((r) => r.tagName);
+}
+
+/** GitHub `org/repo` slug for release and purge commands. */
+export const releaseRepoSlug = releaseRepo;
+
 /** Resolves private GitHub release assets via the API at download time. */
 export const githubPrivateReleaseDownloadStrategyRuby = `  class GitHubPrivateReleaseDownloadStrategy < CurlDownloadStrategy
     def initialize(url, name, version, **meta)
@@ -82,7 +120,7 @@ export function releaseUrlStanza(url: string): string {
 }
 
 export function releaseFormulaUrl(version: string): string {
-  return `https://github.com/${releaseRepo}/releases/download/v${version}/${key}`;
+  return `https://github.com/${releaseRepo}/releases/download/v${version}/${releaseArchiveName()}`;
 }
 
 export function renderFormula(coords: FormulaCoords): string {

package/examples/full-example/scripts/release.ts

@@ -0,0 +1,212 @@
+#!/usr/bin/env bun
+/** Bump version, build, publish zip release; optional `--purge` to drop stale GitHub releases. */
+
+import * as fs from "node:fs";
+import { stdin as input, stdout as output } from "node:process";
+import * as readline from "node:readline/promises";
+import { $ } from "bun";
+import { createIdentity } from "./create-identity.ts";
+import {
+  buildReleaseArchive,
+  type ReleaseTag,
+  releaseRepoSlug,
+  renderReleaseFormula,
+  selectStaleReleaseTags,
+} from "./formula-shared.ts";
+
+const { key } = createIdentity;
+const formulaPath = `Formula/${key}.rb`;
+const binaryPath = `dist/${key}`;
+const programPath = "src/program.ts";
+
+/** Allowed semver bump kinds for `scripts/release.ts`. */
+type Bump = "major" | "minor" | "patch";
+
+interface ReleaseOptions {
+  bump?: Bump;
+  purge: boolean;
+  yes: boolean;
+  dryRun: boolean;
+}
+
+/** Entry point: release bump, purge-only, or release then purge. */
+async function main(): Promise<void> {
+  const options = parseOptions(process.argv.slice(2));
+  if (options.purge && !options.bump) {
+    await purgeStaleReleases(options);
+    return;
+  }
+  if (!options.bump) {
+    usage();
+  }
+  await runRelease(options.bump, options);
+}
+
+/** Prints usage and exits. */
+function usage(): never {
+  process.stderr.write(
+    "Usage:\n" +
+      "  bun scripts/release.ts <major|minor|patch> [--purge]\n" +
+      "  bun scripts/release.ts --purge [--yes] [--dry-run]\n",
+  );
+  process.exit(1);
+}
+
+/** Parses argv into release options. */
+function parseOptions(argv: string[]): ReleaseOptions {
+  const yes = argv.includes("--yes");
+  const dryRun = argv.includes("--dry-run");
+  const purge = argv.includes("--purge");
+  const bump = argv.find((a): a is Bump => a === "major" || a === "minor" || a === "patch");
+  for (const arg of argv) {
+    if (arg.startsWith("--") && arg !== "--purge" && arg !== "--yes" && arg !== "--dry-run") {
+      usage();
+    }
+  }
+  if (!purge && !bump) {
+    usage();
+  }
+  return { bump, purge, yes, dryRun };
+}
+
+/** Full release pipeline for a semver bump. */
+async function runRelease(bump: Bump, options: ReleaseOptions): Promise<void> {
+  const testResult = await $`just test`.nothrow();
+  if (testResult.exitCode !== 0) process.exit(testResult.exitCode);
+
+  const currentVersion = readCurrentVersion();
+  const newVersion = applyBump(currentVersion, bump);
+  console.log(`Releasing ${currentVersion} → ${newVersion}`);
+
+  updateVersion(newVersion);
+  updateChangelog(newVersion);
+
+  const buildResult = await $`just build`.nothrow();
+  if (buildResult.exitCode !== 0) process.exit(buildResult.exitCode);
+
+  const archivePath = await updateReleaseFormula(newVersion);
+
+  const docgenResult = await $`just docgen`.nothrow();
+  if (docgenResult.exitCode !== 0) process.exit(docgenResult.exitCode);
+
+  await commitAndTag(newVersion);
+  await createGithubRelease(`v${newVersion}`, archivePath);
+
+  console.log(`Released v${newVersion}`);
+
+  if (options.purge) {
+    await purgeStaleReleases(options);
+  }
+}
+
+/** Applies a semver bump to `current` and returns the new version string. */
+function applyBump(current: string, bump: Bump): string {
+  const [major, minor, patch] = current.split(".").map(Number) as [number, number, number];
+  if (bump === "major") return `${major + 1}.0.0`;
+  if (bump === "minor") return `${major}.${minor + 1}.0`;
+  return `${major}.${minor}.${patch + 1}`;
+}
+
+/** Commits all staged changes, creates an annotated tag, and pushes both to origin. */
+async function commitAndTag(newVersion: string): Promise<void> {
+  await $`git add -A`;
+  await $`git commit -m ${`chore: release v${newVersion}`}`;
+  await $`git tag v${newVersion}`;
+  await $`git push`;
+  await $`git push origin v${newVersion}`;
+}
+
+/** Creates a GitHub release for `tag` with the zip archive attached. */
+async function createGithubRelease(tag: string, archivePath: string): Promise<void> {
+  await $`gh release create ${tag} ${archivePath} --title ${tag} --generate-notes`;
+}
+
+/** Reads the CLI version from `src/program.ts`. */
+function readCurrentVersion(): string {
+  const content = fs.readFileSync(programPath, "utf-8");
+  const match = /version:\s*"([^"]+)"/.exec(content);
+  if (!match) {
+    process.stderr.write(`Could not read version from ${programPath}\n`);
+    process.exit(1);
+  }
+  const version = match[1];
+  if (!version) {
+    process.stderr.write(`Could not read version from ${programPath}\n`);
+    process.exit(1);
+  }
+  const parts = version.split(".").map(Number);
+  if (parts.length !== 3 || parts.some(Number.isNaN)) {
+    process.stderr.write(`Invalid semver in ${programPath}: ${version}\n`);
+    process.exit(1);
+  }
+  return version;
+}
+
+/** Promotes `[Unreleased]` to a dated version section in `CHANGELOG.md`. */
+function updateChangelog(newVersion: string): void {
+  const changelogPath = "CHANGELOG.md";
+  const content = fs.readFileSync(changelogPath, "utf-8");
+  const date = new Date().toISOString().slice(0, 10);
+  fs.writeFileSync(
+    changelogPath,
+    content.replace(/^## \[Unreleased\]/m, `## [Unreleased]\n\n## [${newVersion}] - ${date}`),
+  );
+}
+
+/** Overwrites the version literal in `src/program.ts`. */
+function updateVersion(newVersion: string): void {
+  const content = fs.readFileSync(programPath, "utf-8");
+  fs.writeFileSync(programPath, content.replace(/version:\s*"[^"]+"/, `version: "${newVersion}"`));
+}
+
+/** Writes the release formula with zip URL and archive sha256; returns the archive path. */
+async function updateReleaseFormula(version: string): Promise<string> {
+  const { archivePath, sha256 } = await buildReleaseArchive(binaryPath);
+  fs.writeFileSync(formulaPath, renderReleaseFormula(version, sha256));
+  return archivePath;
+}
+
+/** Deletes all GitHub releases except the most recent. */
+async function purgeStaleReleases(options: ReleaseOptions): Promise<void> {
+  const list = await $`gh release list -R ${releaseRepoSlug} --json tagName,publishedAt`.nothrow();
+  if (list.exitCode !== 0) process.exit(list.exitCode);
+
+  const releases = JSON.parse(list.stdout.toString()) as ReleaseTag[];
+  const toDelete = selectStaleReleaseTags(releases);
+
+  if (toDelete.length === 0) {
+    console.log("No stale releases to delete.");
+    return;
+  }
+
+  console.log(`Will delete ${toDelete.length} release(s):`);
+  for (const tag of toDelete) {
+    console.log(`  ${tag}`);
+  }
+
+  if (options.dryRun) {
+    return;
+  }
+
+  if (!options.yes) {
+    if (!input.isTTY) {
+      process.stderr.write("Not a TTY; pass --yes to confirm purge.\n");
+      process.exit(1);
+    }
+    const rl = readline.createInterface({ input, output });
+    const answer = await rl.question("Delete these releases? [y/N] ");
+    rl.close();
+    if (answer.trim().toLowerCase() !== "y") {
+      console.log("Aborted.");
+      return;
+    }
+  }
+
+  for (const tag of toDelete) {
+    const del = await $`gh release delete ${tag} -R ${releaseRepoSlug} --yes`.nothrow();
+    if (del.exitCode !== 0) process.exit(del.exitCode);
+    console.log(`Deleted ${tag}`);
+  }
+}
+
+await main();

package/index.d.ts

@@ -7,11 +7,15 @@ export declare function displayAppConfigPath(program: CliProgram): string;
 export type ResolvedConfig = Record<string, unknown>;
 declare class EmptyAppConfigSnapshot {
 	private readonly program;
-	constructor(program: CliProgram);
+	private fileData;
+	constructor(program: CliProgram, fileData?: Record<string, unknown>);
 	get(_key: string): undefined;
 	require(key: string): never;
 	set(_key: string, _value: unknown): void;
 	read(): ResolvedConfig;
+	readUnsafe(): Record<string, unknown>;
+	getUnsafe(key: string): unknown;
+	setUnsafe(key: string, value: unknown): void;
 	/** Resolved absolute path to the app JSON config file (OS default from `program.key`). */
 	get path(): string;
 	/** Resolved absolute directory containing the config file. */
@@ -26,13 +30,18 @@ declare class AppConfigSnapshot {
 	require(key: string): unknown;
 	set(key: string, value: unknown): void;
 	read(): ResolvedConfig;
+	readUnsafe(): Record<string, unknown>;
+	getUnsafe(key: string): unknown;
+	setUnsafe(key: string, value: unknown): void;
 	/** Resolved absolute path to the app JSON config file (`~/.local/lib/<key>/config.json`). */
 	get path(): string;
 	/** Resolved absolute directory containing the config file. */
 	get dir(): string;
 	/** Replace snapshot after external bootstrap (internal). */
 	refresh(fileData: Record<string, unknown>, resolved: ResolvedConfig): void;
+	private persistFileData;
 	private assertEntryKey;
+	private assertUnsafeKey;
 }
 export type AnyAppConfigSnapshot = AppConfigSnapshot | EmptyAppConfigSnapshot;
 /** Coerced leaf inputs keyed by option and positional names. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "5.1.8",
+  "version": "5.1.10",
   "type": "module",
   "engines": {
     "bun": ">=1.3"
@@ -32,6 +32,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.5.0",
     "@types/bun": "^1.3.12",
+    "dts-bundle-generator": "^9.5.1",
     "typescript": "^5.9.3"
   }
 }

package/src/builtins/builtins.test.ts

@@ -52,9 +52,7 @@ describe("builtins help copy", () => {
 
   test("configure copy omits MCP when mcpServer unset", () => {
     const caps = resolveCapabilities(noMcp);
-    expect(configureCommandDescription(noMcp, caps)).toBe(
-      "Set up agent skills for this app (binary via Homebrew).",
-    );
+    expect(configureCommandDescription(noMcp, caps)).toBe("Set up agent skills for this app (binary via Homebrew).");
     expect(configureCommandDescription(noMcp, caps)).not.toContain("MCP");
     expect(configureSyncOptionDescription(noMcp, caps)).not.toContain("MCP");
     const configure = cliBuiltinConfigureCommand(noMcp);