scenescout 3.14.0 → 3.15.0

package/dist/cli.js

@@ -2,6 +2,7 @@
 /**
  * SceneScout CLI.
  *
+ *   scenescout <url>                A first look with no setup: observe mode, capped, never a gate
  *   scenescout scan <projectPath>   Print project discovery results
  *   scenescout serve                Run the MCP server on stdio
  *   scenescout install              Install the skill, download the browser, register the MCP server
@@ -20,15 +21,17 @@ import { APPROX_DISK_MB, BROWSER_ENGINES, browserPresence, defaultAttachNote, de
 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 { defaultCheckDir, readCheckInputs, runCheck } from "./check-run.js";
-import { httpClient, runCi } from "./ci-run.js";
+import { httpClient, httpJudgeAsk, runCi } from "./ci-run.js";
 import { runLogin, runScriptedLogin, savedLine } from "./login-run.js";
 import { credentialRedactor, LOGIN_ENV, readScriptedLogin } from "./engine/scripted-login.js";
 import { parseLoginArgs } from "./engine/profiles.js";
-import { detectProvider, EXIT_CI, KEY_ENV, parseCiArgs, redactKeys, secretValues } from "./engine/ci.js";
-import { EXIT, exitCodeOf, formatCheck, parseCheckArgs, refusedFlowReason, toSarif, toSummaryJson, unmeasuredReason } from "./engine/check.js";
+import { detectProvider, EXIT_CI, judgeEffort, KEY_ENV, parseCiArgs, redactKeys, secretValues } from "./engine/ci.js";
+import { EXIT, exitCodeOf, formatCheck, parseCheckArgs, refusedFlowReason, toSarif, toSummaryJson, unmeasuredReason, } from "./engine/check.js";
+import { downloadLine, EXIT_FIRST_RUN, FIRST_RUN_DIRNAME, firstRunCheckOptions, firstRunDownloads, firstRunSummary, formatFirstRun, modeSentence, parseFirstRunArgs, reportFolderProblem, unreachableReason, writeFirstRunReport, } from "./first-run.js";
 import { LEGACY_MEMORY_DIRNAME, MEMORY_DIRNAME, writeSelfIgnore } from "./engine/memory.js";
 import { formatStatus, liveEngines, liveTokenFileName, localClock, LIVE_TOKEN_FILE, pidAlive, watchTarget, wholeSessions, } from "./engine/live.js";
 import { formatScan, scanProject } from "./scan.js";
+import { dispatch } from "./commands.js";
 const here = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(here, "..");
 /** This package's version, as published. */
@@ -40,6 +43,18 @@ function usage(exitCode = 1) {
     console.log(`SceneScout ${packageVersion()} — AI exploratory UI testing engine (MCP)
 
 Usage:
+  scenescout <url> [options]        A first look, with no setup: visits the app's pages and measures them (no
+                                    model, no API key), writes ${FIRST_RUN_DIRNAME}/ in this folder and prints
+                                    the three issues to look at first. Downloads Chromium if it is missing and
+                                    changes nothing else: no skill, no MCP registration, nothing on PATH.
+                                    The address comes first, its options after it.
+                                    (--max-routes N (default 20), --max-minutes N (default 3): no page is started
+                                     past either; --mode observe|read-only (default observe: nothing but reads
+                                     leaves the page, sign-in and token refresh apart; read-only lets a plain POST
+                                     through); --out dir: where the report goes. ${FIRST_RUN_DIRNAME}/ is written
+                                     only when it is new, empty or an earlier first look's)
+                                    Exit code: 0 it looked, whatever it found; 2 could not run (the URL could
+                                    not be reached, a bad argument, no browser) or could not write the report.
   scenescout scan <projectPath>     Discover framework, routes, auth states
   scenescout serve                  Run the MCP server (stdio)
   scenescout install                One-step setup: skill + Chromium + MCP registration
@@ -95,7 +110,11 @@ Usage:
                                      --project dir (default: here); --out dir (default: .scenescout/ci);
                                      --show "the Save button": instead of exploring, capture that element as a PNG
                                       under shots/; --compare-url https://…: with --show, capture it there too and
-                                      write a diff picture)
+                                      write a diff picture;
+                                     --dedup judge|rule: judge (default) also asks the run's model, at its lowest
+                                      effort, whether a filed finding the rule keeps apart is one already on its
+                                      page (titles, categories, evidence and the page's path are sent);
+                                      rule asks nothing)
                                     Exit code: 0 the run ran (findings never change it), 2 could not run.
   scenescout login <url> --role <name>
                                     Open a visible browser at the URL, sign in there (SSO, MFA, anything), then
@@ -107,7 +126,9 @@ Usage:
   scenescout login <url> --role <name> --script
                                     For CI: sign in headless from SCENESCOUT_LOGIN_USERNAME, SCENESCOUT_LOGIN_PASSWORD
                                     and, if the form asks for a code, SCENESCOUT_LOGIN_TOTP_SECRET (base32 or an
-                                    otpauth:// URI), then save the profile as above. A test user only. No value
+                                    otpauth:// URI) or SCENESCOUT_LOGIN_OTP_CODE (a fixed code a test environment
+                                    accepts), then save the profile as above. With a code and no password, a
+                                    passwordless sign-in (the username, then the code). A test user only. No value
                                     is ever printed. Exit 0 signed in and saved, 1 not.
                                     (--success-url text|url; --success-selector css; --username-selector,
                                     --password-selector, --otp-selector, --submit-selector css; each of these also
@@ -295,13 +316,6 @@ function flagValue(flags, name) {
     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"];
@@ -349,7 +363,7 @@ async function install(flags) {
     // only thing it cannot bring is the browser download.
     const browserOnly = flags.includes("--browser-only");
     // Read the choice before doing anything, so a typo costs nothing.
-    const selection = parseBrowserSelection(browsersFlag(flags));
+    const selection = parseBrowserSelection(flagValue(flags, "--browsers"));
     if ("error" in selection)
         throw new Error(selection.error);
     const chosen = parseClients(flagValues(flags, ["--client", "--clients"]));
@@ -520,8 +534,6 @@ async function doctor(flags) {
 }
 /** `scenescout check`: exit 0 passed, 1 failed the gate, 2 could not run. */
 async function check(args) {
-    if (args.includes("--help") || args.includes("-h"))
-        usage(0);
     const parsed = parseCheckArgs(args, process.cwd());
     if (!parsed.ok) {
         console.error(`scenescout check: ${parsed.error}`);
@@ -582,10 +594,92 @@ async function check(args) {
         console.error(`scenescout check: could not run a saved flow: ${refused}`);
     process.exit(exitCodeOf(result));
 }
+/** `scenescout <url>`: a first look. Exit 0 once it has looked, whatever it found; 2 when it could not look or could not write its report. */
+async function firstRun(args) {
+    const fail = (message) => {
+        console.error(`scenescout: ${message}`);
+        process.exit(EXIT_FIRST_RUN.couldNotRun);
+    };
+    const parsed = parseFirstRunArgs(args, process.cwd());
+    if (!parsed.ok)
+        return fail(parsed.error);
+    const options = parsed.options;
+    // Found out now, not after the look; and nothing is created until the look has something to write.
+    const folderProblem = reportFolderProblem(options.outDir ?? path.join(process.cwd(), FIRST_RUN_DIRNAME), options.outDir !== undefined);
+    if (folderProblem)
+        return fail(folderProblem);
+    console.log(`SceneScout ${packageVersion()} — a first look at ${options.url}`);
+    console.log(`It opens pages and measures them and submits no form: up to ${options.maxRoutes} pages, starting none after ${options.maxMinutes} minute(s). No model, no API key.`);
+    console.log(modeSentence(options.mode));
+    // Only the build a headless Chromium launch needs. Nothing else install does happens here: no skill, no registration, nothing on PATH.
+    const downloads = firstRunDownloads(await presentBrowsers());
+    if (downloads.length > 0) {
+        console.log(downloadLine(downloads));
+        const began = Date.now();
+        if (!downloadBrowsers(downloads)) {
+            return fail(`Chromium could not be downloaded. Check the network or proxy and run this again, or download it by hand: npx playwright install ${downloads.join(" ")}`);
+        }
+        // The installer's exit code is not the build: look again before saying it is there.
+        const still = firstRunDownloads(await presentBrowsers());
+        if (still.length > 0)
+            return fail(`the download finished, but ${still.join(", ")} is still not where Playwright looks for it. Run: npx playwright install ${still.join(" ")}`);
+        console.log(`✓ Chromium downloaded in ${Math.round((Date.now() - began) / 1000)} s.`);
+    }
+    // An empty project of its own: nothing is read from, or written to, the folder this runs in except the report.
+    const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), "scenescout-first-run-"));
+    // Also on an exit the finally below never reaches, such as Ctrl+C, which the browser's driver answers with process.exit.
+    const removeProject = () => fs.rmSync(projectDir, { recursive: true, force: true });
+    process.once("exit", removeProject);
+    const began = Date.now();
+    let result;
+    let error = "";
+    try {
+        console.log(`\nLooking at ${options.url} …`);
+        result = await runCheck(firstRunCheckOptions(options, projectDir), (line) => console.log(line));
+    }
+    catch (err) {
+        error = err instanceof Error ? err.message : String(err);
+    }
+    finally {
+        process.off("exit", removeProject);
+        removeProject();
+    }
+    if (!result)
+        return fail(`could not run: ${error}`);
+    const unreachable = unreachableReason(result.routes);
+    if (unreachable)
+        return fail(`could not reach ${options.url}: ${unreachable}`);
+    const facts = { result, options, elapsedMs: Date.now() - began };
+    const files = {
+        "report.md": formatFirstRun(facts),
+        "check.json": JSON.stringify(toSummaryJson(result, packageVersion()), null, 2) + "\n",
+    };
+    // The look is done whatever happens to the files: its summary is printed either way.
+    let written;
+    let notWritten = "";
+    try {
+        written = writeFirstRunReport(files, { cwd: process.cwd(), tmpdir: os.tmpdir(), outDir: options.outDir });
+    }
+    catch (err) {
+        notWritten = err instanceof Error ? err.message : String(err);
+    }
+    if (written?.note)
+        console.log(written.note);
+    let where = `not written: ${notWritten}`;
+    if (written) {
+        const report = path.join(written.dir, "report.md");
+        const relative = path.relative(process.cwd(), report);
+        where = relative.startsWith("..") || path.isAbsolute(relative) ? report : relative;
+    }
+    console.log("");
+    for (const line of firstRunSummary(facts, where))
+        console.log(line);
+    if (!written)
+        return fail(`could not write the report: ${notWritten}`);
+    process.exit(EXIT_FIRST_RUN.ran);
+}
 /** `scenescout ci`: exit 0 when the run ran, 2 when it could not. Findings never change the exit code. */
 async function ci(args) {
-    if (args.includes("--help") || args.includes("-h"))
-        usage(0);
     const secrets = secretValues(process.env);
     const say = (line) => console.log(redactKeys(line, secrets));
     const fail = (message) => {
@@ -601,11 +695,15 @@ async function ci(args) {
         return fail(provider.error);
     const resolved = provider.resolved;
     const key = (process.env[KEY_ENV[resolved.provider]] ?? "").trim();
-    say(`Exploring ${options.url} with ${resolved.provider} ${resolved.model} (effort ${resolved.effort}), ${options.mode} mode, level ${options.level} …`);
+    // The dedup judge asks the run's model at the lowest effort its API takes; --dedup rule asks nothing.
+    const judge = options.dedup === "judge" && !options.show ? { ...resolved, effort: judgeEffort(resolved.provider) } : null;
+    say(`Exploring ${options.url} with ${resolved.provider} ${resolved.model} (effort ${resolved.effort}), ${options.mode} mode, level ${options.level}` +
+        `${judge ? `, duplicates judged by the model at effort ${judge.effort}` : ""} …`);
     let run;
     try {
         run = await runCi(options, resolved, {
             makeClient: (system, tools, kickoff) => httpClient(resolved, key, system, tools, kickoff),
+            ...(judge ? { judge: httpJudgeAsk(judge, key), judgeEffort: judge.effort } : {}),
             log: say,
             secrets,
             version: packageVersion(),
@@ -627,8 +725,6 @@ async function ci(args) {
 }
 /** `scenescout login`: exit 0 saved, 1 nothing saved. */
 async function login(args) {
-    if (args.includes("--help") || args.includes("-h"))
-        usage(0);
     const parsed = parseLoginArgs(args, process.cwd());
     if (!parsed.ok) {
         console.error(`scenescout login: ${parsed.error}`);
@@ -672,61 +768,40 @@ const [, , command, ...args] = process.argv;
 // 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": {
-            console.log(packageVersion());
-            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 "check": {
-            await check(args);
-            break;
-        }
-        case "ci": {
-            await ci(args);
-            break;
-        }
-        case "login": {
-            await login(args);
-            break;
-        }
-        case "status": {
-            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();
-    }
+    await dispatch(command, args, {
+        usage,
+        version: () => console.log(packageVersion()),
+        refuse: (message) => {
+            console.error(`scenescout ${command}: ${message}`);
+            console.error("Run `scenescout --help` for the options.");
+            process.exit(1);
+        },
+        commands: {
+            scan: (a) => {
+                if (!a[0])
+                    usage();
+                console.log(formatScan(scanProject(a[0])));
+            },
+            serve: async () => {
+                await import("./mcp-server.js");
+            },
+            install,
+            doctor,
+            check,
+            ci,
+            login,
+            status: (a) => status(path.resolve(a[0] ?? process.cwd())),
+            watch: (a) => {
+                const positional = a.filter((x) => !x.startsWith("--"));
+                watch(path.resolve(positional[0] ?? process.cwd()), !a.includes("--no-open"));
+            },
+        },
+        // Anything unforeseen is still "could not run" (2), not the exit 1 the other commands share below.
+        firstRun: (a) => firstRun(a).catch((err) => {
+            console.error(`scenescout: could not run: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(EXIT_FIRST_RUN.couldNotRun);
+        }),
+    });
 }
 catch (err) {
     console.error(`scenescout ${command ?? ""}: ${err instanceof Error ? err.message : String(err)}`);

package/dist/commands.js

@@ -0,0 +1,141 @@
+/**
+ * How the CLI decides what a command line asks for, before any command runs.
+ *
+ * It lives apart from cli.ts so it can be table-tested: `scenescout install
+ * --help` once ran a real install, because install read only the flags it knew
+ * and ignored the rest. Every subcommand now answers `--help` / `-h` with the
+ * usage text and exit 0 before it does anything, and a command that parses its
+ * own flags by hand refuses one it does not know.
+ *
+ * A first argument that is an address instead of a subcommand is a first run,
+ * `scenescout <url>` (first-run.ts), which parses its own options.
+ */
+const HANDLERS_OF = {
+    scan: true,
+    serve: true,
+    install: true,
+    doctor: true,
+    check: true,
+    ci: true,
+    login: true,
+    status: true,
+    watch: true,
+};
+export const SUBCOMMANDS = Object.keys(HANDLERS_OF);
+/**
+ * Commands that read their arguments by hand. `check`, `ci` and `login` are
+ * absent: their own parsers refuse unknown options. `serve` is absent on
+ * purpose: it is the line an MCP client launches, and a stray argument there
+ * should not stop the server from starting.
+ */
+export const HAND_PARSED = {
+    install: {
+        switches: ["--skip-browser", "--no-register", "--no-command", "--browser-only"],
+        valued: ["--browsers", "--client", "--clients"],
+        // `--browser` is what `check` and `login` call it; for install it would otherwise download Chromium regardless.
+        hints: { "--browser": "--browsers" },
+        positional: 0,
+    },
+    doctor: { switches: ["--engine"], valued: [], positional: 0 },
+    scan: { switches: [], valued: [], positional: 1 },
+    status: { switches: [], valued: [], positional: 1 },
+    watch: { switches: ["--no-open"], valued: [], positional: 1 },
+};
+/** True when the arguments ask for help. */
+export function wantsHelp(args) {
+    return args.includes("--help") || args.includes("-h");
+}
+/** The first argument `spec` does not accept, as an error sentence; null when every one is accepted. */
+export function unknownArgument(args, spec) {
+    let positional = 0;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg.startsWith("-") || arg === "-") {
+            if (++positional > spec.positional)
+                return `unexpected argument ${arg}`;
+            continue;
+        }
+        const name = arg.split("=")[0];
+        if (spec.valued.includes(name)) {
+            // The value after a valued flag is not itself a flag, even when it starts with a dash.
+            if (!arg.includes("="))
+                i++;
+            continue;
+        }
+        if (spec.switches.includes(name) && !arg.includes("="))
+            continue;
+        const hint = spec.hints?.[name];
+        return `unknown option ${name}${hint ? ` — did you mean ${hint}?` : ""}`;
+    }
+    return null;
+}
+/** Whether `command` names a subcommand. */
+export function isSubcommand(command) {
+    return command !== undefined && Object.hasOwn(HANDLERS_OF, command);
+}
+/** A host with no scheme: a name or address, an optional port, then optionally a path, query or fragment. */
+const BARE_HOST = /^(?:\[[0-9a-f:.]+\]|[a-z0-9-]+(?:\.[a-z0-9-]+)*)(?::\d{1,5})?(?:[/?#].*)?$/i;
+/** Whether an argument starts with a scheme, such as `http://`. */
+export function hasScheme(arg) {
+    return /^[a-z][a-z0-9+.-]*:\/\//i.test(arg);
+}
+/** The host part of an address written without its scheme: everything before its path, query or fragment. */
+export function hostOf(arg) {
+    return arg.split(/[/?#]/)[0];
+}
+/**
+ * Whether the first argument is an address, which makes the command line a
+ * first run (`scenescout <url>`): it has a scheme (`http://…`, and `ftp://…`,
+ * which the first run then refuses with a reason), or it reads as a host
+ * without one (`localhost:3000`, `example.com/app`), which the first run asks
+ * to be written in full. Subcommands are settled first, and a word that is
+ * neither (`instal`) still gets the usage.
+ */
+export function looksLikeUrl(arg) {
+    if (!arg || arg.startsWith("-"))
+        return false;
+    if (hasScheme(arg))
+        return true;
+    if (!BARE_HOST.test(arg))
+        return false;
+    const host = hostOf(arg);
+    return host.includes(".") || host.includes(":") || host.toLowerCase() === "localhost";
+}
+/** Settle help and flag errors for a subcommand before its handler is reached. */
+export function preflight(command, args) {
+    if (wantsHelp(args))
+        return { kind: "help" };
+    const spec = Object.hasOwn(HAND_PARSED, command) ? HAND_PARSED[command] : undefined;
+    const problem = spec ? unknownArgument(args, spec) : null;
+    return problem ? { kind: "error", message: problem } : { kind: "run" };
+}
+/**
+ * Run the command line: help and flag errors are settled here, so a subcommand's
+ * handler is reached only when it is actually meant to run.
+ */
+export async function dispatch(command, args, h) {
+    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":
+            return h.usage(0);
+        case "--version":
+        case "-v":
+            return h.version();
+    }
+    if (!isSubcommand(command)) {
+        if (!looksLikeUrl(command))
+            return h.usage(1);
+        // Its own parser refuses an option it does not know, with the first run's exit code, as check's does.
+        if (wantsHelp(args))
+            return h.usage(0);
+        return h.firstRun([command, ...args]);
+    }
+    const verdict = preflight(command, args);
+    if (verdict.kind === "help")
+        return h.usage(0);
+    if (verdict.kind === "error")
+        return h.refuse(verdict.message);
+    await h.commands[command](args);
+}