scenescout 1.0.0 → 1.2.0

package/dist/browsers.js

@@ -0,0 +1,185 @@
+/**
+ * Which browsers SceneScout can drive, which builds `scenescout install`
+ * downloads for them, and which build a given launch needs.
+ *
+ * Kept free of Playwright so the rules can be table-tested: the CLI and the
+ * engine pass in the paths Playwright reports and get decisions back.
+ */
+import fs from "node:fs";
+import path from "node:path";
+/** A browser the engine can launch. */
+export const BROWSER_ENGINES = ["chromium", "firefox", "webkit"];
+/**
+ * A build Playwright downloads. Chromium comes as two: the full browser, which
+ * a headed run opens, and the headless shell, which every headless run uses.
+ * Installing "chromium" brings both, which is what install has always done.
+ */
+export const INSTALL_TARGETS = ["chromium", "chromium-headless-shell", "firefox", "webkit"];
+export const DEFAULT_ENGINE = "chromium";
+/** Environment variable naming the browser an attach uses when it does not name one. */
+export const DEFAULT_ENGINE_ENV = "SCENESCOUT_BROWSER";
+/** Approximate size on disk, so the install output can say what it is about to fetch. */
+export const APPROX_DISK_MB = {
+    chromium: 550,
+    "chromium-headless-shell": 200,
+    firefox: 270,
+    webkit: 290,
+};
+export function isBrowserEngine(value) {
+    return BROWSER_ENGINES.includes(value);
+}
+/** The engine an attach uses when the caller names none: the environment's choice, else Chromium. */
+export function defaultEngine(env) {
+    const raw = env[DEFAULT_ENGINE_ENV]?.trim().toLowerCase();
+    if (!raw)
+        return DEFAULT_ENGINE;
+    if (!isBrowserEngine(raw)) {
+        throw new Error(`${DEFAULT_ENGINE_ENV}="${env[DEFAULT_ENGINE_ENV]}" is not a browser SceneScout can drive. Use one of: ${BROWSER_ENGINES.join(", ")}.`);
+    }
+    return raw;
+}
+/**
+ * Read the value of `--browsers`. Absent means what install has always done.
+ * `all` is every engine; a comma-separated list picks several. "chromium"
+ * already includes the headless shell, so naming both is the same as naming it.
+ */
+export function parseBrowserSelection(value) {
+    if (value === undefined)
+        return { targets: ["chromium"] };
+    const names = value
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+    const choices = `${INSTALL_TARGETS.join(", ")}, all`;
+    if (names.length === 0)
+        return { error: `--browsers needs a value. Choose from: ${choices}.` };
+    const picked = new Set();
+    for (const name of names) {
+        if (name === "all") {
+            for (const t of ["chromium", "firefox", "webkit"])
+                picked.add(t);
+        }
+        else if (INSTALL_TARGETS.includes(name)) {
+            picked.add(name);
+        }
+        else {
+            return { error: `"${name}" is not a browser SceneScout can install. Choose from: ${choices}.` };
+        }
+    }
+    if (picked.has("chromium"))
+        picked.delete("chromium-headless-shell");
+    return { targets: INSTALL_TARGETS.filter((t) => picked.has(t)) };
+}
+/** The arguments for Playwright's own installer. Target names are Playwright's names. */
+export function playwrightInstallArgs(targets) {
+    return ["install", ...targets];
+}
+/** The build a launch needs on disk. */
+export function launchTarget(engine, headed) {
+    if (engine !== "chromium")
+        return engine;
+    return headed ? "chromium" : "chromium-headless-shell";
+}
+/** The engine each build belongs to. */
+export function engineOf(target) {
+    return target === "chromium-headless-shell" ? "chromium" : target;
+}
+/**
+ * Where the headless shell lives, worked out from the full browser's path.
+ * Playwright exposes no path for the shell, but it keeps the two side by side
+ * under one revision: `chromium-1234/…` next to `chromium_headless_shell-1234/`.
+ * Null when the path does not have that shape.
+ */
+export function headlessShellDir(chromiumExecutable) {
+    if (!chromiumExecutable)
+        return null;
+    const parts = chromiumExecutable.split(/[\\/]/);
+    // The LAST such segment: a cache kept under a directory that happens to be
+    // named the same way must not be mistaken for the build directory.
+    let at = -1;
+    for (let i = parts.length - 1; i >= 0 && at < 0; i--)
+        if (/^chromium-\d+$/.test(parts[i]))
+            at = i;
+    if (at < 0)
+        return null;
+    const sep = chromiumExecutable.includes("\\") && !chromiumExecutable.includes("/") ? "\\" : "/";
+    return [...parts.slice(0, at), parts[at].replace(/^chromium-/, "chromium_headless_shell-")].join(sep);
+}
+/**
+ * Which builds are on disk. `executables` is what Playwright reports for each
+ * engine; a path Playwright names is not proof the file is there. The shell is
+ * counted only once Playwright has marked its download complete.
+ */
+export function browserPresence(executables, exists = fs.existsSync) {
+    const at = (p) => ({ installed: !!p && exists(p), path: p });
+    const shellDir = headlessShellDir(executables.chromium);
+    const shellMarker = shellDir ? path.join(shellDir, "INSTALLATION_COMPLETE") : null;
+    const chromium = at(executables.chromium);
+    return {
+        chromium: { installed: chromium.installed && !!shellMarker && exists(shellMarker), path: chromium.path },
+        "chromium-headless-shell": { installed: !!shellMarker && exists(shellMarker), path: shellDir },
+        firefox: at(executables.firefox),
+        webkit: at(executables.webkit),
+    };
+}
+/** The command that downloads one build, for the way this copy of SceneScout was installed. */
+export function installCommandFor(target, fromCheckout) {
+    const flags = `--browser-only --browsers ${target}`;
+    return fromCheckout ? `node dist/cli.js install ${flags}` : `npx -y scenescout install ${flags}`;
+}
+/**
+ * Whether pages may register service workers in this browser.
+ *
+ * The write policy works by intercepting requests. Only Chromium lets the
+ * driver intercept a request a service worker issues; in Firefox and WebKit
+ * such a request goes straight to the network, so an app that syncs its writes
+ * from a worker would send a DELETE through read-only mode with nothing
+ * logged. Blocking registration there makes the page send those requests
+ * itself, where the policy sees them.
+ */
+export function serviceWorkerPolicy(engine) {
+    return engine === "chromium" ? "allow" : "block";
+}
+/**
+ * The key that moves keyboard focus to the next control, links and buttons
+ * included. WebKit on macOS follows Safari: plain Tab stops only at text
+ * fields, and Option+Tab stops everywhere. A focus audit that pressed Tab
+ * there would walk past every button and report nothing.
+ */
+export function focusAdvanceKey(engine, platform) {
+    return engine === "webkit" && platform === "darwin" ? "Alt+Tab" : "Tab";
+}
+/**
+ * Run in every page before its own scripts: takes shared workers away.
+ *
+ * A request issued by a shared worker cannot be intercepted in any browser, so
+ * a write sent from one passes the policy unseen and unlogged. Removing the
+ * constructor makes feature detection fail, and an app then does that work on
+ * the page, where the policy sees it. Not applied in `destructive` mode, where
+ * the policy blocks nothing and the person has opted in to everything.
+ */
+export const REMOVE_SHARED_WORKER_SCRIPT = `(() => {
+  try { delete globalThis.SharedWorker; } catch {}
+  if ("SharedWorker" in globalThis) {
+    try { Object.defineProperty(globalThis, "SharedWorker", { value: undefined, configurable: true, writable: true }); } catch {}
+  }
+})()`;
+/** Whether pages may use shared workers in this write mode. */
+export function sharedWorkersAllowed(mode) {
+    return mode === "destructive";
+}
+/**
+ * What install says when the browsers it was asked for do not include the one
+ * a default attach launches, and that one is not on disk either. Without it,
+ * `install --browsers firefox` on a fresh machine ends in "ready" and the first
+ * attach fails. Null when there is nothing to say.
+ */
+export function defaultAttachNote(opts) {
+    if (opts.defaultInstalled || opts.selected.length === 0)
+        return null;
+    if (opts.selected.some((t) => engineOf(t) === opts.defaultEngine))
+        return null;
+    const engine = engineOf(opts.selected[0]);
+    return (`an attach drives ${opts.defaultEngine} unless told otherwise, and that build is not installed. ` +
+        `Pass browser: "${engine}" when attaching, or set ${DEFAULT_ENGINE_ENV}=${engine} in the MCP server's environment.`);
+}

package/dist/cli.js

@@ -4,7 +4,7 @@
  *
  *   scenescout scan <projectPath>   Print project discovery results
  *   scenescout serve                Run the MCP server on stdio
- *   scenescout install              Install the skill, download Chromium, register the MCP server
+ *   scenescout install              Install the skill, download the browser, register the MCP server
  *   scenescout doctor               Check every piece of the setup and say how to fix what is missing
  */
 import { spawnSync } from "node:child_process";
@@ -13,6 +13,8 @@ import { createRequire } from "node:module";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { APPROX_DISK_MB, BROWSER_ENGINES, browserPresence, defaultAttachNote, defaultEngine, launchTarget, parseBrowserSelection, playwrightInstallArgs, } from "./browsers.js";
+import { CLIENT_LABELS, firstMessageHint, manualFor, parseClients, registerWithClient, vscodeBinary } from "./clients.js";
 import { diagnose, installSkill, launchCommand, manualRegisterCommand, registerMcp, resolveClaudeDir, spawnRunner } from "./installer.js";
 import { LEGACY_MEMORY_DIRNAME, MEMORY_DIRNAME } from "./engine/memory.js";
 import { formatScan, scanProject } from "./scan.js";
@@ -26,7 +28,12 @@ Usage:
   scenescout serve                  Run the MCP server (stdio)
   scenescout install                One-step setup: skill + Chromium + MCP registration
                                     (--skip-browser, --no-register to opt out of a step;
-                                     --browser-only when the skill and server came from a plugin)
+                                     --browser-only when the skill and server came from a plugin;
+                                     --browsers <list> to choose what to download: chromium (default),
+                                     chromium-headless-shell, firefox, webkit, all — comma-separated)
+                                    (--client <list> to set up another MCP client instead of, or as well as,
+                                     Claude Code: claude-code (default), cursor, vscode, codex, gemini,
+                                     copilot, windsurf — comma-separated)
   scenescout doctor                 Check the setup and print the fix for anything missing
                                     (--engine: only node, the build and the browser — for plugin
                                      installs and other MCP clients)
@@ -109,23 +116,83 @@ function status(projectPath) {
         }
     }
 }
-/** Where Playwright expects its Chromium build; null when playwright cannot say. */
-async function chromiumPath() {
+/** Which browser builds are on disk, going by the paths Playwright reports for the version we depend on. */
+async function presentBrowsers() {
+    const executables = { chromium: null, firefox: null, webkit: null };
     try {
-        const { chromium } = await import("playwright");
-        return chromium.executablePath() || null;
+        const playwright = await import("playwright");
+        for (const name of BROWSER_ENGINES)
+            executables[name] = playwright[name].executablePath() || null;
     }
     catch {
-        return null;
+        // Playwright cannot be loaded: every build reads as absent, which is what doctor should say.
     }
+    return browserPresence(executables);
 }
-/** Download Chromium through the playwright CLI that ships with our own dependency. */
-function downloadChromium() {
+/** Download browser builds through the playwright CLI that ships with our own dependency. */
+function downloadBrowsers(targets) {
     const require = createRequire(import.meta.url);
     const cli = path.join(path.dirname(require.resolve("playwright/package.json")), "cli.js");
-    const r = spawnSync(process.execPath, [cli, "install", "chromium"], { stdio: "inherit" });
+    const r = spawnSync(process.execPath, [cli, ...playwrightInstallArgs(targets)], { stdio: "inherit" });
     return r.status === 0;
 }
+/**
+ * The value of a flag written as `--name x` or `--name=x`. Undefined when the
+ * flag is absent; empty when it was given no value, which includes being
+ * followed by another flag.
+ */
+function flagValue(flags, name) {
+    const inline = flags.find((f) => f.startsWith(`${name}=`));
+    if (inline)
+        return inline.slice(name.length + 1);
+    const at = flags.indexOf(name);
+    if (at < 0)
+        return undefined;
+    const next = flags[at + 1];
+    return next === undefined || next.startsWith("--") ? "" : next;
+}
+function browsersFlag(flags) {
+    // `--browser-only` is a different flag; a bare `--browser` is a slip that would otherwise be ignored and download Chromium.
+    const slip = flags.find((f) => f === "--browser" || f.startsWith("--browser="));
+    if (slip)
+        throw new Error(`unknown flag ${slip.split("=")[0]} — did you mean --browsers?`);
+    return flagValue(flags, "--browsers");
+}
+/** The `code` command on PATH, with its real path: the real path is what tells VS Code from a fork. */
+function codeOnPath() {
+    const names = process.platform === "win32" ? ["code.cmd", "code.exe"] : ["code"];
+    for (const dir of (process.env.PATH ?? "").split(path.delimiter).filter(Boolean)) {
+        for (const name of names) {
+            const candidate = path.join(dir, name);
+            try {
+                if (fs.existsSync(candidate))
+                    return { command: candidate, realPath: fs.realpathSync(candidate) };
+            }
+            catch {
+                // An unreadable PATH entry is not a VS Code install.
+            }
+        }
+    }
+    return null;
+}
+/** Every value given for a flag, across repeats and both spellings, joined the way one comma-separated value would be. */
+function flagValues(flags, names) {
+    const values = [];
+    flags.forEach((f, i) => {
+        for (const name of names) {
+            if (f.startsWith(`${name}=`))
+                values.push(f.slice(name.length + 1));
+            else if (f === name) {
+                const next = flags[i + 1];
+                values.push(next === undefined || next.startsWith("--") ? "" : next);
+            }
+        }
+    });
+    if (values.length === 0)
+        return undefined;
+    // One occurrence without a value is a mistake even when another has one.
+    return values.some((v) => v.trim() === "") ? "" : values.join(",");
+}
 async function install(flags) {
     const serverPath = path.join(packageRoot, "dist", "mcp-server.js");
     if (!fs.existsSync(serverPath)) {
@@ -137,7 +204,17 @@ async function install(flags) {
     // A plugin install already brings the skill and the server registration; the
     // only thing it cannot bring is the browser download.
     const browserOnly = flags.includes("--browser-only");
-    if (!browserOnly) {
+    // Read the choice before doing anything, so a typo costs nothing.
+    const selection = parseBrowserSelection(browsersFlag(flags));
+    if ("error" in selection)
+        throw new Error(selection.error);
+    const chosen = parseClients(flagValues(flags, ["--client", "--clients"]));
+    if ("error" in chosen)
+        throw new Error(chosen.error);
+    const forClaude = chosen.clients.includes("claude-code");
+    const others = chosen.clients.filter((c) => c !== "claude-code");
+    // The skill is Claude Code's way of receiving the method; every other client gets it from the server.
+    if (!browserOnly && forClaude) {
         const skill = installSkill({ packageRoot, claudeDir: resolveClaudeDir(process.env, os.homedir()) });
         for (const note of skill.notes)
             console.log(`· ${note}`);
@@ -149,45 +226,85 @@ async function install(flags) {
         console.log("· Browser download skipped (--skip-browser).");
     }
     else {
-        const existing = await chromiumPath();
-        if (existing && fs.existsSync(existing)) {
-            console.log(`✓ Chromium already present: ${existing}`);
-        }
-        else {
-            console.log("· Downloading Chromium (one-time, ~150 MB)…");
-            if (downloadChromium())
-                console.log("✓ Chromium downloaded.");
+        const present = await presentBrowsers();
+        const missing = selection.targets.filter((t) => !present[t].installed);
+        for (const t of selection.targets)
+            if (present[t].installed)
+                console.log(`✓ ${t} already present: ${present[t].path}`);
+        if (missing.length > 0) {
+            const size = missing.reduce((sum, t) => sum + APPROX_DISK_MB[t], 0);
+            console.log(`· Downloading ${missing.join(", ")} (one-time, about ${size} MB on disk)…`);
+            if (downloadBrowsers(missing))
+                console.log(`✓ Downloaded: ${missing.join(", ")}.`);
             else {
                 failed = true;
-                console.log("✗ Chromium download failed — run `npx playwright install chromium` and check your network/proxy.");
+                console.log(`✗ Browser download failed — run \`npx playwright install ${missing.join(" ")}\` and check your network/proxy.`);
             }
         }
     }
+    // Downloading a browser the server will not launch leaves the first attach failing with no hint why.
+    const engine = defaultEngine(process.env);
+    const note = defaultAttachNote({
+        selected: flags.includes("--skip-browser") ? [] : selection.targets,
+        defaultEngine: engine,
+        defaultInstalled: (await presentBrowsers())[launchTarget(engine, false)].installed,
+    });
+    if (note)
+        console.log(`· Note: ${note}`);
+    const launch = launchCommand({ packageRoot, nodePath: process.execPath, serverPath });
     if (browserOnly) {
         // nothing to register
     }
     else if (flags.includes("--no-register")) {
-        console.log(`· MCP registration skipped (--no-register). To do it by hand:\n\n  ${manualRegisterCommand(launchCommand({ packageRoot, nodePath: process.execPath, serverPath }))}\n`);
+        console.log("· MCP registration skipped (--no-register). To do it by hand:\n");
+        if (forClaude)
+            console.log(`  ${manualRegisterCommand(launch)}`);
+        for (const client of others)
+            console.log(`  ${CLIENT_LABELS[client]}: ${manualFor(client, launch, os.homedir())}`);
+        console.log("");
     }
     else {
-        const reg = registerMcp({ launch: launchCommand({ packageRoot, nodePath: process.execPath, serverPath }), serverPath, run: spawnRunner });
-        if (reg.status === "registered") {
-            console.log(`✓ MCP server ${reg.replaced ? "re-registered (paths refreshed)" : "registered"} with Claude Code at user scope.`);
-            for (const name of reg.removedLegacy)
-                console.log(`· removed the pre-rename MCP registration "${name}" (it pointed at this same server).`);
-            for (const note of reg.notes)
-                console.log(`· ${note}`);
+        if (forClaude) {
+            const reg = registerMcp({ launch, serverPath, run: spawnRunner });
+            if (reg.status === "registered") {
+                console.log(`✓ MCP server ${reg.replaced ? "re-registered (paths refreshed)" : "registered"} with Claude Code at user scope.`);
+                for (const name of reg.removedLegacy)
+                    console.log(`· removed the pre-rename MCP registration "${name}" (it pointed at this same server).`);
+                for (const note of reg.notes)
+                    console.log(`· ${note}`);
+            }
+            else {
+                failed = true;
+                console.log(reg.status === "claude-missing"
+                    ? "· `claude` is not on this shell's PATH, so the MCP server was not registered."
+                    : `✗ \`claude mcp add\` failed: ${reg.detail}`);
+                console.log(`  Run this once from a terminal where \`claude\` works:\n\n  ${reg.manual}\n`);
+            }
         }
-        else {
-            failed = true;
-            console.log(reg.status === "claude-missing"
-                ? "· `claude` is not on this shell's PATH, so the MCP server was not registered."
-                : `✗ \`claude mcp add\` failed: ${reg.detail}`);
-            console.log(`  Run this once from a terminal where \`claude\` works:\n\n  ${reg.manual}\n`);
+        const vscode = others.includes("vscode")
+            ? vscodeBinary({ platform: process.platform, home: os.homedir(), exists: fs.existsSync, codeOnPath: codeOnPath() })
+            : null;
+        for (const client of others) {
+            const reg = registerWithClient(client, { launch, home: os.homedir(), run: spawnRunner, vscode });
+            const label = CLIENT_LABELS[client];
+            if (reg.status === "registered") {
+                console.log(`✓ MCP server ${reg.replaced ? "re-registered" : "registered"} with ${label} (${reg.where}).`);
+                for (const note of reg.notes)
+                    console.log(`· ${note}`);
+            }
+            else {
+                failed = true;
+                // On Windows a client installed through npm is a .cmd shim, which node cannot start directly.
+                const windowsNote = process.platform === "win32" ? " (or it is installed as a .cmd shim, which cannot be started from here)" : "";
+                console.log(reg.status === "client-missing"
+                    ? `· ${label} was not found on this machine${windowsNote}, so nothing was registered with it.`
+                    : `✗ Registering with ${label} failed: ${reg.detail}`);
+                console.log(`  To do it by hand, ${reg.manual}\n`);
+            }
         }
     }
     if (failed) {
-        console.log("\nSetup is incomplete — fix the lines marked ✗ or · above, then run:  npm run doctor");
+        console.log(`\nSetup is incomplete — fix the lines marked ✗ or · above, then run:  scenescout doctor${forClaude ? "" : " --engine"}`);
         process.exitCode = 1;
         return;
     }
@@ -195,8 +312,12 @@ async function install(flags) {
         console.log("\nThe browser is ready — attach again.");
         return;
     }
-    console.log("\nStart a FRESH Claude Code session, then in any project run:  /scenescout");
-    console.log("Something off? Run:  npm run doctor");
+    if (forClaude)
+        console.log("\nStart a FRESH Claude Code session, then in any project run:  /scenescout");
+    // Telling someone to restart a client nothing was registered with sends them looking for a server that is not there.
+    if (others.length > 0 && !flags.includes("--no-register"))
+        console.log(`\n${firstMessageHint(others)}`);
+    console.log(`Something off? Run:  scenescout doctor${forClaude ? "" : " --engine"}`);
 }
 async function doctor(flags) {
     const checks = diagnose({
@@ -204,7 +325,12 @@ async function doctor(flags) {
         packageRoot,
         claudeDir: resolveClaudeDir(process.env, os.homedir()),
         nodeVersion: process.version,
-        chromiumPath: await chromiumPath(),
+        // What a default attach launches: the headless build of the default browser.
+        defaultBrowser: await (async () => {
+            const target = launchTarget(defaultEngine(process.env), false);
+            const found = (await presentBrowsers())[target];
+            return { target, path: found.installed ? found.path : null, expected: found.path };
+        })(),
         run: spawnRunner,
     });
     for (const c of checks) {
@@ -214,7 +340,9 @@ async function doctor(flags) {
     }
     if (checks.some((c) => !c.ok))
         process.exit(1);
-    console.log("\nAll good. In any project, run:  /scenescout");
+    console.log(flags.includes("--engine")
+        ? "\nAll good. Ask your agent:  Use SceneScout to test http://localhost:3000"
+        : "\nAll good. In any project, run:  /scenescout   (or ask: Use SceneScout to test http://localhost:3000)");
 }
 const [, , command, ...args] = process.argv;
 // A CLI's failure mode should be a sentence, not a stack trace. `scan` on a