FabledCurator/ci-requirements.md

CI Requirements — FabledCurator

Spec: https://git.fabledsword.com/bvandeusen/CI-runner/src/branch/main/docs/process.md

Runtime image

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

Image deps used

• python 3.14
• ruff (analyzer for backend/, tests/, alembic/)
• node (frontend job: npm install + vitest + vite build)
• docker CLI + buildx (.forgejo/workflows/build.yml: build-web, build-ml — Fabled-Git registry push)

Secondary runtime image

node:24-bookworm-slim — .forgejo/workflows/extension.yml only.

The extension lane is the one job that does NOT run on ci-python:3.14: it needs a current Node for web-ext and vitest and nothing Python at all. Kept on the upstream slim image rather than adding a Node toolchain to ci-python, per docs/process.md's "add deps to the image when used by >1 project".

Per-job tool installs

• pip install -r requirements.txt pytest pytest-asyncio — in backend-lint-and-test and integration jobs
• npm install --no-audit --no-fund — in frontend-build job
• npm install --no-audit --no-fund — in extension.yml's lint job (web-ext + vitest)
• unzip — in extension.yml's "Verify XPI contents" step, installed via apt only when absent (node:24-bookworm-slim may or may not carry it). Debian package, ~2s. Not worth baking into a shared image for a single consumer, per docs/process.md's ">1 project" rule.

Notes

• Integration wall time ~3 min, dominated by pgvector container start + the pip install step (~30-45s on cold cache) + alembic + 300+ integration tests.
• The pip install in two jobs is intentional and per docs/process.md's "add deps to image when used by >1 project" rule: FC alone is one Python project, so the deps live in requirements.txt and install per-job. Reconsider when a second Fabled-family Python backend lands.
• Integration uses Fabled-Git Actions services: + socket-discovered bridge IPs because act_runner (swarm-runner v0.6+) puts services on the default bridge with no embedded DNS. The pattern is documented in the rulebook's fabled-git.md "CI philosophy" section and FC's ci.yml is the canonical example.
• No package-lock.json is tracked yet (FC's feedback_no_local_runs memory bans npm install locally). Using npm install rather than npm ci until a lockfile lands.
• No imagemagick / pandoc per-job installs needed.
• extension/'s vitest specs load lib/*.js by evaluating the real file as a classic script (test/helpers/loadLib.js) rather than adding module.exports shims to production code — the libs ship as background.scripts, not ES modules, so the specs exercise exactly the bytes packaged into the XPI.
• extension/scripts/packaging.sh is the single definition of what ships inside the XPI. Two consumers read from it rather than keeping their own copy: web-ext's --ignore-files (extension/package.json), and the git log pathspec inside the script's own version derivation. It was three until 2026-08-27 — ci.yml's extension-version guard held the third and went when the manual bump it guarded did (milestone 271 step 5). Hand-kept copies of that one fact is what allowed issue #2397, so extension/test/version.spec.js asserts no workflow has reintroduced a literal :(exclude)extension/….
• The shipped extension version is derived, not committed. It is the commit TIME of the newest packaged-extension change (minutes since 2020-01-01, per family rule 149 — never a commit count, which orders by branch rather than by recency). build.yml's sign-extension computes it and stamps it into extension/manifest.json + package.json in the working tree before signing; the stamp is never committed. Treat the version in the repo as a base: only its MAJOR.MINOR is read, and its patch component is inert.
• Every job that calls packaging.sh version checks out with fetch-depth: 0 — build.yml's sign-extension and build-web, and ci.yml's extension-version. A depth-1 clone sees one commit and derives a wrong, too-low value rather than failing, so the full-history checkout is load-bearing rather than incidental.
• FC_CHANNEL is a build arg, not a runtime setting. build.yml passes dev / main to the web image only (the ml and agent images have nothing to report it to), and /api/extension/manifest reports it beside the version so an install can be traced to a channel. It is declared LAST in the Dockerfile on purpose: an ARG invalidates every layer below it, and this is the one value that differs between the dev and main builds of identical source, so placing it earlier would stop the two channels ever sharing a cached pip install. Empty by default — a local build then reports no channel at all rather than claiming one.
• Callers MUST set -f before substituting the script's output. Without it the shell expands test/** against the working tree and silently narrows the pattern to whatever files exist at that moment — a failure that looks like nothing until dev files start appearing in the XPI. test/version.spec.js asserts every --ignore-files consumer sets it, and that no consumer has quietly reinstated a hardcoded list.