Function startSidecar

apps/desktop/src/main/sidecar.ts:212–373

(options: StartOptions = {})

  new Promise((resolveDelay) => setTimeout(resolveDelay, ms));

export async function startSidecar(options: StartOptions = {}): Promise<SidecarConnection> {
  const hostname = options.hostname ?? "127.0.0.1";
  const settings = getServerSettings();
  // data.db and the optional executor.jsonc plugin manifest live under
  // ~/.executor — the same path the CLI's `executor web` uses. Desktop and CLI
  // share state on the same machine so sources/secrets/policies set up in one
  // show up in the other, and user-facing commands like
  // `executor mcp --scope ~/.executor` stay copy-paste-friendly. Electron's
  // userData (set in main/index.ts) is still used for electron-store,
  // electron-log, and window-state — those stay app-scoped to avoid colliding
  // with anything else under HOME.
  const scopeDir = join(homedir(), ".executor");
  const dataDir = scopeDir;
  mkdirSync(dataDir, { recursive: true });

  // The stable bearer token from auth.json (shared with the CLI). The main
  // process holds it so it can inject the header into the webview; the child
  // validates against the same value. Always present — auth is unconditional.
  const authToken = loadOrMintLocalAuthToken(dataDir);
  const { command, args, cwd, cliManagedManifest } = resolveSidecarCommand({
    port: settings.port,
    hostname,
    authToken,
  });
  const clientDir = cliManagedManifest ? null : resolveClientDir();

  if (!cliManagedManifest && clientDir && !existsSync(clientDir)) {
    // oxlint-disable-next-line executor/no-error-constructor, executor/no-try-catch-or-throw -- boundary: startup failure is surfaced in the Electron main process
    throw new Error(
      `Executor client bundle not found at ${clientDir}. Run \`bun run --filter @executor-js/local build\` before launching desktop.`,
    );
  }

  // No process-level startup lock: the dev sidecar child opens the DB through
  // openOwnedLocalDatabase, whose ownership lock is the real gate. If the child
  // loses the race, startup fails as before; only the packaged supervised boot
  // path attaches to an existing daemon.
  const webBaseUrl = `http://${hostname}:${settings.port}`;
  const child = spawn(command, args, {
    cwd,
    stdio: ["ignore", "pipe", "pipe"],
    env: {
      ...process.env,
      EXECUTOR_PORT: String(settings.port),
      EXECUTOR_HOST: hostname,
      EXECUTOR_WEB_BASE_URL: webBaseUrl,
      PORT: String(settings.port),
      // The bearer token the child validates and the main process injects into
      // the webview. Always set — auth is unconditional.
      EXECUTOR_AUTH_TOKEN: authToken,
      ...(clientDir ? { EXECUTOR_CLIENT_DIR: clientDir } : {}),
      EXECUTOR_SCOPE_DIR: scopeDir,
      EXECUTOR_DATA_DIR: dataDir,
      EXECUTOR_CLIENT: "desktop",
      // Crash reporting (desktop builds with a baked-in DSN only). The
      // CLI's `executor web` never sets these, so the shared server code
      // stays telemetry-free outside the desktop app.
      ...sidecarCrashReportingEnv(),