scenescout 1.0.0

package/dist/engine/dispatch.js

@@ -0,0 +1,100 @@
+/**
+ * Tool-call dispatch: the per-session queue and the watchdog.
+ *
+ * Extracted from mcp-server.ts because these two are the whole basis of the
+ * multi-role promise — "calls to DIFFERENT sessions run concurrently, calls to
+ * the SAME session never interleave" — and living inside the server module they
+ * could only be exercised by driving a real browser over stdio, so nothing in
+ * `npm test` touched them. A regression here (two same-session calls
+ * overlapping and corrupting one browser's ref table, or a watchdog timer that
+ * never clears) would ship green. Here they are pure and table-testable: see
+ * scripts/dispatch-test.ts.
+ */
+/**
+ * Resolve with `onTimeout(...)` if `p` has not settled within `ms`.
+ *
+ * Two details that look incidental and are not:
+ *  - the timer is cleared when `p` settles, so a long-lived process does not
+ *    accumulate live timers (each would also hold the event loop open);
+ *  - the guarded promise gets its own no-op `.catch`, because once the race has
+ *    been won by the timeout nobody is left to handle a later rejection and
+ *    Node would report an unhandled rejection for a call the caller was
+ *    already told had timed out.
+ */
+export function withWatchdog(label, p, ms, onTimeout) {
+    let timer;
+    const guarded = p.finally(() => clearTimeout(timer));
+    void guarded.catch(() => { });
+    return Promise.race([
+        guarded,
+        new Promise((resolve) => {
+            timer = setTimeout(() => resolve(onTimeout(label, ms)), ms);
+        }),
+    ]);
+}
+/**
+ * Serializes work per key, and only per key.
+ *
+ * One browser's ref table and fingerprint are shared mutable state, so two
+ * calls against the SAME session must not interleave. Two calls against
+ * DIFFERENT sessions share nothing, so they must not queue behind each other —
+ * that is what makes dispatching to several roles in one turn actually
+ * parallel rather than merely concurrent-looking.
+ */
+export class SessionQueue {
+    chains = new Map();
+    /** Calls queued or running per key — a chain may not be dropped while this is above zero. */
+    pending = new Map();
+    /** Keys asked to be forgotten while still busy; dropped when they drain. */
+    forgotten = new Set();
+    /** Queue `fn` behind anything already running for `key`; returns its result. */
+    run(key, fn) {
+        const prior = this.chains.get(key) ?? Promise.resolve();
+        this.pending.set(key, (this.pending.get(key) ?? 0) + 1);
+        // Run `fn` whether the previous call resolved or REJECTED — a failed tool
+        // call must not wedge that session's queue forever.
+        const next = prior.then(fn, fn);
+        // The stored link swallows rejections: it exists only to sequence the next
+        // call, and an unhandled rejection here would crash the process for an
+        // error the caller is already receiving.
+        const settled = next.then(() => this.release(key), () => this.release(key));
+        this.chains.set(key, settled);
+        return next;
+    }
+    release(key) {
+        const left = (this.pending.get(key) ?? 1) - 1;
+        if (left > 0) {
+            this.pending.set(key, left);
+            return;
+        }
+        this.pending.delete(key);
+        if (this.forgotten.delete(key))
+            this.chains.delete(key);
+    }
+    /** Keys with work queued or in flight — diagnostics only. */
+    get size() {
+        return this.chains.size;
+    }
+    /**
+     * Drop a key's chain once it is idle (e.g. its session closed).
+     *
+     * Dropping it WHILE a call is in flight would be a correctness bug, not
+     * housekeeping: the next call for that key would find no chain, start
+     * immediately, and interleave with the call still running — precisely the
+     * overlap this class exists to prevent. `scout_close` runs on its own control
+     * chain, so it really can land mid-call. A still-busy key is marked instead
+     * and dropped when it drains.
+     */
+    forget(key) {
+        if ((this.pending.get(key) ?? 0) > 0) {
+            this.forgotten.add(key);
+            return;
+        }
+        this.chains.delete(key);
+    }
+    /** Forget every key (close-all), honouring the same in-flight rule. */
+    clear() {
+        for (const key of [...this.chains.keys()])
+            this.forget(key);
+    }
+}

package/dist/engine/fingerprint.js

@@ -0,0 +1,100 @@
+import { createHash } from "node:crypto";
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const HEX_RE = /^[0-9a-f]{12,}$/i;
+const NUM_RE = /^\d+$/;
+/** Query params that name a UI state (a different screen), not transient data. */
+const UI_STATE_PARAM_RE = /^(tab|view|mode|step|panel|section)$/i;
+/**
+ * Normalize a URL into a route-class identity:
+ * - path ids collapse (/orders/123 → /orders/:id)
+ * - hash-router paths count as the path (#/orders/5 → /orders/:id)
+ * - UI-state query params are KEPT (?tab=audit is a different screen;
+ *   ?page=2 is not) so tabs are enumerable, crawlable, and countable.
+ *
+ * A NUMERIC FIRST SEGMENT IS NOT AN ID. `/404` and `/500` are the two most
+ * common static pages in any web app, and collapsing them to `/:id` made them
+ * aliases of each other: visiting the 404 page marked the 500 page covered,
+ * because the unvisited filter compares normalized forms. Ids in real apps
+ * follow a collection noun (`/documents/239`, `/orders/5`), so position 1 is
+ * where static numeric pages live and position 2+ is where ids live. A UUID or
+ * long hex string still collapses anywhere — no static page is named one.
+ */
+export function normalizePath(rawUrl) {
+    let path;
+    let search;
+    try {
+        const u = new URL(rawUrl, "http://x");
+        path = u.pathname;
+        search = u.search;
+        if (u.hash.startsWith("#/")) {
+            const [hashPath, hashQuery] = u.hash.slice(1).split("?");
+            path = hashPath;
+            search = hashQuery ? `?${hashQuery}` : "";
+        }
+    }
+    catch {
+        [path = "/", search = ""] = rawUrl.split("?");
+        search = search ? `?${search}` : "";
+    }
+    // segments[0] is always "" for a leading-slash path, so the first REAL
+    // segment is index 1 — that is the one a bare numeric page occupies.
+    const segments = path.split("/").map((seg, i) => {
+        if (UUID_RE.test(seg) || HEX_RE.test(seg))
+            return ":id";
+        if (NUM_RE.test(seg) && i > 1)
+            return ":id";
+        return seg;
+    });
+    let normalized = segments.join("/") || "/";
+    if (normalized === "")
+        normalized = "/";
+    const kept = [];
+    for (const [k, v] of new URLSearchParams(search)) {
+        if (UI_STATE_PARAM_RE.test(k))
+            kept.push(`${k}=${v.slice(0, 40)}`);
+    }
+    if (kept.length > 0)
+        normalized += `?${kept.sort().join("&")}`;
+    return normalized;
+}
+/**
+ * Paths that are not UI pages, however they entered the route list: API
+ * endpoints and file downloads.
+ *
+ * `harvestRoutes` already skips these when it reads an href, but a route can
+ * also arrive by navigation, or from a memory written before that filter
+ * existed — and once in the contract it sits in the gap ledger forever, since
+ * "visiting" it downloads a file instead of rendering a page, so it can never
+ * be exercised or audited. Filtering at the CONTRACT boundary means no entry
+ * path can reintroduce one. The query check catches export links whose path
+ * looks page-like (`/reports/export?format=csv`).
+ */
+export function isNonPageRoute(route) {
+    const [path, query = ""] = route.split("?");
+    if (/^\/api(\/|$)/i.test(path))
+        return true;
+    if (/\.(pdf|zip|csv|xlsx?|docx?|pptx?|png|jpe?g|gif|svg|ico|mp4|webm|json|xml)$/i.test(path))
+        return true;
+    return /\b(format=(csv|pdf|xlsx?|docx?)|download=(1|true))\b/i.test(query);
+}
+/** Stable key identifying an element class within a state (for coverage tracking). */
+export function elementKey(el) {
+    if (el.testid)
+        return `tid:${el.testid}`;
+    const name = el.name.toLowerCase().replace(/\s+/g, " ").trim().slice(0, 60);
+    return `${el.role}:${name}`;
+}
+/**
+ * Fingerprint a UI state: normalized route + hash of the set of interactable
+ * element classes. Same page with different data → same fingerprint; a page
+ * whose available actions changed (modal opened, different role) → new one.
+ */
+export function fingerprintState(url, elements) {
+    const route = normalizePath(url);
+    const keys = [...new Set(elements.map(elementKey))].sort();
+    const hash = createHash("sha1").update(keys.join("|")).digest("hex").slice(0, 8);
+    return `${route}#${hash}`;
+}
+export function shortHash(input) {
+    return createHash("sha1").update(input).digest("hex").slice(0, 10);
+}

package/dist/engine/fixtures.js

@@ -0,0 +1,162 @@
+/**
+ * Synthetic upload fixtures.
+ *
+ * An upload control is the one form field that cannot be exercised with text:
+ * `fill()` refuses `<input type="file">`, so every upload flow used to sit in
+ * the gap ledger forever as "filled but never submitted". Playwright can set a
+ * file input from an in-memory payload, which means nothing has to exist on
+ * disk — this module generates small files that are VALID for their type (a
+ * real PDF structure, a real PNG), so the app's own parser / preview / scan
+ * path runs against something it would accept from a user, not a renamed text
+ * file it rejects on the first byte.
+ *
+ * Pure module: no browser, no filesystem — see scripts/fixture-test.ts.
+ */
+export const FIXTURE_KINDS = ["pdf", "png", "txt", "csv", "json"];
+const MIME = {
+    pdf: "application/pdf",
+    png: "image/png",
+    txt: "text/plain",
+    csv: "text/csv",
+    json: "application/json",
+};
+/** Mime types for extensions a disk file may carry beyond the fixture kinds. */
+const EXTRA_MIME = {
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    svg: "image/svg+xml",
+    html: "text/html",
+    htm: "text/html",
+    xml: "application/xml",
+    zip: "application/zip",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+};
+export function isFixtureKind(value) {
+    return typeof value === "string" && FIXTURE_KINDS.includes(value);
+}
+/** Mime type for a filename by extension — needed when a disk file is uploaded under a custom name. */
+export function mimeForName(name) {
+    const ext = /\.([a-z0-9]+)$/i.exec(name)?.[1]?.toLowerCase();
+    if (!ext)
+        return "application/octet-stream";
+    return (isFixtureKind(ext) ? MIME[ext] : EXTRA_MIME[ext]) ?? "application/octet-stream";
+}
+function tokens(accept) {
+    return (accept ?? "")
+        .toLowerCase()
+        .split(",")
+        .map((t) => t.trim())
+        .filter(Boolean);
+}
+/**
+ * Which fixture an input's `accept` attribute would admit. Tokens are read in
+ * the order the app listed them — the first names the primary type — and the
+ * first that maps to a kind we can generate wins (spreadsheet types get the
+ * CSV, the nearest thing we can make). No `accept`, or only types we cannot
+ * approximate at all (.docx, .zip), falls back to PDF, the most widely
+ * whitelisted document type; `generatedUpload` says which of those happened.
+ */
+export function fixtureKindFor(accept) {
+    for (const token of tokens(accept)) {
+        if (token === ".pdf" || token === "application/pdf")
+            return "pdf";
+        if (token.startsWith("image/") || /^\.(png|jpe?g|gif|webp|bmp)$/.test(token))
+            return "png";
+        if (token === ".csv" || token === "text/csv" || /excel|spreadsheet|^\.xlsx?$/.test(token))
+            return "csv";
+        if (token === ".json" || token === "application/json")
+            return "json";
+        if (token === ".txt" || token === "text/plain" || token === "text/*")
+            return "txt";
+    }
+    return "pdf";
+}
+/**
+ * Does a file satisfy an `accept` attribute? `null` when there is no accept
+ * (nothing to satisfy). Mirrors the browser's own picker filter: `.ext`
+ * matches the filename's extension, `type/*` the mime's major type, `type/sub`
+ * exactly. A file that fails this and is accepted anyway is a validation gap —
+ * the caller says so.
+ */
+export function acceptMatches(accept, fileName, mimeType) {
+    const list = tokens(accept);
+    if (list.length === 0)
+        return null;
+    const lowerName = fileName.toLowerCase();
+    const mime = mimeType.toLowerCase();
+    return list.some((token) => {
+        if (token.startsWith("."))
+            return lowerName.endsWith(token);
+        if (token.endsWith("/*"))
+            return mime.startsWith(token.slice(0, -1));
+        return mime === token;
+    });
+}
+/** Build a small, valid file of the given kind — in memory, nothing on disk. */
+export function syntheticFile(kind, name) {
+    return { name: name ?? `scenescout-fixture.${kind}`, mimeType: MIME[kind], buffer: BUILDERS[kind]() };
+}
+/**
+ * The fixture an upload should send, with an honest account of how its kind
+ * was chosen. `accept` is the input's attribute (`null` = the input has none;
+ * `undefined` = the input could not be inspected), `fixture` an explicit
+ * kind, `name` a filename override. The wording matters: "inferred from
+ * accept" when the accept listed only types we cannot generate would tell the
+ * driver the file matches when it does not.
+ */
+export function generatedUpload(accept, fixture, name) {
+    const kind = fixture ?? fixtureKindFor(accept);
+    const file = syntheticFile(kind, name);
+    let why = "";
+    if (!fixture) {
+        if (accept === undefined)
+            why = " (accept unknown; pdf is the default)";
+        else if (!accept)
+            why = " (no accept attribute; pdf is the default)";
+        else if (acceptMatches(accept, file.name, file.mimeType))
+            why = " (inferred from accept)";
+        else
+            why = " (accept lists no type we can generate; pdf is the fallback)";
+    }
+    return { file, source: `generated ${kind} fixture${why}` };
+}
+const BUILDERS = {
+    txt: () => Buffer.from("SceneScout synthetic upload fixture.\nGenerated for exploratory testing; contains no real data.\n", "utf8"),
+    csv: () => Buffer.from("id,name,status\n1,Alpha widget,active\n2,Beta widget,inactive\n3,Gamma widget,active\n", "utf8"),
+    json: () => Buffer.from(`${JSON.stringify({ fixture: "scenescout", generated: true, items: [{ id: 1, name: "Alpha widget" }] }, null, 2)}\n`, "utf8"),
+    // A tiny well-formed PNG: 1×1 RGBA, one half-transparent pixel, CRCs intact.
+    png: () => Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==", "base64"),
+    pdf: minimalPdf,
+};
+/**
+ * A one-page PDF with a line of text. The cross-reference table carries REAL
+ * byte offsets, computed as the objects are laid down — most viewers tolerate
+ * a wrong xref, but a strict parser (and a backend that validates uploads)
+ * does not, and "valid" is the whole point of a fixture.
+ */
+function minimalPdf() {
+    const content = "BT /F1 24 Tf 72 720 Td (SceneScout synthetic upload fixture) Tj ET";
+    const objects = [
+        "<< /Type /Catalog /Pages 2 0 R >>",
+        "<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
+        "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Contents 4 0 R /Resources << /Font << /F1 5 0 R >> >> >>",
+        `<< /Length ${Buffer.byteLength(content, "latin1")} >>\nstream\n${content}\nendstream`,
+        "<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>",
+    ];
+    let out = "%PDF-1.4\n";
+    const offsets = [];
+    objects.forEach((body, i) => {
+        offsets.push(Buffer.byteLength(out, "latin1"));
+        out += `${i + 1} 0 obj\n${body}\nendobj\n`;
+    });
+    const xrefAt = Buffer.byteLength(out, "latin1");
+    // Every xref entry is exactly 20 bytes: 10-digit offset, 5-digit generation, type, space, newline.
+    out += `xref\n0 ${objects.length + 1}\n0000000000 65535 f \n`;
+    for (const offset of offsets)
+        out += `${String(offset).padStart(10, "0")} 00000 n \n`;
+    out += `trailer\n<< /Size ${objects.length + 1} /Root 1 0 R >>\nstartxref\n${xrefAt}\n%%EOF\n`;
+    return Buffer.from(out, "latin1");
+}

package/dist/engine/journey.js

@@ -0,0 +1,71 @@
+/**
+ * Task-ease measurement: what did it COST a user to get one thing done?
+ *
+ * A passing end-to-end test says a flow works; it says nothing about how many
+ * screens, interactions and wrong turns the flow takes. These numbers are
+ * derived purely from the action log, so the thresholds and the verdict wording
+ * are table-tested here instead of being reachable only through a browser.
+ */
+import { normalizePath } from "./fingerprint.js";
+/** More distinct screens than this for one task is worth questioning. */
+const MANY_SCREENS = 4;
+/** More interactions than this for one task is worth questioning. */
+const MANY_INTERACTIONS = 15;
+function routeOf(url) {
+    try {
+        return normalizePath(new URL(url).pathname);
+    }
+    catch {
+        return url;
+    }
+}
+/** Measure one journey from the slice of the action log that belongs to it. */
+export function measureJourney(log, completed) {
+    const interactions = log.filter((e) => /^(click|type|select|press|plan:(click|type|select|press))/.test(e.action)).length;
+    const navigations = log.filter((e) => /^(navigate|back|plan:navigate|plan:back)/.test(e.action)).length;
+    const routeSeq = log.map((e) => routeOf(e.url)).filter((r, i, a) => i === 0 || r !== a[i - 1]);
+    const distinctScreens = new Set(routeSeq).size;
+    // A backtrack = returning to a route already left behind. Real users do
+    // this when the path wasn't obvious; it is the clearest signal that
+    // information scent failed, and it is invisible to a pass/fail test.
+    const seen = new Set();
+    let backtracks = 0;
+    for (const r of routeSeq) {
+        if (seen.has(r))
+            backtracks += 1;
+        seen.add(r);
+    }
+    const policyBlocks = log.filter((e) => e.action === "write-policy:blocked").length;
+    const refusals = log.filter((e) => /refused|REFUSED/.test(e.result ?? "")).length;
+    const shortcuts = log.filter((e) => /^(navigate|plan:navigate)$/.test(e.action)).length;
+    const verdict = [];
+    if (backtracks > 0)
+        verdict.push(`⚠ ${backtracks} backtrack(s) — the route was re-visited after leaving it, which usually means the next step wasn't discoverable from where the user was`);
+    if (distinctScreens > MANY_SCREENS)
+        verdict.push(`⚠ ${distinctScreens} distinct screens for one task — each hand-off is a chance to lose the user; consider whether steps can be combined or done in place`);
+    if (interactions > MANY_INTERACTIONS)
+        verdict.push(`⚠ ${interactions} interactions — high for a single task; check for over-asking (optional fields up-front) or repeated confirmation steps`);
+    if (shortcuts > 0)
+        verdict.push(`⚠ ${shortcuts} direct-URL jump(s) during the journey — a first-time user cannot type URLs, so the measurement is contaminated: either re-run clicking through the UI, or the destination is unreachable by UI navigation (which is itself a finding).`);
+    if (!completed)
+        verdict.push(`⚠ TASK NOT COMPLETED — this is the strongest possible finding: the journey is blocked or undiscoverable. File it.`);
+    if (verdict.length === 0)
+        verdict.push(`✓ efficient — direct path, no backtracking, proportionate interaction count`);
+    return { interactions, navigations, routeSeq, distinctScreens, backtracks, shortcuts, policyBlocks, refusals, verdict };
+}
+/** The tool result for a finished journey. */
+export function formatJourney(j, m) {
+    return [
+        `JOURNEY ${j.completed ? "COMPLETED" : "ABANDONED"} — "${j.goal}"`,
+        ``,
+        `Interaction cost: ${m.interactions} interactions · ${m.navigations} navigations · ${m.distinctScreens} distinct screens · ${j.seconds}s`,
+        `Path: ${m.routeSeq.slice(0, 12).join(" → ")}${m.routeSeq.length > 12 ? " → …" : ""}`,
+        ...(m.policyBlocks > 0 || m.refusals > 0 ? [`Policy: ${m.policyBlocks} write-policy blocks, ${m.refusals} refusals (tester safety, not app defects)`] : []),
+        ...(j.note ? [`Note: ${j.note}`] : []),
+        ``,
+        `Efficiency read:`,
+        ...m.verdict.map((v) => `  ${v}`),
+        ``,
+        `Judge with product context: a 3-screen approval flow with an e-signature step is legitimately longer than "add a comment". Compare against what the task NEEDS, then file genuine friction as ux-confusing (blocked/undiscoverable) or ux-polish (works but costs more than it should), quoting these numbers.`,
+    ].join("\n");
+}

package/dist/engine/launch.js

@@ -0,0 +1,25 @@
+/**
+ * Turning a failed browser launch into something the person can act on.
+ *
+ * For anyone who installed from npm and never ran the setup step, the first
+ * attach fails because Chromium was never downloaded — and Playwright reports
+ * that as a multi-line box of text with a path in it. That is the single most
+ * likely first-run failure, so it gets one plain instruction instead.
+ */
+/** Playwright's wording when the browser binary is not on disk. */
+const MISSING_BROWSER_RE = /Executable doesn't exist|playwright install|browserType\.launch:.*(not found|ENOENT)/i;
+export function isMissingBrowser(message) {
+    return MISSING_BROWSER_RE.test(message);
+}
+/** The error text for a launch that failed. `reaped` is how many orphaned browsers were cleaned up between attempts. */
+export function explainLaunchFailure(message, reaped) {
+    if (isMissingBrowser(message)) {
+        return (`Chromium has not been downloaded yet (one-time, ~150 MB). Run this once, then attach again:\n` +
+            `  npx -y scenescout install --browser-only\n` +
+            `(from a clone: npm run setup). On Linux, if system libraries are missing: npx playwright install --with-deps chromium`);
+    }
+    const firstLine = message.split("\n")[0];
+    return (`browser launch failed twice (${firstLine})` +
+        (reaped > 0 ? ` — ${reaped} orphaned browser process(es) were reaped between attempts` : "") +
+        `. Check disk space, then run \`scenescout doctor\` to verify the setup.`);
+}