scenescout 3.14.1 → 3.16.0

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 } : {}),
         },
     };
 }

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/provider.js

@@ -3,7 +3,8 @@ export class MalformedReply extends Error {
 }
 /** The most output one model call may produce. Large enough for a plan of steps; small enough that one reply cannot spend the budget. */
 export const MAX_OUTPUT_TOKENS = 16_000;
-const obj = (v) => (v && typeof v === "object" && !Array.isArray(v) ? v : null);
+/** A plain object as a record, or null for anything else (an array, null, a string). */
+export const obj = (v) => (v && typeof v === "object" && !Array.isArray(v) ? v : null);
 const num = (v) => (typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : 0);
 function parseArgs(raw) {
     if (raw === undefined || raw === null || raw === "")
@@ -31,7 +32,7 @@ export class AnthropicConversation {
             headers: { "content-type": "application/json", "x-api-key": key, "anthropic-version": "2023-06-01" },
             body: {
                 model: this.o.model,
-                max_tokens: MAX_OUTPUT_TOKENS,
+                max_tokens: this.o.maxOutputTokens ?? MAX_OUTPUT_TOKENS,
                 // The method and the tools are the same on every call: cached once, read back at a tenth of the price.
                 system: [{ type: "text", text: this.o.system, cache_control: { type: "ephemeral" } }],
                 tools: this.o.tools.map((t) => ({ name: t.name, description: t.description, input_schema: t.parameters })),
@@ -102,7 +103,7 @@ export class OpenAIConversation {
                 input: this.input,
                 tools: this.o.tools.map((t) => ({ type: "function", name: t.name, description: t.description, parameters: t.parameters, strict: false })),
                 reasoning: { effort: this.o.effort },
-                max_output_tokens: MAX_OUTPUT_TOKENS,
+                max_output_tokens: this.o.maxOutputTokens ?? MAX_OUTPUT_TOKENS,
                 // Stateless: nothing of the tested app is kept on the provider's side
                 // between calls, and the reasoning comes back encrypted so it can be
                 // handed back with the rest of the turn.