npm - groundwork-method - Versions diffs - 0.0.1 → 0.10.0 - Mend

groundwork-method 0.0.1 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (629) hide show

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

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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();
+});

package/src/generators/electron-app/files/src/renderer/src/App.tsx.template ADDED Viewed

@@ -0,0 +1,43 @@
+import type { JSX } from 'react';
+import { useQuery } from '@tanstack/react-query';
+// Data fetching is TanStack Query over the typed bridge: queryFns call
+// window.api, and caching/retry/invalidation work exactly as in an HTTP app —
+// the transport is IPC instead of fetch
+// (docs/principles/stack/electron/ipc-contracts.md). Component idiom, styling,
+// and accessibility follow the web stack unchanged
+// (docs/principles/stack/typescript/frontend.md).
+export default function App(): JSX.Element {
+  const { data, isPending, isError } = useQuery({
+    queryKey: ['app', 'status'],
+    queryFn: () => window.api.getStatus(),
+  });
+  // The wiring proof: the workspace core probed through main's core-access
+  // seam (src/main/core-client.ts). An unreachable core renders as a state.
+  const core = useQuery({
+    queryKey: ['core', 'health'],
+    queryFn: () => window.api.getCoreHealth(),
+  });
+  return (
+    <main className="flex min-h-screen flex-col items-center justify-center gap-4 bg-surface text-foreground">
+      <h1 className="font-display text-3xl font-semibold text-primary">
+        <%= name %>
+      </h1>
+      <p data-testid="app-status" className="text-sm">
+        {isPending
+          ? 'Connecting to the shell…'
+          : isError
+            ? 'Shell unreachable'
+            : `Wired to the desktop shell — status ${data.status}, v${data.version} (${data.platform})`}
+      </p>
+      <p data-testid="core-status" className="text-sm">
+        {core.isPending
+          ? 'Probing the workspace core…'
+          : core.isError || !core.data.reachable
+            ? 'Workspace core unreachable'
+            : `Wired to the workspace core — status ${core.data.status}`}
+      </p>
+    </main>
+  );
+}

package/src/generators/electron-app/files/src/renderer/src/assets/main.css ADDED Viewed

@@ -0,0 +1,40 @@
+@import "tailwindcss";
+@import "./brand.css";
+/* Map the projected brand custom properties into Tailwind v4 theme tokens.
+   brand.css is GENERATED from .groundwork/config/brand-tokens.json — evolve
+   the brand there, never here. Components consume the utilities these tokens
+   create (bg-surface, text-primary, font-display, rounded-base, ...) and never
+   read the --gw-* variables directly
+   (docs/principles/stack/typescript/frontend.md). */
+@theme inline {
+  --color-primary: var(--gw-primary);
+  --color-accent: var(--gw-accent);
+  --color-surface: var(--gw-surface);
+  --color-surface-alt: var(--gw-surface-alt);
+  --color-foreground: var(--gw-text-body);
+  --color-success: var(--gw-success);
+  --color-error: var(--gw-error);
+  --color-warning: var(--gw-warning);
+  --color-info: var(--gw-info);
+  --font-display: var(--gw-font-display);
+  --font-body: var(--gw-font-body);
+  --radius-base: var(--gw-radius-base);
+}
+@layer base {
+  html {
+    background-color: var(--gw-surface);
+    color: var(--gw-text-body);
+  }
+  body {
+    font-family: var(--gw-font-body), system-ui, sans-serif;
+    font-weight: var(--gw-font-body-weight);
+  }
+  h1,
+  h2,
+  h3 {
+    font-family: var(--gw-font-display), system-ui, sans-serif;
+    font-weight: var(--gw-font-display-weight);
+  }
+}

package/src/generators/electron-app/files/src/renderer/src/env.d.ts ADDED Viewed

@@ -0,0 +1,14 @@
+/// <reference types="vite/client" />
+import type { RendererApi } from '../../shared/ipc';
+// The renderer's ONLY platform surface: the preload-exposed bridge. It never
+// imports from Electron or Node — the eslint boundary rule and the DOM-only
+// tsconfig both enforce it (docs/principles/stack/electron/process-model.md).
+declare global {
+  interface Window {
+    api: RendererApi;
+  }
+}
+export {};

package/src/generators/electron-app/files/src/renderer/src/main.tsx ADDED Viewed

@@ -0,0 +1,25 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import App from './App';
+import './assets/main.css';
+// nativeTheme (main process) is the source of truth for dark mode: main
+// broadcasts changes over the bridge and the renderer mirrors them onto
+// <html data-theme>, which brand.css resolves into per-theme token values
+// (docs/principles/stack/electron/ipc-contracts.md).
+window.api.onThemeChanged((theme) => {
+  document.documentElement.dataset.theme = theme.shouldUseDarkColors
+    ? 'dark'
+    : 'light';
+});
+const queryClient = new QueryClient();
+ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
+  <React.StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <App />
+    </QueryClientProvider>
+  </React.StrictMode>,
+);

package/src/generators/electron-app/files/src/shared/ipc.ts ADDED Viewed

@@ -0,0 +1,54 @@
+// The typed IPC contract — the single seam between the sandboxed renderer and
+// the privileged main process. This module carries TYPES ONLY: runtime code
+// never crosses the process boundary through src/shared/
+// (docs/principles/stack/electron/process-model.md).
+//
+// Adding a channel: declare it here, implement the handler in src/main/ipc.ts
+// (with sender validation, and zod validation for non-trivial payloads), and
+// expose a purpose-named method in src/preload/index.ts. A channel without an
+// entry here is an untyped seam that drifts silently
+// (docs/principles/stack/electron/ipc-contracts.md).
+export type AppStatus = {
+  status: 'ok';
+  version: string;
+  platform: string;
+};
+export type OpenExternalResult = {
+  opened: boolean;
+};
+/** The workspace core's health as the home view renders it. An unreachable
+ *  core is a value, not an exception (src/main/core-client.ts). */
+export type CoreHealth = {
+  reachable: boolean;
+  status: string;
+};
+export type ThemeInfo = {
+  shouldUseDarkColors: boolean;
+};
+/** Request/response channels, served by ipcMain.handle in src/main/ipc.ts. */
+export type IpcContract = {
+  'app:get-status': { args: []; result: AppStatus };
+  'core:health': { args: []; result: CoreHealth };
+  'shell:open-external': { args: [url: string]; result: OpenExternalResult };
+};
+/** One-way push channels, broadcast main → renderer via webContents.send. */
+export type IpcPushContract = {
+  'theme:changed': ThemeInfo;
+};
+/** The narrow, purpose-named bridge preload exposes as `window.api`. Methods
+ *  name capabilities, never transport — raw ipcRenderer is never exposed. */
+export type RendererApi = {
+  getStatus: () => Promise<AppStatus>;
+  /** Probe the workspace core through main — the surface's wiring proof. */
+  getCoreHealth: () => Promise<CoreHealth>;
+  openExternal: (url: string) => Promise<OpenExternalResult>;
+  /** Subscribe to native theme changes; returns an unsubscribe function. */
+  onThemeChanged: (callback: (theme: ThemeInfo) => void) => () => void;
+};

package/src/generators/electron-app/files/tests/smoke/app.spec.ts.template ADDED Viewed

@@ -0,0 +1,68 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { expect, test } from '@playwright/test';
+import { _electron as electron } from 'playwright';
+import type { AppStatus, CoreHealth } from '../../src/shared/ipc';
+// Boot-tier smoke: the real built app launches, renders, and completes one
+// IPC round-trip. This is the agent-closable loop the stack was chosen for —
+// keep it thin (happy path only); rules are proven in the unit tiers and at
+// the capability core's contracts. Runs under xvfb on Linux CI via the smoke
+// target; tool/electron_exec.sh builds first and skips-with-reason when the
+// Electron binary or a display server is unavailable.
+const MAIN_ENTRY = path.join(__dirname, '..', '..', 'out', 'main', 'index.js');
+test('boots, renders, and answers an IPC round-trip', async () => {
+  if (!fs.existsSync(MAIN_ENTRY)) {
+    throw new Error(
+      'out/main/index.js not found — run the build first (the smoke target does: npx nx run <%= fileName %>:smoke)',
+    );
+  }
+  const app = await electron.launch({ args: [MAIN_ENTRY] });
+  try {
+    const page = await app.firstWindow();
+    // The window booted and rendered app content.
+    await expect(page).toHaveTitle('<%= name %>');
+    await expect(page.getByRole('heading', { name: '<%= name %>' })).toBeVisible();
+    // One invoke/handle round-trip through the typed bridge.
+    const status = await page.evaluate(() => {
+      const bridged = globalThis as unknown as {
+        api: { getStatus(): Promise<AppStatus> };
+      };
+      return bridged.api.getStatus();
+    });
+    expect(status.status).toBe('ok');
+    await expect(page.getByTestId('app-status')).toHaveText(/status ok/);
+    // The core-access seam answers through the bridge. Reachability depends
+    // on whether a workspace core is up at API_BASE_URL (the system-test
+    // harness boots one); the seam itself must answer a value either way.
+    const coreHealth = await page.evaluate(() => {
+      const bridged = globalThis as unknown as {
+        api: { getCoreHealth(): Promise<CoreHealth> };
+      };
+      return bridged.api.getCoreHealth();
+    });
+    expect(typeof coreHealth.reachable).toBe('boolean');
+    expect(coreHealth.status.length).toBeGreaterThan(0);
+    await expect(page.getByTestId('core-status')).toHaveText(
+      /Wired to the workspace core|Workspace core unreachable/,
+    );
+    // The main → renderer push channel delivered the initial theme.
+    await expect(page.locator('html')).toHaveAttribute(
+      'data-theme',
+      /^(light|dark)$/,
+    );
+    // Main-process assertion via the driver's main-process hook.
+    const isPackaged = await app.evaluate(({ app: electronApp }) => electronApp.isPackaged);
+    expect(isPackaged).toBe(false);
+  } finally {
+    await app.close();
+  }
+});

package/src/generators/electron-app/files/tool/electron_exec.sh.template ADDED Viewed

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# Toolchain guard for every Nx target of this app. Node is assumed (the
+# workspace itself runs on it); what this guard covers is the Electron binary
+# download (bootstrap state) and, for the boot smoke, display availability —
+# Electron is never truly headless, so Linux CI runs the smoke under xvfb. A
+# missing prerequisite reports skipped-with-reason instead of failing
+# cryptically — the same way ./dev degrades when the Docker daemon is absent.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+ensure_bootstrapped() {
+  if [ ! -d node_modules ]; then
+    echo "node_modules missing — tier skipped." >&2
+    echo "Run: npx nx run <%= fileName %>:bootstrap" >&2
+    exit 1
+  fi
+  ELECTRON_BIN="$(node -p "require('electron')" 2>/dev/null || true)"
+  if [ -z "$ELECTRON_BIN" ] || [ ! -e "$ELECTRON_BIN" ]; then
+    echo "electron binary not available — tier skipped." >&2
+    echo "npm install downloads it; run: npx nx run <%= fileName %>:bootstrap" >&2
+    exit 1
+  fi
+}
+# Linux without a display server: wrap in xvfb-run when available, otherwise
+# the smoke tier is skipped with a reason (never silently green).
+run_with_display() {
+  if [ "$(uname -s)" = "Linux" ] && [ -z "${DISPLAY:-}" ] && [ -z "${WAYLAND_DISPLAY:-}" ]; then
+    if command -v xvfb-run >/dev/null 2>&1; then
+      xvfb-run --auto-servernum -- "$@"
+    else
+      echo "no display server and xvfb-run not found — smoke tier skipped." >&2
+      echo "Install xvfb (CI) or run from a desktop session." >&2
+      exit 1
+    fi
+  else
+    "$@"
+  fi
+}
+case "${1:-}" in
+  bootstrap)
+    # Generation shipped only sources (no install required). Bootstrap resolves
+    # packages and downloads the Electron binary (~100 MB, cached by npm).
+    npm install
+    ;;
+  run)
+    ensure_bootstrapped
+    npm run dev -- "${@:2}"
+    ;;
+  build)
+    ensure_bootstrapped
+    npm run build -- "${@:2}"
+    ;;
+  lint)
+    ensure_bootstrapped
+    npm run lint -- "${@:2}"
+    ;;
+  typecheck)
+    ensure_bootstrapped
+    npm run typecheck
+    ;;
+  test)
+    ensure_bootstrapped
+    npm test -- "${@:2}"
+    ;;
+  smoke)
+    # Boot tier: build, then drive the built app with Playwright _electron
+    # (docs/principles/stack/electron — testing references).
+    ensure_bootstrapped
+    npm run build
+    run_with_display npm run smoke -- "${@:2}"
+    ;;
+  package)
+    ensure_bootstrapped
+    npm run build
+    npm run package -- "${@:2}"
+    ;;
+  *)
+    echo "Usage: tool/electron_exec.sh {bootstrap|run|build|lint|typecheck|test|smoke|package}" >&2
+    exit 2
+    ;;
+esac

package/src/generators/electron-app/files/tsconfig.json ADDED Viewed

@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.node.json" },
+    { "path": "./tsconfig.web.json" }
+  ]
+}

package/src/generators/electron-app/files/tsconfig.node.json ADDED Viewed

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "target": "ES2022",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "lib": ["ESNext"],
+    "types": ["node"],
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "useDefineForClassFields": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": [
+    "electron.vite.config.ts",
+    "forge.config.ts",
+    "playwright.config.ts",
+    "vitest.config.ts",
+    "src/main/**/*",
+    "src/preload/**/*",
+    "src/shared/**/*",
+    "tests/**/*"
+  ]
+}

package/src/generators/electron-app/files/tsconfig.web.json ADDED Viewed

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "target": "ES2022",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "useDefineForClassFields": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": [
+    "src/renderer/src/**/*",
+    "src/shared/**/*",
+    "vitest.setup.ts"
+  ]
+}

package/src/generators/electron-app/files/vitest.config.ts ADDED Viewed

@@ -0,0 +1,32 @@
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vitest/config';
+// Two unit-test projects, one per process context: main/shared code runs in
+// plain Node (the security policy tests live there), renderer components run
+// in jsdom with the bridge faked at the window seam. The boot smoke is NOT
+// vitest — it is Playwright _electron (tests/smoke/), launched via the smoke
+// target (docs/principles/stack/electron/process-model.md).
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    projects: [
+      {
+        extends: true,
+        test: {
+          name: 'main',
+          environment: 'node',
+          include: ['src/main/**/*.test.ts', 'src/shared/**/*.test.ts'],
+        },
+      },
+      {
+        extends: true,
+        test: {
+          name: 'renderer',
+          environment: 'jsdom',
+          include: ['src/renderer/**/*.test.{ts,tsx}'],
+          setupFiles: ['./vitest.setup.ts'],
+        },
+      },
+    ],
+  },
+});

package/src/generators/electron-app/files/vitest.setup.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ import '@testing-library/jest-dom/vitest';