@xbrowser/cli 0.15.0 → 0.16.0

package/dist/index.js

@@ -107,7 +107,8 @@ import {
   isCommandResult,
   configureArchiveStore,
   appendCommandToArchive,
-  checkGuard
+  checkGuard,
+  PluginStorage
 } from "@dyyz1993/xcli-core";
 
 // src/utils/positional-params.ts
@@ -5962,7 +5963,7 @@ import { join as join2 } from "path";
 import { execSync as execSync6 } from "child_process";
 var SHARED_PLUGIN_DEPENDENCIES = {
   "zod": "^3.24.0",
-  "@dyyz1993/xcli-core": "^0.9.2"
+  "@dyyz1993/xcli-core": "^0.12.1"
 };
 function ensurePluginDependencies(pluginsDir) {
   const zodPath = join2(pluginsDir, "node_modules", "zod");
@@ -6546,45 +6547,13 @@ async function loadHooks() {
 // src/executor.ts
 import { homedir as homedir3 } from "os";
 import { join as join3 } from "path";
-import { existsSync as existsSync6, readFileSync as readFileSync9, writeFileSync as writeFileSync4, mkdirSync as mkdirSync3 } from "fs";
 var NAVIGATION_COMMANDS = /* @__PURE__ */ new Set(["goto", "back", "forward", "refresh"]);
 var snapshotHintShown = /* @__PURE__ */ new WeakSet();
 var STORAGE_DIR = join3(homedir3(), ".xbrowser", "storage");
 var storageCache = /* @__PURE__ */ new Map();
 function getPluginStorage(pluginName) {
   if (!storageCache.has(pluginName)) {
-    const filePath = join3(STORAGE_DIR, `${pluginName}.json`);
-    let data = {};
-    const load3 = () => {
-      if (existsSync6(filePath)) {
-        try {
-          data = JSON.parse(readFileSync9(filePath, "utf-8"));
-        } catch {
-          data = {};
-        }
-      }
-    };
-    const save = () => {
-      mkdirSync3(STORAGE_DIR, { recursive: true });
-      writeFileSync4(filePath, JSON.stringify(data, null, 2), "utf-8");
-    };
-    load3();
-    storageCache.set(pluginName, {
-      get: async (key) => data[key] ?? null,
-      set: async (key, value) => {
-        data[key] = value;
-        save();
-      },
-      delete: async (key) => {
-        delete data[key];
-        save();
-      },
-      clear: async () => {
-        data = {};
-        save();
-      },
-      keys: async () => Object.keys(data)
-    });
+    storageCache.set(pluginName, new PluginStorage(pluginName, STORAGE_DIR));
   }
   return storageCache.get(pluginName);
 }
@@ -6684,6 +6653,10 @@ async function executeCommand(commandName, params, sessionName = "default", extr
     session = await createSession(sessionName, params.url, {
       cdpEndpoint: extraOpts?.cdpEndpoint
     });
+  } else if (command.scope === "browser") {
+    session = await createSession(sessionName, void 0, {
+      cdpEndpoint: extraOpts?.cdpEndpoint
+    });
   } else if (command.scope !== "project") {
     return errorResult(
       `Session '${sessionName}' not found. Run "xbrowser session open <url>" first.`
@@ -7333,26 +7306,26 @@ var configBuiltin = {
 
 // src/plugin/installer.ts
 import {
-  existsSync as existsSync13,
+  existsSync as existsSync12,
   readdirSync as readdirSync3,
-  mkdirSync as mkdirSync8,
+  mkdirSync as mkdirSync7,
   rmSync as rmSync7
 } from "fs";
 import { resolve as resolve15, basename as basename2 } from "path";
 import { homedir as homedir4 } from "os";
 
 // src/plugin/install-sources/local.ts
-import { existsSync as existsSync8, cpSync as cpSync2, rmSync as rmSync2 } from "fs";
+import { existsSync as existsSync7, cpSync as cpSync2, rmSync as rmSync2 } from "fs";
 import { resolve as resolve10 } from "path";
 
 // src/plugin/install-utils.ts
 import {
-  existsSync as existsSync7,
+  existsSync as existsSync6,
   readdirSync as readdirSync2,
   cpSync,
   rmSync,
-  mkdirSync as mkdirSync4,
-  readFileSync as readFileSync10,
+  mkdirSync as mkdirSync3,
+  readFileSync as readFileSync9,
   createWriteStream
 } from "fs";
 import { resolve as resolve9 } from "path";
@@ -7423,7 +7396,7 @@ async function downloadToFile(url, destPath) {
   await pipeline(nodeStream, createWriteStream(destPath));
 }
 function extractTarGz(tarballPath, targetDir) {
-  mkdirSync4(targetDir, { recursive: true });
+  mkdirSync3(targetDir, { recursive: true });
   execSync7(`tar -xzf "${tarballPath}" -C "${targetDir}"`, { stdio: "pipe" });
 }
 function flattenPackageRoot(targetDir) {
@@ -7444,18 +7417,18 @@ function flattenPackageRoot(targetDir) {
 async function verifyPlugin(dir) {
   const warnings = [];
   const indexPath = resolve9(dir, "index.ts");
-  if (!existsSync7(indexPath)) {
+  if (!existsSync6(indexPath)) {
     const indexJs = resolve9(dir, "index.js");
-    if (!existsSync7(indexJs)) {
+    if (!existsSync6(indexJs)) {
       return { valid: false, error: "No index.ts or index.js entry point found", warnings };
     }
   }
   const pkgPath = resolve9(dir, "package.json");
-  if (!existsSync7(pkgPath)) {
+  if (!existsSync6(pkgPath)) {
     warnings.push("No package.json found");
   } else {
     try {
-      const pkg2 = JSON.parse(readFileSync10(pkgPath, "utf-8"));
+      const pkg2 = JSON.parse(readFileSync9(pkgPath, "utf-8"));
       if (!pkg2.xbrowser) {
         warnings.push("No xbrowser metadata in package.json");
       }
@@ -7475,7 +7448,7 @@ function safeCleanup(dir) {
 // src/plugin/install-sources/local.ts
 async function installFromLocal(source, name, targetDir) {
   const srcPath = resolve10(source);
-  if (!existsSync8(srcPath)) {
+  if (!existsSync7(srcPath)) {
     throw new Error(`Local path does not exist: ${srcPath}`);
   }
   const tmpTarget = `${targetDir}-tmp-${Date.now()}`;
@@ -7488,7 +7461,7 @@ async function installFromLocal(source, name, targetDir) {
       safeCleanup(tmpTarget);
       throw new Error(`Invalid plugin: ${verify.error}`);
     }
-    if (existsSync8(targetDir)) {
+    if (existsSync7(targetDir)) {
       rmSync2(targetDir, { recursive: true, force: true });
     }
     cpSync2(tmpTarget, targetDir, { recursive: true, force: true });
@@ -7508,7 +7481,7 @@ async function installFromLocal(source, name, targetDir) {
 }
 
 // src/plugin/install-sources/npm.ts
-import { existsSync as existsSync9, mkdirSync as mkdirSync5, readFileSync as readFileSync11, writeFileSync as writeFileSync5, rmSync as rmSync3, cpSync as cpSync3 } from "fs";
+import { existsSync as existsSync8, mkdirSync as mkdirSync4, readFileSync as readFileSync10, writeFileSync as writeFileSync4, rmSync as rmSync3, cpSync as cpSync3 } from "fs";
 import { resolve as resolve11, join as join4 } from "path";
 import { tmpdir } from "os";
 async function installFromNpm(packageName, name, targetDir) {
@@ -7529,7 +7502,7 @@ async function installFromNpm(packageName, name, targetDir) {
   }
   const tarballUrl = versionMeta.dist.tarball;
   const tmpDir = join4(tmpdir(), `xbrowser-npm-${Date.now()}`);
-  mkdirSync5(tmpDir, { recursive: true });
+  mkdirSync4(tmpDir, { recursive: true });
   let warnings = [];
   try {
     const tarballPath = join4(tmpDir, `${name}.tgz`);
@@ -7542,16 +7515,16 @@ async function installFromNpm(packageName, name, targetDir) {
     if (!verify.valid) {
       throw new Error(`Invalid npm plugin: ${verify.error}`);
     }
-    if (existsSync9(targetDir)) {
+    if (existsSync8(targetDir)) {
       rmSync3(targetDir, { recursive: true, force: true });
     }
     cpSync3(extractDir, targetDir, { recursive: true, force: true });
     const pkgPath = resolve11(targetDir, "package.json");
-    if (existsSync9(pkgPath)) {
-      const pkg2 = JSON.parse(readFileSync11(pkgPath, "utf-8"));
+    if (existsSync8(pkgPath)) {
+      const pkg2 = JSON.parse(readFileSync10(pkgPath, "utf-8"));
       if (!pkg2._npmSource) {
         pkg2._npmSource = { name: packageName, version: latestVersion };
-        writeFileSync5(pkgPath, JSON.stringify(pkg2, null, 2));
+        writeFileSync4(pkgPath, JSON.stringify(pkg2, null, 2));
       }
     }
   } finally {
@@ -7568,7 +7541,7 @@ async function installFromNpm(packageName, name, targetDir) {
 }
 
 // src/plugin/install-sources/git.ts
-import { existsSync as existsSync10, readFileSync as readFileSync12, writeFileSync as writeFileSync6, rmSync as rmSync4, cpSync as cpSync4 } from "fs";
+import { existsSync as existsSync9, readFileSync as readFileSync11, writeFileSync as writeFileSync5, rmSync as rmSync4, cpSync as cpSync4 } from "fs";
 import { resolve as resolve12, join as join5 } from "path";
 import { tmpdir as tmpdir2 } from "os";
 import { execSync as execSync8 } from "child_process";
@@ -7582,17 +7555,17 @@ async function installFromGit(gitUrl, name, targetDir) {
     if (!verify.valid) {
       throw new Error(`Invalid git plugin: ${verify.error}`);
     }
-    if (existsSync10(targetDir)) {
+    if (existsSync9(targetDir)) {
       rmSync4(targetDir, { recursive: true, force: true });
     }
     cpSync4(tmpDir, targetDir, { recursive: true, force: true });
     rmSync4(resolve12(targetDir, ".git"), { recursive: true, force: true });
     const pkgPath = resolve12(targetDir, "package.json");
-    if (existsSync10(pkgPath)) {
-      const pkg2 = JSON.parse(readFileSync12(pkgPath, "utf-8"));
+    if (existsSync9(pkgPath)) {
+      const pkg2 = JSON.parse(readFileSync11(pkgPath, "utf-8"));
       if (!pkg2._gitSource) {
         pkg2._gitSource = { url: gitUrl };
-        writeFileSync6(pkgPath, JSON.stringify(pkg2, null, 2));
+        writeFileSync5(pkgPath, JSON.stringify(pkg2, null, 2));
       }
     }
   } finally {
@@ -7609,12 +7582,12 @@ async function installFromGit(gitUrl, name, targetDir) {
 }
 
 // src/plugin/install-sources/url.ts
-import { existsSync as existsSync11, readFileSync as readFileSync13, writeFileSync as writeFileSync7, mkdirSync as mkdirSync6, rmSync as rmSync5, cpSync as cpSync5 } from "fs";
+import { existsSync as existsSync10, readFileSync as readFileSync12, writeFileSync as writeFileSync6, mkdirSync as mkdirSync5, rmSync as rmSync5, cpSync as cpSync5 } from "fs";
 import { resolve as resolve13, join as join6, basename } from "path";
 import { tmpdir as tmpdir3 } from "os";
 async function installFromUrl(url, name, targetDir) {
   const tmpDir = join6(tmpdir3(), `xbrowser-url-${Date.now()}`);
-  mkdirSync6(tmpDir, { recursive: true });
+  mkdirSync5(tmpDir, { recursive: true });
   let warnings = [];
   try {
     const fileName = basename(new URL(url).pathname) || "plugin.tar.gz";
@@ -7628,16 +7601,16 @@ async function installFromUrl(url, name, targetDir) {
     if (!verify.valid) {
       throw new Error(`Invalid plugin from URL: ${verify.error}`);
     }
-    if (existsSync11(targetDir)) {
+    if (existsSync10(targetDir)) {
       rmSync5(targetDir, { recursive: true, force: true });
     }
     cpSync5(extractDir, targetDir, { recursive: true, force: true });
     const pkgPath = resolve13(targetDir, "package.json");
-    if (existsSync11(pkgPath)) {
-      const pkg2 = JSON.parse(readFileSync13(pkgPath, "utf-8"));
+    if (existsSync10(pkgPath)) {
+      const pkg2 = JSON.parse(readFileSync12(pkgPath, "utf-8"));
       if (!pkg2._urlSource) {
         pkg2._urlSource = { url };
-        writeFileSync7(pkgPath, JSON.stringify(pkg2, null, 2));
+        writeFileSync6(pkgPath, JSON.stringify(pkg2, null, 2));
       }
     }
   } finally {
@@ -7655,10 +7628,10 @@ async function installFromUrl(url, name, targetDir) {
 
 // src/plugin/install-sources/marketplace.ts
 import {
-  existsSync as existsSync12,
-  mkdirSync as mkdirSync7,
-  writeFileSync as writeFileSync8,
-  readFileSync as readFileSync14,
+  existsSync as existsSync11,
+  mkdirSync as mkdirSync6,
+  writeFileSync as writeFileSync7,
+  readFileSync as readFileSync13,
   rmSync as rmSync6,
   cpSync as cpSync6
 } from "fs";
@@ -7680,12 +7653,12 @@ async function installFromMarketplace(pluginsDir, slug, options) {
   const plugin = detailData.data;
   const name = options?.name || String(plugin.slug || slug);
   const targetDir = resolve14(pluginsDir, name);
-  if (existsSync12(targetDir) && !options?.force) {
+  if (existsSync11(targetDir) && !options?.force) {
     throw new Error(`Plugin "${name}" already exists. Use --force to overwrite.`);
   }
-  mkdirSync7(targetDir, { recursive: true });
+  mkdirSync6(targetDir, { recursive: true });
   const tmpDir = join7(tmpdir4(), `xbrowser-marketplace-${Date.now()}`);
-  mkdirSync7(tmpDir, { recursive: true });
+  mkdirSync6(tmpDir, { recursive: true });
   const realSlug = String(plugin.slug || slug);
   try {
     await downloadAndExtractMarketplaceTarball(baseUrl, realSlug, tmpDir, targetDir);
@@ -7715,14 +7688,14 @@ function isManifestArray(data) {
   return Array.isArray(data) && data.length > 0 && typeof data[0].path === "string" && typeof data[0].content === "string";
 }
 function extractManifestToDir(manifest, targetDir) {
-  if (existsSync12(targetDir)) {
+  if (existsSync11(targetDir)) {
     rmSync6(targetDir, { recursive: true, force: true });
   }
-  mkdirSync7(targetDir, { recursive: true });
+  mkdirSync6(targetDir, { recursive: true });
   for (const file of manifest) {
     const filePath = resolve14(targetDir, file.path);
-    mkdirSync7(dirname2(filePath), { recursive: true });
-    writeFileSync8(filePath, Buffer.from(file.content, "base64"));
+    mkdirSync6(dirname2(filePath), { recursive: true });
+    writeFileSync7(filePath, Buffer.from(file.content, "base64"));
   }
 }
 function tryParseAsGzippedManifest(buffer) {
@@ -7749,7 +7722,7 @@ async function downloadAndExtractMarketplaceTarball(baseUrl, slug, tmpDir, targe
     const redirectUrl = tarballRes.headers.get("location");
     const tarballPath = join7(tmpDir, `${slug}.tar.gz`);
     await downloadToFile(redirectUrl, tarballPath);
-    const buffer = readFileSync14(tarballPath);
+    const buffer = readFileSync13(tarballPath);
     const manifest = tryParseAsGzippedManifest(buffer);
     if (manifest) {
       extractManifestToDir(manifest, targetDir);
@@ -7758,7 +7731,7 @@ async function downloadAndExtractMarketplaceTarball(baseUrl, slug, tmpDir, targe
     const extractDir = join7(tmpDir, "extracted");
     extractTarGz(tarballPath, extractDir);
     flattenPackageRoot(extractDir);
-    if (existsSync12(targetDir)) {
+    if (existsSync11(targetDir)) {
       rmSync6(targetDir, { recursive: true, force: true });
     }
     cpSync6(extractDir, targetDir, { recursive: true, force: true });
@@ -7770,12 +7743,12 @@ async function downloadAndExtractMarketplaceTarball(baseUrl, slug, tmpDir, targe
       return;
     }
     const tarballPath = join7(tmpDir, `${slug}.tar.gz`);
-    writeFileSync8(tarballPath, buffer);
+    writeFileSync7(tarballPath, buffer);
     try {
       const extractDir = join7(tmpDir, "extracted");
       extractTarGz(tarballPath, extractDir);
       flattenPackageRoot(extractDir);
-      if (existsSync12(targetDir)) {
+      if (existsSync11(targetDir)) {
         rmSync6(targetDir, { recursive: true, force: true });
       }
       cpSync6(extractDir, targetDir, { recursive: true, force: true });
@@ -7811,24 +7784,24 @@ function writeMarketplacePackageJson(plugin, slug, name, baseUrl, targetDir) {
     }
   };
   const pkgPath = resolve14(targetDir, "package.json");
-  if (!existsSync12(pkgPath)) {
-    writeFileSync8(pkgPath, JSON.stringify(packageJson, null, 2));
+  if (!existsSync11(pkgPath)) {
+    writeFileSync7(pkgPath, JSON.stringify(packageJson, null, 2));
   } else {
     try {
-      const existing = JSON.parse(readFileSync14(pkgPath, "utf-8"));
+      const existing = JSON.parse(readFileSync13(pkgPath, "utf-8"));
       const merged = {
         ...existing,
         xbrowser: { ...existing.xbrowser, ...packageJson.xbrowser },
         _marketplace: packageJson._marketplace
       };
-      writeFileSync8(pkgPath, JSON.stringify(merged, null, 2));
+      writeFileSync7(pkgPath, JSON.stringify(merged, null, 2));
     } catch {
-      writeFileSync8(pkgPath, JSON.stringify(packageJson, null, 2));
+      writeFileSync7(pkgPath, JSON.stringify(packageJson, null, 2));
     }
   }
 }
 function ensureIndexFile(plugin, name, targetDir) {
-  if (!existsSync12(resolve14(targetDir, "index.ts")) && !existsSync12(resolve14(targetDir, "index.js"))) {
+  if (!existsSync11(resolve14(targetDir, "index.ts")) && !existsSync11(resolve14(targetDir, "index.js"))) {
     const commands = plugin.commands || [];
     const commandHandlers = commands.length > 0 ? commands.map((cmd) => {
       return [
@@ -7843,7 +7816,7 @@ function ensureIndexFile(plugin, name, targetDir) {
       `    handler: async () => ({ data: { message: 'Hello from ${name}!' }, tips: [] }),`,
       `  });`
     ].join("\n");
-    writeFileSync8(
+    writeFileSync7(
       resolve14(targetDir, "index.ts"),
       [
         `import type { XCLIAPI } from '@dyyz1993/xcli-core';`,
@@ -7882,10 +7855,10 @@ var PluginInstaller = class {
     const type = this.detectSourceType(source);
     const name = options?.name || this.deriveName(source, type);
     const targetDir = resolve15(this.pluginsDir, name);
-    if (existsSync13(targetDir) && !options?.force) {
+    if (existsSync12(targetDir) && !options?.force) {
       throw new Error(`Plugin "${name}" already exists. Use --force to overwrite.`);
     }
-    mkdirSync8(targetDir, { recursive: true });
+    mkdirSync7(targetDir, { recursive: true });
     const resolvedSource = type === "npm" ? await resolveNpmPackageWithFallback(source) : source;
     switch (type) {
       case "local":
@@ -7943,7 +7916,7 @@ var PluginInstaller = class {
    */
   async uninstall(name) {
     const targetDir = resolve15(this.pluginsDir, name);
-    if (!existsSync13(targetDir)) {
+    if (!existsSync12(targetDir)) {
       throw new Error(`Plugin "${name}" not found`);
     }
     rmSync7(targetDir, { recursive: true, force: true });
@@ -7954,7 +7927,7 @@ var PluginInstaller = class {
    * @returns Array of installed plugin information.
    */
   async list(_options) {
-    if (!existsSync13(this.pluginsDir)) return [];
+    if (!existsSync12(this.pluginsDir)) return [];
     const entries = readdirSync3(this.pluginsDir, { withFileTypes: true });
     const plugins = [];
     for (const entry of entries) {
@@ -7962,7 +7935,7 @@ var PluginInstaller = class {
       const pluginPath = resolve15(this.pluginsDir, entry.name);
       const indexPath = resolve15(pluginPath, "index.ts");
       const indexJsPath = resolve15(pluginPath, "index.js");
-      if (!existsSync13(indexPath) && !existsSync13(indexJsPath)) continue;
+      if (!existsSync12(indexPath) && !existsSync12(indexJsPath)) continue;
       const metadata = PluginMetadataParser.parseFromPackageJson(pluginPath);
       let source = "local";
       const pkg2 = readJsonFile(resolve15(pluginPath, "package.json"), {});
@@ -7989,10 +7962,10 @@ var PluginInstaller = class {
     }
     if (source.startsWith("file://")) {
       const filePath = decodeURIComponent(new URL(source).pathname);
-      if (existsSync13(filePath)) return "url";
+      if (existsSync12(filePath)) return "url";
     }
     if (source.endsWith(".git") || source.includes("github.com/")) return "git";
-    if (existsSync13(resolve15(source))) return "local";
+    if (existsSync12(resolve15(source))) return "local";
     return "npm";
   }
   deriveName(source, type) {
@@ -10021,7 +9994,7 @@ async function handleFilter(args, _mode) {
 
 // src/stdin.ts
 import { createInterface } from "readline";
-import { readFileSync as readFileSync15 } from "fs";
+import { readFileSync as readFileSync14 } from "fs";
 async function readStdin2() {
   if (process.stdin.isTTY) return [];
   const lines = [];
@@ -10035,7 +10008,7 @@ async function readStdin2() {
   return lines;
 }
 function readCommandFile(filePath) {
-  const content = readFileSync15(filePath, "utf-8");
+  const content = readFileSync14(filePath, "utf-8");
   return content.split("\n").map((line) => line.trim()).filter((line) => line && !line.startsWith("#"));
 }
 
@@ -10932,6 +10905,22 @@ var HTTPServer = class {
 };
 
 // src/router.ts
+var KNOWN_GLOBAL_OPTIONS = /* @__PURE__ */ new Set([
+  "json",
+  "yaml",
+  "session",
+  "cdp",
+  "cdp-endpoint",
+  "version",
+  "v",
+  "help",
+  "h",
+  "target",
+  "port",
+  "token",
+  "timeout",
+  "headless"
+]);
 function showCommandHelp(siteName, cmd, siteConfig, mode) {
   const c = cmd;
   if (mode === "json") {
@@ -11056,8 +11045,23 @@ async function handleEvalMode(argv) {
 }
 async function handleChainInput(input, argv) {
   const cdpEndpoint = argv ? extractCdpFromArgv(argv) : void 0;
+  const jsonMode = argv ? argv.includes("--json") || argv.includes("-j") : false;
   const chainResult = await executeChain(input, { cdpEndpoint });
-  printChainResult(chainResult);
+  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));
+  } else {
+    printChainResult(chainResult);
+  }
   if (!chainResult.success) throw new Error("Command failed");
 }
 async function routeCommand(argv, stdinCommands) {
@@ -11080,6 +11084,8 @@ async function routeCommand(argv, stdinCommands) {
   }
   const parsed = parseArgs(argv);
   const { positional, options } = parsed;
+  const command = positional[0];
+  const cmdArgs = positional.slice(1);
   const mode = options.json ? "json" : options.yaml ? "yaml" : "text";
   const sessionName = options.session || process.env.XBROWSER_SESSION || "default";
   const cdpEndpoint = options.cdp;
@@ -11091,8 +11097,6 @@ async function routeCommand(argv, stdinCommands) {
     showMainHelp();
     return;
   }
-  const command = positional[0];
-  const cmdArgs = positional.slice(1);
   if ((options.help || options.h) && positional.length > 0) {
     const loader = await getPluginLoader();
     const internalLoader = loader.getCore().loader;
@@ -11307,10 +11311,30 @@ Run "xbrowser ${command} --help" to see available commands.`
           const subCmdIdx = pluginNameIdx >= 0 ? argv.indexOf(subCommand, pluginNameIdx + 1) : -1;
           const rawPluginArgs = subCmdIdx >= 0 ? argv.slice(subCmdIdx + 1) : [];
           const params = parsePluginParams(rawPluginArgs, cmdEntry.parameters);
+          if (cmdEntry.parameters) {
+            const schemaAny = cmdEntry.parameters;
+            const def = schemaAny._def;
+            const shapeOrFn = def?.shape ?? schemaAny.shape;
+            const shapeObj = typeof shapeOrFn === "function" ? shapeOrFn() : shapeOrFn;
+            if (shapeObj && typeof shapeObj === "object") {
+              const knownKeys = new Set(Object.keys(shapeObj));
+              knownKeys.add("_target");
+              for (const gk of KNOWN_GLOBAL_OPTIONS) knownKeys.add(gk.replace(/-([a-z])/g, (_, c) => c.toUpperCase()));
+              const unknownKeys = Object.keys(params).filter((k) => !knownKeys.has(k));
+              if (unknownKeys.length > 0) {
+                const unknown = unknownKeys.map((k) => `--${k.replace(/([A-Z])/g, "-$1").toLowerCase()}`).join(", ");
+                outputError(
+                  `Unknown parameter: ${unknown}
+Run "xbrowser ${command} ${subCommand} --help" to see available parameters.`
+                );
+                return;
+              }
+            }
+          }
           if (options.target && !params._target) {
             params._target = options.target;
           }
-          const needsBrowser = cmdEntry.scope === "page";
+          const needsBrowser = cmdEntry.scope === "page" || cmdEntry.scope === "browser";
           if (needsBrowser && !process.env.XBROWSER_DAEMON_WORKER) {
             const { forwardExec } = await import("./daemon-client-3IJD6X4B.js");
             const userTimeout = typeof params.timeout === "number" && params.timeout > 0 ? params.timeout * 1e3 + 3e4 : void 0;
@@ -11360,38 +11384,46 @@ Run "xbrowser ${command} --help" to see available commands.`
             }
           };
           try {
+            const cmdStart = Date.now();
+            const cmdHooks = await loadHooks();
+            if (cmdHooks.length > 0 && session?.page) {
+              await Promise.all(cmdHooks.map((h) => h.onBeforeCommand?.({ page: session.page, command: `${command} ${subCommand}`, params })));
+            }
             const result = await cmdEntry.handler(params, ctx);
+            const hookOutputs = [];
+            if (cmdHooks.length > 0 && session?.page) {
+              for (const h of cmdHooks) {
+                const output = await h.onAfterCommand?.({ page: session.page, command: `${command} ${subCommand}`, params, result, duration: Date.now() - cmdStart });
+                if (output) hookOutputs.push({ _hook: h.name, ...output });
+              }
+            }
             if (session && result && result.data) {
               const convUrl = result.data.conversationUrl;
               if (convUrl) {
                 saveSessionDiskMeta(sessionName, { conversationUrl: convUrl, cdpEndpoint });
               }
             }
-            if (isCommandResult2(result)) {
-              if (mode === "json" || mode === "yaml") {
-                console.log(outputFormatter2.format(result.data, { mode, color: false, emoji: false }));
-                if (result.tips?.length) {
-                  for (const tip of result.tips) console.error(`\u{1F4A1} ${tip}`);
-                }
-              } else {
-                console.log(outputFormatter2.format(result.data, { mode: "text", color: true, emoji: true }));
-                if (result.tips?.length) {
-                  for (const tip of result.tips) console.log(`  \u{1F4A1} ${tip}`);
-                }
+            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 (hookOutputs.length > 0) {
+                finalOutput.hooks = hookOutputs;
               }
-            } else if (result && typeof result === "object") {
-              const obj = result;
-              if (mode === "json" || mode === "yaml") {
-                console.log(outputFormatter2.format(obj.data ?? obj, { mode, color: false, emoji: false }));
-                const tips = obj.tips;
-                if (tips?.length) {
-                  for (const tip of tips) console.error(`\u{1F4A1} ${tip}`);
-                }
-              } else {
-                if (obj.data) outputResult(obj.data, mode);
-                const tips = obj.tips;
-                if (tips?.length) {
-                  for (const tip of tips) console.log(`  \u{1F4A1} ${tip}`);
+              console.log(outputFormatter2.format(finalOutput, { mode, color: false, emoji: false }));
+              if (tips?.length) {
+                for (const tip of tips) console.error(`\u{1F4A1} ${tip}`);
+              }
+            } else {
+              console.log(outputFormatter2.format(outputData, { mode: "text", color: true, emoji: true }));
+              if (tips?.length) {
+                for (const tip of tips) console.log(`  \u{1F4A1} ${tip}`);
+              }
+              if (hookOutputs.length > 0) {
+                for (const ho of hookOutputs) {
+                  console.log(`  \u{1F4F8} screenshot: ${ho.screenshot?.url || "captured"}`);
                 }
               }
             }
@@ -12602,10 +12634,10 @@ var WSServer = class extends EventEmitter {
       }
       case "file_download": {
         try {
-          const { readFileSync: readFileSync17 } = await import("fs");
+          const { readFileSync: readFileSync16 } = await import("fs");
           const { resolve: resolve16, basename: basename3 } = await import("path");
           const targetPath = resolve16(msg.path);
-          const data = readFileSync17(targetPath);
+          const data = readFileSync16(targetPath);
           const base64 = data.toString("base64");
           const ext = targetPath.split(".").pop()?.toLowerCase() || "";
           const mimeMap = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xbrowser/cli",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Browser automation CLI for web scraping, headless browsing, SEO analysis, and AI agent workflows. A command-line alternative to Playwright, Puppeteer, and Selenium.",
   "type": "module",
   "bin": {
@@ -82,7 +82,7 @@
     "prepare": "husky"
   },
   "dependencies": {
-    "@dyyz1993/xcli-core": "^0.9.2",
+    "@dyyz1993/xcli-core": "^0.12.1",
     "@types/react-syntax-highlighter": "^15.5.13",
     "@types/turndown": "^5.0.6",
     "cheerio": "^1.2.0",