chrome-cdp-manager 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# chrome-cdp-manager
+
+Set up and drive a **Chrome DevTools Protocol (CDP)** instance on macOS through a
+dedicated `ChromeCDP.app` bundle, so launches always go through the same app and
+the **Dock icon stays consistent**.
+
+- Builds a real macOS `.app` bundle (`/Applications/ChromeCDP.app`) with a proper
+  `Info.plist` and Chrome's own icon — created automatically on first use.
+- Launches Chrome headed via `open <bundle>` (so LaunchServices attaches the
+  ChromeCDP Dock icon) or headless via `--headless=new`.
+- Connects over CDP with **zero heavy dependencies** — uses Node's built-in
+  `fetch` and `WebSocket` (no Playwright/Puppeteer, no browser download).
+
+> Requires macOS on Apple Silicon, Node.js ≥ 22, and Google Chrome installed.
+
+## Usage
+
+The package is published as `chrome-cdp-manager`; the command it installs is
+**`chrome-cdp`**.
+
+```bash
+# Run without installing — invoke via the package name
+npx chrome-cdp-manager setup
+
+# Or install once, then use the `chrome-cdp` command
+npm install -g chrome-cdp-manager
+```
+
+```bash
+# Create / repair ChromeCDP.app and save defaults (port 9222, profile ~/.chrome_cdp_profile)
+chrome-cdp setup
+
+# Launch ChromeCDP (Dock icon = ChromeCDP) and open a page
+chrome-cdp open https://example.com
+
+# Same, headless (no window/Dock)
+chrome-cdp open https://example.com --headless
+
+# Fetch a page's rendered HTML over CDP (headless by default)
+chrome-cdp html example.com -o page.html
+
+# Inspect state
+chrome-cdp status
+
+# Quit the running instance
+chrome-cdp stop
+```
+
+> Tip: with `npx`, run it by package name — `npx chrome-cdp-manager <command>` —
+> since `npx chrome-cdp` would try to fetch an unrelated `chrome-cdp` package.
+
+## Commands
+
+| Command            | Description                                                     |
+| ------------------ | --------------------------------------------------------------- |
+| `setup`            | Create or repair `ChromeCDP.app` (icon, `Info.plist`, launcher) |
+| `open [url]`       | Launch via the bundle, optionally open a URL; leaves it running |
+| `html <url>`       | Navigate and print/save the page's serialized HTML              |
+| `status`           | Show bundle presence and CDP connection state                   |
+| `stop`             | Ask the running ChromeCDP instance to quit                      |
+
+## Common options
+
+| Option                  | Description                                            |
+| ----------------------- | ------------------------------------------------------ |
+| `--port <port>`         | CDP port (default `9222`)                              |
+| `-p, --profile <dir>`   | Chrome `user-data-dir` (default `~/.chrome_cdp_profile`)|
+| `-c, --chrome <path>`   | Google Chrome executable                               |
+| `--bundle <path>`       | App bundle location (default `/Applications/ChromeCDP.app`) |
+| `-t, --timeout <secs>`  | Startup / load timeout (`open`, `html`)                |
+
+Port, profile, Chrome path and bundle path are baked into the app bundle and
+persisted (`~/.config/chrome-cdp-manager/config.json`) at `setup` time so every
+command agrees on the same environment. Re-run `setup --force` after changing
+them.
+
+## How the Dock icon stays consistent
+
+The bundle's executable is a small bash launcher:
+
+```bash
+exec arch -arm64 "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+  --remote-debugging-port=9222 \
+  --user-data-dir="$HOME/.chrome_cdp_profile" \
+  "$@"
+```
+
+Because headed launches go through `open /Applications/ChromeCDP.app`,
+LaunchServices runs Chrome under the ChromeCDP bundle identity — so you get the
+ChromeCDP Dock icon every time instead of a generic/duplicated Chrome entry.

package/bin/cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from "../src/cli.js";
+
+run(process.argv).catch((error) => {
+  console.error(`\nError: ${error.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "chrome-cdp-manager",
+  "version": "1.0.0",
+  "description": "Set up and drive a Chrome DevTools Protocol (CDP) instance on macOS through a dedicated ChromeCDP.app bundle, so the Dock icon stays consistent.",
+  "type": "module",
+  "bin": {
+    "chrome-cdp": "bin/cli.js",
+    "chrome-cdp-manager": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "os": [
+    "darwin"
+  ],
+  "scripts": {
+    "start": "node bin/cli.js",
+    "check": "node --check bin/cli.js && node --check src/cli.js",
+    "prepublishOnly": "npm run check",
+    "release": "bash scripts/publish.sh"
+  },
+  "keywords": [
+    "chrome",
+    "cdp",
+    "devtools-protocol",
+    "remote-debugging",
+    "headless",
+    "macos",
+    "automation"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.1.0"
+  }
+}

package/src/appBundle.js

@@ -0,0 +1,160 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+/**
+ * Build the bash launcher that the bundle executes. It bakes in the canonical
+ * Chrome path, CDP port and profile, and forwards any extra args (`"$@"`) so
+ * callers can append flags such as `--headless=new`.
+ */
+function launcherScript({ chromePath, cdpPort, profileDir }) {
+  return `#!/usr/bin/env bash
+# ChromeCDP launcher — generated by chrome-cdp-manager.
+# Re-run \`npx chrome-cdp-manager setup\` to regenerate this file.
+set -euo pipefail
+
+CHROME=${shellQuote(chromePath)}
+PORT=${shellQuote(String(cdpPort))}
+PROFILE=${shellQuote(profileDir)}
+
+exec arch -arm64 "$CHROME" \\
+  --remote-debugging-port="$PORT" \\
+  --user-data-dir="$PROFILE" \\
+  "$@"
+`;
+}
+
+function infoPlist({ bundleId, version = "1.0.0" }) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+\t<key>CFBundleName</key>
+\t<string>ChromeCDP</string>
+\t<key>CFBundleDisplayName</key>
+\t<string>ChromeCDP</string>
+\t<key>CFBundleIdentifier</key>
+\t<string>${bundleId}</string>
+\t<key>CFBundleVersion</key>
+\t<string>${version}</string>
+\t<key>CFBundleShortVersionString</key>
+\t<string>${version}</string>
+\t<key>CFBundlePackageType</key>
+\t<string>APPL</string>
+\t<key>CFBundleExecutable</key>
+\t<string>ChromeCDP</string>
+\t<key>CFBundleIconFile</key>
+\t<string>AppIcon</string>
+\t<key>LSMinimumSystemVersion</key>
+\t<string>11.0</string>
+\t<key>NSHighResolutionCapable</key>
+\t<true/>
+</dict>
+</plist>
+`;
+}
+
+/** Quote a value for safe single-quoted embedding in bash. */
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+/** Paths to the files that make up the bundle. */
+export function bundleLayout(bundlePath) {
+  const contents = path.join(bundlePath, "Contents");
+  return {
+    contents,
+    macOS: path.join(contents, "MacOS"),
+    resources: path.join(contents, "Resources"),
+    executable: path.join(contents, "MacOS", "ChromeCDP"),
+    plist: path.join(contents, "Info.plist"),
+    icon: path.join(contents, "Resources", "AppIcon.icns"),
+    legacyIcon: path.join(bundlePath, "Icon\r"),
+    legacyIconNoCR: path.join(bundlePath, "Icon"),
+  };
+}
+
+/** True when the bundle's executable launcher already exists. */
+export function bundleExists(bundlePath) {
+  return fs.existsSync(bundleLayout(bundlePath).executable);
+}
+
+/**
+ * Create or repair the ChromeCDP.app bundle so its Dock icon and launch
+ * behaviour are correct and consistent.
+ *
+ * @returns {{ created: boolean }} whether the bundle existed beforehand.
+ */
+export function ensureAppBundle(config, { force = false } = {}) {
+  const { bundlePath, chromePath, chromeIcon, cdpPort, profileDir, bundleId } =
+    config;
+  const layout = bundleLayout(bundlePath);
+  const existed = bundleExists(bundlePath);
+
+  if (existed && !force) {
+    return { created: false };
+  }
+
+  if (!fs.existsSync(chromePath)) {
+    throw new Error(
+      `Google Chrome not found at:\n  ${chromePath}\n` +
+        `Install Chrome or pass --chrome <path>.`,
+    );
+  }
+
+  try {
+    fs.mkdirSync(layout.macOS, { recursive: true });
+    fs.mkdirSync(layout.resources, { recursive: true });
+
+    fs.writeFileSync(
+      layout.executable,
+      launcherScript({ chromePath, cdpPort, profileDir }),
+      { mode: 0o755 },
+    );
+    fs.writeFileSync(layout.plist, infoPlist({ bundleId }));
+
+    // Use Chrome's own icon so the Dock entry is recognisable.
+    if (fs.existsSync(chromeIcon)) {
+      fs.copyFileSync(chromeIcon, layout.icon);
+    }
+
+    // Remove the legacy classic-Mac "Icon\r" resource-fork file if present;
+    // modern bundles render their icon from Info.plist + Resources/*.icns.
+    for (const stale of [layout.legacyIcon, layout.legacyIconNoCR]) {
+      try {
+        fs.rmSync(stale, { force: true });
+      } catch {
+        // best effort
+      }
+    }
+  } catch (error) {
+    if (error.code === "EACCES" || error.code === "EPERM") {
+      throw new Error(
+        `Permission denied writing to ${bundlePath}.\n` +
+          `Try: sudo npx chrome-cdp-manager setup`,
+      );
+    }
+    throw error;
+  }
+
+  refreshLaunchServices(bundlePath);
+  return { created: !existed };
+}
+
+/**
+ * Register the bundle with LaunchServices and bump its mtime so Finder/Dock
+ * pick up the (possibly new) icon without a logout.
+ */
+function refreshLaunchServices(bundlePath) {
+  const lsregister =
+    "/System/Library/Frameworks/CoreServices.framework/Frameworks/" +
+    "LaunchServices.framework/Support/lsregister";
+  try {
+    if (fs.existsSync(lsregister)) {
+      execFileSync(lsregister, ["-f", bundlePath], { stdio: "ignore" });
+    }
+    execFileSync("touch", [bundlePath]);
+  } catch {
+    // Non-fatal: the bundle still works, the icon cache may just lag.
+  }
+}

package/src/cdp.js

@@ -0,0 +1,168 @@
+/**
+ * Minimal Chrome DevTools Protocol client built on Node's global `fetch` and
+ * `WebSocket` (Node >= 22). Avoids a heavyweight Playwright/Puppeteer
+ * dependency so `npx` stays fast and browser-download free.
+ */
+export class CdpClient {
+  #ws;
+  #nextId = 0;
+  #pending = new Map();
+  #eventWaiters = new Map();
+
+  constructor(webSocketDebuggerUrl) {
+    this.url = webSocketDebuggerUrl;
+  }
+
+  /** Resolve the browser-level WebSocket endpoint and connect to it. */
+  static async connect(cdpPort) {
+    const res = await fetch(`http://127.0.0.1:${cdpPort}/json/version`);
+    if (!res.ok) {
+      throw new Error(`CDP not reachable on port ${cdpPort} (HTTP ${res.status}).`);
+    }
+    const { webSocketDebuggerUrl } = await res.json();
+    if (!webSocketDebuggerUrl) {
+      throw new Error("CDP did not advertise a webSocketDebuggerUrl.");
+    }
+    const client = new CdpClient(webSocketDebuggerUrl);
+    await client.#open();
+    return client;
+  }
+
+  #open() {
+    return new Promise((resolve, reject) => {
+      this.#ws = new WebSocket(this.url);
+      this.#ws.addEventListener("open", () => resolve(), { once: true });
+      this.#ws.addEventListener(
+        "error",
+        () => reject(new Error("Failed to open CDP WebSocket.")),
+        { once: true },
+      );
+      this.#ws.addEventListener("message", (ev) => this.#onMessage(ev));
+    });
+  }
+
+  #onMessage(ev) {
+    let data;
+    try {
+      data = JSON.parse(ev.data);
+    } catch {
+      return;
+    }
+
+    if (data.id !== undefined && this.#pending.has(data.id)) {
+      const { resolve, reject } = this.#pending.get(data.id);
+      this.#pending.delete(data.id);
+      if (data.error) reject(new Error(data.error.message));
+      else resolve(data.result);
+      return;
+    }
+
+    if (data.method) {
+      const key = eventKey(data.method, data.sessionId);
+      const waiter = this.#eventWaiters.get(key);
+      if (waiter) {
+        this.#eventWaiters.delete(key);
+        waiter(data.params);
+      }
+    }
+  }
+
+  /** Send a CDP command, optionally scoped to an attached session. */
+  send(method, params = {}, sessionId) {
+    const id = ++this.#nextId;
+    const message = { id, method, params };
+    if (sessionId) message.sessionId = sessionId;
+    this.#ws.send(JSON.stringify(message));
+    return new Promise((resolve, reject) => {
+      this.#pending.set(id, { resolve, reject });
+    });
+  }
+
+  /** Resolve the next time `method` fires (for the given session, if any). */
+  waitForEvent(method, sessionId) {
+    return new Promise((resolve) => {
+      this.#eventWaiters.set(eventKey(method, sessionId), resolve);
+    });
+  }
+
+  close() {
+    try {
+      this.#ws?.close();
+    } catch {
+      // ignore
+    }
+  }
+}
+
+function eventKey(method, sessionId) {
+  return sessionId ? `${sessionId}:${method}` : method;
+}
+
+/** Open a URL in a new tab and leave it running. Returns the new targetId. */
+export async function openUrl(cdpPort, url) {
+  const cdp = await CdpClient.connect(cdpPort);
+  try {
+    const { targetId } = await cdp.send("Target.createTarget", { url });
+    return targetId;
+  } finally {
+    cdp.close();
+  }
+}
+
+/**
+ * Navigate to a URL and return the page's serialized HTML.
+ * @param {object} opts
+ * @param {boolean} [opts.close] close the tab after capturing.
+ * @param {number} [opts.timeoutMs] navigation timeout.
+ */
+export async function getPageHtml(cdpPort, url, { close = false, timeoutMs = 30_000 } = {}) {
+  const cdp = await CdpClient.connect(cdpPort);
+  let targetId;
+  try {
+    ({ targetId } = await cdp.send("Target.createTarget", { url: "about:blank" }));
+    const { sessionId } = await cdp.send("Target.attachToTarget", {
+      targetId,
+      flatten: true,
+    });
+
+    await cdp.send("Page.enable", {}, sessionId);
+    const loaded = cdp.waitForEvent("Page.loadEventFired", sessionId);
+    await cdp.send("Page.navigate", { url }, sessionId);
+
+    await Promise.race([
+      loaded,
+      delay(timeoutMs).then(() => {
+        throw new Error(`Timed out loading ${url} after ${timeoutMs}ms.`);
+      }),
+    ]);
+
+    const { result } = await cdp.send(
+      "Runtime.evaluate",
+      {
+        expression: "document.documentElement.outerHTML",
+        returnByValue: true,
+      },
+      sessionId,
+    );
+    return result.value;
+  } finally {
+    if (close && targetId) {
+      await cdp.send("Target.closeTarget", { targetId }).catch(() => {});
+    }
+    cdp.close();
+  }
+}
+
+/** Close the entire browser via CDP (graceful quit). */
+export async function closeBrowser(cdpPort) {
+  const cdp = await CdpClient.connect(cdpPort);
+  try {
+    await cdp.send("Browser.close").catch(() => {});
+  } finally {
+    cdp.close();
+  }
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/chrome.js

@@ -0,0 +1,74 @@
+import { spawn } from "node:child_process";
+import { bundleLayout } from "./appBundle.js";
+
+/** CDP HTTP endpoint helper. */
+function versionUrl(cdpPort) {
+  return `http://127.0.0.1:${cdpPort}/json/version`;
+}
+
+/** Returns the CDP version payload if Chrome is already listening, else null. */
+export async function probeCdp(cdpPort) {
+  try {
+    const res = await fetch(versionUrl(cdpPort), {
+      signal: AbortSignal.timeout(1000),
+    });
+    if (res.ok) return await res.json();
+  } catch {
+    // not up
+  }
+  return null;
+}
+
+/**
+ * Launch Chrome through the ChromeCDP.app bundle.
+ *
+ * Headed mode goes through `open <bundle>` so LaunchServices attaches the
+ * ChromeCDP Dock icon. Headless mode runs the bundle's launcher directly
+ * (there is no Dock presence to keep consistent) and forwards `--headless=new`.
+ */
+export function launchChrome({ bundlePath, headless }) {
+  if (headless) {
+    const { executable } = bundleLayout(bundlePath);
+    const child = spawn(executable, ["--headless=new"], {
+      detached: true,
+      stdio: "ignore",
+    });
+    child.unref();
+    return;
+  }
+
+  // `open` returns immediately; readiness is awaited via waitForCdp().
+  const child = spawn("open", [bundlePath], { stdio: "ignore" });
+  child.unref();
+}
+
+/** Poll the CDP endpoint until it responds or the timeout elapses. */
+export async function waitForCdp(cdpPort, timeoutMs = 30_000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const version = await probeCdp(cdpPort);
+    if (version) return version;
+    await delay(250);
+  }
+  throw new Error(
+    `Timed out after ${Math.round(timeoutMs / 1000)}s waiting for Chrome CDP ` +
+      `at ${versionUrl(cdpPort)}.`,
+  );
+}
+
+/**
+ * Ensure Chrome is running and CDP is reachable, launching it if needed.
+ * @returns {Promise<{ launched: boolean, version: object }>}
+ */
+export async function ensureChromeRunning({ bundlePath, cdpPort, headless, timeoutMs }) {
+  const existing = await probeCdp(cdpPort);
+  if (existing) return { launched: false, version: existing };
+
+  launchChrome({ bundlePath, headless });
+  const version = await waitForCdp(cdpPort, timeoutMs);
+  return { launched: true, version };
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/cli.js

@@ -0,0 +1,78 @@
+import { createRequire } from "node:module";
+import { Command } from "commander";
+
+import { DEFAULTS } from "./config.js";
+import {
+  setupCommand,
+  openCommand,
+  htmlCommand,
+  statusCommand,
+  stopCommand,
+} from "./commands.js";
+
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+
+export async function run(argv) {
+  const program = new Command();
+
+  program
+    .name("chrome-cdp")
+    .description(
+      "Set up and drive a Chrome DevTools Protocol instance on macOS through a " +
+        "dedicated ChromeCDP.app bundle (consistent Dock icon).",
+    )
+    .version(version, "-v, --version");
+
+  // Options shared across commands.
+  const withCommon = (cmd) =>
+    cmd
+      .option("--port <port>", `CDP port (default: ${DEFAULTS.cdpPort})`)
+      .option("-p, --profile <dir>", "Chrome user-data-dir")
+      .option("-c, --chrome <path>", "Google Chrome executable path")
+      .option("--bundle <path>", `App bundle path (default: ${DEFAULTS.bundlePath})`);
+
+  withCommon(
+    program
+      .command("setup")
+      .description("Create or repair ChromeCDP.app (icon, Info.plist, launcher)")
+      .option("-f, --force", "Rewrite the bundle even if it already exists"),
+  ).action(setupCommand);
+
+  withCommon(
+    program
+      .command("open")
+      .argument("[url]", "URL to open after launch")
+      .description("Launch ChromeCDP via the app bundle and optionally open a URL")
+      .option("--headless", "Run headless (no window/Dock)", false)
+      .option("-t, --timeout <seconds>", "Startup timeout in seconds", "30"),
+  ).action(openCommand);
+
+  withCommon(
+    program
+      .command("html")
+      .argument("<url>", "URL to load")
+      .description("Print or save a page's HTML over CDP")
+      .option("--headless", "Run headless (default for html)")
+      .option("--headed", "Force a visible window")
+      .option("--close", "Close the tab when done", false)
+      .option("-o, --output <file>", "Write HTML to a file instead of stdout")
+      .option("-t, --timeout <seconds>", "Load timeout in seconds", "30"),
+  ).action((url, opts) => {
+    // --headed wins over --headless when both are passed.
+    const headless = opts.headed ? false : opts.headless;
+    return htmlCommand(url, { ...opts, headless });
+  });
+
+  withCommon(
+    program
+      .command("status")
+      .description("Show bundle and CDP connection status"),
+  ).action(statusCommand);
+
+  withCommon(
+    program.command("stop").description("Quit the running ChromeCDP instance"),
+  ).action(stopCommand);
+
+  await program.parseAsync(argv);
+}

package/src/commands.js

@@ -0,0 +1,154 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { DEFAULTS, loadConfig, saveConfig, CONFIG_FILE } from "./config.js";
+import { assertSupportedPlatform } from "./platform.js";
+import { ensureAppBundle, bundleExists } from "./appBundle.js";
+import { ensureChromeRunning, probeCdp } from "./chrome.js";
+import { openUrl, getPageHtml, closeBrowser } from "./cdp.js";
+
+/** Merge persisted config with CLI overrides into a fully-resolved config. */
+function resolveConfig(opts = {}) {
+  const stored = loadConfig();
+  const resolved = { ...stored };
+  if (opts.chrome) resolved.chromePath = opts.chrome;
+  if (opts.profile) resolved.profileDir = path.resolve(opts.profile);
+  if (opts.bundle) resolved.bundlePath = path.resolve(opts.bundle);
+  if (opts.port !== undefined) resolved.cdpPort = parsePort(opts.port);
+  return resolved;
+}
+
+function parsePort(value) {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`Invalid --port "${value}". Use an integer 1-65535.`);
+  }
+  return port;
+}
+
+function parseTimeoutMs(value, fallbackSeconds = 30) {
+  const seconds = value === undefined ? fallbackSeconds : Number(value);
+  if (!Number.isFinite(seconds) || seconds <= 0) {
+    throw new Error(`Invalid --timeout "${value}". Use seconds > 0.`);
+  }
+  return seconds * 1000;
+}
+
+function normalizeUrl(url) {
+  return /^[a-z]+:\/\//i.test(url) ? url : `https://${url}`;
+}
+
+/** Create the bundle on demand (without forcing a rewrite of an existing one). */
+function ensureBundleReady(config) {
+  const { created } = ensureAppBundle(config, { force: false });
+  if (created) {
+    console.error(`Created ${config.bundlePath} (Dock icon: Chrome).`);
+  }
+}
+
+// MARK: setup
+export async function setupCommand(opts) {
+  assertSupportedPlatform();
+  const config = resolveConfig(opts);
+  const { created } = ensureAppBundle(config, { force: true });
+  const file = saveConfig(config);
+
+  console.error(`${created ? "Created" : "Repaired"} ${config.bundlePath}`);
+  console.error(`  Chrome:   ${config.chromePath}`);
+  console.error(`  Profile:  ${config.profileDir}`);
+  console.error(`  CDP port: ${config.cdpPort}`);
+  console.error(`Config saved to ${file}`);
+}
+
+// MARK: open
+export async function openCommand(url, opts) {
+  assertSupportedPlatform();
+  const config = resolveConfig(opts);
+  const headless = Boolean(opts.headless);
+  const timeoutMs = parseTimeoutMs(opts.timeout);
+
+  ensureBundleReady(config);
+
+  const { launched } = await ensureChromeRunning({
+    bundlePath: config.bundlePath,
+    cdpPort: config.cdpPort,
+    headless,
+    timeoutMs,
+  });
+  console.error(
+    launched
+      ? `Launched ChromeCDP (${headless ? "headless" : "headed"}) on port ${config.cdpPort}.`
+      : `ChromeCDP already running on port ${config.cdpPort}.`,
+  );
+
+  if (url) {
+    const target = await openUrl(config.cdpPort, normalizeUrl(url));
+    console.error(`Opened ${normalizeUrl(url)} (target ${target}).`);
+  }
+  console.error(`DevTools: http://127.0.0.1:${config.cdpPort}/json`);
+}
+
+// MARK: html
+export async function htmlCommand(url, opts) {
+  assertSupportedPlatform();
+  const config = resolveConfig(opts);
+  const headless = opts.headless === undefined ? true : Boolean(opts.headless);
+  const timeoutMs = parseTimeoutMs(opts.timeout);
+  const target = normalizeUrl(url);
+
+  ensureBundleReady(config);
+  await ensureChromeRunning({
+    bundlePath: config.bundlePath,
+    cdpPort: config.cdpPort,
+    headless,
+    timeoutMs,
+  });
+
+  console.error(`Fetching HTML for ${target} ...`);
+  const html = await getPageHtml(config.cdpPort, target, {
+    close: Boolean(opts.close),
+    timeoutMs,
+  });
+
+  if (opts.output) {
+    const outPath = path.resolve(opts.output);
+    fs.writeFileSync(outPath, html);
+    console.error(`Saved HTML to ${outPath}`);
+  } else {
+    process.stdout.write(html.endsWith("\n") ? html : `${html}\n`);
+  }
+}
+
+// MARK: status
+export async function statusCommand(opts) {
+  assertSupportedPlatform();
+  const config = resolveConfig(opts);
+  const exists = bundleExists(config.bundlePath);
+  const version = await probeCdp(config.cdpPort);
+
+  console.log("ChromeCDP status");
+  console.log(`  Bundle:   ${exists ? "present" : "missing"} (${config.bundlePath})`);
+  console.log(`  Profile:  ${config.profileDir}`);
+  console.log(`  CDP port: ${config.cdpPort}`);
+  console.log(
+    version
+      ? `  Running:  yes — ${version.Browser} (${version["Protocol-Version"] ?? "?"})`
+      : "  Running:  no",
+  );
+  console.log(`  Config:   ${CONFIG_FILE}`);
+}
+
+// MARK: stop
+export async function stopCommand(opts) {
+  assertSupportedPlatform();
+  const config = resolveConfig(opts);
+  const version = await probeCdp(config.cdpPort);
+  if (!version) {
+    console.error(`No CDP instance reachable on port ${config.cdpPort}.`);
+    return;
+  }
+  await closeBrowser(config.cdpPort);
+  console.error(`Asked ChromeCDP on port ${config.cdpPort} to quit.`);
+}
+
+export { DEFAULTS };

package/src/config.js

@@ -0,0 +1,49 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * Default, canonical values for a ChromeCDP environment.
+ *
+ * These are baked into the ChromeCDP.app bundle at setup time and persisted to
+ * a config file so every subcommand agrees on the same port/profile/binary.
+ */
+export const DEFAULTS = Object.freeze({
+  chromePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+  chromeIcon: "/Applications/Google Chrome.app/Contents/Resources/app.icns",
+  bundlePath: "/Applications/ChromeCDP.app",
+  bundleId: "org.guocity.chrome-cdp",
+  cdpPort: 9222,
+  profileDir: path.join(os.homedir(), ".chrome_cdp_profile"),
+});
+
+const CONFIG_DIR = path.join(os.homedir(), ".config", "chrome-cdp-manager");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+
+/** Load persisted config, falling back to {@link DEFAULTS} for missing keys. */
+export function loadConfig() {
+  let stored = {};
+  try {
+    stored = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+  } catch {
+    // No config yet — first run.
+  }
+  return { ...DEFAULTS, ...stored };
+}
+
+/** Persist the resolved config so other commands stay in sync with the bundle. */
+export function saveConfig(config) {
+  const toStore = {
+    chromePath: config.chromePath,
+    chromeIcon: config.chromeIcon,
+    bundlePath: config.bundlePath,
+    bundleId: config.bundleId,
+    cdpPort: config.cdpPort,
+    profileDir: config.profileDir,
+  };
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_FILE, `${JSON.stringify(toStore, null, 2)}\n`);
+  return CONFIG_FILE;
+}
+
+export { CONFIG_FILE };

package/src/platform.js

@@ -0,0 +1,21 @@
+import os from "node:os";
+
+/**
+ * This tool builds a macOS `.app` bundle and relies on `arch -arm64` plus the
+ * `open` LaunchServices command, so it only runs on Apple Silicon macOS.
+ */
+export function assertSupportedPlatform() {
+  if (process.platform !== "darwin") {
+    throw new Error(
+      `chrome-cdp-manager only supports macOS (found "${process.platform}").`,
+    );
+  }
+  if (os.arch() !== "arm64") {
+    // Not fatal — the launcher uses `arch -arm64`, which is a no-op on arm64
+    // and an error on Intel. Warn rather than block in case of Rosetta setups.
+    process.emitWarning(
+      `Detected CPU arch "${os.arch()}". The launcher uses \`arch -arm64\`; ` +
+        `this is intended for Apple Silicon Macs.`,
+    );
+  }
+}