# CI Requirements — ThoughtSync

> 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
```

Selected via `container.image` (not a `runs-on` label) on all four jobs in
`.forgejo/workflows/ci.yml`: typecheck (Vue/TS), lint (ruff), test (pytest),
build (docker buildx).

## Image deps used

- python 3.12+ (the runtime `Dockerfile` targets python:3.12-slim; tests run on
  the image's 3.14 — both >=3.12, so results stay representative)
- node 24 — `npm ci` + `vue-tsc` in the typecheck job, and the frontend builder
  stage inside the production `Dockerfile`. (Also required by the JS-based
  `actions/checkout` action — a Node-less runner fails every job at checkout.)
- ruff — lint job runs `ruff check src/` with zero install overhead
- uv — test job creates the venv (`uv venv /opt/venv`) and installs the package
  with dev deps
- docker CLI + buildx — build job pushes the dev/release image to the Forgejo
  registry

## Per-job tool installs

Nothing installed at job time beyond what the image provides — all four jobs run
entirely on `ci-python:3.14`.

## Notes

- **No `actions/cache`.** Deliberately omitted for npm/uv: it's a GitHub-fetched
  JS action and on a cold runner concurrent jobs race fetching it. We lean on the
  pinned `ci-python` image's pre-installed toolchain instead; `npm ci` / `uv pip
  install` cold cost is a non-blocker.
- Build gates on `typecheck` + `lint` only. The `test` job runs in parallel for
  visibility but does not block the dev image push. DB-backed / integration tests
  run against the dev image manually — ThoughtSync's unit tests are DB-free (no
  Postgres service lane in CI yet).
- `dev` push -> `:dev` + `:<sha>`; `v*` tag -> `:latest` + `:<version>` + `:<sha>`
  (family rule 46).
- The production runtime `Dockerfile` tracks python:3.12 so test results stay
  representative of the deployed image.

## Desktop (Tauri) lane — separate workflow

The Tauri desktop client (`desktop/`) builds in its own workflow,
`.forgejo/workflows/desktop.yml`, NOT in `ci.yml` — it's a heavy Rust + AppImage
build (~20–40 min) that should only run on `desktop/**` changes, not on every
backend/frontend push.

- **Image:** `git.fabledsword.com/bvandeusen/ci-tauri:1.97` (Rust + Node +
  WebKitGTK 4.1 + Tauri v2 Linux deps + `tauri-cli`). Selected via
  `container.image`; `runs-on: python-ci` is only a scheduling label.
- **Steps:** build the shared frontend (embedded by `generate_context!`) →
  `cargo tauri icon app-icon.png` (platform icon set from the committed 1024px
  source) → `cargo fmt --check` → `cargo clippy -D warnings` → `cargo test` →
  `cargo tauri build` (produces `.deb` + `.AppImage`) → de-bundle the AppImage's
  graphics libs → verify the `.deb` → repackage for pacman.
- **`APPIMAGE_EXTRACT_AND_RUN=1`** is set: AppImage tooling FUSE-mounts by default
  and CI containers have no `/dev/fuse`.
- **Packaging tools used from the image** (none installed at job time, rule 5):
  `dpkg-deb` / `dpkg-query` / `apt-cache` and `dpkg-shlibdeps` (from `dpkg-dev`,
  pulled in by `build-essential`) for `desktop/packaging/deb/verify.sh`; `tar` +
  a compressor for `desktop/packaging/arch/package-prebuilt.sh`. Both scripts
  degrade gracefully rather than hard-failing on an absent optional tool:
  `bsdtar` (`libarchive-tools`) is used for the pacman package's `.MTREE` when
  present and skipped when not, compression falls back zstd → xz → gzip, and the
  `.deb` clean-container install test runs only if a docker CLI is available.
  Run 2872 confirmed all three optional tools are ABSENT today, so the current
  build takes every fallback: the pacman package ships as `.pkg.tar.xz` with no
  `.MTREE`, and the `.deb` clean-container install test is skipped. All three are
  functional outcomes — pacman installs an `.xz` package fine, and only
  `pacman -Qkk` file verification needs `.MTREE`. Adding `libarchive-tools` +
  `zstd` + a docker CLI to `ci-tauri` would upgrade these paths; none of them
  block a green build.
- **Not verifiable in CI:** the runner is Debian, so the pacman package cannot be
  `pacman -U`-tested here. That step logs `.PKGINFO` + the full file listing so
  the package is auditable from the run log; a real Arch install is the operator's
  confirm.
- No Postgres lane (unchanged): the desktop app's local store + sync behavior is
  verified on the operator's machine, not in CI.