@testsmith/api-spector 0.3.2 → 0.3.4

package/bin/cli.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 'use strict'
 
+const fs = require('fs')
+const os = require('os')
 const path = require('path')
-const { spawn } = require('child_process')
+const { spawn, spawnSync } = require('child_process')
 
 const [, , cmd = 'ui', ...rest] = process.argv
 
@@ -61,50 +63,206 @@ if (!command) {
   process.exit(1)
 }
 
-// ui: spawn electron with the app dir
-if (command.runner === 'electron') {
-  // `require('electron')` throws if electron's postinstall didn't download
-  // the platform binary (common behind corporate proxies on Windows: the
-  // npm install completes but the GitHub Releases download is blocked).
-  // The raw stack trace is intimidating; turn it into actionable steps.
-  let electron
+// ─── Electron binary self-repair ─────────────────────────────────────────────
+//
+// `require('electron')` throws when the postinstall didn't download the
+// platform binary. On corporate machines the ~100 MB zip often IS fully
+// downloaded into electron's cache — it's the extraction into node_modules
+// that got interrupted (antivirus, killed install, …). In that case we can
+// repair the install ourselves, using the OS's own unzip tooling (which is
+// not affected by whatever broke Node's extractor), and launch anyway.
+
+// Mirrors getPlatformPath() in electron's install.js — path.txt must contain
+// exactly this value.
+function electronPlatformPath() {
+  switch (process.platform) {
+    case 'win32': return 'electron.exe'
+    case 'darwin':
+    case 'mas': return 'Electron.app/Contents/MacOS/Electron'
+    default: return 'electron'
+  }
+}
+
+// Default cache roots used by @electron/get, per OS. `electron_config_cache`
+// overrides them (same variable electron's own installer respects).
+function electronCacheDirs() {
+  if (process.env.electron_config_cache) return [process.env.electron_config_cache]
+  const home = os.homedir()
+  if (process.platform === 'win32') {
+    return [path.join(process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'electron', 'Cache')]
+  }
+  if (process.platform === 'darwin') {
+    return [path.join(home, 'Library', 'Caches', 'electron')]
+  }
+  return [path.join(process.env.XDG_CACHE_HOME || path.join(home, '.cache'), 'electron')]
+}
+
+// Find a fully-downloaded electron zip for this version/platform/arch in the
+// cache. Entries live in hash-named subdirectories; a real zip is >20 MB —
+// anything smaller is a truncated download or a proxy's HTML block page.
+function findCachedElectronZip(version) {
+  const wanted = `electron-v${version}-${process.platform}-${process.arch}.zip`
+  for (const root of electronCacheDirs()) {
+    let entries
+    try { entries = fs.readdirSync(root) } catch { continue }
+    for (const entry of ['', ...entries]) {
+      const candidate = path.join(root, entry, wanted)
+      try {
+        if (fs.statSync(candidate).size > 20 * 1024 * 1024) return candidate
+      } catch { /* not there — keep looking */ }
+    }
+  }
+  return null
+}
+
+// Extract with OS-native tools: PowerShell on Windows, ditto on macOS (it
+// preserves the symlinks inside Electron.app, plain unzip does not), unzip on
+// Linux. Deliberately NOT extract-zip — when we get here, that path already
+// failed once on this machine.
+function extractZipNative(zip, destDir) {
+  let r
+  if (process.platform === 'win32') {
+    r = spawnSync('powershell.exe', [
+      '-NoProfile', '-NonInteractive', '-Command',
+      `Expand-Archive -LiteralPath "${zip}" -DestinationPath "${destDir}" -Force`,
+    ], { stdio: 'ignore' })
+  } else if (process.platform === 'darwin') {
+    r = spawnSync('ditto', ['-x', '-k', zip, destDir], { stdio: 'ignore' })
+  } else {
+    r = spawnSync('unzip', ['-o', '-q', zip, '-d', destDir], { stdio: 'ignore' })
+  }
+  return Boolean(r && r.status === 0)
+}
+
+// Attempt to rebuild node_modules/electron/dist from a cached zip.
+// Returns 'repaired', 'no-zip', or a { zip } object when extraction failed.
+function tryRepairElectron() {
+  let pkgPath
+  try { pkgPath = require.resolve('electron/package.json') } catch { return 'no-zip' }
+  const electronDir = path.dirname(pkgPath)
+  const version = require(pkgPath).version
+  const zip = findCachedElectronZip(version)
+  if (!zip) return 'no-zip'
+
+  console.error(`  Electron ${version} was already downloaded — repairing the`)
+  console.error('  installation from the local cache...')
+  const distDir = path.join(electronDir, 'dist')
+  try { fs.rmSync(distDir, { recursive: true, force: true }) } catch { /* best effort */ }
+  if (!extractZipNative(zip, distDir) || !fs.existsSync(path.join(distDir, electronPlatformPath()))) {
+    return { zip }
+  }
+  fs.writeFileSync(path.join(electronDir, 'path.txt'), electronPlatformPath())
+  console.error('  Repaired.')
+  console.error('')
+  return 'repaired'
+}
+
+// Resolve the electron executable, classifying the failure modes.
+function loadElectron() {
   try {
-    electron = require('electron')
+    const electron = require('electron')
+    // path.txt can exist while dist/ is incomplete (interrupted extraction) —
+    // require() succeeds but points at a binary that isn't there.
+    if (typeof electron === 'string' && !fs.existsSync(electron)) {
+      return { status: 'binary-missing' }
+    }
+    return { status: 'ok', electron }
   } catch (err) {
     const msg = err && err.message ? err.message : String(err)
-    const looksLikeBinaryMissing = /Electron failed to install correctly|Cannot find module 'electron'/i.test(msg)
+    if (/Cannot find module 'electron'/i.test(msg)) return { status: 'not-installed' }
+    if (/Electron failed to install correctly/i.test(msg)) return { status: 'binary-missing' }
+    return { status: 'error', message: msg }
+  }
+}
+
+const TROUBLESHOOTING_URL =
+  'https://github.com/testsmith-io/api-spector/blob/main/docs/getting-started/troubleshooting.md'
+
+// ui: spawn electron with the app dir
+if (command.runner === 'electron') {
+  let loaded = loadElectron()
+  let failedZip = null
+
+  if (loaded.status === 'binary-missing') {
+    const repair = tryRepairElectron()
+    if (repair === 'repaired') {
+      loaded = loadElectron()
+    } else if (repair && repair.zip) {
+      failedZip = repair.zip
+    }
+  }
+
+  if (loaded.status !== 'ok') {
     console.error('')
     console.error('  API Spector — failed to launch the UI.')
     console.error('')
-    if (looksLikeBinaryMissing) {
-      const installDir = path.dirname(__dirname)
-      console.error('  Electron is installed, but its platform binary is missing — the')
-      console.error('  download during `npm install` did not complete (often a proxy or')
-      console.error('  firewall blocking github.com / electronjs.org).')
-      console.error('')
-      console.error('  Fix options (try in order):')
+    if (loaded.status === 'not-installed') {
+      console.error('  The electron package is not installed alongside API Spector.')
+      console.error('  Versions 0.3.1 and 0.3.2 shipped without it by mistake.')
       console.error('')
-      console.error('    1. Reinstall and force the postinstall script to run:')
-      console.error('         npm install -g @testsmith/api-spector --force')
+      console.error('  Fix options:')
       console.error('')
-      console.error('    2. Behind a proxy? Set npm + electron mirrors and reinstall:')
-      console.error('         npm config set proxy http://your-proxy:port')
-      console.error('         npm config set https-proxy http://your-proxy:port')
-      console.error('         set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/')
-      console.error('         npm install -g @testsmith/api-spector --force')
+      console.error('    1. Update API Spector (0.3.3 or later includes electron):')
+      console.error('         npm install -D @testsmith/api-spector@latest')
+      console.error('       (use -g instead of -D if you installed globally)')
       console.error('')
-      console.error('    3. Re-run electron\'s postinstall manually:')
-      console.error(`         cd "${path.join(installDir, 'node_modules', 'electron')}"`)
-      console.error('         node install.js')
+      console.error('    2. Or keep this version and install electron yourself:')
+      console.error('         npm install -D electron@31')
+    } else if (loaded.status === 'binary-missing') {
+      let electronDir = null
+      let version = '<version>'
+      try {
+        const pkgPath = require.resolve('electron/package.json')
+        electronDir = path.dirname(pkgPath)
+        version = require(pkgPath).version
+      } catch { /* keep placeholders */ }
+      const zipName = `electron-v${version}-${process.platform}-${process.arch}.zip`
+
+      if (failedZip) {
+        console.error('  Electron\'s binary is missing. A downloaded copy exists at')
+        console.error(`    ${failedZip}`)
+        console.error('  but it could not be extracted — the file may be corrupt (delete')
+        console.error('  it and reinstall), or antivirus is blocking the extraction.')
+      } else {
+        console.error('  Electron is installed, but its platform binary is missing and no')
+        console.error('  usable download was found in the local cache. The download during')
+        console.error('  `npm install` was probably blocked.')
+        console.error('')
+        console.error('  Common causes on corporate machines:')
+        console.error('')
+        console.error('    - Proxy blocks github.com downloads. Note: npm\'s proxy settings')
+        console.error('      do NOT apply to electron\'s downloader — it needs:')
+        console.error('        ELECTRON_GET_USE_PROXY=1')
+        console.error('        GLOBAL_AGENT_HTTPS_PROXY=http://your-proxy:port')
+        console.error('      then: npm install -D @testsmith/api-spector --force')
+        console.error('')
+        console.error('    - TLS-intercepting proxy (certificate errors): point Node at')
+        console.error('      your corporate root CA:')
+        console.error('        NODE_EXTRA_CA_CERTS=/path/to/corporate-root-ca.pem')
+        console.error('')
+        console.error('    - ELECTRON_SKIP_BINARY_DOWNLOAD=1 set machine-wide (some IT')
+        console.error('      images do this) — unset it and reinstall.')
+      }
       console.error('')
-      console.error('  CLI subcommands (run / mock / record / contract / wsdl) do not')
-      console.error('  need the UI binary and should work even while this is broken.')
+      console.error('  Manual fix (works without any of the above): download')
+      console.error(`    https://github.com/electron/electron/releases/download/v${version}/${zipName}`)
+      console.error('  in a browser, extract ALL of it into:')
+      console.error(`    ${electronDir ? path.join(electronDir, 'dist') : '<node_modules>/electron/dist'}`)
+      console.error(`  and create a file "path.txt" next to "dist" containing exactly:`)
+      console.error(`    ${electronPlatformPath()}`)
     } else {
-      console.error(`  ${msg}`)
+      console.error(`  ${loaded.message}`)
     }
     console.error('')
+    console.error('  CLI subcommands (run / mock / record / contract / wsdl) do not')
+    console.error('  need the UI binary and work even while this is broken.')
+    console.error('')
+    console.error(`  Full troubleshooting guide: ${TROUBLESHOOTING_URL}`)
+    console.error('')
     process.exit(1)
   }
+
+  const electron = loaded.electron
   const appDir = path.join(__dirname, '..')
   // Forward the user's cwd so the main process can decide whether to open a
   // workspace in this folder, or fall through to the welcome screen. Without

package/out/main/runner.js

@@ -393,7 +393,7 @@ async function main() {
   if (envName && !env) {
     console.warn(cliCommon.color(`Warning: environment "${envName}" not found. Running without environment.`, cliCommon.C.yellow));
   }
-  const version = `v${"0.3.2"}`;
+  const version = `v${"0.3.4"}`;
   console.log("");
   console.log(cliCommon.color("  API Test Runner" + (version ? ` ${version}` : ""), cliCommon.C.bold, cliCommon.C.white));
   console.log(cliCommon.color(`  Workspace:   ${wsPath}`, cliCommon.C.gray));

package/out/renderer/assets/{index-BSWo6Dkt.js → index-BjjOh-E5.js}

@@ -70829,7 +70829,7 @@ function App() {
       /* @__PURE__ */ jsxRuntimeExports.jsx("span", { style: { color: "#6aa3c8" }, children: "Spector" }),
       /* @__PURE__ */ jsxRuntimeExports.jsxs("span", { className: "ml-2 text-[10px] font-normal opacity-50", children: [
         "v",
-        "0.3.2"
+        "0.3.4"
       ] }),
       /* @__PURE__ */ jsxRuntimeExports.jsx("span", { className: "mx-2 opacity-30", children: "·" }),
       /* @__PURE__ */ jsxRuntimeExports.jsx(

package/out/renderer/index.html

@@ -5,7 +5,7 @@
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>API Spector</title>
-  <script type="module" crossorigin src="./assets/index-BSWo6Dkt.js"></script>
+  <script type="module" crossorigin src="./assets/index-BjjOh-E5.js"></script>
   <link rel="stylesheet" crossorigin href="./assets/index-CjvjKHtF.css">
 </head>
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@testsmith/api-spector",
   "productName": "API Spector",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Local-first API testing tool to inspect, test and mock APIs",
   "repository": {
     "type": "git",
@@ -59,7 +59,6 @@
     "@vitest/coverage-v8": "^3.2.4",
     "jsdom": "^25.0.1",
     "autoprefixer": "^10.4.27",
-    "electron": "~31.7.0",
     "electron-builder": "^26.8.1",
     "electron-vite": "^5.0.0",
     "eslint": "^9.39.4",
@@ -96,6 +95,9 @@
     "ws": "^8.20.0",
     "zustand": "^5.0.12"
   },
+  "optionalDependencies": {
+    "electron": "~31.7.0"
+  },
   "build": {
     "appId": "com.apispector.app",
     "productName": "API Spector",

package/readme.md

@@ -13,6 +13,9 @@ Local-first API testing tool. Inspect, test and mock APIs. Secrets stay on your
 npm install -g @testsmith/api-spector
 ```
 
+> UI not starting after install (common on corporate machines — proxies, antivirus)?
+> See [Troubleshooting: the UI won't start](docs/getting-started/troubleshooting.md).
+
 ## Usage
 
 ### GUI