From 547d47d64d68e9039cb6f3fe586827bbe264aae8 Mon Sep 17 00:00:00 2001 From: Kamil Krzywda Date: Sun, 11 Oct 2026 08:08:04 +0000 Subject: [PATCH] Add Gitea Actions CI + switch to PR-based workflow - Add .gitea/workflows/ci.yml: typecheck -> lint -> unit -> build -> deterministic Playwright e2e against the dev webServer (LLM_STUB=1). No dind/docker/static IP. - package-lock.json is committed (reproducible `npm ci`); verified npm install is a no-op. - Add CHANGELOG.md, set version 0.1.0, add .env (gitignored) + .env.example placeholder. - Document the mandatory feature-branch -> PR -> CI -> auto-merge workflow in AGENTS.md + README.md (e2e now runs in CI on every PR). - Add Playwright html/json reporters (playwright-report/, test-results/e2e.json) for the CI E2E-results summary step and the failure artifact upload. --- .env.example | 5 ++ .gitea/workflows/ci.yml | 140 ++++++++++++++++++++++++++++++++++++++++ .gitignore | 1 + AGENTS.md | 13 +++- CHANGELOG.md | 11 ++++ README.md | 9 ++- playwright.config.ts | 7 ++ 7 files changed, 184 insertions(+), 2 deletions(-) create mode 100644 .env.example create mode 100644 .gitea/workflows/ci.yml create mode 100644 CHANGELOG.md diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..24ff92f --- /dev/null +++ b/.env.example @@ -0,0 +1,5 @@ +# Copy to `.env` and fill in real values. `.env` is gitignored; never commit secrets. + +# Gitea API token (used for PR / branch-protection automation via the Gitea REST API). +# Get one from: https://git.kkhost.pl/user/settings/applications +GITEA_TOKEN=gitea-api-token diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml new file mode 100644 index 0000000..699a381 --- /dev/null +++ b/.gitea/workflows/ci.yml @@ -0,0 +1,140 @@ +# CI for the History simulator. Mirrors the local verification list in AGENTS.md +# (typecheck → lint → unit → build) and then runs the deterministic Playwright e2e +# suite (LLM_STUB=1) against the app's OWN dev webServer (npm run dev) on the runner. +# No dind / docker-compose / static IP / NO_PROXY needed: history's e2e targets the dev +# webServer, not a Docker image (unlike flight/orb's image-based e2e). CI never deploys: +# production is updated manually on the host after a tag. +name: CI + +on: + push: + branches: [master] + pull_request: + branches: [master] + workflow_dispatch: + +jobs: + ci: + name: build + unit + e2e + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: 22 + + # Job-level dep cache via the runner's built-in cache server. continue-on-error: + # an unreachable/broken cache server must never break the run (sibling convention). + # Caches node_modules and npm's tarball store ($HOME/.npm); npm ci wipes + # node_modules, so the $HOME/.npm store is what actually makes a cache hit fast. + - name: Restore deps cache + uses: actions/cache@v4 + continue-on-error: true + with: + path: | + node_modules + $HOME/.npm + key: ${{ runner.os }}-deps-npm-${{ hashFiles('package-lock.json') }} + + # Retried: the runner's outbound network/DNS is flaky (transient EAI_AGAIN seen in CI). + # npm ci is fully reproducible from the committed package-lock.json. + - name: Install dependencies + run: | + set -u + ok=0 + for i in 1 2 3; do + if npm ci; then ok=1; break; fi + echo "::warning::dependency install attempt $i/3 failed (likely transient network) — retrying in 5s" >&2 + sleep 5 + done + [ "$ok" = "1" ] || { echo "::error::dependency install failed after 3 attempts" >&2; exit 1; } + + - name: Typecheck + run: npm run typecheck + + - name: Lint + run: npm run lint + + # Deterministic: the LLM client uses the stub transport (LLM_STUB=1), so no model + # or network is needed. vitest auto-appends its summary to $GITHUB_STEP_SUMMARY. + - name: Unit tests + run: npm test + + # Vite client build → dist/ + tsup server bundle → server/dist/. Verifies the + # production build path (docker build does the same thing inside the image). + - name: Build + run: npm run build + + # Browsers run locally in CI (no remote browser server, no dind). Binaries + # (~187 MiB) are cached across runs — the runner's uplink is flaky and + # cdn.playwright.dev downloads time out mid-transfer; once seeded, installs skip. + - name: Restore browser cache + uses: actions/cache@v4 + continue-on-error: true + with: + path: $HOME/.cache/ms-playwright + key: ${{ runner.os }}-pw-browsers-${{ hashFiles('package.json') }} + + # Retried: cdn.playwright.dev is flaky from this runner — Playwright's internal + # retry window is often not enough, but runs get through with a longer one. + # Progress accumulates across attempts: playwright skips already-installed browsers. + - name: Install browsers (local) + run: | + set -u + ok=0 + for i in 1 2 3 4 5 6; do + if npx playwright install --with-deps chromium; then ok=1; break; fi + echo "::warning::browser install attempt $i/6 failed (flaky cdn.playwright.dev) — retrying in 5s" >&2 + sleep 5 + done + [ "$ok" = "1" ] || { echo "::error::browser install failed after 6 attempts" >&2; exit 1; } + + # E2E: fully deterministic. The Playwright config boots its own dev webServer + # (npm run dev) with LLM_STUB=1 and DATA_DIR=data/e2e. VITE_PORT / HISTORY_API_PORT + # are set to free ports so that webServer won't collide with anything else on the + # runner (history's normal dev ports are 5173/4321). The config emits an HTML report + # (playwright-report/) and a JSON report (test-results/e2e.json) used below. + - name: E2E + env: + VITE_PORT: "5199" + HISTORY_API_PORT: "4399" + run: npm run e2e + + # Short machine-readable summary appended to the PR/job. Runs even on failure + # (always()) and never breaks the job (|| true). Parses Playwright's JSON report: + # stats.expected = passed, stats.unexpected = failed, stats.skipped = skipped. + - name: E2E results summary + if: always() + run: | + { + echo "## E2E results" + echo + if [ -f test-results/e2e.json ]; then + node -e ' + const fs = require("fs"); + const r = JSON.parse(fs.readFileSync("test-results/e2e.json", "utf8")); + const s = r.stats || {}; + console.log(`- **Passed:** ${s.expected ?? 0}`); + console.log(`- **Failed:** ${s.unexpected ?? 0}` + (s.flaky ? ` (flaky: ${s.flaky})` : "")); + console.log(`- **Skipped:** ${s.skipped ?? 0}`); + console.log(`- **Duration:** ${((s.duration ?? 0) / 1000).toFixed(1)}s`); + ' || echo "- could not parse test-results/e2e.json" + else + echo "- no test-results/e2e.json produced (e2e did not run)" + fi + } >> "$GITHUB_STEP_SUMMARY" || true + + # On failure, keep the HTML report + raw results for debugging. + - name: Upload Playwright report + if: failure() + uses: actions/upload-artifact@v4 + continue-on-error: true + with: + name: playwright-report + path: | + playwright-report/ + test-results/ + retention-days: 7 diff --git a/.gitignore b/.gitignore index 9eb6b26..1d4fe22 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,7 @@ server/dist/ *.log .env .env.* +!.env.example data/ *.sqlite *.sqlite3 diff --git a/AGENTS.md b/AGENTS.md index 6a047f6..f620f11 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,6 +11,15 @@ which returns a structured `TurnResult` (events + stat/relation/territory deltas validates, clamps, and applies to the world state. A MapLibre choropleth renders territorial ownership; the whole thing persists to SQLite and streams over SSE on a single port. +## Change process (mandatory) + +1. **Small, incremental, well-tested changes** — work is done one change at a time, in smaller parts; each part is tested before moving on. Connected tasks that touch the same area of code MAY be done together on one branch/PR with a single version bump (e.g. two tweaks to the same panel). +2. **Feature branch + PR** — every change lands on a feature branch off `master` (no direct pushes to `master`). Open a pull request against `master` on Gitea (`https://git.kkhost.pl`, repo `OpenCode/History`). +3. **Changelog entry** — every change is listed in `CHANGELOG.md` with a version, date and time (format: `## v — YYYY-MM-DD HH:MM`, then bullet points of what changed). +4. **Version bump** — the version is updated in `package.json`. +5. **CI must pass** — branch protection on `master` requires the CI status check to be green before merge. Merge via auto-merge (`POST /repos/OpenCode/History/pulls/{n}/merge` with body `{"do":"merge","merge_style":"merge","merge_when_checks_succeed":true}`) so the PR merges by itself once CI is green. **CI never deploys to production.** +6. **Tag + manual deploy after merge** — once merged, tag the version on `master` (e.g. `v0.1.0`). Production (`https://history.dev.kkhost.pl`) is updated manually afterwards on the host: `docker compose up -d --build`, then verify the site. + ## Stack - TypeScript everywhere, `strict: true` @@ -80,9 +89,11 @@ history/ | `npm test` | vitest unit tests in `server/` (19 tests) | | `npm run typecheck` | `tsc --noEmit` (strict) across src/server/shared/e2e/configs | | `npm run lint` | ESLint flat config | -| `npm run e2e` | Playwright, fully deterministic (`LLM_STUB=1`); overrides dev ports via `VITE_PORT`/`HISTORY_API_PORT` if set | +| `npm run e2e` | Playwright, fully deterministic (`LLM_STUB=1`); **runs in CI on every PR** (see below) | | `docker compose up -d --build` | prod image on :4321, routed via Traefik at `history.dev.kkhost.pl` | +**Local verification (before every PR):** `npm run typecheck` + `npm run lint` + `npm test` (unit) + `npm run build`. The full **e2e** suite (`npm run e2e`) is verified by **CI on every PR** (the Playwright config boots its own dev webServer with `LLM_STUB=1`) — locally you only need the four checks above; e2e is the CI source of truth. + ## Conventions - **The server is authoritative.** All world state lives in SQLite (`server/db.ts`). The client diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..a639dd3 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,11 @@ +# Changelog + +All notable changes to **History** are listed here, newest first. + +## v0.1.0 — 2026-10-11 08:02 + +- Added a Gitea Actions CI pipeline (`.gitea/workflows/ci.yml`: `typecheck → lint → unit → build → deterministic Playwright e2e`). E2e runs against the app's own dev webServer (`LLM_STUB=1`) — no dind/docker. +- Committed `package-lock.json` so CI uses a reproducible `npm ci`. +- Switched to the mandatory PR-based workflow: feature branch → PR to `master` → CI green → auto-merge → tag + manual deploy (documented in `AGENTS.md`). +- Versioned the repo at `0.1.0` (`package.json`) and added `CHANGELOG.md`, `.env` (gitignored) and `.env.example`. +- This change is the first one landed through the new PR process (dogfooding it). diff --git a/README.md b/README.md index 4b362e0..c82ca0d 100644 --- a/README.md +++ b/README.md @@ -79,7 +79,14 @@ docker compose up -d --build --force-recreate # after uncommenting LLM_STUB=1 i | `npm test` | vitest unit tests in `server/` (19) | | `npm run typecheck` | `tsc --noEmit` (strict) across the whole tree | | `npm run lint` | ESLint (flat config) | -| `npm run e2e` | Playwright, fully deterministic (`LLM_STUB=1`) | +| `npm run e2e` | Playwright, fully deterministic (`LLM_STUB=1`); runs in CI on every PR | + +## Change process + +Changes follow a mandatory PR-based workflow (full rules in [AGENTS.md](./AGENTS.md#change-process-mandatory)): +work on a feature branch off `master` (no direct pushes), add a `CHANGELOG.md` entry and bump the +`package.json` version, open a PR to `master`, and let **CI pass** (typecheck → lint → unit → build → e2e) +before auto-merging. After merge, tag the version and deploy manually (`docker compose up -d --build`). ## Design notes diff --git a/playwright.config.ts b/playwright.config.ts index 0a6f32e..699bd49 100644 --- a/playwright.config.ts +++ b/playwright.config.ts @@ -18,6 +18,13 @@ export default defineConfig({ baseURL: devUrl, headless: true, }, + // Reporters: list → console; html → playwright-report/ (uploaded by CI on failure); + // json → test-results/e2e.json (parsed by CI's "E2E results summary" step). + reporter: [ + ['list'], + ['html'], + ['json', { outputFile: 'test-results/e2e.json' }], + ], webServer: { command: 'npm run dev', url: devUrl, -- 2.54.0