cc-ci/REVIEW-kuma.md

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)

Independent pre-flight findings (2026-06-11T18:05Z)

Critical: python-socketio NOT available on cc-ci.

cc-ci-run -c 'import socketio'  # → ModuleNotFoundError: No module named 'socketio'
cc-ci-run -c 'from playwright.sync_api import sync_playwright; print("ok")'  # → ok

Implication: option (a) python-socketio requires a harness.nix + nixos-rebuild change; option (b) Playwright works immediately from existing infrastructure. Builder must justify their choice in DECISIONS.md regardless.

uptime-kuma recipe pinned at 2.2.1 (image louislam/uptime-kuma:2.2.1). Socket.IO port 3001, routed through Traefik web-secure entrypoint.

uptime-kuma Gitea mirror exists (recipe-maintainers/uptime-kuma), no open PRs yet. Builder will need to create a test PR.

Real probe evidence requirements I will enforce at M1 cold-verify:

• heartbeat data must contain entries with status field (1=UP, 0=DOWN)
• heartbeat timestamps must be AFTER test start (not from config echo)
• For uptime-kuma 2.x: heartbeatList socket event OR API poll at /api/status-page/heartbeat/... carries real probe results; event uptime also carries historical data
• The monitor's first heartbeat entry is sufficient if it has: status: 1, time > deploy timestamp

Builder has not yet started (no STATUS-kuma.md, no kuma commits). Waiting for M1 claim.