argsbarg 5.1.1 → 5.1.2

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.1.2] - 2026-07-04
+
+### Changed
+
+- **Private GitHub release installs** — release formulae use `GitHubPrivateReleaseDownloadStrategy` (GitHub API + `GitHub::API.credentials` / `HOMEBREW_GITHUB_API_TOKEN`); `just install-production` and `just test-release` export the token (with `gh auth token` fallback). Documented in `docs/distribution-homebrew.md`.
+
 ## [5.1.1] - 2026-07-04
 
 ### Fixed
@@ -595,7 +601,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.1...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v5.1.2...HEAD
+[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
 [5.1.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.0
 [5.0.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.0.3

package/docs/configure.md

@@ -14,6 +14,8 @@ brew install <tap>/<key>
 
 Upgrade with `brew upgrade <key>`. Shell completions are installed by Homebrew during `brew install`. Users must configure their shell per [Homebrew Shell Completion](https://docs.brew.sh/Shell-Completion).
 
+Private GitHub release assets require `HOMEBREW_GITHUB_API_TOKEN` at install time — see [distribution-homebrew.md](distribution-homebrew.md#end-user-install).
+
 **Uninstall the binary:** remove agent artifacts first (while the CLI is still on PATH), then `brew uninstall`:
 
 ```bash

package/docs/distribution-homebrew.md

@@ -20,6 +20,16 @@ brew install <tap>/{key}
 {key} configure   # when app config is required
 ```
 
+For **private or internal GitHub repos**, release formulae attach `HOMEBREW_GITHUB_API_TOKEN` when downloading the binary. Export a PAT with `repo` scope (or rely on `gh auth login` — `just install-production` and `just test-release` fall back to `gh auth token`):
+
+```bash
+export HOMEBREW_GITHUB_API_TOKEN="$(gh auth token)"
+brew tap <org>/<repo> git@github.com:<org>/<repo>.git
+brew install <tap>/{key}
+```
+
+Local dev installs (`just install-local`) use a `file://` staging URL and do not need the token.
+
 ### Developer install
 
 ```bash
@@ -56,6 +66,15 @@ def post_install
 end
 ```
 
+Release formulae generated by `scripts/formula-shared.ts` embed a `GitHubPrivateReleaseDownloadStrategy` that resolves the release asset through the GitHub API at download time and authenticates with `GitHub::API.credentials` (backed by `HOMEBREW_GITHUB_API_TOKEN`, `gh auth`, or other Homebrew GitHub credential sources):
+
+```ruby
+url "https://github.com/<org>/<repo>/releases/download/vX.Y.Z/{key}",
+    using: GitHubPrivateReleaseDownloadStrategy
+```
+
+Local dev formulae (`just install-local`) use a plain `file://` URL and do not need the token.
+
 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.

package/docs/output-schema.md

@@ -43,7 +43,7 @@ Production CLIs with several JSON commands tend to use **codegen** so types, han
 
 ## Recommended pipeline (copy per repo)
 
-No shared npm package — each app copies the same **contract**. Reference implementations: **sqsp-qa-tools**, **idp-trees**, **sqsp-i18n-tools** (see each repo’s `docs/architecture.md` for which commands use which schema root).
+No shared npm package — each app copies the same **contract**. Reference implementations: **sqsp-qa-manager**, **idp-trees**, **poc-sqsp-i18n-tools** (see each repo’s `docs/architecture.md` for which commands use which schema root).
 
 ```mermaid
 flowchart LR

package/examples/full-example/README.md

@@ -59,8 +59,8 @@ Requires [Homebrew](https://brew.sh) and a compiled binary at `dist/full-example
 just build
 just install-local              # first-time dev formula (`just install` is an alias)
 just reinstall-local            # fast binary swap during development
-just install-production         # uninstall local dev, install from GitHub tap
-just test-release
+just install-production         # uninstall local dev, install from GitHub tap (needs HOMEBREW_GITHUB_API_TOKEN for private repos)
+just test-release               # same token requirement when formula uses a GitHub release URL
 ```
 
 Undo a local dev install:

package/examples/full-example/justfile

@@ -8,6 +8,8 @@ cli_key := `bun scripts/print-identity.ts key`
 tap_org := `bun scripts/print-identity.ts tapOrg`
 tap_repo := `bun scripts/print-identity.ts tapRepo`
 tap := `bun scripts/print-identity.ts tap`
+release_repo := `bun scripts/print-identity.ts releaseRepo`
+tap_git_url := "git@github.com:" + release_repo + ".git"
 brew_prefix := `brew --prefix`
 tap_parent := brew_prefix + "/Library/Taps/" + tap_org
 tap_path := tap_parent + "/homebrew-" + tap_repo
@@ -59,12 +61,15 @@ install-local: build
     @echo ""
     @echo "Next: {{cli_key}} configure"
 
-# Remove local dev install, then install from GitHub tap
+# Remove local dev install, then install from GitHub tap (private release assets need HOMEBREW_GITHUB_API_TOKEN)
 install-production: uninstall
-    brew tap {{tap}}
-    brew install --formula {{tap}}/{{cli_key}}
-    @echo ""
-    @echo "Next: {{cli_key}} configure"
+    #!/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"
 
 # Alias for backward compatibility
 reinstall: reinstall-local
@@ -96,10 +101,13 @@ test: check
 
 # Install release formula from tap and run formula test
 test-release:
-    @brew untap {{tap}} 2>/dev/null || true
+    #!/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}}
-    @brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
+    brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
     brew install --formula {{tap}}/{{cli_key}}
     brew test {{cli_key}}
 

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

@@ -0,0 +1,9 @@
+#!/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 "Export a GitHub PAT with repo scope, or run: gh auth login" >&2
+  exit 1
+fi
+export HOMEBREW_GITHUB_API_TOKEN

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

@@ -30,8 +30,51 @@ export const formulaTestRuby = `test do
 
 export interface FormulaCoords {
   url: string;
+  urlStanza: string;
   version: string;
   sha256: string;
+  /** When true, embed {@link githubPrivateReleaseDownloadStrategyRuby} in the formula class. */
+  privateRelease?: boolean;
+}
+
+/** Resolves private GitHub release assets via the API at download time. */
+export const githubPrivateReleaseDownloadStrategyRuby = `  class GitHubPrivateReleaseDownloadStrategy < CurlDownloadStrategy
+    def initialize(url, name, version, **meta)
+      super
+      pattern = %r{https://github\\.com/([^/]+)/([^/]+)/releases/download/([^/]+)/(\\S+)}
+      match = url.match(pattern)
+      raise CurlDownloadStrategyError, "Invalid GitHub release URL: #{url}" unless match
+      @owner, @repo, @tag, @filename = match.captures
+    end
+
+    private
+
+    def _fetch(url:, resolved_url: resolved_download_url, timeout:)
+      curl_download resolved_download_url,
+                    "--header", "Accept: application/octet-stream",
+                    "--header", "Authorization: Bearer #{GitHub::API.credentials}",
+                    to: temporary_path
+    end
+
+    def resolved_download_url
+      @resolved_download_url ||= begin
+        asset = GitHub.get_release(@owner, @repo, @tag).fetch("assets")
+          .find { |a| a["name"] == @filename }
+        raise CurlDownloadStrategyError, "Release asset not found: #{@filename}" unless asset
+        asset.fetch("url")
+      end
+    end
+  end`;
+
+/** Homebrew `url` for local dev staging paths. */
+export function devUrlStanza(url: string): string {
+  return `url "${url}"`;
+}
+
+/** Homebrew `url` for GitHub release assets (uses {@link githubPrivateReleaseDownloadStrategyRuby}). */
+export function releaseUrlStanza(url: string): string {
+  return `url "${url}",
+      using: GitHubPrivateReleaseDownloadStrategy`;
 }
 
 export function releaseFormulaUrl(version: string): string {
@@ -39,10 +82,11 @@ export function releaseFormulaUrl(version: string): string {
 }
 
 export function renderFormula(coords: FormulaCoords): string {
+  const strategy = coords.privateRelease ? `${githubPrivateReleaseDownloadStrategyRuby}\n\n  ` : "";
   return `class ${className} < Formula
-  desc "${desc}"
+  ${strategy}desc "${desc}"
   homepage "${homepage}"
-  url "${coords.url}"
+  ${coords.urlStanza}
   version "${coords.version}"
   sha256 "${coords.sha256}"
 {dependsOnBlock}
@@ -58,16 +102,21 @@ end
 }
 
 export function renderReleaseFormula(version: string, sha256: string): string {
+  const url = releaseFormulaUrl(version);
   return renderFormula({
-    url: releaseFormulaUrl(version),
+    url,
+    urlStanza: releaseUrlStanza(url),
     version,
     sha256,
+    privateRelease: true,
   });
 }
 
 export function renderDevFormula(stagingPath: string, version: string, sha256: string): string {
+  const url = `file://${stagingPath}`;
   return renderFormula({
-    url: `file://${stagingPath}`,
+    url,
+    urlStanza: devUrlStanza(url),
     version,
     sha256,
   });

package/examples/full-example/scripts/print-identity.ts

@@ -5,7 +5,7 @@ import { createIdentity } from "./create-identity.ts";
 
 const field = process.argv[2];
 if (!field) {
-  console.error("Usage: bun scripts/print-identity.ts <key|className|tap|tapOrg|tapRepo|envPrefix>");
+  console.error("Usage: bun scripts/print-identity.ts <key|className|tap|tapOrg|tapRepo|releaseRepo|envPrefix>");
   process.exit(1);
 }
 
@@ -17,6 +17,7 @@ const values: Record<string, string> = {
   tapOrg: tapOrg ?? "",
   tapRepo: tapRepo ?? "",
   envPrefix: createIdentity.envPrefix,
+  releaseRepo: createIdentity.releaseRepo,
 };
 
 const value = values[field];

package/package.json

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