opencode-homebrew-agent 1.0.0

package/src/templates/taps/02-root-level/tap-structure/README.md

@@ -0,0 +1,27 @@
+# <Tap Name>
+
+Homebrew tap for <formula>.
+
+## Install
+
+```sh
+brew tap <user>/<tapname>
+brew install <formula>
+```
+
+## Upgrade
+
+```sh
+brew upgrade <formula>
+```
+
+## Uninstall
+
+```sh
+brew uninstall <formula>
+brew untap <user>/<tapname>
+```
+
+## License
+
+MIT

package/src/templates/taps/02-root-level/tap-structure/_formula.rb

@@ -0,0 +1,29 @@
+
+# Root-level formula — place this file at the repository root.
+# Replace <formula>, <description>, <url>, <sha256> with real values.
+# IMPORTANT: Rename class <Formula> to CamelCase matching the filename (e.g., MyTool for my-tool.rb).
+
+class <Formula> < Formula
+  desc "<one-line description>"
+  homepage "https://github.com/<user>/<repo>"
+  url "https://github.com/<user>/<repo>/archive/refs/tags/v<version>.tar.gz"
+  sha256 "<sha256>"
+  version "<version>"
+  license "MIT"
+
+  livecheck do
+    url :stable
+    regex(/^v?(\d+(?:\.\d+)+)$/i)
+  end
+
+  depends_on "<dep>"
+
+  def install
+    system "<build-command>"
+    bin.install "<binary>"
+  end
+
+  test do
+    assert_match "<expected>", shell_output("#{bin}/<cli> --help")
+  end
+end

package/src/templates/taps/02-root-level/template.md

@@ -0,0 +1,35 @@
+# Template 02: Root-Level `.rb`
+
+## Pattern: `yakitrak/homebrew-yakitrak`
+
+A minimal tap with formula files at the repository root. No `Formula/`
+subdirectory, no CI, no scripts. Best for **1-2 formula taps** where
+simplicity is king.
+
+### Structure
+
+```
+homebrew-<tap>/
+├── <formula>.rb           # Formula at root (no Formula/ dir)
+├── LICENSE
+└── README.md
+```
+
+### When to Use
+
+- You have 1-2 simple formulae
+- You don't need CI in the tap
+- You want the absolute minimum structure
+
+### When NOT to Use
+
+- You need CI/bottle workflows (use template 01)
+- You need script-driven releases (use template 03)
+- You need Python virtualenv deps (use template 04)
+
+### Reference
+
+- `brew install <user>/<tap>/<formula>` works regardless of file location
+- Homebrew scans root, `Formula/`, and `HomebrewFormula/` for `.rb` files
+
+- Start with `brew tap-new <user>/homebrew-<tapname>` to generate the CI skeleton (optional — manual structure works too)

package/src/templates/taps/03-simple-script/AGENTS.md

@@ -0,0 +1,71 @@
+---
+name: homebrew-tap-simple-script
+description: Creates and maintains lean Homebrew taps with script-driven release automation (oven-sh/homebrew-bun pattern).
+---
+
+# homebrew-tap-simple-script
+
+Agent for working with Simple + Script tap templates.
+
+## Description
+Helps create and maintain lean Homebrew taps with script-driven release automation and optional versioned formula aliases.
+
+## Stacks
+- homebrew
+- ruby
+- scripts
+
+## Requires
+- basic-homebrew-knowledge
+
+## Key Actions
+
+### Release Script Pattern
+The `scripts/release.rb` takes a version tag, fetches release assets, computes SHA256s, and rewrites the formula. Modeled on `oven-sh/homebrew-bun/scripts/release.rb`.
+
+### Versioned Formulae
+Optionally create `Formula/<formula>@X.Y.Z.rb` aliases by copying the main formula with a modified class name (e.g., `class BunAT1314` for version `1.3.14`).
+
+### Permissions
+- Read/write to `Formula/` and `scripts/`
+- Network access for downloading release assets
+
+### Common Pitfalls
+
+- After running `release.rb`, always `git diff` to verify version/SHA substitution worked.
+- The release script hardcodes `_formula.rb`. If you rename the file, update the `FORMULA_FILE` path.
+- `class <Formula>` must be replaced with the actual formula class name (e.g., `class MyTool < Formula`).
+- For pre-built binary formulae, use versioned aliases (`formula@X.Y.Z.rb`) for rollback support.
+- `ruby release.rb` without arguments prints usage. Always pass a version tag (e.g., `ruby release.rb 1.2.3`).
+
+### LSP Validation
+
+Before finishing any formula, validate with the Ruby LSP:
+
+1. Ensure LSP is available:
+   ```sh
+   ruby-lsp --version  # Verify LSP is installed
+   ```
+2. Run syntax check:
+   ```sh
+   ruby -c Formula/<formula>.rb
+   ```
+3. Run Homebrew linting:
+   ```sh
+   brew style --tap <user>/<tapname> Formula/<formula>.rb
+   ```
+4. Run formula audit:
+   ```sh
+   brew audit --new-formula Formula/<formula>.rb
+   ```
+
+Do NOT mark work as complete until all diagnostics pass.
+
+### Verification
+```sh
+ruby -c scripts/release.rb
+ruby -c Formula/<formula>.rb
+# Dry-run release:
+ruby scripts/release.rb <version>
+git diff  # Verify changes
+```

package/src/templates/taps/03-simple-script/tap-structure/Formula/_formula.rb

@@ -0,0 +1,27 @@
+
+# Simple formula with script-driven release (oven-sh/homebrew-bun pattern).
+# Replace <formula>, <description>, <url>, <sha256> with real values.
+# IMPORTANT: Rename class <Formula> to CamelCase matching the filename (e.g., MyTool for my-tool.rb).
+
+class <Formula> < Formula
+  desc "<one-line description>"
+  homepage "https://github.com/<user>/<repo>"
+  url "https://github.com/<user>/<repo>/archive/refs/tags/v<version>.tar.gz"
+  sha256 "<sha256>"
+  version "<version>"
+  license "MIT"
+
+  livecheck do
+    url :stable
+    regex(/^v?(\d+(?:\.\d+)+)$/i)
+  end
+
+  def install
+    system "<build-command>"
+    bin.install "<binary>"
+  end
+
+  test do
+    assert_match "<expected>", shell_output("#{bin}/<cli> --version")
+  end
+end

package/src/templates/taps/03-simple-script/tap-structure/README.md

@@ -0,0 +1,27 @@
+# <Tap Name>
+
+Homebrew tap for <formula>.
+
+## Install
+
+```sh
+brew tap <user>/<tapname>
+brew install <formula>
+```
+
+## Upgrade
+
+```sh
+brew upgrade <formula>
+```
+
+## Uninstall
+
+```sh
+brew uninstall <formula>
+brew untap <user>/<tapname>
+```
+
+## License
+
+MIT

package/src/templates/taps/03-simple-script/tap-structure/scripts/release.rb

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Release script modeled on oven-sh/homebrew-bun/scripts/release.rb.
+# Usage: ruby scripts/release.rb <version>
+#
+# Fetches the release tarball, computes SHA256, and rewrites Formula/<formula>.rb.
+
+require "open-uri"
+require "digest"
+
+TAP_DIR = File.dirname(__dir__)
+FORMULA_FILE = File.join(TAP_DIR, "Formula", "_formula.rb")  # rename to your formula name
+
+def usage
+  puts "Usage: ruby scripts/release.rb <version>"
+  puts "  e.g., ruby scripts/release.rb 1.2.3"
+  exit 1
+end
+
+def fetch_sha256(url)
+  uri = URI.parse(url)
+  puts "  Downloading #{url}..."
+  content = URI.open(uri).read
+  Digest::SHA256.hexdigest(content)
+end
+
+version = ARGV.first || usage()
+
+tarball_url = "https://github.com/<user>/<repo>/archive/refs/tags/v#{version}.tar.gz"
+
+puts "Updating Formula/<formula>.rb to version #{version}..."
+
+sha = fetch_sha256(tarball_url)
+
+formula_content = File.read(FORMULA_FILE)
+
+# Replace version and sha256
+formula_content.sub!(/version "\d+\.\d+\.\d+"/, "version \"#{version}\"")
+formula_content.sub!(/sha256 "[0-9a-f]{64}"/, "sha256 \"#{sha}\"")
+
+File.write(FORMULA_FILE, formula_content)
+
+puts "Done. Formula updated to v#{version}."
+puts
+puts "Review changes with: git diff Formula/<formula>.rb"

package/src/templates/taps/03-simple-script/template.md

@@ -0,0 +1,41 @@
+# Template 03: Simple + Script
+
+## Pattern: `oven-sh/homebrew-bun`
+
+A lean tap with a `Formula/` subdirectory and a `scripts/release.rb` for
+version bumps. No CI in the tap — releases are script-driven. Best for
+**single-formula taps** where releases are manual or triggered externally.
+
+### Structure
+
+```
+homebrew-<tap>/
+├── Formula/
+│   ├── <formula>.rb        # Latest version (overwritten on release)
+│   └── <formula>@X.Y.Z.rb  # (optional) Versioned aliases for rollback
+├── scripts/
+│   └── release.rb          # Version bump script
+├── .gitignore
+├── LICENSE
+└── README.md
+```
+
+### When to Use
+
+- You have a single formula (binary or script)
+- You want a simple, script-driven release process
+- You don't need CI in the tap itself
+- You want versioned formula aliases for rollback support
+
+### When NOT to Use
+
+- You need CI/bottle workflows (use template 01)
+- Your formula needs Python virtualenv (use template 04)
+
+### Reference
+
+- `scripts/release.rb` takes version, fetches assets, rewrites formula
+- Versioned aliases (`<formula>@X.Y.Z.rb`) enable `brew install <formula>@1.2.3`
+- See `oven-sh/homebrew-bun/scripts/release.rb` for the reference implementation
+
+- Start with `brew tap-new <user>/homebrew-<tapname>` to generate the CI skeleton (optional — manual structure works too)

package/src/templates/taps/04-python-venv/AGENTS.md

@@ -0,0 +1,83 @@
+---
+name: homebrew-tap-python-venv
+description: Creates and maintains Homebrew taps for Python CLI tools with pip dependencies in a virtualenv (bendzgerona/homebrew-litellm pattern).
+---
+
+# homebrew-tap-python-venv
+
+Agent for working with Python Virtualenv tap templates.
+
+## Description
+Helps create and maintain Homebrew taps for Python CLI tools with pip dependencies installed in a Homebrew-managed virtualenv.
+
+## Stacks
+- homebrew
+- python
+- ruby
+
+## Requires
+- basic-homebrew-knowledge
+
+## Key Actions
+
+### Formula Structure
+```ruby
+include Language::Python::Virtualenv
+depends_on "python@3.13"  # Pin to avoid brew's default
+depends_on "openssl@3"
+depends_on "pkgconf" => :build
+```
+
+### Install Pattern
+```ruby
+venv = virtualenv_create(libexec, "python3.13")
+venv.pip_install buildpath          # Install the package itself
+system venv.root/"bin/pip", "install", "package[extras]==#{version}"
+```
+
+### Post-Install Notice
+Use `def caveats` to instruct users about optional deps, service setup, and separate agent/config installation.
+
+### Permissions
+- Read/write to `Formula/` and `scripts/`
+- Network access for pip installs
+- `python@3.X` must be declared as dep (auto-installed)
+
+### Common Pitfalls
+
+- `python@3.13` must match what is available in homebrew-core. Pin to a version that actually exists.
+- Brew's Python packages (uvicorn, fastapi, pydantic) all depend on brew's default python — incompatible with pinned venvs.
+- `virtualenv_create` sets up a Homebrew-managed venv. Do NOT use `python3 -m venv` instead.
+- `pip_install` may fail if wheels need compilation. Add `depends_on "pkgconf" => :build` and `depends_on "openssl@3"`.
+- The `service` block runs `libexec/bin/<cli>` — ensure the symlink target is correct or the service will fail silently.
+
+### LSP Validation
+
+Before finishing any formula, validate with the Ruby LSP:
+
+1. Ensure LSP is available:
+   ```sh
+   ruby-lsp --version  # Verify LSP is installed
+   ```
+2. Run syntax check:
+   ```sh
+   ruby -c Formula/<formula>.rb
+   ```
+3. Run Homebrew linting:
+   ```sh
+   brew style --tap <user>/<tapname> Formula/<formula>.rb
+   ```
+4. Run formula audit:
+   ```sh
+   brew audit --new-formula Formula/<formula>.rb
+   ```
+
+Do NOT mark work as complete until all diagnostics pass.
+
+### Verification
+```sh
+brew sh --ruby
+ruby -c Formula/<formula>.rb
+brew style --tap <user>/<tapname> Formula/<formula>.rb
+brew audit --new-formula Formula/<formula>.rb
+```

package/src/templates/taps/04-python-venv/tap-structure/Formula/_formula.rb

@@ -0,0 +1,57 @@
+
+# Python virtualenv formula (bendzgerona/homebrew-litellm pattern).
+# Replace <formula>, <description>, <url>, <sha256> with real values.
+# IMPORTANT: Rename class <Formula> to CamelCase matching the filename (e.g., MyTool for my-tool.rb).
+
+class <Formula> < Formula
+  include Language::Python::Virtualenv
+
+  desc "<one-line description>"
+  homepage "https://github.com/<user>/<repo>"
+  url "https://github.com/<user>/<repo>/archive/refs/tags/v<version>.tar.gz"
+  sha256 "<sha256>"
+  version "<version>"
+  license "MIT"
+
+  depends_on "python@3.13"    # Pin to avoid brew's default 3.14
+  depends_on "openssl@3"
+  depends_on "pkgconf" => :build
+
+  livecheck do
+    url :stable
+    strategy :github_latest
+    regex(/^v?(\d+(?:\.\d+)+)$/i)
+  end
+
+  def install
+    venv = virtualenv_create(libexec, "python3.13")
+    venv.pip_install buildpath
+
+    # If the package has extras:
+    # system venv.root/"bin/pip", "install", "package[extras]==#{version}"
+
+    bin.install_symlink libexec/"bin/<cli>"
+  end
+
+  service do
+    run [libexec/"bin/<cli>", "--config", etc/"<tool>/config.yaml"]
+    keep_alive true
+    log_path var/"log/<tool>.log"
+    error_log_path var/"log/<tool>.log"
+  end
+
+  def caveats
+    <<~EOS
+      Configuration file: #{etc/"<tool>/config.yaml"}
+      Start the service:  brew services start <user>/<tap>/<formula>
+
+      Optional dependencies:
+        postgresql  — for usage tracking via SQLite → PostgreSQL
+        redis       — for request caching and rate limiting
+    EOS
+  end
+
+  test do
+    assert_match version.to_s, shell_output("#{bin}/<cli> --version")
+  end
+end

package/src/templates/taps/04-python-venv/tap-structure/README.md

@@ -0,0 +1,27 @@
+# <Tap Name>
+
+Homebrew tap for <formula>.
+
+## Install
+
+```sh
+brew tap <user>/<tapname>
+brew install <formula>
+```
+
+## Upgrade
+
+```sh
+brew upgrade <formula>
+```
+
+## Uninstall
+
+```sh
+brew uninstall <formula>
+brew untap <user>/<tapname>
+```
+
+## License
+
+MIT

package/src/templates/taps/04-python-venv/tap-structure/scripts/release.rb

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Version bump script for Python virtualenv formula.
+# Usage: ruby scripts/update-formula.rb <version>
+
+require "open-uri"
+require "digest"
+
+TAP_DIR = File.dirname(__dir__)
+FORMULA_FILE = File.join(TAP_DIR, "Formula", "_formula.rb")  # rename to your formula name
+
+def usage
+  puts "Usage: ruby scripts/update-formula.rb <version>"
+  puts "  e.g., ruby scripts/update-formula.rb 1.2.3"
+  exit 1
+end
+
+def fetch_sha256(url)
+  uri = URI.parse(url)
+  puts "  Downloading #{url}..."
+  content = URI.open(uri).read
+  Digest::SHA256.hexdigest(content)
+end
+
+version = ARGV.first || usage()
+
+tarball_url = "https://github.com/<user>/<repo>/archive/refs/tags/v#{version}.tar.gz"
+
+puts "Updating Formula/<formula>.rb to version #{version}..."
+sha = fetch_sha256(tarball_url)
+
+formula_content = File.read(FORMULA_FILE)
+formula_content.sub!(/version "\d+\.\d+\.\d+"/, "version \"#{version}\"")
+formula_content.sub!(/sha256 "[0-9a-f]{64}"/, "sha256 \"#{sha}\"")
+
+# Also update the pip install version pin if present:
+formula_content.gsub!('package[extras]==#{version}', "package[extras]==#{version}")
+formula_content.sub!(/(# system venv\.root\/"bin\/pip", "install", "package\[extras\]==)#{version}/, "\\1#{version}")
+
+File.write(FORMULA_FILE, formula_content)
+
+puts "Done. Formula updated to v#{version}."
+puts "Review: git diff Formula/<formula>.rb"

package/src/templates/taps/04-python-venv/template.md

@@ -0,0 +1,58 @@
+# Template 04: Python Virtualenv
+
+## Pattern: `bendzgerona/homebrew-litellm`
+
+A tap for Python CLI tools that install dependencies via `pip` inside a
+Homebrew-managed virtualenv. Combines the lean script-driven release
+pattern (template 03) with Python virtualenv formula conventions.
+
+### Structure
+
+```
+homebrew-<tap>/
+├── Formula/
+│   └── <formula>.rb        # Formula with Language::Python::Virtualenv
+├── scripts/
+│   └── release.rb   # Version bump script (SHA256 + version)
+├── .gitignore
+├── LICENSE
+└── README.md
+```
+
+### Key Formula Patterns
+
+```ruby
+include Language::Python::Virtualenv
+
+depends_on "python@3.13"       # Pin Python version
+depends_on "openssl@3"         # For C-extension wheel compilation
+depends_on "pkgconf" => :build
+
+def install
+  venv = virtualenv_create(libexec, "python3.13")
+  venv.pip_install buildpath
+  system venv.root/"bin/pip", "install", "<package>[extras]==#{version}"
+  %w[cli-name another-cli].each do |cmd|
+    (bin/cmd).write_env_script(venv.root/"bin/#{cmd}", PATH: "#{venv.root}/bin:#{ENV["PATH"]}")
+  end
+end
+```
+
+### When to Use
+
+- Your formula installs a Python CLI tool with pip dependencies
+- You need to pin a specific Python version (brew's default may conflict)
+- You have exact pin constraints that differ from brew's versions
+
+### When NOT to Use
+
+- Your formula is a pre-built binary (use template 03)
+- You need CI/bottle workflows (use template 01)
+
+### Reference
+
+- `bendzgerona/homebrew-litellm` — reference implementation
+- Homebrew docs: `Python-for-Formula-Authors.md`, `Formula-Cookbook.md`
+- Use `depends_on "python@3.X"` to pin; brew's default changes over time
+
+- Start with `brew tap-new <user>/homebrew-<tapname>` to generate the CI skeleton (optional — manual structure works too)

package/src/templates/taps/05-node-npm/AGENTS.md

@@ -0,0 +1,90 @@
+---
+name: homebrew-tap-node-npm
+description: Creates and maintains Homebrew taps for JavaScript/TypeScript CLI tools using npm or bun.
+---
+
+# homebrew-tap-node-npm
+
+Agent for working with Node.js / npm / bun tap templates.
+
+## Description
+Helps create and maintain Homebrew taps for JavaScript/TypeScript CLI tools using either npm or bun as the package manager.
+
+## Stacks
+- homebrew
+- nodejs
+- bun
+- javascript
+- typescript
+
+## Requires
+- basic-homebrew-knowledge
+
+## Key Actions
+
+### npm Pattern
+```ruby
+depends_on "node"
+def install
+  system "npm", "install", *std_npm_args
+  bin.install_symlink Dir["#{libexec}/bin/*"]
+end
+```
+
+### bun Pattern
+```ruby
+depends_on "bun"
+def install
+  system "bun", "install", "--production"
+  bin.install_symlink Dir["#{libexec}/bin/*"]
+end
+```
+
+### Compiled bun binary pattern
+```ruby
+depends_on "bun"
+def install
+  system "bun", "install"
+  system "bun", "build", "--compile", "--outfile=#{bin}/<cli>", "./src/index.ts"
+end
+```
+
+### Permissions
+- Read/write to `Formula/` and `scripts/`
+- Network access for npm/bun installs
+- `depends_on "bun"` requires `oven-sh/homebrew-bun` to be tapped
+
+### Common Pitfalls
+
+- `depends_on "bun"` requires `brew tap oven-sh/bun` first — the bun formula is not in homebrew-core.
+- Uncomment exactly ONE of the three install patterns in `_formula.rb`. Multiple `def install` blocks cause a Ruby syntax error.
+- `std_npm_args` is required for npm-based installs — it sets `--prefix`, `--global`, `--no-save`. Raw `npm install` will not place binaries in the correct libexec path.
+
+### LSP Validation
+
+Before finishing any formula, validate with the Ruby LSP:
+
+1. Ensure LSP is available:
+   ```sh
+   ruby-lsp --version  # Verify LSP is installed
+   ```
+2. Run syntax check:
+   ```sh
+   ruby -c Formula/<formula>.rb
+   ```
+3. Run Homebrew linting:
+   ```sh
+   brew style --tap <user>/<tapname> Formula/<formula>.rb
+   ```
+4. Run formula audit:
+   ```sh
+   brew audit --new-formula Formula/<formula>.rb
+   ```
+
+Do NOT mark work as complete until all diagnostics pass.
+
+### Verification
+```sh
+ruby -c Formula/<formula>.rb
+brew style --tap <user>/<tapname> Formula/<formula>.rb
+```