@stacknext/dashboard 0.9.0 → 0.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/development.md +96 -0
- package/docs/index.md +61 -0
- package/docs/routes.md +64 -0
- package/package.json +5 -4
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Development
|
|
3
|
+
description: Build and run the StackNext dashboard locally.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Development
|
|
7
|
+
|
|
8
|
+
## Commands
|
|
9
|
+
|
|
10
|
+
From the repository root:
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
pnpm --filter @stacknext/dashboard dev
|
|
14
|
+
pnpm --filter @stacknext/dashboard build
|
|
15
|
+
pnpm --filter @stacknext/dashboard typecheck
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
<!-- coderabbit-ai-generated:v1 -->
|
|
19
|
+
|
|
20
|
+
<!-- coderabbit-ai-generated-section:v1:e709ca5d57ab669d93f2bd198a2a99d16ff5ce21ca82ffcd40a4255595e2af80 -->
|
|
21
|
+
|
|
22
|
+
`vite` serves the dashboard for UI work at `http://localhost:4401`.
|
|
23
|
+
With the collector running, first open `http://localhost:4400/` in the same
|
|
24
|
+
browser session to establish its dashboard session cookie, then open Vite.
|
|
25
|
+
Use the same hostname for both URLs: if using `127.0.0.1` for Vite, first visit
|
|
26
|
+
`http://127.0.0.1:4400/`. Cookies are shared across ports, but not between
|
|
27
|
+
`localhost` and `127.0.0.1`. Vite proxies `/api` to the collector; opening Vite
|
|
28
|
+
alone in a fresh browser session does not issue the cookie needed for API reads. The production build writes to
|
|
29
|
+
`packages/dashboard/dist`, which `@stacknext/cli` serves.
|
|
30
|
+
|
|
31
|
+
<!-- /coderabbit-ai-generated:v1 -->
|
|
32
|
+
|
|
33
|
+
To exercise the full app, build first and run the example:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
pnpm build
|
|
37
|
+
cd apps/example
|
|
38
|
+
pnpm exec stacknext dev --open
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Data
|
|
42
|
+
|
|
43
|
+
The dashboard has no fixtures of its own for normal development. It reads the
|
|
44
|
+
live collector API. Make requests to the example app to populate requests,
|
|
45
|
+
traces, errors, queries and diagnostics.
|
|
46
|
+
|
|
47
|
+
<!-- coderabbit-ai-generated:v1 -->
|
|
48
|
+
|
|
49
|
+
<!-- coderabbit-ai-generated-section:v1:fe2e5cd58634599f440f5b6916ee13ff23255fc02f0504d3802bf6802183c664 -->
|
|
50
|
+
|
|
51
|
+
`packages/dashboard/test` contains component and route tests. Run the root test
|
|
52
|
+
command for the Vitest unit/integration suite (including dashboard tests):
|
|
53
|
+
|
|
54
|
+
<!-- /coderabbit-ai-generated:v1 -->
|
|
55
|
+
|
|
56
|
+
<!-- coderabbit-ai-generated:v1 -->
|
|
57
|
+
|
|
58
|
+
<!-- coderabbit-ai-generated-section:v1:b657bace04c0c901ec21e7f21bfe46c03b25678d4b7b434aa6767695ce855557 -->
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
pnpm test
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Browser end-to-end checks run separately with `pnpm test:e2e`. Build first
|
|
65
|
+
with `pnpm build` and stop the example runtime before running them so the
|
|
66
|
+
script can start and stop its own runtime.
|
|
67
|
+
|
|
68
|
+
<!-- /coderabbit-ai-generated:v1 -->
|
|
69
|
+
|
|
70
|
+
## Assets
|
|
71
|
+
|
|
72
|
+
- The app icon and favicon live in `public/`.
|
|
73
|
+
- The Open Span symbol is inlined with `currentColor`.
|
|
74
|
+
- Fonts use `@fontsource-variable/inter`.
|
|
75
|
+
- There are no remote assets or telemetry calls.
|
|
76
|
+
|
|
77
|
+
## Packaging
|
|
78
|
+
|
|
79
|
+
<!-- coderabbit-ai-generated:v1 -->
|
|
80
|
+
|
|
81
|
+
<!-- coderabbit-ai-generated-section:v1:177db3123e6955b864904efe7428f3891e8c562d1bd2751311031b63641a3fc3 -->
|
|
82
|
+
|
|
83
|
+
`@stacknext/dashboard` publishes both `dist` and `docs`. The CLI depends on it and resolves
|
|
84
|
+
the built dashboard directory at runtime. If the dashboard build is missing,
|
|
85
|
+
`stacknext doctor` reports a warning and the collector cannot serve the UI.
|
|
86
|
+
|
|
87
|
+
<!-- /coderabbit-ai-generated:v1 -->
|
|
88
|
+
|
|
89
|
+
## Review checklist
|
|
90
|
+
|
|
91
|
+
- Preserve loopback-only behavior and the session-cookie boundary.
|
|
92
|
+
- Do not add outbound analytics or remote fonts.
|
|
93
|
+
- Keep deep links and the documented routes stable.
|
|
94
|
+
- Show coverage, diagnostics and regression limitations in the UI.
|
|
95
|
+
- Do not present `possible`, `not-observed` or `inconclusive` as confirmed
|
|
96
|
+
outcomes.
|
package/docs/index.md
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "@stacknext/dashboard"
|
|
3
|
+
description: The static React dashboard served by the StackNext local collector.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# @stacknext/dashboard
|
|
7
|
+
|
|
8
|
+
`@stacknext/dashboard` is the React/Vite single-page dashboard. It is built to
|
|
9
|
+
static assets and served by the CLI collector at the loopback dashboard URL.
|
|
10
|
+
|
|
11
|
+
## Who should read this
|
|
12
|
+
|
|
13
|
+
Maintainers and UI contributors. This is an **internal implementation package**
|
|
14
|
+
and is not installed or imported directly by applications. It is a dependency
|
|
15
|
+
of `@stacknext/cli`, which serves the built `dist` directory.
|
|
16
|
+
|
|
17
|
+
## Package boundary
|
|
18
|
+
|
|
19
|
+
The dashboard has no runtime exports other than `./package.json`. It reads the
|
|
20
|
+
collector's read API with the dashboard session cookie or bearer token. It does
|
|
21
|
+
not collect telemetry, run diagnostics or write regression records; the
|
|
22
|
+
collector does.
|
|
23
|
+
|
|
24
|
+
`react`, `react-dom`, `vite` and the StackNext source packages are dev
|
|
25
|
+
dependencies. The published archive contains built assets plus the package
|
|
26
|
+
metadata.
|
|
27
|
+
|
|
28
|
+
## Views
|
|
29
|
+
|
|
30
|
+
The dashboard includes:
|
|
31
|
+
|
|
32
|
+
- Overview with counts, latency, recent errors, coverage and top diagnostics;
|
|
33
|
+
- Requests and request detail;
|
|
34
|
+
- Traces and trace waterfall;
|
|
35
|
+
- Database queries;
|
|
36
|
+
- Errors and error detail;
|
|
37
|
+
- Diagnostics list and detail;
|
|
38
|
+
- Runs, baselines and comparisons, including deep links;
|
|
39
|
+
- Snapshots;
|
|
40
|
+
- Settings.
|
|
41
|
+
|
|
42
|
+
It also provides a command menu and responsive layouts. The exact routes are in
|
|
43
|
+
[Routes](routes.md).
|
|
44
|
+
|
|
45
|
+
## Brand
|
|
46
|
+
|
|
47
|
+
The dashboard uses the Open Span symbol with `currentColor` and the shared
|
|
48
|
+
StackNext favicon/PWA icons. Brand rules live in
|
|
49
|
+
`brand/README.md`. Do not introduce gradients,
|
|
50
|
+
shadows or a brand accent.
|
|
51
|
+
|
|
52
|
+
## Development
|
|
53
|
+
|
|
54
|
+
See [Development](development.md). User-facing dashboard documentation belongs
|
|
55
|
+
on the public docs site, not in this package.
|
|
56
|
+
|
|
57
|
+
## Related packages
|
|
58
|
+
|
|
59
|
+
- `@stacknext/core` supplies wire types and coverage/diagnostic shapes.
|
|
60
|
+
- `@stacknext/regression` supplies run/baseline/comparison types.
|
|
61
|
+
- `@stacknext/cli` builds and serves the dashboard.
|
package/docs/routes.md
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Routes
|
|
3
|
+
description: Dashboard routes and deep links served by the StackNext collector.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Routes
|
|
7
|
+
|
|
8
|
+
The dashboard is a client-side app. The collector serves the shell for these
|
|
9
|
+
paths and the browser handles the view.
|
|
10
|
+
|
|
11
|
+
<!-- coderabbit-ai-generated:v1 -->
|
|
12
|
+
|
|
13
|
+
<!-- coderabbit-ai-generated-section:v1:e57ee1f7b1fcf11bf9fbed866b8a7ee034e0c005d5cec80dddb2d4245cd2a410 -->
|
|
14
|
+
|
|
15
|
+
| Path | View |
|
|
16
|
+
| --- | --- |
|
|
17
|
+
| `/` | Overview: counts, latency, recent errors, coverage, top diagnostics. |
|
|
18
|
+
| `/requests` | Request list with filters and sorting. |
|
|
19
|
+
| `/requests/:traceId` | Request detail and span timeline. |
|
|
20
|
+
| `/traces` | Trace list. |
|
|
21
|
+
| `/traces/:traceId` | Trace waterfall, errors and queries. |
|
|
22
|
+
| `/database` | Database query list. |
|
|
23
|
+
| `/database/:id` | Database query shape detail (`DatabaseQueryDetailPage`). |
|
|
24
|
+
| `/errors` | Error list and fingerprints. |
|
|
25
|
+
| `/errors/:errorId` | Error detail and correlated trace. |
|
|
26
|
+
| `/diagnostics` | Deterministic findings list. |
|
|
27
|
+
| `/diagnostics/:diagnosticId` | Finding evidence, verification and limitations. |
|
|
28
|
+
| `/runs` | Capture runs. |
|
|
29
|
+
| `/runs/:runId` | Run scenarios, samples and correlation. |
|
|
30
|
+
| `/baselines` | Saved baselines. |
|
|
31
|
+
| `/baselines/:baselineId` | Baseline detail. |
|
|
32
|
+
| `/comparisons` | Saved comparisons. |
|
|
33
|
+
| `/comparisons/:comparisonId` | Comparison status, severity and metrics. |
|
|
34
|
+
| `/snapshots` | Saved snapshots. |
|
|
35
|
+
| `/snapshots/:snapshotId` | Frozen sample summary. |
|
|
36
|
+
| `/snapshots/:snapshotId/traces` | Frozen trace list (`TracesPage`). |
|
|
37
|
+
| `/snapshots/:snapshotId/traces/:traceId` | Frozen trace waterfall (`TraceDetailPage`). |
|
|
38
|
+
| `/snapshots/:snapshotId/errors` | Frozen error list (`ErrorsPage`). |
|
|
39
|
+
| `/snapshots/:snapshotId/errors/:errorId` | Frozen error detail (`ErrorDetailPage`). |
|
|
40
|
+
| `/snapshots/:snapshotId/database` | Frozen database query list (`DatabasePage`). |
|
|
41
|
+
| `/mcp` | MCP setup and connection state (`McpPage`). |
|
|
42
|
+
| `/settings` | Retention, bounds, connections and privacy state. |
|
|
43
|
+
|
|
44
|
+
<!-- /coderabbit-ai-generated:v1 -->
|
|
45
|
+
|
|
46
|
+
Deep links are stable for the lifetime of a record. A missing or expired
|
|
47
|
+
telemetry record shows an empty state rather than inventing data.
|
|
48
|
+
|
|
49
|
+
## API routes
|
|
50
|
+
|
|
51
|
+
<!-- coderabbit-ai-generated:v1 -->
|
|
52
|
+
|
|
53
|
+
<!-- coderabbit-ai-generated-section:v1:7c1cf7e9433cb99d1f8731529272ab221a8c86e8f6c21fb29ea21a9a02c0eec4 -->
|
|
54
|
+
|
|
55
|
+
The collector also serves read APIs used by the dashboard, CLI and MCP:
|
|
56
|
+
`/api/health`, `/api/summary`, `/api/requests`, `/api/traces`, `/api/errors`,
|
|
57
|
+
`/api/database`, `/api/coverage`, `/api/diagnostics`, `/api/export`,
|
|
58
|
+
`/api/test-runs`, `/api/baselines`, `/api/comparisons` and `/api/snapshots`.
|
|
59
|
+
|
|
60
|
+
<!-- /coderabbit-ai-generated:v1 -->
|
|
61
|
+
|
|
62
|
+
Dashboard API access uses a `HttpOnly`, `SameSite=Strict` session cookie issued
|
|
63
|
+
when the dashboard HTML is loaded. Ingestion and regression capture writes
|
|
64
|
+
require the bearer token.
|
package/package.json
CHANGED
|
@@ -1,18 +1,19 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@stacknext/dashboard",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.10.0",
|
|
4
4
|
"description": "Static React dashboard served by the StackNext local collector",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"files": [
|
|
8
|
-
"dist"
|
|
8
|
+
"dist",
|
|
9
|
+
"docs"
|
|
9
10
|
],
|
|
10
11
|
"exports": {
|
|
11
12
|
"./package.json": "./package.json"
|
|
12
13
|
},
|
|
13
14
|
"devDependencies": {
|
|
14
|
-
"@stacknext/core": "0.
|
|
15
|
-
"@stacknext/regression": "0.
|
|
15
|
+
"@stacknext/core": "0.10.0",
|
|
16
|
+
"@stacknext/regression": "0.10.0",
|
|
16
17
|
"@types/react": "19.3.0",
|
|
17
18
|
"@types/react-dom": "19.3.0",
|
|
18
19
|
"@vitejs/plugin-react": "5.2.0",
|