cc-ci/machine-docs/JOURNAL-3.md

Phase 3 — Beautiful YunoHost-style results — JOURNAL (Builder-private reasoning)

SSOT: /srv/cc-ci/cc-ci-plan/plan-phase3-results-ux.md. WHY lives here; WHAT/HOW/EXPECTED/WHERE → STATUS-3.

2026-05-31T05:41Z — Phase-3 bootstrap + orientation

Read plan-phase3-results-ux.md in full (SSOT) + plan.md §6.1/§7/§9. Oriented on the existing Phase-1/2 artifacts I'll extend:

• runner/run_recipe_ci.py: orchestrates deploy-once → per-tier (install/upgrade/backup/restore/custom), produces an in-memory results dict {tier: 'pass'|'fail'|'skip'} printed to Drone logs. No results.json, no level, no screenshot today. Also tracks deploy-count (DG4.1), deps/SSO readiness (sso_dep_unverified → F2-11), teardown errors.
• bridge/bridge.py: posts a text PR comment with the Drone run URL; watch_and_reflect edits it to ✅/❌ on completion. No image/badge/level.
• dashboard/dashboard.py: stdlib HTTP service (swarm OCI image, Nix-built) that polls the Drone API only and renders a latest-per-recipe table + a basic per-recipe SVG badge (Drone status, not level). Runs as a container with no host volume mounts — relevant for artifact hosting (U0.4).

Key Phase-3 mapping insight: the level ladder (§4.1) maps cleanly onto the existing per-tier results:

• L1 install-tier pass; L2 upgrade pass; L3 backup AND restore pass; L4 custom (functional) pass; L5 SSO/integration (requires_deps tests actually ran + passed — deps_ready and not sso_dep_unverified); L6 recipe-local tests pass (D4 — discovered repo-local overlay/custom).
• Gap-caps-level (YunoHost): level = highest rung L such that every rung ≤ L passed. A rung that is genuinely N/A (e.g. backup not BACKUP_CAPABLE, or no SSO/integration surface) must NOT block the climb but caps with a recorded reason ("L4 — no integration surface" etc.) for fairness (§4.1 L5).
• Invariants surfaced as flags not levels: clean-teardown ✔ (no dep_teardown_error / DG4.1 ok), no-secret-leak ✔.

Adversary is live (REVIEW-3 @05:42Z), flagged the Phase-2-DONE prerequisite but is not treating it as a P3 blocker; operator kicked Phase 3 off manually. Proceeding.

Plan for U0 (foundation)

1. Pure level() function in a new runner/harness/level.py — unit-testable (no I/O), so I can prove "L4-pass" and "L2-cap" semantics cheaply and the Adversary can re-run the unit test cold. This is the load-bearing logic; everything else (card, badge, dashboard) just renders what it returns.
2. Capture per-test detail: run each tier's pytest with --junitxml to a run-scoped dir, parse the XML (stdlib xml.etree) into per-test rows {name, status, ms}. Aggregate per stage.
3. run_recipe_ci.py assembles results.json {recipe, version, pr, ref, run_id, stages[], level, level_cap_reason, flags} and writes it to the artifact dir — wrapped so a failure here NEVER changes the run's exit code (R7: cosmetics never block).
4. Artifact hosting (U0.4): runner writes to a host dir; dashboard bind-mounts it read-only to serve /runs/<id>/.... Decide details + record in DECISIONS.

2026-05-31T06:00Z — U0 complete + CLAIMED

Implemented U0.1–U0.4. Two real end-to-end runs on cc-ci confirm the translation layer (the binding risk the Adversary flagged at df54693) produces correct levels:

• custom-html-tiny (stateless, not backup-capable, ≥2 versions): install+upgrade pass, backup/ restore skip→N/A, no custom → level=2, cap "L3 backup/restore N/A". Proves gap-caps on real data.
• uptime-kuma (backup-capable, 3 functional tests, no deps): all five tiers pass → level=4, cap "L5 integration N/A". Proves a full clean climb with no SSO surface caps at L4. Both: deploy-count=1, clean_teardown=true, no_secret_leak=true, no orphan apps after.

Design notes / WHY:

• Chose STRICT monotonic capping (N/A caps like FAIL, distinct reason) over "N/A transparent for middle rungs" because the only worked example in §4.1 (no-integration → cap L4) is N/A-caps, and the cardinal guardrail is never-inflate. A stateless app that can't back up is honestly capped at L2 with a clear reason rather than shown as L4 — understating is safe, overstating is the cardinal FAIL.
• Kept the LEVEL driven by tier results + deps signals (precise, in-hand) rather than per-test marker plumbing; the per-test JUnit rows are for the card's DISPLAY (U2/U3). functional-vs-SSO split inside the custom tier is conservative: a custom FAIL fails the functional rung (caps L3) since we don't cheaply distinguish — never inflates.
• results.json assembly + the narrow leak-scan are wrapped in try/except in main() so any failure is logged but never changes overall (R7). The broader Adversary leak scan over published artifacts is the authority (U5).
• "version" field currently shows the recipe HEAD sha for a non-PR run (no VERSION env). Honest but ugly for the card; will prefer the tested version tag for display in U2.

Pre-existing repo lint RED (94 reformat + 36 ruff errors on origin/main, ruff 0.7.3 on CI devshell): not mine, flagged in STATUS for the operator. My new files are clean; run_recipe_ci.py left better than found (1 vs 4 errors). NOT reformatting 94 cross-phase files in Phase 3 (out of scope, huge noise).

2026-05-31T06:50Z — U2 render-path de-risked headless on cc-ci (parked at U0 gate)

While U0 is CLAIMED awaiting the Adversary (its cold runs adv-cht=L2 / adv-uk=L4 reproduced my claimed levels exactly @06:06/06:09 — swarm clean, no orphans), I kept the unblocked U2 render path moving. Ran a real headless Playwright PNG render on cc-ci of the pure harness.card renderers from two fixtures (a passing L4 uptime-kuma and a failing L0 custom-html-tiny):

cc-ci-run /tmp/smoke_card.py  (renders render_card_html → render_card_png + level_badge_svg)
pass: png size=119765  badge svg=342B
fail: png size=56353   badge svg=342B

Pulled both PNGs back and eyeballed them:

• pass card — level 4 in a yellow-green badge, full per-stage/per-test ✔ rows with PASS labels, inline sunflower renders, clean teardown + no secret leak flags green. Fonts clean (no tofu).
• fail card — level 0 in a red badge, install FAIL row, no screenshot placeholder shown.
• No inflation: the fail card honestly shows L0/red/FAIL; the card computes nothing, it reports the dict verbatim (cardinal guardrail upheld at the render layer).

This proves the U2 render path (HTML→PNG headless) works on the real cc-ci browser for both pass and fail runs — the U2 acceptance shape — before I wire it into run_recipe_ci.py (which I will not do until U0 PASSes, to avoid rework if the schema changes).

WIRING CONTRACT noted for U1/U2: the broken-image icon seen on the pass fixture is only because the fixture set screenshot:"screenshot.png" with no file present. The wiring MUST set data["screenshot"] truthy ONLY when the captured PNG actually exists (screenshot.capture returns None on failure) — then the card's show_shot gate falls back to the no screenshot placeholder, as the fail fixture already proves. No renderer change needed.

Not claiming U2 — still parked at the U0 gate per §6.1 (no advance past a gate without its PASS).

2026-05-31T07:00Z — U0 PASS; U1 (app screenshot) wired + CLAIMED

Adversary cold-verified U0 (REVIEW-3 @18d2bd1: R1 ladder, no inflation, R7-safe emission, no VETO). Carry-forwards it logged (hard-coded flags scanned at U5; served-URL hosting at U2/U4) are all expected and U1/U5-scoped, not U0 defects. Proceeded past U0 to U1.

WHY / design notes for U1:

• Capture point = right after deploy+health/readiness, before any tier runs. Earliest and cleanest "freshly installed, working app" state; if a later tier hangs/times out we already have the shot. The app stays up through all tiers until the single finally teardown, so the timing is free.
• Placed OUTSIDE the deploy try/except, guarded by if deploy_ok. Originally I put it inside the try right after deploy_ok=True; realised that if capture() ever raised it would be caught by the deploy except and wrongly flip deploy_ok=False (a cosmetic failing the deploy — exactly the R7 violation we forbid). Moved it out so a screenshot issue is structurally incapable of touching the verdict. capture() is also internally all-swallowing, so it's belt-and-suspenders.
• Secret-safety = landing page by default. The default shoots https://<domain>/ (login/landing), which shows form fields, never a generated secret. uptime-kuma's first-run page is "Create your admin account" with EMPTY fields — the user sets the password, nothing is displayed. Recipes whose landing page genuinely needs a post-login view opt in via a SCREENSHOT meta hook that owns the no-credentials-page guarantee; none needed yet. The harness NEVER auto-fills a setup wizard.
• results.json screenshot set only when a file was produced — so the U2 card's show_shot gate falls back to the "no screenshot" placeholder on failure (the fail fixture already proved this), and no broken-image icon appears in real runs.
• Degradation proven, not asserted: capture against an unreachable host returns None after the 45s deadline, writes no file, raises nothing (GRACEFUL_DEGRADATION=True). The deeper U5 R7 hardening (kill-the-renderer, broad leak scan over served images/comments) is still the Adversary's at U5.

Verification (all on cc-ci @5fa15d4):

• 38 phase-3 unit tests pass (incl. 4 test_screenshot pure-helper tests).
• uptime-kuma real install run → 30KB screenshot.png of the working UI (empty cred fields), results.json screenshot="screenshot.png", clean_teardown=true, no orphan service.
• unreachable-host capture → None, no file, no raise.

2026-05-31T07:03Z — U2 generation wired + card embeds the REAL screenshot (held, not claimed)

While parked at the U1 gate (claimed d7e812e, awaiting Adversary), kept unblocked U2 work in hand: wired card_mod into run_recipe_ci.py (afe5e51) so each run renders summary.html→summary.png + badge.svg into the run artifact dir, in a separate best-effort block AFTER results.json is written (so a card failure can't even look like a results.json failure; both swallow → never touch overall, R7). The card passes screenshot_rel=data.get("screenshot") so it embeds the real shot iff one exists.

Proved end-to-end against the REAL u1-uk-shot run data (results.json + screenshot.png): rendered summary.png (69KB) shows the YunoHost-style card — sunflower, "uptime-kuma" + version, an orange LEVEL 1 badge, "capped: L2 upgrade N/A", the install/test_serving ✔ PASS rows, clean-teardown + no-secret-leak flags, AND the real uptime-kuma "Create your admin account" screenshot embedded on the right. badge.svg 342B. This is the U2 acceptance shape with a real embedded app screenshot — the only U2 work left for its gate is SERVING these at stable URLs (U2.3, dashboard bind-mount) + showing a fail run. NOT claiming U2 — still gated behind U1's PASS.

2026-05-31T07:25Z — U2 (summary card + badge + serving) wired, deployed, CLAIMED

U1 PASSED (REVIEW-3 @74a6993). Built out U2 end-to-end and rolled the serving layer to production.

WHY / notable decisions:

• Card generation placed AFTER results.json write, in its own best-effort block (not the same try as results.json) so a card-render failure can't masquerade as a results.json failure; both swallow → never touch overall (R7).
• The card embeds the real screenshot via screenshot_rel=data["screenshot"] (only truthy when U1 captured a file), so the show_shot gate falls back to the "no screenshot" placeholder on a failed/absent capture — no broken-image icon in real runs.
• Serving = a new /runs/<id>/<file> route on the existing dashboard, NOT a new service. Strict allow-list of filenames + run_id regex + realpath-inside-runs-dir = three independent traversal guards (unit-proven locally with ../, .., /etc, non-whitelisted names; live-proven on cc-ci). Runs dir bind-mounted READ-ONLY (dashboard never writes run artifacts).
• DEPLOY: discovered #cc-ci now targets the cc-ci-hetzner migration host (cloud-init/dhcpcd hardware) — a nixos-rebuild build + nix store diff-closures vs the running system showed a big hardware delta, NOT just my dashboard change. So a full switch on the LIVE host would be wrong/ dangerous. Rolled the dashboard via the module reconcile only (docker load + docker stack deploy, image 466582e0aae0) — zero host-config impact, reversible. Recorded the mechanism + migration caveat in DECISIONS.md (Phase-3/U2) and warned the Adversary via ADVERSARY-INBOX. This is the cleanest in-scope way to make the change live without touching the migration-bound host config.
• Transient 404 during the roll: right after docker stack deploy, Traefik briefly returned its own 19B 404 for ALL paths (old task down, new task + Traefik re-sync window). Resolved on its own in ~25s → / 200, /runs/... 200. Noted so it isn't mistaken for a real outage.

Verification (live, post-roll):

• https://ci.commoninternet.net/runs/u1-uk-shot/summary.png → 200 image/png 69313B (card w/ real uptime-kuma screenshot embedded), …/screenshot.png 200 30858B, …/badge.svg 200, …/results.json 200. Traversal/non-whitelisted/nonexistent → 404 (9B = dashboard's own, guard fires).
• 8 test_card unit tests pass; deterministic fail-card render = L0/red/✘/no-screenshot (no inflation).
• /etc/cc-ci restored to main@fa56f6b (had temporarily checked it out to build).

2026-05-31T09:35Z — U3 live demo: discovered Drone DB reset (repo inactive), reactivated

Resuming U3 (bridge code already built+deployed @9a47aa2; deployed bridge image tag 6377f9571f3b == sha256(bridge.py), confirmed; dashboard do_HEAD live → A3-1 CLOSED by Adversary @8807240).

To run the U3 live demo (!testme → image-forward PR comment) I first validated the trigger path and hit a real blocker: the bridge log showed drone trigger failed 404, and GET /api/repos/ recipe-maintainers/cc-ci → 404. Diagnosis: the Drone admin token is valid (/api/user → 200, autonomic-bot admin=true) but the repo was inactive — Drone's DB was reset (the Hetzner migration; created/synced timestamps are all recent ~1780220000). In Phase 1 the repo was activated once via POST /api/repos/recipe-maintainers/cc-ci (JOURNAL.md:258); that activation is NOT Nix-declared (drone.nix only PATCHes the timeout, which itself assumes the repo is already active), so a DB reset silently de-registers it and the bridge can't trigger.

Action (in-scope reconfig of my own CI, reversible): POST /api/user/repos?async=false (sync, 200) → POST /api/repos/recipe-maintainers/cc-ci → active=true, config_path=.drone.yml, timeout=60. The trusted flag stays false — irrelevant for the type: exec pipeline (trusted only gates privileged docker pipelines). Validated by triggering a custom build directly (same params the bridge sends): build #1 → running within ~10s (exec runner picked it up). Watching it produce /runs/1/ artifacts.

NOTE for hardening backlog (U5/operator): repo activation should be folded into the drone reconcile so a future DB reset self-heals (POST /api/repos/<slug> before the timeout PATCH). Filing in BACKLOG-3.