Extract postinstall into script

Author: charlesvien

apps/code/package.json

@@ -25,7 +25,7 @@
     "test": "vitest run",
     "test:e2e": "playwright test --config=tests/e2e/playwright.config.ts",
     "test:e2e:headed": "playwright test --config=tests/e2e/playwright.config.ts --headed",
-    "postinstall": "cd ../.. && npx @electron/rebuild -f -m node_modules/node-pty && npx @electron/rebuild -f -m node_modules/better-sqlite3 || true && bash apps/code/scripts/patch-electron-name.sh && node apps/code/scripts/download-binaries.mjs",
+    "postinstall": "bash scripts/postinstall.sh",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
     "clean": "rm -rf .vite .turbo out node_modules/.vite",

apps/code/scripts/postinstall.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+# Postinstall script for the Electron app
+# Rebuilds native modules against Electron's Node headers and applies patches
+
+set -e
+
+REPO_ROOT="$(cd ../.. && pwd)"
+SCRIPTS_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+echo "Rebuilding native modules for Electron..."
+
+cd "$REPO_ROOT"
+npx @electron/rebuild -f -m node_modules/node-pty
+npx @electron/rebuild -f -m node_modules/better-sqlite3 || true
+
+echo "Patching Electron app name..."
+bash "$SCRIPTS_DIR/patch-electron-name.sh"
+
+echo "Downloading binaries..."
+node "$SCRIPTS_DIR/download-binaries.mjs"
+
+echo "Postinstall complete."

docs/TROUBLESHOOTING.md

@@ -110,6 +110,31 @@ cd apps/code && npx electron-rebuild -f
 
 Then restart the app.
 
+## node-gyp failed to rebuild @parcel/watcher
+
+If you see this error after pulling or switching branches:
+
+```
+Error: node-gyp failed to rebuild '/path/to/node_modules/@parcel/watcher'
+```
+
+`@parcel/watcher` ships prebuilt N-API binaries per platform (e.g. `@parcel/watcher-darwin-arm64`) and should not need recompilation. This error usually means a stale or partial install state is triggering a source rebuild that fails.
+
+### Fix
+
+```bash
+rm -rf node_modules/@parcel/watcher
+pnpm install
+```
+
+If that doesn't work, nuke and reinstall:
+
+```bash
+rm -rf node_modules && pnpm install
+```
+
+Do **not** run `npx @electron/rebuild` against `@parcel/watcher` — it doesn't need it and the rebuild will fail.
+
 ## `pnpm i` shows "Packages: -198"
 
 You might see something like this every time you run `pnpm install`: