@stacknext/dashboard 0.8.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.
Files changed (4) hide show
  1. package/docs/development.md +96 -0
  2. package/docs/index.md +61 -0
  3. package/docs/routes.md +64 -0
  4. package/package.json +5 -4
package/docs/development.md ADDED
@@ -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.8.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.8.0",
15
- "@stacknext/regression": "0.8.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",