cowork-os 0.4.2 → 0.4.3

package/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.3] - 2026-02-26
+
+### Fixed
+- **Windows ARM64 first-run native setup**: when `better-sqlite3` cannot be rebuilt for `arm64`, setup now automatically falls back to `x64` Electron emulation and validates module loading before launch.
+- **Windows ARM64 fallback robustness**: if npm-based x64 rebuild is insufficient, setup now runs an explicit `@electron/rebuild` pass with `--arch x64 --version <electron>` to avoid npm 11 runtime/target env ambiguity.
+- **Windows node-gyp instructions**: replaced invalid npm config guidance with environment-variable-based setup (`GYP_MSVS_VERSION` / `npm_config_msvs_version`) for MSVC detection compatibility.
+
 ## [0.4.0] - 2026-02-26
 
 ### Added

package/README.md

@@ -97,7 +97,7 @@ npm install && npm run setup
 npm run build && npm run package
 ```
 
-> **Windows prerequisites:** Native module compilation (better-sqlite3) requires [Visual C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/). The setup script will warn you if they're missing, but prebuilt binaries may work without them.
+> **Windows prerequisites:** Native module setup may require [Visual Studio Build Tools 2022 (C++)](https://visualstudio.microsoft.com/visual-cpp-build-tools/) and Python 3. On Windows ARM64, setup automatically falls back to x64 Electron emulation when ARM64 native prebuilds are unavailable.
 
 See the [Development Guide](docs/development.md) for prerequisites and details.
 

package/docs/troubleshooting.md

@@ -44,6 +44,39 @@ If you see `Killed: 9` during `npm run setup`, macOS terminated a native build d
 npm run setup
 ```
 
+## Windows native setup fails (`better-sqlite3`)
+
+If first launch exits after:
+
+```text
+[cowork] $ npm.cmd rebuild --ignore-scripts=false better-sqlite3
+[cowork] Native setup failed.
+```
+
+install native build prerequisites, then retry:
+
+1. Install [Visual Studio Build Tools 2022](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with:
+   - Desktop development with C++
+   - MSVC v143 build tools
+   - Windows 10/11 SDK
+2. Install Python 3 and verify:
+
+```powershell
+py -3 --version
+```
+
+3. Set node-gyp MSVC env vars, then retry from a new terminal:
+
+```powershell
+setx GYP_MSVS_VERSION 2022
+setx npm_config_msvs_version 2022
+cowork-os
+```
+
+Windows ARM64 note:
+- Setup now auto-tries x64 Electron emulation if ARM64 native rebuild fails.
+- To disable that fallback and force native ARM64 only, set `COWORK_SETUP_SKIP_X64_FALLBACK=1`.
+
 ## App shows "vUnknown" or remote method error
 
 If the app opens but shows `vUnknown` or `Error invoking remote method 'app:getVersion'`, you likely connected to an older already-running instance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-os",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "CoWork OS - The most complete open-source AI assistant platform",
   "overrides": {
     "@whiskeysockets/baileys": {

package/scripts/setup_native.mjs

@@ -102,6 +102,11 @@ function computeJobs() {
   return Math.min(2, cpuCount);
 }
 
+function nodeMajorVersion() {
+  const major = Number.parseInt(String(process.versions.node || "").split(".")[0], 10);
+  return Number.isFinite(major) ? major : null;
+}
+
 function baseEnvWithJobs(jobs) {
   // These influence node-gyp/make parallelism on macOS/Linux.
   // Always set safe values so global MAKEFLAGS doesn't accidentally cause OOM.
@@ -120,6 +125,25 @@ function readJson(filePath) {
   return JSON.parse(fs.readFileSync(filePath, "utf8"));
 }
 
+function makeElectronTargetEnv(env, electronVersion, arch = process.arch) {
+  return {
+    ...env,
+    npm_config_runtime: "electron",
+    npm_config_target: electronVersion,
+    npm_config_disturl: "https://electronjs.org/headers",
+    npm_config_arch: arch,
+  };
+}
+
+function resolveElectronRebuildCli() {
+  return resolvePackageFile("@electron/rebuild", "cli.js")
+    || (() => {
+      // Fallback: try resolving the main entry and deriving cli.js
+      const entry = resolveFromCwd("@electron/rebuild");
+      return entry ? path.join(path.dirname(entry), "cli.js") : null;
+    })();
+}
+
 function getElectronVersion() {
   try {
     const pkgPath = resolveFromCwd("electron/package.json");
@@ -160,6 +184,97 @@ function testBetterSqlite3InElectron(env) {
   return res;
 }
 
+function shouldTryWindowsArm64X64Fallback() {
+  if (!(process.platform === "win32" && process.arch === "arm64")) return false;
+  const raw = String(process.env.COWORK_SETUP_SKIP_X64_FALLBACK || "")
+    .trim()
+    .toLowerCase();
+  return raw !== "1" && raw !== "true" && raw !== "yes";
+}
+
+function tryWindowsArm64X64Fallback(
+  env,
+  installRootDir,
+  electronInstallScript,
+  electronVersion,
+  electronRebuildCli
+) {
+  if (!shouldTryWindowsArm64X64Fallback()) return null;
+  if (!electronInstallScript || !electronVersion) return null;
+
+  console.log(
+    "[cowork] Windows ARM64 detected; trying x64 Electron + native module fallback (emulation mode)."
+  );
+
+  // Force Electron's installer to fetch x64 binaries, then rebuild better-sqlite3 for x64 Electron ABI.
+  const installRes = run(process.execPath, [electronInstallScript], {
+    env: { ...env, npm_config_arch: "x64" },
+    cwd: installRootDir,
+  });
+  if (installRes.status !== 0) return installRes;
+
+  const x64ElectronEnv = makeElectronTargetEnv(env, electronVersion, "x64");
+  const rebuildRes = run(
+    NPM_CMD,
+    ["rebuild", "--ignore-scripts=false", "better-sqlite3"],
+    { env: x64ElectronEnv, cwd: installRootDir }
+  );
+  if (rebuildRes.status !== 0) {
+    console.log(
+      "[cowork] x64 npm rebuild failed; trying electron-rebuild x64 fallback."
+    );
+  } else {
+    const testRes = testBetterSqlite3InElectron(x64ElectronEnv);
+    if (testRes.status === 0) {
+      console.log("[cowork] better-sqlite3 loads in Electron (x64 emulation mode).");
+      return testRes;
+    }
+
+    console.log(
+      "[cowork] x64 npm rebuild completed, but better-sqlite3 still did not load in Electron."
+    );
+  }
+
+  if (!electronRebuildCli || !fs.existsSync(electronRebuildCli)) {
+    console.log(
+      "[cowork] @electron/rebuild is not installed; cannot run x64 fallback rebuild."
+    );
+    return { status: 1, signal: null };
+  }
+
+  const rebuildX64Res = run(
+    process.execPath,
+    [
+      electronRebuildCli,
+      "-f",
+      "--only",
+      "better-sqlite3",
+      "--sequential",
+      "--arch",
+      "x64",
+      "--version",
+      electronVersion,
+      "--module-dir",
+      installRootDir,
+    ],
+    { env, cwd: installRootDir }
+  );
+  if (rebuildX64Res.status !== 0) return rebuildX64Res;
+
+  const testRes = testBetterSqlite3InElectron(x64ElectronEnv);
+  if (testRes.status === 0) {
+    console.log(
+      "[cowork] better-sqlite3 loads in Electron after x64 electron-rebuild fallback."
+    );
+  } else {
+    console.log(
+      "[cowork] x64 electron-rebuild fallback completed, but better-sqlite3 still did not load."
+    );
+  }
+
+  return testRes;
+}
+
 function ensureBetterSqlite3(env, installRootDir) {
   const pkgPath = resolveFromCwd("better-sqlite3/package.json");
 
@@ -203,6 +318,11 @@ function fail(res, context) {
         "close other apps and re-run `npm run setup`."
     );
   }
+  if (process.platform === "win32") {
+    console.error(
+      "[cowork] On Windows, inspect npm logs in %LocalAppData%\\npm-cache\\_logs\\ for detailed native build errors."
+    );
+  }
   // If a child process was SIGKILL'd, `spawnSync` will surface it as `signal`
   // with `status === null`. Exit 137 (128 + 9) so shell-level retries can
   // reliably detect and retry.
@@ -224,7 +344,7 @@ function checkPrereqs() {
     // Check for Visual C++ build tools (required by node-gyp for native modules)
     const res = spawnSync("where", ["cl.exe"], { encoding: "utf8" });
     if (res.status !== 0) {
-      // Also check via npm config for windows-build-tools
+      // Also check via npm config for an explicit MSVC version.
       const npmRes = spawnSync(NPM_CMD, ["config", "get", "msvs_version"], {
         encoding: "utf8",
       });
@@ -234,16 +354,38 @@ function checkPrereqs() {
         npmRes.stdout.trim() !== "undefined";
       if (!hasMsvs) {
         console.warn(
-          "\n[cowork] Warning: Visual C++ Build Tools may not be installed.\n" +
-            "Native module compilation (better-sqlite3) requires them.\n" +
-            "Install with:\n" +
-            "  npm install -g windows-build-tools\n" +
-            "Or install Visual Studio Build Tools from:\n" +
-            "  https://visualstudio.microsoft.com/visual-cpp-build-tools/\n"
+          "\n[cowork] Warning: Visual Studio C++ Build Tools were not detected.\n" +
+            "Native module compilation (better-sqlite3) may fail without them.\n" +
+            "Install Visual Studio Build Tools 2022 with:\n" +
+            "  - Desktop development with C++\n" +
+            "  - MSVC v143 build tools\n" +
+            "  - Windows 10/11 SDK\n" +
+            "Then set node-gyp MSVC env vars (in cmd):\n" +
+            "  setx GYP_MSVS_VERSION 2022\n" +
+            "  setx npm_config_msvs_version 2022\n" +
+            "Download: https://visualstudio.microsoft.com/visual-cpp-build-tools/\n"
         );
         // Don't exit — prebuilt binaries may work without compilation
       }
     }
+
+    const pyRes = spawnSync("py", ["-3", "--version"], { encoding: "utf8" });
+    const pythonRes = pyRes.status === 0
+      ? pyRes
+      : spawnSync("python", ["--version"], { encoding: "utf8" });
+    if (pythonRes.status !== 0) {
+      console.warn(
+        "\n[cowork] Warning: Python 3 was not detected (`py -3` / `python`).\n" +
+          "node-gyp requires Python 3 for native module builds.\n"
+      );
+    }
+
+    if (process.arch === "arm64" && (nodeMajorVersion() ?? 0) >= 24) {
+      console.log(
+        "[cowork] Windows ARM64 + Node 24 detected. If native ARM64 rebuild fails,\n" +
+          "setup will auto-try x64 Electron emulation for better compatibility."
+      );
+    }
   }
 }
 
@@ -267,6 +409,7 @@ function main() {
     const env = baseEnvWithJobs(attemptJobs);
     const installRootDir = getInstallRootDir();
     const electronInstallScript = resolvePackageFile("electron", "install.js");
+    const electronRebuildCli = resolveElectronRebuildCli();
     const electronBinary = getElectronBinaryPath();
 
     if (!electronInstallScript) {
@@ -300,30 +443,42 @@ function main() {
     // 2) electron-rebuild for the one module (keeps rebuild surface small).
     // 2) Prefer an Electron-targeted rebuild for better-sqlite3 (often prebuilt, lighter).
     if (electronVersion) {
-      const electronEnv = {
-        ...env,
-        npm_config_runtime: "electron",
-        npm_config_target: electronVersion,
-        npm_config_disturl: "https://electronjs.org/headers",
-        npm_config_arch: process.arch,
-      };
+      const electronEnv = makeElectronTargetEnv(env, electronVersion, process.arch);
       const rebuildElectronRes = run(
         NPM_CMD,
         ["rebuild", "--ignore-scripts=false", "better-sqlite3"],
         { env: electronEnv, cwd: installRootDir }
       );
-      if (rebuildElectronRes.status !== 0) return rebuildElectronRes;
-
-      const testRes = testBetterSqlite3InElectron(electronEnv);
-      if (testRes.status === 0) {
-        console.log("[cowork] better-sqlite3 loads in Electron.");
-        return testRes;
+      if (rebuildElectronRes.status !== 0) {
+        console.log(
+          "[cowork] Electron-targeted npm rebuild failed; trying fallback paths."
+        );
+      } else {
+        const testRes = testBetterSqlite3InElectron(electronEnv);
+        if (testRes.status === 0) {
+          console.log("[cowork] better-sqlite3 loads in Electron.");
+          return testRes;
+        }
+
+        console.log(
+          "[cowork] better-sqlite3 did not load after Electron-targeted rebuild; " +
+            "trying fallback paths."
+        );
       }
 
-      console.log(
-        "[cowork] better-sqlite3 did not load after Electron-targeted rebuild; " +
-          "falling back to electron-rebuild."
+      const winArmFallbackRes = tryWindowsArm64X64Fallback(
+        env,
+        installRootDir,
+        electronInstallScript,
+        electronVersion,
+        electronRebuildCli
       );
+      if (winArmFallbackRes) {
+        if (winArmFallbackRes.status === 0) return winArmFallbackRes;
+        console.log(
+          "[cowork] Windows ARM64 x64 fallback did not fully recover; trying current-arch electron-rebuild fallback."
+        );
+      }
     } else {
       console.log(
         "[cowork] Could not determine Electron version; falling back to electron-rebuild."
@@ -331,12 +486,6 @@ function main() {
     }
 
     // 3) Fallback: electron-rebuild.
-    const electronRebuildCli = resolvePackageFile("@electron/rebuild", "cli.js")
-      || (() => {
-        // Fallback: try resolving the main entry and deriving cli.js
-        const entry = resolveFromCwd("@electron/rebuild");
-        return entry ? path.join(path.dirname(entry), "cli.js") : null;
-      })();
     if (!electronRebuildCli || !fs.existsSync(electronRebuildCli)) {
       console.log(
         "[cowork] @electron/rebuild is not installed; skipping fallback rebuild."