frontend: add npm workspace scaffold under frontend/

Phase 1 of the backend/frontend code split (#273). Additive — no
existing code is touched; the legacy hive-c0re/assets, hive-ag3nt/
assets and hive-fr0nt/assets trees stay in place until the Rust
cutover later in this branch.

Layout:
  frontend/package.json                       npm workspaces root
  frontend/packages/shared/                   @hive/shared
    src/{base,terminal}.css + terminal.js     (ES module)
    src/index.js                              re-exports terminal.js
  frontend/packages/dashboard/                @hive/dashboard
    src/{index.html, app.js, dashboard.css}   ported from hive-c0re/assets
    build.mjs                                 esbuild config → dist/
  frontend/packages/agent/                    @hive/agent
    src/{index,stats,screen}.html + agent.css
        + {app,stats}.js                      ported from hive-ag3nt/assets
    build.mjs                                 esbuild config → dist/

Changes vs the existing assets:
- terminal.js is an ES module exporting { create, linkify } instead
  of assigning to window.HiveTerminal. The dashboard / agent app.js
  files re-expose them on window so the IIFE bodies keep working
  unchanged through Phase 1; the global aliases can be dropped in a
  follow-up once the IIFEs are unwrapped.
- marked is imported from the marked@4.3.0 npm package (replacing
  the vendored hive-fr0nt/assets/marked.umd.js bundle).
- chart.js is imported from chart.js@4.4.4 (replacing the jsDelivr
  CDN script tag on the per-agent stats page — page now works
  offline / on operator machines without internet egress).
- dashboard.css and agent.css both gain @import lines at the top
  that pull base.css + terminal.css from @hive/shared, replacing
  the runtime string concatenation in serve_css.
- index.html / stats.html collapse from three / two script tags to
  one type="module" tag pointing at the bundled output.

package-lock.json is intentionally omitted from this commit — npm
isn't available in the iris container yet (approval pending) and the
lockfile will land in the next commit on this branch once the
toolchain is in place. The PR will not be opened until it's there.

Phase 2 (nix derivations), Phase 3 (container plumbing + the
hyperhive.frontend.extraFiles option for per-agent layering), and
Phase 4 (Rust cutover to tower_http::ServeDir, delete hive-fr0nt
+ legacy assets dirs) land as follow-up commits on this same
branch.

Refs #273.
This commit is contained in:
iris 2026-05-23 12:59:20 +02:00 committed by Mara
parent d81b430136
commit 8bebd78895
21 changed files with 7214 additions and 0 deletions

33
frontend/README.md Normal file
View file

@ -0,0 +1,33 @@
# hyperhive frontend
npm workspaces project for the hyperhive browser-facing assets:
- `packages/shared/` — shared modules used by both surfaces (terminal
pane, Catppuccin palette + body typography).
- `packages/dashboard/` — the hive-c0re dashboard SPA.
- `packages/agent/` — the per-container web UI (default agent page,
stats, screen).
## Build
```
npm install # one-off; uses the checked-in package-lock.json
npm run build # builds every workspace into packages/*/dist/
```
The Rust binaries serve `packages/dashboard/dist/` and
`packages/agent/dist/` via `tower_http::ServeDir` at runtime; the
build derivation is wired up in `nix/modules/frontend.nix`. Per-agent
additions are layered on top of the default agent dist via the
`hyperhive.frontend.extraFiles` option in `agent.nix`.
## Why npm + esbuild
- **Hermetic**: dependencies vendored via the checked-in lockfile;
`buildNpmPackage` in nix uses it as the source-of-truth so the
output is reproducible without network access at build time.
- **esbuild**: vanilla-JS bundler, no framework runtime overhead.
Each workspace's `build.mjs` is ~30 lines.
- **Single-PR migration**: see issue #273 for the design proposal and
the four-commit shape (npm scaffold → nix derivations → container
plumbing → Rust cutover).