@comecaramelos/dsh-chrome-mcp 0.0.1 → 1.0.0

package/lib/host/discovery/probe.js

@@ -0,0 +1,97 @@
+/**
+ * Chrome discovery — the low-level `--version` probe and the on-disk/identity
+ * helpers it rides on.
+ *
+ * The one place discovery reaches outside the process: `chromePath --version`
+ * run through a scrubbed parent env under a bounded timeout, the rule that says
+ * whether a path is worth spawning at all (a directory, socket or fifo never
+ * reaches a probe — a Chrome-less host must run one scan that launches nothing),
+ * and the identity key that folds two spellings of the same binary into one
+ * answer. The scan that drives them lives in ./scan.ts.
+ */
+import { spawn } from "node:child_process";
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
+import { scrubbedParentEnv } from "@deepseek-ai/dsh-subprocess";
+import { CHECK_TIMEOUT_MS } from "../constants.js";
+import { firstLine } from "../status.js";
+/**
+ * Spawn one `chromePath --version` probe (scrubbed parent env, bounded
+ * timeout). Resolves the first stdout line (the version); ENOENT rejects with
+ * "Chrome executable not found: <path>" carrying code "ENOENT"; a non-zero
+ * exit rejects with the first non-empty stderr/stdout line.
+ */
+export function probeExecutable(target) {
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(target, ["--version"], {
+                env: scrubbedParentEnv(),
+                stdio: ["ignore", "pipe", "pipe"],
+                timeout: CHECK_TIMEOUT_MS,
+                killSignal: "SIGKILL"
+            });
+        }
+        catch (error) {
+            reject(new Error(`could not run "${target} --version": ${String(error)}`));
+            return;
+        }
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (chunk) => (stdout += chunk));
+        child.stderr?.on("data", (chunk) => (stderr += chunk));
+        child.on("error", (error) => {
+            const code = error && typeof error.code === "string" ? error.code : "";
+            if (code === "ENOENT") {
+                const missing = new Error(`Chrome executable not found: ${target}`);
+                Object.defineProperty(missing, "code", { value: "ENOENT", writable: true, enumerable: false, configurable: true });
+                reject(missing);
+                return;
+            }
+            reject(new Error(`could not run "${target} --version": ${String(error)}`));
+        });
+        child.on("close", (code) => {
+            if (code === null) {
+                reject(new Error(`"${target} --version" timed out after ${String(CHECK_TIMEOUT_MS)}ms`));
+                return;
+            }
+            if (code !== 0) {
+                const detail = firstLine(stderr) !== "" ? firstLine(stderr) : firstLine(stdout) !== "" ? firstLine(stdout) : `exit code ${String(code)}`;
+                reject(new Error(`"${target} --version" failed: ${detail}`));
+                return;
+            }
+            resolve(firstLine(stdout));
+        });
+    });
+}
+/** True when a candidate path can be handed to the OS for a `--version` probe.
+ * A path that is absent (or not executable) never reaches the spawn: a
+ * Chrome-less host runs one scan without launching anything. Paths with no
+ * directory separator go straight to the spawn so the OS resolves them
+ * through `PATH`. */
+export function presentOnDisk(candidate) {
+    if (!candidate.includes("/") && !candidate.includes("\\"))
+        return true;
+    try {
+        // A directory (or a socket, or a fifo) is not an executable, and
+        // spawning one to find out is a side effect we do not want.
+        if (!statSync(candidate).isFile())
+            return false;
+        accessSync(candidate, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Identity key used to fold two spellings of the same binary (`google-chrome`
+ * resolving onto `/usr/bin/google-chrome`) into one option. Falls back to the
+ * path itself when `realpath` cannot resolve it. */
+export function identity(candidate) {
+    try {
+        return realpathSync(candidate);
+    }
+    catch {
+        return candidate;
+    }
+}
+//# sourceMappingURL=probe.js.map

package/lib/host/discovery/probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.js","sourceRoot":"","sources":["../../../src/host/discovery/probe.ts"],"names":[],"mappings":"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"}

package/lib/host/discovery/scan.d.ts

@@ -0,0 +1,67 @@
+import type { ChromeExecutableStatus, ChromeMcpConfig } from "../types/index.js";
+/**
+ * What one run probes: every candidate it has — the row-config candidate list,
+ * the paths the saved rows carry, and the current selection (see
+ * {@link chromeExecutableCandidates}) — probed in that order.
+ *
+ * A candidate that runs answers with its `--version` line; one that is present
+ * but not runnable (bad binary, a probe that timed out) keeps its place in the
+ * list carrying the failure, so a broken pin stays visible instead of vanishing
+ * into a red dot.
+ *
+ * - absent / not executable → dropped without a spawn,
+ * - `blockedForPlatform` answers non-empty → **no spawn**: the candidate keeps
+ *   its place carrying that reason (the one case is a Windows `chrome.exe` on a
+ *   WSL host, whose probe would start a browser instance it can never drive —
+ *   see {@link WSL_WINDOWS_LAUNCH_ERROR}),
+ * - two spellings of the same binary collapse into the first one seen.
+ *
+ * An empty candidate list resolves `[]` (nothing probed: unknown platform, or a
+ * host patched down to nothing).
+ *
+ * @param candidates - candidate executable paths.
+ * @param blockedForPlatform - answers a reason for a candidate this host must
+ * never exec, `""` for one it may probe.
+ */
+export declare function scanChromeExecutables(candidates: string[], blockedForPlatform?: (candidate: string) => string): Promise<ChromeExecutableStatus[]>;
+/**
+ * Discover usable Google Chrome executables when nothing is fixed: probe every
+ * candidate and report the first runnable one. Kept for its `Promise<string>`
+ * contract (`src/index.ts` re-export, tests, diagnostics).
+ * @param candidatePaths - candidate executable paths (default: platform list).
+ * @param blockedForPlatform - answers a reason for a candidate this host must
+ * never exec, `""` for one it may probe.
+ * @returns the discovered executable version line.
+ */
+export declare function discoverChrome(candidatePaths: string[], blockedForPlatform?: (candidate: string) => string): Promise<string>;
+/**
+ * One check run — the public "did we find a runnable Chrome?" question:
+ *
+ * - `chromePath` non-empty → probe that executable (ENOENT → "Chrome
+ *   executable not found: <path>"; non-zero → first stderr/stdout line;
+ *   success → the version line).
+ * - `chromePath` empty → run the scan over the candidate list (row config
+ *   `chromePaths`, default {@link defaultChromePaths}) and report the first
+ *   runnable entry. Nothing usable → the known executable-missing error;
+ *   only-present-but-broken entries → that entry's failure.
+ * - the extra flags declare a connect mode (`--browserUrl` / `--wsEndpoint`) →
+ *   resolve "": there is no local executable to check.
+ * - `blockedForPlatform` answers non-empty for what is selected → resolve "" with
+ *   **no spawn**. A Windows `chrome.exe` on a WSL host is the case: its
+ *   `--version` probe answers (which is why the selection looks healthy) but
+ *   answering means attaching to the Windows browser session, and that *starts*
+ *   a browser instance no tool call could drive
+ *   ({@link WSL_WINDOWS_LAUNCH_ERROR}).
+ *
+ * A run that probes **nothing** (no candidates, a connect mode, or a blocked
+ * path) resolves "" — callers must treat that as "no evidence", never as health.
+ *
+ * @param entry - validated {@link ChromeMcpConfig}.
+ * @param extraFlags - the flags list the bridge currently launches with; only
+ *   inspected for connect-mode options.
+ * @param blockedForPlatform - answers a reason for a path this host must never
+ *   exec, `""` for one it may probe.
+ * @returns the executable version line, or "" when nothing is probed.
+ */
+export declare function checkChrome(entry: ChromeMcpConfig, extraFlags?: string[], blockedForPlatform?: (candidate: string) => string): Promise<string>;
+//# sourceMappingURL=scan.d.ts.map

package/lib/host/discovery/scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../../src/host/discovery/scan.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAKjF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,qBAAqB,CACvC,UAAU,EAAE,MAAM,EAAE,EACpB,kBAAkB,GAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAiB,GAC7D,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAyCnC;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAChC,cAAc,EAAE,MAAM,EAAE,EACxB,kBAAkB,GAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAiB,GAC7D,OAAO,CAAC,MAAM,CAAC,CAYjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,WAAW,CACvB,KAAK,EAAE,eAAe,EACtB,UAAU,CAAC,EAAE,MAAM,EAAE,EACrB,kBAAkB,GAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAiB,GAC7D,OAAO,CAAC,MAAM,CAAC,CAYjB"}

package/lib/host/discovery/scan.js

@@ -0,0 +1,169 @@
+/**
+ * Chrome discovery — the scan and the check run that tie it together.
+ *
+ * What one executable run does: probe every candidate it has (the row-config
+ * list, the saved rows' ids, the selection), publish the per-path answer, and
+ * report the first runnable one. The candidate ordering lives in
+ * ./candidates.ts; the `--version` probe + presence + identity helpers in
+ * ./probe.ts.
+ *
+ * Upstream (`chrome-devtools-mcp`, via puppeteer) starts the browser only
+ * LAZILY, on the first tool call — so without a probe of our own, a
+ * Chrome-less host would show nothing until somebody called a tool. The scan
+ * therefore probes eagerly: there is no "auto" mode, the scan lists what exists,
+ * the card picks one of them, and what is picked stays picked.
+ *
+ * WSL NOTE: the executable must be a Linux binary. Launching the Windows
+ * chrome.exe through the WSL interop layer fails: chrome-devtools-mcp connects
+ * with `pipe: true` (inherited fd 3/4), and Windows-side processes cannot
+ * receive those pipes from WSL; the WebSocket fallback hard-codes 127.0.0.1 in
+ * the DevToolsActivePort file, unreachable across the WSL2 NAT bridge. Verified
+ * empirically 2025-09-19 (.probe/); do not "fix" discovery by pointing candidates
+ * or chromePath at a /mnt/c executable.
+ */
+import { carriesConnectionMode } from "../flags.js";
+import { firstLine } from "../status.js";
+import { defaultChromePaths } from "./candidates.js";
+import { identity, presentOnDisk, probeExecutable } from "./probe.js";
+/**
+ * What one run probes: every candidate it has — the row-config candidate list,
+ * the paths the saved rows carry, and the current selection (see
+ * {@link chromeExecutableCandidates}) — probed in that order.
+ *
+ * A candidate that runs answers with its `--version` line; one that is present
+ * but not runnable (bad binary, a probe that timed out) keeps its place in the
+ * list carrying the failure, so a broken pin stays visible instead of vanishing
+ * into a red dot.
+ *
+ * - absent / not executable → dropped without a spawn,
+ * - `blockedForPlatform` answers non-empty → **no spawn**: the candidate keeps
+ *   its place carrying that reason (the one case is a Windows `chrome.exe` on a
+ *   WSL host, whose probe would start a browser instance it can never drive —
+ *   see {@link WSL_WINDOWS_LAUNCH_ERROR}),
+ * - two spellings of the same binary collapse into the first one seen.
+ *
+ * An empty candidate list resolves `[]` (nothing probed: unknown platform, or a
+ * host patched down to nothing).
+ *
+ * @param candidates - candidate executable paths.
+ * @param blockedForPlatform - answers a reason for a candidate this host must
+ * never exec, `""` for one it may probe.
+ */
+export async function scanChromeExecutables(candidates, blockedForPlatform = () => "") {
+    const list = Array.isArray(candidates) ? candidates : [];
+    const statuses = [];
+    const seen = new Set();
+    for (const candidate of list) {
+        const path = String(candidate ?? "").trim();
+        if (path === "")
+            continue;
+        const blocked = blockedForPlatform(path);
+        if (blocked !== "") {
+            // Never spawned: what a blocked candidate would do is start a
+            // browser this host could not drive. It stays on the list so the
+            // card can name it instead of dropping it into a red dot.
+            const key = `blocked\u0000${identity(path)}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            statuses.push({ path, version: "", error: blocked });
+            continue;
+        }
+        if (!presentOnDisk(path))
+            continue;
+        try {
+            const version = await probeExecutable(path);
+            const key = `${identity(path)}\u0000${version}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            statuses.push({ path, version, error: "" });
+        }
+        catch (error) {
+            const code = (error instanceof Error && typeof error.code === "string")
+                ? error.code
+                : "";
+            if (code === "ENOENT")
+                continue;
+            const key = identity(path);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            statuses.push({
+                path,
+                version: "",
+                error: firstLine(error instanceof Error ? error.message : String(error))
+            });
+        }
+    }
+    return statuses;
+}
+/**
+ * Discover usable Google Chrome executables when nothing is fixed: probe every
+ * candidate and report the first runnable one. Kept for its `Promise<string>`
+ * contract (`src/index.ts` re-export, tests, diagnostics).
+ * @param candidatePaths - candidate executable paths (default: platform list).
+ * @param blockedForPlatform - answers a reason for a candidate this host must
+ * never exec, `""` for one it may probe.
+ * @returns the discovered executable version line.
+ */
+export async function discoverChrome(candidatePaths, blockedForPlatform = () => "") {
+    const candidates = (Array.isArray(candidatePaths) ? candidatePaths : defaultChromePaths())
+        .map((candidate) => String(candidate ?? "").trim())
+        .filter((candidate) => candidate !== "");
+    if (candidates.length === 0)
+        return "";
+    const found = await scanChromeExecutables(candidates, blockedForPlatform);
+    for (const status of found) {
+        if (status.version !== "" && status.error === "")
+            return status.version;
+    }
+    const broken = found.find((status) => status.error !== "");
+    if (broken !== void 0)
+        throw new Error(broken.error);
+    throw new Error(`Chrome executable not found: no executable detected (checked: ${candidates.join(", ")})`);
+}
+/**
+ * One check run — the public "did we find a runnable Chrome?" question:
+ *
+ * - `chromePath` non-empty → probe that executable (ENOENT → "Chrome
+ *   executable not found: <path>"; non-zero → first stderr/stdout line;
+ *   success → the version line).
+ * - `chromePath` empty → run the scan over the candidate list (row config
+ *   `chromePaths`, default {@link defaultChromePaths}) and report the first
+ *   runnable entry. Nothing usable → the known executable-missing error;
+ *   only-present-but-broken entries → that entry's failure.
+ * - the extra flags declare a connect mode (`--browserUrl` / `--wsEndpoint`) →
+ *   resolve "": there is no local executable to check.
+ * - `blockedForPlatform` answers non-empty for what is selected → resolve "" with
+ *   **no spawn**. A Windows `chrome.exe` on a WSL host is the case: its
+ *   `--version` probe answers (which is why the selection looks healthy) but
+ *   answering means attaching to the Windows browser session, and that *starts*
+ *   a browser instance no tool call could drive
+ *   ({@link WSL_WINDOWS_LAUNCH_ERROR}).
+ *
+ * A run that probes **nothing** (no candidates, a connect mode, or a blocked
+ * path) resolves "" — callers must treat that as "no evidence", never as health.
+ *
+ * @param entry - validated {@link ChromeMcpConfig}.
+ * @param extraFlags - the flags list the bridge currently launches with; only
+ *   inspected for connect-mode options.
+ * @param blockedForPlatform - answers a reason for a path this host must never
+ *   exec, `""` for one it may probe.
+ * @returns the executable version line, or "" when nothing is probed.
+ */
+export function checkChrome(entry, extraFlags, blockedForPlatform = () => "") {
+    const target = typeof entry.chromePath === "string" ? entry.chromePath.trim() : "";
+    if (target !== "")
+        return blockedForPlatform(target) !== "" ? Promise.resolve("") : probeExecutable(target);
+    const flags = Array.isArray(extraFlags)
+        ? extraFlags
+        : Array.isArray(entry.extraFlags)
+            ? entry.extraFlags
+            : [];
+    if (flags.some((flag) => typeof flag === "string" && carriesConnectionMode(flag))) {
+        return Promise.resolve("");
+    }
+    return discoverChrome(entry.chromePaths, blockedForPlatform);
+}
+//# sourceMappingURL=scan.js.map

package/lib/host/discovery/scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.js","sourceRoot":"","sources":["../../../src/host/discovery/scan.ts"],"names":[],"mappings":"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"}

package/lib/host/flags.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Validate a user-authored extraFlags list: a plain array of flag strings
+ * carrying no control characters (argv is execve'd without a shell), and no
+ * executable-path flag — the executable is picked in the card's selector, so
+ * letting a flag pin one would put a second source of truth over the bridge
+ * argv. Throws with the offending entry so the settings layer can surface it.
+ * @param value - candidate flags array.
+ * @returns true when valid.
+ */
+export declare function validateExtraFlags(value: unknown): true;
+/** True when a flag selects the Chrome executable (upstream flags:
+ * `--executablePath` / `--executable-path` / `-e`, with or without `=`).
+ * No longer an accepted user flag (see {@link validateExtraFlags}): it stays
+ * here for the row-config fold ({@link extractExecutablePathFlag}) and the
+ * argv guard. */
+export declare function carriesExecutablePath(flag: string): boolean;
+/**
+ * Read the path a legacy `--executablePath` carries in the **row-config** flags
+ * list: the `=` spelling and the separated spelling both count, first entry
+ * wins, "" when nothing pins a path.
+ *
+ * The card's picker owns the executable now, so a row-config pin is not
+ * honored as a flag: it becomes the row-config source of the selection and gets
+ * stripped out of argv (see {@link stripExecutablePathFlags}).
+ */
+export declare function extractExecutablePathFlag(flags: unknown): string;
+/** Drop every entry that pins an executable from a flags list — paired with
+ * {@link extractExecutablePathFlag} so a legacy profile keeps its path as a
+ * selection source instead of reaching argv as a second source of truth.
+ * A `--flag <path>` spelling consumes the following entry; a flag-looking next
+ * entry keeps it (nothing was meant as the value). */
+export declare function stripExecutablePathFlags(flags: unknown): string[];
+/** True when one extraFlag declares a connect mode (no local executable). */
+export declare function carriesConnectionMode(flag: string): boolean;
+/** True when any entry of a flags list declares connect mode — the only thing
+ * that now spares the bridge from an executable probe. A flag that pins an
+ * executable is rejected on the way in instead (see
+ * {@link validateExtraFlags}). */
+export declare function flagsSkipCheck(flags: unknown): boolean;
+/** True when two flags lists are element-wise equal (flags are arrays). */
+export declare function sameFlags(a: unknown, b: unknown): boolean;
+//# sourceMappingURL=flags.d.ts.map

package/lib/host/flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../../src/host/flags.ts"],"names":[],"mappings":"AAoBA;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAkBvD;AAED;;;;iBAIiB;AACjB,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAWhE;AAED;;;;sDAIsD;AACtD,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAejE;AAED,6EAA6E;AAC7E,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;kCAGkC;AAClC,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEtD;AAED,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAGzD"}

package/lib/host/flags.js

@@ -0,0 +1,118 @@
+/**
+ * Extra-flags helpers shared by the bridge argv builder, the executable scan
+ * and the settings validation hook.
+ *
+ * Flags are execve'd as argv entries — never through a shell — so validation
+ * rejects control characters only, and the executable pin / connect-mode
+ * options are matched against their upstream spellings (`--executablePath`,
+ * `--executable-path`, `-e`, `--browserUrl`, `--wsEndpoint`).
+ *
+ * One rule has since hardened: pinning the executable by flag is a second
+ * source of truth for the same lever the executable picker owns, so a
+ * user-authored list may not carry it (`validateExtraFlags` rejects it), and
+ * the row config's copy gets folded into `chromePath` instead of reaching argv
+ * as a second opinion.
+ */
+import { CONTROL_PATTERN } from "./constants.js";
+/** One executable-path flag, upstream spellings, with or without `=`. */
+const EXECUTABLE_PATH_FLAG = /^(?:--executablePath|--executable-path|-e)(?:=|(?=\s)|$)/iu;
+/**
+ * Validate a user-authored extraFlags list: a plain array of flag strings
+ * carrying no control characters (argv is execve'd without a shell), and no
+ * executable-path flag — the executable is picked in the card's selector, so
+ * letting a flag pin one would put a second source of truth over the bridge
+ * argv. Throws with the offending entry so the settings layer can surface it.
+ * @param value - candidate flags array.
+ * @returns true when valid.
+ */
+export function validateExtraFlags(value) {
+    if (!Array.isArray(value)) {
+        throw new Error("extraFlags must be an array of strings");
+    }
+    for (const flag of value) {
+        if (typeof flag !== "string" || flag === "") {
+            throw new Error("extraFlags entries must be non-empty strings");
+        }
+        if (CONTROL_PATTERN.test(flag)) {
+            throw new Error(`extraFlags entry "${flag}" contains control characters`);
+        }
+        if (carriesExecutablePath(flag)) {
+            throw new Error(`extraFlags entry "${flag}" selects the Chrome executable — pick it in the Chrome executable picker instead`);
+        }
+    }
+    return true;
+}
+/** True when a flag selects the Chrome executable (upstream flags:
+ * `--executablePath` / `--executable-path` / `-e`, with or without `=`).
+ * No longer an accepted user flag (see {@link validateExtraFlags}): it stays
+ * here for the row-config fold ({@link extractExecutablePathFlag}) and the
+ * argv guard. */
+export function carriesExecutablePath(flag) {
+    return typeof flag === "string" && EXECUTABLE_PATH_FLAG.test(flag);
+}
+/**
+ * Read the path a legacy `--executablePath` carries in the **row-config** flags
+ * list: the `=` spelling and the separated spelling both count, first entry
+ * wins, "" when nothing pins a path.
+ *
+ * The card's picker owns the executable now, so a row-config pin is not
+ * honored as a flag: it becomes the row-config source of the selection and gets
+ * stripped out of argv (see {@link stripExecutablePathFlags}).
+ */
+export function extractExecutablePathFlag(flags) {
+    if (!Array.isArray(flags))
+        return "";
+    for (let index = 0; index < flags.length; index++) {
+        const flag = flags[index];
+        if (typeof flag !== "string" || !carriesExecutablePath(flag))
+            continue;
+        const eq = flag.indexOf("=");
+        if (eq !== -1)
+            return flag.slice(eq + 1).trim();
+        const next = flags[index + 1];
+        return typeof next === "string" && next.trim() !== "" ? next.trim() : "";
+    }
+    return "";
+}
+/** Drop every entry that pins an executable from a flags list — paired with
+ * {@link extractExecutablePathFlag} so a legacy profile keeps its path as a
+ * selection source instead of reaching argv as a second source of truth.
+ * A `--flag <path>` spelling consumes the following entry; a flag-looking next
+ * entry keeps it (nothing was meant as the value). */
+export function stripExecutablePathFlags(flags) {
+    if (!Array.isArray(flags))
+        return [];
+    const stripped = [];
+    let awaitingValue = false;
+    for (const flag of flags) {
+        if (typeof flag !== "string")
+            continue;
+        if (carriesExecutablePath(flag)) {
+            awaitingValue = !flag.includes("=");
+            continue;
+        }
+        if (awaitingValue && !flag.startsWith("-"))
+            continue;
+        awaitingValue = false;
+        stripped.push(flag);
+    }
+    return stripped;
+}
+/** True when one extraFlag declares a connect mode (no local executable). */
+export function carriesConnectionMode(flag) {
+    return /^--(?:browserUrl|wsEndpoint)(?:=|(?=\s)|$)/iu.test(flag);
+}
+/** True when any entry of a flags list declares connect mode — the only thing
+ * that now spares the bridge from an executable probe. A flag that pins an
+ * executable is rejected on the way in instead (see
+ * {@link validateExtraFlags}). */
+export function flagsSkipCheck(flags) {
+    return Array.isArray(flags) && flags.some((flag) => typeof flag === "string" && carriesConnectionMode(flag));
+}
+/** True when two flags lists are element-wise equal (flags are arrays). */
+export function sameFlags(a, b) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+        return false;
+    return a.every((flag, index) => flag === b[index]);
+}
+//# sourceMappingURL=flags.js.map

package/lib/host/flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.js","sourceRoot":"","sources":["../../src/host/flags.ts"],"names":[],"mappings":"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"}

package/lib/host/platform.d.ts

@@ -0,0 +1,38 @@
+/** Everything {@link isWindowsSubsystemForLinux} consults; each field defaults
+ * to what the running process actually is. */
+export type PlatformProbe = {
+    /** Defaults to `process.platform`. */
+    platform?: NodeJS.Platform;
+    /** Variable lookup; defaults to `process.env`. When a source is supplied its
+     * silence is the answer — the marker file is then not consulted, so a host
+     * that resolves its launch environment gets one deterministic answer
+     * instead of one that depends on the machine it booted on. */
+    env?: (name: string) => unknown;
+    /** File-presence lookup used only when `env` is not supplied (a bare call
+     * with no host to resolve against); defaults to the interop marker. */
+    exists?: (path: string) => boolean;
+};
+/**
+ * True when `path` names a Windows binary — one that lives on the interop mount
+ * (`/mnt/<drive>/…`), in a Windows spelling (`\\host\…`, `C:\…`), or simply
+ * carries the PE suffix. A Linux path is never Windows-side, and a candidate
+ * list built from {@link DEFAULT_CHROME_PATHS} never matches.
+ * @param path - one executable path as selected.
+ */
+export declare function isWindowsExecutablePath(path: unknown): boolean;
+/**
+ * True when the current process runs inside Windows Subsystem for Linux: a
+ * Linux kernel plus the WSL markers. A non-Linux platform (a plain Windows
+ * host) is never "under WSL", whatever its environment says.
+ * @param probe - what to consult (defaults to this process).
+ */
+export declare function isWindowsSubsystemForLinux(probe?: PlatformProbe): boolean;
+/**
+ * The interop trap the card warns about: we are under WSL **and** what is
+ * selected is a Windows executable. Both halves are required — a Linux binary
+ * selected on a Windows host is simply nothing to say.
+ * @param path - the effective executable path.
+ * @param probe - what to consult for the environment (defaults to this process).
+ */
+export declare function isWindowsExecutableUnderWsl(path: unknown, probe?: PlatformProbe): boolean;
+//# sourceMappingURL=platform.d.ts.map

package/lib/host/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../../src/host/platform.ts"],"names":[],"mappings":"AAsBA;8CAC8C;AAC9C,MAAM,MAAM,aAAa,GAAG;IACxB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B;;;kEAG8D;IAC9D,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAChC;2EACuE;IACvE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CACtC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAK9D;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,GAAE,aAAkB,GAAG,OAAO,CAU7E;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,GAAE,aAAkB,GAAG,OAAO,CAE7F"}

package/lib/host/platform.js

@@ -0,0 +1,64 @@
+/**
+ * Host half — where the plugin is running: is this Linux host a Windows
+ * Subsystem for Linux instance, and does one executable path name a Windows
+ * binary rather than a Linux one.
+ *
+ * The two answers only ever combine into one warning. Launching a Windows
+ * `chrome.exe` from WSL cannot work (`.probe/`, AGENTS.md): the debug pipes
+ * `chrome-devtools-mcp` opens do not survive the interop boundary, and the
+ * debugging port it reads from `DevToolsActivePort` stays bound to the Windows
+ * loopback, unreachable across the WSL2 NAT bridge. It even *seems* to work: the
+ * `--version` probe answers successfully, so a broken selection hides behind a
+ * healthy pill until the first tool call. That is why the pair is surfaced on
+ * the card as its own notice rather than through the error dot: nothing is
+ * failing yet, the required configuration is simply different.
+ *
+ * Both probes stay pure and injectable (`platform`, `env`, `exists`) so the
+ * tests never depend on the machine they run on.
+ */
+import { existsSync } from "node:fs";
+import { WINDOWS_EXE_PATTERN, WINDOWS_PATH_PATTERN, WSL_ENV_VARS, WSL_INTEROP_MARKER } from "./constants.js";
+/**
+ * True when `path` names a Windows binary — one that lives on the interop mount
+ * (`/mnt/<drive>/…`), in a Windows spelling (`\\host\…`, `C:\…`), or simply
+ * carries the PE suffix. A Linux path is never Windows-side, and a candidate
+ * list built from {@link DEFAULT_CHROME_PATHS} never matches.
+ * @param path - one executable path as selected.
+ */
+export function isWindowsExecutablePath(path) {
+    if (typeof path !== "string")
+        return false;
+    const candidate = path.trim();
+    if (candidate === "")
+        return false;
+    return WINDOWS_PATH_PATTERN.test(candidate) || WINDOWS_EXE_PATTERN.test(candidate);
+}
+/**
+ * True when the current process runs inside Windows Subsystem for Linux: a
+ * Linux kernel plus the WSL markers. A non-Linux platform (a plain Windows
+ * host) is never "under WSL", whatever its environment says.
+ * @param probe - what to consult (defaults to this process).
+ */
+export function isWindowsSubsystemForLinux(probe = {}) {
+    const platform = probe.platform ?? process.platform;
+    if (platform !== "linux")
+        return false;
+    if (probe.env !== void 0) {
+        return WSL_ENV_VARS.some((name) => {
+            const value = probe.env(name);
+            return typeof value === "string" && value.trim() !== "";
+        });
+    }
+    return (probe.exists ?? ((candidate) => existsSync(candidate)))(WSL_INTEROP_MARKER);
+}
+/**
+ * The interop trap the card warns about: we are under WSL **and** what is
+ * selected is a Windows executable. Both halves are required — a Linux binary
+ * selected on a Windows host is simply nothing to say.
+ * @param path - the effective executable path.
+ * @param probe - what to consult for the environment (defaults to this process).
+ */
+export function isWindowsExecutableUnderWsl(path, probe = {}) {
+    return isWindowsSubsystemForLinux(probe) && isWindowsExecutablePath(path);
+}
+//# sourceMappingURL=platform.js.map

package/lib/host/platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../../src/host/platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAiB7G;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAa;IACjD,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC3C,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,SAAS,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IACnC,OAAO,oBAAoB,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,mBAAmB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AACvF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CAAC,QAAuB,EAAE;IAChE,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC;IACpD,IAAI,QAAQ,KAAK,OAAO;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,KAAK,CAAC,GAAG,KAAK,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;YAC9B,MAAM,KAAK,GAAG,KAAK,CAAC,GAAI,CAAC,IAAI,CAAC,CAAC;YAC/B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;QAC5D,CAAC,CAAC,CAAC;IACP,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,SAAiB,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC;AAChG,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,CAAC,IAAa,EAAE,QAAuB,EAAE;IAChF,OAAO,0BAA0B,CAAC,KAAK,CAAC,IAAI,uBAAuB,CAAC,IAAI,CAAC,CAAC;AAC9E,CAAC"}