scenescout 3.15.0 → 3.17.0

package/dist/engine/project-folder.js

@@ -0,0 +1,191 @@
+/**
+ * Where a run keeps its notes, memory and report when the agent names no
+ * project folder (scout_attach `projectPath`).
+ *
+ * A client with no workspace (a desktop chat app, say) has no folder to offer,
+ * and a person testing a site should not be asked to invent one. So each tested
+ * site gets its own folder under the user's documents folder, such as
+ * `Documents/SceneScout/localhost-3000/`, created on first use.
+ *
+ * What wins, first to last:
+ *   1. the `projectPath` the attach names, always;
+ *   2. the client's workspace folder, when it offers one (MCP roots);
+ *   3. the per-site default, unless PROJECTS_DIR_ENV is `off`.
+ * The default is never placed inside a git repository below the home folder: a
+ * folder of recordings and saved logins does not belong in somebody's commits
+ * unless they chose it. A home folder that is itself a repository (dotfiles)
+ * does not count.
+ *
+ * Everything here is pure (the filesystem is passed in), so it is table-tested
+ * in memory-test.
+ */
+import path from "node:path";
+import { domainToUnicode, fileURLToPath } from "node:url";
+import { MEMORY_DIRNAME } from "./memory.js";
+/** The setting: an absolute folder that holds one folder per tested site, or `off`. */
+export const PROJECTS_DIR_ENV = "SCENESCOUT_PROJECTS_DIR";
+/** The folder made under the documents folder when the setting is unset. */
+export const DEFAULT_PROJECTS_DIRNAME = "SceneScout";
+/**
+ * The user's documents folder. Windows: `%USERPROFILE%\Documents`; Linux and
+ * others: XDG_DOCUMENTS_DIR from the environment or user-dirs.dirs (which the
+ * server reads on Linux only), else
+ * `~/Documents`; macOS: `~/Documents`.
+ */
+export function documentsDir(home) {
+    if (home.platform === "win32") {
+        const profile = home.env.USERPROFILE && path.win32.isAbsolute(home.env.USERPROFILE) ? home.env.USERPROFILE : home.homedir;
+        return path.win32.join(profile, "Documents");
+    }
+    if (home.platform !== "darwin") {
+        const fromEnv = home.env.XDG_DOCUMENTS_DIR;
+        const fromFile = home.userDirs?.match(/^\s*XDG_DOCUMENTS_DIR\s*=\s*"([^"\n]*)"/m)?.[1];
+        for (const raw of [fromEnv, fromFile]) {
+            if (!raw)
+                continue;
+            const expanded = raw.replace(/^\$HOME(?=\/|$)/, home.homedir);
+            if (!path.posix.isAbsolute(expanded))
+                continue;
+            // resolve() drops a trailing slash, so "$HOME/" compares equal to the home folder.
+            const dir = path.posix.resolve(expanded);
+            // XDG says a documents folder equal to $HOME means "none": fall through to ~/Documents.
+            if (dir !== path.posix.resolve(home.homedir))
+                return dir;
+        }
+    }
+    return path.posix.join(home.homedir, "Documents");
+}
+/** Names Windows reserves, which no folder may take, whatever its extension. */
+const RESERVED = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])(\.|$)/i;
+/**
+ * The folder name for a tested site: its host as a person would write it, with
+ * the port when there is one. `http://localhost:3000` → `localhost-3000`,
+ * `https://xn--bcher-kva.example/` → `bücher.example`, `http://[::1]:8080` →
+ * `ipv6-__1-8080`. Two addresses of one site (http and https, any path) share
+ * a folder; a different port is a different site. Throws for an address with
+ * no host, which has no site to name.
+ */
+export function siteFolderName(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`"${url}" is not a full address, so there is no site to name a folder after. Pass projectPath.`);
+    }
+    let host = parsed.hostname.toLowerCase().replace(/\.+$/, "");
+    if (!host)
+        throw new Error(`"${url}" has no host, so there is no site to name a folder after. Pass projectPath.`);
+    if (host.startsWith("["))
+        host = `ipv6-${host.slice(1, -1).replace(/:/g, "_")}`;
+    else
+        host = domainToUnicode(host).normalize("NFC") || host;
+    // A hostname holds only letters, digits, hyphens and dots, but say so here
+    // rather than trust it: this becomes one path segment.
+    host = host.replace(/[^\p{L}\p{M}\p{N}._-]/gu, "_").replace(/^\.+/, "_");
+    if (RESERVED.test(host))
+        host = `site-${host}`;
+    return parsed.port ? `${host}-${parsed.port}` : host;
+}
+/**
+ * The folder holding one folder per site: the setting when it names an
+ * absolute folder, `null` when it is `off`, else `<documents>/SceneScout`.
+ * A setting that is neither throws, naming the variable.
+ */
+export function projectsRoot(home) {
+    const setting = home.env[PROJECTS_DIR_ENV]?.trim();
+    const p = home.platform === "win32" ? path.win32 : path.posix;
+    if (setting) {
+        if (setting.toLowerCase() === "off")
+            return null;
+        if (!p.isAbsolute(setting))
+            throw new Error(`${PROJECTS_DIR_ENV} must be an absolute folder or "off", not "${setting}".`);
+        return p.normalize(setting);
+    }
+    return p.join(documentsDir(home), DEFAULT_PROJECTS_DIRNAME);
+}
+/**
+ * The git repository a folder would sit inside: the nearest folder, the folder
+ * itself included, holding a `.git` (a directory, or a file in a worktree).
+ * `exists` is fs.existsSync in use; the folder need not exist yet.
+ *
+ * With `stopAt` (the home folder), the walk ends below it: a home folder that
+ * is itself a repository, as a dotfiles setup makes it, does not count, since
+ * refusing every default folder there is worse than one untracked folder in
+ * it. A folder outside `stopAt` is walked to the root.
+ */
+export function enclosingRepo(dir, exists, platform = process.platform, stopAt) {
+    const p = platform === "win32" ? path.win32 : path.posix;
+    const same = (a, b) => (platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b);
+    const stop = stopAt === undefined ? undefined : p.resolve(stopAt);
+    for (let at = p.resolve(dir);;) {
+        if (stop !== undefined && same(at, stop))
+            return null;
+        if (exists(p.join(at, ".git")))
+            return at;
+        const up = p.dirname(at);
+        if (up === at)
+            return null;
+        at = up;
+    }
+}
+/**
+ * The first workspace folder a client offers as MCP roots, or null. Only `file:`
+ * roots name a folder, read as `platform` reads them: `file:///C:/work/app` is
+ * `C:\\work\\app` on Windows, and a root with no drive letter is no folder there.
+ */
+export function workspaceFromRoots(roots, platform = process.platform) {
+    for (const root of roots ?? []) {
+        if (!root.uri.startsWith("file:"))
+            continue;
+        try {
+            return fileURLToPath(root.uri, { windows: platform === "win32" });
+        }
+        catch {
+            continue; // a file: URI naming another host, or no absolute path on this platform: not a folder here
+        }
+    }
+    return null;
+}
+/**
+ * Which folder a run keeps its files in, and the plain line that says so.
+ * `given` is the attach's projectPath; `workspace` the client's folder, if any.
+ */
+export function chooseProjectFolder(input) {
+    if (input.given !== undefined)
+        return { dir: input.given, source: "given", note: "" };
+    if (input.workspace) {
+        return {
+            dir: input.workspace,
+            source: "workspace",
+            note: `📁 FILES: no projectPath was given, so this run's notes, memory, sign-ins and report are kept in your workspace folder, under ${input.workspace}.`,
+        };
+    }
+    let root;
+    let name;
+    try {
+        root = projectsRoot(input.home);
+        name = siteFolderName(input.url);
+    }
+    catch (err) {
+        return { refused: `No projectPath was given and no default folder could be chosen: ${err.message}` };
+    }
+    if (root === null)
+        return {
+            refused: `No projectPath was given, and ${PROJECTS_DIR_ENV} is "off", so there is no default folder. Pass projectPath: the folder this run's notes, memory and report go in.`,
+        };
+    const p = input.home.platform === "win32" ? path.win32 : path.posix;
+    const dir = p.join(root, name);
+    const repo = enclosingRepo(dir, input.exists, input.home.platform, input.home.homedir);
+    if (repo)
+        return {
+            refused: `No projectPath was given, and the default folder ${dir} would be inside the git repository ${repo}, where a run's recordings and saved logins could be committed. ` +
+                `Pass projectPath to choose a folder (inside that repository too, if that is what you want), or set ${PROJECTS_DIR_ENV} to a folder outside it.`,
+        };
+    return {
+        dir,
+        source: "default",
+        note: `📁 FILES: this site's notes, memory, sign-ins and report are kept in ${dir} — a folder SceneScout made for this site, since none was given. ` +
+            `The report will be ${p.join(dir, MEMORY_DIRNAME, "report.md")}. Pass projectPath, or set ${PROJECTS_DIR_ENV}, to keep them elsewhere.`,
+    };
+}

package/dist/engine/refresh.js

@@ -264,6 +264,9 @@ export function planRefresh(sent, current) {
     const same = current.find((c) => c.slot === sent.slot);
     return same ? { kind: "swap", to: same } : { kind: "unknown" };
 }
+export function profileLoadWhileHeld(isNavigation) {
+    return isNavigation ? "cookies" : "storage";
+}
 /** Replace a spent token with the current one in a body, URL or header value, in whichever wire form it appears. */
 export function swapToken(text, from, to) {
     let out = text.split(from).join(to);
@@ -308,12 +311,74 @@ export function rotationStored(state, sent) {
  * page's storage state, which has no sessionStorage, with the sessionStorage
  * of the profile on disk kept beside it. Without it, an app whose sign-in also
  * lives in sessionStorage would lose that half on every brokered refresh.
- * A profile that could not be read (null) leaves the page's state as it is.
+ * The same goes for IndexedDB, which a storage state holds only when it was
+ * asked for: an origin the page's state has no IndexedDB entry for keeps the
+ * one on disk. An origin whose state does list IndexedDB, even an empty list,
+ * is the page's as it now is. With `storageFrom` "disk" the origins
+ * (localStorage and IndexedDB) are the profile's on disk and only the cookies
+ * are the page's (writeBackStorageFrom). A profile that could not be read
+ * (null) leaves the page's state as it is.
  */
-export function profileAfterRotation(pageState, profileOnDisk) {
+export function profileAfterRotation(pageState, profileOnDisk, storageFrom = "page") {
     if (profileOnDisk === null)
         return pageState;
-    return withSessionStorage(pageState, splitProfile(profileOnDisk).sessionStorage);
+    const disk = splitProfile(profileOnDisk);
+    if (storageFrom === "disk" && pageState && typeof pageState === "object") {
+        return withSessionStorage({ ...pageState, origins: disk.storageState.origins ?? [] }, disk.sessionStorage);
+    }
+    return withSessionStorage(withIndexedDB(pageState, disk.storageState.origins), disk.sessionStorage);
+}
+/**
+ * Where a write-back takes each origin's storage from (profileAfterRotation's
+ * `storageFrom`). A swap that loaded only the profile's cookies while it held
+ * a navigation (profileLoadWhileHeld) left the page's storage as it was
+ * before the other session's rotation, so writing that back would put spent
+ * tokens over the current ones on disk: the storage stays the profile's, and
+ * only the cookies, where the rotation it presented lives, are the page's.
+ * A token presented from storage is the page's to store, so its storage is
+ * taken from the page as it is now.
+ */
+export function writeBackStorageFrom(loaded, presented) {
+    return loaded === "cookies" && presented.cookie !== undefined ? "disk" : "page";
+}
+/** `state` with each disk origin's IndexedDB carried over where the state has none of its own (profileAfterRotation). */
+function withIndexedDB(state, diskOrigins) {
+    const kept = diskOrigins.filter((o) => !!o && typeof o === "object" && typeof o.origin === "string" && Array.isArray(o.indexedDB));
+    if (kept.length === 0 || !state || typeof state !== "object")
+        return state;
+    const origins = Array.isArray(state.origins) ? [...state.origins] : [];
+    for (const disk of kept) {
+        const at = origins.findIndex((o) => !!o && typeof o === "object" && o.origin === disk.origin);
+        if (at === -1)
+            origins.push({ origin: disk.origin, localStorage: [], indexedDB: disk.indexedDB });
+        else if (origins[at].indexedDB === undefined)
+            origins[at] = { ...origins[at], indexedDB: disk.indexedDB };
+    }
+    return { ...state, origins };
+}
+/**
+ * The lines an action's result carries for what the refresh broker did since
+ * the last action result (a write-back can finish after the action that
+ * started it): one line per kind of event, counted, in a fixed order. Counts only: no
+ * token, slot value or endpoint is named. Empty when it did nothing.
+ */
+export function refreshNotice(events) {
+    const count = (kind) => events.filter((e) => e === kind).length;
+    const times = (n) => (n > 1 ? ` (${n} times)` : "");
+    const lines = [];
+    const refreshed = count("refreshed");
+    if (refreshed > 0)
+        lines.push(`↻ token refreshed under the role's lock and stored in its profile${times(refreshed)}`);
+    const swapped = count("swapped");
+    if (swapped > 0)
+        lines.push(`↻ another session had rotated the role's token; loaded its profile and sent the current one${times(swapped)}`);
+    const learned = count("learned");
+    if (learned > 0)
+        lines.push(`↻ learned ${learned} endpoint${learned === 1 ? "" : "s"} that rotate${learned === 1 ? "s" : ""} the role's token; brokered from now on`);
+    const failed = count("failed");
+    if (failed > 0)
+        lines.push(`⚠ ${failed === 1 ? "a refresh" : `${failed} refreshes`} could not be brokered (see the action log)`);
+    return lines.map((l) => `\n${l}`).join("");
 }
 /**
  * The cookies a response's Set-Cookie headers set, by name. A header value may

package/dist/engine/replay.js

@@ -19,8 +19,16 @@
  * escaping and the grouping are table-tested.
  */
 import path from "node:path";
+import { isSafeRelativePath } from "./plain.js";
 /** Most frames one recorded session keeps. A long run is thousands of actions, and a project folder is not a video store. */
 export const RECORD_MAX_FRAMES = 600;
+/** A name reduced to one plain path segment: letters, digits, dot, dash and underscore, never leading with a dot or dash. */
+export function plainSegment(text, fallback) {
+    return (text
+        .replace(/[^a-z0-9._-]+/gi, "-")
+        .replace(/^[.-]+/, "")
+        .slice(0, 60) || fallback);
+}
 /**
  * Where a recorded frame is stored, relative to the memory directory — and
  * the path the live view serves it at, so it is always written with forward
@@ -29,11 +37,7 @@ export const RECORD_MAX_FRAMES = 600;
  * nothing about where the engine writes.
  */
 export function framePath(session, index, action) {
-    const plain = (text, fallback) => text
-        .replace(/[^a-z0-9._-]+/gi, "-")
-        .replace(/^[.-]+/, "")
-        .slice(0, 60) || fallback;
-    return `recordings/${plain(session, "session")}/${String(index).padStart(4, "0")}-${plain(action, "step")}.jpg`;
+    return `recordings/${plainSegment(session, "session")}/${String(index).padStart(4, "0")}-${plainSegment(action, "step")}.jpg`;
 }
 /**
  * The file a viewer's frame request names, or null when it is not one of this
@@ -136,9 +140,18 @@ export function evidenceFor(steps, foundAt, most = 4) {
         frame: x.frame,
     }));
 }
+/** A finding's own picture, shown open under it: the evidence a reader looks for first. */
+function renderPicture(p, id, framePrefix = "", savedAt = "") {
+    const src = escapeHtml(framePrefix + p.file);
+    return (`<figure class="picture"><a class="frame" href="${src}" target="_blank" rel="noreferrer" data-testid="finding-picture-open" data-finding="${escapeHtml(id)}">` +
+        `<img loading="lazy" ${GONE} src="${src}"${p.width && p.height ? ` width="${p.width}" height="${p.height}"` : ""} alt="What the finding is about, when it was filed">` +
+        `<p class="gone-note">This picture is not beside this file. Pictures live in the run's <code>recordings/</code> folder, which travels with it.</p></a>` +
+        `<figcaption>${escapeHtml(p.caption)}${savedAt ? `<span class="onDisk">${escapeHtml(savedAt + "/" + p.file)}</span>` : ""}</figcaption></figure>`);
+}
 function renderEvidence(e, framePrefix = "", savedAt = "") {
+    const picture = e.picture ? renderPicture(e.picture, e.id, framePrefix, savedAt) : "";
     if (e.frames.length === 0)
-        return "";
+        return picture;
     const shots = e.frames
         .map((f) => `<figure><img loading="lazy" ${GONE} src="${escapeHtml(framePrefix + f.frame)}" alt="The page when this step ran">` +
         `<p class="gone-note">This frame is not beside this file. Frames live in the run's <code>recordings/</code> folder, which travels with it.</p>` +
@@ -146,8 +159,10 @@ function renderEvidence(e, framePrefix = "", savedAt = "") {
         (savedAt ? `<span class="onDisk">${escapeHtml(savedAt + "/" + f.frame)}</span>` : "") +
         `</figcaption></figure>`)
         .join("");
-    return `<details class="evidence"><summary>Evidence — the ${e.frames.length} step${e.frames.length === 1 ? "" : "s"} on screen before this was filed</summary><div class="shots">${shots}</div></details>`;
+    return `${picture}<details class="evidence"><summary>Evidence — the ${e.frames.length} step${e.frames.length === 1 ? "" : "s"} on screen before this was filed</summary><div class="shots">${shots}</div></details>`;
 }
+/** The report's sections the header links to, by heading. */
+const SECTION_ANCHORS = { "In plain words": "plain", "Technical detail": "technical" };
 /**
  * The report's markdown as elements. A deliberately small subset — headings,
  * tables, lists, code fences, the report's own <details> repro blocks — built
@@ -184,12 +199,28 @@ export function renderMarkdown(md, evidence = [], framePrefix = "", savedAt = ""
         else if ((m = /^(#{1,6}) (.*)$/.exec(line))) {
             flush();
             const level = Math.min(6, m[1].length + 1);
-            out.push(`<h${level}>${inline(m[2])}</h${level}>`);
+            // The two parts of the report are what the header links to.
+            const anchor = m[1] === "##" ? SECTION_ANCHORS[m[2]] : undefined;
+            out.push(`<h${level}${anchor ? ` id="${anchor}"` : ""}>${inline(m[2])}</h${level}>`);
+            i += 1;
+        }
+        else if ((m = /^!\[([^\]]*)\]\(([^)\s]+)\)$/.exec(line))) {
+            // A finding's picture. The path is the report's own, relative to the run's
+            // folder, and anything else (a scheme, an absolute path, `..`) is dropped.
+            flush();
+            if (isSafeRelativePath(m[2])) {
+                const src = (m[2].startsWith("recordings/") ? framePrefix : "") + m[2];
+                out.push(`<figure class="picture"><a href="${escapeHtml(src)}" target="_blank" rel="noreferrer" data-testid="report-picture-open"><img loading="lazy" ${GONE} src="${escapeHtml(src)}" alt="${escapeHtml(m[1])}"></a>` +
+                    `<p class="gone-note">This picture is not beside this file. It lives in the run's folder, which travels with it.</p>` +
+                    (savedAt ? `<span class="onDisk">${escapeHtml(savedAt + "/" + m[2])}</span>` : "") +
+                    `</figure>`);
+            }
             i += 1;
         }
         else if ((m = /^<details><summary>(.*)<\/summary>$/.exec(line))) {
             flush();
-            out.push(`<details><summary>${inline(m[1])}</summary>`);
+            const testid = m[1] === "Technical detail" ? "report-technical-toggle" : "report-details-toggle";
+            out.push(`<details><summary data-testid="${testid}">${inline(m[1])}</summary>`);
             i += 1;
         }
         else if (/^<\/details>$/.test(line)) {
@@ -298,6 +329,10 @@ ol.steps { list-style:none; margin:0; padding:0; }
 .step .d { color:var(--muted); overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
 .step .frame { display:block; margin:4px 0 10px; }
 .step .frame img { max-width:min(100%,720px); max-height:360px; object-fit:cover; object-position:top; border:1px solid var(--line); border-radius:6px; display:block; }
+figure.picture { margin:6px 0 14px; max-width:min(100%,720px); }
+figure.picture img { max-width:100%; height:auto; border:1px solid var(--line); border-radius:6px; display:block; background:var(--panel); }
+figure.picture figcaption { margin-top:4px; color:var(--muted); font-size:12px; }
+figure.picture figcaption .onDisk { display:block; font:11px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; overflow-wrap:anywhere; }
 details.evidence { margin:6px 0 18px; padding:8px 12px; background:var(--panel); border:1px solid var(--line); border-radius:8px; }
 details.evidence > summary { cursor:pointer; color:var(--muted); font-size:13px; }
 details.evidence .shots { display:flex; flex-wrap:wrap; gap:14px; margin-top:12px; }
@@ -317,6 +352,11 @@ header .served code { font:11px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,m
 figure.gone .gone-note, a.gone .gone-note { display:block; }
 figure.gone img, a.gone img { display:none; }
 a.frame.gone { display:block; max-width:min(100%,720px); }
+figure.picture { margin:8px 0 14px; max-width:min(100%,720px); }
+figure.picture img { width:auto; max-width:100%; max-height:420px; border:1px solid var(--line); border-radius:6px; display:block; background:var(--panel); }
+details > summary { cursor:pointer; }
+details:not(.session):not(.evidence) { margin:4px 0 18px; padding:6px 12px; border:1px solid var(--line); border-radius:8px; background:var(--panel); }
+details:not(.session):not(.evidence) > summary { color:var(--muted); font-size:13px; }
 details.evidence figcaption { margin-top:4px; color:var(--muted); font:11px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; overflow-wrap:anywhere; }
 `;
 /**
@@ -366,6 +406,19 @@ function exitWatch(savedFile) {
         "  });\n" +
         "})();</script>");
 }
+/** The header's links: the report's parts it holds, then the steps. */
+function navLinks(markdown) {
+    const has = (heading) => markdown.split("\n").includes(`## ${heading}`);
+    return [
+        has("In plain words")
+            ? `<a href="#plain" data-testid="report-plain-link">In plain words</a>`
+            : `<a href="#report" data-testid="report-top-link">Report</a>`,
+        has("Technical detail") ? `<a href="#technical" data-testid="report-technical-link">Technical detail</a>` : "",
+        `<a href="#steps" data-testid="report-steps-link">Steps</a>`,
+    ]
+        .filter(Boolean)
+        .join("");
+}
 /** The whole document: one file, no external assets, opens from the file system. */
 export function buildReplayHtml(input) {
     const framed = input.sessions.some((s) => s.steps.some((x) => x.frame));
@@ -385,7 +438,7 @@ export function buildReplayHtml(input) {
   <h1>SceneScout run</h1>
   <span class="meta">${escapeHtml(input.project)} · written ${escapeHtml(stamp(input.at))}${input.version ? ` · v${escapeHtml(input.version)}` : ""}</span>
   ${savedAt ? `<p class="served">This page is served by the engine and goes when it does. The copy that stays is <code>${escapeHtml(savedAt)}/report.html</code>, beside the frames it shows.</p>` : ""}
-  <nav><a href="#report">Report</a><a href="#steps">Steps</a></nav>
+  <nav>${navLinks(input.markdown)}</nav>
 </header>
 ${savedAt
         ? `<div id="gone-bar" role="alert" data-testid="run-engine-gone" hidden>