@dimina-kit/devtools 0.4.0 → 0.5.0

package/dist/main/app/project-window.js

@@ -0,0 +1,93 @@
+import { nativeImage } from 'electron';
+import path from 'path';
+import { defaultPreloadPath } from '../utils/paths.js';
+import { createMainWindow } from '../windows/main-window/index.js';
+// eslint-disable-next-line no-restricted-syntax -- grandfathered(workbench-context): shrink-only
+import { createWorkbenchContext } from '../services/workbench-context.js';
+function createConfiguredMainWindow(config, rendererDir, entry, title, autoShow, query) {
+    const mainWindow = createMainWindow({
+        title,
+        indexHtml: path.join(rendererDir, entry),
+        query,
+        width: config.window?.width,
+        height: config.window?.height,
+        minWidth: config.window?.minWidth,
+        minHeight: config.window?.minHeight,
+        autoShow,
+    });
+    // Set window/taskbar icon if provided (Linux/Windows; macOS uses app bundle icon)
+    if (config.icon) {
+        const icon = nativeImage.createFromPath(config.icon);
+        if (!icon.isEmpty())
+            mainWindow.setIcon(icon);
+    }
+    return mainWindow;
+}
+function createContext(config, mainWindow, rendererDir, appServices) {
+    return createWorkbenchContext({
+        mainWindow,
+        appServices,
+        adapter: config.adapter,
+        preloadPath: config.preloadPath ?? defaultPreloadPath,
+        rendererDir,
+        appName: config.appName,
+        apiNamespaces: config.apiNamespaces,
+        fileTypes: config.fileTypes,
+        brandingProvider: config.brandingProvider,
+        customCreateProjectDialog: config.customCreateProjectDialog,
+        // No cast needed here: the hook receives the project record, so the
+        // main-process `Project` the context hands it satisfies the structural
+        // `EditableProject` the config declares.
+        customEditProjectDialog: config.customEditProjectDialog,
+        onBeforeOpenProject: config.onBeforeOpenProject,
+    });
+}
+export async function disposeContext(ctx) {
+    await ctx.workspace.closeProject();
+    await ctx.registry.dispose().catch((err) => {
+        console.warn('[workbench] dispose registry encountered errors:', err);
+    });
+}
+/**
+ * Build a window together with the context that owns it, and publish that
+ * context to the router so IPC arriving from this window is answered by it.
+ *
+ * The router registration is parked on the context's own registry: a window
+ * that is torn down must stop claiming senders in the same breath, or a
+ * recycled `webContents.id` would resolve to a dead context.
+ */
+function createWindowWithContext(opts, entry, title, autoShow, query) {
+    const { config, rendererDir, appServices, router } = opts;
+    const window = createConfiguredMainWindow(config, rendererDir, entry, title, autoShow, query);
+    const context = createContext(config, window, rendererDir, appServices);
+    // Anchor the window's renderer as the first Connection. Resources scoped to
+    // that webContents (acquired by later wiring) tear down with it; see
+    // packages/electron-deck/docs/foundation.md (teardown paths).
+    context.connections.acquire(window.webContents);
+    context.registry.add(router.register(context));
+    return { window, context, dispose: () => disposeContext(context) };
+}
+/**
+ * The project-list window. It is the application's root window: the app-level
+ * IPC surface is registered while it exists, and it stays open for the whole
+ * session so workbench windows can come and go around it.
+ */
+export function createLauncherWindow(opts) {
+    return createWindowWithContext(opts, 'entries/main/index.html', opts.config.appName ?? 'Dimina DevTools', opts.config.window?.autoShow);
+}
+/**
+ * A workbench window: one open mini-program project, with its own simulator,
+ * panels and editor. The project identity travels in the URL query so the
+ * renderer entry can mount straight into the project without asking main.
+ */
+export function createWorkbenchWindow(opts, project) {
+    return createWindowWithContext(opts, 'entries/workbench/index.html', project.name || opts.config.appName || 'Dimina DevTools', 
+    // Always hidden: `workbench-window.ts`'s reveal gate is the sole place
+    // that ever shows a project window, once BOTH `setupProjectWindow` has
+    // resolved and the renderer's own `ready-to-show` has fired. Passing
+    // anything but `false` here would let `createMainWindow`'s own
+    // `ready-to-show` handler show the window itself and race that gate.
+    // `config.projectWindow?.autoShow` is read by the gate instead, not here.
+    false, { path: project.path, name: project.name ?? '' });
+}
+//# sourceMappingURL=project-window.js.map

package/dist/main/app/servers.d.ts

@@ -0,0 +1,17 @@
+import type { WorkbenchAppInstance } from './app.js';
+import { startAutomationServer } from '../services/automation/index.js';
+import { type McpOpenedProject, type McpProjectTarget } from '../services/mcp/index.js';
+import type { Disposable } from '@dimina-kit/electron-deck/main';
+/**
+ * The automation server outlives every window: it binds its port at boot,
+ * before any project is open, so it cannot capture a context at start and
+ * takes `getContext` instead. What that resolver hands back is only the
+ * starting point — each connection pins the first project window it reaches
+ * and stays there, so window focus cannot redirect a live client.
+ */
+export declare function setupAutomation(instance: WorkbenchAppInstance, getContext: Parameters<typeof startAutomationServer>[0], senders: Parameters<typeof startAutomationServer>[1]): Promise<Disposable | null>;
+export declare function setupMcp(currentProject: () => McpProjectTarget, openProjectWindow: (project: {
+    path: string;
+    name: string;
+}) => Promise<McpOpenedProject>): Disposable | null;
+//# sourceMappingURL=servers.d.ts.map

package/dist/main/app/servers.js

@@ -0,0 +1,60 @@
+import { app } from 'electron';
+import { startAutomationServer } from '../services/automation/index.js';
+import { startMcpServer, } from '../services/mcp/index.js';
+import { loadWorkbenchSettings } from '../services/settings/index.js';
+/** Parse --auto, --auto-port, --project from process.argv. */
+function parseAutoArgs() {
+    const argv = process.argv;
+    let auto = false;
+    let autoPort = 9420;
+    let projectPath = '';
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === 'auto' || argv[i] === '--auto')
+            auto = true;
+        if ((argv[i] === '--auto-port' || argv[i] === '--auto_port') && argv[i + 1]) {
+            const parsed = parseInt(argv[i + 1], 10);
+            // 0 → OS-assigned free port (used by parallel e2e workers)
+            if (Number.isFinite(parsed) && parsed >= 0)
+                autoPort = parsed;
+        }
+        if (argv[i] === '--project' && argv[i + 1]) {
+            projectPath = argv[i + 1];
+        }
+    }
+    return { auto, autoPort, projectPath };
+}
+/**
+ * The automation server outlives every window: it binds its port at boot,
+ * before any project is open, so it cannot capture a context at start and
+ * takes `getContext` instead. What that resolver hands back is only the
+ * starting point — each connection pins the first project window it reaches
+ * and stays there, so window focus cannot redirect a live client.
+ */
+export async function setupAutomation(instance, getContext, senders) {
+    // Start automation server if --auto flag is present
+    const autoArgs = parseAutoArgs();
+    if (!autoArgs.auto)
+        return null;
+    const server = await startAutomationServer(getContext, senders, autoArgs.autoPort);
+    instance.automationServer = server;
+    // Stable, parseable line for e2e harnesses that scrape stdout.
+    console.log(`[automation] listening on ws://127.0.0.1:${server.port}`);
+    return { dispose: () => server.close() };
+}
+export function setupMcp(currentProject, openProjectWindow) {
+    const settings = loadWorkbenchSettings();
+    if (!settings.mcp.enabled)
+        return null;
+    const cdpPortSwitch = app.commandLine.getSwitchValue('remote-debugging-port');
+    const cdpPort = cdpPortSwitch ? parseInt(cdpPortSwitch, 10) : settings.cdp.port;
+    // Resolved per tool call, not once at boot: the project MCP drives lives in
+    // whichever workbench window is active, and that changes as windows open and
+    // close. Each call then holds the target it got.
+    return startMcpServer(cdpPort, settings.mcp.port, {
+        currentProject,
+        // A project opens into its own window; the renderer entry mounted there
+        // compiles it and attaches the simulator.
+        requestOpenInUi: (p) => openProjectWindow(p),
+    });
+}
+//# sourceMappingURL=servers.js.map

package/dist/main/app/ui-extension-targets.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The ledger of host-registered simulator UI extensions.
+ *
+ * A registration is app-level — the host makes it once — but an extension can
+ * only exist inside a PROJECT window: it mounts into that window's device
+ * frame and talks to its simulator renderer. So one registration becomes one
+ * live extension per project window, and the ledger is what keeps those copies
+ * in step with the windows: every project window that opens gets its own copy,
+ * and a copy exists exactly as long as the window that owns it.
+ *
+ * The project list is deliberately not a target. It runs no bridge router and
+ * no simulator, so an extension registered into it could never mount, and
+ * `invoke` — which follows the window the user works in — would be answered by
+ * that dead copy every time the list window has focus.
+ */
+import { type Disposable } from '@dimina-kit/electron-deck/main';
+import type { SimulatorUiExtensionHandle, SimulatorUiExtensionRegistration } from '../../shared/simulator-ui.js';
+/**
+ * The window surface the ledger needs, described structurally so this module
+ * does not import WorkbenchContext (see eslint-workbench-context-gate).
+ */
+export interface UiExtensionWindow {
+    simulatorUiExtensions: {
+        register: (registration: SimulatorUiExtensionRegistration) => SimulatorUiExtensionHandle;
+    };
+    registry: {
+        add: (d: Disposable) => Disposable;
+    };
+}
+export interface UiExtensionTargetsDeps<W extends UiExtensionWindow> {
+    /** Every open project window, in open order. */
+    projectWindows: () => W[];
+    /** The project window the user is working in, or null when none is open. */
+    activeWindow: () => W | null;
+}
+export interface UiExtensionTargets<W extends UiExtensionWindow> {
+    /** Give a freshly opened project window its copy of every registration. */
+    attachTo: (window: W) => void;
+    register: (registration: SimulatorUiExtensionRegistration) => SimulatorUiExtensionHandle;
+}
+export declare function createUiExtensionTargets<W extends UiExtensionWindow>(deps: UiExtensionTargetsDeps<W>): UiExtensionTargets<W>;
+//# sourceMappingURL=ui-extension-targets.d.ts.map

package/dist/main/app/ui-extension-targets.js

@@ -0,0 +1,101 @@
+/**
+ * The ledger of host-registered simulator UI extensions.
+ *
+ * A registration is app-level — the host makes it once — but an extension can
+ * only exist inside a PROJECT window: it mounts into that window's device
+ * frame and talks to its simulator renderer. So one registration becomes one
+ * live extension per project window, and the ledger is what keeps those copies
+ * in step with the windows: every project window that opens gets its own copy,
+ * and a copy exists exactly as long as the window that owns it.
+ *
+ * The project list is deliberately not a target. It runs no bridge router and
+ * no simulator, so an extension registered into it could never mount, and
+ * `invoke` — which follows the window the user works in — would be answered by
+ * that dead copy every time the list window has focus.
+ */
+import { toDisposable } from '@dimina-kit/electron-deck/main';
+import { assertSimulatorUiExtensionShape } from '../services/simulator/ui-extensions.js';
+export function createUiExtensionTargets(deps) {
+    /** Per registration, one target per project window that currently holds it. */
+    const ledger = new Map();
+    /** Ids currently spoken for app-wide, so a clash is caught where it happens. */
+    const ids = new Set();
+    function attach(window, targets, registration) {
+        const extension = window.simulatorUiExtensions.register(registration);
+        // Owned by the window: its registry drives this on close, which both tears
+        // the extension down and drops the record. A record left behind would keep
+        // a disposed extension reachable as an `invoke` target and would make the
+        // ledger grow with every window ever opened.
+        const owned = window.registry.add(toDisposable(async () => {
+            const index = targets.findIndex((t) => t.extension === extension);
+            if (index >= 0)
+                targets.splice(index, 1);
+            await extension.dispose();
+        }));
+        targets.push({ window, extension, owned });
+    }
+    /**
+     * A window refusing an extension is a fact about that window: the project
+     * still opens, the other windows keep their copies, and windows opened later
+     * still get theirs. Letting it escape would turn one bad extension into "no
+     * project can be opened any more".
+     */
+    function tryAttach(window, targets, registration) {
+        try {
+            attach(window, targets, registration);
+        }
+        catch (error) {
+            console.warn(`[simulator-ui] project window did not take extension "${registration.id}":`, error instanceof Error ? error.message : String(error));
+        }
+    }
+    return {
+        attachTo: (window) => {
+            for (const [registration, targets] of ledger)
+                tryAttach(window, targets, registration);
+        },
+        register: (registration) => {
+            // Checked here, before anything is recorded: the ledger owns the
+            // app-level set of registrations, and hosts register in `onSetup` where
+            // there is no project window to do the checking. A rejected registration
+            // must leave no record — otherwise it is handed to every project window
+            // opened afterwards and takes each of them down as it is built.
+            // Snapshotted before anything reads it: the ledger outlives this call and
+            // hands the registration to every project window opened later, so a host
+            // that reuses its object to describe the next extension would otherwise
+            // rewrite what an already-registered one means — the id it releases, and
+            // the extension future windows are given.
+            const snapshot = { ...registration };
+            assertSimulatorUiExtensionShape(snapshot);
+            const id = snapshot.id;
+            if (ids.has(id)) {
+                throw new Error(`Simulator UI extension "${id}" is already registered`);
+            }
+            const targets = [];
+            ids.add(id);
+            ledger.set(snapshot, targets);
+            for (const window of deps.projectWindows())
+                tryAttach(window, targets, snapshot);
+            return {
+                dispose: () => {
+                    // Only while this registration is the one holding the id: a second
+                    // dispose must not free an id a later registration now owns.
+                    if (!ledger.delete(snapshot))
+                        return;
+                    ids.delete(id);
+                    // Copied: disposing a window-owned record splices it out of `targets`.
+                    for (const target of [...targets])
+                        void target.owned.dispose();
+                    targets.length = 0;
+                },
+                invoke: (method, params) => {
+                    const active = deps.activeWindow();
+                    const target = targets.find((t) => t.window === active) ?? targets[targets.length - 1];
+                    if (!target)
+                        throw new Error('simulator UI extension has no live window');
+                    return target.extension.invoke(method, params);
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=ui-extension-targets.js.map

package/dist/main/app/window-close-reveal.harness.d.ts

@@ -0,0 +1,34 @@
+export { stubs, devkitStubs } from '../runtime/devtools-runtime-mock.harness.js';
+/**
+ * Shared per-test setup: reset modules (fresh module-level state each test),
+ * reset the mock harness above, and dynamically re-import `electron` +
+ * `createDevtoolsRuntime` + the lifecycle flag — dynamic, not a static
+ * top-level import, because it must happen AFTER `vi.resetModules()` picks
+ * up a fresh module instance each test. Registers its own `beforeEach`; call
+ * once per describing test file.
+ */
+export interface RuntimeTestState {
+    createDevtoolsRuntime: typeof import('./app.js').createDevtoolsRuntime;
+    registerAppLifecycle: typeof import('./lifecycle.js').registerAppLifecycle;
+    isAppQuitting: typeof import('./lifecycle.js').isAppQuitting;
+    electron: typeof import('electron');
+}
+export declare function registerRuntimeTestLifecycle(): RuntimeTestState;
+/**
+ * Registers `projectDir` as an openable project (app.json present, empty
+ * projects list) and opens it in its own window via the real
+ * `openProjectWindow`. Does NOT open a devkit session — the close guards
+ * under test branch on window-list membership, not session state (teardown
+ * is unconditional; see workbench-window.ts's `wireWorkbenchWindowEvents`
+ * doc comment), so a session adds cost without adding coverage here.
+ */
+export declare function openProjectWindow(instance: Awaited<ReturnType<typeof import('./app.js').createDevtoolsRuntime>>, projectDir: string): Promise<ReturnType<Awaited<ReturnType<typeof import('./app.js').createDevtoolsRuntime>>['projectWindows']>[number]>;
+/** A fresh Electron-shaped close event, plus a getter for whether it was prevented. */
+export declare function makeCloseEvent(): {
+    event: {
+        preventDefault: () => void;
+    };
+    prevented: () => boolean;
+};
+export declare function emitClose(win: unknown, event: unknown): void;
+//# sourceMappingURL=window-close-reveal.harness.d.ts.map

package/dist/main/app/window-close-reveal.harness.js

@@ -0,0 +1,65 @@
+/**
+ * Shared vitest mock harness for the list/workbench-window close-guard test
+ * files (`main-window-close-guard.test.ts`, `workbench-window-reveal-on-
+ * close.test.ts`, and siblings) — all drive the REAL `createDevtoolsRuntime`
+ * against the electron/fs/`@dimina-kit/devkit` mock set defined in
+ * `../runtime/devtools-runtime-mock.harness.ts`, plus the runtime-lifecycle
+ * and window-opening helpers below that those tests need in common.
+ *
+ * `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.
+ */
+import { beforeEach, vi } from 'vitest';
+import { stubs, devkitStubs } from '../runtime/devtools-runtime-mock.harness.js';
+export { stubs, devkitStubs } from '../runtime/devtools-runtime-mock.harness.js';
+export function registerRuntimeTestLifecycle() {
+    const state = {};
+    beforeEach(async () => {
+        vi.resetModules();
+        stubs.reset();
+        devkitStubs.sessionClose.mockClear();
+        state.electron = await import('electron');
+        ({ createDevtoolsRuntime: state.createDevtoolsRuntime } = await import('./app.js'));
+        ({ registerAppLifecycle: state.registerAppLifecycle, isAppQuitting: state.isAppQuitting } =
+            await import('./lifecycle.js'));
+    });
+    return state;
+}
+/**
+ * Registers `projectDir` as an openable project (app.json present, empty
+ * projects list) and opens it in its own window via the real
+ * `openProjectWindow`. Does NOT open a devkit session — the close guards
+ * under test branch on window-list membership, not session state (teardown
+ * is unconditional; see workbench-window.ts's `wireWorkbenchWindowEvents`
+ * doc comment), so a session adds cost without adding coverage here.
+ */
+export async function openProjectWindow(instance, projectDir) {
+    stubs.projectsWithAppJson.add(projectDir);
+    if (stubs.getProjectsJson() === null)
+        stubs.setProjectsJson(JSON.stringify([]));
+    await instance.openProjectWindow({ path: projectDir });
+    // The manager keys its window map by project path and this helper always
+    // opens a path it just registered, so the newest entry is the one that was
+    // asked for. Matching on anything weaker (e.g. "the first window that isn't
+    // the list window") hands back the PREVIOUSLY opened project once a second
+    // one is open, which is exactly the multi-window case these tests exist for.
+    const found = instance.projectWindows().at(-1);
+    if (!found)
+        throw new Error(`openProjectWindow(${projectDir}) did not publish a window`);
+    return found;
+}
+/** A fresh Electron-shaped close event, plus a getter for whether it was prevented. */
+export function makeCloseEvent() {
+    let count = 0;
+    return {
+        event: { preventDefault: () => { count += 1; } },
+        prevented: () => count > 0,
+    };
+}
+export function emitClose(win, event) {
+    ;
+    win.emit('close', event);
+}
+//# sourceMappingURL=window-close-reveal.harness.js.map

package/dist/main/app/window-events.d.ts

@@ -0,0 +1,15 @@
+import { BrowserWindow } from 'electron';
+import { type Disposable } from '@dimina-kit/electron-deck/main';
+/**
+ * Bring `win` back in front of the user from any hidden or minimized state.
+ *
+ * The project-list window hides instead of closing while projects are open —
+ * it owns app-level IPC that cannot be registered a second time, so it must
+ * outlive its own close button — which makes "show the project list" a real
+ * operation with several entry points (the menu, a macOS dock activate, the
+ * last project window closing). They all go through here so none of them can
+ * drift into handling only some of the hidden states.
+ */
+export declare function revealWindow(win: BrowserWindow): void;
+export declare function enableDevRendererAutoReload(rendererDir: string): Disposable;
+//# sourceMappingURL=window-events.d.ts.map

package/dist/main/app/window-events.js

@@ -0,0 +1,45 @@
+import { app, BrowserWindow } from 'electron';
+import fs from 'fs';
+import { toDisposable } from '@dimina-kit/electron-deck/main';
+/**
+ * Bring `win` back in front of the user from any hidden or minimized state.
+ *
+ * The project-list window hides instead of closing while projects are open —
+ * it owns app-level IPC that cannot be registered a second time, so it must
+ * outlive its own close button — which makes "show the project list" a real
+ * operation with several entry points (the menu, a macOS dock activate, the
+ * last project window closing). They all go through here so none of them can
+ * drift into handling only some of the hidden states.
+ */
+export function revealWindow(win) {
+    if (win.isDestroyed())
+        return;
+    if (win.isMinimized())
+        win.restore();
+    win.show();
+    win.focus();
+}
+export function enableDevRendererAutoReload(rendererDir) {
+    // Auto-reload renderer windows when dist files change during development
+    if (app.isPackaged) {
+        return toDisposable(() => { });
+    }
+    let reloadTimer = null;
+    const watcher = fs.watch(rendererDir, { recursive: true }, () => {
+        if (reloadTimer)
+            clearTimeout(reloadTimer);
+        reloadTimer = setTimeout(() => {
+            for (const win of BrowserWindow.getAllWindows()) {
+                win.webContents.reload();
+            }
+        }, 300);
+    });
+    return toDisposable(() => {
+        if (reloadTimer) {
+            clearTimeout(reloadTimer);
+            reloadTimer = null;
+        }
+        watcher.close();
+    });
+}
+//# sourceMappingURL=window-events.js.map

package/dist/main/app/window-runtime-services.d.ts

@@ -0,0 +1,41 @@
+import type { BrowserWindow } from "electron";
+import type { ConnectionRegistry, DisposableRegistry } from "@dimina-kit/electron-deck/main";
+import type { SyncStorageChange } from "../../shared/ipc-channels.js";
+import type { SenderPolicy } from "../utils/ipc-registry.js";
+import type { BridgeRouterHandle } from "../ipc/bridge-router.js";
+import type { CdpSessionBroker } from "../services/cdp-session/index.js";
+import type { InternalDevtoolsWindow } from "../windows/internal-devtools-window/index.js";
+import type { NetworkForwarder } from "../services/network-forward/index.js";
+import type { AppDataTap } from "../services/simulator-appdata/index.js";
+import type { StorageApi } from "../services/simulator-storage/index.js";
+import type { WorkspaceService } from "../services/workspace/workspace-service.js";
+/**
+ * Narrow view of the context fields these services read, plus the four fields
+ * they publish back onto it for bridge-router to consume.
+ */
+export interface WindowRuntimeContext {
+    registry: DisposableRegistry;
+    connections: ConnectionRegistry;
+    cdpSessionBroker: CdpSessionBroker;
+    senderPolicy: SenderPolicy;
+    workspace: WorkspaceService;
+    bridge?: BridgeRouterHandle;
+    internalDevtoolsWindow?: InternalDevtoolsWindow;
+    storageApi?: StorageApi;
+    onServiceStorageChanged?: (appId: string, change: SyncStorageChange) => void;
+    networkForward?: NetworkForwarder;
+    appData?: AppDataTap;
+}
+/**
+ * Resolve the active project's appId. Shared by the storage panel filter, the
+ * native-host WXML/element-inspect services (which scope the active render
+ * guest by appId) and the editor's per-project workspace identity.
+ */
+export declare function createActiveAppIdResolver(context: Pick<WindowRuntimeContext, "workspace">): () => string | null;
+/**
+ * Panel-backing services that push into one window's renderer: storage, and
+ * under native-host the MCP target tracking plus the WXML / AppData /
+ * current-page streams.
+ */
+export declare function setupWindowRuntimeServices(context: WindowRuntimeContext, mainWindow: BrowserWindow, getActiveAppId: () => string | null, projectPath: string): void;
+//# sourceMappingURL=window-runtime-services.d.ts.map