StashHandler/ci-requirements.md

CI Requirements — StashHandler

Spec lives in docs/process.md in the CI-Runner repo.

Runtime image

The runner image this project's CI consumes via container.image.

git.fabledsword.com/bvandeusen/ci-python:3.14

CI lints and tests under 3.14; the shipped runtime is Python 3.12 (the app Dockerfile is FROM python:3.12-slim). The code targets 3.12+ features only (walrus, datetime.now(timezone.utc)), so the version gap is intentional and harmless.

Image deps used

Tools/libraries already in the image that this project actually relies on:

• python 3.14 (test interpreter)
• ruff (lint lane — runs with no per-job install)
• docker CLI + buildx (used by the publish job's build-push step)

Per-job tool installs

Anything CI installs at job time (not in the image):

• pip/uv install -r requirements.txt pytest blake3 in the unit job.
  • pytest — test runner (not in the image).
  • blake3 — optional runtime hash backend (HASH_ALGORITHM=blake3), exercised by the hasher tests. Not in requirements.txt because the default sha256 path uses stdlib hashlib.

Notes

Friction, expectations, and anything the maintainer wouldn't see otherwise:

• No integration lane. StashHandler persists to SQLite (per-run tmpfiles in tests) and talks to qBittorrent/Stash over HTTP at runtime only — there is no service container to stand up, so family rules 79–82 don't apply here.
• Three lanes: lint (ruff) → unit (pytest) → publish (gated image build+push, family rule 46 tag scheme). Publish image is git.fabledsword.com/bvandeusen/stashhandler (lowercase — matches the prod compose pull).
• Unit suite is a starter set covering the pure logic (hashing, SQLite dedup, media-extension filter, file transfer modes). Grow it as behavior is added.
• Requires repo Actions secret REGISTRY_TOKEN (Forgejo PAT, read:package + write:package) for the publish lane — the injected GITHUB_TOKEN can't push to the registry (family rule 7).