scenescout 3.15.0 → 3.16.0

package/dist/first-run.js

@@ -19,6 +19,7 @@
  * and scripts/smoke/first-run.ts runs the built CLI against the demo app with
  * a throwaway home directory.
  */
+import { DEFAULT_BASELINE_THRESHOLD } from "./engine/baseline.js";
 import fs from "node:fs";
 import path from "node:path";
 import { APPROX_DISK_MB, launchTarget } from "./browsers.js";
@@ -151,6 +152,9 @@ export function firstRunCheckOptions(o, projectDir) {
         flowWrites: "never",
         onRefusedStep: "report",
         gateRetests: "never",
+        // A first look pictures nothing: baselines are a project's own list.
+        baseline: "off",
+        baselineThreshold: DEFAULT_BASELINE_THRESHOLD,
     };
 }
 /** What a first look downloads: the one build a headless Chromium launch needs, when it is not on disk, and nothing else. */

package/dist/installer.js

@@ -6,10 +6,11 @@
  * command runner) as an argument, so a test can point it at a temp dir and a
  * fake `claude` binary instead of mutating the developer's real ~/.claude.
  */
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs";
+import { createRequire } from "node:module";
 import path from "node:path";
-import { engineOf } from "./browsers.js";
+import { APPROX_DISK_MB, BROWSER_ENGINES, browserPresence, engineOf, playwrightInstallArgs, } from "./browsers.js";
 export const SKILL_NAME = "scenescout";
 export const MCP_NAME = "scenescout";
 /** Names this tool's skill and MCP server had before renames; cleaned up on install so the old slash command and a duplicate tool set do not linger. */
@@ -363,11 +364,24 @@ export function diagnose(opts) {
         detail: browser.path ?? (browser.expected ? `not found at ${browser.expected}` : "playwright could not name a browser path"),
         fix: `${repair.browser(browser.target)}   (or: npx playwright install ${browser.target})`,
     });
+    const extension = opts.desktopExtension ?? null;
+    if (extension)
+        checks.push(...desktopExtensionChecks(extension, opts.headlessShellDir ?? null, opts.version));
     if (opts.scope === "engine")
         return checks;
     const skill = path.join(opts.claudeDir, "skills", SKILL_NAME, "SKILL.md");
-    checks.push({ name: "skill installed", ok: fs.existsSync(skill), detail: skill, fix: repair.setup });
     const got = opts.run("claude", ["mcp", "get", MCP_NAME]);
+    if (extension && !fs.existsSync(skill) && (got.missing || got.status !== 0)) {
+        // The extension brings its own server, and Claude Desktop has no skill
+        // folder: someone who only uses Claude Desktop has nothing to fix here.
+        checks.push({
+            name: CLAUDE_CODE_NOT_NEEDED,
+            ok: true,
+            detail: `not set up, and the desktop extension does not need it (to use SceneScout in Claude Code as well: ${repair.setup})`,
+        });
+        return checks;
+    }
+    checks.push({ name: "skill installed", ok: fs.existsSync(skill), detail: skill, fix: repair.setup });
     if (got.missing) {
         checks.push({
             name: "claude CLI on PATH",
@@ -419,3 +433,253 @@ export function diagnose(opts) {
     }
     return checks;
 }
+/** Which browser builds are on disk, going by the paths Playwright reports for the version we depend on. */
+export 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);
+}
+/**
+ * The reason Playwright's installer gives for a failed download: its first
+ * `Error:` line, which names the cause (a refused connection, a proxy, a full
+ * disk) where its last lines are a stack trace. Null when it gave none.
+ */
+export function installerFailure(stderr) {
+    const lines = stderr.split(/\r?\n/).map((l) => l.trim());
+    const first = lines.find((l) => /^Error: \S/.test(l)) ?? lines.find((l) => l !== "" && !l.startsWith("at ") && /fail/i.test(l));
+    return first
+        ? first
+            .replace(/^Error: /, "")
+            .replace(/, caused by$/, "")
+            .slice(0, 300)
+        : null;
+}
+/** How long a browser download may run before it is stopped and reported as failed. */
+export const BROWSER_DOWNLOAD_TIMEOUT_MS = 15 * 60_000;
+/**
+ * The environment Playwright's installer runs in. A host that runs this server
+ * inside its own Electron binary (a desktop app's bundled runtime) makes
+ * process.execPath that binary, which starts the app instead of a script
+ * unless told to behave as Node.
+ */
+export function downloadEnv(env, electron) {
+    return electron ? { ...env, ELECTRON_RUN_AS_NODE: "1" } : env;
+}
+/**
+ * Download browser builds through the playwright CLI that ships with our own
+ * dependency. `inherit` shows its progress on this terminal; `stderr` keeps
+ * stdout clean for a server whose stdout is its protocol channel.
+ */
+export function downloadBrowsers(targets, output) {
+    return new Promise((resolve) => {
+        let cli;
+        try {
+            cli = path.join(path.dirname(createRequire(import.meta.url).resolve("playwright/package.json")), "cli.js");
+        }
+        catch (err) {
+            resolve({ ok: false, detail: `Playwright's installer could not be found: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}` });
+            return;
+        }
+        let seen = "";
+        let timedOut = false;
+        const child = spawn(process.execPath, [cli, ...playwrightInstallArgs(targets)], {
+            stdio: output === "inherit" ? "inherit" : ["ignore", process.stderr, "pipe"],
+            env: downloadEnv(process.env, process.versions.electron),
+        });
+        child.stderr?.on("data", (chunk) => {
+            process.stderr.write(chunk);
+            if (seen.length < 20_000)
+                seen += chunk.toString();
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill();
+        }, BROWSER_DOWNLOAD_TIMEOUT_MS);
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            resolve({ ok: false, detail: err.message });
+        });
+        // A stopped download may leave a child of the installer holding the pipe, so `close` may never come: answer on `exit`.
+        child.on("exit", () => {
+            if (timedOut)
+                resolve({ ok: false, detail: `stopped after ${BROWSER_DOWNLOAD_TIMEOUT_MS / 60_000} minutes` });
+        });
+        child.on("close", (code, signal) => {
+            clearTimeout(timer);
+            if (code === 0)
+                resolve({ ok: true });
+            else if (timedOut)
+                resolve({ ok: false, detail: `stopped after ${BROWSER_DOWNLOAD_TIMEOUT_MS / 60_000} minutes` });
+            else
+                resolve({
+                    ok: false,
+                    detail: installerFailure(seen) ?? (signal ? `the installer was stopped by ${signal}` : `the installer exited with code ${code}`),
+                });
+        });
+    });
+}
+/** The `name` in the desktop extension's manifest.json, which is how its install is told apart from other extensions. */
+export const DESKTOP_EXTENSION_NAME = "scenescout";
+/** Where Claude Desktop keeps the folder it unpacks each installed extension into. */
+export function desktopExtensionRoots(opts) {
+    const folder = "Claude Extensions";
+    if (opts.platform === "darwin")
+        return [path.join(opts.home, "Library", "Application Support", "Claude", folder)];
+    if (opts.platform === "win32") {
+        const roots = [];
+        const appData = opts.env.APPDATA?.trim() || path.join(opts.home, "AppData", "Roaming");
+        roots.push(path.join(appData, "Claude", folder));
+        // The Microsoft Store build keeps its data in its package's own folder,
+        // named after the package with a publisher suffix.
+        const packages = path.join(opts.env.LOCALAPPDATA?.trim() || path.join(opts.home, "AppData", "Local"), "Packages");
+        for (const entry of readDirNames(packages)) {
+            if (/^Claude_/i.test(entry))
+                roots.push(path.join(packages, entry, "LocalCache", "Roaming", "Claude", folder));
+        }
+        return roots;
+    }
+    return [path.join(opts.env.XDG_CONFIG_HOME?.trim() || path.join(opts.home, ".config"), "Claude", folder)];
+}
+/** The names in a folder, or none when the folder does not exist or cannot be listed. */
+function readDirNames(dir) {
+    try {
+        return fs.readdirSync(dir);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT" || code === "ENOTDIR" || code === "EACCES" || code === "EPERM")
+            return [];
+        throw err;
+    }
+}
+function readJson(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch (err) {
+        // No such file, or a plain file where a folder was expected (a .DS_Store among the extension folders).
+        const code = err.code;
+        if (code === "ENOENT" || code === "ENOTDIR" || code === "EACCES" || code === "EPERM")
+            return null;
+        throw err;
+    }
+    try {
+        const value = JSON.parse(text);
+        return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+    }
+    catch {
+        // A manifest that is not JSON is not one this function can vouch for; another extension's broken file is not ours to report.
+        return null;
+    }
+}
+/**
+ * The SceneScout desktop extension under any of `roots`, or null.
+ *
+ * Extensions are matched by the `name` in their manifest.json, not by folder
+ * name: Claude Desktop names the folder after an id it derives itself.
+ */
+export function findDesktopExtension(roots) {
+    for (const root of roots) {
+        for (const name of readDirNames(root).sort()) {
+            const dir = path.join(root, name);
+            const manifest = readJson(path.join(dir, "manifest.json"));
+            if (manifest?.name !== DESKTOP_EXTENSION_NAME)
+                continue;
+            const server = manifest.server;
+            const entry = typeof server?.entry_point === "string" ? path.join(dir, server.entry_point) : null;
+            const browsers = readJson(path.join(dir, "node_modules", "playwright-core", "browsers.json"))?.browsers;
+            const shell = Array.isArray(browsers)
+                ? browsers.find((b) => b?.name === "chromium-headless-shell")
+                : undefined;
+            return {
+                dir,
+                version: typeof manifest.version === "string" ? manifest.version : null,
+                entry,
+                entryPresent: entry !== null && fs.existsSync(entry),
+                headlessShellRevision: typeof shell?.revision === "string" && /^\d+$/.test(shell.revision) ? shell.revision : null,
+            };
+        }
+    }
+    return null;
+}
+/** The check doctor reports, passing, when only the desktop extension is set up and Claude Code's skill and registration are not needed. */
+export const CLAUDE_CODE_NOT_NEEDED = "Claude Code setup";
+/** What doctor says about a desktop extension install. */
+function desktopExtensionChecks(extension, ownShellDir, ownVersion) {
+    const reinstall = "in Claude Desktop, remove SceneScout under Settings > Extensions, then install the .mcpb file from the latest release again";
+    const label = `SceneScout ${extension.version ?? "(no version in its manifest)"}`;
+    const checks = [
+        {
+            name: "desktop extension installed",
+            ok: extension.entryPresent,
+            detail: extension.entryPresent
+                ? `${label} in Claude Desktop: ${extension.dir}`
+                : `${label} in Claude Desktop, but its server is missing: ${extension.entry ?? "the manifest names none"}`,
+            fix: reinstall,
+        },
+    ];
+    // The browser check above is for this copy's Playwright. The extension's may
+    // launch another revision, downloaded into its own folder beside this one.
+    if (extension.headlessShellRevision && ownShellDir) {
+        const dir = path.join(path.dirname(ownShellDir), `chromium_headless_shell-${extension.headlessShellRevision}`);
+        if (!samePath(dir, ownShellDir)) {
+            const present = fs.existsSync(path.join(dir, "INSTALLATION_COMPLETE"));
+            const byHand = extension.version ? `npx -y scenescout@${extension.version} install --browser-only` : "npx -y scenescout install --browser-only";
+            const onFirstUse = !present && atLeastVersion(extension.version, ownVersion);
+            checks.push({
+                name: "browser downloaded (desktop extension)",
+                // An extension that downloads its own browser on its first test is ready to use without it.
+                ok: present || onFirstUse,
+                detail: present
+                    ? dir
+                    : onFirstUse
+                        ? `not yet: the test browser downloads on first use (one-time, about ${APPROX_DISK_MB["chromium-headless-shell"]} MB). To have it ready now: ${byHand}`
+                        : `the extension launches another Chromium build than this copy, and it is not at ${dir}`,
+                fix: byHand,
+            });
+        }
+    }
+    return checks;
+}
+/** Whether version `a` (x.y.z) is at least `b`. False when either is missing or not of that shape, so an unknown version is never assumed to be new. */
+export function atLeastVersion(a, b) {
+    const parse = (v) => {
+        const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v?.trim() ?? "");
+        return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+    };
+    const x = parse(a);
+    const y = parse(b);
+    if (!x || !y)
+        return false;
+    for (let i = 0; i < 3; i++)
+        if (x[i] !== y[i])
+            return x[i] > y[i];
+    return true;
+}
+/** The last thing `install` prints when every step worked. */
+export function installClosing(opts) {
+    // A plugin install, or a browser download for a server already set up. A
+    // plugin's tools appear in a chat started after it was installed; in a chat
+    // that already has them, asking again is enough.
+    if (opts.browserOnly)
+        return "The browser is ready. Start a new chat to use SceneScout.\n(If SceneScout asked you for this download in a chat it already works in, ask it to try again there.)";
+    if (opts.forClaude)
+        return "Start a new chat in Claude Code to use SceneScout. In any project, run:  /scenescout";
+    return null;
+}
+/** The line doctor ends on when every check passed. */
+export function doctorAllGood(opts) {
+    if (opts.desktopOnly)
+        return "All good. In Claude Desktop, start a new chat and ask:  Use SceneScout to test http://localhost:3000";
+    if (opts.engineOnly)
+        return "All good. Ask your agent:  Use SceneScout to test http://localhost:3000";
+    return "All good. In any project, run:  /scenescout   (or ask: Use SceneScout to test http://localhost:3000)";
+}

package/dist/intake.js

@@ -0,0 +1,104 @@
+/**
+ * The questions a run starts with when the person gave no settings.
+ *
+ * Someone who is not a developer should not have to know what "observe" or a
+ * storage state is. When the skill is invoked with none of its flags, the agent
+ * asks four plain questions instead, and each answer chooses a setting: the
+ * address chooses the URL, the sign-in answer chooses whether to call
+ * scout_login and attach by role, what to check chooses the objective (and, for
+ * tickets, the criteria scout_tickets reads so the report answers each), and real
+ * data chooses the write mode. A developer who passes flags is asked nothing.
+ *
+ * The skill (skills/scenescout/SKILL.md) states the same questions and the same
+ * mapping in words; guide-test holds that text to this module, so the two
+ * cannot drift. The `explore` prompt asks them through `introQuestions`.
+ */
+/** The flags the skill reads. Any one given means the person chose settings themselves. */
+export const SKILL_FLAGS = ["url", "role", "focus", "level", "observe", "read-only", "safe-write", "allow-destructive"];
+export const INTAKE_QUESTIONS = [
+    { id: "address", ask: "What is the address of the site?", sets: "url", flags: ["url"] },
+    {
+        id: "sign-in",
+        ask: "Do you need to sign in to use it? If so, how: Google or Microsoft single sign-on, an email and password, or a one-time code?",
+        sets: "role",
+        flags: ["role"],
+    },
+    {
+        id: "what-to-check",
+        ask: 'What should I check? Upload or paste the tickets, or describe it in a sentence. Say "everything" to look at the whole site.',
+        sets: "objective",
+        flags: ["focus", "level"],
+    },
+    {
+        id: "real-data",
+        ask: "Does the site hold real data, such as real customers, orders or records?",
+        sets: "mode",
+        flags: ["observe", "read-only", "safe-write", "allow-destructive"],
+    },
+];
+/** The skill's flags present in what the person typed after the command, in the order SKILL_FLAGS lists them. */
+export function flagsGiven(argumentText) {
+    const seen = new Set();
+    // A flag is `--name` standing alone or followed by `=` or a space; `--urlx` and a word inside a value are not flags.
+    for (const m of argumentText.matchAll(/(?<![\w-])--([a-z][a-z-]*)(?![\w-])/g))
+        seen.add(m[1]);
+    return SKILL_FLAGS.filter((f) => seen.has(f));
+}
+/**
+ * The questions to ask before setup. None when any flag was given: a person who
+ * passes flags has chosen settings, and what they left out takes its default.
+ */
+export function questionsToAsk(argumentText) {
+    return flagsGiven(argumentText).length > 0 ? [] : [...INTAKE_QUESTIONS];
+}
+/** The role a plain-question run saves its sign-in under; any later run that asks for it reuses that login. */
+export const INTAKE_ROLE = "user";
+/** What a sign-in answer tells the person before the window opens. */
+export const SIGN_IN_HINT = {
+    sso: "sign in with Google or Microsoft as you normally would",
+    password: "sign in with your email and password as you normally would",
+    "one-time-code": "sign in as you normally would and enter the code when it arrives",
+};
+/**
+ * The settings the four answers choose. Real data, or an answer that is not
+ * sure, is observe: nothing but GET requests leaves the page. Only a plain no
+ * allows read-only, and plain answers never reach safe-write or destructive,
+ * which need the person to ask for them by name.
+ */
+export function settingsFromAnswers(a) {
+    const url = a.address.trim();
+    if (!url)
+        throw new Error("the address is empty: ask for it again before attaching");
+    const mode = a.realData === "no" ? "read-only" : "observe";
+    const login = a.signIn === "none" ? null : { tool: "scout_login", url, role: INTAKE_ROLE, tellUser: `A browser window will open: ${SIGN_IN_HINT[a.signIn]}.` };
+    let objective = "Explore the whole site";
+    let focus;
+    let readTickets;
+    if (a.whatToCheck !== "everything") {
+        if ("tickets" in a.whatToCheck) {
+            const tickets = a.whatToCheck.tickets.map((t) => t.trim()).filter(Boolean);
+            if (tickets.length === 0)
+                throw new Error("no tickets were given: ask what to check again, or explore the whole site");
+            focus = tickets.join("; ");
+            objective = `Check the tickets: ${focus}`;
+            // A rule between them, so each one given is read as its own ticket.
+            readTickets = { tool: "scout_tickets", text: tickets.join("\n\n---\n\n") };
+        }
+        else {
+            focus = a.whatToCheck.description.trim();
+            if (!focus)
+                throw new Error("the description is empty: ask what to check again, or explore the whole site");
+            objective = focus;
+        }
+    }
+    return {
+        login,
+        attach: { url, mode, ...(login ? { role: login.role } : {}), objective },
+        ...(focus ? { focus } : {}),
+        ...(readTickets ? { readTickets } : {}),
+    };
+}
+/** The questions as a numbered list, the way the explore prompt and the skill put them. */
+export function introQuestions() {
+    return INTAKE_QUESTIONS.map((q, i) => `${i + 1}. ${q.ask}`).join("\n");
+}