@comecaramelos/dsh-chrome-mcp 0.0.1 → 2.0.0

package/lib/host/discovery/scan.js

@@ -0,0 +1,195 @@
+/**
+ * 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 the bridge *launches* has to 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/). What
+ * the Windows side *is* good for is connect mode, so on a WSL host the Windows
+ * executables join the candidate list as `blockedForPlatform` answers it —
+ * visible, selectable, never spawned — and the run that drives them is the
+ * **Prelaunch Windows Chrome** one. Never spawn a blocked candidate.
+ */
+import { flagsSkipProbe } from "../flags.js";
+import { firstLine } from "../status.js";
+import { readConfigField } from "../values.js";
+import { windowsPathToMount } from "../windows/paths.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 as a `note`, never as a failure (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 keeps its place on the list
+            // carrying that reason as a **note** — what gets reported is what
+            // this host could not do with the path, not whether it is there, and
+            // reporting it as a failure would read as a broken executable.
+            //
+            // The seen key folds through the interop mount, because the same
+            // executable reaches this list in either spelling: the Windows one
+            // the locate answers, and the mount one a saved row or the row config
+            // can carry (the only spelling the WSL side can stat). One executable
+            // answers once, under the first spelling seen.
+            const mounted = windowsPathToMount(path);
+            const key = `blocked\u0000${identity(mounted !== "" ? mounted : path)}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            statuses.push({ path, version: "", error: "", note: 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: "", note: "" });
+        }
+        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)),
+                note: ""
+            });
+        }
+    }
+    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);
+    // A note is the other half of "nothing answered": the candidate is there, it
+    // is simply not launchable as a local executable from this host (the one
+    // case is a Windows executable under WSL), and the note names the run that
+    // drives it.
+    const noted = found.find((status) => status.note !== "");
+    if (noted !== void 0) {
+        throw new Error(`Chrome executable not found: no executable detected for this host (checked: ${candidates.join(", ")}); ${noted.note}`);
+    }
+    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 leave the check mute: they declare a connect mode
+ *     (`--browserUrl` / `--browser-url` / `-u`, `--wsEndpoint` /
+ *     `--ws-endpoint` / `-w`, `--autoConnect` / `--auto-connect`), name a
+ *     config file (`--config`), or fix another `--channel` than the `stable`
+ *     the candidate list models → resolve "": there is no local executable
+ *     this check could honestly answer for.
+ * - `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, a config file
+ * or another channel standing in for the local executable, 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;
+ *   inspected for the entries that leave the check mute.
+ * @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 = () => "") {
+    // The two config fields read here are volatile, so what they carry is either a
+    // reference or the value a caller handed in explicitly.
+    const target = readConfigField(entry.chromePath, "").trim();
+    if (target !== "")
+        return blockedForPlatform(target) !== "" ? Promise.resolve("") : probeExecutable(target);
+    const flags = extraFlags === void 0 ? readConfigField(entry.extraFlags, []) : extraFlags;
+    if (flagsSkipProbe(flags)) {
+        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,65 @@
+/**
+ * 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 (the bridge will not launch a
+ * local executable). Upstream spellings (docs/configuration.md): the two URL
+ * options — `--browserUrl`/`--browser-url`/`-u` and
+ * `--wsEndpoint`/`--ws-endpoint`/`-w` — plus `--autoConnect`/`--auto-connect`,
+ * which attaches to an already-running Chrome (Chrome 144+) instead of starting
+ * one. Each form counts with its value inline (`=`), carried as the following
+ * entry (the whitespace-split env source's spelling), or bare.
+ */
+export declare function carriesConnectionMode(flag: string): boolean;
+/** True when one extraFlag names a config file. */
+export declare function carriesConfigFile(flag: unknown): boolean;
+/** True when one extraFlag fixes the update channel to something other than
+ * `stable` (the default the candidate list models). `next` is the entry that
+ * follows a bare `--channel`; a value equal to the default is not a skip. */
+export declare function carriesOtherChannel(flag: unknown, next?: unknown): boolean;
+/** True when an executable probe could not answer here, whatever the host
+ * carries: the bridge connects instead of launching (connect mode), the
+ * executable it runs came from a config file, or the channel it looks in is
+ * not the `stable` one the candidate list models. A check that ran **no**
+ * probe answers `""` — *no evidence*, never health: it must not clear
+ * `lastError` nor the known `chromeMissing` state. */
+export declare function flagsSkipProbe(flags: unknown): boolean;
+/** True when any entry of a flags list declares connect mode — the connect
+ * half that answers the live `carriesConnectionMode` mirror, keys the pill
+ * relabel on, and drops `--executablePath` from the argv. For what spares the
+ * *executable check* there is the wider {@link flagsSkipProbe}: a config file
+ * and a non-`stable` channel also leave the probe mute, while the bridge still
+ * launches a local executable. */
+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":"AAsBA;;;;;;;;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;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAQD,mDAAmD;AACnD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAExD;AAQD;;6EAE6E;AAC7E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAa1E;AAED;;;;;sDAKsD;AACtD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAStD;AAED;;;;;kCAKkC;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,186 @@
+/**
+ * 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`; the connect group `--browserUrl`/`--browser-url`/
+ * `-u`, `--wsEndpoint`/`--ws-endpoint`/`-w`, `--autoConnect`/`--auto-connect`;
+ * plus the probe-skipping `--config` and `--channel`).
+ *
+ * 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 (the bridge will not launch a
+ * local executable). Upstream spellings (docs/configuration.md): the two URL
+ * options — `--browserUrl`/`--browser-url`/`-u` and
+ * `--wsEndpoint`/`--ws-endpoint`/`-w` — plus `--autoConnect`/`--auto-connect`,
+ * which attaches to an already-running Chrome (Chrome 144+) instead of starting
+ * one. Each form counts with its value inline (`=`), carried as the following
+ * entry (the whitespace-split env source's spelling), or bare.
+ */
+export function carriesConnectionMode(flag) {
+    return /^(?:--(?:auto[-]?connect|browser[-]?url|ws[-]?endpoint)(?:=|(?=\s)|$)|-[uw]\b)/iu.test(flag);
+}
+/** One config-file flag, `--config <file>` (also matched for the
+ * `--config-path` spelling). A JSON config can fix the executable and the
+ * connect mode itself, so the bridge argv no longer states locally what will
+ * run — the check would only guess. */
+const CONFIG_FILE_FLAG = /^--config(?:-path)?(?:=|(?=\s)|$)/iu;
+/** True when one extraFlag names a config file. */
+export function carriesConfigFile(flag) {
+    return typeof flag === "string" && CONFIG_FILE_FLAG.test(flag);
+}
+/** One `--channel` flag. Its value picks where upstream looks for a browser
+ * (`canary`/`dev`/`beta`/`stable`); the check's own candidate list models only
+ * `stable`, so any other value makes it answer "not found" about a browser
+ * living in another channel. */
+const CHANNEL_FLAG = /^--channel(?:=|(?=\s)|$)/iu;
+/** True when one extraFlag fixes the update channel to something other than
+ * `stable` (the default the candidate list models). `next` is the entry that
+ * follows a bare `--channel`; a value equal to the default is not a skip. */
+export function carriesOtherChannel(flag, next) {
+    if (typeof flag !== "string" || !CHANNEL_FLAG.test(flag))
+        return false;
+    const eq = flag.indexOf("=");
+    let value;
+    if (eq !== -1) {
+        value = flag.slice(eq + 1).trim();
+    }
+    else {
+        const whitespace = /\s/u.exec(flag);
+        if (whitespace !== null)
+            value = flag.slice(whitespace.index + 1).trim();
+        else if (typeof next === "string" && !next.startsWith("-"))
+            value = next.trim();
+        else
+            return false;
+    }
+    return value !== "" && value.toLowerCase() !== "stable";
+}
+/** True when an executable probe could not answer here, whatever the host
+ * carries: the bridge connects instead of launching (connect mode), the
+ * executable it runs came from a config file, or the channel it looks in is
+ * not the `stable` one the candidate list models. A check that ran **no**
+ * probe answers `""` — *no evidence*, never health: it must not clear
+ * `lastError` nor the known `chromeMissing` state. */
+export function flagsSkipProbe(flags) {
+    if (!Array.isArray(flags))
+        return false;
+    for (let index = 0; index < flags.length; index += 1) {
+        const flag = flags[index];
+        if (typeof flag !== "string")
+            continue;
+        if (carriesConnectionMode(flag) || carriesConfigFile(flag))
+            return true;
+        if (CHANNEL_FLAG.test(flag) && carriesOtherChannel(flag, flags[index + 1]))
+            return true;
+    }
+    return false;
+}
+/** True when any entry of a flags list declares connect mode — the connect
+ * half that answers the live `carriesConnectionMode` mirror, keys the pill
+ * relabel on, and drops `--executablePath` from the argv. For what spares the
+ * *executable check* there is the wider {@link flagsSkipProbe}: a config file
+ * and a non-`stable` channel also leave the probe mute, while the bridge still
+ * launches a local executable. */
+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":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD,yEAAyE;AACzE,MAAM,oBAAoB,GAAG,4DAA4D,CAAC;AAE1F;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC7C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;IAC9D,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;QACpE,CAAC;QACD,IAAI,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,+BAA+B,CAAC,CAAC;QAC9E,CAAC;QACD,IAAI,qBAAqB,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CACX,qBAAqB,IAAI,mFAAmF,CAC/G,CAAC;QACN,CAAC;IACL,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;;iBAIiB;AACjB,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAC9C,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACvE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAAc;IACpD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACrC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QAChD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC;YAAE,SAAS;QACvE,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,EAAE,KAAK,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAChD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QAC9B,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7E,CAAC;IACD,OAAO,EAAE,CAAC;AACd,CAAC;AAED;;;;sDAIsD;AACtD,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACnD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACrC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,aAAa,GAAG,KAAK,CAAC;IAC1B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,SAAS;QACvC,IAAI,qBAAqB,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9B,aAAa,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YACpC,SAAS;QACb,CAAC;QACD,IAAI,aAAa,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QACrD,aAAa,GAAG,KAAK,CAAC;QACtB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,QAAQ,CAAC;AACpB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAC9C,OAAO,kFAAkF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzG,CAAC;AAED;;;uCAGuC;AACvC,MAAM,gBAAgB,GAAG,qCAAqC,CAAC;AAE/D,mDAAmD;AACnD,MAAM,UAAU,iBAAiB,CAAC,IAAa;IAC3C,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACnE,CAAC;AAED;;;gCAGgC;AAChC,MAAM,YAAY,GAAG,4BAA4B,CAAC;AAElD;;6EAE6E;AAC7E,MAAM,UAAU,mBAAmB,CAAC,IAAa,EAAE,IAAc;IAC7D,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACvE,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,KAAa,CAAC;IAClB,IAAI,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC;QACZ,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACtC,CAAC;SAAM,CAAC;QACJ,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,UAAU,KAAK,IAAI;YAAE,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;aACpE,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;;YAC3E,OAAO,KAAK,CAAC;IACtB,CAAC;IACD,OAAO,KAAK,KAAK,EAAE,IAAI,KAAK,CAAC,WAAW,EAAE,KAAK,QAAQ,CAAC;AAC5D,CAAC;AAED;;;;;sDAKsD;AACtD,MAAM,UAAU,cAAc,CAAC,KAAc;IACzC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACxC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1B,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,SAAS;QACvC,IAAI,qBAAqB,CAAC,IAAI,CAAC,IAAI,iBAAiB,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QACxE,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,mBAAmB,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;IAC5F,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;;kCAKkC;AAClC,MAAM,UAAU,cAAc,CAAC,KAAc;IACzC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,qBAAqB,CAAC,IAAI,CAAC,CAAC,CAAC;AACjH,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,SAAS,CAAC,CAAU,EAAE,CAAU;IAC5C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAClF,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,KAAM,CAAc,CAAC,KAAK,CAAC,CAAC,CAAC;AACrE,CAAC"}

package/lib/host/kind.d.ts

@@ -0,0 +1,45 @@
+import type { KindOption, McpKind, ServerEntry } from "@comecaramelos/dsh-mcp-manager/api";
+import type { Controller } from "./controller/index.js";
+/** Split one `lines` field's value into its flags. Missing/blank answers nothing
+ * — the entry carries no own answer, so the caller falls through to the row. */
+export declare function parseFlagLines(value: unknown): string[] | undefined;
+/** Join one flags list back into a `lines` field value (round-trips with
+ * {@link parseFlagLines}). */
+export declare function joinFlagLines(flags: readonly string[]): string;
+/**
+ * What the executable field offers: the saved rows first, then every path the
+ * last scan reported, then the Windows-side executables a WSL host carries, then
+ * the path a live connection actually launches with — the running path is the
+ * answer the Host knows best, and it may not be a saved row yet. A stored pick
+ * the choices stop carrying stays offered by the card itself, so it never
+ * silently becomes another one.
+ */
+export declare function executableChoices(controller: Controller): readonly KindOption[];
+/** The executable one entry launches with: its own pick, else what the row's
+ * layers resolve (the user layer, then the row config with a legacy
+ * `--executablePath` folded in) — never a scan answer and never a re-resolve. */
+export declare function entryExecutable(entry: ServerEntry, controller: Controller): string;
+/** The flags one entry launches with: its own `lines` field, else the row's
+ * resolved precedence (user layer > `DSH_CHROME_MCP_FLAGS` > row config > the
+ * schema default). */
+export declare function entryExtraFlags(entry: ServerEntry, controller: Controller): string[];
+/** The console-output mode one entry runs with: its own pick, else the row's
+ * answer. Never a third state. The field is a toggle (`"true"` = reduce = log
+ * file); the `log`/`console` it stored while it was a choice still read. */
+export declare function entryStderrMode(entry: ServerEntry, controller: Controller): "log" | "console";
+/** The `chrome` kind: the local `chrome-devtools-mcp` bridge — what the row used
+ * to start for itself, now as one of the manager's connections. */
+export declare function createChromeKind(controller: Controller): McpKind;
+/** The `chrome-windows` kind: the Windows browser driven through the WSL interop
+ * mount. `resolve` runs the prelaunch itself — locate, prereq, free port,
+ * launch, wait for the bind — and answers the local `chrome-devtools-mcp` in
+ * connect mode against that port. The port speaks no MCP; the MCP stays the
+ * local process. Off WSL the entry is refused, with the answer the card shows. */
+export declare function createChromeWindowsKind(controller: Controller): McpKind;
+/** The kinds this host can answer, in registration order — `chrome` first,
+ * because it is the answer a standalone config translates into by default
+ * (./migration.ts). `chrome-windows` is offered on WSL only: anywhere else its
+ * `resolve` could only refuse, so the picker never lists it there (a native
+ * Windows host drives its own Chrome through `chrome`). */
+export declare function createChromeKinds(controller: Controller): McpKind[];
+//# sourceMappingURL=kind.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"kind.d.ts","sourceRoot":"","sources":["../../src/host/kind.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAsB,WAAW,EAAE,MAAM,oCAAoC,CAAC;AAC/G,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD;gFACgF;AAChF,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,GAAG,SAAS,CAInE;AAED;8BAC8B;AAC9B,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,UAAU,EAAE,CAe/E;AAED;;iFAEiF;AACjF,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,GAAG,MAAM,CAIlF;AAED;;sBAEsB;AACtB,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,GAAG,MAAM,EAAE,CAIpF;AAED;;4EAE4E;AAC5E,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,GAAG,KAAK,GAAG,SAAS,CAM7F;AAwCD;mEACmE;AACnE,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAgDhE;AAED;;;;kFAIkF;AAClF,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CA8CvE;AAED;;;;2DAI2D;AAC3D,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,EAAE,CAEnE"}