@jackwener/opencli 1.3.3 → 1.4.0

package/src/generate.ts

@@ -12,30 +12,13 @@ import { exploreUrl } from './explore.js';
 import type { IBrowserFactory } from './runtime.js';
 import { synthesizeFromExplore, type SynthesizeCandidateSummary, type SynthesizeResult } from './synthesize.js';
 
-// Registration is a no-op stub — candidates are written to disk by synthesize,
-// but not yet auto-copied into the user clis dir.
-interface RegisterCandidatesOptions {
-  target: string;
-  builtinClis?: string;
-  userClis?: string;
-  name?: string;
-}
-
-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;
 }
 
@@ -57,11 +40,6 @@ export interface GenerateCliResult {
     candidate_count: number;
     candidates: Array<Pick<SynthesizeCandidateSummary, 'name' | 'strategy' | 'confidence'>>;
   };
-  register: RegisterCandidatesResult | null;
-}
-
-function registerCandidates(_opts: RegisterCandidatesOptions): RegisterCandidatesResult {
-  return { ok: true, count: 0 };
 }
 
 const CAPABILITY_ALIASES: Record<string, string[]> = {
@@ -102,9 +80,10 @@ function selectCandidate(candidates: SynthesizeResult['candidates'], goal?: stri
   }
 
   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];
 }
 
@@ -127,19 +106,6 @@ export async function generateCliFromUrl(opts: GenerateCliOptions): Promise<Gene
   const selected = selectCandidate(synthesizeResult.candidates ?? [], opts.goal);
   const selectedSite = synthesizeResult.site ?? exploreResult.site;
 
-  // Step 4: Register (if requested)
-  let registerResult: RegisterCandidatesResult | null = 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 {
@@ -164,7 +130,6 @@ export async function generateCliFromUrl(opts: GenerateCliOptions): Promise<Gene
         confidence: c.confidence,
       })),
     },
-    register: registerResult,
   };
 }
 
@@ -188,8 +153,6 @@ export function renderGenerateSummary(r: GenerateCliResult): string {
     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) lines.push(`Framework: ${fwNames.join(', ')}`);

package/src/hooks.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Tests for the plugin lifecycle hooks system.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  onStartup,
+  onBeforeExecute,
+  onAfterExecute,
+  emitHook,
+  clearAllHooks,
+  type HookContext,
+} from './hooks.js';
+
+beforeEach(() => {
+  clearAllHooks();
+});
+
+describe('hook registration and emission', () => {
+  it('onBeforeExecute hook is called with context', async () => {
+    const calls: HookContext[] = [];
+    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: unknown[] = [];
+    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: number[] = [];
+    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: string[] = [];
+    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: string[] = [];
+
+    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: string[] = [];
+
+    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/src/hooks.ts

@@ -0,0 +1,90 @@
+/**
+ * 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';
+
+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>;
+
+// ── Singleton hook store (shared across module instances via globalThis) ──
+declare global {
+  // eslint-disable-next-line no-var
+  var __opencli_hooks__: Map<HookName, HookFn[]> | undefined;
+}
+const _hooks: Map<HookName, HookFn[]> =
+  globalThis.__opencli_hooks__ ??= new Map();
+
+// ── Registration API (used by plugins) ─────────────────────────────────────
+
+function addHook(name: HookName, fn: HookFn): void {
+  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: HookFn): void {
+  addHook('onStartup', fn);
+}
+
+/** Register a hook that fires before every command execution. */
+export function onBeforeExecute(fn: HookFn): void {
+  addHook('onBeforeExecute', fn);
+}
+
+/** Register a hook that fires after every command execution with the result. */
+export function onAfterExecute(fn: HookFn): void {
+  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: HookName, ctx: HookContext, result?: unknown): Promise<void> {
+  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(): void {
+  _hooks.clear();
+}

package/src/interceptor.ts

@@ -9,6 +9,44 @@
  *   - 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`.
@@ -24,18 +62,24 @@ export function generateInterceptorJs(
   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);
@@ -47,28 +91,28 @@ export function generateInterceptorJs(
             } 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);
       }
     }
   `;
@@ -109,13 +153,19 @@ export function generateTapInterceptorJs(patternExpr: string): {
       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]
@@ -125,17 +175,17 @@ export function generateTapInterceptorJs(patternExpr: string): {
           }
         } 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 {}
@@ -143,7 +193,7 @@ export function generateTapInterceptorJs(patternExpr: string): {
           });
         }
         return origXhrSend.apply(this, arguments);
-      };
+      }, 'send');
     `,
     restorePatch: `
       window.fetch = origFetch;

package/src/main.ts

@@ -19,6 +19,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);
@@ -49,4 +50,5 @@ if (getCompIdx !== -1) {
   process.exit(0);
 }
 
+await emitHook('onStartup', { command: '__startup__', args: {} });
 runCli(BUILTIN_CLIS, USER_CLIS);

package/src/output.ts

@@ -15,6 +15,14 @@ export interface RenderOptions {
   footerExtra?: string;
 }
 
+function normalizeRows(data: unknown): Record<string, unknown>[] {
+  return Array.isArray(data) ? data : [data as Record<string, unknown>];
+}
+
+function resolveColumns(rows: Record<string, unknown>[], opts: RenderOptions): string[] {
+  return opts.columns ?? Object.keys(rows[0] ?? {});
+}
+
 export function render(data: unknown, opts: RenderOptions = {}): void {
   const fmt = opts.fmt ?? 'table';
   if (data === null || data === undefined) {
@@ -31,9 +39,9 @@ export function render(data: unknown, opts: RenderOptions = {}): void {
 }
 
 function renderTable(data: unknown, opts: RenderOptions): void {
-  const rows = Array.isArray(data) ? data : [data as Record<string, unknown>];
+  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({
@@ -66,9 +74,9 @@ function renderJson(data: unknown): void {
 }
 
 function renderMarkdown(data: unknown, opts: RenderOptions): void {
-  const rows = Array.isArray(data) ? data : [data as Record<string, unknown>];
+  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) {
@@ -77,9 +85,9 @@ function renderMarkdown(data: unknown, opts: RenderOptions): void {
 }
 
 function renderCsv(data: unknown, opts: RenderOptions): void {
-  const rows = Array.isArray(data) ? data : [data as Record<string, unknown>];
+  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/src/pipeline/executor.ts

@@ -16,7 +16,7 @@ export interface PipelineContext {
 }
 
 /** 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: IPage | null,

package/src/pipeline/steps/browser.ts

@@ -6,9 +6,7 @@
 import type { IPage } from '../../types.js';
 import { render } from '../template.js';
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
+import { isRecord } from '../../utils.js';
 
 export async function stepNavigate(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown> {
   if (isRecord(params) && 'url' in params) {