From 905df3b78302757b7e9d6b9bfa2cb80034d681fd Mon Sep 17 00:00:00 2001
From: Chen <99816898+donteatfriedrice@users.noreply.github.com>
Date: Tue, 14 Apr 2026 12:20:48 +0800
Subject: [PATCH] feat: add dev-install script for macOS

Add scripts/dev-install-mac.sh and a pnpm dev:install:mac shortcut so
contributors can build a local production bundle, install it into
/Applications, and launch it with a single command.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 CONTRIBUTING.md            | 10 ++++++++++
 package.json               |  3 ++-
 scripts/dev-install-mac.sh | 33 +++++++++++++++++++++++++++++++++
 3 files changed, 45 insertions(+), 1 deletion(-)
 create mode 100755 scripts/dev-install-mac.sh

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7a7e2ca..8d72a93 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -22,6 +22,16 @@ pnpm run rebuild:native:electron  # Electron app / Playwright e2e
 
 If you hit a `NODE_MODULE_VERSION` mismatch, rerun the matching rebuild command and try again.
 
+## Installing a local build (macOS)
+
+To test a production build of the app locally — builds, installs to `/Applications/Spool.app`, and launches it:
+
+```bash
+pnpm dev:install:mac
+```
+
+Requires Apple Silicon. The script quits any running Spool instance before replacing the bundle and strips the quarantine attribute so Gatekeeper doesn't block the unsigned local build.
+
 ## Project structure
 
 ```
diff --git a/package.json b/package.json
index 882668d..bef3e7c 100644
--- a/package.json
+++ b/package.json
@@ -13,7 +13,8 @@
     "rebuild:native:electron": "pnpm --filter @spool/app run rebuild:native:electron",
     "lint": "turbo lint",
     "clean": "turbo clean",
-    "check:phantom-independence": "scripts/phantom-independence-check.sh"
+    "check:phantom-independence": "scripts/phantom-independence-check.sh",
+    "dev:install:mac": "scripts/dev-install-mac.sh"
   },
   "devDependencies": {
     "turbo": "^2.9.6",
diff --git a/scripts/dev-install-mac.sh b/scripts/dev-install-mac.sh
new file mode 100755
index 0000000..0425f64
--- /dev/null
+++ b/scripts/dev-install-mac.sh
@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Build Spool from source and install it into /Applications.
+# Intended for developer machines (Apple Silicon, unsigned local builds).
+# Run from repo root: bash scripts/dev-install-mac.sh
+
+[[ "$(uname)" == "Darwin" ]] || { echo "dev-install-mac: macOS only"; exit 1; }
+[[ "$(uname -m)" == "arm64" ]] || { echo "dev-install-mac: Apple Silicon only"; exit 1; }
+
+cd "$(dirname "$0")/.."
+
+APP_NAME="Spool"
+DEST="/Applications/${APP_NAME}.app"
+BUILT="packages/app/dist/mac-arm64/${APP_NAME}.app"
+
+echo "==> Quitting running ${APP_NAME}…"
+osascript -e "quit app \"${APP_NAME}\"" 2>/dev/null || true
+
+echo "==> Building (pnpm -F @spool/app build:mac)…"
+pnpm -F @spool/app build:mac
+
+[[ -d "$BUILT" ]] || { echo "dev-install-mac: build output not found at $BUILT"; exit 1; }
+
+echo "==> Installing to ${DEST}…"
+rm -rf "$DEST"
+cp -R "$BUILT" "$DEST"
+
+# Unsigned local builds trigger Gatekeeper; strip quarantine so `open` just works.
+xattr -rd com.apple.quarantine "$DEST" 2>/dev/null || true
+
+echo "==> Launching…"
+open "$DEST"