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/docs/principles/stack/electron/index.md ADDED Viewed

@@ -0,0 +1,47 @@
+---
+title: Electron Desktop Shell
+description: Process model, IPC contracts, security defaults, and packaging for Electron desktop applications.
+status: active
+last_reviewed: 2026-06-12
+---
+# Electron Desktop Shell
+## TL;DR
+Electron is GroundWork's standard desktop surface. This set owns what the desktop shell adds over a web app: the process model, the IPC seam, the security posture, and packaging/updates. Everything the renderer shares with a web frontend — component idiom, styling, accessibility, design-system discipline — is owned by [TypeScript Frontend](../typescript/frontend.md) and is not restated here.
+## Why Electron
+[Surface Stack Selection](../../surface-stack-selection.md) picks Electron on the agent-closable-loop axis: Electron renders on bundled Chromium, so Playwright's `_electron` driver launches the real packaged app, drives its windows as ordinary `Page`s, and evaluates code in the main process — one deterministic engine on every OS, headless under Xvfb in CI. No other desktop option closes generate → boot → test → observe without a human in the loop. The renderer reusing the web stack and brand-token projection wholesale is the second axis win. Tauri is the recorded alternative when binary size and RAM dominate — its per-OS system webviews and WebDriver-only testing surrender the loop, so it is never the default.
+## What this set owns
+| File | Owns |
+|---|---|
+| [Process Model](process-model.md) | Main/renderer/utility split, `utilityProcess`, the enforced folder boundary |
+| [IPC Contracts](ipc-contracts.md) | The typed bridge, validation at the process seam, renderer data fetching over IPC |
+| [Security](security.md) | The hardened defaults, fuses, navigation and permission policy |
+| [Packaging & Updates](packaging-and-updates.md) | Forge, electron-vite, auto-update routes, code signing |
+The split follows the capability-core model: the renderer is a thin surface adapter, and the desktop shell's job is to host it safely. Where the shell adds something to the renderer's world, the addition lives here and the rest defers:
+- **Tailwind v4** loads as a Vite plugin (`@tailwindcss/vite`) in the **renderer section** of `electron.vite.config.ts` — no `tailwind.config.js`; brand tokens live as CSS custom properties via `@theme`. Composition rules: [TypeScript Frontend](../typescript/frontend.md).
+- **Theme sync** is `nativeTheme` in main, broadcast over IPC, mapped to an attribute on `<html>`. What the theme contains: [TypeScript Frontend](../typescript/frontend.md).
+- Everything else about components, styling, and accessibility: [TypeScript Frontend](../typescript/frontend.md), unmodified.
+## Currency is a security obligation
+Electron 42 is current (released 2026-05-05, Chromium M148, Node 24). A new major ships every 8 weeks, and only the latest **three** majors receive security patches — Chromium CVEs land in your app on that clock whether you upgrade or not. An app more than three majors behind is out of security support, so the upgrade cadence is scheduled work, not deferred maintenance. Pin the version, take every major within its support window, and treat a skipped window as a security finding.
+## Survey basis
+Authored from the Electron ecosystem survey dated **2026-06-12**. Load-bearing sources:
+- [Electron security checklist](https://www.electronjs.org/docs/latest/tutorial/security) and [process model](https://www.electronjs.org/docs/latest/tutorial/process-model) — the official baseline.
+- [IPC tutorial](https://www.electronjs.org/docs/latest/tutorial/ipc) and [`utilityProcess` API](https://www.electronjs.org/docs/latest/api/utility-process).
+- [endoflife.date/electron](https://endoflife.date/electron) and [Electron timelines](https://www.electronjs.org/docs/latest/tutorial/electron-timelines) — version and support windows.
+- [VS Code sandbox migration](https://code.visualstudio.com/blogs/2022/11/28/vscode-sandbox) and [Slack: The App Sandbox](https://slack.engineering/the-app-sandbox/) — the reference process architectures.
+- [Trail of Bits, CVE-2025-55305](https://blog.trailofbits.com/2025/09/03/subverting-code-integrity-checks-to-locally-backdoor-signal-1password-slack-and-more/) — why fuses are now expected.
+- [Why Electron Forge](https://www.electronforge.io/core-concepts/why-electron-forge), [electron-vite](https://electron-vite.org/guide/) (v5, alex8088), [Updating Applications](https://www.electronjs.org/docs/latest/tutorial/updates), [update.electronjs.org](https://github.com/electron/update.electronjs.org).
+- [Playwright Electron class](https://playwright.dev/docs/architecture/api/class-electron) — the loop driver.
+- [Azure Artifact Signing](https://azure.microsoft.com/en-us/products/artifact-signing) — Windows signing (renamed from Trusted Signing, GA Jan 2026).

package/src/generators/electron-app/docs/principles/stack/electron/ipc-contracts.md ADDED Viewed

@@ -0,0 +1,71 @@
+---
+title: IPC Contracts
+description: The typed bridge, invoke/handle, runtime validation at the process seam, and IPC-aware data fetching in the renderer.
+status: active
+last_reviewed: 2026-06-12
+---
+# IPC Contracts
+## TL;DR
+The main↔renderer seam is a contract boundary and gets the same discipline the capability core enforces at its contracts: a narrow, purpose-named bridge; `invoke`/`handle` for two-way calls; one shared TypeScript contract type both sides consume; runtime validation in main because renderer input is untrusted. `ipcRenderer` is never exposed and `sendSync` is forbidden.
+## Why this matters
+IPC is where the privileged process meets the sandboxed one. A wide or untyped bridge re-creates the Node-enabled renderer one channel at a time, and an unvalidated handler lets a compromised renderer drive privileged code with arbitrary payloads. Treating the seam as a typed, validated contract keeps the sandbox meaningful — and gives the agent a single place to read what the shell can do.
+## Our principles
+### 1. The bridge is narrow and purpose-named
+Preload exposes a small API object via `contextBridge.exposeInMainWorld()` whose methods name capabilities, not transport:
+```ts
+// src/preload/index.ts
+contextBridge.exposeInMainWorld('api', {
+  openProject: (path: string) => ipcRenderer.invoke('project:open', path),
+  onThemeChanged: (cb: (theme: Theme) => void) => {
+    ipcRenderer.on('theme:changed', (_e, theme) => cb(theme));
+  },
+});
+```
+`ipcRenderer` itself — or any whole Electron module — is never put on `window`; the official docs forbid it for security reasons, because a raw `ipcRenderer` lets injected code call every channel the app has.
+### 2. `invoke`/`handle` for two-way, `send`/`on` for one-way
+`ipcRenderer.invoke` / `ipcMain.handle` is the request/response pattern — promise-based, with errors propagating to the caller. `send`/`on` carries one-way pushes from main (theme changes, update events, file-watcher notifications). `sendSync` is forbidden: it blocks the renderer's event loop for the round trip.
+### 3. One shared contract type, consumed by both sides
+A channel-name → request/response signature map lives in `src/shared/` and types a thin wrapper on each side, so a channel rename or payload change is a compile error in both processes:
+```ts
+// src/shared/ipc.ts
+export type IpcContract = {
+  'project:open': { args: [path: string]; result: ProjectSummary };
+  'settings:get': { args: []; result: Settings };
+};
+```
+This is the hand-rolled convergent pattern. **electron-trpc** (tRPC over IPC, Zod inputs, subscriptions) is the documented variant for apps that want a full RPC layer — but it sits in a maintenance lull (last release 2024-12-07; tRPC v11 support lives in forks) and adds per-call overhead on hot paths, so it is a recorded choice, not the default.
+### 4. Main validates everything it receives
+Main treats renderer input as untrusted, the same way an API treats the public internet. Two checks in every non-trivial `ipcMain.handle`:
+- **Payload validation** with zod for anything beyond a trivial getter — the TypeScript types vanish at runtime, and a compromised renderer is not bound by them.
+- **Sender validation** via `event.senderFrame` (security checklist item 17) — verify the call comes from your app's frame, not an iframe or a navigated-away window.
+### 5. Renderer data fetching is TanStack Query over the bridge
+The renderer's data source is IPC, not HTTP, and TanStack Query is the convergent IPC-aware pattern: `queryFn`s call the typed bridge (`window.api.foo()`), and main-process push events arrive through a bridge subscription that invalidates queries. Caching, retry, and invalidation work exactly as in an HTTP app. This is the desktop shell's one deviation from the web stack's SWR pick in [TypeScript Frontend](../typescript/frontend.md) — the one-cache-one-mental-model rule there still holds: TanStack Query is the renderer's only query library. Theme is the canonical push example: `nativeTheme` in main, broadcast over `send`, mapped to an attribute on `<html>`; everything about what the theme contains defers to [TypeScript Frontend](../typescript/frontend.md).
+## Anti-patterns we reject
+- **Exposing `ipcRenderer` or Electron modules on `window`.** The bridge exists to be narrow; this makes it infinitely wide.
+- **`sendSync`.** It blocks the renderer event loop. There is always an async shape.
+- **String-typed ad-hoc channels.** A channel with no entry in the shared contract is an untyped seam that drifts silently.
+- **Trusting renderer payloads or senders in main.** Compile-time types are not runtime guarantees.
+- **The `remote` module.** Removed from core; any dependency resurrecting it is a finding.
+- **Raw `useEffect` IPC fetching in React.** Same rule as the web stack: data goes through the cache layer, not effect spaghetti.

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

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

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

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

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

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

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

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

@@ -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.",
+            },
+          ],
+        },
+      ],
+    },
+  },
+);