scenescout 3.15.0 → 3.17.0

package/dist/cli.js

@@ -10,25 +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 { 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, 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";
@@ -73,7 +78,8 @@ Usage:
                                     so it can gate a pull request. Writes report.md, check.sarif and check.json.
                                     (--fail-on high|medium|low|never (default high); --mode observe|read-only;
                                      --max-routes N (default 50); --paths /a,/b to check only those;
-                                     --ignore rule,rule; --storage-state file to check signed in;
+                                     --ignore rule,rule; --ignore-path /a,rule:/b to exempt a path, or one rule on it;
+                                     --storage-state file to check signed in;
                                      --project dir (default: here); --out dir (default: .scenescout/check);
                                      --browser chromium|firefox|webkit;
                                      --action-timeout-ms N (default 5000), --nav-timeout-ms N (default 20000;
@@ -87,7 +93,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.
@@ -100,6 +118,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;
@@ -114,15 +134,22 @@ Usage:
                                      --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)
+                                      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
@@ -134,6 +161,30 @@ Usage:
                                     --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
@@ -281,26 +332,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
@@ -392,7 +423,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;
@@ -452,10 +483,8 @@ async function install(flags) {
             }
             else {
                 failed = true;
-                // On Windows a client installed through npm is a .cmd shim, which node cannot start directly.
-                const windowsNote = process.platform === "win32" ? " (or it is installed as a .cmd shim, which cannot be started from here)" : "";
                 console.log(reg.status === "client-missing"
-                    ? `· ${label} was not found on this machine${windowsNote}, so nothing was registered with it.`
+                    ? `· ${label} was not found on this machine, so nothing was registered with it.`
                     : `✗ Registering with ${label} failed: ${reg.detail}`);
                 console.log(`  To do it by hand, ${reg.manual}\n`);
             }
@@ -496,12 +525,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)}`);
@@ -513,12 +541,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) {
@@ -528,9 +559,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) {
@@ -576,7 +605,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)
@@ -589,6 +627,12 @@ 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}`);
@@ -616,7 +660,7 @@ async function firstRun(args) {
     if (downloads.length > 0) {
         console.log(downloadLine(downloads));
         const began = Date.now();
-        if (!downloadBrowsers(downloads)) {
+        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.
@@ -761,6 +805,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
@@ -790,6 +849,7 @@ try {
             check,
             ci,
             login,
+            export: exportFindings,
             status: (a) => status(path.resolve(a[0] ?? process.cwd())),
             watch: (a) => {
                 const positional = a.filter((x) => !x.startsWith("--"));

package/dist/commands.js

@@ -18,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.
  */