@mindexec/cli 0.2.478 → 0.2.480

package/electron/main.cjs

@@ -1,517 +1,517 @@
-'use strict';
-
-const { app, BrowserWindow, dialog, ipcMain } = require('electron');
-const { spawn } = require('child_process');
-const fs = require('fs');
-const http = require('http');
-const net = require('net');
-const path = require('path');
-const workspaceState = require('../desktop-workspace-state.cjs');
-const { createProductUpdateManager } = require('./update-manager.cjs');
-const {
-  DEFAULT_UPDATE_INTERVAL_MS,
-  createRecurringProductUpdateOwner
-} = require('./recurring-update-owner.cjs');
-
-const { resolveDesktopWorkspace } = workspaceState;
-
-const DEFAULT_BRIDGE_PORT = 5147;
-const DEFAULT_REMOTE_HUB_PORT = 5198;
-const STARTUP_TIMEOUT_MS = 45_000;
-const HEALTH_POLL_MS = 250;
-const UPDATE_RUNTIME_RELEASE_TIMEOUT_MS = 10_000;
-const DESKTOP_APP_ID = 'com.mindexec.desktop';
-
-let mainWindow = null;
-let bridgeChild = null;
-let isQuitting = false;
-let requestedExitCode = 0;
-let activeBridgePort = DEFAULT_BRIDGE_PORT;
-let activeRemoteHubPort = DEFAULT_REMOTE_HUB_PORT;
-let activeWorkspace = '';
-let desktopWorkspaceStatePath = '';
-let productUpdates = null;
-let recurringProductUpdates = null;
-let updateInstallSequenceStarted = false;
-let updatePromptPromise = null;
-let updatePromptedVersion = '';
-
-function resolveDesktopIconPath() {
-  const iconPath = path.resolve(__dirname, '..', 'wwwroot', 'icon-512.png');
-  return fs.existsSync(iconPath) ? iconPath : undefined;
-}
-
-function resolveDesktopInstallKind() {
-  if (!app.isPackaged) return 'development';
-  if (process.env.PORTABLE_EXECUTABLE_FILE || process.env.PORTABLE_EXECUTABLE_DIR) return 'portable';
-  if (path.basename(path.dirname(process.execPath)).toLowerCase() === 'win-unpacked') return 'unpacked';
-  return process.platform === 'win32' ? 'installed' : 'unsupported-platform';
-}
-
-function parsePort(value) {
-  const parsed = Number.parseInt(String(value ?? ''), 10);
-  return Number.isInteger(parsed) && parsed > 0 && parsed <= 65_535 ? parsed : 0;
-}
-
-function requestJson(url, timeoutMs = 2_000) {
-  return new Promise((resolve, reject) => {
-    const request = http.get(url, { timeout: timeoutMs }, (response) => {
-      let body = '';
-      response.setEncoding('utf8');
-      response.on('data', (chunk) => {
-        body += chunk;
-      });
-      response.on('end', () => {
-        if (response.statusCode < 200 || response.statusCode >= 300) {
-          reject(new Error(`HTTP ${response.statusCode} from ${url}`));
-          return;
-        }
-
-        try {
-          resolve(JSON.parse(body));
-        } catch (error) {
-          reject(new Error(`Invalid JSON from ${url}: ${error.message}`));
-        }
-      });
-    });
-
-    request.on('timeout', () => {
-      request.destroy(new Error(`Timed out requesting ${url}`));
-    });
-    request.on('error', reject);
-  });
-}
-
-function isPortAvailable(port) {
-  return new Promise((resolve) => {
-    const server = net.createServer();
-    server.unref();
-    server.once('error', () => resolve(false));
-    server.listen({ host: '127.0.0.1', port, exclusive: true }, () => {
-      server.close(() => resolve(true));
-    });
-  });
-}
-
-async function resolveDedicatedPort(explicitValue, defaultPort, label, excludedPort = 0) {
-  const explicitPort = parsePort(explicitValue);
-  if (explicitPort) {
-    if (explicitPort === excludedPort) {
-      throw new Error(`${label} port ${explicitPort} conflicts with the bundled LocalBridge port.`);
-    }
-    if (!await isPortAvailable(explicitPort)) {
-      throw new Error(`${label} port ${explicitPort} is already occupied.`);
-    }
-    return explicitPort;
-  }
-
-  for (let offset = 0; offset < 100; offset += 1) {
-    const candidate = defaultPort + offset;
-    if (candidate !== excludedPort && candidate <= 65_535 && await isPortAvailable(candidate)) {
-      return candidate;
-    }
-  }
-
-  throw new Error(`No free ${label} port was found from ${defaultPort}.`);
-}
-
-function appendDesktopLog(message) {
-  const line = `[${new Date().toISOString()}] ${message}\n`;
-  try {
-    const logDirectory = app.getPath('logs');
-    fs.mkdirSync(logDirectory, { recursive: true });
-    fs.appendFileSync(path.join(logDirectory, 'desktop.log'), line, 'utf8');
-  } catch {
-    process.stderr.write(line);
-  }
-}
-
-function spawnBundledBridge(packageRoot) {
-  const serverPath = path.join(packageRoot, 'server.js');
-  const frontendPath = path.join(packageRoot, 'wwwroot', 'index.html');
-  if (!fs.existsSync(serverPath)) {
-    throw new Error(`Bundled LocalBridge entry is missing: ${serverPath}`);
-  }
-  if (!fs.existsSync(frontendPath)) {
-    throw new Error(`Bundled MindCanvas frontend is missing: ${frontendPath}`);
-  }
-
-  const child = spawn(process.execPath, [serverPath], {
-    cwd: packageRoot,
-    env: {
-      ...process.env,
-      ELECTRON_RUN_AS_NODE: '1',
-      MINDEXEC_DESKTOP: '1',
-      MINDEXEC_NO_OPEN: '1',
-      MINDEXEC_DESKTOP_WORKSPACE_STATE_PATH: desktopWorkspaceStatePath,
-      WORKSPACE_PATH: activeWorkspace,
-      BRIDGE_PORT: String(activeBridgePort),
-      REMOTE_HUB_PORT: String(activeRemoteHubPort)
-    },
-    stdio: ['ignore', 'pipe', 'pipe'],
-    windowsHide: true
-  });
-
-  child.stdout?.on('data', (chunk) => appendDesktopLog(`[bridge] ${String(chunk).trimEnd()}`));
-  child.stderr?.on('data', (chunk) => appendDesktopLog(`[bridge:error] ${String(chunk).trimEnd()}`));
-  child.on('error', (error) => appendDesktopLog(`[bridge:spawn-error] ${error.stack || error.message}`));
-  child.on('exit', (code, signal) => {
-    appendDesktopLog(`[bridge:exit] code=${String(code)} signal=${String(signal)}`);
-    if (!isQuitting && process.env.MINDEXEC_DESKTOP_SMOKE !== '1') {
-      dialog.showErrorBox(
-        'MindExec LocalBridge stopped',
-        `The bundled local runtime exited unexpectedly (code ${String(code)}, signal ${String(signal)}).`
-      );
-    }
-  });
-
-  bridgeChild = child;
-}
-
-async function waitForBundledBridge() {
-  const deadline = Date.now() + STARTUP_TIMEOUT_MS;
-  let lastError = null;
-
-  while (Date.now() < deadline) {
-    if (bridgeChild && bridgeChild.exitCode !== null) {
-      throw new Error(`Bundled LocalBridge exited during startup with code ${bridgeChild.exitCode}.`);
-    }
-
-    try {
-      const status = await requestJson(`http://127.0.0.1:${activeBridgePort}/api/status?refresh=cache`);
-      if (status?.status === 'ok' && status?.workspace) {
-        return status;
-      }
-    } catch (error) {
-      lastError = error;
-    }
-
-    await new Promise((resolve) => setTimeout(resolve, HEALTH_POLL_MS));
-  }
-
-  throw new Error(
-    `Bundled LocalBridge did not become ready on port ${activeBridgePort}: ${lastError?.message || 'timeout'}`
-  );
-}
-
-async function prepareBundledRuntime() {
-  const packageRoot = path.resolve(__dirname, '..');
-  activeBridgePort = await resolveDedicatedPort(process.env.BRIDGE_PORT, DEFAULT_BRIDGE_PORT, 'LocalBridge');
-  activeRemoteHubPort = await resolveDedicatedPort(
-    process.env.REMOTE_HUB_PORT,
-    DEFAULT_REMOTE_HUB_PORT,
-    'RemoteHub',
-    activeBridgePort
-  );
-  desktopWorkspaceStatePath = path.resolve(
-    process.env.MINDEXEC_DESKTOP_WORKSPACE_STATE_PATH
-      || path.join(app.getPath('userData'), 'workspace-state.json')
-  );
-  const workspaceResolution = resolveDesktopWorkspace({
-    explicitWorkspace: process.env.MINDEXEC_DESKTOP_WORKSPACE || process.env.WORKSPACE_PATH,
-    statePath: desktopWorkspaceStatePath,
-    fallbackWorkspace: path.join(app.getPath('documents'), 'MindExecution')
-  });
-  activeWorkspace = workspaceResolution.workspacePath;
-
-  fs.mkdirSync(activeWorkspace, { recursive: true });
-  appendDesktopLog(
-    `Starting bundled runtime: bridge=${activeBridgePort}, remoteHub=${activeRemoteHubPort}, ` +
-    `workspace=${activeWorkspace}, workspaceSource=${workspaceResolution.source}`
-  );
-  spawnBundledBridge(packageRoot);
-  return waitForBundledBridge();
-}
-
-function assertTrustedUpdateIpc(event) {
-  const senderUrl = event?.senderFrame?.url || event?.sender?.getURL?.() || '';
-  let sender;
-  try {
-    sender = new URL(senderUrl);
-  } catch {
-    throw new Error('desktop-update-ipc-sender-invalid');
-  }
-  if (sender.protocol !== 'http:' || sender.hostname !== '127.0.0.1' || sender.port !== String(activeBridgePort)) {
-    throw new Error('desktop-update-ipc-sender-untrusted');
-  }
-}
-
-function registerUpdateIpc() {
-  const handle = (channel, callback) => {
-    ipcMain.handle(channel, async (event) => {
-      assertTrustedUpdateIpc(event);
-      return callback();
-    });
-  };
-  handle('updates:get-status', () => productUpdates?.getStatus() || { state: 'unavailable' });
-  handle('updates:check', () => productUpdates?.check() || Promise.resolve({ state: 'unavailable' }));
-  handle('updates:install', () => productUpdates?.install() || Promise.resolve({ state: 'unavailable' }));
-}
-
-function sendUpdateStatus(status) {
-  appendDesktopLog(
-    `[update] state=${status.state} current=${status.currentVersion || ''} ` +
-    `available=${status.availableVersion || ''} progress=${Math.round(status.progress || 0)} ` +
-    `kind=${status.installKind || ''}${status.error ? ` error=${status.error}` : ''}`
-  );
-  if (mainWindow && !mainWindow.isDestroyed() && !mainWindow.webContents.isDestroyed()) {
-    mainWindow.webContents.send('updates:status', status);
-  }
-  if (status.state === 'downloaded') void promptForDownloadedUpdate(status);
-}
-
-async function promptForDownloadedUpdate(status = productUpdates?.getStatus()) {
-  if (!status?.downloaded || !status.availableVersion || !mainWindow || mainWindow.isDestroyed()) return;
-  if (process.env.MINDEXEC_DESKTOP_SMOKE === '1') return;
-  if (updatePromptedVersion === status.availableVersion || updatePromptPromise) return updatePromptPromise;
-
-  updatePromptedVersion = status.availableVersion;
-  updatePromptPromise = dialog.showMessageBox(mainWindow, {
-    type: 'info',
-    title: 'MindExec update ready',
-    message: `MindExec ${status.availableVersion} is ready.`,
-    detail: 'Restart now to use the new development build. Your project folder and saved data stay unchanged.',
-    buttons: ['Restart and update', 'Later'],
-    defaultId: 0,
-    cancelId: 1,
-    noLink: true
-  }).then(result => {
-    if (result.response === 0) return productUpdates?.install();
-    return productUpdates?.getStatus();
-  }).catch(error => {
-    appendDesktopLog(`[update:prompt-error] ${error?.stack || error}`);
-    return productUpdates?.getStatus();
-  }).finally(() => {
-    updatePromptPromise = null;
-  });
-  return updatePromptPromise;
-}
-
-function initializeProductUpdates() {
-  productUpdates = createProductUpdateManager({
-    app,
-    installKind: resolveDesktopInstallKind(),
-    onStatus: sendUpdateStatus,
-    beforeInstall: prepareRuntimeForUpdateInstall,
-    onInstallError: recoverRuntimeAfterUpdateInstallError
-  });
-  recurringProductUpdates = createRecurringProductUpdateOwner({
-    manager: productUpdates,
-    canRun: () => !isQuitting && !updateInstallSequenceStarted,
-    initialDelayMs: DEFAULT_UPDATE_INTERVAL_MS,
-    intervalMs: DEFAULT_UPDATE_INTERVAL_MS,
-    onError: error => appendDesktopLog(`[update:recurring-error] ${error?.stack || error}`)
-  });
-}
-
-function createMainWindow() {
-  const hiddenSmokeMode = process.env.MINDEXEC_DESKTOP_SMOKE === '1';
-  const window = new BrowserWindow({
-    width: 1440,
-    height: 960,
-    minWidth: 960,
-    minHeight: 640,
-    show: !hiddenSmokeMode,
-    autoHideMenuBar: true,
-    backgroundColor: '#f8fafc',
-    title: 'MindExec',
-    icon: resolveDesktopIconPath(),
-    webPreferences: {
-      preload: path.join(__dirname, 'preload.cjs'),
-      contextIsolation: true,
-      nodeIntegration: false,
-      sandbox: true,
-      webSecurity: true
-    }
-  });
-
-  window.webContents.setWindowOpenHandler(() => ({
-    action: 'allow',
-    overrideBrowserWindowOptions: {
-      autoHideMenuBar: true,
-      icon: resolveDesktopIconPath(),
-      webPreferences: {
-        contextIsolation: true,
-        nodeIntegration: false,
-        sandbox: true,
-        webSecurity: true
-      }
-    }
-  }));
-
-  window.on('closed', () => {
-    if (mainWindow === window) {
-      mainWindow = null;
-    }
-  });
-
-  mainWindow = window;
-  return window;
-}
-
-function writeSmokeResult(payload) {
-  const resultPath = process.env.MINDEXEC_DESKTOP_SMOKE_RESULT;
-  if (!resultPath) {
-    return;
-  }
-
-  fs.mkdirSync(path.dirname(resultPath), { recursive: true });
-  fs.writeFileSync(resultPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
-}
-
-async function stopBundledBridge() {
-  const child = bridgeChild;
-  bridgeChild = null;
-  if (!child || child.exitCode !== null) {
-    return;
-  }
-
-  await new Promise((resolve) => {
-    let settled = false;
-    const finish = () => {
-      if (settled) {
-        return;
-      }
-      settled = true;
-      resolve();
-    };
-
-    child.once('exit', finish);
-    try {
-      child.kill('SIGTERM');
-    } catch {
-      finish();
-      return;
-    }
-
-    setTimeout(() => {
-      if (child.exitCode === null) {
-        try {
-          child.kill('SIGKILL');
-        } catch {
-          // The child may have exited between the check and the kill.
-        }
-      }
-      finish();
-    }, 5_000).unref();
-  });
-}
-
-async function waitForBundledRuntimePortsReleased(timeoutMs = UPDATE_RUNTIME_RELEASE_TIMEOUT_MS) {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    const [bridgeReleased, remoteHubReleased] = await Promise.all([
-      isPortAvailable(activeBridgePort),
-      isPortAvailable(activeRemoteHubPort)
-    ]);
-    if (bridgeReleased && remoteHubReleased) return;
-    await new Promise(resolve => setTimeout(resolve, HEALTH_POLL_MS));
-  }
-  throw new Error(
-    `Bundled runtime ports did not release before update: bridge=${activeBridgePort}, remoteHub=${activeRemoteHubPort}`
-  );
-}
-
-async function prepareRuntimeForUpdateInstall() {
-  if (updateInstallSequenceStarted) return;
-  updateInstallSequenceStarted = true;
-  recurringProductUpdates?.stop();
-  isQuitting = true;
-  appendDesktopLog('[update] stopping bundled runtime before installer launch');
-  await stopBundledBridge();
-  await waitForBundledRuntimePortsReleased();
-  appendDesktopLog('[update] bundled runtime and ports are fully released');
-}
-
-async function recoverRuntimeAfterUpdateInstallError(error) {
-  appendDesktopLog(`[update:install-recovery] ${error?.stack || error}`);
-  isQuitting = false;
-  updateInstallSequenceStarted = false;
-  if (!bridgeChild || bridgeChild.exitCode !== null) {
-    await prepareBundledRuntime();
-  }
-  recurringProductUpdates?.start();
-}
-
-async function launchDesktop() {
-  const status = await prepareBundledRuntime();
-  const window = createMainWindow();
-  const appUrl = `http://127.0.0.1:${activeBridgePort}/mindcanvas`;
-  await window.loadURL(appUrl);
-  void promptForDownloadedUpdate();
-
-  if (process.env.MINDEXEC_DESKTOP_SMOKE === '1') {
-    writeSmokeResult({
-      ok: true,
-      appVersion: app.getVersion(),
-      bridgeVersion: status.version || null,
-      runtimeMode: 'bundled',
-      bridgePort: activeBridgePort,
-      remoteHubPort: activeRemoteHubPort,
-      workspace: activeWorkspace,
-      url: appUrl,
-      desktopUpdate: productUpdates?.getStatus() || null
-    });
-    setTimeout(() => app.quit(), 250).unref();
-  }
-}
-
-if (process.platform === 'win32') {
-  app.setAppUserModelId(DESKTOP_APP_ID);
-}
-
-const hasSingleInstanceLock = app.requestSingleInstanceLock();
-if (!hasSingleInstanceLock) {
-  app.quit();
-} else {
-  app.on('second-instance', () => {
-    if (mainWindow) {
-      if (mainWindow.isMinimized()) {
-        mainWindow.restore();
-      }
-      mainWindow.focus();
-    }
-  });
-
-  app.on('window-all-closed', () => {
-    app.quit();
-  });
-
-  app.on('before-quit', (event) => {
-    if (isQuitting || !bridgeChild || bridgeChild.exitCode !== null) {
-      return;
-    }
-
-    event.preventDefault();
-    recurringProductUpdates?.stop();
-    isQuitting = true;
-    stopBundledBridge().finally(() => app.exit(requestedExitCode));
-  });
-
-  app.whenReady()
-    .then(async () => {
-      initializeProductUpdates();
-      registerUpdateIpc();
-      void productUpdates.checkAtStartup().catch(error => {
-        appendDesktopLog(`[update:startup-error] ${error?.stack || error}`);
-      });
-      await launchDesktop();
-      recurringProductUpdates.start();
-    })
-    .catch((error) => {
-      const message = error?.stack || String(error);
-      appendDesktopLog(`[desktop:start-error] ${message}`);
-      writeSmokeResult({
-        ok: false,
-        appVersion: app.getVersion(),
-        runtimeMode: 'bundled',
-        error: error?.message || String(error)
-      });
-
-      requestedExitCode = 1;
-      if (process.env.MINDEXEC_DESKTOP_SMOKE !== '1') {
-        dialog.showErrorBox('MindExec failed to start', error?.message || String(error));
-      }
-      app.quit();
-    });
-}
+'use strict';
+
+const { app, BrowserWindow, dialog, ipcMain } = require('electron');
+const { spawn } = require('child_process');
+const fs = require('fs');
+const http = require('http');
+const net = require('net');
+const path = require('path');
+const workspaceState = require('../desktop-workspace-state.cjs');
+const { createProductUpdateManager } = require('./update-manager.cjs');
+const {
+  DEFAULT_UPDATE_INTERVAL_MS,
+  createRecurringProductUpdateOwner
+} = require('./recurring-update-owner.cjs');
+
+const { resolveDesktopWorkspace } = workspaceState;
+
+const DEFAULT_BRIDGE_PORT = 5147;
+const DEFAULT_REMOTE_HUB_PORT = 5198;
+const STARTUP_TIMEOUT_MS = 45_000;
+const HEALTH_POLL_MS = 250;
+const UPDATE_RUNTIME_RELEASE_TIMEOUT_MS = 10_000;
+const DESKTOP_APP_ID = 'com.mindexec.desktop';
+
+let mainWindow = null;
+let bridgeChild = null;
+let isQuitting = false;
+let requestedExitCode = 0;
+let activeBridgePort = DEFAULT_BRIDGE_PORT;
+let activeRemoteHubPort = DEFAULT_REMOTE_HUB_PORT;
+let activeWorkspace = '';
+let desktopWorkspaceStatePath = '';
+let productUpdates = null;
+let recurringProductUpdates = null;
+let updateInstallSequenceStarted = false;
+let updatePromptPromise = null;
+let updatePromptedVersion = '';
+
+function resolveDesktopIconPath() {
+  const iconPath = path.resolve(__dirname, '..', 'wwwroot', 'icon-512.png');
+  return fs.existsSync(iconPath) ? iconPath : undefined;
+}
+
+function resolveDesktopInstallKind() {
+  if (!app.isPackaged) return 'development';
+  if (process.env.PORTABLE_EXECUTABLE_FILE || process.env.PORTABLE_EXECUTABLE_DIR) return 'portable';
+  if (path.basename(path.dirname(process.execPath)).toLowerCase() === 'win-unpacked') return 'unpacked';
+  return process.platform === 'win32' ? 'installed' : 'unsupported-platform';
+}
+
+function parsePort(value) {
+  const parsed = Number.parseInt(String(value ?? ''), 10);
+  return Number.isInteger(parsed) && parsed > 0 && parsed <= 65_535 ? parsed : 0;
+}
+
+function requestJson(url, timeoutMs = 2_000) {
+  return new Promise((resolve, reject) => {
+    const request = http.get(url, { timeout: timeoutMs }, (response) => {
+      let body = '';
+      response.setEncoding('utf8');
+      response.on('data', (chunk) => {
+        body += chunk;
+      });
+      response.on('end', () => {
+        if (response.statusCode < 200 || response.statusCode >= 300) {
+          reject(new Error(`HTTP ${response.statusCode} from ${url}`));
+          return;
+        }
+
+        try {
+          resolve(JSON.parse(body));
+        } catch (error) {
+          reject(new Error(`Invalid JSON from ${url}: ${error.message}`));
+        }
+      });
+    });
+
+    request.on('timeout', () => {
+      request.destroy(new Error(`Timed out requesting ${url}`));
+    });
+    request.on('error', reject);
+  });
+}
+
+function isPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.unref();
+    server.once('error', () => resolve(false));
+    server.listen({ host: '127.0.0.1', port, exclusive: true }, () => {
+      server.close(() => resolve(true));
+    });
+  });
+}
+
+async function resolveDedicatedPort(explicitValue, defaultPort, label, excludedPort = 0) {
+  const explicitPort = parsePort(explicitValue);
+  if (explicitPort) {
+    if (explicitPort === excludedPort) {
+      throw new Error(`${label} port ${explicitPort} conflicts with the bundled LocalBridge port.`);
+    }
+    if (!await isPortAvailable(explicitPort)) {
+      throw new Error(`${label} port ${explicitPort} is already occupied.`);
+    }
+    return explicitPort;
+  }
+
+  for (let offset = 0; offset < 100; offset += 1) {
+    const candidate = defaultPort + offset;
+    if (candidate !== excludedPort && candidate <= 65_535 && await isPortAvailable(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new Error(`No free ${label} port was found from ${defaultPort}.`);
+}
+
+function appendDesktopLog(message) {
+  const line = `[${new Date().toISOString()}] ${message}\n`;
+  try {
+    const logDirectory = app.getPath('logs');
+    fs.mkdirSync(logDirectory, { recursive: true });
+    fs.appendFileSync(path.join(logDirectory, 'desktop.log'), line, 'utf8');
+  } catch {
+    process.stderr.write(line);
+  }
+}
+
+function spawnBundledBridge(packageRoot) {
+  const serverPath = path.join(packageRoot, 'server.js');
+  const frontendPath = path.join(packageRoot, 'wwwroot', 'index.html');
+  if (!fs.existsSync(serverPath)) {
+    throw new Error(`Bundled LocalBridge entry is missing: ${serverPath}`);
+  }
+  if (!fs.existsSync(frontendPath)) {
+    throw new Error(`Bundled MindCanvas frontend is missing: ${frontendPath}`);
+  }
+
+  const child = spawn(process.execPath, [serverPath], {
+    cwd: packageRoot,
+    env: {
+      ...process.env,
+      ELECTRON_RUN_AS_NODE: '1',
+      MINDEXEC_DESKTOP: '1',
+      MINDEXEC_NO_OPEN: '1',
+      MINDEXEC_DESKTOP_WORKSPACE_STATE_PATH: desktopWorkspaceStatePath,
+      WORKSPACE_PATH: activeWorkspace,
+      BRIDGE_PORT: String(activeBridgePort),
+      REMOTE_HUB_PORT: String(activeRemoteHubPort)
+    },
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true
+  });
+
+  child.stdout?.on('data', (chunk) => appendDesktopLog(`[bridge] ${String(chunk).trimEnd()}`));
+  child.stderr?.on('data', (chunk) => appendDesktopLog(`[bridge:error] ${String(chunk).trimEnd()}`));
+  child.on('error', (error) => appendDesktopLog(`[bridge:spawn-error] ${error.stack || error.message}`));
+  child.on('exit', (code, signal) => {
+    appendDesktopLog(`[bridge:exit] code=${String(code)} signal=${String(signal)}`);
+    if (!isQuitting && process.env.MINDEXEC_DESKTOP_SMOKE !== '1') {
+      dialog.showErrorBox(
+        'MindExec LocalBridge stopped',
+        `The bundled local runtime exited unexpectedly (code ${String(code)}, signal ${String(signal)}).`
+      );
+    }
+  });
+
+  bridgeChild = child;
+}
+
+async function waitForBundledBridge() {
+  const deadline = Date.now() + STARTUP_TIMEOUT_MS;
+  let lastError = null;
+
+  while (Date.now() < deadline) {
+    if (bridgeChild && bridgeChild.exitCode !== null) {
+      throw new Error(`Bundled LocalBridge exited during startup with code ${bridgeChild.exitCode}.`);
+    }
+
+    try {
+      const status = await requestJson(`http://127.0.0.1:${activeBridgePort}/api/status?refresh=cache`);
+      if (status?.status === 'ok' && status?.workspace) {
+        return status;
+      }
+    } catch (error) {
+      lastError = error;
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, HEALTH_POLL_MS));
+  }
+
+  throw new Error(
+    `Bundled LocalBridge did not become ready on port ${activeBridgePort}: ${lastError?.message || 'timeout'}`
+  );
+}
+
+async function prepareBundledRuntime() {
+  const packageRoot = path.resolve(__dirname, '..');
+  activeBridgePort = await resolveDedicatedPort(process.env.BRIDGE_PORT, DEFAULT_BRIDGE_PORT, 'LocalBridge');
+  activeRemoteHubPort = await resolveDedicatedPort(
+    process.env.REMOTE_HUB_PORT,
+    DEFAULT_REMOTE_HUB_PORT,
+    'RemoteHub',
+    activeBridgePort
+  );
+  desktopWorkspaceStatePath = path.resolve(
+    process.env.MINDEXEC_DESKTOP_WORKSPACE_STATE_PATH
+      || path.join(app.getPath('userData'), 'workspace-state.json')
+  );
+  const workspaceResolution = resolveDesktopWorkspace({
+    explicitWorkspace: process.env.MINDEXEC_DESKTOP_WORKSPACE || process.env.WORKSPACE_PATH,
+    statePath: desktopWorkspaceStatePath,
+    fallbackWorkspace: path.join(app.getPath('documents'), 'MindExecution')
+  });
+  activeWorkspace = workspaceResolution.workspacePath;
+
+  fs.mkdirSync(activeWorkspace, { recursive: true });
+  appendDesktopLog(
+    `Starting bundled runtime: bridge=${activeBridgePort}, remoteHub=${activeRemoteHubPort}, ` +
+    `workspace=${activeWorkspace}, workspaceSource=${workspaceResolution.source}`
+  );
+  spawnBundledBridge(packageRoot);
+  return waitForBundledBridge();
+}
+
+function assertTrustedUpdateIpc(event) {
+  const senderUrl = event?.senderFrame?.url || event?.sender?.getURL?.() || '';
+  let sender;
+  try {
+    sender = new URL(senderUrl);
+  } catch {
+    throw new Error('desktop-update-ipc-sender-invalid');
+  }
+  if (sender.protocol !== 'http:' || sender.hostname !== '127.0.0.1' || sender.port !== String(activeBridgePort)) {
+    throw new Error('desktop-update-ipc-sender-untrusted');
+  }
+}
+
+function registerUpdateIpc() {
+  const handle = (channel, callback) => {
+    ipcMain.handle(channel, async (event) => {
+      assertTrustedUpdateIpc(event);
+      return callback();
+    });
+  };
+  handle('updates:get-status', () => productUpdates?.getStatus() || { state: 'unavailable' });
+  handle('updates:check', () => productUpdates?.check() || Promise.resolve({ state: 'unavailable' }));
+  handle('updates:install', () => productUpdates?.install() || Promise.resolve({ state: 'unavailable' }));
+}
+
+function sendUpdateStatus(status) {
+  appendDesktopLog(
+    `[update] state=${status.state} current=${status.currentVersion || ''} ` +
+    `available=${status.availableVersion || ''} progress=${Math.round(status.progress || 0)} ` +
+    `kind=${status.installKind || ''}${status.error ? ` error=${status.error}` : ''}`
+  );
+  if (mainWindow && !mainWindow.isDestroyed() && !mainWindow.webContents.isDestroyed()) {
+    mainWindow.webContents.send('updates:status', status);
+  }
+  if (status.state === 'downloaded') void promptForDownloadedUpdate(status);
+}
+
+async function promptForDownloadedUpdate(status = productUpdates?.getStatus()) {
+  if (!status?.downloaded || !status.availableVersion || !mainWindow || mainWindow.isDestroyed()) return;
+  if (process.env.MINDEXEC_DESKTOP_SMOKE === '1') return;
+  if (updatePromptedVersion === status.availableVersion || updatePromptPromise) return updatePromptPromise;
+
+  updatePromptedVersion = status.availableVersion;
+  updatePromptPromise = dialog.showMessageBox(mainWindow, {
+    type: 'info',
+    title: 'MindExec update ready',
+    message: `MindExec ${status.availableVersion} is ready.`,
+    detail: 'Restart now to use the new development build. Your project folder and saved data stay unchanged.',
+    buttons: ['Restart and update', 'Later'],
+    defaultId: 0,
+    cancelId: 1,
+    noLink: true
+  }).then(result => {
+    if (result.response === 0) return productUpdates?.install();
+    return productUpdates?.getStatus();
+  }).catch(error => {
+    appendDesktopLog(`[update:prompt-error] ${error?.stack || error}`);
+    return productUpdates?.getStatus();
+  }).finally(() => {
+    updatePromptPromise = null;
+  });
+  return updatePromptPromise;
+}
+
+function initializeProductUpdates() {
+  productUpdates = createProductUpdateManager({
+    app,
+    installKind: resolveDesktopInstallKind(),
+    onStatus: sendUpdateStatus,
+    beforeInstall: prepareRuntimeForUpdateInstall,
+    onInstallError: recoverRuntimeAfterUpdateInstallError
+  });
+  recurringProductUpdates = createRecurringProductUpdateOwner({
+    manager: productUpdates,
+    canRun: () => !isQuitting && !updateInstallSequenceStarted,
+    initialDelayMs: DEFAULT_UPDATE_INTERVAL_MS,
+    intervalMs: DEFAULT_UPDATE_INTERVAL_MS,
+    onError: error => appendDesktopLog(`[update:recurring-error] ${error?.stack || error}`)
+  });
+}
+
+function createMainWindow() {
+  const hiddenSmokeMode = process.env.MINDEXEC_DESKTOP_SMOKE === '1';
+  const window = new BrowserWindow({
+    width: 1440,
+    height: 960,
+    minWidth: 960,
+    minHeight: 640,
+    show: !hiddenSmokeMode,
+    autoHideMenuBar: true,
+    backgroundColor: '#f8fafc',
+    title: 'MindExec',
+    icon: resolveDesktopIconPath(),
+    webPreferences: {
+      preload: path.join(__dirname, 'preload.cjs'),
+      contextIsolation: true,
+      nodeIntegration: false,
+      sandbox: true,
+      webSecurity: true
+    }
+  });
+
+  window.webContents.setWindowOpenHandler(() => ({
+    action: 'allow',
+    overrideBrowserWindowOptions: {
+      autoHideMenuBar: true,
+      icon: resolveDesktopIconPath(),
+      webPreferences: {
+        contextIsolation: true,
+        nodeIntegration: false,
+        sandbox: true,
+        webSecurity: true
+      }
+    }
+  }));
+
+  window.on('closed', () => {
+    if (mainWindow === window) {
+      mainWindow = null;
+    }
+  });
+
+  mainWindow = window;
+  return window;
+}
+
+function writeSmokeResult(payload) {
+  const resultPath = process.env.MINDEXEC_DESKTOP_SMOKE_RESULT;
+  if (!resultPath) {
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(resultPath), { recursive: true });
+  fs.writeFileSync(resultPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+
+async function stopBundledBridge() {
+  const child = bridgeChild;
+  bridgeChild = null;
+  if (!child || child.exitCode !== null) {
+    return;
+  }
+
+  await new Promise((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      resolve();
+    };
+
+    child.once('exit', finish);
+    try {
+      child.kill('SIGTERM');
+    } catch {
+      finish();
+      return;
+    }
+
+    setTimeout(() => {
+      if (child.exitCode === null) {
+        try {
+          child.kill('SIGKILL');
+        } catch {
+          // The child may have exited between the check and the kill.
+        }
+      }
+      finish();
+    }, 5_000).unref();
+  });
+}
+
+async function waitForBundledRuntimePortsReleased(timeoutMs = UPDATE_RUNTIME_RELEASE_TIMEOUT_MS) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const [bridgeReleased, remoteHubReleased] = await Promise.all([
+      isPortAvailable(activeBridgePort),
+      isPortAvailable(activeRemoteHubPort)
+    ]);
+    if (bridgeReleased && remoteHubReleased) return;
+    await new Promise(resolve => setTimeout(resolve, HEALTH_POLL_MS));
+  }
+  throw new Error(
+    `Bundled runtime ports did not release before update: bridge=${activeBridgePort}, remoteHub=${activeRemoteHubPort}`
+  );
+}
+
+async function prepareRuntimeForUpdateInstall() {
+  if (updateInstallSequenceStarted) return;
+  updateInstallSequenceStarted = true;
+  recurringProductUpdates?.stop();
+  isQuitting = true;
+  appendDesktopLog('[update] stopping bundled runtime before installer launch');
+  await stopBundledBridge();
+  await waitForBundledRuntimePortsReleased();
+  appendDesktopLog('[update] bundled runtime and ports are fully released');
+}
+
+async function recoverRuntimeAfterUpdateInstallError(error) {
+  appendDesktopLog(`[update:install-recovery] ${error?.stack || error}`);
+  isQuitting = false;
+  updateInstallSequenceStarted = false;
+  if (!bridgeChild || bridgeChild.exitCode !== null) {
+    await prepareBundledRuntime();
+  }
+  recurringProductUpdates?.start();
+}
+
+async function launchDesktop() {
+  const status = await prepareBundledRuntime();
+  const window = createMainWindow();
+  const appUrl = `http://127.0.0.1:${activeBridgePort}/mindcanvas`;
+  await window.loadURL(appUrl);
+  void promptForDownloadedUpdate();
+
+  if (process.env.MINDEXEC_DESKTOP_SMOKE === '1') {
+    writeSmokeResult({
+      ok: true,
+      appVersion: app.getVersion(),
+      bridgeVersion: status.version || null,
+      runtimeMode: 'bundled',
+      bridgePort: activeBridgePort,
+      remoteHubPort: activeRemoteHubPort,
+      workspace: activeWorkspace,
+      url: appUrl,
+      desktopUpdate: productUpdates?.getStatus() || null
+    });
+    setTimeout(() => app.quit(), 250).unref();
+  }
+}
+
+if (process.platform === 'win32') {
+  app.setAppUserModelId(DESKTOP_APP_ID);
+}
+
+const hasSingleInstanceLock = app.requestSingleInstanceLock();
+if (!hasSingleInstanceLock) {
+  app.quit();
+} else {
+  app.on('second-instance', () => {
+    if (mainWindow) {
+      if (mainWindow.isMinimized()) {
+        mainWindow.restore();
+      }
+      mainWindow.focus();
+    }
+  });
+
+  app.on('window-all-closed', () => {
+    app.quit();
+  });
+
+  app.on('before-quit', (event) => {
+    if (isQuitting || !bridgeChild || bridgeChild.exitCode !== null) {
+      return;
+    }
+
+    event.preventDefault();
+    recurringProductUpdates?.stop();
+    isQuitting = true;
+    stopBundledBridge().finally(() => app.exit(requestedExitCode));
+  });
+
+  app.whenReady()
+    .then(async () => {
+      initializeProductUpdates();
+      registerUpdateIpc();
+      void productUpdates.checkAtStartup().catch(error => {
+        appendDesktopLog(`[update:startup-error] ${error?.stack || error}`);
+      });
+      await launchDesktop();
+      recurringProductUpdates.start();
+    })
+    .catch((error) => {
+      const message = error?.stack || String(error);
+      appendDesktopLog(`[desktop:start-error] ${message}`);
+      writeSmokeResult({
+        ok: false,
+        appVersion: app.getVersion(),
+        runtimeMode: 'bundled',
+        error: error?.message || String(error)
+      });
+
+      requestedExitCode = 1;
+      if (process.env.MINDEXEC_DESKTOP_SMOKE !== '1') {
+        dialog.showErrorBox('MindExec failed to start', error?.message || String(error));
+      }
+      app.quit();
+    });
+}