fix: harden better-sqlite3 Electron ABI compatibility and install workflow

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: astyfx

.nvmrc

@@ -0,0 +1 @@
+22

README.md

@@ -29,8 +29,12 @@ Stave is an Electron-based AI coding workspace built with Bun, React, Vite, and
 
 ## Prerequisites
 
-- Bun
-- Node.js
+- **Bun** — package manager and script runner
+- **Node.js ≥ 20** (Node 22 LTS recommended — see `.nvmrc`). The project pins a version in `.nvmrc`; if you use `nvm` just run `nvm use` after cloning.
+- **C++ build toolchain** — required for compiling `better-sqlite3` and `node-pty` native modules:
+  - macOS: Xcode Command Line Tools (`xcode-select --install`)
+  - Linux: `build-essential` (`sudo apt install build-essential`)
+  - Windows: Windows Build Tools (`npm install -g windows-build-tools`)
 - a working `claude` CLI login if you want Claude support
 - a working `codex` CLI login if you want Codex support
 - `pyright-langserver` or `basedpyright-langserver` on your PATH if you want Python LSP support in the editor
@@ -48,6 +52,14 @@ codex login
 bun install
 ```
 
+`bun install` automatically runs a `postinstall` hook that patches `better-sqlite3` for Electron 41 compatibility and recompiles both `better-sqlite3` and `node-pty` against the Electron ABI. This is required because these native modules must be compiled for Electron's internal Node runtime, not the host Node version.
+
+If you need to skip the native rebuild (e.g. in a CI environment that only runs web builds), set `SKIP_ELECTRON_REBUILD=1`:
+
+```bash
+SKIP_ELECTRON_REBUILD=1 bun install
+```
+
 ## Development
 
 ```bash
@@ -78,24 +90,65 @@ bun run dev:desktop:poll
 - `bun run package:linux:appimage`
 - `bun run package:linux:deb`
 
+## Running the desktop app
+
+The primary way to build and launch Stave locally is:
+
+```bash
+bun run run:desktop:built
+```
+
+This single command:
+1. Recompiles native modules (`better-sqlite3`, `node-pty`) against the Electron ABI
+2. Applies the Electron 41 `better-sqlite3` C++ patch (`info.HolderV2()`)
+3. Runs `electron-vite build` to produce the production bundle
+4. Launches the app:
+   - **macOS** — packages with `electron-builder --dir` and opens `Stave.app` so the OS titlebar shows "Stave" instead of "Electron"
+   - **Linux / Windows** — runs `electron .` with `STAVE_RUNTIME_PROFILE=production`
+
 ## Desktop packaging
 
-The desktop packaging scripts and `bun run run:desktop:built` now rebuild native Electron modules automatically before bundling or launching the built app. On macOS, `bun run run:desktop:built` now launches the unpacked `Stave.app` bundle so the OS shows the app as `Stave` instead of `Electron`. If your local install gets out of sync after `bun install`, run the rebuild manually:
+### Why native modules need rebuilding
+
+`better-sqlite3` and `node-pty` are C++ native modules. When you run `bun install`, they are compiled for the **host Node.js** ABI. Electron bundles its **own Node.js runtime** with a different ABI, so the modules must be recompiled for Electron specifically. Additionally, Electron 41 changed how V8 `PropertyCallbackInfo` works in getter callbacks, requiring a source-level patch to `better-sqlite3` (`info.This()` → `info.HolderV2()`) before the C++ is compiled.
+
+All of this is handled automatically by `postinstall` and by each packaging/run script. You should not need to think about it in normal development.
+
+### Manual rebuild
+
+If you reinstall packages with `--ignore-scripts`, or if your native modules become out of sync for any reason, rebuild manually:
 
 ```bash
 bun run rebuild:electron-deps
 ```
 
-This rebuild now patches `better-sqlite3` in the Electron 41 getter contexts that need `HolderV2()`, then runs `node-gyp rebuild --runtime=electron --build-from-source` for `better-sqlite3` and `node-pty` using the current Electron version and host architecture. Electron headers are cached under `.cache/node-gyp/` in the repo so the rebuild does not depend on a writable home-directory cache.
+The rebuild reads the **actual installed Electron version** from `node_modules/electron/package.json`, so the compiled ABI always matches what is on disk — regardless of semver ranges in `package.json`. Electron headers are cached under `.cache/node-gyp/` inside the repo so the rebuild does not depend on a writable home-directory cache.
 
-Useful packaging commands:
+### Packaging commands
 
 ```bash
+# Build and run locally (primary workflow)
 bun run run:desktop:built
+
+# Package as unpacked directory
+bun run package:desktop
+
+# Linux targets
 bun run package:linux:dir
+bun run package:linux:appimage
 bun run package:linux:deb
 ```
 
+### Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `NODE_MODULE_VERSION` mismatch on launch | Native modules compiled for host Node, not Electron | `bun run rebuild:electron-deps` |
+| App crashes or freezes on first persist | Electron 41 `HolderV2` patch not applied | `bun run rebuild:electron-deps` |
+| `[persistence] upsert-workspace-sync failed` in Electron logs | Same as above, check the full error message | `bun run rebuild:electron-deps` |
+| `Patch signature not found` error during rebuild | `better-sqlite3` version changed or `node_modules` corrupted | `bun install && bun run rebuild:electron-deps` |
+| Build fails with `node-gyp` errors | Missing C++ toolchain | Install Xcode CLT / build-essential (see Prerequisites) |
+
 ## Docs
 
 Stable project documentation now lives under `docs/`.

electron/main/ipc/persistence.ts

@@ -55,6 +55,7 @@ export function registerPersistenceHandlers() {
       });
       event.returnValue = { ok: true };
     } catch (error) {
+      console.error("[persistence] upsert-workspace-sync failed:", error);
       event.returnValue = { ok: false, message: String(error) };
     }
   });

package.json

@@ -9,7 +9,11 @@
   },
   "type": "module",
   "main": "out/main/index.js",
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
+    "postinstall": "node scripts/rebuild-electron-deps.mjs",
     "server-dev": "bun run server/dev-server.ts",
     "dev": "vite",
     "dev:all": "concurrently -n server,client -c blue,green \"bun run server-dev\" \"bun run dev\"",

scripts/rebuild-electron-deps.mjs

@@ -10,6 +10,21 @@ const nativeModules = ["better-sqlite3", "node-pty"];
 
 export function resolveElectronVersion(args = {}) {
   const repoRoot = args.repoRoot ?? defaultRepoRoot;
+
+  // Prefer the actual installed version from node_modules/electron/package.json
+  // so that the compiled ABI matches exactly what is on disk, even when
+  // package.json contains a semver range like "^41.0.0".
+  const installedElectronPkgPath = path.join(repoRoot, "node_modules", "electron", "package.json");
+  try {
+    const installedPkg = JSON.parse(readFileSync(installedElectronPkgPath, "utf8"));
+    if (typeof installedPkg.version === "string" && installedPkg.version.length > 0) {
+      return installedPkg.version;
+    }
+  } catch {
+    // Fall through to package.json derivation below.
+  }
+
+  // Fallback: strip the semver prefix from the devDependencies range.
   const packageJson = JSON.parse(readFileSync(path.join(repoRoot, "package.json"), "utf8"));
   const rawElectronVersion = packageJson.devDependencies?.electron;
 
@@ -83,6 +98,10 @@ function isDirectExecution() {
 }
 
 if (isDirectExecution()) {
+  if (process.env.SKIP_ELECTRON_REBUILD) {
+    console.log("SKIP_ELECTRON_REBUILD is set — skipping Electron native module rebuild.");
+    process.exit(0);
+  }
   try {
     rebuildElectronDeps();
   } catch (error) {

skills/stave-patch-release/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: stave-release
+description: Release workflow for the Stave repository that bumps the patch version, generates release notes with `conventional-changelog`, and opens a pull request against `main`. Use when the user asks to cut the next patch release, ship the current changes as a versioned release, or prepare a release PR. After the PR merges, the repository's GitHub Actions workflow builds and publishes the release artifacts automatically.
+---
+
+# Stave Release
+
+Use this skill to create a versioned release PR for the Stave repository.
+
+Read `references/stave-release-checklist.md` for the exact sequence and repair rules.
+
+## Workflow
+
+1. Detect the repository root.
+   - Run `git rev-parse --show-toplevel` to find the repo root. Never assume a hardcoded path.
+   - All subsequent file reads and writes use this path as the base.
+
+2. Inspect the release state before editing.
+   - Read `package.json` to load the current version.
+   - Run `git status --short` to confirm the working tree is clean (or note what is uncommitted).
+   - Run `git remote -v` and confirm `origin` exists.
+   - Run `git tag --list 'v*' --sort=-version:refname | head -5` to find the most recent semver tag. Incremental `conventional-changelog` generation depends on at least one prior tag.
+   - If no prior semver tag exists, stop and explain that a baseline `vX.Y.Z` tag is required before incremental changelog generation is safe.
+
+3. Bump only the patch version.
+   - Increment `package.json` from `x.y.z` to `x.y.(z+1)`.
+   - Do not bump if the working tree already reflects the intended release version.
+
+4. Generate release notes.
+   - Run: `bunx --bun conventional-changelog-cli -p conventionalcommits -i CHANGELOG.md -s`
+   - Inspect the newly generated top section. If it is empty, heading-only, or missing meaningful bullets, automatically append a concise 3–7 bullet summary derived from the actual diff since the previous tag:
+     - Use `git diff --stat <prev-tag>..HEAD` and `git diff --name-only <prev-tag>..HEAD` as signals.
+     - Summarize user-visible or architecture-significant outcomes — not file lists.
+   - Update `README.md` and any other release-facing docs that changed as part of the shipped behavior so docs and changelog stay aligned.
+   - Review the generated notes before committing.
+
+5. Verify before commit.
+   - Run `bun run typecheck` at minimum.
+   - Run focused tests for changed areas (`bun test` or `bun run test:ci` when scope is broad).
+   - Report any verification that could not run.
+
+6. Stage and commit directly on the current branch (or in a worktree if the working tree is unclean).
+   - Stage: `git add -A`
+   - Commit with a Conventional Commit: `chore: release x.y.z`
+   - Do not amend a previously pushed release commit; always create a new commit.
+
+7. Push the release branch and open a PR.
+   - Push to `origin`: `git push origin <branch>`
+   - Open a PR against `main` using `gh pr create --base main`.
+   - PR title: `chore: release x.y.z`
+   - PR body must include: a bullet summary of shipped changes, the verification commands run and their results, and the `🤖 Generated with Claude Code` footer.
+   - **Never push directly to `main`.** All releases land via PR.
+
+8. Report the outcome.
+   - State the new version.
+   - State the release commit hash and message.
+   - State the PR URL.
+   - State which verification commands ran and their results.
+   - Note that GitHub Actions will build and publish release artifacts after the PR merges.
+
+## Guardrails
+
+- **Never push directly to `main`.** All releases land via PR.
+- Never hardcode a repository path. Always derive it with `git rev-parse --show-toplevel`.
+- Do not bump the version twice if the working tree already reflects the intended release.
+- Do not create a non-Conventional commit.
+- Do not hand-write release notes when `conventional-changelog` is the required path.
+- Do not silently skip changelog review or release-facing doc updates when shipped behavior changed.
+- Do not create a local semver tag before the PR is merged. Tag the merged `main` commit after merge.
+- If verification fails, stop and surface the failure unless the user explicitly accepts releasing anyway.