@ai-ecoverse/slicc-cdp 1.3.3 → 1.5.0

package/README.md

@@ -1,6 +1,6 @@
 # slicc-cdp
 
-`@ai-ecoverse/slicc-cdp` publishes `playwright-cli` and `curlwright`, Rust clients for an already-running Chrome. They speak Chrome DevTools Protocol JSON. The JavaScript CDP layer from SLICC is not in this package yet (`src/index.js` is `export {}`).
+`@ai-ecoverse/slicc-cdp` publishes `playwright-cli` and `curlwright`, Rust clients for an already-running Chrome. They speak Chrome DevTools Protocol JSON. The package root exports `CDPClient` and `connect`, one browser DevTools socket.
 
 ## playwright-cli
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-ecoverse/slicc-cdp",
-  "version": "1.3.3",
+  "version": "1.5.0",
   "description": "SLICC's CDP layer: client, browser API, transports, HAR, and ARIA snapshot",
   "type": "module",
   "license": "Apache-2.0",
@@ -22,7 +22,10 @@
     "provenance": true
   },
   "exports": {
-    ".": "./src/index.js"
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
   },
   "files": [
     "src",
@@ -45,16 +48,21 @@
     "build:wasm": "cargo build --release --target wasm32-wasip1 -p playwright-cli -p curlwright && mkdir -p bin && cp target/wasm32-wasip1/release/playwright-cli.wasm bin/playwright-cli.wasm && cp target/wasm32-wasip1/release/curlwright.wasm bin/curlwright.wasm",
     "prepublishOnly": "npm run build:wasm",
     "lint": "slicc-lint",
+    "typecheck": "node --check src/index.js && node --check src/cdp-client.js && node --check src/connect.js",
     "format": "biome check --write .",
     "test": "true",
+    "test:integration": "PATH=\"$HOME/.cargo/bin:$PATH\" cargo build -p playwright-cli -p curlwright && PATH=\"$HOME/.cargo/bin:$PATH\" cargo build --target wasm32-wasip1 -p playwright-cli -p curlwright && npx playwright-core install chromium && node --test --test-timeout=180000 test/integration/chromium.test.mjs",
+    "test:unit": "mcr -c node_modules/@ai-ecoverse/slicc-shared-web/mcr.config.mjs node --test 'test/unit/**/*.test.mjs'",
     "trust": "npx fledgling sync -y --skip-publish",
     "trust:dry": "npx fledgling sync --dry-run -y --skip-publish",
     "release": "semantic-release"
   },
   "devDependencies": {
-    "@ai-ecoverse/slicc-shared-web": "1.12.0",
+    "@ai-ecoverse/slicc-kernel": "1.48.1",
+    "@ai-ecoverse/slicc-shared-web": "1.12.1",
     "@biomejs/biome": "2.5.15",
     "lefthook": "2.1.16",
+    "playwright-core": "1.63.0",
     "semantic-release": "25.0.9"
   }
 }

package/src/cdp-client.js

@@ -0,0 +1,217 @@
+export class CDPClient {
+  #WebSocket;
+  #ws = null;
+  #state = 'disconnected';
+  #nextId = 0;
+  #pending = new Map();
+  #listeners = new Map();
+  #failure;
+  #localClose = false;
+
+  constructor(WebSocketImpl = globalThis.WebSocket) {
+    this.#WebSocket = WebSocketImpl;
+  }
+
+  async open(url, options = {}) {
+    if (this.#state === 'connecting' || this.#state === 'connected') {
+      throw new Error(`Cannot connect: state is ${this.#state}\n`);
+    }
+    this.#failure = undefined;
+    this.#localClose = false;
+    this.#state = 'connecting';
+    const timeout = options.timeout ?? 10000;
+    const WS = this.#WebSocket;
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let timer;
+      const finish = (error) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (error) reject(error);
+        else resolve();
+      };
+      let ws;
+      try {
+        ws = new WS(url);
+      } catch (err) {
+        this.#state = 'disconnected';
+        finish(err instanceof Error ? err : new Error(String(err)));
+        return;
+      }
+      this.#ws = ws;
+      timer = setTimeout(() => {
+        this.#localClose = true;
+        this.#failure = new Error('CDP connection timed out\n');
+        this.#state = 'disconnected';
+        const socket = this.#ws;
+        this.#ws = null;
+        closeQuiet(socket);
+        finish(this.#failure);
+      }, timeout);
+      ws.addEventListener('open', () => {
+        if (ws !== this.#ws) return;
+        this.#state = 'connected';
+        finish();
+      });
+      ws.addEventListener('message', (event) => {
+        if (ws !== this.#ws) return;
+        this.#onMessage(event?.data);
+      });
+      ws.addEventListener('error', () => {
+        if (ws !== this.#ws) return;
+        if (this.#state !== 'connecting') return;
+        const error = new Error('CDP connection failed\n');
+        this.#failure = error;
+        this.#state = 'disconnected';
+        finish(error);
+      });
+      ws.addEventListener('close', (event) => {
+        if (ws !== this.#ws) return;
+        const error = new Error(closeMessage(event?.code, event?.reason));
+        this.#fail(error);
+        finish(error);
+      });
+    });
+  }
+
+  send(method, params, sessionId, timeout = 30000) {
+    if (this.#failure) return Promise.reject(this.#failure);
+    if (this.#state !== 'connected' || !this.#ws) {
+      return Promise.reject(new Error('CDP client is not connected\n'));
+    }
+    const id = ++this.#nextId;
+    const message = { id, method };
+    if (params !== undefined) message.params = params;
+    if (sessionId !== undefined) message.sessionId = sessionId;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pending.delete(id);
+        reject(new Error(`${method} timed out\n`));
+      }, timeout);
+      this.#pending.set(id, { resolve, reject, timer, method });
+      try {
+        this.#ws.send(JSON.stringify(message));
+      } catch (err) {
+        clearTimeout(timer);
+        this.#pending.delete(id);
+        reject(err instanceof Error ? err : new Error(String(err)));
+      }
+    });
+  }
+
+  on(event, listener) {
+    let set = this.#listeners.get(event);
+    if (!set) {
+      set = new Set();
+      this.#listeners.set(event, set);
+    }
+    set.add(listener);
+    return () => this.off(event, listener);
+  }
+
+  off(event, listener) {
+    const set = this.#listeners.get(event);
+    if (!set) return;
+    set.delete(listener);
+    if (set.size === 0) this.#listeners.delete(event);
+  }
+
+  async attach(targetId) {
+    const result = await this.send('Target.attachToTarget', { targetId, flatten: true });
+    const sessionId = result && typeof result.sessionId === 'string' ? result.sessionId : '';
+    if (sessionId.length === 0) {
+      throw new Error('Target.attachToTarget returned no sessionId\n');
+    }
+    return sessionId;
+  }
+
+  close() {
+    if (this.#localClose) return;
+    this.#localClose = true;
+    this.#fail(new Error('CDP client disconnected\n'));
+    const ws = this.#ws;
+    this.#ws = null;
+    closeQuiet(ws);
+  }
+
+  #onMessage(raw) {
+    const text = typeof raw === 'string' ? raw : '';
+    let message;
+    try {
+      message = JSON.parse(text);
+    } catch (err) {
+      this.#fail(jsonError(err));
+      return;
+    }
+    if (this.#settle(message)) return;
+    this.#dispatch(message);
+  }
+
+  #settle(message) {
+    if (!isRecord(message)) return false;
+    if (typeof message.id !== 'number') return false;
+    const entry = this.#pending.get(message.id);
+    if (!entry) return false;
+    this.#pending.delete(message.id);
+    clearTimeout(entry.timer);
+    if (message.error) {
+      entry.reject(new Error(`${entry.method}: ${errorText(message.error)}\n`));
+    } else {
+      entry.resolve(message.result ?? null);
+    }
+    return true;
+  }
+
+  #dispatch(message) {
+    if (!isRecord(message)) return;
+    if (typeof message.method !== 'string') return;
+    const set = this.#listeners.get(message.method);
+    if (!set) return;
+    for (const listener of set) {
+      try {
+        listener(message);
+      } catch {}
+    }
+  }
+
+  #fail(error) {
+    this.#failure = this.#failure ?? error;
+    this.#state = 'closed';
+    for (const entry of this.#pending.values()) {
+      clearTimeout(entry.timer);
+      entry.reject(this.#failure);
+    }
+    this.#pending.clear();
+  }
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === 'object';
+}
+
+function errorText(error) {
+  if (isRecord(error) && typeof error.message === 'string') return error.message;
+  return 'CDP error';
+}
+
+function jsonError(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  return new Error(`CDP response was not JSON: ${message}\n`);
+}
+
+function closeMessage(code, reason) {
+  const text = typeof reason === 'string' ? reason : '';
+  if (typeof code !== 'number' || code === 1005) return 'websocket closed\n';
+  if (text.length === 0) return `websocket closed ${code}\n`;
+  return `websocket closed ${code} ${text}\n`;
+}
+
+function closeQuiet(ws) {
+  if (!ws) return;
+  try {
+    ws.close();
+  } catch {
+    return;
+  }
+}

package/src/connect.js

@@ -0,0 +1,117 @@
+import { CDPClient } from './cdp-client.js';
+
+const UNRESERVED = /[A-Za-z0-9._~-]/u;
+
+function nonempty(value) {
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return undefined;
+  return trimmed;
+}
+
+export function chooseStart(cdp, env) {
+  const explicit = nonempty(cdp);
+  if (explicit !== undefined) return classify(explicit);
+  const fromEnv = nonempty(env);
+  if (fromEnv !== undefined) return classify(fromEnv);
+  return { kind: 'discover', url: 'http://127.0.0.1:9222/json/version' };
+}
+
+function classify(url) {
+  const lower = url.toLowerCase();
+  if (lower.startsWith('ws://') || lower.startsWith('wss://')) {
+    return { kind: 'direct', url };
+  }
+  if (lower.startsWith('http://') || lower.startsWith('https://')) {
+    return { kind: 'discover', url: discoveryUrl(url) };
+  }
+  throw new Error(`unsupported CDP URL "${url}" (expected ws://, wss://, http://, or https://)\n`);
+}
+
+export function discoveryUrl(httpUrl) {
+  if (httpUrl.includes('/json/version')) return httpUrl;
+  const trimmed = httpUrl.replace(/\/+$/u, '');
+  return `${trimmed}/json/version`;
+}
+
+export function appendRuntime(url, runtime) {
+  const value = nonempty(runtime);
+  if (value === undefined) return url;
+  const enc = percentEncode(value);
+  if (url.includes('?')) return `${url}&runtime=${enc}`;
+  return `${url}?runtime=${enc}`;
+}
+
+function percentEncode(value) {
+  let out = '';
+  for (const byte of new TextEncoder().encode(value)) {
+    const char = String.fromCharCode(byte);
+    if (UNRESERVED.test(char)) out += char;
+    else out += `%${byte.toString(16).toUpperCase().padStart(2, '0')}`;
+  }
+  return out;
+}
+
+export function formatHttpError(status, body) {
+  const text = String(body ?? '').replace(/\0+$/u, '');
+  if (text.length === 0) return `HTTP ${status}\n`;
+  if (text.endsWith('\n')) return `HTTP ${status}\n${text}`;
+  return `HTTP ${status}\n${text}\n`;
+}
+
+export function websocketUrlFromVersion(body) {
+  let value;
+  try {
+    value = JSON.parse(body);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`json/version: ${message}\n`);
+  }
+  const url = isRecord(value) ? value.webSocketDebuggerUrl : undefined;
+  if (typeof url !== 'string' || url.length === 0) {
+    throw new Error('json/version returned no webSocketDebuggerUrl\n');
+  }
+  return url;
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === 'object';
+}
+
+export async function connect(options = {}) {
+  const env = options.env ?? process.env.SLICC_CDP_URL;
+  const start = chooseStart(options.url, env);
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const socketUrl = await socketFromStart(start, fetchImpl);
+  const withRuntime = appendRuntime(socketUrl, options.runtime);
+  const client = new CDPClient(options.WebSocket ?? globalThis.WebSocket);
+  await client.open(withRuntime, { timeout: options.timeout ?? 10000 });
+  return client;
+}
+
+async function socketFromStart(start, fetchImpl) {
+  if (start.kind === 'direct') return start.url;
+  return discover(fetchImpl, start.url);
+}
+
+async function discover(fetchImpl, url) {
+  let response;
+  try {
+    response = await fetchImpl(url);
+  } catch (err) {
+    throw discoveryFailure(err);
+  }
+  const body = await response.text();
+  if (!response.ok) throw new Error(formatHttpError(response.status, body));
+  return websocketUrlFromVersion(body);
+}
+
+function discoveryFailure(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  if (message.startsWith('HTTP ') || message.includes('does not launch Chrome')) {
+    return err instanceof Error ? err : new Error(message);
+  }
+  return new Error(
+    `${message}\nThis CLI does not launch Chrome. Pass --cdp or set SLICC_CDP_URL.\n`
+  );
+}

package/src/index.d.ts

@@ -0,0 +1,33 @@
+export type CdpParams = Record<string, unknown>;
+
+export interface CdpMessage {
+  method?: string;
+  params?: CdpParams;
+  sessionId?: string;
+  id?: number;
+  result?: unknown;
+  error?: { message?: string };
+}
+
+export type CdpListener = (message: CdpMessage) => void;
+
+export interface CdpConnectOptions {
+  url?: string;
+  env?: string;
+  runtime?: string;
+  timeout?: number;
+  fetch?: typeof fetch;
+  WebSocket?: typeof WebSocket;
+}
+
+export declare function connect(options?: CdpConnectOptions): Promise<CDPClient>;
+
+export declare class CDPClient {
+  constructor(socket?: typeof WebSocket);
+  open(url: string, options?: { timeout?: number }): Promise<void>;
+  send(method: string, params?: CdpParams, sessionId?: string, timeout?: number): Promise<unknown>;
+  on(event: string, listener: CdpListener): () => void;
+  off(event: string, listener: CdpListener): void;
+  attach(targetId: string): Promise<string>;
+  close(): void;
+}

package/src/index.js

@@ -1 +1,2 @@
-export {};
+export { CDPClient } from './cdp-client.js';
+export { connect } from './connect.js';