mara/hyperhive
mara/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

docs: sort the top-level directories into five sections by what the reader wants

Browse source 
Every docs directory moves under 1-getting-started, 2-handbook,
4-implementation or 5-project; the options reference (section 3) comes from
the website and has no directory here. trust-boundary stays whole under the
handbook for now. web-ui, swarm and tools split between handbook and
implementation, and the command-line references move to
2-handbook/reference. Links, path references in code and nix, and the docs
index follow the moves; no page content changes.
This commit is contained in:
iris 2026-11-06 18:30:12 +01:00 • committed by mara
commit 6739bb903d
9 changed files with 736 additions and 701 deletions
Download patch file Download diff file Expand all files Collapse all files

20
frontend/packages/dashboard/src/agents.js
View file

@ -1,7 +1,7 @@
// 4G3NTS (containers) domain — extracted from tabs.js.
// Agent topology, container-row rendering, selection bar, and all
// live-update apply handlers for container-state, transient, and
// job-queue-rollup ops. See docs/web-ui/dashboard.md::Container row for the
// job-queue-rollup ops. See docs/2-handbook/web-ui/dashboard.md::Container row for the
// rendering contract.
import { $, form, fmtAgeSecs } from "./common.js";
@ -37,14 +37,14 @@ const containerRowCache = new Map();
// by agent name -> Map<transient_kind, since_unix>: an agent can hold
// several pills at once (every *running* node naming the agent lights
// one now, not just a curated "worth surfacing" subset — see
// docs/web-ui/dashboard.md::Container row), keyed the same way the backend's
// docs/2-handbook/web-ui/dashboard.md::Container row), keyed the same way the backend's
// own tombstone map is, `(agent, label)`, so a clear only removes the
// specific pill it names rather than guessing. `since_unix` is
// wall-clock so the elapsed-seconds badge ticks without polling.
const transientsState = new Map();
// In-memory set of selected agent logical names backing the sticky
// #selection-bar. See docs/web-ui/dashboard.md::Selection bar for the
// #selection-bar. See docs/2-handbook/web-ui/dashboard.md::Selection bar for the
// interaction model (icon-click toggle, Esc/clear button drop,
// tab-gated visibility).
const selectionState = new Set();
@ -225,7 +225,7 @@ function derivePortConflicts(containers) {
}
// ─── container ordering ──────────────────────────────────────────────────────
// Flat alphabetical sort — see docs/web-ui/dashboard.md::C0NTAINERS.
// Flat alphabetical sort — see docs/2-handbook/web-ui/dashboard.md::C0NTAINERS.
function sortedContainerRows(containers) {
// Close any open context menu before replacing the DOM tree — the
@ -285,7 +285,7 @@ function buildContainerLi(c, opts) {
// Agent icon: 5em square wrapper with an absolutely-positioned
// <img> + fire-and-forget load with /favicon.svg fallback. The
// wrapper doubles as the selection toggle (click / keyboard).
// See docs/web-ui/dashboard.md::Container row for the layout + load-strategy
// See docs/2-handbook/web-ui/dashboard.md::Container row for the layout + load-strategy
// rationale.
const iconImg = el("img", { class: "container-icon-img", alt: "" });
const icon = el(
@ -478,7 +478,7 @@ function buildContainerLi(c, opts) {
// dashboard-state fetch above.
if (pending.length) {
// One badge per pill — an agent can carry several transients at
// once now (see docs/web-ui/dashboard.md::Container row), each rendered
// once now (see docs/2-handbook/web-ui/dashboard.md::Container row), each rendered
// independently rather than collapsed into one label.
for (const label of pending) {
head.append(
@ -561,7 +561,7 @@ function buildContainerLi(c, opts) {
// Per-card action buttons (R3ST4RT / ST0P / ST4RT / R3BU1LD /
// DESTR0Y / PURG3) live on the selection bar, not here — see
// docs/web-ui/dashboard.md::Selection bar. The contextual `needs update ↻`
// docs/2-handbook/web-ui/dashboard.md::Selection bar. The contextual `needs update ↻`
// chip in the head row stays — it's a state-hint, not an
// action button.
@ -632,7 +632,7 @@ export function renderContainers(s) {
// TCP fallback — the gateway proxies the prefix to the per-agent
// harness (unix-domain via `agent-sockets.json`, or a computed TCP
// loopback port while the socket marker is absent). See
// `docs/web-ui/dashboard.md::Container row` + `docs/networking/gateway.md::Vhost map`.
// `docs/2-handbook/web-ui/dashboard.md::Container row` + `docs/4-implementation/networking/gateway.md::Vhost map`.
const gatewayLinks = !!(s && s.gateway_enabled);
// Forge public URL: state.forge_public_url (set by the NixOS module
// from services.hyperhive.swarm.forge.publicUrl) or null — never guessed
@ -658,7 +658,7 @@ export function renderContainers(s) {
// full stop (mara, on review: "remove the per agent pending stuff -
// only show what is running"; rendered one badge per pill — mara,
// earlier: "show all running nodes that name the agent"). See
// docs/web-ui/dashboard.md::Container row.
// docs/2-handbook/web-ui/dashboard.md::Container row.
const transientKindsMap = transientsState.get(c.name);
// Sorted for stable badge order across renders — Map iteration
// order is insertion order, which shifts as pills clear/re-add.
@ -725,7 +725,7 @@ export function renderContainers(s) {
// ─── selection bar ───────────────────────────────────────────────────────────
// Sticky-bottom strip; visible when >=1 agent selected on the 4G3NTS
// tab. See docs/web-ui/dashboard.md::Selection bar for the interaction model
// tab. See docs/2-handbook/web-ui/dashboard.md::Selection bar for the interaction model
// and the per-action availability rules (disabled-with-tooltip for
// actions that don't apply to the full selection). Actions POST per
// agent in a loop (endpoints are individually idempotent /

2
frontend/packages/dashboard/src/colors.css
View file

@ -2,5 +2,5 @@
esbuild emits its own `dist/static/colors.css`, linked first by every
dashboard page (before theme.css). This is the theme swap contract: a
stylix-generated variant replaces only this file. See
@hive/shared/colors.css + docs/web-ui/css-vars.md. */
@hive/shared/colors.css + docs/4-implementation/web-ui/css-vars.md. */
@import "@hive/shared/colors.css";

2
frontend/packages/dashboard/src/common.css
View file

@ -247,7 +247,7 @@ code {
}
/* M0V3 affordance (selection bar) — mauve reads as "structural
change" rather than the destructive red / amber chrome of
destroy / rebuild. See docs/web-ui/dashboard.md::Selection bar. */
destroy / rebuild. See docs/2-handbook/web-ui/dashboard.md::Selection bar. */
.btn-move {
color: var(--purple);
border-color: var(--purple);

4
frontend/packages/dashboard/src/common.js
View file

@ -63,7 +63,7 @@ export const form = (
// ─── shared-worker SSE pipe ─────────────────────────────────────────────
// Returns an EventSource-shaped facade backed by a SharedWorker that
// holds one upstream `new EventSource(url)` and fans events out to
// every connected tab. See docs/web-ui/shape.md (SSE multiplexing paragraph)
// every connected tab. See docs/4-implementation/web-ui/shape.md (SSE multiplexing paragraph)
// for the design + Firefox throttling motivation; graceful fallback to
// direct EventSource on environments without SharedWorker.
//
@ -100,7 +100,7 @@ function getSharedPort() {
// SharedWorker death detection: pings from the worker bump the
// activity clock; a visibility-gated watchdog polls and re-subscribes
// on a fresh port if the page has been silent past the threshold.
// See docs/web-ui/shape.md (Worker-death self-heal paragraph) for the
// See docs/4-implementation/web-ui/shape.md (Worker-death self-heal paragraph) for the
// timing rationale + Firefox reclaim symptom.
const WORKER_DEAD_THRESHOLD_MS = 90_000;
const WORKER_WATCHDOG_INTERVAL_MS = 15_000;

2
frontend/packages/dashboard/src/dashboard.css
View file

@ -12,7 +12,7 @@
/* ─── tabbed dashboard chrome ──────────────────────────────────────
Top-of-page sticky header with banner + tab strip. SSE stays
alive across tab switches. See docs/web-ui/dashboard.md::Chrome header + Tab strip for the
alive across tab switches. See docs/2-handbook/web-ui/dashboard.md::Chrome header + Tab strip for the
routing model. */
body.dashboard-shell {

2
frontend/packages/dashboard/src/index.html
View file

@ -165,7 +165,7 @@
<!-- Selection action bar. Sticky-bottom strip that slides into
view when one or more agent cards is selected (click the icon
to toggle). See docs/web-ui/dashboard.md::Selection bar for the bulk
to toggle). See docs/2-handbook/web-ui/dashboard.md::Selection bar for the bulk
action gating + clear semantics. -->
<div
id="selection-bar"

2
frontend/packages/dashboard/src/stream-worker.js
View file

@ -1,6 +1,6 @@
// SharedWorker that holds ONE EventSource per stream URL and fans
// every server-sent event out to every connected tab via MessagePort.
// Design rationale: docs/web-ui/shape.md (SSE multiplexing paragraph).
// Design rationale: docs/4-implementation/web-ui/shape.md (SSE multiplexing paragraph).
//
// Wire protocol (port.postMessage payloads):
//

4
frontend/packages/dashboard/src/tabs.js
View file

@ -2,7 +2,7 @@
// Reads /api/state on cold load and after every async-form submit; live
// updates run through `applyXxx` mutation handlers triggered by the
// dashboard event stream (subscribed via `openStream` from common.js). See
// docs/web-ui/shape.md::Shape (shared by both) for the broader contract.
// docs/4-implementation/web-ui/shape.md::Shape (shared by both) for the broader contract.
//
// Pure helpers (DOM, side panel, path linkification)
// live in `./common.js`.
@ -213,7 +213,7 @@ import { renderUserMenu } from "./user-menu.js";
(function bindDashboardStream() {
// Route through the SharedWorker so all open hyperhive tabs on the
// SAME kinds= filter share one upstream SSE connection — see
// docs/web-ui/shape.md (SSE multiplexing paragraph) for the design
// docs/4-implementation/web-ui/shape.md (SSE multiplexing paragraph) for the design
// + Firefox throttling motivation. `openStream` returns an
// EventSource-shaped facade with a graceful direct-EventSource
// fallback when SharedWorker isn't supported.

2
frontend/packages/dashboard/src/theme.css
View file

@ -2,5 +2,5 @@
esbuild emits it as its own `dist/static/theme.css`, linked by every
dashboard page right after colors.css. The base16 slots it derives
from live in colors.css (the swap contract); a theme swap replaces
only that file. See @hive/shared/theme.css + docs/web-ui/css-vars.md. */
only that file. See @hive/shared/theme.css + docs/4-implementation/web-ui/css-vars.md. */
@import "@hive/shared/theme.css";