Webapp Load Fixer

Overview

Fix locally-run web apps (Node static server + vanilla JS SPA, e.g. the user's ERP / LIMS
systems) that report "can't enter" / "can't use". The failure is almost never a single bug —
it is usually one of four recurring causes. Work the diagnostic decision tree top-down, fix
the real cause, then verify in a real browser before declaring done.

When To Use

• User says "进不去 / 无法进入 / 打不开 / 用不了 / 无法使用" about a local app.
• A localhost:<port> page is blank, stuck on a login mask, or a modal blocks all clicks.
• After an AI session ends, a previously-working local app stops responding.

Diagnostic Decision Tree (work top-down)

1. Is the server listening? netstat -ano | grep ":<port>" | grep LISTEN
   - Not listening → Cause 1 (start the server).
   - Listening → continue.
2. Does a trivial HTTP GET of the homepage succeed? curl -s -o /dev/null -w "%{http_code}" http://localhost:<port>/
   - Non-200 → server crashed or wrong port → Cause 1.
   - 200 → continue.
3. Do static assets return 200? curl each /js/*.js, /css/*.css.
   - Any non-200 → path/route bug → fix server static routes.
   - All 200 → continue (this is the "service is fine but UI is broken" case).
4. Is there a login/mask overlay stuck on screen? Read the CSS for .login-mask /
   .modal-mask / any *-mask and check whether it sets display: flex|grid|block. If so and
   the HTML hides it via the hidden attribute → Cause 2.
5. Did code change recently but the browser still shows the bug? Check whether the static
   server sets Cache-Control. If absent → Cause 3 (stale cache).
6. Did it work during the session, then die after the session closed? → Cause 4
   (process recycled; add autostart).

Root Cause 1 — Server process not running

The Node server was never started, or its process was recycled (e.g. when the AI session
ends). Start it in the background and verify the login chain.

# locate the entry file (often server.js) and start it with managed node
cd "<app-dir>"
"/c/Users/DJHdj/.workbuddy/binaries/node/versions/22.22.2/node.exe" server.js &
sleep 1
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://localhost:<port>/
# verify login chain
curl -s -X POST http://localhost:<port>/api/login -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}' | \
  "/c/Users/DJHdj/.workbuddy/binaries/node/versions/22.22.2/node.exe" \
  -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{const j=JSON.parse(d);console.log('token:',j.token?'OK':'NONE','| user:',j.user&&j.user.name)}catch(e){console.log('ERR',d.slice(0,150))}})"

Note the demo accounts typically live on the login page as clickable chips; read
index.html to get the real username/password and the #login-user / #login-pwd /
#login-btn selectors.

Root Cause 2 — CSS [hidden] overridden by display:flex

Classic bug. A login mask or modal is hidden in JS via el.hidden = true, which relies on the
user-agent rule [hidden] { display: none }. But if the CSS sets .login-mask { display: flex }, that declaration outranks the UA [hidden] rule, so the element never disappears
and sits on top (high z-index) blocking the whole UI — "can't enter".

Fix: add a global override at the very top of the stylesheet (before :root):

[hidden] { display: none !important; }

Also check for missing button/utility classes the SPA references (e.g. .btn-warning) and add
them. After editing CSS/JS, pair this fix with Cause 3 so the browser actually picks it up.

Root Cause 3 — Browser serving stale CSS/JS (no cache headers)

If server.js serves static files without Cache-Control, the browser caches the
pre-fix assets. Every refresh reloads the broken old version. Force freshness by emitting
no-cache headers from the static handler:

res.writeHead(200, {
  'Content-Type': STATIC_TYPES[ext] || 'application/octet-stream',
  'Cache-Control': 'no-store, no-cache, must-revalidate, max-age=0',
  'Pragma': 'no-cache',
  'Expires': '0'
});
res.end(content);

Restart the server after editing. The user can then do a normal refresh (no forced Ctrl+F5
needed). Verify via curl -s -D - -o /dev/null http://localhost:<port>/css/style.css | grep -i cache-control.

Root Cause 4 — Process recycled when the AI session ends

A background server started inside an AI session is killed when the session closes, so the
next time the user opens the app it is "down". Make it survive by auto-starting on Windows
login.

> Environment quirk: this sandbox blocks reg.exe and wscript.exe as LOLBins, so the
> HKCU\Run registry key cannot be written by the agent. Use the Startup folder instead —
> it is functionally equivalent (runs on user login). See references/windows-autostart.md
> and the template scripts/windows_autostart.bat.

The bat does an idempotent netstat check (if the port is already LISTENING, exit) then
start "" /min launches the node server with absolute paths. Prefer generating a
project-specific bat with the included generator instead of hand-editing paths:

node scripts/make_autostart.js --app "<abs-path-to-server.js>" --port 3000 \
  --name "My App" --out "<dir>/start-myapp.bat" --install   # --install -> Startup folder

The generator validates paths, auto-detects the managed node binary, and writes the bat
CRLF/ASCII-clean. The template scripts/windows_autostart.bat also works standalone —
just edit its 4-line CONFIG block (APP_NAME / PORT / APP / NODE). To verify
end-to-end: kill the running server PID, run the bat (bash can execute it directly), curl
the homepage for HTTP 200, run it again to confirm the "already running" guard.

Verification — Real browser via agent-browser

This is the definitive check: it catches runtime errors that curl/headless JSON cannot.

export PATH="/c/Users/DJHdj/.workbuddy/binaries/node/versions/22.22.2:$PATH"
# first time only — downloads Chrome (~2.5 min, retry-safe):
agent-browser install
agent-browser open http://localhost:<port>/
agent-browser console --clear; agent-browser errors --clear
agent-browser fill "#login-user" admin
agent-browser fill "#login-pwd" admin123
agent-browser click "#login-btn"
agent-browser wait "#content"
# assert the mask is gone and dashboard rendered:
agent-browser eval "document.getElementById('login-mask').hidden + '|title=' + document.getElementById('page-title').textContent + '|len=' + document.getElementById('content').innerHTML.length"
agent-browser errors      # must be empty
agent-browser console     # must be empty
agent-browser screenshot "<app-dir>/verify.png"

Interpretation: login-mask.hidden === true, a non-empty #content, and empty errors
and console mean the app is fully working. If errors appear, paste them and fix the
underlying JS; if the mask is still visible, re-check Cause 2.

> Pitfall — clicking the last nav items may silently miss. When you agent-browser click ".nav-item[data-id='finance']" on a SPA whose nav re-renders on every route change, the click can land before the new element is attached (or scroll/race), so the page just stays on the previous module — looking like the module is broken when it is not. If a trailing module (e.g. finance/statement at the end of the nav) appears to render the wrong content with no errors, do NOT conclude it is a bug. Re-verify from inside the page:
> js > agent-browser eval "navigate('finance'); 'called'" // or document.querySelector('.nav-item[data-id=statement]').click() > // then re-read title + content after a short sleep >
> If navigate(id) / .click() switch correctly, the module is fine and the earlier miss was a tooling artifact.

Fallback — Node vm headless harness

When the Chrome download is too slow/unavailable, validate the front-end JS logic without a
browser using scripts/headless_check.js: it loads api.js/ui.js/app.js into a vm
context with a mocked DOM + fetch and runs boot(), capturing any thrown error. This proves
the logic is sound but will NOT catch CSS-rendering bugs (Cause 2) — always prefer the real
browser when available.

Resources

• scripts/headless_check.js — Node vm harness that loads the three SPA JS files, mocks DOM
  and fetch, runs boot(), and reports runtime errors. Adapt the mock to the app's globals.
• scripts/make_autostart.js — generator that emits a project-specific autostart .bat
  from --app/--port/--name/--node/--out flags; --install copies it into the Windows
  Startup folder. Use this instead of hand-editing bat paths (also passes .bat-rejecting
  upload pipelines since only the .js ships).
• scripts/windows_autostart.bat — idempotent autostart template (netstat guard + start /min
  node) with a 4-line CONFIG block (APP_NAME/PORT/APP/NODE) for manual editing.
• references/windows-autostart.md — why HKCU\Run is blocked here and the Startup-folder
  alternative, generator usage, and the exact paths used for the user's ERP/LIMS.