scenescout 3.23.3 → 3.23.4

package/dist/engine/check.js

@@ -13,13 +13,14 @@
 import { createHash } from "node:crypto";
 import { BROWSER_ENGINES } from "../browsers.js";
 import { BASELINE_MODES, baselineEvidence, baselineFingerprint, countStatuses, describeChange, parseThreshold, VISUAL_RULE, } from "./baseline.js";
+import { readFlagValue } from "./args.js";
 import { isNonPageResource } from "./crawl.js";
 import { flowStepEvidence } from "./flow.js";
 import { parseLimitFlag } from "./limits.js";
 import { redactRoute, redactSecrets } from "./memory.js";
 import { SARIF_ANCHOR_FALLBACKS, checkSarifAnchor, sarifFileFor, sarifLocation } from "./sarif.js";
 import { httpErrorDetail, httpStatusOf } from "./oracles.js";
-export const CHECK_SEVERITIES = ["high", "medium", "low"];
+const CHECK_SEVERITIES = ["high", "medium", "low"];
 export const FAIL_ON = [...CHECK_SEVERITIES, "never"];
 /**
  * The routes that answered as pages, and those that answered as something
@@ -154,8 +155,8 @@ export const WORTH_A_LOOK_RULES = {
         convention: "row actions and other controls that stay in view without a sideways scroll of their container at this viewport width",
     },
 };
-export const CHECK_RULE_IDS = [...Object.keys(CHECK_RULES), ...Object.keys(WORTH_A_LOOK_RULES)];
-export function isWorthALookRule(rule) {
+const CHECK_RULE_IDS = [...Object.keys(CHECK_RULES), ...Object.keys(WORTH_A_LOOK_RULES)];
+function isWorthALookRule(rule) {
     return Object.prototype.hasOwnProperty.call(WORTH_A_LOOK_RULES, rule);
 }
 export const SEVERITY_RANK = { high: 0, medium: 1, low: 2 };
@@ -371,7 +372,7 @@ export function issuesFromRoutes(routes, origin, ignore = [], flows = [], ignore
  * Fewest controls a start page must show for a check that measured nothing
  * else to count as having measured the app (unmeasuredReason).
  */
-export const START_PAGE_MIN_CONTROLS = 2;
+const START_PAGE_MIN_CONTROLS = 2;
 /**
  * Why a check has nothing to give a verdict on, or null when it measured the
  * app. Neither case is a pass: a gate that goes green on a login page or a
@@ -470,9 +471,9 @@ export const EXIT = { pass: 0, gateFailed: 1, error: 2 };
  * pages. Each default is the one that does the least harm on an unfamiliar
  * project: it never writes and never silently hides a result (ADR 12).
  */
-export const FLOW_WRITES = ["never", "allow"];
-export const ON_REFUSED_STEP = ["report", "stop"];
-export const GATE_RETESTS = ["never", "high", "all"];
+const FLOW_WRITES = ["never", "allow"];
+const ON_REFUSED_STEP = ["report", "stop"];
+const GATE_RETESTS = ["never", "high", "all"];
 export const DEFAULT_SETTINGS = { flowWrites: "never", onRefusedStep: "report", gateRetests: "high", retest: true };
 /**
  * Every `--option` `scenescout check` accepts. The GitHub Action at the
@@ -512,7 +513,7 @@ const SWITCH_OFF = ["off", "false", "0"];
 export const MAX_CHECK_ROUTES = 150;
 /** Link discovery rounds: each crawl reveals the routes its pages link to. Past a few, a site is paginating rather than revealing. */
 export const MAX_DISCOVERY_ROUNDS = 6;
-export const DEFAULT_CHECK_ROUTES = 50;
+const DEFAULT_CHECK_ROUTES = 50;
 /** A path given on the command line, resolved from the directory the command runs in; the same on every platform. */
 export function resolveArgPath(cwd, p) {
     return p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p) ? p : `${cwd.replace(/[\\/]$/, "")}/${p}`;
@@ -537,12 +538,11 @@ export function parseCheckArgs(args, cwd) {
             flags.set(name, next !== undefined && [...SWITCH_ON, ...SWITCH_OFF].includes(next) ? next : "on");
             continue;
         }
-        const value = eq > 0 ? a.slice(eq + 1) : args[i + 1];
-        if (value === undefined || (eq < 0 && value.startsWith("--")))
-            return { ok: false, error: `--${name} needs a value` };
-        if (eq < 0)
-            i += 1;
-        flags.set(name, value);
+        const read = readFlagValue(args, i);
+        if (!read.ok)
+            return read;
+        i = read.last;
+        flags.set(name, read.value);
     }
     const known = new Set(CHECK_OPTION_NAMES);
     for (const name of flags.keys())
@@ -1038,7 +1038,7 @@ export function needsSignInText(count, cover, noun = "route") {
     return `${count} ${noun}${count === 1 ? " needs" : "s need"} sign-in; give a role to cover them: ${cover}.`;
 }
 /** The routes that sent a check with no session to sign-in, as their own section; nothing when there were none. */
-export function needsSignInSection(result) {
+function needsSignInSection(result) {
     const routes = result.needsSignIn ?? [];
     if (routes.length === 0)
         return [];

package/dist/engine/ci.js

@@ -11,6 +11,7 @@
 import { createHash } from "node:crypto";
 import path from "node:path";
 import { BROWSER_ENGINES } from "../browsers.js";
+import { readFlagValue } from "./args.js";
 import { MAX_LANES } from "./brief.js";
 import { markdownCell } from "./check.js";
 import { parseLimitFlag } from "./limits.js";
@@ -18,18 +19,18 @@ import { isWorthALook, redactSecrets } from "./memory.js";
 import { SARIF_ANCHOR_FALLBACKS, checkSarifAnchor, sarifLocation } from "./sarif.js";
 import { fromRunLine, resolveFromRun } from "./from-run.js";
 // ── options ─────────────────────────────────────────────────────────────────
-export const PROVIDERS = ["anthropic", "openai"];
+const PROVIDERS = ["anthropic", "openai"];
 /** Where each provider's key is read from. Nothing else is: no flag, no file, no input. */
 export const KEY_ENV = { anthropic: "ANTHROPIC_API_KEY", openai: "OPENAI_API_KEY" };
-export const DEFAULT_MODEL = { anthropic: "claude-sonnet-5", openai: "gpt-6-luna" };
+const DEFAULT_MODEL = { anthropic: "claude-sonnet-5", openai: "gpt-6-luna" };
 /** The API root each request path is joined to. `--base-url` replaces it, for a compatible endpoint. */
-export const DEFAULT_BASE_URL = { anthropic: "https://api.anthropic.com/v1", openai: "https://api.openai.com/v1" };
+const DEFAULT_BASE_URL = { anthropic: "https://api.anthropic.com/v1", openai: "https://api.openai.com/v1" };
 /** Reasoning effort each API accepts. The Messages API has no "none": thinking is lowered, not switched off. */
-export const EFFORTS = {
+const EFFORTS = {
     anthropic: ["low", "medium", "high", "xhigh", "max"],
     openai: ["none", "low", "medium", "high", "xhigh", "max"],
 };
-export const DEFAULT_EFFORT = "low";
+const DEFAULT_EFFORT = "low";
 /**
  * The write policies a CI run may use. `destructive` lets the model send any
  * request, deletes of records it did not create included, so it is taken only
@@ -37,8 +38,8 @@ export const DEFAULT_EFFORT = "low";
  * workflow or typed by an agent, never enables it. What CI may do is the
  * developer's decision; the default stays read-only (ADR 14).
  */
-export const CI_MODES = ["observe", "read-only", "safe-write", "destructive"];
-export const CI_LEVELS = ["minimal", "medium", "extensive"];
+const CI_MODES = ["observe", "read-only", "safe-write", "destructive"];
+const CI_LEVELS = ["minimal", "medium", "extensive"];
 /**
  * How a filed finding is told apart from one already stored. `rule`: the
  * store's rule alone (memory.ts isDuplicateFinding). `judge`: the rule first,
@@ -49,11 +50,11 @@ export const CI_LEVELS = ["minimal", "medium", "extensive"];
  * judges only when asked to (DEDUP_ENV or scout_attach {dedup}).
  */
 export const DEDUP_MODES = ["rule", "judge"];
-export const DEFAULT_CI_DEDUP = "judge";
+const DEFAULT_CI_DEDUP = "judge";
 /** Turns the dedup judge on for the MCP server: `rule` (the default) or `judge`. An attach's `dedup` wins over it. */
 export const DEDUP_ENV = "SCENESCOUT_DEDUP";
 /** Which provider the MCP server's dedup judge uses when both keys are in its environment. */
-export const DEDUP_PROVIDER_ENV = "SCENESCOUT_DEDUP_PROVIDER";
+const DEDUP_PROVIDER_ENV = "SCENESCOUT_DEDUP_PROVIDER";
 /** Why these are the defaults: docs/benchmark.md, "Choosing the defaults (issue 419)". */
 export const DEFAULT_CAPS = { turns: 80, tokens: 3_000_000, wallMs: 20 * 60_000 };
 const CAP_BOUNDS = { turns: [1, 500], tokens: [1_000, 20_000_000], minutes: [1, 360] };
@@ -66,7 +67,7 @@ const CAP_BOUNDS = { turns: [1, 500], tokens: [1_000, 20_000_000], minutes: [1,
  * lanes) runs as one loop rather than failing; --lanes given explicitly is
  * held to those rules.
  */
-export const DEFAULT_LANES = 2;
+const DEFAULT_LANES = 2;
 export const MAX_CI_LANES = MAX_LANES;
 /** Every option `scenescout ci` accepts; the ci action's inputs are these names (ci-test holds them equal). */
 export const CI_OPTION_NAMES = [
@@ -100,7 +101,7 @@ export const CI_OPTION_NAMES = [
     "sarif-file-anchor",
 ];
 /** The longest --show description: it becomes a line of the model's prompt. */
-export const MAX_SHOW = 200;
+const MAX_SHOW = 200;
 const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "[::1]", "::1"]);
 /** A base URL a key may be sent to: https, or plain http only to this machine. */
 export function checkBaseUrl(raw) {
@@ -136,12 +137,11 @@ export function parseCiArgs(args, cwd, env = {}) {
             flags.set(name, "true");
             continue;
         }
-        const value = eq > 0 ? a.slice(eq + 1) : args[i + 1];
-        if (value === undefined || (eq < 0 && value.startsWith("--")))
-            return { ok: false, error: `--${name} needs a value` };
-        if (eq < 0)
-            i += 1;
-        flags.set(name, value);
+        const read = readFlagValue(args, i);
+        if (!read.ok)
+            return read;
+        i = read.last;
+        flags.set(name, read.value);
     }
     const known = new Set(CI_OPTION_NAMES);
     for (const name of flags.keys()) {
@@ -522,7 +522,7 @@ export function describeStop(reason, caps, detail) {
             return `could not start${detail ? `: ${detail}` : ""}`;
     }
 }
-export const PRICES = {
+const PRICES = {
     "gpt-6-luna": { input: 0.1, cachedInput: 0.01, output: 0.5 },
     "gpt-5.6-luna": { input: 0.2, cachedInput: 0.02, output: 1.2 },
     "claude-sonnet-5": { input: 2, cachedInput: 0.2, cacheWrite: 2.5, output: 10 },
@@ -666,7 +666,7 @@ export function guardToolArgs(name, args, projectDir) {
     return { ok: true, args: { ...args, projectPath: path.resolve(projectDir) } };
 }
 /** The longest tool result handed back to the model, in characters. The report keeps everything; this only bounds the context. */
-export const TOOL_RESULT_MAX_CHARS = 16_000;
+const TOOL_RESULT_MAX_CHARS = 16_000;
 /** One tool result as text: images named rather than sent, and the length bounded. */
 export function toolResultText(content, max = TOOL_RESULT_MAX_CHARS) {
     const parts = (content ?? []).map((c) => (c.type === "text" ? (c.text ?? "") : `[${c.type} omitted: this run is text-only]`));
@@ -737,7 +737,7 @@ export function findingsThisRun(before, after) {
     return after.filter((f) => f.status !== "resolved" && (!runsBefore.has(f.id) || f.runs > (runsBefore.get(f.id) ?? 0)));
 }
 /** One line on how a run deduplicated, for the summary. */
-export function dedupLine(d) {
+function dedupLine(d) {
     if (d.by === "rule")
         return "the rule alone";
     const tokens = d.usage.input + d.usage.output;

package/dist/engine/claims.js

@@ -282,7 +282,7 @@ function pathNames(req, subject) {
  * sentence naming what they fetched is a genuinely empty section rather than
  * a refusal hidden behind an empty state.
  */
-export function pairEmptyState(text, refusedReads, loaded) {
+function pairEmptyState(text, refusedReads, loaded) {
     const subject = emptyStateSubject(text);
     if (subject.length === 0)
         return { certain: true, read: refusedReads[0] };
@@ -446,7 +446,7 @@ export const COUNTER_RE = /(?<![\d/.,:])(?:\d{1,4} ?(?:\/|of) ?\d{1,4}|\d{1,3} ?
 /** The containers a counter must share with the control to count as its counter. */
 const CONTROL_CONTAINER_SEL = 'dialog, [role="dialog"], [role="alertdialog"], fieldset, form, [role="group"], [role="radiogroup"], [role="toolbar"], [role="region"], section, aside, [role="complementary"]';
 /** Most counters read for one control. */
-export const MAX_COUNTERS = 20;
+const MAX_COUNTERS = 20;
 /**
  * Page-side reader of an acted-on control: `(${ACTED_CONTROL_SRC})(node)`
  * returns an ActedControl, or null for no node. A label stands for the box it
@@ -560,9 +560,9 @@ export function saidSince(text, baseline) {
     return true;
 }
 /** Most announced regions read from one page. */
-export const MAX_ANNOUNCED = 40;
+const MAX_ANNOUNCED = 40;
 /** Most pieces of text read from one page. A page with more than this has nothing useful to say in the extra ones. */
-export const MAX_CLAIM_TEXTS = 120;
+const MAX_CLAIM_TEXTS = 120;
 /**
  * Page-side reader for the two signals `findContradictions` needs. Shipped as
  * a STRING expression for the same reason the collector is: loader transforms

package/dist/engine/collector.js

@@ -48,7 +48,7 @@ export const XPATH_OF_SRC = `(el) => {
  * says nothing. Kept apart from NAME_FACTS_SRC so the order can be
  * table-tested without a browser (contentSays).
  */
-export const CONTENT_SAYS_SRC = `(d) => {
+const CONTENT_SAYS_SRC = `(d) => {
     if (d.ariaLabel && d.ariaLabel.trim()) return d.ariaLabel;
     if (d.tag === "img") return d.alt && d.alt.trim() ? d.alt : d.title;
     if (d.tag === "svg") return d.svgTitle;
@@ -75,7 +75,7 @@ export function contentSays(facts) {
  * an <img>'s alt and an <svg>'s or role="img"'s aria-label or <title>: it is
  * read so a control renamed since keeps its coverage.
  */
-export const NAME_FACTS_SRC = `(el) => {
+const NAME_FACTS_SRC = `(el) => {
     const tag = el.tagName.toLowerCase();
     const role = el.getAttribute("role") || "";
     const inputType = tag === "input" ? el.type : "";
@@ -156,7 +156,7 @@ export const NAME_FACTS_SRC = `(el) => {
  * - A whitespace-only aria-label ends the name with nothing, as it always has
  *   here: the field it hides is reported as unnamed.
  */
-export const PICK_NAME_SRC = `(f) => {
+const PICK_NAME_SRC = `(f) => {
     const clean = (s) => (s || "").replace(/\\s+/g, " ").trim();
     const named = (s) => ({ name: s.slice(0, 80), from: null });
     const field = f.tag === "input" || f.tag === "textarea" || f.tag === "select";
@@ -300,9 +300,9 @@ export const FOCUS_MOVES_PROPS = [
 /** The most elements a snapshot lists in full; past it, what is left is counted (cutSummary). */
 export const COLLECTOR_CAP = 150;
 /** Pager and "load more" controls listed past the cap, so a lane can still reach the rest of a long list. */
-export const MAX_KEPT_PAST_CAP = 10;
+const MAX_KEPT_PAST_CAP = 10;
 /** How many elements past the cap are looked at, to keep them or count them, before the rest goes uncounted. */
-export const MAX_SCANNED_PAST_CAP = 2000;
+const MAX_SCANNED_PAST_CAP = 2000;
 /**
  * A control that pages a list or loads more of it, by its name: "Next",
  * "Previous page", "Page 3", "»", "Load more", "Show 20 more", "More results".
@@ -906,7 +906,7 @@ export function cutSummary(cut, groups = 8) {
     return named.join(", ");
 }
 /** A key without the ordinal the collector adds to the second and later elements sharing it ("tid:row~3" → "tid:row"). */
-export function keyFamily(key) {
+function keyFamily(key) {
     return key.replace(/~\d+$/, "");
 }
 /**
@@ -1315,7 +1315,7 @@ export function frameElementKey(baseKey, frame) {
     return `frame:${where}|${baseKey}`;
 }
 /** The longest name kept for a control in another site's frame: a chat that renders messages as buttons would otherwise print them whole. */
-export const MAX_FOREIGN_NAME = 40;
+const MAX_FOREIGN_NAME = 40;
 /** A control's name from another site's frame, cut to MAX_FOREIGN_NAME. */
 export function capForeignName(name) {
     return name.length > MAX_FOREIGN_NAME ? `${name.slice(0, MAX_FOREIGN_NAME)}…` : name;

package/dist/engine/crawl.js

@@ -48,7 +48,7 @@ export function crawlLine(o, counts, flags) {
         (allFlags.length ? ` · ${allFlags.join(" ")}` : ""));
 }
 /** The media types a browser renders as a page: anything else a route answers with is a file, a feed or data. */
-export const PAGE_MEDIA_TYPES = ["text/html", "application/xhtml+xml"];
+const PAGE_MEDIA_TYPES = ["text/html", "application/xhtml+xml"];
 /**
  * A Content-Type header's media type, lowercased and without its parameters
  * ("text/HTML; charset=utf-8" → "text/html"); undefined when there is none.

package/dist/engine/dedup.js

@@ -150,7 +150,7 @@ export const JUDGE_SYSTEM = "You decide whether two findings filed by explorator
     "never below 0.5: near 0.5 when the text can barely tell, near 1 only when it plainly can. " +
     "Example: verdict different with confidence 0.9 means a 10% chance they are one defect. Use unsure only when the findings give too little to go on.";
 /** What the judge is shown: the fields a tester filed, nothing from the key. */
-export function judgeKickoff(route, a, b) {
+function judgeKickoff(route, a, b) {
     const show = (f) => ({ title: f.title, category: f.category, evidence: f.evidence ?? "" });
     return `Both findings were filed on the page ${route}.\n\nFinding A: ${JSON.stringify(show(a))}\nFinding B: ${JSON.stringify(show(b))}`;
 }
@@ -223,7 +223,7 @@ export async function decideDuplicate(p, ask, ruleVerdict) {
 }
 // ── the judge the store asks ────────────────────────────────────────────────
 /** Calls made about one filing at most: its most alike open findings on the page. */
-export const JUDGE_MAX_CALLS = 3;
+const JUDGE_MAX_CALLS = 3;
 /** The longest one judge call may take. */
 export const JUDGE_CALL_MS = 15_000;
 /**
@@ -231,9 +231,9 @@ export const JUDGE_CALL_MS = 15_000;
  * scout_finding's 60-second watchdog, so a slow provider costs a filing its
  * judge and never the filing.
  */
-export const JUDGE_FILING_MS = 40_000;
+const JUDGE_FILING_MS = 40_000;
 /** Failed calls in a row after which the judge is switched off for the rest of the run. */
-export const JUDGE_MAX_FAILURES = 3;
+const JUDGE_MAX_FAILURES = 3;
 /** The most output one judge call may produce: the answer is one short tool call (24 to 26 tokens when measured). */
 export const JUDGE_MAX_OUTPUT_TOKENS = 2_000;
 /**

package/dist/engine/design.js

@@ -53,7 +53,7 @@ export function focusedControl(doc) {
  * words, split at camelCase and punctuation, is filter(s) or facet(s). Whole
  * words only, so "filterable-list" or "unfiltered" says nothing.
  */
-export const FILTER_WORDS_SRC = `(s) => (s || "").replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z]+/).some((w) => w === "filter" || w === "filters" || w === "facet" || w === "facets")`;
+const FILTER_WORDS_SRC = `(s) => (s || "").replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z]+/).some((w) => w === "filter" || w === "filters" || w === "facet" || w === "facets")`;
 /** FILTER_WORDS_SRC run outside a page, from the same source, so a table test exercises the rule the collector ships. */
 export function namesFilter(text) {
     return new Function(`return (${FILTER_WORDS_SRC});`)()(text);
@@ -435,7 +435,7 @@ function gridValues(top) {
         .join(", ");
 }
 /** The box a pointer user hits to operate the control: its label or drop zone where one operates it, else its own. */
-export function targetBox(r) {
+function targetBox(r) {
     return r.target ?? r.rect;
 }
 /** The WCAG 2.2 target-size minimum, in CSS pixels. */
@@ -536,7 +536,7 @@ export function distinguishingLayer(key, others) {
  * stone), the shades text and surfaces are built from. Near-white and
  * near-black are left out, as before: every page has them.
  */
-export function grayOf(rgb) {
+function grayOf(rgb) {
     const avg = (rgb[0] + rgb[1] + rgb[2]) / 3;
     return hueOf(rgb) === null && avg > 20 && avg < 245;
 }
@@ -574,7 +574,7 @@ const GRAY_STEP = 4;
  * the audit and the snapshot agree on a page. Records with no name read are
  * left out rather than guessed.
  */
-export function unnamedControls(records) {
+function unnamedControls(records) {
     const named = records.filter((r) => r.interactive && typeof r.name === "string");
     const asSnapshot = (r) => ({
         role: r.role,
@@ -606,7 +606,7 @@ function distanceToBox([px, py], b) {
  * target's circle. `others` is every interactive record on the page, shell
  * included, since a neighbour in the shell is as easy to hit by mistake.
  */
-export function spacedApart(r, others) {
+function spacedApart(r, others) {
     const c = centreOf(targetBox(r));
     for (const o of others) {
         if (o === r || !o.interactive)
@@ -628,11 +628,11 @@ export function spacedApart(r, others) {
  * A target that fails WCAG 2.5.8: under 24px, measured on what the user hits
  * (targetBox), and not saved by the spacing exception.
  */
-export function tooSmall(r, all) {
+function tooSmall(r, all) {
     return undersized(r) && !spacedApart(r, all);
 }
 /** Past this, a stretched image reads as distorted rather than as rounding. */
-export const ASPECT_TOLERANCE = 0.12;
+const ASPECT_TOLERANCE = 0.12;
 /**
  * How far an image is stretched out of its proportions, or null when it is not.
  * Only `fill`, the default, stretches the picture to its box: `cover` and `contain`

package/dist/engine/expiry.js

@@ -154,7 +154,7 @@ export function readLifetime(state, opts = {}) {
     return { credentials, dated, undated: credentials.length - dated.length, elsewhere, unreadableTokens };
 }
 /** A span as a person says it; days past two, since "73h00m" reads badly. */
-export function sayLifetime(ms) {
+function sayLifetime(ms) {
     const days = Math.floor(ms / 86_400_000);
     return days >= 2 ? `${days} days` : sayDuration(ms);
 }

package/dist/engine/export.js

@@ -12,6 +12,7 @@
  * made inert before it goes into an issue.
  */
 import { createHash } from "node:crypto";
+import { readFlagValue } from "./args.js";
 import { readFindingPicture } from "./capture.js";
 import { CHECK_RULES, WORTH_A_LOOK_RULES } from "./check.js";
 import { readFindings } from "./ci.js";
@@ -20,7 +21,7 @@ import { retryAfterMs } from "./provider.js";
 import { answerTicket } from "./tickets.js";
 const TRACKERS = ["github", "jira"];
 export const TRACKER_LABEL = { github: "GitHub", jira: "Jira" };
-export const SEVERITIES = ["high", "medium", "low"];
+const SEVERITIES = ["high", "medium", "low"];
 const SEVERITY_RANK = { high: 0, medium: 1, low: 2 };
 /** Every option `scenescout export` accepts. guide-test holds the configuration reference equal to it. */
 export const EXPORT_OPTION_NAMES = [
@@ -183,12 +184,11 @@ export function parseExportArgs(args, cwd, env) {
             flags.set(name, "true");
             continue;
         }
-        const value = eq > 0 ? a.slice(eq + 1) : args[i + 1];
-        if (value === undefined || (eq < 0 && value.startsWith("--")))
-            return { ok: false, error: `--${name} needs a value` };
-        if (eq < 0)
-            i += 1;
-        flags.set(name, value);
+        const read = readFlagValue(args, i);
+        if (!read.ok)
+            return read;
+        i = read.last;
+        flags.set(name, read.value);
     }
     const to = flags.get("to");
     if (to === undefined)

package/dist/engine/flow.js

@@ -25,23 +25,23 @@ import { FIXTURE_KINDS } from "./fixtures.js";
 import { MEMORY_DIRNAME, SELF_IGNORE_KEEP } from "./memory.js";
 import { validateRoleName } from "./profiles.js";
 /** Most steps one flow may hold. A longer flow is several flows, and each would fail more usefully on its own. */
-export const MAX_FLOW_STEPS = 50;
+const MAX_FLOW_STEPS = 50;
 /** Most flows one check replays. */
-export const MAX_FLOWS = 50;
+const MAX_FLOWS = 50;
 /**
  * How long a flow waits after its last step for a write that step set off
  * late (a save on a timer, a debounced autosave), before it counts as passed.
  */
 export const FLOW_AFTER_LAST_STEP_MS = 750;
 /** Where a project keeps its flows, relative to the project directory. */
-export const FLOWS_SUBDIR = path.join(MEMORY_DIRNAME, SELF_IGNORE_KEEP);
+const FLOWS_SUBDIR = path.join(MEMORY_DIRNAME, SELF_IGNORE_KEEP);
 export const TARGET_HELP = 'testid=…, text=…, label=… or role=<role>[name="…"]';
 /**
  * The ARIA roles a `role=` target may name (WAI-ARIA 1.2, as Playwright's
  * getByRole accepts them). A misspelt role matches nothing, so a flow using
  * one would only ever fail at replay; it is refused when the file is read.
  */
-export const ARIA_ROLE_LIST = [
+const ARIA_ROLE_LIST = [
     "alert",
     "alertdialog",
     "application",
@@ -126,7 +126,7 @@ export const ARIA_ROLE_LIST = [
     "treeitem",
 ];
 export const ARIA_ROLES = new Set(ARIA_ROLE_LIST);
-export const ARIA_ROLES_MATCH_PLAYWRIGHT = ARIA_ROLE_LIST;
+const ARIA_ROLES_MATCH_PLAYWRIGHT = ARIA_ROLE_LIST;
 /** Parse a target string, or null when it is not one. */
 export function parseTarget(target) {
     for (const by of ["testid", "text", "label"]) {
@@ -159,7 +159,7 @@ export function notActionable(action, facts) {
  * when nothing matches: "the receipt was never shown" and "the dialog closed"
  * are both the absence of a visible element.
  */
-export const ELEMENT_STATES = ["visible", "hidden", "enabled", "disabled", "checked", "unchecked"];
+const ELEMENT_STATES = ["visible", "hidden", "enabled", "disabled", "checked", "unchecked"];
 /**
  * Whether an element in the state `facts` describes satisfies `state`, and if
  * not, what is true instead, in the words the report uses. `facts` is null when
@@ -213,7 +213,7 @@ const target = z
  */
 const expected = z.string().trim().min(1, "is the result the step should bring about, in words").max(500).optional();
 /** Most times a repeat step may run its steps. A longer loop is a page that should be reached another way. */
-export const MAX_REPEATS = 100;
+const MAX_REPEATS = 100;
 const SINGLE_STEP_SCHEMAS = [
     z.object({ action: z.literal("navigate"), expected, target: z.string().regex(/^\//, "must be a path on the app, starting with /") }).strict(),
     z.object({ action: z.literal("click"), expected, target }).strict(),
@@ -269,7 +269,7 @@ const repeatSchema = z
     .strict();
 const STEP_SCHEMAS = [...SINGLE_STEP_SCHEMAS, repeatSchema];
 const stepSchema = z.discriminatedUnion("action", [...STEP_SCHEMAS]);
-export const FLOW_ACTIONS = STEP_SCHEMAS.map((s) => s.shape.action.value);
+const FLOW_ACTIONS = STEP_SCHEMAS.map((s) => s.shape.action.value);
 const flowSchema = z
     .object({
     name: z.string().min(1).max(100).optional(),
@@ -509,7 +509,7 @@ export function matchRequest(expect, seen) {
  * (browsers.ts `beaconResourceType`). They are fire-and-forget by design, a
  * page sends them on its own schedule, and no step waits for one.
  */
-export const BACKGROUND_REQUEST_TYPES = new Set(["ping", ...BROWSER_ENGINES.map(beaconResourceType)]);
+const BACKGROUND_REQUEST_TYPES = new Set(["ping", ...BROWSER_ENGINES.map(beaconResourceType)]);
 /**
  * Split what the write policy refused during a step into what the step is
  * charged with and background requests, which are only listed. The rule is
@@ -534,7 +534,7 @@ export function splitRefusals(refusals, appOrigin) {
 /** A value taken from the environment when the flow runs: `${env:NAME}` in a type or select step's value. */
 const ENV_REF = /\$\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g;
 /** Shortest substituted value masked in the check's output. Shorter ones would mask ordinary words and numbers. */
-export const MIN_MASKED_ENV_VALUE = 4;
+const MIN_MASKED_ENV_VALUE = 4;
 /** Every step that takes a value, the steps inside a repeat included. */
 function valueSteps(steps) {
     return steps.flatMap((s) => s.action === "repeat" ? valueSteps(s.steps) : "value" in s && s.action !== "press" ? [s] : []);

package/dist/engine/forms.js

@@ -135,7 +135,7 @@ export const APP_FILLED_TYPES = new Set(["date", "datetime-local", "month", "wee
  * Input types in which Enter submits the form (the HTML standard's implicit
  * submission). Not checkboxes, radios or buttons: Enter does nothing there.
  */
-export const IMPLICIT_SUBMIT_TYPES = new Set([...TEXT_ENTRY_TYPES, "search"]);
+const IMPLICIT_SUBMIT_TYPES = new Set([...TEXT_ENTRY_TYPES, "search"]);
 /** Whether a field takes typed text and a user could type into it right now. */
 export function isTextEntry(f) {
     if (!f.visible || f.disabled || f.readOnly)

package/dist/engine/from-run.js

@@ -27,7 +27,7 @@ export const FROM_RUN_ENV = "SCENESCOUT_FROM_RUN";
 /** How to use it: `continue` (the default) or `replay`. */
 export const FROM_RUN_MODE_ENV = "SCENESCOUT_FROM_RUN_MODE";
 /** How many model turns a continued run budgets for each page it takes on: what sets its page cap (pageCap). */
-export const FROM_RUN_TURNS_PER_PAGE_ENV = "SCENESCOUT_FROM_RUN_TURNS_PER_PAGE";
+const FROM_RUN_TURNS_PER_PAGE_ENV = "SCENESCOUT_FROM_RUN_TURNS_PER_PAGE";
 /**
  * Turns a continued run spends on one page by default: enough to exercise its
  * controls, submit its forms and try its options, measured against what a run
@@ -36,13 +36,13 @@ export const FROM_RUN_TURNS_PER_PAGE_ENV = "SCENESCOUT_FROM_RUN_TURNS_PER_PAGE";
  */
 export const DEFAULT_TURNS_PER_PAGE = 7;
 /** The bounds of the setting. */
-export const TURNS_PER_PAGE_RANGE = { min: 1, max: 200 };
+const TURNS_PER_PAGE_RANGE = { min: 1, max: 200 };
 /**
  * `continue`: start where the earlier run left off. `replay`: follow its route
  * and step order again.
  */
 export const FROM_RUN_MODES = ["continue", "replay"];
-export const DEFAULT_FROM_RUN_MODE = "continue";
+const DEFAULT_FROM_RUN_MODE = "continue";
 /**
  * The earlier run a run starts from: the path option, else the environment
  * variable, else none; the mode option, else its variable, else `continue`.
@@ -86,11 +86,11 @@ export function pageCap(turns, turnsPerPage) {
     return Math.max(1, Math.floor(turns / Math.max(1, turnsPerPage)));
 }
 /** The most steps a record keeps: a replay of more would not fit a model's first message anyway. */
-export const MAX_RECORD_STEPS = 400;
+const MAX_RECORD_STEPS = 400;
 /** The most routes a record lists in any one list. */
-export const MAX_RECORD_ROUTES = 300;
+const MAX_RECORD_ROUTES = 300;
 /** The most controls, forms or options a record keeps per route. */
-export const MAX_RECORD_KEYS = 40;
+const MAX_RECORD_KEYS = 40;
 /** The most records a project's memory keeps; the oldest go first. */
 export const MAX_RECORDS = 20;
 /** A route's identity for matching: two spellings of one page are one route. */

package/dist/engine/injection.js

@@ -22,7 +22,7 @@ export const MAX_PROBES = 60;
 /** Text is compared on this many characters, on both sides, so a long fuzz value still matches its element. */
 export const INJECTION_TEXT_MAX = 200;
 /** Most matching elements reported per probe per page. */
-export const MAX_HITS = 20;
+const MAX_HITS = 20;
 const OPEN_RE = /<([a-zA-Z][a-zA-Z0-9-]*)/;
 // One attribute at a time, anchored where the last one ended: a slash between
 // attributes is the same as a space to a browser (`<svg/onload=…>`). Each

package/dist/engine/lane.js

@@ -380,7 +380,7 @@ function pathSegments(path) {
  * `order-{id}` is a literal, and so is `**`, which some routers read as "any
  * number of segments": a template here stands for exactly one.
  */
-export function isTemplateSegment(seg) {
+function isTemplateSegment(seg) {
     return seg === "*" || /^\{[^/{}]+\}$/.test(seg) || /^:[a-z_][a-z0-9_-]*$/i.test(seg);
 }
 /**

package/dist/engine/limits.js

@@ -18,7 +18,7 @@ export const DEFAULT_NAV_TIMEOUT_MS = 20000;
 /** The crawl has always given each route less than a deliberate navigation. */
 export const DEFAULT_CRAWL_NAV_TIMEOUT_MS = 15000;
 /** Going back and a popup's load have always had the shortest wait. */
-export const DEFAULT_BACK_NAV_TIMEOUT_MS = 10000;
+const DEFAULT_BACK_NAV_TIMEOUT_MS = 10000;
 export const DEFAULT_TIME_LIMITS = {
     actionMs: DEFAULT_ACTION_TIMEOUT_MS,
     navMs: DEFAULT_NAV_TIMEOUT_MS,
@@ -42,7 +42,7 @@ function boundsText(kind) {
     return `a whole number of milliseconds from ${min} to ${max}`;
 }
 /** Check one value against its bounds. `source` names where it came from, so the error says what to fix. */
-export function checkLimit(kind, value, source) {
+function checkLimit(kind, value, source) {
     const { min, max } = LIMIT_BOUNDS[kind];
     if (!Number.isInteger(value) || value < min || value > max) {
         throw new Error(`${source} must be ${boundsText(kind)} (got ${value}).`);

package/dist/engine/live.js

@@ -35,6 +35,36 @@ export const LIVE_TOKEN_FILE = "live-token";
 export function liveTokenFileName(pid) {
     return `${LIVE_TOKEN_FILE}.${pid}`;
 }
+/**
+ * Hand the live view's token to `scenescout watch`: this engine's own file,
+ * then the shared name. Each is born owner-only under a fresh temporary name
+ * and renamed into place. Writing to the name itself would keep the bits of a
+ * file already there (`mode` applies only on creation) and would follow a link
+ * left at it, sending the token into whatever file the link points at; a
+ * rename replaces the entry, link or file, and never writes through it.
+ */
+export async function writeLiveToken(dir, pid, token) {
+    for (const name of [liveTokenFileName(pid), LIVE_TOKEN_FILE]) {
+        const file = path.join(dir, name);
+        const temp = `${file}.${pid}.${crypto.randomBytes(6).toString("hex")}.tmp`;
+        // "wx": created here and now, so the mode given is the one it is born with, and never a link's target.
+        const handle = await fs.promises.open(temp, "wx", 0o600);
+        try {
+            try {
+                await handle.writeFile(token);
+            }
+            finally {
+                await handle.close();
+            }
+            await fs.promises.rename(temp, file);
+        }
+        catch (err) {
+            // The temporary file holds the token too: nothing that failed may leave it behind.
+            await fs.promises.rm(temp, { force: true }).catch(() => { });
+            throw err;
+        }
+    }
+}
 /** `SCENESCOUT_LIVE=off` keeps the engine from opening the live view's port at all. */
 export const LIVE_ENV = "SCENESCOUT_LIVE";
 /**