camoufox-playwright-cli 0.1.0 → 0.2.0

package/README.md

@@ -1,63 +1,81 @@
 # camoufox-playwright-cli
 
-Official [`@playwright/cli`](https://github.com/microsoft/playwright-cli) (Microsoft's Playwright CLI — open, click, fill, snapshot, tabs, network, tracing, video, ...), driven by [Camoufox](https://camoufox.com) instead of stock Chromium/Firefox, so the browser doesn't look automated.
+Camoufox configuration and fingerprint management for the official [Playwright CLI](https://github.com/microsoft/playwright-cli). No fork, protocol patches, command rewriting, or replacement `playwright-cli` executable.
 
-No fork of playwright-cli, no monkey-patching. Camoufox's stealth is just three standard Playwright launch options — `executablePath`, `firefoxUserPrefs`, and a `CAMOU_CONFIG_*` env blob — and playwright-cli already passes those through from a config file. This package generates that config for you and manages it as named **profiles**.
-
-Short alias: `cpw` (same binary as `camoufox-playwright-cli`).
+Requires Node.js 22 or newer.
 
 ## Install
 
-```bash
+```sh
+npm install -g @playwright/cli@0.1.12
 npm install -g camoufox-playwright-cli
 cpw install
+cpw doctor
+playwright-cli open https://example.com
 ```
 
-`install` downloads the Camoufox browser binary (shared cache, only happens once even across other Camoufox-based tools) and generates a `default` profile.
-
-## Profiles
+If you already have the official CLI, check its version before installing. `cpw` never installs or overwrites another CLI automatically. Only the validated version is accepted for setup and session cleanup; other versions remain usable directly at your own discretion.
 
-A profile is a fingerprint identity + its own isolated browser data (cookies, localStorage, login sessions) — think of it as "one persona". The `default` profile is created automatically and its fingerprint is generated from **your actual machine** where possible:
+`cpw install` downloads Camoufox, creates the default fingerprint, and sets it as the official CLI's global default in `~/.playwright/cli.config.json`. Existing unrelated settings are preserved. Browser launch settings are replaced together, including the executable, Firefox preferences and fingerprint environment. Remote browser and persistent-directory defaults are cleared to enable local Camoufox launches. This affects new CLI browser sessions, not already running browsers or ordinary Playwright libraries.
 
-- Real GPU vendor (via `Get-CimInstance Win32_VideoController` on Windows) — matched to the closest vendor bucket in Camoufox's curated WebGL database. Camoufox only ships a fixed, vetted set of older reference GPU models per vendor (no RTX 20/30/40-series entries at all, for example), so the *vendor* will match your real hardware but the exact renderer string won't be your literal card model. That vendor-match is what fingerprinting scripts actually cross-check; matching the exact model isn't possible through Camoufox's public API without maintaining a separate spoofing database, which is out of scope here.
-- Real screen resolution, locale, and timezone (via `Intl` + WMI).
+Project configuration, environment variables and explicit CLI flags can override the global default. `cpw doctor` reports project configuration and environment override names without printing environment values.
 
-If any of these can't be detected (non-Windows, sandboxed environment, etc.) that field silently falls back to Camoufox's own randomized default — it never errors out.
+## Profiles
 
-```bash
+```sh
 cpw profile list
 cpw profile create work
-cpw profile rotate work      # wipes cookies + regenerates fingerprint
+cpw profile use work
+cpw profile path work
+cpw profile rotate work
 cpw profile delete work
 ```
 
-Rotating or deleting a profile always wipes its browser session data first — keeping old cookies with a new fingerprint is itself an inconsistency signal, so we don't allow that combination.
+`use` changes the global default for new sessions. Close existing sessions before switching identities. An active global profile cannot be deleted; switch to another profile first. Rotating the active profile updates its global launch settings too.
 
-## Usage
+For simultaneous identities, use an explicit config on each `open`:
 
-Everything besides `install` and `profile` is forwarded verbatim to the real `playwright-cli`, with `--profile` mapped to its `-s=` session flag and (for `open`) `--config=` pointed at that profile's generated config:
+```sh
+playwright-cli -s=work open https://example.com --config=/absolute/path/from-profile-path
+playwright-cli -s=work snapshot
+playwright-cli -s=work close
+```
 
-```bash
-cpw open https://example.com
-cpw snapshot
-cpw click e3
-cpw fill e5 "hello"
-cpw screenshot --filename out.png
-cpw close
+Fingerprint names and CLI session names are independent. `rotate` and `delete` only clear the same-named CLI session in the current workspace. Before using them, close and clear any other sessions that use the fingerprint, including other workspaces and custom persistent data directories. The tool cannot infer every use of an exported config.
 
-cpw --profile=work open https://example.com   # separate identity + separate cookies
-```
+## Migration from 0.1
+
+Browser commands now go directly to `playwright-cli`; `cpw` only manages Camoufox. Existing fingerprint files remain usable. Run `cpw profile use default` to activate an existing profile without fetching a browser again.
 
-See the [playwright-cli command reference](https://github.com/microsoft/playwright-cli) for the full list — tabs, network routing, storage state, tracing, video recording, etc. all work unmodified.
+`--profile` has its official meaning: a persistent browser data directory. It no longer selects a Camoufox fingerprint. Use `cpw profile use` or `--config` instead. Official help, errors, skills and command prefixes remain unchanged.
 
-## How it works
+## Compatibility
 
-- [`camoufox-js`](https://github.com/apify/camoufox-js)'s `launchOptions()` computes `{executablePath, env, firefoxUserPrefs}` for a given fingerprint.
-- We write that into `~/.camoufox-playwright-cli/profiles/<name>/cli.config.json`, in the shape `@playwright/cli` expects (`browser.launchOptions`).
-- `cpw <command>` is a thin wrapper: it ensures that config exists, then spawns the real `playwright-cli` binary with `-s=<profile>` (and `--config=` on `open`) injected.
+Validated locally on Windows with Node.js 24.12.0:
+
+| Component | Version |
+| --- | --- |
+| Official CLI | 0.1.12 |
+| CLI's Playwright driver | 1.60.0-alpha-1778101408000 |
+| camoufox-js | 0.12.0 |
+| Camoufox browser | 152.0.4-beta.28 |
+| better-sqlite3 | 13.0.3 |
+
+CLI 0.1.19 was tested and rejected: its 1.63 alpha driver sends `viewport.isMobile`, which this Camoufox binary rejects when creating a page. `camoufox-js@0.12.0` declares `playwright-core <1.61.0`. CLI 0.1.12 is the newest published CLI whose declared driver is in the 1.60 line. This is a deliberate compatibility downgrade from the previous 0.1.18, not an upgrade to the latest CLI.
+
+Also validated on WSL Linux with Node.js 24.13.0, the same npm dependency versions, and Camoufox `152.0.4-beta.30`: configuration tests, browser interactions/context isolation, and official CLI persistent-cookie restart tests all passed. Install dependencies natively in WSL; do not reuse Windows `node_modules` or Windows executable paths.
+
+No transitive driver overrides or browser patches are used. Future CLI or browser updates require retesting; a pinned npm package does not pin the separately downloaded browser binary. The official CLI is a development dependency here for reproducible tests, and a separate installation for normal use.
+
+```sh
+npm ci
+npm test
+npm run test:browser
+npm run test:cli
+```
 
-Dependency versions (`@playwright/cli`, `camoufox-js`) are pinned exactly, not range-matched — both are young/prerelease packages and an unpinned `npm install` could silently pick up a breaking protocol change between Playwright's internal Firefox/Juggler driver and Camoufox's patched binary. Upgrades are deliberate, one version bump at a time, tested against the checks in this README before being released.
+Browser tests use generated HTML and a fresh browser context, not personal content. They check launch, input, click, accessibility text and context isolation. The CLI test additionally checks global configuration, leading session flags, persistent cookies across restart and upstream error help. These checks do not establish compatibility for every CLI feature or operating system.
 
-## Security note
+## Fingerprints
 
-The `env` passed to the Camoufox process is an explicit allowlist (`PATH`, temp dirs, etc.) — never your full shell environment. Don't widen it without checking what secrets might be sitting in `process.env`.
+Profiles live in `~/.camoufox-playwright-cli/profiles/<name>/cli.config.json`. Host OS, locale, screen and a vendor-matched WebGL identity feed Camoufox's fingerprint generator. Browser launch environment variables use an explicit allowlist; the full shell environment is never serialized into profile files.

package/bin/cli.js

@@ -1,172 +1,181 @@
 #!/usr/bin/env node
-import { spawnSync } from "node:child_process";
-import {
-  DEFAULT_PROFILE,
-  ensureProfile,
-  profileConfigPath,
-  profileExists,
-  listProfiles,
-  deleteProfileFiles,
-} from "../src/profiles.js";
-import { playwrightCliBin, camoufoxJsBin } from "../src/paths.js";
-
-function extractProfileFlag(argv) {
-  let profile = DEFAULT_PROFILE;
-  const rest = [];
-  for (const arg of argv) {
-    if (arg.startsWith("--profile=")) {
-      profile = arg.slice("--profile=".length);
-    } else {
-      rest.push(arg);
-    }
-  }
-  return { profile, rest };
-}
-
-async function main() {
-  const { profile, rest } = extractProfileFlag(process.argv.slice(2));
-  const [command, ...args] = rest;
-
-  switch (command) {
-    case "install":
-      return runInstall();
-    case "profile":
-      return runProfile(args);
-    case undefined:
-    case "-h":
-    case "--help":
-      return printHelp();
-    default:
-      return runPlaywrightCli(profile, rest);
-  }
-}
-
-function runCamoufoxFetch() {
-  const result = spawnSync(process.execPath, [camoufoxJsBin(), "fetch"], { stdio: "inherit" });
-  if (result.status !== 0) process.exit(result.status ?? 1);
-}
-
-// Stops the daemon (if running) and wipes its browser profile dir (cookies,
-// storage). Used before rotate/delete so a new fingerprint never keeps the
-// old identity's login state — a fingerprint change with stale cookies is
-// itself an inconsistency signal.
-function resetSessionData(profileName) {
-  spawnSync(process.execPath, [playwrightCliBin(), `-s=${profileName}`, "close"], { stdio: "ignore" });
-  spawnSync(process.execPath, [playwrightCliBin(), `-s=${profileName}`, "delete-data"], { stdio: "ignore" });
-}
-
-async function runInstall() {
-  console.log("Downloading Camoufox browser binary (this only needs to run once)...");
-  runCamoufoxFetch();
-
-  console.log("\nGenerating default profile from your machine's real parameters...");
-  const file = await ensureProfile(DEFAULT_PROFILE);
-  console.log(`Profile written to ${file}`);
-  console.log("\nDone. Try: camoufox-playwright-cli open https://example.com");
-}
-
-async function runProfile(args) {
-  const [sub, name] = args;
-  switch (sub) {
-    case "list": {
-      const profiles = await listProfiles();
-      if (profiles.length === 0) {
-        console.log("No profiles yet. Run `camoufox-playwright-cli install` first.");
-        return;
-      }
-      for (const p of profiles) {
-        console.log(`${p.name}${p.name === DEFAULT_PROFILE ? " (default)" : ""}`);
-        console.log(`  created: ${p.createdAt}`);
-        console.log(`  os: ${p.os}  locale: ${p.locale}  timezone: ${p.timezone}`);
-        console.log(`  screen: ${JSON.stringify(p.screen)}`);
-        console.log(`  gpu: ${JSON.stringify(p.gpu)}`);
-      }
-      return;
-    }
-    case "create": {
-      if (!name) return console.error("Usage: camoufox-playwright-cli profile create <name>");
-      if (profileExists(name)) return console.error(`Profile "${name}" already exists. Use \`profile rotate ${name}\` to regenerate it.`);
-      const file = await ensureProfile(name);
-      console.log(`Created profile "${name}" -> ${file}`);
-      return;
-    }
-    case "rotate": {
-      const target = name || DEFAULT_PROFILE;
-      if (!profileExists(target)) return console.error(`Profile "${target}" does not exist. Use \`profile create ${target}\` first.`);
-      resetSessionData(target);
-      const file = await ensureProfile(target, { rotate: true });
-      console.log(`Rotated profile "${target}" (browser data wiped, new fingerprint generated) -> ${file}`);
-      return;
-    }
-    case "delete": {
-      if (!name) return console.error("Usage: camoufox-playwright-cli profile delete <name>");
-      if (name === DEFAULT_PROFILE) return console.error(`Refusing to delete the "${DEFAULT_PROFILE}" profile. Use \`profile rotate\` instead.`);
-      resetSessionData(name);
-      const existed = await deleteProfileFiles(name);
-      console.log(existed ? `Deleted profile "${name}"` : `Profile "${name}" did not exist`);
-      return;
-    }
-    default:
-      console.log(`Usage:
-  camoufox-playwright-cli profile list
-  camoufox-playwright-cli profile create <name>
-  camoufox-playwright-cli profile rotate [name]   (defaults to "default")
-  camoufox-playwright-cli profile delete <name>`);
-  }
-}
-
-async function runPlaywrightCli(profile, argv) {
-  if (!profileExists(profile)) {
-    if (profile === DEFAULT_PROFILE) {
-      console.log("No default profile yet - running setup first...");
-      runCamoufoxFetch();
-      await ensureProfile(DEFAULT_PROFILE);
-    } else {
-      console.error(`Profile "${profile}" does not exist. Create it with: camoufox-playwright-cli profile create ${profile}`);
-      process.exit(1);
-    }
-  }
-
-  const configFile = profileConfigPath(profile);
-  const finalArgs = [...argv];
-
-  if (!finalArgs.some((a) => a === "-s" || a.startsWith("-s="))) {
-    finalArgs.push(`-s=${profile}`);
-  }
-  if (finalArgs[0] === "open" && !finalArgs.some((a) => a.startsWith("--config"))) {
-    finalArgs.push(`--config=${configFile}`);
-  }
-
-  const result = spawnSync(process.execPath, [playwrightCliBin(), ...finalArgs], { stdio: "inherit" });
-  process.exit(result.status ?? 0);
-}
-
-function printHelp() {
-  console.log(`camoufox-playwright-cli (alias: cpw) - Playwright CLI (@playwright/cli), driven by Camoufox (stealth Firefox)
-
-Setup (run once):
-  cpw install                 Download Camoufox + generate the "default" profile
-
-Profiles (fingerprint + isolated browser data, one per identity):
-  cpw profile list
-  cpw profile create <name>
-  cpw profile rotate [name]    Wipe cookies + regenerate fingerprint (defaults to "default")
-  cpw profile delete <name>
-
-Everything else is forwarded to the real playwright-cli, pointed at Camoufox.
-Use --profile=<name> to pick which identity to drive (defaults to "default"):
-  cpw open <url>
-  cpw --profile=work open <url>
-  cpw snapshot
-  cpw click <ref>
-  cpw fill <ref> <text>
-  cpw screenshot
-  cpw close
-
-("camoufox-playwright-cli" also works everywhere "cpw" does — same binary, two names.)
-
-See https://github.com/microsoft/playwright-cli for the full command reference.
-`);
-}
-
-main();
+import { spawnSync } from "node:child_process";
+import {
+  DEFAULT_PROFILE,
+  ensureProfile,
+  profileConfigPath,
+  profileExists,
+  listProfiles,
+  deleteProfileFiles,
+  readProfileConfig,
+} from "../src/profiles.js";
+import { camoufoxJsBin } from "../src/paths.js";
+import { activateProfile, readJson, globalConfigPath } from "../src/config.js";
+import { installedCLI, requireCompatibleCLI, RECOMMENDED_CLI } from "../src/compatibility.js";
+import { isDeepStrictEqual } from "node:util";
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+async function main() {
+  const [command, ...args] = process.argv.slice(2);
+
+  switch (command) {
+    case "install":
+      return runInstall();
+    case "doctor":
+      return runDoctor();
+    case "profile":
+      return runProfile(args);
+    case undefined:
+    case "-h":
+    case "--help":
+      return printHelp();
+    default:
+      throw new Error("Browser commands now use official playwright-cli. Run playwright-cli --help.");
+  }
+}
+
+function runCamoufoxFetch() {
+  const result = spawnSync(process.execPath, [camoufoxJsBin(), "fetch"], { stdio: "inherit" });
+  if (result.status !== 0) process.exit(result.status ?? 1);
+}
+
+// Only the same-named session in the current workspace is managed here.
+function resetSessionData(profileName) {
+  const { bin } = requireCompatibleCLI();
+  for (const command of ["close", "delete-data"]) {
+    const result = spawnSync(process.execPath, [bin, `-s=${profileName}`, command], { stdio: "inherit" });
+    if (result.error || result.status !== 0) throw new Error(`Session cleanup failed: ${command}`);
+  }
+}
+
+async function runInstall() {
+  requireCompatibleCLI();
+  console.log("Downloading Camoufox browser binary (this only needs to run once)...");
+  runCamoufoxFetch();
+
+  console.log("\nGenerating default profile from your machine's real parameters...");
+  const file = await ensureProfile(DEFAULT_PROFILE);
+  console.log(`Profile written to ${file}`);
+  await activateProfile(await readProfileConfig(DEFAULT_PROFILE));
+  console.log("\nDone. Try: playwright-cli open https://example.com");
+}
+
+async function runProfile(args) {
+  const [sub, name] = args;
+  switch (sub) {
+    case "list": {
+      const profiles = await listProfiles();
+      if (profiles.length === 0) {
+        console.log("No profiles yet. Run `camoufox-playwright-cli install` first.");
+        return;
+      }
+      for (const p of profiles) {
+        console.log(`${p.name}${await isActive(p.name) ? " (active global default)" : ""}`);
+        console.log(`  created: ${p.createdAt}`);
+        console.log(`  os: ${p.os}  locale: ${p.locale}  timezone: ${p.timezone}`);
+        console.log(`  screen: ${JSON.stringify(p.screen)}`);
+        console.log(`  gpu: ${JSON.stringify(p.gpu)}`);
+      }
+      return;
+    }
+    case "use": {
+      if (!name || !profileExists(name)) throw new Error("Usage: cpw profile use <existing-name>");
+      requireCompatibleCLI();
+      console.log(`Global Camoufox config: ${await activateProfile(await readProfileConfig(name))}`);
+      console.log("Applies to new sessions. Close existing sessions before switching identities.");
+      return;
+    }
+    case "path": {
+      if (!name || !profileExists(name)) throw new Error("Usage: cpw profile path <existing-name>");
+      console.log(profileConfigPath(name));
+      return;
+    }
+    case "create": {
+      if (!name) throw new Error("Usage: camoufox-playwright-cli profile create <name>");
+      if (profileExists(name)) throw new Error(`Profile "${name}" already exists. Use \`profile rotate ${name}\` to regenerate it.`);
+      const file = await ensureProfile(name);
+      console.log(`Created profile "${name}" -> ${file}`);
+      return;
+    }
+    case "rotate": {
+      const target = name || DEFAULT_PROFILE;
+      if (!profileExists(target)) throw new Error(`Profile "${target}" does not exist. Use \`profile create ${target}\` first.`);
+      const active = await isActive(target);
+      resetSessionData(target);
+      const file = await ensureProfile(target, { rotate: true });
+      if (active) await activateProfile(await readProfileConfig(target));
+      console.log(`Rotated profile "${target}" (same-named workspace session cleared, new fingerprint generated) -> ${file}`);
+      return;
+    }
+    case "delete": {
+      if (!name) throw new Error("Usage: camoufox-playwright-cli profile delete <name>");
+      if (name === DEFAULT_PROFILE) throw new Error(`Refusing to delete the "${DEFAULT_PROFILE}" profile. Use \`profile rotate\` instead.`);
+      if (await isActive(name)) throw new Error("Switch the global default before deleting this profile.");
+      resetSessionData(name);
+      const existed = await deleteProfileFiles(name);
+      console.log(existed ? `Deleted profile "${name}"` : `Profile "${name}" did not exist`);
+      return;
+    }
+    default:
+      console.log(`Usage:
+  camoufox-playwright-cli profile list
+  camoufox-playwright-cli profile use <name>
+  camoufox-playwright-cli profile path <name>
+  camoufox-playwright-cli profile create <name>
+  camoufox-playwright-cli profile rotate [name]   (defaults to "default")
+  camoufox-playwright-cli profile delete <name>`);
+  }
+}
+
+async function isActive(name) {
+  const current = await readJson(globalConfigPath());
+  const profile = await readProfileConfig(name);
+  return !!profile && isDeepStrictEqual(current?.browser?.launchOptions, profile.browser.launchOptions);
+}
+
+async function runDoctor() {
+  const cli = installedCLI();
+  console.log(`Official CLI: ${cli ? `${cli.version} (driver ${cli.driver}) at ${cli.command}` : 'missing'}`);
+  console.log(`Validated CLI: ${RECOMMENDED_CLI}`);
+  const config = await readJson(globalConfigPath());
+  const executable = config?.browser?.launchOptions?.executablePath;
+  console.log(`Global config: ${globalConfigPath()}`);
+  console.log(`Browser: ${config?.browser?.browserName ?? 'not configured'}`);
+  console.log(`Executable exists: ${!!executable && existsSync(executable)}`);
+  const local = path.resolve('.playwright', 'cli.config.json');
+  if (existsSync(local)) console.log(`Project override: ${local}`);
+  for (const key of Object.keys(process.env).filter(key => key.startsWith('PLAYWRIGHT_MCP_') || key === 'PWTEST_CLI_GLOBAL_CONFIG')) {
+    console.log(`Environment override present: ${key}`);
+  }
+  requireCompatibleCLI();
+  if (config?.browser?.browserName !== 'firefox' || !executable || !existsSync(executable)) {
+    throw new Error('Camoufox default is not configured. Run cpw install or cpw profile use <name>.');
+  }
+}
+
+function printHelp() {
+  console.log(`cpw - Camoufox configuration for the official Playwright CLI
+
+  cpw install                  Fetch Camoufox, create and activate default profile
+  cpw doctor                   Check official CLI and browser configuration
+  cpw profile list
+  cpw profile create <name>
+  cpw profile use <name>        Set the global default for new sessions
+  cpw profile path <name>       Print config path for --config
+  cpw profile rotate [name]     Reset same-named session in this workspace
+  cpw profile delete <name>     Reset same-named session and delete fingerprint
+
+Browser operations use official commands:
+  playwright-cli open <url>
+  playwright-cli -s=work open <url> --config=<path-from-cpw-profile-path>
+  playwright-cli click <ref>
+  playwright-cli close
+
+--profile belongs to the official CLI and means a persistent data directory.
+Before rotating/deleting, close and clear any other sessions using that fingerprint,
+including sessions in other projects or custom persistent directories.
+`);
+}
+
+main().catch(error => { console.error(error.message); process.exitCode = 1; });

package/package.json

@@ -1,39 +1,46 @@
-{
-  "name": "camoufox-playwright-cli",
-  "version": "0.1.0",
-  "description": "Playwright CLI (@playwright/cli), driven by Camoufox for stealth browsing. Profile-based: auto-generated default fingerprint on install, create/rotate/delete named profiles.",
-  "type": "module",
-  "bin": {
-    "camoufox-playwright-cli": "bin/cli.js",
-    "cpw": "bin/cli.js"
-  },
-  "files": [
-    "bin",
-    "src",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "license": "MIT",
-  "author": "Shun",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ShunL12324/camoufox-playwright-cli.git"
-  },
-  "keywords": [
-    "camoufox",
-    "playwright",
-    "stealth",
-    "anti-detect",
-    "browser-automation",
-    "cli",
-    "profiles"
-  ],
-  "dependencies": {
-    "@playwright/cli": "0.1.18",
-    "better-sqlite3": "13.0.1",
-    "camoufox-js": "0.12.0"
-  }
-}
+{
+  "name": "camoufox-playwright-cli",
+  "version": "0.2.0",
+  "description": "Playwright CLI (@playwright/cli), driven by Camoufox for stealth browsing. Profile-based: auto-generated default fingerprint on install, create/rotate/delete named profiles.",
+  "type": "module",
+  "bin": {
+    "camoufox-playwright-cli": "bin/cli.js",
+    "cpw": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "author": "Shun",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShunL12324/camoufox-playwright-cli.git"
+  },
+  "keywords": [
+    "camoufox",
+    "playwright",
+    "stealth",
+    "anti-detect",
+    "browser-automation",
+    "cli",
+    "profiles"
+  ],
+  "dependencies": {
+    "better-sqlite3": "13.0.3",
+    "camoufox-js": "0.12.0"
+  },
+  "scripts": {
+    "test": "node --test test/config.test.mjs",
+    "test:browser": "node test/browser-smoke.mjs",
+    "test:cli": "node test/cli-smoke.mjs"
+  },
+  "devDependencies": {
+    "@playwright/cli": "0.1.12"
+  }
+}

package/src/compatibility.js

@@ -0,0 +1,31 @@
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+export const RECOMMENDED_CLI = '0.1.12';
+
+// Resolve the executable actually exposed on PATH; never shadow it with our bin.
+export function installedCLI() {
+  for (const directory of (process.env.PATH ?? '').split(path.delimiter)) {
+    if (!directory) continue;
+    const command = path.join(directory, process.platform === 'win32' ? 'playwright-cli.cmd' : 'playwright-cli');
+    if (!existsSync(command)) continue;
+    const bin = process.platform === 'win32'
+      ? path.join(directory, 'node_modules', '@playwright', 'cli', 'playwright-cli.js')
+      : realpathSync(command);
+    if (!existsSync(bin)) throw new Error(`Unrecognized playwright-cli installation: ${command}`);
+    const pkg = JSON.parse(readFileSync(path.join(path.dirname(bin), 'package.json'), 'utf8'));
+    if (pkg.name !== '@playwright/cli') throw new Error(`Unexpected package behind ${command}`);
+    const require = createRequire(bin);
+    return { bin, command, version: pkg.version, driver: require('playwright-core/package.json').version };
+  }
+  return null;
+}
+
+export function requireCompatibleCLI() {
+  const cli = installedCLI();
+  if (!cli || cli.version !== RECOMMENDED_CLI) {
+    throw new Error(`${cli ? `Installed CLI ${cli.version} is not validated.` : 'Official playwright-cli is not installed on PATH.'} Recommended: npm install -g @playwright/cli@${RECOMMENDED_CLI}. Existing installations are never overwritten automatically.`);
+  }
+  return cli;
+}

package/src/config.js

@@ -0,0 +1,35 @@
+import { mkdir, readFile, writeFile, rename, unlink } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export const globalConfigPath = () => path.join(os.homedir(), '.playwright', 'cli.config.json');
+
+export async function readJson(file) {
+  try { return JSON.parse(await readFile(file, 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+// Preserve unrelated settings, but replace launch settings as one coherent set.
+export function mergeCamoufoxConfig(existing, profile) {
+  const browser = { ...existing?.browser, ...profile.browser };
+  for (const key of ['remoteEndpoint', 'cdpEndpoint', 'userDataDir', 'isolated']) delete browser[key];
+  return { ...existing, extension: false, browser };
+}
+
+export async function writeJson(file, value) {
+  await mkdir(path.dirname(file), { recursive: true });
+  const pending = `${file}.${randomUUID()}.pending`;
+  try {
+    await writeFile(pending, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 });
+    await rename(pending, file);
+  } finally {
+    await unlink(pending).catch(error => { if (error.code !== 'ENOENT') throw error; });
+  }
+}
+
+export async function activateProfile(profile, file = globalConfigPath()) {
+  const existing = await readJson(file);
+  await writeJson(file, mergeCamoufoxConfig(existing, profile));
+  return file;
+}

package/src/paths.js

@@ -1,19 +1,12 @@
-import { createRequire } from "node:module";
-import path from "node:path";
-
-const require = createRequire(import.meta.url);
-
-export function playwrightCliBin() {
-  const pkgJsonPath = require.resolve("@playwright/cli/package.json");
-  const pkgDir = path.dirname(pkgJsonPath);
-  const pkg = require(pkgJsonPath);
-  return path.join(pkgDir, pkg.bin["playwright-cli"]);
-}
-
-export function camoufoxJsBin() {
-  const pkgJsonPath = require.resolve("camoufox-js/package.json");
-  const pkgDir = path.dirname(pkgJsonPath);
-  const pkg = require(pkgJsonPath);
-  const bin = typeof pkg.bin === "string" ? pkg.bin : Object.values(pkg.bin)[0];
-  return path.join(pkgDir, bin);
-}
+import { createRequire } from "node:module";
+import path from "node:path";
+
+const require = createRequire(import.meta.url);
+
+export function camoufoxJsBin() {
+  const pkgJsonPath = require.resolve("camoufox-js/package.json");
+  const pkgDir = path.dirname(pkgJsonPath);
+  const pkg = require(pkgJsonPath);
+  const bin = typeof pkg.bin === "string" ? pkg.bin : Object.values(pkg.bin)[0];
+  return path.join(pkgDir, bin);
+}