@jackwener/opencli 1.1.0 → 1.2.0

package/scripts/copy-yaml.cjs

@@ -19,3 +19,10 @@ function walk(src, dst) {
 }
 
 walk('src/clis', 'dist/clis');
+
+// Copy external CLI registry to dist/
+const extSrc = 'src/external-clis.yaml';
+if (existsSync(extSrc)) {
+  mkdirSync('dist', { recursive: true });
+  copyFileSync(extSrc, 'dist/external-clis.yaml');
+}

package/src/browser/cdp.ts

@@ -9,8 +9,9 @@
  */
 
 import { WebSocket, type RawData } from 'ws';
-import type { IPage } from '../types.js';
+import type { BrowserCookie, IPage, ScreenshotOptions, SnapshotOptions, WaitOptions } from '../types.js';
 import { wrapForEval } from './utils.js';
+import { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
 import {
   clickJs,
   typeTextJs,
@@ -28,13 +29,24 @@ export interface CDPTarget {
   webSocketDebuggerUrl?: string;
 }
 
+interface RuntimeEvaluateResult {
+  result?: {
+    value?: unknown;
+  };
+  exceptionDetails?: {
+    exception?: {
+      description?: string;
+    };
+  };
+}
+
 const CDP_SEND_TIMEOUT = 30_000; // 30s per command
 
 export class CDPBridge {
   private _ws: WebSocket | null = null;
   private _idCounter = 0;
-  private _pending = new Map<number, { resolve: (val: any) => void; reject: (err: Error) => void; timer: ReturnType<typeof setTimeout> }>();
-  private _eventListeners = new Map<string, Set<(params: any) => void>>();
+  private _pending = new Map<number, { resolve: (val: unknown) => void; reject: (err: Error) => void; timer: ReturnType<typeof setTimeout> }>();
+  private _eventListeners = new Map<string, Set<(params: unknown) => void>>();
 
   async connect(opts?: { timeout?: number; workspace?: string }): Promise<IPage> {
     const endpoint = process.env.OPENCLI_CDP_ENDPOINT;
@@ -55,7 +67,8 @@ export class CDPBridge {
 
     return new Promise((resolve, reject) => {
       const ws = new WebSocket(wsUrl);
-      const timeout = setTimeout(() => reject(new Error('CDP connect timeout')), opts?.timeout ?? 10000);
+      const timeoutMs = (opts?.timeout ?? 10) * 1000; // opts.timeout is in seconds
+      const timeout = setTimeout(() => reject(new Error('CDP connect timeout')), timeoutMs);
 
       ws.on('open', () => {
         clearTimeout(timeout);
@@ -110,7 +123,7 @@ export class CDPBridge {
   }
 
   /** Send a CDP command with timeout guard (P0 fix #4) */
-  async send(method: string, params: any = {}, timeoutMs: number = CDP_SEND_TIMEOUT): Promise<any> {
+  async send(method: string, params: Record<string, unknown> = {}, timeoutMs: number = CDP_SEND_TIMEOUT): Promise<unknown> {
     if (!this._ws || this._ws.readyState !== WebSocket.OPEN) {
       throw new Error('CDP connection is not open');
     }
@@ -126,25 +139,25 @@ export class CDPBridge {
   }
 
   /** Listen for a CDP event */
-  on(event: string, handler: (params: any) => void): void {
+  on(event: string, handler: (params: unknown) => void): void {
     let set = this._eventListeners.get(event);
     if (!set) { set = new Set(); this._eventListeners.set(event, set); }
     set.add(handler);
   }
 
   /** Remove a CDP event listener */
-  off(event: string, handler: (params: any) => void): void {
+  off(event: string, handler: (params: unknown) => void): void {
     this._eventListeners.get(event)?.delete(handler);
   }
 
   /** Wait for a CDP event to fire (one-shot) */
-  waitForEvent(event: string, timeoutMs: number = 15_000): Promise<any> {
+  waitForEvent(event: string, timeoutMs: number = 15_000): Promise<unknown> {
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         this.off(event, handler);
         reject(new Error(`Timed out waiting for CDP event '${event}'`));
       }, timeoutMs);
-      const handler = (params: any) => {
+      const handler = (params: unknown) => {
         clearTimeout(timer);
         this.off(event, handler);
         resolve(params);
@@ -158,38 +171,51 @@ class CDPPage implements IPage {
   constructor(private bridge: CDPBridge) {}
 
   /** Navigate with proper load event waiting (P1 fix #3) */
-  async goto(url: string): Promise<void> {
+  async goto(url: string, options?: { waitUntil?: 'load' | 'none'; settleMs?: number }): Promise<void> {
     await this.bridge.send('Page.enable');
     const loadPromise = this.bridge.waitForEvent('Page.loadEventFired', 30_000)
       .catch(() => {}); // Don't fail if event times out
     await this.bridge.send('Page.navigate', { url });
     await loadPromise;
+    // Post-load settle: SPA frameworks need extra time to render after load event
+    if (options?.waitUntil !== 'none') {
+      const settleMs = options?.settleMs ?? 1000;
+      await new Promise(resolve => setTimeout(resolve, settleMs));
+    }
   }
 
-  async evaluate(js: string): Promise<any> {
+  async evaluate(js: string): Promise<unknown> {
     const expression = wrapForEval(js);
     const result = await this.bridge.send('Runtime.evaluate', {
       expression,
       returnByValue: true,
       awaitPromise: true
-    });
+    }) as RuntimeEvaluateResult;
     if (result.exceptionDetails) {
       throw new Error('Evaluate error: ' + (result.exceptionDetails.exception?.description || 'Unknown exception'));
     }
     return result.result?.value;
   }
 
-  async getCookies(opts: { domain?: string; url?: string } = {}): Promise<any[]> {
+  async getCookies(opts: { domain?: string; url?: string } = {}): Promise<BrowserCookie[]> {
     const result = await this.bridge.send('Network.getCookies', opts.url ? { urls: [opts.url] } : {});
-    const cookies = Array.isArray(result?.cookies) ? result.cookies : [];
-    return opts.domain
-      ? cookies.filter((cookie: any) => typeof cookie.domain === 'string' && cookie.domain.includes(opts.domain!))
+    const cookies = isRecord(result) && Array.isArray(result.cookies) ? result.cookies : [];
+    const domain = opts.domain;
+    return domain
+      ? cookies.filter((cookie): cookie is BrowserCookie => isCookie(cookie) && cookie.domain.includes(domain))
       : cookies;
   }
 
-  async snapshot(_opts?: any): Promise<any> {
-    // CDP doesn't have a built-in accessibility tree equivalent without additional setup
-    return '(snapshot not available in CDP mode)';
+  async snapshot(opts: SnapshotOptions = {}): Promise<unknown> {
+    const snapshotJs = generateSnapshotJs({
+      viewportExpand: opts.viewportExpand ?? 800,
+      maxDepth: Math.max(1, Math.min(Number(opts.maxDepth) || 50, 200)),
+      interactiveOnly: opts.interactive ?? false,
+      maxTextLength: opts.maxTextLength ?? 120,
+      includeScrollInfo: true,
+      bboxDedup: true,
+    });
+    return this.evaluate(snapshotJs);
   }
 
   // ── Shared DOM operations (P1 fix #5 — using dom-helpers.ts) ──
@@ -206,13 +232,22 @@ class CDPPage implements IPage {
     await this.evaluate(pressKeyJs(key));
   }
 
-  async wait(options: any): Promise<void> {
+  async scrollTo(ref: string): Promise<unknown> {
+    return this.evaluate(scrollToRefJs(ref));
+  }
+
+  async getFormState(): Promise<Record<string, unknown>> {
+    return (await this.evaluate(getFormStateJs())) as Record<string, unknown>;
+  }
+
+  async wait(options: number | WaitOptions): Promise<void> {
     if (typeof options === 'number') {
       await new Promise(resolve => setTimeout(resolve, options * 1000));
       return;
     }
-    if (options.time) {
-      await new Promise(resolve => setTimeout(resolve, options.time * 1000));
+    if (typeof options.time === 'number') {
+      const waitTime = options.time;
+      await new Promise(resolve => setTimeout(resolve, waitTime * 1000));
       return;
     }
     if (options.text) {
@@ -233,13 +268,13 @@ class CDPPage implements IPage {
     await this.evaluate(autoScrollJs(times, delayMs));
   }
 
-  async screenshot(options: any = {}): Promise<string> {
+  async screenshot(options: ScreenshotOptions = {}): Promise<string> {
     const result = await this.bridge.send('Page.captureScreenshot', {
       format: options.format ?? 'png',
       quality: options.format === 'jpeg' ? (options.quality ?? 80) : undefined,
       captureBeyondViewport: options.fullPage ?? false,
     });
-    const base64 = result.data;
+    const base64 = isRecord(result) && typeof result.data === 'string' ? result.data : '';
     if (options.path) {
       const fs = await import('node:fs');
       const path = await import('node:path');
@@ -250,11 +285,12 @@ class CDPPage implements IPage {
     return base64;
   }
 
-  async networkRequests(includeStatic: boolean = false): Promise<any> {
-    return this.evaluate(networkRequestsJs(includeStatic));
+  async networkRequests(includeStatic: boolean = false): Promise<unknown[]> {
+    const result = await this.evaluate(networkRequestsJs(includeStatic));
+    return Array.isArray(result) ? result : [];
   }
 
-  async tabs(): Promise<any> {
+  async tabs(): Promise<unknown[]> {
     return [];
   }
 
@@ -270,7 +306,7 @@ class CDPPage implements IPage {
     // Not supported in direct CDP mode
   }
 
-  async consoleMessages(_level?: string): Promise<any> {
+  async consoleMessages(_level?: string): Promise<unknown[]> {
     return [];
   }
 
@@ -282,13 +318,24 @@ class CDPPage implements IPage {
     }));
   }
 
-  async getInterceptedRequests(): Promise<any[]> {
+  async getInterceptedRequests(): Promise<unknown[]> {
     const { generateReadInterceptedJs } = await import('../interceptor.js');
     const result = await this.evaluate(generateReadInterceptedJs('__opencli_xhr'));
-    return (result as any[]) || [];
+    return Array.isArray(result) ? result : [];
   }
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isCookie(value: unknown): value is BrowserCookie {
+  return isRecord(value)
+    && typeof value.name === 'string'
+    && typeof value.value === 'string'
+    && typeof value.domain === 'string';
+}
+
 // ── CDP target selection (unchanged) ──
 
 function selectCDPTarget(targets: CDPTarget[]): CDPTarget | undefined {
@@ -338,7 +385,6 @@ function scoreCDPTarget(target: CDPTarget, preferredPattern?: RegExp): number {
   if (title.includes('chatwise')) score += 120;
   if (title.includes('notion')) score += 120;
   if (title.includes('discord')) score += 120;
-  if (title.includes('netease')) score += 120;
 
   if (url.includes('antigravity')) score += 100;
   if (url.includes('codex')) score += 100;
@@ -346,7 +392,6 @@ function scoreCDPTarget(target: CDPTarget, preferredPattern?: RegExp): number {
   if (url.includes('chatwise')) score += 100;
   if (url.includes('notion')) score += 100;
   if (url.includes('discord')) score += 100;
-  if (url.includes('netease')) score += 100;
 
   return score;
 }

package/src/browser/daemon-client.ts

@@ -113,7 +113,8 @@ export async function sendCommand(
   throw new Error('sendCommand: max retries exhausted');
 }
 
-export async function listSessions(): Promise<any[]> {
+export async function listSessions(): Promise<BrowserSessionInfo[]> {
   const result = await sendCommand('sessions');
   return Array.isArray(result) ? result : [];
 }
+import type { BrowserSessionInfo } from '../types.js';

package/src/browser/dom-helpers.ts

@@ -11,8 +11,21 @@ export function clickJs(ref: string): string {
   return `
     (() => {
       const ref = ${safeRef};
-      const el = document.querySelector('[data-ref="' + ref + '"]')
-        || document.querySelectorAll('a, button, input, [role="button"], [tabindex]')[parseInt(ref, 10) || 0];
+      // 1. data-opencli-ref (set by snapshot engine)
+      let el = document.querySelector('[data-opencli-ref="' + ref + '"]');
+      // 2. data-ref (legacy)
+      if (!el) el = document.querySelector('[data-ref="' + ref + '"]');
+      // 3. CSS selector
+      if (!el && ref.match(/^[a-zA-Z#.\\[]/)) {
+        try { el = document.querySelector(ref); } catch {}
+      }
+      // 4. Numeric index into interactive elements
+      if (!el) {
+        const idx = parseInt(ref, 10);
+        if (!isNaN(idx)) {
+          el = document.querySelectorAll('a, button, input, select, textarea, [role="button"], [tabindex]:not([tabindex="-1"])')[idx];
+        }
+      }
       if (!el) throw new Error('Element not found: ' + ref);
       el.scrollIntoView({ behavior: 'instant', block: 'center' });
       el.click();
@@ -28,13 +41,31 @@ export function typeTextJs(ref: string, text: string): string {
   return `
     (() => {
       const ref = ${safeRef};
-      const el = document.querySelector('[data-ref="' + ref + '"]')
-        || document.querySelectorAll('input, textarea, [contenteditable]')[parseInt(ref, 10) || 0];
+      // 1. data-opencli-ref (set by snapshot engine)
+      let el = document.querySelector('[data-opencli-ref="' + ref + '"]');
+      // 2. data-ref (legacy)
+      if (!el) el = document.querySelector('[data-ref="' + ref + '"]');
+      // 3. CSS selector
+      if (!el && ref.match(/^[a-zA-Z#.\\[]/)) {
+        try { el = document.querySelector(ref); } catch {}
+      }
+      // 4. Numeric index into typeable elements
+      if (!el) {
+        const idx = parseInt(ref, 10);
+        if (!isNaN(idx)) {
+          el = document.querySelectorAll('input, textarea, [contenteditable="true"]')[idx];
+        }
+      }
       if (!el) throw new Error('Element not found: ' + ref);
       el.focus();
-      el.value = ${safeText};
-      el.dispatchEvent(new Event('input', { bubbles: true }));
-      el.dispatchEvent(new Event('change', { bubbles: true }));
+      if (el.isContentEditable) {
+        el.textContent = ${safeText};
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+      } else {
+        el.value = ${safeText};
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+        el.dispatchEvent(new Event('change', { bubbles: true }));
+      }
       return 'typed';
     })()
   `;

package/src/browser/dom-snapshot.test.ts

@@ -0,0 +1,249 @@
+/**
+ * Tests for dom-snapshot.ts: DOM snapshot engine.
+ *
+ * Since the engine generates JavaScript strings for in-page evaluation,
+ * these tests validate:
+ * 1. The generated code is syntactically valid JS
+ * 2. Options are correctly embedded
+ * 3. The output structure matches expected format
+ * 4. All features are present (Shadow DOM, iframe, table, diff, etc.)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
+
+describe('generateSnapshotJs', () => {
+  it('returns a non-empty string', () => {
+    const js = generateSnapshotJs();
+    expect(typeof js).toBe('string');
+    expect(js.length).toBeGreaterThan(100);
+  });
+
+  it('generates syntactically valid JS (can be parsed)', () => {
+    const js = generateSnapshotJs();
+    expect(() => new Function(js)).not.toThrow();
+  });
+
+  it('embeds default options correctly', () => {
+    const js = generateSnapshotJs();
+    expect(js).toContain('VIEWPORT_EXPAND = 800');
+    expect(js).toContain('MAX_DEPTH = 50');
+    expect(js).toContain('INTERACTIVE_ONLY = false');
+    expect(js).toContain('MAX_TEXT_LEN = 120');
+    expect(js).toContain('INCLUDE_SCROLL_INFO = true');
+    expect(js).toContain('BBOX_DEDUP = true');
+    expect(js).toContain('INCLUDE_SHADOW_DOM = true');
+    expect(js).toContain('INCLUDE_IFRAMES = true');
+    expect(js).toContain('PAINT_ORDER_CHECK = true');
+    expect(js).toContain('ANNOTATE_REFS = true');
+    expect(js).toContain('REPORT_HIDDEN = true');
+    expect(js).toContain('FILTER_ADS = true');
+    expect(js).toContain('MARKDOWN_TABLES = true');
+    expect(js).toContain('PREV_HASHES = null');
+  });
+
+  it('embeds custom options correctly', () => {
+    const js = generateSnapshotJs({
+      viewportExpand: 2000,
+      maxDepth: 30,
+      interactiveOnly: true,
+      maxTextLength: 200,
+      includeScrollInfo: false,
+      bboxDedup: false,
+      includeShadowDom: false,
+      includeIframes: false,
+      maxIframes: 3,
+      paintOrderCheck: false,
+      annotateRefs: false,
+      reportHidden: false,
+      filterAds: false,
+      markdownTables: false,
+    });
+    expect(js).toContain('VIEWPORT_EXPAND = 2000');
+    expect(js).toContain('MAX_DEPTH = 30');
+    expect(js).toContain('INTERACTIVE_ONLY = true');
+    expect(js).toContain('MAX_TEXT_LEN = 200');
+    expect(js).toContain('INCLUDE_SCROLL_INFO = false');
+    expect(js).toContain('BBOX_DEDUP = false');
+    expect(js).toContain('INCLUDE_SHADOW_DOM = false');
+    expect(js).toContain('INCLUDE_IFRAMES = false');
+    expect(js).toContain('MAX_IFRAMES = 3');
+    expect(js).toContain('PAINT_ORDER_CHECK = false');
+    expect(js).toContain('ANNOTATE_REFS = false');
+    expect(js).toContain('REPORT_HIDDEN = false');
+    expect(js).toContain('FILTER_ADS = false');
+    expect(js).toContain('MARKDOWN_TABLES = false');
+  });
+
+  it('clamps maxDepth between 1 and 200', () => {
+    expect(generateSnapshotJs({ maxDepth: -5 })).toContain('MAX_DEPTH = 1');
+    expect(generateSnapshotJs({ maxDepth: 999 })).toContain('MAX_DEPTH = 200');
+    expect(generateSnapshotJs({ maxDepth: 75 })).toContain('MAX_DEPTH = 75');
+  });
+
+  it('wraps output as an IIFE', () => {
+    const js = generateSnapshotJs();
+    expect(js.startsWith('(() =>')).toBe(true);
+    expect(js.trimEnd().endsWith(')()')).toBe(true);
+  });
+
+  it('embeds previousHashes for incremental diff', () => {
+    const hashes = JSON.stringify(['12345', '67890']);
+    const js = generateSnapshotJs({ previousHashes: hashes });
+    expect(js).toContain('new Set(["12345","67890"])');
+  });
+
+  it('includes all core features in generated code', () => {
+    const js = generateSnapshotJs();
+
+    // Tag filtering
+    expect(js).toContain('SKIP_TAGS');
+    expect(js).toContain("'script'");
+    expect(js).toContain("'style'");
+
+    // SVG collapsing
+    expect(js).toContain('SVG_CHILDREN');
+
+    // Interactive detection
+    expect(js).toContain('INTERACTIVE_TAGS');
+    expect(js).toContain('INTERACTIVE_ROLES');
+    expect(js).toContain('isInteractive');
+
+    // Visibility
+    expect(js).toContain('isVisibleByCSS');
+    expect(js).toContain('isInExpandedViewport');
+
+    // BBox dedup
+    expect(js).toContain('isContainedBy');
+    expect(js).toContain('PROPAGATING_TAGS');
+
+    // Shadow DOM
+    expect(js).toContain('shadowRoot');
+    expect(js).toContain('|shadow|');
+
+    // iframe
+    expect(js).toContain('walkIframe');
+    expect(js).toContain('|iframe|');
+
+    // Paint order
+    expect(js).toContain('isOccludedByOverlay');
+    expect(js).toContain('elementFromPoint');
+
+    // Ad filtering
+    expect(js).toContain('isAdElement');
+    expect(js).toContain('AD_PATTERNS');
+
+    // data-ref annotation
+    expect(js).toContain('data-opencli-ref');
+
+    // Hidden elements report
+    expect(js).toContain('hiddenInteractives');
+    expect(js).toContain('hidden_interactive');
+
+    // Incremental diff
+    expect(js).toContain('hashElement');
+    expect(js).toContain('currentHashes');
+    expect(js).toContain('__opencli_prev_hashes');
+
+    // Table serialization
+    expect(js).toContain('serializeTable');
+    expect(js).toContain('|table|');
+
+    // Synthetic attributes
+    expect(js).toContain("'YYYY-MM-DD'");
+    expect(js).toContain('value=••••');
+
+    // Page metadata
+    expect(js).toContain('location.href');
+    expect(js).toContain('document.title');
+  });
+
+  it('contains proper attribute whitelist', () => {
+    const js = generateSnapshotJs();
+    const expectedAttrs = [
+      'aria-label', 'aria-expanded', 'aria-checked', 'aria-selected',
+      'placeholder', 'href', 'role', 'data-testid', 'autocomplete',
+    ];
+    for (const attr of expectedAttrs) {
+      expect(js).toContain(`'${attr}'`);
+    }
+  });
+
+  it('includes scroll info formatting', () => {
+    const js = generateSnapshotJs();
+    expect(js).toContain('scrollHeight');
+    expect(js).toContain('scrollTop');
+    expect(js).toContain('|scroll|');
+    expect(js).toContain('page_scroll');
+  });
+});
+
+describe('scrollToRefJs', () => {
+  it('generates valid JS', () => {
+    const js = scrollToRefJs('42');
+    expect(() => new Function(js)).not.toThrow();
+  });
+
+  it('targets data-opencli-ref', () => {
+    const js = scrollToRefJs('7');
+    expect(js).toContain('data-opencli-ref');
+    expect(js).toContain('scrollIntoView');
+    expect(js).toContain('"7"');
+  });
+
+  it('falls back to data-ref', () => {
+    const js = scrollToRefJs('3');
+    expect(js).toContain('data-ref');
+  });
+
+  it('returns scrolled info', () => {
+    const js = scrollToRefJs('1');
+    expect(js).toContain('scrolled: true');
+    expect(js).toContain('tag:');
+  });
+});
+
+describe('getFormStateJs', () => {
+  it('generates valid JS', () => {
+    const js = getFormStateJs();
+    expect(() => new Function(js)).not.toThrow();
+  });
+
+  it('collects form elements', () => {
+    const js = getFormStateJs();
+    expect(js).toContain('document.forms');
+    expect(js).toContain('form.elements');
+  });
+
+  it('collects orphan fields', () => {
+    const js = getFormStateJs();
+    expect(js).toContain('orphanFields');
+    expect(js).toContain('el.form');
+  });
+
+  it('handles different input types', () => {
+    const js = getFormStateJs();
+    expect(js).toContain('checkbox');
+    expect(js).toContain('radio');
+    expect(js).toContain('password');
+    expect(js).toContain('contenteditable');
+  });
+
+  it('extracts labels', () => {
+    const js = getFormStateJs();
+    expect(js).toContain('aria-label');
+    expect(js).toContain('label[for=');
+    expect(js).toContain('closest');
+    expect(js).toContain('placeholder');
+  });
+
+  it('masks passwords', () => {
+    const js = getFormStateJs();
+    expect(js).toContain('••••');
+  });
+
+  it('includes data-opencli-ref in output', () => {
+    const js = getFormStateJs();
+    expect(js).toContain('data-opencli-ref');
+  });
+});