@jackwener/opencli 1.3.3 → 1.4.0

package/dist/hooks.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Plugin lifecycle hooks: allows plugins to tap into opencli's execution lifecycle.
+ *
+ * Hooks use globalThis (like the command registry) to guarantee a single shared
+ * instance across all module copies — critical when TS plugins are loaded via
+ * npm link / peerDependency symlinks.
+ *
+ * Available hooks:
+ *   onStartup        — fired once after all commands & plugins are discovered
+ *   onBeforeExecute  — fired before every command execution
+ *   onAfterExecute   — fired after every command execution (receives result)
+ */
+export type HookName = 'onStartup' | 'onBeforeExecute' | 'onAfterExecute';
+export interface HookContext {
+    /** Command full name in "site/name" format, or "__startup__" for onStartup */
+    command: string;
+    /** Coerced and validated arguments */
+    args: Record<string, unknown>;
+    /** Epoch ms when execution started (set by executeCommand) */
+    startedAt?: number;
+    /** Epoch ms when execution finished (set by executeCommand) */
+    finishedAt?: number;
+    /** Error thrown by the command, if execution failed */
+    error?: unknown;
+    /** Plugins can attach arbitrary data here for cross-hook communication */
+    [key: string]: unknown;
+}
+export type HookFn = (ctx: HookContext, result?: unknown) => void | Promise<void>;
+declare global {
+    var __opencli_hooks__: Map<HookName, HookFn[]> | undefined;
+}
+/** Register a hook that fires once after all plugins are discovered. */
+export declare function onStartup(fn: HookFn): void;
+/** Register a hook that fires before every command execution. */
+export declare function onBeforeExecute(fn: HookFn): void;
+/** Register a hook that fires after every command execution with the result. */
+export declare function onAfterExecute(fn: HookFn): void;
+/**
+ * Trigger all registered handlers for a hook.
+ * Each handler is wrapped in try/catch — a failing hook never blocks command execution.
+ */
+export declare function emitHook(name: HookName, ctx: HookContext, result?: unknown): Promise<void>;
+/**
+ * Remove all registered hooks. Intended for testing only.
+ */
+export declare function clearAllHooks(): void;

package/dist/hooks.js

@@ -0,0 +1,56 @@
+/**
+ * Plugin lifecycle hooks: allows plugins to tap into opencli's execution lifecycle.
+ *
+ * Hooks use globalThis (like the command registry) to guarantee a single shared
+ * instance across all module copies — critical when TS plugins are loaded via
+ * npm link / peerDependency symlinks.
+ *
+ * Available hooks:
+ *   onStartup        — fired once after all commands & plugins are discovered
+ *   onBeforeExecute  — fired before every command execution
+ *   onAfterExecute   — fired after every command execution (receives result)
+ */
+import { log } from './logger.js';
+const _hooks = globalThis.__opencli_hooks__ ??= new Map();
+// ── Registration API (used by plugins) ─────────────────────────────────────
+function addHook(name, fn) {
+    const list = _hooks.get(name) ?? [];
+    list.push(fn);
+    _hooks.set(name, list);
+}
+/** Register a hook that fires once after all plugins are discovered. */
+export function onStartup(fn) {
+    addHook('onStartup', fn);
+}
+/** Register a hook that fires before every command execution. */
+export function onBeforeExecute(fn) {
+    addHook('onBeforeExecute', fn);
+}
+/** Register a hook that fires after every command execution with the result. */
+export function onAfterExecute(fn) {
+    addHook('onAfterExecute', fn);
+}
+// ── Emit API (used internally by opencli core) ─────────────────────────────
+/**
+ * Trigger all registered handlers for a hook.
+ * Each handler is wrapped in try/catch — a failing hook never blocks command execution.
+ */
+export async function emitHook(name, ctx, result) {
+    const handlers = _hooks.get(name);
+    if (!handlers || handlers.length === 0)
+        return;
+    for (const fn of handlers) {
+        try {
+            await fn(ctx, result);
+        }
+        catch (err) {
+            log.warn(`Hook ${name} handler failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+/**
+ * Remove all registered hooks. Intended for testing only.
+ */
+export function clearAllHooks() {
+    _hooks.clear();
+}

package/dist/hooks.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for the plugin lifecycle hooks system.
+ */
+export {};

package/dist/hooks.test.js

@@ -0,0 +1,92 @@
+/**
+ * Tests for the plugin lifecycle hooks system.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { onStartup, onBeforeExecute, onAfterExecute, emitHook, clearAllHooks, } from './hooks.js';
+beforeEach(() => {
+    clearAllHooks();
+});
+describe('hook registration and emission', () => {
+    it('onBeforeExecute hook is called with context', async () => {
+        const calls = [];
+        onBeforeExecute((ctx) => { calls.push({ ...ctx }); });
+        await emitHook('onBeforeExecute', { command: 'test/cmd', args: { limit: 5 }, startedAt: 100 });
+        expect(calls).toHaveLength(1);
+        expect(calls[0].command).toBe('test/cmd');
+        expect(calls[0].args).toEqual({ limit: 5 });
+        expect(calls[0].startedAt).toBe(100);
+    });
+    it('onAfterExecute hook receives result', async () => {
+        const results = [];
+        onAfterExecute((_ctx, result) => { results.push(result); });
+        const mockResult = [{ title: 'item1' }, { title: 'item2' }];
+        await emitHook('onAfterExecute', { command: 'test/cmd', args: {} }, mockResult);
+        expect(results).toHaveLength(1);
+        expect(results[0]).toEqual(mockResult);
+    });
+    it('onStartup hook fires', async () => {
+        let fired = false;
+        onStartup(() => { fired = true; });
+        await emitHook('onStartup', { command: '__startup__', args: {} });
+        expect(fired).toBe(true);
+    });
+    it('multiple hooks on the same event fire in order', async () => {
+        const order = [];
+        onBeforeExecute(() => { order.push(1); });
+        onBeforeExecute(() => { order.push(2); });
+        onBeforeExecute(() => { order.push(3); });
+        await emitHook('onBeforeExecute', { command: 'test/cmd', args: {} });
+        expect(order).toEqual([1, 2, 3]);
+    });
+    it('async hooks are awaited', async () => {
+        const order = [];
+        onBeforeExecute(async () => {
+            await new Promise((r) => setTimeout(r, 10));
+            order.push('async-done');
+        });
+        onBeforeExecute(() => { order.push('sync'); });
+        await emitHook('onBeforeExecute', { command: 'test/cmd', args: {} });
+        expect(order).toEqual(['async-done', 'sync']);
+    });
+});
+describe('hook error isolation', () => {
+    it('failing hook does not prevent other hooks from running', async () => {
+        const calls = [];
+        onBeforeExecute(() => { calls.push('first'); });
+        onBeforeExecute(() => { throw new Error('boom'); });
+        onBeforeExecute(() => { calls.push('third'); });
+        await emitHook('onBeforeExecute', { command: 'test/cmd', args: {} });
+        // First and third should still run despite the second throwing
+        expect(calls).toEqual(['first', 'third']);
+    });
+    it('async hook rejection does not prevent other hooks', async () => {
+        const calls = [];
+        onAfterExecute(() => { calls.push('before-reject'); });
+        onAfterExecute(async () => { throw new Error('async boom'); });
+        onAfterExecute(() => { calls.push('after-reject'); });
+        await emitHook('onAfterExecute', { command: 'test/cmd', args: {} }, null);
+        expect(calls).toEqual(['before-reject', 'after-reject']);
+    });
+});
+describe('no-op when no hooks registered', () => {
+    it('emitHook with no registered hooks does nothing', async () => {
+        // Should not throw
+        await emitHook('onBeforeExecute', { command: 'test/cmd', args: {} });
+        await emitHook('onAfterExecute', { command: 'test/cmd', args: {} }, []);
+        await emitHook('onStartup', { command: '__startup__', args: {} });
+    });
+});
+describe('clearAllHooks', () => {
+    it('removes all hooks', async () => {
+        let called = false;
+        onStartup(() => { called = true; });
+        clearAllHooks();
+        await emitHook('onStartup', { command: '__startup__', args: {} });
+        expect(called).toBe(false);
+    });
+});
+describe('globalThis singleton', () => {
+    it('uses globalThis.__opencli_hooks__ for shared state', () => {
+        expect(globalThis.__opencli_hooks__).toBeInstanceOf(Map);
+    });
+});

package/dist/interceptor.js

@@ -8,6 +8,42 @@
  *   - stepIntercept              (pipeline/steps/intercept.ts)
  *   - stepTap                    (pipeline/steps/tap.ts)
  */
+/**
+ * Helper: define a non-enumerable property on window.
+ * Avoids detection via Object.keys(window) or for..in loops.
+ */
+const DEFINE_HIDDEN = `
+      function __defHidden(obj, key, val) {
+        try {
+          Object.defineProperty(obj, key, { value: val, writable: true, enumerable: false, configurable: true });
+        } catch { obj[key] = val; }
+      }`;
+/**
+ * Helper: disguise a patched function so toString() returns native code signature.
+ */
+const DISGUISE_FN = `
+      function __disguise(fn, name) {
+        const nativeStr = 'function ' + name + '() { [native code] }';
+        // Override toString on the instance AND patch Function.prototype.toString
+        // to handle Function.prototype.toString.call(fn) bypasses.
+        const _origToString = Function.prototype.toString;
+        const _patchedFns = window.__dFns || (function() {
+          const m = new Map();
+          Object.defineProperty(window, '__dFns', { value: m, enumerable: false, configurable: true });
+          // Patch Function.prototype.toString once to consult the map
+          Object.defineProperty(Function.prototype, 'toString', {
+            value: function() {
+              const override = m.get(this);
+              return override !== undefined ? override : _origToString.call(this);
+            },
+            writable: true, configurable: true
+          });
+          return m;
+        })();
+        _patchedFns.set(fn, nativeStr);
+        try { Object.defineProperty(fn, 'name', { value: name, configurable: true }); } catch {}
+        return fn;
+      }`;
 /**
  * Generate JavaScript source that installs a fetch/XHR interceptor.
  * Captured responses are pushed to `window.__opencli_intercepted`.
@@ -19,18 +55,23 @@
 export function generateInterceptorJs(patternExpr, opts = {}) {
     const arr = opts.arrayName ?? '__opencli_intercepted';
     const guard = opts.patchGuard ?? '__opencli_interceptor_patched';
+    // Store the current pattern in a separate global so it can be updated
+    // without re-patching fetch/XHR (the patchGuard only prevents double-patching).
+    const patternVar = `${guard}_pattern`;
     return `
     () => {
-      window.${arr} = window.${arr} || [];
-      window.${arr}_errors = window.${arr}_errors || [];
-      const __pattern = ${patternExpr};
+      ${DEFINE_HIDDEN}
+      ${DISGUISE_FN}
 
-      if (!window.${guard}) {
-        const __checkMatch = (url) => __pattern && url.includes(__pattern);
+      if (!window.${arr}) __defHidden(window, '${arr}', []);
+      if (!window.${arr}_errors) __defHidden(window, '${arr}_errors', []);
+      __defHidden(window, '${patternVar}', ${patternExpr});
+      const __checkMatch = (url) => window.${patternVar} && url.includes(window.${patternVar});
 
+      if (!window.${guard}) {
         // ── Patch fetch ──
         const __origFetch = window.fetch;
-        window.fetch = async function(...args) {
+        window.fetch = __disguise(async function(...args) {
           const reqUrl = typeof args[0] === 'string' ? args[0]
             : (args[0] && args[0].url) || '';
           const response = await __origFetch.apply(this, args);
@@ -42,28 +83,28 @@ export function generateInterceptorJs(patternExpr, opts = {}) {
             } catch(e) { window.${arr}_errors.push({ url: reqUrl, error: String(e) }); }
           }
           return response;
-        };
+        }, 'fetch');
 
         // ── Patch XMLHttpRequest ──
         const __XHR = XMLHttpRequest.prototype;
         const __origOpen = __XHR.open;
         const __origSend = __XHR.send;
-        __XHR.open = function(method, url) {
-          this.__opencli_url = String(url);
+        __XHR.open = __disguise(function(method, url) {
+          Object.defineProperty(this, '__iurl', { value: String(url), writable: true, enumerable: false, configurable: true });
           return __origOpen.apply(this, arguments);
-        };
-        __XHR.send = function() {
-          if (__checkMatch(this.__opencli_url)) {
+        }, 'open');
+        __XHR.send = __disguise(function() {
+          if (__checkMatch(this.__iurl)) {
             this.addEventListener('load', function() {
               try {
                 window.${arr}.push(JSON.parse(this.responseText));
-              } catch(e) { window.${arr}_errors.push({ url: this.__opencli_url, error: String(e) }); }
+              } catch(e) { window.${arr}_errors.push({ url: this.__iurl, error: String(e) }); }
             });
           }
           return __origSend.apply(this, arguments);
-        };
+        }, 'send');
 
-        window.${guard} = true;
+        __defHidden(window, '${guard}', true);
       }
     }
   `;
@@ -94,13 +135,19 @@ export function generateTapInterceptorJs(patternExpr) {
       let captureResolve;
       const capturePromise = new Promise(r => { captureResolve = r; });
       const capturePattern = ${patternExpr};
+      function __disguise(fn, name) {
+        const s = 'function ' + name + '() { [native code] }';
+        Object.defineProperty(fn, 'toString', { value: function() { return s; }, writable: true, configurable: true, enumerable: false });
+        try { Object.defineProperty(fn, 'name', { value: name, configurable: true }); } catch {}
+        return fn;
+      }
     `,
         capturedVar: 'captured',
         promiseVar: 'capturePromise',
         resolveVar: 'captureResolve',
         fetchPatch: `
       const origFetch = window.fetch;
-      window.fetch = async function(...fetchArgs) {
+      window.fetch = __disguise(async function(...fetchArgs) {
         const resp = await origFetch.apply(this, fetchArgs);
         try {
           const url = typeof fetchArgs[0] === 'string' ? fetchArgs[0]
@@ -110,17 +157,17 @@ export function generateTapInterceptorJs(patternExpr) {
           }
         } catch {}
         return resp;
-      };
+      }, 'fetch');
     `,
         xhrPatch: `
       const origXhrOpen = XMLHttpRequest.prototype.open;
       const origXhrSend = XMLHttpRequest.prototype.send;
-      XMLHttpRequest.prototype.open = function(method, url) {
-        this.__tapUrl = String(url);
+      XMLHttpRequest.prototype.open = __disguise(function(method, url) {
+        Object.defineProperty(this, '__iurl', { value: String(url), writable: true, enumerable: false, configurable: true });
         return origXhrOpen.apply(this, arguments);
-      };
-      XMLHttpRequest.prototype.send = function(body) {
-        if (capturePattern && this.__tapUrl?.includes(capturePattern)) {
+      }, 'open');
+      XMLHttpRequest.prototype.send = __disguise(function(body) {
+        if (capturePattern && this.__iurl?.includes(capturePattern)) {
           this.addEventListener('load', function() {
             if (!captured) {
               try { captured = JSON.parse(this.responseText); captureResolve(); } catch {}
@@ -128,7 +175,7 @@ export function generateTapInterceptorJs(patternExpr) {
           });
         }
         return origXhrSend.apply(this, arguments);
-      };
+      }, 'send');
     `,
         restorePatch: `
       window.fetch = origFetch;

package/dist/main.js

@@ -18,6 +18,7 @@ import { fileURLToPath } from 'node:url';
 import { discoverClis, discoverPlugins } from './discovery.js';
 import { getCompletions } from './completion.js';
 import { runCli } from './cli.js';
+import { emitHook } from './hooks.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const BUILTIN_CLIS = path.resolve(__dirname, 'clis');
@@ -46,4 +47,5 @@ if (getCompIdx !== -1) {
     process.stdout.write(candidates.join('\n') + '\n');
     process.exit(0);
 }
+await emitHook('onStartup', { command: '__startup__', args: {} });
 runCli(BUILTIN_CLIS, USER_CLIS);

package/dist/output.js

@@ -4,6 +4,12 @@
 import chalk from 'chalk';
 import Table from 'cli-table3';
 import yaml from 'js-yaml';
+function normalizeRows(data) {
+    return Array.isArray(data) ? data : [data];
+}
+function resolveColumns(rows, opts) {
+    return opts.columns ?? Object.keys(rows[0] ?? {});
+}
 export function render(data, opts = {}) {
     const fmt = opts.fmt ?? 'table';
     if (data === null || data === undefined) {
@@ -31,12 +37,12 @@ export function render(data, opts = {}) {
     }
 }
 function renderTable(data, opts) {
-    const rows = Array.isArray(data) ? data : [data];
+    const rows = normalizeRows(data);
     if (!rows.length) {
         console.log(chalk.dim('(no data)'));
         return;
     }
-    const columns = opts.columns ?? Object.keys(rows[0]);
+    const columns = resolveColumns(rows, opts);
     const header = columns.map(c => capitalize(c));
     const table = new Table({
         head: header.map(h => chalk.bold(h)),
@@ -68,10 +74,10 @@ function renderJson(data) {
     console.log(JSON.stringify(data, null, 2));
 }
 function renderMarkdown(data, opts) {
-    const rows = Array.isArray(data) ? data : [data];
+    const rows = normalizeRows(data);
     if (!rows.length)
         return;
-    const columns = opts.columns ?? Object.keys(rows[0]);
+    const columns = resolveColumns(rows, opts);
     console.log('| ' + columns.join(' | ') + ' |');
     console.log('| ' + columns.map(() => '---').join(' | ') + ' |');
     for (const row of rows) {
@@ -79,10 +85,10 @@ function renderMarkdown(data, opts) {
     }
 }
 function renderCsv(data, opts) {
-    const rows = Array.isArray(data) ? data : [data];
+    const rows = normalizeRows(data);
     if (!rows.length)
         return;
-    const columns = opts.columns ?? Object.keys(rows[0]);
+    const columns = resolveColumns(rows, opts);
     console.log(columns.join(','));
     for (const row of rows) {
         console.log(columns.map(c => {

package/dist/pipeline/executor.js

@@ -5,7 +5,7 @@ import { getStep } from './registry.js';
 import { log } from '../logger.js';
 import { ConfigError } from '../errors.js';
 /** Steps that interact with the browser and may fail transiently */
-const BROWSER_STEPS = new Set(['navigate', 'evaluate', 'click', 'type', 'press', 'wait', 'snapshot', 'scroll']);
+const BROWSER_STEPS = new Set(['navigate', 'evaluate', 'click', 'type', 'press', 'wait', 'snapshot']);
 export async function executePipeline(page, pipeline, ctx = {}) {
     const args = ctx.args ?? {};
     const debug = ctx.debug ?? false;

package/dist/pipeline/steps/browser.js

@@ -3,9 +3,7 @@
  * Browser interaction primitives.
  */
 import { render } from '../template.js';
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
+import { isRecord } from '../../utils.js';
 export async function stepNavigate(page, params, data, args) {
     if (isRecord(params) && 'url' in params) {
         const url = String(render(params.url, { args, data }));

package/dist/pipeline/steps/download.js

@@ -10,30 +10,16 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { render } from '../template.js';
+import { getErrorMessage } from '../../errors.js';
 import { httpDownload, ytdlpDownload, saveDocument, detectContentType, requiresYtdlp, sanitizeFilename, generateFilename, exportCookiesToNetscape, getTempDir, formatCookieHeader, } from '../../download/index.js';
 import { DownloadProgressTracker, formatBytes } from '../../download/progress.js';
-/**
- * Simple async concurrency limiter for downloads.
- */
-async function mapConcurrent(items, limit, fn) {
-    const results = new Array(items.length);
-    let index = 0;
-    async function worker() {
-        while (index < items.length) {
-            const i = index++;
-            results[i] = await fn(items[i], i);
-        }
-    }
-    const workers = Array.from({ length: Math.min(limit, items.length) }, () => worker());
-    await Promise.all(workers);
-    return results;
-}
+import { mapConcurrent } from '../../utils.js';
 /**
  * Extract cookies from browser page.
  */
 async function extractBrowserCookies(page, domain) {
     try {
-        const cookies = await page.getCookies(domain ? { domain } : {});
+        const cookies = await page.getCookies({ domain });
         return formatCookieHeader(cookies);
     }
     catch {
@@ -61,6 +47,13 @@ async function extractCookiesArray(page, domain) {
         return [];
     }
 }
+function dedupeCookies(cookies) {
+    const deduped = new Map();
+    for (const cookie of cookies) {
+        deduped.set(`${cookie.domain}\t${cookie.path}\t${cookie.name}`, cookie);
+    }
+    return [...deduped.values()];
+}
 /**
  * Download step handler for YAML pipelines.
  *
@@ -101,21 +94,28 @@ export async function stepDownload(page, params, data, args) {
     }
     // Create progress tracker
     const tracker = new DownloadProgressTracker(items.length, showProgress);
-    // Extract cookies if browser is available
-    let cookies = '';
+    // Cache cookie lookups per domain so mixed-domain batches stay isolated without repeated browser calls.
+    const cookieHeaderCache = new Map();
     let cookiesFile;
     if (page) {
-        cookies = await extractBrowserCookies(page);
         // For yt-dlp, we need to export cookies to Netscape format
         if (useYtdlp || items.some((item, index) => {
             const url = String(render(urlTemplate, { args, data, item, index }));
             return requiresYtdlp(url);
         })) {
             try {
-                // Try to get domain from first URL
-                const firstUrl = String(render(urlTemplate, { args, data, item: items[0], index: 0 }));
-                const domain = new URL(firstUrl).hostname;
-                const cookiesArray = await extractCookiesArray(page, domain);
+                const ytdlpDomains = [...new Set(items.flatMap((item, index) => {
+                        const url = String(render(urlTemplate, { args, data, item, index }));
+                        if (!useYtdlp && !requiresYtdlp(url))
+                            return [];
+                        try {
+                            return [new URL(url).hostname];
+                        }
+                        catch {
+                            return [];
+                        }
+                    }))];
+                const cookiesArray = dedupeCookies((await Promise.all(ytdlpDomains.map((domain) => extractCookiesArray(page, domain)))).flat());
                 if (cookiesArray.length > 0) {
                     const tempDir = getTempDir();
                     fs.mkdirSync(tempDir, { recursive: true });
@@ -199,6 +199,21 @@ export async function stepDownload(page, params, data, args) {
             }
             else {
                 // Direct HTTP download
+                let cookies = '';
+                if (page) {
+                    try {
+                        const targetDomain = new URL(url).hostname;
+                        let cookiePromise = cookieHeaderCache.get(targetDomain);
+                        if (!cookiePromise) {
+                            cookiePromise = extractBrowserCookies(page, targetDomain);
+                            cookieHeaderCache.set(targetDomain, cookiePromise);
+                        }
+                        cookies = await cookiePromise;
+                    }
+                    catch {
+                        cookies = '';
+                    }
+                }
                 result = await httpDownload(url, destPath, {
                     cookies,
                     timeout,
@@ -214,9 +229,10 @@ export async function stepDownload(page, params, data, args) {
             }
         }
         catch (err) {
-            result = { success: false, size: 0, error: err.message };
+            const msg = getErrorMessage(err);
+            result = { success: false, size: 0, error: msg };
             if (progressBar) {
-                progressBar.fail(err.message);
+                progressBar.fail(msg);
             }
         }
         tracker.onFileComplete(result.success);

package/dist/pipeline/steps/download.test.d.ts

@@ -0,0 +1 @@
+export {};