spareparts-cli 0.1.0__tar.gz

spareparts_cli-0.1.0/.github/dependabot.yml

@@ -0,0 +1,31 @@
+version: 2
+
+# The upgrade half of dependency scanning. `dependency-scan.yml` fails a build
+# that is already vulnerable; this opens the pull request that fixes it.
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: chore
+    groups:
+      # One PR for the whole set. Three vendor SDKs on separate weekly PRs is
+      # how a repository trains its owner to stop reading them.
+      python:
+        patterns: ["*"]
+
+  # Workflow actions pin to major tags that move, so this mostly catches
+  # deprecations (a runner dropping node16 actions, say) before they break CI.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    commit-message:
+      prefix: chore
+    groups:
+      actions:
+        patterns: ["*"]

spareparts_cli-0.1.0/.github/workflows/dependency-scan.yml

@@ -0,0 +1,46 @@
+name: Dependency scan
+
+# Known-vulnerable dependencies, checked against the Python Packaging Advisory
+# Database and OSV by pip-audit (https://pypi.org/project/pip-audit/).
+#
+# Self-contained, like the secret scan: no shared workflow, no GitHub Advanced
+# Security. Dependabot (see .github/dependabot.yml) opens the upgrade PRs; this
+# job is what fails a build that ships a vulnerable dependency in the meantime.
+#
+# The schedule matters more than the PR trigger. A dependency does not become
+# vulnerable when someone edits pyproject.toml; it becomes vulnerable when an
+# advisory is published, which can be months after the last commit here.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "0 7 * * 1"
+  workflow_dispatch:
+
+jobs:
+  audit:
+    name: pip-audit
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      # `all`, not the bare install: the extras are dependencies this project
+      # tells people to install, so an advisory against one of them is ours.
+      - name: Install every declared dependency
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[all]' pip-audit
+
+      - name: Audit
+        # --skip-editable skips this project itself, which has no PyPI release
+        # to look up. Everything it pulled in is still audited, and the summary
+        # pip-audit prints lists exactly what was skipped and why.
+        run: pip-audit --skip-editable

spareparts_cli-0.1.0/.github/workflows/homebrew.yml

@@ -0,0 +1,110 @@
+name: Update Homebrew tap
+
+# On every release tag, point the sparepartslabs/homebrew-tap formula at the new
+# PyPI sdist. Runs alongside publish.yml (same v* trigger) and waits for the
+# sdist to appear on PyPI before reading its canonical URL + sha256.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  bump:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Resolve version
+        id: v
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Fetch sdist url + sha256 from PyPI (wait for publish)
+        id: pypi
+        run: |
+          VERSION="${{ steps.v.outputs.version }}"
+          for i in $(seq 1 30); do
+            JSON=$(curl -fsSL "https://pypi.org/pypi/spareparts-cli/${VERSION}/json" || true)
+            URL=$(printf '%s' "$JSON" | jq -r '.urls[]? | select(.packagetype=="sdist") | .url')
+            SHA=$(printf '%s' "$JSON" | jq -r '.urls[]? | select(.packagetype=="sdist") | .digests.sha256')
+            if [ -n "$URL" ] && [ "$URL" != "null" ]; then break; fi
+            echo "sdist for ${VERSION} not on PyPI yet, retrying ($i)..."
+            sleep 10
+          done
+          if [ -z "$URL" ] || [ "$URL" = "null" ]; then
+            echo "::error::spareparts-cli ${VERSION} sdist not found on PyPI"; exit 1
+          fi
+          echo "url=$URL" >> "$GITHUB_OUTPUT"
+          echo "sha=$SHA" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout tap
+        uses: actions/checkout@v4
+        with:
+          repository: sparepartslabs/homebrew-tap
+          token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+
+      - name: Update formula (url, sha256, and vendored resources)
+        env:
+          VERSION: ${{ steps.v.outputs.version }}
+          URL: ${{ steps.pypi.outputs.url }}
+          SHA: ${{ steps.pypi.outputs.sha }}
+        run: |
+          F=Formula/spareparts-cli.rb
+          sed -i -E "s#^  url \".*\"#  url \"${URL}\"#" "$F"
+          sed -i -E "s#^  sha256 \".*\"#  sha256 \"${SHA}\"#" "$F"
+
+          # Refresh the vendored `resource` blocks. `brew update-python-resources`
+          # can't be used on release day (it skips PyPI uploads less than a day
+          # old), so resolve the deps in a throwaway venv and read each sdist
+          # url+sha256 from PyPI.
+          #
+          # `[all]` on purpose: pip installing this package brings no vendor SDK,
+          # because none of the three is the assumed one. A brew install has no
+          # extras syntax to offer, so the bottle carries all three and the CLI
+          # uses whichever key you have set.
+          python3 - "$F" "$VERSION" <<'PY'
+          import json, re, subprocess, sys, tempfile, urllib.request, venv
+
+          formula, version = sys.argv[1], sys.argv[2]
+          tmp = tempfile.mkdtemp()
+          venv.create(f"{tmp}/v", with_pip=True)
+          pip = f"{tmp}/v/bin/pip"
+          subprocess.check_call([pip, "install", "-q", f"spareparts-cli[all]=={version}"])
+          freeze = subprocess.check_output([pip, "list", "--format=freeze"]).decode()
+
+          skip = {"spareparts-cli", "pip", "setuptools", "wheel"}
+          deps = []
+          for line in freeze.splitlines():
+              if "==" in line:
+                  name, ver = line.split("==", 1)
+                  if name.lower() not in skip:
+                      deps.append((name, ver))
+
+          blocks = []
+          for name, ver in sorted(deps, key=lambda x: x[0].lower()):
+              d = json.load(urllib.request.urlopen(f"https://pypi.org/pypi/{name}/{ver}/json"))
+              sd = next((u for u in d["urls"] if u["packagetype"] == "sdist"), None)
+              if not sd:
+                  sys.exit(f"no sdist for {name} {ver}")
+              blocks.append(
+                  f'  resource "{d["info"]["name"]}" do\n'
+                  f'    url "{sd["url"]}"\n'
+                  f'    sha256 "{sd["digests"]["sha256"]}"\n'
+                  f'  end'
+              )
+
+          text = open(formula).read()
+          # drop existing resource blocks, then insert fresh ones after depends_on
+          text = re.sub(r'\n  resource "[^"]+" do\n(?:.*\n)*?  end\n', '\n', text)
+          inject = "\n" + "\n\n".join(blocks) + "\n"
+          text = re.sub(r'(  depends_on "python@[^"]+"\n)', r'\1' + inject, text, count=1)
+          text = re.sub(r'\n{3,}', '\n\n', text)  # collapse blank runs (idempotent)
+          open(formula, "w").write(text)
+          print(f"refreshed {len(blocks)} resources: {', '.join(n for n, _ in deps)}")
+          PY
+
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          if git diff --quiet; then
+            echo "formula already up to date"; exit 0
+          fi
+          git commit -am "spareparts-cli ${VERSION}"
+          git push

spareparts_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,82 @@
+name: Publish to PyPI
+
+# Releases are tags. `git tag v0.2.0 && git push --tags` publishes 0.2.0 and
+# nothing else does, so what is on PyPI is always something someone chose to
+# put there.
+
+on:
+  push:
+    tags:
+      - "v*" # e.g. v0.1.0
+
+permissions:
+  contents: read
+  id-token: write # PyPI Trusted Publishing (OIDC)
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # A tag that disagrees with pyproject publishes a version nobody asked
+      # for, under a name that already means something else. Cheaper to fail
+      # here than to yank a release: PyPI will not let the number be reused.
+      - name: The tag must match the version in pyproject
+        run: |
+          python - <<'PY'
+          import os, sys, tomllib
+          tag = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+          with open("pyproject.toml", "rb") as f:
+              declared = tomllib.load(f)["project"]["version"]
+          if tag != declared:
+              sys.exit(f"tag {tag} does not match pyproject version {declared}")
+          print(f"releasing {declared}")
+          PY
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      # Trusted Publishing, so there is no API token to store or rotate. PyPI
+      # is configured to trust this repository, this workflow file, and the
+      # `pypi` environment above; changing any of those three breaks the
+      # release until PyPI's publisher settings are updated to match.
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  # A tag is a git object with no page. A release is where someone deciding
+  # whether to install this reads what changed and whether it is still alive,
+  # and PyPI shows them the current version and nothing about the last one.
+  #
+  # Its own job so that `publish` keeps `contents: read`: the job holding the
+  # PyPI identity token has no business also being able to write to the repo.
+  release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Notes are generated from what changed since the previous tag, which
+          # a shallow clone cannot see.
+          fetch-depth: 0
+
+      # --generate-notes writes them from the pull requests merged since that
+      # tag, so there is no changelog to maintain by hand and no second place
+      # for the history to be wrong.
+      #
+      # The sdist and wheel are deliberately not attached: PyPI already serves
+      # them, and a second copy is one more thing that can disagree.
+      - name: Create the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" --generate-notes --verify-tag

spareparts_cli-0.1.0/.github/workflows/secret-scan.yml

@@ -0,0 +1,81 @@
+name: Secret scan
+
+# Detection is TruffleHog (https://github.com/trufflesecurity/trufflehog): it
+# verifies found credentials against live services, so a match reported here is
+# far more likely to be a real, active secret than a shape-based false positive.
+#
+# Self-contained by design. This repository depends on nothing private to run
+# its own CI, so the steps are inlined rather than called from a shared workflow.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  secrets:
+    name: trufflehog
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    env:
+      TRUFFLEHOG_VERSION: "3.95.9"
+    steps:
+      - name: Check out full history
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Resolve scan base
+        id: base
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          PR_BASE: ${{ github.event.pull_request.base.sha }}
+          PUSH_BEFORE: ${{ github.event.before }}
+        run: |
+          # A pull request scans everything its head adds over its base. A push
+          # scans the pushed range; a first push (all-zero "before") has no base,
+          # so scan the whole history that arrived with it.
+          if [ "$EVENT_NAME" = "pull_request" ]; then
+            echo "since=$PR_BASE" >> "$GITHUB_OUTPUT"
+          elif [ "$PUSH_BEFORE" = "0000000000000000000000000000000000000000" ] || [ -z "$PUSH_BEFORE" ]; then
+            echo "since=" >> "$GITHUB_OUTPUT"
+          else
+            echo "since=$PUSH_BEFORE" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Install TruffleHog
+        run: |
+          curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh \
+            | sh -s -- -b /usr/local/bin "v${TRUFFLEHOG_VERSION}"
+          trufflehog --version
+
+      - name: Scan for secrets
+        env:
+          SINCE: ${{ steps.base.outputs.since }}
+        run: |
+          # --results=verified,unknown: fail on live-verified credentials AND on
+          # findings TruffleHog cannot verify (private keys, offline tokens), so a
+          # real secret with no live endpoint to check is not silently ignored.
+          # --fail exits non-zero when any such result is found; --no-update keeps
+          # CI from self-upgrading the pinned binary.
+          #
+          # --exclude-detectors=Lob: Lob's detector matches any `test_`-prefixed
+          # token of about thirty characters, and Lob's API verifies those, so
+          # four pytest function names in this repository (for instance
+          # `test_the_revisit_note_points_at_the_file`) report as live, verified
+          # credentials. Nothing here talks to Lob, so the detector costs
+          # nothing to drop; the alternative, excluding the paths, would blind
+          # the scan to every test file instead.
+          set -- git "file://." --results=verified,unknown --fail --no-update \
+            --exclude-detectors=Lob
+          if [ -n "$SINCE" ]; then
+            set -- "$@" --since-commit "$SINCE"
+          fi
+          # A repo may ship a .trufflehog-exclude file (newline-separated path
+          # regexes) to suppress known-safe committed matches, e.g. throwaway
+          # keys in test fixtures or example connection strings in docs.
+          if [ -f .trufflehog-exclude ]; then
+            set -- "$@" --exclude-paths .trufflehog-exclude
+          fi
+          trufflehog "$@"

spareparts_cli-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,92 @@
+name: Tests
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  pytest:
+    # What the check reads as on a PR: "Tests / pytest on Python 3.11". The
+    # default would be `pytest (3.11)`, a bare number next to two others.
+    name: pytest on Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # The floor pyproject declares, through the current release. `sp` is
+        # installed onto whatever interpreter a contributor already has, so the
+        # supported range is a promise rather than an aspiration.
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: pip install -e '.[dev]'
+
+      - name: Run tests
+        run: pytest -q
+
+  # A bare `pip install spareparts-cli` pulls Anthropic and nothing else, which
+  # is the install most people get. If an OpenAI or Gemini import ever leaks out
+  # of its adapter and into a shared path, it surfaces here as a crash on
+  # `--help` rather than in a stranger's terminal.
+  bare-install:
+    name: bare install runs with no provider extras
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install without provider extras
+        run: pip install .
+
+      - name: The CLI must run with only the default vendor installed
+        run: |
+          if python -c "import openai" 2>/dev/null; then
+            echo "openai is installed; this job is not testing what it claims"
+            exit 1
+          fi
+          sp --help
+          sp lgtm --help
+
+  build:
+    name: build the wheel and check its contents
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: |
+          pip install build
+          python -m build
+
+      - name: Check the distribution
+        run: |
+          pip install twine
+          twine check dist/*
+
+      # The prompt files are data, not code, and a packaging change that drops
+      # them leaves a CLI that imports fine and then cannot generate anything.
+      - name: The wheel must carry the prompt files
+        run: |
+          python - <<'PY'
+          import pathlib, zipfile
+          wheel = next(iter(sorted(pathlib.Path("dist").glob("*.whl"))))
+          names = zipfile.ZipFile(wheel).namelist()
+          prompts = [n for n in names if "/prompts/" in n and n.endswith(".json")]
+          assert prompts, f"no prompt JSON in {wheel.name}: {names}"
+          print("\n".join(prompts))
+          PY

spareparts_cli-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.env
+*.pem
+specs/

spareparts_cli-0.1.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: spareparts-cli
+Version: 0.1.0
+Summary: sp — the Spare Parts command line
+Author: Spare Parts Labs
+License: UNLICENSED
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: all
+Requires-Dist: anthropic>=0.72; extra == 'all'
+Requires-Dist: google-genai>=2.0; extra == 'all'
+Requires-Dist: openai>=2.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.72; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: anthropic>=0.72; extra == 'dev'
+Requires-Dist: google-genai>=2.0; extra == 'dev'
+Requires-Dist: openai>=2.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: gemini
+Requires-Dist: google-genai>=2.0; extra == 'gemini'
+Provides-Extra: openai
+Requires-Dist: openai>=2.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# sp
+
+The Spare Parts command line.
+
+```
+pip install ".[anthropic]"     # or [openai], or [gemini], or [all]
+sp
+```
+
+## Modules
+
+| Module | What it does |
+|---|---|
+| `sp lgtm` | Prove you read a diff before you merge it |
+
+---
+
+## `sp lgtm`
+
+Generates a few multiple-choice questions about a range of commits and asks
+them, in your terminal. The questions are about what the change *does* — what a
+new guard prevents, what the error path now returns, which edit can touch
+existing rows — never about statistics, naming, or formatting.
+
+```sh
+sp lgtm                       # what this branch adds since it left main
+sp lgtm main...feature/x      # someone else's branch, before you merge it
+sp lgtm -n 3 -d hard
+sp lgtm --dry-run             # what it would ask about, no model call
+```
+
+Generation is three model calls, so expect it to take a moment — this is a thing
+you run before a merge, not on every commit.
+
+### Providers
+
+Anthropic, OpenAI and Gemini, and no vendor is the assumed one. Install the SDK
+for whichever you use:
+
+```sh
+pip install ".[anthropic]"     # or [openai], or [gemini], or [all]
+```
+
+Name nobody and `sp` uses whichever key you have set. With more than one set it
+picks in the order below, which is a tie-break rather than a ranking; name
+`provider:` in `.github/lgtm.yml` to decide it yourself.
+
+| Vendor | Key | Default model | Typical run |
+|---|---|---|---|
+| `anthropic` | `ANTHROPIC_API_KEY` | `claude-opus-5` | ~55s |
+| `openai` | `OPENAI_API_KEY` | `gpt-5.5` | ~65s |
+| `gemini` | `GEMINI_API_KEY` or `GOOGLE_API_KEY` | `gemini-pro-latest` | ~115s |
+
+```sh
+sp lgtm -p openai
+sp lgtm -p gemini --model gemini-3.6-flash
+sp lgtm -p anthropic --verifier openai     # see below
+```
+
+All three are exercised against live APIs, on a 32KB diff, and the timings above
+are from those runs.
+
+The defaults were chosen by listing each vendor's models with a live key. Gemini
+uses the tracking alias because the vendor currently publishes no plain
+`gemini-3.x-pro` — only `-image` variants — so pinning a pro model would mean
+pinning to 2.5 indefinitely. The other two pin, because a default that changes
+underneath a quiz changes what the quiz asks.
+
+### Two vendors are better than one
+
+`sp lgtm` writes a question with one call and then asks a second call to refute
+it. A candidate that can't be refuted survives; everything else is dropped.
+
+Both calls going to the same model is the weak version of that check — a model
+asked to find fault with its own reasoning mostly doesn't. If you have keys for
+two vendors, split them:
+
+```sh
+sp lgtm --provider anthropic --verifier openai
+```
+
+That is the strongest arrangement available, and it is why the provider layer
+exists rather than a bare `--model` flag. It costs one extra vendor's tokens and
+nothing else — the verifier sees the question and the diff, never the
+proposer's reasoning.
+
+It also costs no extra wall-clock in practice: proposing and verifying are
+sequential either way, and the cross-vendor run above came in at 68s against
+55s for Anthropic alone.
+
+### It is a self-check, not a gate
+
+`sp lgtm` has no way to stop you doing anything. The answers live in the same
+process as the questions, on your machine, and you can skip the whole thing.
+That is on purpose: the version that actually gates is the
+[GitHub Action](https://github.com/sparepartslabs/spareparts-lgtm), which asks
+the *reviewer* after they approve and holds a check run open until they answer.
+
+What local gets in exchange is the thing the Action can't have: the code is
+checked out. Press `?` on any question to print the hunk it came from. Wrong
+answers are never a failure — you get told which files to look at again, and it
+re-asks, as many times as you like.
+
+### Configuration
+
+Reads `.github/lgtm.yml` from the repo you're in, the same file the Action uses,
+so a repo is configured once:
+
+```yaml
+questions: 2          # 1-5
+difficulty: medium    # easy | medium | hard
+provider: anthropic   # anthropic | openai | gemini, or vendor:model
+verifier: openai      # optional; defaults to the proposer
+exemptPaths:
+  - "docs/**"
+```
+
+`provider` and `verifier` are read here but validated by the provider layer, so
+a typo is reported with the list of known vendors rather than silently ignored.
+
+Keys that only mean something to the Action (`enforce`, `webConcepts`,
+`surfaceReading`, `answerQuestions`, `exemptReviewers`) are accepted and
+ignored. `-n` and `-d` override the file.
+
+Lockfiles, `dist/`, `vendor/`, `*.pbxproj` and friends are never quizzed.
+
+### As a git hook
+
+```sh
+sp lgtm install                       # pre-push, advisory
+sp lgtm install --hook pre-commit     # earlier, and once per commit
+sp lgtm install --blocking            # wrong answers stop the push
+sp lgtm uninstall
+```
+
+**`pre-push` is the default.** The old framing for this tool was "the person
+answering didn't write the code" — that's why it quizzes a *reviewer*. That
+framing is dated: when a model wrote the diff, nobody in the loop wrote it, and
+the author is as much a reader as anyone. The useful question isn't who typed
+it, it's where the last cheap moment to catch it is — and that's before the code
+leaves your machine, which is left of anything the Action can do.
+
+It also matches how the cost lands. Generation is three model calls and about a
+minute; per *push* that's fine, per *commit* it taxes every checkpoint you save.
+`--hook pre-commit` is there if you want it, and quizzes the staged diff.
+
+**Advisory by default.** A hook that costs a minute *and* can stop you is one
+you delete within a week. `--blocking` is opt-in, and even then only a wrong
+answer (exit 1) blocks — "couldn't ask" (exit 2: no API key, vendor outage,
+nothing quizzable) never costs you a push.
+
+Escape hatches, in the order you'll want them:
+
+```sh
+SP_LGTM_SKIP=1 git push ...    # skip this once
+git push --no-verify ...       # skip every hook
+```
+
+#### What it reads
+
+`pre-push` quizzes exactly what you're about to push. Git names the refs on
+stdin, so the hook takes `<remote sha>..<local sha>` — the commits the remote
+doesn't have yet. A branch the remote has never seen has no such range, so it
+falls back to what the branch adds since it left the default branch. A push that
+only *deletes* a remote branch reads nothing at all.
+
+That ref list arrives on the same stdin the quiz needs for answers, so the hook
+consumes it before attaching `/dev/tty`.
+
+It skips itself silently when there's no terminal — a rebase, a GUI client, CI.
+Git runs hooks with stdin closed; where there's no tty, nobody can answer and
+nobody failed.
+
+`sp lgtm install` refuses to overwrite a hook it didn't write (`--force`
+overrides), and honours `core.hooksPath` — writing to an assumed `.git/hooks`
+when that's set installs a hook that never runs, which looks exactly like
+success.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Confirmed |
+| 1 | Not confirmed — wrong answers, or you quit |
+| 2 | Couldn't ask — no API key, git failed, nothing quizzable |
+
+If you wire this into a git hook, treat only `1` as a failure. A tool that
+cannot run must not block a commit.
+
+## Development
+
+```sh
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/python -m pytest
+```
+
+`lgtm`'s diff parsing, config, screening and generator are a port of the
+TypeScript in
+[`spareparts-lgtm`](https://github.com/sparepartslabs/spareparts-lgtm). The
+prompts in `generator.py` are the part worth keeping identical — changing the
+wording here without changing it there produces two tools that disagree about
+the same diff.