scenescout 3.14.1 → 3.16.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
@@ -9,24 +10,30 @@
  *   scenescout check <url>          Visit every route, measure it, and pass or fail (no model involved)
  *   scenescout ci <url>             An exploratory run driven by a model's API, unattended, that reports
  *   scenescout login <url> --role r Sign in once in a visible browser and save it as a named role
+ *   scenescout export --to github   File the project's findings as GitHub or Jira issues, each once
  */
 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 { APPROX_DISK_MB, BROWSER_ENGINES, browserPresence, defaultAttachNote, defaultEngine, launchTarget, parseBrowserSelection, playwrightInstallArgs, } from "./browsers.js";
+import { APPROX_DISK_MB, defaultAttachNote, defaultEngine, launchTarget, parseBrowserSelection } 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 { defaultCheckDir, readCheckInputs, runCheck } from "./check-run.js";
-import { httpClient, runCi } from "./ci-run.js";
+import { CLAUDE_CODE_NOT_NEEDED, CLI_NAME, desktopExtensionRoots, diagnose, doctorAllGood, findDesktopExtension, installClosing, ensureCommand, findOnUserPath, installSkill, isEphemeralRoot, launchCommand, manualRegisterCommand, planCommand, registerMcp, resolveClaudeDir, spawnRunner, } from "./installer.js";
+import { downloadBrowsers, presentBrowsers } from "./installer.js";
+import { baselinesDirOf, defaultCheckDir, readCheckInputs, runCheck } from "./check-run.js";
+import { httpClient, httpJudgeAsk, runCi } from "./ci-run.js";
+import { runExport } from "./export-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 { VISUAL_DIRNAME } from "./engine/baseline.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 { credentialSecrets, EXIT_EXPORT, parseExportArgs } from "./engine/export.js";
 import { LEGACY_MEMORY_DIRNAME, MEMORY_DIRNAME, writeSelfIgnore } from "./engine/memory.js";
+import { sarifFilesFor } from "./engine/sarif.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";
@@ -41,6 +48,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
@@ -73,7 +92,19 @@ Usage:
                                      --on-refused-step report|stop: report (default) marks a flow whose step was
                                       refused "could not run", keeps every other verdict and exits 2; stop exits 2 there;
                                      --gate-retests never|high|all: which still-reproducing findings fail the gate
-                                      (default high: those filed high))
+                                      (default high: those filed high);
+                                     --baseline off|compare|update: compare each page or element listed in the
+                                      baselines' targets.json with its baseline picture, or write new baselines
+                                      (update; only when asked) (default off);
+                                     --baselines dir: where targets.json and the baselines are (default
+                                      .scenescout/baselines, which git ignores; name a folder you commit to share
+                                      them); --baseline-threshold N: the % of a picture's pixels that may change
+                                      before its baseline is not met; update rewrites those past it, and any taken
+                                      on another OS (default 0.1, so small anti-aliasing noise between machines
+                                      passes; 0 counts every changed pixel);
+                                     --sarif-file-anchor path: the repository file a SARIF result points at when
+                                      no saved flow raised it (default: the running workflow's file on GitHub
+                                      Actions, else package.json, else README.md))
                                     Exit code: 0 passed, 1 failed the gate, 2 could not run.
   scenescout ci <url>               An exploratory run with no person present: a model reached through its API
                                     drives the tools by the SceneScout method and the run ends in the report.
@@ -86,6 +117,8 @@ Usage:
                                      --max-turns N (default 40); --max-tokens N (default 1500000);
                                      --max-minutes N (default 20): the run stops at the first cap reached and still
                                       writes the report;
+                                     --lanes N (default 1, at most 8): split the app between N model loops that
+                                      explore at once, each in its own browser, sharing those caps;
                                      --price-in, --price-cached-in, --price-out: US dollars per million tokens,
                                       over the built-in prices, for the cost estimate of any model;
                                      --mode observe|read-only|safe-write|destructive (default read-only;
@@ -96,24 +129,61 @@ 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;
+                                     --sarif-file-anchor path: the repository file each SARIF result points at,
+                                      as for check)
                                     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
-                                    press Enter in this terminal to save the session as that role's profile, in
-                                    .scenescout/auth/<name>.json (owner-only; never printed, never committed).
-                                    Closing the window or Ctrl+C saves nothing. Agents then attach with
-                                    scout_attach { role: "<name>" }, as many sessions as they like from one login.
-                                    (--project dir (default: here); --browser chromium|firefox|webkit)
+                                    Open a visible browser at the URL and sign in there (SSO, MFA, anything). Once
+                                    you are back on the app with a new session, the window saves it as that role's
+                                    profile, in .scenescout/auth/<name>.json (owner-only; never printed, never
+                                    committed), and closes. Enter in this terminal saves at once. Closing the window
+                                    or Ctrl+C saves nothing. Agents then attach with scout_attach { role: "<name>" },
+                                    as many sessions as they like from one login. From a conversation, scout_login
+                                    opens the same window.
+                                    (--project dir (default: here); --browser chromium|firefox|webkit;
+                                    --save auto|enter (default auto; enter: save on Enter only, as before);
+                                    --success-url text|url: signed in once the URL's path contains this, or the URL
+                                    starts with it, instead of when a new session appears)
   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
                                     from SCENESCOUT_LOGIN_<FLAG>, e.g. SCENESCOUT_LOGIN_SUCCESS_URL;
                                     --timeout seconds (default 60))
+  scenescout export --to github|jira
+                                    File the project's open findings (from .scenescout/memory.json) as issues,
+                                    each once: a finding whose marker is already on an issue is skipped. A dry run
+                                    that lists what it would file unless --yes is given. Credentials come from the
+                                    environment only: GH_TOKEN or GITHUB_TOKEN; JIRA_EMAIL and JIRA_API_TOKEN.
+                                    (--repo owner/name for GitHub (GITHUB_API_URL for GitHub Enterprise Server);
+                                     --jira-url https://…, --jira-project KEY, --jira-issue-type name (default Bug),
+                                      --jira-link-type name|none (default Relates), or JIRA_BASE_URL,
+                                      JIRA_PROJECT_KEY, JIRA_ISSUE_TYPE, JIRA_LINK_TYPE, for Jira Cloud: an issue
+                                      is linked to each ticket whose criterion its finding fails;
+                                     --jira-update on|off (default on): update an open Jira issue filed earlier,
+                                      leaving a summary or description edited in Jira as it is;
+                                     --min-severity high|medium|low (default low); --only id,id;
+                                     --max-issues N (default 20, at most 100): the most one export files;
+                                     --refile-closed: file a finding again when its issue was closed (by default
+                                      an issue open or closed counts as filed); --include-worth-a-look;
+                                     --severity-map high=…,medium=…,low=… or none: a label on GitHub, a priority
+                                      in Jira (default severity: high… / High, Medium, Low); --labels a,b;
+                                     --screenshots on|off (default on: the finding's picture and the run's frames,
+                                      attached in Jira, named on GitHub);
+                                     --project dir (default: here); --dry-run; --yes)
+                                    Exit code: 0 done (findings over the cap wait for the next export), 2 could not
+                                    export (it lists what it filed before it stopped), or a screenshot was not
+                                    attached or a ticket not linked.
   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
@@ -261,26 +331,6 @@ function browserOpener(url) {
             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 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, ...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
@@ -372,7 +422,7 @@ async function install(flags) {
         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))
+            if ((await downloadBrowsers(missing, "inherit")).ok)
                 console.log(`✓ Downloaded: ${missing.join(", ")}.`);
             else {
                 failed = true;
@@ -476,12 +526,11 @@ async function install(flags) {
         process.exitCode = 1;
         return;
     }
-    if (browserOnly) {
-        console.log("\nThe browser is ready — attach again.");
+    const closing = installClosing({ browserOnly, forClaude });
+    if (closing)
+        console.log(`\n${closing}`);
+    if (browserOnly)
         return;
-    }
-    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)}`);
@@ -493,12 +542,15 @@ async function doctor(flags) {
         packageRoot,
         claudeDir: resolveClaudeDir(process.env, os.homedir()),
         nodeVersion: process.version,
+        version: packageVersion(),
         // 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 };
         })(),
+        desktopExtension: findDesktopExtension(desktopExtensionRoots({ platform: process.platform, home: os.homedir(), env: process.env })),
+        headlessShellDir: (await presentBrowsers())["chromium-headless-shell"].path,
         run: spawnRunner,
     });
     for (const c of checks) {
@@ -508,9 +560,7 @@ async function doctor(flags) {
     }
     if (checks.some((c) => !c.ok))
         process.exit(1);
-    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)");
+    console.log(`\n${doctorAllGood({ engineOnly: flags.includes("--engine"), desktopOnly: checks.some((c) => c.name === CLAUDE_CODE_NOT_NEEDED) })}`);
 }
 /** `scenescout check`: exit 0 passed, 1 failed the gate, 2 could not run. */
 async function check(args) {
@@ -556,7 +606,16 @@ async function check(args) {
             writeSelfIgnore(path.dirname(outDir));
         fs.mkdirSync(outDir, { recursive: true });
         fs.writeFileSync(path.join(outDir, "report.md"), markdown);
-        fs.writeFileSync(path.join(outDir, "check.sarif"), JSON.stringify(toSarif(result, version), null, 2) + "\n");
+        const sarifFiles = sarifFilesFor({
+            option: options.sarifFileAnchor,
+            env: process.env,
+            projectDir: options.projectDir,
+            flowsDir: inputs.flowsDir,
+            exists: (p) => fs.existsSync(p),
+        });
+        if (sarifFiles.warning)
+            console.error(`scenescout check: ${sarifFiles.warning}`);
+        fs.writeFileSync(path.join(outDir, "check.sarif"), JSON.stringify(toSarif(result, version, sarifFiles), null, 2) + "\n");
         fs.writeFileSync(path.join(outDir, "check.json"), JSON.stringify(toSummaryJson(result, version), null, 2) + "\n");
         // On GitHub Actions the verdict also goes on the run's summary page.
         if (process.env.GITHUB_STEP_SUMMARY)
@@ -569,11 +628,101 @@ async function check(args) {
     }
     console.log("\n" + markdown);
     console.log(`Wrote report.md, check.sarif and check.json to ${outDir}`);
+    const pictured = result.baselines?.results.filter((r) => r.files).length ?? 0;
+    if (pictured > 0)
+        console.log(`Wrote the pictures of ${pictured} changed baseline(s) under ${path.join(outDir, VISUAL_DIRNAME)}`);
+    const written = result.baselines?.results.filter((r) => r.status === "updated").length ?? 0;
+    if (written > 0)
+        console.log(`Wrote ${written} baseline(s) to ${baselinesDirOf(options)}`);
     // --on-refused-step report: everything else has its verdict in the files, and the exit code still says the run was incomplete.
     if (refused)
         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 (!(await downloadBrowsers(downloads, "inherit")).ok) {
+            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) {
     const secrets = secretValues(process.env);
@@ -591,11 +740,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(),
@@ -653,6 +806,21 @@ async function login(args) {
     }
     process.exit(0);
 }
+/** `scenescout export`: exits as EXIT_EXPORT says. */
+async function exportFindings(args) {
+    const parsed = parseExportArgs(args, process.cwd(), process.env);
+    if (!parsed.ok) {
+        // A refusal can quote the value it refused, and a credential pasted into an option is still a credential.
+        console.error(redactKeys(`scenescout export: ${parsed.error}`, credentialSecrets(process.env)));
+        process.exit(EXIT_EXPORT.couldNotExport);
+    }
+    const outcome = await runExport(parsed.options, {
+        env: process.env,
+        log: (line) => console.log(line),
+        error: (line) => console.error(line),
+    });
+    process.exit(outcome.exitCode);
+}
 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
@@ -682,12 +850,18 @@ try {
             check,
             ci,
             login,
+            export: exportFindings,
             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) {

package/dist/commands.js

@@ -6,6 +6,9 @@
  * 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,
@@ -15,13 +18,14 @@ const HANDLERS_OF = {
     check: true,
     ci: true,
     login: true,
+    export: 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
+ * Commands that read their arguments by hand. `check`, `ci`, `login` and
+ * `export` 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.
  */
@@ -70,6 +74,34 @@ export function unknownArgument(args, spec) {
 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))
@@ -93,8 +125,14 @@ export async function dispatch(command, args, h) {
         case "-v":
             return h.version();
     }
-    if (!isSubcommand(command))
-        return h.usage(1);
+    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);