opencode-homebrew-agent 1.0.0

package/src/templates/taps/08-go-binary/AGENTS.md

@@ -0,0 +1,86 @@
+---
+name: homebrew-tap-go-binary
+description: Creates and maintains Homebrew taps for Go CLI tools that build from source.
+---
+
+# homebrew-tap-go-binary
+
+Agent for working with Go Binary tap templates.
+
+## Description
+Helps create and maintain Homebrew taps for Go CLI tools that build from source.
+
+## Stacks
+- homebrew
+- go
+- ruby
+
+## Requires
+- basic-homebrew-knowledge
+
+## Key Actions
+
+### Go Build Pattern
+```ruby
+depends_on "go" => :build
+
+def install
+  system "go", "build", *std_go_args(ldflags: "-s -w -X main.version=#{version}")
+end
+```
+
+### With Module Path
+```ruby
+def install
+  ENV["GOPATH"] = buildpath
+  path = buildpath/"src/github.com/<user>/<repo>"
+  path.install Dir["*"]
+  cd path do
+    system "go", "build", *std_go_args(ldflags: "-s -w -X main.version=#{version}")
+  end
+end
+```
+
+### Common ldflags
+- `-s -w` — strip debug information (smaller binary)
+- `-X main.version=#{version}` — inject version at build time
+- `-X main.commit=#{Utils.git_head}` — inject commit hash
+
+### Permissions
+- Read/write to `Formula/` and `scripts/`
+- Network access for Go module downloads
+
+### Common Pitfalls
+
+- `depends_on "go" => :build` is required — without `=> :build`, Go becomes a runtime dependency and users must install it to use your binary.
+- `ldflags` must be a single string: `"-s -w -X main.version=#{version}"`. Multiple arguments will cause a `go build` error.
+- Module-aware projects (Go 1.11+) should NOT use the GOPATH layout. Uncomment the GOPATH `def install` only for legacy projects.
+
+### 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
+```

package/src/templates/taps/08-go-binary/tap-structure/Formula/_formula.rb

@@ -0,0 +1,40 @@
+
+# Go CLI tool formula — builds from source.
+# 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"
+
+  depends_on "go" => :build
+
+  livecheck do
+    url :stable
+    regex(/^v?(\d+(?:\.\d+)+)$/i)
+  end
+
+  def install
+    ldflags = "-s -w -X main.version=#{version}"
+    system "go", "build", *std_go_args(ldflags: ldflags)
+  end
+
+  # Alternative: traditional GOPATH layout
+  # def install
+  #   ENV["GOPATH"] = buildpath
+  #   path = buildpath/"src/github.com/<user>/<repo>"
+  #   path.install Dir["*"]
+  #   cd path do
+  #     ldflags = "-s -w -X main.version=#{version}"
+  #     system "go", "build", *std_go_args(ldflags: ldflags)
+  #   end
+  # end
+
+  test do
+    assert_match version.to_s, shell_output("#{bin}/<cli> --version")
+  end
+end

package/src/templates/taps/08-go-binary/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/08-go-binary/tap-structure/scripts/release.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Version bump script for Go binary 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}\"")
+
+File.write(FORMULA_FILE, formula_content)
+puts "Done. Formula updated to v#{version}."
+puts "Review: git diff Formula/<formula>.rb"

package/src/templates/taps/08-go-binary/template.md

@@ -0,0 +1,60 @@
+# Template 08: Go Binary
+
+## Pattern: CLI tools written in Go
+
+For Go CLI tools that build from source using `go build`. Common for
+modern cloud/CLI tools (e.g., `gh`, `docker`, `kubectl` clone). Uses
+`depends_on "go" => :build` and compiles during `brew install`.
+
+### Structure
+
+```
+homebrew-<tap>/
+├── Formula/
+│   └── <formula>.rb        # Formula with Go build
+├── scripts/
+│   └── release.rb   # (optional) Version bump script
+├── .gitignore
+├── LICENSE
+└── README.md
+```
+
+### Key Formula Pattern
+
+```ruby
+depends_on "go" => :build
+
+def install
+  system "go", "build", *std_go_args(ldflags: "-s -w -X main.version=#{version}")
+end
+
+# Alternative: traditional GOPATH layout (uncomment if needed)
+# def install
+#   ENV["GOPATH"] = buildpath
+#   path = buildpath/"src/github.com/<user>/<repo>"
+#   path.install Dir["*"]
+#   cd path do
+#     system "go", "build", *std_go_args(ldflags: "-s -w -X main.version=#{version}")
+#   end
+# end
+```
+
+### When to Use
+
+- Your CLI tool is written in Go
+- The source is available on GitHub
+- You want to build from source (not download a pre-built binary)
+- You want to set version via `ldflags` at build time
+
+### When NOT to Use
+
+- The Go tool is distributed as a pre-built binary (use template 03 instead)
+- The tool requires CGo with external C libraries (add `depends_on` as needed)
+
+### Reference
+
+- `std_go_args` is a Homebrew helper that sets `-o`, `-trimpath`, etc.
+- Common `ldflags`: `-s -w` (strip debug), `-X main.version=#{version}` (inject version)
+- For module-based projects, `GOPROXY` may need setting via `ENV`
+
+- Start with `brew tap-new <user>/homebrew-<tapname>` to generate the CI skeleton (optional — manual structure works too)

package/src/workflows/analyze-source.sh

@@ -0,0 +1,124 @@
+#!/bin/bash
+# workflows/analyze-source.sh
+# Rich wrapper around brew-analyze.sh with human-readable output.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+ANALYZE="${PROJECT_ROOT}/scripts/brew-analyze.sh"
+
+# --- Usage ---
+usage() {
+  cat << 'EOF'
+Usage: analyze-source.sh [OPTIONS]
+
+Analyze a source directory or GitHub URL and recommend a Homebrew template.
+
+Options:
+  --dir <path>       Analyze local directory
+  --url <github-url> Analyze GitHub URL
+  --json             Output raw JSON
+  --human            Output human-readable report (default)
+  --help             Show this help message
+EOF
+}
+
+# --- Parse args ---
+DIR=""
+URL=""
+JSON_MODE=false
+HUMAN_MODE=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dir) DIR="$2"; shift 2 ;;
+    --url) URL="$2"; shift 2 ;;
+    --json) JSON_MODE=true; shift ;;
+    --human) HUMAN_MODE=true; shift ;;
+    --help) usage; exit 0 ;;
+    *) echo "error: unknown option: $1" >&2; usage >&2; exit 1 ;;
+  esac
+done
+
+# --- Determine mode ---
+if $JSON_MODE; then
+  if [[ -n "$DIR" ]]; then
+    "$ANALYZE" --dir "$DIR" --json
+  elif [[ -n "$URL" ]]; then
+    "$ANALYZE" --url "$URL" --json
+  else
+    echo "error: --dir or --url required" >&2
+    usage >&2
+    exit 1
+  fi
+  exit 0
+fi
+
+# --- Run analysis ---
+if [[ -n "$DIR" ]]; then
+  ANALYSIS=$("$ANALYZE" --dir "$DIR" --json 2>/dev/null)
+  SOURCE="$DIR"
+elif [[ -n "$URL" ]]; then
+  ANALYSIS=$("$ANALYZE" --url "$URL" --json 2>/dev/null)
+  SOURCE="$URL"
+else
+  echo "error: --dir or --url required" >&2
+  usage >&2
+  exit 1
+fi
+
+# --- Parse JSON ---
+TYPE=$(echo "$ANALYSIS" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("type","unknown"))')
+TEMPLATE=$(echo "$ANALYSIS" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("template","02"))')
+TEMPLATE_NAME=$(echo "$ANALYSIS" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("template_name","root-level"))')
+CONFIDENCE=$(echo "$ANALYSIS" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("confidence","low"))')
+MARKERS=$(echo "$ANALYSIS" | python3 -c 'import sys,json; print(" ".join(json.load(sys.stdin).get("markers",[])))')
+
+# --- Complexity estimation ---
+COMPLEXITY="simple"
+case "$TYPE" in
+  simple-script|root-level) COMPLEXITY="simple" ;;
+  node-npm|python-venv|go-binary) COMPLEXITY="medium" ;;
+  full-ci|cask|keg-only) COMPLEXITY="complex" ;;
+  *) COMPLEXITY="unknown" ;;
+esac
+
+# --- Print report ---
+cat << EOF
+
+Source Analysis Report
+======================
+Source:       $SOURCE
+
+Detected Type
+-------------
+Project type: $TYPE
+Template:     $TEMPLATE ($TEMPLATE_NAME)
+Confidence:   $CONFIDENCE
+Markers:      $MARKERS
+
+Complexity Estimate
+-------------------
+$COMPLEXITY
+
+Next Steps
+----------
+To scaffold this as a Homebrew tap, run:
+
+  bash workflows/create-tap.sh --source "$SOURCE" --name <FormulaName> --tap <user>/homebrew-<tap>
+
+Or with all options:
+
+  bash workflows/create-tap.sh \
+    --source "$SOURCE" \
+    --name MyCli \
+    --tap myuser/homebrew-mycli \
+    --output ./mytap \
+    --non-interactive
+
+EOF
+
+if [[ "$TYPE" == "node-npm" ]]; then
+  echo "Note: This project uses npm. You can convert to bun with --convert-to-bun"
+  echo ""
+fi

package/src/workflows/convert-npm-to-bun.sh

@@ -0,0 +1,112 @@
+#!/bin/bash
+# workflows/convert-npm-to-bun.sh
+# Convert an npm-based Homebrew formula to use bun.
+set -euo pipefail
+
+# --- Usage ---
+usage() {
+  cat << 'EOF'
+Usage: convert-npm-to-bun.sh [OPTIONS]
+
+Convert an npm-based Homebrew formula to use bun.
+
+Options:
+  --formula <path>  Path to the formula .rb file
+  --check           Only check if conversion is possible
+  --dry-run         Show what would change without modifying
+  --help            Show this help message
+
+Examples:
+  convert-npm-to-bun.sh --formula Formula/my-cli.rb --dry-run
+  convert-npm-to-bun.sh --formula Formula/my-cli.rb
+EOF
+}
+
+# --- Parse args ---
+FORMULA=""
+CHECK=false
+DRY_RUN=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --formula) FORMULA="$2"; shift 2 ;;
+    --check) CHECK=true; shift ;;
+    --dry-run) DRY_RUN=true; shift ;;
+    --help) usage; exit 0 ;;
+    *) echo "error: unknown option: $1" >&2; usage >&2; exit 1 ;;
+  esac
+done
+
+# --- Validate ---
+if [[ -z "$FORMULA" ]]; then
+  echo "error: --formula is required" >&2
+  usage >&2
+  exit 1
+fi
+
+if [[ ! -f "$FORMULA" ]]; then
+  echo "error: file not found: $FORMULA" >&2
+  exit 1
+fi
+
+# --- Check for bun ---
+if ! command -v bun >/dev/null 2>&1; then
+  echo "warning: bun is not installed. Install with: brew install oven-sh/bun/bun" >&2
+fi
+
+# --- Analyze formula ---
+if grep -q 'depends_on.*"bun"' "$FORMULA"; then
+  echo "info: formula already uses bun — nothing to convert" >&2
+  exit 0
+fi
+
+if ! grep -q 'depends_on.*"node"' "$FORMULA"; then
+  echo "error: no npm/node dependency found in formula" >&2
+  exit 1
+fi
+
+if $CHECK; then
+  echo "info: conversion is possible (npm formula detected)" >&2
+  exit 0
+fi
+
+# --- Compute changes ---
+TMP_FORMULA=$(mktemp -p /tmp)
+trap 'rm -f "$TMP_FORMULA"' EXIT
+
+cp "$FORMULA" "$TMP_FORMULA"
+
+# Replace node dependency with bun
+sed -i.bak 's/depends_on "node"/depends_on "bun"/' "$TMP_FORMULA"
+
+# Replace npm install with bun install
+sed -i.bak 's/system "npm", "install", \*std_npm_args/system "bun", "install"/' "$TMP_FORMULA"
+sed -i.bak 's/system "npm", "install"/system "bun", "install"/' "$TMP_FORMULA"
+
+# Add bun tap note comment after the bun dependency line
+awk '/depends_on "bun"/ { print; print "  # NOTE: bun is provided by oven-sh/bun tap: brew tap oven-sh/bun"; next } 1' "$TMP_FORMULA" > "${TMP_FORMULA}.tmp"
+mv "${TMP_FORMULA}.tmp" "$TMP_FORMULA"
+
+rm -f "$TMP_FORMULA.bak"
+
+# --- Show diff ---
+if $DRY_RUN; then
+  echo "=== Proposed changes ===" >&2
+  diff -u "$FORMULA" "$TMP_FORMULA" || true
+  echo "" >&2
+  echo "Run without --dry-run to apply changes" >&2
+  exit 0
+fi
+
+# --- Apply changes ---
+cp "$TMP_FORMULA" "$FORMULA"
+
+# --- Validate ---
+echo "=== Validating converted formula ===" >&2
+if ruby -c "$FORMULA" >&2; then
+  echo "Formula syntax: OK" >&2
+  echo "Conversion complete: $FORMULA" >&2
+else
+  echo "error: converted formula has syntax errors" >&2
+  exit 1
+fi

package/src/workflows/create-tap.sh

@@ -0,0 +1,196 @@
+#!/bin/bash
+# workflows/create-tap.sh
+# End-to-end workflow: analyze source, recommend template, scaffold tap.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+ANALYZE="${PROJECT_ROOT}/scripts/brew-analyze.sh"
+TEMPLATE="${PROJECT_ROOT}/scripts/brew-template.sh"
+
+# --- Defaults ---
+SOURCE=""
+NAME=""
+TAP=""
+OUTPUT=""
+NON_INTERACTIVE=false
+CONVERT_TO_BUN=false
+
+# --- Usage ---
+usage() {
+  cat << 'EOF'
+Usage: create-tap.sh [OPTIONS]
+
+Create a Homebrew tap from a source directory or GitHub URL.
+
+Options:
+  --source <url|path>   Source to analyze (GitHub URL or local directory)
+  --name <formula>      Formula name (CamelCase or kebab-case)
+  --tap <user/tap>      Tap identifier (e.g., user/homebrew-mytap)
+  --output <path>       Output directory for the tap
+  --non-interactive     Skip all prompts
+  --convert-to-bun      Prefer bun over npm for node projects
+  --help                Show this help message
+
+Examples:
+  create-tap.sh --source https://github.com/user/cli-tool --name mycli --tap myuser/homebrew-mycli --output ./mytap --non-interactive
+  create-tap.sh --source /path/to/project --non-interactive
+EOF
+}
+
+# --- Parse args ---
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --source) SOURCE="$2"; shift 2 ;;
+    --name) NAME="$2"; shift 2 ;;
+    --tap) TAP="$2"; shift 2 ;;
+    --output) OUTPUT="$2"; shift 2 ;;
+    --non-interactive) NON_INTERACTIVE=true; shift ;;
+    --convert-to-bun) CONVERT_TO_BUN=true; shift ;;
+    --help) usage; exit 0 ;;
+    *) echo "error: unknown option: $1" >&2; usage >&2; exit 1 ;;
+  esac
+done
+
+# --- Validate ---
+if [[ -z "$SOURCE" ]]; then
+  echo "error: --source is required" >&2
+  usage >&2
+  exit 1
+fi
+
+# --- Interactive prompts ---
+prompt() {
+  local var_name="$1"
+  local question="$2"
+  local default="${3:-}"
+  if $NON_INTERACTIVE; then
+    echo "error: $var_name is required in non-interactive mode" >&2
+    exit 1
+  fi
+  if [[ -n "$default" ]]; then
+    read -rp "$question [$default]: " val
+    val="${val:-$default}"
+  else
+    read -rp "$question: " val
+  fi
+  if [[ -z "$val" ]]; then
+    echo "error: $var_name cannot be empty" >&2
+    exit 1
+  fi
+  printf -v "$var_name" '%s' "$val"
+}
+
+# --- Analyze source ---
+echo "=== Analyzing source: $SOURCE ===" >&2
+
+if [[ -d "$SOURCE" ]]; then
+  ANALYSIS=$("$ANALYZE" --dir "$SOURCE" --json 2>/dev/null)
+else
+  ANALYSIS=$("$ANALYZE" --url "$SOURCE" --json 2>/dev/null)
+fi
+
+TYPE=$(echo "$ANALYSIS" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("type","unknown"))')
+TEMPLATE_NUM=$(echo "$ANALYSIS" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("template","02"))')
+CONFIDENCE=$(echo "$ANALYSIS" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("confidence","low"))')
+
+echo "Detected type: $TYPE (template $TEMPLATE_NUM, confidence: $CONFIDENCE)" >&2
+
+# --- Gather metadata ---
+if [[ -z "$NAME" ]]; then
+  prompt NAME "Formula name (e.g., MyCli)"
+fi
+
+if [[ -z "$TAP" ]]; then
+  if [[ "$SOURCE" =~ github\.com/([^/]+)/([^/]+) ]]; then
+    DEFAULT_TAP="${BASH_REMATCH[1]}/homebrew-${BASH_REMATCH[2]}"
+  else
+    DEFAULT_TAP=""
+  fi
+  prompt TAP "Tap identifier (e.g., user/homebrew-mytap)" "$DEFAULT_TAP"
+fi
+
+# --- Auto-generate output directory ---
+# Smart fallback:
+#   GitHub URL: github.com/owner/repo-name → ./repo-name
+#   Local path: /path/to/my-project      → ./my-project
+#   Prepend "homebrew-" if not present
+if [[ -z "$OUTPUT" ]]; then
+  if [[ "$SOURCE" =~ github\.com/([^/]+)/([^/]+)(\.git)?$ ]]; then
+    # GitHub URL: use repo name
+    repo_name="${BASH_REMATCH[2]}"
+    # Strip .git suffix if present
+    repo_name="${repo_name%.git}"
+    raw_name="$repo_name"
+  else
+    # Local path: use basename
+    raw_name=$(basename "$SOURCE")
+  fi
+  
+  # Sanitize: lowercase, replace spaces with hyphens
+  raw_name=$(echo "$raw_name" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
+  
+  # Prepend "homebrew-" if not already present
+  if [[ "$raw_name" == homebrew-* ]]; then
+    DEFAULT_OUTPUT="./${raw_name}"
+  else
+    DEFAULT_OUTPUT="./homebrew-${raw_name}"
+  fi
+  
+  if $NON_INTERACTIVE; then
+    OUTPUT="$DEFAULT_OUTPUT"
+    echo "Auto-generated output directory: $OUTPUT" >&2
+  else
+    prompt OUTPUT "Output directory" "$DEFAULT_OUTPUT"
+  fi
+fi
+
+# --- Apply template ---
+echo "=== Generating tap structure ===" >&2
+
+TEMPLATE_ARGS=(
+  "$TYPE"
+  --name "$NAME"
+  --output "$OUTPUT"
+)
+
+if $CONVERT_TO_BUN; then
+  TEMPLATE_ARGS+=(--convert-to-bun)
+fi
+
+"$TEMPLATE" "${TEMPLATE_ARGS[@]}"
+
+# --- Validate ---
+FORMULA_FILE=""
+for f in "$OUTPUT"/Formula/*.rb; do
+  if [[ -f "$f" ]]; then
+    FORMULA_FILE="$f"
+    break
+  fi
+done
+
+if [[ -n "$FORMULA_FILE" ]]; then
+  echo "=== Validating formula ===" >&2
+  if ruby -c "$FORMULA_FILE" >&2; then
+    echo "Formula syntax: OK" >&2
+  else
+    echo "Warning: formula has syntax errors" >&2
+  fi
+fi
+
+# --- Summary ---
+echo "" >&2
+echo "=== Tap Created ===" >&2
+echo "Location:    $(cd "$OUTPUT" && pwd)" >&2
+echo "Tap:         $TAP" >&2
+echo "Formula:     $NAME" >&2
+echo "Template:    $TEMPLATE_NUM ($TYPE)" >&2
+echo "" >&2
+echo "Next steps:" >&2
+echo "  1. cd $(cd "$OUTPUT" && pwd)" >&2
+echo "  2. Edit the formula in Formula/" >&2
+echo "  3. Run: brew style --tap $TAP Formula/$NAME.rb" >&2
+echo "  4. Run: brew audit --new-formula Formula/$NAME.rb" >&2
+echo "  5. git init && git add . && git commit -m 'Initial commit'" >&2
+echo "  6. git remote add origin https://github.com/$TAP.git" >&2
+echo "  7. git push -u origin main" >&2