Skip to content

Commit 4465795

Browse files
ToolboxAidToolboxAid
committed
PLAN_PR PR_26175_CHARLIE_002 system health dashboard
1 parent 122e40a commit 4465795

5 files changed

Lines changed: 395 additions & 86 deletions

‎docs_build/dev/reports/PR_26175_CHARLIE_002-system-health-dashboard-instruction-compliance-checklist.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# PR_26175_CHARLIE_002 Instruction Compliance Checklist
2+
3+
| Requirement | Status | Evidence |
4+
|---|---:|---|
5+
| Verify worktree clean before switching from Bravo | PASS | `git status --short` returned clean before checkout. |
6+
| Do not merge Bravo | PASS | No merge command was run. |
7+
| Do not modify Bravo | PASS | No Bravo files were changed. |
8+
| Resolve Charlie branch | PASS | Existing `PR_26172_CHARLIE_repository-compliance-stack` branch checked out. |
9+
| Sync Charlie if it exists | PASS | `git pull --ff-only` reported up to date. |
10+
| Hard stop if Charlie branch cannot be resolved | PASS | Branch resolved; no stop required. |
11+
| PLAN_PR only | PASS | Only planning/report artifacts are changed. |
12+
| Scope only System Health dashboard plan | PASS | Report limits scope to Admin System Health dashboard diagnostics. |
13+
| Do not implement configurable multiple runtime ports | PASS | Multiple runtime ports recorded as deferred/cancelled. |
14+
| Return repo-structured ZIP under `tmp/` | PASS | Planned artifact: `tmp/PR_26175_CHARLIE_002-system-health-dashboard_PLAN_delta.zip`. |
15+
| Required reports under `docs_build/dev/reports/` | PASS | PLAN, manual notes, checklist, codex diff, and changed-files reports are produced. |
16+
| No implementation changes | PASS | No runtime/source/test files are modified by PLAN. |

‎docs_build/dev/reports/PR_26175_CHARLIE_002-system-health-dashboard-manual-validation-notes.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# PR_26175_CHARLIE_002 System Health Dashboard Manual Validation Notes
2+
3+
## Manual Checks Completed During PLAN
4+
5+
- Confirmed Bravo branch was clean before switching.
6+
- Confirmed Bravo branch was not merged or modified.
7+
- Resolved existing Charlie branch: `PR_26172_CHARLIE_repository-compliance-stack`.
8+
- Pulled/synced Charlie branch.
9+
- Confirmed Charlie branch local/origin sync was `0 0`.
10+
- Reviewed ProjectInstructions startup, branch context, branch lock, PR workflow, team assignment, and team ownership guidance.
11+
- Reviewed existing System Health dashboard files and tests.
12+
13+
## Manual Checks Required During APPLY/Build
14+
15+
- Verify `PR_26175_CHARLIE_001-local-api-startup-diagnostics` is merged or included in the approved stack.
16+
- Verify Local API startup output matches approved diagnostics format.
17+
- Verify dashboard renders only safe sanitized startup diagnostics.
18+
- Verify no secret values are visible in DOM text, API payloads, console output, reports, or ZIP contents.
19+
- Verify configurable multiple runtime ports remain deferred/cancelled and are not implemented.
20+
21+
## Skipped During PLAN
22+
23+
- No implementation validation was run because this task is PLAN_PR only.
24+
- No Playwright validation was run because no runtime or UI files were changed.
25+
- No samples were run.

‎docs_build/dev/reports/PR_26175_CHARLIE_002-system-health-dashboard_PLAN.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# PLAN_PR: PR_26175_CHARLIE_002-system-health-dashboard
2+
3+
Team: Charlie
4+
5+
Purpose: Plan a scoped System Health dashboard increment that builds on the Local API startup diagnostics lane without implementing configurable multiple runtime ports or unrelated telemetry/governance work.
6+
7+
## Branch and Context Validation
8+
9+
| Check | Expected | Actual | Status |
10+
|---|---|---|---|
11+
| Starting branch before switch | `pr/26172-BRAVO-text2speech-messages-inventory` | `pr/26172-BRAVO-text2speech-messages-inventory` | PASS |
12+
| Bravo worktree clean before switch | no output from `git status --short` | clean | PASS |
13+
| Bravo branch merged | not merged | not merged | PASS |
14+
| Bravo branch modified | no | no | PASS |
15+
| Charlie branch resolved | existing Team Charlie branch | `PR_26172_CHARLIE_repository-compliance-stack` | PASS |
16+
| Charlie branch synced | local equals remote | `0 0` against `origin/PR_26172_CHARLIE_repository-compliance-stack` | PASS |
17+
| Active team | Team Charlie | Team Charlie | PASS |
18+
| Active assignment | PLAN_PR for System Health dashboard | `PR_26175_CHARLIE_002-system-health-dashboard` | PASS |
19+
20+
## Dependency Gate
21+
22+
This PR depends on:
23+
24+
- `PR_26175_CHARLIE_001-local-api-startup-diagnostics`
25+
26+
Start gate for APPLY/build:
27+
28+
- PASS only when PR_001 is merged or the approved stack branch includes its committed startup diagnostics work.
29+
- PASS only when the Local API startup output matches the approved diagnostics format.
30+
- FAIL if PR_001 is absent, unmerged, or if startup diagnostics output is still ambiguous.
31+
32+
## Scope
33+
34+
Plan only for a System Health dashboard increment.
35+
36+
Allowed implementation scope for the later APPLY/build:
37+
38+
- Use existing Admin System Health page and safe API client patterns.
39+
- Surface Local API startup diagnostics inside the System Health dashboard only if PR_001 provides a safe structured contract or stable parseable output.
40+
- Keep dashboard data server-owned and browser-safe.
41+
- Preserve existing Theme V2 Admin System Health layout.
42+
- Preserve existing Postgres, R2, runtime environment, limits/capacity, diagnostics plan, and diagnostics log sections unless a narrowly scoped dashboard row/section addition is required.
43+
- Use PASS/WARN/FAIL indicators only when backed by real diagnostics.
44+
- Use PENDING or equivalent non-failure status for intentionally unwired dashboard items.
45+
- Provide hover/title or accessible reason text for every non-PASS status.
46+
- Do not expose secrets, raw connection strings, access keys, tokens, service role values, or database credentials.
47+
48+
Out of scope:
49+
50+
- Configurable multiple runtime ports implementation.
51+
- New telemetry foundation.
52+
- In-use delete governance.
53+
- New persistence.
54+
- New database schema.
55+
- New R2 write behavior beyond existing safe connectivity actions.
56+
- Runtime feature work outside Admin/System Health.
57+
- Any changes to Team Bravo branch or reports.
58+
59+
Deferred/cancelled carry-forward:
60+
61+
- Configurable multiple runtime ports remains cancelled/deferred for this System Health dashboard PR.
62+
- `PR_26175_CHARLIE_004-telemetry-foundation` remains deferred.
63+
- `PR_26175_CHARLIE_005-in-use-delete-governance-rule` remains future governance.
64+
65+
## Current Relevant Implementation Inventory
66+
67+
Existing files to review during APPLY/build:
68+
69+
- `admin/system-health.html`
70+
- `assets/theme-v2/js/admin-system-health.js`
71+
- `src/api/admin-system-health-api-client.js`
72+
- `src/dev-runtime/server/local-api-router.mjs`
73+
- `scripts/start-local-api-server.mjs`
74+
- `tests/playwright/tools/AdminHealthOperationsPage.spec.mjs`
75+
- `tests/playwright/tools/AdminPlatformToolsWireframes.spec.mjs`
76+
- `tests/dev-runtime/AdminHealthOperations.test.mjs`
77+
- `tests/dev-runtime/LocalApiStartupLogging.test.mjs`
78+
79+
Existing System Health route/API surface:
80+
81+
- Browser client calls `/api/admin/system-health/status`.
82+
- Browser client calls `/api/admin/system-health/storage-connectivity-action`.
83+
- Local API router already returns `databaseStatus`, `storageStatus`, `runtimeEnvironment`, `limitsStatus`, `operationsHealth`, `overview`, and `summary`.
84+
- Admin System Health page already renders Postgres-only database diagnostics, R2 diagnostics, runtime environment rows, limits/capacity, diagnostics plan, and diagnostics log.
85+
86+
Existing validation evidence:
87+
88+
- `tests/playwright/tools/AdminHealthOperationsPage.spec.mjs` covers safe System Health rendering, Postgres diagnostics, R2 diagnostics, runtime key masking, admin-only access, and no inline scripts/styles.
89+
- `tests/dev-runtime/AdminHealthOperations.test.mjs` covers `/api/admin/system-health/status` admin access and blocks Creator sessions.
90+
- `docs_build/dev/reports/PR_26171_018-local-api-startup-diagnostics.md` documents an older startup diagnostics shape, including environment variable output and runtime port listing.
91+
- `docs_build/dev/reports/PR_26169_026-local-api-startup-url-logging.md` documents earlier Local API startup URL logging behavior.
92+
93+
## Proposed APPLY/Build Steps
94+
95+
1. Start from the approved Charlie branch or the owner-approved stack branch containing PR_001.
96+
2. Verify dependency:
97+
- confirm PR_001 commit/report exists in the branch or mainline dependency chain;
98+
- run the startup diagnostics unit test;
99+
- confirm approved startup output format.
100+
3. Inspect `scripts/start-local-api-server.mjs` and the PR_001 startup diagnostics contract.
101+
4. Add a System Health dashboard row/section for Local API startup diagnostics only if the data source is safe and stable.
102+
5. If PR_001 exposes only console text, prefer a server-owned helper in `src/dev-runtime/server/local-api-router.mjs` that returns sanitized startup diagnostic metadata rather than browser-parsing console output.
103+
6. Extend `src/api/admin-system-health-api-client.js` only if a new API route is needed; otherwise reuse `/admin/system-health/status`.
104+
7. Extend `assets/theme-v2/js/admin-system-health.js` to render any new dashboard data with existing status helper functions.
105+
8. Update `admin/system-health.html` only for scoped dashboard placeholders/rows required by the new diagnostics.
106+
9. Update targeted tests only.
107+
10. Produce reports and delta ZIP.
108+
109+
## Approved Diagnostics Format Expectation
110+
111+
The later APPLY/build must verify PR_001 startup output before changing dashboard behavior. Expected properties:
112+
113+
- Environment variables are listed in a deterministic section.
114+
- Secret-like values are masked.
115+
- URL credentials are redacted.
116+
- Runtime URL/API URL/database/storage information is shown only as safe diagnostics.
117+
- Configurable multiple runtime ports are not implemented in this PR.
118+
- Cancelled/deferred multiple-port work is documented rather than built.
119+
120+
## Status Model
121+
122+
Use existing status model:
123+
124+
- `PASS`: known good, backed by real diagnostic evidence.
125+
- `WARN`: actionable partial/missing configuration, not a placeholder.
126+
- `FAIL`: actual failed diagnostic or blocked required behavior.
127+
- `PENDING`: intentional future wiring or dependency not active yet.
128+
129+
Every non-PASS status must include title or accessible reason text.
130+
131+
## Validation Plan
132+
133+
Required targeted validation for APPLY/build:
134+
135+
- `git diff --check`
136+
- `node --test tests/dev-runtime/LocalApiStartupLogging.test.mjs`
137+
- `node --test tests/dev-runtime/AdminHealthOperations.test.mjs`
138+
- `npx playwright test tests/playwright/tools/AdminHealthOperationsPage.spec.mjs`
139+
- Targeted browser/static validation for no secret exposure:
140+
- no raw `DATABASE_URL`;
141+
- no `PASSWORD`, `SECRET`, `TOKEN`, `KEY`, `SERVICE_ROLE`, or `JWT` values exposed;
142+
- no inline scripts/styles introduced.
143+
144+
Skipped lanes:
145+
146+
- Full samples smoke: skipped because the scope is Admin System Health dashboard diagnostics only.
147+
- Broad Playwright: skipped unless targeted Admin/System Health tests require support coverage.
148+
- Runtime feature tests outside System Health: skipped as out of scope.
149+
150+
## Required Reports for APPLY/Build
151+
152+
- `docs_build/dev/reports/codex_review.diff`
153+
- `docs_build/dev/reports/codex_changed_files.txt`
154+
- `docs_build/dev/reports/PR_26175_CHARLIE_002-system-health-dashboard.md`
155+
- `docs_build/dev/reports/PR_26175_CHARLIE_002-system-health-dashboard-manual-validation-notes.md`
156+
- `docs_build/dev/reports/PR_26175_CHARLIE_002-system-health-dashboard-instruction-compliance-checklist.md`
157+
- repo-structured delta ZIP under `tmp/`
158+
159+
## PLAN_PR Result
160+
161+
PLAN status: PASS.
162+
163+
Recommendation: Continue to APPLY only after `PR_26175_CHARLIE_001-local-api-startup-diagnostics` is present in the approved dependency chain and its startup output format has been validated.

‎docs_build/dev/reports/codex_changed_files.txt‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,5 @@
1-
A docs_build/dev/reports/PR_26172_CHARLIE_043-final-charlie-compliance-reaudit.md
1+
docs_build/dev/reports/PR_26175_CHARLIE_002-system-health-dashboard_PLAN.md
2+
docs_build/dev/reports/PR_26175_CHARLIE_002-system-health-dashboard-manual-validation-notes.md
3+
docs_build/dev/reports/PR_26175_CHARLIE_002-system-health-dashboard-instruction-compliance-checklist.md
4+
docs_build/dev/reports/codex_review.diff
5+
docs_build/dev/reports/codex_changed_files.txt

0 commit comments

Comments
 (0)