scenescout 3.14.0 → 3.14.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # scenescout
 
+## 3.14.1
+
+### Patch Changes
+
+- 5358a81: `--help` and `-h` now print the usage and exit 0 on every subcommand before it does anything; `scenescout install --help` used to run a real install. `install`, `doctor`, `scan`, `status` and `watch` now refuse a flag or argument they do not know instead of ignoring it.
+
 ## 3.14.0
 
 ### Minor Changes

package/README.md

@@ -12,7 +12,7 @@ Works with Claude Code · Cursor · VS Code (Copilot) · Codex CLI · Gemini CLI
 ![node >= 20](https://img.shields.io/badge/node-%E2%89%A5%2020-339933?logo=node.js&logoColor=white)
 ![MCP server](https://img.shields.io/badge/MCP-server-8A2BE2)
 
-[👀 See it work](#-see-it-work) · [✨ Why](#-why-its-different) · [🎯 Two ways to use it](#-two-ways-to-use-it) · [🚀 Quickstart](#-quickstart) · [🧰 Toolbox](#-the-toolbox) · [🔌 Other clients](#-other-mcp-clients) · [🔒 Safety](#-safety-model) · [🩺 Troubleshooting](#-troubleshooting)
+[📖 Guide](docs/guide/Home.md) · [👀 See it work](#-see-it-work) · [✨ Why](#-why-its-different) · [🎯 Two ways to use it](#-two-ways-to-use-it) · [🚀 Quickstart](#-quickstart) · [🧰 Toolbox](#-the-toolbox) · [🔌 Other clients](#-other-mcp-clients) · [🔒 Safety](#-safety-model) · [🩺 Troubleshooting](#-troubleshooting)
 
 </div>
 

package/dist/cli.js

@@ -29,6 +29,7 @@ import { EXIT, exitCodeOf, formatCheck, parseCheckArgs, refusedFlowReason, toSar
 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. */
@@ -295,13 +296,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 +343,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 +514,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}`);
@@ -584,8 +576,6 @@ async function check(args) {
 }
 /** `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) => {
@@ -627,8 +617,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 +660,35 @@ 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"));
+            },
+        },
+    });
 }
 catch (err) {
     console.error(`scenescout ${command ?? ""}: ${err instanceof Error ? err.message : String(err)}`);

package/dist/commands.js

@@ -0,0 +1,104 @@
+/**
+ * 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.
+ */
+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);
+}
+/** 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))
+        return h.usage(1);
+    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);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scenescout",
-  "version": "3.14.0",
+  "version": "3.14.1",
   "description": "SceneScout — exploratory UI testing for AI coding agents. An MCP server that gives any agent (Claude Code, Cursor, VS Code Copilot, Codex, Gemini CLI and others) a structured view of a running web app, always-on oracles, a network-level write policy, memory across runs and a gap-checked report.",
   "license": "MIT",
   "author": "brunoboto96",
@@ -72,7 +72,7 @@
     "mcp-check": "npm run build && npm run mcp-check:run",
     "mcp-check:run": "tsx scripts/mcp-check.ts",
     "test": "npm run build && npm run test:unit && npm run smoke:run && npm run mcp-check:run",
-    "test:unit": "npm run scan-test && npm run oracle-test && npm run policy-test && npm run fixture-test && npm run dispatch-test && npm run design-test && npm run check-test && npm run ci-test && npm run qa-test && npm run contract-test && npm run pace-test && npm run limits-test && npm run request-test && npm run settle-test && npm run claims-test && npm run verify-test && npm run brief-test && npm run lane-test && npm run calibration-test && npm run bench-test && npm run memory-test && npm run install-test && npm run profiles-test && npm run refresh-test && npm run scripted-login-test && npm run live-test && npm run demo-test && npm run holdout-test && npm run hygiene-test",
+    "test:unit": "npm run scan-test && npm run oracle-test && npm run policy-test && npm run fixture-test && npm run dispatch-test && npm run design-test && npm run check-test && npm run ci-test && npm run qa-test && npm run contract-test && npm run pace-test && npm run limits-test && npm run request-test && npm run settle-test && npm run claims-test && npm run verify-test && npm run brief-test && npm run lane-test && npm run calibration-test && npm run bench-test && npm run memory-test && npm run install-test && npm run profiles-test && npm run refresh-test && npm run scripted-login-test && npm run live-test && npm run demo-test && npm run holdout-test && npm run hygiene-test && npm run guide-test",
     "scan-test": "tsx scripts/scan-test.ts",
     "oracle-test": "tsx --test scripts/oracle-test.ts",
     "policy-test": "tsx --test scripts/policy-test.ts",
@@ -93,6 +93,7 @@
     "demo-test": "tsx --test scripts/demo-test.ts",
     "holdout-test": "tsx --test scripts/holdout-test.ts",
     "hygiene-test": "tsx --test scripts/hygiene-test.ts",
+    "guide-test": "tsx --test scripts/guide-test.ts",
     "pace-test": "tsx --test scripts/pace-test.ts",
     "limits-test": "tsx --test scripts/limits-test.ts",
     "request-test": "tsx --test scripts/request-test.ts",