refactor: type browser core (#218)

Author: jackwener

src/browser/cdp.ts

@@ -9,7 +9,7 @@
  */
 
 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 {
@@ -29,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;
@@ -112,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');
     }
@@ -128,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);
@@ -173,28 +184,29 @@ class CDPPage implements IPage {
     }
   }
 
-  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: { interactive?: boolean; compact?: boolean; maxDepth?: number; raw?: boolean; viewportExpand?: number; maxTextLength?: number } = {}): Promise<any> {
+  async snapshot(opts: SnapshotOptions = {}): Promise<unknown> {
     const snapshotJs = generateSnapshotJs({
       viewportExpand: opts.viewportExpand ?? 800,
       maxDepth: Math.max(1, Math.min(Number(opts.maxDepth) || 50, 200)),
@@ -220,21 +232,22 @@ class CDPPage implements IPage {
     await this.evaluate(pressKeyJs(key));
   }
 
-  async scrollTo(ref: string): Promise<any> {
+  async scrollTo(ref: string): Promise<unknown> {
     return this.evaluate(scrollToRefJs(ref));
   }
 
-  async getFormState(): Promise<any> {
-    return this.evaluate(getFormStateJs());
+  async getFormState(): Promise<Record<string, unknown>> {
+    return (await this.evaluate(getFormStateJs())) as Record<string, unknown>;
   }
 
-  async wait(options: any): Promise<void> {
+  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) {
@@ -255,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');
@@ -272,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 [];
   }
 
@@ -292,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 [];
   }
 
@@ -304,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 {

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';

src/browser/page.ts

@@ -11,7 +11,7 @@
  */
 
 import { formatSnapshot } from '../snapshotFormatter.js';
-import type { IPage } from '../types.js';
+import type { BrowserCookie, IPage, ScreenshotOptions, SnapshotOptions, WaitOptions } from '../types.js';
 import { sendCommand } from './daemon-client.js';
 import { wrapForEval } from './utils.js';
 import { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
@@ -70,17 +70,17 @@ export class Page implements IPage {
     }
   }
 
-  async evaluate(js: string): Promise<any> {
+  async evaluate(js: string): Promise<unknown> {
     const code = wrapForEval(js);
     return sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() });
   }
 
-  async getCookies(opts: { domain?: string; url?: string } = {}): Promise<any[]> {
+  async getCookies(opts: { domain?: string; url?: string } = {}): Promise<BrowserCookie[]> {
     const result = await sendCommand('cookies', { ...this._workspaceOpt(), ...opts });
     return Array.isArray(result) ? result : [];
   }
 
-  async snapshot(opts: { interactive?: boolean; compact?: boolean; maxDepth?: number; raw?: boolean; viewportExpand?: number; maxTextLength?: number } = {}): Promise<any> {
+  async snapshot(opts: SnapshotOptions = {}): Promise<unknown> {
     // Primary: use the advanced DOM snapshot engine with multi-layer pruning
     const snapshotJs = generateSnapshotJs({
       viewportExpand: opts.viewportExpand ?? 800,
@@ -103,7 +103,7 @@ export class Page implements IPage {
   }
 
   /** Fallback basic snapshot — original buildTree approach */
-  private async _basicSnapshot(opts: { interactive?: boolean; compact?: boolean; maxDepth?: number; raw?: boolean } = {}): Promise<any> {
+  private async _basicSnapshot(opts: Pick<SnapshotOptions, 'interactive' | 'compact' | 'maxDepth' | 'raw'> = {}): Promise<unknown> {
     const maxDepth = Math.max(1, Math.min(Number(opts.maxDepth) || 50, 200));
     const code = `
       (async () => {
@@ -153,17 +153,17 @@ export class Page implements IPage {
     await sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() });
   }
 
-  async scrollTo(ref: string): Promise<any> {
+  async scrollTo(ref: string): Promise<unknown> {
     const code = scrollToRefJs(ref);
     return sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() });
   }
 
-  async getFormState(): Promise<any> {
+  async getFormState(): Promise<Record<string, unknown>> {
     const code = getFormStateJs();
-    return sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() });
+    return (await sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() })) as Record<string, unknown>;
   }
 
-  async wait(options: number | { text?: string; time?: number; timeout?: number }): Promise<void> {
+  async wait(options: number | WaitOptions): Promise<void> {
     if (typeof options === 'number') {
       await new Promise(resolve => setTimeout(resolve, options * 1000));
       return;
@@ -179,8 +179,9 @@ export class Page implements IPage {
     }
   }
 
-  async tabs(): Promise<any> {
-    return sendCommand('tabs', { op: 'list', ...this._workspaceOpt() });
+  async tabs(): Promise<unknown[]> {
+    const result = await sendCommand('tabs', { op: 'list', ...this._workspaceOpt() });
+    return Array.isArray(result) ? result : [];
   }
 
   async closeTab(index?: number): Promise<void> {
@@ -195,17 +196,18 @@ export class Page implements IPage {
     await sendCommand('tabs', { op: 'select', index, ...this._workspaceOpt() });
   }
 
-  async networkRequests(includeStatic: boolean = false): Promise<any> {
+  async networkRequests(includeStatic: boolean = false): Promise<unknown[]> {
     const code = networkRequestsJs(includeStatic);
-    return sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() });
+    const result = await sendCommand('exec', { code, ...this._workspaceOpt(), ...this._tabOpt() });
+    return Array.isArray(result) ? result : [];
   }
 
   /**
    * Console messages are not available in lightweight daemon mode.
    * Would require CDP Runtime.consoleAPICalled event listener.
    * @returns Always returns empty array.
    */
-  async consoleMessages(_level: string = 'info'): Promise<any> {
+  async consoleMessages(_level: string = 'info'): Promise<unknown[]> {
     return [];
   }
 
@@ -216,12 +218,7 @@ export class Page implements IPage {
    * @param options.fullPage - capture full scrollable page
    * @param options.path - save to file path (returns base64 if omitted)
    */
-  async screenshot(options: {
-    format?: 'png' | 'jpeg';
-    quality?: number;
-    fullPage?: boolean;
-    path?: string;
-  } = {}): Promise<string> {
+  async screenshot(options: ScreenshotOptions = {}): Promise<string> {
     const base64 = await sendCommand('screenshot', {
       ...this._workspaceOpt(),
       format: options.format,
@@ -263,11 +260,11 @@ export class Page implements IPage {
     }));
   }
 
-  async getInterceptedRequests(): Promise<any[]> {
+  async getInterceptedRequests(): Promise<unknown[]> {
     const { generateReadInterceptedJs } = await import('../interceptor.js');
     // Same as installInterceptor: must go through evaluate() for IIFE wrapping
     const result = await this.evaluate(generateReadInterceptedJs('__opencli_xhr'));
-    return (result as any[]) || [];
+    return Array.isArray(result) ? result : [];
   }
 }
 

src/explore.ts

@@ -223,6 +223,10 @@ function flattenFields(obj: unknown, prefix: string, maxDepth: number): string[]
   return names;
 }
 
+function isBooleanRecord(value: unknown): value is Record<string, boolean> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 function scoreEndpoint(ep: { contentType: string; responseAnalysis: AnalyzedEndpoint['responseAnalysis']; pattern: string; status: number | null; hasSearchParam: boolean; hasPaginationParam: boolean; hasLimitParam: boolean }): number {
   let s = 0;
   if (ep.contentType.includes('json')) s += 10;
@@ -488,7 +492,10 @@ export async function exploreUrl(
 
       // Step 6: Detect framework
       let framework: Record<string, boolean> = {};
-      try { const fw = await page.evaluate(FRAMEWORK_DETECT_JS); if (fw && typeof fw === 'object') framework = fw; } catch {}
+      try {
+        const fw = await page.evaluate(FRAMEWORK_DETECT_JS);
+        if (isBooleanRecord(fw)) framework = fw;
+      } catch {}
 
       // Step 6.5: Discover stores (Pinia / Vuex)
       let stores: DiscoveredStore[] = [];
@@ -551,7 +558,12 @@ export function renderExploreSummary(result: ExploreResult): string {
 async function readPageMetadata(page: IPage): Promise<{ url: string; title: string }> {
   try {
     const result = await page.evaluate(`() => ({ url: window.location.href, title: document.title || '' })`);
-    if (result && typeof result === 'object') return { url: String(result.url ?? ''), title: String(result.title ?? '') };
+    if (result && typeof result === 'object' && !Array.isArray(result)) {
+      return {
+        url: String((result as Record<string, unknown>).url ?? ''),
+        title: String((result as Record<string, unknown>).title ?? ''),
+      };
+    }
   } catch {}
   return { url: '', title: '' };
 }

src/pipeline/steps/fetch.ts

@@ -72,7 +72,7 @@ async function fetchBatchInBrowser(
 ): Promise<unknown[]> {
   const headersJs = JSON.stringify(headers);
   const urlsJs = JSON.stringify(urls);
-  return page.evaluate(`
+  return (await page.evaluate(`
     async () => {
       const urls = ${urlsJs};
       const method = "${method}";
@@ -98,7 +98,7 @@ async function fetchBatchInBrowser(
       await Promise.all(workers);
       return results;
     }
-  `);
+  `)) as unknown[];
 }
 
 export async function stepFetch(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown> {