@jackwener/opencli 1.3.2 → 1.4.0

package/dist/external.test.js

@@ -25,6 +25,10 @@ describe('parseCommand', () => {
     it('rejects shell operators', () => {
         expect(() => parseCommand('brew install gh && rm -rf /')).toThrow('Install command contains unsafe shell operators');
     });
+    it('rejects command substitution and multiline input', () => {
+        expect(() => parseCommand('brew install $(whoami)')).toThrow('Install command contains unsafe shell operators');
+        expect(() => parseCommand('brew install gh\nrm -rf /')).toThrow('Install command contains unsafe shell operators');
+    });
 });
 describe('installExternalCli', () => {
     const cli = {

package/dist/generate.d.ts

@@ -9,20 +9,13 @@
  */
 import type { IBrowserFactory } from './runtime.js';
 import { type SynthesizeCandidateSummary } from './synthesize.js';
-interface RegisterCandidatesResult {
-    ok: boolean;
-    count: number;
-}
 export interface GenerateCliOptions {
     url: string;
     BrowserFactory: new () => IBrowserFactory;
-    builtinClis?: string;
-    userClis?: string;
     goal?: string | null;
     site?: string;
     waitSeconds?: number;
     top?: number;
-    register?: boolean;
     workspace?: string;
 }
 export interface GenerateCliResult {
@@ -43,8 +36,6 @@ export interface GenerateCliResult {
         candidate_count: number;
         candidates: Array<Pick<SynthesizeCandidateSummary, 'name' | 'strategy' | 'confidence'>>;
     };
-    register: RegisterCandidatesResult | null;
 }
 export declare function generateCliFromUrl(opts: GenerateCliOptions): Promise<GenerateCliResult>;
 export declare function renderGenerateSummary(r: GenerateCliResult): string;
-export {};

package/dist/generate.js

@@ -9,9 +9,6 @@
  */
 import { exploreUrl } from './explore.js';
 import { synthesizeFromExplore } from './synthesize.js';
-function registerCandidates(_opts) {
-    return { ok: true, count: 0 };
-}
 const CAPABILITY_ALIASES = {
     search: ['search', '搜索', '查找', 'query', 'keyword'],
     hot: ['hot', '热门', '热榜', '热搜', 'popular', 'top', 'ranking'],
@@ -51,7 +48,10 @@ function selectCandidate(candidates, goal) {
             return exact;
     }
     const lower = (goal ?? '').trim().toLowerCase();
-    const partial = candidates.find(c => c.name?.toLowerCase().includes(lower) || lower.includes(c.name?.toLowerCase()));
+    const partial = candidates.find(c => {
+        const cName = c.name?.toLowerCase() ?? '';
+        return cName.includes(lower) || lower.includes(cName);
+    });
     return partial ?? candidates[0];
 }
 export async function generateCliFromUrl(opts) {
@@ -70,19 +70,6 @@ export async function generateCliFromUrl(opts) {
     // Step 3: Select best candidate for goal
     const selected = selectCandidate(synthesizeResult.candidates ?? [], opts.goal);
     const selectedSite = synthesizeResult.site ?? exploreResult.site;
-    // Step 4: Register (if requested)
-    let registerResult = null;
-    if (opts.register !== false && synthesizeResult.candidate_count > 0) {
-        try {
-            registerResult = registerCandidates({
-                target: synthesizeResult.out_dir,
-                builtinClis: opts.builtinClis,
-                userClis: opts.userClis,
-                name: selected?.name,
-            });
-        }
-        catch { }
-    }
     const ok = exploreResult.endpoint_count > 0 && synthesizeResult.candidate_count > 0;
     return {
         ok,
@@ -106,7 +93,6 @@ export async function generateCliFromUrl(opts) {
                 confidence: c.confidence,
             })),
         },
-        register: registerResult,
     };
 }
 export function renderGenerateSummary(r) {
@@ -127,8 +113,6 @@ export function renderGenerateSummary(r) {
     for (const c of r.synthesize?.candidates ?? []) {
         lines.push(`    • ${c.name} (${c.strategy}, ${((c.confidence ?? 0) * 100).toFixed(0)}%)`);
     }
-    if (r.register)
-        lines.push(`\nRegistered: ${r.register.count ?? 0}`);
     const fw = r.explore?.framework ?? {};
     const fwNames = Object.entries(fw).filter(([, v]) => v).map(([k]) => k);
     if (fwNames.length)

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 }));