mdfetch 0.5.0__tar.gz → 0.5.2__tar.gz

mdfetch-0.5.2/.github/workflows/publish.yml

@@ -0,0 +1,120 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    if: github.event.release.target_commitish == 'main'
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+      - name: Set up Python
+        run: uv python pin 3.12
+      - name: Validate version
+        run: |
+          TAG_VERSION=${GITHUB_REF_NAME#v}
+          TOML_VERSION=$(uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          if [ "$TAG_VERSION" != "$TOML_VERSION" ]; then
+            echo "Error: Tag version ($TAG_VERSION) does not match pyproject.toml version ($TOML_VERSION)"
+            exit 1
+          fi
+      - name: Build package
+        run: make build
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mdfetch
+    permissions:
+      id-token: write
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+  update-homebrew-tap:
+    name: Update Homebrew tap
+    runs-on: ubuntu-latest
+    needs: publish
+    concurrency:
+      group: homebrew-tap-update
+      cancel-in-progress: false
+    permissions:
+      contents: read
+
+    steps:
+      - name: Fetch sdist info from PyPI (with retry)
+        env:
+          VERSION: ${{ github.ref_name }}
+        run: |
+          VERSION="${VERSION#v}"
+          SHA256=""
+          for i in 1 2 3; do
+            RESPONSE=$(curl -sf "https://pypi.org/pypi/mdfetch/${VERSION}/json" || true)
+            if [ -n "$RESPONSE" ]; then
+              SDIST_URL=$(echo "$RESPONSE" | python3 -c \
+                "import sys,json; d=json.load(sys.stdin); \
+                 urls=[u for u in d['urls'] if u['packagetype']=='sdist']; \
+                 print(urls[0]['url'] if urls else '')" 2>/dev/null || true)
+              SHA256=$(echo "$RESPONSE" | python3 -c \
+                "import sys,json; d=json.load(sys.stdin); \
+                 urls=[u for u in d['urls'] if u['packagetype']=='sdist']; \
+                 print(urls[0]['digests']['sha256'] if urls else '')" 2>/dev/null || true)
+              if [ -n "$SHA256" ] && [ -n "$SDIST_URL" ]; then break; fi
+            fi
+            echo "PyPI not ready, retrying in 30s (attempt $i/3)..."
+            sleep 30
+          done
+          if [ -z "$SHA256" ]; then
+            echo "ERROR: Could not fetch sdist info from PyPI after 3 retries" >&2; exit 1
+          fi
+          echo "SDIST_URL=${SDIST_URL}" >> "$GITHUB_ENV"
+          echo "SHA256=${SHA256}"       >> "$GITHUB_ENV"
+          echo "VERSION=${VERSION}"     >> "$GITHUB_ENV"
+
+      - name: Clone homebrew-tap and update formula
+        env:
+          TAP_GITHUB_TOKEN: ${{ secrets.TAP_GITHUB_TOKEN }}
+        run: |
+          git clone "https://x-access-token:${TAP_GITHUB_TOKEN}@github.com/stn1slv/homebrew-tap.git"
+          cd homebrew-tap
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          sed -i "s|  url \"https://files.pythonhosted.org/packages/.*/mdfetch-.*\.tar\.gz\"|  url \"${SDIST_URL}\"|" \
+            Formula/md-fetch.rb
+          sed -i "0,/  sha256 \"[a-f0-9]*\"/{s|  sha256 \"[a-f0-9]*\"|  sha256 \"${SHA256}\"|}" Formula/md-fetch.rb
+
+          if ! grep -qF "  url \"${SDIST_URL}\"" Formula/md-fetch.rb; then
+            echo "ERROR: URL substitution made no change — formula URL pattern may have drifted" >&2; exit 1
+          fi
+          if ! grep -qF "  sha256 \"${SHA256}\"" Formula/md-fetch.rb; then
+            echo "ERROR: SHA256 substitution made no change — formula sha256 pattern may have drifted" >&2; exit 1
+          fi
+
+          git add Formula/md-fetch.rb
+          git commit -m "chore: bump md-fetch to v${VERSION}"
+          git pull --rebase
+          git push

mdfetch-0.5.2/.specify/feature.json

@@ -0,0 +1,3 @@
+{
+  "feature_directory": "specs/009-homebrew-tap-formula"
+}

{mdfetch-0.5.0 → mdfetch-0.5.2}/.specify/memory/changelog.md

@@ -1,3 +1,23 @@
+### mdfetch — Homebrew Tap Formula — 2026-05-16
+
+**Branch**: `009-homebrew-tap-formula`
+**Spec**: specs/009-homebrew-tap-formula
+
+**What was added**:
+- `Formula/md-fetch.rb` in `stn1slv/homebrew-tap` using `Language::Python::Virtualenv` pattern with 13 resource blocks; `depends_on "python@3.12"`; `uses_from_macos "libxml2"` and `uses_from_macos "libxslt"` (required by lxml); test block verifying `md-fetch --version`
+- `update-homebrew-tap` job in `.github/workflows/publish.yml`: polls PyPI JSON API (3×30s retry), patches formula url+sha256 via sed, commits and pushes to tap; `concurrency: group=homebrew-tap-update, cancel-in-progress: false` serializes concurrent release runs
+- `README.md` updated with `brew install stn1slv/tap/md-fetch` as secondary install option beneath `pip install mdfetch`
+- `homebrew-tap/README.md` updated with md-fetch row in Available Formulas table
+- TAP_GITHUB_TOKEN documented as required fine-grained PAT (`Contents: read+write` on `stn1slv/homebrew-tap` only)
+
+**New Components**:
+- `Formula/md-fetch.rb` (in `stn1slv/homebrew-tap`) — Homebrew formula
+- `update-homebrew-tap` CI job (in `.github/workflows/publish.yml`)
+
+**Tasks Completed**: 13/15 (T002 manual PAT setup, T015 post-merge verification pending)
+
+---
+
 ### mdfetch — Architecture Refactoring & CLI Improvements — 2026-05-16
 
 **Branch**: `refactor/reduce-duplication-and-robustness`

{mdfetch-0.5.0 → mdfetch-0.5.2}/.specify/memory/plan.md

@@ -165,8 +165,46 @@ tests/
 specs/                       # Speckit feature specifications
 pyproject.toml               # hatchling build backend, uv package manager
 Makefile                     # setup / test / integration / lint / typecheck / format / build / clean / upgrade-deps
+.github/workflows/
+├── ci.yml                   # lint + unit tests on push/PR (Python 3.12–3.14)
+├── integration.yml          # scheduled integration tests
+└── publish.yml              # PyPI publish + Homebrew tap update on release tag
 ```
 
+**External repository: `stn1slv/homebrew-tap`** [009-homebrew-tap-formula]
+```
+Formula/
+└── md-fetch.rb              # Language::Python::Virtualenv formula; 13 resource blocks;
+                             # depends_on "python@3.12"; uses_from_macos "libxml2" + "libxslt"
+README.md                    # Available Formulas table updated with md-fetch row
+```
+
+---
+
+## Homebrew Distribution Architecture [009-homebrew-tap-formula]
+
+```
+GitHub Release tag vX.Y.Z
+  ↓
+build job → publish job (PyPI)
+  ↓
+update-homebrew-tap job (NEW, needs: publish)
+  [concurrency: group=homebrew-tap-update, cancel-in-progress=false]
+  1. Poll https://pypi.org/pypi/mdfetch/{VERSION}/json (retry 3× / 30s)
+  2. Extract SDIST_URL and SHA256
+  3. Clone stn1slv/homebrew-tap via TAP_GITHUB_TOKEN (fine-grained PAT)
+  4. sed patch Formula/md-fetch.rb (url + first sha256 only)
+  5. git commit + pull --rebase + push
+```
+
+**Formula pattern**: `Language::Python::Virtualenv` — creates isolated venv in Cellar, installs 13 resource blocks, symlinks `libexec/bin/md-fetch` → `bin/md-fetch`.
+
+**System library dependencies** (required by `lxml` resource):
+- `uses_from_macos "libxml2"`
+- `uses_from_macos "libxslt"`
+
+**TAP_GITHUB_TOKEN**: Fine-grained PAT with `Contents: read+write` on `stn1slv/homebrew-tap` only. Stored as repository secret in `stn1slv/md-fetch`. Must NOT be a classic `repo`-scoped PAT.
+
 ---
 
 ## Constraints
@@ -261,4 +299,4 @@ Makefile                     # setup / test / integration / lint / typecheck / f
 
 ---
 
-*Last Updated: 2026-05-16 | Sources appended: [specs/004-remove-backoff/plan.md], [specs/005-substack-provider/plan.md], [specs/006-thenewstack-provider/plan.md]*
+*Last Updated: 2026-05-16 | Sources appended: [specs/004-remove-backoff/plan.md], [specs/005-substack-provider/plan.md], [specs/006-thenewstack-provider/plan.md], [specs/009-homebrew-tap-formula/plan.md]*

{mdfetch-0.5.0 → mdfetch-0.5.2}/.specify/memory/spec.md

@@ -175,6 +175,43 @@ A developer passes a thenewstack.io URL that does not point to an article (e.g.,
 
 ---
 
+### US-016 — Install md-fetch via Homebrew (P1)
+[Source: specs/009-homebrew-tap-formula]
+
+A macOS or Linux developer who does not want to manage a Python environment installs the `md-fetch` CLI using a single Homebrew command. After installation, the `md-fetch` binary is immediately available on the PATH without any additional configuration.
+
+**Acceptance Scenarios**:
+1. Given a macOS or Linux machine with Homebrew installed, when the user runs `brew install stn1slv/tap/md-fetch`, then the installation completes without errors and `md-fetch` is available on the PATH.
+2. Given a successful installation, when the user runs `md-fetch --version`, then the command exits with code 0 and outputs the installed package version.
+3. Given a successful installation, when the user runs `md-fetch <url>` with a supported URL, then the command returns Markdown output, confirming all dependencies are correctly bundled.
+4. Given an existing installation, when the user runs `brew upgrade stn1slv/tap/md-fetch`, then the installation upgrades to the latest published version.
+
+---
+
+### US-017 — Formula Stays in Sync with PyPI Releases (P2)
+[Source: specs/009-homebrew-tap-formula]
+
+When a new version of `md-fetch` is published to PyPI, the Homebrew formula in `stn1slv/homebrew-tap` is updated automatically without any manual intervention from the maintainer. Users running `brew upgrade` receive the new version promptly.
+
+**Acceptance Scenarios**:
+1. Given a new version is successfully published to PyPI, when the release pipeline completes, then the formula in `stn1slv/homebrew-tap` reflects the new version number and correct integrity checksum.
+2. Given a new version is successfully published to PyPI, when the release pipeline completes, then the tap update is committed and pushed without any manual step from the maintainer.
+3. Given the automated tap update fails (e.g., token invalid, network error), when the pipeline completes, then the failure is reported as a visible CI job failure.
+4. Given a published package, when a user on the previous formula version runs `brew upgrade`, then they receive the newly published version.
+
+---
+
+### US-018 — Discover Homebrew Installation via Documentation (P3)
+[Source: specs/009-homebrew-tap-formula]
+
+A new user reading the project README discovers that Homebrew is an installation option on macOS and can install `md-fetch` without reading further instructions.
+
+**Acceptance Scenarios**:
+1. Given the updated README, when a user visits the install section, then `brew install stn1slv/tap/md-fetch` is present as an installation option below the existing `pip install mdfetch` instruction.
+2. Given the README install section, when a user follows the brew instruction verbatim, then the installation succeeds.
+
+---
+
 ### US-006 — Integration Tests Pass Against Real dev.to Article URLs (P3)
 [Source: specs/002-devto-provider]
 
@@ -247,6 +284,17 @@ A developer runs the integration test suite and all dev.to integration tests pas
 - **FR-049**: The library MUST convert embedded third-party content (e.g., YouTube video iframes) in thenewstack.io articles to plain anchor links using the embed's source URL, discarding the embed wrapper — matching the pattern used by existing providers. [Source: specs/006-thenewstack-provider]
 - **FR-050**: The library MUST treat sponsored and native-advertising thenewstack.io article pages identically to editorial articles — extracting content as-is with no special detection, marking, or rejection. [Source: specs/006-thenewstack-provider]
 
+### Homebrew Distribution
+- **FR-051**: A Homebrew formula for the `md-fetch` package MUST be available in the `stn1slv/homebrew-tap` repository so that users can install the tool with standard Homebrew commands. [Source: specs/009-homebrew-tap-formula]
+- **FR-052**: The formula MUST install a working `md-fetch` binary into Homebrew's `bin/` directory, making it immediately available on the user's PATH after installation. [Source: specs/009-homebrew-tap-formula]
+- **FR-053**: The formula MUST bundle all runtime dependencies so that no external Python environment or manual dependency installation is required. [Source: specs/009-homebrew-tap-formula]
+- **FR-054**: The formula MUST include a `brew test` block that verifies the installed binary runs successfully (`md-fetch --version` exits with code 0). [Source: specs/009-homebrew-tap-formula]
+- **FR-055**: When a new version is published to PyPI, the release pipeline MUST automatically update the formula with the new version and correct integrity checksum. The checksum fetch MUST retry up to 3 times with 30-second intervals before failing. [Source: specs/009-homebrew-tap-formula]
+- **FR-056**: The automated formula update MUST commit and push to `stn1slv/homebrew-tap` using a dedicated fine-grained PAT (`Contents: read+write` on that repository only). [Source: specs/009-homebrew-tap-formula]
+- **FR-057**: If the automated formula update step fails for any reason, the failure MUST surface as a failed CI job, preventing silent divergence between PyPI and Homebrew. [Source: specs/009-homebrew-tap-formula]
+- **FR-058**: The project README MUST include the `brew install stn1slv/tap/md-fetch` command as a secondary install option beneath `pip install mdfetch`. [Source: specs/009-homebrew-tap-formula]
+- **FR-059**: The `TAP_GITHUB_TOKEN` secret (a fine-grained PAT with `Contents: read+write` on `stn1slv/homebrew-tap`) must be documented as a required repository secret for the automation to function. [Source: specs/009-homebrew-tap-formula]
+
 ### dev.to Platform
 - **FR-015**: The library MUST add `dev.to` to the provider router so that any URL with the `dev.to` domain is dispatched to the dev.to provider without any change to the caller's code. [Source: specs/002-devto-provider]
 - **FR-016**: The library MUST include a dev.to provider that fetches the article page, isolates the main article body from `<div id="article-body">`, removes all non-content elements (navigation, social reaction widgets, comments, author sidebar, tag links), and returns the body as Markdown. [Source: specs/002-devto-provider]
@@ -304,6 +352,23 @@ A developer runs the integration test suite and all dev.to integration tests pas
 
 **Validation**: Page must contain `div#tns-post-body-content`; absent → `UnsupportedContentTypeError`. Body must yield non-empty text after stripping → else `EmptyContentError`. No paywall — all thenewstack.io articles are publicly accessible.
 
+### Homebrew Formula
+[Source: specs/009-homebrew-tap-formula]
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `url` | `str` | PyPI sdist tarball URL, changes on every release |
+| `sha256` | `str` | Hex SHA-256 of the sdist tarball, changes on every release |
+| `depends_on` | `str` | `"python@3.12"` (static) |
+| `uses_from_macos` | `list[str]` | `["libxml2", "libxslt"]` — required by `lxml` resource |
+| `resource` blocks | 13 entries | All runtime dependencies pinned to versions in `uv.lock` at formula creation time |
+
+**Mutable fields per release**: `url` and `sha256` only. All `resource` blocks are static until a separate manual dependency-bump PR.
+
+### TAP_GITHUB_TOKEN
+[Source: specs/009-homebrew-tap-formula]
+
+A GitHub fine-grained Personal Access Token with `Contents: read+write` on `stn1slv/homebrew-tap` only. Stored as a repository secret in `stn1slv/md-fetch` and consumed exclusively by the `update-homebrew-tap` CI job.
+
 ### ExtractionResult (Output)
 | Attribute | Type | Description |
 |-----------|------|-------------|
@@ -379,6 +444,12 @@ caller provides URL string
 - **thenewstack.io sponsored content**: `div.tns-sponsor-note` (mid-article sponsor injection) and three disclosure div variants are inside `div#tns-post-body-content` and must be decomposed before conversion. Sponsored article pages are extracted identically to editorial articles (FR-050). [Source: specs/006-thenewstack-provider]
 - **thenewstack.io deck element**: `div.post-excerpt` is a `<div>`, not a semantic subtitle element; the extractor creates a new `<p>` tag with the deck text rather than copying the div directly, to ensure proper paragraph rendering. [Source: specs/006-thenewstack-provider]
 - **thenewstack.io HTML structure changes**: If the site redesign moves content outside `div#tns-post-body-content`, the extractor will require an update.
+- **Homebrew tap temporarily unavailable**: If `stn1slv/homebrew-tap` is unreachable when the pipeline tries to push, `git push` fails and the CI job surfaces a failure — the maintainer must retry manually. [Source: specs/009-homebrew-tap-formula]
+- **TAP_GITHUB_TOKEN expired or revoked**: `git clone` or `git push` exits non-zero → CI job fails → maintainer is alerted to rotate the token. [Source: specs/009-homebrew-tap-formula]
+- **PyPI release yanked after formula update**: The formula is not automatically rolled back; the maintainer handles yanked-release scenarios manually. [Source: specs/009-homebrew-tap-formula]
+- **Concurrent releases**: Addressed by `concurrency: group=homebrew-tap-update, cancel-in-progress=false` — runs are serialized so the second release waits for the first tap-update to complete. [Source: specs/009-homebrew-tap-formula]
+- **brew test fails after install**: `brew test md-fetch` exits non-zero when a transitive dependency is missing or `md-fetch --version` fails — installation validation fails. [Source: specs/009-homebrew-tap-formula]
+- **Formula structure changed (sed no-op)**: If the formula is manually edited and the url/sha256 line format changes, `sed` produces no diff and `git commit` finds nothing staged → exits non-zero → CI job fails. [Source: specs/009-homebrew-tap-formula]
 
 ---
 
@@ -409,6 +480,12 @@ caller provides URL string
 - **SC-029**: The extracted Markdown for any thenewstack.io article contains no consecutive blank-line runs of three or more lines. [Source: specs/006-thenewstack-provider]
 - **SC-030**: The TheNewStack provider is exercised by integration tests using real network requests against all five reference article URLs, matching the pattern established by existing providers. [Source: specs/006-thenewstack-provider]
 
+- **SC-031**: A user with Homebrew installed can complete the full `md-fetch` installation using a single command, with no Python environment setup required, in under 3 minutes on a standard broadband connection. [Source: specs/009-homebrew-tap-formula]
+- **SC-032**: The Homebrew formula's built-in test (`brew test md-fetch`) passes on macOS and Linux after every installation. [Source: specs/009-homebrew-tap-formula]
+- **SC-033**: The formula in `stn1slv/homebrew-tap` is updated within 10 minutes of PyPI publish confirmation — no manual maintainer action is required. [Source: specs/009-homebrew-tap-formula]
+- **SC-034**: Formula update failures produce a visible CI job failure on every failed attempt, with zero silent failures. [Source: specs/009-homebrew-tap-formula]
+- **SC-035**: The README install section includes the Homebrew installation command, enabling users to discover and use it without prior knowledge of the project's Python packaging. [Source: specs/009-homebrew-tap-formula]
+
 ---
 
 ## Assumptions
@@ -428,7 +505,12 @@ caller provides URL string
 - **SC-015**: Zero changes are required in existing caller code to benefit from the Freedium fallback — existing integrations continue to work as-is. [Source: specs/003-medium-freedium-fallback]
 - **SC-016**: When the primary Medium request succeeds, there is no additional latency attributable to the fallback mechanism. [Source: specs/003-medium-freedium-fallback]
 - **SC-017**: All existing unit and integration tests for the Medium extractor continue to pass without modification after the fallback is introduced. [Source: specs/003-medium-freedium-fallback]
+- Homebrew is already installed on the user's machine; the feature does not cover installing Homebrew itself. [Source: specs/009-homebrew-tap-formula]
+- The formula targets the standard Homebrew installation on both macOS and Linux; Windows (WSL) is out of scope. [Source: specs/009-homebrew-tap-formula]
+- Only the source distribution (sdist) is used as the formula's source artifact; binary wheels are not referenced by the formula. [Source: specs/009-homebrew-tap-formula]
+- A `TAP_GITHUB_TOKEN` PAT will be created and added to repository secrets by the maintainer before first use — this is a one-time manual prerequisite. [Source: specs/009-homebrew-tap-formula]
+- If a PyPI release is yanked after the formula has been updated, the formula is not automatically rolled back. [Source: specs/009-homebrew-tap-formula]
 
 ---
 
-*Last Updated: 2026-05-16 | Sources appended: [specs/004-remove-backoff/spec.md], [specs/005-substack-provider/spec.md], [specs/006-thenewstack-provider/spec.md]*
+*Last Updated: 2026-05-16 | Sources appended: [specs/004-remove-backoff/spec.md], [specs/005-substack-provider/spec.md], [specs/006-thenewstack-provider/spec.md], [specs/009-homebrew-tap-formula/spec.md]*

{mdfetch-0.5.0 → mdfetch-0.5.2}/CLAUDE.md

@@ -55,10 +55,6 @@ make typecheck    # type check
 ```
 
 <!-- SPECKIT START -->
-## Active Feature Plan
-
-Active feature: `008-mdfetch-cli`. Implementation plan: [`specs/008-mdfetch-cli/plan.md`](specs/008-mdfetch-cli/plan.md).
-
 ## Known Issues & Gotchas
 
 ### ⚠️ test_router.py "unsupported domain" fixture must be updated per new provider
@@ -75,4 +71,9 @@ Active feature: `008-mdfetch-cli`. Implementation plan: [`specs/008-mdfetch-cli/
 **Issue:** VoxPop poll widgets (`div.tns-voxpop-screen`) appear to be inline article content but are actually page-level overlay modals.
 **Root Cause:** VoxPop is injected outside `div#tns-post-body-content` — confirmed via live DOM inspection across all 5 reference articles.
 **Prevention Rule:** Do not add VoxPop stripping to `TheNewStackExtractor.clean_html()`. If a future redesign moves VoxPop inside the body container, update `clean_html()` to decompose `div.tns-voxpop-screen`.
+
+### ⚠️ Homebrew formula requires `uses_from_macos` for lxml
+**Issue:** `brew audit --strict --new Formula/md-fetch.rb` fails with missing system library declarations when `lxml` is a resource block.
+**Root Cause:** `lxml` requires `libxml2` and `libxslt`, which are macOS system libraries. Homebrew requires these to be declared explicitly via `uses_from_macos`.
+**Prevention Rule:** Any Homebrew formula that includes `lxml` as a resource MUST declare `uses_from_macos "libxml2"` and `uses_from_macos "libxslt"` after the `depends_on` lines. Discovered via `brew audit --strict --new` during implementation.
 <!-- SPECKIT END -->

{mdfetch-0.5.0 → mdfetch-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdfetch
-Version: 0.5.0
+Version: 0.5.2
 Summary: Extract article content from web platforms and return it as clean Markdown.
 Project-URL: Homepage, https://github.com/stn1slv/md-fetch
 Project-URL: Source, https://github.com/stn1slv/md-fetch
@@ -37,10 +37,20 @@ A Python library that extracts article content from web platforms and returns it
 
 ## Install
 
+### pip
+
 ```bash
 pip install mdfetch
 ```
 
+### Homebrew (macOS / Linux)
+
+```bash
+brew install stn1slv/tap/md-fetch
+```
+
+No Python environment setup required.
+
 ## CLI Usage
 
 You can use the built-in `md-fetch` command directly from your terminal:

{mdfetch-0.5.0 → mdfetch-0.5.2}/README.md

@@ -4,10 +4,20 @@ A Python library that extracts article content from web platforms and returns it
 
 ## Install
 
+### pip
+
 ```bash
 pip install mdfetch
 ```
 
+### Homebrew (macOS / Linux)
+
+```bash
+brew install stn1slv/tap/md-fetch
+```
+
+No Python environment setup required.
+
 ## CLI Usage
 
 You can use the built-in `md-fetch` command directly from your terminal:

{mdfetch-0.5.0 → mdfetch-0.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mdfetch"
-version = "0.5.0"
+version = "0.5.2"
 description = "Extract article content from web platforms and return it as clean Markdown."
 readme = "README.md"
 license = { text = "MIT" }

mdfetch-0.5.2/specs/009-homebrew-tap-formula/checklists/requirements.md

@@ -0,0 +1,36 @@
+# Specification Quality Checklist: Homebrew Tap Formula
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-05-16
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- All items pass. Spec is ready for `/speckit-plan`.
+- The formula's `Language::Python::Virtualenv` pattern and SHA256 mechanics are deliberately kept out of the spec (they are implementation decisions captured in the plan).
+- The `TAP_GITHUB_TOKEN` prerequisite is documented as an assumption since it requires a one-time manual step outside the automated workflow.

mdfetch-0.5.2/specs/009-homebrew-tap-formula/contracts/formula.md

@@ -0,0 +1,119 @@
+# Contract: Homebrew Formula (`Formula/md-fetch.rb`)
+
+**Repository**: `stn1slv/homebrew-tap`  
+**Date**: 2026-05-16
+
+## Purpose
+
+Defines the complete structure of the `md-fetch` Homebrew formula so that the implementation can be written without ambiguity.
+
+## Formula Skeleton
+
+```ruby
+# typed: false
+# frozen_string_literal: true
+
+class MdFetch < Formula
+  include Language::Python::Virtualenv
+
+  desc "Extract article content from web platforms and return it as clean Markdown"
+  homepage "https://github.com/stn1slv/md-fetch"
+  url "https://files.pythonhosted.org/packages/<hash-path>/mdfetch-0.5.0.tar.gz"
+  sha256 "<mdfetch-0.5.0-sdist-sha256>"
+  license "MIT"
+
+  depends_on "python@3.12"
+
+  uses_from_macos "libxml2"
+  uses_from_macos "libxslt"
+
+  resource "anyio" do
+    url "https://files.pythonhosted.org/packages/19/14/2c5dd9f512b66549ae92767a9c7b330ae88e1932ca57876909410251fe13/anyio-4.13.0.tar.gz"
+    sha256 "334b70e641fd2221c1505b3890c69882fe4a2df910cba14d97019b90b24439dc"
+  end
+
+  resource "beautifulsoup4" do
+    url "https://files.pythonhosted.org/packages/c3/b0/1c6a16426d389813b48d95e26898aff79abbde42ad353958ad95cc8c9b21/beautifulsoup4-4.14.3.tar.gz"
+    sha256 "6292b1c5186d356bba669ef9f7f051757099565ad9ada5dd630bd9de5fa7fb86"
+  end
+
+  resource "certifi" do
+    url "https://files.pythonhosted.org/packages/25/ee/6caf7a40c36a1220410afe15a1cc64993a1f864871f698c0f93acb72842a/certifi-2026.4.22.tar.gz"
+    sha256 "8d455352a37b71bf76a79caa83a3d6c25afee4a385d632127b6afb3963f1c580"
+  end
+
+  resource "click" do
+    url "https://files.pythonhosted.org/packages/bb/63/f9e1ea081ce35720d8b92acde70daaedace594dc93b693c869e0d5910718/click-8.3.3.tar.gz"
+    sha256 "398329ad4837b2ff7cbe1dd166a4c0f8900c3ca3a218de04466f38f6497f18a2"
+  end
+
+  resource "h11" do
+    url "https://files.pythonhosted.org/packages/01/ee/02a2c011bdab74c6fb3c75474d40b3052059d95df7e73351460c8588d963/h11-0.16.0.tar.gz"
+    sha256 "4e35b956cf45792e4caa5885e69fba00bdbc6ffafbfa020300e549b208ee5ff1"
+  end
+
+  resource "httpcore" do
+    url "https://files.pythonhosted.org/packages/06/94/82699a10bca87a5556c9c59b5963f2d039dbd239f25bc2a63907a05a14cb/httpcore-1.0.9.tar.gz"
+    sha256 "6e34463af53fd2ab5d807f399a9b45ea31c3dfa2276f15a2c3f00afff6e176e8"
+  end
+
+  resource "httpx" do
+    url "https://files.pythonhosted.org/packages/b1/df/48c586a5fe32a0f01324ee087459e112ebb7224f646c0b5023f5e79e9956/httpx-0.28.1.tar.gz"
+    sha256 "75e98c5f16b0f35b567856f597f06ff2270a374470a5c2392242528e3e3e42fc"
+  end
+
+  resource "idna" do
+    url "https://files.pythonhosted.org/packages/82/77/7b3966d0b9d1d31a36ddf1746926a11dface89a83409bf1483f0237aa758/idna-3.15.tar.gz"
+    sha256 "ca962446ea538f7092a95e057da437618e886f4d349216d2b1e294abfdb65fdc"
+  end
+
+  resource "lxml" do
+    url "https://files.pythonhosted.org/packages/28/30/9abc9e34c657c33834eaf6cd02124c61bdf5944d802aa48e69be8da3585d/lxml-6.1.0.tar.gz"
+    sha256 "bfd57d8008c4965709a919c3e9a98f76c2c7cb319086b3d26858250620023b13"
+  end
+
+  resource "markdownify" do
+    url "https://files.pythonhosted.org/packages/3f/bc/c8c8eea5335341306b0fa7e1cb33c5e1c8d24ef70ddd684da65f41c49c92/markdownify-1.2.2.tar.gz"
+    sha256 "b274f1b5943180b031b699b199cbaeb1e2ac938b75851849a31fd0c3d6603d09"
+  end
+
+  resource "six" do
+    url "https://files.pythonhosted.org/packages/94/e7/b2c673351809dca68a0e064b6af791aa332cf192da575fd474ed7d6f16a2/six-1.17.0.tar.gz"
+    sha256 "ff70335d468e7eb6ec65b95b99d3a2836546063f63acc5171de367e834932a81"
+  end
+
+  resource "soupsieve" do
+    url "https://files.pythonhosted.org/packages/7b/ae/2d9c981590ed9999a0d91755b47fc74f74de286b0f5cee14c9269041e6c4/soupsieve-2.8.3.tar.gz"
+    sha256 "3267f1eeea4251fb42728b6dfb746edc9acaffc4a45b27e19450b676586e8349"
+  end
+
+  resource "typing-extensions" do
+    url "https://files.pythonhosted.org/packages/72/94/1a15dd82efb362ac84269196e94cf00f187f7ed21c242792a923cdb1c61f/typing_extensions-4.15.0.tar.gz"
+    sha256 "0cea48d173cc12fa28ecabc3b837ea3cf6f38c6d1136f85cbaaf598984861466"
+  end
+
+  def install
+    virtualenv_install_with_resources
+  end
+
+  test do
+    assert_match version.to_s, shell_output("#{bin}/md-fetch --version")
+  end
+end
+```
+
+## Invariants
+
+- `url` and `sha256` (package) are the **only** fields updated on each mdfetch release.
+- All `resource` blocks are updated only when runtime dependencies change (separate manual PR to homebrew-tap).
+- The `test` block uses `assert_match version.to_s` so it automatically validates the installed binary reports the expected version.
+
+## Pre-Implementation Note
+
+The `url` path component for `mdfetch-0.5.0.tar.gz` (the `<hash-path>` placeholder above) must be retrieved from PyPI before writing the initial formula. Run:
+
+```bash
+curl -s https://pypi.org/pypi/mdfetch/0.5.0/json | \
+  python3 -c "import sys,json; d=json.load(sys.stdin); \
+  [print(u['url'], u['digests']['sha256']) for u in d['urls'] if u['packagetype']=='sdist']"
+```

mdfetch-0.5.2/specs/009-homebrew-tap-formula/contracts/tap-update-job.md

@@ -0,0 +1,86 @@
+# Contract: Tap-Update CI Job (`update-homebrew-tap`)
+
+**Workflow file**: `.github/workflows/publish.yml` in `stn1slv/md-fetch`  
+**Date**: 2026-05-16
+
+## Job Summary
+
+A new `update-homebrew-tap` job is added to `publish.yml`, running after the existing `publish` job succeeds. It fetches the new release's sdist SHA-256 from PyPI, clones the homebrew-tap repo, patches the formula, and pushes the commit.
+
+## Job Definition Skeleton
+
+```yaml
+update-homebrew-tap:
+  name: Update Homebrew tap
+  runs-on: ubuntu-latest
+  needs: publish
+  concurrency:
+    group: homebrew-tap-update
+    cancel-in-progress: false
+  permissions:
+    contents: read
+
+  steps:
+    - name: Fetch sdist info from PyPI (with retry)
+      env:
+        VERSION: ${{ github.ref_name }}  # e.g. v0.5.1
+      run: |
+        VERSION="${VERSION#v}"           # strip leading 'v'
+        SHA256=""
+        for i in 1 2 3; do
+          RESPONSE=$(curl -sf "https://pypi.org/pypi/mdfetch/${VERSION}/json" || true)
+          if [ -n "$RESPONSE" ]; then
+            SDIST_URL=$(echo "$RESPONSE" | python3 -c \
+              "import sys,json; d=json.load(sys.stdin); \
+               urls=[u for u in d['urls'] if u['packagetype']=='sdist']; \
+               print(urls[0]['url'] if urls else '')" 2>/dev/null || true)
+            SHA256=$(echo "$RESPONSE" | python3 -c \
+              "import sys,json; d=json.load(sys.stdin); \
+               urls=[u for u in d['urls'] if u['packagetype']=='sdist']; \
+               print(urls[0]['digests']['sha256'] if urls else '')" 2>/dev/null || true)
+            if [ -n "$SHA256" ] && [ -n "$SDIST_URL" ]; then break; fi
+          fi
+          echo "PyPI not ready, retrying in 30s (attempt $i/3)..."
+          sleep 30
+        done
+        if [ -z "$SHA256" ]; then
+          echo "ERROR: Could not fetch sdist info from PyPI after 3 retries" >&2; exit 1
+        fi
+        echo "SDIST_URL=${SDIST_URL}" >> "$GITHUB_ENV"
+        echo "SHA256=${SHA256}"       >> "$GITHUB_ENV"
+        echo "VERSION=${VERSION}"     >> "$GITHUB_ENV"
+
+    - name: Clone homebrew-tap and update formula
+      env:
+        TAP_GITHUB_TOKEN: ${{ secrets.TAP_GITHUB_TOKEN }}
+      run: |
+        git clone "https://x-access-token:${TAP_GITHUB_TOKEN}@github.com/stn1slv/homebrew-tap.git"
+        cd homebrew-tap
+        git config user.name  "github-actions[bot]"
+        git config user.email "github-actions[bot]@users.noreply.github.com"
+
+        # Replace the main package url and sha256 lines
+        sed -i "s|  url \"https://files.pythonhosted.org/packages/.*/mdfetch-.*\.tar\.gz\"|  url \"${SDIST_URL}\"|" \
+          Formula/md-fetch.rb
+        sed -i "0,/  sha256 \"[a-f0-9]*\"/{s|  sha256 \"[a-f0-9]*\"|  sha256 \"${SHA256}\"|}" Formula/md-fetch.rb
+
+        git add Formula/md-fetch.rb
+        git commit -m "chore: bump md-fetch to v${VERSION}"
+        git pull --rebase
+        git push
+```
+
+## Failure Modes and Expected Behavior
+
+| Failure | Job Behaviour |
+|---------|--------------|
+| PyPI returns 404 for new version after 3×30s retries | Step exits non-zero → job fails → workflow shows red |
+| `TAP_GITHUB_TOKEN` absent or invalid | `git clone` or `git push` exits non-zero → job fails |
+| `sed` finds no matching line (formula structure changed) | `git diff --quiet` would show no changes; `git commit` would fail — job exits non-zero |
+| Concurrent release overlap | `concurrency: group=homebrew-tap-update` serializes runs; second run queues and proceeds after first completes (`cancel-in-progress: false`) |
+
+## Prerequisites
+
+- `TAP_GITHUB_TOKEN` secret must be set in `stn1slv/md-fetch` repository settings.
+- Token must be a **fine-grained PAT** with `Contents: read+write` on `stn1slv/homebrew-tap` only. Do not use a classic `repo`-scoped PAT.
+- `jq` is **not** required — Python 3 (always available on `ubuntu-latest`) is used for JSON parsing.