Clarify local API server entrypoint and stop static login API calls - PR_26158_033-local-server-entrypoint-cleanup

Author: ToolboxAid

assets/theme-v2/js/gamefoundry-partials.js

@@ -110,6 +110,7 @@
 
     const currentScript = document.currentScript || document.querySelector("script[src*='gamefoundry-partials.js']");
     const assetRoot = currentScript ? new URL("../", currentScript.src) : null;
+    const apiBackedLoginDiagnostic = "Use the API-backed local server for login.";
 
     function assetUrl(path) {
         if (!assetRoot) return rootPrefix() + path;
@@ -142,6 +143,11 @@
         return "Local server API route unavailable for " + method + " " + url + " (" + status + "). Start the API-backed local server route instead of a static-only server.";
     }
 
+    function isStaticLocalEntrypoint() {
+        return ["127.0.0.1", "localhost"].includes(window.location.hostname) &&
+            window.location.port === "5500";
+    }
+
     function missingSessionApiLoginState(diagnostic) {
         return {
             authenticated: false,
@@ -163,6 +169,9 @@
     }
 
     function localDevLoginState() {
+        if (isStaticLocalEntrypoint()) {
+            return missingSessionApiLoginState(apiBackedLoginDiagnostic);
+        }
         try {
             const request = new XMLHttpRequest();
             request.open("GET", "/api/session/current", false);

assets/theme-v2/js/login-session.js

@@ -13,6 +13,7 @@ const modeStatus = document.querySelector("[data-login-mode-status]");
 const userControls = document.querySelector("[data-login-user-controls]");
 const userStatus = document.querySelector("[data-login-user-status]");
 const continueLink = document.querySelector("[data-login-continue]");
+const apiBackedLoginDiagnostic = "Use the API-backed local server for login.";
 
 function currentReturnTo() {
   const params = new URLSearchParams(window.location.search);
@@ -95,6 +96,11 @@ function errorMessage(error) {
   return error instanceof Error ? error.message : String(error || "Session API unavailable.");
 }
 
+function isStaticLocalEntrypoint() {
+  return ["127.0.0.1", "localhost"].includes(window.location.hostname) &&
+    window.location.port === "5500";
+}
+
 function renderError(error) {
   const message = errorMessage(error);
   modeButtons.forEach((button) => {
@@ -122,6 +128,10 @@ function renderError(error) {
 }
 
 function render() {
+  if (isStaticLocalEntrypoint()) {
+    renderError(new Error(apiBackedLoginDiagnostic));
+    return;
+  }
   try {
     const session = getSessionCurrent();
     const mode = getSessionModes().find((item) => item.id === session.mode) || {
@@ -158,6 +168,10 @@ function render() {
 modeButtons.forEach((button) => {
   button.addEventListener("click", () => {
     const modeId = button.dataset.loginMode || "local-mem";
+    if (isStaticLocalEntrypoint()) {
+      renderError(new Error(apiBackedLoginDiagnostic));
+      return;
+    }
     try {
       setSessionMode(modeId);
       dispatchModeChanged();

docs_build/dev/reports/local-server-entrypoint-cleanup-report.md

@@ -0,0 +1,66 @@
+# PR_26158_033 Local Server Entrypoint Cleanup Report
+
+## Executive Summary
+
+Static `127.0.0.1:5500` is no longer treated as a supported login/session entrypoint. When `login.html` is opened from that static server, the page displays:
+
+`Use the API-backed local server for login.`
+
+The static 5500 path does not call `/api/session/current`, and Local Mem / Local DB controls remain disabled. API-backed Local Mem and Local DB behavior still works through the real local server.
+
+## Implementation
+
+| Area | Change | Evidence |
+| --- | --- | --- |
+| Login page runtime | Detects `127.0.0.1:5500` / `localhost:5500` before session API calls and renders the API-backed server diagnostic. | `assets/theme-v2/js/login-session.js` |
+| Shared header partial | Detects the unsupported static local entrypoint before header/account session reads, preventing `/api/session/current` from static 5500 pages. | `assets/theme-v2/js/gamefoundry-partials.js` |
+| Static Playwright | Uses `127.0.0.1:5500` explicitly and asserts no `/api/session/current` or `/api/session/` requests are made. | `tests/playwright/tools/StaticOnlyLoginApiRequired.spec.mjs` |
+
+## Requirement Checklist
+
+| Requirement | Evidence | Status |
+| --- | --- | --- |
+| Read `docs_build/dev/PROJECT_INSTRUCTIONS.md` first. | Read before implementation. | PASS |
+| Remove static `127.0.0.1:5500` as a supported login/session entrypoint. | Static 5500 detection now renders a blocked diagnostic before session API usage. | PASS |
+| Add visible page diagnostic: `Use the API-backed local server for login.` | Static 5500 Playwright verifies this exact text appears in login status. | PASS |
+| Do not call `/api/session/current` from static-only 5500 pages. | Static 5500 Playwright records all requests and asserts no `/api/session/current` or `/api/session/` requests. | PASS |
+| Do not make Local Mem or Local DB appear usable from static-only 5500. | Static 5500 Playwright verifies both mode buttons are disabled and not selected. | PASS |
+| Preserve API-backed Local Mem and Local DB behavior when served from the real local server. | `LoginSessionMode.spec.mjs` passed 5/5. | PASS |
+| Document `ShowOneChild.js` / `ActionableCoachmark` is browser-extension injected if repo audit confirms it. | Repo audit found no `ShowOneChild.js` file and no active repo HTML/JS load path; test noise filtering only treats those names as extension noise when an extension URL scheme is present. Therefore any observed runtime `ShowOneChild.js` / `ActionableCoachmark` error is browser-extension injected, not repo-served. | PASS |
+| Do not add shims or fallbacks. | No `ActionableCoachmark` global, static API fallback, or login fallback shim was added. | PASS |
+| Do not add UAT/Prod behavior. | No UAT/Prod login choices or adapter behavior changed. | PASS |
+
+## ShowOneChild / ActionableCoachmark Evidence
+
+| Check | Evidence | Result |
+| --- | --- | --- |
+| Repo-owned file search | `Get-ChildItem -Path . -Recurse -Filter ShowOneChild.js -File` returned no files. | PASS |
+| Active HTML/JS reference search | Scoped active HTML/JS `rg` found only `tests/helpers/browserExtensionNoise.mjs`, `tests/playwright/tools/ApiStaticRouteRecovery.spec.mjs`, and `tests/playwright/tools/StaticOnlyLoginApiRequired.spec.mjs`. | PASS |
+| Browser-extension injection conclusion | No repo-owned file or load path exists. The existing helper requires `chrome-extension://`, `moz-extension://`, or `extension://` before treating these script names as extension noise. | PASS |
+| Shim check | No shim or fallback global was added. | PASS |
+
+## Validation Commands
+
+| Command | Result |
+| --- | --- |
+| `node --check assets/theme-v2/js/login-session.js` | PASS |
+| `node --check assets/theme-v2/js/gamefoundry-partials.js` | PASS |
+| `node --check src/engine/api/server-api-client.js` | PASS |
+| `node --check tests/playwright/tools/StaticOnlyLoginApiRequired.spec.mjs` | PASS |
+| `npx playwright test tests/playwright/tools/StaticOnlyLoginApiRequired.spec.mjs` | PASS, 1/1 |
+| `npx playwright test tests/playwright/tools/LoginSessionMode.spec.mjs` | PASS, 5/5 |
+| `npx playwright test tests/playwright/tools/ToolboxRoutePages.spec.mjs` | PASS, 1/1 |
+| `git diff --check` | PASS, with Git line-ending warnings only |
+
+## Skipped Lanes
+
+| Lane | Decision | Reason |
+| --- | --- | --- |
+| AdminDbViewer Playwright | SKIP | DB Viewer routes and rendering were not changed. |
+| Full samples smoke | SKIP | No sample files, sample loader, or shared sample framework changed. |
+| Full Playwright suite | SKIP | Requested targeted lanes cover the changed login/session and toolbox-route surfaces. |
+
+## Notes
+
+- Playwright emitted Node SQLite experimental warnings from the existing Local DB path. They are not introduced by this PR and did not fail validation.
+- This PR intentionally does not add fallback behavior for static servers. The visible diagnostic directs users to the API-backed local server.

docs_build/dev/reports/playwright_v8_coverage_report.txt

@@ -14,7 +14,7 @@ Note: coverage entries are aggregated across every page/tool where coverageRepor
 Exercised tool entry points detected:
 (61%) Toolbox Index - exercised 3 runtime JS files
 (0%) Tool Template V2 - not exercised by this Playwright run
-(80%) Theme V2 Shared JS - exercised 3 runtime JS files
+(81%) Theme V2 Shared JS - exercised 3 runtime JS files
 
 Changed runtime JS files covered:
 (53%) src/engine/api/server-api-client.js - executed lines 159/159; executed functions 10/19
@@ -26,10 +26,10 @@ Files with executed line/function counts where available:
 (64%) assets/theme-v2/js/tool-display-mode.js - executed lines 201/201; executed functions 9/14
 (67%) admin/db-viewer.js - executed lines 53/53; executed functions 4/6
 (81%) toolbox/tool-registry-api-client.js - executed lines 148/148; executed functions 22/27
-(82%) assets/theme-v2/js/gamefoundry-partials.js - executed lines 434/434; executed functions 32/39
+(83%) assets/theme-v2/js/gamefoundry-partials.js - executed lines 442/442; executed functions 33/40
 (85%) src/engine/api/mock-db-viewer-ui.js - executed lines 510/510; executed functions 82/96
-(88%) assets/theme-v2/js/login-session.js - executed lines 169/169; executed functions 15/17
 (88%) src/engine/api/session-api-client.js - executed lines 34/34; executed functions 7/8
+(89%) assets/theme-v2/js/login-session.js - executed lines 182/182; executed functions 16/18
 (100%) toolbox/project-journey/project-journey-api-client.js - executed lines 12/12; executed functions 2/2
 
 Uncovered or low-coverage changed JS files:
@@ -38,5 +38,5 @@ Uncovered or low-coverage changed JS files:
 Changed JS files considered:
 (0%) tests/playwright/tools/StaticOnlyLoginApiRequired.spec.mjs - changed JS file not collected as browser runtime coverage
 (53%) src/engine/api/server-api-client.js - changed JS file with browser V8 coverage
-(82%) assets/theme-v2/js/gamefoundry-partials.js - changed JS file with browser V8 coverage
-(88%) assets/theme-v2/js/login-session.js - changed JS file with browser V8 coverage
+(83%) assets/theme-v2/js/gamefoundry-partials.js - changed JS file with browser V8 coverage
+(89%) assets/theme-v2/js/login-session.js - changed JS file with browser V8 coverage

docs_build/dev/reports/testing_lane_execution_report.md

@@ -1,24 +1,24 @@
-# PR_26158_032 Testing Lane Execution Report
+# PR_26158_033 Testing Lane Execution Report
 
 ## Lanes Run
 
 | Lane | Command | Result |
 | --- | --- | --- |
 | Changed-file syntax | `node --check assets/theme-v2/js/login-session.js`; `node --check assets/theme-v2/js/gamefoundry-partials.js`; `node --check src/engine/api/server-api-client.js`; `node --check tests/playwright/tools/StaticOnlyLoginApiRequired.spec.mjs` | PASS |
-| Static-only login API-required Playwright | `npx playwright test tests/playwright/tools/StaticOnlyLoginApiRequired.spec.mjs` | PASS, 1/1 |
+| Static 127.0.0.1:5500 login Playwright | `npx playwright test tests/playwright/tools/StaticOnlyLoginApiRequired.spec.mjs` | PASS, 1/1 |
 | LoginSessionMode Playwright | `npx playwright test tests/playwright/tools/LoginSessionMode.spec.mjs` | PASS, 5/5 |
 | ToolboxRoutePages Playwright | `npx playwright test tests/playwright/tools/ToolboxRoutePages.spec.mjs` | PASS, 1/1 |
-| Changed-file/static validation | `git diff --check` | PASS, with Git line-ending warning only |
+| Changed-file/static validation | `git diff --check` | PASS, with Git line-ending warnings only |
 | ShowOneChild/ActionableCoachmark reference audit | `Get-ChildItem -Path . -Recurse -Filter ShowOneChild.js -File`; scoped active HTML/JS `rg` | PASS |
 | Runtime JS V8 coverage | Playwright coverage generated by targeted runs | PASS/WARN; `docs_build/dev/reports/playwright_v8_coverage_report.txt` and `coverage_changed_js_guardrail.txt` generated. |
 
 ## Validation Notes
 
 | Check | Evidence | Result |
 | --- | --- | --- |
-| Static-only login shows visible API-required diagnostic. | `StaticOnlyLoginApiRequired.spec.mjs` serves `login.html` from a static-only `127.0.0.1` server and verifies `Session API required` plus the `/api/session/current` route-unavailable diagnostic. | PASS |
-| Static-only login modes do not silently work. | `StaticOnlyLoginApiRequired.spec.mjs` verifies Local Mem and Local DB buttons are disabled and not selected when `/api/session/current` is unavailable. | PASS |
-| Static-only login does not make mode/user session updates. | `StaticOnlyLoginApiRequired.spec.mjs` verifies no `/api/session/mode`, `/api/session/users`, or `/api/session/modes` requests occur. | PASS |
+| Static `127.0.0.1:5500` login shows visible API-backed server diagnostic. | `StaticOnlyLoginApiRequired.spec.mjs` serves `login.html` on `127.0.0.1:5500` and verifies `Use the API-backed local server for login.` is visible. | PASS |
+| Static `127.0.0.1:5500` login does not call `/api/session/current`. | `StaticOnlyLoginApiRequired.spec.mjs` records all requests and asserts no request URL contains `/api/session/current` or `/api/session/`. | PASS |
+| Static `127.0.0.1:5500` login modes do not appear usable. | Static lane verifies Local Mem and Local DB buttons are disabled and not selected. | PASS |
 | API-backed Local Mem and Local DB behavior still works. | `LoginSessionMode.spec.mjs` passed 5/5, including Local DB session behavior. | PASS |
 | Toolbox route pages still render. | `ToolboxRoutePages.spec.mjs` passed 1/1 for Project Journey, Colors, and Assets `/tools/...` aliases. | PASS |
 | Repo-owned ShowOneChild/ActionableCoachmark errors are absent. | Static-only Playwright asserts no non-extension `ShowOneChild`, `showOneChild`, or `ActionableCoachmark` error text in page or console errors. | PASS |
@@ -29,4 +29,4 @@
 | --- | --- | --- |
 | AdminDbViewer Playwright | SKIP | DB Viewer routes, DB adapters, and admin DB rendering were not changed. |
 | Full samples smoke | SKIP | No samples, shared sample loader, or sample framework files changed. |
-| Full Playwright suite | SKIP | Static-only login, API-backed login, toolbox route, syntax, static, and V8 coverage checks cover the changed surfaces. |
+| Full Playwright suite | SKIP | Static 5500 login, API-backed login, toolbox route, syntax, static, and V8 coverage checks cover the changed surfaces. |

tests/playwright/tools/StaticOnlyLoginApiRequired.spec.mjs

@@ -5,6 +5,8 @@ import { expect, test } from "@playwright/test";
 import { isBrowserExtensionNoise } from "../../helpers/browserExtensionNoise.mjs";
 import { workspaceV2CoverageReporter } from "../../helpers/workspaceV2CoverageReporter.mjs";
 
+const STATIC_LOCAL_PORT = 5500;
+
 function contentTypeForPath(filePath) {
   const extension = path.extname(filePath).toLowerCase();
   if (extension === ".html") return "text/html; charset=utf-8";
@@ -45,11 +47,11 @@ async function startStaticOnlyServer() {
 
   await new Promise((resolve, reject) => {
     server.once("error", reject);
-    server.listen(0, "127.0.0.1", resolve);
+    server.listen(STATIC_LOCAL_PORT, "127.0.0.1", resolve);
   });
   const address = server.address();
   if (!address || typeof address === "string") {
-    throw new Error("Failed to start static-only test server.");
+    throw new Error("Failed to start static-only 127.0.0.1:5500 test server.");
   }
   return {
     baseUrl: `http://127.0.0.1:${address.port}`,
@@ -63,12 +65,16 @@ test.afterAll(async () => {
   await workspaceV2CoverageReporter.writeReport();
 });
 
-test("static-only login requires API-backed session routes", async ({ page }) => {
+test("static 127.0.0.1:5500 login requires the API-backed local server", async ({ page }) => {
   const server = await startStaticOnlyServer();
+  const requests = [];
   const failedRequests = [];
   const pageErrors = [];
   const consoleErrors = [];
 
+  page.on("request", (request) => {
+    requests.push(request.url());
+  });
   page.on("response", (response) => {
     if (response.status() >= 400) {
       failedRequests.push(`${response.status()} ${response.url()}`);
@@ -101,13 +107,15 @@ test("static-only login requires API-backed session routes", async ({ page }) =>
     await expect(page.locator("[data-login-mode-title]")).toHaveText("Session API required");
     await expect(page.locator("[data-login-mode-description]")).toContainText("Start the API-backed local server");
     await expect(page.locator("[data-login-mode-status]")).toContainText("Login/session diagnostic");
-    await expect(page.locator("[data-login-mode-status]")).toContainText("Local server API route unavailable for GET /api/session/current (404)");
+    await expect(page.locator("[data-login-mode-status]")).toContainText("Use the API-backed local server for login.");
     await expect(page.locator("[data-login-user]")).toHaveCount(0);
     await expect(page.locator("[data-login-user-status]")).toContainText("No local users are available until /api/session responds");
     await expect(page.getByRole("button", { name: "UAT" })).toHaveCount(0);
     await expect(page.getByRole("button", { name: "Prod" })).toHaveCount(0);
 
-    expect(failedRequests.filter((request) => request.includes("/api/session/current")).length).toBeGreaterThan(0);
+    expect(requests.filter((request) => request.includes("/api/session/current"))).toEqual([]);
+    expect(requests.filter((request) => request.includes("/api/session/"))).toEqual([]);
+    expect(failedRequests.filter((request) => request.includes("/api/session/current"))).toEqual([]);
     expect(failedRequests.filter((request) => request.includes("/api/session/mode"))).toEqual([]);
     expect(failedRequests.filter((request) => request.includes("/api/session/users"))).toEqual([]);
     expect(failedRequests.filter((request) => request.includes("/api/session/modes"))).toEqual([]);