scenescout 1.0.0

package/dist/cli.js

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+/**
+ * SceneScout CLI.
+ *
+ *   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 doctor               Check every piece of the setup and say how to fix what is missing
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+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 { LEGACY_MEMORY_DIRNAME, MEMORY_DIRNAME } from "./engine/memory.js";
+import { formatScan, scanProject } from "./scan.js";
+const here = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(here, "..");
+function usage(exitCode = 1) {
+    console.log(`SceneScout — AI exploratory UI testing engine (MCP)
+
+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)
+  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)
+`);
+    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]
+        .map((name) => path.join(projectPath, name))
+        .find((candidate) => fs.existsSync(path.join(candidate, "status.json"))) ?? path.join(projectPath, MEMORY_DIRNAME);
+    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;
+    try {
+        st = 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;
+    }
+    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";
+        }
+    }
+    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}`);
+    // Recent actions from the newest session log — the "what has it been doing" trail.
+    const logs = fs.existsSync(dir)
+        ? fs
+            .readdirSync(dir)
+            .filter((f) => f.startsWith("session-") && f.endsWith(".jsonl"))
+            .sort()
+        : [];
+    const newest = logs[logs.length - 1];
+    if (newest) {
+        // Tail-read: the action log grows by one line per engine action (MBs on a
+        // long run) and status is a poll target — read only the final chunk.
+        const logPath = path.join(dir, newest);
+        const size = fs.statSync(logPath).size;
+        const buf = Buffer.alloc(Math.min(16384, size));
+        const fd = fs.openSync(logPath, "r");
+        fs.readSync(fd, buf, 0, buf.length, Math.max(0, size - buf.length));
+        fs.closeSync(fd);
+        const raw = buf.toString("utf8");
+        // When the chunk starts mid-file, the first line is probably partial — drop it.
+        const text = size > buf.length ? raw.slice(raw.indexOf("\n") + 1) : raw;
+        const lines = text.trim().split("\n").slice(-8);
+        console.log(`\nRecent actions (${newest}):`);
+        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}`);
+            }
+            catch {
+                /* skip malformed line */
+            }
+        }
+    }
+}
+/** Where Playwright expects its Chromium build; null when playwright cannot say. */
+async function chromiumPath() {
+    try {
+        const { chromium } = await import("playwright");
+        return chromium.executablePath() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Download Chromium through the playwright CLI that ships with our own dependency. */
+function downloadChromium() {
+    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" });
+    return r.status === 0;
+}
+async function install(flags) {
+    const serverPath = path.join(packageRoot, "dist", "mcp-server.js");
+    if (!fs.existsSync(serverPath)) {
+        throw new Error(`${serverPath} is missing — run \`npm run build\` first.`);
+    }
+    // A step that fails is reported AND fails the command: `setup && next-step`
+    // must not carry on past a missing browser or an unregistered server.
+    let failed = false;
+    // 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) {
+        const skill = installSkill({ packageRoot, claudeDir: resolveClaudeDir(process.env, os.homedir()) });
+        for (const note of skill.notes)
+            console.log(`· ${note}`);
+        console.log(skill.mode === "symlink"
+            ? `✓ Skill installed (symlink): ${skill.dest} → ${skill.src}`
+            : `✓ Skill installed (copy): ${skill.dest} — re-run install after upgrading SceneScout.`);
+    }
+    if (flags.includes("--skip-browser")) {
+        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.");
+            else {
+                failed = true;
+                console.log("✗ Chromium download failed — run `npx playwright install chromium` and check your network/proxy.");
+            }
+        }
+    }
+    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`);
+    }
+    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}`);
+        }
+        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`);
+        }
+    }
+    if (failed) {
+        console.log("\nSetup is incomplete — fix the lines marked ✗ or · above, then run:  npm run doctor");
+        process.exitCode = 1;
+        return;
+    }
+    if (browserOnly) {
+        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");
+}
+async function doctor(flags) {
+    const checks = diagnose({
+        scope: flags.includes("--engine") ? "engine" : "claude-code",
+        packageRoot,
+        claudeDir: resolveClaudeDir(process.env, os.homedir()),
+        nodeVersion: process.version,
+        chromiumPath: await chromiumPath(),
+        run: spawnRunner,
+    });
+    for (const c of checks) {
+        console.log(`${c.ok ? "✓" : "✗"} ${c.name} — ${c.detail}`);
+        if (!c.ok && c.fix)
+            console.log(`    fix: ${c.fix}`);
+    }
+    if (checks.some((c) => !c.ok))
+        process.exit(1);
+    console.log("\nAll good. In any project, run:  /scenescout");
+}
+const [, , command, ...args] = process.argv;
+// A CLI's failure mode should be a sentence, not a stack trace. `scan` on a
+// path that does not exist and `status` on a half-written status.json both
+// throw ordinary Errors; unguarded, they printed a V8 trace that buries the
+// one line the user needs. `serve` is deliberately outside this: it hands off
+// to the MCP server, whose own transport owns error reporting from then on.
+try {
+    switch (command) {
+        // Asking for help is not an error; scripts and shells treat a non-zero
+        // exit as one.
+        case "--help":
+        case "-h":
+        case "help":
+            usage(0);
+        case "--version":
+        case "-v": {
+            const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+            console.log(pkg.version);
+            break;
+        }
+        case "scan": {
+            const target = args[0];
+            if (!target)
+                usage();
+            console.log(formatScan(scanProject(target)));
+            break;
+        }
+        case "serve": {
+            await import("./mcp-server.js");
+            break;
+        }
+        case "install": {
+            await install(args);
+            break;
+        }
+        case "doctor": {
+            await doctor(args);
+            break;
+        }
+        case "status": {
+            status(path.resolve(args[0] ?? process.cwd()));
+            break;
+        }
+        default:
+            usage();
+    }
+}
+catch (err) {
+    console.error(`scenescout ${command ?? ""}: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+}

package/dist/engine/authloss.js

@@ -0,0 +1,125 @@
+/**
+ * Auth-loss detection: telling "this role may not see that page" apart from
+ * "our credentials died and nothing since is meaningful".
+ *
+ * Extracted from browser.ts because it is a small state machine with real
+ * invariants — a streak, a once-only explanatory tail, a single-consumption
+ * notice buffer — that was previously inline in a 2300-line class and reachable
+ * only by driving a whole browser. Three separate bugs landed in it there
+ * (a bounce judged before the page settled, a notice lost whenever the
+ * surrounding call threw, and that same notice then leaking onto the NEXT
+ * call's result). All three are cheap to pin once the logic stands alone.
+ */
+/** Paths that look like a login/auth screen — the landing place of a dead session. */
+export const LOGIN_ROUTE_RE = /\/(login|signin|sign-in|auth)(\/|$)/;
+/** Consecutive login bounces before we stop assuming it is a permission wall. */
+export const AUTH_LOSS_STREAK = 3;
+export class AuthLossTracker {
+    /** Consecutive navigations that ended on a login page. */
+    streak = 0;
+    /** Set once the verdict has been delivered, so the long tail is added once. */
+    reported = false;
+    /** Notice for the in-flight call, consumed exactly once by take(). */
+    pending = "";
+    /**
+     * Did a navigation to `requested` end up on a login screen?
+     *
+     * Normalizes `requested` itself rather than trusting callers: crawl passes
+     * raw targets and tolerates slash-less paths, so an explicit crawl of
+     * "login" — the anonymous auth-surface pass — was scored as a bounce and fed
+     * the streak. Deliberately does not fire when the caller ASKED for the login
+     * page, whatever shape they asked in.
+     */
+    isLoginRedirect(requested, landedUrl, baseUrl) {
+        let landedPath;
+        try {
+            landedPath = new URL(landedUrl, baseUrl || "http://x").pathname;
+        }
+        catch {
+            return false;
+        }
+        const wanted = requested.startsWith("/") ? requested : `/${requested}`;
+        return LOGIN_ROUTE_RE.test(landedPath) && !LOGIN_ROUTE_RE.test(wanted);
+    }
+    /**
+     * Record one navigation's outcome and build the notice for it.
+     *
+     * `bounced` decides both the streak and whether the route counts as covered;
+     * the caller owns the memory writes, because ownership of the store belongs
+     * to the engine, not to this tracker.
+     */
+    record(opts) {
+        const { requestedRoute, landedRoute, bounced, role } = opts;
+        if (bounced)
+            this.streak += 1;
+        else
+            this.streak = 0;
+        const divergence = landedRoute === requestedRoute
+            ? ""
+            : `⚠ REDIRECTED: asked for ${requestedRoute}, landed on ${landedRoute}` +
+                (bounced
+                    ? ` — this is a login page, so the route is NOT counted as covered.`
+                    : ` — the app redirected; the route counts as covered for role '${role}'.`) +
+                `\n`;
+        this.pending = this.banner() + divergence;
+    }
+    /**
+     * The verdict, once the streak says the session is dead.
+     *
+     * One bounce is ordinary (a permission wall, a session that was never
+     * authenticated). Three in a row means the credentials this session attached
+     * with have expired, and every subsequent "OK" is a lie: the page rendered,
+     * the URL changed, and nothing that follows tests the app. This used to be
+     * invisible because the passive HTTP oracle rates 401 as `medium` and then
+     * collapses repeats to "nothing new" — the signal decayed exactly as the
+     * problem got worse.
+     */
+    banner() {
+        if (this.streak < AUTH_LOSS_STREAK)
+            return "";
+        const first = !this.reported;
+        this.reported = true;
+        return (`⚠ SESSION AUTH LOST — ${this.streak} consecutive navigations were redirected to a login page. ` +
+            `The credentials this session attached with have almost certainly expired. ` +
+            `Nothing tested past this point is meaningful: re-attach with a fresh storage state before continuing.` +
+            (first ? ` Routes bounced this way are recorded as NOT covered, so the completion contract still sees them as gaps.` : "") +
+            `\n`);
+    }
+    /**
+     * Take the pending notice, clearing it.
+     *
+     * Single-consumption matters: the notice describes ONE navigation. Left set,
+     * it prepended a stale "REDIRECTED: asked for X" to the next, unrelated call
+     * — which is what happened whenever the surrounding navigate() threw before
+     * reaching its return statement.
+     */
+    take() {
+        const out = this.pending;
+        this.pending = "";
+        return out;
+    }
+    /** Discard any un-consumed notice. Called before a navigation starts. */
+    clear() {
+        this.pending = "";
+    }
+    /**
+     * The verdict for a BATCH of navigations (a crawl), independent of how the
+     * last one happened to land.
+     *
+     * A crawl records every route in turn, so the per-route notice is overwritten
+     * on each iteration and only the final one survives to be taken. That loses
+     * the verdict in the ordinary mixed case: the token dies, forty routes bounce,
+     * and then the sweep reaches a genuinely public route — which resets the
+     * streak, so the last notice is empty and the crawl reports nothing wrong.
+     * Once the session has been declared dead, say so at the end of the batch
+     * whatever the final route did.
+     */
+    batchVerdict() {
+        if (!this.reported)
+            return "";
+        return (`⚠ SESSION AUTH LOST during this sweep — navigations were redirected to a login page. ` +
+            `The credentials this session attached with have almost certainly expired, so routes crawled after that ` +
+            `point tested a logged-out app. They are recorded as NOT covered; re-attach with a fresh storage state ` +
+            `and crawl again.\n`);
+    }
+}