feat(build): adopt electron-vite for dev + build pipeline

.github/workflows/e2e.yml

@@ -22,6 +22,12 @@ jobs:
 
       - run: npm ci
 
+      - name: Cache Playwright browsers
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-chromium-${{ runner.os }}-${{ hashFiles('app/packages/web/package-lock.json', 'package-lock.json') }}
+
       - name: Install Playwright browsers
         run: npx playwright install chromium --with-deps
         working-directory: app/packages/web

.github/workflows/integration.yml

@@ -22,6 +22,12 @@ jobs:
 
       - run: npm ci
 
+      - name: Cache Playwright browsers
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-chromium-${{ runner.os }}-${{ hashFiles('app/packages/web/package-lock.json', 'package-lock.json') }}
+
       - name: Install Playwright browsers
         run: npx playwright install chromium --with-deps
         working-directory: app/packages/web

CLAUDE.md

@@ -20,6 +20,11 @@ npm run app:dev
 # Production build (shared → server → web)
 npm run app:build && npm run app:start  # http://localhost:3001
 
+# Electron desktop app — electron-vite drives three pipelines (main/preload/renderer)
+# configured in electron.vite.config.ts; outputs land in out/main, out/preload, out/renderer
+npm run desktop:dev    # electron-vite dev: HMR on renderer saves, auto-restarts main+preload
+npm run desktop:build  # electron-vite build: produces out/main, out/preload, out/renderer
+
 # Build all Lambda bundles (required before `terraform apply`)
 npm run app:build:lambdas
 

app/eslint.config.js

@@ -10,6 +10,7 @@ export default tseslint.config(
   {
     ignores: [
       '**/dist/**',
+      '**/out/**',
       '**/node_modules/**',
       '**/*.d.ts',
       'packages/web/vite.config.ts',

app/package.json

@@ -5,11 +5,11 @@
   "type": "module",
   "scripts": {
     "predev": "node scripts/embed-tfstate.mjs",
-    "dev": "echo 'app:dev requires the Electron launcher from Epic A (#136). Run npm run dev -w @hyveon/web for the web-only dev server.' && exit 1",
+    "dev": "electron-vite dev",
     "prebuild": "node scripts/embed-tfstate.mjs",
     "build": "npm run build -w @hyveon/shared && npm run build -w @hyveon/desktop-main && npm run build -w @hyveon/web",
     "build:lambdas": "npm run build -w @hyveon/shared && npm run build -w @hyveon/lambda-interactions -w @hyveon/lambda-followup -w @hyveon/lambda-update-dns -w @hyveon/lambda-watchdog -w @hyveon/lambda-efs-seeder",
-    "start": "echo 'app:start requires the Electron launcher from Epic A (#136).' && exit 1",
+    "start": "electron-vite build",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",

app/packages/desktop-main/package.json

@@ -5,9 +5,9 @@
   "type": "module",
   "main": "./dist/main.js",
   "scripts": {
-    "dev": "echo 'desktop-main now runs as an Electron IPC microservice. The Electron launcher is wired in Epic A (#136).' && exit 1",
+    "dev": "electron-vite dev",
     "build": "tsc -b",
-    "start": "echo 'desktop-main now runs as an Electron IPC microservice. The Electron launcher is wired in Epic A (#136).' && exit 1"
+    "start": "electron-vite build"
   },
   "dependencies": {
     "@aws-sdk/client-cloudwatch-logs": "^3.600.0",

app/packages/desktop-main/src/electron-entry.test.ts

@@ -0,0 +1,241 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+/*
+ * Spy variables must be hoisted before vi.mock() factories run, because
+ * vi.mock() calls are lifted to the top of the compiled output above regular
+ * declarations.
+ */
+const {
+  mockLoadURL,
+  mockLoadFile,
+  mockQuit,
+  mockOn,
+  mockWhenReady,
+  MockBrowserWindow,
+  mockGetAllWindows,
+  bootstrapMock,
+  whenReadyCallbacks,
+  onCallbacks,
+} = vi.hoisted(() => {
+  const mockLoadURL = vi.fn().mockResolvedValue(undefined);
+  const mockLoadFile = vi.fn().mockResolvedValue(undefined);
+  const mockQuit = vi.fn();
+  const mockGetAllWindows = vi.fn().mockReturnValue([]);
+
+  /**
+   * Collects every callback passed to `app.whenReady().then(cb)`.
+   * Tests can fire them on demand by calling `whenReadyCallbacks[n]()`.
+   */
+  const whenReadyCallbacks: Array<() => void> = [];
+
+  /**
+   * Collects every callback registered via `app.on(event, cb)` keyed by
+   * event name, so tests can trigger lifecycle events synchronously.
+   */
+  const onCallbacks: Record<string, () => void> = {};
+
+  const mockOn = vi.fn((event: string, cb: () => void) => {
+    onCallbacks[event] = cb;
+  });
+
+  /**
+   * Returns a thenable that stores the `.then()` callback instead of
+   * resolving it, giving tests full control over when the ready handler fires.
+   */
+  const mockWhenReady = vi.fn(() => ({
+    then: (cb: () => void) => {
+      whenReadyCallbacks.push(cb);
+      return { then: vi.fn() };
+    },
+  }));
+
+  /** Spy BrowserWindow constructor whose instances expose controlled load fns. */
+  const MockBrowserWindow = vi.fn().mockImplementation(() => ({
+    loadURL: mockLoadURL,
+    loadFile: mockLoadFile,
+  }));
+
+  /** `BrowserWindow.getAllWindows()` static method used by the activate handler. */
+  MockBrowserWindow.getAllWindows = mockGetAllWindows;
+
+  /** Spy for `bootstrap` imported from `./main.js`. */
+  const bootstrapMock = vi.fn().mockResolvedValue(undefined);
+
+  return {
+    mockLoadURL,
+    mockLoadFile,
+    mockQuit,
+    mockOn,
+    mockWhenReady,
+    MockBrowserWindow,
+    mockGetAllWindows,
+    bootstrapMock,
+    whenReadyCallbacks,
+    onCallbacks,
+  };
+});
+
+vi.mock('electron', () => ({
+  app: {
+    whenReady: mockWhenReady,
+    on: mockOn,
+    quit: mockQuit,
+  },
+  BrowserWindow: MockBrowserWindow,
+}));
+
+vi.mock('./main.js', () => ({
+  bootstrap: bootstrapMock,
+}));
+
+/** Flush the micro-task / timer queue so async chains fully settle. */
+async function flushPromises(): Promise<void> {
+  await new Promise<void>((resolve) => setTimeout(resolve, 0));
+}
+
+describe('electron-entry', () => {
+  beforeEach(() => {
+    mockLoadURL.mockResolvedValue(undefined);
+    mockLoadFile.mockResolvedValue(undefined);
+    mockQuit.mockImplementation(() => undefined);
+    bootstrapMock.mockResolvedValue(undefined);
+    mockGetAllWindows.mockReturnValue([]);
+
+    // Re-apply the BrowserWindow constructor implementation in case clearMocks
+    // cleared it between tests (clearMocks resets call history and return value
+    // queues; mockImplementation persists, but we re-set to be defensive).
+    MockBrowserWindow.mockImplementation(() => ({
+      loadURL: mockLoadURL,
+      loadFile: mockLoadFile,
+    }));
+
+    // Re-apply mockOn and mockWhenReady implementations so callback capturing
+    // works correctly after clearMocks resets the call history.
+    mockOn.mockImplementation((event: string, cb: () => void) => {
+      onCallbacks[event] = cb;
+    });
+    mockWhenReady.mockImplementation(() => ({
+      then: (cb: () => void) => {
+        whenReadyCallbacks.push(cb);
+        return { then: vi.fn() };
+      },
+    }));
+
+    // Reset the callback queues so each test starts clean.
+    whenReadyCallbacks.length = 0;
+    for (const key of Object.keys(onCallbacks)) {
+      delete onCallbacks[key];
+    }
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it('should call bootstrap() inside the app.whenReady() callback', async () => {
+    vi.resetModules();
+    delete process.env['ELECTRON_RENDERER_URL'];
+
+    await import('./electron-entry.js');
+    await flushPromises();
+
+    // Fire the whenReady callback that the module registered at import time.
+    expect(whenReadyCallbacks).toHaveLength(1);
+    whenReadyCallbacks[0]!();
+    await flushPromises();
+
+    expect(bootstrapMock).toHaveBeenCalledOnce();
+  });
+
+  it('should call win.loadURL() with the dev server URL when ELECTRON_RENDERER_URL is set', async () => {
+    vi.resetModules();
+    process.env['ELECTRON_RENDERER_URL'] = 'http://localhost:5173';
+
+    await import('./electron-entry.js');
+    await flushPromises();
+
+    expect(whenReadyCallbacks).toHaveLength(1);
+    whenReadyCallbacks[0]!();
+    await flushPromises();
+
+    expect(mockLoadURL).toHaveBeenCalledOnce();
+    expect(mockLoadURL).toHaveBeenCalledWith('http://localhost:5173');
+    expect(mockLoadFile).not.toHaveBeenCalled();
+  });
+
+  it('should call win.loadFile() with the production renderer path when ELECTRON_RENDERER_URL is not set', async () => {
+    vi.resetModules();
+    delete process.env['ELECTRON_RENDERER_URL'];
+
+    await import('./electron-entry.js');
+    await flushPromises();
+
+    expect(whenReadyCallbacks).toHaveLength(1);
+    whenReadyCallbacks[0]!();
+    await flushPromises();
+
+    expect(mockLoadFile).toHaveBeenCalledOnce();
+    expect(mockLoadURL).not.toHaveBeenCalled();
+
+    // The path must end with the standard electron-vite renderer bundle location.
+    const calledPath = mockLoadFile.mock.calls[0]?.[0] as string;
+    expect(calledPath).toMatch(/renderer[/\\]index\.html$/);
+  });
+
+  it('should call app.quit() on window-all-closed for non-macOS platforms', async () => {
+    vi.resetModules();
+    delete process.env['ELECTRON_RENDERER_URL'];
+
+    await import('./electron-entry.js');
+    await flushPromises();
+
+    const handler = onCallbacks['window-all-closed'];
+    expect(handler).toBeDefined();
+
+    const originalPlatform = process.platform;
+    Object.defineProperty(process, 'platform', { value: 'linux', configurable: true });
+
+    handler!();
+
+    expect(mockQuit).toHaveBeenCalledOnce();
+
+    Object.defineProperty(process, 'platform', { value: originalPlatform, configurable: true });
+  });
+
+  it('should NOT call app.quit() on window-all-closed on macOS', async () => {
+    vi.resetModules();
+    delete process.env['ELECTRON_RENDERER_URL'];
+
+    await import('./electron-entry.js');
+    await flushPromises();
+
+    const handler = onCallbacks['window-all-closed'];
+    expect(handler).toBeDefined();
+
+    const originalPlatform = process.platform;
+    Object.defineProperty(process, 'platform', { value: 'darwin', configurable: true });
+
+    handler!();
+
+    expect(mockQuit).not.toHaveBeenCalled();
+
+    Object.defineProperty(process, 'platform', { value: originalPlatform, configurable: true });
+  });
+
+  it('should call app.quit() and not open a window when bootstrap() rejects', async () => {
+    vi.resetModules();
+    delete process.env['ELECTRON_RENDERER_URL'];
+
+    bootstrapMock.mockRejectedValueOnce(new Error('IPC init failure'));
+
+    await import('./electron-entry.js');
+    await flushPromises();
+
+    expect(whenReadyCallbacks).toHaveLength(1);
+    whenReadyCallbacks[0]!();
+    await flushPromises();
+
+    expect(mockQuit).toHaveBeenCalledOnce();
+    expect(MockBrowserWindow).not.toHaveBeenCalled();
+  });
+});

app/packages/desktop-main/src/electron-entry.ts

@@ -0,0 +1,55 @@
+import { app, BrowserWindow } from 'electron';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { bootstrap } from './main.js';
+
+// electron-vite injects __dirname for main-process entries, but we also
+// compute it explicitly via import.meta.url so the file is valid plain ESM.
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Creates the main application window with the preload script wired in and
+ * loads either the dev server URL or the production renderer bundle.
+ */
+function createWindow(): void {
+  const win = new BrowserWindow({
+    width: 1200,
+    height: 800,
+    webPreferences: {
+      // electron-vite outputs the preload bundle to out/preload/index.js by
+      // default. __dirname here resolves to out/main, so we go one level up.
+      preload: path.join(__dirname, '../preload/index.js'),
+      contextIsolation: true,
+      sandbox: true,
+    },
+  });
+
+  if (process.env.ELECTRON_RENDERER_URL) {
+    void win.loadURL(process.env.ELECTRON_RENDERER_URL);
+  } else {
+    void win.loadFile(path.join(__dirname, '../renderer/index.html'));
+  }
+}
+
+app.whenReady().then(() => {
+  bootstrap()
+    .then(() => {
+      createWindow();
+
+      // On macOS re-create the window when the dock icon is clicked and there
+      // are no other windows open (standard macOS behaviour).
+      app.on('activate', () => {
+        if (BrowserWindow.getAllWindows().length === 0) createWindow();
+      });
+    })
+    .catch((err: unknown) => {
+      console.error('[desktop-main] NestJS IPC bootstrap failed — quitting:', err);
+      app.quit();
+    });
+});
+
+// Quit the app when all windows are closed, except on macOS where the app and
+// its menu bar conventionally stay active until the user explicitly quits.
+app.on('window-all-closed', () => {
+  if (process.platform !== 'darwin') app.quit();
+});