# CI Requirements — FabledScribe

> Spec lives in [`docs/process.md`](https://git.fabledsword.com/bvandeusen/CI-runner/src/branch/main/docs/process.md)
> in the CI-Runner repo.

## Runtime image

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

Used by all six jobs in `.forgejo/workflows/ci.yml`: typecheck (Vue/TS),
plugin (hook checks), lint (ruff), test (pytest), integration (pytest +
real Postgres), build (docker buildx).

## Image deps used

- python 3.14
- node 24 (`npm ci` + `vue-tsc` in the typecheck job; the production
  `Dockerfile` builds the frontend on `node:22-alpine`)
- ruff (lint job runs `ruff check src/ scripts/` with zero install overhead)
- uv (test + integration jobs run `uv sync --locked`)
- docker CLI + buildx (build job pushes the production image to the
  Fabled-Git registry)

## Per-job tool installs

Anything CI installs at job time that isn't in the image. Promotion
candidates if more than one project needs them.

- `shellcheck` — apt-installed in the **plugin** job, which lints the
  Claude Code hook scripts and runs their fail-open smoke test. Scribe is
  its only consumer, so per `docs/process.md` it stays per-job. It is small
  (~20 MB) and a promotion candidate once another project lints shell.

The hooks ship to users' machines, so they use only POSIX tools (awk, sed,
tr, od, cut, head, tail, grep, sort, date, printf) plus `git` and `curl`.
The smoke test runs on a bare image to keep it that way: a tool such as `jq`
is missing on macOS, slim Debian/Ubuntu and Alpine, and a hook that needed it
would give those machines nothing.

## Notes

- Production runtime image (`Dockerfile`) also tracks Python 3.14 — the
  CI image and runtime image stay aligned by design so test results are
  representative.
- Build wall time: dominated by `pytest` (full async test suite). Cold
  ci-python pulls add ~30s; not a blocker.
- Registry-backed BuildKit layer cache (`type=registry,ref=…:cache,mode=max`)
  gives ~80% speedup on warm builds — see the build job comment.
- `pyproject.toml` pins `requires-python = ">=3.14"` to match the CI +
  runtime target; lockfile (`uv.lock`) is committed and resolves against
  Python 3.14.