@jackwener/opencli 1.1.1 → 1.2.1

package/dist/commanderAdapter.js

@@ -15,6 +15,9 @@ import { formatRegistryHelpText } from './serialization.js';
 import { render as renderOutput } from './output.js';
 import { executeCommand } from './execution.js';
 import { CliError } from './errors.js';
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 /**
  * Register a single CliCommand as a Commander subcommand.
  */
@@ -46,6 +49,7 @@ export function registerCommandToProgram(siteCmd, cmd) {
     subCmd.addHelpText('after', formatRegistryHelpText(cmd));
     subCmd.action(async (...actionArgs) => {
         const actionOpts = actionArgs[positionalArgs.length] ?? {};
+        const optionsRecord = typeof actionOpts === 'object' && actionOpts !== null ? actionOpts : {};
         const startTime = Date.now();
         // ── Collect kwargs ──────────────────────────────────────────────────
         const kwargs = {};
@@ -58,21 +62,23 @@ export function registerCommandToProgram(siteCmd, cmd) {
             if (arg.positional)
                 continue;
             const camelName = arg.name.replace(/-([a-z])/g, (_m, ch) => ch.toUpperCase());
-            const v = actionOpts[arg.name] ?? actionOpts[camelName];
+            const v = optionsRecord[arg.name] ?? optionsRecord[camelName];
             if (v !== undefined)
                 kwargs[arg.name] = v;
         }
         // ── Execute + render ────────────────────────────────────────────────
         try {
-            if (actionOpts.verbose)
+            const verbose = optionsRecord.verbose === true;
+            const format = typeof optionsRecord.format === 'string' ? optionsRecord.format : 'table';
+            if (verbose)
                 process.env.OPENCLI_VERBOSE = '1';
-            const result = await executeCommand(cmd, kwargs, actionOpts.verbose);
-            if (actionOpts.verbose && (!result || (Array.isArray(result) && result.length === 0))) {
+            const result = await executeCommand(cmd, kwargs, verbose);
+            if (verbose && (!result || (Array.isArray(result) && result.length === 0))) {
                 console.error(chalk.yellow('[Verbose] Warning: Command returned an empty result.'));
             }
             const resolved = getRegistry().get(fullName(cmd)) ?? cmd;
             renderOutput(result, {
-                fmt: actionOpts.format,
+                fmt: format,
                 columns: resolved.columns,
                 title: `${resolved.site}/${resolved.name}`,
                 elapsed: (Date.now() - startTime) / 1000,
@@ -86,11 +92,11 @@ export function registerCommandToProgram(siteCmd, cmd) {
                 if (err.hint)
                     console.error(chalk.yellow(`Hint: ${err.hint}`));
             }
-            else if (actionOpts.verbose && err.stack) {
+            else if (optionsRecord.verbose === true && err instanceof Error && err.stack) {
                 console.error(chalk.red(err.stack));
             }
             else {
-                console.error(chalk.red(`Error: ${err.message ?? err}`));
+                console.error(chalk.red(`Error: ${getErrorMessage(err)}`));
             }
             process.exitCode = 1;
         }

package/dist/daemon.js

@@ -118,6 +118,25 @@ const wss = new WebSocketServer({ server: httpServer, path: '/ext' });
 wss.on('connection', (ws) => {
     console.error('[daemon] Extension connected');
     extensionWs = ws;
+    // ── Heartbeat: ping every 15s, close if 2 pongs missed ──
+    let missedPongs = 0;
+    const heartbeatInterval = setInterval(() => {
+        if (ws.readyState !== WebSocket.OPEN) {
+            clearInterval(heartbeatInterval);
+            return;
+        }
+        if (missedPongs >= 2) {
+            console.error('[daemon] Extension heartbeat lost, closing connection');
+            clearInterval(heartbeatInterval);
+            ws.terminate();
+            return;
+        }
+        missedPongs++;
+        ws.ping();
+    }, 15000);
+    ws.on('pong', () => {
+        missedPongs = 0;
+    });
     ws.on('message', (data) => {
         try {
             const msg = JSON.parse(data.toString());
@@ -142,6 +161,7 @@ wss.on('connection', (ws) => {
     });
     ws.on('close', () => {
         console.error('[daemon] Extension disconnected');
+        clearInterval(heartbeatInterval);
         if (extensionWs === ws) {
             extensionWs = null;
             // Reject all pending requests since the extension is gone
@@ -153,6 +173,7 @@ wss.on('connection', (ws) => {
         }
     });
     ws.on('error', () => {
+        clearInterval(heartbeatInterval);
         if (extensionWs === ws)
             extensionWs = null;
     });

package/dist/discovery.d.ts

@@ -7,8 +7,16 @@
  *    TS modules are loaded lazily only when their command is executed.
  * 2. FALLBACK (filesystem scan): Traditional runtime discovery for development.
  */
+/** Plugins directory: ~/.opencli/plugins/ */
+export declare const PLUGINS_DIR: string;
 /**
  * Discover and register CLI commands.
  * Uses pre-compiled manifest when available for instant startup.
  */
 export declare function discoverClis(...dirs: string[]): Promise<void>;
+/**
+ * Discover and register plugins from ~/.opencli/plugins/.
+ * Each subdirectory is treated as a plugin (site = directory name).
+ * Files inside are scanned flat (no nested site subdirs).
+ */
+export declare function discoverPlugins(): Promise<void>;

package/dist/discovery.js

@@ -8,10 +8,27 @@
  * 2. FALLBACK (filesystem scan): Traditional runtime discovery for development.
  */
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
 import yaml from 'js-yaml';
 import { Strategy, registerCommand } from './registry.js';
 import { log } from './logger.js';
+/** Plugins directory: ~/.opencli/plugins/ */
+export const PLUGINS_DIR = path.join(os.homedir(), '.opencli', 'plugins');
+const CLI_MODULE_PATTERN = /\bcli\s*\(/;
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function parseStrategy(rawStrategy, fallback = Strategy.COOKIE) {
+    if (!rawStrategy)
+        return fallback;
+    const key = rawStrategy.toUpperCase();
+    return Strategy[key] ?? fallback;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 /**
  * Discover and register CLI commands.
  * Uses pre-compiled manifest when available for instant startup.
@@ -43,7 +60,7 @@ async function loadFromManifest(manifestPath, clisDir) {
         for (const entry of manifest) {
             if (entry.type === 'yaml') {
                 // YAML pipelines fully inlined in manifest — register directly
-                const strategy = Strategy[entry.strategy.toUpperCase()] ?? Strategy.COOKIE;
+                const strategy = parseStrategy(entry.strategy);
                 const cmd = {
                     site: entry.site,
                     name: entry.name,
@@ -56,13 +73,14 @@ async function loadFromManifest(manifestPath, clisDir) {
                     pipeline: entry.pipeline,
                     timeoutSeconds: entry.timeout,
                     source: `manifest:${entry.site}/${entry.name}`,
+                    navigateBefore: entry.navigateBefore,
                 };
                 registerCommand(cmd);
             }
             else if (entry.type === 'ts' && entry.modulePath) {
                 // TS adapters: register a lightweight stub.
                 // The actual module is loaded lazily on first executeCommand().
-                const strategy = Strategy[(entry.strategy ?? 'cookie').toUpperCase()] ?? Strategy.COOKIE;
+                const strategy = parseStrategy(entry.strategy ?? 'cookie');
                 const modulePath = path.resolve(clisDir, entry.modulePath);
                 const cmd = {
                     site: entry.site,
@@ -75,6 +93,7 @@ async function loadFromManifest(manifestPath, clisDir) {
                     columns: entry.columns,
                     timeoutSeconds: entry.timeout,
                     source: modulePath,
+                    navigateBefore: entry.navigateBefore,
                     _lazy: true,
                     _modulePath: modulePath,
                 };
@@ -83,7 +102,7 @@ async function loadFromManifest(manifestPath, clisDir) {
         }
     }
     catch (err) {
-        log.warn(`Failed to load manifest ${manifestPath}: ${err.message}`);
+        log.warn(`Failed to load manifest ${manifestPath}: ${getErrorMessage(err)}`);
     }
 }
 /**
@@ -111,8 +130,10 @@ async function discoverClisFromFs(dir) {
             }
             else if ((file.endsWith('.js') && !file.endsWith('.d.js')) ||
                 (file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.endsWith('.test.ts'))) {
-                promises.push(import(`file://${filePath}`).catch((err) => {
-                    log.warn(`Failed to load module ${filePath}: ${err.message}`);
+                if (!(await isCliModule(filePath)))
+                    continue;
+                promises.push(import(pathToFileURL(filePath).href).catch((err) => {
+                    log.warn(`Failed to load module ${filePath}: ${getErrorMessage(err)}`);
                 }));
             }
         }
@@ -123,16 +144,17 @@ async function registerYamlCli(filePath, defaultSite) {
     try {
         const raw = await fs.promises.readFile(filePath, 'utf-8');
         const def = yaml.load(raw);
-        if (!def || typeof def !== 'object')
+        if (!isRecord(def))
             return;
-        const site = def.site ?? defaultSite;
-        const name = def.name ?? path.basename(filePath, path.extname(filePath));
-        const strategyStr = def.strategy ?? (def.browser === false ? 'public' : 'cookie');
-        const strategy = Strategy[strategyStr.toUpperCase()] ?? Strategy.COOKIE;
-        const browser = def.browser ?? (strategy !== Strategy.PUBLIC);
+        const cliDef = def;
+        const site = cliDef.site ?? defaultSite;
+        const name = cliDef.name ?? path.basename(filePath, path.extname(filePath));
+        const strategyStr = cliDef.strategy ?? (cliDef.browser === false ? 'public' : 'cookie');
+        const strategy = parseStrategy(strategyStr);
+        const browser = cliDef.browser ?? (strategy !== Strategy.PUBLIC);
         const args = [];
-        if (def.args && typeof def.args === 'object') {
-            for (const [argName, argDef] of Object.entries(def.args)) {
+        if (cliDef.args && typeof cliDef.args === 'object') {
+            for (const [argName, argDef] of Object.entries(cliDef.args)) {
                 args.push({
                     name: argName,
                     type: argDef?.type ?? 'str',
@@ -147,19 +169,83 @@ async function registerYamlCli(filePath, defaultSite) {
         const cmd = {
             site,
             name,
-            description: def.description ?? '',
-            domain: def.domain,
+            description: cliDef.description ?? '',
+            domain: cliDef.domain,
             strategy,
             browser,
             args,
-            columns: def.columns,
-            pipeline: def.pipeline,
-            timeoutSeconds: def.timeout,
+            columns: cliDef.columns,
+            pipeline: cliDef.pipeline,
+            timeoutSeconds: cliDef.timeout,
             source: filePath,
+            navigateBefore: cliDef.navigateBefore,
         };
         registerCommand(cmd);
     }
     catch (err) {
-        log.warn(`Failed to load ${filePath}: ${err.message}`);
+        log.warn(`Failed to load ${filePath}: ${getErrorMessage(err)}`);
+    }
+}
+/**
+ * Discover and register plugins from ~/.opencli/plugins/.
+ * Each subdirectory is treated as a plugin (site = directory name).
+ * Files inside are scanned flat (no nested site subdirs).
+ */
+export async function discoverPlugins() {
+    try {
+        await fs.promises.access(PLUGINS_DIR);
+    }
+    catch {
+        return;
+    }
+    const entries = await fs.promises.readdir(PLUGINS_DIR, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        await discoverPluginDir(path.join(PLUGINS_DIR, entry.name), entry.name);
+    }
+}
+/**
+ * Flat scan: read yaml/ts files directly in a plugin directory.
+ * Unlike discoverClisFromFs, this does NOT expect nested site subdirectories.
+ */
+async function discoverPluginDir(dir, site) {
+    const files = await fs.promises.readdir(dir);
+    const fileSet = new Set(files);
+    const promises = [];
+    for (const file of files) {
+        const filePath = path.join(dir, file);
+        if (file.endsWith('.yaml') || file.endsWith('.yml')) {
+            promises.push(registerYamlCli(filePath, site));
+        }
+        else if (file.endsWith('.js') && !file.endsWith('.d.js')) {
+            if (!(await isCliModule(filePath)))
+                continue;
+            promises.push(import(pathToFileURL(filePath).href).catch((err) => {
+                log.warn(`Plugin ${site}/${file}: ${getErrorMessage(err)}`);
+            }));
+        }
+        else if (file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.endsWith('.test.ts')) {
+            // Skip .ts if a compiled .js sibling exists (production mode can't load .ts)
+            const jsFile = file.replace(/\.ts$/, '.js');
+            if (fileSet.has(jsFile))
+                continue;
+            if (!(await isCliModule(filePath)))
+                continue;
+            promises.push(import(pathToFileURL(filePath).href).catch((err) => {
+                log.warn(`Plugin ${site}/${file}: ${getErrorMessage(err)}`);
+            }));
+        }
+    }
+    await Promise.all(promises);
+}
+async function isCliModule(filePath) {
+    try {
+        const source = await fs.promises.readFile(filePath, 'utf-8');
+        return CLI_MODULE_PATTERN.test(source);
+    }
+    catch (err) {
+        log.warn(`Failed to inspect module ${filePath}: ${getErrorMessage(err)}`);
+        return false;
     }
 }

package/dist/doctor.js

@@ -26,11 +26,13 @@ export async function checkConnectivity(opts) {
     }
 }
 export async function runBrowserDoctor(opts = {}) {
-    const status = await checkDaemonStatus();
+    // Run the live connectivity check first — it may auto-start the daemon as a
+    // side-effect, so we read daemon status only *after* all side-effects settle.
     let connectivity;
     if (opts.live) {
         connectivity = await checkConnectivity();
     }
+    const status = await checkDaemonStatus();
     const sessions = opts.sessions && status.running && status.extensionConnected
         ? await listSessions()
         : undefined;

package/dist/doctor.test.js

@@ -1,7 +1,28 @@
-import { describe, expect, it } from 'vitest';
-import { renderBrowserDoctorReport } from './doctor.js';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+const { mockCheckDaemonStatus, mockListSessions, mockConnect, mockClose } = vi.hoisted(() => ({
+    mockCheckDaemonStatus: vi.fn(),
+    mockListSessions: vi.fn(),
+    mockConnect: vi.fn(),
+    mockClose: vi.fn(),
+}));
+vi.mock('./browser/discover.js', () => ({
+    checkDaemonStatus: mockCheckDaemonStatus,
+}));
+vi.mock('./browser/daemon-client.js', () => ({
+    listSessions: mockListSessions,
+}));
+vi.mock('./browser/index.js', () => ({
+    BrowserBridge: class {
+        connect = mockConnect;
+        close = mockClose;
+    },
+}));
+import { renderBrowserDoctorReport, runBrowserDoctor } from './doctor.js';
 describe('doctor report rendering', () => {
     const strip = (s) => s.replace(/\x1b\[[0-9;]*m/g, '');
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
     it('renders OK-style report when daemon and extension connected', () => {
         const text = strip(renderBrowserDoctorReport({
             daemonRunning: true,
@@ -48,4 +69,27 @@ describe('doctor report rendering', () => {
         }));
         expect(text).toContain('[SKIP] Connectivity: not tested (use --live)');
     });
+    it('reports consistent status when live check auto-starts the daemon', async () => {
+        // With the reordered flow, checkDaemonStatus is called only ONCE — after
+        // the connectivity check that may auto-start the daemon.
+        mockCheckDaemonStatus.mockResolvedValueOnce({ running: true, extensionConnected: false });
+        mockConnect.mockRejectedValueOnce(new Error('Daemon is running but the Browser Extension is not connected.\n' +
+            'Please install and enable the opencli Browser Bridge extension in Chrome.'));
+        const report = await runBrowserDoctor({ live: true });
+        // Status reflects the post-connectivity state (daemon running)
+        expect(report.daemonRunning).toBe(true);
+        expect(report.extensionConnected).toBe(false);
+        // checkDaemonStatus should only be called once
+        expect(mockCheckDaemonStatus).toHaveBeenCalledTimes(1);
+        // Should NOT report "daemon not running" since it IS running after live check
+        expect(report.issues).not.toContain(expect.stringContaining('Daemon is not running'));
+        // Should report extension not connected
+        expect(report.issues).toEqual(expect.arrayContaining([
+            expect.stringContaining('Chrome extension is not connected'),
+        ]));
+        // Should report connectivity failure
+        expect(report.issues).toEqual(expect.arrayContaining([
+            expect.stringContaining('Browser connectivity test failed'),
+        ]));
+    });
 });

package/dist/engine.test.d.ts

@@ -1,4 +1 @@
-/**
- * Tests for discovery and execution modules.
- */
 export {};

package/dist/engine.test.js

@@ -1,15 +1,83 @@
-/**
- * Tests for discovery and execution modules.
- */
-import { describe, it, expect } from 'vitest';
-import { discoverClis } from './discovery.js';
+import { describe, it, expect, afterEach } from 'vitest';
+import { discoverClis, discoverPlugins, PLUGINS_DIR } from './discovery.js';
 import { executeCommand } from './execution.js';
-import { cli, Strategy } from './registry.js';
+import { getRegistry, cli, Strategy } from './registry.js';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 describe('discoverClis', () => {
     it('handles non-existent directories gracefully', async () => {
         // Should not throw for missing directories
         await expect(discoverClis('/tmp/nonexistent-opencli-test-dir')).resolves.not.toThrow();
     });
+    it('imports only CLI command modules during filesystem discovery', async () => {
+        const tempRoot = await fs.promises.mkdtemp(path.join('/tmp', 'opencli-discovery-'));
+        const siteDir = path.join(tempRoot, 'temp-site');
+        const helperPath = path.join(siteDir, 'helper.ts');
+        const commandPath = path.join(siteDir, 'hello.ts');
+        try {
+            await fs.promises.mkdir(siteDir, { recursive: true });
+            await fs.promises.writeFile(helperPath, `
+globalThis.__opencli_helper_loaded__ = true;
+export const helper = true;
+`);
+            await fs.promises.writeFile(commandPath, `
+import { cli, Strategy } from '${path.join(process.cwd(), 'src', 'registry.ts')}';
+cli({
+  site: 'temp-site',
+  name: 'hello',
+  description: 'hello command',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  func: async () => [{ ok: true }],
+});
+`);
+            delete globalThis.__opencli_helper_loaded__;
+            await discoverClis(tempRoot);
+            expect(globalThis.__opencli_helper_loaded__).toBeUndefined();
+            expect(getRegistry().get('temp-site/hello')).toBeDefined();
+        }
+        finally {
+            delete globalThis.__opencli_helper_loaded__;
+            await fs.promises.rm(tempRoot, { recursive: true, force: true });
+        }
+    });
+});
+describe('discoverPlugins', () => {
+    const testPluginDir = path.join(PLUGINS_DIR, '__test-plugin__');
+    const yamlPath = path.join(testPluginDir, 'greeting.yaml');
+    afterEach(async () => {
+        try {
+            await fs.promises.rm(testPluginDir, { recursive: true });
+        }
+        catch { }
+    });
+    it('discovers YAML plugins from ~/.opencli/plugins/', async () => {
+        // Create a simple YAML adapter in the plugins directory
+        await fs.promises.mkdir(testPluginDir, { recursive: true });
+        await fs.promises.writeFile(yamlPath, `
+site: __test-plugin__
+name: greeting
+description: Test plugin greeting
+strategy: public
+browser: false
+
+pipeline:
+  - evaluate: "() => [{ message: 'hello from plugin' }]"
+
+columns: [message]
+`);
+        await discoverPlugins();
+        const registry = getRegistry();
+        const cmd = registry.get('__test-plugin__/greeting');
+        expect(cmd).toBeDefined();
+        expect(cmd.site).toBe('__test-plugin__');
+        expect(cmd.name).toBe('greeting');
+        expect(cmd.description).toBe('Test plugin greeting');
+    });
+    it('handles non-existent plugins directory gracefully', async () => {
+        // discoverPlugins should not throw if ~/.opencli/plugins/ does not exist
+        await expect(discoverPlugins()).resolves.not.toThrow();
+    });
 });
 describe('executeCommand', () => {
     it('accepts kebab-case option names after Commander camelCases them', async () => {

package/dist/execution.d.ts

@@ -9,14 +9,16 @@
  * 5. Lazy-loading of TS modules from manifest
  */
 import { type CliCommand, type Arg } from './registry.js';
+type CommandArgs = Record<string, unknown>;
 /**
  * Validates and coerces arguments based on the command's Arg definitions.
  */
-export declare function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: Record<string, any>): Record<string, any>;
+export declare function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: CommandArgs): CommandArgs;
 /**
  * Execute a CLI command. Automatically manages browser sessions when needed.
  *
  * This is the unified entry point — callers don't need to care about
  * whether the command requires a browser or not.
  */
-export declare function executeCommand(cmd: CliCommand, rawKwargs: Record<string, any>, debug?: boolean): Promise<any>;
+export declare function executeCommand(cmd: CliCommand, rawKwargs: CommandArgs, debug?: boolean): Promise<unknown>;
+export {};

package/dist/execution.js

@@ -9,12 +9,16 @@
  * 5. Lazy-loading of TS modules from manifest
  */
 import { Strategy, getRegistry, fullName } from './registry.js';
-import { executePipeline } from './pipeline.js';
+import { pathToFileURL } from 'node:url';
+import { executePipeline } from './pipeline/index.js';
 import { AdapterLoadError } from './errors.js';
 import { shouldUseBrowserSession } from './capabilityRouting.js';
 import { getBrowserFactory, browserSession, runWithTimeout, DEFAULT_BROWSER_COMMAND_TIMEOUT } from './runtime.js';
 /** Set of TS module paths that have been loaded */
 const _loadedModules = new Set();
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 /**
  * Validates and coerces arguments based on the command's Arg definitions.
  */
@@ -73,11 +77,11 @@ async function runCommand(cmd, page, kwargs, debug) {
         const modulePath = internal._modulePath;
         if (!_loadedModules.has(modulePath)) {
             try {
-                await import(`file://${modulePath}`);
+                await import(pathToFileURL(modulePath).href);
                 _loadedModules.add(modulePath);
             }
             catch (err) {
-                throw new AdapterLoadError(`Failed to load adapter module ${modulePath}: ${err.message}`, 'Check that the adapter file exists and has no syntax errors.');
+                throw new AdapterLoadError(`Failed to load adapter module ${modulePath}: ${getErrorMessage(err)}`, 'Check that the adapter file exists and has no syntax errors.');
             }
         }
         // After loading, the module's cli() call will have updated the registry.
@@ -93,6 +97,24 @@ async function runCommand(cmd, page, kwargs, debug) {
         return executePipeline(page, cmd.pipeline, { args: kwargs, debug });
     throw new Error(`Command ${fullName(cmd)} has no func or pipeline`);
 }
+/**
+ * Resolve the pre-navigation URL for a command, or null to skip.
+ *
+ * COOKIE/HEADER strategies need the browser on the target domain so
+ * `fetch(url, { credentials: 'include' })` carries cookies.
+ * Adapters that handle their own navigation set `navigateBefore: false`.
+ */
+function resolvePreNav(cmd) {
+    if (cmd.navigateBefore === false)
+        return null;
+    if (typeof cmd.navigateBefore === 'string')
+        return cmd.navigateBefore;
+    // Default: pre-navigate for COOKIE/HEADER strategies with a domain
+    if ((cmd.strategy === Strategy.COOKIE || cmd.strategy === Strategy.HEADER) && cmd.domain) {
+        return `https://${cmd.domain}`;
+    }
+    return null;
+}
 /**
  * Execute a CLI command. Automatically manages browser sessions when needed.
  *
@@ -105,15 +127,17 @@ export async function executeCommand(cmd, rawKwargs, debug = false) {
         kwargs = coerceAndValidateArgs(cmd.args, rawKwargs);
     }
     catch (err) {
-        throw new Error(`[Argument Validation Error]\n${err.message}`);
+        throw new Error(`[Argument Validation Error]\n${getErrorMessage(err)}`);
     }
     if (shouldUseBrowserSession(cmd)) {
         const BrowserFactory = getBrowserFactory();
         return browserSession(BrowserFactory, async (page) => {
-            // Cookie/header strategies require same-origin context for credentialed fetch.
-            if ((cmd.strategy === Strategy.COOKIE || cmd.strategy === Strategy.HEADER) && cmd.domain) {
+            // Pre-navigate to target domain for cookie/header context if needed.
+            // Each adapter controls this via `navigateBefore` (see CliCommand docs).
+            const preNavUrl = resolvePreNav(cmd);
+            if (preNavUrl) {
                 try {
-                    await page.goto(`https://${cmd.domain}`);
+                    await page.goto(preNavUrl);
                     await page.wait(2);
                 }
                 catch { }