scrapefold 0.1.0a2__tar.gz

scrapefold-0.1.0a2/.github/workflows/ci.yml

@@ -0,0 +1,131 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      run_paid:
+        description: 'Also run tests marked "paid" (uses real vendor API keys)'
+        type: boolean
+        default: false
+      run_network:
+        description: 'Also run tests marked "network" (hits live internet)'
+        type: boolean
+        default: false
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[test]"
+
+      - name: Changelog gate (skips on main pushes)
+        if: github.event_name == 'pull_request'
+        run: bash scripts/check-changelog.sh "origin/${{ github.base_ref }}"
+
+      - name: Ruff lint
+        run: ruff check src tests
+
+      - name: Ruff format
+        run: ruff format --check src tests
+
+      - name: Mypy
+        run: mypy src
+
+      - name: Pytest — offline default
+        run: pytest -m "not paid and not network" --maxfail=3
+
+      - name: Pytest — network (manual dispatch only)
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.run_network == true }}
+        run: pytest -m network --maxfail=3
+
+      - name: Pytest — paid (manual dispatch only)
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.run_paid == true }}
+        env:
+          FIRECRAWL_API_KEY:    ${{ secrets.FIRECRAWL_API_KEY }}
+          SCRAPINGBEE_API_KEY:  ${{ secrets.SCRAPINGBEE_API_KEY }}
+          SCRAPINGDOG_API_KEY:  ${{ secrets.SCRAPINGDOG_API_KEY }}
+          JINA_API_KEY:         ${{ secrets.JINA_API_KEY }}
+          OUTSCRAPER_API_KEY:   ${{ secrets.OUTSCRAPER_API_KEY }}
+          APIFY_API_TOKEN:      ${{ secrets.APIFY_API_TOKEN }}
+          BRIGHTDATA_API_KEY:   ${{ secrets.BRIGHTDATA_API_KEY }}
+          ANYSITE_API_KEY:      ${{ secrets.ANYSITE_API_KEY }}
+        run: pytest -m paid --maxfail=3
+
+  release-rehearsal:
+    name: Release rehearsal (build + twine check + install)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install build + twine
+        run: pip install build twine
+
+      - name: Build sdist + wheel
+        run: python -m build
+
+      - name: twine check
+        run: python -m twine check dist/*
+
+      - name: Install built wheel in a clean env
+        run: pip install dist/*.whl
+
+      - name: Smoke-import installed package
+        run: python -c "import scrapefold; print(scrapefold.__version__)"
+
+  publish:
+    name: Publish to PyPI
+    needs: [test, release-rehearsal]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      id-token: write  # trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

scrapefold-0.1.0a2/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+.installed.cfg
+MANIFEST
+
+# Environments
+.venv/
+venv/
+env/
+.env
+.env.local
+.env.*.local
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tox/
+.hypothesis/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Project-specific
+.scrapefold/
+~/.scrapefold/
+*.cache
+Data/
+
+# Secrets
+*.pem
+*.key
+secrets.json

scrapefold-0.1.0a2/.python-version

@@ -0,0 +1 @@
+3.11

scrapefold-0.1.0a2/AGENTS.md

@@ -0,0 +1,34 @@
+# AGENTS.md
+
+Entry point for non-Claude AI agents (Codex, Cursor, custom orchestrators) working on this repo.
+
+This file mirrors [CLAUDE.md](CLAUDE.md) — pointers, not content. Read the docs/ graph for everything.
+
+## What this project is
+
+`scrapefold` — unified Python library for web scraping with one async API across 16 engines and a built-in anti-bot escalation ladder.
+
+## Start here
+
+1. [docs/README.md](docs/README.md) — index of all docs
+2. [docs/conventions/golden-rules.md](docs/conventions/golden-rules.md) — the constraints
+3. [CONTRIBUTING.md](CONTRIBUTING.md) — how to add an engine
+
+## Run / test / lint
+
+```bash
+pip install -e ".[test]"
+./scripts/check.sh                              # lint + type-check + offline tests
+pytest -m "not paid and not network"            # default suite
+```
+
+## Conventions
+
+- All code under `src/scrapefold/`. Tests under `tests/`. Docs under `docs/`. Scripts under `scripts/`.
+- Async-everywhere. `httpx` for HTTP, `asyncio` for concurrency. No `requests` package.
+- No vendor LLM SDK imports anywhere in `src/`. LLM is an injected callable.
+- Engines are lazy-imported via `src/scrapefold/engines/__init__.py` registry.
+
+## Output
+
+Default CLI output is human-readable. Pass `--json` everywhere for machine-parseable output. Errors are fatal (non-zero exit + clear stderr message).

scrapefold-0.1.0a2/CHANGELOG.md

@@ -0,0 +1,147 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning follows [SemVer](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0a2] - 2026-05-24
+
+Pack 3 — sequential router shell + Cloudflare Browser Rendering engine + comprehensive cost/policy/timeout enforcement. The public `scrape()` path is live for sequential ladders and explicit `opts.engines` overrides; the router now walks `RaceStep` members sequentially (parallel fan-out remains deferred to v0.2). `AllEnginesFailed` is now a structured exception with `.url` and `.failures` attributes. Release mechanics scaffolded: dynamic version from `__init__.py`, dep-freshness audit script, CHANGELOG gate.
+
+### Changed — dependency floors refreshed
+
+- Bumped lower-bound pins to current PyPI stable (pack-opening
+  freshness policy from spec §4.4). Affected pins:
+  - `tldextract` 5.0 → 5.3
+  - `beautifulsoup4` 4.12 → 4.14
+  - `typer` 0.12 → 0.25
+  - `firecrawl-py` 4.0 → 4.27
+  - `selenium` 4.25 → 4.44
+  - `apify-client` 2.2 → 3.0
+  - `mcp` 1.0 → 1.27
+  - `pytest` 7.0 → 9.0
+  - `pytest-asyncio` 0.21 → 1.3
+  - `pytest-httpx` 0.30 → 0.36
+  - `ruff` 0.4 → 0.15
+  - `mypy` 1.8 → 2.1
+
+### Changed — structured AllEnginesFailed (consumer error contract)
+
+- `AllEnginesFailed` now carries `.url: str` and `.failures: list[str]`.
+  Consumers no longer need to parse the exception message. The
+  `failures` list shape is `"<engine>:<reason>:<detail>"` (e.g.
+  `"firecrawl:error:404 Not Found"`, `"jina:empty"`,
+  `"scrapingbee:unavailable"`, `"budget:cost"`). Pack 7 consumer
+  migrations (phynder + ai-utils) target this contract directly.
+
+### Fixed — golden-rule violation: router now consults detection.is_suspicious
+
+- The sequential router shell originally only checked `result.is_empty()`
+  for advancement — a captcha page with non-empty text would have been
+  returned as success. Per `docs/conventions/golden-rules.md` ("Suspicious-
+  content detection lives in one place"), the router now calls
+  `scrapefold.detection.is_suspicious(result)` after the empty check and
+  advances on True with a `"<engine>:suspicious"` failure entry.
+- Internal: `_resolve_policy` site_class arg typed as `SiteClass` instead
+  of `str`; load-bearing `type: ignore[arg-type]` removed.
+
+### Fixed — detection: is_suspicious short-text check is now conjoint
+
+- `detection.is_suspicious` previously flagged any result with fewer than
+  50 chars regardless of HTTP status. Now short-text is only suspicious
+  when the status code is also non-2xx or when the result is empty,
+  eliminating false positives for legitimately short pages (e.g. API
+  endpoints returning `{"ok":true}`).
+
+### Added — Pack 3 cloudflare engine
+
+- `src/scrapefold/engines/cloudflare.py` — port of ai-utils
+  `get_content_cloudflare` to scrapefold's `ScrapeEngine` ABC. Calls
+  Cloudflare Browser Rendering `/markdown` first (native markdown), falls
+  back to `/content` (raw HTML → html_to_text). Env: `CLOUDFLARE_API_TOKEN`
+  + `CLOUDFLARE_ACCOUNT_ID`.
+- `tests/test_engine_cloudflare.py` — 13 tests covering both endpoints,
+  fallback paths, auth headers, body shape, is_available gating,
+  registry registration.
+- `docs/workflows/development.md` — env-var table fixed
+  (`CLOUDFLARE_API_KEY` → `CLOUDFLARE_API_TOKEN`, matching Cloudflare's
+  Bearer-token convention).
+
+### Added — Pack 3 router shell (sequential)
+
+- `src/scrapefold/router.py` — `async walk(url, opts) -> ScrapeResult` walks the per-site-class ladder. Honors `Policy` (paid_allowed / legal_constraints_blocked / geography_required), `WalkBudget` ceilings (`max_engines`, `max_cost_usd`, `timeout_s`), and the `engines_tried` dedup set. `RaceStep` entries are walked sequentially with a DEBUG log until Pack 9.
+- `tests/test_router.py` — 13 tests covering happy path, empty-result advance, EngineError advance, unavailable-engine skip, AllEnginesFailed, unknown-engine skip, policy gating, budget halt, RaceStep skip, public `scrape()` delegation, failures-list, no-retry-within-walk, EngineError-non-propagation.
+- `scrapefold.scrape(url, opts)` now delegates to `router.walk` instead of raising `NotImplementedError`.
+- `tests/test_smoke.py` — the obsolete `NotImplementedError` smoke test is removed.
+- Budget enforcement: 12 rounds of Codex review hardening. Key fixes: cost-budget skips engine (not halts walk), unavailable engines don't consume `max_engines` slot, timeout boundary uses `>=`, actual cost credits over estimate, `opts.engines` override respects all budget/policy gates, geography `()` means global.
+
+### Added — release mechanics scaffolding
+
+- `scripts/check-deps-fresh.sh` — pack-opening dep-floor nag: parses `pyproject.toml` lower bounds and warns when a dependency is more than 90 days behind PyPI stable.
+- `scripts/check-changelog.sh` — PR-time gate: fails if `## [Unreleased]` is empty (no changes documented), scoped to the `[Unreleased]` section only.
+- `scripts/check.sh` — version-equality gate added: reads dynamic version from `pyproject.toml` (via `tomli`) and asserts it matches `__init__.__version__`; prevents version drift between the two sources.
+- `pyproject.toml` — `tomli` added as Python 3.10 compat dep for the version check; broken `obscura` and `brightdata` optional extras removed.
+
+## [0.1.0a1] — 2026-05-22
+
+### Added — S1.5 per-site-class escalation ladders
+
+- `src/scrapefold/ladders.py` — full v3 design after three Codex review rounds.
+  - `SiteClass` literal with 27 classes (LinkedIn ×5, Amazon ×2, social ×4, SERP ×3, easy content ×4, paywall_news, yandex_protected, anti-bot vendor ×4, js_spa, static_general).
+  - Sum type for steps: `SequentialStep` + `RaceStep` (no more weak tuple of tuples).
+    - `RaceStep` carries explicit `winner_policy`, `cancel_policy`, `cancel_grace_ms`, `budget_accounting` — race semantics are data, not router convention.
+  - `LADDERS: dict[SiteClass, Ladder]` — per-class ordered tuple of steps.
+  - `WalkBudget` — mutable walk state (elapsed_ms, cost_usd, engines_tried, **visited_site_classes** to block A→B→A reclassification loops, reclassifications, `MAX_RECLASSIFICATIONS=3`).
+  - `BudgetExceeded` + `AllEnginesFailed` — typed exceptions surfaced to the router.
+  - `Policy` + `DEFAULT_POLICY` — `paid_allowed`, `legal_constraints_blocked`, `geography_required`. Government class defaults to `paid_allowed=False`.
+  - `is_step_allowed(step, policy)` and `check_budget(step, walk, ...)` — pure functions consumed by the router. `check_budget` accounts for **race fan-out** in the engine-count ceiling (Codex round-3 fix).
+  - `_estimate_step_cost(step, avg_response_mb)` — converts `(estimated_cost_usd, billing_unit)` into per-call USD; `gb` billing scales with response size.
+  - `URL_PATTERNS` + `classify_url` — ordered specific-first regex table, fallback `static_general`.
+  - `GOLDEN_CORPUS` — 22 `(url, class)` rows pinning regex-order safety. The parametrized test `test_url_classification_golden_corpus` makes any reorder regression visible per-row.
+  - `SIGNATURES` — response-content matchers (Cloudflare / Datadome / PerimeterX / Akamai cookies, body phrases, headers) for mid-walk reclassification by `detection.py` (S2). `min_matches=2` prevents single-phrase false positives.
+- `src/scrapefold/engines/base.py` — extended `EngineCapabilities` with `estimated_cost_usd`, `billing_unit`, `avg_response_mb_estimate`, `geography`, `proxy_type`, `legal_constraints`, `default_timeout_s`. Added `PROBE_SCOPE: Literal["none", "per_url", "per_domain", "per_session"]` and default `async def probe(url) -> bool` returning `True`. Reddit's requests-engine override (`PROBE_SCOPE="per_domain"`) means a 50-URL crawl on reddit.com costs one probe, not 50.
+- `src/scrapefold/engines/__init__.py` — `ENGINE_ALIASES`, `register_alias`, `resolve_alias`. Multi-mode engines (Bright Data Unlocker async/sync, Scrapling stealth/fast) register as distinct names; user-facing aliases route a bare `scrapling` to `scrapling_stealth`.
+- `src/scrapefold/__init__.py` — re-exports `Policy`, `SequentialStep`, `RaceStep`, `WalkBudget`, `SiteClass`, `BudgetExceeded`, `AllEnginesFailed`, `classify_url`, `get_ladder`. Version bumped to `0.1.0a1`.
+- `tests/test_ladders.py` — 59 tests covering structural well-formedness, 22-row golden corpus + completeness, `is_step_allowed` policy enforcement (paid/legal/geography), `check_budget` ceilings + race fan-out, sum-type defaults, multi-mode engine separation, `WalkBudget` visited-class loop guard, `_estimate_step_cost` billing-unit math.
+
+### Changed
+
+- Architecture overview (`docs/architecture/overview.md`) — replaced universal T0-T5 ladder narrative with per-class ladder description, race-step semantics, walk-time contracts.
+- Golden rules (`docs/conventions/golden-rules.md`) — rewrote the escalation rule, added three new rules: "Ladders are data", "Multi-mode engines register as distinct names", "New URL pattern → new GOLDEN_CORPUS row".
+
+### Deferred
+
+Seven Codex round-3 implementation items tracked in `docs/TECH_DEBT.md`:
+
+1. `budget_mode` wiring in the router (S7).
+2. Race fan-out cost crediting when `budget_accounting="sum_all"`.
+3. Per-engine `avg_response_mb` override wiring through `_estimate_step_cost`.
+4. Race billing default re-examination once benchmarks land.
+5. `avg_response_mb_estimate` default tuning per engine.
+6. Engine-registration code must populate `ENGINE_ALIASES` (S2-S11).
+7. Probe-cache implementation in the router (S7).
+
+## [0.1.0a0] — 2026-05-22
+
+### Added — S1 scaffold
+
+- Package layout: `src/scrapefold/` with `options.py`, `result.py`, `engines/base.py`, lazy engine registry.
+- `ScrapeOptions` dataclass — single unified parameter schema (language, country, render_js, wait_ms, stealth, premium_proxy, user_agent, custom_headers, cookies, output_format, take_screenshot, max_pages, max_depth, engines, parallel, timeout_s, skip_cache, extra).
+- `ScrapeResult` dataclass — four format slots (`text`, `markdown`, `html`, `json`) + `screenshot_b64`, `meta`, `failures`, `elapsed_ms`, `cost_usd`.
+- `ScrapeEngine` ABC with `EngineCapabilities` + `EngineError`. Base class handles option-stripping (DEBUG log, never raises), timing, error wrapping.
+- Public `scrape()` and `crawl_site()` stubs in `__init__.py` (raise `NotImplementedError` until S7/S8).
+- CLI scaffold (`scrapefold` console script via Typer).
+- MCP server scaffold (`scrapefold-mcp` console script).
+- Docs graph per HARNESS_BOOTSTRAP: `docs/README.md`, `docs/architecture/overview.md`, `docs/workflows/{development,testing}.md`, `docs/conventions/golden-rules.md`, `docs/tools/{agent-mode,scripts}.md`.
+- Anti-bot escalation ladder documented (T0→T4 + stop rules + suspicious-content detection heuristics planned in `detection.py`).
+- Golden rules: unified options, options-dropping-never-raises, ScrapeResult invariant (all four slots), escalate-and-stop, suspicious-detection-in-one-place, no vendor LLM SDK, lazy engine imports, async everywhere.
+- Helper scripts: `scripts/check.sh`, `scripts/describe.sh`, `scripts/quick-test.sh`.
+- GitHub Actions CI: lint + type-check + offline tests on Python 3.10/3.11/3.12; PyPI publish via trusted publishing on `v*` tag; opt-in `paid` and `network` test jobs via `workflow_dispatch`.
+- Smoke tests + `ScrapeEngine` ABC contract tests.
+
+[Unreleased]: https://github.com/mihailorama/scrapefold/compare/v0.1.0a2...HEAD
+[0.1.0a2]: https://github.com/mihailorama/scrapefold/compare/v0.1.0a1...v0.1.0a2
+[0.1.0a1]: https://github.com/mihailorama/scrapefold/compare/v0.1.0a0...v0.1.0a1
+[0.1.0a0]: https://github.com/mihailorama/scrapefold/releases/tag/v0.1.0a0

scrapefold-0.1.0a2/CLAUDE.md

@@ -0,0 +1,48 @@
+# scrapefold
+
+Unified Python library for web scraping — single URL or whole-site → markdown, with stealth, JS rendering, and LLM-ready output.
+
+## Quick Start
+
+```bash
+# Run tests (offline)
+pytest -m "not paid and not network"
+
+# Pre-commit gate
+./scripts/check.sh
+
+# Project state snapshot
+./scripts/describe.sh
+```
+
+## Key Files
+
+| File / Dir | Purpose |
+|---|---|
+| [docs/](docs/) | Full documentation graph — start with [docs/README.md](docs/README.md) |
+| [docs/conventions/golden-rules.md](docs/conventions/golden-rules.md) | Rules you MUST follow |
+| [docs/architecture/overview.md](docs/architecture/overview.md) | Module map, data flow, escalation ladder, result format slots |
+| [docs/workflows/development.md](docs/workflows/development.md) | Dev env setup |
+| [docs/workflows/testing.md](docs/workflows/testing.md) | Test markers, layered plan |
+| [docs/tools/agent-mode.md](docs/tools/agent-mode.md) | CLI / MCP for AI agents |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | How to add a new engine (5-step checklist) |
+| `src/scrapefold/options.py` | `ScrapeOptions` — unified parameter schema |
+| `src/scrapefold/result.py` | `ScrapeResult` — text/markdown/html/json slots |
+| `src/scrapefold/engines/base.py` | `ScrapeEngine` ABC + `EngineCapabilities` |
+| `scripts/check.sh` | Lint + type-check + offline tests |
+
+## Golden Rules (top 5)
+
+1. **One unified options schema** — every engine takes the same `ScrapeOptions`.
+2. **Engines drop unsupported options, never raise** — `SUPPORTED_OPTIONS` set + DEBUG log.
+3. **All four format slots are populated when achievable** — `text`+`markdown` always, `html`/`json` when native.
+4. **Escalate cheap-to-expensive, stop at first good response** — T0→T1→T2→T3→T4 ladder with stop rules.
+5. **No vendor LLM SDK in the library** — LLM passed as a user-provided async callable.
+
+_Full rules: [docs/conventions/golden-rules.md](docs/conventions/golden-rules.md)_
+
+## Architecture (one-liner)
+
+`scrape(url, opts) → ScrapeRouter walks an escalation ladder of engines, each implementing `ScrapeEngine._fetch(url, opts) → ScrapeResult`, until a non-suspicious response is returned.
+
+_Full details: [docs/architecture/overview.md](docs/architecture/overview.md)_

scrapefold-0.1.0a2/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to scrapefold
+
+## Add a new engine — 5-step checklist
+
+1. **Create the module** at `src/scrapefold/engines/<name>.py`:
+
+   ```python
+   from __future__ import annotations
+
+   from scrapefold.engines.base import EngineCapabilities, ScrapeEngine
+   from scrapefold.options import ScrapeOptions
+   from scrapefold.result import ScrapeResult
+
+
+   class FooEngine(ScrapeEngine):
+       NAME = "foo"
+       CAPABILITIES = EngineCapabilities(
+           js_rendering=True,
+           stealth=True,
+           cost_per_1k=1.0,
+           requires_api_key=True,
+       )
+       SUPPORTED_OPTIONS = frozenset({
+           "language", "country", "render_js", "wait_ms",
+           "stealth", "user_agent", "custom_headers", "timeout_s",
+       })
+
+       async def _fetch(self, url: str, opts: ScrapeOptions) -> ScrapeResult:
+           # 1. Translate opts -> native vendor params via local _adapt(opts)
+           # 2. Call vendor (httpx.AsyncClient or vendor SDK, lazy-imported)
+           # 3. Convert HTML→markdown if needed via scrapefold.html_to_text
+           # 4. Return ScrapeResult with text+markdown+html (+json if structured)
+           ...
+   ```
+
+2. **Document the native parameter surface** in the module docstring as a table — every vendor parameter you support, what unified option it maps from, defaults. This is the input to the global adapter matrix.
+
+3. **Register it lazily** in `src/scrapefold/engines/__init__.py`:
+
+   ```python
+   def _load_foo():
+       from scrapefold.engines.foo import FooEngine
+       return FooEngine
+
+   register("foo", _load_foo)
+   ```
+
+4. **Add tests** under `tests/test_engines/test_foo.py` covering:
+   - Success path (vendor mocked via `pytest-httpx`)
+   - Vendor error (4xx/5xx → `EngineError`)
+   - Timeout (engine respects `opts.timeout_s`)
+   - Missing API key (`is_available() is False`)
+   - One unified-opt → native-param adapter assertion
+
+5. **Add an extra** in `pyproject.toml` if the engine needs a non-stdlib dependency:
+
+   ```toml
+   [project.optional-dependencies]
+   foo = ["foo-sdk>=1.0"]
+   ```
+
+   And update `all = [...]`.
+
+## Style
+
+- `ruff check` and `ruff format` must be clean.
+- `mypy src` must be clean.
+- Async everywhere — `async def`, `await`, `httpx.AsyncClient`.
+- No top-level imports of optional vendor SDKs. Import inside the class or function.
+- No `print()` — use `logging.getLogger(__name__)`.
+
+## Commits
+
+Conventional-ish prefixes: `feat:`, `fix:`, `chore:`, `docs:`, `test:`, `refactor:`, `release:`.
+
+## Release
+
+See `.claude/commands/release-scrapefold.md` (lands in S12). TL;DR: bump version in `pyproject.toml`, update `CHANGELOG.md`, tag `vX.Y.Z`, push — GitHub Actions publishes via PyPI trusted publishing.

scrapefold-0.1.0a2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mihailorama
+
+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.