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/`, `agent/`, `scripts/`)
- node (frontend job: `npm install` + vitest + vite build)
- docker CLI + buildx (`.forgejo/workflows/build.yml`: build-web, build-ml, build-agent — Fabled-Git registry push, and `imagetools inspect`/`create` for the reuse path)

## Secondary runtime image

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

`.forgejo/workflows/release.yml` runs on `ci-python:3.14` like everything else
and installs nothing: it needs git and stdlib python, and builds no image.

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.** Three consumers read from it rather than keeping their own
  copy: web-ext's `--ignore-files` (`extension/package.json`), the `git log`
  pathspec inside the script's own version derivation, and `scripts/artifacts.sh`,
  which appends the extension's set to web's because the web image bundles the
  signed XPI. 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/…`.
- **Packaged and version-relevant are two different sets** (#3156). `scripts/`
  is excluded from the XPI and is NOT excluded from the version derivation,
  because `packaging.sh` decides the version string stamped into the packaged
  `manifest.json`. The membership test is *"can changing this file change the
  published bytes?"*, not *"is this file copied in?"* — which is why the script
  keeps two lists rather than one.
- **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 derives anything checks out with `fetch-depth: 0` — all four
  `build.yml` jobs, `ci.yml`'s `extension-version` and `backend-lint-and-test`
  (for `tests/test_artifact_paths.py` and `test_artifact_identity.py`), and
  `release.yml`, which additionally walks the tag graph. 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.
- **`scripts/artifacts.sh` is the same shape one level up: one definition per
  artifact of what it is built from, and the two values derived from it.**
  `revision` (12 hex of the newest commit touching that set) and `version`
  (`YYYY.MM.DD.HHMM` UTC, rule 148). Four artifacts, four independent answers,
  so a push touching only `agent/` leaves web and ml alone.
  `tests/test_artifact_paths.py` reads each Dockerfile and asserts every COPY
  source is covered, so adding a COPY without updating the script fails CI.
- **A file that DECIDES an artifact's identity belongs in its set even though it
  is copied into nothing** — `packaging.sh` for the extension and web (#3156),
  and `artifacts.sh` itself for web (#3202), which decides the `FC_VERSION`
  baked into that image. Only web needs the second entry: every artifact stamps
  a revision, but a revision has a backstop (a changed derivation stops matching
  the published label and forces a rebuild) and a version has none, because
  nothing compares it to anything. `tests/test_artifact_paths.py`'s `DERIVERS`
  table is the guard.
- **Builds are skipped when the content is already published.** Each image
  carries its revision as an `fc.revision` LABEL, and `build.yml` reads that
  label back off the moving channel tag (`imagetools inspect --format`). Equal
  to the derived revision means the bytes are already published, so the job
  repoints the remaining tags at the existing manifest instead of rebuilding.
  Two things this depends on: an inspect that errors for ANY reason reads as a
  MISS so no needed build is ever skipped, and the repoint must EXCLUDE the
  source tag — `imagetools create` wraps its source in a manifest index, and
  config labels do not resolve through an index, so writing the channel tag
  from itself destroys the label the next run reads (#3183).
- **The build pushes exactly ONE tag — the channel's — and every other tag is
  written registry-side afterwards** (#3190). buildx on this runner pushes the
  first tag to the registry and then re-pushes the rest through the docker
  driver, out of a local image store that a registry-direct build never fills;
  it fails intermittently with `tag does not exist`. On `dev` that only reddens
  a job, but on `main` it silently skips `:c-<sha>` while `:latest` publishes
  fine — a missing rollback tag has no consumer that fails, so nothing but the
  red job would notice until somebody needs to roll back. `imagetools create`
  has no local store to be absent from, and it is the code the reuse path
  already ran, so both paths now share one proven route. The cost: `:c-<sha>`
  is an index rather than a plain image, so `fc.revision` does not resolve
  through it — nothing reads it there, and the index names the same manifest.
- **`FC_CHANNEL` and `FC_VERSION` are build args, not runtime settings.**
  `build.yml` passes them to the web image only — the ml and agent images have
  nothing to report them to. `/api/health` returns both, the foot of Settings
  renders them, and `/api/extension/manifest` reports the channel beside the
  extension version so an install can be traced to a channel. With no version image tags, that
  self-report is the ONLY answer to "which build is this?" — which is why a
  missing version renders `unknown` rather than a blank: an empty footer reads
  as "no version", a different and false claim.
  Both are declared LAST in the Dockerfile on purpose: an ARG invalidates every
  layer below it, and these are the values that differ between the dev and main
  builds of identical source, so placing them earlier would stop the two
  channels ever sharing a cached `pip install`. Empty by default — a local build
  then reports nothing rather than claiming a channel it is not on.
- **The channel is never folded into the version.** A `-dev` suffix makes the
  extension's per-segment `parseInt` comparator read that segment as 0, so every
  dev build compares equal to every other — issue #2993 exactly (rule 149).
  `frontend/test/systemBuild.spec.js` pins the rendered version to the bare
  number.
- 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.