blocked 4

docs/modules/devops/console-ci-contract.md

@@ -0,0 +1,102 @@
+# Console CI Contract (DEVOPS-CONSOLE-23-001)
+
+## Scope
+Define a deterministic, offline-friendly CI pipeline for the Console web app covering lint, type-check, unit, Storybook a11y, Playwright smoke, Lighthouse perf/a11y, and artifact retention.
+
+## Stages & Gates
+1. **Setup**
+   - Node 20.x, pnpm 9.x from cached tarball (`tools/cache/node20.tgz`, `tools/cache/pnpm-9.tgz`).
+   - Restore `node_modules` from `.pnpm-store` cache key `console-${{ hashFiles('pnpm-lock.yaml') }}`; fallback to offline tarball `local-npm-cache.tar.zst`.
+   - Export `PLAYWRIGHT_BROWSERS_PATH=./.playwright` and hydrate from `tools/cache/playwright-browsers.tar.zst`.
+2. **Lint/Format/Types** (fail-fast)
+   - `pnpm lint`
+   - `pnpm format:check`
+   - `pnpm typecheck`
+3. **Unit Tests**
+   - `pnpm test -- --runInBand --reporter=junit --outputFile=.artifacts/junit.xml`
+   - Collect coverage to `.artifacts/coverage` (lcov + summary).
+4. **Storybook a11y**
+   - `pnpm storybook:build` (static export)
+   - `pnpm storybook:a11y --ci --output .artifacts/storybook-a11y.json`
+5. **Playwright Smoke**
+   - `pnpm playwright test --config=playwright.config.ci.ts --reporter=list,junit=.artifacts/playwright.xml`
+   - Upload `playwright-report/` and `.artifacts/playwright.xml`.
+6. **Lighthouse (CI mode)**
+   - Serve built app with `pnpm serve --port 4173` and run `pnpm lhci autorun --config=lighthouserc.ci.js --upload.target=filesystem --upload.outputDir=.artifacts/lhci`
+   - Enforce budgets: performance >= 0.80, accessibility >= 0.90, best-practices >= 0.90, seo >= 0.85.
+7. **SBOM/Provenance**
+   - `pnpm exec syft packages dir:dist --output=spdx-json=.artifacts/console.spdx.json`
+   - Attach `.artifacts/console.spdx.json` and provenance attestation from release job.
+
+## Determinism & Offline
+- No network fetches after cache hydrate; fail if `pnpm install` hits the network (set `PNPM_FETCH_RETRIES=0`, `PNPM_OFFLINE=1`).
+- All artifacts written under `.artifacts/` and uploaded as CI artifacts.
+- Timestamps normalized via `SOURCE_DATE_EPOCH=${{ github.run_id }}` for reproducible Storybook/LH builds.
+
+## Inputs/Secrets
+- Required only for Playwright auth flows: `CONSOLE_E2E_USER`, `CONSOLE_E2E_PASS` (scoped to non-prod tenant). Pipeline must soft-skip auth tests when unset.
+- No signing keys required in CI; release handles signing separately.
+
+## Outputs
+- `.artifacts/junit.xml` (unit)
+- `.artifacts/playwright.xml`, `playwright-report/`
+- `.artifacts/storybook-a11y.json`
+- `.artifacts/lhci/` (Lighthouse reports)
+- `.artifacts/coverage/`
+- `.artifacts/console.spdx.json`
+
+## Example Gitea workflow snippet
+```yaml
+- name: Console CI (DEVOPS-CONSOLE-23-001)
+  uses: actions/setup-node@v4
+  with:
+    node-version: '20'
+
+- name: Prep pnpm
+  run: |
+    corepack enable
+    corepack prepare pnpm@9 --activate
+
+- name: Cache pnpm store
+  uses: actions/cache@v4
+  with:
+    path: |
+      ~/.pnpm-store
+      ./node_modules
+    key: console-${{ hashFiles('pnpm-lock.yaml') }}
+
+- name: Install (offline)
+  env:
+    PNPM_FETCH_RETRIES: 0
+    PNPM_OFFLINE: 1
+  run: pnpm install --frozen-lockfile
+
+- name: Lint/Types
+  run: pnpm lint && pnpm format:check && pnpm typecheck
+
+- name: Unit
+  run: pnpm test -- --runInBand --reporter=junit --outputFile=.artifacts/junit.xml
+
+- name: Storybook a11y
+  run: pnpm storybook:build && pnpm storybook:a11y --ci --output .artifacts/storybook-a11y.json
+
+- name: Playwright
+  run: pnpm playwright test --config=playwright.config.ci.ts --reporter=list,junit=.artifacts/playwright.xml
+
+- name: Lighthouse
+  run: pnpm serve --port 4173 & pnpm lhci autorun --config=lighthouserc.ci.js --upload.target=filesystem --upload.outputDir=.artifacts/lhci
+
+- name: SBOM
+  run: pnpm exec syft packages dir:dist --output=spdx-json=.artifacts/console.spdx.json
+
+- name: Upload artifacts
+  uses: actions/upload-artifact@v4
+  with:
+    name: console-ci-artifacts
+    path: .artifacts
+```
+
+## Acceptance to mark blocker cleared
+- Pipeline executes fully in a clean runner with network blocked after cache hydrate.
+- All artefacts uploaded and budgets enforced; failing budgets fail the job.
+- Soft-skip auth-dependent tests when secrets are absent, without failing the pipeline.