scenescout 1.1.0 → 1.3.0

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,8 +13,11 @@ import { createRequire } from "node:module";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { diagnose, installSkill, launchCommand, manualRegisterCommand, registerMcp, resolveClaudeDir, spawnRunner } from "./installer.js";
+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 { CLI_NAME, diagnose, ensureCommand, findOnUserPath, installSkill, isEphemeralRoot, launchCommand, manualRegisterCommand, planCommand, registerMcp, resolveClaudeDir, spawnRunner, } from "./installer.js";
 import { LEGACY_MEMORY_DIRNAME, MEMORY_DIRNAME } from "./engine/memory.js";
+import { localClock, formatSessionLine, LIVE_TOKEN_FILE, watchTarget, wholeSessions } from "./engine/live.js";
 import { formatScan, scanProject } from "./scan.js";
 const here = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(here, "..");
@@ -25,57 +28,98 @@ Usage:
   scenescout scan <projectPath>     Discover framework, routes, auth states
   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)
+                                    It also puts the \`scenescout\` command on your PATH.
+                                    (--skip-browser, --no-register, --no-command to opt out of a step;
+                                     --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)
-  scenescout status [projectPath]   What is the engine doing right now? (live status + recent actions)
+  scenescout status [projectPath]   What is the engine doing right now? (every session + recent actions)
+  scenescout watch [projectPath]    Open the live view in a browser: what each session is doing, a thumbnail
+                                    of its page, and a live stream you can switch on per session
+                                    (--no-open to print the address only)
 `);
     process.exit(exitCode);
 }
-/** Realtime observability: read the status file + recent action log the running engine maintains. */
-function status(projectPath) {
-    // A project last touched before the rename (or one a pre-rename engine is
-    // using right now) still keeps its status under the legacy directory.
-    const dir = [MEMORY_DIRNAME, LEGACY_MEMORY_DIRNAME]
+/**
+ * A project last touched before the rename (or one a pre-rename engine is using
+ * right now) still keeps its status under the legacy directory.
+ */
+function statusDir(projectPath) {
+    return ([MEMORY_DIRNAME, LEGACY_MEMORY_DIRNAME]
         .map((name) => path.join(projectPath, name))
-        .find((candidate) => fs.existsSync(path.join(candidate, "status.json"))) ?? path.join(projectPath, MEMORY_DIRNAME);
+        .find((candidate) => fs.existsSync(path.join(candidate, "status.json"))) ?? path.join(projectPath, MEMORY_DIRNAME));
+}
+/** null when there is no file; "unreadable" when there is one and it does not parse. */
+function readStatusFile(dir) {
     const statusPath = path.join(dir, "status.json");
-    if (!fs.existsSync(statusPath)) {
-        console.log(`No status file at ${statusPath} — no SceneScout engine has attached to this project (or it predates v0.8).`);
-        return;
-    }
-    let st;
+    if (!fs.existsSync(statusPath))
+        return null;
     try {
-        st = JSON.parse(fs.readFileSync(statusPath, "utf8"));
+        return JSON.parse(fs.readFileSync(statusPath, "utf8"));
     }
     catch {
         // status.json is written fire-and-forget on every tool call, so a process
         // killed mid-write leaves a truncated file. That is a diagnosable state,
         // not a reason for the diagnostic tool itself to crash.
-        console.log(`Status file at ${statusPath} is unreadable or truncated — the engine was probably killed mid-write. Re-attach to refresh it.`);
+        return "unreadable";
+    }
+}
+function pidAlive(pid) {
+    if (!pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means the process EXISTS but belongs to another user — only
+        // ESRCH actually means "no such process". Treating both as dead reported
+        // a live engine as stale.
+        return err?.code === "EPERM";
+    }
+}
+/** Realtime observability: read the status file + recent action log the running engine maintains. */
+function status(projectPath) {
+    const dir = statusDir(projectPath);
+    const statusPath = path.join(dir, "status.json");
+    const st = readStatusFile(dir);
+    if (st === null) {
+        console.log(`No status file at ${statusPath} — no SceneScout engine has attached to this project (or it predates v0.8).`);
         return;
     }
-    let alive = false;
-    if (st.pid) {
-        try {
-            process.kill(st.pid, 0);
-            alive = true;
-        }
-        catch (err) {
-            // EPERM means the process EXISTS but belongs to another user — only
-            // ESRCH actually means "no such process". Treating both as dead reported
-            // a live engine as stale.
-            alive = err?.code === "EPERM";
-        }
+    if (st === "unreadable") {
+        console.log(`Status file at ${statusPath} is unreadable or truncated — the engine was probably killed mid-write. Re-attach to refresh it.`);
+        return;
     }
+    const alive = pidAlive(st.pid);
     const age = st.at ? Math.round((Date.now() - new Date(st.at).getTime()) / 1000) : null;
     console.log(`Engine pid ${st.pid ?? "?"} — ${alive ? "ALIVE" : "not running (stale status)"}`);
     console.log(`${st.phase === "running" ? "⏳ running" : "· idle after"}: ${st.tool ?? "?"}${age !== null ? ` (as of ${age}s ago)` : ""}`);
-    console.log(`Session: ${st.session ?? "?"} (${st.role ?? "?"})${st.sessions && st.sessions.length > 1 ? ` · all sessions: ${st.sessions.join(", ")}` : ""}`);
-    if (st.url)
-        console.log(`URL: ${st.url}`);
+    // The file is written by another process and can be caught mid-write, so
+    // only entries whole enough to describe are described.
+    const sessions = wholeSessions(st.detail);
+    if (sessions.length > 0) {
+        // One line per session. The single "Session:" line below it is all an
+        // engine from before the live view can offer.
+        console.log(`Sessions (${sessions.length}):`);
+        for (const entry of sessions)
+            console.log(`  ${formatSessionLine(entry, Date.now())}`);
+        if (alive && st.live?.port)
+            console.log("Live view: scenescout watch");
+        if (alive && st.live?.error)
+            console.log(`Live view unavailable: ${st.live.error}`);
+    }
+    else {
+        console.log(`Session: ${st.session ?? "?"} (${st.role ?? "?"})${st.sessions && st.sessions.length > 1 ? ` · all sessions: ${st.sessions.join(", ")}` : ""}`);
+        if (st.url)
+            console.log(`URL: ${st.url}`);
+    }
     // Recent actions from the newest session log — the "what has it been doing" trail.
     const logs = fs.existsSync(dir)
         ? fs
@@ -101,7 +145,7 @@ function status(projectPath) {
         for (const line of lines) {
             try {
                 const e = JSON.parse(line);
-                console.log(`  ${e.at.slice(11, 19)} ${e.action}${e.target ? ` ${e.target}` : ""} @ ${e.url}`);
+                console.log(`  ${localClock(e.at)} ${e.action}${e.target ? ` ${e.target}` : ""} @ ${e.url}`);
             }
             catch {
                 /* skip malformed line */
@@ -109,23 +153,120 @@ function status(projectPath) {
         }
     }
 }
-/** Where Playwright expects its Chromium build; null when playwright cannot say. */
-async function chromiumPath() {
+/** Open the engine's live view. The engine serves it; this only finds the address and hands it to a browser. */
+function watch(projectPath, open) {
+    const dir = statusDir(projectPath);
+    const st = readStatusFile(dir);
+    let token = null;
     try {
-        const { chromium } = await import("playwright");
-        return chromium.executablePath() || null;
+        token = fs.readFileSync(path.join(dir, LIVE_TOKEN_FILE), "utf8");
     }
     catch {
-        return null;
+        // watchTarget explains a missing token in context.
+    }
+    const target = watchTarget({ status: st, alive: st !== null && st !== "unreadable" && pidAlive(st.pid), token });
+    if ("problem" in target) {
+        console.log(target.problem);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`Live view: ${target.url}`);
+    console.log("It is served on this machine only, and the address holds its access token: treat it like a password.");
+    if (!open)
+        return;
+    const { command, args } = browserOpener(target.url);
+    const result = spawnSync(command, args, { stdio: "ignore" });
+    if (result.error || result.status !== 0)
+        console.log("Could not open a browser from here. Open the address above yourself.");
+}
+/** The platform's own "open this URL" command. */
+function browserOpener(url) {
+    switch (process.platform) {
+        case "darwin":
+            return { command: "open", args: [url] };
+        case "win32":
+            return { command: "cmd", args: ["/c", "start", "", url] };
+        default:
+            return { command: "xdg-open", args: [url] };
+    }
+}
+/** 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 playwright = await import("playwright");
+        for (const name of BROWSER_ENGINES)
+            executables[name] = playwright[name].executablePath() || null;
     }
+    catch {
+        // 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 +278,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 +300,116 @@ 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`);
+            }
+        }
+        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`);
+            }
+        }
+    }
+    // `scenescout status`, `watch` and `doctor` are typed by a person, and neither
+    // a checkout nor an npx run leaves the command on PATH. Not having it costs
+    // convenience, never a working setup, so this step reports and does not fail.
+    let cli = isEphemeralRoot(packageRoot) ? `npx -y ${CLI_NAME}` : `node ${path.join(packageRoot, "dist", "cli.js")}`;
+    if (browserOnly) {
+        // a plugin install has no package of its own to put on PATH
+    }
+    else if (flags.includes("--no-command")) {
+        console.log(`· Putting \`${CLI_NAME}\` on PATH skipped (--no-command). Until then the command is:  ${cli}`);
+    }
+    else {
+        const onPath = () => findOnUserPath({ names: process.platform === "win32" ? [`${CLI_NAME}.cmd`] : [CLI_NAME], pathValue: process.env.PATH ?? "" });
+        const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+        const done = ensureCommand(planCommand({ packageRoot, nodePath: process.execPath, version: pkg.version, resolved: onPath(), platform: process.platform }), spawnRunner);
+        if (done.status === "present") {
+            cli = CLI_NAME;
+            console.log(`✓ \`${CLI_NAME}\` command already on PATH: ${done.at}`);
+        }
+        else if (done.status === "installed") {
+            const at = onPath();
+            if (at)
+                cli = CLI_NAME;
+            const what = done.how === "link" ? "linked to this checkout, so it runs whatever was last built" : "installed globally";
+            console.log(at
+                ? `✓ \`${CLI_NAME}\` command ${what}: ${at}${done.replaced ? `   (it replaces ${done.replaced})` : ""}`
+                : `· \`${CLI_NAME}\` was ${what}, but npm's global bin directory is not on this shell's PATH. Add it (\`npm prefix -g\` names it; the commands are in its bin folder), or use:  ${cli}`);
         }
         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`);
+            console.log(`· \`${CLI_NAME}\` was not put on PATH (${done.detail}). To do it by hand:  ${done.manual}\n  Until then the command is:  ${cli}`);
         }
     }
     if (failed) {
-        console.log("\nSetup is incomplete — fix the lines marked ✗ or · above, then run:  scenescout doctor");
+        console.log(`\nSetup is incomplete — fix the lines marked ✗ or · above, then run:  ${cli} doctor${forClaude ? "" : " --engine"}`);
         process.exitCode = 1;
         return;
     }
@@ -195,8 +417,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:  scenescout 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:  ${cli} doctor${forClaude ? "" : " --engine"}`);
 }
 async function doctor(flags) {
     const checks = diagnose({
@@ -204,7 +430,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 +445,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
@@ -259,6 +492,11 @@ try {
             status(path.resolve(args[0] ?? process.cwd()));
             break;
         }
+        case "watch": {
+            const positional = args.filter((a) => !a.startsWith("--"));
+            watch(path.resolve(positional[0] ?? process.cwd()), !args.includes("--no-open"));
+            break;
+        }
         default:
             usage();
     }