Skip to content

Commit 7a42c64

Browse files
ToolboxAidToolboxAid
committed
Improve System Health severity logic, readiness visibility, and R2 operational reporting - PR_26168_229-through-232-system-health-readiness-stack
1 parent 65becfe commit 7a42c64

15 files changed

Lines changed: 1495 additions & 1042 deletions

‎admin/system-health.html‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,24 @@ <h2>Admin</h2>
5656
<div class="kicker">Read-only Status</div>
5757
<h2 id="admin-system-health-title">System Health Overview</h2>
5858
</div>
59+
<div class="table-wrapper">
60+
<table class="data-table" aria-label="System health dashboard summary">
61+
<caption>System Health Dashboard Summary</caption>
62+
<thead>
63+
<tr>
64+
<th scope="col">Status</th>
65+
<th scope="col">Score</th>
66+
<th scope="col">PASS</th>
67+
<th scope="col">WARN</th>
68+
<th scope="col">FAIL</th>
69+
<th scope="col">Last Refresh</th>
70+
</tr>
71+
</thead>
72+
<tbody data-admin-system-health-summary-rows>
73+
<tr><td>Loading</td><td>0</td><td>0</td><td>0</td><td>0</td><td>Loading refresh timestamp.</td></tr>
74+
</tbody>
75+
</table>
76+
</div>
5977
<div class="table-wrapper">
6078
<table class="data-table" aria-label="System health overview">
6179
<caption>System Health Overview</caption>
@@ -71,6 +89,23 @@ <h2 id="admin-system-health-title">System Health Overview</h2>
7189
</tbody>
7290
</table>
7391
</div>
92+
<div class="table-wrapper">
93+
<table class="data-table" aria-label="R2 operational readiness">
94+
<caption>R2 Operational Readiness</caption>
95+
<thead>
96+
<tr>
97+
<th scope="col">Area</th>
98+
<th scope="col">Signal</th>
99+
<th scope="col">Status</th>
100+
<th scope="col">Value</th>
101+
<th scope="col">Next Step</th>
102+
</tr>
103+
</thead>
104+
<tbody data-admin-system-health-r2-readiness-rows>
105+
<tr><td>Project Asset Storage / R2</td><td>Status</td><td>Loading</td><td>Loading</td><td>Loading R2 readiness.</td></tr>
106+
</tbody>
107+
</table>
108+
</div>
74109
<div class="table-wrapper">
75110
<table class="data-table" aria-label="System health details">
76111
<caption>System Health Details</caption>

‎assets/theme-v2/js/admin-system-health.js‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,13 @@ class AdminSystemHealthController {
88
this.details = root.querySelector("[data-admin-system-health-detail-rows]");
99
this.limits = root.querySelector("[data-admin-system-health-limit-rows]");
1010
this.overview = root.querySelector("[data-admin-system-health-overview-rows]");
11+
this.r2Readiness = root.querySelector("[data-admin-system-health-r2-readiness-rows]");
1112
this.status = root.querySelector("[data-admin-system-health-status]");
13+
this.summary = root.querySelector("[data-admin-system-health-summary-rows]");
1214
}
1315

1416
init() {
15-
if (!this.details || !this.limits || !this.overview || !this.status) {
17+
if (!this.details || !this.limits || !this.overview || !this.r2Readiness || !this.status || !this.summary) {
1618
return;
1719
}
1820
this.load();
@@ -43,6 +45,18 @@ class AdminSystemHealthController {
4345
});
4446
}
4547

48+
renderSummary(summary) {
49+
this.summary.replaceChildren();
50+
this.summary.append(this.createRow([
51+
summary.status || "WARN",
52+
typeof summary.score === "number" ? `${summary.score}` : "0",
53+
`${summary.counts?.PASS || 0}`,
54+
`${summary.counts?.WARN || 0}`,
55+
`${summary.counts?.FAIL || 0}`,
56+
summary.lastRefreshAt || "not available",
57+
]));
58+
}
59+
4660
renderDetails(rows) {
4761
this.details.replaceChildren();
4862
rows.forEach((row) => {
@@ -68,14 +82,31 @@ class AdminSystemHealthController {
6882
});
6983
}
7084

85+
renderR2Readiness(readiness) {
86+
this.r2Readiness.replaceChildren();
87+
const rows = Array.isArray(readiness?.rows) ? readiness.rows : [];
88+
rows.forEach((row) => {
89+
this.r2Readiness.append(this.createRow([
90+
row.area || "Project Asset Storage / R2",
91+
row.field || "Status",
92+
row.status || "WARN",
93+
row.value || "not configured",
94+
row.nextStep || "Review R2 configuration.",
95+
]));
96+
});
97+
}
98+
7199
load() {
72100
try {
73101
const payload = readAdminSystemHealthStatus();
102+
this.renderSummary(payload.summary || {});
74103
this.renderOverview(Array.isArray(payload.overview) ? payload.overview : []);
75104
this.renderDetails(Array.isArray(payload.details) ? payload.details : []);
76105
this.renderLimits(Array.isArray(payload.limits) ? payload.limits : []);
106+
this.renderR2Readiness(payload.r2Readiness || {});
77107
this.setStatus(payload.status || "WARN", payload.message || "Admin System Health loaded.");
78108
} catch (error) {
109+
this.renderSummary({ counts: { FAIL: 1, PASS: 0, WARN: 0 }, lastRefreshAt: "not available", score: 0, status: "FAIL" });
79110
this.renderOverview([
80111
{
81112
area: "System Health",
@@ -85,6 +116,7 @@ class AdminSystemHealthController {
85116
]);
86117
this.renderDetails([]);
87118
this.renderLimits([]);
119+
this.renderR2Readiness({ rows: [] });
88120
this.setStatus("FAIL", error instanceof Error ? error.message : "Admin System Health unavailable.");
89121
}
90122
}

‎docs_build/codex/decisions/system-health-usage-reporting.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# System Health Usage Reporting Foundation
2+
3+
Admin System Health separates service limits, current usage, and pressure calculation.
4+
5+
## Contract
6+
7+
- Configured limits come from the active `.env` file copied from the selected `.env.<target>` copy-source.
8+
- Current usage is a service-contract value and may be `NOT AVAILABLE` or a numeric usage value.
9+
- Pressure is calculated only when both a configured numeric limit and a numeric usage value exist.
10+
- Missing or invalid limit configuration is a warning.
11+
- `NOT AVAILABLE` usage is not a warning by itself.
12+
13+
## Pressure Labels
14+
15+
- `OK`
16+
- `WATCH`
17+
- `UPGRADE SOON`
18+
- `RISK`
19+
20+
`RISK` is the highest concern label.
21+
22+
## Future Provider Integration Points
23+
24+
- R2 storage bytes: a future R2 provider telemetry adapter can report project asset storage bytes used through the Local API.
25+
- R2 Class A operations: a future R2 provider telemetry adapter can report monthly Class A operation counts through the Local API.
26+
- R2 Class B operations: a future R2 provider telemetry adapter can report monthly Class B operation counts through the Local API.
27+
- Local DB size: a future Local DB telemetry adapter can report database bytes used through the Local API.
28+
- Local DB connections: a future Local DB pool telemetry adapter can report active connection counts through the Local API.
29+
30+
Cloudflare billing integration is not required for the current foundation.

‎docs_build/dev/codex_commands.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2392,3 +2392,112 @@ Required reports:
23922392

23932393
Packaging:
23942394
- `tmp/PR_26168_228-system-health-env-limits_delta.zip`
2395+
2396+
2397+
## PR_26168_229-system-health-severity-cleanup
2398+
2399+
Changes:
2400+
- Read `docs_build/dev/PROJECT_INSTRUCTIONS.md`.
2401+
- Verified the current branch is `main`.
2402+
- Fixed Admin System Health limit severity so configured limits can be PASS.
2403+
- Kept `NOT AVAILABLE` usage from generating WARN by itself.
2404+
- Preserved exact pressure labels: `OK`, `WATCH`, `UPGRADE SOON`, `RISK`.
2405+
2406+
Validation:
2407+
- `node --check src/dev-runtime/server/local-api-router.mjs`
2408+
- `node --check assets/theme-v2/js/admin-system-health.js`
2409+
- `node --check src/engine/api/admin-system-health-api-client.js`
2410+
- `node --check tests/playwright/tools/AdminPlatformToolsWireframes.spec.mjs`
2411+
- Static System Health contract validation.
2412+
- `rg -n "LIMIT RISK" . --glob '!node_modules/**' --glob '!tmp/**' --glob '!docs_build/dev/reports/codex_review.diff'`
2413+
- Targeted Admin System Health/Admin navigation/R2 status/Assets regression Playwright.
2414+
- Full samples smoke skipped because samples and `start_of_day` folders were not touched.
2415+
2416+
Required reports:
2417+
- `docs_build/dev/reports/PR_26168_229-system-health-severity-cleanup.md`
2418+
- `docs_build/dev/reports/codex_changed_files.txt`
2419+
- `docs_build/dev/reports/codex_review.diff`
2420+
- `docs_build/dev/reports/playwright_v8_coverage_report.txt`
2421+
- `docs_build/dev/reports/coverage_changed_js_guardrail.txt`
2422+
2423+
Packaging:
2424+
- `tmp/PR_26168_229-system-health-severity-cleanup_delta.zip`
2425+
2426+
2427+
## PR_26168_230-system-health-live-usage-foundation
2428+
2429+
Changes:
2430+
- Read `docs_build/dev/PROJECT_INSTRUCTIONS.md`.
2431+
- Verified the current branch is `main`.
2432+
- Added service-contract separation for configured limits, current usage, and pressure calculation.
2433+
- Documented provider-specific future usage integration points.
2434+
- Avoided Cloudflare billing integration and credential exposure.
2435+
2436+
Validation:
2437+
- `node --check src/dev-runtime/server/local-api-router.mjs`
2438+
- `node --check assets/theme-v2/js/admin-system-health.js`
2439+
- `node --check tests/playwright/tools/AdminPlatformToolsWireframes.spec.mjs`
2440+
- Static System Health usage-foundation contract validation.
2441+
- Targeted Admin System Health Playwright.
2442+
- Full samples smoke skipped because samples and `start_of_day` folders were not touched.
2443+
2444+
Required reports:
2445+
- `docs_build/dev/reports/PR_26168_230-system-health-live-usage-foundation.md`
2446+
- `docs_build/dev/reports/codex_changed_files.txt`
2447+
- `docs_build/dev/reports/codex_review.diff`
2448+
2449+
Packaging:
2450+
- `tmp/PR_26168_230-system-health-live-usage-foundation_delta.zip`
2451+
2452+
2453+
## PR_26168_231-admin-system-health-consolidation
2454+
2455+
Changes:
2456+
- Read `docs_build/dev/PROJECT_INSTRUCTIONS.md`.
2457+
- Verified the current branch is `main`.
2458+
- Added Admin System Health summary status, score, refresh timestamp, and PASS/WARN/FAIL counts.
2459+
- Preserved Admin Infrastructure as reference and Owner Operations as actions.
2460+
2461+
Validation:
2462+
- `node --check src/dev-runtime/server/local-api-router.mjs`
2463+
- `node --check assets/theme-v2/js/admin-system-health.js`
2464+
- `node --check tests/playwright/tools/AdminPlatformToolsWireframes.spec.mjs`
2465+
- Targeted Admin System Health and Admin navigation Playwright.
2466+
- Full samples smoke skipped because samples and `start_of_day` folders were not touched.
2467+
2468+
Required reports:
2469+
- `docs_build/dev/reports/PR_26168_231-admin-system-health-consolidation.md`
2470+
- `docs_build/dev/reports/codex_changed_files.txt`
2471+
- `docs_build/dev/reports/codex_review.diff`
2472+
- `docs_build/dev/reports/playwright_v8_coverage_report.txt`
2473+
2474+
Packaging:
2475+
- `tmp/PR_26168_231-admin-system-health-consolidation_delta.zip`
2476+
2477+
2478+
## PR_26168_232-r2-operational-readiness
2479+
2480+
Changes:
2481+
- Read `docs_build/dev/PROJECT_INSTRUCTIONS.md`.
2482+
- Verified the current branch is `main`.
2483+
- Added read-only R2 Operational Readiness visibility to Admin System Health.
2484+
- Surfaced endpoint, bucket, prefix, hidden credential configured status, connectivity test status, readiness rows, and next steps.
2485+
- Did not add destructive operations.
2486+
2487+
Validation:
2488+
- `node --check src/dev-runtime/server/local-api-router.mjs`
2489+
- `node --check assets/theme-v2/js/admin-system-health.js`
2490+
- `node --check tests/playwright/tools/AdminPlatformToolsWireframes.spec.mjs`
2491+
- Static R2 readiness contract validation.
2492+
- Targeted Admin System Health/R2 readiness/Admin navigation/Assets R2 regression Playwright.
2493+
- Full samples smoke skipped because samples and `start_of_day` folders were not touched.
2494+
2495+
Required reports:
2496+
- `docs_build/dev/reports/PR_26168_232-r2-operational-readiness.md`
2497+
- `docs_build/dev/reports/codex_changed_files.txt`
2498+
- `docs_build/dev/reports/codex_review.diff`
2499+
- `docs_build/dev/reports/playwright_v8_coverage_report.txt`
2500+
- `docs_build/dev/reports/coverage_changed_js_guardrail.txt`
2501+
2502+
Packaging:
2503+
- `tmp/PR_26168_232-r2-operational-readiness_delta.zip`

‎docs_build/dev/commit_comment.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
System Health env limits - PR_26168_228-system-health-env-limits
1+
R2 operational readiness - PR_26168_232-r2-operational-readiness

‎docs_build/dev/reports/PR_26168_229-system-health-severity-cleanup.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# PR_26168_229-system-health-severity-cleanup
2+
3+
## Branch Validation
4+
5+
PASS
6+
7+
- Current branch: `main`
8+
- Expected branch: `main`
9+
- Local branches found: `main`
10+
11+
## Summary
12+
13+
Fixed Admin System Health limit severity so configured limits are PASS, `NOT AVAILABLE` usage does not automatically produce WARN, and WARN is reserved for missing or invalid limit configuration.
14+
15+
## Requirement Checklist
16+
17+
- PASS - Environment Limits can be PASS when all required limit variables are configured with valid positive integer values.
18+
- PASS - `NOT AVAILABLE` usage values no longer automatically generate WARN.
19+
- PASS - Missing required limit variables report WARN.
20+
- PASS - Invalid limit values report WARN.
21+
- PASS - Failed limit configuration validation reports WARN.
22+
- PASS - Pressure labels remain exactly `OK`, `WATCH`, `UPGRADE SOON`, and `RISK`.
23+
- PASS - `RISK` remains the highest severity label.
24+
- PASS - Forbidden alternate pressure wording was scanned and is absent.
25+
- PASS - PR222-228 behavior remains intact.
26+
27+
## Validation Lane Report
28+
29+
PASS
30+
31+
- `node --check src/dev-runtime/server/local-api-router.mjs`
32+
- `node --check assets/theme-v2/js/admin-system-health.js`
33+
- `node --check src/engine/api/admin-system-health-api-client.js`
34+
- `node --check tests/playwright/tools/AdminPlatformToolsWireframes.spec.mjs`
35+
- Static System Health contract validation for severity, exact pressure labels, no forbidden pressure wording, and no inline HTML script/style/event handlers.
36+
- Targeted Playwright:
37+
- `npx playwright test tests/playwright/tools/AdminPlatformToolsWireframes.spec.mjs tests/playwright/tools/AssetToolMockRepository.spec.mjs -g "System Health|Tool Votes side menu includes Admin platform wireframes|Infrastructure storage connectivity actions call Local API and hide secrets|Infrastructure storage path status reports missing env path as ERROR|Infrastructure storage path status reports invalid env path as ERROR|Infrastructure storage path status reports DEV match only|Infrastructure storage path status reports IST match only|Assets DEV storage upload list read and delete use configured projects prefix"`
38+
- `rg -n "LIMIT RISK" . --glob '!node_modules/**' --glob '!tmp/**' --glob '!docs_build/dev/reports/codex_review.diff'`
39+
40+
## Manual Validation Notes
41+
42+
PASS
43+
44+
- Confirmed limit status now derives from configured limit validation, not usage availability.
45+
- Confirmed usage may remain `NOT AVAILABLE` without lowering Environment Limits severity.
46+
- Confirmed no secrets or full connection strings are exposed.
47+
48+
## Full Samples Decision
49+
50+
SKIP
51+
52+
Full samples smoke was not run because this PR only changes Admin System Health limit severity and targeted tests. Sample JSON, game samples, and `start_of_day` folders were not touched.
53+
54+
## Artifact Output
55+
56+
PASS
57+
58+
- Repo-structured delta ZIP: `tmp/PR_26168_229-system-health-severity-cleanup_delta.zip`
59+
- Review diff: `docs_build/dev/reports/codex_review.diff`
60+
- Changed files: `docs_build/dev/reports/codex_changed_files.txt`

‎docs_build/dev/reports/PR_26168_230-system-health-live-usage-foundation.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# PR_26168_230-system-health-live-usage-foundation
2+
3+
## Branch Validation
4+
5+
PASS
6+
7+
- Current branch: `main`
8+
- Expected branch: `main`
9+
- Local branches found: `main`
10+
11+
## Summary
12+
13+
Added a service-contract foundation that separates configured limits, current usage, and pressure calculation for future System Health usage reporting.
14+
15+
## Requirement Checklist
16+
17+
- PASS - Configured limits are represented separately from current usage.
18+
- PASS - Current usage is represented separately and may be `NOT AVAILABLE`.
19+
- PASS - Current usage contract can also carry numeric usage when a provider integration supplies it later.
20+
- PASS - Pressure calculation is represented separately from limits and usage.
21+
- PASS - Pressure is calculated only when both a configured numeric limit and numeric usage exist.
22+
- PASS - Cloudflare billing integration is not required.
23+
- PASS - Provider-specific future integration points are documented in `docs_build/codex/decisions/system-health-usage-reporting.md`.
24+
- PASS - PR222-228 behavior remains intact.
25+
26+
## Validation Lane Report
27+
28+
PASS
29+
30+
- `node --check src/dev-runtime/server/local-api-router.mjs`
31+
- `node --check assets/theme-v2/js/admin-system-health.js`
32+
- `node --check tests/playwright/tools/AdminPlatformToolsWireframes.spec.mjs`
33+
- Static System Health contract validation for `configuredLimit`, `currentUsage`, and `pressureCalculation` separation.
34+
- Targeted Playwright System Health validation through `AdminPlatformToolsWireframes.spec.mjs`.
35+
36+
## Manual Validation Notes
37+
38+
PASS
39+
40+
- Confirmed the API payload includes separate `configuredLimit`, `currentUsage`, and `pressureCalculation` objects for each limit row.
41+
- Confirmed the documentation names R2 and Local DB future telemetry integration points.
42+
- Confirmed no Cloudflare billing dependency or credential exposure was added.
43+
44+
## Full Samples Decision
45+
46+
SKIP
47+
48+
Full samples smoke was not run because this PR only adds Admin System Health usage-reporting contract structure and documentation. Sample JSON, game samples, and `start_of_day` folders were not touched.
49+
50+
## Artifact Output
51+
52+
PASS
53+
54+
- Repo-structured delta ZIP: `tmp/PR_26168_230-system-health-live-usage-foundation_delta.zip`
55+
- Review diff: `docs_build/dev/reports/codex_review.diff`
56+
- Changed files: `docs_build/dev/reports/codex_changed_files.txt`

0 commit comments

Comments
 (0)