@xbrowser/cli 1.22.0 → 1.23.0

package/dist/index.js

@@ -72,7 +72,7 @@ import {
   resolveNpmPackageWithFallback,
   resolveScreenshotsDir,
   setConfigValue
-} from "./chunk-NKW4A74J.js";
+} from "./chunk-XTUAUFL3.js";
 import {
   getDaemonConfig,
   getDaemonProcessStatus,
@@ -7403,7 +7403,7 @@ function attachWaitForHuman(ctx, getOrCreateWSServer) {
     if (!ctx.page) {
       throw new Error("waitForHuman requires an active page");
     }
-    const { HumanInteractionManager: HumanInteractionManager2 } = await import("./human-interaction-Y5IDH6LD.js");
+    const { HumanInteractionManager: HumanInteractionManager2 } = await import("./human-interaction-57VYIR56.js");
     const wsServer2 = await getOrCreateWSServer(ctx.browserContext);
     const manager = new HumanInteractionManager2(wsServer2, ctx.page);
     return manager.waitForHuman(options);
@@ -7519,7 +7519,7 @@ import { join as join7 } from "path";
 import { execSync } from "child_process";
 var SHARED_PLUGIN_DEPENDENCIES = {
   "zod": "^3.24.0",
-  "@dyyz1993/xcli-core": "^0.12.1"
+  "@dyyz1993/xcli-core": "^0.19.0"
 };
 function ensurePluginDependencies(pluginsDir) {
   const zodPath = join7(pluginsDir, "node_modules", "zod");
@@ -8817,7 +8817,7 @@ async function executeCommand(commandName, params, sessionName = "default", extr
     const errorMessage = errMsg(err);
     if (session?.page && process.env.XBROWSER_RECOVERY && !extraOpts?._recoveryAttempted) {
       try {
-        const { attemptRecovery } = await import("./recovery-L5GLDX4O.js");
+        const { attemptRecovery } = await import("./recovery-LMJW537X.js");
         const recovery = await attemptRecovery(
           session.page,
           sessionName,
@@ -9532,13 +9532,39 @@ async function installFromNpm(packageName, name, targetDir) {
 import { existsSync as existsSync9, readFileSync as readFileSync7, writeFileSync as writeFileSync7, rmSync as rmSync3, cpSync as cpSync3 } from "fs";
 import { resolve as resolve5, join as join10 } from "path";
 import { tmpdir as tmpdir2 } from "os";
-import { execSync as execSync2 } from "child_process";
+import { execFile as execFile2 } from "child_process";
 import { verifyPlugin as verifyPlugin3, safeCleanup as safeCleanup3 } from "@dyyz1993/xcli-core";
+var GIT_URL_RE = /^(?:https|git|git\+https|git\+ssh|ssh):\/\/[^\s"'`\\;<>()&]+$/i;
+var GIT_SCP_RE = /^git@[\w.-]+:[\w./~+-]+$/;
+function isValidGitUrl(url) {
+  if (typeof url !== "string" || url.length === 0) return false;
+  if (url.startsWith("-")) return false;
+  if (/[\r\n\0]/.test(url)) return false;
+  return GIT_URL_RE.test(url) || GIT_SCP_RE.test(url);
+}
+function execGit(args) {
+  return new Promise((resolve10, reject) => {
+    execFile2("git", args, (err, _stdout, stderr) => {
+      if (err) {
+        const stderrText = typeof stderr === "string" ? stderr : stderr?.toString("utf-8") ?? "";
+        const detail = stderrText.trim() || err.message;
+        reject(new Error(`git clone failed: ${detail}`));
+      } else {
+        resolve10();
+      }
+    });
+  });
+}
 async function installFromGit(gitUrl, name, targetDir) {
+  if (!isValidGitUrl(gitUrl)) {
+    throw new Error(
+      `Invalid git URL: ${JSON.stringify(gitUrl).slice(0, 120)} \u2014 allowed forms: https://, git://, git+https://, git+ssh://, ssh://, git@host:path`
+    );
+  }
   const tmpDir = join10(tmpdir2(), `xbrowser-git-${Date.now()}`);
   let warnings = [];
   try {
-    execSync2(`git clone --depth 1 "${gitUrl}" "${tmpDir}"`, { stdio: "pipe" });
+    await execGit(["clone", "--depth", "1", "--", gitUrl, tmpDir]);
     const verify = verifyPlugin3(tmpDir, { metadataField: "xbrowser" });
     warnings = verify.warnings ?? [];
     if (!verify.valid) {
@@ -11378,7 +11404,7 @@ async function handleBrowserCommand(command, args, options, sessionName, mode, c
         }
         outputResult({ command: cmdDef.name, description: cmdDef.description, scope: cmdDef.scope, parameters: paramsList }, mode);
       } else {
-        console.log(helpGenerator.generate(cmdDef, { color: true, emoji: false }));
+        process.stdout.write(helpGenerator.generate(cmdDef, { color: true, emoji: false }));
       }
     } else {
       outputError(`Unknown command: ${command}`);
@@ -11779,7 +11805,7 @@ async function handleBrowserCommand(command, args, options, sessionName, mode, c
     if (isEmptyResult) {
       const hint = cdpEndpoint ? `\u53EF\u80FD\u672A\u8FDE\u63A5\u5230\u6D4F\u89C8\u5668\u3002\u8BF7\u786E\u8BA4 ${cdpEndpoint} \u4E0A\u6709 Chrome \u8FD0\u884C\uFF08--remote-debugging-port\uFF09\u3002` : "\u53EF\u80FD\u672A\u8FDE\u63A5\u5230\u6D4F\u89C8\u5668\u3002\u8BF7\u4F7F\u7528 --cdp <endpoint> \u8FDE\u63A5\uFF0C\u6216\u5B89\u88C5 cdp-tunnel \u590D\u7528\u5DF2\u6709 Chrome\u3002";
       outputResult(result.data, mode);
-      console.error(`
+      outputError(`
   \u26A0\uFE0F  ${hint}`);
       process.exit(1);
     } else {
@@ -11796,8 +11822,9 @@ async function handleBrowserCommand(command, args, options, sessionName, mode, c
     try {
       mkdirSync11(dirname7(outputFile), { recursive: true });
       writeFileSync13(outputFile, content, "utf-8");
-      console.log(`
-  \u{1F4C4} Written to ${outputFile}`);
+      process.stdout.write(`
+  \u{1F4C4} Written to ${outputFile}
+`);
     } catch (err) {
       outputError(`Failed to write --output "${outputFile}": ${err instanceof Error ? err.message : String(err)}`);
     }
@@ -11895,7 +11922,7 @@ async function handleSession(args, options, mode, _cdpEndpoint) {
       break;
     }
     default:
-      console.log(handleSessionHelp());
+      process.stdout.write(handleSessionHelp() + "\n");
   }
 }
 
@@ -12069,19 +12096,24 @@ async function handleSearch(args, options, mode) {
     outputEnvelope({ success: true, data: { results: deduped, total: deduped.length } }, { command: "plugin search" }, mode);
   } else {
     if (deduped.length === 0) {
-      console.log("No plugins found");
+      process.stdout.write("No plugins found\n");
       return;
     }
     for (const r of deduped) {
       const src = r.source === "marketplace" ? "[marketplace]" : r.source === "local" ? "[local]" : "[npm]";
       const slug = r.slug ? ` (${r.slug})` : "";
-      console.log(`  ${src} ${r.name}${slug}`);
-      if (r.description) console.log(`    ${r.description}`);
-      if (r.version) console.log(`    Version: ${r.version}`);
-      if (r.downloads) console.log(`    Downloads: ${r.downloads}`);
-      console.log("");
+      process.stdout.write(`  ${src} ${r.name}${slug}
+`);
+      if (r.description) process.stdout.write(`    ${r.description}
+`);
+      if (r.version) process.stdout.write(`    Version: ${r.version}
+`);
+      if (r.downloads) process.stdout.write(`    Downloads: ${r.downloads}
+`);
+      process.stdout.write("\n");
     }
-    console.log(`Total: ${deduped.length} plugins`);
+    process.stdout.write(`Total: ${deduped.length} plugins
+`);
   }
 }
 async function handlePluginInfo(args, options, mode) {
@@ -12098,14 +12130,22 @@ async function handlePluginInfo(args, options, mode) {
         outputEnvelope({ success: true, data: { source: "marketplace", ...d } }, { command: "plugin info" }, mode);
         return;
       }
-      console.log(`\u540D\u79F0: ${d.name || ""}`);
-      console.log(`\u7248\u672C: ${d.version || ""}`);
-      console.log(`\u63CF\u8FF0: ${d.description || ""}`);
-      console.log(`\u4F5C\u8005: ${d.author || ""}`);
-      console.log(`\u547D\u4EE4: ${(d.commands || []).join(", ")}`);
-      console.log(`\u4E0B\u8F7D\u91CF: ${d.downloads || 0}`);
-      console.log(`\u6807\u7B7E: ${(d.tags || []).join(", ")}`);
-      console.log(`\u7F51\u7AD9: ${(d.sites || []).join(", ")}`);
+      process.stdout.write(`\u540D\u79F0: ${d.name || ""}
+`);
+      process.stdout.write(`\u7248\u672C: ${d.version || ""}
+`);
+      process.stdout.write(`\u63CF\u8FF0: ${d.description || ""}
+`);
+      process.stdout.write(`\u4F5C\u8005: ${d.author || ""}
+`);
+      process.stdout.write(`\u547D\u4EE4: ${(d.commands || []).join(", ")}
+`);
+      process.stdout.write(`\u4E0B\u8F7D\u91CF: ${d.downloads || 0}
+`);
+      process.stdout.write(`\u6807\u7B7E: ${(d.tags || []).join(", ")}
+`);
+      process.stdout.write(`\u7F51\u7AD9: ${(d.sites || []).join(", ")}
+`);
       return;
     }
   } catch {
@@ -12124,19 +12164,25 @@ async function handlePluginInfo(args, options, mode) {
           outputEnvelope({ success: true, data: { source: "npm", name: pkg.name, version: latest, description: pkg.description } }, { command: "plugin info" }, mode);
           return;
         }
-        console.log(`\u540D\u79F0: ${pkg.name || ""}`);
-        console.log(`\u7248\u672C: ${latest}`);
-        console.log(`\u63CF\u8FF0: ${pkg.description || ""}`);
+        process.stdout.write(`\u540D\u79F0: ${pkg.name || ""}
+`);
+        process.stdout.write(`\u7248\u672C: ${latest}
+`);
+        process.stdout.write(`\u63CF\u8FF0: ${pkg.description || ""}
+`);
         const author = pkg.author;
-        console.log(`\u4F5C\u8005: ${typeof author === "string" ? author : author?.name || ""}`);
-        console.log(`\u5173\u952E\u8BCD: ${(pkg.keywords || []).join(", ")}`);
-        console.log(`\u8BB8\u53EF\u8BC1: ${pkg.license || ""}`);
+        process.stdout.write(`\u4F5C\u8005: ${typeof author === "string" ? author : author?.name || ""}
+`);
+        process.stdout.write(`\u5173\u952E\u8BCD: ${(pkg.keywords || []).join(", ")}
+`);
+        process.stdout.write(`\u8BB8\u53EF\u8BC1: ${pkg.license || ""}
+`);
         return;
       }
     }
-    console.error(`\u63D2\u4EF6 '${slug}' \u672A\u627E\u5230`);
+    outputError(`\u63D2\u4EF6 '${slug}' \u672A\u627E\u5230`);
   } catch (err) {
-    console.error("\u67E5\u8BE2\u5931\u8D25:", errMsg(err));
+    outputError("\u67E5\u8BE2\u5931\u8D25: " + errMsg(err));
   }
 }
 async function handlePluginSchema(args, mode) {
@@ -12160,32 +12206,39 @@ async function handlePluginSchema(args, mode) {
   }
 }
 function printPluginContract(contract) {
-  console.log(`${contract.plugin.name} contract v${contract.version}`);
-  if (contract.plugin.description) console.log(contract.plugin.description);
-  console.log("");
+  process.stdout.write(`${contract.plugin.name} contract v${contract.version}
+`);
+  if (contract.plugin.description) process.stdout.write(contract.plugin.description + "\n");
+  process.stdout.write("\n");
   for (const command of contract.commands) {
     printCommandContract(contract.plugin.name, command);
   }
 }
 function printCommandContract(pluginName, command) {
-  console.log(`${pluginName} ${command.name}`);
-  if (command.description) console.log(`  ${command.description}`);
-  console.log(`  scope: ${command.scope}`);
+  process.stdout.write(`${pluginName} ${command.name}
+`);
+  if (command.description) process.stdout.write(`  ${command.description}
+`);
+  process.stdout.write(`  scope: ${command.scope}
+`);
   if (command.capabilities.length > 0) {
-    console.log(`  capabilities: ${command.capabilities.join(", ")}`);
+    process.stdout.write(`  capabilities: ${command.capabilities.join(", ")}
+`);
   }
   if (command.positional.length > 0) {
-    console.log(`  positional: ${command.positional.join(", ")}`);
+    process.stdout.write(`  positional: ${command.positional.join(", ")}
+`);
   }
   if (command.form.fields.length > 0) {
-    console.log("  fields:");
+    process.stdout.write("  fields:\n");
     for (const field of command.form.fields) {
       const required = field.required ? "required" : "optional";
       const choices = field.enum ? ` [${field.enum.join("|")}]` : "";
-      console.log(`    --${field.name}: ${field.type}/${field.widget} ${required}${choices}`);
+      process.stdout.write(`    --${field.name}: ${field.type}/${field.widget} ${required}${choices}
+`);
     }
   }
-  console.log("");
+  process.stdout.write("\n");
 }
 async function handlePlugin(args, options, mode) {
   const sub = args[0];
@@ -12274,24 +12327,28 @@ async function handlePlugin(args, options, mode) {
         outputEnvelope({ success: true, data: { plugins: enrichedPlugins } }, { command: "plugin list" }, mode);
       } else {
         if (enrichedPlugins.length === 0) {
-          console.log("No plugins installed");
+          process.stdout.write("No plugins installed\n");
           return;
         }
         for (const p of enrichedPlugins) {
           const loginTag = p.hasLogin ? p.loggedIn ? " [logged in]" : " [need login]" : "";
           if (p.version && p.description) {
-            console.log(`${p.name} (${p.version}) - ${p.description}${loginTag}`);
+            process.stdout.write(`${p.name} (${p.version}) - ${p.description}${loginTag}
+`);
           } else {
-            console.log(`${p.name}${loginTag}`);
+            process.stdout.write(`${p.name}${loginTag}
+`);
           }
           if (p.commands && p.commands.length > 0) {
-            console.log(`  ${p.commands.join(", ")}`);
+            process.stdout.write(`  ${p.commands.join(", ")}
+`);
           }
           if (p.requiresLoginCommands.length > 0) {
-            console.log(`  requires login: ${p.requiresLoginCommands.join(", ")}`);
+            process.stdout.write(`  requires login: ${p.requiresLoginCommands.join(", ")}
+`);
           }
         }
-        console.log(`
+        process.stdout.write(`
 Total: ${enrichedPlugins.length} plugins`);
       }
       break;
@@ -12328,7 +12385,7 @@ See docs/plugin-guide.md for the publishing workflow.`
       );
       break;
     default:
-      console.log(handlePluginHelp());
+      process.stdout.write(handlePluginHelp() + "\n");
   }
 }
 function handleCreate(args, options) {
@@ -12362,7 +12419,7 @@ function handleDaemon(args, options, mode) {
       break;
     }
     default:
-      console.log("Daemon starts automatically. No manual action needed.");
+      process.stdout.write("Daemon starts automatically. No manual action needed.\n");
   }
 }
 
@@ -12431,8 +12488,8 @@ async function handleRecord(args, options, mode) {
       }, mode);
       const md = SessionRecorder.readMarkdownSummary(sessionName);
       if (md) {
-        console.log("");
-        console.log(md);
+        process.stdout.write("\n");
+        process.stdout.write(md + "\n");
       } else {
         const summary = SessionRecorder.readSummary(sessionName);
         if (summary) {
@@ -12491,25 +12548,30 @@ async function handleRecord(args, options, mode) {
       break;
     }
     default:
-      console.log("Usage:");
-      console.log("  xbrowser record start [--url <url>] [--session <name>]");
-      console.log("  xbrowser record stop  [--session <name>]");
-      console.log("  xbrowser record status [--session <name>]");
-      console.log("  xbrowser record summary [--session <name>] [--json]");
-      console.log('  xbrowser record checkpoint --type <type> --hint "description" [--selector <sel>] [--session <name>]');
-      console.log("  xbrowser record generate-plugin [--session <name>] [--name <plugin>] [--output <dir>]");
-      console.log("");
-      console.log("Checkpoint types: dialog, captcha, login, iframe, slider, custom");
+      process.stdout.write("Usage:\n");
+      process.stdout.write("  xbrowser record start [--url <url>] [--session <name>]\n");
+      process.stdout.write("  xbrowser record stop  [--session <name>]\n");
+      process.stdout.write("  xbrowser record status [--session <name>]\n");
+      process.stdout.write("  xbrowser record summary [--session <name>] [--json]\n");
+      process.stdout.write('  xbrowser record checkpoint --type <type> --hint "description" [--selector <sel>] [--session <name>]\n');
+      process.stdout.write("  xbrowser record generate-plugin [--session <name>] [--name <plugin>] [--output <dir>]\n");
+      process.stdout.write("\n");
+      process.stdout.write("Checkpoint types: dialog, captcha, login, iframe, slider, custom\n");
   }
 }
 function printRecordingSummary(summary, sessionName) {
-  console.log("");
-  console.log("=== Recording Summary ===");
-  console.log(`  Start URL: ${summary.startUrl}`);
-  console.log(`  Duration:  ${Math.round(summary.durationMs / 1e3)}s`);
-  console.log(`  Actions:   ${summary.totalActions}`);
-  console.log(`  Network:   ${summary.totalNetworkRequests}`);
-  console.log(`  Steps:     ${summary.steps.length}`);
+  process.stdout.write("\n");
+  process.stdout.write("=== Recording Summary ===\n");
+  process.stdout.write(`  Start URL: ${summary.startUrl}
+`);
+  process.stdout.write(`  Duration:  ${Math.round(summary.durationMs / 1e3)}s
+`);
+  process.stdout.write(`  Actions:   ${summary.totalActions}
+`);
+  process.stdout.write(`  Network:   ${summary.totalNetworkRequests}
+`);
+  process.stdout.write(`  Steps:     ${summary.steps.length}
+`);
   for (const step of summary.steps) {
     const a = step.action;
     const el = a.element;
@@ -12531,20 +12593,24 @@ function printRecordingSummary(summary, sessionName) {
     }
     const navInfo = step.contextChanges.find((c) => c.type === "navigate");
     if (navInfo) desc += ` \u2192 navigate to ${navInfo.url?.substring(0, 80)}`;
-    console.log(`  ${step.step}. ${desc}`);
+    process.stdout.write(`  ${step.step}. ${desc}
+`);
     if (a.clickContext) {
       const ctx = a.clickContext;
       if (ctx.appeared?.length > 0) {
         for (const popup of ctx.appeared) {
           const roleStr = popup.role ? ` [${popup.role}]` : "";
-          console.log(`      \u21B3 ${popup.tag}${roleStr} "${(popup.text || "").substring(0, 60)}"`);
+          process.stdout.write(`      \u21B3 ${popup.tag}${roleStr} "${(popup.text || "").substring(0, 60)}"
+`);
           if (popup.items?.length > 0) {
             for (const item of popup.items.slice(0, 10)) {
               const disStr = item.disabled ? " [disabled]" : "";
-              console.log(`        \u2022 ${item.text}${disStr}`);
+              process.stdout.write(`        \u2022 ${item.text}${disStr}
+`);
             }
             if (popup.items.length > 10) {
-              console.log(`        ... and ${popup.items.length - 10} more items`);
+              process.stdout.write(`        ... and ${popup.items.length - 10} more items
+`);
             }
           }
         }
@@ -12557,31 +12623,41 @@ function printRecordingSummary(summary, sessionName) {
           if (sc.ariaSelected !== void 0) parts.push(`selected=${sc.ariaSelected}`);
           if (sc.dataState) parts.push(`state=${sc.dataState}`);
           if (parts.length > 0) {
-            console.log(`      \u21B3 state: <${sc.tag}> "${(sc.text || "").substring(0, 30)}" ${parts.join(", ")}`);
+            process.stdout.write(`      \u21B3 state: <${sc.tag}> "${(sc.text || "").substring(0, 30)}" ${parts.join(", ")}
+`);
           }
         }
       }
     }
   }
-  console.log("");
-  console.log(`  Files: ${SessionRecorder.getRecordingsDir(sessionName)}/`);
+  process.stdout.write("\n");
+  process.stdout.write(`  Files: ${SessionRecorder.getRecordingsDir(sessionName)}/
+`);
   if (summary.checkpoints && summary.checkpoints.length > 0) {
-    console.log("");
-    console.log(`  Checkpoints (${summary.checkpoints.length}):`);
+    process.stdout.write("\n");
+    process.stdout.write(`  Checkpoints (${summary.checkpoints.length}):
+`);
     for (const cp of summary.checkpoints) {
       const src = cp.source === "auto" ? "[auto]" : "[manual]";
-      console.log(`    ${cp.id}. ${src} [${cp.type}] ${cp.hint}`);
-      if (cp.selector) console.log(`       selector: ${cp.selector}`);
+      process.stdout.write(`    ${cp.id}. ${src} [${cp.type}] ${cp.hint}
+`);
+      if (cp.selector) process.stdout.write(`       selector: ${cp.selector}
+`);
     }
   }
 }
 function printHumanReadableSummary(summary) {
-  console.log(`Start URL: ${summary.startUrl}`);
-  console.log(`Recorded:  ${summary.recordedAt}`);
-  console.log(`Duration:  ${Math.round(summary.durationMs / 1e3)}s`);
-  console.log(`Actions:   ${summary.totalActions}`);
-  console.log(`Network:   ${summary.totalNetworkRequests}`);
-  console.log("");
+  process.stdout.write(`Start URL: ${summary.startUrl}
+`);
+  process.stdout.write(`Recorded:  ${summary.recordedAt}
+`);
+  process.stdout.write(`Duration:  ${Math.round(summary.durationMs / 1e3)}s
+`);
+  process.stdout.write(`Actions:   ${summary.totalActions}
+`);
+  process.stdout.write(`Network:   ${summary.totalNetworkRequests}
+`);
+  process.stdout.write("\n");
   for (const step of summary.steps) {
     const a = step.action;
     const el = a.element;
@@ -12597,20 +12673,23 @@ function printHumanReadableSummary(summary) {
     if (a.value) parts.push(`value="${a.value.substring(0, 50)}"`);
     if (a.key) parts.push(`key=${a.key}`);
     if (a.x !== void 0 && a.y !== void 0) parts.push(`@(${a.x},${a.y})`);
-    console.log(parts.join(" "));
+    process.stdout.write(parts.join(" ") + "\n");
     if (a.clickContext) {
       const ctx = a.clickContext;
       if (ctx.appeared?.length > 0) {
         for (const popup of ctx.appeared) {
           const roleStr = popup.role ? ` [${popup.role}]` : "";
-          console.log(`    \u{1F4CB} ${popup.tag}${roleStr} "${(popup.text || "").substring(0, 60)}"`);
+          process.stdout.write(`    \u{1F4CB} ${popup.tag}${roleStr} "${(popup.text || "").substring(0, 60)}"
+`);
           if (popup.items?.length > 0) {
             for (const item of popup.items.slice(0, 10)) {
               const disStr = item.disabled ? " [disabled]" : "";
-              console.log(`       \u2022 ${item.text}${disStr}`);
+              process.stdout.write(`       \u2022 ${item.text}${disStr}
+`);
             }
             if (popup.items.length > 10) {
-              console.log(`       ... and ${popup.items.length - 10} more items`);
+              process.stdout.write(`       ... and ${popup.items.length - 10} more items
+`);
             }
           }
         }
@@ -12623,40 +12702,50 @@ function printHumanReadableSummary(summary) {
           if (sc.ariaSelected !== void 0) stateParts.push(`selected=${sc.ariaSelected}`);
           if (sc.dataState) stateParts.push(`state=${sc.dataState}`);
           if (stateParts.length > 0) {
-            console.log(`    \u{1F504} <${sc.tag}> "${(sc.text || "").substring(0, 30)}" ${stateParts.join(", ")}`);
+            process.stdout.write(`    \u{1F504} <${sc.tag}> "${(sc.text || "").substring(0, 30)}" ${stateParts.join(", ")}
+`);
           }
         }
       }
     }
     for (const net of step.network) {
-      console.log(`    \u2192 ${net.method} ${net.path} [${net.status}] ${net.resourceType}`);
+      process.stdout.write(`    \u2192 ${net.method} ${net.path} [${net.status}] ${net.resourceType}
+`);
       if (net.requestBody && typeof net.requestBody === "object") {
         const bodyStr = JSON.stringify(net.requestBody);
         if (bodyStr.length <= 200) {
-          console.log(`      body: ${bodyStr}`);
+          process.stdout.write(`      body: ${bodyStr}
+`);
         } else {
-          console.log(`      body: ${bodyStr.substring(0, 200)}... (${bodyStr.length} bytes)`);
+          process.stdout.write(`      body: ${bodyStr.substring(0, 200)}... (${bodyStr.length} bytes)
+`);
         }
       }
     }
     for (const match of step.matchedInputs) {
-      console.log(`    \u{1F517} input "${match.inputValue}" \u2192 network #${match.networkId} param "${match.paramName}"`);
+      process.stdout.write(`    \u{1F517} input "${match.inputValue}" \u2192 network #${match.networkId} param "${match.paramName}"
+`);
     }
     for (const ctx of step.contextChanges) {
       if (ctx.type === "navigate") {
-        console.log(`    \u2197 navigate \u2192 ${ctx.url}`);
+        process.stdout.write(`    \u2197 navigate \u2192 ${ctx.url}
+`);
       } else if (ctx.type === "new_tab") {
-        console.log(`    \u2197 new tab: ${ctx.url}`);
+        process.stdout.write(`    \u2197 new tab: ${ctx.url}
+`);
       }
     }
   }
   if (summary.checkpoints && summary.checkpoints.length > 0) {
-    console.log("");
-    console.log(`Checkpoints (${summary.checkpoints.length}):`);
+    process.stdout.write("\n");
+    process.stdout.write(`Checkpoints (${summary.checkpoints.length}):
+`);
     for (const cp of summary.checkpoints) {
       const src = cp.source === "auto" ? "[auto]" : "[manual]";
-      console.log(`  ${cp.id}. ${src} [${cp.type}] ${cp.hint}`);
-      if (cp.selector) console.log(`     selector: ${cp.selector}`);
+      process.stdout.write(`  ${cp.id}. ${src} [${cp.type}] ${cp.hint}
+`);
+      if (cp.selector) process.stdout.write(`     selector: ${cp.selector}
+`);
     }
   }
 }
@@ -12685,10 +12774,12 @@ async function handleReplay(args, options, mode) {
   if (result.ok && mode !== "json" && mode !== "yaml") {
     const healed = typeof result.healed === "number" ? result.healed : 0;
     if (healed > 0) {
-      console.log(`
-Self-healed ${healed} action(s):`);
+      process.stdout.write(`
+Self-healed ${healed} action(s):
+`);
       for (const d of result.healedDetails ?? []) {
-        console.log(`  - step ${d.index + 1}: ${d.strategy}`);
+        process.stdout.write(`  - step ${d.index + 1}: ${d.strategy}
+`);
       }
     }
   }
@@ -12698,7 +12789,7 @@ async function handleConvert(args, _mode) {
   const filePath = args[0];
   const outputPath = args[1];
   if (!filePath || !outputPath) {
-    console.error("Usage: xbrowser convert <recording.yaml> <output.{js,py,sh}>");
+    outputError("Usage: xbrowser convert <recording.yaml> <output.{js,py,sh}>");
     process.exit(1);
   }
   const fs6 = await import("fs");
@@ -12710,11 +12801,11 @@ async function handleConvert(args, _mode) {
     const content = fs6.readFileSync(filePath, "utf-8");
     recording = yaml3.parse(content);
   } catch (e) {
-    console.error(`Error: Failed to read "${filePath}": ${e instanceof Error ? e.message.split("\n")[0] : String(e)}`);
+    outputError(`Error: Failed to read "${filePath}": ${e instanceof Error ? e.message.split("\n")[0] : String(e)}`);
     process.exit(1);
   }
   if (recording === null || typeof recording !== "object" || Array.isArray(recording)) {
-    console.error(`Error: "${filePath}" does not contain a valid recording (expected a YAML/JSON object with events or actions).`);
+    outputError(`Error: "${filePath}" does not contain a valid recording (expected a YAML/JSON object with events or actions).`);
     process.exit(1);
   }
   const rawActions = recording.actions;
@@ -12748,24 +12839,28 @@ async function handleConvert(args, _mode) {
   fs6.writeFileSync(outputPath, script);
   fs6.chmodSync(outputPath, 493);
   const eventCount = (recordingTyped.events || []).length;
-  console.log(`Converted ${filePath} -> ${outputPath}`);
-  console.log(`  Events: ${eventCount}, Start URL: ${recordingTyped.startUrl}`);
-  console.log(`  Run: ${ext === ".py" ? "python" : ext === ".sh" ? "./" : "node"} ${outputPath}`);
+  process.stdout.write(`Converted ${filePath} -> ${outputPath}
+`);
+  process.stdout.write(`  Events: ${eventCount}, Start URL: ${recordingTyped.startUrl}
+`);
+  process.stdout.write(`  Run: ${ext === ".py" ? "python" : ext === ".sh" ? "./" : "node"} ${outputPath}
+`);
 }
 async function handleExtract(args, _mode) {
   const filePath = args[0];
   if (!filePath) {
-    console.error("Usage: xbrowser extract <recording.yaml>");
+    outputError("Usage: xbrowser extract <recording.yaml>");
     process.exit(1);
   }
   const { extractAndSave: extractAndSave2, printExtractSummary: printExtractSummary2 } = await import("./extract-DSU2RVMN.js");
   try {
     const { summary, outputPath } = extractAndSave2(filePath);
     printExtractSummary2(summary);
-    console.log(`
-Saved LLM summary: ${outputPath}`);
+    process.stdout.write(`
+Saved LLM summary: ${outputPath}
+`);
   } catch (e) {
-    console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);
+    outputError(`Error: ${e instanceof Error ? e.message : String(e)}`);
     process.exit(1);
   }
 }
@@ -12773,7 +12868,7 @@ async function handleFilter(args, _mode, options) {
   const filePath = args[0];
   const outputPath = args[1];
   if (!filePath || !outputPath) {
-    console.error("Usage: xbrowser filter <input.yaml> <output.yaml> [--exclude type1,type2]");
+    outputError("Usage: xbrowser filter <input.yaml> <output.yaml> [--exclude type1,type2]");
     process.exit(1);
   }
   const { filterRecording: filterRecording2, parseExcludeTypes: parseExcludeTypes2 } = await import("./filter-3DXC6432.js");
@@ -12785,10 +12880,12 @@ async function handleFilter(args, _mode, options) {
   const excludeTypes = parseExcludeTypes2(excludeArgs);
   try {
     const result = filterRecording2(filePath, outputPath, excludeTypes);
-    console.log(`Filtered ${filePath} -> ${outputPath}`);
-    console.log(`  Original: ${result.originalCount}, After: ${result.filteredCount}, Removed: ${result.removed} (${result.percentage}%)`);
+    process.stdout.write(`Filtered ${filePath} -> ${outputPath}
+`);
+    process.stdout.write(`  Original: ${result.originalCount}, After: ${result.filteredCount}, Removed: ${result.removed} (${result.percentage}%)
+`);
   } catch (e) {
-    console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);
+    outputError(`Error: ${e instanceof Error ? e.message : String(e)}`);
     process.exit(1);
   }
 }
@@ -12817,21 +12914,30 @@ async function handleGeneratePlugin(sessionName, pluginName, outputDir) {
   if (knowledgeMd) {
     writeFileSync13(join16(finalOutputDir, "SITE_KNOWLEDGE.md"), knowledgeMd, "utf-8");
   }
-  console.log("");
-  console.log("=== Plugin Generated ===");
-  console.log(`  Plugin:     ${finalPluginName}`);
-  console.log(`  Domain:     ${domain}`);
-  console.log(`  Output:     ${finalOutputDir}/index.ts`);
+  process.stdout.write("\n");
+  process.stdout.write("=== Plugin Generated ===\n");
+  process.stdout.write(`  Plugin:     ${finalPluginName}
+`);
+  process.stdout.write(`  Domain:     ${domain}
+`);
+  process.stdout.write(`  Output:     ${finalOutputDir}/index.ts
+`);
   if (knowledgeMd) {
-    console.log(`  Knowledge:  ${finalOutputDir}/SITE_KNOWLEDGE.md`);
+    process.stdout.write(`  Knowledge:  ${finalOutputDir}/SITE_KNOWLEDGE.md
+`);
   }
-  console.log(`  Actions:    ${data.actions.length}`);
-  console.log(`  APIs:       ${data.network.filter((n) => n.contentType.includes("json") || n.url.includes("/api/")).length}`);
-  console.log("");
-  console.log("Next steps:");
-  console.log(`  1. Review and edit:  ${finalOutputDir}/index.ts`);
-  console.log(`  2. Test:             xbrowser ${finalPluginName} <command>`);
-  console.log(`  3. Reference:        ${finalOutputDir}/SITE_KNOWLEDGE.md (for LLM)`);
+  process.stdout.write(`  Actions:    ${data.actions.length}
+`);
+  process.stdout.write(`  APIs:       ${data.network.filter((n) => n.contentType.includes("json") || n.url.includes("/api/")).length}
+`);
+  process.stdout.write("\n");
+  process.stdout.write("Next steps:\n");
+  process.stdout.write(`  1. Review and edit:  ${finalOutputDir}/index.ts
+`);
+  process.stdout.write(`  2. Test:             xbrowser ${finalPluginName} <command>
+`);
+  process.stdout.write(`  3. Reference:        ${finalOutputDir}/SITE_KNOWLEDGE.md (for LLM)
+`);
 }
 function generatePluginCode(pluginName, domain, data, _knowledgeMd) {
   const pagePaths = /* @__PURE__ */ new Set();
@@ -13010,20 +13116,22 @@ async function handleRun(filePath, options) {
   });
   for (const step of chainResult.steps) {
     if (step.success) {
-      console.log(`[OK] ${step.raw}`);
+      process.stdout.write(`[OK] ${step.raw}
+`);
       if (step.data && typeof step.data === "object") {
         const d = step.data;
         for (const [k, v] of Object.entries(d)) {
           if (k !== "ok")
-            console.log(`     ${k}: ${typeof v === "string" ? v : JSON.stringify(v)}`);
+            process.stdout.write(`     ${k}: ${typeof v === "string" ? v : JSON.stringify(v)}
+`);
         }
       }
     } else {
-      console.error(`[FAIL] ${step.raw}: ${step.message}`);
+      outputError(`[FAIL] ${step.raw}: ${step.message}`);
     }
   }
   if (chainResult.stoppedReason) {
-    console.error(`Stopped: ${chainResult.stoppedReason}`);
+    outputError(`Stopped: ${chainResult.stoppedReason}`);
   }
   if (!chainResult.success) process.exit(1);
 }
@@ -13066,26 +13174,29 @@ async function handleNetCommand(args, options, mode, sessionName) {
         if (mode === "json") {
           outputResult(result, mode);
         } else {
-          console.log(`
+          process.stdout.write(`
   Network captures (session: ${netSession})`);
-          console.log(`  Total: ${result.total}, Showing: ${result.captures.length}
+          process.stdout.write(`  Total: ${result.total}, Showing: ${result.captures.length}
 `);
           for (const c of result.captures) {
             const statusColor = c.status < 300 ? "\x1B[32m" : c.status < 400 ? "\x1B[33m" : "\x1B[31m";
             const reset = "\x1B[0m";
-            console.log(`  #${c.id} ${c.method.padEnd(6)} ${statusColor}${c.status}${reset} ${c.resourceType.padEnd(10)} ${c.path}`);
+            process.stdout.write(`  #${c.id} ${c.method.padEnd(6)} ${statusColor}${c.status}${reset} ${c.resourceType.padEnd(10)} ${c.path}
+`);
             if (c.size > 0) {
               const sizeStr = c.size > 1024 ? `${(c.size / 1024).toFixed(1)}KB` : `${c.size}B`;
-              console.log(`         ${c.contentType.split(";")[0]} ${sizeStr}`);
+              process.stdout.write(`         ${c.contentType.split(";")[0]} ${sizeStr}
+`);
             }
           }
-          console.log("");
+          process.stdout.write("\n");
         }
         break;
       }
       case "clear": {
         await forwardNetworkClear(netSession);
-        console.log(`Network captures cleared for session: ${netSession}`);
+        process.stdout.write(`Network captures cleared for session: ${netSession}
+`);
         break;
       }
       case "top": {
@@ -13095,21 +13206,23 @@ async function handleNetCommand(args, options, mode, sessionName) {
         if (mode === "json") {
           outputResult(result, mode);
         } else {
-          console.log(`
+          process.stdout.write(`
   Top valued requests (session: ${netSession})`);
-          console.log(`  Showing: ${result.entries.length}
+          process.stdout.write(`  Showing: ${result.entries.length}
 `);
           for (const e of result.entries) {
             const scoreColor = e.score >= 50 ? "\x1B[32m" : e.score >= 20 ? "\x1B[33m" : "\x1B[90m";
             const reset = "\x1B[0m";
             const methodStr = e.method.padEnd(6);
             const scoreStr = `${scoreColor}${e.score.toString().padStart(3)}${reset}`;
-            console.log(`  ${scoreStr} ${methodStr} ${e.status} ${e.resourceType.padEnd(10)} ${e.path}`);
+            process.stdout.write(`  ${scoreStr} ${methodStr} ${e.status} ${e.resourceType.padEnd(10)} ${e.path}
+`);
             if (e.scoreBreakdown.content > 0) {
-              console.log(`         ${e.contentType.split(";")[0]} ${e.size > 1024 ? (e.size / 1024).toFixed(1) + "KB" : e.size + "B"}`);
+              process.stdout.write(`         ${e.contentType.split(";")[0]} ${e.size > 1024 ? (e.size / 1024).toFixed(1) + "KB" : e.size + "B"}
+`);
             }
           }
-          console.log("");
+          process.stdout.write("\n");
         }
         break;
       }
@@ -13118,16 +13231,17 @@ async function handleNetCommand(args, options, mode, sessionName) {
         if (mode === "json") {
           outputResult(logResult, mode);
         } else {
-          console.log(`
+          process.stdout.write(`
   Command log (session: ${netSession})`);
-          console.log(`  Total: ${logResult.commands.length}
+          process.stdout.write(`  Total: ${logResult.commands.length}
 `);
           for (const cmd of logResult.commands) {
             const ts = new Date(cmd.timestamp).toISOString().substring(11, 19);
             const paramsStr = Object.entries(cmd.params).map(([k, v]) => `${k}=${v}`).join(" ");
-            console.log(`  #${cmd.id} [${ts}] ${cmd.command} ${paramsStr}`);
+            process.stdout.write(`  #${cmd.id} [${ts}] ${cmd.command} ${paramsStr}
+`);
           }
-          console.log("");
+          process.stdout.write("\n");
         }
         break;
       }
@@ -13143,28 +13257,31 @@ async function handleNetCommand(args, options, mode, sessionName) {
           outputResult(aroundResult, mode);
         } else {
           if (!aroundResult) {
-            console.log("  No command found with that ID");
+            process.stdout.write("  No command found with that ID\n");
             break;
           }
           const cmd = aroundResult.command;
           const ts = new Date(cmd.timestamp).toISOString().substring(11, 19);
-          console.log(`
+          process.stdout.write(`
   Command: #${cmd.id} [${ts}] ${cmd.command}`);
-          console.log(`  Window: \xB1${windowMs}ms
+          process.stdout.write(`  Window: \xB1${windowMs}ms
 `);
           const before = aroundResult.before;
           const after = aroundResult.after;
-          console.log(`  BEFORE (${before.length} requests):`);
+          process.stdout.write(`  BEFORE (${before.length} requests):
+`);
           for (const r of before.slice(0, 5)) {
-            console.log(`    ${r.method} ${r.status} ${String(r.resourceType).padEnd(10)} ${r.path}`);
+            process.stdout.write(`    ${r.method} ${r.status} ${String(r.resourceType).padEnd(10)} ${r.path}
+`);
           }
-          console.log(`
+          process.stdout.write(`
   AFTER (${aroundResult.afterCount} requests):`);
           for (const r of after.slice(0, 10)) {
             const highlight = r.method !== "GET" ? " \u2190" : "";
-            console.log(`    ${String(r.method).padEnd(6)} ${r.status} ${String(r.resourceType).padEnd(10)} ${r.path}${highlight}`);
+            process.stdout.write(`    ${String(r.method).padEnd(6)} ${r.status} ${String(r.resourceType).padEnd(10)} ${r.path}${highlight}
+`);
           }
-          console.log("");
+          process.stdout.write("\n");
         }
         break;
       }
@@ -13173,9 +13290,9 @@ async function handleNetCommand(args, options, mode, sessionName) {
         if (mode === "json") {
           outputResult(result, mode);
         } else {
-          console.log(`
+          process.stdout.write(`
   API Reusability Analysis (session: ${netSession})`);
-          console.log(`  Total: ${result.total}, Analyzed: ${result.analyzed.length}
+          process.stdout.write(`  Total: ${result.total}, Analyzed: ${result.analyzed.length}
 `);
           const groups = { high: [], medium: [], low: [], unknown: [] };
           for (const e of result.analyzed) {
@@ -13186,16 +13303,20 @@ async function handleNetCommand(args, options, mode, sessionName) {
             if (!items?.length) continue;
             const color = level === "high" ? "\x1B[32m" : level === "medium" ? "\x1B[33m" : level === "low" ? "\x1B[31m" : "\x1B[90m";
             const reset = "\x1B[0m";
-            console.log(`  ${color}${level.toUpperCase()}${reset} (${items.length})`);
+            process.stdout.write(`  ${color}${level.toUpperCase()}${reset} (${items.length})
+`);
             for (const e of items.slice(0, 5)) {
               const scoreStr = `[${e.reusability.score.toString().padStart(3)}]`;
-              console.log(`    ${e.method.padEnd(6)} ${e.status} ${scoreStr} ${e.path}`);
+              process.stdout.write(`    ${e.method.padEnd(6)} ${e.status} ${scoreStr} ${e.path}
+`);
               if (e.reusability.reasons.length > 0) {
-                console.log(`           ${e.reusability.reasons.join(", ")}`);
+                process.stdout.write(`           ${e.reusability.reasons.join(", ")}
+`);
               }
             }
-            if (items.length > 5) console.log(`    ... and ${items.length - 5} more`);
-            console.log("");
+            if (items.length > 5) process.stdout.write(`    ... and ${items.length - 5} more
+`);
+            process.stdout.write("\n");
           }
         }
         break;
@@ -13214,12 +13335,12 @@ async function handleNetCommand(args, options, mode, sessionName) {
         if (mode === "json") {
           outputResult(result, mode);
         } else {
-          console.log(`
+          process.stdout.write(`
   ${result.method} ${result.url}`);
-          console.log(`  Headers: ${result.headerCount}, Body: ${result.hasBody}
+          process.stdout.write(`  Headers: ${result.headerCount}, Body: ${result.hasBody}
 `);
-          console.log(result.command);
-          console.log("");
+          process.stdout.write(result.command + "\n");
+          process.stdout.write("\n");
         }
         break;
       }
@@ -13237,27 +13358,33 @@ async function handleNetCommand(args, options, mode, sessionName) {
         if (mode === "json") {
           outputResult(result, mode);
         } else {
-          console.log(`
+          process.stdout.write(`
   Replay Result`);
-          console.log(`  ${result.curlCommand?.split("\n")[0]?.trim()}
+          process.stdout.write(`  ${result.curlCommand?.split("\n")[0]?.trim()}
 `);
           const replay = result.replay;
           if (replay?.error) {
-            console.log(`  \x1B[31mFAILED\x1B[0m: ${replay.error}`);
+            process.stdout.write(`  \x1B[31mFAILED\x1B[0m: ${replay.error}
+`);
           } else if (replay) {
             const statusColor = replay.status && replay.status < 300 ? "\x1B[32m" : "\x1B[31m";
             const status = replay.status;
             const size = replay.size;
             const duration = replay.duration;
-            console.log(`  Status: ${statusColor}${status}\x1B[0m ${replay.statusText}`);
-            console.log(`  Size: ${size > 1024 ? (size / 1024).toFixed(1) + "KB" : size + "B"}`);
-            console.log(`  Duration: ${duration}ms`);
-            console.log(`  Body Match: ${replay.bodyMatch ? "\x1B[32mYes\x1B[0m" : "\x1B[33mNo\x1B[0m"}`);
+            process.stdout.write(`  Status: ${statusColor}${status}\x1B[0m ${replay.statusText}
+`);
+            process.stdout.write(`  Size: ${size > 1024 ? (size / 1024).toFixed(1) + "KB" : size + "B"}
+`);
+            process.stdout.write(`  Duration: ${duration}ms
+`);
+            process.stdout.write(`  Body Match: ${replay.bodyMatch ? "\x1B[32mYes\x1B[0m" : "\x1B[33mNo\x1B[0m"}
+`);
             if (status && status >= 400) {
-              console.log(`  \x1B[33m\u26A0 API may require fresh signature/token\x1B[0m`);
+              process.stdout.write(`  \x1B[33m\u26A0 API may require fresh signature/token\x1B[0m
+`);
             }
           }
-          console.log("");
+          process.stdout.write("\n");
         }
         break;
       }
@@ -13276,40 +13403,47 @@ async function handleNetCommand(args, options, mode, sessionName) {
           outputResult(result, mode);
         } else {
           const c = result.capture;
-          console.log(`
+          process.stdout.write(`
   Request #${c.id}`);
-          console.log(`  ${c.method} ${c.url}`);
-          console.log(`  Status: ${c.status} | Size: ${c.size}B | Type: ${c.contentType}`);
-          console.log(`  Resource: ${c.resourceType}`);
+          process.stdout.write(`  ${c.method} ${c.url}
+`);
+          process.stdout.write(`  Status: ${c.status} | Size: ${c.size}B | Type: ${c.contentType}
+`);
+          process.stdout.write(`  Resource: ${c.resourceType}
+`);
           if (c.requestHeaders) {
-            console.log(`
+            process.stdout.write(`
   Request Headers:`);
             for (const [k, v] of Object.entries(c.requestHeaders)) {
-              console.log(`    ${k}: ${String(v).substring(0, 100)}`);
+              process.stdout.write(`    ${k}: ${String(v).substring(0, 100)}
+`);
             }
           }
           if (c.requestBody !== void 0) {
-            console.log(`
+            process.stdout.write(`
   Request Body:`);
             const bodyStr = typeof c.requestBody === "string" ? c.requestBody : JSON.stringify(c.requestBody, null, 2);
             const lines = bodyStr.split("\n").slice(0, 20);
-            for (const line of lines) console.log(`    ${line}`);
-            if (bodyStr.split("\n").length > 20) console.log("    ...");
+            for (const line of lines) process.stdout.write(`    ${line}
+`);
+            if (bodyStr.split("\n").length > 20) process.stdout.write("    ...");
           }
-          console.log(`
+          process.stdout.write(`
   Response Headers:`);
           for (const [k, v] of Object.entries(c.headers)) {
-            console.log(`    ${k}: ${String(v).substring(0, 100)}`);
+            process.stdout.write(`    ${k}: ${String(v).substring(0, 100)}
+`);
           }
           if (c.body !== void 0) {
-            console.log(`
+            process.stdout.write(`
   Response Body:`);
             const bodyStr = typeof c.body === "string" ? c.body : JSON.stringify(c.body, null, 2);
             const lines = bodyStr.split("\n").slice(0, 20);
-            for (const line of lines) console.log(`    ${line}`);
-            if (bodyStr.split("\n").length > 20) console.log("    ...");
+            for (const line of lines) process.stdout.write(`    ${line}
+`);
+            if (bodyStr.split("\n").length > 20) process.stdout.write("    ...");
           }
-          console.log("");
+          process.stdout.write("\n");
         }
         break;
       }
@@ -13320,7 +13454,8 @@ async function handleNetCommand(args, options, mode, sessionName) {
           break;
         }
         await forwardNetworkLike(netSession, id);
-        console.log(`Marked #${id} as useful`);
+        process.stdout.write(`Marked #${id} as useful
+`);
         break;
       }
       case "dislike": {
@@ -13330,7 +13465,8 @@ async function handleNetCommand(args, options, mode, sessionName) {
           break;
         }
         await forwardNetworkDislike(netSession, id);
-        console.log(`Marked #${id} as not useful`);
+        process.stdout.write(`Marked #${id} as not useful
+`);
         break;
       }
       case "export": {
@@ -13345,7 +13481,7 @@ async function handleNetCommand(args, options, mode, sessionName) {
           outputError(result.error);
           break;
         }
-        console.log(result.code);
+        process.stdout.write(result.code + "\n");
         break;
       }
       default:
@@ -13357,9 +13493,25 @@ async function handleNetCommand(args, options, mode, sessionName) {
 }
 
 // src/cli/test-routes.ts
-import { execSync as execSync3 } from "child_process";
+import { execFile as execFile3 } from "child_process";
 import { readFileSync as readFileSync11 } from "fs";
 import { resolve as resolve9 } from "path";
+function execCli(args) {
+  return new Promise((resolvePromise) => {
+    execFile3(
+      "npx",
+      args,
+      { timeout: 65e3, env: { ...process.env, FORCE_COLOR: "0" } },
+      (err, stdout, stderr) => {
+        resolvePromise({
+          stdout: typeof stdout === "string" ? stdout : stdout?.toString("utf-8") ?? "",
+          stderr: typeof stderr === "string" ? stderr : stderr?.toString("utf-8") ?? "",
+          error: err ?? null
+        });
+      }
+    );
+  });
+}
 function findPluginPath(plugin) {
   const candidates = [
     resolve9(process.cwd(), ".xcli/plugins", plugin, "index.ts"),
@@ -13424,20 +13576,21 @@ function extractSchema(plugin, command) {
 }
 async function runTest(plugin, command, cmdArgs, options) {
   const cdp = options.cdp || options.cdpEndpoint || "http://localhost:9221";
-  const argsStr = cmdArgs.filter((a) => !a.startsWith("--cdp")).join(" ");
+  const passthroughArgs = cmdArgs.filter((a) => !a.startsWith("--cdp"));
   const schema = extractSchema(plugin, command);
-  const fullCmd = `npx xbrowser ${plugin} ${command} ${argsStr} --cdp ${cdp} --json --timeout 60000`;
-  let stdout = "";
-  try {
-    stdout = execSync3(fullCmd, {
-      timeout: 65e3,
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-      env: { ...process.env, FORCE_COLOR: "0" }
-    });
-  } catch (e) {
-    const err = e;
-    stdout = err.stdout?.toString() || "";
+  const cliArgs = [
+    "xbrowser",
+    plugin,
+    command,
+    ...passthroughArgs,
+    "--cdp",
+    String(cdp),
+    "--json",
+    "--timeout",
+    "60000"
+  ];
+  const { stdout, stderr, error } = await execCli(cliArgs);
+  if (error) {
     const jsonLine = stdout.split("\n").find((l) => {
       try {
         JSON.parse(l);
@@ -13456,11 +13609,10 @@ async function runTest(plugin, command, cmdArgs, options) {
       } catch {
       }
     }
-    const stderr = err.stderr?.toString() || "";
     if (stdout.includes("captcha") || stderr.includes("captcha") || stdout.includes("CAPTCHA")) {
       return { status: "CAPTCHA", message: "\u68C0\u6D4B\u5230\u9A8C\u8BC1\u7801", viewerUrl: "http://localhost:9224/preview/default" };
     }
-    return { status: "EXEC_ERROR", message: (err.message || "").slice(0, 200) || "\u6267\u884C\u5931\u8D25" };
+    return { status: "EXEC_ERROR", message: (error.message || "").slice(0, 200) || "\u6267\u884C\u5931\u8D25" };
   }
   const allLines = stdout.split("\n");
   const jsonStart = allLines.findIndex((l) => l.trim().startsWith("{"));
@@ -13530,27 +13682,27 @@ async function handleTest(cmdArgs, options, mode, cdpEndpoint) {
   const plugin = cmdArgs[0];
   const command = cmdArgs[1];
   if (!plugin || !command) {
-    console.error("\u7528\u6CD5: xbrowser test <plugin> <command> [\u53C2\u6570...]");
-    console.error("\u793A\u4F8B: xbrowser test doubao list --cdp 9221");
+    outputError("\u7528\u6CD5: xbrowser test <plugin> <command> [\u53C2\u6570...]");
+    outputError("\u793A\u4F8B: xbrowser test doubao list --cdp 9221");
     return;
   }
   const loader = await getPluginLoader();
   const internalLoader = loader.getCore().loader;
   const site = internalLoader.getSite(plugin);
   if (!site) {
-    console.error(`\u63D2\u4EF6 "${plugin}" \u4E0D\u5B58\u5728`);
+    outputError(`\u63D2\u4EF6 "${plugin}" \u4E0D\u5B58\u5728`);
     return;
   }
   const cmdEntry = site.getCommand(command);
   if (!cmdEntry) {
-    console.error(`\u6307\u4EE4 "${command}" \u4E0D\u5B58\u5728`);
+    outputError(`\u6307\u4EE4 "${command}" \u4E0D\u5B58\u5728`);
     return;
   }
   const testArgs = cmdArgs.slice(2);
   const mergedOptions = { ...options, cdp: cdpEndpoint || options.cdp };
   const result = await runTest(plugin, command, testArgs, mergedOptions);
   if (mode === "json") {
-    console.log(JSON.stringify(result, null, 2));
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
     return;
   }
   const r = result;
@@ -13565,23 +13717,32 @@ async function handleTest(cmdArgs, options, mode, cdpEndpoint) {
   };
   const status = String(r.status);
   const icon = icons[status] || "\u2753";
-  console.log(`
-${icon}  ${plugin}.${command}`);
-  console.log(`   \u72B6\u6001: ${status}`);
+  process.stdout.write(`
+${icon}  ${plugin}.${command}
+`);
+  process.stdout.write(`   \u72B6\u6001: ${status}
+`);
   if (status === "OK") {
-    if (r.count) console.log(`   \u6570\u636E: ${r.count} \u9879`);
-    if (r.data) console.log(`   \u9884\u89C8: ${String(r.data).slice(0, 150)}`);
+    if (r.count) process.stdout.write(`   \u6570\u636E: ${r.count} \u9879
+`);
+    if (r.data) process.stdout.write(`   \u9884\u89C8: ${String(r.data).slice(0, 150)}
+`);
   } else if (status === "LOGIN_REQUIRED" || status === "CAPTCHA") {
-    console.log(`   \u4FE1\u606F: ${String(r.message)}`);
-    console.log(`   Viewer: ${String(r.viewerUrl)}`);
+    process.stdout.write(`   \u4FE1\u606F: ${String(r.message)}
+`);
+    process.stdout.write(`   Viewer: ${String(r.viewerUrl)}`);
   } else if (status === "SCHEMA_ERROR") {
     const errs = r.errors;
-    if (errs) console.log(`   \u9519\u8BEF: ${errs.join("; ")}`);
+    if (errs) process.stdout.write(`   \u9519\u8BEF: ${errs.join("; ")}
+`);
   } else if (["NO_DATA", "BLOCKED"].includes(status)) {
-    console.log(`   \u4FE1\u606F: ${String(r.message)}`);
-    if (r.viewerUrl) console.log(`   Viewer: ${String(r.viewerUrl)}`);
+    process.stdout.write(`   \u4FE1\u606F: ${String(r.message)}
+`);
+    if (r.viewerUrl) process.stdout.write(`   Viewer: ${String(r.viewerUrl)}
+`);
   } else {
-    console.log(`   \u4FE1\u606F: ${String(r.message)}`);
+    process.stdout.write(`   \u4FE1\u606F: ${String(r.message)}
+`);
   }
 }
 
@@ -13679,7 +13840,7 @@ Commands:
   plugin list                       List plugins
   plugin reload <name>              Reload plugin
   create <name> --template <type>   Create plugin
-  serve [--port <port>] [--token <t>] Start HTTP server
+  serve [--port <p>] [--host <h>] [--token <t>] [--cors-origins <csv>] Start HTTP server (loopback by default)
   remote <url> [command] [--token <t>] Execute on remote server
   run <file>                        Execute commands from file
   viewer [--name <n>]               Generate viewer URL
@@ -13800,10 +13961,26 @@ function validateAuth(authHeader, validTokens) {
 function isAuthRequired(validTokens) {
   return validTokens.length > 0;
 }
+var IPV6_LOOPBACK = /* @__PURE__ */ new Set(["::1", "0:0:0:0:0:0:0:1"]);
+function isLoopbackHost(host) {
+  const h = host.trim().toLowerCase().replace(/^\[/, "").replace(/\]$/, "");
+  if (h === "localhost") return true;
+  if (IPV6_LOOPBACK.has(h)) return true;
+  const ipv4 = h.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  return ipv4 !== null && ipv4[1] === "127";
+}
+function isLoopbackOrigin(origin) {
+  try {
+    const url = new URL(origin);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+    return isLoopbackHost(url.hostname);
+  } catch {
+    return false;
+  }
+}
 
 // src/server/router.ts
-var CORS_HEADERS = {
-  "Access-Control-Allow-Origin": "*",
+var CORS_BASE_HEADERS = {
   "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
   "Access-Control-Allow-Headers": "Content-Type, Authorization"
 };
@@ -13856,9 +14033,31 @@ function jsonResponse(statusCode, body, extraHeaders) {
   return {
     statusCode,
     body,
-    headers: { ...CORS_HEADERS, "Content-Type": "application/json", ...extraHeaders }
+    headers: { "Content-Type": "application/json", ...extraHeaders }
   };
 }
+function corsHeadersFor(origin, explicitOrigins) {
+  if (!origin || !isOriginAllowed(origin, explicitOrigins)) return {};
+  return {
+    "Access-Control-Allow-Origin": origin,
+    Vary: "Origin",
+    ...CORS_BASE_HEADERS
+  };
+}
+function isOriginAllowed(origin, explicitOrigins) {
+  if (explicitOrigins && explicitOrigins.length > 0) {
+    return explicitOrigins.includes("*") || explicitOrigins.includes(origin);
+  }
+  return isLoopbackOrigin(origin);
+}
+function isJsonContentType(contentType) {
+  return contentType.toLowerCase().split(";")[0].trim() === "application/json";
+}
+function applyCorsHeaders(response, origin, corsOrigins) {
+  const cors = corsHeadersFor(origin, corsOrigins);
+  if (Object.keys(cors).length === 0) return response;
+  return { ...response, headers: { ...cors, ...response.headers ?? {} } };
+}
 function errorResponse(statusCode, error, message) {
   return jsonResponse(statusCode, { error, message, statusCode });
 }
@@ -13976,13 +14175,30 @@ async function ensureSession(sessionName, url, cdpEndpoint) {
 function isHealthCheckPath(pathname) {
   return pathname === "/api/v1/health";
 }
-async function route(method, url, headers, body) {
+async function route(method, url, headers, body, corsOrigins) {
+  const response = await routeInner(method, url, headers, body, corsOrigins);
+  return applyCorsHeaders(response, headers.origin, corsOrigins);
+}
+async function routeInner(method, url, headers, body, corsOrigins) {
   const parsedUrl = new URL(url, "http://localhost");
   const pathname = parsedUrl.pathname;
   const query = parseQueryString(parsedUrl.search);
   if (method === "OPTIONS") {
     return jsonResponse(204, null);
   }
+  if (headers.origin && !isOriginAllowed(headers.origin, corsOrigins)) {
+    return errorResponse(403, "FORBIDDEN", `Origin ${headers.origin} is not allowed to call this API`);
+  }
+  if (method === "POST" || method === "PUT") {
+    const contentType = headers["content-type"];
+    if (contentType && !isJsonContentType(contentType)) {
+      return errorResponse(
+        415,
+        "UNSUPPORTED_MEDIA_TYPE",
+        `Content-Type must be application/json, got "${contentType}"`
+      );
+    }
+  }
   const match = matchRoute(method, pathname);
   if (!match) {
     const pathMatch = matchRoute("GET", pathname) || matchRoute("POST", pathname) || matchRoute("DELETE", pathname);
@@ -14005,19 +14221,24 @@ async function route(method, url, headers, body) {
     return errorResponse(500, "INTERNAL_ERROR", errMsg(err));
   }
 }
-async function handleRequest(req, res, validateAuthFn) {
+async function handleRequest(req, res, validateAuthFn, corsOrigins) {
   const url = req.url || "/";
   const method = (req.method || "GET").toUpperCase();
   const pathname = new URL(url, "http://localhost").pathname;
   if (method === "OPTIONS") {
-    const response2 = await route(method, url, headersToObject(req.headers), null);
+    const response2 = await route(method, url, headersToObject(req.headers), null, corsOrigins);
     writeResponse(res, response2);
     return;
   }
   if (validateAuthFn && !isHealthCheckPath(pathname)) {
     const authHeader = req.headers["authorization"];
     if (!validateAuthFn(authHeader)) {
-      writeResponse(res, errorResponse(401, "UNAUTHORIZED", "Invalid or missing authentication token"));
+      const denied = applyCorsHeaders(
+        errorResponse(401, "UNAUTHORIZED", "Invalid or missing authentication token"),
+        req.headers.origin,
+        corsOrigins
+      );
+      writeResponse(res, denied);
       return;
     }
   }
@@ -14025,7 +14246,7 @@ async function handleRequest(req, res, validateAuthFn) {
   if (method === "POST" || method === "PUT") {
     body = await readBody(req);
   }
-  const response = await route(method, url, headersToObject(req.headers), body);
+  const response = await route(method, url, headersToObject(req.headers), body, corsOrigins);
   writeResponse(res, response);
 }
 function headersToObject(headers) {
@@ -14066,26 +14287,35 @@ var HTTPServer = class {
   host;
   server = null;
   validTokens;
+  corsOrigins;
   constructor(config) {
     this.port = config?.port ?? 9224;
-    this.host = config?.host ?? "0.0.0.0";
+    this.host = config?.host ?? "127.0.0.1";
     this.validTokens = resolveTokens(config?.tokens);
+    this.corsOrigins = config?.corsOrigins;
   }
   /**
    * Start the HTTP server and begin listening for requests.
    *
    * @returns The actual port and host the server bound to.
-   * @throws If the server is already running or fails to start.
+   * @throws If the server is already running, if binding a non-loopback
+   *   host without an auth token, or if the port cannot be bound.
    */
   async start() {
     if (this.server) {
       throw new Error("HTTP server is already running");
     }
+    if (!isLoopbackHost(this.host) && !isAuthRequired(this.validTokens)) {
+      throw new Error(
+        `Refusing to start on non-loopback host "${this.host}" without an auth token \u2014 the API exposes session creation and command execution. Bind loopback only (the default, or --host 127.0.0.1), or provide a token via --token or XBROWSER_SERVER_TOKEN.`
+      );
+    }
     const authRequired = isAuthRequired(this.validTokens);
     const tokens = this.validTokens;
+    const corsOrigins = this.corsOrigins;
     this.server = createServer((req, res) => {
       const authFn = authRequired ? (authHeader) => validateAuth(authHeader, tokens) : void 0;
-      handleRequest(req, res, authFn).catch((err) => {
+      handleRequest(req, res, authFn, corsOrigins).catch((err) => {
         const message = err instanceof Error ? err.message : String(err);
         if (!res.headersSent) {
           res.writeHead(500, { "Content-Type": "application/json" });
@@ -14556,7 +14786,7 @@ async function routeCommand(argvIn, stdinCommands) {
       replay: "replay <file> [--slow-mo <ms>] [--stop-on-error]",
       create: "create <name> [--template static|dynamic|login|api]",
       run: "run <file>",
-      serve: "serve [--port <port>] [--token <token>]",
+      serve: "serve [--port <port>] [--host <host>] [--token <token>] [--cors-origins <csv>]",
       remote: "remote <url> [command] [--token <token>]",
       convert: "convert <file> [--to js|py|sh]",
       extract: "extract <file> [--format json|yaml]",
@@ -14955,7 +15185,10 @@ Run "xbrowser ${command} ${subCommand} --help" to see available parameters.`
 async function handleServe(_args, options, mode) {
   const port = options.port ? Number(options.port) : void 0;
   const token = options.token;
-  const httpServer = new HTTPServer({ port, tokens: token ? [token] : void 0 });
+  const host = options.host;
+  const corsOriginsRaw = options["cors-origins"];
+  const corsOrigins = corsOriginsRaw ? corsOriginsRaw.split(",").map((s) => s.trim()).filter(Boolean) : void 0;
+  const httpServer = new HTTPServer({ port, host, tokens: token ? [token] : void 0, corsOrigins });
   process.on("SIGINT", async () => {
     await httpServer.stop();
     return;