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
1 change: 1 addition & 0 deletions changelog.d/added-16064-hub-activity-display-mode.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The hub **Fleet activity** page (`/activity`) takes the spoke Activity Monitor's display parameters, read by the spoke's own code: `?kiosk=1` hides the chrome and cursor for an unattended screen, `?display=1` gives an attended chrome-less wall view that **Esc** or **d** leaves, `am.*` describes the board's view with the spoke's keys (kind, repo, q, author, sort, dir and `am.group=none`), and in display mode `am.view` + `interval` rotate `hub-activity` views with the spoke's wall-clock dwell. `am.*` keys the activity digest has no data for stay in the URL and are named on the board as not applied. A copy of the spoke's URL-view and playlist helpers is served byte-identical from `/activity/assets/` (`pkg/webassets/trackerview`), and a compatibility test fails if it drifts. The spoke tracker's display mode is unchanged ([#16064](https://github.com/hivecommons/hive/issues/16064), part of [#15965](https://github.com/hivecommons/hive/issues/15965), RFC [#15861](https://github.com/hivecommons/hive/issues/15861)).
2 changes: 1 addition & 1 deletion src/docs/api-reference/hub-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `GET` | `/fleet` | Hub handler-specific | My-Hives Fleet Page (static; data via `/api/saas/my-hives`) | `pkg/hub/server.go:1773` |
| `GET` | `/my-hives` | Hub handler-specific | 301 redirect to `/fleet` (query preserved) | `pkg/hub/server.go:1774` |
| `GET` | `/activity` | Signed-in user | Fleet activity page ([#16063](https://github.com/hivecommons/hive/issues/16063)): read-only, data-free shell that polls `/api/hub/activity` every 15 s with `If-None-Match`. No session → `307` to `/login`; blocked user → `403`. Own Content-Security-Policy (scripts and styles from `'self'` only, `script-src-attr`/`style-src-attr` `'none'`), `Cache-Control: no-cache` + content `ETag`. See [Hub Fleet activity page](../hub-fleet-activity.md) | `pkg/hub/activity_page.go` |
| `GET` | `/activity/assets/{name}` | Public | The shared tracker row asset (`pkg/webassets/trackerrow`, [#16062](https://github.com/hivecommons/hive/issues/16062)) the Fleet activity page draws rows with, byte-identical; only names in `trackerrow.Files`, else `404`. `Cache-Control: no-cache` + content `ETag` | `pkg/hub/activity_page.go` |
| `GET` | `/activity/assets/{name}` | Public | The shared tracker assets the Fleet activity page loads, byte-identical: the row asset (`pkg/webassets/trackerrow`, [#16062](https://github.com/hivecommons/hive/issues/16062)) and the `am.*` URL-view and display-playlist helpers (`pkg/webassets/trackerview`, [#16064](https://github.com/hivecommons/hive/issues/16064)); only names in `trackerrow.Files` or `trackerview.Files`, else `404`. `Cache-Control: no-cache` + content `ETag` | `pkg/hub/activity_page.go` |
| `POST` | `/api/shared-agent-pool/leases` | Hub handler-specific | Acquire or renew a shared CLI session lease | `pkg/hub/server.go:1708` |
| `PUT` | `/api/shared-agent-pool/leases` | Hub handler-specific | Renew an active shared CLI session lease | `pkg/hub/server.go:1709` |
| `DELETE` | `/api/shared-agent-pool/leases` | Hub handler-specific | Release a shared CLI session lease | `pkg/hub/server.go:1710` |
Expand Down
13 changes: 13 additions & 0 deletions src/docs/dashboard-source-layout.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,19 @@ code without importing `pkg/dashboard`. The generator only reads
`TestTrackerRowSharedAssetRendersSpokeFixtures` renders the same fixtures
through both. Edit both copies in the same PR.

The same rule applies to the Activity Monitor URL-view and display-playlist
helpers: `stageTrackerDefaultFilter` (`js/tracker-words-stage.js`),
`stageTrackerNormalizeFilter` (`js/tracker-filter.js`) and the
`tracker url view helpers` and `tracker display playlist helpers` blocks of
`js/tracker-filter-state.js`. `src/pkg/webassets/trackerview/tracker-view.js`
carries a verbatim copy so the hub Fleet activity page reads `am.*`, `am.view`
and `interval` as a spoke display does
([#16064](https://github.com/hivecommons/hive/issues/16064)).
`TestTrackerViewSharedAssetCompat` (in `pkg/dashboard`) compares that copy
with the declarations in the committed `static/index.html` and fails when they
drift: after editing one of these spoke helpers, run `make dashboard-gen` and
re-copy them into `tracker-view.js` in the same PR.

## Working with it

```sh
Expand Down
2 changes: 1 addition & 1 deletion src/docs/documentation-map.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Documentation for the current Hive line (branch `v5`; the code and docs live und
### First installation

- [Hosted Hive Hub onboarding](hosted-hub.md) — signing in at `https://hive.hivecommons.dev`, requesting a hosted hive, installing the GitHub App, configuring model gateways and Copilot login, reading `/fleet`, and fixing common setup problems.
- [Hub Fleet activity page](hub-fleet-activity.md) — the read-only `/activity` board of open issues and PRs across the hives you can see: per-viewer scoping, hive chips, group-by-hive freshness headers, always-visible truncation and stale-source disclosures, and 15-second ETag polling.
- [Hub Fleet activity page](hub-fleet-activity.md) — the read-only `/activity` board of open issues and PRs across the hives you can see: per-viewer scoping, hive chips, group-by-hive freshness headers, always-visible truncation and stale-source disclosures, 15-second ETag polling, and display mode (`?kiosk=1`, `?display=1`, `am.*` views and `hub-activity` playlists).
- [Docker Compose quick start](quickstart-docker-compose.md) — default standalone installation, prerequisites, and verification.
- [Podman quick start](quickstart-podman.md) — standalone Quadlet/systemd installation, with rootless/rootful prerequisites.
- [Kubernetes deployment](kubernetes-deployment.md) — standalone cluster installation, storage, authentication, and dashboard access. Related: [health checks](health-checks.md).
Expand Down
62 changes: 56 additions & 6 deletions src/docs/hub-fleet-activity.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@ signed in; a browser without a hub session is sent to `/login`.

The design is RFC [#15861](https://github.com/hivecommons/hive/issues/15861)
by @hanthor, delivered in [#15965](https://github.com/hivecommons/hive/issues/15965)
and its children. The page itself is [#16063](https://github.com/hivecommons/hive/issues/16063).
and its children. The page itself is [#16063](https://github.com/hivecommons/hive/issues/16063);
its display mode is [#16064](https://github.com/hivecommons/hive/issues/16064).

## Who sees what

Expand Down Expand Up @@ -40,7 +41,10 @@ Each row is one open issue or PR:
| **Stage** | The strip column the spoke tracker would light (Open, Actionable, Claimed, PR in progress, CI / Review, Merge gate, Merged) and the stage slug. |
| **Author** | `human`, `clanker` or `hive` when the spoke knows it. |

Rows come in the endpoint's order: most urgent first, then furthest stage.
Rows are ordered like the spoke tracker's default sort: furthest strip column
first; within a column, rows with a modifier or parked on a person first and
held or draft rows last; then longest in stage. `am.sort` and `am.dir` change
the order (see [Display mode and URL views](#display-mode-and-url-views)).

**Group by hive** is on by default. It draws one header row per hive, even when
the hive has no open items. The header shows:
Expand Down Expand Up @@ -77,13 +81,59 @@ hidden and resumes, with an immediate refresh, when you come back. The status
line shows when the data last changed and when it was last checked. If your
session expires, the page sends you to `/login`.

## Display mode and URL views

The page takes the same display parameters as the spoke Activity Monitor
(see [Display mode and URL views](streaming-the-activity-monitor.md#display-mode-and-url-views)).
They are the spoke's own parameters, read by the spoke's own code: the hub
serves a byte-identical copy of the spoke's URL-view and playlist helpers
(`src/pkg/webassets/trackerview`). There are no hub-only display parameters.

| Parameter | On `/activity` |
|---|---|
| `kiosk=1` | Unattended screen: hides the hub header, the description and the **Group by hive** toggle, and hides the cursor. The status line and the coverage list stay. A kiosk never rotates a playlist. |
| `display=1` | Attended wall screen: the same chrome-less board, with the cursor. **Esc** (unless the browser is in full screen) or **d** leaves display mode and keeps the rest of the URL. `kiosk=1` wins when both are set. |
| `am.*` | The board's view, with the spoke's keys and values. See the table below. |
| `am.view`, `interval` | A playlist, in display mode only. Each `am.view` is a URL-encoded `am.*` query string, and every entry is a `hub-activity` view: this board under that entry's `am.*` state. `interval` is `Ns` or `Nm`, clamped to 10 s – 1 h, default 60 s. With fewer than two valid entries the board does not rotate. |

How each `am.*` key applies here:

| Key | Effect on the hub board |
|---|---|
| `am.kind` | `pr` or `issue` only. |
| `am.repo` | One `owner/repo`, exact match. |
| `am.q` | Title text, or the item number (`123` or `#123`). |
| `am.author` | `human`, `clanker` or `hive`. |
| `am.sort`, `am.dir` | `furthest` (default), `waiting` (longest in stage) or `number`; `asc` / `desc`. `newest` needs an opening time the digest does not carry, so it sorts as `furthest`. |
| `am.group` | `none` turns grouping off. Grouping by hive is the default and is never written into the URL. A spoke value the hub board has no grouping for (`repo`) falls back to the default, as an unknown value does on the spoke. |
| `am.labels`, `am.needsHuman`, `am.onHold`, `am.attention`, `am.age`, `am.acted` | Not applied: the activity digest carries no labels or verdicts for them. They stay in the URL, so the link still works on a spoke, and the coverage list names them under *Not applied on the hub*. |

A link copied from a spoke display therefore opens on the hub with the same
view where the hub has the data for it, and says which parts it could not
apply. Turning **Group by hive** on or off rewrites `am.group` in the address
bar, so the address is always a link to the current view; credentials in the
URL never survive that rewrite.

The playlist follows the spoke's rules:

- The current view follows the wall clock, so a reload resumes on the same
view. Rotation happens in memory: it does not navigate, refetch or change
the URL.
- A thin bar at the top shows the time until the next view. With reduced
motion it is a static *N/M · next in Ns* label instead.

```text
/activity?display=1&am.view=am.kind%3Dpr&am.view=am.group%3Dnone%26am.repo%3Dhivecommons%2Fhive&interval=2m
```

The spoke-only wall options `density=tv` and `shift=1` are ignored here.

## What the page does not do

- It has no action menus. The hub is visibility-only: act on an item on
GitHub, or from the hive's own tracker.
- Display mode (`?kiosk=1`, `am.*` URL state, `?display=1` and a
`hub-activity` playlist view) is not part of this page yet; it is tracked in
[#16064](https://github.com/hivecommons/hive/issues/16064).
- It is not a broadcast source. Display mode only changes how the signed-in
page looks; the page still needs a hub session and shows only your hives.

## Security

Expand All @@ -93,7 +143,7 @@ session expires, the page sends you to `/login`.
from other origins.
- Titles and every other value from a spoke are written as text, never parsed
as HTML.
- The page, its script and the shared row-presentation asset are revalidated
- The page, its script and the shared row-presentation and view assets are revalidated
on every load (`Cache-Control: no-cache` with a content ETag), so a hub
upgrade is picked up on the next visit.
- `/activity` is marked `noindex` and is disallowed in `robots.txt`.
Expand Down
78 changes: 78 additions & 0 deletions src/pkg/dashboard/tracker_view_shared_asset_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
package dashboard

import (
"io/fs"
"regexp"
"strings"
"testing"

"github.com/hivecommons/hive/pkg/webassets/trackerview"
)

// TestTrackerViewSharedAssetCompat pins the hub's copy of the Activity
// Monitor URL-view and display-playlist helpers (hivecommons/hive#16064) to
// the spoke: past its header comment, pkg/webassets/trackerview/tracker-view.js
// must be exactly these spoke declarations, in this order, as the committed
// static/index.html serves them. The spoke side is only read, never changed:
// a drift fails here and is fixed by re-copying from the spoke.
func TestTrackerViewSharedAssetCompat(t *testing.T) {
html := indexHTML(t)
want := spokeFuncSource(t, html, "stageTrackerDefaultFilter") +
spokeFuncSource(t, html, "stageTrackerNormalizeFilter") +
spokeMarkedBlock(t, html, "tracker url view helpers begin", "tracker url view helpers end") +
spokeMarkedBlock(t, html, "tracker display playlist helpers begin", "tracker display playlist helpers end")

b, err := fs.ReadFile(trackerview.FS, "tracker-view.js")
if err != nil {
t.Fatal(err)
}
got := sharedAssetBody(string(b))
if got != want {
t.Errorf("pkg/webassets/trackerview/tracker-view.js differs from the spoke's declarations; re-copy them verbatim from static/index.html\n--- got ---\n%s\n--- want ---\n%s", got, want)
}
}

// sharedAssetBody drops the leading block of column-0 `//` header lines.
func sharedAssetBody(src string) string {
lines := strings.SplitAfter(src, "\n")
i := 0
for i < len(lines) && strings.HasPrefix(lines[i], "//") {
i++
}
return strings.Join(lines[i:], "")
}

// spokeFuncSource is one function declaration from the spoke page, from the
// start of its line (indentation included) to its closing brace and newline.
func spokeFuncSource(t *testing.T, html, name string) string {
t.Helper()
start := strings.Index(html, "function "+name+"(")
if start < 0 {
t.Fatalf("spoke page does not define %s", name)
}
lineStart := strings.LastIndex(html[:start], "\n") + 1
depth := 0
for i := start + strings.Index(html[start:], "{"); i < len(html); i++ {
switch html[i] {
case '{':
depth++
case '}':
depth--
if depth == 0 {
return html[lineStart:i+1] + "\n"
}
}
}
t.Fatalf("unbalanced braces in %s", name)
return ""
}

// spokeMarkedBlock is a `// begin` … `// end` block, both marker lines included.
func spokeMarkedBlock(t *testing.T, html, begin, end string) string {
t.Helper()
m := regexp.MustCompile(`( *// ` + regexp.QuoteMeta(begin) + `\n[\s\S]*?// ` + regexp.QuoteMeta(end) + `\n)`).FindStringSubmatch(html)
if m == nil {
t.Fatalf("spoke page has no %q … %q block", begin, end)
}
return m[1]
}
Loading
Loading