fix(plugins): make a module plugin actually re-evaluate on reload (#879) (#897)

A plugin reload silently did nothing for scriptType:"module" plugins. ES modules are
evaluated ONCE PER URL PER DOCUMENT, so re-inserting a <script type="module"> whose src
the module map has already seen fires `load` without re-running the body — and the loader
then recorded the reload as applied. A no-op that reported success.

THE ISSUE UNDERSTATES IT. #879 says "upgrades are fine — a new version yields a new URL".
That is true of screen.js and FALSE of the plugin. I drove a real browser through
install(1.0.0) -> upgrade(1.1.0) -> rollback(1.0.0), counting evaluations of src/main.js:

    ONE.

Not three, not two. The upgrade re-runs the one-line screen.js shim at its new ?v= URL;
the shim does `import './src/main.js'`; a relative specifier resolves against the base URL
WITH THE QUERY DROPPED; that is the same URL as before; the module map hands back the
already-evaluated v1.0.0 module. The plugin's own code never re-ran. Busting the entry
point cannot fix this, whatever token you hang off it.

So the token goes in the PATH: /api/plugins/<id>/g/<n>/screen.js. From there
'./src/main.js' resolves to /api/plugins/<id>/g/<n>/src/main.js — every relative import
inherits it, at every depth, for free. No import-specifier rewriting (which could never
see `import(expr)` anyway). Same browser drive after the fix: THREE evaluations.

Keyed on the plugin ID, not id@version: EVERY re-load of a module plugin needs a fresh
path, not just a rollback. First load keeps the stable ?v= URL, so the ETag/304 live-edit
caching the R0 rails depend on is untouched. Classic-script plugins are not affected and
never take a /g/ path.

━━━ A PATH REWRITE, NOT TWO MIRRORED ROUTES ━━━

Codex caught this, and it was right. The token shifts the BASE URL, so EVERYTHING the
module graph resolves relatively moves with it — not only imports.
`new URL('../assets/worklet.js', import.meta.url)` from /api/plugins/x/g/1/src/main.js
resolves to /api/plugins/x/g/1/assets/worklet.js. Mirroring only screen.js and src/ would
have fixed imports and 404'd every asset, worklet and wasm file the graph reaches — and
would have broken again the next time someone added a plugin route.

So the /g/<token> segment is STRIPPED BEFORE ROUTING. Every plugin route, present and
future, works under the prefix with no extra wiring. The token is opaque and never joined
into a filesystem path, so containment still rests entirely on the same safe_join.

Codex then caught a [P3] in that: eagerly re-encoding raw_path with latin-1 raises
UnicodeEncodeError on a valid plugin file like src/工具.js, 500ing a request the plain
route serves fine. raw_path is informational and Starlette routes on scope["path"], so the
mutation is simply gone — and leaving raw_path as the client sent it is more truthful for
logs anyway.

TESTS. tests/js/plugin_module_rollback.test.js (5) + 8 in test_plugin_src_route.py:
identical bytes under the prefix, the whole graph one and two levels deep, ASSETS (the
Codex [P2]), every plugin route, non-ASCII filenames (the [P3]), an opaque token, and
containment asserted as PARITY with the un-prefixed route rather than a guessed 404 —
`../screen.js` legitimately 200s on both, because the URL normalises before routing.
All bite-tested: reverting the fix fails the rollback tests, disabling the rewrite fails
the asset tests.

Two harnesses re-anchored on `script.src = _pluginScriptUrl(` — the URL literal they keyed
on now lives in the helper, further down the file, so their slice ran off the end.

node 1045, pytest 2404, ESLint 0, Codex 0.

Closes #879

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

plugins/__init__.py

@@ -6,6 +6,7 @@ import json
 import logging
 import mimetypes
 import os
+import re
 import subprocess
 import sys
 import threading
@@ -2384,6 +2385,53 @@ def register_plugin_api(app: FastAPI):
                     return _plugin_file_response(request, script_file, "application/javascript")
         return Response("", status_code=404)
 
+    # ── Module-graph cache busting (#879) ────────────────────────────────
+    #
+    # ES modules are evaluated ONCE PER URL PER DOCUMENT. Re-inserting a
+    # <script type="module"> whose src the module map has already seen fires
+    # `load` but does NOT re-run the body. So re-loading a plugin — a rollback,
+    # and (see below) an upgrade too — silently kept the OLD module live while
+    # the loader recorded success: a no-op that reported it worked.
+    #
+    # Busting the ENTRY url does not help. A module plugin's screen.js is a
+    # one-line `import './src/main.js'`, and a relative specifier resolves
+    # against the base URL WITH THE QUERY DROPPED — so a ?v= token never reaches
+    # the graph. Driving a real browser through install -> upgrade -> rollback and
+    # counting evaluations of src/main.js gives ONE. The upgrade re-runs the shim
+    # at its new ?v= URL; the shim imports './src/main.js'; that resolves to the
+    # same URL; the module map returns the already-evaluated old module.
+    #
+    # So the token goes in the PATH: /api/plugins/<id>/g/<n>/screen.js. Every
+    # relative import inherits it at every depth — for free, with no
+    # import-specifier rewriting (which could never see `import(expr)` anyway).
+    #
+    # WHY A PATH REWRITE AND NOT TWO MIRRORED ROUTES. The token shifts the base
+    # URL, so EVERYTHING a module resolves relatively moves with it — not just
+    # imports. `new URL('../assets/worklet.js', import.meta.url)` from
+    # /api/plugins/x/g/1/src/main.js resolves to /api/plugins/x/g/1/assets/... .
+    # Mirroring only screen.js and src/ would fix imports and 404 every asset,
+    # worklet and wasm file the graph reaches — and would silently break again the
+    # next time someone adds a plugin route. Stripping the segment before routing
+    # makes every plugin route, present and future, work under the prefix.
+    #
+    # The token is opaque: it is never joined into a filesystem path (and is gone
+    # by the time any handler runs), so containment still rests entirely on the
+    # same safe_join the un-prefixed routes use.
+    _GEN_PREFIX = re.compile(r"^(/api/plugins/[^/]+)/g/[^/]+(/.+)$")
+
+    @app.middleware("http")
+    async def _strip_plugin_generation_prefix(request: Request, call_next):
+        m = _GEN_PREFIX.match(request.scope.get("path", ""))
+        if m:
+            # Starlette routes on scope["path"] alone. raw_path is deliberately left
+            # ALONE: it is informational, and re-encoding the rewritten str back to
+            # bytes would have to guess a codec — `.encode("latin-1")` raises
+            # UnicodeEncodeError on a perfectly valid plugin file like src/工具.js,
+            # 500ing a request the un-prefixed route serves fine. Leaving raw_path as
+            # the client actually sent it is also simply more truthful for logs.
+            request.scope["path"] = m.group(1) + m.group(2)
+        return await call_next(request)
+
     @app.get("/api/plugins/{plugin_id}/settings.html")
     def plugin_settings_html(plugin_id: str):
         with PLUGINS_LOCK: