@bewa/cdp-cli 0.1.0

package/lib/browser.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync, spawn } = require('node:child_process');
+
+const BROWSERS = {
+  darwin: {
+    canary:   '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+    chrome:   '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    chromium: '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    edge:     '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+  },
+  linux: {
+    canary:   'google-chrome-canary',
+    chrome:   ['google-chrome', 'google-chrome-stable'],
+    chromium: ['chromium', 'chromium-browser'],
+    edge:     'microsoft-edge',
+  },
+  win32: {
+    canary:   path.join(process.env.LOCALAPPDATA || '', 'Google', 'Chrome SxS', 'Application', 'chrome.exe'),
+    chrome:   path.join(process.env.PROGRAMFILES || '', 'Google', 'Chrome', 'Application', 'chrome.exe'),
+    chromium: path.join(process.env.PROGRAMFILES || '', 'Chromium', 'Application', 'chrome.exe'),
+    edge:     path.join(process.env['PROGRAMFILES(X86)'] || process.env.PROGRAMFILES || '', 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
+  },
+};
+
+/**
+ * Find browser executable. Returns absolute path or command name.
+ */
+function detect(preference) {
+  // If preference is an absolute path, use it directly
+  if (preference && preference !== 'auto' && (preference.startsWith('/') || preference.includes('\\'))) {
+    if (fs.existsSync(preference)) return preference;
+    throw new Error(`Browser not found at: ${preference}`);
+  }
+
+  const platform = process.platform;
+  const candidates = BROWSERS[platform];
+  if (!candidates) throw new Error(`Unsupported platform: ${platform}`);
+
+  // If a specific browser name is given, try that first
+  const order = (preference && preference !== 'auto')
+    ? [preference]
+    : ['canary', 'chrome', 'chromium', 'edge'];
+
+  for (const name of order) {
+    const paths = candidates[name];
+    if (!paths) continue;
+
+    const pathList = Array.isArray(paths) ? paths : [paths];
+    for (const p of pathList) {
+      if (platform === 'linux') {
+        // On Linux, browser names are commands in PATH
+        try {
+          execFileSync('which', [p], { stdio: 'ignore' });
+          return p;
+        } catch { /* not found */ }
+      } else {
+        if (fs.existsSync(p)) return p;
+      }
+    }
+  }
+
+  throw new Error(
+    `No browser found. Install Chrome/Chromium or specify path: cdp-cli launch --browser /path/to/chrome`
+  );
+}
+
+/**
+ * Launch browser with CDP enabled. Returns child process PID.
+ */
+function launch(browserPath, config) {
+  const args = [
+    `--remote-debugging-port=${config.port}`,
+    `--user-data-dir=${config.userDataDir}`,
+  ];
+
+  if (config.extensions.length) {
+    args.push(`--load-extension=${config.extensions.join(',')}`);
+  }
+
+  if (config.launchArgs.length) {
+    args.push(...config.launchArgs);
+  }
+
+  const child = spawn(browserPath, args, {
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+
+  return child.pid;
+}
+
+module.exports = { detect, launch };

package/lib/cdp.js

@@ -0,0 +1,116 @@
+'use strict';
+
+const http = require('node:http');
+const { MinimalWebSocket } = require('./ws');
+
+/**
+ * HTTP GET to CDP endpoint. Returns parsed JSON.
+ */
+function httpGet(port, urlPath) {
+  return new Promise((resolve, reject) => {
+    http.get(`http://127.0.0.1:${port}${urlPath}`, res => {
+      let body = '';
+      res.on('data', c => body += c);
+      res.on('end', () => {
+        try { resolve(JSON.parse(body)); }
+        catch { resolve(body); }
+      });
+    }).on('error', reject);
+  });
+}
+
+/**
+ * Check if CDP is listening on port.
+ */
+async function isAlive(port) {
+  try {
+    await httpGet(port, '/json/version');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * List page targets.
+ */
+async function getTargets(port) {
+  const list = await httpGet(port, '/json');
+  return list
+    .filter(t => t.type === 'page')
+    .map(t => ({
+      id: t.id.substring(0, 8),
+      fullId: t.id,
+      title: t.title,
+      url: t.url,
+      wsUrl: t.webSocketDebuggerUrl,
+    }));
+}
+
+/**
+ * Find a target by ID prefix (minimum 4 chars).
+ */
+async function findTarget(port, prefix) {
+  const targets = await getTargets(port);
+  const match = targets.find(t => t.fullId.startsWith(prefix) || t.id.startsWith(prefix));
+  if (!match) {
+    throw new Error(`No target matching "${prefix}". Run: cdp-cli targets`);
+  }
+  return match;
+}
+
+/**
+ * Open a WebSocket connection to a target and send a CDP command.
+ * Returns the result.
+ */
+async function sendCommand(wsUrl, method, params = {}, timeout = 30000) {
+  const ws = new MinimalWebSocket(wsUrl);
+  await ws.connect();
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      ws.close();
+      reject(new Error(`CDP command timed out after ${timeout}ms`));
+    }, timeout);
+
+    ws.onMessage(raw => {
+      const msg = JSON.parse(raw);
+      if (msg.id !== 1) return;
+      clearTimeout(timer);
+      ws.close();
+
+      if (msg.error) {
+        reject(new Error(msg.error.message));
+      } else {
+        resolve(msg.result);
+      }
+    });
+
+    ws.send(JSON.stringify({ id: 1, method, params }));
+  });
+}
+
+/**
+ * Evaluate JS in a page. Handles async, JSON auto-parsing.
+ */
+async function evaluate(wsUrl, expression, timeout = 30000) {
+  const result = await sendCommand(wsUrl, 'Runtime.evaluate', {
+    expression,
+    returnByValue: true,
+    awaitPromise: true,
+  }, timeout);
+
+  if (result.exceptionDetails) {
+    const desc = result.exceptionDetails.exception?.description
+      || result.exceptionDetails.text
+      || 'Evaluation error';
+    throw new Error(desc);
+  }
+
+  const val = result.result;
+  if (val.type === 'undefined') return undefined;
+  if (val.value !== undefined) return val.value;
+  return val;
+}
+
+module.exports = { httpGet, isAlive, getTargets, findTarget, sendCommand, evaluate };

package/lib/commands/eval.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const fs = require('node:fs');
+const { resolve } = require('../config');
+const { findTarget, evaluate } = require('../cdp');
+const { fail } = require('../output');
+
+async function run(argv) {
+  const config = resolve(argv);
+  const args = config.positionals;
+
+  // Determine if this is eval or eval-file (check original command)
+  const isFile = process.argv[2] === 'eval-file';
+
+  if (args.length < (isFile ? 2 : 2)) {
+    const cmd = isFile ? 'eval-file <id> <file>' : 'eval <id> <expression>';
+    fail(`Usage: cdp-cli ${cmd}`);
+  }
+
+  const targetId = args[0];
+  let expression;
+
+  if (isFile) {
+    const filePath = args[1];
+    try {
+      expression = fs.readFileSync(filePath, 'utf-8');
+    } catch (e) {
+      fail(`Cannot read file: ${filePath} — ${e.message}`);
+    }
+  } else {
+    expression = args.slice(1).join(' ');
+  }
+
+  const target = await findTarget(config.port, targetId);
+  const result = await evaluate(target.wsUrl, expression, config.timeout);
+
+  // Output the result
+  if (result === undefined) {
+    // Undefined — no output
+    return;
+  }
+
+  if (typeof result === 'string') {
+    // Try to parse as JSON for pretty-printing
+    try {
+      const parsed = JSON.parse(result);
+      console.log(JSON.stringify(parsed, null, 2));
+    } catch {
+      console.log(result);
+    }
+  } else {
+    console.log(JSON.stringify(result, null, 2));
+  }
+}
+
+module.exports = { run };

package/lib/commands/init.js

@@ -0,0 +1,73 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolve, DEFAULTS } = require('../config');
+const { print } = require('../output');
+
+const AGENT_CONFIGS = [
+  { file: 'CLAUDE.md', name: 'Claude Code' },
+  { file: '.cursorrules', name: 'Cursor' },
+  { file: '.github/copilot-instructions.md', name: 'GitHub Copilot' },
+  { file: 'AGENTS.md', name: 'Codex' },
+];
+
+const AGENT_SNIPPET = `
+## Browser Debugging
+
+This project uses \`cdp-cli\` for browser debugging via Chrome DevTools Protocol.
+Run \`cdp-cli --help\` for commands. Common workflow:
+
+\`\`\`bash
+cdp-cli launch          # Start browser with CDP
+cdp-cli targets         # List pages
+cdp-cli eval <id> "js"  # Evaluate JS in page
+cdp-cli reload [id]     # Reload after code changes
+\`\`\`
+`;
+
+async function run(argv) {
+  const config = resolve(argv);
+  const cwd = process.cwd();
+
+  // Write .cdprc.json
+  const rcPath = path.join(cwd, '.cdprc.json');
+  if (fs.existsSync(rcPath)) {
+    print({ ok: true, config: 'exists', path: rcPath }, config.human);
+  } else {
+    const rcContent = {
+      browser: 'auto',
+      port: DEFAULTS.port,
+      extensions: [],
+    };
+    fs.writeFileSync(rcPath, JSON.stringify(rcContent, null, 2) + '\n');
+    print({ ok: true, config: 'created', path: rcPath }, config.human);
+  }
+
+  // --agent: inject reference into AI assistant config files
+  if (config.agent) {
+    const injected = [];
+
+    for (const { file, name } of AGENT_CONFIGS) {
+      const filePath = path.join(cwd, file);
+      const dir = path.dirname(filePath);
+
+      if (fs.existsSync(filePath)) {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        if (content.includes('cdp-cli')) {
+          continue; // already present
+        }
+        fs.appendFileSync(filePath, AGENT_SNIPPET);
+        injected.push({ file, name });
+      }
+    }
+
+    if (injected.length) {
+      print({ ok: true, agent: injected.map(i => i.file) }, config.human);
+    } else {
+      print({ ok: true, agent: 'no_config_files_found' }, config.human);
+    }
+  }
+}
+
+module.exports = { run };

package/lib/commands/launch.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const { resolve } = require('../config');
+const { detect, launch } = require('../browser');
+const { isAlive } = require('../cdp');
+const { print, fail } = require('../output');
+
+async function run(argv) {
+  const config = resolve(argv);
+
+  // Already running?
+  if (await isAlive(config.port)) {
+    print({ ok: true, status: 'already_running', port: config.port }, config.human);
+    return;
+  }
+
+  const browserPath = detect(config.browser);
+  const browserName = browserPath.toLowerCase().includes('canary') ? 'canary'
+    : browserPath.toLowerCase().includes('edge') ? 'edge'
+    : browserPath.toLowerCase().includes('chromium') ? 'chromium'
+    : 'chrome';
+
+  const pid = launch(browserPath, config);
+
+  // Wait for CDP to be ready
+  for (let i = 0; i < 60; i++) {
+    if (await isAlive(config.port)) {
+      print({
+        ok: true,
+        status: 'launched',
+        browser: browserName,
+        port: config.port,
+        pid,
+        extensions: config.extensions.length || undefined,
+      }, config.human);
+      return;
+    }
+    await new Promise(r => setTimeout(r, 500));
+  }
+
+  fail(`Browser started (pid ${pid}) but CDP port ${config.port} not responding after 30s`);
+}
+
+module.exports = { run };

package/lib/commands/navigate.js

@@ -0,0 +1,22 @@
+'use strict';
+
+const { resolve } = require('../config');
+const { findTarget, sendCommand } = require('../cdp');
+const { print, fail } = require('../output');
+
+async function run(argv) {
+  const config = resolve(argv);
+  const args = config.positionals;
+
+  if (args.length < 2) {
+    fail('Usage: cdp-cli navigate <id> <url>');
+  }
+
+  const target = await findTarget(config.port, args[0]);
+  const url = args[1];
+
+  await sendCommand(target.wsUrl, 'Page.navigate', { url });
+  print({ ok: true, id: target.id, url }, config.human);
+}
+
+module.exports = { run };

package/lib/commands/reload.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const { resolve } = require('../config');
+const { getTargets, findTarget, sendCommand } = require('../cdp');
+const { print } = require('../output');
+
+async function run(argv) {
+  const config = resolve(argv);
+  const args = config.positionals;
+
+  let targets;
+
+  if (args[0]) {
+    // Reload specific target
+    const t = await findTarget(config.port, args[0]);
+    targets = [t];
+  } else {
+    // Reload all non-chrome:// pages
+    const all = await getTargets(config.port);
+    targets = all.filter(t => !t.url.startsWith('chrome://'));
+  }
+
+  const reloaded = [];
+  for (const target of targets) {
+    await sendCommand(target.wsUrl, 'Page.reload', {});
+    reloaded.push(target.id);
+  }
+
+  print({ ok: true, reloaded }, config.human);
+}
+
+module.exports = { run };

package/lib/commands/targets.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const { resolve } = require('../config');
+const { getTargets } = require('../cdp');
+const { print, fail } = require('../output');
+
+async function run(argv) {
+  const config = resolve(argv);
+  const targets = await getTargets(config.port);
+
+  if (!targets.length) {
+    print([], config.human);
+    return;
+  }
+
+  const out = targets.map(t => ({ id: t.id, title: t.title, url: t.url }));
+  print(out, config.human);
+}
+
+module.exports = { run };

package/lib/config.js

@@ -0,0 +1,94 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseArgs } = require('node:util');
+
+const DEFAULTS = {
+  browser: 'auto',
+  port: 9222,
+  userDataDir: '/tmp/cdp-debug-profile',
+  extensions: [],
+  launchArgs: [],
+  timeout: 30000,
+};
+
+// Common CLI options shared across commands
+const CLI_OPTIONS = {
+  port:      { type: 'string', short: 'p' },
+  browser:   { type: 'string', short: 'b' },
+  timeout:   { type: 'string', short: 't' },
+  extension: { type: 'string', multiple: true },
+  human:     { type: 'boolean' },
+  agent:     { type: 'boolean' },
+};
+
+/**
+ * Search upward from cwd for .cdprc.json
+ */
+function findConfig() {
+  let dir = process.cwd();
+  const root = path.parse(dir).root;
+
+  while (dir !== root) {
+    const configPath = path.join(dir, '.cdprc.json');
+    if (fs.existsSync(configPath)) {
+      try {
+        const raw = fs.readFileSync(configPath, 'utf-8');
+        const config = JSON.parse(raw);
+        config._dir = dir; // for resolving relative paths
+        return config;
+      } catch {
+        return {};
+      }
+    }
+    dir = path.dirname(dir);
+  }
+  return {};
+}
+
+/**
+ * Merge: CLI flags > .cdprc.json > defaults
+ * Returns resolved config object.
+ */
+function resolve(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    options: CLI_OPTIONS,
+    allowPositionals: true,
+    strict: false,
+  });
+
+  const file = findConfig();
+  const configDir = file._dir || process.cwd();
+
+  const config = { ...DEFAULTS };
+
+  // Layer 1: file config
+  if (file.browser)     config.browser = file.browser;
+  if (file.port)        config.port = file.port;
+  if (file.userDataDir) config.userDataDir = file.userDataDir;
+  if (file.timeout)     config.timeout = file.timeout;
+  if (file.launchArgs)  config.launchArgs = file.launchArgs;
+  if (file.extensions) {
+    config.extensions = file.extensions.map(e =>
+      path.isAbsolute(e) ? e : path.resolve(configDir, e)
+    );
+  }
+
+  // Layer 2: CLI flags
+  if (values.port)      config.port = parseInt(values.port, 10);
+  if (values.browser)   config.browser = values.browser;
+  if (values.timeout)   config.timeout = parseInt(values.timeout, 10);
+  if (values.extension) {
+    config.extensions = values.extension.map(e => path.resolve(e));
+  }
+
+  config.human = !!values.human;
+  config.agent = !!values.agent;
+  config.positionals = positionals;
+
+  return config;
+}
+
+module.exports = { resolve, DEFAULTS, findConfig };

package/lib/output.js

@@ -0,0 +1,38 @@
+'use strict';
+
+/**
+ * Output a result object. JSON by default, human-readable with --human.
+ */
+function print(data, human) {
+  if (human) {
+    if (Array.isArray(data)) {
+      data.forEach(item => console.log(formatHuman(item)));
+    } else {
+      console.log(formatHuman(data));
+    }
+  } else {
+    if (Array.isArray(data)) {
+      data.forEach(item => console.log(JSON.stringify(item)));
+    } else {
+      console.log(JSON.stringify(data));
+    }
+  }
+}
+
+function formatHuman(obj) {
+  if (typeof obj === 'string') return obj;
+  if (obj.id && obj.title && obj.url) {
+    return `${obj.id}  ${obj.title.substring(0, 50).padEnd(50)}  ${obj.url.substring(0, 80)}`;
+  }
+  return JSON.stringify(obj, null, 2);
+}
+
+/**
+ * Print error to stderr and exit.
+ */
+function fail(message, code = 1) {
+  console.error(JSON.stringify({ error: message }));
+  process.exit(code);
+}
+
+module.exports = { print, fail };