docs: REUSE.md introduced — reuse map (hub+website+scripts+manifests) + reuse_refs_check.py gate + consolidated cross-repo REPORT
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PSK5g6qYLknKj8u3QAFEr6
This commit is contained in:
@@ -4,114 +4,104 @@
|
||||
|
||||
---
|
||||
|
||||
# REPORT — TASK-D4: Felhom Hub re-skin (design system v2, final surface) → hub v0.30.0
|
||||
# REPORT — docs: REUSE.md introduced across all four felhom repos (consolidated)
|
||||
|
||||
**Date:** 2026-07-02 · **Deployed:** k3s felhom-system `deploy/hub` @ `felhom-hub:0.30.1` (0.30.0 + the badge no-wrap follow-up; rolled out)
|
||||
**Date:** 2026-07-03 · **Class:** docs-only (no code change, no version bumps, no builds, no deploys)
|
||||
**Deliverable:** a per-repo `REUSE.md` reuse map (canonical helpers / patterns / traps / seams /
|
||||
extension points / known duplication), code-verified at file+symbol, plus `scripts/reuse_refs_check.py`
|
||||
as the staleness gate, plus CLAUDE.md maintenance hooks.
|
||||
|
||||
## 1. Baselines
|
||||
## 1. Baselines used (all matched the task's expected hashes; trees clean, pulled fresh)
|
||||
|
||||
- felhom.eu `main` @ `43189e8` (D3 final) — matched; main had not moved.
|
||||
- felhom-controller @ `d0c70a7` — read-only woff2 source (byte-copied).
|
||||
|
||||
## 2. The enumerated OverallStatus set and its mapping
|
||||
|
||||
From source (server.go `handleDashboard`, configs.go `overallStatus`, hosts.go `hostStatusClass`):
|
||||
**ok, warn, down, pending, disabled, blocked** (+ `fail` accepted as a statusColor input, `stale`
|
||||
in the hosts domain). Complete mapping (exception-color principle):
|
||||
|
||||
| Status | Token | Reasoning |
|
||||
| Repo | `main` @ baseline | State |
|
||||
|---|---|---|
|
||||
| ok | `nominal` | operating normally — blue, not green |
|
||||
| warn | `warn` | degraded / stale report — amber |
|
||||
| stale (hosts) | `warn` | consistent with hostStatusClass's existing warn reuse |
|
||||
| down | `crit` | outage — red |
|
||||
| fail | `crit` | health=fail — red |
|
||||
| pending | `neutral` | a not-yet-provisioned customer is a NORMAL fleet state (Peti Debian stays quiet) |
|
||||
| disabled | `neutral` | deliberately paused — not a deviation |
|
||||
| blocked | `warn` | operator cut a customer off: intentional but attention-worthy — amber, not red (not an outage) |
|
||||
| unknown/"" | `neutral` | unknown values stay quiet |
|
||||
| felhom-controller | `d0c70a7da6f4060422a545cea2396f9df5f7d61f` | v0.98.3 |
|
||||
| felhom-agent | `0db09bf34fe2eff4b80ac77ed19afa18aef7675f` | v0.61.0 |
|
||||
| felhom.eu | `b0de6b34f61fef2e14807fba2c6176b888dc3327` | hub v0.30.1 |
|
||||
| app-catalog-felhom.eu | `bb81cd414afcb89e28ac60f405133f40195e6c43` | n/a |
|
||||
|
||||
A healthy fleet dashboard is blue/neutral only. Event severity counts remain filled amber/red
|
||||
badges (exceptions stay loud, per the design-system `.badge` addendum).
|
||||
## 2. Files created/modified per repo
|
||||
|
||||
## 3. Commits
|
||||
- **felhom-controller:** `REUSE.md` (new, 210 lines); `CLAUDE.md` (+2 hook lines); `CHANGELOG.md`
|
||||
(docs entry); `CONTEXT.md` (note); `REPORT.md` (overwritten).
|
||||
- **felhom-agent:** `REUSE.md` (new, 160 lines); `CLAUDE.md` (+2 hook lines); `CHANGELOG.md`;
|
||||
`CONTEXT.md`; `REPORT.md`.
|
||||
- **felhom.eu:** `REUSE.md` (new, 151 lines — hub + website + scripts + manifests);
|
||||
`scripts/reuse_refs_check.py` (new gate); `CLAUDE.md` (+2 hook lines); `hub/CHANGELOG.md` +
|
||||
`scripts/CHANGELOG.md` (docs entries); `CONTEXT.md` (new, minimal — repo had none); `REPORT.md`
|
||||
(this file).
|
||||
- **app-catalog-felhom.eu:** `REUSE.md` (new, 58 lines, light §2/§5 variant per spec); `CLAUDE.md`
|
||||
(new, minimal — repo had none; full CLAUDE.md is a separate task); `CHANGELOG.md`; `CONTEXT.md`
|
||||
(new, minimal); `REPORT.md`.
|
||||
|
||||
| Commit | Content |
|
||||
## 3. Commits pushed to `main` (one per repo)
|
||||
|
||||
| Repo | Commit |
|
||||
|---|---|
|
||||
| `bc8d54d` | Part 1: fonts embedded + `/static/fonts/` route, 12-symbol sprite partial on all 9 pages, statusColor semantic remap, statusIcon retired, truth-table + parse tests |
|
||||
| `c136308` | Part 2: style.css v2 (tokens, tag-style status badges + CSS dots, hairline rows, row tints warn/down only), two-tone H1 ×8, charts retinted, inline hexes swept, login retinted |
|
||||
| `fc79a3a` | manifests: hub image 0.30.0 (GitOps truth kept in sync with the set-image deploy — repo convention; auto-sync is off) |
|
||||
| (docs) | Part 3: hub/CHANGELOG v0.30.0 + this REPORT |
|
||||
| felhom-controller | `eda33400da0fd6a3b80271c44df24a177f7a444a` |
|
||||
| felhom-agent | `2a024b603973e79a0c84d6847a7cde0898091c61` |
|
||||
| app-catalog-felhom.eu | `c5a3d1b15b71103a3d1da217f1ff5a834857375c` |
|
||||
| felhom.eu | the commit carrying this REPORT (HEAD of `main` after this push) |
|
||||
|
||||
## 4. Tests + red-proof
|
||||
## 4. Per-repo sweep counts (evidence of depth)
|
||||
|
||||
`go build ./... && go vet ./... && go test ./...` green after each commit (hub/).
|
||||
New tests (the hub web package previously had none for funcmap/templates):
|
||||
- `TestStatusColorTruthTable` — full enumerated set. **Red-proof:** against the stashed pre-change
|
||||
implementation it failed exactly as required (`statusColor("ok") = "#4ade80", want "nominal"`,
|
||||
warn→`#facc15`, stale→`#94a3b8`, down→`#f87171`). Restored → pass.
|
||||
- `TestTemplatesParseWithFuncmap` — all 9 templates parse with the production funcmap.
|
||||
| Repo | funcs scanned (non-test) | §1 rows | §3 traps | §6 duplications |
|
||||
|---|---|---|---|---|
|
||||
| felhom-controller | 1174 | 62 | 8 | 12 |
|
||||
| felhom-agent | 702 | 48 | 10 | 7 |
|
||||
| felhom.eu (hub Go) | 297 | 34 | 8 | 5 |
|
||||
| app-catalog | 53 apps scanned | 0 (by design) | 3 | 6 |
|
||||
|
||||
## 5. Grep gates (before → after, hub/internal/web non-test files)
|
||||
Trap sweeps ran mechanically per §Method (`--delete`, `wipefs`, `mkfs`, `os.RemoveAll`, `rm -rf`,
|
||||
`sfdisk`, `dd `, `Format`, `Wipe`) in every repo; each hit classified as guarded-canonical (§1, guard
|
||||
named) or §3 trap. Known traps (rsyncMirror `--delete`, gokapi entrypoint, AGENT-001 TOCTOU shape,
|
||||
allowedEventTypes 400) were independently rediscovered from code.
|
||||
|
||||
`#0f172a` 2→0 · `#1e293b` 2→0 · `#334155` 3→0 · `#60a5fa` 3→0 · `#4ade80` 5→0 · `#facc15` 1→0 ·
|
||||
`#f87171` 7→0 · `#94a3b8` 10→0 · `#64748b` 3→0 · `#475569` 3→0 · `#e2e8f0` 2→0 · `#0088cc`
|
||||
(login) →0 · `statusIcon` template usage 2→0 · inline `style="color: {{statusColor}}"` 2→0 ·
|
||||
box-shadow 0→0 (never had any).
|
||||
|
||||
## 6. API freeze proof
|
||||
|
||||
`git diff 43189e8..HEAD --stat` touches ONLY `hub/internal/web/**` (+ hub/CHANGELOG.md,
|
||||
manifests/hub.yaml one-line tag, REPORT.md). Nothing under `hub/internal/api/`,
|
||||
`hub/internal/store/`, or any ingestion/notify/monitor package.
|
||||
|
||||
## 7. Deployment + Scenario E (live E2E)
|
||||
## 5. reuse_refs_check.py output (final, all four repos)
|
||||
|
||||
```
|
||||
deployment "hub" successfully rolled out
|
||||
hub-757d8dcb46-pq84j 1/1 Running 0 13s
|
||||
[INFO] Listening on :8080 (felhom-hub 0.30.0)
|
||||
OK [felhom-controller]: 65 cited paths, all exist
|
||||
OK [felhom-agent]: 57 cited paths, all exist
|
||||
OK [felhom.eu]: 30 cited paths, all exist
|
||||
OK [app-catalog-felhom.eu]: 10 cited paths, all exist
|
||||
```
|
||||
Scenario E **passed**: hub deployed 22:40 CEST; the demo controller's next 15-minute cycle at
|
||||
`2026/07/02 20:45:19 UTC (22:45 CEST)` logged `Hub report pushed successfully (5423 bytes)` —
|
||||
an HTTP 200 from the freshly deployed hub's `/api/v1/report`, proving ingestion end-to-end after
|
||||
the re-skin (the controller only logs success on a 2xx). The dashboard LAST SEEN visual
|
||||
confirmation joins the authenticated Chrome pass (§8).
|
||||
|
||||
## 8. Chrome checks (authenticated pass — operator logged in)
|
||||
(The gate earned its keep during authoring: it caught the controller map citing
|
||||
`scripts/{template_id_gate,emoji_gate}.py` — the real location is `controller/scripts/` — fixed
|
||||
before commit.)
|
||||
|
||||
- **Dashboard (Scenario A/B):** two-tone "Felhom Hub", navy tokens, hairline rows. DOM-asserted:
|
||||
**0 green** and **0 red** elements on the healthy fleet; OK = blue outline tag + dot
|
||||
(`rgb(46,168,245)`); PENDING (Peti Debian) = quiet neutral tag with hollow dot; 0 radii beyond
|
||||
0/2px/50%. (First load showed the OLD skin from the browser's 1-hour /style.css cache — a hard
|
||||
reload fixed it; noted in Observations.)
|
||||
- **Fonts (Scenario C):** `document.fonts.check` true for both faces; woff2 served from
|
||||
`/static/fonts/`; **0 external requests**; "Demo Ügyfél" renders in Plus Jakarta Sans
|
||||
(screenshots — dashboard + customer page H1).
|
||||
- **Charts (Scenario D):** app_detail (nextcloud) memory trend — avg `#2EA8F5` filled, peak
|
||||
`#8E7CE8` dashed, catalog-limit `#E0A93E` dashed; clearly distinguishable (screenshot).
|
||||
Severity `warn` chips filled amber in Known Issues (exceptions loud).
|
||||
- **Scenario E visual:** dashboard LAST SEEN "4 min ago" + Controller 0.98.3 in the version
|
||||
column — the post-deploy report cycle rendered.
|
||||
- Customers/customer_unified, Apps, Hosts (blue ONLINE tag, neutral NO REPORT), Configuration
|
||||
(rendered read-only, nothing submitted; the artifact manifest shows agent 0.60.0 / golden
|
||||
0.85.1 selected — unchanged) all render v2.
|
||||
- **v0.30.1 follow-up:** the pass caught multi-word badges (PENDING / NO REPORT) wrapping between
|
||||
the CSS dot and label in narrow columns — fixed with `white-space: nowrap` on `.status-badge`,
|
||||
built + deployed (manifest bumped).
|
||||
## 6. Observations — doc↔code drift & findings (recorded, NOT acted on)
|
||||
|
||||
## 9. NOT live-validated
|
||||
**Worth operator attention:**
|
||||
- **hub severity-coercion gotcha (NEW finding):** the remembered "dispatcher drops critical" issue is
|
||||
FIXED in code (`severityNotifies` routes warning/error/critical since v0.24.0), **but**
|
||||
`handleEvent` (hub/internal/api/handler.go) coerces any severity outside {info,warning,error} —
|
||||
including `"critical"` — to `"info"` at ingest, so a controller-POSTed critical event never
|
||||
notifies. Hub-internal events bypass this. Recorded in felhom.eu REUSE.md §3.
|
||||
- **Committed secrets:** `manifests/felhom.secret.yaml` still carries inline `stringData`
|
||||
credentials (healthchecks superuser pw + Django secret — not deployed; umami APP_SECRET +
|
||||
POSTGRES_PASSWORD — deployed), unlike the de-gitted Resend key. Recorded as a §3 trap; rotation/
|
||||
de-git is an operator follow-up.
|
||||
|
||||
- warn/crit fleet states (no customer is currently degraded) — truth-table-tested only.
|
||||
- The Configuration page was NOT submitted/altered (per spec §12).
|
||||
**Stale docs (each a separate refresh task):**
|
||||
- `felhom-agent/CLAUDE.md` says "Current: v0.31.0" and omits ~8 live packages (localapi, signedjobs,
|
||||
escrow, capability, guesthook, lanresolver, desired, provision).
|
||||
- `felhom.eu/CLAUDE.md` "Hub — current state (v0.7.x)" is ~23 minor versions stale (live 0.30.1).
|
||||
- `felhom-controller/CLAUDE.md` layout lists ~7 of ~30 internal packages; bare-metal deploy steps
|
||||
superseded (already flagged in-file).
|
||||
- app-catalog `README.md`: phantom `filebrowser/` template, missing `recipe-importer/`, field-type
|
||||
table omits `subdomain`/`secret_input`, smtp_mapping list undercounts (2 listed, 6 real).
|
||||
|
||||
## 10. Observations (not acted on)
|
||||
**Duplication highlights (full lists in each REUSE.md §6):** controller atomic-write ×4 (+1 inline,
|
||||
two with deliberate non-atomic bind-mount fallback), dir-size ×6, JSON writers ×5/3 envelopes;
|
||||
agent lsblk parsers ×2, atomic JSON store ×3, run() helper ×4, plus the acknowledged
|
||||
antiRetarget↔WipeExecutor mirror; hub Resend sender ×2 + Hungarian formatter ×2 (frozen legacy
|
||||
path) and semver-compare ×2 with different failure semantics; agent dead config knobs
|
||||
`Binaries.MkfsExt4/MkfsXfs` (never executed — wrapper paths are hardcoded).
|
||||
|
||||
1. The hub login page is inline HTML in server.go (two copies, error + plain) — a template would
|
||||
be cleaner; retinted only.
|
||||
2. customer_unified.html carries a small per-page `<style>` block (toggle styles) — tokens updated
|
||||
in place; consolidation into style.css is a candidate for a later pass.
|
||||
3. `memoryColor`/`accuracyClass` (mem-ok/warn/danger) already returned classes; their CSS is now
|
||||
v2 but the class names keep their legacy spelling (grep-safe rename candidate).
|
||||
4. Session store is in-memory — every deploy logs the operator out; fine for a single-operator
|
||||
tool, noted for the future.
|
||||
## 7. Maintenance hooks now active
|
||||
|
||||
Every repo's CLAUDE.md: "See `REUSE.md` before writing new code" + "update REUSE.md in the SAME
|
||||
commit that adds/changes/deprecates a shared helper or pattern". Staleness gate:
|
||||
`python scripts/reuse_refs_check.py <repo-root> [...]` (run from felhom.eu). Reviewer-side: symbols
|
||||
spot-verified at file:line (line numbers in the maps are landmarks only).
|
||||
|
||||
Reference in New Issue
Block a user