argsbarg 5.1.9 → 5.1.10

package/CHANGELOG.md

@@ -7,6 +7,16 @@ 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
@@ -646,7 +656,8 @@ 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.9...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

package/docs/distribution-homebrew.md

@@ -118,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

@@ -88,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "5.1.9",
+  "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"
   }
 }