surf-cli 2.18.0 → 2.20.0

package/native/workflow-runtime.cjs

@@ -75,6 +75,58 @@ function assertNotAborted(signal) {
   if (message) throw new Error(message);
 }
 
+const SEMANTIC_SUCCESS_STATUSES = new Set(["completed", "verified", "skipped_already_satisfied"]);
+
+function semanticFailure(result) {
+  if (!result || typeof result !== "object") return "semantic executor returned an invalid result";
+  if (typeof result.error === "string" && result.error) return result.error;
+  if (typeof result.reason === "string" && result.reason) return result.reason;
+  return `semantic step did not succeed (status: ${String(result.status || "missing")})`;
+}
+
+function semanticDetail(result, step) {
+  if (result?.semantic) return result.semantic;
+  if (!result || typeof result !== "object") return undefined;
+  const detail = {
+    ...(result.runId ? { runId: result.runId } : {}),
+    ...(step.id ? { stepId: step.id } : {}),
+    ...(result.reason ? { reason: result.reason } : {}),
+    ...(result.write ? { write: result.write } : {}),
+    ...(result.coverage ? { coverage: result.coverage } : {}),
+    ...(result.checkpoint ? { checkpoint: result.checkpoint } : {}),
+    ...(result.usage ? { usage: result.usage } : {}),
+    ...(result.limits ? { limits: result.limits } : {}),
+  };
+  return Object.keys(detail).length ? detail : undefined;
+}
+
+async function executeSemanticStep(step, semanticContext, options) {
+  const { executeSemanticStep: executor, onEvent = () => {}, signal } = options;
+  if (typeof executor !== "function") throw new Error("semantic.step requires an injected semantic executor");
+  const startedAt = new Date().toISOString();
+  const baseEvent = { command: step.cmd, argsRedacted: redactCommandArgs(step.cmd, step.args || {}, false), startedAt };
+  onEvent({ type: "tool.started", ...baseEvent });
+  try {
+    assertNotAborted(signal);
+    const result = await executor(step, semanticContext, { signal });
+    assertNotAborted(signal);
+    if (!SEMANTIC_SUCCESS_STATUSES.has(result?.status)) {
+      const error = semanticFailure(result);
+      onEvent({ type: "tool.failed", ...baseEvent, endedAt: new Date().toISOString(), resultSummary: error });
+      const semantic = semanticDetail(result, step);
+      return { success: false, error, ...(semantic ? { semantic } : {}) };
+    }
+    const output = result.publicResult;
+    const semantic = semanticDetail(result, step);
+    onEvent({ type: "tool.completed", ...baseEvent, endedAt: new Date().toISOString(), resultSummary: result.status });
+    return { success: true, ...(output !== undefined ? { output } : {}), ...(semantic ? { semantic } : {}) };
+  } catch (error) {
+    const message = error?.message || String(error);
+    onEvent({ type: "tool.failed", ...baseEvent, endedAt: new Date().toISOString(), resultSummary: message });
+    return { success: false, error: message };
+  }
+}
+
 async function executeSingleStep(step, vars, options) {
   const {
     autoWait = true,
@@ -126,6 +178,11 @@ async function executeSingleStep(step, vars, options) {
 async function executeStep(step, vars, options) {
   const { onError = "stop" } = options;
   assertNotAborted(options.signal);
+  if (step.cmd === "semantic.step") {
+    const result = await executeSemanticStep(step, options.semanticContext, options);
+    if (result.success && step.as && result.output !== undefined) vars[step.as] = result.output;
+    return { ...result, stepsExecuted: 1 };
+  }
   if (step.repeat !== undefined) {
     let max = resolveVar(step.repeat, vars);
     if (typeof max === "string") max = Number.parseInt(max, 10);
@@ -177,9 +234,16 @@ function copyCapturedVars(steps, source, target) {
 }
 
 async function executeWorkflow(steps, options = {}) {
+  const semanticEnabled = steps.some((step) => step.cmd === "semantic.step");
+  if (semanticEnabled && (options.onError || "stop") !== "stop") {
+    return { status: "failed", completedSteps: 0, totalSteps: steps.length, results: [], error: "semantic workflows require onError='stop'", totalMs: 0, vars: { ...(options.vars || {}), ...(options.context?.vars || {}) } };
+  }
   const vars = { ...(options.vars || {}), ...(options.context?.vars || {}) };
+  const semanticContext = semanticEnabled ? (options.createSemanticContext?.() || Object.create(null)) : undefined;
+  const executionOptions = semanticEnabled ? { ...options, semanticContext } : options;
   const results = [];
   let failed = 0;
+  let semantic;
   let stepsExecuted = 0;
   const startTotal = Date.now();
   for (let index = 0; index < steps.length; index++) {
@@ -189,25 +253,26 @@ async function executeWorkflow(steps, options = {}) {
     options.onProgress?.({ phase: "start", index, total: steps.length, step, type });
     let result;
     try {
-      result = await executeStep(step, vars, options);
+      result = await executeStep(step, vars, executionOptions);
     } catch (error) {
       result = { success: false, error: error?.message || String(error), stepsExecuted: 0 };
     }
     const ms = Date.now() - startTime;
+    if (result.semantic) semantic = result.semantic;
     stepsExecuted += type === "loop" ? result.stepsExecuted || 0 : 1;
     if (!result.success) {
       failed++;
-      results.push({ step: index + 1, ...(type === "loop" ? { type: "loop" } : { cmd: step.cmd }), status: "error", error: result.error, ms });
+      results.push({ step: index + 1, ...(type === "loop" ? { type: "loop" } : { cmd: step.cmd }), status: "error", error: result.error, ...(result.semantic ? { semantic: result.semantic } : {}), ms });
       options.onProgress?.({ phase: "fail", index, total: steps.length, step, type, ms, error: result.error });
       if ((options.onError || "stop") === "stop") {
-        return { status: "failed", completedSteps: type === "loop" ? stepsExecuted : stepsExecuted - 1, totalSteps: steps.length, results, error: result.error, totalMs: Date.now() - startTotal, vars };
+        return { status: "failed", completedSteps: type === "loop" ? stepsExecuted : stepsExecuted - 1, totalSteps: steps.length, results, error: result.error, ...(semantic ? { semantic } : {}), totalMs: Date.now() - startTotal, vars };
       }
     } else {
-      results.push({ step: index + 1, ...(type === "loop" ? { type: "loop", stepsExecuted: result.stepsExecuted } : { cmd: step.cmd }), status: "ok", ms });
+      results.push({ step: index + 1, ...(type === "loop" ? { type: "loop", stepsExecuted: result.stepsExecuted } : { cmd: step.cmd }), status: "ok", ...(result.semantic ? { semantic: result.semantic } : {}), ms });
       options.onProgress?.({ phase: "ok", index, total: steps.length, step, type, ms, stepsExecuted: result.stepsExecuted });
     }
   }
-  return { status: failed > 0 ? "partial" : "completed", completedSteps: stepsExecuted, totalSteps: steps.length, results, failed, totalMs: Date.now() - startTotal, vars };
+  return { status: failed > 0 ? "partial" : "completed", completedSteps: stepsExecuted, totalSteps: steps.length, results, failed, ...(semantic ? { semantic } : {}), totalMs: Date.now() - startTotal, vars };
 }
 
 module.exports = {
@@ -215,6 +280,7 @@ module.exports = {
   AUTO_WAIT_MAP,
   MAX_LOOP_ITERATIONS,
   executeSingleStep,
+  executeSemanticStep,
   executeStep,
   executeWorkflow,
   extractStepOutput,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "surf-cli",
-  "version": "2.18.0",
+  "version": "2.20.0",
   "description": "CLI for AI agents to control Chrome. Zero config, agent-agnostic, battle-tested.",
   "keywords": [
     "chrome",
@@ -41,13 +41,16 @@
   "scripts": {
     "dev": "vite build --watch --mode development",
     "build": "vite build",
+    "prepack": "npm run build",
     "check": "tsc --noEmit && tsc --noEmit -p tsconfig.pi-extension.json",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "lint:test": "biome check test/",
     "format": "biome format --write .",
     "test": "vitest run",
+    "test:package": "node test/package-artifact.mjs",
     "test:e2e:chrome": "node test/e2e/real-chrome.mjs",
+    "eval:jev": "node test/eval/real-jev.mjs",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:ui": "vitest --ui",
@@ -57,6 +60,7 @@
   "dependencies": {
     "@google/generative-ai": "^0.24.1",
     "@modelcontextprotocol/sdk": "^1.26.0",
+    "@typesafe-ai/sdk": "0.6.0",
     "buffer": "^6.0.3",
     "crypto-browserify": "^3.12.1",
     "events": "^3.3.0",
@@ -66,16 +70,16 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.4",
-    "@types/chrome": "^0.2.2",
+    "@types/chrome": "^0.3.0",
     "@types/node": "^26.1.2",
-    "@vitest/coverage-v8": "^4.1.9",
-    "@vitest/ui": "^4.1.9",
-    "pi-subagents": "^0.58.0",
-    "puppeteer": "25.9.0",
+    "@vitest/coverage-v8": "^5.0.0",
+    "@vitest/ui": "^5.0.0",
+    "pi-subagents": "^0.69.0",
+    "puppeteer": "25.11.0",
     "typebox": "^1.3.11",
     "typescript": "^7.0.2",
     "vite": "^8.1.4",
-    "vitest": "^4.1.9"
+    "vitest": "^5.0.0"
   },
   "pi": {
     "extensions": [

package/scripts/install-native-host.cjs

@@ -3,9 +3,20 @@ const fs = require("fs");
 const path = require("path");
 const os = require("os");
 const { execFileSync, execSync } = require("child_process");
+const {
+  convertWindowsPath,
+  convertWslPath,
+  getWindowsEnv,
+  nativeMessagingRegistryPath,
+  runWindowsExecutable,
+} = require("./windows-interop.cjs");
 const { parseListenEndpoint } = require("../native/listener.cjs");
 const { normalizeSocketConfig } = require("../native/socket-permissions.cjs");
 const { getStateDir, loadHostIdentity, loadRegistry } = require("../native/remote-auth.cjs");
+const {
+  renderWslWrapper,
+  probeWindowsWrapper,
+} = require("../native/native-host-launch-probe.cjs");
 
 const HOST_NAME = "surf.browser.host";
 
@@ -111,8 +122,7 @@ function getWrapperDir(target = process.platform) {
   const home = os.homedir();
   if (target === "wsl-windows") {
     const localAppData = getWindowsEnv("LOCALAPPDATA");
-    if (!localAppData) return null;
-    return path.join(windowsPathToWslPath(localAppData), "surf-cli");
+    return path.join(convertWindowsPath(localAppData), "surf-cli");
   }
   switch (process.platform) {
     case "darwin":
@@ -140,44 +150,21 @@ function getHostPath() {
   return null;
 }
 
-function getWindowsEnv(name) {
-  try {
-    return execFileSync("cmd.exe", ["/c", "echo", `%${name}%`], { encoding: "utf8" })
-      .trim()
-      .replace(/\r/g, "");
-  } catch {
-    return null;
-  }
-}
-
-function windowsPathToWslPath(winPath) {
-  const normalized = winPath.replace(/\\/g, "/");
-  const match = normalized.match(/^([A-Za-z]):\/(.*)$/);
-  if (!match) return normalized;
-  return `/mnt/${match[1].toLowerCase()}/${match[2]}`;
-}
-
 function wslPathToWindowsPath(wslPath) {
-  try {
-    return execFileSync("wslpath", ["-w", wslPath], { encoding: "utf8" }).trim().replace(/\r/g, "");
-  } catch {
-    const match = wslPath.match(/^\/mnt\/([a-zA-Z])\/(.*)$/);
-    if (match) return `${match[1].toUpperCase()}:\\${match[2].replace(/\//g, "\\")}`;
-    return wslPath;
-  }
+  if (!isWsl()) return wslPath;
+  return convertWslPath(wslPath);
 }
 
-function createWrapper(wrapperDir, nodePath, hostPath, target = process.platform, listen, socketMode, socketGroup) {
+function createWrapper(wrapperDir, nodePath, hostPath, target = process.platform, listen, socketMode, socketGroup, distro = process.env.WSL_DISTRO_NAME, convertPath = wslPathToWindowsPath) {
   const socketConfig = normalizeSocketConfig(socketMode, socketGroup);
   assertSocketAccessTargetSupported(socketConfig.mode, socketConfig.group, target);
   fs.mkdirSync(wrapperDir, { recursive: true });
 
   if (target === "wsl-windows") {
     const cmdPath = path.join(wrapperDir, "host-wrapper-wsl.cmd");
-    const distroArg = process.env.WSL_DISTRO_NAME ? ` -d "${process.env.WSL_DISTRO_NAME}"` : "";
-    const content = `@echo off\r\nwsl.exe${distroArg} --cd "${path.dirname(hostPath)}" --exec "${nodePath}" "${hostPath}" %*\r\n`;
-    fs.writeFileSync(cmdPath, content);
-    return wslPathToWindowsPath(cmdPath);
+    const windowsPath = convertPath(cmdPath);
+    fs.writeFileSync(cmdPath, renderWslWrapper(nodePath, hostPath, distro));
+    return windowsPath;
   }
 
   if (process.platform === "win32") {
@@ -202,6 +189,32 @@ ${listen ? `: "\${SURF_LISTEN:=${listen}}"\nexport SURF_LISTEN\n` : ""}${socketE
   return shPath;
 }
 
+function installWithValidatedWrapper(wrapperPath, target, install, deps = {}) {
+  if (target === "wsl-windows") {
+    if (!deps.distro) throw new Error("WSL_DISTRO_NAME is required for Windows browser installation");
+    try {
+      probeWindowsWrapper(wrapperPath, deps);
+    } catch (error) {
+      if (!error.message.includes("WSL_E_DISTRO_NOT_FOUND")) {
+        throw new Error(`WSL wrapper validation failed before registration: ${error.message}`);
+      }
+      const explicitFailure = error;
+      const original = fs.readFileSync(deps.wrapperFsPath, "utf8");
+      fs.writeFileSync(deps.wrapperFsPath, renderWslWrapper(deps.nodePath, deps.hostPath, null));
+      try {
+        const defaultDistro = probeWindowsWrapper(wrapperPath, { ...deps, verifyDistro: true });
+        if (defaultDistro !== deps.distro) {
+          throw new Error("Windows default WSL distro does not match the installing distro");
+        }
+      } catch (fallbackError) {
+        fs.writeFileSync(deps.wrapperFsPath, original);
+        throw new Error(`WSL wrapper validation failed before registration (explicit distro: ${explicitFailure.message}; default distro: ${fallbackError.message})`);
+      }
+    }
+  }
+  return install();
+}
+
 function assertListenTargetSupported(listen, target) {
   if (listen && (target === "win32" || target === "wsl-windows")) {
     throw new Error("--listen is not supported for Windows native-host wrappers");
@@ -238,22 +251,24 @@ function writeManifest(manifestPath, extensionId, wrapperPath) {
   return manifestPath;
 }
 
-function getWslWindowsManifestDir(browserConfig) {
-  const localAppData = getWindowsEnv("LOCALAPPDATA");
-  if (!localAppData || !browserConfig.wsl) return null;
-  return path.join(windowsPathToWslPath(localAppData), browserConfig.wsl);
+function getWslWindowsManifestDir(browserConfig, deps = {}) {
+  if (!browserConfig.wsl) return null;
+  const localAppData = getWindowsEnv("LOCALAPPDATA", deps);
+  return path.join(convertWindowsPath(localAppData, deps), browserConfig.wsl);
 }
 
-function installManifest(browser, extensionId, wrapperPath, target) {
+function installManifest(browser, extensionId, wrapperPath, target, deps = {}) {
   const browserConfig = BROWSERS[browser];
 
   if (!browserConfig) return null;
 
   if (target === "wsl-windows") {
-    const manifestDir = getWslWindowsManifestDir(browserConfig);
+    const manifestDir = getWslWindowsManifestDir(browserConfig, deps);
     if (!manifestDir) return null;
     const manifestPath = path.join(manifestDir, `${HOST_NAME}.json`);
-    return writeManifest(manifestPath, extensionId, wrapperPath);
+    writeManifest(manifestPath, extensionId, wrapperPath);
+    addWindowsRegistry(browser, convertWslPath(manifestPath, deps), true, deps);
+    return manifestPath;
   }
 
   const platform = process.platform;
@@ -268,23 +283,27 @@ function installManifest(browser, extensionId, wrapperPath, target) {
   return writeManifest(manifestPath, extensionId, wrapperPath);
 }
 
+function addWindowsRegistry(browser, manifestPath, allowWslFallback = false, deps = {}) {
+  const browserConfig = BROWSERS[browser];
+  const regPath = nativeMessagingRegistryPath(browserConfig.win32, HOST_NAME);
+
+  runWindowsExecutable("reg.exe", ["add", regPath, "/ve", "/t", "REG_SZ", "/d", manifestPath, "/f"], {
+    execFileSync: deps.execFileSync || execFileSync,
+    allowWslFallback,
+    execOptions: { stdio: "pipe", encoding: "utf8" },
+  });
+  return regPath;
+}
+
 function installWindowsRegistry(browser, extensionId, wrapperPath) {
   const browserConfig = BROWSERS[browser];
-  const regPath = `HKCU\\Software\\${browserConfig.win32}\\NativeMessagingHosts\\${HOST_NAME}`;
+  if (!browserConfig.win32) return null;
 
   const manifestDir = getWrapperDir();
   const manifestPath = path.join(manifestDir, `${HOST_NAME}.json`);
   writeManifest(manifestPath, extensionId, wrapperPath);
-
-  try {
-    execSync(`reg add "${regPath}" /ve /t REG_SZ /d "${manifestPath}" /f`, {
-      stdio: "pipe",
-    });
-    return manifestPath;
-  } catch (e) {
-    console.error(`Failed to add registry entry: ${e.message}`);
-    return null;
-  }
+  addWindowsRegistry(browser, manifestPath);
+  return manifestPath;
 }
 
 function parseArgs() {
@@ -445,6 +464,9 @@ function main() {
   console.log(`Wrapper dir: ${wrapperDir}`);
   console.log("");
 
+  const wrapperFsPath = path.join(wrapperDir, "host-wrapper-wsl.cmd");
+  const previousWrapper = effectiveTarget === "wsl-windows" && fs.existsSync(wrapperFsPath)
+    ? fs.readFileSync(wrapperFsPath, "utf8") : null;
   const wrapperPath = createWrapper(
     wrapperDir,
     nodePath,
@@ -460,18 +482,34 @@ function main() {
   const installed = [];
   const skipped = [];
 
-  for (const browser of browsers) {
-    if (!BROWSERS[browser]) {
-      console.error(`Unknown browser: ${browser}`);
-      continue;
-    }
-
-    const result = installManifest(browser, extensionId, wrapperPath, effectiveTarget);
-    if (result) {
-      installed.push({ browser: BROWSERS[browser].name, path: result });
-    } else {
-      skipped.push(BROWSERS[browser].name);
+  try {
+    installWithValidatedWrapper(wrapperPath, effectiveTarget, () => {
+      for (const browser of browsers) {
+        if (!BROWSERS[browser]) {
+          console.error(`Unknown browser: ${browser}`);
+          continue;
+        }
+
+        let result;
+        try {
+          result = installManifest(browser, extensionId, wrapperPath, effectiveTarget);
+        } catch (error) {
+          throw new Error(`Failed to install ${BROWSERS[browser].name}: ${error.message}`);
+        }
+        if (result) {
+          installed.push({ browser: BROWSERS[browser].name, path: result });
+        } else {
+          skipped.push(BROWSERS[browser].name);
+        }
+      }
+    }, { wrapperFsPath, nodePath, hostPath, distro: process.env.WSL_DISTRO_NAME });
+  } catch (error) {
+    if (effectiveTarget === "wsl-windows" && installed.length === 0) {
+      if (previousWrapper === null) fs.rmSync(wrapperFsPath, { force: true });
+      else fs.writeFileSync(wrapperFsPath, previousWrapper);
     }
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
   }
 
   if (installed.length > 0) {
@@ -494,7 +532,12 @@ if (require.main === module) {
 
 module.exports = {
   createWrapper,
+  findNode,
+  getHostPath,
+  probeWindowsWrapper,
+  installWithValidatedWrapper,
   writeManifest,
   assertListenTargetSupported,
   assertSocketAccessTargetSupported,
+  installManifest,
 };

package/scripts/uninstall-native-host.cjs

@@ -2,7 +2,13 @@
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
-const { execFileSync, execSync } = require("child_process");
+const { execFileSync } = require("child_process");
+const {
+  convertWindowsPath,
+  getWindowsEnv,
+  nativeMessagingRegistryPath,
+  runWindowsExecutable,
+} = require("./windows-interop.cjs");
 
 const HOST_NAME = "surf.browser.host";
 
@@ -61,29 +67,11 @@ function isWsl() {
   }
 }
 
-function getWindowsEnv(name) {
-  try {
-    return execFileSync("cmd.exe", ["/c", "echo", `%${name}%`], { encoding: "utf8" })
-      .trim()
-      .replace(/\r/g, "");
-  } catch {
-    return null;
-  }
-}
-
-function windowsPathToWslPath(winPath) {
-  const normalized = winPath.replace(/\\/g, "/");
-  const match = normalized.match(/^([A-Za-z]):\/(.*)$/);
-  if (!match) return normalized;
-  return `/mnt/${match[1].toLowerCase()}/${match[2]}`;
-}
-
 function getWrapperDir(target = process.platform) {
   const home = os.homedir();
   if (target === "wsl-windows") {
     const localAppData = getWindowsEnv("LOCALAPPDATA");
-    if (!localAppData) return null;
-    return path.join(windowsPathToWslPath(localAppData), "surf-cli");
+    return path.join(convertWindowsPath(localAppData), "surf-cli");
   }
   switch (process.platform) {
     case "darwin":
@@ -97,25 +85,27 @@ function getWrapperDir(target = process.platform) {
   }
 }
 
-function getWslWindowsManifestPath(browserConfig) {
-  const localAppData = getWindowsEnv("LOCALAPPDATA");
-  if (!localAppData || !browserConfig.wsl) return null;
-  return path.join(windowsPathToWslPath(localAppData), browserConfig.wsl, `${HOST_NAME}.json`);
+function getWslWindowsManifestPath(browserConfig, deps = {}) {
+  if (!browserConfig.wsl) return null;
+  const localAppData = getWindowsEnv("LOCALAPPDATA", deps);
+  return path.join(convertWindowsPath(localAppData, deps), browserConfig.wsl, `${HOST_NAME}.json`);
 }
 
-function removeManifest(browser, target) {
+function removeManifest(browser, target, deps = {}) {
   const browserConfig = BROWSERS[browser];
 
   if (!browserConfig) return null;
 
   if (target === "wsl-windows") {
-    const manifestPath = getWslWindowsManifestPath(browserConfig);
+    const manifestPath = getWslWindowsManifestPath(browserConfig, deps);
     if (!manifestPath) return null;
+    removeWindowsRegistry(browser, true, deps);
     try {
-      fs.unlinkSync(manifestPath);
+      (deps.fs || fs).unlinkSync(manifestPath);
       return manifestPath;
-    } catch {
-      return null;
+    } catch (error) {
+      if (error?.code === "ENOENT") return null;
+      throw new Error(`Failed to remove manifest ${manifestPath}: ${error.message || String(error)}`);
     }
   }
 
@@ -140,16 +130,20 @@ function removeManifest(browser, target) {
   }
 }
 
-function removeWindowsRegistry(browser) {
+function removeWindowsRegistry(browser, allowWslFallback = false, deps = {}) {
   const browserConfig = BROWSERS[browser];
-  const regPath = `HKCU\\Software\\${browserConfig.win32}\\NativeMessagingHosts\\${HOST_NAME}`;
-
+  const regPath = nativeMessagingRegistryPath(browserConfig.win32, HOST_NAME);
   try {
-    execSync(`reg delete "${regPath}" /f`, { stdio: "pipe" });
-    return regPath;
-  } catch {
-    return null;
+    runWindowsExecutable("reg.exe", ["delete", regPath, "/f"], {
+      execFileSync: deps.execFileSync || execFileSync,
+      allowWslFallback,
+      execOptions: { stdio: "pipe", encoding: "utf8" },
+    });
+  } catch (error) {
+    if (/unable to find the specified registry key or value/i.test(error.message)) return null;
+    throw error;
   }
+  return regPath;
 }
 
 function removeWrapperDir(target) {
@@ -246,7 +240,13 @@ function main() {
       continue;
     }
 
-    const result = removeManifest(browser, effectiveTarget);
+    let result;
+    try {
+      result = removeManifest(browser, effectiveTarget);
+    } catch (error) {
+      console.error(`Error: Failed to uninstall ${BROWSERS[browser].name}: ${error.message}`);
+      process.exit(1);
+    }
     if (result) {
       removed.push({ browser: BROWSERS[browser].name, path: result });
     } else {
@@ -275,4 +275,6 @@ function main() {
   console.log("\nDone!");
 }
 
-main();
+if (require.main === module) main();
+
+module.exports = { removeManifest };

package/scripts/windows-interop.cjs

@@ -0,0 +1,89 @@
+const { execFileSync } = require("child_process");
+
+function errorDetail(error) {
+  const stderr = typeof error.stderr === "string" ? error.stderr.trim() : "";
+  return stderr || error.message || String(error);
+}
+
+function runWindowsExecutable(executable, args, options = {}) {
+  const execFile = options.execFileSync || execFileSync;
+  const execOptions = options.execOptions || { encoding: "utf8" };
+
+  try {
+    return execFile(executable, args, execOptions);
+  } catch (directError) {
+    if (!options.allowWslFallback || directError?.code !== "ENOENT") {
+      throw new Error(`Failed to run ${executable}: ${errorDetail(directError)}`);
+    }
+
+    const windowsPath = `C:\\Windows\\System32\\${executable}`;
+    let resolvedPath;
+    try {
+      resolvedPath = execFile("wslpath", ["-u", windowsPath], { encoding: "utf8" }).trim();
+    } catch (resolveError) {
+      throw new Error(
+        `Could not find ${executable} (bare lookup: ${errorDetail(directError)}; ` +
+          `wslpath ${windowsPath}: ${errorDetail(resolveError)})`,
+      );
+    }
+    if (!resolvedPath) {
+      throw new Error(`Could not find ${executable}: wslpath returned an empty path for ${windowsPath}`);
+    }
+
+    try {
+      return execFile(resolvedPath, args, execOptions);
+    } catch (resolvedError) {
+      throw new Error(
+        `Failed to run ${executable} at ${resolvedPath}: ${errorDetail(resolvedError)}`,
+      );
+    }
+  }
+}
+
+function getWindowsEnv(name, options = {}) {
+  const value = runWindowsExecutable("cmd.exe", ["/c", "echo", `%${name}%`], {
+    execFileSync: options.execFileSync || execFileSync,
+    allowWslFallback: true,
+    execOptions: { encoding: "utf8" },
+  }).trim();
+  if (!value || value === `%${name}%`) {
+    throw new Error(
+      `Windows environment variable ${name} is unavailable (cmd.exe returned ${JSON.stringify(value)})`,
+    );
+  }
+  return value;
+}
+
+function nativeMessagingRegistryPath(browserRegistryRoot, hostName) {
+  return `HKCU\\Software\\${browserRegistryRoot}\\NativeMessagingHosts\\${hostName}`;
+}
+
+function convertWindowsPath(windowsPath, options = {}) {
+  const execFile = options.execFileSync || execFileSync;
+  try {
+    const converted = execFile("wslpath", ["-u", windowsPath], { encoding: "utf8" }).trim();
+    if (!converted) throw new Error("wslpath returned an empty path");
+    return converted;
+  } catch (error) {
+    throw new Error(`Could not convert Windows path ${windowsPath}: ${errorDetail(error)}`);
+  }
+}
+
+function convertWslPath(wslPath, options = {}) {
+  const execFile = options.execFileSync || execFileSync;
+  try {
+    const converted = execFile("wslpath", ["-w", wslPath], { encoding: "utf8" }).trim();
+    if (!converted) throw new Error("wslpath returned an empty path");
+    return converted;
+  } catch (error) {
+    throw new Error(`Could not convert WSL path ${wslPath}: ${errorDetail(error)}`);
+  }
+}
+
+module.exports = {
+  convertWindowsPath,
+  convertWslPath,
+  getWindowsEnv,
+  nativeMessagingRegistryPath,
+  runWindowsExecutable,
+};