diff --git a/BACKLOG-kuma.md b/BACKLOG-kuma.md new file mode 100644 index 0000000..e15bbfa --- /dev/null +++ b/BACKLOG-kuma.md @@ -0,0 +1,7 @@ +# BACKLOG — phase `kuma` (uptime-kuma create-a-monitor functional test) + +## Build backlog +(Builder-owned — read only for Adversary) + +## Adversary findings +(Adversary-owned — no items yet; populated as issues are found) diff --git a/REVIEW-kuma.md b/REVIEW-kuma.md new file mode 100644 index 0000000..223a76f --- /dev/null +++ b/REVIEW-kuma.md @@ -0,0 +1,50 @@ +# REVIEW — phase `kuma` (uptime-kuma create-a-monitor functional test) + +Adversary verdict log. Append-only. SSOT: `cc-ci-plan/plan-phase-kuma-monitor.md`. + +## Phase orientation (2026-06-11T18:03Z) + +Builder clone: `/srv/cc-ci/cc-ci`; Adversary clone: `/srv/cc-ci/cc-ci-adv`. +Phase goal: add functional test that completes uptime-kuma's first-run setup wizard and exercises +its core function — create a monitor, see it probe a target, assert UP + real probe timestamp. +Negative test (monitor → dead target → DOWN) required if it fits the runtime budget. + +Two gates: +- **M1** — test implemented + green locally; approach justified; bounded waits; real assertions +- **M2** — drone-path green (≥2 consecutive runs); flake check; DEFERRED closed + +Pre-phase independent research notes: +- uptime-kuma uses Socket.IO for ALL management operations (setup wizard, login, monitor CRUD) +- Existing tests: Socket.IO handshake (EIO v4), SPA branding, health check — NONE exercise wizard/monitor +- Two viable approaches per plan: (a) python-socketio client speaking events; (b) Playwright UI +- Key verification concerns for M1: + - Probe reality: must confirm a *real* HTTP check occurred (timestamp advance + status from + uptime-kuma's state, not echo of config) + - Secret safety: generated admin creds must not appear in logs or test output + - Budget: target ≤90s added to functional tier; must use bounded poll not sleep + - Negative teeth: dead-target monitor must go DOWN (proves probe isn't stub) — required unless + runtime budget forces explicit justification +- Existing `tests/uptime-kuma/functional/` dir has 3 files: health_check, socketio_handshake, + spa_branding — all pass in CI (build #91 was green for uptime-kuma level 5) +- Phase plan says new test goes in `tests/uptime-kuma/functional/` (or `playwright/` if option b) + +## Adversary pre-flight checks (2026-06-11T18:03Z) + +uptime-kuma Socket.IO event map (from source / prior investigation): +- Setup wizard: `setup` event with `{username, password}` → response `{ok: true}` +- Login: `login` event with `{username, password, token: ""}` → response `{ok: true, token: "..."}` +- Add monitor: `add` event with monitor config → response `{ok: true, monitorID: N}` +- Heartbeat list: `heartbeatList` event or `uptime` event to check recent probe status +- Monitor status: `getMonitorList` or heartbeat events contain `{status: 1}` (UP) or `{status: 0}` (DOWN) + +Adversary independent acceptance criteria (what I will cold-verify for M1): +1. Test file in correct location per plan (tests/uptime-kuma/functional/ or playwright/) +2. Setup wizard completed and login token obtained (not hardcoded) +3. Monitor created pointing at a harness-controlled URL (not a stub/no-op) +4. Wait loop is BOUNDED (deadline/max_wait, not open-ended sleep) +5. Assertion is on ACTUAL probe data: at minimum one heartbeat with status=1 + timestamp > deploy time +6. Admin credentials NOT printed/logged in test output +7. Negative test included OR explicit runtime-budget justification in DECISIONS.md +8. Runtime ≤ ~90s added (measure from CI timing) + +Builder has not yet started (no STATUS-kuma.md, no kuma commits). Waiting for M1 claim.