# Development

**For:** contributors. **At the end:** you can set up the project, run every check, and cut a release.

Everything needed to work on wow-stats and cut a release. The command and the
Python package are `wow-stats`; the images are `wow-mcp` and `wow-mcp-render`.

## Set up

Python goes through [uv](https://docs.astral.sh/uv/) only.

```sh
uv sync --frozen --extra publish --extra mcp --group browser
uv run playwright install chromium webkit
```

The `browser` group and the two browsers are for the browser tests
(`tests/test_browser.py`, `tests/test_advice_browser.py`). Without them those
tests skip; CI doesn't install them, so run them locally before a release.

## The checks

```sh
uv run ruff check .
uv run pytest -q -rs        # about 950 tests, a few minutes; -rs lists what skipped
docker build -t wow-stats:dev .
docker build --target renderer -t wow-stats-render:dev .
```

What skips without what:

| Tests | Need |
|---|---|
| browser tests | the `browser` group and its browsers |
| `tests/test_compose.py` | `docker compose` |
| `tests/test_windows_e2e.py` | Windows (CI runs it on `windows-latest`) |
| `tests/test_renderer_browser.py`, `tests/test_model3d_browser.py` | `WOW_STATS_BROWSER=1`: they fetch Wowhead's viewer over the network |
| `tests/test_gear_parity.py` | `POLESTAR_CHECKOUT`: a Polestar clone at the pinned tag ([docs/gear-reference.md](https://sam-dumont.github.io/wow-mcp/game-data/gear-reference/)) |
| `tests/test_public_scan.py`, the name check | the denylist file (below) |

Optional: `pre-commit install` runs ruff, the lock and fixture checks,
actionlint and gitleaks before each commit (`.pre-commit-config.yaml`; the
last two when installed).

A pull request is ready when ruff and the tests that cover the change pass,
plus both image builds when it touches `data/`, `pyproject.toml` or the
Dockerfile. The whole list above runs once before a release.

## The docs site and its demo

The site (`site/`, Starlight) is built from this repository's Markdown: `README.md` stays
GitHub's front page, the site's home page is `site/pages/index.md`, and every page's address
and sidebar place come from `SECTIONS` in `site/scripts/prepare.mjs`. A Markdown file under
`docs/` that isn't placed there, or a broken link, fails the build. Images go in
`docs/images/`: the site serves them itself.

```bash
site/scripts/build-demo.sh        # the demo character's pages; needs uv and Docker (or VL_BIN)
npm --prefix site ci && npm --prefix site run build
npm --prefix site run preview     # http://localhost:4321/wow-mcp/
```

`build-demo.sh` plays Nibbet, a made-up priest (`tools/fixtures/generate.py --demo`, seeded,
so every build plays the same evenings, shifted so his last one is yesterday), then runs the
product's own publisher to build his public and friends' pages under `/demo/`. Astro's preview
server doesn't map `model3d/view` to `model3d/view.html` the way GitHub Pages does, so View in
3D stays blank there.

The manual's screenshots come from that demo, never from a real player:
`uv run --extra render python site/scripts/screenshots.py <address of the built site>` writes
`docs/images/*.webp` and the link preview `docs/images/social.png`; commit them.

`.github/workflows/pages.yml` builds the site on every push to `main` and deploys it to GitHub
Pages once the repository is public; before that, and on pull requests, the build is a
`site-preview` artifact.

## Made-up data only

No test, fixture, doc or screenshot holds a real account, character, guild,
host or address.

- **Test fixtures** come from `tools/fixtures/generate.py` (seeded, byte for
  byte reproducible; its header lists what it writes). After changing it, or
  the code that derives the planner's inputs: `uv run python
  tools/fixtures/generate.py`, read the diff, commit both. CI runs it with
  `--check`.
- **The demo** is `dev/seed.py`: five made-up characters with a DEMO DATA
  banner. Its header has the commands; the compose kit's header has the
  two-line version.
- **The scan** (`tests/test_public_scan.py`) checks the shapes in git (no
  e-mail address, no private IP, no token-looking string) and, when a
  denylist file exists, every name in it. The denylist is never committed:
  one term per line in `~/.config/wow-stats-public/denylist.txt`, or the
  file `WOW_STATS_DENYLIST` names. Put your own names, characters, guild,
  domains and hosts in it.

## CI in a fork

`.github/workflows/ci.yml` runs on GitHub-hosted runners with no secret: the
tests on Linux, the Windows installer test, the demo seed through
PowerShell's pipe (5.1 and 7), both images with smoke tests (read-only
root, uid 10001), and the `audit` job (below). A fork gets all of it as is.

Three more workflows run only while the repository is public, because a
private repository needs GitHub Advanced Security for them. Elsewhere they
skip, which counts as passed for a required check:

| Workflow | What |
|---|---|
| `codeql.yml` | CodeQL on the Python and the JavaScript, results in the Security tab |
| `dependency-review.yml` | the dependencies a pull request adds or bumps: known vulnerabilities (moderate and up) and licenses that can't ship with GPL-3.0-only |
| `scorecard.yml` | OpenSSF Scorecard, published to api.scorecard.dev and the Security tab |

## Dependencies and supply chain

- **Updates**: Dependabot (`.github/dependabot.yml`), weekly on Monday:
  one grouped pull request per ecosystem (uv, GitHub Actions, the
  Dockerfile, the compose kit, the videos' npm) for minor and patch bumps,
  one per major. A release has to be 7 days old before it's proposed.
  Security updates come as soon as an advisory lands.
- **Pins**: actions by commit SHA with the tag in a comment, base images by
  tag and digest on literal `FROM` lines (Dependabot doesn't follow
  `ARG`s), Python packages by `uv.lock` with hashes. The Python minor
  (3.15) moves by hand, not with the weekly bumps.
- **Moved by hand**: `POLESTAR_TAG` in `route-reference.yml` (kb-refresh's
  watcher reports new Polestar releases), the renderer's Debian snapshot
  date, and the Polestar Recorder version and checksum in the shipper.
- **The `audit` job** (CI, every push and pull request):
  - `actionlint` on the workflows, with shellcheck on their scripts;
  - `uv lock --check`: `uv.lock` in step with `pyproject.toml`;
  - `tools/audit_deps.py`: pip-audit on every locked package, every extra
    and group. A known vulnerability fails the job;
  - gitleaks on the tree and every commit (`.gitleaks.toml`: the default
    rules plus two proven false positives).

  The same, locally:
  ```sh
  actionlint
  uv lock --check
  uv run --frozen --only-group audit python tools/audit_deps.py
  gitleaks git --redact --config .gitleaks.toml .
  ```
- **A vulnerability that can't be fixed yet** (no release upstream, or the
  vulnerable path is never reached): add it to
  `.github/vulnerability-allowlist.toml` with the advisory id and a reason a
  reviewer can check. An entry without a reason fails the job. Remove it
  when the fix lands.

`route-reference.yml` reruns the route export when its inputs change, with
nothing to set up. `kb-refresh.yaml` needs a schedule and, for its model
pass, an Anthropic federation rule: [docs/kb.md](https://sam-dumont.github.io/wow-mcp/game-data/kb/), "Running the
refresh job in your own repository". Until then it runs only when you start
it by hand, and its model pass skips with a notice.

## Releasing

1. Bump `version` in `pyproject.toml`, `__version__` in `wowstats/__init__.py` and
   `VERSION` in `shipper/wow_stats.py` (a test keeps the three equal: every install's
   shipper updates itself to a higher `VERSION`), write the CHANGELOG entry (what
   changed for a player, then "Upgrading" with every changed variable, port,
   volume or route), merge.
2. Run the full checks above on that commit, browsers included.
3. Tag it `vX.Y.Z` and push the tag. `.github/workflows/release.yml` builds
   both images for linux/amd64 and linux/arm64, pushes
   `ghcr.io/<owner>/wow-mcp:X.Y.Z` and `ghcr.io/<owner>/wow-mcp-render:X.Y.Z`
   and prints each `tag@digest` in the run summary. The tag must match
   `pyproject.toml` or the run stops. Each platform builds on a runner of
   its own architecture (GitHub's `ubuntu-24.04-arm` for arm64, no
   emulation), and a merge job joins them into one index per image.

A pull request that changes the `Dockerfile`, `.dockerignore` or
`release.yml` runs the same workflow as a dry run: both platforms build,
merge in a registry on the runner and pass the same checks. Nothing is
pushed.

Each image carries BuildKit's SLSA provenance and an SPDX SBOM per
platform, and the run keeps the SBOMs as an artifact. From a public
repository the run also writes GitHub artifact attestations and a keyless
cosign signature (below). From a private one those steps skip: artifact
attestations need GitHub Enterprise Cloud there, and a signature would put
the private repository's name in Sigstore's public log.

The image names live in one place, the `env:` block at the top of
`release.yml`. The owner part comes from the repository, so a fork publishes
to its own namespace. The builds stamp the repository's URL in the
`org.opencontainers.image.source` label.

A package pushed from a private repository is private. Its visibility is
set by hand in the package settings, never by the workflow.

## Using a released image

Pin by digest: `ghcr.io/<owner>/wow-mcp:X.Y.Z@sha256:...`, from the release
run's summary.

While the package is private, every pull needs a token with
`read:packages` (a classic personal access token, or a GitHub App token
with that permission):

- **Docker / compose**: `docker login ghcr.io -u <user>` with the token as
  the password (from stdin, never on the command line). Then in
  `deploy/compose/.env`: `WOW_STATS_IMAGE=ghcr.io/<owner>/wow-mcp:X.Y.Z@sha256:...`,
  and `docker compose pull ui publish site && docker compose up -d`.
- **Kubernetes**: a `kubernetes.io/dockerconfigjson` Secret for `ghcr.io`
  with that token, named in each pod's `imagePullSecrets`. The variables,
  ports and mounts are in [docs/deploy.md](https://sam-dumont.github.io/wow-mcp/self-host/deploy/).

Without `WOW_STATS_IMAGE` the compose kit builds the image from the tree
(`docker compose up -d --build`), so a clone runs with no registry at all.

## Verifying an image

Releases from the public repository are attested and signed by
`release.yml` in that repository, on a `v*` tag. Replace `<owner>` with the
repository's owner and `X.Y.Z` with the release.

Build provenance (which workflow, commit and tag built it), with the
[GitHub CLI](https://cli.github.com/):

```sh
gh attestation verify oci://ghcr.io/<owner>/wow-mcp:X.Y.Z --repo <owner>/wow-mcp
gh attestation verify oci://ghcr.io/<owner>/wow-mcp-render:X.Y.Z --repo <owner>/wow-mcp
```

The SBOM attestations (one per platform), and the SBOM itself:

```sh
gh attestation verify oci://ghcr.io/<owner>/wow-mcp:X.Y.Z --repo <owner>/wow-mcp \
  --predicate-type https://spdx.dev/Document/v2.3
docker buildx imagetools inspect ghcr.io/<owner>/wow-mcp:X.Y.Z \
  --format '{{ json (index .SBOM "linux/amd64").SPDX }}' > wow-mcp-amd64.spdx.json
```

The cosign signature, tied to the release workflow at a tag:

```sh
cosign verify ghcr.io/<owner>/wow-mcp@sha256:<digest> \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github\.com/<owner>/wow-mcp/\.github/workflows/release\.yml@refs/tags/v'
```

Pin what you verified by digest (`ghcr.io/<owner>/wow-mcp:X.Y.Z@sha256:...`):
a tag can move, a digest can't.
