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

package/dist/main/runtime/devtools-backend-before-quit.harness.js

@@ -0,0 +1,87 @@
+/**
+ * Shared vitest mock harness for `devtools-backend-before-quit.test.ts` and
+ * `devtools-backend-shutdown-race.test.ts` — both drive the REAL
+ * `createDevtoolsBackend`/`createDevtoolsRuntime` against the electron/fs/
+ * `@dimina-kit/devkit` mock set defined in `./devtools-runtime-mock.harness.ts`,
+ * plus the view-manager spy shim and backend-lifecycle helpers below that
+ * only these two tests need.
+ *
+ * `vi.mock(...)` calls in the imported core module run once per importing
+ * test file's own isolated module graph (vitest scopes mocking per test
+ * file); chaining through this module has the same effect as if they were
+ * written directly in the importing file — both test files' `beforeEach`
+ * still dynamically `await import('./devtools-backend.js')` AFTER
+ * `vi.resetModules()`, well after the core module's mock registrations have
+ * already run.
+ */
+import { beforeEach, expect, vi } from 'vitest';
+import { stubs, devkitStubs } from './devtools-runtime-mock.harness.js';
+// ── view-manager spy shim ───────────────────────────────────────────────
+// `createDevtoolsBackend` keeps its assembled `instance` in a private
+// closure — the returned `RuntimeBackend` exposes no getter for
+// `instance.context.views`. Wrapping `createViewManager` here (real
+// implementation, just observed) gives the test a handle on the exact
+// `ViewManager` the backend's `assemble` wires up, equivalent to
+// `vi.spyOn(instance.context.views, 'disposeAll')` without needing the
+// backend to leak its internals.
+const viewManagerStubs = vi.hoisted(() => ({
+    createdManagers: [],
+}));
+vi.mock('../services/views/view-manager.js', async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        createViewManager: (ctx) => {
+            const real = actual.createViewManager(ctx);
+            vi.spyOn(real, 'disposeAll');
+            viewManagerStubs.createdManagers.push(real);
+            return real;
+        },
+    };
+});
+export { stubs, devkitStubs } from './devtools-runtime-mock.harness.js';
+export { viewManagerStubs };
+export function registerBackendTestLifecycle() {
+    const state = {};
+    beforeEach(async () => {
+        vi.resetModules();
+        stubs.reset();
+        devkitStubs.sessionClose.mockClear();
+        viewManagerStubs.createdManagers.length = 0;
+        state.electron = await import('electron');
+        ({ createDevtoolsBackend: state.createDevtoolsBackend } = await import('./devtools-backend.js'));
+    });
+    return state;
+}
+/**
+ * Shared setup for the two tests (one in `devtools-backend-before-quit.test.ts`,
+ * one in `devtools-backend-shutdown-race.test.ts`) that need to observe
+ * `assemble()` PAUSED mid-flight, inside a still-pending `config.onSetup`:
+ * builds the backend with a gated `onSetup`, runs `beforeReady`/`assemble`,
+ * and waits until the assembled `ViewManager` is actually reachable (proof
+ * `createDevtoolsRuntime` has progressed past instance construction) before
+ * handing control back — the caller then fires whatever quit-path event it's
+ * testing while `onSetup` is still gated, and is responsible for calling
+ * `releaseOnSetup()` + awaiting `assemblePromise` itself.
+ */
+export async function startAssemblingWithGatedOnSetup(createDevtoolsBackend, extraConfig = {}) {
+    let releaseOnSetup = () => { };
+    const onSetupGate = new Promise((resolve) => {
+        releaseOnSetup = resolve;
+    });
+    const backend = createDevtoolsBackend({
+        ...extraConfig,
+        onSetup: async () => {
+            await onSetupGate;
+        },
+    });
+    backend.beforeReady?.({});
+    const assemblePromise = Promise.resolve(backend.assemble({}));
+    // Let `assemble` progress through `createDevtoolsRuntime` up to (and into)
+    // the pending `onSetup` gate — the instance must exist by then.
+    await vi.waitFor(() => {
+        expect(viewManagerStubs.createdManagers.length).toBeGreaterThan(0);
+    });
+    return { backend, assemblePromise, releaseOnSetup };
+}
+//# sourceMappingURL=devtools-backend-before-quit.harness.js.map

package/dist/main/runtime/devtools-backend.js

@@ -1,5 +1,6 @@
 import { runDevtoolsBootstrap, createDevtoolsRuntime } from '../app/app.js';
-import { registerAppLifecycle } from '../app/lifecycle.js';
+import { isAppQuitting, registerAppLifecycle } from '../app/lifecycle.js';
+import { closeAllCoiHosts } from '../services/workbench-coi-host.js';
 /**
  * Adapts the devtools runtime into a {@link RuntimeBackend} the framework
  * (`@dimina-kit/electron-deck`) orchestrates. The framework owns the process
@@ -21,6 +22,15 @@ import { registerAppLifecycle } from '../app/lifecycle.js';
 export function createDevtoolsBackend(config = {}) {
     // Hoisted so `onShutdown` can reach the assembled context (assigned by `assemble`).
     let instance = null;
+    // `assemble`'s own in-flight promise: `instance` is now published EARLY (see
+    // below), before `createDevtoolsRuntime`'s async body — including the host's
+    // `config.onSetup(instance)` and everything after it — has finished running.
+    // `onShutdown` must wait for THIS to settle before disposing: disposing
+    // `instance.context.registry` while `createDevtoolsRuntime` is still adding
+    // entries to that same registry (e.g. the `updateChecker`/`setupMcp` wiring
+    // that runs after `onSetup`) hits `DisposableRegistry.add()`'s "cannot add
+    // to disposed registry" throw instead of a clean teardown.
+    let assembling = null;
     return {
         // The backend builds the devtools main window itself (framework skips its own).
         // Its only construction-time needs are the host preload + `sandbox:false`
@@ -42,15 +52,61 @@ export function createDevtoolsBackend(config = {}) {
         // Setup (post-whenReady): app lifecycle (window-all-closed → quit) + the
         // full devtools assembly.
         assemble: async () => {
-            registerAppLifecycle();
-            instance = await createDevtoolsRuntime(config);
+            // `onBeforeQuit` runs synchronously at Electron's `before-quit` — main
+            // loop still fully healthy, well before `will-quit`'s unawaited
+            // `shutdown()` and any window/WebContentsView destruction. Disposing
+            // the host-scoped views (host-toolbar's WebContentsView + its
+            // MessagePortMain) here, instead of leaving them to `onShutdown`'s
+            // best-effort async teardown, keeps them from surviving into
+            // Chromium's native shutdown sequence, where a late `'destroyed'`
+            // handler closing an already-torn-down MessagePort segfaults natively.
+            // Safe to run again from `onShutdown`'s `instance.dispose()` afterwards
+            // — `views.disposeAll()` and its constituents are dispose-idempotent.
+            registerAppLifecycle(() => instance?.disposeViews());
+            // `onInstanceCreated` (not the return value) is what assigns `instance`:
+            // `createDevtoolsRuntime` awaits the host's `config.onSetup(instance)`
+            // — which may run arbitrarily long and can itself load the host toolbar
+            // (a live MessagePort) — before returning. Waiting for the return value
+            // would leave `instance` null, and the before-quit hook above a no-op,
+            // for that entire window. Publishing from the callback closes it.
+            assembling = createDevtoolsRuntime(config, (created) => {
+                instance = created;
+                // Quit may have already started (before-quit already fired) before
+                // this instance existed, so the hook above ran with nothing to
+                // dispose. Self-heal: run the same teardown now that there is.
+                if (isAppQuitting())
+                    instance.disposeViews();
+            }).then(() => { });
+            await assembling;
         },
         // Dispose the devtools context during the framework's deterministic shutdown
         // (app.on('will-quit') → shutdown() → runShutdownCleanup(), awaited once).
         // Without this, the compile session (a child process, torn down by
         // closeProject) and the IPC registry would leak on exit. The framework awaits
         // this hook, so teardown is no longer a best-effort before-quit reach-around.
-        onShutdown: () => instance?.dispose(),
+        //
+        // Waits for `assembling` first: `instance` can be non-null (published
+        // early, above) while `createDevtoolsRuntime`'s own async body — the
+        // host's `onSetup` and everything scheduled after it — is still running
+        // and still adding entries to `instance.context.registry`. Disposing
+        // that registry out from under an in-flight assembly throws instead of
+        // tearing down cleanly (`DisposableRegistry.add` rejects post-dispose).
+        // `.catch()` here: assembly failing is `assemble`'s problem to surface,
+        // not a reason to skip disposing whatever DID get constructed.
+        onShutdown: async () => {
+            await assembling?.catch(() => { });
+            // The workbench COI listener is deliberately kept alive across project
+            // windows (its port IS the workbench origin, see workbench-coi-host.ts),
+            // so no window teardown ever closes it. Process shutdown is the one place
+            // that must — after the windows above have released their routes, and
+            // even if one of their disposers threw on the way.
+            try {
+                await instance?.dispose();
+            }
+            finally {
+                await closeAllCoiHosts();
+            }
+        },
     };
 }
 //# sourceMappingURL=devtools-backend.js.map

package/dist/main/runtime/devtools-runtime-mock.harness.d.ts

@@ -0,0 +1,21 @@
+declare const stubs: {
+    handlers: Map<string, (...args: unknown[]) => unknown>;
+    projectsJsonPath: string;
+    getProjectsJson(): string | null;
+    setProjectsJson(v: string | null): void;
+    projectsWithAppJson: Set<string>;
+    makeEmitter: () => {
+        listeners: Record<string, Set<(...args: unknown[]) => unknown>>;
+        on(event: string, fn: (...args: unknown[]) => unknown): /*elided*/ any;
+        once(event: string, fn: (...args: unknown[]) => unknown): /*elided*/ any;
+        off(event: string, fn: (...args: unknown[]) => unknown): /*elided*/ any;
+        removeListener(event: string, fn: (...args: unknown[]) => unknown): /*elided*/ any;
+        emit(event: string, ...args: unknown[]): void;
+    };
+    reset: () => void;
+};
+declare const devkitStubs: {
+    sessionClose: import("vitest").Mock<() => Promise<void>>;
+};
+export { stubs, devkitStubs };
+//# sourceMappingURL=devtools-runtime-mock.harness.d.ts.map

package/dist/main/runtime/devtools-runtime-mock.harness.js

@@ -0,0 +1,313 @@
+/**
+ * Shared electron/fs/`@dimina-kit/devkit` mock core for
+ * `window-close-reveal.harness.ts` (app/) and
+ * `devtools-backend-before-quit.harness.ts` (runtime/) — both those harnesses
+ * drive a REAL runtime (`createDevtoolsRuntime` or `createDevtoolsBackend`)
+ * against the same mock set (lifted from `quit-flag-onclose.test.ts`) and
+ * previously duplicated it in full; this module holds the part that's
+ * actually identical between them.
+ *
+ * `BrowserWindow` here tracks visible/minimized state and implements
+ * `hide`/`isVisible`/`minimize`/`isMinimized`/`restore` on top of `show`/
+ * `showInactive` — the window-close-reveal guards need all of that, while the
+ * before-quit/shutdown-race tests only ever `destroy()` a window and never
+ * observe the extra state, so carrying it there is a no-op.
+ *
+ * `vi.mock(...)` calls here run once per importing test file's own isolated
+ * module graph (vitest scopes mocking per test file). A harness that imports
+ * this module chains into that same module graph, so importing THIS module
+ * (directly, or transitively through one of the two harnesses above) has the
+ * same effect as if each `vi.mock` call were written directly in the test
+ * file itself.
+ */
+import { vi } from 'vitest';
+// ── Hoisted stub state ──────────────────────────────────────────────────
+const stubs = vi.hoisted(() => {
+    const handlers = new Map();
+    const projectsJsonPath = '/tmp/dimina-test-userdata/dimina-projects.json';
+    let projectsJsonContent = null;
+    const projectsWithAppJson = new Set();
+    function makeEmitter() {
+        const listeners = {};
+        return {
+            listeners,
+            on(event, fn) {
+                ;
+                (listeners[event] ??= new Set()).add(fn);
+                return this;
+            },
+            once(event, fn) {
+                const wrap = (...args) => {
+                    listeners[event]?.delete(wrap);
+                    return fn(...args);
+                };
+                (listeners[event] ??= new Set()).add(wrap);
+                return this;
+            },
+            off(event, fn) {
+                listeners[event]?.delete(fn);
+                return this;
+            },
+            removeListener(event, fn) {
+                listeners[event]?.delete(fn);
+                return this;
+            },
+            emit(event, ...args) {
+                for (const fn of [...(listeners[event] ?? [])])
+                    fn(...args);
+            },
+        };
+    }
+    function reset() {
+        handlers.clear();
+        projectsJsonContent = null;
+        projectsWithAppJson.clear();
+    }
+    return {
+        handlers,
+        projectsJsonPath,
+        getProjectsJson() {
+            return projectsJsonContent;
+        },
+        setProjectsJson(v) {
+            projectsJsonContent = v;
+        },
+        projectsWithAppJson,
+        makeEmitter,
+        reset,
+    };
+});
+// ── electron stub ────────────────────────────────────────────────────────
+vi.mock('electron', () => {
+    const ipcEmitter = stubs.makeEmitter();
+    const ipcMain = {
+        ...ipcEmitter,
+        handle: vi.fn((channel, fn) => {
+            stubs.handlers.set(channel, fn);
+        }),
+        removeHandler: vi.fn((channel) => {
+            stubs.handlers.delete(channel);
+        }),
+        on: vi.fn((event, fn) => ipcEmitter.on(event, fn)),
+        removeListener: vi.fn((event, fn) => ipcEmitter.removeListener(event, fn)),
+    };
+    const appEmitter = stubs.makeEmitter();
+    const app = {
+        ...appEmitter,
+        isPackaged: true,
+        whenReady: vi.fn(() => Promise.resolve()),
+        getPath: vi.fn(() => '/tmp/dimina-test-userdata'),
+        quit: vi.fn(),
+        setName: vi.fn(),
+        commandLine: {
+            getSwitchValue: vi.fn(() => ''),
+            appendSwitch: vi.fn(),
+        },
+    };
+    // `WebContents` and `BrowserWindow` below both wrap a `stubs.makeEmitter()`
+    // and need the SAME on/once/off/removeListener/emit delegation (the
+    // emitter's own methods use `this` internally, so a plain property copy
+    // would call them with the wrong receiver — each needs `.bind(em)`). Shared
+    // base class instead of re-declaring the same 5 bound fields in both.
+    class EmittingStub {
+        em = stubs.makeEmitter();
+        on = this.em.on.bind(this.em);
+        once = this.em.once.bind(this.em);
+        off = this.em.off.bind(this.em);
+        removeListener = this.em.removeListener.bind(this.em);
+        emit = this.em.emit.bind(this.em);
+    }
+    class WebContents extends EmittingStub {
+        destroyed = false;
+        id = Math.floor(Math.random() * 1e6);
+        send = vi.fn();
+        isDestroyed = () => this.destroyed;
+        openDevTools = vi.fn();
+        closeDevTools = vi.fn();
+        setDevToolsWebContents = vi.fn();
+        setWindowOpenHandler = vi.fn();
+        loadFile = vi.fn(() => Promise.resolve());
+        loadURL = vi.fn(() => Promise.resolve());
+        executeJavaScript = vi.fn(() => Promise.resolve(undefined));
+        reload = vi.fn();
+        getType = () => 'window';
+        getURL = () => '';
+        debugger = {
+            attach: vi.fn(),
+            detach: vi.fn(),
+            isAttached: () => false,
+            on: vi.fn(),
+            removeListener: vi.fn(),
+            sendCommand: vi.fn(() => Promise.resolve({ entries: [] })),
+        };
+        close = vi.fn(() => {
+            this.destroyed = true;
+        });
+    }
+    class WebContentsView {
+        webContents = new WebContents();
+        setBounds = vi.fn();
+        setBackgroundColor = vi.fn();
+    }
+    class View {
+        children = [];
+        addChildView(child) {
+            this.children.push(child);
+        }
+        removeChildView(child) {
+            const i = this.children.indexOf(child);
+            if (i >= 0)
+                this.children.splice(i, 1);
+        }
+    }
+    class BrowserWindow extends EmittingStub {
+        destroyed = false;
+        // The list window and every workbench window start shown/restored — the
+        // reveal/hide guards this state exists for only ever move a window AWAY
+        // from it, never establish it.
+        visible = true;
+        minimized = false;
+        webContents = new WebContents();
+        contentView = new WebContentsView();
+        isDestroyed = () => this.destroyed;
+        isVisible = () => this.visible && !this.destroyed;
+        isMinimized = () => this.minimized;
+        getContentSize = () => [1280, 980];
+        setIcon = vi.fn();
+        setTitle = vi.fn();
+        show = vi.fn(() => {
+            this.visible = true;
+        });
+        showInactive = vi.fn(() => {
+            this.visible = true;
+        });
+        hide = vi.fn(() => {
+            this.visible = false;
+        });
+        minimize = vi.fn(() => {
+            this.minimized = true;
+        });
+        restore = vi.fn(() => {
+            this.minimized = false;
+            this.visible = true;
+        });
+        focus = vi.fn();
+        close = vi.fn();
+        destroy = vi.fn(() => {
+            this.destroyed = true;
+        });
+        loadFile = vi.fn(() => Promise.resolve());
+        loadURL = vi.fn(() => Promise.resolve());
+        static getAllWindows = vi.fn(() => []);
+    }
+    const sessionStub = {
+        fromPartition: vi.fn(() => ({
+            webRequest: {
+                onBeforeSendHeaders: vi.fn(),
+                onHeadersReceived: vi.fn(),
+            },
+            registerPreloadScript: vi.fn(),
+            protocol: { handle: vi.fn(), unhandle: vi.fn() },
+        })),
+        defaultSession: {
+            protocol: { handle: vi.fn(), unhandle: vi.fn() },
+        },
+    };
+    const dialog = {
+        showOpenDialog: vi.fn(() => Promise.resolve({ canceled: true, filePaths: [] })),
+        showMessageBox: vi.fn(() => Promise.resolve({ response: 0 })),
+    };
+    const Menu = {
+        buildFromTemplate: vi.fn((tpl) => ({ template: tpl })),
+        setApplicationMenu: vi.fn(),
+    };
+    const shell = {
+        openExternal: vi.fn(() => Promise.resolve()),
+        openPath: vi.fn(() => Promise.resolve('')),
+    };
+    const nativeImage = {
+        createFromPath: vi.fn(() => ({ isEmpty: () => true })),
+    };
+    const nativeTheme = { ...stubs.makeEmitter(), themeSource: 'system' };
+    const globalShortcut = {
+        register: vi.fn(() => false),
+        unregister: vi.fn(),
+        unregisterAll: vi.fn(),
+    };
+    const webContentsStatic = {
+        fromId: vi.fn(() => null),
+        getAllWebContents: vi.fn(() => []),
+    };
+    const Tray = vi.fn();
+    return {
+        app,
+        ipcMain,
+        BrowserWindow,
+        WebContentsView,
+        BrowserView: WebContentsView,
+        View,
+        webContents: webContentsStatic,
+        session: sessionStub,
+        protocol: { registerSchemesAsPrivileged: vi.fn(), handle: vi.fn(), unhandle: vi.fn() },
+        dialog,
+        Menu,
+        shell,
+        nativeImage,
+        nativeTheme,
+        globalShortcut,
+        Tray,
+        default: {},
+    };
+});
+vi.mock('fs', async () => {
+    const real = await vi.importActual('fs');
+    function existsSync(p) {
+        const s = String(p);
+        if (s === stubs.projectsJsonPath)
+            return stubs.getProjectsJson() !== null;
+        if (s.endsWith('/app.json') || s.endsWith('\\app.json')) {
+            const dir = s.replace(/[\\/]app\.json$/, '');
+            return stubs.projectsWithAppJson.has(dir);
+        }
+        return true;
+    }
+    function readFileSync(p, opts) {
+        const s = String(p);
+        if (s === stubs.projectsJsonPath) {
+            const content = stubs.getProjectsJson();
+            if (content === null)
+                throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+            return content;
+        }
+        return real.readFileSync(p, opts);
+    }
+    function writeFileSync(p, data) {
+        const s = String(p);
+        if (s === stubs.projectsJsonPath) {
+            stubs.setProjectsJson(typeof data === 'string' ? data : Buffer.from(data).toString('utf8'));
+        }
+    }
+    const mocked = {
+        ...real,
+        existsSync,
+        readFileSync,
+        writeFileSync,
+        mkdirSync: vi.fn(),
+        statSync: vi.fn(() => ({ isDirectory: () => true, isFile: () => false, size: 0, mtimeMs: 0 })),
+        watch: vi.fn(),
+        realpathSync: vi.fn((p) => p),
+    };
+    return { ...mocked, default: mocked };
+});
+const devkitStubs = vi.hoisted(() => ({
+    sessionClose: vi.fn(() => Promise.resolve()),
+}));
+vi.mock('@dimina-kit/devkit', () => ({
+    openProject: vi.fn(() => Promise.resolve({
+        port: 12345,
+        appInfo: { appId: 'fakeApp' },
+        close: devkitStubs.sessionClose,
+    })),
+}));
+export { stubs, devkitStubs };
+//# sourceMappingURL=devtools-runtime-mock.harness.js.map