argsbarg 5.1.3 → 5.1.5

package/CHANGELOG.md

@@ -7,8 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [5.1.3] - 2026-07-04
+## [5.1.5] - 2026-07-05
+
+### Changed
+
+- **`just install-local`** — back up release `Formula/{key}.rb`, write dev formula for `brew install`, then restore the release formula (`scripts/with-dev-formula.ts`).
+- **`just ensure-release-formula`** — normalize release formula layout; restore from install-local backup or fail with `git restore` hint if a dev `file://` formula is left on disk.
+
+## [5.1.4] - 2026-07-04
 
+### Changed
+
+- **Template justfile** — export `HOMEBREW_GITHUB_API_TOKEN` from `gh auth token` at top of justfile; removed `scripts/ensure-brew-github-token.sh` and `HOMEBREW_NO_*` suppress vars.
+
+## [5.1.3] - 2026-07-04
 
 ## [5.1.2] - 2026-07-04
 
@@ -605,7 +617,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.3...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v5.1.5...HEAD
+[5.1.5]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.5
+[5.1.4]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.4
 [5.1.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.3
 [5.1.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.2
 [5.1.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.1

package/docs/distribution-homebrew.md

@@ -51,7 +51,7 @@ just reinstall-local   # fast binary swap (`install -m 755` into Cellar; run ins
 just uninstall        # undo formula + agent artifacts (not app config)
 ```
 
-Dev and release use the **same formula** (`Formula/{key}.rb`, class name, install/post_install/test). `gen-dev-formula.ts` only changes `url`, `version`, and `sha256` to point at the local binary in `Formula/.staging/`. Release bumps restore the GitHub URL via `scripts/release.ts`.
+Dev and release use the **same formula file** (`Formula/{key}.rb`, class name, install/post_install/test). `just install-local` temporarily overwrites it with a `file://` dev formula (staged under `Formula/.staging/`), runs `brew install`, then **restores** the release formula from backup. Release bumps rewrite the GitHub URL via `scripts/release.ts`.
 
 ### Developer uninstall
 

package/examples/full-example/README.md

@@ -59,7 +59,7 @@ brew install just bun
 just setup
 just install              # build + local dev formula
 just reinstall-local      # fast binary swap during development
-just install-production   # remote tap install (needs HOMEBREW_GITHUB_API_TOKEN)
+just install-production   # remote tap install (uses gh auth token)
 just test-release
 ```
 

package/examples/full-example/justfile

@@ -1,8 +1,6 @@
 set shell := ["bash", "-eu", "-o", "pipefail", "-c"]
 
-HOMEBREW_NO_AUTO_UPDATE := "1"
-HOMEBREW_NO_INSTALL_CLEANUP := "1"
-HOMEBREW_NO_ENV_HINTS := "1"
+export HOMEBREW_GITHUB_API_TOKEN := `gh auth token`
 
 cli_key := `bun scripts/print-identity.ts key`
 tap_org := `bun scripts/print-identity.ts tapOrg`
@@ -51,25 +49,25 @@ install: install-local
 sync-artifacts:
     just run configure --sync --yes
 
-# Dev install: build, write dev formula, symlink tap, brew install
-install-local: build
-    @bun scripts/gen-dev-formula.ts
+# Normalize release formula (fix leftover dev formula or stale layout)
+ensure-release-formula:
+    bun scripts/ensure-release-formula.ts
+
+# Dev install: build, dev formula (restored after brew), symlink tap, brew install
+install-local: build ensure-release-formula
     @brew untap {{tap}} 2>/dev/null || true
     mkdir -p {{tap_parent}}
     ln -sfn '{{justfile_directory()}}' {{tap_path}}
-    brew install --formula {{tap}}/{{cli_key}}
+    bun scripts/with-dev-formula.ts -- brew install --formula {{tap}}/{{cli_key}}
     @echo ""
     @echo "Next: {{cli_key}} configure"
 
-# Remove local dev install, then install from GitHub tap (private release assets need HOMEBREW_GITHUB_API_TOKEN)
+# Remove local dev install, then install from GitHub tap (private release assets need gh auth token)
 install-production: uninstall
-    #!/usr/bin/env bash
-    set -eu -o pipefail
-    source scripts/ensure-brew-github-token.sh
     brew tap {{release_repo}} {{tap_git_url}}
     brew install --formula {{release_repo}}/{{cli_key}}
-    echo ""
-    echo "Next: {{cli_key}} configure"
+    @echo ""
+    @echo "Next: {{cli_key}} configure"
 
 # Alias for backward compatibility
 reinstall: reinstall-local
@@ -101,9 +99,6 @@ test: check
 
 # Install release formula from tap and run formula test
 test-release:
-    #!/usr/bin/env bash
-    set -eu -o pipefail
-    source scripts/ensure-brew-github-token.sh
     brew untap {{tap}} 2>/dev/null || true
     mkdir -p {{tap_parent}}
     ln -sfn '{{justfile_directory()}}' {{tap_path}}

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

@@ -0,0 +1,54 @@
+/** Backup, write, and restore the release formula for local dev Homebrew installs. */
+
+import { createHash } from "node:crypto";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createIdentity } from "./create-identity.ts";
+import { renderDevFormula } from "./formula-shared.ts";
+
+const { key } = createIdentity;
+const root = join(import.meta.dir, "..");
+const stagingDir = join(root, "Formula", ".staging");
+const stagingPath = join(stagingDir, key);
+const formulaPath = join(root, "Formula", `${key}.rb`);
+const backupPath = join(stagingDir, `${key}.rb.bak`);
+
+/** Path to the committed release formula (`Formula/full-example.rb`). */
+export function releaseFormulaPath(): string {
+  return formulaPath;
+}
+
+/** Gitignored backup path used during `install-local`. */
+export function releaseFormulaBackupPath(): string {
+  return backupPath;
+}
+
+/** Copy the release formula to `.staging` before overwriting with the dev formula. */
+export function backupReleaseFormula(): void {
+  if (!existsSync(formulaPath)) {
+    return;
+  }
+  mkdirSync(stagingDir, { recursive: true });
+  copyFileSync(formulaPath, backupPath);
+}
+
+/** Restore the release formula from backup; no-op when no backup exists. */
+export function restoreReleaseFormula(): void {
+  if (!existsSync(backupPath)) {
+    return;
+  }
+  copyFileSync(backupPath, formulaPath);
+  unlinkSync(backupPath);
+}
+
+/** Stage `dist/full-example` and overwrite `Formula/full-example.rb` with a local `file://` dev formula. */
+export function writeDevFormula(): void {
+  const distPath = join(root, "dist", key);
+  mkdirSync(stagingDir, { recursive: true });
+  copyFileSync(distPath, stagingPath);
+  chmodSync(stagingPath, 0o755);
+
+  const sha256 = createHash("sha256").update(readFileSync(stagingPath)).digest("hex");
+  const version = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version as string;
+  writeFileSync(formulaPath, renderDevFormula(stagingPath, version, sha256), "utf8");
+}

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

@@ -0,0 +1,41 @@
+#!/usr/bin/env bun
+/** Normalize `Formula/full-example.rb` to the release layout; recover from a leftover dev formula. */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  releaseFormulaPath,
+  restoreReleaseFormula,
+  releaseFormulaBackupPath,
+} from "./dev-formula.ts";
+import { renderReleaseFormula } from "./formula-shared.ts";
+
+const formulaPath = releaseFormulaPath();
+const backupPath = releaseFormulaBackupPath();
+
+if (existsSync(backupPath)) {
+  restoreReleaseFormula();
+  console.log(`Restored release formula from ${backupPath}`);
+}
+
+let content = readFileSync(formulaPath, "utf8");
+if (content.includes("file://")) {
+  process.stderr.write(
+    `Dev formula still present at ${formulaPath}. Run: git restore ${formulaPath}\n`,
+  );
+  process.exit(1);
+}
+
+const version = content.match(/^\s*version\s+"([^"]+)"/m)?.[1];
+const sha256 = content.match(/^\s*sha256\s+"([^"]+)"/m)?.[1];
+if (!version || !sha256) {
+  process.stderr.write(`Could not parse version/sha256 from ${formulaPath}\n`);
+  process.exit(1);
+}
+
+const normalized = renderReleaseFormula(version, sha256);
+if (content !== normalized) {
+  writeFileSync(formulaPath, normalized, "utf8");
+  console.log(`Normalized ${formulaPath} (v${version})`);
+} else {
+  console.log(`Release formula OK: ${formulaPath} (v${version})`);
+}

package/examples/full-example/scripts/gen-dev-formula.ts

@@ -1,26 +1,7 @@
 #!/usr/bin/env bun
-/** Generate Formula/full-example.rb for local dev install (same formula as release; file:// URL only). */
+/** Generate Formula/full-example.rb for local dev install (file:// URL). Prefer `with-dev-formula.ts` via `just install-local`. */
 
-import { createHash } from "node:crypto";
-import { chmodSync, copyFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { createIdentity } from "./create-identity.ts";
-import { renderDevFormula } from "./formula-shared.ts";
+import { releaseFormulaPath, writeDevFormula } from "./dev-formula.ts";
 
-const { key } = createIdentity;
-const root = join(import.meta.dir, "..");
-const distPath = join(root, "dist", key);
-const stagingDir = join(root, "Formula", ".staging");
-const stagingPath = join(stagingDir, key);
-
-mkdirSync(stagingDir, { recursive: true });
-copyFileSync(distPath, stagingPath);
-chmodSync(stagingPath, 0o755);
-
-const binary = readFileSync(stagingPath);
-const sha256 = createHash("sha256").update(binary).digest("hex");
-const version = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version as string;
-
-const out = join(root, "Formula", `${key}.rb`);
-writeFileSync(out, renderDevFormula(stagingPath, version, sha256), "utf8");
-console.log(`Wrote ${out}`);
+writeDevFormula();
+console.log(`Wrote ${releaseFormulaPath()}`);

package/examples/full-example/scripts/with-dev-formula.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env bun
+/** Back up release formula, write dev formula, run a command, then restore. Usage: bun scripts/with-dev-formula.ts -- brew install … */
+
+import { spawnSync } from "node:child_process";
+import { backupReleaseFormula, releaseFormulaPath, restoreReleaseFormula, writeDevFormula } from "./dev-formula.ts";
+
+const sep = process.argv.indexOf("--");
+if (sep === -1 || sep === process.argv.length - 1) {
+  process.stderr.write("Usage: bun scripts/with-dev-formula.ts -- <command...>\n");
+  process.exit(1);
+}
+
+const cmd = process.argv.slice(sep + 1);
+let restored = false;
+
+function restore(): void {
+  if (restored) {
+    return;
+  }
+  restored = true;
+  restoreReleaseFormula();
+}
+
+try {
+  backupReleaseFormula();
+  writeDevFormula();
+  const result = spawnSync(cmd[0], cmd.slice(1), { stdio: "inherit" });
+  process.exitCode = result.status === null ? 1 : result.status;
+} finally {
+  restore();
+}
+
+if (process.exitCode === 0) {
+  console.log(`Restored ${releaseFormulaPath()}`);
+}

package/package.json

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

package/examples/full-example/scripts/ensure-brew-github-token.sh

@@ -1,10 +0,0 @@
-#!/usr/bin/env bash
-# Ensure HOMEBREW_GITHUB_API_TOKEN is set for private GitHub release downloads.
-: "${HOMEBREW_GITHUB_API_TOKEN:=$(gh auth token 2>/dev/null || true)}"
-if [[ -z "${HOMEBREW_GITHUB_API_TOKEN}" ]]; then
-  echo "HOMEBREW_GITHUB_API_TOKEN is required to download private GitHub release assets." >&2
-  echo "Use: HOMEBREW_GITHUB_API_TOKEN=\"\$(gh auth token)\" (if gh is installed)" >&2
-  echo "Or create a PAT at https://github.com/settings/personal-access-tokens/new (Contents read on the tap repo)." >&2
-  exit 1
-fi
-export HOMEBREW_GITHUB_API_TOKEN