docs: add Homebrew install for fff-mcp (#345)

[jellydn]

Closes #345

Summary

Adds Homebrew as an install path for the fff-mcp MCP server binary, plus automation so the external tap stays on the latest stable release.

Tap & formula

• Tap: jellydn/homebrew-tap
• Formula: Formula/fff-mcp.rb
• Pins release v0.9.1 with sha256 checksums from GitHub release sidecars

Auto-bump (tap is outside this repo)

The tap is maintained in jellydn/homebrew-tap, not here. Automation lives there:

Mechanism	Behavior
Scheduled workflow	Every 6h, polls latest stable fff.nvim release and updates the formula
repository_dispatch	Instant bump when upstream notifies the tap
scripts/bump-fff-mcp.sh	Regenerates the formula from release .sha256 sidecars

This PR adds a bump-homebrew-tap job to release.yaml that dispatches fff-release-published after stable releases. Optional: add repo secret HOMEBREW_TAP_DISPATCH_TOKEN (fine-grained PAT with Contents: write on jellydn/homebrew-tap). Without it, the scheduled tap workflow still catches up within hours.

Setup details: tap workflow README.

README

brew install jellydn/tap/fff-mcp

Verified

brew install jellydn/tap/fff-mcp
/opt/homebrew/opt/fff-mcp/bin/fff-mcp --version
# fff-mcp 0.9.1 (1e055f9d7b94f33a7f393ac95e779bed72650d56f)

Tap bump workflow: https://github.com/jellydn/homebrew-tap/actions/workflows/bump-fff-mcp.yml

[jellydn]

PR babysit status

Marked draft → ready for review.

CI workflows were triggered but report action_required (typical for fork PRs until a maintainer approves workflow runs on this PR).

No code issues found in bump-homebrew-tap / README changes (YAML + actionlint validated locally).

Maintainer action needed: Approve pending workflow runs on the Actions tab.

Secrets (optional, for instant Homebrew tap bump after merge):

• HOMEBREW_TAP_DISPATCH_TOKEN — PAT with write on jellydn/homebrew-tap
• FFF_RELEASE_BUMP_SECRET — same value on tap repo

Without secrets, tap still auto-updates every 6h via scheduled workflow.

Note: #513 is an older bot draft for the same issue; this PR supersedes it (v0.9.1 + tap automation + auth restrictions).

[dmtrKovalenko]

thank you I really appreciate it though the biggest problem is that you harcode the version

what we actually need is to always store the lateest vesrion in the formula, that's why we need to have the formula in our repo and update it every time we bump the version so people can update using brew upgrade now you need to manually follow the version

[dmtrKovalenko]

@gustav-fff can you please preserving @jellydn config just move the homebrew tap to our repo and update it

keep the credits of making it to the original author but it would be easier for us to maintain it this way without relying on the other 3rd party repo

[gustav-fff]

[triage-bot] DIRECTED:

Cannot push — PR head is on fork jellydn/fff. Posting plan; @jellydn please apply on this branch (or open follow-up PR).

Plan

1. Add Formula/fff-mcp.rb to this repo (Homebrew taps work from any repo with top-level Formula/ dir). Install becomes brew install dmtrKovalenko/fff/fff-mcp.
2. Replace the bump-homebrew-tap job in .github/workflows/release.yaml with one that rewrites Formula/fff-mcp.rb in-repo from release .sha256 sidecars and commits to main. Drops dependency on HOMEBREW_TAP_DISPATCH_TOKEN / FFF_RELEASE_BUMP_SECRET.
3. Update README.md to point at dmtrKovalenko/fff tap. Keep credit line to @jellydn in formula header + README footnote.
4. Leave jellydn/homebrew-tap formula in place for transition; it can be deprecated separately.

Formula (Formula/fff-mcp.rb)

# Originally authored by @jellydn (https://github.com/jellydn/homebrew-tap).
# Maintained in-repo; auto-bumped by .github/workflows/release.yaml on stable releases.
class FffMcp < Formula
  desc "Fast file search toolkit for AI agents (MCP server)"
  homepage "https://github.com/dmtrKovalenko/fff.nvim"
  license "MIT"

  v = "0.9.1"

  on_macos do
    on_arm do
      url "https://github.com/dmtrKovalenko/fff.nvim/releases/download/v#{v}/fff-mcp-aarch64-apple-darwin"
      sha256 "cee75793fff67b25b95303c4708ec88b2c707f5ca51df5975a77330fc169f6ab"
    end
    on_intel do
      url "https://github.com/dmtrKovalenko/fff.nvim/releases/download/v#{v}/fff-mcp-x86_64-apple-darwin"
      sha256 "37b7d09098c5a1a0f036111e125885f58f3e3ec65d5eac7dd1f5f773407dd0c9"
    end
  end

  on_linux do
    on_arm do
      url "https://github.com/dmtrKovalenko/fff.nvim/releases/download/v#{v}/fff-mcp-aarch64-unknown-linux-gnu"
      sha256 "32cae6f55e0eed764d0ae150c2e6c9332608b131442b56a14d9afa9877294ef7"
    end
    on_intel do
      url "https://github.com/dmtrKovalenko/fff.nvim/releases/download/v#{v}/fff-mcp-x86_64-unknown-linux-gnu"
      sha256 "df96f1a25112d83117909b215e5e4a98917ac885163b23147c1819c4700a4f21"
    end
  end

  def install
    if OS.mac?
      bin.install (Hardware::CPU.arm? ? "fff-mcp-aarch64-apple-darwin" : "fff-mcp-x86_64-apple-darwin") => "fff-mcp"
    else
      bin.install (Hardware::CPU.arm? ? "fff-mcp-aarch64-unknown-linux-gnu" : "fff-mcp-x86_64-unknown-linux-gnu") => "fff-mcp"
    end
  end

  test do
    system bin/"fff-mcp", "--version"
  end
end

Auto-bump job (replace bump-homebrew-tap in .github/workflows/release.yaml)

  bump-homebrew-formula:
    name: Bump in-repo Homebrew formula
    needs: release
    runs-on: ubuntu-latest
    if: >-
      github.event_name == 'push'
      && github.repository_owner == 'dmtrKovalenko'
      && startsWith(github.ref, 'refs/tags/v')
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v5
        with:
          ref: main
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Determine version
        id: version
        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"

      - name: Fetch sha256 sidecars
        env:
          V: ${{ steps.version.outputs.version }}
        run: |
          base="https://github.com/dmtrKovalenko/fff.nvim/releases/download/v${V}"
          for t in aarch64-apple-darwin x86_64-apple-darwin aarch64-unknown-linux-gnu x86_64-unknown-linux-gnu; do
            curl -fsSL "${base}/fff-mcp-${t}.sha256" -o "/tmp/${t}.sha256"
          done

      - name: Rewrite formula
        env:
          V: ${{ steps.version.outputs.version }}
        run: |
          DARWIN_ARM=$(awk '{print $1}' /tmp/aarch64-apple-darwin.sha256)
          DARWIN_X64=$(awk '{print $1}' /tmp/x86_64-apple-darwin.sha256)
          LINUX_ARM=$(awk '{print $1}' /tmp/aarch64-unknown-linux-gnu.sha256)
          LINUX_X64=$(awk '{print $1}' /tmp/x86_64-unknown-linux-gnu.sha256)
          # regenerate Formula/fff-mcp.rb from template (heredoc) using $V and the four sha vars
          # ...see scripts/bump-homebrew-formula.sh

      - name: Commit if changed
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          if ! git diff --quiet Formula/fff-mcp.rb; then
            git add Formula/fff-mcp.rb
            git commit -m "chore: bump fff-mcp formula to v${{ steps.version.outputs.version }}"
            git push origin main
          fi

Recommend extracting the rewrite into scripts/bump-homebrew-formula.sh (port of @jellydn's bump-fff-mcp.sh) so it stays testable.

README change

Replace brew install jellydn/tap/fff-mcp with:

brew install dmtrKovalenko/fff/fff-mcp

Keep one-line credit: "Formula originally authored by @jellydn."

Open question

Push directly to main from the workflow, or open auto-PR via peter-evans/create-pull-request? Direct push is simpler (brew upgrade works immediately after release) but bypasses review. Default: direct push, gated on github.repository_owner == 'dmtrKovalenko' + tag refs only — same guard already in bump-homebrew-tap.

Honk-Honk 🪿

[dmtrKovalenko]

@gustav-fff can you just do gh pr checkout 571 and then commit + push? thx

[jellydn]

Addressed review feedback:

1. No hardcoded version in docs — Formula/fff-mcp.rb lives in this repo and is regenerated on every stable release via bump-homebrew-formula (commits to main after assets publish). Users can brew upgrade fff-mcp when a new version ships.

2. Tap moved in-repo — install path is now:

   brew install dmtrKovalenko/fff/fff-mcp

   Credit to @jellydn preserved in the formula header and README.

3. Dropped external jellydn/homebrew-tap dispatch — no HOMEBREW_TAP_DISPATCH_TOKEN / FFF_RELEASE_BUMP_SECRET needed on this repo.

Files added: Formula/fff-mcp.rb, scripts/bump-fff-mcp.sh. Release job updated in .github/workflows/release.yaml.

[gustav-fff]

[triage-bot] DIRECTED:

Nothing to commit. Branch feat/homebrew-install-345 is clean; local HEAD 339272f matches fork tip jellydn/fff@feat/homebrew-install-345. @jellydn already pushed the three plan items:

• b166e8a — Formula/fff-mcp.rb in-repo + bump-homebrew-formula job in .github/workflows/release.yaml
• 339272f — formula uses version DSL + #{version} URLs (no hardcoded path repetition)
• README install line points at dmtrKovalenko/fff/fff-mcp (README.md:43)

PR is also cross-repo (head on jellydn/fff), so gustav-fff cannot push to it regardless.

If something specific still needs changing (e.g. tweak Formula/fff-mcp.rb, adjust bump-fff-mcp.sh, README wording), name it and I'll prepare a diff for @jellydn to apply, or you can grant push access to gustav-fff on the fork.

Honk-Honk 🪿