@jackwener/opencli 1.3.3 → 1.4.1

package/dist/discovery.js

@@ -17,16 +17,15 @@ import { getErrorMessage } from './errors.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*\(/;
+/** Matches files that register commands via cli() or lifecycle hooks */
+const PLUGIN_MODULE_PATTERN = /\b(?:cli|onStartup|onBeforeExecute|onAfterExecute)\s*\(/;
 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);
-}
+import { isRecord } from './utils.js';
 /**
  * Discover and register CLI commands.
  * Uses pre-compiled manifest when available for instant startup.
@@ -37,13 +36,14 @@ export async function discoverClis(...dirs) {
         const manifestPath = path.resolve(dir, '..', 'cli-manifest.json');
         try {
             await fs.promises.access(manifestPath);
-            await loadFromManifest(manifestPath, dir);
-            continue; // Skip filesystem scan for this directory
+            const loaded = await loadFromManifest(manifestPath, dir);
+            if (loaded)
+                continue; // Skip filesystem scan only when manifest is usable
         }
         catch {
-            // Fallback: runtime filesystem scan (development)
-            await discoverClisFromFs(dir);
+            // Fall through to filesystem scan
         }
+        await discoverClisFromFs(dir);
     }
 }
 /**
@@ -98,9 +98,11 @@ async function loadFromManifest(manifestPath, clisDir) {
                 registerCommand(cmd);
             }
         }
+        return true;
     }
     catch (err) {
         log.warn(`Failed to load manifest ${manifestPath}: ${getErrorMessage(err)}`);
+        return false;
     }
 }
 /**
@@ -113,7 +115,6 @@ async function discoverClisFromFs(dir) {
     catch {
         return;
     }
-    const promises = [];
     const entries = await fs.promises.readdir(dir, { withFileTypes: true });
     const sitePromises = entries
         .filter(entry => entry.isDirectory())
@@ -242,7 +243,7 @@ async function discoverPluginDir(dir, site) {
 async function isCliModule(filePath) {
     try {
         const source = await fs.promises.readFile(filePath, 'utf-8');
-        return CLI_MODULE_PATTERN.test(source);
+        return PLUGIN_MODULE_PATTERN.test(source);
     }
     catch (err) {
         log.warn(`Failed to inspect module ${filePath}: ${getErrorMessage(err)}`);

package/dist/doctor.js

@@ -9,6 +9,7 @@ import { DEFAULT_DAEMON_PORT } from './constants.js';
 import { checkDaemonStatus } from './browser/discover.js';
 import { BrowserBridge } from './browser/index.js';
 import { listSessions } from './browser/daemon-client.js';
+import { getErrorMessage } from './errors.js';
 /**
  * Test connectivity by attempting a real browser command.
  */
@@ -23,7 +24,7 @@ export async function checkConnectivity(opts) {
         return { ok: true, durationMs: Date.now() - start };
     }
     catch (err) {
-        return { ok: false, error: err?.message ?? String(err), durationMs: Date.now() - start };
+        return { ok: false, error: getErrorMessage(err), durationMs: Date.now() - start };
     }
 }
 export async function runBrowserDoctor(opts = {}) {

package/dist/download/index.d.ts

@@ -1,11 +1,14 @@
 /**
  * Download utilities: HTTP downloads, yt-dlp wrapper, format conversion.
  */
+import type { BrowserCookie } from '../types.js';
+export type { BrowserCookie } from '../types.js';
 export interface DownloadOptions {
     cookies?: string;
     headers?: Record<string, string>;
     timeout?: number;
     onProgress?: (received: number, total: number) => void;
+    maxRedirects?: number;
 }
 export interface YtdlpOptions {
     cookies?: string;
@@ -14,19 +17,8 @@ export interface YtdlpOptions {
     extraArgs?: string[];
     onProgress?: (percent: number) => void;
 }
-export interface BrowserCookie {
-    name: string;
-    value: string;
-    domain: string;
-    path?: string;
-    secure?: boolean;
-    httpOnly?: boolean;
-    expirationDate?: number;
-}
 /** Check if yt-dlp is available in PATH. */
 export declare function checkYtdlp(): boolean;
-/** Check if ffmpeg is available in PATH. */
-export declare function checkFfmpeg(): boolean;
 /**
  * Detect content type from URL and optional headers.
  */
@@ -38,7 +30,7 @@ export declare function requiresYtdlp(url: string): boolean;
 /**
  * HTTP download with progress callback.
  */
-export declare function httpDownload(url: string, destPath: string, options?: DownloadOptions): Promise<{
+export declare function httpDownload(url: string, destPath: string, options?: DownloadOptions, redirectCount?: number): Promise<{
     success: boolean;
     size: number;
     error?: string;

package/dist/download/index.js

@@ -9,14 +9,11 @@ import * as http from 'node:http';
 import * as os from 'node:os';
 import { URL } from 'node:url';
 import { isBinaryInstalled } from '../external.js';
+import { getErrorMessage } from '../errors.js';
 /** Check if yt-dlp is available in PATH. */
 export function checkYtdlp() {
     return isBinaryInstalled('yt-dlp');
 }
-/** Check if ffmpeg is available in PATH. */
-export function checkFfmpeg() {
-    return isBinaryInstalled('ffmpeg');
-}
 /** Domains that host video content and can be downloaded via yt-dlp. */
 const VIDEO_PLATFORM_DOMAINS = [
     'youtube.com', 'youtu.be', 'bilibili.com', 'twitter.com',
@@ -59,13 +56,13 @@ export function requiresYtdlp(url) {
 /**
  * HTTP download with progress callback.
  */
-export async function httpDownload(url, destPath, options = {}) {
-    const { cookies, headers = {}, timeout = 30000, onProgress } = options;
+export async function httpDownload(url, destPath, options = {}, redirectCount = 0) {
+    const { cookies, headers = {}, timeout = 30000, onProgress, maxRedirects = 10 } = options;
     return new Promise((resolve) => {
         const parsedUrl = new URL(url);
         const protocol = parsedUrl.protocol === 'https:' ? https : http;
         const requestHeaders = {
-            'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+            'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36',
             ...headers,
         };
         if (cookies) {
@@ -82,7 +79,18 @@ export async function httpDownload(url, destPath, options = {}) {
                 file.close();
                 if (fs.existsSync(tempPath))
                     fs.unlinkSync(tempPath);
-                httpDownload(resolveRedirectUrl(url, response.headers.location), destPath, options).then(resolve);
+                if (redirectCount >= maxRedirects) {
+                    resolve({ success: false, size: 0, error: `Too many redirects (> ${maxRedirects})` });
+                    return;
+                }
+                const redirectUrl = resolveRedirectUrl(url, response.headers.location);
+                const originalHost = new URL(url).hostname;
+                const redirectHost = new URL(redirectUrl).hostname;
+                // Do not forward cookies when a redirect crosses host boundaries.
+                const redirectOptions = originalHost === redirectHost
+                    ? options
+                    : { ...options, cookies: undefined, headers: stripCookieHeaders(options.headers) };
+                httpDownload(redirectUrl, destPath, redirectOptions, redirectCount + 1).then(resolve);
                 return;
             }
             if (response.statusCode !== 200) {
@@ -125,6 +133,11 @@ export async function httpDownload(url, destPath, options = {}) {
 export function resolveRedirectUrl(currentUrl, location) {
     return new URL(location, currentUrl).toString();
 }
+function stripCookieHeaders(headers) {
+    if (!headers)
+        return headers;
+    return Object.fromEntries(Object.entries(headers).filter(([key]) => key.toLowerCase() !== 'cookie'));
+}
 /**
  * Export cookies to Netscape format for yt-dlp.
  */
@@ -141,7 +154,9 @@ export function exportCookiesToNetscape(cookies, filePath) {
         const cookiePath = cookie.path || '/';
         const secure = cookie.secure ? 'TRUE' : 'FALSE';
         const expiry = Math.floor(Date.now() / 1000) + 86400 * 365; // 1 year from now
-        lines.push(`${domain}\t${includeSubdomains}\t${cookiePath}\t${secure}\t${expiry}\t${cookie.name}\t${cookie.value}`);
+        const safeName = cookie.name.replace(/[\t\n\r]/g, '');
+        const safeValue = cookie.value.replace(/[\t\n\r]/g, '');
+        lines.push(`${domain}\t${includeSubdomains}\t${cookiePath}\t${secure}\t${expiry}\t${safeName}\t${safeValue}`);
     }
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     fs.writeFileSync(filePath, lines.join('\n'));
@@ -168,8 +183,14 @@ export async function ytdlpDownload(url, destPath, options = {}) {
             '--no-playlist',
             '--progress',
         ];
-        if (cookiesFile && fs.existsSync(cookiesFile)) {
-            args.push('--cookies', cookiesFile);
+        if (cookiesFile) {
+            if (fs.existsSync(cookiesFile)) {
+                args.push('--cookies', cookiesFile);
+            }
+            else {
+                console.error(`[download] Cookies file not found: ${cookiesFile}, falling back to browser cookies`);
+                args.push('--cookies-from-browser', 'chrome');
+            }
         }
         else {
             // Try to use browser cookies
@@ -251,7 +272,7 @@ export async function saveDocument(content, destPath, format = 'markdown', metad
         return { success: true, size: Buffer.byteLength(output, 'utf-8') };
     }
     catch (err) {
-        return { success: false, size: 0, error: err.message };
+        return { success: false, size: 0, error: getErrorMessage(err) };
     }
 }
 /**

package/dist/download/index.test.js

@@ -1,5 +1,26 @@
-import { describe, expect, it } from 'vitest';
-import { formatCookieHeader, resolveRedirectUrl } from './index.js';
+import * as fs from 'node:fs';
+import * as http from 'node:http';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { formatCookieHeader, httpDownload, resolveRedirectUrl } from './index.js';
+const servers = [];
+afterEach(async () => {
+    await Promise.all(servers.map((server) => new Promise((resolve, reject) => {
+        server.close((err) => (err ? reject(err) : resolve()));
+    })));
+    servers.length = 0;
+});
+async function startServer(handler, hostname = '127.0.0.1') {
+    const server = http.createServer(handler);
+    servers.push(server);
+    await new Promise((resolve) => server.listen(0, hostname, resolve));
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+        throw new Error('Failed to start test server');
+    }
+    return `http://${hostname}:${address.port}`;
+}
 describe('download helpers', () => {
     it('resolves relative redirects against the original URL', () => {
         expect(resolveRedirectUrl('https://example.com/a/file', '/cdn/file.bin')).toBe('https://example.com/cdn/file.bin');
@@ -11,4 +32,60 @@ describe('download helpers', () => {
             { name: 'ct0', value: 'def', domain: 'example.com' },
         ])).toBe('sid=abc; ct0=def');
     });
+    it('fails after exceeding the redirect limit', async () => {
+        const baseUrl = await startServer((_req, res) => {
+            res.statusCode = 302;
+            res.setHeader('Location', '/loop');
+            res.end();
+        });
+        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-download-'));
+        const destPath = path.join(tempDir, 'file.txt');
+        const result = await httpDownload(`${baseUrl}/loop`, destPath, { maxRedirects: 2 });
+        expect(result).toEqual({
+            success: false,
+            size: 0,
+            error: 'Too many redirects (> 2)',
+        });
+        expect(fs.existsSync(destPath)).toBe(false);
+    });
+    it('does not forward cookies across cross-domain redirects', async () => {
+        let forwardedCookie;
+        const targetUrl = await startServer((req, res) => {
+            forwardedCookie = req.headers.cookie;
+            res.statusCode = 200;
+            res.end('ok');
+        }, 'localhost');
+        const redirectUrl = await startServer((_req, res) => {
+            res.statusCode = 302;
+            res.setHeader('Location', targetUrl);
+            res.end();
+        });
+        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-download-'));
+        const destPath = path.join(tempDir, 'redirect.txt');
+        const result = await httpDownload(`${redirectUrl}/start`, destPath, { cookies: 'sid=abc' });
+        expect(result).toEqual({ success: true, size: 2 });
+        expect(forwardedCookie).toBeUndefined();
+        expect(fs.readFileSync(destPath, 'utf8')).toBe('ok');
+    });
+    it('does not forward cookie headers across cross-domain redirects', async () => {
+        let forwardedCookie;
+        const targetUrl = await startServer((req, res) => {
+            forwardedCookie = req.headers.cookie;
+            res.statusCode = 200;
+            res.end('ok');
+        }, 'localhost');
+        const redirectUrl = await startServer((_req, res) => {
+            res.statusCode = 302;
+            res.setHeader('Location', targetUrl);
+            res.end();
+        });
+        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-download-'));
+        const destPath = path.join(tempDir, 'redirect-header.txt');
+        const result = await httpDownload(`${redirectUrl}/start`, destPath, {
+            headers: { Cookie: 'sid=header-cookie' },
+        });
+        expect(result).toEqual({ success: true, size: 2 });
+        expect(forwardedCookie).toBeUndefined();
+        expect(fs.readFileSync(destPath, 'utf8')).toBe('ok');
+    });
 });

package/dist/download/media-download.js

@@ -8,6 +8,7 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { getErrorMessage } from '../errors.js';
 import { httpDownload, ytdlpDownload, checkYtdlp, getTempDir, exportCookiesToNetscape, } from './index.js';
 import { DownloadProgressTracker, formatBytes } from './progress.js';
 // ============================================================
@@ -89,14 +90,15 @@ export async function downloadMedia(items, options) {
                 });
             }
             catch (err) {
+                const msg = getErrorMessage(err);
                 if (progressBar)
-                    progressBar.fail(err.message);
+                    progressBar.fail(msg);
                 tracker.onFileComplete(false);
                 results.push({
                     index: i + 1,
                     type: media.type,
                     status: 'failed',
-                    size: err.message,
+                    size: msg,
                 });
             }
         }

package/dist/engine.test.js

@@ -1,16 +1,19 @@
-import { describe, it, expect, afterEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { discoverClis, discoverPlugins, PLUGINS_DIR } from './discovery.js';
 import { executeCommand } from './execution.js';
 import { getRegistry, cli, Strategy } from './registry.js';
+import { clearAllHooks, onAfterExecute } from './hooks.js';
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
 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();
+        await expect(discoverClis(path.join(os.tmpdir(), '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 tempRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-discovery-'));
         const siteDir = path.join(tempRoot, 'temp-site');
         const helperPath = path.join(siteDir, 'helper.ts');
         const commandPath = path.join(siteDir, 'hello.ts');
@@ -21,7 +24,7 @@ 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')}';
+import { cli, Strategy } from '${pathToFileURL(path.join(process.cwd(), 'src', 'registry.ts')).href}';
 cli({
   site: 'temp-site',
   name: 'hello',
@@ -41,6 +44,33 @@ cli({
             await fs.promises.rm(tempRoot, { recursive: true, force: true });
         }
     });
+    it('falls back to filesystem discovery when the manifest is invalid', async () => {
+        const tempBuildRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-manifest-fallback-'));
+        const distDir = path.join(tempBuildRoot, 'dist');
+        const siteDir = path.join(distDir, 'fallback-site');
+        const commandPath = path.join(siteDir, 'hello.ts');
+        const manifestPath = path.join(tempBuildRoot, 'cli-manifest.json');
+        try {
+            await fs.promises.mkdir(siteDir, { recursive: true });
+            await fs.promises.writeFile(manifestPath, '{ invalid json');
+            await fs.promises.writeFile(commandPath, `
+import { cli, Strategy } from '${pathToFileURL(path.join(process.cwd(), 'src', 'registry.ts')).href}';
+cli({
+  site: 'fallback-site',
+  name: 'hello',
+  description: 'hello command',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  func: async () => [{ ok: true }],
+});
+`);
+            await discoverClis(distDir);
+            expect(getRegistry().get('fallback-site/hello')).toBeDefined();
+        }
+        finally {
+            await fs.promises.rm(tempBuildRoot, { recursive: true, force: true });
+        }
+    });
 });
 describe('discoverPlugins', () => {
     const testPluginDir = path.join(PLUGINS_DIR, '__test-plugin__');
@@ -80,6 +110,10 @@ columns: [message]
     });
 });
 describe('executeCommand', () => {
+    beforeEach(() => {
+        clearAllHooks();
+        vi.unstubAllEnvs();
+    });
     it('accepts kebab-case option names after Commander camelCases them', async () => {
         const cmd = cli({
             site: 'test-engine',
@@ -148,4 +182,42 @@ describe('executeCommand', () => {
         await executeCommand(cmd, {}, true);
         expect(receivedDebug).toBe(true);
     });
+    it('fires onAfterExecute even when command execution throws', async () => {
+        const seen = [];
+        onAfterExecute((ctx) => {
+            seen.push({ error: ctx.error, finishedAt: ctx.finishedAt });
+        });
+        const cmd = cli({
+            site: 'test-engine',
+            name: 'failing-test',
+            description: 'failing command',
+            browser: false,
+            strategy: Strategy.PUBLIC,
+            func: async () => {
+                throw new Error('boom');
+            },
+        });
+        await expect(executeCommand(cmd, {})).rejects.toThrow('boom');
+        expect(seen).toHaveLength(1);
+        expect(seen[0].error).toBeInstanceOf(Error);
+        expect(seen[0].error.message).toBe('boom');
+        expect(typeof seen[0].finishedAt).toBe('number');
+    });
+    it('fails fast for chatwise commands when OPENCLI_CDP_ENDPOINT is missing', async () => {
+        const cmd = cli({
+            site: 'chatwise',
+            name: 'status',
+            description: 'chatwise status',
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            requiredEnv: [
+                {
+                    name: 'OPENCLI_CDP_ENDPOINT',
+                    help: 'Set OPENCLI_CDP_ENDPOINT before running chatwise commands.',
+                },
+            ],
+            func: async () => [{ ok: true }],
+        });
+        await expect(executeCommand(cmd, {})).rejects.toThrow('requires environment variable OPENCLI_CDP_ENDPOINT');
+    });
 });

package/dist/execution.d.ts

@@ -7,18 +7,10 @@
  * 3. Domain pre-navigation for cookie/header strategies
  * 4. Timeout enforcement
  * 5. Lazy-loading of TS modules from manifest
+ * 6. Lifecycle hooks (onBeforeExecute / onAfterExecute)
  */
 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: 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: CommandArgs, debug?: boolean): Promise<unknown>;
 export {};

package/dist/execution.js

@@ -7,6 +7,7 @@
  * 3. Domain pre-navigation for cookie/header strategies
  * 4. Timeout enforcement
  * 5. Lazy-loading of TS modules from manifest
+ * 6. Lifecycle hooks (onBeforeExecute / onAfterExecute)
  */
 import { Strategy, getRegistry, fullName } from './registry.js';
 import { pathToFileURL } from 'node:url';
@@ -14,21 +15,16 @@ import { executePipeline } from './pipeline/index.js';
 import { AdapterLoadError, ArgumentError, CommandExecutionError, getErrorMessage } 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 */
+import { emitHook } from './hooks.js';
 const _loadedModules = new Set();
-/**
- * Validates and coerces arguments based on the command's Arg definitions.
- */
 export function coerceAndValidateArgs(cmdArgs, kwargs) {
     const result = { ...kwargs };
     for (const argDef of cmdArgs) {
         const val = result[argDef.name];
-        // 1. Check required
         if (argDef.required && (val === undefined || val === null || val === '')) {
             throw new ArgumentError(`Argument "${argDef.name}" is required.`, argDef.help ?? `Provide a value for --${argDef.name}`);
         }
         if (val !== undefined && val !== null) {
-            // 2. Type coercion
             if (argDef.type === 'int' || argDef.type === 'number') {
                 const num = Number(val);
                 if (Number.isNaN(num)) {
@@ -50,7 +46,6 @@ export function coerceAndValidateArgs(cmdArgs, kwargs) {
                     result[argDef.name] = Boolean(val);
                 }
             }
-            // 3. Choices validation
             const coercedVal = result[argDef.name];
             if (argDef.choices && argDef.choices.length > 0) {
                 if (!argDef.choices.map(String).includes(String(coercedVal))) {
@@ -64,11 +59,7 @@ export function coerceAndValidateArgs(cmdArgs, kwargs) {
     }
     return result;
 }
-/**
- * Run a command's func or pipeline against a page.
- */
 async function runCommand(cmd, page, kwargs, debug) {
-    // Lazy-load TS module on first execution (manifest fast-path)
     const internal = cmd;
     if (internal._lazy && internal._modulePath) {
         const modulePath = internal._modulePath;
@@ -81,10 +72,13 @@ async function runCommand(cmd, page, kwargs, debug) {
                 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.
         const updated = getRegistry().get(fullName(cmd));
-        if (updated?.func)
+        if (updated?.func) {
+            if (!page && updated.browser !== false) {
+                throw new CommandExecutionError(`Command ${fullName(cmd)} requires a browser session but none was provided`);
+            }
             return updated.func(page, kwargs, debug);
+        }
         if (updated?.pipeline)
             return executePipeline(page, updated.pipeline, { args: kwargs, debug });
     }
@@ -94,30 +88,25 @@ async function runCommand(cmd, page, kwargs, debug) {
         return executePipeline(page, cmd.pipeline, { args: kwargs, debug });
     throw new CommandExecutionError(`Command ${fullName(cmd)} has no func or pipeline`, 'This is likely a bug in the adapter definition. Please report this issue.');
 }
-/**
- * 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.
- *
- * This is the unified entry point — callers don't need to care about
- * whether the command requires a browser or not.
- */
+function ensureRequiredEnv(cmd) {
+    const missing = (cmd.requiredEnv ?? []).find(({ name }) => {
+        const value = process.env[name];
+        return value === undefined || value === null || value === '';
+    });
+    if (!missing)
+        return;
+    throw new CommandExecutionError(`Command ${fullName(cmd)} requires environment variable ${missing.name}.`, missing.help ?? `Set ${missing.name} before running ${fullName(cmd)}.`);
+}
 export async function executeCommand(cmd, rawKwargs, debug = false) {
     let kwargs;
     try {
@@ -128,25 +117,46 @@ export async function executeCommand(cmd, rawKwargs, debug = false) {
             throw err;
         throw new ArgumentError(getErrorMessage(err));
     }
-    if (shouldUseBrowserSession(cmd)) {
-        const BrowserFactory = getBrowserFactory();
-        return browserSession(BrowserFactory, async (page) => {
-            // 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(preNavUrl);
-                    await page.wait(2);
+    const hookCtx = {
+        command: fullName(cmd),
+        args: kwargs,
+        startedAt: Date.now(),
+    };
+    await emitHook('onBeforeExecute', hookCtx);
+    let result;
+    try {
+        if (shouldUseBrowserSession(cmd)) {
+            ensureRequiredEnv(cmd);
+            const BrowserFactory = getBrowserFactory();
+            result = await browserSession(BrowserFactory, async (page) => {
+                const preNavUrl = resolvePreNav(cmd);
+                if (preNavUrl) {
+                    try {
+                        await page.goto(preNavUrl);
+                        await page.wait(2);
+                    }
+                    catch (err) {
+                        if (debug)
+                            console.error(`[pre-nav] Failed to navigate to ${preNavUrl}: ${err instanceof Error ? err.message : err}`);
+                    }
                 }
-                catch { }
-            }
-            return runWithTimeout(runCommand(cmd, page, kwargs, debug), {
-                timeout: cmd.timeoutSeconds ?? DEFAULT_BROWSER_COMMAND_TIMEOUT,
-                label: fullName(cmd),
-            });
-        }, { workspace: `site:${cmd.site}` });
+                return runWithTimeout(runCommand(cmd, page, kwargs, debug), {
+                    timeout: cmd.timeoutSeconds ?? DEFAULT_BROWSER_COMMAND_TIMEOUT,
+                    label: fullName(cmd),
+                });
+            }, { workspace: `site:${cmd.site}` });
+        }
+        else {
+            result = await runCommand(cmd, null, kwargs, debug);
+        }
     }
-    // Non-browser commands run directly
-    return runCommand(cmd, null, kwargs, debug);
+    catch (err) {
+        hookCtx.error = err;
+        hookCtx.finishedAt = Date.now();
+        await emitHook('onAfterExecute', hookCtx);
+        throw err;
+    }
+    hookCtx.finishedAt = Date.now();
+    await emitHook('onAfterExecute', hookCtx, result);
+    return result;
 }