scenescout 3.15.0 → 3.17.0

package/dist/engine/policy.js

@@ -5,7 +5,12 @@
  */
 const DESTRUCTIVE_PATTERNS = [
     /\bdelete\b/i,
-    /\bremove\b/i,
+    // "Remove" a filter chip drops a condition from the view: "Remove Status:
+    // Open filter" re-queries the list, the same sense the reset rule exempts.
+    // A label whose object, at its end, is a filter or a chip, or a test id with
+    // the chip before the verb ("filter-remove"), is exempt; "Remove member",
+    // and "Remove member. Use the filter to find others.", still count.
+    /(?<!\b(?:filters?|chips?)[\s-]{1,3})\bremove\b(?![^\n]{0,60}?\b(?:filters?|chips?)\W*$)/i,
     /\brevoke\b/i,
     /\bdestroy\b/i,
     /\bpurge\b/i,
@@ -20,13 +25,23 @@ const DESTRUCTIVE_PATTERNS = [
     // view/form senses; everything else ("Reset workspace", "Factory reset",
     // "Reset all data") still counts.
     /\breset\b(?!\s+(filters?|zoom|search|view|sort|order|form|password|layout|columns?|selection|preferences?|defaults?))/i,
-    /\bdiscard\b/i,
+    // "Discard" names two different things. "Discard changes", "Discard your
+    // edits" and "Discard unsaved changes" drop what the tester typed and has not
+    // sent: no record exists to lose, and refusing it left a session stuck on a
+    // dirty form behind the app's own leave-confirmation. Those senses are
+    // exempt, written as words or as a test id ("discard-changes"); "Discard
+    // draft", "Discard record" and a bare "Discard" still count.
+    // If the confirm does send a write, the wire policy judges that request as it
+    // judges any other, and `discard` is a destructive verb in a path there.
+    /\bdiscard\b(?![\s_-]+(?:(?:your|my|all|the|any)[\s_-]+)?(?:unsaved[\s_-]+|pending[\s_-]+|local[\s_-]+|draft[\s_-]+)?(?:changes|edits)\b)/i,
     /\bcancel subscription\b/i,
-    // The verb: a control that signs the user off, alone or after another verb
-    // ("Save and sign off"). The noun is how approval apps label things, and it
-    // is told by the word before it ("Needs sign-off", "Awaiting sign-off",
-    // "Send for sign-off"); those destroy nothing. Same shape as the reset rule.
-    /(?<!\b(?:needs?|awaiting|awaits|pending|requires?|required|for|before|after|without|of|the|a|an|its|their|your|my)\s)\bsign(?: |-)?off\b/i,
+    // The verb: a control that signs the user off, starting the label ("Sign
+    // off", "(Sign off)", a test id "sign-off-button") or joined to another verb
+    // ("Save and sign off", "Save & sign off"). Anywhere else it is the noun
+    // approval apps label things with ("Needs sign-off", "Manager sign-off",
+    // "Final sign-off recorded"), which destroys nothing. Told by position, not
+    // by a list of the words that may come before it: any modifier can.
+    /(?:^[^\p{L}\p{N}]*|\b(?:and|then)\s+|&\s*)sign(?: |-)?off\b/iu,
     // The tool is generic — destructive labels come in many languages.
     /\b(eliminar|borrar|suprimir)\b/i, // es
     /\b(excluir|apagar|remover)\b/i, // pt
@@ -55,7 +70,7 @@ const DESTRUCTIVE_PATTERNS = [
  * destructive. So the body is matched only for STRUCTURED destructive intent.
  */
 /** A destructive verb occupying a URL PATH segment. Bare keywords are meaningful here — a path is not prose. */
-const DESTRUCTIVE_URL_RE = /(\/|\b|_)(delete|remove|purge|destroy|archive|revoke|deactivate|wipe|bulk[-_]?delete|force[-_]?delete)(\/|\b|_)/i;
+const DESTRUCTIVE_URL_RE = /(\/|\b|_)(delete|remove|purge|destroy|archive|revoke|deactivate|wipe|discard|bulk[-_]?delete|force[-_]?delete)(\/|\b|_)/i;
 /**
  * Structured destructive intent inside a body — never a bare keyword.
  * Two shapes: (a) a GraphQL destructive mutation (the 200-char window after
@@ -72,7 +87,7 @@ const DESTRUCTIVE_URL_RE = /(\/|\b|_)(delete|remove|purge|destroy|archive|revoke
  * and `verb` are not in the key list at all — they read as prose far more often
  * than as command fields.
  */
-const DESTRUCTIVE_BODY_RE = /\bmutation\b[\s\S]{0,200}?\b(?:delete|remove|archive|destroy|purge|revoke)[A-Za-z_]|(?:^|[{,[\s]*["']|[?&])\s*(?:action|operation|op|method|_method|command|cmd)["']?\s*[:=]\s*["']?(?:delete|remove|purge|destroy|archive|revoke|deactivate|wipe)\b/i;
+const DESTRUCTIVE_BODY_RE = /\bmutation\b[\s\S]{0,200}?\b(?:delete|remove|archive|destroy|purge|revoke)[A-Za-z_]|(?:^|[{,[\s]*["']|[?&])\s*(?:action|operation|op|method|_method|command|cmd)["']?\s*[:=]\s*["']?(?:delete|remove|purge|destroy|archive|revoke|deactivate|wipe|discard)\b/i;
 export function isDestructiveWire(url, body) {
     return DESTRUCTIVE_URL_RE.test(url) || (!!body && DESTRUCTIVE_BODY_RE.test(body.slice(0, 2000)));
 }
@@ -128,11 +143,226 @@ export function isDestructive(...labels) {
         });
     });
 }
+/** The most words a click target's own text may have and still be read as its command. */
+export const COMMAND_TEXT_WORDS = 4;
+/** A short verb phrase, or null: at most COMMAND_TEXT_WORDS words and no sentence. */
+function commandText(text) {
+    const words = text.trim().split(/\s+/).filter(Boolean);
+    return words.length > 0 && words.length <= COMMAND_TEXT_WORDS && !SENTENCE_RE.test(text) ? text : null;
+}
+/** Roles whose accessible name is the label of the one thing a click does. */
+const LABELLED_CONTROL_ROLES = new Set([
+    "button",
+    "link",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "tab",
+    "option",
+    "checkbox",
+    "radio",
+    "switch",
+    "treeitem",
+    "image",
+]);
+/**
+ * The label that makes a listed element destructive, or null. A control is
+ * judged by its OWN name, never by what it merely contains:
+ *
+ * - A button, link, menu item, tab or option (by tag or by role) is named
+ *   by what it does, and that name is judged whole, however long: a button
+ *   "Delete all my saved data" is refused. The word cap below is only for
+ *   containers, whose text is the record they show.
+ * - A dropdown (a `<select>`, a combobox, a listbox) is named by its options,
+ *   all of them, so a filter offering "All, Create, Update, Delete" read as a
+ *   delete control and choosing "Create" was refused. Choosing is judged where
+ *   the value is known: scout_select vets the chosen option, and an option
+ *   clicked in a custom list is a control of its own. Only its test id, and a
+ *   control covering its centre, are judged here.
+ * - Anything else (a row, a card, a heading, a panel listed for its test id
+ *   or a click handler) is judged by its test id and by the control covering
+ *   its centre, where a click on it lands: a row whose middle IS a delete
+ *   button is still refused, and the buttons inside it are listed, and
+ *   refused, on their own. Its text is the record it shows ("Archive Test
+ *   Widget", "Final sign-off recorded"), not a command, so the text counts
+ *   only for a click target whose own text is a short verb phrase
+ *   (COMMAND_TEXT_WORDS words, no sentence): a clickable div saying "Delete".
+ *   A heading is never judged by its text.
+ *
+ * When the page could not say what the own text is, the whole name stands in
+ * and is judged whole, so a reading that failed can only refuse more.
+ */
+export function destructiveLabelOf(c) {
+    const first = (...labels) => labels.find((l) => typeof l === "string" && l.length > 0 && isDestructive(l)) ?? null;
+    const centre = c.centre ?? [];
+    if (c.tag === "select" || c.role === "combobox" || c.role === "listbox")
+        return first(c.testid, ...centre);
+    if (LABELLED_CONTROL_ROLES.has(c.role) || c.tag === "button" || c.tag === "a")
+        return first(c.name, c.testid);
+    if (c.role === "heading" || /^h[1-6]$/i.test(c.tag))
+        return first(c.testid, ...centre);
+    const own = c.ownText == null ? c.name : c.interactive === false ? null : commandText(c.ownText);
+    return first(own, c.testid, ...centre);
+}
+/**
+ * A dropdown pick, judged by the value asked for, the dropdown's test id and
+ * the label of the option it matches. The dropdown's own name is not judged
+ * (destructiveLabelOf), so this is the check, and a label that could not be
+ * read (null) refuses: an unvetted pick could be "Delete".
+ */
+export function pickIsDestructive(value, testid, optionLabel) {
+    return optionLabel === null || isDestructive(value, testid, optionLabel);
+}
 export function destructiveRefusal(label, mode = "read-only") {
     return (`REFUSED by ${mode} policy: "${label}" matches a destructive-action pattern. ` +
         `This run is ${mode}; do not attempt this element again. If destructive flows must be tested, ` +
         `the user has to re-attach with mode="destructive" against a disposable/seeded environment.`);
 }
+/** The `why` of a page move refused as a possible escape from a foreign frame's sandbox. */
+export const ESCAPE_REFUSAL = "a possible frame escape";
+/** New blocked endpoints listed by name in one notice; the rest are counted. */
+export const BLOCK_NOTICE_LIST = 5;
+/** What a blocked write is remembered by: its method and URL, without query or fragment. */
+export function blockSignature(sig) {
+    return sig.replace(/[?#].*$/, "");
+}
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+/**
+ * The write-policy block notice, said once. A page that beacons to a
+ * monitoring endpoint on every load had every tool result open with the same
+ * blocked request five times over and the whole explanation after it, which
+ * buried the action's own result and the blocks that mattered.
+ *
+ * So a session remembers what it has been told. Each endpoint (by
+ * blockSignature, per write rule) is named in full the first time it is
+ * blocked; after that it is counted on one line. The explanation is given in
+ * full once per rule, and later notices for a new endpoint refer back to it.
+ * Nothing about the blocking changes: every request is still refused, and
+ * every refusal is still reported, if only as a count.
+ */
+export class BlockNotices {
+    seen = new Set();
+    explained = new Set();
+    /** Forget everything said: a re-attached session starts a new conversation. */
+    reset() {
+        this.seen.clear();
+        this.explained.clear();
+    }
+    /**
+     * The notice for the writes refused since the last action, or "" when there
+     * were none. `createdCount` is how many records this run has created, which
+     * the safe-write advice names.
+     */
+    notice(rule, blocked, createdCount = 0) {
+        if (blocked.length === 0)
+            return "";
+        const groups = new Map();
+        for (const b of blocked) {
+            const key = blockSignature(b.sig);
+            const g = groups.get(key);
+            if (g) {
+                g.count += 1;
+                g.allLate &&= b.late;
+                g.answered ||= !!b.answered;
+                if (b.why)
+                    g.whys.add(b.why);
+            }
+            else
+                groups.set(key, { first: b, count: 1, allLate: b.late, answered: !!b.answered, whys: new Set(b.why ? [b.why] : []) });
+        }
+        const fresh = [];
+        const repeats = [];
+        for (const [key, g] of groups) {
+            const memo = `${rule} ${key}`;
+            if (this.seen.has(memo))
+                repeats.push([key, g]);
+            else {
+                this.seen.add(memo);
+                fresh.push([key, g]);
+            }
+        }
+        const late = (g) => (g.allLate ? " (late — likely from a previous action or background traffic)" : "");
+        const times = (g) => (g.count > 1 ? ` ×${g.count}` : "");
+        const repeatCount = repeats.reduce((n, [, g]) => n + g.count, 0);
+        const repeatLine = repeats.length === 0
+            ? ""
+            : `${plural(repeatCount, "repeat block")} of ${plural(repeats.length, "known endpoint")} (` +
+                repeats
+                    .slice(0, 3)
+                    .map(([key, g]) => `${key} ×${g.count}${g.allLate ? ", background" : ""}`)
+                    .join("; ") +
+                (repeats.length > 3 ? `; +${repeats.length - 3} more` : "") +
+                `)`;
+        const head = `\n🛡 WRITE-POLICY blocked (${rule}): `;
+        if (fresh.length === 0)
+            return `${head}${repeatLine}, refused as before. The tester's safety policy, not an app bug.`;
+        const list = fresh
+            .slice(0, BLOCK_NOTICE_LIST)
+            .map(([, g]) => `${g.first.sig}${times(g)}${late(g)}`)
+            .join("; ");
+        const more = fresh.length > BLOCK_NOTICE_LIST ? ` (+${fresh.length - BLOCK_NOTICE_LIST} more new)` : "";
+        const also = repeatLine ? `; also ${repeatLine}` : "";
+        const whys = new Set(fresh.flatMap(([, g]) => [...g.whys]));
+        const escaped = whys.delete(ESCAPE_REFUSAL);
+        const foreign = [...whys];
+        const answered = fresh.some(([, g]) => g.answered);
+        const reasons = (foreign.length > 0
+            ? `Refused because it was ${foreign.join("; ")}: it would reach a site embedded in the page rather than the app, which no mode but destructive allows. `
+            : "") +
+            (escaped
+                ? `A move of the whole page off the app, with no Referer, was refused: a frame that held another site now sits on a data: or blob: URL, where WebKit drops the frame's sandbox, so the move may be that frame's. No mode but destructive allows it. `
+                : "");
+        if (this.explained.has(rule)) {
+            return (`${head}${list}${more}${also}. The tester's safety policy, not an app bug (explained in full earlier in this session). ` +
+                reasons +
+                (answered ? `The page's request was answered with a 403 in the server's place, as before. ` : "")).trimEnd();
+        }
+        this.explained.add(rule);
+        return (`${head}${list}${more}${also}. ` +
+            `This is the tester's safety policy, NOT an app bug — do not file a finding for the resulting error UI. ` +
+            reasons +
+            (answered
+                ? `The page's own requests were answered with a 403 in the server's place, so the page's handling of a refusal is real: an error message is correct, and a success message is a false_success violation. `
+                : "") +
+            (rule === "observe"
+                ? `observe mode blocks every request that is not a GET, so no form submission reaches the server. Re-attach with mode="read-only" ONLY if the user confirms that ordinary form submissions are acceptable on this target. If a refused POST only reads (a search or query sent as POST), the user can name it in readPosts instead; never add one yourself.`
+                : rule === "read-only"
+                    ? `Re-attach with mode="safe-write" to test create/edit flows, or "destructive" (user-approved disposable env only).`
+                    : `In safe-write, updates/deletes are only allowed on resources this session created (${createdCount} so far).`));
+    }
+}
+/**
+ * The answer to a native dialog. alert, confirm and prompt are dismissed in
+ * the modes that protect data (observe, read-only) and accepted otherwise, as
+ * before: a confirm can stand between a click and a delete.
+ *
+ * `beforeunload` is the page asking whether to leave while it holds unsent
+ * input. Leaving sends no write of its own, and whatever the page sends as it
+ * goes is judged by the wire policy like any other request, but leaving does
+ * throw away what the tester typed. So it is the caller's choice: `leave: true`
+ * leaves, `leave: false` stays, and with no choice the mode decides, staying
+ * in observe and read-only. Either way the result says what happened (see
+ * dialogNote), because a dismissed one surfaced only as a bare ERR_ABORTED.
+ */
+export function dialogResponse(type, readOnly, leave) {
+    if (type === "beforeunload")
+        return (leave ?? !readOnly) ? "accept" : "dismiss";
+    return readOnly ? "dismiss" : "accept";
+}
+/** The line an action's result carries for a native dialog the page opened during it. */
+export function dialogNote(d) {
+    const message = d.message.trim().replace(/\s+/g, " ").slice(0, 120);
+    if (d.type === "beforeunload") {
+        return d.response === "dismiss"
+            ? `\n⚠ LEAVE CONFIRMATION: the page asked to confirm leaving (it holds input that was never sent), and the engine answered "stay"` +
+                `${d.leave === false ? " as asked (leave: false)" : ""}, so the navigation was cancelled and the page is unchanged. ` +
+                `This is not an app bug, and nothing was sent. To leave and discard that unsent input, repeat the action with leave: true.`
+            : `\nℹ LEAVE CONFIRMATION: the page asked to confirm leaving (it held input that was never sent), and the engine answered "leave"` +
+                `${d.leave === true ? " as asked (leave: true)" : ""}, so that unsent input is discarded. ` +
+                `Any request the page sends as it is left is judged by the write policy like any other.`;
+    }
+    return `\nℹ DIALOG (${d.type})${message ? `: "${message}"` : ""} — ${d.response === "accept" ? "accepted" : "dismissed"} by the engine.`;
+}
 export const WRITE_MODES = ["observe", "read-only", "safe-write", "destructive"];
 /** The stricter of two modes: WRITE_MODES runs from the strictest to the loosest. */
 export function stricterMode(a, b) {
@@ -572,6 +802,146 @@ export const FOREIGN_FRAME_SANDBOX = "sandbox allow-scripts allow-forms allow-sa
 export function withForeignFrameSandbox(existing) {
     return existing && existing.trim() ? `${existing}, ${FOREIGN_FRAME_SANDBOX}` : FOREIGN_FRAME_SANDBOX;
 }
+/** The most POST endpoints a session may name as reads. */
+export const MAX_READ_POSTS = 20;
+/** The environment variable naming POST endpoints that only read, for every surface that attaches. A `readPosts` option wins over it. */
+export const READ_POSTS_ENV = "SCENESCOUT_READ_POSTS";
+/**
+ * The POST endpoints a session was told only read, from the `readPosts`
+ * option, else the environment variable (entries separated by commas or new
+ * lines). Nothing by default: observe refuses every POST until the user names
+ * one, and the agent must never add one itself.
+ */
+export function readPostsSetting(option, env) {
+    if (option !== undefined)
+        return [...option];
+    return (env ?? "")
+        .split(/[,\n]/)
+        .map((e) => e.trim())
+        .filter(Boolean);
+}
+/**
+ * The entries parsed, and what was given that is not one. An entry is
+ * `POST <path>` for the app's own origin, or `POST <http(s) URL>` for an API
+ * on another origin: the method must be POST, the path must start with `/`
+ * and carry no query or fragment, and `*` may stand only for one whole path
+ * segment, such as an id. Exact otherwise, so nothing is widened by accident;
+ * a trailing slash is ignored.
+ */
+export function readPostEntries(list) {
+    const entries = [];
+    const rejected = [];
+    const overflow = [];
+    for (const raw of list) {
+        const m = /^\s*POST\s+(\S+)\s*$/i.exec(raw);
+        if (!m) {
+            rejected.push(raw);
+            continue;
+        }
+        let origin = null;
+        let pathname = m[1];
+        if (/^https?:\/\//i.test(pathname)) {
+            let u;
+            try {
+                u = new URL(pathname);
+            }
+            catch {
+                rejected.push(raw);
+                continue;
+            }
+            if (u.search || u.hash || u.username || u.password || /[?#]/.test(pathname)) {
+                rejected.push(raw);
+                continue;
+            }
+            origin = u.origin;
+            // The path as written: URL would percent-encode a `*`.
+            const slash = pathname.indexOf("/", pathname.indexOf("//") + 2);
+            pathname = slash === -1 ? "/" : pathname.slice(slash);
+        }
+        const segments = pathname.split("/").filter(Boolean);
+        if (!pathname.startsWith("/") || /[?#\s]/.test(pathname) || segments.some((seg) => seg.includes("*") && seg !== "*")) {
+            rejected.push(raw);
+            continue;
+        }
+        const entry = `POST ${origin ?? ""}${"/" + segments.join("/")}`;
+        if (entries.some((e) => e.entry === entry))
+            continue;
+        if (entries.length < MAX_READ_POSTS)
+            entries.push({ entry, origin, segments });
+        else
+            overflow.push(raw);
+    }
+    return { entries, rejected, overflow };
+}
+/** The entry a POST to `url` matches, or null. An entry with no origin matches the app's own origin only. */
+export function matchReadPost(entries, appUrl, url) {
+    let target;
+    let app;
+    try {
+        target = new URL(url);
+        app = new URL(appUrl).origin;
+    }
+    catch {
+        return null;
+    }
+    const segments = target.pathname.split("/").filter(Boolean);
+    return (entries.find((e) => (e.origin ?? app) === target.origin && e.segments.length === segments.length && e.segments.every((seg, i) => seg === "*" || seg === segments[i])) ?? null);
+}
+/** The longest body read for a GraphQL operation; a longer one cannot be vetted and is refused. */
+export const MAX_READ_POST_BODY = 100_000;
+/** A GraphQL operation that writes: `mutation` or `subscription`, then an optional name, then its variables, directives or selection. */
+const GRAPHQL_WRITE_OP_RE = /(?:^|[^A-Za-z0-9_$])(?:mutation|subscription)\s*(?:[A-Za-z_][A-Za-z0-9_]*\s*)?[({@]/;
+/**
+ * Whether a body carries a GraphQL operation that is not a query, or one that
+ * cannot be read. Read from the body as sent, from every `query` string in a
+ * JSON body (or a batch of them), so an escaped newline cannot hide the
+ * keyword, and from a form-encoded `query` field. A persisted query (a hash
+ * and no text) counts, since its operation is unknown. A search box's text
+ * ("mutation testing") is not an operation and does not match.
+ */
+export function graphqlWriteOperation(body) {
+    if (GRAPHQL_WRITE_OP_RE.test(body))
+        return true;
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        // A form-encoded body: its `query` field, decoded.
+        const query = /(?:^|&)query=/.test(body) ? new URLSearchParams(body).get("query") : null;
+        return query !== null && GRAPHQL_WRITE_OP_RE.test(query);
+    }
+    const items = Array.isArray(parsed) ? parsed : [parsed];
+    return items.some((item) => {
+        if (typeof item !== "object" || item === null)
+            return false;
+        const { query, extensions } = item;
+        if (typeof query === "string")
+            return GRAPHQL_WRITE_OP_RE.test(query);
+        // A persisted query names its operation by hash alone, so what it runs cannot be read: refused.
+        return typeof extensions === "object" && extensions !== null && extensions.persistedQuery !== undefined;
+    });
+}
+/**
+ * The entry that lets this POST out of observe, or null. Only in observe:
+ * read-only and safe-write already let a POST out unless it looks
+ * destructive, and destructive lets everything out. Even a listed endpoint is
+ * refused when its path or body looks destructive (the whole body is read),
+ * when its body is a GraphQL mutation, subscription or persisted query, or
+ * when the body is too long to vet.
+ */
+export function readPostAllowed(input) {
+    if (input.mode !== "observe" || input.method !== "POST" || input.destructiveWire || input.entries.length === 0)
+        return null;
+    const entry = matchReadPost(input.entries, input.appUrl, input.url);
+    if (!entry)
+        return null;
+    const body = input.body ?? "";
+    // The whole body, not the first 2000 characters isDestructiveWire reads: a command after a long filter still counts.
+    if (body.length > MAX_READ_POST_BODY || DESTRUCTIVE_BODY_RE.test(body) || graphqlWriteOperation(body))
+        return null;
+    return entry;
+}
 export function allowsWrite(mode, method, destructiveWire, owned) {
     if (mode === "destructive")
         return true;

package/dist/engine/probes.js

@@ -1,4 +1,4 @@
-import { DIALOG_LIKE_SEL } from "./collector.js";
+import { ACCESSIBLE_NAME_SRC, DIALOG_LIKE_SEL } from "./collector.js";
 import { focusAdvanceKey, isBrowserEngine } from "../browsers.js";
 /**
  * Scroll ONE named region rather than the page. The page-level heuristic
@@ -267,7 +267,8 @@ export async function probeFocusIndicators(page) {
         el.setAttribute("data-scout-focus-probe", "${i}");
         const s = getComputedStyle(el);
         const tid = el.getAttribute("data-testid");
-        const name = ((el.textContent || el.getAttribute("aria-label") || "").trim().replace(/\\s+/g, " ").slice(0, 30));
+        // Named as the snapshot names it, so an icon button reads by its aria-label here too.
+        const name = (${ACCESSIBLE_NAME_SRC})(el).slice(0, 30);
         return { label: tid ? "[" + tid + "]" : "<" + el.tagName.toLowerCase() + "> " + JSON.stringify(name), focused: ${styleSig} };
       })()`));
             if (info === null || info === "wrapped")

package/dist/engine/profiles.js

@@ -22,6 +22,7 @@ import path from "node:path";
 import { BROWSER_ENGINES } from "../browsers.js";
 import { MEMORY_DIRNAME, writeSelfIgnore } from "./memory.js";
 import { SCRIPT_FLAGS } from "./scripted-login.js";
+import { SAVE_MODES } from "./signed-in.js";
 /** The directory under .scenescout/ that holds one file per role. */
 export const AUTH_DIRNAME = "auth";
 /** Owner read/write only: a profile is a live session. */
@@ -279,14 +280,36 @@ export function permissionNote(file, mode, platform = process.platform) {
         return null;
     return `The profile at ${file} can be read by other accounts on this machine (mode ${(mode & 0o777).toString(8)}); it holds a live session. Tighten it: chmod 600 "${file}"`;
 }
-/** The command that records a role's profile, with the URL when it is known. */
-export function loginCommand(role, url) {
-    return `scenescout login ${url ?? "<url>"} --role ${role}`;
+/** One argument quoted for the platform's usual shell: double quotes on Windows, single quotes elsewhere. */
+export function shellQuote(value, platform = process.platform) {
+    if (platform === "win32")
+        return `"${value.replace(/"/g, '""')}"`;
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * The command that records a role's profile, with the URL when it is known,
+ * and `--project` when the profile must go somewhere other than the folder
+ * the command is run from (a project folder SceneScout chose itself).
+ */
+export function loginCommand(role, url, project, platform = process.platform) {
+    return `scenescout login ${url ?? "<url>"} --role ${role}${project ? ` --project ${shellQuote(project, platform)}` : ""}`;
+}
+/**
+ * The command that records a role's profile again for a session: with
+ * `--project` only when SceneScout chose the session's folder itself
+ * (`projectChosen`), since the command otherwise saves into the folder it is
+ * run from and the next attach would not find it. Used by a refusal for a
+ * missing role and by every hint for an expired one.
+ */
+export function reloginCommand(opts) {
+    return loginCommand(opts.role, opts.url, opts.projectChosen ? opts.projectDir : undefined, opts.platform);
 }
 /**
  * Turn scout_attach's `role` and `storageStatePath` into the one storage state
  * the session loads. Both at once is refused rather than letting one win
- * silently. A missing profile names the command that records it.
+ * silently. A missing profile names the command that records it, with
+ * `--project` when SceneScout chose the folder (`projectChosen`), so the
+ * command saves where the next attach looks.
  */
 export function resolveAttachAuth(opts, exists = fs.existsSync, listRoles = listProfiles) {
     if (opts.role !== undefined && opts.storageStatePath !== undefined) {
@@ -305,7 +328,7 @@ export function resolveAttachAuth(opts, exists = fs.existsSync, listRoles = list
             catch {
                 /* the list is a hint in the message; the refusal stands without it */
             }
-            throw new Error(`no sign-in is saved for role "${checked.role}" in this project. Run \`${loginCommand(checked.role, opts.url)}\`, sign in in the window it opens, then attach again.` +
+            throw new Error(`no sign-in is saved for role "${checked.role}" in this project. Run \`${reloginCommand({ role: checked.role, url: opts.url, projectDir: opts.projectDir, projectChosen: opts.projectChosen, platform: opts.platform })}\` (or, from a conversation, scout_login { role: "${checked.role}" }), sign in in the window it opens, then attach again.` +
                 (saved.length > 0 ? ` Saved roles: ${saved.join(", ")}.` : ""));
         }
         return { kind: "role", role: checked.role, storageStatePath: file };
@@ -322,11 +345,14 @@ export function roleLabel(auth) {
         return path.basename(auth.storageStatePath).replace(/\.json$/i, "");
     return "anonymous";
 }
-export const LOGIN_OPTION_NAMES = ["role", "project", "browser"];
+export const LOGIN_OPTION_NAMES = ["role", "project", "browser", "save"];
+/** Of the `--script` flags, those the window reads too. */
+const WINDOW_SCRIPT_FLAGS = new Set(["success-url"]);
 /**
  * Parse `scenescout login <url> --role <name> [--project dir] [--browser engine]
- * [--script [--success-url …] [--timeout s] …]`. `--script` takes no value; the
- * flags only it reads are refused without it.
+ * [--save auto|enter] [--success-url …] [--script [--timeout s] …]`. `--script`
+ * takes no value; the flags only it reads are refused without it, and `--save`,
+ * which only the window reads, is refused with it.
  */
 export function parseLoginArgs(args, cwd) {
     const positional = [];
@@ -354,8 +380,10 @@ export function parseLoginArgs(args, cwd) {
     const known = new Set(LOGIN_OPTION_NAMES);
     const scriptOnly = new Set(SCRIPT_FLAGS);
     for (const name of flags.keys()) {
-        if (scriptOnly.has(name) && !script)
+        if (scriptOnly.has(name) && !script && !WINDOW_SCRIPT_FLAGS.has(name))
             return { ok: false, error: `--${name} only applies with --script` };
+        if (name === "save" && script)
+            return { ok: false, error: "--save applies to the window, not to --script, which saves once its sign-in succeeds" };
         if (!known.has(name) && !scriptOnly.has(name))
             return { ok: false, error: `unknown option --${name}` };
     }
@@ -379,6 +407,12 @@ export function parseLoginArgs(args, cwd) {
     if (browser !== undefined && !BROWSER_ENGINES.includes(browser)) {
         return { ok: false, error: `--browser must be one of ${BROWSER_ENGINES.join(", ")}` };
     }
+    const save = flags.get("save");
+    if (save !== undefined && !SAVE_MODES.includes(save))
+        return { ok: false, error: `--save must be one of ${SAVE_MODES.join(", ")}` };
+    const successUrl = flags.get("success-url");
+    if (successUrl !== undefined && successUrl.trim() === "")
+        return { ok: false, error: "--success-url needs a value" };
     return {
         ok: true,
         options: {
@@ -387,6 +421,8 @@ export function parseLoginArgs(args, cwd) {
             projectDir: path.resolve(cwd, flags.get("project") ?? "."),
             ...(browser ? { browser: browser } : {}),
             ...(script ? { script: new Map([...flags].filter(([name]) => scriptOnly.has(name))) } : {}),
+            ...(save ? { save: save } : {}),
+            ...(!script && successUrl !== undefined ? { successUrl } : {}),
         },
     };
 }