zevairouter 1.0.0

package/cli/hooks/camoufoxRuntime.js

@@ -0,0 +1,169 @@
+// Ensure camoufox-js (optional stealth Firefox engine) is installed AND its
+// browser binary is downloaded. The package is in optionalDependencies, so
+// `npm install -g zevairouter` may legitimately ship without it (e.g. when npm
+// skipped optional install on a constrained network). When the user picks
+// Camoufox in the bulk-import modal we install lazily \u2014 same shape as the
+// sqlite/playwright runtime helpers \u2014 instead of failing the worker.
+const { spawnSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const { runNpmInstall, getRuntimeDir, getRuntimeNodeModules } = require("./sqliteRuntime");
+
+const CAMOUFOX_PACKAGE = "camoufox-js";
+const CAMOUFOX_VERSION = "^0.11.0";
+
+let cachedReady = null;
+
+function tryRequireCamoufox() {
+  try {
+    return require(CAMOUFOX_PACKAGE);
+  } catch {}
+  try {
+    const runtimeNm = getRuntimeNodeModules();
+    const candidate = path.join(runtimeNm, CAMOUFOX_PACKAGE);
+    if (fs.existsSync(path.join(candidate, "package.json"))) {
+      return require(candidate);
+    }
+  } catch {}
+  return null;
+}
+
+function findCamoufoxCli() {
+  const candidates = [];
+  try {
+    const pkgJson = require.resolve(`${CAMOUFOX_PACKAGE}/package.json`);
+    candidates.push(path.join(path.dirname(pkgJson), "dist", "cli.js"));
+  } catch {}
+  try {
+    candidates.push(path.join(getRuntimeNodeModules(), CAMOUFOX_PACKAGE, "dist", "cli.js"));
+  } catch {}
+  for (const candidate of candidates) {
+    if (candidate && fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function getCamoufoxBinaryDir() {
+  const homeDir = os.homedir();
+  if (process.platform === "win32") {
+    return path.join(process.env.LOCALAPPDATA || path.join(homeDir, "AppData", "Local"), "camoufox");
+  }
+  if (process.platform === "darwin") {
+    return path.join(homeDir, "Library", "Caches", "camoufox");
+  }
+  return path.join(homeDir, ".cache", "camoufox");
+}
+
+function isCamoufoxBinaryAvailable() {
+  const dir = getCamoufoxBinaryDir();
+  if (!fs.existsSync(dir)) return false;
+  const candidates = [
+    path.join(dir, "camoufox.exe"),
+    path.join(dir, "camoufox"),
+    path.join(dir, "camoufox", "camoufox.exe"),
+    path.join(dir, "camoufox", "camoufox"),
+  ];
+  return candidates.some((p) => {
+    try { return fs.existsSync(p); } catch { return false; }
+  });
+}
+
+function ensureCamoufoxPackage({ silent = false } = {}) {
+  const mod = tryRequireCamoufox();
+  if (mod) return { ok: true, module: mod };
+
+  if (!silent) console.log("\u23f3 Installing camoufox-js (first run, ~few MB)...");
+  const installRes = runNpmInstall({
+    cwd: getRuntimeDir(),
+    pkgs: [`${CAMOUFOX_PACKAGE}@${CAMOUFOX_VERSION}`],
+    extraArgs: ["--no-save"],
+    timeout: 300_000,
+  });
+
+  if (!installRes.ok) {
+    return {
+      ok: false,
+      reason: `npm install ${CAMOUFOX_PACKAGE} failed: ${installRes.stderr.split("\n").pop().slice(0, 200)}`,
+    };
+  }
+
+  const installed = tryRequireCamoufox();
+  if (!installed) {
+    return { ok: false, reason: "camoufox-js installed but cannot be required" };
+  }
+  return { ok: true, module: installed };
+}
+
+function fetchCamoufoxBinary({ silent = false, timeout = 600_000 } = {}) {
+  const cliPath = findCamoufoxCli();
+  if (!cliPath) {
+    return { ok: false, reason: "camoufox-js cli script not found after install" };
+  }
+  if (!silent) console.log("\u23f3 Downloading Camoufox browser binary (first run, ~150MB)...");
+  const res = spawnSync(process.execPath, [cliPath, "fetch"], {
+    stdio: silent ? ["ignore", "pipe", "pipe"] : "inherit",
+    timeout,
+    encoding: "utf8",
+  });
+  if (res.status === 0) {
+    if (!silent) console.log("\u2705 Camoufox browser ready");
+    return { ok: true };
+  }
+  const stderr = String(res.stderr || "");
+  let reason = "unknown error";
+  if (/ENOTFOUND|ETIMEDOUT|getaddrinfo/i.test(stderr)) reason = "no internet connection";
+  else if (/EACCES|EPERM/i.test(stderr)) reason = "permission denied";
+  else if (/ENOSPC/i.test(stderr)) reason = "not enough disk space";
+  else if (stderr.trim()) reason = stderr.trim().split(/\r?\n/).pop().slice(0, 200);
+  return { ok: false, reason };
+}
+
+function ensureCamoufoxRuntime({ silent = false } = {}) {
+  if (cachedReady === true) return { ok: true };
+
+  const pkg = ensureCamoufoxPackage({ silent });
+  if (!pkg.ok) {
+    cachedReady = false;
+    const error = new Error(
+      `Camoufox engine not available. ${pkg.reason}. ` +
+      `Install manually with "npm install -g camoufox-js && npx camoufox-js fetch", then retry. ` +
+      `You can also switch back to the Chromium engine in the bulk-import modal.`
+    );
+    error.code = "CAMOUFOX_PACKAGE_MISSING";
+    return { ok: false, error };
+  }
+
+  if (!isCamoufoxBinaryAvailable()) {
+    const fetched = fetchCamoufoxBinary({ silent });
+    if (!fetched.ok) {
+      cachedReady = false;
+      const error = new Error(
+        `Camoufox browser binary not downloaded. ${fetched.reason}. ` +
+        `Run "npx camoufox-js fetch" manually, then retry. ` +
+        `You can also switch back to the Chromium engine in the bulk-import modal.`
+      );
+      error.code = "CAMOUFOX_BINARY_MISSING";
+      return { ok: false, error };
+    }
+  }
+
+  cachedReady = true;
+  return { ok: true, module: pkg.module };
+}
+
+function loadCamoufoxModule() {
+  return tryRequireCamoufox();
+}
+
+function resetCache() {
+  cachedReady = null;
+}
+
+module.exports = {
+  ensureCamoufoxRuntime,
+  loadCamoufoxModule,
+  isCamoufoxBinaryAvailable,
+  resetCache,
+};

package/cli/hooks/playwrightRuntime.js

@@ -0,0 +1,168 @@
+// Ensure Playwright + Chromium are usable at runtime. `npm i -g zevairouter`
+// installs the playwright npm package but does NOT trigger its postinstall
+// browser download under all package managers, so the first bulk-import
+// attempt fails with "Executable doesn't exist at .../chrome-headless-shell".
+// We download lazily on first launch so users who never touch automation
+// aren't billed ~150MB of disk.
+const { spawnSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+const { runNpmInstall, getRuntimeDir, getRuntimeNodeModules } = require("./sqliteRuntime");
+
+const PLAYWRIGHT_PACKAGE = "playwright";
+const PLAYWRIGHT_VERSION = "^1.54.2";
+
+let cachedReady = null;
+
+function tryRequirePlaywright() {
+  try {
+    return require(PLAYWRIGHT_PACKAGE);
+  } catch {}
+  try {
+    const runtimeNm = getRuntimeNodeModules();
+    const candidate = path.join(runtimeNm, PLAYWRIGHT_PACKAGE);
+    if (fs.existsSync(path.join(candidate, "package.json"))) {
+      return require(candidate);
+    }
+  } catch {}
+  return null;
+}
+
+function isChromiumBinaryAvailable() {
+  const playwright = tryRequirePlaywright();
+  if (!playwright?.chromium?.executablePath) return false;
+  let executable;
+  try {
+    executable = playwright.chromium.executablePath();
+  } catch {
+    return false;
+  }
+  if (!executable) return false;
+  return fs.existsSync(executable);
+}
+
+function findCli() {
+  const candidates = [];
+  try {
+    const pwPkg = require.resolve("playwright/package.json");
+    candidates.push(path.join(path.dirname(pwPkg), "cli.js"));
+  } catch {}
+  try {
+    const pwCorePkg = require.resolve("playwright-core/package.json");
+    candidates.push(path.join(path.dirname(pwCorePkg), "cli.js"));
+  } catch {}
+  try {
+    candidates.push(path.join(getRuntimeNodeModules(), "playwright", "cli.js"));
+    candidates.push(path.join(getRuntimeNodeModules(), "playwright-core", "cli.js"));
+  } catch {}
+  for (const candidate of candidates) {
+    if (candidate && fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function ensurePlaywrightPackage({ silent = false } = {}) {
+  const mod = tryRequirePlaywright();
+  if (mod) return { ok: true, module: mod };
+
+  if (!silent) console.log("\u23f3 Installing playwright package (first run)...");
+  const installRes = runNpmInstall({
+    cwd: getRuntimeDir(),
+    pkgs: [`${PLAYWRIGHT_PACKAGE}@${PLAYWRIGHT_VERSION}`],
+    extraArgs: ["--no-save"],
+    timeout: 300_000,
+  });
+
+  if (!installRes.ok) {
+    return {
+      ok: false,
+      reason: `npm install ${PLAYWRIGHT_PACKAGE} failed: ${installRes.stderr.split("\n").pop().slice(0, 200)}`,
+    };
+  }
+
+  const installed = tryRequirePlaywright();
+  if (!installed) {
+    return { ok: false, reason: "playwright installed but cannot be required" };
+  }
+  return { ok: true, module: installed };
+}
+
+function runInstall({ silent = false, timeout = 600_000 } = {}) {
+  const cliPath = findCli();
+  if (!cliPath) {
+    return { ok: false, reason: "playwright cli not resolvable" };
+  }
+
+  if (!silent) console.log("\u23f3 Downloading Playwright Chromium (first run, ~150MB)...");
+
+  const res = spawnSync(process.execPath, [cliPath, "install", "chromium"], {
+    stdio: silent ? ["ignore", "pipe", "pipe"] : "inherit",
+    timeout,
+    encoding: "utf8",
+  });
+
+  if (res.status === 0) {
+    if (!silent) console.log("\u2705 Playwright Chromium ready");
+    return { ok: true };
+  }
+
+  const stderr = String(res.stderr || "");
+  let reason = "unknown error";
+  if (/ENOTFOUND|ETIMEDOUT|getaddrinfo/i.test(stderr)) reason = "no internet connection";
+  else if (/EACCES|EPERM/i.test(stderr)) reason = "permission denied";
+  else if (/ENOSPC/i.test(stderr)) reason = "not enough disk space";
+  else if (stderr.trim()) reason = stderr.trim().split(/\r?\n/).pop().slice(0, 200);
+
+  return { ok: false, reason };
+}
+
+function ensurePlaywrightRuntime({ silent = false, timeout } = {}) {
+  if (cachedReady === true) return { ok: true };
+
+  const pkg = ensurePlaywrightPackage({ silent });
+  if (!pkg.ok) {
+    cachedReady = false;
+    const error = new Error(
+      `Playwright not available. ${pkg.reason}. ` +
+      `Run "npm install -g playwright && npx playwright install chromium" manually, then retry.`
+    );
+    error.code = "PLAYWRIGHT_PACKAGE_MISSING";
+    return { ok: false, error };
+  }
+
+  if (isChromiumBinaryAvailable()) {
+    cachedReady = true;
+    return { ok: true, module: pkg.module };
+  }
+
+  const result = runInstall({ silent, timeout });
+  if (result.ok && isChromiumBinaryAvailable()) {
+    cachedReady = true;
+    return { ok: true, module: pkg.module };
+  }
+
+  cachedReady = false;
+  const error = new Error(
+    `Playwright Chromium not available. ${result.reason}. ` +
+    `Run "npx playwright install chromium" manually, then retry.`
+  );
+  error.code = "PLAYWRIGHT_CHROMIUM_MISSING";
+  return { ok: false, error };
+}
+
+function loadPlaywrightModule() {
+  return tryRequirePlaywright();
+}
+
+function resetCache() {
+  cachedReady = null;
+}
+
+module.exports = {
+  ensurePlaywrightRuntime,
+  loadPlaywrightModule,
+  isChromiumBinaryAvailable,
+  resetCache,
+  findPlaywrightCli: findCli,
+};

package/cli/hooks/postinstall.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+// Postinstall: warm-up SQLite deps into ~/.zevai/runtime so the first
+// `zevai` start doesn't need network. Failure here is non-fatal —
+// cli.js will retry at runtime if anything is missing.
+const { ensureSqliteRuntime } = require("./sqliteRuntime");
+const { ensureTrayRuntime } = require("./trayRuntime");
+
+try {
+  ensureSqliteRuntime({ silent: false });
+  console.log("[zevai] runtime SQLite deps ready");
+} catch (e) {
+  console.warn(`[zevai] runtime warm-up skipped: ${e.message}`);
+}
+
+try {
+  ensureTrayRuntime({ silent: false });
+} catch (e) {
+  console.warn(`[zevai] tray runtime skipped: ${e.message}`);
+}
+
+process.exit(0);

package/cli/hooks/sqliteRuntime.js

@@ -0,0 +1,147 @@
+// Ensure better-sqlite3 is installed in USER_DATA_DIR/runtime/node_modules
+// (user-writable, avoids Windows EBUSY locks during npm i -g updates).
+// sql.js is bundled in bin/app already; node:sqlite / bun:sqlite are built-in.
+//
+// NOTE: APP_NAME here MUST stay in sync with src/lib/dataDir.js (ESM). This
+// CommonJS copy exists because cli/ can't import the ESM src/ module at
+// runtime. Both resolve to ~/.zevai (or %APPDATA%/zevai on Windows).
+const { execSync, spawnSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const APP_NAME = "zevai";
+const BETTER_SQLITE3_VERSION = "12.6.2";
+
+function getDataDir() {
+  if (process.env.DATA_DIR) return process.env.DATA_DIR;
+  return process.platform === "win32"
+    ? path.join(process.env.APPDATA || os.homedir(), APP_NAME)
+    : path.join(os.homedir(), `.${APP_NAME}`);
+}
+
+function getRuntimeDir() {
+  return path.join(getDataDir(), "runtime");
+}
+
+function getRuntimeNodeModules() {
+  return path.join(getRuntimeDir(), "node_modules");
+}
+
+function ensureRuntimeDir() {
+  const dir = getRuntimeDir();
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  // Minimal package.json so npm treats it as a project root
+  const pkgPath = path.join(dir, "package.json");
+  if (!fs.existsSync(pkgPath)) {
+    fs.writeFileSync(pkgPath, JSON.stringify({
+      name: "zevai-runtime",
+      version: "1.0.0",
+      private: true,
+      description: "User-writable runtime deps for ZevaiRouter (better-sqlite3 native binary)",
+    }, null, 2));
+  }
+  return dir;
+}
+
+function hasModule(name) {
+  return fs.existsSync(path.join(getRuntimeNodeModules(), name, "package.json"));
+}
+
+function isBetterSqliteBinaryValid() {
+  const binary = path.join(getRuntimeNodeModules(), "better-sqlite3", "build", "Release", "better_sqlite3.node");
+  if (!fs.existsSync(binary)) return false;
+  try {
+    const fd = fs.openSync(binary, "r");
+    const buf = Buffer.alloc(4);
+    fs.readSync(fd, buf, 0, 4, 0);
+    fs.closeSync(fd);
+    const magic = buf.toString("hex");
+    if (process.platform === "linux") return magic.startsWith("7f454c46");
+    if (process.platform === "darwin") return magic.startsWith("cffaedfe") || magic.startsWith("cefaedfe");
+    if (process.platform === "win32") return magic.startsWith("4d5a");
+    return true;
+  } catch { return false; }
+}
+
+// Extract a short, user-friendly reason from npm stderr.
+function summarizeNpmError(stderr = "") {
+  const text = String(stderr);
+  if (/ENOTFOUND|ETIMEDOUT|EAI_AGAIN|network|getaddrinfo/i.test(text)) return "No internet connection or registry unreachable";
+  if (/EACCES|EPERM|permission denied/i.test(text)) return "Permission denied (check folder permissions)";
+  if (/ENOSPC|no space/i.test(text)) return "Not enough disk space";
+  if (/node-gyp|gyp ERR|python|MSBuild|Visual Studio|Xcode/i.test(text)) return "Missing build tools (Xcode CLT / Python / VS Build Tools)";
+  if (/ETARGET|version.*not found/i.test(text)) return "Package version not found on registry";
+  const m = text.match(/npm ERR! (.+)/);
+  if (m) return m[1].slice(0, 200);
+  const lastLine = text.trim().split(/\r?\n/).filter(Boolean).pop();
+  return lastLine ? lastLine.slice(0, 200) : "Unknown error";
+}
+
+function runNpmInstall({ cwd, pkgs, extraArgs = [], timeout = 180000 }) {
+  const args = ["install", ...pkgs, "--no-audit", "--no-fund", "--prefer-online", ...extraArgs];
+  const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
+  const res = spawnSync(npmCmd, args, {
+    cwd,
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout,
+    shell: process.platform === "win32",
+    encoding: "utf8",
+  });
+  return { ok: res.status === 0, code: res.status, stderr: res.stderr || "", stdout: res.stdout || "" };
+}
+
+function npmInstall(pkgs, opts = {}) {
+  const cwd = ensureRuntimeDir();
+  const extra = opts.optional ? ["--no-save"] : [];
+  if (!opts.silent) console.log("⏳ Installing SQLite engine (first run)...");
+  const res = runNpmInstall({ cwd, pkgs, extraArgs: extra, timeout: opts.timeout || 180000 });
+  if (!res.ok && !opts.silent) {
+    const reason = summarizeNpmError(res.stderr);
+    console.warn("⚠️  SQLite engine install failed — using fallback");
+    console.warn(`   Reason: ${reason}`);
+    console.warn(`   Retry:  cd "${cwd}" && npm install ${pkgs.join(" ")}`);
+  }
+  return res.ok;
+}
+
+// Public: ensure better-sqlite3 native module is installed in user-writable
+// runtime dir. sql.js is bundled in bin/app already; node:sqlite is built-in.
+// This is purely a *speed optimization* — app works without it via fallbacks.
+function ensureSqliteRuntime({ silent = false } = {}) {
+  ensureRuntimeDir();
+
+  const needBetterSqlite = !hasModule("better-sqlite3") || !isBetterSqliteBinaryValid();
+  if (!needBetterSqlite) {
+    if (!silent) console.log("✅ SQLite engine ready");
+    return { betterSqlite: true };
+  }
+
+  const ok = npmInstall([`better-sqlite3@${BETTER_SQLITE3_VERSION}`], { optional: true, silent });
+  return {
+    betterSqlite: ok && hasModule("better-sqlite3") && isBetterSqliteBinaryValid(),
+  };
+}
+
+// Inject runtime + bundled node_modules into NODE_PATH so child Node processes
+// resolve sql.js (bundled in bin/app/node_modules) and better-sqlite3 (runtime).
+function buildEnvWithRuntime(baseEnv = process.env) {
+  const runtimeNm = getRuntimeNodeModules();
+  const bundledNm = path.join(__dirname, "..", "app", "node_modules");
+  // Also check parent package node_modules (for npm global install where
+  // cli/app/node_modules is not shipped — deps live in root node_modules)
+  const parentNm = path.join(__dirname, "..", "..", "node_modules");
+  const existing = baseEnv.NODE_PATH || "";
+  const NODE_PATH = [runtimeNm, bundledNm, parentNm, existing].filter(Boolean).join(path.delimiter);
+  return { ...baseEnv, NODE_PATH };
+}
+
+module.exports = {
+  ensureSqliteRuntime,
+  buildEnvWithRuntime,
+  getRuntimeDir,
+  getRuntimeNodeModules,
+  runNpmInstall,
+  summarizeNpmError,
+};

package/cli/hooks/trayRuntime.js

@@ -0,0 +1,107 @@
+// Lazy install systray2 for macOS/Linux into USER_DATA_DIR/runtime/node_modules.
+// Windows uses PowerShell NotifyIcon (no binary) → no systray needed.
+// This keeps the published npm tarball free of unsigned Go binaries that
+// trigger antivirus false positives (e.g. Kaspersky flagging tray_windows.exe).
+//
+// We use the maintained `systray2` fork. The original `systray@1.0.5` package
+// bundles a 2017 x86_64 Go binary whose Mach-O headers are rejected by modern
+// dyld (macOS 14+), so the tray silently fails to register on Apple Silicon.
+const { spawnSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const { getRuntimeDir, getRuntimeNodeModules, runNpmInstall, summarizeNpmError } = require("./sqliteRuntime");
+
+const SYSTRAY_PKG = "systray2";
+const SYSTRAY_VERSION = "2.1.4";
+const LEGACY_SYSTRAY_PKG = "systray";
+
+function hasSystray() {
+  return fs.existsSync(path.join(getRuntimeNodeModules(), SYSTRAY_PKG, "package.json"));
+}
+
+// Remove the legacy `systray` package from all known locations.
+// On Windows it was an AV false-positive risk; on macOS/Linux its bundled
+// binary is broken on modern OS versions.
+function cleanupLegacySystray({ silent = false } = {}) {
+  // 1) Runtime dir: ~/.zevai/runtime/node_modules/systray (or %APPDATA% on Win)
+  // 2) npm global nested: <npm_prefix>/node_modules/zevairouter/node_modules/systray
+  //    __dirname here = <pkg root>/hooks → up 1 = pkg root
+  const targets = [
+    path.join(getRuntimeNodeModules(), LEGACY_SYSTRAY_PKG),
+    path.join(__dirname, "..", "node_modules", LEGACY_SYSTRAY_PKG)
+  ];
+  for (const dir of targets) {
+    if (fs.existsSync(dir)) {
+      try {
+        fs.rmSync(dir, { recursive: true, force: true });
+        if (!silent) console.log(`[zevai][runtime] removed legacy systray: ${dir}`);
+      } catch (e) {
+        if (!silent) console.warn(`[zevai][runtime] failed to remove ${dir}: ${e.message}`);
+      }
+    }
+  }
+}
+
+// systray2's npm tarball sometimes ships the bundled Go binary without the
+// executable bit set on macOS, causing spawn() to fail with EACCES. Set +x
+// best-effort so the tray actually starts.
+function chmodSystrayBin({ silent = false } = {}) {
+  if (process.platform === "win32") return;
+  const binName = process.platform === "darwin" ? "tray_darwin_release" : "tray_linux_release";
+  const binPath = path.join(getRuntimeNodeModules(), SYSTRAY_PKG, "traybin", binName);
+  if (!fs.existsSync(binPath)) return;
+  try {
+    fs.chmodSync(binPath, 0o755);
+  } catch (e) {
+    if (!silent) console.warn(`[zevai][runtime] chmod tray bin failed: ${e.message}`);
+  }
+}
+
+function ensureRuntimeDir() {
+  const dir = getRuntimeDir();
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const pkgPath = path.join(dir, "package.json");
+  if (!fs.existsSync(pkgPath)) {
+    fs.writeFileSync(pkgPath, JSON.stringify({
+      name: "zevai-runtime",
+      version: "1.0.0",
+      private: true
+    }, null, 2));
+  }
+  return dir;
+}
+
+function npmInstall(pkgs, { silent = false } = {}) {
+  const cwd = ensureRuntimeDir();
+  if (!silent) console.log("⏳ Installing system tray (first run)...");
+  const res = runNpmInstall({ cwd, pkgs, extraArgs: ["--no-save"], timeout: 120000 });
+  if (!res.ok && !silent) {
+    const reason = summarizeNpmError(res.stderr);
+    console.warn("⚠️  System tray install failed — tray disabled");
+    console.warn(`   Reason: ${reason}`);
+    console.warn(`   Retry:  cd "${cwd}" && npm install ${pkgs.join(" ")}`);
+  }
+  return res.ok;
+}
+
+// Public: ensure systray2 is installed on macOS/Linux only.
+// Windows skips entirely (uses PowerShell tray).
+function ensureTrayRuntime({ silent = false } = {}) {
+  // Always evict the legacy `systray` package — its binary is broken on
+  // modern macOS and an AV false-positive on Windows.
+  cleanupLegacySystray({ silent });
+
+  if (process.platform === "win32") {
+    return { systray: false, skipped: true };
+  }
+  if (hasSystray()) {
+    chmodSystrayBin({ silent });
+    if (!silent) console.log("✅ System tray ready");
+    return { systray: true };
+  }
+  const ok = npmInstall([`${SYSTRAY_PKG}@${SYSTRAY_VERSION}`], { silent });
+  if (ok) chmodSystrayBin({ silent });
+  return { systray: ok && hasSystray() };
+}
+
+module.exports = { ensureTrayRuntime };

package/cli/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "zevairouter-cli",
+  "version": "1.0.0",
+  "description": "ZevaiRouter CLI - Start and manage ZevaiRouter server",
+  "bin": {
+    "zevai": "./cli.js"
+  },
+  "files": [
+    "cli.js",
+    "src",
+    "hooks",
+    "app",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "nodemon -I --watch cli.js --watch src --watch hooks --ext js,json cli.js",
+    "build": "node scripts/build-cli.js",
+    "pack:cli": "npm run build && npm pack --pack-destination ../..",
+    "publish:cli": "npm run build && npm publish",
+    "postinstall": "node hooks/postinstall.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "enquirer": "^2.4.1",
+    "node-forge": "^1.3.3",
+    "node-machine-id": "^1.1.12",
+    "react": "19.2.1",
+    "react-dom": "19.2.1"
+  },
+  "comment_sqlite": "sql.js + better-sqlite3 are NOT bundled here. They are installed into ~/.zevai/runtime/node_modules by hooks/postinstall.js (and re-checked at runtime by cli.js). This avoids Windows EBUSY errors when updating the global CLI, since native .node files no longer live under the locked install dir.",
+  "comment_systray": "systray2 is NOT bundled here. It is lazy-installed into ~/.zevai/runtime/node_modules by hooks/postinstall.js on macOS/Linux only. Windows uses PowerShell NotifyIcon (zero binary). This avoids shipping unsigned Go binaries that trigger antivirus false positives (Kaspersky). We use the systray2 fork because the legacy systray@1.0.5 ships a 2017 x86_64 binary that fails on modern macOS dyld.",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "zevairouter",
+    "zevai",
+    "cli",
+    "proxy",
+    "ai",
+    "api"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Verifiedlabs/zevairouter"
+  },
+  "homepage": "https://github.com/Verifiedlabs/zevairouter",
+  "devDependencies": {
+    "esbuild": "^0.25.12",
+    "nodemon": "^3.1.14"
+  }
+}