@ai-ecoverse/slicc-cdp 1.25.1 → 1.26.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 package root exports `CDPClient` and `connect`, one browser DevTools socket. Host `connect()` does not dial port 9222 unless `options.url` or `SLICC_CDP_URL` names it.
+`@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, and `findBrowser`, `installBrowser` and `launchBrowser` (see [Browser](#browser)). Host `connect()` does not dial port 9222 unless `options.url` or `SLICC_CDP_URL` names it.
 
 `playwright-cli` is a playwright-cli-compatible command for SLICC and not affiliated with Microsoft Playwright.
 
@@ -8,7 +8,7 @@
 
 The binary is `crates/playwright-cli`. Host `open` launches a browser into `<config>/slicc/seven-profiles/<id>` when no debugger is already connected, and inside slicc it only opens a tab. It does not invent a debugger path.
 
-Connect, in order: `--cdp`, else `SLICC_CDP_URL`, else a live `DevToolsActivePort` under `<config>/slicc/seven-profiles`, else a loopback endpoint this tool saved at `<config>/slicc/playwright-cli/sessions/<hash>.json`. A `.playwright-cli/session.json` in the working directory is ignored. A child of that directory is a profile only when its name is a browser id: it starts with a letter or digit, then letters, digits, `.`, `_`, or `-`, at most 64 characters, and it does not contain `..`. Dotfiles, including `.migrated-from-profiles`, are not profiles. `playwright-cli` does not migrate `slicc/profiles`. Host `list`, and `open` when that port is absent or unreachable, GET `/json/version` and `/json/list` on `127.0.0.1:9222-9229`. An unreachable seven-profiles port falls through to that probe, so `open` may attach to a personal browser that already has a seven tab. A successful command writes the loopback endpoint it used, its provenance, and the ids of tabs it created. A saved endpoint is reused only when it is loopback. A probe-derived session is reused only while that browser still has a seven tab, and later commands show only tabs this tool created. An explicit `--cdp` or `SLICC_CDP_URL` may name any host, and that URL is not saved unless it is loopback. Host `open` and `tab-new` treat an unreachable saved endpoint as absent, then probe and may launch. Other commands report that connection error. Launch never binds those ports. The wasm build still uses port 9222. A `ws://` URL is dialed as given. An `http://` URL is discovery. On the native build a `wss://` URL is dialed as given. The WASI build has no TLS, so `wss://` and `https://` fail there. `--runtime <name>` is appended to the query of the URL that is opened and is not interpreted.
+Connect, in order: `--cdp`, else `SLICC_CDP_URL`, else a live `DevToolsActivePort` under `<config>/slicc/seven-profiles`, else a loopback endpoint this tool saved at `<config>/slicc/playwright-cli/sessions/<hash>.json`. A `.playwright-cli/session.json` in the working directory is ignored. In the kernel, the wasm builds keep it at `<state>/slicc/playwright-cli/sessions/<hash>.json`, where `<state>` is `$XDG_STATE_HOME`, else `$XDG_CONFIG_HOME`, else `$HOME/.config`, and the hash is of `$PWD`. When that is not writable, `playwright-cli` prints `playwright-cli: running without saved state (<reason>)` on stderr and the command still succeeds, except `route` and `unroute`, which fail because they only save state. A child of that directory is a profile only when its name is a browser id: it starts with a letter or digit, then letters, digits, `.`, `_`, or `-`, at most 64 characters, and it does not contain `..`. Dotfiles, including `.migrated-from-profiles`, are not profiles. `playwright-cli` does not migrate `slicc/profiles`. Host `list`, and `open` when that port is absent or unreachable, GET `/json/version` and `/json/list` on `127.0.0.1:9222-9229`. An unreachable seven-profiles port falls through to that probe, so `open` may attach to a personal browser that already has a seven tab. A successful command writes the loopback endpoint it used, its provenance, and the ids of tabs it created. A saved endpoint is reused only when it is loopback. A probe-derived session is reused only while that browser still has a seven tab, and later commands show only tabs this tool created. An explicit `--cdp` or `SLICC_CDP_URL` may name any host, and that URL is not saved unless it is loopback. Host `open` and `tab-new` treat an unreachable saved endpoint as absent, then probe and may launch. Other commands report that connection error. Launch never binds those ports. The wasm build still uses port 9222. A `ws://` URL is dialed as given. An `http://` URL is discovery. On the native build a `wss://` URL is dialed as given. The WASI build has no TLS, so `wss://` and `https://` fail there. `--runtime <name>` is appended to the query of the URL that is opened and is not interpreted.
 
 One browser WebSocket. `Target.attachToTarget` uses `{targetId, flatten: true}`. Later page commands send that `sessionId` at the top level. There is no `/devtools/page/<id>` socket.
 
@@ -58,6 +58,24 @@ A non-2xx discovery response prints the status and the body and exits non-zero.
 
 `curlwright` is the Rust binary in `crates/curlwright`. It runs curl-style requests as a page-context `fetch()` in an already-open tab, so that tab's cookies, origin, and service worker apply. It uses `--cdp`, else `SLICC_CDP_URL`, else a live `seven-profiles` DevToolsActivePort. On the host, if none of those exist, it exits without dialing port 9222. Ports 9222-9229 inside those files are not dialed. The wasm build still uses port 9222. The shared CDP client is `crates/cdp-client`. Without `--tab`, it uses the `current` target this tool saved for the working directory under the user config dir when that tab is still open, otherwise the single open tab on the request URL's origin. It does not read a `.playwright-cli/session.json` in the working directory and it does not read the saved endpoint. Any other case exits 2 and lists `--tab` choices. A tab on a different origin is not used unless `--tab` or that session names it. A request URL on a protected origin (any `sliccy.ai` host, the vault, or `//` to one) is refused before any tab is chosen, with `curlwright: slicc: refused: target is on seven's origin`, and so is `--tab` on a protected tab.
 
+## Browser
+
+On the host, the package can find, install and launch a Chrome for a test suite or a script. This is Node only, not in the wasm commands.
+
+- **`findBrowser({ version })`:** `$CHROME_PATH`, else the newest Chrome for Testing that `install-browser` put under the install root, else a system Chrome or Chromium (`/Applications`, `/usr/bin`, `/snap/bin`, Program Files). With `version` (a full version or a milestone) only that installed Chrome for Testing counts, and `$CHROME_PATH` is not used. Returns `{ executable, source, version? }` or `null`.
+- **`installBrowser({ version, channel, withDeps })`:** downloads Chrome for Testing for this platform, unzips it, checks that `--version` prints the expected version (on Windows, which prints nothing, that the build's `<version>.manifest` is there), and marks it with `.slicc-cdp-browser.json`. An exact version that is already installed is used without the network. The install root is `$SLICC_BROWSERS_PATH`, else `~/Library/Caches/slicc-cdp/browsers`, `$XDG_CACHE_HOME/slicc-cdp/browsers` (default `~/.cache`), or `%LOCALAPPDATA%\slicc-cdp\browsers`. `withDeps` is opt-in. On Linux it runs `apt-get satisfy` on the build's `deb.deps`, as root or with `sudo -n`, and otherwise fails saying so.
+- **`launchBrowser({ executable, userDataDir, port, headless, sandbox, args })`:** starts the browser with `--remote-debugging-port` (0 by default) on `127.0.0.1`. Without `userDataDir` the profile is a fresh `slicc-cdp-profile-*` directory in the temp dir, never the user's, and `close()` kills the browser and removes the profile. Ports 9222-9229 are refused, and so are `args` that set the debugging port, address, pipe or profile. A fixed `port` that already answers is refused. Returns `{ child, executable, userDataDir, port, wsUrl, close }`. With port 0 the `wsUrl` comes from a fresh `DevToolsActivePort`, which is removed before launch. Otherwise it comes from `/json/version` on that port. The sandbox stays on unless `sandbox: false`. Linux without unprivileged user namespaces (Ubuntu 23.10 and later, GitHub's `ubuntu-latest` included) needs that, or Chrome aborts with "No usable sandbox".
+
+The `slicc-cdp` bin does the same from a shell:
+
+```
+npx slicc-cdp install-browser --version 153.0.8010.12   # prints the executable
+npx slicc-cdp install-browser --channel stable --with-deps
+npx slicc-cdp find-browser
+```
+
+Trust: Chrome for Testing publishes no checksums or signatures for its zips. `installBrowser` downloads only over HTTPS, only from `googlechromelabs.github.io` (the version index) and `storage.googleapis.com` (the zips). Redirects are refused. The only checks are the byte count and the version, so you are trusting those Google hosts and TLS. Pin an exact version (`--version x.y.z.w`) in CI, so a run gets the build you tested.
+
 ## Kernel commands
 
 `slicc.abi` is `wasi`. The commands are `playwright-cli` (`bin/playwright-cli.wasm`) and `curlwright` (`bin/curlwright.wasm`). `npm run build:wasm` builds both for `wasm32-wasip1` and copies them there. The release workflow runs that before publish. Do not commit the wasm. On that target, TCP comes from the `wasix-net` 0.1 crate on crates.io.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-ecoverse/slicc-cdp",
-  "version": "1.25.1",
+  "version": "1.26.0",
   "description": "SLICC's CDP layer: client, browser API, transports, HAR, and ARIA snapshot",
   "type": "module",
   "license": "Apache-2.0",
@@ -30,6 +30,9 @@
       "default": "./src/index.js"
     }
   },
+  "bin": {
+    "slicc-cdp": "src/cli.js"
+  },
   "files": [
     "src",
     "bin/playwright-cli.wasm",
@@ -51,21 +54,24 @@
     "build:wasm": "cargo build --release --target wasm32-wasip1 -p slicc-cdp -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 && node --check src/page.js && node --check packages/sliccy-browser/src/browser.js && node --check packages/sliccy-browser/src/fetch-script.js && node --check packages/sliccy-browser/src/ws-router.js",
+    "typecheck": "node --check src/index.js && node --check src/cdp-client.js && node --check src/connect.js && node --check src/page.js && node --check src/browser.js && node --check src/cli.js && node --check packages/sliccy-browser/src/browser.js && node --check packages/sliccy-browser/src/fetch-script.js",
     "format": "biome check --write .",
     "test": "true",
-    "test:integration": "PATH=\"$HOME/.cargo/bin:$PATH\" cargo test --workspace && PATH=\"$HOME/.cargo/bin:$PATH\" cargo build -p slicc-cdp -p curlwright && PATH=\"$HOME/.cargo/bin:$PATH\" cargo build --target wasm32-wasip1 -p slicc-cdp -p curlwright && npx playwright-core install chromium && node --test --test-timeout=600000 test/integration/*.test.mjs",
+    "test:integration": "PATH=\"$HOME/.cargo/bin:$PATH\" cargo test --workspace && PATH=\"$HOME/.cargo/bin:$PATH\" cargo build -p slicc-cdp -p curlwright && PATH=\"$HOME/.cargo/bin:$PATH\" cargo build --target wasm32-wasip1 -p slicc-cdp -p curlwright && npm run -s browser >/dev/null && node --test --test-timeout=600000 test/integration/*.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"
+    "release": "semantic-release",
+    "browser": "node src/cli.js install-browser --version \"$npm_package_config_chrome\""
+  },
+  "config": {
+    "chrome": "156.0.8078.4"
   },
   "devDependencies": {
-    "@ai-ecoverse/slicc-kernel": "1.85.1",
-    "@ai-ecoverse/slicc-shared-web": "1.13.2",
+    "@ai-ecoverse/slicc-kernel": "1.92.0",
+    "@ai-ecoverse/slicc-shared-web": "1.15.1",
     "@biomejs/biome": "2.5.15",
-    "lefthook": "2.1.17",
-    "playwright-core": "1.63.0",
+    "lefthook": "2.2.0",
     "semantic-release": "25.0.9"
   }
 }

package/src/browser.js

@@ -0,0 +1,456 @@
+import { execFile as execFileCallback, spawn } from 'node:child_process';
+import { createWriteStream, existsSync, statSync } from 'node:fs';
+import { mkdir, mkdtemp, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { promisify } from 'node:util';
+
+const execFile = promisify(execFileCallback);
+
+export const CFT = 'https://googlechromelabs.github.io/chrome-for-testing';
+export const TRUSTED_HOSTS = ['googlechromelabs.github.io', 'storage.googleapis.com'];
+export const CHANNELS = ['Stable', 'Beta', 'Dev', 'Canary'];
+export const MARKER = '.slicc-cdp-browser.json';
+export const PROFILE_PREFIX = 'slicc-cdp-profile-';
+export const RESERVED_PORTS = [9222, 9229];
+const EXACT = /^\d+\.\d+\.\d+\.\d+$/u;
+const MILESTONE = /^\d+$/u;
+
+export function cftPlatform(platform = process.platform, arch = process.arch) {
+  if (platform === 'darwin') return arch === 'arm64' ? 'mac-arm64' : 'mac-x64';
+  if (platform === 'linux') {
+    if (arch === 'x64') return 'linux64';
+    if (arch === 'arm64') return 'linux-arm64';
+    return null;
+  }
+  if (platform === 'win32') return arch === 'ia32' ? 'win32' : 'win64';
+  return null;
+}
+
+export function executableIn(dir, platform) {
+  const root = join(dir, `chrome-${platform}`);
+  if (platform.startsWith('mac-')) {
+    return join(
+      root,
+      'Google Chrome for Testing.app',
+      'Contents',
+      'MacOS',
+      'Google Chrome for Testing'
+    );
+  }
+  if (platform.startsWith('win')) return join(root, 'chrome.exe');
+  return join(root, 'chrome');
+}
+
+export function browsersRoot(env = process.env, platform = process.platform, home = homedir()) {
+  if (env.SLICC_BROWSERS_PATH) return env.SLICC_BROWSERS_PATH;
+  if (platform === 'darwin') return join(home, 'Library', 'Caches', 'slicc-cdp', 'browsers');
+  if (platform === 'win32') {
+    return join(env.LOCALAPPDATA || join(home, 'AppData', 'Local'), 'slicc-cdp', 'browsers');
+  }
+  return join(env.XDG_CACHE_HOME || join(home, '.cache'), 'slicc-cdp', 'browsers');
+}
+
+export function systemCandidates(env = process.env, platform = process.platform) {
+  if (platform === 'darwin') {
+    return [
+      'Google Chrome',
+      'Google Chrome for Testing',
+      'Chromium',
+      'Google Chrome Canary',
+      'Google Chrome Beta',
+      'Google Chrome Dev',
+    ].map((app) => `/Applications/${app}.app/Contents/MacOS/${app}`);
+  }
+  if (platform === 'win32') {
+    const roots = [env.PROGRAMFILES, env['PROGRAMFILES(X86)'], env.LOCALAPPDATA].filter(Boolean);
+    return roots.flatMap((root) => [
+      join(root, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+      join(root, 'Chromium', 'Application', 'chrome.exe'),
+    ]);
+  }
+  return [
+    '/usr/bin/google-chrome',
+    '/usr/bin/google-chrome-stable',
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+    '/snap/bin/chromium',
+  ];
+}
+
+function isFile(path) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export function compareVersions(a, b) {
+  const left = a.split('.').map(Number);
+  const right = b.split('.').map(Number);
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const diff = (left[i] ?? 0) - (right[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+export async function installedBrowsers({ root = browsersRoot(), platform = cftPlatform() } = {}) {
+  const names = await readdir(root).catch(() => []);
+  const found = [];
+  for (const name of names) {
+    const marker = await readFile(join(root, name, MARKER), 'utf8').catch(() => null);
+    if (marker === null) continue;
+    let info;
+    try {
+      info = JSON.parse(marker);
+    } catch {
+      continue;
+    }
+    if (info.platform !== platform || typeof info.version !== 'string') continue;
+    const executable = executableIn(join(root, name), platform);
+    if (!isFile(executable)) continue;
+    found.push({ version: info.version, platform, dir: join(root, name), executable });
+  }
+  return found.sort((a, b) => compareVersions(b.version, a.version));
+}
+
+export async function findBrowser({
+  env = process.env,
+  platform = process.platform,
+  arch = process.arch,
+  root = browsersRoot(env, platform),
+  candidates = systemCandidates(env, platform),
+  version,
+} = {}) {
+  if (env.CHROME_PATH && !version) {
+    if (isFile(env.CHROME_PATH)) return { executable: env.CHROME_PATH, source: 'env' };
+    throw new Error(`CHROME_PATH is ${env.CHROME_PATH}, which is not a file`);
+  }
+  const target = cftPlatform(platform, arch);
+  if (target) {
+    const installs = await installedBrowsers({ root, platform: target });
+    const match = version
+      ? installs.find((item) => item.version === version || item.version.startsWith(`${version}.`))
+      : installs[0];
+    if (match) return { executable: match.executable, source: 'installed', version: match.version };
+    if (version) return null;
+  }
+  const system = candidates.find(isFile);
+  if (system) return { executable: system, source: 'system' };
+  return null;
+}
+
+export function trusted(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
+  }
+  return parsed.protocol === 'https:' && TRUSTED_HOSTS.includes(parsed.hostname);
+}
+
+function channelName(channel) {
+  const match = CHANNELS.find((name) => name.toLowerCase() === String(channel).toLowerCase());
+  if (!match) throw new Error(`unknown channel "${channel}" (expected ${CHANNELS.join(', ')})`);
+  return match;
+}
+
+async function json(fetchImpl, url) {
+  const response = await fetchImpl(url);
+  if (!response.ok) throw new Error(`GET ${url}: ${response.status} ${response.statusText}`);
+  return response.json();
+}
+
+export async function resolveRelease({
+  channel = 'Stable',
+  version,
+  fetch: fetchImpl = fetch,
+} = {}) {
+  let entry;
+  if (version && EXACT.test(version)) {
+    const data = await json(fetchImpl, `${CFT}/known-good-versions-with-downloads.json`);
+    entry = data.versions?.find((item) => item.version === version);
+  } else if (version && MILESTONE.test(version)) {
+    const data = await json(fetchImpl, `${CFT}/latest-versions-per-milestone-with-downloads.json`);
+    entry = data.milestones?.[version];
+  } else if (version) {
+    throw new Error(
+      `unsupported version "${version}" (expected a full version such as 148.0.7778.97, or a milestone)`
+    );
+  } else {
+    const data = await json(fetchImpl, `${CFT}/last-known-good-versions-with-downloads.json`);
+    entry = data.channels?.[channelName(channel)];
+  }
+  if (!entry) throw new Error(`Chrome for Testing has no release for ${version ?? channel}`);
+  return { version: entry.version, downloads: entry.downloads?.chrome ?? [] };
+}
+
+async function download(fetchImpl, url, file) {
+  if (!trusted(url)) {
+    throw new Error(`refusing to download ${url}: only https from ${TRUSTED_HOSTS.join(', ')}`);
+  }
+  const response = await fetchImpl(url, { redirect: 'error' });
+  if (!response.ok || !response.body) {
+    throw new Error(`GET ${url}: ${response.status} ${response.statusText}`);
+  }
+  await pipeline(Readable.fromWeb(response.body), createWriteStream(file));
+  const expected = Number(response.headers.get('content-length'));
+  const actual = statSync(file).size;
+  if (expected > 0 && actual !== expected) {
+    throw new Error(`GET ${url}: got ${actual} bytes, expected ${expected}`);
+  }
+}
+
+export async function extract(zip, dir, platform, run = execFile) {
+  if (platform.startsWith('mac')) return run('ditto', ['-x', '-k', zip, dir]);
+  if (platform.startsWith('win')) return run('tar', ['-xf', zip, '-C', dir]);
+  return run('unzip', ['-q', '-o', zip, '-d', dir]);
+}
+
+export async function verify(executable, version, platform, run = execFile) {
+  if (!isFile(executable)) throw new Error(`${executable} is missing after extraction`);
+  if (platform.startsWith('win')) {
+    const manifest = join(executable, '..', `${version}.manifest`);
+    if (!isFile(manifest)) throw new Error(`${manifest} is missing, so this is not ${version}`);
+    return;
+  }
+  const { stdout } = await run(executable, ['--version']);
+  if (!stdout.includes(version)) {
+    throw new Error(`${executable} --version printed "${stdout.trim()}", expected ${version}`);
+  }
+}
+
+export async function privilege({ run = execFile, uid = process.getuid?.() } = {}) {
+  if (uid === 0) return [];
+  const sudo = await run('sudo', ['-n', 'true']).then(
+    () => true,
+    () => false
+  );
+  if (sudo) return ['sudo', '-n'];
+  throw new Error(
+    '--with-deps installs system packages with apt-get and needs root or passwordless sudo'
+  );
+}
+
+export async function installDeps(
+  dir,
+  platform,
+  { run = execFile, uid = process.getuid?.() } = {}
+) {
+  if (!platform.startsWith('linux')) return;
+  const deps = await readFile(join(dir, `chrome-${platform}`, 'deb.deps'), 'utf8');
+  const list = deps
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+  if (list.length === 0) return;
+  const [file, ...prefix] = [...(await privilege({ run, uid })), 'apt-get'];
+  const env = { ...process.env, DEBIAN_FRONTEND: 'noninteractive' };
+  await run(file, [...prefix, 'update'], { env });
+  await run(file, [...prefix, 'satisfy', '-y', '--no-install-recommends', list.join(', ')], {
+    env,
+  });
+}
+
+export async function installBrowser({
+  channel = 'Stable',
+  version,
+  root = browsersRoot(),
+  platform = cftPlatform(),
+  withDeps = false,
+  force = false,
+  fetch: fetchImpl = fetch,
+  run = execFile,
+  uid = process.getuid?.(),
+  log = () => {},
+} = {}) {
+  if (!platform) {
+    throw new Error(`Chrome for Testing has no build for ${process.platform} ${process.arch}`);
+  }
+  const deps = (dir) => (withDeps ? installDeps(dir, platform, { run, uid }) : undefined);
+  if (version && EXACT.test(version) && !force) {
+    const installs = await installedBrowsers({ root, platform });
+    const ready = installs.find((item) => item.version === version);
+    if (ready) {
+      await deps(ready.dir);
+      return { ...ready, installed: false };
+    }
+  }
+  const release = await resolveRelease({ channel, version, fetch: fetchImpl });
+  const dir = join(root, `chrome-${release.version}-${platform}`);
+  const executable = executableIn(dir, platform);
+  if (!force && existsSync(join(dir, MARKER)) && isFile(executable)) {
+    await deps(dir);
+    return { version: release.version, platform, dir, executable, installed: false };
+  }
+  const url = release.downloads.find((item) => item.platform === platform)?.url;
+  if (!url) throw new Error(`Chrome for Testing ${release.version} has no ${platform} build`);
+  await mkdir(root, { recursive: true });
+  const staging = await mkdtemp(join(root, '.staging-'));
+  try {
+    const zip = join(staging, 'chrome.zip');
+    log(`downloading Chrome for Testing ${release.version} (${platform}) from ${url}`);
+    await download(fetchImpl, url, zip);
+    const unpacked = join(staging, 'unpacked');
+    await mkdir(unpacked);
+    await extract(zip, unpacked, platform, run);
+    await deps(unpacked);
+    await verify(executableIn(unpacked, platform), release.version, platform, run);
+    await writeFile(
+      join(unpacked, MARKER),
+      `${JSON.stringify({ version: release.version, platform, url }, null, 2)}\n`
+    );
+    await rm(dir, { recursive: true, force: true });
+    await rename(unpacked, dir);
+  } finally {
+    await rm(staging, { recursive: true, force: true });
+  }
+  log(`installed ${executable}`);
+  return { version: release.version, platform, dir, executable, installed: true };
+}
+
+export const LAUNCH_FLAGS = [
+  '--no-first-run',
+  '--no-default-browser-check',
+  '--disable-background-networking',
+  '--disable-component-update',
+  '--disable-sync',
+  '--password-store=basic',
+  '--use-mock-keychain',
+];
+
+export function launchArgs({ userDataDir, port = 0, headless = true, sandbox = true, args = [] }) {
+  return [
+    `--remote-debugging-port=${port}`,
+    '--remote-debugging-address=127.0.0.1',
+    `--user-data-dir=${userDataDir}`,
+    ...(headless ? ['--headless'] : []),
+    ...(sandbox ? [] : ['--no-sandbox']),
+    ...LAUNCH_FLAGS,
+    ...args,
+    'about:blank',
+  ];
+}
+
+export const OWNED_SWITCHES = [
+  '--remote-debugging-port',
+  '--remote-debugging-address',
+  '--remote-debugging-pipe',
+  '--user-data-dir',
+];
+
+function owned(arg) {
+  return OWNED_SWITCHES.some((name) => arg === name || arg.startsWith(`${name}=`));
+}
+
+const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const reserved = (port) => port >= RESERVED_PORTS[0] && port <= RESERVED_PORTS[1];
+const gone = (child) => child.exitCode !== null || child.signalCode !== null;
+
+async function versionAt(port, fetchImpl) {
+  try {
+    const response = await fetchImpl(`http://127.0.0.1:${port}/json/version`);
+    if (!response.ok) return null;
+    const { webSocketDebuggerUrl } = await response.json();
+    if (typeof webSocketDebuggerUrl !== 'string') return null;
+    return { port, path: new URL(webSocketDebuggerUrl).pathname };
+  } catch {
+    return null;
+  }
+}
+
+async function ready(userDataDir, port, child, deadline, fetchImpl) {
+  const file = join(userDataDir, 'DevToolsActivePort');
+  while (Date.now() < deadline) {
+    if (port === 0) {
+      const text = await readFile(file, 'utf8').catch(() => '');
+      const [found, path] = text.split('\n');
+      if (found && path) return { port: Number(found), path: path.trim() };
+    } else {
+      const found = await versionAt(port, fetchImpl);
+      if (found) return found;
+    }
+    if (gone(child)) return null;
+    await pause(50);
+  }
+  return null;
+}
+
+export async function launchBrowser({
+  executable,
+  userDataDir,
+  port = 0,
+  headless = true,
+  sandbox = true,
+  args = [],
+  env = process.env,
+  timeout = 30000,
+  fetch: fetchImpl = fetch,
+} = {}) {
+  const path = executable ?? (await findBrowser({ env }))?.executable;
+  if (!path) {
+    throw new Error(
+      'no Chrome or Chromium found: set CHROME_PATH or run `slicc-cdp install-browser`'
+    );
+  }
+  if (reserved(port)) {
+    throw new Error(`refusing to bind port ${port} (9222-9229 belong to the kernel and the probe)`);
+  }
+  const taken = args.find(owned);
+  if (taken) {
+    throw new Error(`args may not set ${taken}: use the port and userDataDir options`);
+  }
+  if (port !== 0 && (await versionAt(port, fetchImpl))) {
+    throw new Error(`a browser already listens on 127.0.0.1:${port}`);
+  }
+  const temporary = userDataDir === undefined;
+  const profile = userDataDir ?? (await mkdtemp(join(tmpdir(), PROFILE_PREFIX)));
+  await rm(join(profile, 'DevToolsActivePort'), { force: true });
+  let log = '';
+  const child = spawn(path, launchArgs({ userDataDir: profile, port, headless, sandbox, args }), {
+    env,
+    stdio: ['ignore', 'ignore', 'pipe'],
+  });
+  child.stderr.setEncoding('utf8');
+  child.stderr.on('data', (chunk) => {
+    log = (log + chunk).slice(-4000);
+  });
+  const spawned = new Promise((resolve) => child.once('error', resolve));
+  const exited = new Promise((resolve) => child.once('close', resolve));
+  const close = async () => {
+    if (child.pid !== undefined && !gone(child)) {
+      child.kill('SIGKILL');
+      await exited;
+    }
+    if (temporary) await rm(profile, { recursive: true, force: true });
+  };
+  const found = await Promise.race([
+    ready(profile, port, child, Date.now() + timeout, fetchImpl),
+    spawned.then((error) => ({ error })),
+  ]);
+  if (!found || found.error) {
+    const status = gone(child)
+      ? `exited with ${child.signalCode ?? `code ${child.exitCode}`}`
+      : `no DevTools endpoint after ${timeout} ms`;
+    await close();
+    const reason = found?.error?.message ?? (log.trim() || status);
+    throw new Error(`${path} did not start: ${reason}`);
+  }
+  if (reserved(found.port)) {
+    await close();
+    throw new Error(`browser bound reserved port ${found.port}`);
+  }
+  return {
+    child,
+    executable: path,
+    userDataDir: profile,
+    port: found.port,
+    wsUrl: `ws://127.0.0.1:${found.port}${found.path}`,
+    close,
+  };
+}

package/src/cli.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { browsersRoot, findBrowser, installBrowser } from './browser.js';
+
+export const USAGE = `usage: slicc-cdp <command> [options]
+
+commands:
+  install-browser   download Chrome for Testing, verify it, print its path
+      --version <x.y.z.w|milestone>   pin a full version (recommended) or a milestone
+      --channel <stable|beta|dev|canary>   without --version (default stable)
+      --path <dir>                    install root (default $SLICC_BROWSERS_PATH or the user cache)
+      --with-deps                     on Linux, apt-get Chrome's packages (needs root or sudo -n)
+      --force                         download again even when installed
+  find-browser      print the browser launchBrowser() uses: $CHROME_PATH, else the
+                    newest installed Chrome for Testing, else a system Chrome
+      --version <x.y.z.w|milestone>   only that installed Chrome for Testing ($CHROME_PATH is not used)
+  --version, -V     print the slicc-cdp version
+`;
+
+export const VERSION = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8')
+).version;
+
+export async function main(
+  argv,
+  io = { out: process.stdout, err: process.stderr, env: process.env }
+) {
+  const [command, ...rest] = argv;
+  if (!command || command === '--help' || command === '-h' || command === 'help') {
+    io.out.write(USAGE);
+    return command ? 0 : 2;
+  }
+  if (command === '--version' || command === '-V') {
+    io.out.write(`slicc-cdp ${VERSION}\n`);
+    return 0;
+  }
+  if (command === 'install-browser') {
+    const { values } = parseArgs({
+      args: rest,
+      options: {
+        channel: { type: 'string', default: 'stable' },
+        version: { type: 'string' },
+        path: { type: 'string' },
+        'with-deps': { type: 'boolean', default: false },
+        force: { type: 'boolean', default: false },
+      },
+    });
+    const result = await installBrowser({
+      channel: values.channel,
+      version: values.version,
+      root: values.path ?? browsersRoot(io.env),
+      withDeps: values['with-deps'],
+      force: values.force,
+      log: (line) => io.err.write(`${line}\n`),
+    });
+    if (!result.installed) {
+      io.err.write(`Chrome for Testing ${result.version} is already installed\n`);
+    }
+    io.out.write(`${result.executable}\n`);
+    return 0;
+  }
+  if (command === 'find-browser') {
+    const { values } = parseArgs({ args: rest, options: { version: { type: 'string' } } });
+    const found = await findBrowser({ env: io.env, version: values.version });
+    if (!found) {
+      io.err.write(
+        'no Chrome or Chromium found: set CHROME_PATH or run `slicc-cdp install-browser`\n'
+      );
+      return 1;
+    }
+    io.out.write(`${found.executable}\n`);
+    return 0;
+  }
+  io.err.write(`slicc-cdp: unknown command "${command}"\n${USAGE}`);
+  return 2;
+}
+
+const invoked = process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invoked) {
+  main(process.argv.slice(2)).then(
+    (code) => {
+      process.exitCode = code;
+    },
+    (error) => {
+      process.stderr.write(`slicc-cdp: ${error.message}\n`);
+      process.exitCode = 1;
+    }
+  );
+}

package/src/index.d.ts

@@ -31,3 +31,67 @@ export declare class CDPClient {
   attach(targetId: string): Promise<string>;
   close(): void;
 }
+
+export type CftPlatform = 'linux64' | 'linux-arm64' | 'mac-arm64' | 'mac-x64' | 'win32' | 'win64';
+
+export interface FoundBrowser {
+  executable: string;
+  source: 'env' | 'installed' | 'system';
+  version?: string;
+}
+
+export interface InstalledBrowser {
+  version: string;
+  platform: CftPlatform;
+  dir: string;
+  executable: string;
+}
+
+export declare function cftPlatform(platform?: string, arch?: string): CftPlatform | null;
+export declare function browsersRoot(
+  env?: Record<string, string | undefined>,
+  platform?: string,
+  home?: string
+): string;
+export declare function installedBrowsers(options?: {
+  root?: string;
+  platform?: CftPlatform;
+}): Promise<InstalledBrowser[]>;
+export declare function findBrowser(options?: {
+  env?: Record<string, string | undefined>;
+  platform?: string;
+  arch?: string;
+  root?: string;
+  candidates?: string[];
+  version?: string;
+}): Promise<FoundBrowser | null>;
+export declare function installBrowser(options?: {
+  channel?: string;
+  version?: string;
+  root?: string;
+  platform?: CftPlatform | null;
+  withDeps?: boolean;
+  force?: boolean;
+  fetch?: typeof fetch;
+  log?: (line: string) => void;
+}): Promise<InstalledBrowser & { installed: boolean }>;
+
+export interface LaunchedBrowser {
+  child: import('node:child_process').ChildProcess;
+  executable: string;
+  userDataDir: string;
+  port: number;
+  wsUrl: string;
+  close(): Promise<void>;
+}
+
+export declare function launchBrowser(options?: {
+  executable?: string;
+  userDataDir?: string;
+  port?: number;
+  headless?: boolean;
+  sandbox?: boolean;
+  args?: string[];
+  env?: Record<string, string | undefined>;
+  timeout?: number;
+}): Promise<LaunchedBrowser>;

package/src/index.js

@@ -1,2 +1,10 @@
+export {
+  browsersRoot,
+  cftPlatform,
+  findBrowser,
+  installBrowser,
+  installedBrowsers,
+  launchBrowser,
+} from './browser.js';
 export { CDPClient } from './cdp-client.js';
 export { connect } from './connect.js';