groundwork-method 0.0.1 → 0.11.0

package/src/generators/electron-app/docs/principles/stack/electron/packaging-and-updates.md

@@ -0,0 +1,59 @@
+---
+title: Packaging & Updates
+description: Electron Forge, electron-vite, auto-update routes, code signing, and fuse-flipping in the release pipeline.
+status: active
+last_reviewed: 2026-06-12
+---
+# Packaging & Updates
+
+## TL;DR
+
+Electron Forge packages and publishes; electron-vite builds. Auto-update is `update-electron-app` + update.electronjs.org for open-source apps, `electron-updater` feeds otherwise. Code signing on both platforms is non-optional, and fuses are flipped inside the packaging step so an unhardened binary cannot ship.
+
+## Why this matters
+
+Packaging is where the security posture becomes physical: signing, notarization, ASAR integrity, and fuses all happen here or not at all. It is also where users experience the app's lifecycle — an app that updates silently and reliably stays inside the 3-major security window; one with a hand-rolled update path drifts out of support and into known CVEs.
+
+## Our principles
+
+### 1. Electron Forge is the toolchain default
+
+Forge is the officially recommended pipeline — maintained in the `electron/` GitHub org, composing the first-party tools (`@electron/packager`, `@electron/osx-sign`, `@electron/notarize`, `@electron/fuses`) into one configuration. **electron-builder** is the documented escape hatch when packaging needs outgrow Forge's makers (exotic targets, NSIS specifics, percentage rollouts via its updater); it is healthy and more downloaded, but "official" means Forge, and the default needs no justification in a decision record — the escape hatch does.
+
+### 2. electron-vite is the build layer
+
+electron-vite (v5, electron-vite.org) builds all three targets from one `electron.vite.config.ts` with `main`/`preload`/`renderer` sections — renderer HMR, main/preload hot-reload, and `utilityProcess` workers via `?modulePath`. Forge's own Vite plugin remains marked experimental and lags Vite majors, so the production pairing is electron-vite for the build and Forge for packaging. The renderer section is where web-stack build config lives — Tailwind v4 loads here as `@tailwindcss/vite`, applied to the renderer only; everything about how it is used defers to [TypeScript Frontend](../typescript/frontend.md).
+
+### 3. Two sanctioned auto-update routes
+
+- **Open-source, GitHub-released:** the drop-in `update-electron-app` module against **update.electronjs.org** — free, zero-infrastructure, feeding the platform-native Squirrel updaters behind Electron's built-in `autoUpdater`. It serves only semver-tagged, non-draft releases.
+- **Everything else:** `electron-updater` with a generic, S3, or GitHub feed — channels and staged rollouts included. Self-hosted feed servers (Nucleus-style) only when rollout control demands them.
+
+A hand-rolled update endpoint without semver and rollback discipline is an outage generator and is not a third route.
+
+### 4. Update discipline is a fixed set of rules
+
+- Never check for updates on `--squirrel-firstrun` — the install is still settling.
+- Call `quitAndInstall()` only after the `update-downloaded` event.
+- One in-flight `checkForUpdates()` at a time; double-calls corrupt state.
+- Set `app.setAppUserModelId()` to match the Squirrel shortcut ID, or Windows notifications detach from the app.
+- Staying inside the 3-major support window is an update-discipline item, not a backlog wish ([Security](security.md)).
+
+### 5. Code signing is non-optional on both platforms
+
+An unsigned build is a development artifact, never a release.
+
+- **macOS:** Developer ID signing with the hardened runtime and entitlements, then notarization via `notarytool` (Forge wraps `@electron/notarize`). `altool` is dead; Gatekeeper rejects un-notarized apps outright.
+- **Windows:** **Azure Artifact Signing** (renamed from Azure Trusted Signing; GA in US/Canada/Europe since Jan 2026) — cloud-HSM-backed, clears SmartScreen, runs from CI via signtool/jsign. It displaced OV/EV certificates on USB tokens, which cannot live in a pipeline.
+
+### 6. Fuses are flipped inside the packaging step
+
+`@electron/fuses` runs as part of the Forge packaging hook — `RunAsNode` off, `EnableEmbeddedAsarIntegrityValidation` and `OnlyLoadAppFromAsar` on ([Security](security.md) for why). Putting the flip in the pipeline rather than a checklist means a release artifact that skipped hardening cannot exist.
+
+## Anti-patterns we reject
+
+- **electron-packager as a standalone "toolchain."** It is a Forge internal (`@electron/packager`) now; driving it by hand re-implements Forge badly.
+- **webpack-based Forge templates and boilerplates.** The ecosystem's motion is uniformly Vite; webpack templates receive no investment.
+- **Shipping unsigned or un-notarized builds.** Both desktop platforms treat them as malware, because malware is what unsigned binaries usually are.
+- **`altool`, USB-token certificates, and other pre-cloud signing flows.** They cannot run in CI, so they guarantee a human in the release loop.
+- **Update checks wired to app startup with no event discipline.** First-run checks and premature `quitAndInstall()` are the two classic self-inflicted update outages.

package/src/generators/electron-app/docs/principles/stack/electron/process-model.md

@@ -0,0 +1,53 @@
+---
+title: Process Model
+description: Main as orchestrator, sandboxed Node-free renderers, utilityProcess for heavy work, and the lint-enforced folder boundary.
+status: active
+last_reviewed: 2026-06-12
+---
+# Process Model
+
+## TL;DR
+
+Main orchestrates and nothing more. Renderers are fully sandboxed, context-isolated, and Node-free. Heavy or crash-prone work runs in a `utilityProcess` with MessagePorts wired renderer↔utility directly. The split is physical — `src/main` / `src/preload` / `src/renderer` / `src/shared` — and a lint rule enforces it.
+
+## Why this matters
+
+The main process owns the event loop that services every window: a CPU-heavy task in main freezes every UI the app has at once. A renderer with Node access turns any XSS into full machine compromise. The process model is where Electron apps are won or lost, and the flagship apps — VS Code, Slack, Signal, 1Password — have all converged on the same shape after learning this the hard way.
+
+## Our principles
+
+### 1. Main is an orchestrator
+
+Main creates windows, registers IPC handlers, talks to the OS, and delegates. It never does CPU-heavy or blocking work — parsing large files, crypto, indexing, image processing all starve the UI event loop. If a task can take longer than a frame, it does not belong in main.
+
+### 2. Renderers are sandboxed, context-isolated, and Node-free
+
+Every renderer runs with the hardened quartet ([Security](security.md)) and imports nothing from Electron or Node. The renderer is a normal Vite + React web app whose only platform surface is the preload-exposed bridge object ([IPC Contracts](ipc-contracts.md)). This is what lets the renderer reuse the web frontend idiom wholesale — component, styling, and accessibility rules come from [TypeScript Frontend](../typescript/frontend.md) unchanged.
+
+### 3. Heavy and crash-prone work runs in `utilityProcess`
+
+`utilityProcess` is the documented home for CPU-intensive tasks, untrusted services, and components that may crash — a `child_process.fork` equivalent with Node enabled and MessagePort support. Wire MessagePorts **renderer↔utility directly** so the traffic never transits, or blocks, the main process. This is the VS Code pattern: its extension host moved out of the renderer into a `utilityProcess`, and VS Code contributed the API to Electron for exactly this purpose. electron-vite builds utility workers first-class via the `?modulePath` import suffix.
+
+### 4. The folder split is enforced, not conventional
+
+```
+src/
+  main/      # privileged orchestration — Node + Electron main APIs
+  preload/   # the bridge — contextBridge only
+  renderer/  # the web app — no Node, no Electron imports
+  shared/    # IPC contract types — types only, imported by all three
+```
+
+A lint boundary (dependency-cruiser or ESLint import rules, the Slack pattern) fails the build when renderer code imports anything Node-touching. The rule exists because the boundary erodes one convenient import at a time, and each erosion is invisible until it is a sandbox hole. Each process target gets its own tsconfig — main and preload compile against Node types, the renderer against DOM types — so the compiler polices the boundary too.
+
+### 5. Shared code crosses the boundary as types only
+
+`src/shared/` holds the IPC contract types both sides consume ([IPC Contracts](ipc-contracts.md)) and nothing with runtime behaviour. A "utils" folder imported by both main and renderer is a process boundary leak: it drags Node-flavoured code toward the sandbox and couples the two sides' upgrade paths.
+
+## Anti-patterns we reject
+
+- **Node-enabled renderers.** Enabling `nodeIntegration` also silently disables the sandbox for that renderer — the settings only protect as a set.
+- **Plugin or extension code in the renderer.** Untrusted code belongs in a `utilityProcess`, where a crash or compromise is contained.
+- **CPU-heavy work in main.** It freezes every window. Move it to a utility process.
+- **`child_process.fork` for work that talks to a renderer.** `utilityProcess` + MessagePorts replaced it; fork has no port wiring and no Services API integration.
+- **A shared folder with runtime code.** Shared types, yes. Shared behaviour across the process boundary, no.

package/src/generators/electron-app/docs/principles/stack/electron/security.md

@@ -0,0 +1,70 @@
+---
+title: Security
+description: The hardened quartet, CSP, navigation and permission policy, fuses, and the currency window — enforced defaults, not advice.
+status: active
+last_reviewed: 2026-06-12
+---
+# Security
+
+## TL;DR
+
+Electron's security checklist is our enforced baseline, not a menu. The quartet — `contextIsolation: true`, `sandbox: true`, `nodeIntegration: false`, `webSecurity: true` — never changes. CSP is required, permissions and navigation are explicitly handled, local content ships over a custom protocol, and fuses are flipped at package time. Staying inside the 3-major support window is itself a security control.
+
+## Why this matters
+
+An Electron app is a browser with a privileged process attached. Every web vulnerability the renderer inherits becomes a local-machine vulnerability the moment a boundary control is loosened — and the controls fail as a set, not individually: enabling `nodeIntegration` silently disables the sandbox for that renderer. CVE-2025-55305 showed that even apps with the runtime controls right (Signal, Slack, 1Password) were backdoorable at rest because packaging integrity was left off. The baseline below is what "done" means.
+
+## The enforced defaults
+
+### 1. The quartet is never changed
+
+```ts
+new BrowserWindow({
+  webPreferences: {
+    contextIsolation: true,   // default since 12 — never off
+    sandbox: true,            // default since 20 — never off
+    nodeIntegration: false,   // default since 5 — never on
+    // webSecurity defaults true — never off, not even "temporarily for dev"
+  },
+});
+```
+
+These are Electron's defaults; our rule is that no code path, flag, or debugging session turns them off. `webSecurity: false` and `allowRunningInsecureContent` as debugging crutches are how production apps ship with the front door open.
+
+### 2. A CSP is required
+
+Every renderer ships a Content-Security-Policy — HTTP header where content is served, `<meta http-equiv>` for custom-protocol content. `default-src 'self'`-style strictness is achievable because all privileged data flows over IPC, not fetch; a CSP containing `*` is no CSP.
+
+### 3. Permission requests are handled, never defaulted
+
+`session.setPermissionRequestHandler()` is registered with an explicit allowlist. The default grants permissions (camera, microphone, geolocation) to any content that asks — in a desktop app, content that asks unexpectedly is the attack.
+
+### 4. Navigation is restricted
+
+`will-navigate` blocks navigation away from app content, and `setWindowOpenHandler()` denies or routes every `window.open`. A renderer that can navigate to an attacker's page hands the attacker a sandboxed-but-privileged-adjacent context. `shell.openExternal` is called only on validated, allowlisted URLs (scheme check at minimum) — it launches whatever the OS associates with the input.
+
+### 5. Local content ships over a custom protocol, not `file://`
+
+A registered custom protocol (`app://`) scopes what the renderer can load; `file://` grants origin-level access to the filesystem's namespace and breaks standard web security semantics.
+
+### 6. Fuses are flipped at package time
+
+Fuses are build-time switches baked into the binary — runtime config cannot re-enable what a fuse removed:
+
+- `RunAsNode` **off** — otherwise the shipped binary doubles as a general-purpose Node executable for anything on the machine.
+- `EnableEmbeddedAsarIntegrityValidation` **on** and `OnlyLoadAppFromAsar` **on** — CVE-2025-55305 (Trail of Bits, 2025-09) backdoored Signal, Slack, and 1Password via local V8 heap-snapshot tampering that bypassed code-integrity checks; ASAR integrity validation is the fix, and shipping without it is now called out as a defect, not a hardening opportunity.
+- `nodeCliInspect` stays **on** — flipping it off breaks Playwright's `_electron` launch, and the agent-closable test loop ([Surface Stack Selection](../../surface-stack-selection.md)) outranks the marginal hardening.
+
+Fuse flipping lives in the packaging pipeline ([Packaging & Updates](packaging-and-updates.md)), so an unfused build cannot reach a release channel.
+
+### 7. The currency window is a security obligation
+
+Only the latest three Electron majors receive patches, and majors ship every 8 weeks — Chromium CVEs apply to your shipped app on Chromium's schedule, not yours. Falling out of the window means known-exploitable, unpatched browser bugs in production. The upgrade is scheduled work with the same priority as a dependency CVE.
+
+## Anti-patterns we reject
+
+- **`nodeIntegration: true` anywhere, for any window.** It also kills the sandbox for that renderer.
+- **`webSecurity: false` or `allowRunningInsecureContent` to "unblock" development.** Fix the content, not the boundary.
+- **The `remote` module or packages that emulate it.** Synchronous privileged access from the renderer is the whole threat model in one API.
+- **Un-fused release builds.** Post-CVE-2025-55305, ASAR integrity off is a shipping defect.
+- **Treating the checklist as guidance for a security review later.** It is the definition of a correctly configured app on day one.

package/src/generators/electron-app/docs/principles/stack/typescript/frontend.md

@@ -0,0 +1,65 @@
+---
+title: Frontend
+description: React 19, Server Components, SWR, Tailwind, and the design language of a Next.js application.
+status: active
+last_reviewed: 2026-05-26
+---
+# Frontend
+
+## TL;DR
+
+The frontend is Next.js 16 with React 19 Server Components, SWR for client-side data, and Tailwind for styling. We render on the server by default, hydrate the minimum needed for interactivity, and keep data-fetching at the leaves. The design language is consistent, calm, and accessible first.
+
+## Why this matters
+
+Frontend engineering in 2026 is no longer a "client-side" discipline. Most pixels are rendered on the server before they reach the browser, and the browser's job is to stay responsive to the user's input rather than to fetch data on their behalf. Getting this split right — what runs on the server, what runs on the client, what streams in between — is the single biggest determinant of how fast and how reliable the app feels. It is also where most frontend bugs live.
+
+## Our principles
+
+### 1. Server components are the default
+
+Every component starts as a Server Component. We add `"use client"` only when we need state, events, or browser-only APIs. The economic argument is simple: every client component costs download, parse, hydrate, and memory on every user's device. Server components cost none of that. The ratio of server-to-client components is tracked and kept high.
+
+### 2. Data fetches at the leaves, not the root
+
+Data fetching happens in the component that actually renders the data, not in a page-level fetcher that passes everything down through props. This lets Suspense boundaries stream exactly as deep as they need to, and it keeps prop-drilling in check. The exception is when two leaves need the same data — then we fetch once in a common ancestor and share via React's built-in request deduplication.
+
+### 3. SWR for client-interactive state
+
+For state that must respond to user interaction in real time — live views, session state, optimistic updates — we use SWR. One cache, one invalidation story, one mental model. We do not mix query libraries in the same app.
+
+### 4. Styling is Tailwind utilities, composed
+
+We style with Tailwind utility classes. When a composition of utilities gets long or is repeated, we extract a component — not a custom CSS class. Component extraction keeps the `className` strings honest; new CSS classes are where design systems go to die of untracked one-offs.
+
+### 5. The design system is a library, not a guideline
+
+Buttons, inputs, modals, tooltips — every primitive is a typed, reviewed component in the shared component library. Ad-hoc styling of a button in a feature folder is a smell; the fix is to add the variant to the library, not to reimplement it.
+
+### 6. Accessibility is a baseline, not a feature
+
+Every interactive component supports keyboard navigation, is screen-reader labelled, and meets WCAG 2.2 AA contrast at minimum. Accessibility failures block merges the same way type errors do. The golden path for every new UI begins with "can I get to it, use it, and understand it with just the keyboard and a screen reader?"
+
+### 7. Client state is recoverable
+
+We do not store state in React that cannot be rebuilt from the server or the URL. Refreshing the page is the end-to-end test of this: if the user loses context after a refresh, we are holding state we should not. The URL is a first-class state container; so are Server Components.
+
+### 8. Performance budgets are enforced in CI
+
+Largest Contentful Paint, Interaction-to-Next-Paint, JS bundle size — all tracked in CI with budgets. A PR that regresses a budget requires an explicit waiver. Performance is never negotiated after the fact; it is designed in.
+
+## Anti-patterns we reject
+
+- **`useEffect` for data fetching.** `useEffect` is an escape hatch for non-React systems; it is not a data-fetching primitive. Use Server Components or SWR.
+- **Context for everything.** React Context is a tool for genuinely app-wide concerns (theme, auth, locale). Using it to avoid prop-drilling on three levels is overreach.
+- **CSS Modules alongside Tailwind.** One styling system. Not three.
+- **Ad-hoc design primitives.** Every new button variant is a tax on the design system. If it needs a variant, add it to the library.
+- **State that cannot survive refresh.** Modals that disappear on refresh lose user context; counters that reset on refresh are not counters.
+- **"Fix it in a later PR" accessibility.** The later PR will not happen. Ship accessible or ship later.
+
+## Further reading
+
+- *React documentation* ([react.dev](https://react.dev)) — the canonical source for the Server Component mental model.
+- *Patterns.dev*, Lydia Hallie & Addy Osmani — a clean survey of modern frontend patterns.
+- *Inclusive Components*, Heydon Pickering — the pattern language of accessible component design.
+- *Refactoring UI*, Schoger & Wathan — the design vocabulary that informs how we compose Tailwind.

package/src/generators/electron-app/files/.gitignore.template

@@ -0,0 +1,20 @@
+# Dependencies
+node_modules/
+
+# electron-vite build output
+out/
+dist/
+
+# Electron Forge packaging output
+.vite/
+make/
+
+# Test artifacts
+coverage/
+playwright-report/
+test-results/
+
+# Tooling
+*.tsbuildinfo
+.DS_Store
+.env.local

package/src/generators/electron-app/files/README.md.template

@@ -0,0 +1,125 @@
+# <%= name %>
+
+An Electron desktop surface scaffolded by GroundWork. It is a thin adapter
+over the workspace's capability core: business logic lives behind the promoted
+contracts and is proven there once; this app proves wiring, rendering, and
+interaction. The shell follows the flagship-app architecture — a privileged
+main process that only orchestrates, a fully sandboxed Node-free renderer on
+the same React + Tailwind stack as the web surface, and a typed IPC contract
+at the process seam. Electron is GroundWork's standard desktop pick per its
+surface-stack-selection principle (Playwright's `_electron` driver makes it
+the strongest agent-closable loop of any desktop option); the engineering
+principles this app embodies live in `docs/principles/stack/electron/`.
+
+## Toolchain
+
+Node is assumed (the workspace runs on it); the Electron binary is a
+**declared prerequisite, not an assumption** — generation required no install,
+everything below does. Every Nx target runs through `tool/electron_exec.sh`,
+which reports `tier skipped` with a reason instead of failing cryptically when
+the binary (or, for the smoke, a display server) is missing.
+
+```bash
+npx nx run <%= fileName %>:bootstrap   # one-time: npm install (downloads the Electron binary)
+npx nx run <%= fileName %>:run         # electron-vite dev (renderer HMR, main/preload hot-reload)
+npx nx run <%= fileName %>:build       # electron-vite build → out/
+npx nx run <%= fileName %>:lint        # eslint, including the process-boundary rules
+npx nx run <%= fileName %>:typecheck   # tsc per process target (node + web tsconfigs)
+npx nx run <%= fileName %>:test        # vitest: main policy tests (node) + renderer tests (jsdom)
+npx nx run <%= fileName %>:smoke       # build + Playwright _electron boot smoke
+npx nx run <%= fileName %>:package     # electron-forge package (flips the fuses)
+```
+
+This app joins the Nx workspace through `project.json` run-commands targets
+and does **not** join `docker-compose.yml` (a desktop app has no Docker boot).
+Its verification tiers follow the multi-surface contract: **generation**
+(snapshot, no toolchain), **compilation** (`tsc` + lint, renderer and main
+both), **boot** (Playwright `_electron` launch + smoke — under `xvfb` on
+Linux CI, since Electron is never truly headless).
+
+## Structure
+
+```
+src/
+├── main/                 # privileged orchestration — Node + Electron main APIs
+│   ├── index.ts          # window creation (hardened quartet), security policy,
+│   │                     # bundle protocol, nativeTheme broadcast
+│   ├── ipc.ts            # ipcMain.handle: sender validation + zod payloads
+│   ├── core-client.ts    # the core-access seam: main fetches the workspace
+│   │                     # gateway (API_BASE_URL); the renderer never can (CSP)
+│   ├── core-client.test.ts
+│   ├── policy.ts         # pure, unit-tested security rules (no Electron imports)
+│   └── policy.test.ts
+├── preload/
+│   └── index.ts          # the narrow contextBridge API — never raw ipcRenderer
+├── renderer/             # a normal Vite + React web app — no Node, no Electron
+│   ├── index.html        # strict CSP
+│   └── src/
+│       ├── assets/brand.css   # GENERATED from brand-tokens.json — do not hand-edit
+│       ├── assets/main.css    # Tailwind v4 + @theme token mapping
+│       ├── App.tsx
+│       ├── App.test.tsx
+│       └── main.tsx           # React root + theme sync subscription
+└── shared/
+    └── ipc.ts            # the typed IPC contract — types only, both sides import it
+tests/smoke/              # Playwright _electron boot smoke (the boot tier)
+```
+
+The folder split is enforced, not conventional: the renderer and shared
+tsconfig/eslint configurations fail the build when renderer code imports
+anything Node-touching (`docs/principles/stack/electron/process-model.md`).
+
+## Security posture (baked, not advisory)
+
+- **The hardened quartet** — `contextIsolation: true`, `sandbox: true`,
+  `nodeIntegration: false`, `webSecurity: true` — set explicitly in
+  `src/main/index.ts` and asserted by the framework's generation tests. No
+  code path turns them off.
+- **Permissions denied by default**; navigation restricted via `will-navigate`
+  and `setWindowOpenHandler`; `shell.openExternal` only on allowlisted https
+  URLs (`src/main/policy.ts` — pure and unit-tested).
+- **The renderer ships over the custom `app://` protocol**, never `file://`.
+- **A strict CSP** in `index.html` — privileged data flows over IPC, not fetch.
+- **Fuses flipped at package time** (`forge.config.ts`): `RunAsNode` off, ASAR
+  integrity validation + asar-only load on (CVE-2025-55305). `nodeCliInspect`
+  stays on deliberately — Playwright's `_electron` launch needs it, and the
+  agent-closable loop outranks the marginal hardening.
+
+See `docs/principles/stack/electron/security.md` for the full baseline.
+
+## The IPC contract
+
+`src/shared/ipc.ts` is the single seam between renderer and main. Adding a
+channel: declare it in the contract type, implement the handler in
+`src/main/ipc.ts` (sender validation always; zod for non-trivial payloads),
+expose a purpose-named method in `src/preload/index.ts`. The renderer fetches
+through TanStack Query with `queryFn`s calling `window.api` — caching, retry,
+and invalidation exactly as in an HTTP app. For a hosted capability core, core
+access belongs on the privileged side of this seam: main talks to the gateway,
+the renderer talks to main.
+
+## Theme: a projection, not an authoring surface
+
+`src/renderer/src/assets/brand.css` is generated from
+`.groundwork/config/brand-tokens.json` (the design system's `visual` block —
+palette roles in both themes, typography families, base radius). `main.css`
+maps the custom properties into Tailwind v4 theme tokens, so components
+consume utilities (`bg-surface`, `text-primary`, `font-display`) and never
+declare hex values. Dark mode is `nativeTheme` in main, broadcast over IPC,
+mirrored onto `<html data-theme>`. Re-run the design system to evolve the
+brand, then regenerate `brand.css` to match.
+
+## Testing
+
+Three tiers, mirroring `docs/principles/stack/electron/` and the web stack's
+testing discipline:
+
+1. **Unit (node)** — `src/main/policy.test.ts`: the pure security rules.
+2. **Unit (jsdom)** — renderer components with the bridge faked at the
+   `window.api` seam.
+3. **Smoke (Playwright `_electron`)** — `tests/smoke/`: launch the built app,
+   assert title + rendering, one IPC round-trip, and the theme push channel.
+   Thin by design; emulator-class minutes are the expensive currency here too.
+
+Surface tests never re-prove core business logic — that proof lives at the
+core's contract.

package/src/generators/electron-app/files/electron.vite.config.ts

@@ -0,0 +1,31 @@
+import { defineConfig, externalizeDepsPlugin } from 'electron-vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+// One config, three build targets — main and preload compile against the Node
+// context, the renderer is a normal Vite + React web app. Tailwind v4 loads as
+// a Vite plugin in the renderer section ONLY: it never applies to main or
+// preload (docs/principles/stack/electron/packaging-and-updates.md).
+export default defineConfig({
+  main: {
+    plugins: [externalizeDepsPlugin()],
+    build: {
+      lib: { entry: 'src/main/index.ts' },
+    },
+  },
+  preload: {
+    plugins: [externalizeDepsPlugin()],
+    build: {
+      lib: { entry: 'src/preload/index.ts' },
+    },
+  },
+  renderer: {
+    root: 'src/renderer',
+    plugins: [react(), tailwindcss()],
+    build: {
+      rollupOptions: {
+        input: 'src/renderer/index.html',
+      },
+    },
+  },
+});

package/src/generators/electron-app/files/eslint.config.mjs

@@ -0,0 +1,92 @@
+import js from "@eslint/js";
+import hooksPlugin from "eslint-plugin-react-hooks";
+import tseslint from "typescript-eslint";
+import globals from "globals";
+
+// Node built-ins that must never reach the sandboxed renderer or the shared
+// contract types. The list backs the lint-enforced process boundary — the
+// Slack pattern: the folder split is physical, and a rule fails the build when
+// it erodes (docs/principles/stack/electron/process-model.md).
+const nodeBuiltinPatterns = ["node:*", "fs", "path", "os", "child_process", "crypto", "net", "http", "https"];
+
+export default tseslint.config(
+  {
+    ignores: ["out/", "dist/", "node_modules/", "coverage/", "playwright-report/", "test-results/"],
+  },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.node,
+        ...globals.es2024,
+      },
+    },
+    rules: {
+      "no-console": "off",
+      "@typescript-eslint/no-unused-vars": ["warn", { argsIgnorePattern: "^_", varsIgnorePattern: "^_" }],
+    },
+  },
+  {
+    // The renderer is a normal web app: browser globals, React hooks rules,
+    // and a hard boundary — no Electron, no Node. Its only platform surface
+    // is the preload-exposed window.api bridge.
+    files: ["src/renderer/**/*.{ts,tsx}"],
+    plugins: {
+      "react-hooks": hooksPlugin,
+    },
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+        ...globals.es2024,
+      },
+    },
+    rules: {
+      ...hooksPlugin.configs.recommended.rules,
+      "no-restricted-imports": [
+        "error",
+        {
+          paths: [
+            {
+              name: "electron",
+              message:
+                "The renderer is sandboxed and Node-free; talk to main through window.api (docs/principles/stack/electron/process-model.md).",
+            },
+          ],
+          patterns: [
+            {
+              group: nodeBuiltinPatterns,
+              message:
+                "Node built-ins do not exist in the sandboxed renderer; move the capability behind the IPC bridge.",
+            },
+          ],
+        },
+      ],
+    },
+  },
+  {
+    // Shared code crosses the process boundary as types only.
+    files: ["src/shared/**/*.ts"],
+    rules: {
+      "no-restricted-imports": [
+        "error",
+        {
+          paths: [
+            {
+              name: "electron",
+              message:
+                "src/shared/ carries the IPC contract types only — no runtime, no Electron (docs/principles/stack/electron/process-model.md).",
+            },
+          ],
+          patterns: [
+            {
+              group: nodeBuiltinPatterns,
+              message:
+                "src/shared/ carries the IPC contract types only — no runtime, no Node.",
+            },
+          ],
+        },
+      ],
+    },
+  },
+);

package/src/generators/electron-app/files/forge.config.ts.template

@@ -0,0 +1,44 @@
+import type { ForgeConfig } from '@electron-forge/shared-types';
+import { MakerZIP } from '@electron-forge/maker-zip';
+import { FusesPlugin } from '@electron-forge/plugin-fuses';
+import { FuseV1Options, FuseVersion } from '@electron/fuses';
+
+// Packaging is where the security posture becomes physical: fuses are flipped
+// inside this pipeline so an unhardened binary cannot reach a release channel
+// (docs/principles/stack/electron/packaging-and-updates.md). Run `electron-vite
+// build` before packaging — package.json's `main` points at the built output.
+//
+// Code signing is non-optional for release builds (macOS Developer ID +
+// notarytool, Windows Azure Artifact Signing); wire osxSign/osxNotarize and the
+// Windows signing hook here when release credentials exist. An unsigned build
+// is a development artifact, never a release.
+const config: ForgeConfig = {
+  packagerConfig: {
+    asar: true,
+    appBundleId: '<%= appId %>',
+  },
+  makers: [new MakerZIP({}, ['darwin', 'linux', 'win32'])],
+  plugins: [
+    new FusesPlugin({
+      version: FuseVersion.V1,
+      // The shipped binary must not double as a general-purpose Node
+      // executable (docs/principles/stack/electron/security.md).
+      [FuseV1Options.RunAsNode]: false,
+      [FuseV1Options.EnableCookieEncryption]: true,
+      [FuseV1Options.EnableNodeOptionsEnvironmentVariable]: false,
+      // Left ON deliberately: flipping nodeCliInspect off breaks Playwright's
+      // _electron launch, and the agent-closable smoke loop outranks the
+      // marginal hardening (docs/principles/stack/electron/security.md).
+      [FuseV1Options.EnableNodeCliInspectArguments]: true,
+      // CVE-2025-55305: local V8 heap-snapshot tampering backdoored Signal,
+      // Slack, and 1Password past their code-integrity checks. ASAR integrity
+      // validation + asar-only load is the fix; shipping without it is a
+      // defect, not a hardening opportunity
+      // (docs/principles/stack/electron/security.md).
+      [FuseV1Options.EnableEmbeddedAsarIntegrityValidation]: true,
+      [FuseV1Options.OnlyLoadAppFromAsar]: true,
+    }),
+  ],
+};
+
+export default config;

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

@@ -0,0 +1,54 @@
+{
+  "name": "<%= fileName %>",
+  "productName": "<%= name %>",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Electron desktop surface scaffolded by GroundWork",
+  "main": "./out/main/index.js",
+  "scripts": {
+    "dev": "electron-vite dev",
+    "build": "electron-vite build",
+    "start": "electron-vite preview",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc --noEmit -p tsconfig.node.json --composite false && tsc --noEmit -p tsconfig.web.json --composite false",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "smoke": "playwright test",
+    "package": "electron-forge package",
+    "make": "electron-forge make"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.90.0",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@electron-forge/cli": "^7.11.0",
+    "@electron-forge/maker-zip": "^7.11.0",
+    "@electron-forge/plugin-fuses": "^7.11.0",
+    "@electron/fuses": "^1.8.0",
+    "@playwright/test": "^1.60.0",
+    "@tailwindcss/vite": "^4.3.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^24.0.0",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "^5.2.0",
+    "electron": "^42.0.0",
+    "electron-vite": "^5.0.0",
+    "eslint": "^9.39.4",
+    "eslint-plugin-react-hooks": "^7.1.0",
+    "globals": "^17.4.0",
+    "jsdom": "^29.0.0",
+    "playwright": "^1.60.0",
+    "tailwindcss": "^4.3.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "^8.58.0",
+    "vite": "^7.3.0",
+    "vitest": "^4.1.0"
+  }
+}

package/src/generators/electron-app/files/playwright.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from '@playwright/test';
+
+// Boot-tier smoke configuration. The suite launches this app's own Electron
+// binary through Playwright's _electron driver — no browser downloads are
+// needed (`playwright install` is not required). On Linux CI it runs under
+// xvfb; tool/electron_exec.sh handles the display guard
+// (docs/principles/stack/electron/security.md → testing references).
+export default defineConfig({
+  testDir: './tests/smoke',
+  timeout: 60_000,
+  // The smoke drives one app instance; keep the lane serial and thin.
+  fullyParallel: false,
+  workers: 1,
+  use: {
+    screenshot: 'only-on-failure',
+    trace: 'retain-on-failure',
+  },
+});