@dimina-kit/devtools 0.4.0 → 0.5.0-dev.20260908120530

package/dist/main/services/workbench-coi-server.js

@@ -1,113 +1,15 @@
-/**
- * Cross-Origin-Isolation static server for the embedded VS Code workbench.
- *
- * The workbench needs `SharedArrayBuffer` for the TS web ext-host's
- * project-wide IntelliSense. Chromium only serves that to a document fetched
- * over http(s) carrying COOP `same-origin` + COEP `require-corp` (a custom
- * `protocol.handle` response does NOT unlock it), so the workbench bundle is
- * served from this in-process http server bound to 127.0.0.1 on a random port.
- * Every response carries the three isolation headers so same-origin
- * sub-resources and workers satisfy COEP `require-corp`.
- *
- * Kept separate from `dimina-resource-server` on purpose: that server sends
- * CORP `cross-origin` for the simulator bundles, which is incompatible with the
- * workbench's `same-origin` isolation requirement.
- *
- * `/__fs/*` bridges a `diminafs:`-style FileSystemProvider in the workbench to
- * the live active project on disk, reusing the renderer `project:fs:*`
- * sandbox's realpath-based guards (`resolveWithinProjectRoot`,
- * `assertWritableAncestor`, and the `O_NOFOLLOW` + post-open re-check inside
- * `readFileBuffer`/`writeFile`) so there is a SINGLE sandbox implementation: a
- * symlink inside the root pointing outside it cannot be followed to read or
- * write past the sandbox. The active project root is read per-request (via the
- * injected getter) so project switches take effect immediately.
- *
- * Mutating actions (write/mkdir/delete/rename) additionally require a non-GET
- * method and a same-origin (or origin-less) request, so an arbitrary localhost
- * page cannot drive a destructive `/__fs` call. GET serves only the read-only
- * stat/readdir/read actions.
- */
-import http from 'node:http';
-import nodeFs from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { readFileBufferWithin, writeFileWithin, statWithin, readdirWithin, mkdirWithin, deleteWithin, renameWithin, } from '../ipc/project-fs.js';
+import { readFileBufferWithin, writeFileWithin, statWithin, readdirWithin, mkdirWithin, deleteWithin, renameWithin, SKIP_DIRS, } from '../ipc/project-fs.js';
+import { handleFsWatchRequest } from './fs-watch-sse.js';
+import { createCoiServerShutdown } from './workbench-coi-shutdown.js';
+import { serveStaticFile } from './workbench-coi-static.js';
+import { registerCoiHostSession } from './workbench-coi-host.js';
+import { FS_TYPE_DIR, FS_TYPE_FILE, toFsBridgeEntry } from './fs-bridge-protocol.js';
+import { jsonRes } from './http-json.js';
+import { miniappPartitionKey } from './views/miniapp-partition.js';
 /** Max `/__fs/write` body; enough to save large source files without OOM. */
 const MAX_FS_WRITE_BYTES = 32 * 1024 * 1024;
-const MIME = {
-    '.html': 'text/html; charset=utf-8',
-    '.js': 'text/javascript; charset=utf-8',
-    '.mjs': 'text/javascript; charset=utf-8',
-    '.css': 'text/css; charset=utf-8',
-    '.json': 'application/json; charset=utf-8',
-    '.map': 'application/json; charset=utf-8',
-    '.wasm': 'application/wasm',
-    '.svg': 'image/svg+xml',
-    '.png': 'image/png',
-    '.ttf': 'font/ttf',
-    '.woff': 'font/woff',
-    '.woff2': 'font/woff2',
-    '.ico': 'image/x-icon',
-};
-function setIsolationHeaders(res) {
-    res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
-    res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
-    res.setHeader('Cross-Origin-Resource-Policy', 'same-origin');
-}
-/** Resolve a request pathname inside `root`, rejecting lexical traversal escapes. */
-function containedStaticPath(root, pathname) {
-    const rel = pathname.replace(/^\/+/, '') || 'index.html';
-    const resolved = path.resolve(root, rel);
-    if (resolved !== root && !resolved.startsWith(root + path.sep))
-        return null;
-    return resolved;
-}
-/**
- * Serve a static file under `root`: lexical containment, then `fs.realpath`
- * BOTH the root and the resolved file before stat/stream, so a symlink inside
- * `root` pointing outside it cannot be served (the lexical check alone follows
- * symlinks because `stat`/`createReadStream` do). Sends the response itself.
- */
-function serveStaticFile(res, root, pathname) {
-    const candidate = containedStaticPath(root, pathname);
-    if (!candidate) {
-        res.writeHead(403);
-        res.end('Forbidden');
-        return;
-    }
-    Promise.all([fs.realpath(root), fs.realpath(candidate)])
-        .then(([realRoot, realFile]) => {
-        if (realFile !== realRoot && !realFile.startsWith(realRoot + path.sep)) {
-            res.writeHead(403);
-            res.end('Forbidden');
-            return;
-        }
-        nodeFs.stat(realFile, (err, stat) => {
-            if (err || !stat.isFile()) {
-                res.writeHead(404);
-                res.end('Not Found');
-                return;
-            }
-            res.writeHead(200, {
-                'Content-Type': MIME[path.extname(realFile)] ?? 'application/octet-stream',
-                'Content-Length': stat.size,
-                'Cache-Control': 'no-store',
-            });
-            // Stream the realpath'd file (already resolved to its real on-disk
-            // location, so a symlink inside the root cannot redirect it outside).
-            nodeFs.createReadStream(realFile).pipe(res);
-        });
-    })
-        .catch(() => { if (!res.headersSent) {
-        res.writeHead(404);
-        res.end('Not Found');
-    } });
-}
-function jsonRes(res, code, obj) {
-    const body = Buffer.from(JSON.stringify(obj));
-    res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8', 'Content-Length': body.length });
-    res.end(body);
-}
 /** Thrown by {@link readBody} when the accumulated body exceeds the cap. */
 class BodyTooLargeError extends Error {
     constructor() {
@@ -178,6 +80,22 @@ function rejectUnsafeMutation(req) {
     return null;
 }
 /** Map a node fs error to the HTTP status the provider expects. */
+/**
+ * Percent-decode a request path, answering the client on a malformed escape.
+ * A stray `%` is the client's error and belongs here, not at the shared
+ * listener's exception boundary, which cannot tell a bad request from a bug in
+ * this handler. Returns `null` once the 400 has been sent.
+ */
+function decodePath(res, pathname) {
+    try {
+        return decodeURIComponent(pathname);
+    }
+    catch {
+        res.writeHead(400);
+        res.end('Bad Request');
+        return null;
+    }
+}
 function fsErrorStatus(e) {
     const code = e.code;
     if (code === 'ENOACTIVE')
@@ -186,15 +104,33 @@ function fsErrorStatus(e) {
         return 403;
     if (code === 'ENOENT')
         return 404;
+    // Reading a path that is (now) a DIRECTORY: as a *file* it does not exist.
+    // 404 lets the sync engine's not-found discipline retire the stale ledger
+    // FILE record when an external change replaces a file with a same-named
+    // directory — a 500 would make it skip forever ("transient failure").
+    if (code === 'EISDIR')
+        return 404;
     return 500;
 }
 async function fsStat(ctx) {
     const st = await statWithin(ctx.projectRoot, ctx.rel);
-    jsonRes(ctx.res, 200, { type: st.isDirectory() ? 2 : 1, size: st.size, ctime: st.ctimeMs, mtime: st.mtimeMs });
+    const payload = {
+        type: st.isDirectory() ? FS_TYPE_DIR : FS_TYPE_FILE,
+        size: st.size,
+        ctime: st.ctimeMs,
+        mtime: st.mtimeMs,
+    };
+    jsonRes(ctx.res, 200, payload);
 }
 async function fsReaddir(ctx) {
     const entries = await readdirWithin(ctx.projectRoot, ctx.rel);
-    jsonRes(ctx.res, 200, entries.map((e) => [e.name, e.isDirectory() ? 2 : 1]));
+    // Directories in SKIP_DIRS (node_modules, .git, dist, ...) are omitted at
+    // every level: the workbench mirror and the WAL ledger seed walk whatever
+    // this returns, so listing them would pull entire dependency trees into the
+    // editor memfs and the OPFS ledger. Same-named FILES stay visible.
+    const visible = entries.filter((e) => !(e.isDirectory && SKIP_DIRS.has(e.name)));
+    // Wire shape and why it carries stats: see fs-bridge-protocol.ts.
+    jsonRes(ctx.res, 200, visible.map(toFsBridgeEntry));
 }
 async function fsRead(ctx) {
     const buf = await readFileBufferWithin(ctx.projectRoot, ctx.rel);
@@ -317,12 +253,46 @@ async function readContributedExtensions(extensionsDir) {
     }
     return out;
 }
+/**
+ * The `/__project` workspace id: the miniapp partition key of the active
+ * project, or null when there is no committed project identity yet.
+ *
+ * Reuses `miniappPartitionKey` (the same derivation the per-project Electron
+ * session partition uses) so the editor's storage bucket and the runtime's
+ * storage partition are named off the same project identity: the `appId`,
+ * disambiguated by the project path because `appId` comes from the manifest and
+ * two checkouts can declare the same one.
+ */
+function workspaceIdOf(identity) {
+    if (!identity?.appId)
+        return null;
+    return miniappPartitionKey(identity.appId, identity.projectPath || null);
+}
 export async function startWorkbenchCoiServer(options) {
     const root = path.resolve(options.rootDir);
     const contribRoot = options.extensionsDir ? path.resolve(options.extensionsDir) : null;
-    const server = http.createServer((req, res) => {
-        setIsolationHeaders(res);
-        const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+    const shutdown = createCoiServerShutdown();
+    const handle = (req, res, url) => {
+        // This window is tearing down. Anything accepted from here on would act on
+        // a project the user has already closed, and a new SSE stream would outlive
+        // the drain that was supposed to end them all.
+        if (shutdown.closing) {
+            res.writeHead(503);
+            res.end('Closing');
+            return;
+        }
+        // Special-cased ahead of the generic `/__fs/*` dispatch: unlike every other
+        // action, this is a long-lived SSE stream, not a one-shot JSON response.
+        if (url.pathname === '/__fs/watch') {
+            const endStream = handleFsWatchRequest(req, res, options.getProjectRoot);
+            if (endStream)
+                shutdown.trackWatchStream(res, endStream);
+            return;
+        }
+        // Everything below answers once. Shutdown lets these land rather than
+        // dropping the socket under them — a `/__fs/write` mid-body is the file the
+        // user just saved.
+        shutdown.trackRequest(res);
         if (url.pathname.startsWith('/__fs/')) {
             handleFsRequest(req, res, options.getProjectRoot(), url).catch((e) => {
                 if (!res.headersSent)
@@ -336,6 +306,22 @@ export async function startWorkbenchCoiServer(options) {
             jsonRes(res, 200, options.getFileTypes?.() ?? {});
             return;
         }
+        // Identity of the active project, as the id the editor names its VS Code
+        // workspace after. Every project is mirrored at the same constant
+        // `file:///workspace` root, and VS Code keys WORKSPACE-scope storage (open
+        // editors, view state, explorer expansion) off the workspace identity — so
+        // without a distinct id per project, one project's tabs are restored into
+        // the next, stranded behind "the file was not found".
+        //
+        // Served here rather than baked into the editor's load URL because the
+        // editor view can attach BEFORE the open commits its session (its attach
+        // gate self-releases on a slow compile), when there is no identity to hand
+        // it; `null` then tells the page to keep polling, the same way its disk
+        // mirror already polls `/__fs` for the project root to appear.
+        if (url.pathname === '/__project') {
+            jsonRes(res, 200, { workspaceId: workspaceIdOf(options.getProjectIdentity?.()) });
+            return;
+        }
         // Host-contributed web extensions: manifest + static files (same-origin so
         // they satisfy the workbench's COEP require-corp).
         if (url.pathname.startsWith('/__contrib/')) {
@@ -351,25 +337,39 @@ export async function startWorkbenchCoiServer(options) {
                     jsonRes(res, 500, { error: String(e) }); });
                 return;
             }
-            const rel = decodeURIComponent(url.pathname.slice('/__contrib/'.length));
+            const rel = decodePath(res, url.pathname.slice('/__contrib/'.length));
+            if (rel === null)
+                return;
             serveStaticFile(res, contribRoot, rel);
             return;
         }
-        serveStaticFile(res, root, decodeURIComponent(url.pathname));
-    });
-    await new Promise((resolve, reject) => {
-        server.once('error', reject);
-        server.listen(0, '127.0.0.1', () => {
-            server.off('error', reject);
-            resolve();
-        });
-    });
-    const addr = server.address();
-    const port = typeof addr === 'object' && addr ? addr.port : 0;
+        const filePath = decodePath(res, url.pathname);
+        if (filePath === null)
+            return;
+        serveStaticFile(res, root, filePath);
+    };
+    // The listener is shared with every other project window so they land on one
+    // origin; this window is reached through its own path prefix. See
+    // workbench-coi-host.ts for why the port cannot be per-window.
+    const registration = await registerCoiHostSession({ rootDir: root, extensionsDir: contribRoot, session: { handle } });
     return {
-        baseUrl: `http://127.0.0.1:${port}/`,
-        port,
-        close: () => new Promise((r) => server.close(() => r())),
+        baseUrl: `${registration.origin}/w/${registration.token}/`,
+        port: registration.port,
+        // Why this is not a bare `server.close()`: see workbench-coi-shutdown.ts.
+        // Drain first so this window's SSE streams end and its in-flight writes
+        // land, THEN drop the route — the listener itself only goes away with the
+        // last window.
+        close: async () => {
+            // `finally`: a drain that throws must still drop this window's route.
+            // Leaving it registered would keep a torn-down window's bridge reachable
+            // on the shared listener for the rest of the process.
+            try {
+                await shutdown.drain();
+            }
+            finally {
+                await registration.release();
+            }
+        },
     };
 }
 //# sourceMappingURL=workbench-coi-server.js.map

package/dist/main/services/workbench-coi-shutdown.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Shutdown bookkeeping for the workbench COI bridge, at two levels.
+ *
+ * A project window's bridge is closed as part of that window's teardown, which
+ * awaits it. Two things pull against each other at that moment. `/__fs/watch`
+ * is an SSE stream that only ever ends when its client disconnects, so waiting
+ * on it waits on the editor being destroyed in the same breath — the window
+ * hangs. Dropping every socket outright instead loses a `/__fs/write` whose
+ * body is still arriving, which is the file the user just saved.
+ *
+ * So neither extreme: {@link CoiServerShutdown.drain} ends the streams this
+ * owner started, lets a request already being served finish, and returns once
+ * it has — or once the grace window expires, so teardown is bounded no matter
+ * what a client does. The shared listener behind every window (see
+ * workbench-coi-host.ts) then uses {@link CoiServerShutdown.close}, which adds
+ * the server close and takes the sockets that outlived it.
+ */
+import type http from 'node:http';
+export interface CoiServerShutdown {
+    /** A live `/__fs/watch` stream, with the call that ends it server-side. */
+    trackWatchStream: (res: http.ServerResponse, endStream: () => void) => void;
+    /** A one-shot request whose response must be allowed to land. */
+    trackRequest: (res: http.ServerResponse) => void;
+    /**
+     * True once {@link drain} has started. The owner refuses new requests from
+     * here on: this bridge is bound to a window that is going away, and a
+     * request accepted now would act on a project the user has closed.
+     */
+    readonly closing: boolean;
+    /**
+     * End the tracked streams and wait for the tracked one-shot responses to
+     * land, bounded by the grace window. Leaves the listener alone — one window
+     * going away must not take the shared server with it.
+     */
+    drain: () => Promise<void>;
+    /** {@link drain}, plus closing the server and taking any surviving sockets. */
+    close: (server: http.Server) => Promise<void>;
+}
+export declare function createCoiServerShutdown(graceMs?: number): CoiServerShutdown;
+//# sourceMappingURL=workbench-coi-shutdown.d.ts.map

package/dist/main/services/workbench-coi-shutdown.js

@@ -0,0 +1,69 @@
+/** How long a request already in flight may hold up the window's teardown. */
+const DEFAULT_GRACE_MS = 2_000;
+export function createCoiServerShutdown(graceMs = DEFAULT_GRACE_MS) {
+    const watchStreams = new Set();
+    const inFlight = new Set();
+    let onDrained = null;
+    let closing = false;
+    const drain = () => new Promise((resolve) => {
+        closing = true;
+        for (const endStream of watchStreams)
+            endStream();
+        watchStreams.clear();
+        // Nothing is being served: the sockets that remain are a client's to
+        // keep alive, and waiting on them is waiting on nobody.
+        if (inFlight.size === 0) {
+            resolve();
+            return;
+        }
+        let deadline = null;
+        const finish = () => {
+            onDrained = null;
+            if (deadline)
+                clearTimeout(deadline);
+            resolve();
+        };
+        const expire = () => {
+            // The grace window is up and something is still mid-request — a client
+            // that stalled halfway through a body, most likely. Destroying it here
+            // is the point: the handler still holds the closing window's project,
+            // so a body that lands minutes from now would write into a project the
+            // user has closed, and the socket would outlive the window on the
+            // shared listener.
+            for (const res of [...inFlight])
+                res.destroy();
+            inFlight.clear();
+            finish();
+        };
+        deadline = setTimeout(expire, graceMs);
+        onDrained = finish;
+    });
+    return {
+        get closing() {
+            return closing;
+        },
+        trackWatchStream(res, endStream) {
+            watchStreams.add(endStream);
+            res.on('close', () => watchStreams.delete(endStream));
+        },
+        trackRequest(res) {
+            inFlight.add(res);
+            res.on('close', () => {
+                inFlight.delete(res);
+                if (inFlight.size === 0)
+                    onDrained?.();
+            });
+        },
+        drain,
+        async close(server) {
+            // Stop accepting first, so nothing new arrives during the drain; the
+            // callback only fires once every connection is gone, which is why the
+            // sockets are taken below rather than waited on.
+            const closed = new Promise((resolve) => server.close(() => resolve()));
+            await drain();
+            server.closeAllConnections();
+            await closed;
+        },
+    };
+}
+//# sourceMappingURL=workbench-coi-shutdown.js.map

package/dist/main/services/workbench-coi-static.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Static-file serving and the cross-origin-isolation headers shared by the
+ * workbench COI host and every window's bridge.
+ *
+ * Split out of `workbench-coi-server.ts` so the host module can serve the
+ * bundle without importing the per-window bridge (which imports the host).
+ */
+import http from 'node:http';
+/**
+ * The workbench needs `SharedArrayBuffer` for the TS web ext-host's
+ * project-wide IntelliSense, and Chromium only serves that to a
+ * cross-origin-isolated document. Every response carries the three headers so
+ * same-origin sub-resources and workers satisfy COEP `require-corp`.
+ */
+export declare function setIsolationHeaders(res: http.ServerResponse): void;
+/**
+ * Serve a static file under `root`: lexical containment, then `fs.realpath`
+ * BOTH the root and the resolved file before stat/stream, so a symlink inside
+ * `root` pointing outside it cannot be served (the lexical check alone follows
+ * symlinks because `stat`/`createReadStream` do). Sends the response itself.
+ */
+export declare function serveStaticFile(res: http.ServerResponse, root: string, pathname: string): void;
+//# sourceMappingURL=workbench-coi-static.d.ts.map

package/dist/main/services/workbench-coi-static.js

@@ -0,0 +1,87 @@
+import nodeFs from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+const MIME = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.map': 'application/json; charset=utf-8',
+    '.wasm': 'application/wasm',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.ttf': 'font/ttf',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ico': 'image/x-icon',
+};
+/**
+ * The workbench needs `SharedArrayBuffer` for the TS web ext-host's
+ * project-wide IntelliSense, and Chromium only serves that to a
+ * cross-origin-isolated document. Every response carries the three headers so
+ * same-origin sub-resources and workers satisfy COEP `require-corp`.
+ */
+export function setIsolationHeaders(res) {
+    res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
+    res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
+    res.setHeader('Cross-Origin-Resource-Policy', 'same-origin');
+}
+/** Resolve a request pathname inside `root`, rejecting lexical traversal escapes. */
+function containedStaticPath(root, pathname) {
+    const rel = pathname.replace(/^\/+/, '') || 'index.html';
+    const resolved = path.resolve(root, rel);
+    if (resolved !== root && !resolved.startsWith(root + path.sep))
+        return null;
+    return resolved;
+}
+/**
+ * Serve a static file under `root`: lexical containment, then `fs.realpath`
+ * BOTH the root and the resolved file before stat/stream, so a symlink inside
+ * `root` pointing outside it cannot be served (the lexical check alone follows
+ * symlinks because `stat`/`createReadStream` do). Sends the response itself.
+ */
+export function serveStaticFile(res, root, pathname) {
+    const candidate = containedStaticPath(root, pathname);
+    if (!candidate) {
+        res.writeHead(403);
+        res.end('Forbidden');
+        return;
+    }
+    Promise.all([fs.realpath(root), fs.realpath(candidate)])
+        .then(([realRoot, realFile]) => {
+        if (realFile !== realRoot && !realFile.startsWith(realRoot + path.sep)) {
+            res.writeHead(403);
+            res.end('Forbidden');
+            return;
+        }
+        nodeFs.stat(realFile, (err, stat) => {
+            if (err || !stat.isFile()) {
+                res.writeHead(404);
+                res.end('Not Found');
+                return;
+            }
+            res.writeHead(200, {
+                'Content-Type': MIME[path.extname(realFile)] ?? 'application/octet-stream',
+                'Content-Length': stat.size,
+                'Cache-Control': 'no-store',
+            });
+            // Stream the realpath'd file (already resolved to its real on-disk
+            // location, so a symlink inside the root cannot redirect it outside).
+            const stream = nodeFs.createReadStream(realFile);
+            // The file can vanish or lose permissions between the stat and the
+            // open. The stream reports that asynchronously, once the 200 and the
+            // Content-Length are already on the wire, so no status can be changed
+            // — and an unhandled 'error' on a stream is an uncaught exception in
+            // the main process. Take the socket instead, which is what a client
+            // sees for a truncated body anyway.
+            stream.on('error', () => { res.destroy(); });
+            stream.pipe(res);
+        });
+    })
+        .catch(() => { if (!res.headersSent) {
+        res.writeHead(404);
+        res.end('Not Found');
+    } });
+}
+//# sourceMappingURL=workbench-coi-static.js.map