opencode-homebrew-agent 1.0.0

package/src/templates/taps/05-node-npm/tap-structure/Formula/_formula.rb

@@ -0,0 +1,46 @@
+
+# JavaScript/TypeScript CLI formula — npm or 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
+
+  # ---- npm pattern (uncomment if using npm) ----
+  # depends_on "node"
+  #
+  # def install
+  #   system "npm", "install", *std_npm_args
+  #   bin.install_symlink Dir["#{libexec}/bin/*"]
+  # end
+
+  # ---- bun pattern (uncomment if using bun) ----
+  # depends_on "bun"
+  #
+  # def install
+  #   system "bun", "install", "--production"
+  #   bin.install_symlink Dir["#{libexec}/bin/*"]
+  # end
+
+  # ---- bun compiled binary pattern (uncomment if compiling with bun) ----
+  # depends_on "bun"
+  #
+  # def install
+  #   system "bun", "install"
+  #   system "bun", "build", "--compile", "--outfile=#{bin}/<cli>", "./src/index.ts"
+  # end
+
+  test do
+    assert_match "<expected>", shell_output("#{bin}/<cli> --version")
+  end
+end

package/src/templates/taps/05-node-npm/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/05-node-npm/tap-structure/scripts/release.rb

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Version bump script for JS Runtime 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()
+# NOTE: This URL assumes GitHub releases. For npm-published tools, use:
+# tarball_url = "https://registry.npmjs.org/<package>/-/package-#{version}.tgz"
+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}\"")
+
+File.write(FORMULA_FILE, formula_content)
+puts "Done. Formula updated to v#{version}."
+puts "Review: git diff Formula/<formula>.rb"

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

@@ -0,0 +1,74 @@
+# Template 05: JavaScript Runtime (npm + bun)
+
+## Pattern: CLI tools distributed via npm or built with bun
+
+For JavaScript/TypeScript CLI tools. Two sub-patterns depending on the
+runtime/bundler:
+
+- **npm pattern**: `depends_on "node"` + `std_npm_args` (standard Homebrew convention)
+- **bun pattern**: `depends_on "bun"` + `bun install`/`bun build` (for bun-native toolchains)
+
+### Structure
+
+```
+homebrew-<tap>/
+├── Formula/
+│   └── <formula>.rb        # Formula with depends_on "node" or "bun"
+├── scripts/
+│   └── release.rb   # (optional) Version bump script
+├── .gitignore
+├── LICENSE
+└── README.md
+```
+
+### Key Formula Patterns
+
+**npm-based** (standard — for packages distributed via npm registry):
+
+```ruby
+depends_on "node"
+
+def install
+  system "npm", "install", *std_npm_args
+  bin.install_symlink Dir["#{libexec}/bin/*"]
+end
+```
+
+**bun-based** (for bun-native tools or when bun produces smaller builds):
+
+```ruby
+depends_on "bun"
+
+def install
+  # Install dependencies and build
+  system "bun", "install"
+  system "bun", "build", "--compile", "--outfile=#{bin}/<cli-name>", "./src/index.ts"
+
+  # Or for a simpler install (package with bin field):
+  # system "bun", "install", "--production"
+  # bin.install_symlink Dir["#{libexec}/bin/*"]
+end
+```
+
+See also: `scripts/` can include `bunx` stubs that invoke `bunx <package>`
+without requiring the package to be installed globally.
+
+### When to Use
+
+- **npm**: Your CLI tool is published to npm and uses Node.js runtime
+- **bun**: Your tool uses bun as runtime, or bun is specifically required/bundled
+- **Either**: You want Homebrew as the install method instead of `npm install -g` / `bun install -g`
+
+### When NOT to Use
+
+- The tool has native C++ extensions (may need additional build deps like `pkgconf`)
+- The tool is a Python CLI (use template 04 instead)
+
+### Reference
+
+- `std_npm_args` is a Homebrew helper that sets `--prefix`, `--global`, `--no-save`
+- `depends_on "bun"` — bun is a formula in `oven-sh/homebrew-bun` tap
+- `bun build --compile` produces a standalone binary (no runtime dep needed)
+- For bun packages: `bun install --production` only installs runtime deps (no devDependencies)
+
+- Start with `brew tap-new <user>/homebrew-<tapname>` to generate the CI skeleton (optional — manual structure works too)

package/src/templates/taps/06-keg-only/AGENTS.md

@@ -0,0 +1,82 @@
+---
+name: homebrew-tap-keg-only
+description: Creates and maintains Homebrew taps for system tool replacements that are keg-only (not symlinked into PATH).
+---
+
+# homebrew-tap-keg-only
+
+Agent for working with Keg-Only System Tool tap templates.
+
+## Description
+Helps create and maintain Homebrew taps for system tool replacements that are keg-only (not symlinked into PATH) with caveats explaining PATH setup.
+
+## Stacks
+- homebrew
+- ruby
+
+## Requires
+- basic-homebrew-knowledge
+
+## Key Actions
+
+### keg_only Declaration
+```ruby
+keg_only "this is an alternate version of another formula"
+```
+
+### PATH Caveat
+```ruby
+def caveats
+  <<~EOS
+    <command> is keg-only, which means it was not symlinked into
+    #{HOMEBREW_PREFIX}, because this is an alternate version of
+    another formula.
+
+    If you need to have <command> first in your PATH, run:
+      echo 'export PATH="#{opt_bin}:$PATH"' >> ~/.zshrc
+  EOS
+end
+```
+
+### GNU Prefix Convention
+Use `--program-prefix=g` with GNU configure scripts to shadow system binaries safely.
+
+### Permissions
+- Read/write to `Formula/`
+- No special permissions needed beyond standard formula creation
+
+### Common Pitfalls
+
+- `keg_only` reason must explain WHY the formula conflicts with a system binary (e.g., "this is an alternate version of another formula"). Vague reasons will fail `brew audit`.
+- Always provide `def caveats` with a PATH export example. Users won't know the tool is installed otherwise.
+- GNU tools should use `--program-prefix=g` to avoid shadowing `/usr/bin/<tool>` on macOS.
+
+### 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
+brew audit --strict Formula/<formula>.rb
+```

package/src/templates/taps/06-keg-only/tap-structure/Formula/_formula.rb

@@ -0,0 +1,45 @@
+
+# Keg-only system tool formula.
+# 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 "<license>"
+
+  livecheck do
+    url :stable
+    regex(/^v?(\d+(?:\.\d+)+)$/i)
+  end
+
+  keg_only "this is an alternate version of another formula"
+
+  # Optional: GNU prefix to avoid shadowing macOS system binaries
+  # depends_on "autoconf" => :build
+  # depends_on "automake" => :build
+
+  def install
+    # GNU-style --program-prefix avoids collision with /usr/bin/<tool>
+    system "./configure", "--prefix=#{prefix}", "--program-prefix=g"
+    system "make", "install"
+  end
+
+  def caveats
+    <<~EOS
+      <formula> is keg-only, which means it was not symlinked into
+      #{HOMEBREW_PREFIX}, because this is an alternate version of
+      another formula.
+
+      If you need to have <formula> first in your PATH, run:
+        echo 'export PATH="#{opt_bin}:$PATH"' >> ~/.zshrc
+    EOS
+  end
+
+  test do
+    assert_match "<expected>", shell_output("#{bin}/g<cli> --version")
+  end
+end

package/src/templates/taps/06-keg-only/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/06-keg-only/template.md

@@ -0,0 +1,60 @@
+# Template 06: Keg-Only System Tool
+
+## Pattern: `homebrew-core` keg-only formulae (e.g., `gnuwhich`, `coreutils`)
+
+For tools that provide alternative versions of common system utilities.
+These are typically `keg_only` (not symlinked into PATH) with caveats
+telling the user how to add them to their PATH. Often have a `gnubin/`
+and `gnuman/` directory structure.
+
+### Structure
+
+```
+homebrew-<tap>/
+├── Formula/
+│   └── <formula>.rb        # Formula with keg_only + caveats
+├── .gitignore
+├── LICENSE
+└── README.md
+```
+
+### Key Formula Pattern
+
+```ruby
+keg_only "this is an alternate version of another formula"
+
+def install
+  system "./configure", "--prefix=#{prefix}", "--program-prefix=g"
+  system "make", "install"
+end
+
+def caveats
+  <<~EOS
+    <command> is keg-only, which means it was not symlinked into
+    #{HOMEBREW_PREFIX}, because this is an alternate version of
+    another formula.
+
+    If you need to have <command> first in your PATH, run:
+      echo 'export PATH="#{opt_bin}:$PATH"' >> ~/.zshrc
+  EOS
+end
+```
+
+### When to Use
+
+- You're packaging a newer/macOS-specific version of a system tool
+- The formula shadows an existing macOS binary (`/usr/bin/<tool>`)
+- You want the `--program-prefix=g` convention (GNU-style)
+
+### When NOT to Use
+
+- There's no conflict with system binaries (use template 01 or 03 instead)
+- The tool has no macOS equivalent
+
+### Reference
+
+- `keg_only` prevents symlinking into `HOMEBREW_PREFIX/bin`
+- Caveats explain how to add to PATH
+- GNU tools typically use `--program-prefix=g` to avoid shadowing system versions
+
+- Start with `brew tap-new <user>/homebrew-<tapname>` to generate the CI skeleton (optional — manual structure works too)

package/src/templates/taps/07-cask-only/AGENTS.md

@@ -0,0 +1,97 @@
+---
+name: homebrew-tap-cask-only
+description: Creates and maintains Homebrew taps for macOS GUI applications using the Cask DSL.
+---
+
+# homebrew-tap-cask-only
+
+Agent for working with Cask-Only tap templates.
+
+## Description
+Helps create and maintain Homebrew taps for macOS GUI applications using the Cask DSL.
+
+## Stacks
+- homebrew
+- ruby
+
+## Requires
+- basic-homebrew-knowledge
+
+## Key Actions
+
+### Cask Structure
+Casks go in `Casks/` directory (not `Formula/`). The DSL is different from formula:
+
+```ruby
+cask "<app-name>" do
+  version "<version>"
+  sha256 "<sha256>"
+  url "https://..."
+  name "<App Name>"
+  desc "Description"
+  homepage "https://..."
+  app "<App>.app"
+end
+```
+
+### Install Command
+```sh
+brew install --cask <user>/<tap>/<app>
+```
+
+### Livecheck Strategies
+Casks use different livecheck strategies than formulae:
+- `strategy :github_latest` — for GitHub releases
+- `strategy :page_match` — for pages with version numbers in HTML
+- `strategy :sparkle` — for apps using Sparkle auto-update framework
+
+### Zap vs Uninstall
+- `zap` defines cleanup paths for user data (Preferences, Caches, etc.)
+- `uninstall` handles app removal, pkg scripts, and launch jobs
+- Use both for complete removal: `brew uninstall --zap --cask <app>`
+
+### Architecture Support
+For universal binaries or separate Intel/Apple Silicon builds:
+```ruby
+arch arm: "arm64", intel: "x64"
+url "https://.../#{arch}/<app>.dmg"
+```
+
+### Permissions
+- Read/write to `Casks/` directory
+
+### Common Pitfalls
+
+- Cask filenames must be lowercase with hyphens (e.g., `my-app.rb` → `cask "my-app"`)
+- The `sha256` must match the downloaded `.dmg`/`.zip`/`.pkg` file, not the app bundle
+- `livecheck` `url :url` points to the cask's download URL — use `url :stable` or an explicit GitHub releases URL instead
+- Always test `brew install --cask` and `brew uninstall --cask` before committing
+
+### LSP Validation
+
+Before finishing any cask, 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 Casks/<app>.rb
+   ```
+3. Run Homebrew linting:
+   ```sh
+   brew style --tap <user>/<tapname> Casks/<app>.rb
+   ```
+4. Run new-cask audit:
+   ```sh
+   brew audit --new-cask Casks/<app>.rb
+   ```
+
+Do NOT mark work as complete until all diagnostics pass.
+
+### Verification
+```sh
+ruby -c Casks/<app>.rb
+brew style --tap <user>/<tapname> Casks/<app>.rb
+```

package/src/templates/taps/07-cask-only/tap-structure/Casks/_app.rb

@@ -0,0 +1,26 @@
+
+# Cask template for macOS GUI applications.
+# Replace <app>, <version>, <sha256>, <url> with real values.
+
+cask "<app>" do
+  version "<version>"
+  sha256 "<sha256>"
+
+  url "https://github.com/<user>/<repo>/releases/download/v#{version}/<app>.dmg"
+  name "<App Name>"
+  desc "<one-line description>"
+  homepage "https://github.com/<user>/<repo>"
+
+  livecheck do
+    url :stable
+    strategy :github_latest
+  end
+
+  app "<App>.app"
+
+  zap trash: [
+    "~/Library/Application Support/<app>",
+    "~/Library/Preferences/<app>.plist",
+    "~/Library/Caches/<app>",
+  ]
+end

package/src/templates/taps/07-cask-only/tap-structure/README.md

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

package/src/templates/taps/07-cask-only/template.md

@@ -0,0 +1,58 @@
+# Template 07: Cask-Only
+
+## Pattern: Personal cask taps for GUI applications
+
+For macOS GUI applications distributed as `.app` bundles, `.dmg` files,
+or `.pkg` installers. Uses Homebrew Cask DSL instead of the formula DSL.
+
+### Structure
+
+```
+homebrew-<tap>/
+├── Casks/
+│   └── <app>.rb            # Cask definition (not a formula)
+├── .gitignore
+├── LICENSE
+└── README.md
+```
+
+### Key Cask Pattern
+
+```ruby
+cask "<app-name>" do
+  version "<version>"
+  sha256 "<sha256>"
+
+  url "https://github.com/<user>/<repo>/releases/download/v#{version}/<app>.dmg"
+  name "<App Name>"
+  desc "Description of the application"
+  homepage "https://github.com/<user>/<repo>"
+
+  app "<App>.app"
+
+  zap trash: [
+    "~/Library/Application Support/<app>",
+    "~/Library/Preferences/<app>.plist",
+  ]
+end
+```
+
+### When to Use
+
+- You distribute a macOS GUI application
+- You want users to install via `brew install --cask <user>/<tap>/<app>`
+- The app comes as `.app`, `.dmg`, or `.pkg`
+
+### When NOT to Use
+
+- Your tool is CLI-only (use a formula template instead)
+- The app is already in `homebrew/cask`
+
+### Reference
+
+- Casks go in `Casks/` directory, not `Formula/`
+- Use `brew install --cask` to install
+- `zap` block defines uninstall cleanup paths
+- `app` stanza moves the `.app` to `/Applications`
+
+- Start with `brew tap-new <user>/homebrew-<tapname>` to generate the CI skeleton (optional — manual structure works too)