groundwork-method 0.0.1 → 0.11.0

package/src/generators/electron-app/files/project.json.template

@@ -0,0 +1,65 @@
+{
+  "name": "<%= fileName %>",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "projectType": "application",
+  "sourceRoot": "services/<%= fileName %>/src",
+  "tags": ["surface:desktop", "stack:electron"],
+  "targets": {
+    "bootstrap": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tool/electron_exec.sh bootstrap",
+        "cwd": "services/<%= fileName %>"
+      }
+    },
+    "run": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tool/electron_exec.sh run",
+        "cwd": "services/<%= fileName %>"
+      }
+    },
+    "build": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tool/electron_exec.sh build",
+        "cwd": "services/<%= fileName %>"
+      }
+    },
+    "lint": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tool/electron_exec.sh lint",
+        "cwd": "services/<%= fileName %>"
+      }
+    },
+    "typecheck": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tool/electron_exec.sh typecheck",
+        "cwd": "services/<%= fileName %>"
+      }
+    },
+    "test": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tool/electron_exec.sh test",
+        "cwd": "services/<%= fileName %>"
+      }
+    },
+    "smoke": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tool/electron_exec.sh smoke",
+        "cwd": "services/<%= fileName %>"
+      }
+    },
+    "package": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bash tool/electron_exec.sh package",
+        "cwd": "services/<%= fileName %>"
+      }
+    }
+  }
+}

package/src/generators/electron-app/files/src/main/core-client.test.ts

@@ -0,0 +1,81 @@
+// The core-access seam is proven without a network: fetch is injected, so
+// every reachability outcome (ok, non-200, thrown) is a deterministic case.
+import { describe, expect, it } from 'vitest';
+import {
+  DEFAULT_CORE_BASE_URL,
+  coreAuthHeaders,
+  coreBaseUrl,
+  fetchCoreHealth,
+} from './core-client';
+
+function fetchReturning(status: number, body: unknown): typeof fetch {
+  return (async () =>
+    new Response(JSON.stringify(body), {
+      status,
+      headers: { 'Content-Type': 'application/json' },
+    })) as typeof fetch;
+}
+
+describe('coreBaseUrl', () => {
+  it('defaults to the workspace gateway', () => {
+    expect(coreBaseUrl({})).toBe(DEFAULT_CORE_BASE_URL);
+  });
+
+  it('honours API_BASE_URL from the environment', () => {
+    expect(coreBaseUrl({ API_BASE_URL: 'http://10.0.0.5:4000' })).toBe(
+      'http://10.0.0.5:4000',
+    );
+  });
+
+  it('treats a blank API_BASE_URL as unset', () => {
+    expect(coreBaseUrl({ API_BASE_URL: '  ' })).toBe(DEFAULT_CORE_BASE_URL);
+  });
+});
+
+describe('coreAuthHeaders', () => {
+  it('is unauthenticated by default', () => {
+    expect(coreAuthHeaders()).toEqual({});
+  });
+
+  it('carries a supplied token as a Bearer header', () => {
+    expect(coreAuthHeaders('jwt-123')).toEqual({
+      Authorization: 'Bearer jwt-123',
+    });
+  });
+});
+
+describe('fetchCoreHealth', () => {
+  it('maps a healthy core to reachable + its reported status', async () => {
+    const health = await fetchCoreHealth(
+      'http://core.test',
+      fetchReturning(200, { status: 'ok', checks: { db: 'ok' } }),
+    );
+    expect(health).toEqual({ reachable: true, status: 'ok' });
+  });
+
+  it('requests the /health route of the configured base URL', async () => {
+    let requested: string | undefined;
+    const probe = (async (input: Parameters<typeof fetch>[0]) => {
+      requested = String(input);
+      return new Response('{"status":"ok"}', { status: 200 });
+    }) as typeof fetch;
+    await fetchCoreHealth('http://core.test:4000', probe);
+    expect(requested).toBe('http://core.test:4000/health');
+  });
+
+  it('maps a non-200 to unreachable with the code as the status', async () => {
+    const health = await fetchCoreHealth(
+      'http://core.test',
+      fetchReturning(503, { error: 'overloaded' }),
+    );
+    expect(health).toEqual({ reachable: false, status: 'http 503' });
+  });
+
+  it('maps a network failure to a value, never a throw', async () => {
+    const down = (async () => {
+      throw new Error('ECONNREFUSED');
+    }) as typeof fetch;
+    const health = await fetchCoreHealth('http://core.test', down);
+    expect(health).toEqual({ reachable: false, status: 'unreachable' });
+  });
+});

package/src/generators/electron-app/files/src/main/core-client.ts

@@ -0,0 +1,55 @@
+// The core-access seam: the ONLY place this app talks to the workspace
+// gateway. The sandboxed renderer cannot reach the core directly (CSP locks
+// it to the bundle origin), so it asks over the typed bridge and main makes
+// the request — the desktop twin of the mobile scaffold's thin dio client
+// (docs/principles/stack/electron/ipc-contracts.md).
+//
+// Contract-client stance (O8): hand-rolled and deliberately thin — one
+// function per promoted-contract operation, typed results in src/shared/.
+// When the promoted openapi.yaml grows past a handful of operations, switch
+// to a generated TypeScript client and keep this module as the seam the IPC
+// handlers consume — nothing across the bridge changes.
+import type { CoreHealth } from '../shared/ipc';
+
+export const DEFAULT_CORE_BASE_URL = 'http://localhost:4000';
+
+/** Where the workspace core lives. The system-test harness (and any packaged
+ *  environment) overrides via the API_BASE_URL environment variable. */
+export function coreBaseUrl(env: NodeJS.ProcessEnv = process.env): string {
+  const configured = env['API_BASE_URL']?.trim();
+  return configured ? configured : DEFAULT_CORE_BASE_URL;
+}
+
+/** The auth seam: headers attached to every core request. Unauthenticated by
+ *  default — wire your identity provider here (e.g. a session JWT becomes
+ *  `Authorization: Bearer <token>`); the core's /health route stays public. */
+export function coreAuthHeaders(token?: string): Record<string, string> {
+  return token ? { Authorization: `Bearer ${token}` } : {};
+}
+
+/** Probe the gateway's health endpoint — the wiring proof the renderer's
+ *  home view displays. `/health` is what GroundWork's Go and Python cores
+ *  serve; a Next.js BFF would be `/api/healthz` — adjust to your gateway.
+ *  Failures map to a value, never a throw: an unreachable core is a state
+ *  the UI renders, not an exception that kills the handler. */
+export async function fetchCoreHealth(
+  baseUrl: string = coreBaseUrl(),
+  fetchImpl: typeof fetch = fetch,
+): Promise<CoreHealth> {
+  try {
+    const response = await fetchImpl(new URL('/health', baseUrl), {
+      headers: { Accept: 'application/json', ...coreAuthHeaders() },
+      signal: AbortSignal.timeout(5_000),
+    });
+    if (!response.ok) {
+      return { reachable: false, status: `http ${response.status}` };
+    }
+    const body = (await response.json()) as { status?: unknown };
+    return {
+      reachable: true,
+      status: typeof body.status === 'string' ? body.status : 'ok',
+    };
+  } catch {
+    return { reachable: false, status: 'unreachable' };
+  }
+}

package/src/generators/electron-app/files/src/main/index.ts

@@ -0,0 +1,157 @@
+import {
+  app,
+  BrowserWindow,
+  nativeTheme,
+  net,
+  protocol,
+  session,
+  shell,
+} from 'electron';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { registerIpcHandlers } from './ipc';
+import {
+  APP_ORIGIN,
+  APP_SCHEME,
+  isAllowedExternalUrl,
+  isContainedPath,
+  isTrustedNavigationTarget,
+} from './policy';
+
+// Main is an orchestrator and nothing more: window creation, security policy,
+// IPC registration, OS integration. CPU-heavy or crash-prone work belongs in a
+// utilityProcess with MessagePorts wired renderer↔utility directly — never
+// here, where it would starve every window's event loop
+// (docs/principles/stack/electron/process-model.md).
+
+// Set by electron-vite during `dev`; absent in built/packaged runs.
+const DEV_SERVER_URL = process.env['ELECTRON_RENDERER_URL'];
+
+// Must run before app ready: the bundle protocol needs standard-scheme
+// privileges so the renderer keeps ordinary web security semantics.
+protocol.registerSchemesAsPrivileged([
+  {
+    scheme: APP_SCHEME,
+    privileges: { standard: true, secure: true, supportFetchAPI: true },
+  },
+]);
+
+/** Serve the built renderer over the custom bundle protocol — never file://
+ *  (docs/principles/stack/electron/security.md). Paths are resolved against
+ *  the renderer output and containment-checked against traversal. */
+function registerBundleProtocol(): void {
+  const rendererRoot = path.join(__dirname, '../renderer');
+  protocol.handle(APP_SCHEME, (request) => {
+    const { pathname } = new URL(request.url);
+    const requested = pathname === '/' ? '/index.html' : decodeURIComponent(pathname);
+    const target = path.resolve(rendererRoot, `.${requested}`);
+    if (!isContainedPath(rendererRoot, target, path.sep)) {
+      return new Response('Not found', { status: 404 });
+    }
+    return net.fetch(pathToFileURL(target).toString());
+  });
+}
+
+/** Global policy, registered before any window exists. */
+function applySecurityPolicy(): void {
+  // Permission requests (camera, microphone, geolocation, ...) are denied by
+  // default — in a desktop app, content that asks unexpectedly is the attack.
+  // Grant individual permissions here only as a recorded product decision
+  // (docs/principles/stack/electron/security.md).
+  session.defaultSession.setPermissionRequestHandler(
+    (_webContents, _permission, callback) => {
+      callback(false);
+    },
+  );
+
+  app.on('web-contents-created', (_event, contents) => {
+    // Navigation away from app content is blocked outright.
+    contents.on('will-navigate', (event, url) => {
+      if (!isTrustedNavigationTarget(url, DEV_SERVER_URL)) {
+        event.preventDefault();
+      }
+    });
+    // window.open never creates an Electron window: allowlisted https links
+    // are handed to the OS browser; everything else is dropped.
+    contents.setWindowOpenHandler(({ url }) => {
+      if (isAllowedExternalUrl(url)) {
+        void shell.openExternal(url);
+      }
+      return { action: 'deny' };
+    });
+  });
+}
+
+function broadcastTheme(window: BrowserWindow): void {
+  window.webContents.send('theme:changed', {
+    shouldUseDarkColors: nativeTheme.shouldUseDarkColors,
+  });
+}
+
+function createWindow(): BrowserWindow {
+  const window = new BrowserWindow({
+    width: 1080,
+    height: 720,
+    show: false,
+    autoHideMenuBar: true,
+    webPreferences: {
+      preload: path.join(__dirname, '../preload/index.js'),
+      // The hardened quartet. These are Electron's own defaults, restated so
+      // no code path, flag, or debugging session ever loosens them — the
+      // controls fail as a set, not individually
+      // (docs/principles/stack/electron/security.md).
+      contextIsolation: true,
+      sandbox: true,
+      nodeIntegration: false,
+      webSecurity: true,
+    },
+  });
+
+  window.on('ready-to-show', () => window.show());
+  // Initial theme push once the renderer can receive it; updates are
+  // broadcast from the nativeTheme listener below.
+  window.webContents.on('did-finish-load', () => broadcastTheme(window));
+
+  if (DEV_SERVER_URL) {
+    void window.loadURL(DEV_SERVER_URL);
+  } else {
+    void window.loadURL(`${APP_ORIGIN}/`);
+  }
+  return window;
+}
+
+// Squirrel.Windows ties notifications and shortcuts to the AppUserModelID
+// (docs/principles/stack/electron/packaging-and-updates.md).
+if (process.platform === 'win32') {
+  app.setAppUserModelId('<%= appId %>');
+}
+
+void app.whenReady().then(() => {
+  if (!DEV_SERVER_URL) {
+    registerBundleProtocol();
+  }
+  applySecurityPolicy();
+  registerIpcHandlers(DEV_SERVER_URL);
+
+  // nativeTheme is the source of truth for dark mode; the renderer mirrors it
+  // onto <html data-theme> from this broadcast.
+  nativeTheme.on('updated', () => {
+    for (const window of BrowserWindow.getAllWindows()) {
+      broadcastTheme(window);
+    }
+  });
+
+  createWindow();
+
+  app.on('activate', () => {
+    if (BrowserWindow.getAllWindows().length === 0) {
+      createWindow();
+    }
+  });
+});
+
+app.on('window-all-closed', () => {
+  if (process.platform !== 'darwin') {
+    app.quit();
+  }
+});

package/src/generators/electron-app/files/src/main/ipc.ts

@@ -0,0 +1,52 @@
+import { app, ipcMain, shell } from 'electron';
+import { z } from 'zod';
+import type { AppStatus, CoreHealth, OpenExternalResult } from '../shared/ipc';
+import { fetchCoreHealth } from './core-client';
+import { isAllowedExternalUrl, isTrustedSender } from './policy';
+
+// Main treats renderer input as untrusted, the same way an API treats the
+// public internet. Two checks in every handler: sender validation
+// (event.senderFrame — checklist item 17), and zod payload validation for
+// anything beyond a trivial getter, because compile-time types vanish at
+// runtime and a compromised renderer is not bound by them
+// (docs/principles/stack/electron/ipc-contracts.md).
+
+const openExternalPayload = z.string().url();
+
+function assertTrustedSender(
+  event: Electron.IpcMainInvokeEvent,
+  devServerUrl?: string,
+): void {
+  if (!isTrustedSender(event.senderFrame?.url, devServerUrl)) {
+    throw new Error('IPC call rejected: untrusted sender frame');
+  }
+}
+
+export function registerIpcHandlers(devServerUrl?: string): void {
+  ipcMain.handle('app:get-status', (event): AppStatus => {
+    assertTrustedSender(event, devServerUrl);
+    return {
+      status: 'ok',
+      version: app.getVersion(),
+      platform: process.platform,
+    };
+  });
+
+  ipcMain.handle('core:health', async (event): Promise<CoreHealth> => {
+    assertTrustedSender(event, devServerUrl);
+    return fetchCoreHealth();
+  });
+
+  ipcMain.handle(
+    'shell:open-external',
+    async (event, rawUrl: unknown): Promise<OpenExternalResult> => {
+      assertTrustedSender(event, devServerUrl);
+      const url = openExternalPayload.parse(rawUrl);
+      if (!isAllowedExternalUrl(url)) {
+        return { opened: false };
+      }
+      await shell.openExternal(url);
+      return { opened: true };
+    },
+  );
+}

package/src/generators/electron-app/files/src/main/policy.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+import {
+  APP_ORIGIN,
+  isAllowedExternalUrl,
+  isContainedPath,
+  isTrustedNavigationTarget,
+  isTrustedSender,
+} from './policy';
+
+// The security policy is pure (no Electron imports), so the privileged
+// decisions are proven in a plain Node environment. The boot smoke
+// (tests/smoke/) proves the wiring; these tests prove the rules.
+
+describe('isAllowedExternalUrl', () => {
+  it('allows https URLs', () => {
+    expect(isAllowedExternalUrl('https://example.com/docs')).toBe(true);
+  });
+
+  it.each([
+    'http://example.com',
+    'file:///etc/passwd',
+    'javascript:alert(1)',
+    'smb://attacker/share',
+    'not a url',
+    '',
+  ])('rejects %s', (url) => {
+    expect(isAllowedExternalUrl(url)).toBe(false);
+  });
+});
+
+describe('isTrustedNavigationTarget', () => {
+  it('allows the bundle protocol', () => {
+    expect(isTrustedNavigationTarget(`${APP_ORIGIN}/index.html`)).toBe(true);
+  });
+
+  it('allows the dev server origin only while developing', () => {
+    expect(
+      isTrustedNavigationTarget('http://localhost:5173/', 'http://localhost:5173'),
+    ).toBe(true);
+    expect(isTrustedNavigationTarget('http://localhost:5173/')).toBe(false);
+  });
+
+  it('rejects everything else', () => {
+    expect(isTrustedNavigationTarget('https://attacker.example')).toBe(false);
+    expect(isTrustedNavigationTarget('file:///etc/passwd')).toBe(false);
+    expect(isTrustedNavigationTarget('')).toBe(false);
+  });
+});
+
+describe('isTrustedSender', () => {
+  it('rejects a missing frame (destroyed sender)', () => {
+    expect(isTrustedSender(undefined)).toBe(false);
+  });
+
+  it('accepts the app frame', () => {
+    expect(isTrustedSender(`${APP_ORIGIN}/`)).toBe(true);
+  });
+});
+
+describe('isContainedPath', () => {
+  it('accepts files inside the root', () => {
+    expect(isContainedPath('/out/renderer', '/out/renderer/index.html')).toBe(true);
+    expect(isContainedPath('/out/renderer', '/out/renderer/assets/app.css')).toBe(true);
+  });
+
+  it('rejects traversal escapes and the root itself', () => {
+    expect(isContainedPath('/out/renderer', '/out/secret.js')).toBe(false);
+    expect(isContainedPath('/out/renderer', '/out/renderer-evil/x')).toBe(false);
+    expect(isContainedPath('/out/renderer', '/out/renderer')).toBe(false);
+  });
+});

package/src/generators/electron-app/files/src/main/policy.ts

@@ -0,0 +1,73 @@
+// Pure security policy — no Electron imports, so every rule in this file is
+// unit-testable in a plain Node environment (src/main/policy.test.ts) and the
+// privileged decisions live in one reviewable place.
+
+/** The custom protocol the packaged renderer is served over. file:// is never
+ *  used: it grants origin-level filesystem access and breaks web security
+ *  semantics (docs/principles/stack/electron/security.md). */
+export const APP_SCHEME = 'app';
+export const APP_ORIGIN = `${APP_SCHEME}://bundle`;
+
+/** shell.openExternal launches whatever the OS associates with the input, so
+ *  it only ever receives validated, allowlisted URLs. https-only is the
+ *  baseline; widen it per-scheme as a recorded product decision, never with a
+ *  pass-through. */
+export function isAllowedExternalUrl(raw: string): boolean {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return false;
+  }
+  return url.protocol === 'https:';
+}
+
+/** Navigation policy for will-navigate: app content stays on the bundle
+ *  protocol (or the dev server while developing). Everything else is blocked —
+ *  a renderer that can navigate to an attacker's page hands the attacker a
+ *  privileged-adjacent context. */
+export function isTrustedNavigationTarget(
+  raw: string,
+  devServerUrl?: string,
+): boolean {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return false;
+  }
+  if (url.protocol === `${APP_SCHEME}:`) return true;
+  if (devServerUrl) {
+    try {
+      if (url.origin === new URL(devServerUrl).origin) return true;
+    } catch {
+      // unparseable dev URL — fall through to deny
+    }
+  }
+  return false;
+}
+
+/** Sender validation for every IPC handler (security checklist item 17): the
+ *  call must come from this app's own frame, not an iframe or a navigated-away
+ *  window. A missing frame (destroyed sender) is rejected. */
+export function isTrustedSender(
+  frameUrl: string | undefined,
+  devServerUrl?: string,
+): boolean {
+  if (!frameUrl) return false;
+  return isTrustedNavigationTarget(frameUrl, devServerUrl);
+}
+
+/** Containment check for the bundle protocol handler: the resolved path must
+ *  stay inside the renderer output directory (no traversal escapes). The
+ *  separator is a parameter so the rule stays pure and testable; callers pass
+ *  path.sep. */
+export function isContainedPath(
+  rootDir: string,
+  target: string,
+  sep = '/',
+): boolean {
+  if (target === rootDir) return false; // the root itself is not a file
+  const root = rootDir.endsWith(sep) ? rootDir : `${rootDir}${sep}`;
+  return target.startsWith(root);
+}

package/src/generators/electron-app/files/src/preload/index.ts

@@ -0,0 +1,23 @@
+import { contextBridge, ipcRenderer } from 'electron';
+import type { RendererApi, ThemeInfo } from '../shared/ipc';
+
+// The bridge is narrow and purpose-named: methods name capabilities, never
+// transport. Raw ipcRenderer (or any whole Electron module) is never put on
+// window — it would hand injected code every channel the app has
+// (docs/principles/stack/electron/ipc-contracts.md).
+
+const api: RendererApi = {
+  getStatus: () => ipcRenderer.invoke('app:get-status'),
+  getCoreHealth: () => ipcRenderer.invoke('core:health'),
+  openExternal: (url) => ipcRenderer.invoke('shell:open-external', url),
+  onThemeChanged: (callback) => {
+    const listener = (_event: Electron.IpcRendererEvent, theme: ThemeInfo) =>
+      callback(theme);
+    ipcRenderer.on('theme:changed', listener);
+    return () => {
+      ipcRenderer.removeListener('theme:changed', listener);
+    };
+  },
+};
+
+contextBridge.exposeInMainWorld('api', api);

package/src/generators/electron-app/files/src/renderer/index.html.template

@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <!-- A strict CSP is achievable because all privileged data flows over IPC,
+         not fetch. style-src 'unsafe-inline' carries Vite's dev-mode style
+         injection; scripts stay 'self'-only in every mode
+         (docs/principles/stack/electron/security.md). -->
+    <meta
+      http-equiv="Content-Security-Policy"
+      content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:"
+    />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title><%= name %></title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/src/generators/electron-app/files/src/renderer/src/App.test.tsx

@@ -0,0 +1,61 @@
+import { beforeEach, expect, it } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import App from './App';
+import type { CoreHealth, RendererApi } from '../../shared/ipc';
+
+// The bridge is faked at the window seam — exactly the surface a sandboxed
+// renderer sees, so the test proves the component against the same contract
+// the preload script implements. Deeper component-testing idiom is the web
+// stack's, unchanged (the groundwork-nextjs-engineer skill's testing
+// reference).
+
+function fakeApi(coreHealth: CoreHealth): RendererApi {
+  return {
+    getStatus: async () => ({ status: 'ok', version: '0.1.0-test', platform: 'test' }),
+    getCoreHealth: async () => coreHealth,
+    openExternal: async () => ({ opened: false }),
+    onThemeChanged: () => () => undefined,
+  };
+}
+
+function renderApp(): void {
+  render(
+    <QueryClientProvider client={new QueryClient()}>
+      <App />
+    </QueryClientProvider>,
+  );
+}
+
+beforeEach(() => {
+  Object.defineProperty(window, 'api', {
+    value: fakeApi({ reachable: true, status: 'ok' }),
+    configurable: true,
+  });
+});
+
+it('renders the IPC-backed status', async () => {
+  renderApp();
+  // findByText retries until the query resolves past the pending state.
+  expect(
+    await screen.findByText(/desktop shell — status ok/),
+  ).toBeInTheDocument();
+});
+
+it('renders the workspace core wiring proof', async () => {
+  renderApp();
+  expect(
+    await screen.findByText(/Wired to the workspace core — status ok/),
+  ).toBeInTheDocument();
+});
+
+it('renders an unreachable core as a state, not a crash', async () => {
+  Object.defineProperty(window, 'api', {
+    value: fakeApi({ reachable: false, status: 'unreachable' }),
+    configurable: true,
+  });
+  renderApp();
+  expect(
+    await screen.findByText(/Workspace core unreachable/),
+  ).toBeInTheDocument();
+});