fix(macos): fix node-pty posix_spawnp error with postinstall script (#347)

* fix(macos): fix node-pty posix_spawnp error with postinstall script

Add postinstall script that fixes spawn-helper permissions on macOS.
The node-pty package ships spawn-helper without execute permissions (644),
causing "posix_spawnp failed" errors when spawning terminal processes.

Closes #284

package-lock.json

@@ -7,6 +7,7 @@
     "": {
       "name": "@siteboon/claude-code-ui",
       "version": "1.18.2",
+      "hasInstallScript": true,
       "license": "GPL-3.0",
       "dependencies": {
         "@anthropic-ai/claude-agent-sdk": "^0.1.71",

package.json

@@ -12,6 +12,7 @@
     "server/",
     "shared/",
     "dist/",
+    "scripts/",
     "README.md"
   ],
   "homepage": "https://cloudcli.ai",
@@ -30,7 +31,8 @@
     "preview": "vite preview",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "start": "npm run build && npm run server",
-    "release": "./release.sh"
+    "release": "./release.sh",
+    "postinstall": "node scripts/fix-node-pty.js"
   },
   "keywords": [
     "claude code",

scripts/fix-node-pty.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * Fix node-pty spawn-helper permissions on macOS
+ *
+ * This script fixes a known issue with node-pty where the spawn-helper
+ * binary is shipped without execute permissions, causing "posix_spawnp failed" errors.
+ *
+ * @see https://github.com/microsoft/node-pty/issues/850
+ * @module scripts/fix-node-pty
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Fixes the spawn-helper binary permissions for node-pty on macOS.
+ *
+ * The node-pty package ships the spawn-helper binary without execute permissions
+ * (644 instead of 755), which causes "posix_spawnp failed" errors when trying
+ * to spawn terminal processes.
+ *
+ * This function:
+ * 1. Checks if running on macOS (darwin)
+ * 2. Locates spawn-helper binaries for both arm64 and x64 architectures
+ * 3. Sets execute permissions (755) on each binary found
+ *
+ * @async
+ * @function fixSpawnHelper
+ * @returns {Promise<void>} Resolves when permissions are fixed or skipped
+ * @example
+ * // Run as postinstall script
+ * await fixSpawnHelper();
+ */
+async function fixSpawnHelper() {
+  const nodeModulesPath = path.join(__dirname, '..', 'node_modules', 'node-pty', 'prebuilds');
+
+  // Only run on macOS
+  if (process.platform !== 'darwin') {
+    return;
+  }
+
+  const darwinDirs = ['darwin-arm64', 'darwin-x64'];
+
+  for (const dir of darwinDirs) {
+    const spawnHelperPath = path.join(nodeModulesPath, dir, 'spawn-helper');
+
+    try {
+      // Check if file exists
+      await fs.access(spawnHelperPath);
+
+      // Make it executable (755)
+      await fs.chmod(spawnHelperPath, 0o755);
+      console.log(`[postinstall] Fixed permissions for ${spawnHelperPath}`);
+    } catch (err) {
+      // File doesn't exist or other error - ignore
+      if (err.code !== 'ENOENT') {
+        console.warn(`[postinstall] Warning: Could not fix ${spawnHelperPath}: ${err.message}`);
+      }
+    }
+  }
+}
+
+fixSpawnHelper().catch(console.error);