diff --git a/Makefile b/Makefile index df3efe7d10..0d285eb22f 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,13 @@ -.PHONY: quota-report +.PHONY: quota-report dashboard-gen dashboard-gen-check quota-report: bash src/scripts/gh-quota-report.sh + +# Regenerate src/pkg/dashboard/static/index.html from the per-area sources in +# src/pkg/dashboard/static-src/ (see src/docs/dashboard-source-layout.md). +dashboard-gen: + cd src && go generate ./pkg/dashboard/webstatic/ + +# Fail if the committed index.html is stale relative to static-src/. +dashboard-gen-check: + cd src && go run ./pkg/dashboard/webstatic/gen -src pkg/dashboard/static-src -out pkg/dashboard/static/index.html -check diff --git a/changelog.d/changed-dashboard-index-generated.md b/changelog.d/changed-dashboard-index-generated.md new file mode 100644 index 0000000000..5bd0768b26 --- /dev/null +++ b/changelog.d/changed-dashboard-index-generated.md @@ -0,0 +1 @@ +- The spoke dashboard's `static/index.html` is now generated from per-area sources in `src/pkg/dashboard/static-src/` (CSS, JS and HTML split by dashboard area, concatenated byte-for-byte per `manifest.txt` by `make dashboard-gen`). Served bytes are unchanged; `TestIndexHTMLIsGenerated` fails when the artifact and its sources drift, so PRs touch the area they change instead of one 60k-line file and stop conflicting with each other. diff --git a/src/docs/dashboard-source-layout.md b/src/docs/dashboard-source-layout.md new file mode 100644 index 0000000000..9362398fe2 --- /dev/null +++ b/src/docs/dashboard-source-layout.md @@ -0,0 +1,145 @@ +# Dashboard source layout + +`src/pkg/dashboard/static/index.html` — the single document the spoke +dashboard serves — is a **generated artifact**. Its sources live in +`src/pkg/dashboard/static-src/`, one file per dashboard area, and a tiny +generator concatenates them, byte for byte, into the committed `index.html`. + +The rule, in one line: + +> **Edit `static-src/**`, run `make dashboard-gen`, commit both.** + +`TestIndexHTMLIsGenerated` (`pkg/dashboard/webstatic/indexgen_test.go`) +regenerates the document in memory and fails when the committed artifact +differs from its sources, so an edit made directly to `index.html` — or a +source edit without regeneration — is caught in CI, not in a review. + +## Why a generated artifact and not a build step + +`index.html` is embedded with `//go:embed static` (`server.go`), gzipped once +at startup, and its inline style sheet is hashed into the `Content-Security-Policy` +header. Dozens of tests read `../static/index.html` and assert on literal +ids, classes and markup; the node harnesses under `webstatic/testdata/` load JS +functions straight out of it. Keeping the artifact committed means none of that +changes: the served bytes are identical, CSP hashes are identical, and the +embed, the lint workflow and every existing test are untouched. What changes +is *where edits land* — a toast fix touches `css/alerts-toasts.css`, a tracker +fix touches `js/tracker-row.js`, and two such PRs no longer conflict on one +60 000-line file. + +The sources sit in a sibling directory (`static-src/`, not `static/src/`) on +purpose: `//go:embed static` embeds everything under `static/` recursively, so +sources placed inside it would be compiled into the binary and served. + +## Layout + +``` +src/pkg/dashboard/ +├── static/ +│ └── index.html ← GENERATED. Do not edit. +├── static-src/ +│ ├── manifest.txt ← ordered list of parts; blank lines and # comments ignored +│ ├── head.html ← …
… up to and including ……` tags, so every `.css` and `.js` part is pure CSS or JS that an +editor can lint on its own. Each part ends exactly where the next begins — at a +blank line or a section comment — so the document reads the same as before the +split. + +### Areas + +CSS (`css/`): `base` (tokens, reset, shared primitives), `sidebar`, `topbar`, +`agent-detail`, `agent-cards`, `auth`, `agent-state`, `tracker` (Hive activity +monitor), `agent-fields`, `governor`, `advisory-lifecycle`, `evidence`, +`throughput`, `repos`, `label-filter`, `overview`, `sparklines-indicators`, +`governor-matrix`, `cost`, `alerts-toasts`, `feedback-faq`, `config-dialog`, +`chat`, `nous`, `knowledge`, `sections-collapse`, `design-system`, +`responsive`, `recipes-utilities`, `welcome`, `review-campaigns`, `variables`. + +Body HTML (`html/`): `auth`, `root-notices`, `chat`, `dialogs`, `sidebar`, +`topbar`, `overview-governor`, `throughput-advisory`, `cost`, `repos`, +`acmm-approvals-audit`, `review-queue`, `nous-inception-knowledge-contributors`, +`debug-logs`, `agents`, `tracker`, `faq`. + +JS (`js/`): `boot`, `core`, `feedback`, `sections`, `layout`, `agent-detail`, +`sidebar`, `history-sparklines`, `cost-trend`, `stats`, `agent-now`, +`tracker-words`, `tracker-row`, `tracker-motion`, `tracker-filter`, +`tracker-actions`, `tracker-merged`, `tracker-sound`, `agent-cards`, `banners`, +`governor-view`, `repos`, `overview`, `label-filter`, `pinned-filters`, +`repos-render`, `budget`, `backends-tokens`, `cost`, `acmm-lifecycle`, +`throughput`, `evidence`, `approvals`, `nous`, `knowledge`, `vault-audit`, +`review-queue`, `contributors`, `refresh`, `inception`, `debug-logs`, +`tooltips-dialogs`, `plan-agent-controls`, `acmm`, `version`, `sse-bootstrap`, +`config-state`, `settings-search`, `config-dialog`, `config-tabs`, +`config-hub`, `config-agent`, `config-governor`, `config-watchdog-security`, +`config-features`, `config-sentinel`, `compliance`, `config-helpers`, +`linear-repos-save`, `chat`, `gh-auth`, `nps`, `welcome`, `shimmy-handlers`. + +Function groups were kept intact: a part begins at a section banner or the +blank line before a top-level function, never inside one. When a function +clearly belongs to another area than the file it sits in, move it — the +generator does not care about order inside a region as long as the manifest +order still yields a document where every definition precedes its first use. + +## Working with it + +```sh +make dashboard-gen # regenerate static/index.html from static-src/ +make dashboard-gen-check # fail if the committed index.html is stale +cd src && go test ./pkg/dashboard/webstatic/ -run 'TestIndex|TestConcatIndex' +``` + +`make dashboard-gen` runs `go generate ./pkg/dashboard/webstatic/`, whose +directive is in `indexgen.go`. + +**Adding an area.** Create the file under `css/`, `html/` or `js/`, add its +path to `manifest.txt` at the position where its bytes must appear (CSS inside +the ` + + + +