Skip to content

Commit 4ad73d1

Browse files
ToolboxAidToolboxAid
committed
Add local-only Admin Notes menu entry to dev-runtime viewer - PR_26158_044-admin-notes-local-menu-entry
1 parent c32ebe4 commit 4ad73d1

9 files changed

Lines changed: 161 additions & 20 deletions

‎docs_build/dev/reports/admin-notes-local-menu-entry-report.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# PR_26158_044 Admin Notes Local Menu Entry Report
2+
3+
## Summary
4+
5+
Added Admin Notes to the Admin menu only for the local/dev server by injecting the menu item into the served header partial from dev-runtime code. The checked-in Theme V2 header partial remains production-clean, and the link targets `/src/dev-runtime/admin/admin-notes.html`.
6+
7+
## Requirement Checklist
8+
9+
| Requirement | Evidence | Status |
10+
| --- | --- | --- |
11+
| Read `docs_build/dev/PROJECT_INSTRUCTIONS.md` first. | Read before implementation. | PASS |
12+
| Add Admin Notes to the Admin menu only when running the local/dev server. | `src/dev-runtime/admin/admin-notes-menu.mjs` injects the menu item only into the local/test server response for `header-nav.html`. | PASS |
13+
| Link Admin Notes to `/src/dev-runtime/admin/admin-notes.html`. | `ADMIN_NOTES_LOCAL_VIEWER_PATH`; LoginSessionMode Playwright `href` assertion. | PASS |
14+
| Do not add `/admin/notes.html` unless dev-only and excluded from UAT/PROD. | No `/admin/notes.html` was added; `Test-Path admin/notes.html` returned `False`. | PASS |
15+
| Do not modify `assets/theme-v2/partials/header-nav.html` with a production-visible hardcoded link. | Header partial remains free of Admin Notes strings; boundary/static audits pass. | PASS |
16+
| Keep Admin Notes implementation under `src/dev-runtime/admin/`. | Local menu injector, viewer, and directory handler live under `src/dev-runtime/admin/`. | PASS |
17+
| Verify UAT/PROD paths do not expose or import Admin Notes. | Static audits over `account admin assets toolbox src/engine src/shared` returned no matches. | PASS |
18+
| Do not modify `start_of_day` folders. | `git diff --name-only \| rg "(^|/)start_of_day(/|$)"` returned no matches. | PASS |
19+
| Run changed-file syntax checks. | `node --check` lane passed. | PASS |
20+
| Run AdminNotesLocalViewer Playwright. | `npx playwright test tests/playwright/tools/AdminNotesLocalViewer.spec.mjs` passed. | PASS |
21+
| Run LoginSessionMode/Admin menu Playwright proving the menu link appears locally only. | LoginSessionMode Admin test validates visible Admin link locally and hidden link for normal user; static source audit proves no production/public source exposure. | PASS |
22+
| Verify `/admin/notes.html` is not required and does not become production-facing. | Viewer link uses `/src/dev-runtime/admin/admin-notes.html`; production route absence check passed. | PASS |
23+
24+
## Changed Files
25+
26+
| File | Purpose |
27+
| --- | --- |
28+
| `src/dev-runtime/admin/admin-notes-menu.mjs` | Adds local/dev-only served-header Admin Notes menu injection. |
29+
| `src/dev-runtime/server/local-api-server.mjs` | Applies the local menu injection to the served header partial. |
30+
| `tests/helpers/playwrightRepoServer.mjs` | Applies the same injection in the Playwright local server. |
31+
| `tests/dev-runtime/AdminNotesBoundary.test.mjs` | Validates the production header stays clean and local injection exists only in the served copy. |
32+
| `tests/playwright/tools/LoginSessionMode.spec.mjs` | Validates the local Admin menu link is visible for Admin and hidden for normal users. |
33+
| `docs_build/dev/reports/testing_lane_execution_report.md` | Records PR044 validation lanes. |
34+
| `docs_build/dev/reports/playwright_v8_coverage_report.txt` | Records advisory V8 coverage from the scoped Playwright run. |
35+
| `docs_build/dev/reports/coverage_changed_js_guardrail.txt` | Records advisory changed-runtime-JS coverage guardrail. |
36+
37+
## Validation Evidence
38+
39+
| Validation | Result |
40+
| --- | --- |
41+
| Changed-file `node --check` lane | PASS |
42+
| `node --test tests/dev-runtime/AdminNotesBoundary.test.mjs` | PASS, 4/4 |
43+
| `npx playwright test tests/playwright/tools/AdminNotesLocalViewer.spec.mjs` | PASS |
44+
| `npx playwright test tests/playwright/tools/LoginSessionMode.spec.mjs --grep "Local users unlock their allowed Account and Admin pages"` | PASS |
45+
| Combined scoped Playwright run with `--workers=1` | PASS, 2/2 |
46+
| Public navigation exposure audit | PASS, no matches |
47+
| UAT/PROD dev-runtime admin import audit | PASS, no matches |
48+
| `Test-Path admin/notes.html` | PASS, returned `False` |
49+
| `git diff --check` | PASS, line-ending warnings only |
50+
51+
## Playwright Impact
52+
53+
Playwright impacted: Yes. This PR changes local/dev Admin menu behavior. Expected pass behavior is that local Admin sessions see `Admin Notes (Local Dev)` linking to `/src/dev-runtime/admin/admin-notes.html`, normal users do not see it, and the Admin Notes viewer still loads and opens notes. Expected fail behavior is a production-visible hardcoded header link, a missing local Admin menu item, or a broken viewer link.
54+
55+
## Manual Test Notes
56+
57+
1. Start the API-backed local server.
58+
2. Log in as Admin and open an Admin page.
59+
3. Confirm the Admin menu shows `Admin Notes (Local Dev)`.
60+
4. Open the link and confirm `/src/dev-runtime/admin/admin-notes.html` displays `docs_build/dev/admin-notes/index.txt`.
61+
5. Confirm `assets/theme-v2/partials/header-nav.html` does not contain an Admin Notes link.
62+
63+
## Skipped Lanes
64+
65+
- Full samples smoke: skipped because samples and game runtime were not touched.
66+
- Full Playwright suite: skipped because targeted Admin menu and Admin Notes local viewer lanes cover the changed behavior.

‎docs_build/dev/reports/coverage_changed_js_guardrail.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,11 @@ Source: Playwright/Chromium built-in V8 coverage from the active Playwright run.
77

88
Changed runtime JS files considered:
99
(0%) src/dev-runtime/admin/admin-notes-directory.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
10+
(0%) src/dev-runtime/admin/admin-notes-menu.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
1011
(0%) src/dev-runtime/server/local-api-server.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
1112
(96%) src/dev-runtime/admin/admin-notes-viewer.js - executed lines 501/501; executed functions 47/49
1213

1314
Guardrail warnings:
1415
(0%) src/dev-runtime/admin/admin-notes-directory.mjs - WARNING: changed runtime JS file missing from coverage; advisory only
16+
(0%) src/dev-runtime/admin/admin-notes-menu.mjs - WARNING: changed runtime JS file missing from coverage; advisory only
1517
(0%) src/dev-runtime/server/local-api-server.mjs - WARNING: changed runtime JS file missing from coverage; advisory only

‎docs_build/dev/reports/playwright_v8_coverage_report.txt‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,26 +14,30 @@ Note: coverage entries are aggregated across every page/tool where coverageRepor
1414
Exercised tool entry points detected:
1515
(0%) Toolbox Index - not exercised by this Playwright run
1616
(0%) Tool Template V2 - not exercised by this Playwright run
17-
(0%) Theme V2 Shared JS - not exercised by this Playwright run
17+
(75%) Theme V2 Shared JS - exercised 1 runtime JS files
1818

1919
Changed runtime JS files covered:
2020
(0%) src/dev-runtime/admin/admin-notes-directory.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
21+
(0%) src/dev-runtime/admin/admin-notes-menu.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
2122
(0%) src/dev-runtime/server/local-api-server.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
2223
(96%) src/dev-runtime/admin/admin-notes-viewer.js - executed lines 501/501; executed functions 47/49
2324

2425
Files with executed line/function counts where available:
26+
(75%) assets/theme-v2/js/gamefoundry-partials.js - executed lines 441/441; executed functions 30/40
2527
(96%) src/dev-runtime/admin/admin-notes-viewer.js - executed lines 501/501; executed functions 47/49
2628

2729
Uncovered or low-coverage changed JS files:
2830
(0%) src/dev-runtime/admin/admin-notes-directory.mjs - WARNING: uncovered changed runtime JS file; advisory only
31+
(0%) src/dev-runtime/admin/admin-notes-menu.mjs - WARNING: uncovered changed runtime JS file; advisory only
2932
(0%) src/dev-runtime/server/local-api-server.mjs - WARNING: uncovered changed runtime JS file; advisory only
3033

3134
Changed JS files considered:
32-
(0%) assets/theme-v2/js/gamefoundry-partials.js - changed JS file not collected as browser runtime coverage
3335
(0%) src/dev-runtime/admin/admin-notes-directory.mjs - changed JS file not collected as browser runtime coverage
36+
(0%) src/dev-runtime/admin/admin-notes-menu.mjs - changed JS file not collected as browser runtime coverage
3437
(0%) src/dev-runtime/server/local-api-server.mjs - changed JS file not collected as browser runtime coverage
3538
(0%) tests/dev-runtime/AdminNotesBoundary.test.mjs - changed JS file not collected as browser runtime coverage
3639
(0%) tests/helpers/playwrightRepoServer.mjs - changed JS file not collected as browser runtime coverage
3740
(0%) tests/playwright/tools/AdminNotesLocalViewer.spec.mjs - changed JS file not collected as browser runtime coverage
3841
(0%) tests/playwright/tools/LoginSessionMode.spec.mjs - changed JS file not collected as browser runtime coverage
42+
(75%) assets/theme-v2/js/gamefoundry-partials.js - changed JS file with browser V8 coverage
3943
(96%) src/dev-runtime/admin/admin-notes-viewer.js - changed JS file with browser V8 coverage

‎docs_build/dev/reports/testing_lane_execution_report.md‎

Lines changed: 23 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,45 @@
1-
# PR_26158_043 Testing Lane Execution Report
1+
# PR_26158_044 Testing Lane Execution Report
22

33
## Lanes Run
44

55
| Lane | Command | Result |
66
| --- | --- | --- |
7-
| Changed-file syntax checks | `node --check src/dev-runtime/admin/admin-notes-directory.mjs`; `node --check src/dev-runtime/admin/admin-notes-viewer.js`; `node --check src/dev-runtime/server/local-api-server.mjs`; `node --check tests/helpers/playwrightRepoServer.mjs`; `node --check tests/dev-runtime/AdminNotesBoundary.test.mjs`; `node --check tests/playwright/tools/AdminNotesLocalViewer.spec.mjs`; `node --check tests/playwright/tools/LoginSessionMode.spec.mjs`; `node --check assets/theme-v2/js/gamefoundry-partials.js` | PASS |
8-
| Admin Notes boundary validation | `node --test tests/dev-runtime/AdminNotesBoundary.test.mjs` | PASS, 3/3 |
9-
| Admin Notes local viewer validation | `npx playwright test tests/playwright/tools/AdminNotesLocalViewer.spec.mjs` | PASS |
10-
| Admin/login menu regression check | `npx playwright test tests/playwright/tools/LoginSessionMode.spec.mjs --grep "Local users unlock their allowed Account and Admin pages"` | PASS |
11-
| Header/navigation order check | `npx playwright test tests/playwright/tools/RootToolsFutureState.spec.mjs --grep "common header renders primary navigation order across active pages"` | PASS |
12-
| Public navigation exposure audit | `rg -n "docs_build/dev/admin-notes\|docs_build\\dev\\admin-notes\|admin-notes-dev\|Admin Notes" account admin assets toolbox src/engine src/shared --glob '!archive/v1-v2/**' --glob '!tmp/**'` | PASS, no matches |
7+
| Changed-file syntax checks | `node --check src/dev-runtime/admin/admin-notes-directory.mjs`; `node --check src/dev-runtime/admin/admin-notes-menu.mjs`; `node --check src/dev-runtime/admin/admin-notes-viewer.js`; `node --check src/dev-runtime/server/local-api-server.mjs`; `node --check tests/helpers/playwrightRepoServer.mjs`; `node --check tests/dev-runtime/AdminNotesBoundary.test.mjs`; `node --check tests/playwright/tools/AdminNotesLocalViewer.spec.mjs`; `node --check tests/playwright/tools/LoginSessionMode.spec.mjs`; `node --check assets/theme-v2/js/gamefoundry-partials.js` | PASS |
8+
| Admin Notes boundary/local menu validation | `node --test tests/dev-runtime/AdminNotesBoundary.test.mjs` | PASS, 4/4 |
9+
| Admin Notes local viewer Playwright | `npx playwright test tests/playwright/tools/AdminNotesLocalViewer.spec.mjs` | PASS |
10+
| Login/Admin local menu Playwright | `npx playwright test tests/playwright/tools/LoginSessionMode.spec.mjs --grep "Local users unlock their allowed Account and Admin pages"` | PASS |
11+
| Combined scoped Playwright and V8 coverage | `npx playwright test tests/playwright/tools/AdminNotesLocalViewer.spec.mjs tests/playwright/tools/LoginSessionMode.spec.mjs --grep "Admin Notes local viewer loads\|Local users unlock" --workers=1` | PASS, 2/2 |
12+
| Public navigation exposure audit | `rg -n "docs_build/dev/admin-notes\|docs_build\\dev\\admin-notes\|admin-notes-dev\|data-admin-notes-local-menu\|Admin Notes" account admin assets toolbox src/engine src/shared --glob '!archive/v1-v2/**' --glob '!tmp/**'` | PASS, no matches |
1313
| UAT/PROD dev-runtime admin import audit | `rg -n "src/dev-runtime/admin\|src\\dev-runtime\\admin" account admin assets toolbox src/engine src/shared --glob '!archive/v1-v2/**' --glob '!tmp/**'` | PASS, no matches |
14+
| Production route absence check | `Test-Path admin/notes.html` | PASS, returned `False` |
1415
| Changed-file whitespace/static validation | `git diff --check` | PASS, Git line-ending warnings only |
1516
| start_of_day protection check | `git diff --name-only \| rg "(^|/)start_of_day(/|$)"` | PASS, no matches |
1617

1718
## Validation Notes
1819

1920
| Check | Evidence | Result |
2021
| --- | --- | --- |
21-
| `docs_build/dev/admin-notes/index.txt` displays by default. | AdminNotesLocalViewer Playwright validates title/status and note content. | PASS |
22-
| Folders and files under `docs_build/dev/admin-notes/` render as selectable links. | AdminNotesLocalViewer Playwright validates `notes/`, `other/`, `quick-reference.txt`, and `sample.txt`. | PASS |
23-
| Selecting `.txt` content displays selected note content. | AdminNotesLocalViewer Playwright opens `quick-reference.txt` and `other/index.txt`. | PASS |
24-
| Header nav no longer links directly to Admin Notes content. | Boundary test and static exposure audit. | PASS |
25-
| Admin Notes implementation stays dev-only. | Viewer page, JS, and directory handler are under `src/dev-runtime/admin/`. | PASS |
26-
| UAT/PROD candidate paths do not import `src/dev-runtime/admin/`. | Static import audit returned no matches. | PASS |
27-
| Playwright V8 coverage report produced for changed runtime JS. | `docs_build/dev/reports/playwright_v8_coverage_report.txt`; `src/dev-runtime/admin/admin-notes-viewer.js` covered at 96%. | PASS |
22+
| Admin Notes appears in the Admin menu when served from the local/dev server. | `tests/playwright/tools/LoginSessionMode.spec.mjs` asserts `data-admin-notes-local-menu` is visible for Admin. | PASS |
23+
| Admin Notes link targets `/src/dev-runtime/admin/admin-notes.html`. | LoginSessionMode Playwright validates the link `href`. | PASS |
24+
| Non-admin users do not see the Admin Notes menu link. | LoginSessionMode Playwright validates the link is hidden when the Admin menu is hidden. | PASS |
25+
| `assets/theme-v2/partials/header-nav.html` does not contain a production-visible Admin Notes hardcoded link. | AdminNotesBoundary node test and static `rg` exposure audit. | PASS |
26+
| Local injection is dev-runtime owned. | `src/dev-runtime/admin/admin-notes-menu.mjs` injects only the served header copy in the local/test server. | PASS |
27+
| `/admin/notes.html` was not added or required. | `Test-Path admin/notes.html` returned `False`. | PASS |
28+
| UAT/PROD candidate paths do not expose or import Admin Notes. | Static exposure/import audits returned no matches. | PASS |
29+
| Admin Notes viewer behavior remains intact. | AdminNotesLocalViewer Playwright still loads `index.txt` and opens folder/file notes. | PASS |
30+
31+
## Retry Note
32+
33+
| Command | Result | Disposition |
34+
| --- | --- | --- |
35+
| Initial parallel run of AdminNotesLocalViewer and LoginSessionMode Playwright lanes | LoginSessionMode hit Playwright artifact-copy `ENOENT` while parallel artifact writers were active. | Infrastructure artifact contention. The same LoginSessionMode lane passed when rerun alone, and both scoped tests passed together with `--workers=1`. |
2836

2937
## Skipped Lanes
3038

3139
| Lane | Decision | Reason |
3240
| --- | --- | --- |
3341
| Full samples smoke | SKIP | No sample loader/framework, game runtime, or sample data changed. |
34-
| Full Playwright suite | SKIP | PR scope is limited to the Admin Notes local viewer and shared header link removal; targeted viewer/header/auth lanes passed. |
42+
| Full Playwright suite | SKIP | PR scope is limited to local/dev Admin menu injection and existing Admin Notes local viewer behavior; targeted viewer/menu lanes passed. |
3543
| Full Node suite | SKIP | Targeted syntax checks and AdminNotesBoundary node test cover the changed dev-runtime/static boundary. |
3644

3745
## Notes

‎src/dev-runtime/admin/admin-notes-menu.mjs‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
import path from "node:path";
2+
3+
export const ADMIN_NOTES_LOCAL_VIEWER_PATH = "/src/dev-runtime/admin/admin-notes.html";
4+
export const ADMIN_NOTES_LOCAL_MENU_LABEL = "Admin Notes (Local Dev)";
5+
6+
const HEADER_PARTIAL_PATH = "assets/theme-v2/partials/header-nav.html";
7+
const INSERT_BEFORE = ' <a data-nav-link data-route="admin-analytics" href="admin/analytics.html">Analytics</a>';
8+
const LOCAL_MENU_LINK = ` <a data-admin-notes-local-menu href="${ADMIN_NOTES_LOCAL_VIEWER_PATH}">${ADMIN_NOTES_LOCAL_MENU_LABEL}</a>`;
9+
10+
function repoRelativePath(repoRoot, targetPath) {
11+
return path.relative(repoRoot, targetPath).replaceAll(path.sep, "/");
12+
}
13+
14+
export function localAdminNotesMenuContent(repoRoot, targetPath, fileContents) {
15+
if (repoRelativePath(repoRoot, targetPath) !== HEADER_PARTIAL_PATH) {
16+
return fileContents;
17+
}
18+
const source = fileContents.toString("utf8");
19+
if (source.includes("data-admin-notes-local-menu")) {
20+
return fileContents;
21+
}
22+
if (!source.includes(INSERT_BEFORE)) {
23+
return fileContents;
24+
}
25+
return Buffer.from(source.replace(INSERT_BEFORE, `${LOCAL_MENU_LINK}\n${INSERT_BEFORE}`), "utf8");
26+
}

‎src/dev-runtime/server/local-api-server.mjs‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import http from "node:http";
33
import path from "node:path";
44
import { fileURLToPath } from "node:url";
55
import { handleAdminNotesDirectoryRequest } from "../admin/admin-notes-directory.mjs";
6+
import { localAdminNotesMenuContent } from "../admin/admin-notes-menu.mjs";
67
import { createMockApiRouter } from "./mock-api-router.mjs";
78

89
const __filename = fileURLToPath(import.meta.url);
@@ -61,9 +62,10 @@ export async function startLocalApiServer({
6162
targetPath = path.join(targetPath, "index.html");
6263
}
6364
const fileContents = await fs.readFile(targetPath);
65+
const responseContents = localAdminNotesMenuContent(repoRoot, targetPath, fileContents);
6466
response.statusCode = 200;
6567
response.setHeader("Content-Type", contentTypeForPath(targetPath));
66-
response.end(fileContents);
68+
response.end(responseContents);
6769
} catch {
6870
response.statusCode = 404;
6971
response.end("Not Found");

0 commit comments

Comments
 (0)