mcp-context-sync 1.0.10 → 1.0.11

package/README.md

@@ -24,10 +24,16 @@ context-sync install --all
 context-sync doctor
 ```
 
-## Requirements
+## Supported Platforms
 
-- **Node.js 18+** (20 or 22 LTS recommended)
-- Node 24+ may require Visual Studio Build Tools on Windows (see [Troubleshooting](#windows--node-24-better-sqlite3-build-fails))
+| Node version | macOS / Linux | Windows |
+|-------------|---------------|---------|
+| 18 LTS | ✓ | ✓ |
+| 20 LTS | ✓ recommended | ✓ recommended |
+| 22 LTS | ✓ recommended | ✓ recommended |
+| 23+ | ✓ (may compile from source) | ✗ requires Build Tools¹ |
+
+¹ Node 23+ on Windows has no prebuilt `better-sqlite3` binary. The installer will **abort with a clear message** instead of leaving broken shims. Fix: use Node 20/22 LTS, or install [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with "Desktop development with C++".
 
 ## What gets installed
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-context-sync",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "description": "MCP server for synchronizing work context between AI coding agents (Claude Code, Codex, Gemini, Cursor)",
   "type": "module",
   "main": "dist/index.js",
@@ -10,11 +10,13 @@
   },
   "files": [
     "dist",
+    "scripts/preinstall.cjs",
     "scripts/postinstall.cjs",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
+    "preinstall": "node scripts/preinstall.cjs",
     "postinstall": "node scripts/postinstall.cjs",
     "clean": "node -e \"const fs=require('fs');fs.rmSync('dist',{recursive:true,force:true})\"",
     "build": "npm run clean && tsc",

package/scripts/preinstall.cjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+
+/**
+ * preinstall check — runs BEFORE npm installs dependencies.
+ * Detects known-broken combinations (Node 23+/Windows/no Build Tools)
+ * and aborts with a clear message BEFORE npm leaves broken shims.
+ */
+
+const nodeVersion = process.version;
+const major = parseInt(nodeVersion.slice(1), 10);
+const isWin = process.platform === 'win32';
+
+// Node 18-22 on any platform: prebuilt binaries exist, no issues
+if (major < 23) {
+  process.exit(0);
+}
+
+// Node 23+ on non-Windows: usually has build tools, let it try
+if (!isWin) {
+  console.warn(`\n  ⚠ Node ${nodeVersion} detected. better-sqlite3 may need to compile from source.`);
+  console.warn('  If installation fails, use Node 20 or 22 LTS.\n');
+  process.exit(0);
+}
+
+// Node 23+ on Windows: check if Build Tools are available
+let hasBuildTools = false;
+try {
+  const { execSync } = require('child_process');
+
+  // Method 1: Check for cl.exe (MSVC compiler)
+  try {
+    execSync('where cl.exe', { stdio: ['pipe', 'pipe', 'pipe'] });
+    hasBuildTools = true;
+  } catch {}
+
+  // Method 2: Check for MSBuild (Visual Studio Build Tools)
+  if (!hasBuildTools) {
+    try {
+      execSync('where msbuild', { stdio: ['pipe', 'pipe', 'pipe'] });
+      hasBuildTools = true;
+    } catch {}
+  }
+
+  // Method 3: Check VS install path
+  if (!hasBuildTools) {
+    const fs = require('fs');
+    const vsPath = 'C:\\Program Files (x86)\\Microsoft Visual Studio\\Installer\\vswhere.exe';
+    if (fs.existsSync(vsPath)) {
+      try {
+        const output = execSync(`"${vsPath}" -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath`, {
+          encoding: 'utf-8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        if (output) hasBuildTools = true;
+      } catch {}
+    }
+  }
+} catch {}
+
+if (hasBuildTools) {
+  console.warn(`\n  ⚠ Node ${nodeVersion} on Windows — no prebuilt binary for better-sqlite3.`);
+  console.warn('  Build Tools detected, will compile from source (may take a minute).\n');
+  process.exit(0);
+}
+
+// Node 23+ on Windows without Build Tools — this WILL fail and leave broken shims
+console.error('');
+console.error('╔══════════════════════════════════════════════════════════════════╗');
+console.error('║  mcp-context-sync: installation will fail on this environment   ║');
+console.error('╚══════════════════════════════════════════════════════════════════╝');
+console.error('');
+console.error(`  Node:     ${nodeVersion}`);
+console.error(`  Platform: Windows`);
+console.error('  Build:    Visual Studio Build Tools NOT found');
+console.error('');
+console.error('  better-sqlite3 has no prebuilt binary for Node 23+ on Windows,');
+console.error('  and native compilation requires Visual Studio Build Tools.');
+console.error('  Without them, npm will leave broken .cmd shims in your PATH.');
+console.error('');
+console.error('  ── Recommended fix (fastest) ──────────────────────────────────');
+console.error('');
+console.error('  Use Node 20 or 22 LTS:');
+console.error('');
+console.error('    nvm install 22');
+console.error('    nvm use 22');
+console.error('    npm install -g mcp-context-sync');
+console.error('');
+console.error('  ── Alternative fix ────────────────────────────────────────────');
+console.error('');
+console.error('  Install Visual Studio Build Tools:');
+console.error('    https://visualstudio.microsoft.com/visual-cpp-build-tools/');
+console.error('    Select "Desktop development with C++" workload');
+console.error('    Then retry: npm install -g mcp-context-sync');
+console.error('');
+
+// Exit with error to PREVENT npm from proceeding
+process.exit(1);