docs(plugins): update docs for QuickJS bootstrap refactor

DavidBabinec · claude · DavidBabinec · commit a6bc979ee67c · 2026-06-06T17:46:26.000+02:00
- Fix stale server/plugins/quickjsHost.ts path → server/plugins/quickjs/vm.ts
  across plugin-system.md, README.md, architecture.md, server.md
- Add bootstrap source paths to plugin-system.md Related section
  (bootstrap/src/, bootstrap/generated/, scripts/sync-plugin-bootstrap.ts)
- Add new gate and test files to plugin-system.md Related section:
  plugin-bootstrap-fresh.test.ts, pluginVmPermissions.test.ts,
  pluginVmLoopDispatch.test.ts
- Add plugin-bootstrap-fresh.test.ts to reference/architecture-tests.md
  Plugin system table

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/docs/README.md b/docs/README.md
@@ -221,7 +221,7 @@ Quick map from "where do I look for X?" to the canonical file:
 | Plugin SDK                       | `src/core/plugin-sdk/`                                   |
 | Plugin permission catalog        | `src/core/plugin-sdk/capabilities.ts`                    |
 | Plugin manifest parser           | `src/core/plugins/manifest.ts`                           |
-| Plugin sandbox host              | `server/plugins/quickjsHost.ts`, `server/plugins/modulePackVm.ts` |
+| Plugin sandbox host              | `server/plugins/quickjs/vm.ts`, `server/plugins/modulePackVm.ts` |
 | Publisher                        | `src/core/publisher/`                                    |
 | TypeBox helpers                  | `src/core/utils/typeboxHelpers.ts`                       |
 | Error message extraction         | `src/core/utils/errorMessage.ts`                         |
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -268,7 +268,7 @@ Key properties:
 
 Plugins are zip packages containing a `plugin.json` manifest and bundled entrypoints. The host runs plugin code in a **QuickJS-WASM sandbox**:
 
-- `entrypoints.server` runs in `server/plugins/quickjsHost.ts`
+- `entrypoints.server` runs in `server/plugins/quickjs/vm.ts`
 - `entrypoints.modules` (canvas module packs) run in `server/plugins/modulePackVm.ts`
 - Author-facing API lives in `src/core/plugin-sdk/`
 - Host-side runtime (install, activate, deactivate, uninstall) lives in `src/core/plugins/`
diff --git a/docs/features/plugin-system.md b/docs/features/plugin-system.md
@@ -9,7 +9,7 @@ A plugin is a zip package containing a `plugin.json` manifest and one or more Ja
 ## TL;DR
 
 - **Package shape:** a zip containing `plugin.json` plus entrypoint bundles (`server/index.js`, `editor/index.js`, `admin/dashboard.js`, `modules/index.js`, `frontend/*.js`, optional `pack/site.json`).
-- **Runtime:** server entrypoint runs in **QuickJS-WASM** (`server/plugins/quickjsHost.ts`). Canvas module packs run in a separate QuickJS VM (`server/plugins/modulePackVm.ts`). No host APIs leak.
+- **Runtime:** server entrypoint runs in **QuickJS-WASM** (`server/plugins/quickjs/vm.ts`). Canvas module packs run in a separate QuickJS VM (`server/plugins/modulePackVm.ts`). No host APIs leak.
 - **SDK:** every API call goes through `api` — `api.plugin.*` for plugin metadata + logging, `api.cms.*` for routes, storage, hooks, loops, settings, schedule, pages.
 - **Lifecycle:** `install` → `activate` → (optionally `deactivate` / `migrate`) → `uninstall`. Each hook is async-capable and isolated; if one throws, the host rolls back and parks the plugin in `error`.
 - **Permissions:** declared in `plugin.json`, approved by the site owner at install time, enforced by the SDK at runtime. Outbound network also requires `networkAllowedHosts` allowlist.
@@ -677,7 +677,10 @@ Manifest:
   - `src/core/plugins/manifest.ts` — manifest parser + validator
   - `src/core/plugins/` — host-side runtime
   - `server/plugins/runtime.ts` — boot-time plugin activation
-  - `server/plugins/quickjsHost.ts` — server entrypoint sandbox
+  - `server/plugins/quickjs/vm.ts` — server entrypoint sandbox (QuickJS VM factory)
+  - `server/plugins/quickjs/bootstrap/src/` — bootstrap TypeScript source (authored, typed, lintable)
+  - `server/plugins/quickjs/bootstrap/generated/` — committed bootstrap artifacts (regenerate with `bun run bootstrap:sync`)
+  - `scripts/sync-plugin-bootstrap.ts` — bundler that writes the generated artifacts
   - `server/plugins/modulePackVm.ts` — module pack VM constructor
   - `src/core/plugins/modulePackLoader.ts` — module pack lifecycle coordinator (activate, deactivate, reset, VM tracking)
   - `server/plugins/package.ts` — install / `assertSandboxSafe`
@@ -696,5 +699,8 @@ Manifest:
   - `src/__tests__/architecture/plugin-schedule-invariants.test.ts`
   - `src/__tests__/architecture/no-plugin-tab-shells.test.ts`
   - `src/__tests__/architecture/sandbox-crypto-bridge.test.ts`
+  - `src/__tests__/architecture/plugin-bootstrap-fresh.test.ts` — generated bootstrap artifacts match source; fails if `bun run bootstrap:sync` is needed
   - `src/__tests__/plugins/gatedFetchSsrf.test.ts` — SSRF guards: allowlist, DNS rebinding, redirect re-validation, redirect cap
   - `src/__tests__/plugins/pluginModulePack.test.ts` — module pack activation, re-activation, deactivation, and VM disposal
+  - `src/__tests__/server/pluginVmPermissions.test.ts` — VM-side permission check: declared-but-not-granted permissions are denied at the VM boundary before host dispatch
+  - `src/__tests__/server/pluginVmLoopDispatch.test.ts` — loop fetch/preview dispatcher robustness (no-return fallbacks, async-preview detection)
diff --git a/docs/reference/architecture-tests.md b/docs/reference/architecture-tests.md
@@ -129,6 +129,7 @@ See [docs/features/spotlight.md](../features/spotlight.md).
 
 | Test                                          | What it enforces                                                                 |
 |-----------------------------------------------|----------------------------------------------------------------------------------|
+| `plugin-bootstrap-fresh.test.ts`              | Generated bootstrap artifacts in `bootstrap/generated/` match a fresh bundle of `bootstrap/src/`. Fails if `bun run bootstrap:sync` is needed. |
 | `plugin-sandbox-invariants.test.ts`           | No `node:`, `bun:`, `require(`, `process.binding` in plugin bundles. Sandbox-safe assertions.|
 | `plugin-boot-resilience.test.ts`              | One bad plugin doesn't bring the server down. Crashes are isolated.              |
 | `plugin-cms-content-surface.test.ts`          | All five `cms.content.*` permissions are wired across all sync-points (permission values, capability matrix, permission alias builder, SDK type surface, host-side dispatch). |
diff --git a/docs/server.md b/docs/server.md
@@ -14,7 +14,7 @@ The server is a single `Bun.serve` process that boots the DB, runs migrations, a
 - **Auth:** session cookie (`SESSION_COOKIE_NAME`) → `findUserBySessionHash` → `requireCapability(req, db, 'site.read')`. Every state-changing handler starts with one of these guards.
 - **DB:** one `DbClient` interface (`server/db/client.ts`) — tagged-template callable returning `{ rows, rowCount }`. Two adapters: `postgres.ts` (via `Bun.sql`) and `sqlite.ts` (via `bun:sqlite`). Selected by `DATABASE_URL`.
 - **Repositories** (`server/repositories/`) hold all SQL. Handlers never write SQL directly.
-- **Plugins:** `server/plugins/runtime.ts` activates installed plugins at boot; per-plugin code runs in QuickJS-WASM sandboxes (`server/plugins/quickjsHost.ts`, `modulePackVm.ts`).
+- **Plugins:** `server/plugins/runtime.ts` activates installed plugins at boot; per-plugin code runs in QuickJS-WASM sandboxes (`server/plugins/quickjs/vm.ts`, `modulePackVm.ts`).
 - **Published pages and content rows** are served by `tryServePublicRoute`, which delegates resolution + render to `server/publish/publicRouter.ts` (live render from the JSON snapshot stored in `data_row_versions.snapshot_json`). Uploads + admin SPA assets are served from disk by `tryServeUpload` and `tryServeStaticAsset`.
 
 ---
@@ -453,7 +453,7 @@ Plugins ship as zip packages with a `plugin.json` manifest. The host:
 
 1. **Installs** the package (unzips into `uploads/plugins/<id>/<version>/`) — `server/plugins/package.ts`.
 2. **Validates** the manifest and scans the bundled JS for forbidden sandbox-incompatible patterns — `assertSandboxSafe` in `package.ts` + `parsePluginManifest` in `src/core/plugins/manifest.ts`.
-3. **Activates** the plugin at boot or on user action — `server/plugins/runtime.ts`. Activation loads the server entrypoint into a per-plugin QuickJS-WASM VM (`server/plugins/quickjsHost.ts`) and runs its `activate(api)` lifecycle hook.
+3. **Activates** the plugin at boot or on user action — `server/plugins/runtime.ts`. Activation loads the server entrypoint into a per-plugin QuickJS-WASM VM (`server/plugins/quickjs/vm.ts`) and runs its `activate(api)` lifecycle hook.
 4. **Routes** plugin-registered HTTP routes through `/admin/api/cms/plugins/<id>/runtime/…` (handled by `handleRuntimeRoutes`).
 5. **Brokers** the SDK boundary — `api.cms.routes.*`, `api.cms.storage.*`, `api.cms.hooks.*`, `api.cms.loops.*`, `api.cms.settings.*`, `api.cms.schedule.*`. The SDK shape is defined in `src/core/plugin-sdk/`.
 
