argsbarg 5.1.10 → 5.1.12

package/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.1.12] - 2026-07-05
+
+### Changed
+
+- **`scripts/dev-formula.ts`** — `install` stages a `file://` dev formula; `reset` restores the release formula. `just install-local` orchestrates stage → `brew install` → reset.
+
+## [5.1.11] - 2026-07-05
+
+
 ## [5.1.10] - 2026-07-05
 
 ### Added
@@ -656,7 +665,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.10...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v5.1.12...HEAD
+[5.1.12]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.12
+[5.1.11]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.11
 [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

package/README.md

@@ -266,7 +266,7 @@ To refresh the Cursor rule in an existing consumer: `bun scripts/merge-cli-progr
 | Command layout | `src/commands/<name>/command.ts`; registration in `src/program.ts` |
 | MCP doc topics | `docs.topics` auto-exposed as `<key>://docs/<topic>` resources when docs + MCP enabled |
 | Package import | `from "argsbarg"` (not relative to argsbarg `src/`) |
-| Homebrew distribution | `scripts/formula-shared.ts`, `scripts/with-dev-formula.ts`, `Formula/`, `justfile` |
+| Homebrew distribution | `scripts/formula-shared.ts`, `scripts/dev-formula.ts`, `Formula/`, `justfile` |
 | Dev tooling | Biome (`just format` / `just lint`), TypeScript, colocated tests |
 | Cursor rules | `.cursor/rules/cli-program.mdc`, `.cursor/rules/code.mdc` |
 

package/docs/distribution-homebrew.md

@@ -48,7 +48,15 @@ just reinstall-local   # fast binary swap (`install -m 755` into Cellar; run ins
 just uninstall        # undo formula + agent artifacts (app config removed by formula uninstall)
 ```
 
-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`.
+Dev and release use the **same formula file** (`Formula/{key}.rb`). `just install-local` runs:
+
+```bash
+bun scripts/dev-formula.ts install    # back up release formula, write file:// dev formula
+brew install --formula <tap>/{key}  # install from the dev formula
+bun scripts/dev-formula.ts reset      # restore release formula
+```
+
+If `brew install` fails, run `bun scripts/dev-formula.ts reset` manually to restore the release formula.
 
 ### Developer uninstall
 

package/examples/full-example/justfile

@@ -45,12 +45,14 @@ install: install-local
 sync-artifacts:
     just run configure --sync --yes
 
-# Dev install: build, dev formula (restored after brew), symlink tap, brew install
+# Dev install: build, stage dev formula, brew install, restore release formula
 install-local: build
     @brew untap {{tap}} 2>/dev/null || true
     mkdir -p {{tap_parent}}
     ln -sfn '{{justfile_directory()}}' {{tap_path}}
-    bun scripts/with-dev-formula.ts -- brew install --formula {{tap}}/{{cli_key}}
+    bun scripts/dev-formula.ts install
+    brew install --formula {{tap}}/{{cli_key}}
+    bun scripts/dev-formula.ts reset
     @echo ""
     @echo "Next: {{cli_key}} configure"
 

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

@@ -0,0 +1,97 @@
+#!/usr/bin/env bun
+/**
+ * Stage or restore the dev Homebrew formula for `just install-local`.
+ * `install` — back up release `Formula/{key}.rb` and write a `file://` dev formula.
+ * `reset` — restore the release formula from backup.
+ */
+
+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`);
+const programPath = join(root, "src/program.ts");
+
+type Command = "install" | "reset";
+
+function usage(): never {
+  process.stderr.write("Usage: bun scripts/dev-formula.ts <install|reset>\n");
+  process.exit(1);
+}
+
+function parseCommand(argv: string[]): Command {
+  const cmd = argv[2];
+  if (cmd === "install" || cmd === "reset") {
+    return cmd;
+  }
+  usage();
+}
+
+function backupReleaseFormula(): void {
+  if (!existsSync(formulaPath)) {
+    return;
+  }
+  mkdirSync(stagingDir, { recursive: true });
+  copyFileSync(formulaPath, backupPath);
+}
+
+function restoreReleaseFormula(): void {
+  if (!existsSync(backupPath)) {
+    return;
+  }
+  copyFileSync(backupPath, formulaPath);
+  unlinkSync(backupPath);
+}
+
+function readVersion(): string {
+  const content = readFileSync(programPath, "utf8");
+  const match = /version:\s*"([^"]+)"/.exec(content);
+  if (!match?.[1]) {
+    process.stderr.write(`Could not read version from ${programPath}\n`);
+    process.exit(1);
+  }
+  return match[1];
+}
+
+function stageDevFormula(): void {
+  const distPath = join(root, "dist", key);
+  if (!existsSync(distPath)) {
+    process.stderr.write(`Missing binary: ${distPath} (run just build first)\n`);
+    process.exit(1);
+  }
+  mkdirSync(stagingDir, { recursive: true });
+  copyFileSync(distPath, stagingPath);
+  chmodSync(stagingPath, 0o755);
+
+  const sha256 = createHash("sha256").update(readFileSync(stagingPath)).digest("hex");
+  writeFileSync(formulaPath, renderDevFormula(stagingPath, readVersion(), sha256), "utf8");
+}
+
+function install(): void {
+  backupReleaseFormula();
+  stageDevFormula();
+  console.log(`Wrote dev formula: ${formulaPath}`);
+}
+
+function reset(): void {
+  if (!existsSync(backupPath)) {
+    console.log("No dev formula backup to restore.");
+    return;
+  }
+  restoreReleaseFormula();
+  console.log(`Restored ${formulaPath}`);
+}
+
+const command = parseCommand(process.argv);
+if (command === "install") {
+  install();
+} else {
+  reset();
+}

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

@@ -29,15 +29,19 @@ function generateJson(root: SchemaRoot): Record<string, unknown> {
 }
 
 function writeBridge(path: string, scriptName: string, roots: SchemaRoot[], banner: string): void {
+  /** Sort by import binding so Biome `organizeImports` does not reorder the bridge file. */
+  const sorted = [...roots].sort((left, right) =>
+    jsonImportVar(left.outfile).localeCompare(jsonImportVar(right.outfile)),
+  );
   const lines = [`// Auto-generated by scripts/${scriptName} — do not edit by hand.`, ""];
-  for (const root of roots) {
+  for (const root of sorted) {
     const varName = jsonImportVar(root.outfile);
     lines.push(`import ${varName} from "./generated/${root.outfile}";`);
   }
-  if (roots.length > 0) {
+  if (sorted.length > 0) {
     lines.push("");
   }
-  for (const root of roots) {
+  for (const root of sorted) {
     const varName = jsonImportVar(root.outfile);
     lines.push(`/** ${banner} \`${root.typeName}\`. */`);
     lines.push(`export const ${root.exportName} = ${varName} as Record<string, unknown>;`);

package/package.json

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

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

@@ -1,79 +0,0 @@
-#!/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 { 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`);
-
-function backupReleaseFormula(): void {
-  if (!existsSync(formulaPath)) {
-    return;
-  }
-  mkdirSync(stagingDir, { recursive: true });
-  copyFileSync(formulaPath, backupPath);
-}
-
-function restoreReleaseFormula(): void {
-  if (!existsSync(backupPath)) {
-    return;
-  }
-  copyFileSync(backupPath, formulaPath);
-  unlinkSync(backupPath);
-}
-
-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");
-}
-
-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);
-const executable = cmd[0];
-if (!executable) {
-  process.stderr.write("Usage: bun scripts/with-dev-formula.ts -- <command...>\n");
-  process.exit(1);
-}
-let restored = false;
-
-function restore(): void {
-  if (restored) {
-    return;
-  }
-  restored = true;
-  restoreReleaseFormula();
-}
-
-try {
-  backupReleaseFormula();
-  writeDevFormula();
-  const result = spawnSync(executable, cmd.slice(1), { stdio: "inherit" });
-  process.exitCode = result.status === null ? 1 : result.status;
-} finally {
-  restore();
-}
-
-if (process.exitCode === 0) {
-  console.log(`Restored ${formulaPath}`);
-}