@xbrowser/cli 1.8.5 → 1.8.7

package/dist/index.js

@@ -57,7 +57,7 @@ import {
 } from "./chunk-GJAV3QGG.js";
 import {
   SessionRecorder
-} from "./chunk-XU5WOJIV.js";
+} from "./chunk-RMYEHTLS.js";
 import {
   addKnownIssue,
   getKnowledgePath,
@@ -82,7 +82,7 @@ import {
   resolveLaunchOpts,
   saveSessionDiskMeta,
   setActivePage
-} from "./chunk-7EOQV6ZW.js";
+} from "./chunk-CJJ564VK.js";
 import "./chunk-VJNMAWPZ.js";
 import "./chunk-TNEN6VQ2.js";
 import {
@@ -109,7 +109,7 @@ import {
 // src/executor.ts
 import {
   ok as ok25,
-  fail as fail8,
+  fail as fail9,
   isCommandResult,
   CompositeStorage as CompositeStorage2,
   TipCollector as TipCollector2,
@@ -2356,7 +2356,7 @@ var scrapeCommand = registerCommand({
   scope: "project",
   selectorParams: ["selector"],
   parameters: z15.object({
-    url: z15.string(),
+    url: z15.string().optional(),
     selector: z15.string().optional(),
     timeout: z15.number().default(3e4),
     format: z15.enum(["markdown", "html", "text"]).default("markdown"),
@@ -2369,10 +2369,14 @@ var scrapeCommand = registerCommand({
     const { context, page } = await createEphemeralContext(resolveLaunchOpts(ctx));
     const maxAttempts = p.retries + 1;
     try {
+      const targetUrl = p.url || page.url();
+      if (!targetUrl || targetUrl === "about:blank") {
+        return fail3("URL is required. Provide a URL or connect to a browser (--cdp) with a non-blank page.");
+      }
       let lastError;
       for (let attempt = 1; attempt <= maxAttempts; attempt++) {
         try {
-          await page.goto(p.url, { waitUntil: "commit", timeout: p.timeout });
+          await page.goto(targetUrl, { waitUntil: "commit", timeout: p.timeout });
           await page.waitForSelector("body", { timeout: p.timeout }).catch(() => {
           });
           await page.waitForLoadState("networkidle", Math.min(p.timeout, 8e3)).catch(() => {
@@ -2433,7 +2437,7 @@ var scrapeCommand = registerCommand({
               return { url: location.href, title: document.title, navigation, tables, forms: forms.slice(0, 20), links: links.slice(0, 30), mainText };
             });
             try {
-              persistFromScrape(p.url, structured);
+              persistFromScrape(targetUrl, structured);
             } catch {
             }
             if (p.mode === "smart") {
@@ -2534,7 +2538,7 @@ var scrapeCommand = registerCommand({
 
 // src/commands/map.ts
 import { z as z16 } from "zod";
-import { ok as ok16 } from "@dyyz1993/xcli-core";
+import { ok as ok16, fail as fail4 } from "@dyyz1993/xcli-core";
 
 // src/utils/url.ts
 var SKIP_EXTENSIONS = /* @__PURE__ */ new Set([
@@ -2770,7 +2774,7 @@ var mapCommand = registerCommand({
   description: "Discover all URLs on a website via sitemap and page link extraction",
   scope: "project",
   parameters: z16.object({
-    url: z16.string(),
+    url: z16.string().optional(),
     search: z16.string().optional(),
     sitemap: z16.enum(["include", "only"]).optional(),
     includeSubdomains: z16.boolean().optional(),
@@ -2781,7 +2785,11 @@ var mapCommand = registerCommand({
   handler: async (p, ctx) => {
     const { context, page } = await createEphemeralContext(resolveLaunchOpts(ctx));
     try {
-      const links = await discoverUrls(page, p.url, {
+      const targetUrl = p.url || page.url();
+      if (!targetUrl || targetUrl === "about:blank") {
+        return fail4("URL is required. Provide a URL or connect to a browser (--cdp) with a non-blank page.");
+      }
+      const links = await discoverUrls(page, targetUrl, {
         sitemap: p.sitemap,
         includeSubdomains: p.includeSubdomains,
         allowExternalLinks: p.allowExternalLinks,
@@ -3624,7 +3632,7 @@ ${errors.map((e) => `  - ${e.engine}: ${e.error}`).join("\n")}`
 
 // src/commands/network.ts
 import { z as z19 } from "zod";
-import { ok as ok19, fail as fail4 } from "@dyyz1993/xcli-core";
+import { ok as ok19, fail as fail5 } from "@dyyz1993/xcli-core";
 function extractPath2(url) {
   try {
     const u = new URL(url);
@@ -3789,7 +3797,7 @@ var networkCommand = registerCommand({
     };
     if (p.listen) {
       const page2 = ctx.page;
-      if (!page2) return fail4("No active page. Use --cdp to connect first.");
+      if (!page2) return fail5("No active page. Use --cdp to connect first.");
       const captures = [];
       const consoleMessages = [];
       const wsCaptures = [];
@@ -4446,7 +4454,7 @@ function parseMarkdownResults(rawText) {
 
 // src/commands/snapshot.ts
 import { z as z21 } from "zod";
-import { ok as ok20, fail as fail5, normalizeTips as normalizeTips3 } from "@dyyz1993/xcli-core";
+import { ok as ok20, fail as fail6, normalizeTips as normalizeTips3 } from "@dyyz1993/xcli-core";
 
 // src/runtime/ref-store.ts
 var sessions = /* @__PURE__ */ new Map();
@@ -5417,7 +5425,7 @@ var snapshotCommand = registerCommand({
       persistSemantics(url, aria);
       return ok20({ url, title, aria, text, dom }, normalizeTips3(tips));
     }
-    return fail5(`Unknown snapshot type: ${p.type}`);
+    return fail6(`Unknown snapshot type: ${p.type}`);
   }
 });
 function persistSemantics(url, aria) {
@@ -5586,7 +5594,7 @@ var waitForCommand = registerCommand({
 
 // src/commands/tab.ts
 import { z as z23 } from "zod";
-import { ok as ok22, fail as fail6 } from "@dyyz1993/xcli-core";
+import { ok as ok22, fail as fail7 } from "@dyyz1993/xcli-core";
 var TabParams = z23.object({
   subcommand: z23.enum(["list", "new", "close", "switch"]),
   url: z23.string().optional(),
@@ -5603,7 +5611,7 @@ var tabCommand = registerCommand({
   }),
   handler: async (p, ctx) => {
     if (!ctx.browserContext) {
-      return fail6("No browser context available. Use --cdp to connect to a browser first.");
+      return fail7("No browser context available. Use --cdp to connect to a browser first.");
     }
     const pages = ctx.browserContext.pages();
     switch (p.subcommand) {
@@ -5616,7 +5624,7 @@ var tabCommand = registerCommand({
       case "switch":
         return handleSwitch(p, pages, ctx);
       default:
-        return fail6(`Unknown subcommand: ${p.subcommand}`);
+        return fail7(`Unknown subcommand: ${p.subcommand}`);
     }
   }
 });
@@ -5673,11 +5681,11 @@ async function handleNew(p, _pages, ctx) {
 }
 async function handleClose(p, pages, ctx) {
   if (pages.length <= 1) {
-    return fail6("Cannot close the last remaining tab");
+    return fail7("Cannot close the last remaining tab");
   }
   const closeIndex = p.index ?? pages.indexOf(ctx.page);
   if (closeIndex < 0 || closeIndex >= pages.length) {
-    return fail6(`Invalid tab index: ${closeIndex}. Valid range: 0-${pages.length - 1}`);
+    return fail7(`Invalid tab index: ${closeIndex}. Valid range: 0-${pages.length - 1}`);
   }
   const pageToClose = pages[closeIndex];
   const isActivePage = pageToClose === ctx.page;
@@ -5700,10 +5708,10 @@ async function handleClose(p, pages, ctx) {
 }
 async function handleSwitch(p, pages, ctx) {
   if (p.index === void 0) {
-    return fail6("Parameter --index is required for switch subcommand");
+    return fail7("Parameter --index is required for switch subcommand");
   }
   if (p.index < 0 || p.index >= pages.length) {
-    return fail6(`Invalid tab index: ${p.index}. Valid range: 0-${pages.length - 1}`);
+    return fail7(`Invalid tab index: ${p.index}. Valid range: 0-${pages.length - 1}`);
   }
   const targetPage = pages[p.index];
   await targetPage.bringToFront().catch(() => {
@@ -5955,7 +5963,7 @@ registerCommandDefinition("addinitscript", ["script"]);
 
 // src/commands/find.ts
 import { z as z25 } from "zod";
-import { ok as ok24, fail as fail7, normalizeTips as normalizeTips5 } from "@dyyz1993/xcli-core";
+import { ok as ok24, fail as fail8, normalizeTips as normalizeTips5 } from "@dyyz1993/xcli-core";
 var actionSchema2 = z25.enum(["click", "fill", "type", "select", "hover", "check"]);
 var findCommand = registerCommand({
   name: "find",
@@ -5996,7 +6004,7 @@ var findCommand = registerCommand({
     });
     const count = await locator.count();
     if (count === 0) {
-      return fail7(`No element found with ${p.strategy}="${p.value}"`);
+      return fail8(`No element found with ${p.strategy}="${p.value}"`);
     }
     const tips = [];
     const target = selectTarget(locator, p.strategy);
@@ -6008,15 +6016,15 @@ var findCommand = registerCommand({
       await target.click({ timeout: p.timeout, force: true });
       return okWithTips({ matched: count, selector, action: "click" }, tips);
     } else if (actionName === "fill") {
-      if (actionValue === void 0) return fail7("find fill requires a value");
+      if (actionValue === void 0) return fail8("find fill requires a value");
       await target.fill(actionValue, { timeout: p.timeout, force: true });
       return okWithTips({ matched: count, selector, action: `fill("${actionValue}")` }, tips);
     } else if (actionName === "type") {
-      if (actionValue === void 0) return fail7("find type requires a value");
+      if (actionValue === void 0) return fail8("find type requires a value");
       await target.type(actionValue, { delay: 10, timeout: p.timeout });
       return okWithTips({ matched: count, selector, action: `type("${actionValue}")` }, tips);
     } else if (actionName === "select") {
-      if (actionValue === void 0) return fail7("find select requires a value");
+      if (actionValue === void 0) return fail8("find select requires a value");
       await target.selectOption(actionValue);
       return okWithTips({ matched: count, selector, action: `select("${actionValue}")` }, tips);
     } else if (actionName === "hover") {
@@ -7452,7 +7460,7 @@ async function guardCheck(commandName) {
   }
 }
 function errorResult(message) {
-  return { ...fail8(message), duration: 0 };
+  return { ...fail9(message), duration: 0 };
 }
 function tipsToMessages(tips) {
   if (!tips || tips.length === 0) return [];
@@ -7525,9 +7533,14 @@ async function executeCommand(commandName, params, sessionName = "default", extr
     const { _target: _u, ...rest } = params;
     params = rest;
   }
+  const _tabIndex = params._tabIndex;
+  if (_tabIndex !== void 0) {
+    const { _tabIndex: _u, ...rest } = params;
+    params = rest;
+  }
   let targetPageOverride = null;
   if (_target && extraOpts?.cdpEndpoint) {
-    const { findTargetPage } = await import("./browser-PTELW3WS.js");
+    const { findTargetPage } = await import("./browser-TLIDFFEG.js");
     targetPageOverride = await findTargetPage(extraOpts.cdpEndpoint, _target);
     if (!targetPageOverride) {
       return errorResult(`Target "${_target}" not found. Use 'xbrowser targets --cdp ${extraOpts.cdpEndpoint}' to list available pages.`);
@@ -7599,6 +7612,16 @@ async function executeCommand(commandName, params, sessionName = "default", extr
     cliName: "xbrowser",
     tips: new TipCollector2()
   };
+  if (_tabIndex !== void 0 && session?.context) {
+    const pages = session.context.pages();
+    if (_tabIndex >= 0 && _tabIndex < pages.length) {
+      const targetPage = pages[_tabIndex];
+      await targetPage.bringToFront().catch(() => {
+      });
+      setActivePage(session, targetPage);
+      ctx.page = targetPage;
+    }
+  }
   const start = Date.now();
   if (session) {
     streamCommandEvent(session.id, {
@@ -7627,7 +7650,17 @@ async function executeCommand(commandName, params, sessionName = "default", extr
     if (hooks.length > 0 && session?.page) {
       await Promise.all(hooks.map((h) => h.onBeforeCommand?.({ page: session.page, command: commandName, params })));
     }
-    const raw = await command.handler(params, ctx);
+    let raw;
+    const handlerPromise = command.handler(params, ctx);
+    if (extraOpts?.timeout && extraOpts.timeout > 0) {
+      const timeoutMs = extraOpts.timeout;
+      const timeoutPromise = new Promise(
+        (_, reject) => setTimeout(() => reject(new Error(`Command timed out after ${timeoutMs}ms`)), timeoutMs)
+      );
+      raw = await Promise.race([handlerPromise, timeoutPromise]);
+    } else {
+      raw = await handlerPromise;
+    }
     const end = Date.now();
     const duration = end - start;
     let hookOutputs;
@@ -7731,7 +7764,7 @@ async function executeCommand(commandName, params, sessionName = "default", extr
       duration,
       timestamp: start
     });
-    return { ...fail8(errorMessage), duration };
+    return { ...fail9(errorMessage), duration };
   } finally {
   }
 }
@@ -7772,7 +7805,7 @@ async function executeChain(input, options) {
             results.push({
               command: cmdName,
               raw: cmdStr,
-              ...fail8(`Plugin "${cmdName}" requires a sub-command`),
+              ...fail9(`Plugin "${cmdName}" requires a sub-command`),
               duration: 0
             });
             if (type === "and") {
@@ -7791,7 +7824,7 @@ async function executeChain(input, options) {
             results.push({
               command: cmdName,
               raw: cmdStr,
-              ...fail8(`Unknown command "${subCommand}" for plugin "${cmdName}"`),
+              ...fail9(`Unknown command "${subCommand}" for plugin "${cmdName}"`),
               duration: 0
             });
             if (type === "and") {
@@ -7923,7 +7956,7 @@ async function executeChain(input, options) {
             results.push({
               command: `${cmdName} ${subCommand}`,
               raw: cmdStr,
-              ...fail8(errorMessage),
+              ...fail9(errorMessage),
               duration: duration2
             });
             if (type === "and") {
@@ -8201,16 +8234,29 @@ var configBuiltin = {
   execute: async (args, _options, _ctx) => {
     const [subcommand, ...rest] = args;
     if (!subcommand || subcommand === "list") {
+      let flatten2 = function(obj, prefix = "") {
+        const entries2 = [];
+        for (const [k, v] of Object.entries(obj)) {
+          const fullKey = prefix ? `${prefix}.${k}` : k;
+          if (v && typeof v === "object" && !Array.isArray(v)) {
+            entries2.push(...flatten2(v, fullKey));
+          } else {
+            entries2.push({ key: fullKey, value: v });
+          }
+        }
+        return entries2;
+      };
+      var flatten = flatten2;
       const config = loadConfig();
-      const keys = Object.keys(config);
-      if (keys.length === 0) {
+      const entries = flatten2(config);
+      if (entries.length === 0) {
         console.log("Configuration is empty");
         return;
       }
       console.log("Configuration:");
       console.log("");
-      for (const k of keys) {
-        console.log(`  ${k} = ${config[k]}`);
+      for (const { key, value } of entries) {
+        console.log(`  ${key} = ${value}`);
       }
       return;
     }
@@ -9009,6 +9055,39 @@ function outputError(message) {
   console.error(formatted);
   process.exit(1);
 }
+function outputEnvelope(result, meta, mode) {
+  if (mode !== "json" && mode !== "yaml") {
+    if (!result.success) {
+      outputError(result.message || "Unknown error");
+      return;
+    }
+    outputResult(result.data, mode);
+    return;
+  }
+  const { command, ...extraMeta } = meta;
+  const commandResult = {
+    success: result.success,
+    data: result.data,
+    message: result.message,
+    tips: [],
+    meta: {
+      duration: result.duration ?? 0,
+      ...extraMeta
+    }
+  };
+  const formatted = outputFormatter.formatEnvelope(commandResult, {
+    command,
+    extraMeta,
+    mode
+  });
+  console.log(formatted);
+  if (result.tips?.length) {
+    for (const tip of result.tips) {
+      const text = typeof tip === "string" ? tip : tip.message;
+      if (text) console.error(`  \u{1F4A1} ${text}`);
+    }
+  }
+}
 
 // src/builtins/plugin.ts
 var pluginLoader2 = null;
@@ -10573,9 +10652,13 @@ async function handleBrowserCommand(command, args, options, sessionName, mode, c
   if (target) {
     params = { ...params, _target: target };
   }
+  const tabIndex = options.tab;
+  if (tabIndex !== void 0) {
+    params = { ...params, _tabIndex: Number(tabIndex) };
+  }
   const result = cdpEndpoint ? await executeCommand(cmdName, params, sessionName, { cdpEndpoint }) : await executeCommand(cmdName, params, sessionName);
   if (mode === "json" || mode === "yaml") {
-    outputResult(result, mode);
+    outputEnvelope(result, { command: cmdName }, mode);
   } else if (!result.success) {
     outputError(result.message || "Command failed");
   } else {
@@ -10635,7 +10718,7 @@ async function handleSession(args, options, mode, _cdpEndpoint) {
           }
         } catch {
         }
-        outputResult({ ok: true, closed: count, all: true }, mode);
+        outputEnvelope({ success: true, data: { closed: count, all: true } }, { command: "session close" }, mode);
       } else {
         const name = options.session || options.name || process.env.XBROWSER_SESSION || "default";
         try {
@@ -10643,7 +10726,7 @@ async function handleSession(args, options, mode, _cdpEndpoint) {
         } catch {
         }
         await closeSession(name);
-        outputResult({ ok: true, name }, mode);
+        outputEnvelope({ success: true, data: { name } }, { command: "session close" }, mode);
       }
       break;
     }
@@ -10651,10 +10734,10 @@ async function handleSession(args, options, mode, _cdpEndpoint) {
     case "ls": {
       try {
         const sessions2 = await forwardSessionList();
-        outputResult({ sessions: sessions2 }, mode);
+        outputEnvelope({ success: true, data: { sessions: sessions2 } }, { command: "session list" }, mode);
       } catch {
         const sessions2 = await listSessions();
-        outputResult({ sessions: sessions2 }, mode);
+        outputEnvelope({ success: true, data: { sessions: sessions2 } }, { command: "session list" }, mode);
       }
       break;
     }
@@ -10669,7 +10752,7 @@ async function handleSession(args, options, mode, _cdpEndpoint) {
         await stopDaemonProcess();
       } catch {
       }
-      outputResult({ ok: true, name, killed: true, daemon: "stopped" }, mode);
+      outputEnvelope({ success: true, data: { name, killed: true, daemon: "stopped" } }, { command: "session kill" }, mode);
       break;
     }
     case "kill-all": {
@@ -10688,7 +10771,7 @@ async function handleSession(args, options, mode, _cdpEndpoint) {
       } catch {
       }
       const cleaned = cleanSessionFiles();
-      outputResult({ ok: true, sessionsCleaned: cleaned, daemon: "killed" }, mode);
+      outputEnvelope({ success: true, data: { sessionsCleaned: cleaned, daemon: "killed" } }, { command: "session kill-all" }, mode);
       break;
     }
     default:
@@ -10808,7 +10891,7 @@ async function handleSearch(args, options, mode) {
     }
   }
   if (mode === "json") {
-    outputResult({ results, total: results.length }, mode);
+    outputEnvelope({ success: true, data: { results, total: results.length } }, { command: "plugin search" }, mode);
   } else {
     if (results.length === 0) {
       console.log("No plugins found");
@@ -10837,7 +10920,7 @@ async function handlePluginInfo(args, options, mode) {
     if (pluginInfo) {
       const d = pluginInfo;
       if (mode === "json") {
-        outputResult({ source: "marketplace", ...d }, mode);
+        outputEnvelope({ success: true, data: { source: "marketplace", ...d } }, { command: "plugin info" }, mode);
         return;
       }
       console.log(`\u540D\u79F0: ${d.name || ""}`);
@@ -10863,7 +10946,7 @@ async function handlePluginInfo(args, options, mode) {
       const pkg = latest && versions?.[latest];
       if (pkg) {
         if (mode === "json") {
-          outputResult({ source: "npm", name: pkg.name, version: latest, description: pkg.description }, 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 || ""}`);
@@ -10892,7 +10975,7 @@ async function handlePluginSchema(args, mode) {
     return;
   }
   if (mode === "json") {
-    outputResult(contract, mode);
+    outputEnvelope({ success: true, data: contract }, { command: "plugin schema" }, mode);
     return;
   }
   if ("commands" in contract) {
@@ -10970,8 +11053,9 @@ async function handlePlugin(args, options, mode) {
         }
       } catch {
       }
-      outputResult(
-        { ok: true, name: result.name, source: result.source, path: result.path },
+      outputEnvelope(
+        { success: true, data: { name: result.name, source: result.source, path: result.path } },
+        { command: "plugin install" },
         mode
       );
       break;
@@ -10990,7 +11074,7 @@ async function handlePlugin(args, options, mode) {
         await loader.reloadPlugin(name);
       } catch {
       }
-      outputResult({ ok: true, name }, mode);
+      outputEnvelope({ success: true, data: { name } }, { command: "plugin uninstall" }, mode);
       break;
     }
     case "list": {
@@ -11012,7 +11096,7 @@ async function handlePlugin(args, options, mode) {
         };
       });
       if (mode === "json") {
-        outputResult({ plugins: enrichedPlugins }, mode);
+        outputEnvelope({ success: true, data: { plugins: enrichedPlugins } }, { command: "plugin list" }, mode);
       } else {
         if (enrichedPlugins.length === 0) {
           console.log("No plugins installed");
@@ -11048,7 +11132,7 @@ Total: ${enrichedPlugins.length} plugins`);
       } catch {
         outputError(`Plugin "${name}" not found. Use 'xbrowser plugin list' to see installed plugins.`);
       }
-      outputResult({ ok: true, name }, mode);
+      outputEnvelope({ success: true, data: { name } }, { command: "plugin reload" }, mode);
       break;
     }
     case "search":
@@ -11080,24 +11164,22 @@ function handleDaemon(args, options, mode) {
     case "start": {
       const port = options.port ? Number(options.port) : 9224;
       startDaemonProcess(port).then(
-        (config) => outputResult({ ok: true, pid: config.pid, port: config.port }, mode)
+        (config) => outputEnvelope({ success: true, data: { pid: config.pid, port: config.port } }, { command: "daemon start" }, mode)
       ).catch(
         (e) => outputError(e instanceof Error ? e.message : String(e))
       );
       break;
     }
     case "stop": {
-      stopDaemonProcess().then(() => outputResult({ ok: true }, mode)).catch(
+      stopDaemonProcess().then(() => outputEnvelope({ success: true, data: {} }, { command: "daemon stop" }, mode)).catch(
         (e) => outputError(e instanceof Error ? e.message : String(e))
       );
       break;
     }
     case "status": {
       const status = getDaemonProcessStatus();
-      outputResult(
-        status.running ? { running: true, pid: status.pid, port: status.port } : { running: false },
-        mode
-      );
+      const statusData = status.running ? { running: true, pid: status.pid, port: status.port } : { running: false };
+      outputEnvelope({ success: true, data: statusData }, { command: "daemon status" }, mode);
       break;
     }
     default:
@@ -11475,7 +11557,7 @@ async function handleFilter(args, _mode, options) {
   console.log(`  Original: ${result.originalCount}, After: ${result.filteredCount}, Removed: ${result.removed} (${result.percentage}%)`);
 }
 async function handleGeneratePlugin(sessionName, pluginName, outputDir) {
-  const { SessionRecorder: SessionRecorder2 } = await import("./session-recorder-H2WPBCSW.js");
+  const { SessionRecorder: SessionRecorder2 } = await import("./session-recorder-33UKWCIR.js");
   const { readSiteKnowledge: readSiteKnowledge2, toMarkdown } = await import("./site-knowledge-SYC6VCDB.js");
   const { mkdirSync: mkdirSync11, writeFileSync: writeFileSync13 } = await import("fs");
   const { join: join14 } = await import("path");
@@ -12822,7 +12904,8 @@ var KNOWN_GLOBAL_OPTIONS = /* @__PURE__ */ new Set([
   "port",
   "token",
   "timeout",
-  "headless"
+  "headless",
+  "tab"
 ]);
 function showCommandHelp(siteName, cmd, siteConfig, mode) {
   const c = cmd;
@@ -12976,20 +13059,28 @@ async function handleEvalMode(argv) {
 }
 async function handleChainInput(input, argv) {
   const cdpEndpoint = argv ? extractCdpFromArgv(argv) : void 0;
-  const jsonMode = argv ? argv.some((a) => a === "--json" || a.startsWith("--json=") || a.includes(" --json") || a.startsWith("--json")) || argv.includes("-j") : false;
+  const hasJson = argv ? argv.some((a) => a === "--json" || a.startsWith("--json=") || a.includes(" --json") || a.startsWith("--json")) || argv.includes("-j") : false;
+  const hasYaml = argv ? argv.some((a) => a === "--yaml" || a.startsWith("--yaml=")) : false;
+  const mode = hasJson ? "json" : hasYaml ? "yaml" : "text";
   const chainResult = await executeChain(input, { cdpEndpoint });
-  if (jsonMode) {
-    const output = {
-      success: chainResult.success,
-      steps: chainResult.steps.map((s) => ({
-        command: s.raw,
-        success: s.success,
-        data: s.data,
-        duration: s.duration,
-        ...s.hookOutputs?.length ? { hooks: s.hookOutputs } : {}
-      }))
-    };
-    console.log(JSON.stringify(output, null, 2));
+  if (mode === "json" || mode === "yaml") {
+    outputEnvelope(
+      {
+        success: chainResult.success,
+        data: {
+          steps: chainResult.steps.map((s) => ({
+            command: s.raw,
+            success: s.success,
+            data: s.data,
+            duration: s.duration,
+            ...s.hookOutputs?.length ? { hooks: s.hookOutputs } : {}
+          }))
+        },
+        duration: chainResult.totalDuration
+      },
+      { command: "chain", totalSteps: chainResult.steps.length },
+      mode
+    );
   } else {
     printChainResult(chainResult);
   }
@@ -13056,7 +13147,15 @@ async function routeCommand(argvIn, stdinCommands) {
   const sessionName = options.session || process.env.XBROWSER_SESSION || "default";
   const cdpEndpoint = options.cdp || process.env.XBROWSER_CDP;
   if (options.version || options.v && positional.length === 0) {
-    console.log(`xbrowser v${version}`);
+    if (mode === "json") {
+      outputEnvelope(
+        { success: true, data: { version, name: "@xbrowser/cli" } },
+        { command: "version" },
+        mode
+      );
+    } else {
+      console.log(`xbrowser v${version}`);
+    }
     return;
   }
   if (positional.length === 0) {
@@ -13252,18 +13351,23 @@ async function routeCommand(argvIn, stdinCommands) {
           if (isChainInput(fullInput)) {
             const chainResult = await executeChain(fullInput, { cdpEndpoint, sessionName });
             if (mode === "json" || mode === "yaml") {
-              const output = {
-                success: chainResult.success,
-                steps: chainResult.steps.map((s) => ({
-                  command: s.raw,
-                  success: s.success,
-                  data: s.data,
-                  duration: s.duration
-                })),
-                totalDuration: chainResult.totalDuration,
-                ...chainResult.stoppedReason ? { stoppedReason: chainResult.stoppedReason } : {}
-              };
-              outputResult(output, mode);
+              outputEnvelope(
+                {
+                  success: chainResult.success,
+                  data: {
+                    steps: chainResult.steps.map((s) => ({
+                      command: s.raw,
+                      success: s.success,
+                      data: s.data,
+                      duration: s.duration
+                    })),
+                    ...chainResult.stoppedReason ? { stoppedReason: chainResult.stoppedReason } : {}
+                  },
+                  duration: chainResult.totalDuration
+                },
+                { command: "chain", totalSteps: chainResult.steps.length },
+                mode
+              );
               if (!chainResult.success) throw new Error("Command failed");
               return;
             }
@@ -13408,6 +13512,17 @@ Run "xbrowser ${command} ${subCommand} --help" to see available parameters.`
               session = await createSession(sessionName, void 0, cdpEndpoint ? { cdpEndpoint } : {});
             }
           }
+          const cmdTabIndex = options.tab !== void 0 ? Number(options.tab) : void 0;
+          if (cmdTabIndex !== void 0 && session?.context) {
+            const pages = session.context.pages();
+            if (cmdTabIndex >= 0 && cmdTabIndex < pages.length) {
+              const targetPage = pages[cmdTabIndex];
+              await targetPage.bringToFront().catch(() => {
+              });
+              const { setActivePage: setActivePage2 } = await import("./browser-TLIDFFEG.js");
+              setActivePage2(session, targetPage);
+            }
+          }
           const ctx = {
             args: cmdArgsForPlugin,
             options,
@@ -13485,22 +13600,17 @@ Run "xbrowser ${command} ${subCommand} --help" to see available parameters.`
             const outputData = isCommandResult2(result) ? result.data : result && typeof result === "object" ? result.data ?? result : result;
             const tips = isCommandResult2(result) ? result.tips : result && typeof result === "object" ? result.tips : void 0;
             if (mode === "json" || mode === "yaml") {
-              const finalOutput = {
-                data: outputData
-              };
-              if (injectedViewerUrl) {
-                finalOutput.viewerUrl = injectedViewerUrl;
-              }
-              if (tips?.length) {
-                finalOutput.tips = tips;
-              }
-              if (hookOutputs.length > 0) {
-                finalOutput.hooks = hookOutputs;
-              }
-              console.log(outputFormatter2.format(finalOutput, { mode, color: false, emoji: false }));
-              if (tips?.length) {
-                for (const tip of tips) console.error(`\u{1F4A1} ${typeof tip === "string" ? tip : tip.message}`);
-              }
+              const resultSuccess = isCommandResult2(result) ? result.success !== false : true;
+              const resultMsg = isCommandResult2(result) ? result.message : void 0;
+              const duration = Date.now() - cmdStart;
+              const envelopeMeta = { command: `${command} ${subCommand}` };
+              if (injectedViewerUrl) envelopeMeta.viewerUrl = injectedViewerUrl;
+              if (hookOutputs.length > 0) envelopeMeta.hooks = hookOutputs;
+              outputEnvelope(
+                { success: resultSuccess, data: outputData, message: resultMsg, tips, duration },
+                envelopeMeta,
+                mode
+              );
             } else {
               console.log(outputFormatter2.format(outputData, { mode: "text", color: true, emoji: true }));
               if (tips?.length) {