From 52fb52ea3b213bfce99dcd3660a912d4f8a89c4e Mon Sep 17 00:00:00 2001 From: Eric Wagoner Date: Thu, 6 Aug 2026 00:54:10 -0400 Subject: [PATCH] Quick start finishes the move off git clone; Windows stops being banned MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Eric caught two leftovers. The Quick start still opened with git clone — the exact path the last commit built two warning layers against — and now leads with uv tool install into a directory of your own, with the stage commands dropping their uv run prefix to match (the clone recipe moves to Development, its one remaining legitimate home, with a pointer to run real pipelines elsewhere). And the requirements line claimed macOS or Linux. Nothing in the code is platform-specific — pure Python, pathlib throughout, and uv, FastAPI, and Playwright all support Windows — so the honest statement is: Windows works but is untested, with one real caveat named in place: the owner-only chmod on .env and browser session state is POSIX-only, so Windows users keep those files in an account-protected directory. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_016jXZFSTZQKzAC8fqpWSz9g --- README.md | 53 ++++++++++++++++++++++++++--------------------------- 1 file changed, 26 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 564ef78..d5d1627 100644 --- a/README.md +++ b/README.md @@ -73,20 +73,21 @@ Every stage is idempotent and resumable: kill it mid-run, restart, lose nothing. ## Requirements -- macOS or Linux, Python 3.12+, [uv](https://docs.astral.sh/uv/) +- Python 3.12+ and [uv](https://docs.astral.sh/uv/), on macOS, Linux, or Windows. (Development happens on macOS; Windows is untested but nothing is platform-specific. One caveat: the owner-only file permissions bggpipe sets on `.env` and browser session state are POSIX-only — on Windows, keep those files in a directory protected by your account.) - A vision model for extraction — an [Anthropic API key](https://console.anthropic.com/) by default, or any OpenAI-compatible endpoint: OpenAI, OpenRouter, or a free local runtime like [Ollama](https://ollama.com/) with a vision-capable model. `config.toml` carries a `[vision.]` block for each; `vision_provider` picks one. Local models read spines noticeably worse than frontier ones — expect a longer proofread pass on the Titles page, not a broken pipeline. - A BoardGameGeek account **and a registered BGG application** — as of BGG's [2025 API policy](https://boardgamegeek.com/using_the_xml_api), the XML API requires a Bearer token from a registered app. Register a free non-commercial application at [boardgamegeek.com/applications](https://boardgamegeek.com/applications) (approval can take a week or more, so **apply on day one**), then create a token. Each user needs their own; tokens must not be shared. ## Quick start ```sh -git clone https://git.kestrelsnest.social/eric/bggpipe.git -cd bggpipe -uv sync # installs Python deps -uv run bggpipe init # guided setup: folders, credentials, browser download +uv tool install git+https://git.kestrelsnest.social/eric/bggpipe +mkdir shelves && cd shelves # any directory of your own — NOT a clone of this repo +bggpipe init # guided setup: folders, credentials, browser download ``` -The `init` wizard is idempotent — re-run it anytime to check status or add keys you skipped. It prompts for the credentials below (hidden input, saved to a `.env` it creates with owner-only permissions) and offers the one-time Playwright Chromium download. Prefer doing it by hand? `cp .env.example .env`, fill it in, and run `uv run playwright install chromium` yourself. +Your photos and every pipeline artifact live in the directory where you run it, and `uv tool upgrade bggpipe` picks up fixes without going anywhere near your data ([why this matters](#bring-your-own-shelves)). + +The `init` wizard is idempotent — re-run it anytime to check status or add keys you skipped. It prompts for the credentials below (hidden input, saved to a `.env` it creates with owner-only permissions) and offers the one-time Playwright Chromium download. Prefer doing it by hand? Copy [.env.example](.env.example) beside your data, fill it in, and run `playwright install chromium` yourself. Secrets live in environment variables only, never in config files, code, or logs. `.env` is gitignored. If you use [direnv](https://direnv.net/), the committed `.envrc` loads `.env` automatically after a one-time `direnv allow`; otherwise export the variables yourself (e.g. `set -a; source .env; set +a`). @@ -100,15 +101,17 @@ Secrets live in environment variables only, never in config files, code, or logs Non-secret knobs (`photos_dir`, `data_dir`, the per-provider vision blocks, the rate limit) live in `config.toml`. From here you can drive everything from the browser: ```sh -uv run bggpipe web # opens http://127.0.0.1:8377/ — the whole app in the browser +bggpipe web # opens http://127.0.0.1:8377/ — the whole app in the browser ``` +(Working from a development clone instead? Prefix commands with `uv run`.) + ### From your phone The app is localhost-only by default. To use it from a phone or tablet on your network — proofreading from the couch, or shooting shelf photos straight into the pipeline — serve it to the LAN instead: ```sh -uv run bggpipe web --lan # localhost + your network, behind an access key +bggpipe web --lan # localhost + your network, behind an access key ``` Startup prints a pairing link (`?k=...`) and a QR code: point the phone's camera at the terminal and tap. Pairing is one-time per device — the key persists across restarts (`data/.lan_key`; delete it to revoke every paired device) and the cookie lasts a year. Save the page to the phone's home screen for the full-screen treatment, piper icon included. @@ -118,13 +121,13 @@ To photograph shelves from the phone: on the Photos page, tap the drop zone and Seven pages in one local app — Pipeline, Photos, Titles, Review, Queue, Library, and Help, each pictured above. The real upload sits behind a confirmation (and behind a stub-data lock if synthetic fixtures ever regenerate). Prefer the terminal? Every stage is also a command, and the two interfaces share all state: ```sh -uv run bggpipe extract # photos → titles.json (+ retake prompts) -uv run bggpipe resolve # titles → BGG ids/versions in matches.csv -uv run bggpipe review --web # review UI only -uv run bggpipe diff # compare against your BGG collection -uv run bggpipe upload --dry-run # ALWAYS inspect this first -uv run bggpipe upload --limit 1 # then one game, then small batches -uv run bggpipe enrich # full metadata → data/games.json +bggpipe extract # photos → titles.json (+ retake prompts) +bggpipe resolve # titles → BGG ids/versions in matches.csv +bggpipe review --web # review UI only +bggpipe diff # compare against your BGG collection +bggpipe upload --dry-run # ALWAYS inspect this first +bggpipe upload --limit 1 # then one game, then small batches +bggpipe enrich # full metadata → data/games.json ``` Each stage skips work it has already done; `--force`/`--refresh` flags redo it. `review` without `--web` runs in the terminal instead. `upload` also has `--retry-failed`, `--verify` (re-fetches your collection and cross-checks the log), and runs a **headed** browser by default — BGG's Cloudflare check blocks headless ones, and a first login may need one human click before the session is saved locally and reused. @@ -143,16 +146,7 @@ Straight-on, one shelf (or part of one) per shot, close enough that spine text i ## Bring your own shelves -Install bggpipe as a tool and run it in its own directory — **not inside a clone of this repo**: - -```sh -uv tool install git+https://git.kestrelsnest.social/eric/bggpipe -mkdir ~/shelves && cd ~/shelves -bggpipe init # folders, credentials, one-time browser install -bggpipe web # or run stages from the terminal -``` - -Everything the pipeline produces — photos, matches, review decisions, your upload log — lives in the directory where you run it. A bug fix is `uv tool upgrade bggpipe`, which by construction cannot touch your data. +The [Quick start](#quick-start) install — as a tool, run in a directory of your own — is the only supported way to use bggpipe on your collection. Everything the pipeline produces (photos, matches, review decisions, your upload log) lives where you run it, and a bug fix is `uv tool upgrade bggpipe`, which by construction cannot touch your data. **Why not clone and run?** This repo doubles as its author's live pipeline: `data/` ships with their real artifacts, committed and updated often. Run inside a clone and *your* data lands at git-tracked paths — the next `git pull` will refuse to merge, and the usual remedies (`git reset --hard`, `git checkout .`, `git stash`, `git clean -fdx`) would destroy your review decisions, hand-written games, upload log, and photos. bggpipe detects this arrangement and warns at `init` and on the web dashboard; don't ignore it. Clone only to develop (see [Development](#development)), and keep your own pipeline runs elsewhere. @@ -168,12 +162,17 @@ No token yet? `extract` works immediately (it only needs the Anthropic key), and ## Development ```sh -uv run pytest # offline test suite (stub fixtures, no network) +git clone https://git.kestrelsnest.social/eric/bggpipe.git +cd bggpipe +uv sync # installs Python deps +uv run pytest # offline test suite (recorded fixtures, no network) uv run pytest --run-live # + a read-only live-API smoke test (needs token) uv run ruff check src tests # lint -uv run bggpipe review --web --dev # review UI with code hot-reload +uv run bggpipe web --dev # the app with code hot-reload ``` +Run your own *pipeline* from a different directory (see [Bring your own shelves](#bring-your-own-shelves)) — the clone's `data/` is the author's live data, and the app will warn if you point it at git-tracked paths. + The review UI live-follows the data files — run `extract` or `resolve` in another terminal and the page updates itself. Architecture and contributor guidance: [CLAUDE.md](CLAUDE.md) and the [full spec](bgg-shelf-pipeline-spec.md); BGG automation notes: [docs/bgg-upload-flow.md](docs/bgg-upload-flow.md). ## A note on being a good BGG citizen