chrome-proc 1.0.0

package/.claude/scripts/publish-npm.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+cd "$PROJECT_DIR"
+
+echo "=== npm publish routine for chrome-proc ==="
+
+# 1. Verify npm auth
+echo ""
+echo "[1/5] Checking npm authentication..."
+if ! npm whoami > /dev/null 2>&1; then
+    echo "ERROR: You are not logged into npm."
+    echo "Please run: npm login"
+    echo "Then re-run this script."
+    exit 1
+fi
+USERNAME=$(npm whoami)
+echo "Authenticated as: $USERNAME"
+
+# 2. Build project
+echo ""
+echo "[2/5] Building project..."
+npm run build
+
+# 3. Verify artifacts
+echo ""
+echo "[3/5] Verifying build artifacts..."
+if [ ! -f "dist/index.js" ]; then
+    echo "ERROR: dist/index.js not found. Build may have failed."
+    exit 1
+fi
+if [ ! -f "bin/chrome-proc" ]; then
+    echo "ERROR: bin/chrome-proc not found."
+    exit 1
+fi
+echo "Artifacts verified."
+
+# 4. Check if version already exists
+echo ""
+echo "[4/5] Checking if version already exists on npm..."
+VERSION=$(node -p "require('./package.json').version")
+if npm view "chrome-proc@$VERSION" version > /dev/null 2>&1; then
+    echo "ERROR: chrome-proc@$VERSION already exists on npm."
+    echo "Please bump the version in package.json before publishing."
+    exit 1
+fi
+echo "Version $VERSION is available for publish."
+
+# 5. Publish
+echo ""
+echo "[5/5] Publishing chrome-proc@$VERSION to npm..."
+npm publish --access public
+
+# 6. Verify
+echo ""
+echo "Verifying publish..."
+sleep 2
+PUBLISHED_VERSION=$(npm view chrome-proc version 2>/dev/null || echo "")
+if [ "$PUBLISHED_VERSION" = "$VERSION" ]; then
+    echo "SUCCESS: chrome-proc@$VERSION is now live on npm!"
+    echo ""
+    echo "You can install it with:"
+    echo "  npm install -g chrome-proc"
+else
+    echo "WARNING: Publish command succeeded but verification failed."
+    echo "Published version: $PUBLISHED_VERSION"
+    echo "Expected version: $VERSION"
+    echo "Check https://www.npmjs.com/package/chrome-proc for status."
+fi

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bing Tong
+
+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 @@
+

package/bin/chrome-proc

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/index.js');

package/dist/commands/cdp.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cdpCommand = cdpCommand;
+const process_1 = require("../utils/process");
+const format_1 = require("../utils/format");
+async function cdpCommand(options) {
+    const pids = (0, process_1.getChromePids)(true);
+    if (pids.length === 0) {
+        console.error("(no Chrome processes found)");
+        process.exit(1);
+    }
+    const ports = [];
+    for (const pid of pids) {
+        const args = (0, process_1.getProcessArgs)(pid);
+        const port = (0, process_1.extractDebugPort)(args);
+        if (port !== null && !ports.includes(port)) {
+            ports.push(port);
+        }
+    }
+    if (ports.length === 0) {
+        console.error("(no Chrome processes found with remote debugging enabled)");
+        process.exit(1);
+    }
+    let any = false;
+    let printedHeader = false;
+    for (const port of ports) {
+        const base = `http://localhost:${port}`;
+        let verResp = null;
+        let listResp = null;
+        try {
+            const ver = await fetchWithTimeout(`${base}/json/version`, 3000);
+            verResp = (await ver.json());
+        }
+        catch {
+            verResp = null;
+        }
+        try {
+            const list = await fetchWithTimeout(`${base}/json/list`, 3000);
+            listResp = (await list.json());
+        }
+        catch {
+            listResp = null;
+        }
+        if (!verResp && !listResp) {
+            console.error(`Warning: failed to query debug endpoint on port ${port}`);
+            continue;
+        }
+        any = true;
+        if (options.json) {
+            if (verResp) {
+                const browserUrl = typeof verResp.webSocketDebuggerUrl === "string" ? verResp.webSocketDebuggerUrl : "";
+                const browserName = typeof verResp.Browser === "string" ? verResp.Browser : "Browser";
+                if (browserUrl) {
+                    console.log(JSON.stringify({ port, level: "browser", name: browserName, url: browserUrl }, null, 2));
+                }
+            }
+            if (listResp) {
+                for (const item of listResp) {
+                    const name = item.title || item.url || "unknown";
+                    const url = item.webSocketDebuggerUrl || "";
+                    if (url) {
+                        console.log(JSON.stringify({ port, level: "tab", name, url }, null, 2));
+                    }
+                }
+            }
+        }
+        else {
+            if (!printedHeader) {
+                console.log(`${(0, format_1.padEnd)("PORT", 6)}  ${(0, format_1.padEnd)("LEVEL", 8)}  ${(0, format_1.padEnd)("NAME", 30)}  URL`);
+                console.log(`${(0, format_1.padEnd)("----", 6)}  ${(0, format_1.padEnd)("-----", 8)}  ${(0, format_1.padEnd)("----", 30)}  ---`);
+                printedHeader = true;
+            }
+            if (verResp) {
+                const browserUrl = typeof verResp.webSocketDebuggerUrl === "string" ? verResp.webSocketDebuggerUrl : "";
+                const browserName = typeof verResp.Browser === "string" ? verResp.Browser : "Browser";
+                if (browserUrl) {
+                    console.log(`${(0, format_1.padEnd)(String(port), 6)}  ${(0, format_1.padEnd)("browser", 8)}  ${(0, format_1.padEnd)(truncate(browserName, 30), 30)}  ${browserUrl}`);
+                }
+            }
+            if (listResp) {
+                for (const item of listResp) {
+                    const name = item.title || item.url || "unknown";
+                    const url = item.webSocketDebuggerUrl || "";
+                    if (url) {
+                        console.log(`${(0, format_1.padEnd)(String(port), 6)}  ${(0, format_1.padEnd)("tab", 8)}  ${(0, format_1.padEnd)(truncate(name, 30), 30)}  ${url}`);
+                    }
+                }
+            }
+        }
+    }
+    if (!any) {
+        process.exit(1);
+    }
+}
+async function fetchWithTimeout(url, ms) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), ms);
+    try {
+        const res = await fetch(url, { signal: controller.signal });
+        clearTimeout(timeout);
+        return res;
+    }
+    catch (err) {
+        clearTimeout(timeout);
+        throw err;
+    }
+}
+function truncate(str, max) {
+    if (str.length > max) {
+        return str.slice(0, max - 3) + "...";
+    }
+    return str;
+}

package/dist/commands/kill.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.killCommand = killCommand;
+const process_1 = require("../utils/process");
+function killCommand(options) {
+    const signal = options.force ? "KILL" : "TERM";
+    const exact = !options.all;
+    const pids = (0, process_1.getChromePids)(exact);
+    if (pids.length === 0) {
+        console.log("(no Chrome processes found)");
+        return;
+    }
+    let count = 0;
+    for (const pid of pids) {
+        if ((0, process_1.killPid)(pid, signal)) {
+            console.log(`Killed PID ${pid} (SIG${signal})`);
+            count++;
+        }
+        else {
+            console.error(`Failed to kill PID ${pid}`);
+        }
+    }
+    console.log("");
+    console.log(`Sent SIG${signal} to ${count} process(es)`);
+}

package/dist/commands/launch.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.launchCommand = launchCommand;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const process_1 = require("../utils/process");
+function launchCommand(options) {
+    const chromeBin = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+    const profile = options.profile ?? process.env.CHROME_PROFILE ?? "";
+    const dataDir = options.dir ?? process.env.CHROME_DATA_DIR ?? "";
+    if (!(0, fs_1.existsSync)(chromeBin)) {
+        console.error(`Error: Chrome not found at ${chromeBin}`);
+        process.exit(1);
+    }
+    if (!dataDir) {
+        console.error("Error: CHROME_DATA_DIR environment variable is not set and --dir was not provided");
+        process.exit(1);
+    }
+    const args = [];
+    args.push(`--user-data-dir=${dataDir}`);
+    if (profile) {
+        args.push(`--profile-directory=${profile}`);
+    }
+    if (options.debug) {
+        const port = options.debuggingPort ?? "9222";
+        args.push(`--remote-debugging-port=${port}`);
+    }
+    else if (options.debuggingPort) {
+        console.error("Warning: --debugging-port is ignored without --debug");
+    }
+    if ((0, process_1.isChromeRunning)()) {
+        const { execSync } = require("child_process");
+        const existing = execSync('pgrep -x "Google Chrome" | tr "\\n" " " | sed "s/ $//"', { encoding: "utf-8" }).trim();
+        if (existing) {
+            console.error(`Warning: Chrome is already running (PIDs: ${existing})`);
+        }
+    }
+    console.log("Launching Chrome...");
+    console.log(`  binary:   ${chromeBin}`);
+    console.log(`  data dir: ${dataDir}`);
+    if (profile) {
+        console.log(`  profile:  ${profile}`);
+    }
+    if (options.debug) {
+        console.log(`  debug:    port ${options.debuggingPort ?? "9222"}`);
+    }
+    // Spawn detached so it survives parent exit, with stdio ignored
+    const child = (0, child_process_1.spawn)(chromeBin, args, {
+        detached: true,
+        stdio: "ignore",
+    });
+    child.unref();
+    console.log(`Chrome started (pid=${child.pid})`);
+}

package/dist/commands/list.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listCommand = listCommand;
+const process_1 = require("../utils/process");
+const format_1 = require("../utils/format");
+function listCommand(options) {
+    const pids = (0, process_1.getChromePids)(true);
+    if (pids.length === 0) {
+        console.log("(no Chrome processes found)");
+        return;
+    }
+    if (options.json) {
+        for (const pid of pids) {
+            const cmd = (0, process_1.getProcessArgs)(pid);
+            const port = (0, process_1.extractDebugPort)(cmd);
+            const obj = { pid, cmd };
+            if (port !== null) {
+                obj.port = port;
+            }
+            else {
+                obj.port = null;
+            }
+            console.log(JSON.stringify(obj));
+        }
+        return;
+    }
+    if (options.verbose) {
+        console.log(`${(0, format_1.padEnd)("PID", 8)}  ${(0, format_1.padEnd)("PORT", 6)}  COMMAND`);
+        console.log(`${(0, format_1.padEnd)("---", 8)}  ${(0, format_1.padEnd)("----", 6)}  -------`);
+        for (const pid of pids) {
+            const cmd = (0, process_1.getProcessArgs)(pid);
+            const port = (0, process_1.extractDebugPort)(cmd);
+            console.log(`${(0, format_1.padEnd)(String(pid), 8)}  ${(0, format_1.padEnd)(port !== null ? String(port) : "-", 6)}  ${cmd}`);
+        }
+    }
+    else {
+        console.log(`${(0, format_1.padEnd)("PID", 8)}  ${(0, format_1.padEnd)("PORT", 6)}  NAME`);
+        console.log(`${(0, format_1.padEnd)("---", 8)}  ${(0, format_1.padEnd)("----", 6)}  ----`);
+        for (const pid of pids) {
+            const name = (0, process_1.getProcessName)(pid);
+            const cmd = (0, process_1.getProcessArgs)(pid);
+            const port = (0, process_1.extractDebugPort)(cmd);
+            console.log(`${(0, format_1.padEnd)(String(pid), 8)}  ${(0, format_1.padEnd)(port !== null ? String(port) : "-", 6)}  ${name}`);
+        }
+    }
+}

package/dist/commands/profile.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.profileList = profileList;
+exports.profileName = profileName;
+exports.profileDelete = profileDelete;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const readline_1 = require("readline");
+const localState_1 = require("../utils/localState");
+const process_1 = require("../utils/process");
+const format_1 = require("../utils/format");
+function profileList(options) {
+    const dataDir = (0, localState_1.getChromeDataDir)();
+    const localStatePath = (0, path_1.join)(dataDir, "Local State");
+    if (!(0, fs_1.existsSync)(localStatePath)) {
+        console.error(`Error: Local State not found at ${localStatePath}`);
+        process.exit(1);
+    }
+    const state = (0, localState_1.readLocalState)();
+    const cache = state.profile?.info_cache ?? {};
+    if (options.json) {
+        for (const [dir, info] of Object.entries(cache)) {
+            console.log(JSON.stringify({ dir, name: info.name }));
+        }
+        return;
+    }
+    console.log(`${(0, format_1.padEnd)("DIR", 20)}  NAME`);
+    console.log(`${(0, format_1.padEnd)("---", 20)}  ----`);
+    for (const [dir, info] of Object.entries(cache)) {
+        console.log(`${(0, format_1.padEnd)(dir, 20)}  ${info.name}`);
+    }
+}
+function profileName(profileDir, newName) {
+    const state = (0, localState_1.readLocalState)();
+    if (!(0, localState_1.profileExists)(profileDir, state)) {
+        console.error(`Error: profile directory '${profileDir}' not found in Local State`);
+        process.exit(1);
+    }
+    state.profile = state.profile ?? {};
+    state.profile.info_cache = state.profile.info_cache ?? {};
+    state.profile.info_cache[profileDir].name = newName;
+    (0, localState_1.writeLocalState)(state);
+    console.log(`Renamed '${profileDir}' to '${newName}'`);
+}
+async function profileDelete(profileDir) {
+    const dataDir = (0, localState_1.getChromeDataDir)();
+    const state = (0, localState_1.readLocalState)();
+    if (!(0, localState_1.profileExists)(profileDir, state)) {
+        console.error(`Error: profile directory '${profileDir}' not found in Local State`);
+        process.exit(1);
+    }
+    const profilePath = (0, path_1.join)(dataDir, profileDir);
+    if ((0, fs_1.existsSync)(profilePath)) {
+        (0, localState_1.validateProfileDir)(profileDir);
+    }
+    if ((0, process_1.isChromeRunning)()) {
+        console.error("Warning: Chrome is currently running. Deleting a profile while Chrome is active may cause data loss.");
+        const rl = (0, readline_1.createInterface)({ input: process.stdin, output: process.stdout });
+        const answer = await new Promise((resolve) => {
+            rl.question("Are you sure you want to continue? [y/N] ", (ans) => {
+                rl.close();
+                resolve(ans.trim());
+            });
+        });
+        if (answer !== "y" && answer !== "Y") {
+            console.error("Aborted.");
+            process.exit(1);
+        }
+    }
+    if ((0, fs_1.existsSync)(profilePath)) {
+        (0, fs_1.rmSync)(profilePath, { recursive: true, force: true });
+        console.log(`Deleted directory '${profilePath}'`);
+    }
+    delete state.profile.info_cache[profileDir];
+    (0, localState_1.writeLocalState)(state);
+    console.log(`Removed '${profileDir}' from Local State`);
+}

package/dist/index.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const list_1 = require("./commands/list");
+const kill_1 = require("./commands/kill");
+const launch_1 = require("./commands/launch");
+const profile_1 = require("./commands/profile");
+const cdp_1 = require("./commands/cdp");
+const program = new commander_1.Command();
+program
+    .name("chrome-proc")
+    .description("Manage Chrome browser processes, profiles, and CDP endpoints");
+program
+    .command("list")
+    .description("List Chrome processes")
+    .option("-v, --verbose", "Show full command line")
+    .option("-j, --json", "Output as JSON lines")
+    .action((options) => {
+    (0, list_1.listCommand)(options);
+});
+program
+    .command("kill")
+    .description("Kill Chrome processes")
+    .option("-f, --force", "Use SIGKILL instead of SIGTERM")
+    .option("-a, --all", "Kill helper processes too (not just the main process)")
+    .action((options) => {
+    (0, kill_1.killCommand)(options);
+});
+program
+    .command("launch")
+    .description("Launch Chrome browser")
+    .option("--dir <dir>", "Chrome user data directory (overrides CHROME_DATA_DIR)")
+    .option("--profile <profile>", "Chrome profile name (default: $CHROME_PROFILE)")
+    .option("-d, --debug", "Enable remote debugging mode")
+    .option("-p, --debugging-port <port>", "Remote debugging port (default: 9222, only with --debug)")
+    .action((options) => {
+    (0, launch_1.launchCommand)(options);
+});
+const profileCmd = program
+    .command("profile")
+    .description("Manage Chrome profiles");
+profileCmd
+    .command("list")
+    .description("List Chrome profiles")
+    .option("-j, --json", "Output as JSON lines")
+    .action((options) => {
+    (0, profile_1.profileList)(options);
+});
+profileCmd
+    .command("name <profile_dir> <new_name>")
+    .description("Rename a Chrome profile")
+    .action((profileDir, newName) => {
+    (0, profile_1.profileName)(profileDir, newName);
+});
+profileCmd
+    .command("delete <profile_dir>")
+    .description("Delete a Chrome profile")
+    .action(async (profileDir) => {
+    await (0, profile_1.profileDelete)(profileDir);
+});
+program
+    .command("cdp")
+    .description("List Chrome DevTools Protocol (CDP) WebSocket URLs")
+    .option("-j, --json", "Output as JSON lines")
+    .action(async (options) => {
+    await (0, cdp_1.cdpCommand)(options);
+});
+program.parse();

package/dist/utils/format.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.padEnd = padEnd;
+exports.padStart = padStart;
+function padEnd(str, length) {
+    return str.length >= length ? str : str + " ".repeat(length - str.length);
+}
+function padStart(str, length) {
+    return str.length >= length ? str : " ".repeat(length - str.length) + str;
+}

package/dist/utils/localState.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getChromeDataDir = getChromeDataDir;
+exports.getLocalStatePath = getLocalStatePath;
+exports.readLocalState = readLocalState;
+exports.writeLocalState = writeLocalState;
+exports.profileExists = profileExists;
+exports.validateProfileDir = validateProfileDir;
+const fs_1 = require("fs");
+const path_1 = require("path");
+function getChromeDataDir() {
+    const dir = process.env.CHROME_DATA_DIR;
+    if (!dir) {
+        throw new Error("CHROME_DATA_DIR environment variable is not set");
+    }
+    return dir;
+}
+function getLocalStatePath() {
+    return (0, path_1.join)(getChromeDataDir(), "Local State");
+}
+function readLocalState() {
+    const path = getLocalStatePath();
+    if (!(0, fs_1.existsSync)(path)) {
+        throw new Error(`Local State not found at ${path}`);
+    }
+    const raw = (0, fs_1.readFileSync)(path, "utf-8");
+    return JSON.parse(raw);
+}
+function writeLocalState(data) {
+    const path = getLocalStatePath();
+    const tmpPath = `${path}.tmp.${process.pid}`;
+    try {
+        (0, fs_1.writeFileSync)(tmpPath, JSON.stringify(data, null, 2), "utf-8");
+        // Atomic rename
+        const { renameSync } = require("fs");
+        renameSync(tmpPath, path);
+    }
+    catch (err) {
+        try {
+            (0, fs_1.rmSync)(tmpPath);
+        }
+        catch { }
+        throw new Error("failed to update Local State");
+    }
+}
+function profileExists(dir, state) {
+    const s = state || readLocalState();
+    return !!s.profile?.info_cache?.[dir];
+}
+function validateProfileDir(profileDir) {
+    const dataDir = getChromeDataDir();
+    const profilePath = (0, path_1.resolve)(dataDir, profileDir);
+    const realDataDir = (0, fs_1.realpathSync)(dataDir);
+    const realProfilePath = (0, fs_1.realpathSync)(profilePath);
+    if (!realProfilePath.startsWith(realDataDir)) {
+        throw new Error(`profile path '${profilePath}' is not inside CHROME_DATA_DIR`);
+    }
+}

package/dist/utils/process.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getChromePids = getChromePids;
+exports.getProcessArgs = getProcessArgs;
+exports.getProcessName = getProcessName;
+exports.extractDebugPort = extractDebugPort;
+exports.killPid = killPid;
+exports.isChromeRunning = isChromeRunning;
+const child_process_1 = require("child_process");
+function getChromePids(exact = false) {
+    try {
+        const flag = exact ? "-x" : "-f";
+        const output = (0, child_process_1.execSync)(`pgrep ${flag} "Google Chrome"`, { encoding: "utf-8" });
+        return output
+            .trim()
+            .split("\n")
+            .filter((line) => line.trim() !== "")
+            .map((line) => parseInt(line.trim(), 10))
+            .filter((pid) => !isNaN(pid));
+    }
+    catch {
+        return [];
+    }
+}
+function getProcessArgs(pid) {
+    try {
+        return (0, child_process_1.execSync)(`ps -p "${pid}" -o args=`, { encoding: "utf-8" }).trim();
+    }
+    catch {
+        return "?";
+    }
+}
+function getProcessName(pid) {
+    try {
+        return (0, child_process_1.execSync)(`ps -p "${pid}" -o comm=`, { encoding: "utf-8" }).trim();
+    }
+    catch {
+        return "?";
+    }
+}
+function extractDebugPort(args) {
+    const match = args.match(/--remote-debugging-port=(\d+)/);
+    return match ? parseInt(match[1], 10) : null;
+}
+function killPid(pid, signal) {
+    try {
+        (0, child_process_1.execSync)(`/bin/kill -${signal} "${pid}"`, { stdio: "pipe" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isChromeRunning() {
+    return getChromePids(true).length > 0;
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "chrome-proc",
+  "version": "1.0.0",
+  "description": "Manage Chrome browser processes, profiles, and CDP endpoints",
+  "main": "dist/index.js",
+  "bin": {
+    "chrome-proc": "./bin/chrome-proc"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "keywords": ["chrome", "cdp", "devtools"],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  }
+}

package/src/commands/cdp.ts

@@ -0,0 +1,137 @@
+import { getChromePids, getProcessArgs, extractDebugPort } from "../utils/process";
+import { padEnd } from "../utils/format";
+
+interface CdpOptions {
+  json?: boolean;
+}
+
+interface CdpEntry {
+  port: number;
+  level: string;
+  name: string;
+  url: string;
+}
+
+export async function cdpCommand(options: CdpOptions): Promise<void> {
+  const pids = getChromePids(true);
+
+  if (pids.length === 0) {
+    console.error("(no Chrome processes found)");
+    process.exit(1);
+  }
+
+  const ports: number[] = [];
+  for (const pid of pids) {
+    const args = getProcessArgs(pid);
+    const port = extractDebugPort(args);
+    if (port !== null && !ports.includes(port)) {
+      ports.push(port);
+    }
+  }
+
+  if (ports.length === 0) {
+    console.error("(no Chrome processes found with remote debugging enabled)");
+    process.exit(1);
+  }
+
+  let any = false;
+  let printedHeader = false;
+
+  for (const port of ports) {
+    const base = `http://localhost:${port}`;
+    let verResp: Record<string, unknown> | null = null;
+    let listResp: Array<Record<string, unknown>> | null = null;
+
+    try {
+      const ver = await fetchWithTimeout(`${base}/json/version`, 3000);
+      verResp = (await ver.json()) as Record<string, unknown>;
+    } catch {
+      verResp = null;
+    }
+
+    try {
+      const list = await fetchWithTimeout(`${base}/json/list`, 3000);
+      listResp = (await list.json()) as Array<Record<string, unknown>>;
+    } catch {
+      listResp = null;
+    }
+
+    if (!verResp && !listResp) {
+      console.error(`Warning: failed to query debug endpoint on port ${port}`);
+      continue;
+    }
+
+    any = true;
+
+    if (options.json) {
+      if (verResp) {
+        const browserUrl = typeof verResp.webSocketDebuggerUrl === "string" ? verResp.webSocketDebuggerUrl : "";
+        const browserName = typeof verResp.Browser === "string" ? verResp.Browser : "Browser";
+        if (browserUrl) {
+          console.log(JSON.stringify({ port, level: "browser", name: browserName, url: browserUrl }, null, 2));
+        }
+      }
+      if (listResp) {
+        for (const item of listResp) {
+          const name = (item.title as string) || (item.url as string) || "unknown";
+          const url = (item.webSocketDebuggerUrl as string) || "";
+          if (url) {
+            console.log(JSON.stringify({ port, level: "tab", name, url }, null, 2));
+          }
+        }
+      }
+    } else {
+      if (!printedHeader) {
+        console.log(`${padEnd("PORT", 6)}  ${padEnd("LEVEL", 8)}  ${padEnd("NAME", 30)}  URL`);
+        console.log(`${padEnd("----", 6)}  ${padEnd("-----", 8)}  ${padEnd("----", 30)}  ---`);
+        printedHeader = true;
+      }
+
+      if (verResp) {
+        const browserUrl = typeof verResp.webSocketDebuggerUrl === "string" ? verResp.webSocketDebuggerUrl : "";
+        const browserName = typeof verResp.Browser === "string" ? verResp.Browser : "Browser";
+        if (browserUrl) {
+          console.log(
+            `${padEnd(String(port), 6)}  ${padEnd("browser", 8)}  ${padEnd(truncate(browserName, 30), 30)}  ${browserUrl}`
+          );
+        }
+      }
+
+      if (listResp) {
+        for (const item of listResp) {
+          const name = (item.title as string) || (item.url as string) || "unknown";
+          const url = (item.webSocketDebuggerUrl as string) || "";
+          if (url) {
+            console.log(
+              `${padEnd(String(port), 6)}  ${padEnd("tab", 8)}  ${padEnd(truncate(name, 30), 30)}  ${url}`
+            );
+          }
+        }
+      }
+    }
+  }
+
+  if (!any) {
+    process.exit(1);
+  }
+}
+
+async function fetchWithTimeout(url: string, ms: number): Promise<Response> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), ms);
+  try {
+    const res = await fetch(url, { signal: controller.signal });
+    clearTimeout(timeout);
+    return res;
+  } catch (err) {
+    clearTimeout(timeout);
+    throw err;
+  }
+}
+
+function truncate(str: string, max: number): string {
+  if (str.length > max) {
+    return str.slice(0, max - 3) + "...";
+  }
+  return str;
+}

package/src/commands/kill.ts

@@ -0,0 +1,30 @@
+import { getChromePids, killPid } from "../utils/process";
+
+interface KillOptions {
+  force?: boolean;
+  all?: boolean;
+}
+
+export function killCommand(options: KillOptions): void {
+  const signal: "TERM" | "KILL" = options.force ? "KILL" : "TERM";
+  const exact = !options.all;
+  const pids = getChromePids(exact);
+
+  if (pids.length === 0) {
+    console.log("(no Chrome processes found)");
+    return;
+  }
+
+  let count = 0;
+  for (const pid of pids) {
+    if (killPid(pid, signal)) {
+      console.log(`Killed PID ${pid} (SIG${signal})`);
+      count++;
+    } else {
+      console.error(`Failed to kill PID ${pid}`);
+    }
+  }
+
+  console.log("");
+  console.log(`Sent SIG${signal} to ${count} process(es)`);
+}

package/src/commands/launch.ts

@@ -0,0 +1,65 @@
+import { spawn } from "child_process";
+import { existsSync } from "fs";
+import { isChromeRunning } from "../utils/process";
+
+interface LaunchOptions {
+  dir?: string;
+  profile?: string;
+  debug?: boolean;
+  debuggingPort?: string;
+}
+
+export function launchCommand(options: LaunchOptions): void {
+  const chromeBin = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+  const profile = options.profile ?? process.env.CHROME_PROFILE ?? "";
+  const dataDir = options.dir ?? process.env.CHROME_DATA_DIR ?? "";
+
+  if (!existsSync(chromeBin)) {
+    console.error(`Error: Chrome not found at ${chromeBin}`);
+    process.exit(1);
+  }
+
+  if (!dataDir) {
+    console.error("Error: CHROME_DATA_DIR environment variable is not set and --dir was not provided");
+    process.exit(1);
+  }
+
+  const args: string[] = [];
+  args.push(`--user-data-dir=${dataDir}`);
+  if (profile) {
+    args.push(`--profile-directory=${profile}`);
+  }
+
+  if (options.debug) {
+    const port = options.debuggingPort ?? "9222";
+    args.push(`--remote-debugging-port=${port}`);
+  } else if (options.debuggingPort) {
+    console.error("Warning: --debugging-port is ignored without --debug");
+  }
+
+  if (isChromeRunning()) {
+    const { execSync } = require("child_process");
+    const existing = execSync('pgrep -x "Google Chrome" | tr "\\n" " " | sed "s/ $//"', { encoding: "utf-8" }).trim();
+    if (existing) {
+      console.error(`Warning: Chrome is already running (PIDs: ${existing})`);
+    }
+  }
+
+  console.log("Launching Chrome...");
+  console.log(`  binary:   ${chromeBin}`);
+  console.log(`  data dir: ${dataDir}`);
+  if (profile) {
+    console.log(`  profile:  ${profile}`);
+  }
+  if (options.debug) {
+    console.log(`  debug:    port ${options.debuggingPort ?? "9222"}`);
+  }
+
+  // Spawn detached so it survives parent exit, with stdio ignored
+  const child = spawn(chromeBin, args, {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+  console.log(`Chrome started (pid=${child.pid})`);
+}

package/src/commands/list.ts

@@ -0,0 +1,50 @@
+import { getChromePids, getProcessArgs, getProcessName, extractDebugPort } from "../utils/process";
+import { padEnd } from "../utils/format";
+
+interface ListOptions {
+  verbose?: boolean;
+  json?: boolean;
+}
+
+export function listCommand(options: ListOptions): void {
+  const pids = getChromePids(true);
+
+  if (pids.length === 0) {
+    console.log("(no Chrome processes found)");
+    return;
+  }
+
+  if (options.json) {
+    for (const pid of pids) {
+      const cmd = getProcessArgs(pid);
+      const port = extractDebugPort(cmd);
+      const obj: Record<string, unknown> = { pid, cmd };
+      if (port !== null) {
+        obj.port = port;
+      } else {
+        obj.port = null;
+      }
+      console.log(JSON.stringify(obj));
+    }
+    return;
+  }
+
+  if (options.verbose) {
+    console.log(`${padEnd("PID", 8)}  ${padEnd("PORT", 6)}  COMMAND`);
+    console.log(`${padEnd("---", 8)}  ${padEnd("----", 6)}  -------`);
+    for (const pid of pids) {
+      const cmd = getProcessArgs(pid);
+      const port = extractDebugPort(cmd);
+      console.log(`${padEnd(String(pid), 8)}  ${padEnd(port !== null ? String(port) : "-", 6)}  ${cmd}`);
+    }
+  } else {
+    console.log(`${padEnd("PID", 8)}  ${padEnd("PORT", 6)}  NAME`);
+    console.log(`${padEnd("---", 8)}  ${padEnd("----", 6)}  ----`);
+    for (const pid of pids) {
+      const name = getProcessName(pid);
+      const cmd = getProcessArgs(pid);
+      const port = extractDebugPort(cmd);
+      console.log(`${padEnd(String(pid), 8)}  ${padEnd(port !== null ? String(port) : "-", 6)}  ${name}`);
+    }
+  }
+}

package/src/commands/profile.ts

@@ -0,0 +1,96 @@
+import { existsSync, rmSync } from "fs";
+import { join } from "path";
+import { createInterface } from "readline";
+import {
+  getChromeDataDir,
+  readLocalState,
+  writeLocalState,
+  profileExists,
+  validateProfileDir,
+} from "../utils/localState";
+import { isChromeRunning } from "../utils/process";
+import { padEnd } from "../utils/format";
+
+interface ProfileListOptions {
+  json?: boolean;
+}
+
+export function profileList(options: ProfileListOptions): void {
+  const dataDir = getChromeDataDir();
+  const localStatePath = join(dataDir, "Local State");
+
+  if (!existsSync(localStatePath)) {
+    console.error(`Error: Local State not found at ${localStatePath}`);
+    process.exit(1);
+  }
+
+  const state = readLocalState();
+  const cache = state.profile?.info_cache ?? {};
+
+  if (options.json) {
+    for (const [dir, info] of Object.entries(cache)) {
+      console.log(JSON.stringify({ dir, name: info.name }));
+    }
+    return;
+  }
+
+  console.log(`${padEnd("DIR", 20)}  NAME`);
+  console.log(`${padEnd("---", 20)}  ----`);
+  for (const [dir, info] of Object.entries(cache)) {
+    console.log(`${padEnd(dir, 20)}  ${info.name}`);
+  }
+}
+
+export function profileName(profileDir: string, newName: string): void {
+  const state = readLocalState();
+
+  if (!profileExists(profileDir, state)) {
+    console.error(`Error: profile directory '${profileDir}' not found in Local State`);
+    process.exit(1);
+  }
+
+  state.profile = state.profile ?? {};
+  state.profile.info_cache = state.profile.info_cache ?? {};
+  state.profile.info_cache[profileDir].name = newName;
+  writeLocalState(state);
+  console.log(`Renamed '${profileDir}' to '${newName}'`);
+}
+
+export async function profileDelete(profileDir: string): Promise<void> {
+  const dataDir = getChromeDataDir();
+  const state = readLocalState();
+
+  if (!profileExists(profileDir, state)) {
+    console.error(`Error: profile directory '${profileDir}' not found in Local State`);
+    process.exit(1);
+  }
+
+  const profilePath = join(dataDir, profileDir);
+  if (existsSync(profilePath)) {
+    validateProfileDir(profileDir);
+  }
+
+  if (isChromeRunning()) {
+    console.error("Warning: Chrome is currently running. Deleting a profile while Chrome is active may cause data loss.");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise<string>((resolve) => {
+      rl.question("Are you sure you want to continue? [y/N] ", (ans) => {
+        rl.close();
+        resolve(ans.trim());
+      });
+    });
+    if (answer !== "y" && answer !== "Y") {
+      console.error("Aborted.");
+      process.exit(1);
+    }
+  }
+
+  if (existsSync(profilePath)) {
+    rmSync(profilePath, { recursive: true, force: true });
+    console.log(`Deleted directory '${profilePath}'`);
+  }
+
+  delete state.profile!.info_cache![profileDir];
+  writeLocalState(state);
+  console.log(`Removed '${profileDir}' from Local State`);
+}

package/src/index.ts

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { listCommand } from "./commands/list";
+import { killCommand } from "./commands/kill";
+import { launchCommand } from "./commands/launch";
+import { profileList, profileName, profileDelete } from "./commands/profile";
+import { cdpCommand } from "./commands/cdp";
+
+const program = new Command();
+
+program
+  .name("chrome-proc")
+  .description("Manage Chrome browser processes, profiles, and CDP endpoints");
+
+program
+  .command("list")
+  .description("List Chrome processes")
+  .option("-v, --verbose", "Show full command line")
+  .option("-j, --json", "Output as JSON lines")
+  .action((options) => {
+    listCommand(options);
+  });
+
+program
+  .command("kill")
+  .description("Kill Chrome processes")
+  .option("-f, --force", "Use SIGKILL instead of SIGTERM")
+  .option("-a, --all", "Kill helper processes too (not just the main process)")
+  .action((options) => {
+    killCommand(options);
+  });
+
+program
+  .command("launch")
+  .description("Launch Chrome browser")
+  .option("--dir <dir>", "Chrome user data directory (overrides CHROME_DATA_DIR)")
+  .option("--profile <profile>", "Chrome profile name (default: $CHROME_PROFILE)")
+  .option("-d, --debug", "Enable remote debugging mode")
+  .option("-p, --debugging-port <port>", "Remote debugging port (default: 9222, only with --debug)")
+  .action((options) => {
+    launchCommand(options);
+  });
+
+const profileCmd = program
+  .command("profile")
+  .description("Manage Chrome profiles");
+
+profileCmd
+  .command("list")
+  .description("List Chrome profiles")
+  .option("-j, --json", "Output as JSON lines")
+  .action((options) => {
+    profileList(options);
+  });
+
+profileCmd
+  .command("name <profile_dir> <new_name>")
+  .description("Rename a Chrome profile")
+  .action((profileDir: string, newName: string) => {
+    profileName(profileDir, newName);
+  });
+
+profileCmd
+  .command("delete <profile_dir>")
+  .description("Delete a Chrome profile")
+  .action(async (profileDir: string) => {
+    await profileDelete(profileDir);
+  });
+
+program
+  .command("cdp")
+  .description("List Chrome DevTools Protocol (CDP) WebSocket URLs")
+  .option("-j, --json", "Output as JSON lines")
+  .action(async (options) => {
+    await cdpCommand(options);
+  });
+
+program.parse();

package/src/utils/format.ts

@@ -0,0 +1,7 @@
+export function padEnd(str: string, length: number): string {
+  return str.length >= length ? str : str + " ".repeat(length - str.length);
+}
+
+export function padStart(str: string, length: number): string {
+  return str.length >= length ? str : " ".repeat(length - str.length) + str;
+}

package/src/utils/localState.ts

@@ -0,0 +1,64 @@
+import { readFileSync, writeFileSync, existsSync, realpathSync, rmSync } from "fs";
+import { join, resolve } from "path";
+
+export interface ProfileEntry {
+  name: string;
+}
+
+export interface LocalState {
+  profile?: {
+    info_cache?: Record<string, ProfileEntry>;
+  };
+}
+
+export function getChromeDataDir(): string {
+  const dir = process.env.CHROME_DATA_DIR;
+  if (!dir) {
+    throw new Error("CHROME_DATA_DIR environment variable is not set");
+  }
+  return dir;
+}
+
+export function getLocalStatePath(): string {
+  return join(getChromeDataDir(), "Local State");
+}
+
+export function readLocalState(): LocalState {
+  const path = getLocalStatePath();
+  if (!existsSync(path)) {
+    throw new Error(`Local State not found at ${path}`);
+  }
+  const raw = readFileSync(path, "utf-8");
+  return JSON.parse(raw) as LocalState;
+}
+
+export function writeLocalState(data: LocalState): void {
+  const path = getLocalStatePath();
+  const tmpPath = `${path}.tmp.${process.pid}`;
+  try {
+    writeFileSync(tmpPath, JSON.stringify(data, null, 2), "utf-8");
+    // Atomic rename
+    const { renameSync } = require("fs");
+    renameSync(tmpPath, path);
+  } catch (err) {
+    try {
+      rmSync(tmpPath);
+    } catch {}
+    throw new Error("failed to update Local State");
+  }
+}
+
+export function profileExists(dir: string, state?: LocalState): boolean {
+  const s = state || readLocalState();
+  return !!s.profile?.info_cache?.[dir];
+}
+
+export function validateProfileDir(profileDir: string): void {
+  const dataDir = getChromeDataDir();
+  const profilePath = resolve(dataDir, profileDir);
+  const realDataDir = realpathSync(dataDir);
+  const realProfilePath = realpathSync(profilePath);
+  if (!realProfilePath.startsWith(realDataDir)) {
+    throw new Error(`profile path '${profilePath}' is not inside CHROME_DATA_DIR`);
+  }
+}

package/src/utils/process.ts

@@ -0,0 +1,50 @@
+import { execSync } from "child_process";
+
+export function getChromePids(exact = false): number[] {
+  try {
+    const flag = exact ? "-x" : "-f";
+    const output = execSync(`pgrep ${flag} "Google Chrome"`, { encoding: "utf-8" });
+    return output
+      .trim()
+      .split("\n")
+      .filter((line) => line.trim() !== "")
+      .map((line) => parseInt(line.trim(), 10))
+      .filter((pid) => !isNaN(pid));
+  } catch {
+    return [];
+  }
+}
+
+export function getProcessArgs(pid: number): string {
+  try {
+    return execSync(`ps -p "${pid}" -o args=`, { encoding: "utf-8" }).trim();
+  } catch {
+    return "?";
+  }
+}
+
+export function getProcessName(pid: number): string {
+  try {
+    return execSync(`ps -p "${pid}" -o comm=`, { encoding: "utf-8" }).trim();
+  } catch {
+    return "?";
+  }
+}
+
+export function extractDebugPort(args: string): number | null {
+  const match = args.match(/--remote-debugging-port=(\d+)/);
+  return match ? parseInt(match[1], 10) : null;
+}
+
+export function killPid(pid: number, signal: "TERM" | "KILL"): boolean {
+  try {
+    execSync(`/bin/kill -${signal} "${pid}"`, { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function isChromeRunning(): boolean {
+  return getChromePids(true).length > 0;
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"]
+}