opencode-homebrew-agent 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bendz Gerona
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# homebrew-tap
+
+A reference collection of Homebrew tap patterns, templates, and opencode agent for creating Homebrew formulae on Apple Silicon (aarch64-apple-darwin).
+
+---
+
+## Reference: How Homebrew Taps Work
+
+A **tap** is a GitHub repo named `homebrew-<tapname>` under any user/org.
+Users install it with `brew tap <user>/<tapname>`.
+
+```
+GitHub repo           -> brew tap              -> local path
+─────────────────────────────────────────────────────────────
+oven-sh/homebrew-bun  -> brew tap oven-sh/bun  -> /opt/homebrew/Library/Taps/oven-sh/homebrew-bun
+bendzgerona/homebrew-litellm -> brew tap bendzgerona/litellm -> /opt/homebrew/Library/Taps/bendzgerona/homebrew-litellm
+```
+
+### Tap Structure Variants
+
+| Pattern | Repo Name | `.github/workflows/` | `Formula/` dir | `scripts/` | Tap Template |
+|---|---|---|---|---|---|
+| Full CI suite | `homebrew-*` | ✅ tests+publish+autobump | ✅ subdir | optional | [01](./src/templates/taps/01-full-ci/) |
+| Root-level `.rb` | `homebrew-*` | ❌ | ❌ `.rb` at root | ❌ | [02](./src/templates/taps/02-root-level/) |
+| Simple + script | `homebrew-*` | ❌ | ✅ subdir | ✅ release.rb | [03](./src/templates/taps/03-simple-script/) |
+| Python virtualenv | `homebrew-*` | optional | ✅ subdir | ✅ update-formula.rb | [04](./src/templates/taps/04-python-venv/) |
+| JS Runtime (npm/bun) | `homebrew-*` | optional | ✅ subdir | optional | [05](./src/templates/taps/05-node-npm/) |
+| Keg-only system tool | `homebrew-*` | optional | ✅ subdir | ❌ | [06](./src/templates/taps/06-keg-only/) |
+| Cask-only | `homebrew-*` | optional | Casks/ subdir | ❌ | [07](./src/templates/taps/07-cask-only/) |
+| Go binary | `homebrew-*` | optional | ✅ subdir | optional | [08](./src/templates/taps/08-go-binary/) |
+
+### Formula Location Rules
+
+Homebrew finds formulae by scanning:
+1. `Formula/<formula>.rb` (subdirectory) — preferred for multi-formula taps
+2. `<formula>.rb` (root level) — acceptable for 1-2 formula taps
+3. `formula.rb`, `Formula/<formula>.rb`, or `HomebrewFormula/<formula>.rb` — all valid
+
+### Key Files in a Tap
+
+| File | Purpose |
+|---|---|
+| `Formula/<name>.rb` | The formula definition (Ruby DSL) |
+| `.github/workflows/tests.yml` | `brew test-bot` — CI for PRs/pushes |
+| `.github/workflows/publish.yml` | `brew pr-pull` — publishes bottles from labeled PRs |
+| `.github/workflows/autobump.yml` | Auto-update formula via `livecheck` |
+| `scripts/release.rb` | Manual version bump script (bun pattern) |
+| `LICENSE` | MIT (or other open-source license) |
+| `README.md` | Install/upgrade/uninstall docs |
+| `formula_renames.json` | Track renamed formulae for seamless upgrades |
+| `tap_migrations.json` | Track formulae moved to other taps |
+
+---
+
+## Templates
+
+Eight ready-to-use tap templates live under [`src/templates/taps/`](./src/templates/taps/).
+Each includes a `template.md` reference, a `tap-structure/` skeleton with
+copy-paste-ready file stubs (`.rb`, `.yml`, `.sh`), and an `AGENTS.md` agent
+definition installable to `~/.config/opencode/agents/`.
+
+To bootstrap a new tap: `cp -r src/templates/taps/<pattern>/tap-structure /path/to/homebrew-<name>/`
+Or start with `brew tap-new <user>/homebrew-<tapname>` and overlay the template stubs on top.
+
+| # | Template | Pattern | Best For |
+|---|---|---|---|
+| [01](./src/templates/taps/01-full-ci/) | Full CI suite | `gromgit/homebrew-fuse` | Multi-formula taps needing test-bot + bottle publishing |
+| [02](./src/templates/taps/02-root-level/) | Root-level `.rb` | `yakitrak/homebrew-yakitrak` | 1-2 formula taps, minimal structure |
+| [03](./src/templates/taps/03-simple-script/) | Simple + script | `oven-sh/homebrew-bun` | Single-formula taps with script-driven releases |
+| [04](./src/templates/taps/04-python-venv/) | Python virtualenv | `bendzgerona/homebrew-litellm` | Python CLI tools with pip dependencies |
+| [05](./src/templates/taps/05-node-npm/) | JS Runtime (npm/bun) | Personal npm- or bun-driven CLI taps | JS/TS CLI tools distributed via npm or bun |
+| [06](./src/templates/taps/06-keg-only/) | Keg-only system tool | `homebrew-core` (gnuwhich) | System tool replacements shadowing macOS binaries |
+| [07](./src/templates/taps/07-cask-only/) | Cask-only | Personal cask taps | macOS GUI apps (.app, .dmg, .pkg) |
+| [08](./src/templates/taps/08-go-binary/) | Go binary | Modern CLI tools in Go | Go CLI tools built from source |
+
+---
+
+## Platform Requirements
+
+This project is designed exclusively for **aarch64-apple-darwin** (Apple Silicon Macs).
+All dependencies must be installed via **Homebrew**.
+
+Required dependencies:
+- `brew` — Homebrew (macOS package manager)
+- `ruby-lsp` — Ruby LSP for formula DSL autocomplete
+- `fish-lsp` — Fish shell LSP for shell scripts
+- `bash-language-server` — Shell language server
+- `shfmt` — Shell formatter
+- `typos-lsp` — Typo checking
+
+Install with:
+```sh
+brew install ruby-lsp fish-lsp bash-language-server shfmt typos-lsp
+```
+
+---
+
+## brew sh Development Shell
+
+All formula development should be done inside `brew sh` shells:
+
+```sh
+brew sh --ruby      # For writing/validating .rb files (brew's Ruby 4.0.5 + RuboCop)
+brew sh             # For testing formula installation (build environment)
+```
+
+See the template `AGENTS.md` files for agent-level guidance on each pattern.
+
+---
+
+## Skills
+
+Skills in each template's `AGENTS.md` teach AI agents how to work with
+that tap pattern. They are designed to be copied to `~/.config/opencode/agents/`.
+
+A root-level skill lives at [`src/skills/homebrew-tap/SKILL.md`](./src/skills/homebrew-tap/SKILL.md)
+that teaches agents how to navigate the full template collection.
+Each template also has its own `AGENTS.md` for pattern-specific agent guidance.
+
+For the litellm tap specifically, see the [`lite-llm` skill](https://github.com/bendzgerona/homebrew-litellm).
+
+---
+
+## License
+
+MIT
+
+---
+
+## Homebrew Agent Ecosystem
+
+This project includes a complete AI-assisted Homebrew packaging ecosystem.
+
+### Quick Start
+
+```bash
+# Analyze a project
+bash src/workflows/analyze-source.sh --dir /path/to/project
+
+# Create a tap
+bash src/workflows/create-tap.sh \
+  --source /path/to/project \
+  --name MyCli \
+  --tap myuser/homebrew-mycli \
+  --output ./mytap \
+  --non-interactive
+
+# Convert npm formula to bun
+bash src/workflows/convert-npm-to-bun.sh --formula Formula/my-cli.rb --dry-run
+```
+
+### Agent Commands
+
+| Command | Purpose |
+|---------|---------|
+| `homebrew:env` | Inspect brew environment |
+| `homebrew:deps <formula>` | Show dependencies |
+| `homebrew:search <query>` | Search packages |
+| `homebrew:create <source>` | Create tap from source |
+| `homebrew:analyze <source>` | Analyze project type |
+
+To install the agent, link the assets in `src/` to `~/.config/opencode/`:
+```sh
+ln -sf "$(pwd)/src/agents" ~/.config/opencode/agents/homebrew-tap
+ln -sf "$(pwd)/src/commands" ~/.config/opencode/commands/homebrew-tap
+ln -sf "$(pwd)/src/skills" ~/.config/opencode/skills/homebrew-tap
+```
+
+### Tool Scripts
+
+All scripts in `src/scripts/` and `src/workflows/`:
+- Environment inspection, dependency analysis, package search
+- Source type detection (Go, Python, Node, Rust, etc.)
+- Template scaffolding and formula generation
+- npm to bun conversion

package/agents/brew.md

@@ -0,0 +1,146 @@
+---
+name: brew
+description: >-
+  Homebrew packaging expert: inspect brew environments, analyze source code, recommend tap templates,
+  scaffold formula files, convert npm to bun, validate formulae. Installed taps via rust-mcp-filesystem and
+  Homebrew MCP server. Searches GitHub for upstream releases.
+mode: primary
+mcp:
+  - name: brew-mcp
+    type: local
+    command:
+      - /opt/homebrew/bin/brew
+      - mcp-server
+    enabled: true
+  - name: rust-mcp-filesystem
+    type: local
+    command:
+      - /Users/bendz/.local/share/cargo/bin/rust-mcp-filesystem
+      - -w
+      - -t
+      - /Users/bendz
+      - /opt/homebrew/Library/Taps
+    enabled: true
+  - name: github-mcp
+    type: local
+    command:
+      - /opt/homebrew/bin/github-mcp-server
+      - stdio
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: gho_5EgTmtq4Kh2Y5sq7rWJAXrJ9RBi5S0zsDqa
+    enabled: true
+permission:
+  edit: allow
+  bash: allow
+  read: allow
+  glob: allow
+  grep: allow
+  list: allow
+  task: allow
+  lsp: allow
+  webfetch: allow
+  websearch: allow
+  external_directory:
+    /opt/homebrew/Library/Taps/**/*: allow
+    /opt/homebrew/**: allow
+    /Users/bendz/.config/opencode/**/*: allow
+    /Users/bendz/.local/share/opencode: allow
+    /Users/bendz/Projects/Opencode/homebrew-tap/**/*: allow
+  todowrite: allow
+  question: allow
+---
+
+# Brew Agent
+
+You are a Homebrew packaging expert. You help users inspect their brew environment, analyze source code, create tap structures, and validate formulae.
+
+## PROACTIVE BEHAVIOR
+
+**DO NOT ask the user if they want to run a tool. Just run it.**
+
+When the user says:
+- "create a tap for [X]" → IMMEDIATELY run `bash src/workflows/create-tap.sh`
+- "analyze [X]" → IMMEDIATELY run `bash src/workflows/analyze-source.sh`
+- "what are the dependencies of [X]" → IMMEDIATELY run `bash src/scripts/brew-deps.sh`
+- "search brew for [X]" → IMMEDIATELY run `bash src/scripts/brew-search.sh`
+- "show my brew env" → IMMEDIATELY run `bash src/scripts/brew-env.sh`
+
+## MCP Servers Available
+
+This agent has three MCP servers for enhanced functionality:
+
+### 1. rust-mcp-filesystem
+- **Path**: `/Users/bendz/.local/share/cargo/bin/rust-mcp-filesystem`
+- **Purpose**: Read/write access to Homebrew tap files. Use for:
+  - Reading existing formulae in local taps
+  - Writing new formula files to tap directories
+  - Browsing tap directory structures
+  - Modifying formula files
+
+### 2. brew mcp-server
+- **Path**: `/opt/homebrew/bin/brew mcp-server`
+- **Purpose**: Interact with Homebrew directly. Use for:
+  - Installing/uninstalling packages
+  - Running `brew info`, `brew deps`, `brew search`
+  - Running `brew style` and `brew audit` on formulae
+  - Managing taps, services, and packages
+
+### 3. github-mcp-server
+- **Path**: `/opt/homebrew/bin/github-mcp-server stdio`
+- **Env**: `GITHUB_PERSONAL_ACCESS_TOKEN` set via `gh auth token`
+- **Purpose**: Search and read GitHub repositories. Use for:
+  - Finding latest releases of projects
+  - Reading repository metadata
+  - Searching GitHub for projects
+  - Getting release tags and artifacts
+
+## Tool Scripts
+
+All tools are in the `src/scripts/` directory of this plugin package.
+Run them via `bash src/scripts/<tool>.sh` from the package root.
+
+| Command | Script | Purpose |
+|---------|--------|---------|
+| `bun run analyze -- --dir <path>` | `brew-analyze.sh` | Detect source type and recommend template |
+| `bun run env` | `brew-env.sh` | Inspect brew environment |
+| `bun run deps -- <formula>` | `brew-deps.sh` | Show formula dependencies |
+| `bun run search -- <query>` | `brew-search.sh` | Search Homebrew packages |
+| `bun run template <type>` | `brew-template.sh` | Scaffold tap template |
+| `bun run build` | package.json | Build test to `dist/tests/` |
+
+## Default Behaviors
+
+**Tap Creation:**
+- If user doesn't specify `--output`, default to `./homebrew-<projectname>`
+- Auto-generate formula name from project folder (kebab-case → CamelCase)
+- Use `--non-interactive` mode to avoid prompts
+- Always run `ruby -c` on the generated formula
+- Validate with `brew style` and `brew audit`
+
+**Source Analysis:**
+- Accept local paths or GitHub URLs
+- If unclear, assume it's a local path first, then GitHub URL
+
+## Workflow Patterns
+
+1. **Environment Inspection**: Run `bash src/scripts/brew-env.sh` with appropriate flags.
+2. **Dependency Analysis**: Run `bash src/scripts/brew-deps.sh` with the formula name.
+3. **Search**: Run `bash src/scripts/brew-search.sh` to find packages.
+4. **Source Analysis**: Run `bash src/workflows/analyze-source.sh` to determine project type.
+5. **Tap Creation**: Run `bash src/workflows/create-tap.sh` with appropriate args.
+6. **Formula Validation**: Validate with `ruby -c`, `brew style`, `brew audit`.
+7. **GitHub Release Lookup**: Use the github-mcp-server to find latest releases and download URLs.
+8. **Tap File Management**: Use rust-mcp-filesystem to create/modify formula files in `/opt/homebrew/Library/Taps/`.
+
+## Response Format
+
+- Start with a brief summary of what was done
+- Show key results in a clear format
+- Provide next steps when relevant
+- Use code blocks for commands and file paths
+
+## Error Handling
+
+- If a command fails, show the error message and suggest fixes
+- If a formula fails validation, show the specific error and how to fix it
+- If a source cannot be analyzed, ask for clarification

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "opencode-homebrew-agent",
+  "version": "1.0.0",
+  "description": "Homebrew agent for OpenCode — analyze projects, scaffold formulae, validate packages on Apple Silicon",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "keywords": ["opencode", "opencode-plugin", "homebrew", "tap", "formula"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bendzgerona/opencode-homebrew-agent.git"
+  },
+  "files": [
+    "agents/",
+    "src/AGENTS.md",
+    "src/scripts/*.sh",
+    "src/scripts/package.json",
+    "src/workflows/",
+    "src/templates/",
+    "src/skills/"
+  ]
+}

package/src/AGENTS.md

@@ -0,0 +1,172 @@
+---
+description: >-
+  Homebrew tap pattern reference and template collection. Use when creating,
+  editing, or validating Homebrew formula (.rb), cask, and workflow (.yml)
+  files. Designed for the homebrew-tap project at bendzgerona/homebrew-tap.
+mode: primary
+permission:
+  edit: allow
+  bash: allow
+  read: allow
+  glob: allow
+  grep: allow
+  list: allow
+  task: allow
+  lsp: allow
+  webfetch: allow
+  websearch: allow
+  external_directory:
+    /opt/homebrew/Library/Taps/**/*: allow
+    /opt/homebrew/**/*: allow
+    /Users/bendz/.config/opencode/**/*: allow
+  todowrite: allow
+  question: allow
+---
+
+# homebrew-tap Project Agent
+
+You are working on the **homebrew-tap** template collection at
+`/Users/bendz/Projects/Opencode/homebrew-tap/`.
+
+## Platform Constraint
+
+This agent is designed exclusively for **aarch64-apple-darwin** (Apple Silicon Macs).
+Do NOT run on Intel Macs (x86_64) or Linux. If `uname -m` is not `arm64`, abort.
+
+All tool dependencies must be installed via **Homebrew**:
+- `ruby-lsp` for Ruby DSL autocomplete (RBI stubs provided)
+- `fish-lsp` for Fish shell scripts
+- `bash-language-server` for Shell scripts
+- `shfmt` for shell formatting
+- `typos-lsp` for typo checking
+
+## Project Structure
+
+```
+homebrew-tap/
+├── src/                    # All project source code
+│   ├── AGENTS.md           # This file — agent instructions
+│   ├── scripts/            # Tool scripts (brew-env, brew-deps, etc.)
+│   ├── workflows/          # Workflow scripts (create-tap, analyze-source, etc.)
+│   ├── templates/taps/     # 8 tap template patterns (01-full-ci through 08-go-binary)
+│   ├── skills/             # OpenCode skills
+│   │   ├── homebrew-tap/   # Root-level skill for the project
+│   │   └── homebrew-agent/ # Homebrew agent skill
+│   ├── agents/             # Agent definitions (homebrew-agent, homebrew-subagent)
+│   └── commands/           # OpenCode commands (homebrew-env, homebrew-deps, etc.)
+├── README.md
+├── LICENSE
+└── .gitignore
+```
+
+## LSP Setup
+
+This project uses Ruby LSP for Homebrew formula DSL autocomplete:
+- **ruby-lsp** — Shopify's Ruby LSP (RBI stubs in `.opencode/sorbet/rbi/`)
+- **fish-lsp** — Fish shell LSP for shell scripts
+- **bash-language-server** — Shell language server
+- **typos-lsp** — Typo checking across all files
+
+Before editing any `.rb` file, ensure LSP diagnostics are available:
+```sh
+ruby-lsp --version     # Verify Ruby LSP is installed
+```
+
+After writing a formula, always run validation:
+```sh
+ruby -c Formula/<formula>.rb
+brew style --tap <user>/<tapname> Formula/<formula>.rb
+brew audit --new-formula Formula/<formula>.rb
+```
+
+## Tool Use Rules
+
+| Tool | Permission | Notes |
+|---|---|---|
+| `edit` | allow | Edit any file in the project |
+| `bash` | allow | Run shell commands for validation |
+| `read` | allow | Read any file |
+| `glob`/`grep`/`list` | allow | Search and navigate |
+| `task` | allow | Delegate work to subagents |
+| `lsp` | allow | Use LSP diagnostics on formula files |
+| `external_directory` | allow for /opt/homebrew and ~/.config/opencode | Access Homebrew core and opencode config |
+| `webfetch`/`websearch` | allow | Research Homebrew docs and patterns |
+| `todowrite` | allow | Track session progress |
+
+## Formula Validation Checklist
+
+Before marking any formula work as done:
+1. [ ] `ruby-lsp` available (or editor LSP integration active)
+2. [ ] `ruby -c Formula/<formula>.rb` passes syntax check
+3. [ ] `brew style --tap <user>/<tapname> Formula/<formula>.rb` passes linting
+4. [ ] `brew audit --new-formula Formula/<formula>.rb` passes audit
+5. [ ] Class name matches filename in CamelCase
+6. [ ] `depends_on` ordering: build deps before runtime deps
+7. [ ] `version` and `sha256` fields present and correct
+8. [ ] `livecheck` block present for updateable formulae
+9. [ ] `test` block exercises at least the CLI entry point
+
+## Editor LSP Configuration
+
+### VSCode
+Install the **Ruby LSP** extension (Shopify). Configure in `.vscode/settings.json`:
+```json
+{
+  "rubyLsp.bundleGemfile": "Gemfile",
+  "rubyLsp.formatter": "rubocop",
+  "rubyLsp.linters": ["rubocop"],
+  "LSP": {
+    "ruby-lsp": { "enabled": true },
+    "fish-lsp": { "enabled": true }
+  }
+}
+```
+
+### Zed
+```json
+{
+  "lsp": {
+    "ruby-lsp": {
+      "initialization_options": {
+        "enabledFeatures": { "diagnostics": true, "formatting": true }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Homebrew Agent Ecosystem
+
+This project includes a complete Homebrew agent ecosystem for AI-assisted tap development.
+
+### Agent: `@homebrew-agent`
+
+The primary agent for Homebrew packaging tasks. Invoke with `@homebrew-agent` or via commands.
+
+### Commands
+
+| Command | Purpose | Example |
+|---------|---------|---------|
+| `homebrew:env` | Inspect brew environment | `homebrew:env --json` |
+| `homebrew:deps` | Show formula dependencies | `homebrew:deps git` |
+| `homebrew:search` | Search formulae/casks | `homebrew:search python` |
+| `homebrew:create` | Create tap from source | `homebrew:create --source /path/to/project` |
+| `homebrew:analyze` | Analyze source type | `homebrew:analyze --dir /path/to/project` |
+
+### Tool Scripts
+
+Located in `src/scripts/`:
+- `brew-env.sh` — Environment inspection
+- `brew-deps.sh` — Dependency analysis
+- `brew-search.sh` — Package search
+- `brew-analyze.sh` — Source type detection
+- `brew-template.sh` — Template application
+
+### Workflow Scripts
+
+Located in `src/workflows/`:
+- `create-tap.sh` — End-to-end tap creation
+- `analyze-source.sh` — Rich analysis report
+- `convert-npm-to-bun.sh` — npm to bun conversion