Add CI/release workflows, snapshot tests, and pytest

- .github/workflows/ci.yml: test on Python 3.9/3.12/3.13 (macOS)
- .github/workflows/release.yml: PyPI trusted publishing + GitHub release on tag
- tests/snap.py: Jane Street expect-test style snapshot helper
- tests/test_cli.py: 8 tests covering help, version, cache JSON, duration
  parsing/formatting, FTS scoring, query building, and .rb parser
- UPDATE_SNAPSHOTS=1 to regenerate snapshots

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: mcint

.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: macos-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install
+        run: uv sync --python ${{ matrix.python-version }}
+      - name: Smoke test
+        run: |
+          uv run brew-hop-search --help
+          uv run python -c "from brew_hop_search import __version__; print(__version__)"
+      - name: Run tests
+        run: uv run python -m pytest tests/ -v

.github/workflows/release.yml

@@ -0,0 +1,61 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Build
+        run: uv build
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi-publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/brew-hop-search/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create ${{ github.ref_name }} dist/* \
+            --title "${{ github.ref_name }}" \
+            --generate-notes

pyproject.toml

@@ -22,6 +22,9 @@ classifiers = [
 ]
 dependencies = ["sqlite-utils"]
 
+[dependency-groups]
+dev = ["pytest"]
+
 [project.scripts]
 brew-hop-search = "brew_hop_search.cli:main"
 

tests/__init__.py

@@ -0,0 +1,64 @@
+"""Snapshot testing helper — Jane Street expect-test style.
+
+Usage in tests:
+    from tests.snap import snap
+
+    def test_help(snap):
+        result = subprocess.run(["brew-hop-search", "--help"], capture_output=True, text=True)
+        snap.assert_match(result.stdout)
+
+On first run (or with UPDATE_SNAPSHOTS=1), writes the snapshot file.
+On subsequent runs, diffs against stored snapshot.
+To update: UPDATE_SNAPSHOTS=1 pytest tests/
+"""
+from __future__ import annotations
+
+import os
+import textwrap
+from pathlib import Path
+
+import pytest
+
+SNAP_DIR = Path(__file__).parent / "snapshots"
+UPDATE = os.environ.get("UPDATE_SNAPSHOTS", "") == "1"
+
+
+class Snap:
+    def __init__(self, name: str):
+        self.path = SNAP_DIR / f"{name}.txt"
+        self._call_count = 0
+
+    def assert_match(self, actual: str, suffix: str = "") -> None:
+        self._call_count += 1
+        snap_path = self.path.with_suffix(f".{suffix}.txt") if suffix else self.path
+        if self._call_count > 1 and not suffix:
+            snap_path = self.path.with_suffix(f".{self._call_count}.txt")
+
+        actual = actual.rstrip("\n") + "\n"
+
+        if UPDATE or not snap_path.exists():
+            SNAP_DIR.mkdir(parents=True, exist_ok=True)
+            snap_path.write_text(actual)
+            return
+
+        expected = snap_path.read_text()
+        if actual != expected:
+            # Show unified diff
+            import difflib
+            diff = difflib.unified_diff(
+                expected.splitlines(keepends=True),
+                actual.splitlines(keepends=True),
+                fromfile=f"expected ({snap_path.name})",
+                tofile="actual",
+            )
+            diff_str = "".join(diff)
+            pytest.fail(
+                f"Snapshot mismatch for {snap_path.name}.\n"
+                f"Run with UPDATE_SNAPSHOTS=1 to update.\n\n{diff_str}"
+            )
+
+
+@pytest.fixture
+def snap(request) -> Snap:
+    """Pytest fixture — snapshot name derived from test function name."""
+    return Snap(request.node.name)

tests/snap.py

@@ -0,0 +1,25 @@
+usage: brew-hop-search [-h] [--refresh] [-f] [-c] [-i] [-t] [-L] [-C]
+                       [--stale DUR] [--fresh DUR] [-n N] [--json] [-g]
+                       [query]
+
+Fast offline-first Homebrew formula/cask search.
+
+positional arguments:
+  query                 Search query
+
+options:
+  -h, --help            show this help message and exit
+  --refresh             Force synchronous re-fetch before searching
+  -f, --formulae, --formula
+                        Search formulae only
+  -c, --casks, --cask   Search casks only
+  -i, --installed       Search only installed packages
+  -t, --taps            Also search formulae/casks from tapped repos
+  -L, --local           Search brew's local API cache (offline)
+  -C, --cache           Show cache status and exit
+  --stale DUR           Background refresh if cache older than DUR (default:
+                        6h)
+  --fresh DUR           Force synchronous refresh if cache older than DUR
+  -n N, --limit N       Max results per section (default 20)
+  --json                Output raw JSON
+  -g, --grep            Greppable output: slug\tversion\turl\n description

tests/snapshots/test_help.txt

@@ -0,0 +1,108 @@
+"""Snapshot tests for brew-hop-search CLI output."""
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+
+import pytest
+
+from tests.snap import snap  # noqa: F401 (fixture)
+
+
+def run(*args: str) -> str:
+    """Run brew-hop-search and return stdout, stripping ANSI codes."""
+    result = subprocess.run(
+        [sys.executable, "-m", "brew_hop_search.cli", *args],
+        capture_output=True, text=True, timeout=30,
+    )
+    # Strip ANSI escape codes for stable snapshots
+    clean = re.sub(r"\033\[[0-9;]*m", "", result.stdout + result.stderr)
+    return clean
+
+
+def test_help(snap):
+    snap.assert_match(run("--help"))
+
+
+def test_version_importable():
+    from brew_hop_search import __version__
+    assert re.match(r"\d+\.\d+\.\d+", __version__)
+
+
+def test_cache_status_json():
+    """Cache status JSON should be valid and have expected keys."""
+    import json
+    output = run("-C", "--json")
+    data = json.loads(output)
+    assert "cache_dir" in data
+    assert "db_path" in data
+    assert "sources" in data
+
+
+def test_duration_parsing():
+    from brew_hop_search.cli import parse_duration
+    assert parse_duration("30m") == 1800
+    assert parse_duration("6h") == 21600
+    assert parse_duration("1d") == 86400
+    assert parse_duration("1h30m") == 5400
+    assert parse_duration("90") == 90
+
+
+def test_duration_formatting():
+    from brew_hop_search.display import fmt_duration
+    assert fmt_duration(30) == "30s"
+    assert fmt_duration(90) == "1m30s"
+    assert fmt_duration(3600) == "1h"
+    assert fmt_duration(3660) == "1h1m"
+    assert fmt_duration(86400) == "1d"
+    assert fmt_duration(float("inf")) == "never"
+
+
+def test_scoring():
+    from brew_hop_search.search import score
+    # Exact match
+    assert score("python", "", ["python"]) == 100
+    # Prefix match
+    assert score("python3", "", ["python"]) == 60
+    # Substring match
+    assert score("cpython", "", ["python"]) == 30
+    # Description match
+    assert score("foo", "uses python", ["python"]) == 10
+    # No match
+    assert score("foo", "bar", ["python"]) == 0
+    # All terms must match
+    assert score("python", "language", ["python", "java"]) == 0
+
+
+def test_fts_query():
+    from brew_hop_search.search import fts_query
+    assert fts_query(["python"]) == '"python"*'
+    assert fts_query(["python", "build"]) == '"python"* AND "build"*'
+
+
+def test_rb_parser():
+    """Test the lightweight Ruby formula parser."""
+    import tempfile
+    from pathlib import Path
+    from brew_hop_search.sources.taps import parse_rb
+
+    rb_content = '''
+cask "test-app" do
+  version "1.2.3"
+  desc "A test application"
+  homepage "https://example.com"
+  url "https://example.com/download/v1.2.3/test.dmg"
+end
+'''
+    with tempfile.NamedTemporaryFile(suffix=".rb", mode="w", delete=False) as f:
+        f.write(rb_content)
+        f.flush()
+        result = parse_rb(Path(f.name), "test/tap")
+
+    assert result is not None
+    assert result["name"] == Path(f.name).stem
+    assert result["version"] == "1.2.3"
+    assert result["desc"] == "A test application"
+    assert result["homepage"] == "https://example.com"
+    assert result["tap"] == "test/tap"