argsbarg 5.1.2 → 5.1.3

package/CHANGELOG.md

@@ -7,11 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.1.3] - 2026-07-04
+
+
 ## [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`.
+- **Homebrew install docs** — README template and consumer READMEs document private-tap install; `configure` CLI notes stay post-install only.
 
 ## [5.1.1] - 2026-07-04
 
@@ -601,7 +605,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.2...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v5.1.3...HEAD
+[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
 [5.1.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v5.1.0

package/README.md

@@ -112,11 +112,11 @@ See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom
 
 ### Configure CLI
 
-Ship via **Homebrew** (tap-from-repo). The formula installs the binary and shell completions; `post_install` runs agent artifact refresh:
+Ship via **Homebrew** (tap-from-repo). The formula installs the binary and shell completions; `post_install` runs agent artifact refresh. Private taps need `HOMEBREW_GITHUB_API_TOKEN` on install — see [docs/distribution-homebrew.md](docs/distribution-homebrew.md#end-user-install).
 
 ```bash
-brew tap <org>/<repo>
-brew install <tap>/myapp
+brew tap <org>/<repo> git@github.com:<org>/<repo>.git
+HOMEBREW_GITHUB_API_TOKEN="$(gh auth token)" brew install <tap>/myapp
 myapp configure    # interactive per-target setup; opt-in app config wizard
 ```
 
@@ -224,7 +224,51 @@ Check the `examples/` directory for full working scripts:
 | `ArgsBargFullExample` | `examples/full-example/` | **Copy template:** all builtins, schemagen, Homebrew justfile, `outputSchema`, `from "argsbarg"`. |
 
 
-Examples ship in the npm package under `node_modules/argsbarg/examples/`. Bootstrap a production CLI with `bunx argsbarg create my-cli`.
+Examples ship in the npm package under `node_modules/argsbarg/examples/`.
+
+## Bootstrap a new CLI
+
+Copy the shipped `examples/full-example` template into a new directory:
+
+Interactive (TTY):
+
+```bash
+bunx argsbarg create my-cli
+```
+
+Non-interactive:
+
+```bash
+bunx argsbarg create my-cli \
+  --key my-cli --release-repo org/my-cli --yes
+```
+
+Edit `scripts/create-identity.ts` in the new repo to set `desc` (used by `program.description` and the Homebrew formula).
+
+`create` copies the template (including `.cursor/rules/cli-program.mdc`), substitutes `{key}` / `{tap}` / `{releaseRepo}` placeholders in `README.md` and other files, runs `bun install`, schemagen, `bun test`, and `git init` + Initial commit when appropriate.
+
+**Git bootstrap:** skipped when the target already has a `.git` directory, or when the target sits inside an existing git work tree (monorepo subfolder). Standalone new directories get an `Initial commit`.
+
+Verify an existing tree: `bunx argsbarg create --check .`
+
+To refresh the Cursor rule in an existing consumer: `bun scripts/merge-cli-program-rule.ts .` from an argsbarg checkout (or pass the npm package path to the template).
+
+### What the full-example template includes
+
+| Area | Files / wiring |
+| --- | --- |
+| All builtins | `completion`, `version`, `configure`, `docs`, `mcp`, `configure get`/`set` |
+| `program.appConfig` | `src/types.ts` (`AppConfig`) → `schemas/configSchemas.ts` |
+| `outputSchema` | `src/commands/status/types.ts` → `schemas/outputSchemas.ts` |
+| Schemagen | `scripts/schemagen.ts` + `scripts/schemagen/discover-schema-roots.ts` |
+| 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/gen-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` |
+
+When changing builtins or the template, run `just check-full-example` from the argsbarg repo root.
 
 ```bash
 export PATH="$PATH:$(pwd)/examples"
@@ -240,7 +284,7 @@ nested.ts read ./README.md
 bun ./examples/formats.ts run --tags demo,docs --on 2026-06-22
 
 cd examples/full-example && just setup && just schemagen
-FULL_EXAMPLE_API_TOKEN=dev just run status --json
+just run status --json
 ```
 
 

package/docs/configure.md

@@ -6,15 +6,15 @@ Opt out with `configure: { enabled: false }` on the program root.
 
 ## End-user install (Homebrew)
 
+Private GitHub release downloads require `HOMEBREW_GITHUB_API_TOKEN` on `brew install` and `brew upgrade`. See [distribution-homebrew.md](distribution-homebrew.md#end-user-install) for token setup (`gh auth token` or a personal access token with **Contents** read).
+
 ```bash
-brew tap <org>/<repo>
-brew install <tap>/<key>
+brew tap <org>/<repo> git@github.com:<org>/<repo>.git
+HOMEBREW_GITHUB_API_TOKEN="$(gh auth token)" brew install <tap>/<key>
 <key> configure    # interactive: per-target prompts; run when app config is required
 ```
 
-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).
+Upgrade with `HOMEBREW_GITHUB_API_TOKEN="$(gh auth token)" 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).
 
 **Uninstall the binary:** remove agent artifacts first (while the CLI is still on PATH), then `brew uninstall`:
 

package/docs/distribution-homebrew.md

@@ -14,18 +14,30 @@ Argsbarg apps distribute the **binary and shell completions** through Homebrew,
 
 ### End-user install
 
+For **private or internal GitHub taps**, prepend `HOMEBREW_GITHUB_API_TOKEN` on `brew install` and `brew upgrade` (release formulae download via the GitHub API).
+
+If [GitHub CLI](https://cli.github.com/) is installed:
+
 ```bash
-brew tap <org>/<repo>
-brew install <tap>/{key}
+brew tap <org>/<repo> git@github.com:<org>/<repo>.git
+HOMEBREW_GITHUB_API_TOKEN="$(gh auth token)" 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`):
+Without `gh`, create a personal access token at [github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new):
+
+- Resource owner — your org (e.g. sqsp)
+- Repository access — the tap repo or all repositories
+- Permissions — **Contents** (read-only)
 
 ```bash
-export HOMEBREW_GITHUB_API_TOKEN="$(gh auth token)"
-brew tap <org>/<repo> git@github.com:<org>/<repo>.git
-brew install <tap>/{key}
+HOMEBREW_GITHUB_API_TOKEN=YOUR_TOKEN brew install <tap>/{key}
+```
+
+Upgrade:
+
+```bash
+HOMEBREW_GITHUB_API_TOKEN="$(gh auth token)" brew upgrade {key}
 ```
 
 Local dev installs (`just install-local`) use a `file://` staging URL and do not need the token.

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-manager**, **idp-trees**, **poc-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-poc**, **idp-trees**, **sqsp-i18n-tools-poc** (see each repo’s `docs/architecture.md` for which commands use which schema root).
 
 ```mermaid
 flowchart LR

package/examples/full-example/README.md

@@ -1,77 +1,69 @@
 # full-example
 
-**Full argsbarg reference app** — bootstrap new production CLIs with `bunx argsbarg create`.
+Argsbarg full example reference app
 
-## What this demonstrates
+## Quick start
 
-| Area | Files / wiring |
-| --- | --- |
-| All builtins | `completion`, `version`, `configure`, `docs`, `mcp`, `configure get`/`set` |
-| `program.appConfig` | `src/types.ts` (`AppConfig`) → `schemas/configSchemas.ts` |
-| `outputSchema` | `src/commands/status/types.ts` (`StatusJsonOutput`) → `schemas/outputSchemas.ts` |
-| Schemagen | `scripts/schemagen.ts` + `scripts/schemagen/discover-schema-roots.ts` |
-| 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/gen-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` |
-
-## Bootstrap a new CLI
-
-Interactive (TTY):
+From a git checkout at this directory (requires [Homebrew](https://brew.sh), [just](https://just.systems), and [Bun](https://bun.sh)):
 
 ```bash
-bunx argsbarg create my-cli
+brew install just bun
+just setup
+just schemagen   # after changing src/**/types.ts
+just run status --json
+just run docs readme
 ```
 
-Non-interactive:
-
-```bash
-bunx argsbarg create my-cli \
-  --key my-cli --release-repo org/my-cli --yes
-```
+Run `full-example configure` when the app needs secrets or other app config (interactive wizard).
 
-Edit `scripts/create-identity.ts` to set `desc` (used by `program.description` and the Homebrew formula).
+## Install
 
-`create` copies this template (including `.cursor/rules/cli-program.mdc`), substitutes identity placeholders, runs `bun install`, schemagen, `bun test`, and `git init` + Initial commit when appropriate.
+Requires [Homebrew](https://brew.sh).
 
-**Git bootstrap:** skipped when `{target}/.git` already exists, or when the target is inside an existing git work tree (monorepo subfolder). Standalone new directories get `Initial commit`.
+### End users
 
-To refresh the Cursor rule in an existing consumer: `bun scripts/merge-cli-program-rule.ts .` from an argsbarg checkout (or pass the npm package path to the template).
+Private GitHub release downloads require `HOMEBREW_GITHUB_API_TOKEN` on `brew install` and `brew upgrade`.
 
-## Quick start (in this repo)
+If [GitHub CLI](https://cli.github.com/) is installed:
 
 ```bash
-cd examples/full-example
-just setup
-just schemagen   # after changing src/**/types.ts
-FULL_EXAMPLE_API_TOKEN=dev just run status --json
-FULL_EXAMPLE_API_TOKEN=dev just run configure get apiToken --json
-FULL_EXAMPLE_API_TOKEN=dev just run docs readme
+brew tap bdombro/bun-argsbarg git@github.com:bdombro/bun-argsbarg.git
+HOMEBREW_GITHUB_API_TOKEN="$(gh auth token)" brew install bdombro/bun-argsbarg/full-example
+full-example configure
 ```
 
-## Homebrew dev install
+Without `gh`, create a personal access token at [github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new):
 
-Requires [Homebrew](https://brew.sh) and a compiled binary at `dist/full-example`:
+- Resource owner — your org
+- Repository access — this repo (or all repositories)
+- Permissions — **Contents** (read-only)
 
 ```bash
-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 (needs HOMEBREW_GITHUB_API_TOKEN for private repos)
-just test-release               # same token requirement when formula uses a GitHub release URL
+HOMEBREW_GITHUB_API_TOKEN=YOUR_TOKEN brew install bdombro/bun-argsbarg/full-example
 ```
 
-Undo a local dev install:
+Upgrade:
 
 ```bash
-just uninstall          # dev formula + agent artifacts
-just uninstall-config   # app config only
-just uninstall-release  # release formula (keeps tap)
+HOMEBREW_GITHUB_API_TOKEN="$(gh auth token)" brew upgrade full-example
 ```
 
-See [docs/distribution-homebrew.md](../../docs/distribution-homebrew.md).
+Shell completions install during `brew install`. See [Homebrew Shell Completion](https://docs.brew.sh/Shell-Completion).
+
+### Developers
+
+Requires [Homebrew](https://brew.sh), [just](https://just.systems), and [Bun](https://bun.sh). From the repository root (this directory — the folder with `justfile` and `Formula/`):
+
+```bash
+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 test-release
+```
+
+Undo a local dev install: `just uninstall` (formula + agent artifacts), `just uninstall-config` (app config only).
 
 ## Schemagen markers
 
@@ -84,15 +76,8 @@ Discovery walks `src/**/types.ts` only.
 
 ## Environment
 
+Optional overrides for `program.appConfig` (the configure wizard is the usual path):
+
 | Variable | Purpose |
 | --- | --- |
-| `FULL_EXAMPLE_API_TOKEN` | Overrides `apiToken` via `program.appConfig` env mapping |
-
-## Maintainers (argsbarg repo)
-
-When adding or changing builtins, update this example and run:
-
-```bash
-just check-full-example   # from argsbarg repo root
-just test                 # from examples/full-example
-```
+| `FULL_EXAMPLE_API_TOKEN` | Overrides `apiToken` when set in the shell |

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

@@ -3,7 +3,7 @@
 export const createIdentity = {
   key: "full-example",
   className: "FullExample",
-  tap: "local/full-example",
+  tap: "bdombro/bun-argsbarg",
   homepage: "https://github.com/bdombro/bun-argsbarg",
   releaseRepo: "bdombro/bun-argsbarg",
   desc: "Argsbarg full example reference app",

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

@@ -3,7 +3,8 @@
 : "${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
+  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

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

@@ -47,8 +47,6 @@ export const githubPrivateReleaseDownloadStrategyRuby = `  class GitHubPrivateRe
       @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",
@@ -56,6 +54,8 @@ export const githubPrivateReleaseDownloadStrategyRuby = `  class GitHubPrivateRe
                     to: temporary_path
     end
 
+    private
+
     def resolved_download_url
       @resolved_download_url ||= begin
         asset = GitHub.get_release(@owner, @repo, @tag).fetch("assets")
@@ -82,14 +82,13 @@ export function releaseFormulaUrl(version: string): string {
 }
 
 export function renderFormula(coords: FormulaCoords): string {
-  const strategy = coords.privateRelease ? `${githubPrivateReleaseDownloadStrategyRuby}\n\n  ` : "";
+  const strategyBlock = coords.privateRelease ? `\n${githubPrivateReleaseDownloadStrategyRuby}\n\n  ` : "";
   return `class ${className} < Formula
-  ${strategy}desc "${desc}"
+  desc "${desc}"
   homepage "${homepage}"
-  ${coords.urlStanza}
   version "${coords.version}"
   sha256 "${coords.sha256}"
-{dependsOnBlock}
+
   ${formulaInstallRuby}
 
   ${formulaPostInstallRuby}
@@ -97,6 +96,7 @@ export function renderFormula(coords: FormulaCoords): string {
   ${formulaCaveatsRuby}
 
   ${formulaTestRuby}
+${strategyBlock}${coords.urlStanza}
 end
 `;
 }

package/package.json

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

package/src/builtins/builtins.test.ts

@@ -41,7 +41,8 @@ describe("builtins help copy", () => {
     const configure = cliBuiltinConfigureCommand(fixture);
     expect(configure.description).toContain("agent skills");
     expect(configure.description).toContain("MCP config");
-    expect(configure.notes).toContain("brew install");
+    expect(configure.notes).toContain("brew upgrade");
+    expect(configure.notes).not.toContain("HOMEBREW_GITHUB_API_TOKEN");
     const names = configureBuiltinOptions(fixture).map((o) => o.name);
     expect(names).toContain("sync");
     expect(names).toContain("remove-all");

package/src/builtins/configure-copy.ts

@@ -48,12 +48,10 @@ export function docsSkillTopicDescription(program: CliProgram, caps: CliCapabili
   return "Print a reference agent SKILL for AI agents.";
 }
 
-export function configureCommandNotes(program: CliProgram, caps: CliCapabilities): string {
+export function configureCommandNotes(program: CliProgram, _caps: CliCapabilities): string {
   const app = program.key;
   const lines = [
-    "Install the binary via Homebrew (tap-from-repo), then set up agent artifacts:",
-    `  brew tap <org>/<repo>`,
-    `  brew install <tap>/${app}`,
+    "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).",
     "",
     "Homebrew post_install runs:",
     `  ${app} configure --sync --yes`,

package/src/docs/api-guide.test.ts

@@ -66,7 +66,7 @@ test("generateApiGuide covers the same command keys as cliSchemaExport", () => {
   expect(schema.commands?.map((c) => c.key)).toEqual(["stat"]);
 });
 
-test("generateApiGuide resolves program key in install notes", () => {
+test("generateApiGuide configure notes point to README not brew install", () => {
   const fixture: CliProgram = {
     key: "myapp",
     version: "1.0.0",
@@ -75,7 +75,8 @@ test("generateApiGuide resolves program key in install notes", () => {
   };
   const md = generateApiGuide(fixture);
   expect(md).not.toContain("{argsbarg:program}");
-  expect(md).toContain("brew install");
+  expect(md).toContain("README");
+  expect(md).not.toContain("brew install <tap>");
   expect(md).not.toContain("Upgrade to latest release");
 });
 

package/src/parse.test.ts

@@ -617,8 +617,8 @@ test("cliSchemaJson omits handlers and completion built-ins", () => {
   expect(schema).not.toHaveProperty("handler");
 });
 
-/** CliSchemaExport resolves program key in install notes. */
-test("cliSchemaExport resolves program key in install notes", () => {
+/** CliSchemaExport configure notes reference README for install. */
+test("cliSchemaExport configure notes reference README for install", () => {
   const root = testProgram({
     key: "myapp",
     version: "1.0.0",
@@ -634,7 +634,8 @@ test("cliSchemaExport resolves program key in install notes", () => {
 
   const json = cliSchemaJson(root);
   expect(json).not.toContain("{argsbarg:program}");
-  expect(json).toContain("brew install");
+  expect(json).toContain("README");
+  expect(json).not.toContain("brew install <tap>");
 });
 
 /** CliSchemaExport resolves {argsbarg:program} in consumer notes. */