Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
@@ -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
1 change: 1 addition & 0 deletions changelog.d/changed-dashboard-index-generated.md
Original file line number Diff line number Diff line change
@@ -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.
145 changes: 145 additions & 0 deletions src/docs/dashboard-source-layout.md
Original file line number Diff line number Diff line change
@@ -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 ← <!DOCTYPE> … <head> … up to and including <style>
│ ├── css/<area>.css ← inline style sheet, one file per area
│ ├── glue/*.html ← the wrapper tags between regions (</style>…<body>…<script> etc.)
│ ├── js/boot.js ← the small boot script that runs before the body
│ ├── html/<area>.html ← body templates, one file per section
│ └── js/<area>.js ← the main script, one file per function group
└── webstatic/
├── indexgen.go ← ParseIndexManifest / ConcatIndex + the go:generate directive
├── indexgen_test.go ← TestIndexHTMLIsGenerated and manifest hygiene tests
└── gen/concat.go ← `go run ./gen -src ../static-src -out ../static/index.html [-check]`
```

The generator is a pure concatenation: no separators, no rewriting, no
reformatting. The `glue/` files hold the `</style>`, `<body>`, `<script>` and
`</script>` 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 `<style>` region, templates inside `<body>`, functions inside the main
script), regenerate. `TestIndexManifestEveryFileListedAndUsed` fails if a file
exists under `static-src/` but is not in the manifest, or vice versa.

**Reviewing.** Review the diff to `static-src/**`; the `index.html` hunk is the
same change again and can be collapsed. If a PR changes `index.html` without
a matching change under `static-src/`, it edited the artifact — ask for the
sources.

## Merge conflicts

Because the artifact is regenerated, conflicts in `static/index.html` are never
resolved by hand:

1. Take the base branch's copy: `git checkout --theirs src/pkg/dashboard/static/index.html`
(during `git rebase`, "theirs" is the branch being rebased onto).
2. Resolve any real conflicts under `static-src/**` normally — they are small
and per area.
3. `make dashboard-gen`, then `git diff --stat src/pkg/dashboard/static/index.html`
should show only your intended change on top of the base.
4. `make dashboard-gen-check` and `git add` both.

If the base branch changed `index.html` directly (an edit that bypassed the
sources), step 3 shows the drift: move that delta into the right part file and
regenerate until the check passes.

No `.gitattributes` merge driver (`merge=union` or similar) is used for the
artifact: a union merge of a 60 000-line document silently interleaves
unrelated hunks and would produce an `index.html` that no longer matches its
sources, which `TestIndexHTMLIsGenerated` would then reject anyway. Regenerating
is both simpler and always correct.

## Related

- [Spoke dashboard](dashboard.md) — how the dashboard behaves and is built.
- [Dashboard design system](dashboard-design-system.md) — tokens and component variants the CSS parts use.
- [Dashboard sections explained](dashboard-sections.md) — operator help per section.
4 changes: 3 additions & 1 deletion src/docs/dashboard.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
# Spoke dashboard

The spoke dashboard is the operator UI served from
`src/pkg/dashboard/static/index.html`. For the behavior behind the labels the repository cards show or mutate, see [Hive Labels and Control Signals](labels-and-control-signals.md). Its FAQ panel (`#faq-section` /
`src/pkg/dashboard/static/index.html`. That file is **generated**: edit the
per-area sources under `src/pkg/dashboard/static-src/` and run `make
dashboard-gen` (see [Dashboard source layout](dashboard-source-layout.md)). For the behavior behind the labels the repository cards show or mutate, see [Hive Labels and Control Signals](labels-and-control-signals.md). Its FAQ panel (`#faq-section` /
`#faq-panel`) is intentionally static HTML: it is not ACMM-gated, does not
fetch data, and is visible to confused L1/L2 users before they understand the
rest of the UI. Its only script is a client-side filter box (`faqFilter`) that
Expand Down
1 change: 1 addition & 0 deletions src/docs/documentation-map.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@ Documentation for the current Hive line (branch `v5`; the code and docs live und
- [Dashboard sections explained](dashboard-sections.md) — plain-language operator help for every dashboard section: what it shows, how its numbers are worked out, what to do about them, when it appears, and which settings change it. The **?** mark on each section title opens its entry.
- [Dashboard settings explained](settings.md) — one entry per Settings tab: what it controls and which guide explains it. The **?** mark next to each setting opens its guide or this page.
- [Dashboard feedback](feedback.md) — reporting bugs and requesting features from the spoke dashboard, including diagnostics, screenshot handling, hub relay, user-auth, and fallback issue paths.
- [Dashboard source layout](dashboard-source-layout.md) — `static/index.html` is generated from per-area CSS/JS/HTML sources in `static-src/` via `make dashboard-gen`; how to edit, add an area, and resolve merge conflicts.
- [Dashboard design system](dashboard-design-system.md) — shared token catalogue, component variants, migration rules, ratchet plan, and #8536 theme override contract for spoke, contributor, and hub dashboard surfaces.
- [Dashboard glossary and sidebar IA](dashboard-glossary.md) — the operator-facing names used by the dashboard and the ADR-0018 sidebar information architecture.
- [The `auto-update` Compose profile](auto-update-profile.md) — what unattended Watchtower updates cost you, what the Docker socket proxy does and does **not** fix, and why Kubernetes should not use this profile at all.
Expand Down
Loading
Loading