PR #28996: fix(dashboard): force JavaScript MIME on built SPA assets (#28987)

• Repository: NousResearch/hermes-agent
• Author: xxxigm
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/28996

Description (problem / solution / changelog)

What does this PR do?

On native Windows hermes dashboard renders as a blank page: the HTML shell loads fine, but the Vite ESM bundle comes back with Content-Type: text/plain; charset=utf-8 and Chrome refuses the module script under strict MIME checking ("Failed to load module script: Expected a JavaScript-or-Wasm module script…").

Root cause. Starlette's StaticFiles / FileResponse both pick Content-Type from mimetypes.guess_type. Python's mimetypes.init() reads the Windows registry, and many installers (older IIS / Visual Studio toolchains, even some antivirus suites) pollute HKEY_CLASSES_ROOT\.js with Content Type = text/plain. Python faithfully honours that, the browser refuses the module, the SPA never mounts.

Fix. At hermes_cli.web_server import time, explicitly override the strict mimetypes map for the asset extensions we actually serve — text/javascript for .js / .mjs / .cjs (per RFC 9239), plus correct values for .css, .json, .map, .svg, .wasm, .webp, .webmanifest, .woff, .woff2, .ico. mimetypes.add_type(..., strict=True) writes directly into the types_map dict that guess_type consults first, so our values win regardless of what the registry says. Idempotent.

Related Issue

Fixes #28987

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• hermes_cli/web_server.py — Add _WEB_ASSET_MIME_OVERRIDES (13 extensions) and _normalize_web_asset_mime_types(); invoke it once at module import. Long block comment documents the Windows registry corner case so the next maintainer doesn't accidentally "simplify" the override away.
• tests/hermes_cli/test_web_server_asset_mime.py — 23 new regression tests in four classes:
  • TestMimeNormalizationFunction — unit-level: simulate the Windows registry poison by writing text/plain into mimetypes.types_map[".js"], then assert the helper recovers a JavaScript MIME. Parametrised once-per-extension so a future drive-by removal is identified by name.
  • TestMimeNormalizationAtImport — reload hermes_cli.web_server from scratch under a poisoned map and assert the module-level call self-heals the import order.
  • TestStaticFileServingEndToEnd — drive a real starlette.testclient.TestClient against a synthetic Vite-style WEB_DIST. Asserts /assets/index-abc.js returns a JavaScript MIME and / still returns text/html (no accidental downgrade).
  • TestMimeOverrideRegistryShape — structural guards: every entry maps to a valid type/subtype pair and every extension starts with ..

How to Test

Reproduce the bug on Windows main:

hermes dashboard --no-open
# Browse to http://127.0.0.1:9119/ — blank page.
# Check the response header:
Invoke-WebRequest -UseBasicParsing http://127.0.0.1:9119/assets/index-<hash>.js |
  Select-Object -ExpandProperty Headers
# Content-Type: text/plain; charset=utf-8   ← the bug

After this PR:

hermes dashboard --no-open
# Dashboard renders normally.
Invoke-WebRequest -UseBasicParsing http://127.0.0.1:9119/assets/index-<hash>.js |
  Select-Object -ExpandProperty Headers
# Content-Type: text/javascript; charset=utf-8   ← fixed

Automated coverage (portable — reproduces the failure mode on any OS by directly poisoning the mimetypes map):

scripts/run_tests.sh tests/hermes_cli/test_web_server_asset_mime.py -q
# 23 passed in 5.45s

Quick manual sanity check on macOS:

.venv/bin/python -c "
import mimetypes
mimetypes.types_map['.js'] = 'text/plain'        # simulate Windows
print('before:', mimetypes.guess_type('a.js'))
import hermes_cli.web_server                     # trigger the fix
print('after: ', mimetypes.guess_type('a.js'))
"
# before: ('text/plain', None)
# after:  ('text/javascript', None)

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(dashboard):, test(dashboard):)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix
• I've run the relevant tests locally and they pass
• I've added tests for my changes (23 new regression tests)
• Tested on my platform: macOS 15.2 (Darwin 24.6.0). Test design reproduces the Windows-specific failure portably by poisoning the strict mimetypes map.

Documentation & Housekeeping

• N/A — no user-facing config / docs touched (the fix is invisible to operators who run a working setup; only fixes a regression for the affected install profile)
• N/A — no config keys added or changed
• N/A — no architecture or workflow changes
• Cross-platform — the fix is harmless on Linux/macOS (their stock mimetypes already report text/javascript for .js; we still upgrade .mjs and .map which aren't in Python's defaults)
• N/A — no tool descriptions / schemas changed

Screenshots / Logs

Browser console before the fix (per #28987):

Failed to load module script: Expected a JavaScript-or-Wasm module script
but the server responded with a MIME type of "text/plain". Strict MIME
type checking is enforced for module scripts per HTML spec.

Response headers before / after the fix (curl -I on a built Vite bundle):

# Before
HTTP/1.1 200 OK
content-type: text/plain; charset=utf-8

# After
HTTP/1.1 200 OK
content-type: text/javascript; charset=utf-8

Changed files

• hermes_cli/web_server.py (modified, +56/-0)
• tests/hermes_cli/test_web_server_asset_mime.py (added, +292/-0)