sourcemonkey 0.0.0-stage → 0.5.0

package/lib/harness/browser-extensions.js

@@ -0,0 +1,285 @@
+// The userscript managers in a browser, and turning them on, off and
+// in: what `status`, a run's first lines and the `manager` commands
+// read and do.
+//
+// - Over a CDP WebSocket of sm-dev's own, since Playwright's browser
+//   session can't reach the hidden target used here.
+// - Listing, enabling and "Allow User Scripts" go through a hidden
+//   `chrome://extensions` target (no tab in the tab strip), calling
+//   the `chrome.developerPrivate` and `chrome.management` functions
+//   behind that page's own toggles. CDP has no calls of its own for
+//   them. No user gesture is needed.
+// - Loading an unpacked extension is CDP's `Extensions.loadUnpacked`,
+//   which works over a debugging port in Chrome and Chromium alike.
+import { quoted, WARNING_PREFIX } from './output-style.js';
+import { MANAGERS, MANAGER_NAMES, managerFlag } from './managers.js';
+import { sourceMonkeyExtensionId } from './extension-backend.js';
+// The browser's own WebSocket. Every send fails once `signal` aborts or
+// the socket closes, so nothing waits on a browser that's gone.
+async function openBrowserSocket(endpoint, signal) {
+    const aborted = new Promise((_, reject) => {
+        const fail = () => reject(new Error('The browser took too long to answer'));
+        if (signal.aborted)
+            fail();
+        else
+            signal.addEventListener('abort', fail);
+    });
+    aborted.catch(() => undefined);
+    const waiting = new Map();
+    const url = /^wss?:/.test(endpoint) ? endpoint
+        : (await Promise.race([fetch(`${endpoint}/json/version`, { signal }).then((r) => r.json()), aborted])).webSocketDebuggerUrl;
+    const open = new WebSocket(url);
+    let closed = false;
+    const settleAll = () => {
+        closed = true;
+        for (const answer of waiting.values())
+            answer({ error: { message: 'The connection to the browser closed' } });
+        waiting.clear();
+    };
+    try {
+        await Promise.race([
+            new Promise((resolve, reject) => {
+                open.onopen = resolve;
+                open.onerror = () => reject(new Error('The browser\'s CDP socket could not be opened'));
+            }),
+            aborted,
+        ]);
+    }
+    catch (err) {
+        open.close();
+        throw err;
+    }
+    open.onclose = settleAll;
+    let last = 0;
+    open.onmessage = (event) => {
+        const reply = JSON.parse(String(event.data));
+        waiting.get(reply.id)?.(reply);
+        waiting.delete(reply.id);
+    };
+    const send = async (method, params = {}, sessionId) => {
+        if (closed)
+            throw new Error(`${method} failed: The connection to the browser closed`);
+        const id = ++last;
+        const reply = await Promise.race([
+            new Promise((resolve) => {
+                waiting.set(id, resolve);
+                open.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
+            }),
+            aborted,
+        ]);
+        if (reply.error)
+            throw new Error(`${method} failed: ${reply.error.message}`);
+        return reply.result ?? {};
+    };
+    return {
+        send,
+        close: () => {
+            open.close();
+            settleAll();
+        },
+    };
+}
+// The browser's own WebSocket, open for `fn`, closed after. Throws when
+// it can't be reached, or `fn` takes longer than `timeoutMs`.
+async function withBrowserSocket(endpoint, timeoutMs, fn) {
+    const signal = AbortSignal.timeout(timeoutMs);
+    const aborted = new Promise((_, reject) => {
+        signal.addEventListener('abort', () => reject(new Error('The browser took too long to answer')));
+    });
+    aborted.catch(() => undefined);
+    const socket = await openBrowserSocket(endpoint, signal);
+    try {
+        return await Promise.race([fn(socket.send, signal), aborted]);
+    }
+    finally {
+        socket.close();
+    }
+}
+// A hidden target (no tab in the tab strip) at `url`, attached, once
+// `ready` (an expression) is true there. Not past `signal`, when every
+// call fails at once. Returns its evaluate and its target id.
+async function hiddenTarget(send, url, ready, signal) {
+    const { targetId } = await send('Target.createTarget', { url, hidden: true });
+    try {
+        const { sessionId } = await send('Target.attachToTarget', { targetId, flatten: true });
+        const evaluate = async (expression) => {
+            const reply = await send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }, sessionId);
+            if (reply.exceptionDetails) {
+                const { exception, text } = reply.exceptionDetails;
+                // A thrown string (as Violentmonkey's calls throw) has no description.
+                const why = exception?.description ?? (typeof exception?.value === 'string' ? exception.value : undefined) ?? text ?? 'It threw';
+                throw new Error(why.split('\n')[0]);
+            }
+            return reply.result?.value;
+        };
+        // The page's functions are there once it has loaded.
+        while (!await evaluate(ready).catch(() => false)) {
+            signal.throwIfAborted();
+            await new Promise((r) => setTimeout(r, 50));
+        }
+        return { evaluate, targetId };
+    }
+    catch (err) {
+        await send('Target.closeTarget', { targetId }).catch(() => undefined);
+        throw err;
+    }
+}
+// A hidden `chrome://extensions` target for `fn`'s calls, closed after.
+async function withExtensionsPage(endpoint, timeoutMs, fn) {
+    return withBrowserSocket(endpoint, timeoutMs, async (send, signal) => {
+        const { evaluate, targetId } = await hiddenTarget(send, 'chrome://extensions', 'typeof chrome?.developerPrivate?.getExtensionsInfo === "function"', signal);
+        try {
+            return await fn(evaluate);
+        }
+        finally {
+            await send('Target.closeTarget', { targetId }).catch(() => undefined);
+        }
+    });
+}
+/**
+ * Opens a hidden page at `url` in the browser at `endpoint`, once
+ * `ready` (an expression) is true there, for several calls. Throws when
+ * it isn't ready within `timeoutMs`.
+ */
+export async function openHiddenPage(endpoint, url, ready, timeoutMs = 10_000) {
+    const life = new AbortController();
+    const opening = AbortSignal.any([life.signal, AbortSignal.timeout(timeoutMs)]);
+    const socket = await openBrowserSocket(endpoint, life.signal);
+    let target;
+    try {
+        target = await Promise.race([
+            hiddenTarget(socket.send, url, ready, opening),
+            new Promise((_, reject) => opening.addEventListener('abort', () => reject(new Error('The page took too long to open')))),
+        ]);
+    }
+    catch (err) {
+        socket.close();
+        throw err;
+    }
+    return {
+        evaluate: async (expression, callMs = 30_000) => {
+            let timer;
+            try {
+                return await Promise.race([
+                    target.evaluate(expression),
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => reject(new Error('The browser took too long to answer')), callMs);
+                    }),
+                ]);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+        close: async () => {
+            await socket.send('Target.closeTarget', { targetId: target.targetId }).catch(() => undefined);
+            socket.close();
+            life.abort();
+        },
+    };
+}
+// Which manager an extension is: by its id (SourceMonkey's fixed one,
+// or a Web Store id, which a fetched copy keeps), else by its name.
+function managerOf(info, sourceMonkeyId) {
+    if (info.id === sourceMonkeyId)
+        return 'sourcemonkey';
+    const byId = MANAGER_NAMES.find((name) => MANAGERS[name].storeId === info.id);
+    if (byId)
+        return byId;
+    return MANAGER_NAMES.find((name) => info.name.toLowerCase().startsWith(MANAGERS[name].label.toLowerCase())) ?? null;
+}
+/**
+ * The managers installed in the browser at `endpoint`, enabled or not:
+ * SourceMonkey first, then Tampermonkey, then Violentmonkey. Throws when
+ * it can't tell.
+ */
+export async function installedManagers(endpoint, timeoutMs = 5000) {
+    const sourceMonkeyId = await sourceMonkeyExtensionId();
+    const infos = await withExtensionsPage(endpoint, timeoutMs, (evaluate) => evaluate('chrome.developerPrivate.getExtensionsInfo().then((all) => all.map((i) => ({ id: i.id, name: i.name, version: i.version, state: i.state, location: i.location, path: i.path, userScriptsAccess: i.userScriptsAccess })))'));
+    const found = [];
+    for (const info of infos) {
+        const manager = managerOf(info, sourceMonkeyId);
+        if (!manager)
+            continue;
+        found.push({
+            manager,
+            id: info.id,
+            name: info.name,
+            version: info.version,
+            enabled: info.state === 'ENABLED',
+            userScripts: info.userScriptsAccess?.isActive === true,
+            ...(info.location === 'UNPACKED' && info.path ? { path: info.path } : {}),
+            ...(info.location === 'FROM_STORE' ? { fromStore: true } : {}),
+        });
+    }
+    // In a fixed order, rather than Chrome's.
+    return found.sort((a, b) => MANAGER_NAMES.indexOf(a.manager) - MANAGER_NAMES.indexOf(b.manager));
+}
+/** `installedManagers`, or null when it can't tell, for what only reports. */
+export function managersIn(endpoint) {
+    return installedManagers(endpoint).catch(() => null);
+}
+/** Turns an extension on or off, as its toggle in `chrome://extensions` does. */
+export async function setExtensionEnabled(endpoint, id, enabled) {
+    await withExtensionsPage(endpoint, 10_000, (evaluate) => evaluate(`chrome.management.setEnabled(${JSON.stringify(id)}, ${enabled})`));
+}
+/** Turns on an extension's "Allow User Scripts", as its details page does. */
+export async function allowUserScripts(endpoint, id) {
+    await withExtensionsPage(endpoint, 10_000, (evaluate) => evaluate(`chrome.developerPrivate.updateExtensionConfiguration({ extensionId: ${JSON.stringify(id)}, userScriptsAccess: true })`));
+}
+/**
+ * Loads the unpacked extension in `dir` into the browser, or reloads it
+ * from there when it's loaded already. Returns its id.
+ */
+export async function loadUnpacked(endpoint, dir) {
+    const { id } = await withBrowserSocket(endpoint, 30_000, (send) => send('Extensions.loadUnpacked', { path: dir }));
+    return id;
+}
+/**
+ * Warns of each manager enabled beside `chosen`, whose scripts run in
+ * the run's tabs too, with how to turn it off. For a run's first lines,
+ * `status`, and the commands that connect without a run. `browserArg`:
+ * the flags that name the browser in the advice (see `browserArg` in
+ * run.ts).
+ */
+export function otherManagersWarning(managers, chosen, browserArg = '') {
+    const others = [...new Set(managers.filter((m) => m.enabled && m.manager !== chosen).map((m) => m.manager))];
+    return others.map((manager) => `${WARNING_PREFIX}${MANAGERS[manager].label} is also enabled in this browser, so its scripts run too. To turn it off, use ${quoted(`sm-dev${browserArg} ${managerFlag(manager)} manager disable`)}.`);
+}
+/**
+ * The managers in the browser, for `status`: `SourceMonkey 0.0.1 (in
+ * use), Tampermonkey 5.5.1 (disabled)`. Each copy is listed, with what
+ * keeps it from running scripts. `None` when there are none. `mark`:
+ * what the chosen one is, when enabled.
+ */
+export function managersText(managers, chosen, mark = 'in use') {
+    if (managers.length === 0)
+        return 'None';
+    return managers.map((m) => {
+        const notes = [
+            ...(m.manager === chosen && m.enabled ? [mark] : []),
+            ...(!m.enabled ? ['disabled'] : []),
+            ...(!m.userScripts ? ['Allow User Scripts is off'] : []),
+        ];
+        return `${m.name} ${m.version}${notes.length > 0 ? ` (${notes.join(', ')})` : ''}`;
+    }).join(', ');
+}
+export function managerState(managers, name) {
+    const copies = managers.filter((m) => m.manager === name);
+    return copies.some((m) => m.enabled) ? 'installed' : copies.length > 0 ? 'disabled' : 'absent';
+}
+/** How a run's first line says the chosen manager's state: `has Tampermonkey`. */
+export function stateLabel(state, name) {
+    const { label } = MANAGERS[name];
+    return { installed: `has ${label}`, disabled: `${label} disabled`, absent: `no ${label}` }[state];
+}
+/** The browser at `endpoint`: Chrome's version, and whether it's headless. Null when nothing answers. */
+export async function browserVersion(endpoint) {
+    try {
+        const info = await withBrowserSocket(endpoint, 2000, (send) => send('Browser.getVersion'));
+        return { version: (info.product ?? '').replace(/^\w+\//, ''), headless: /\bHeadlessChrome\//.test(info.userAgent ?? '') };
+    }
+    catch {
+        return null;
+    }
+}

package/lib/harness/browser-lang.d.ts

@@ -0,0 +1,20 @@
+import type { Page } from '@playwright/test';
+/** What `--lang` takes, for its messages. */
+export declare const LANG_NEEDS = "The --lang flag needs a language tag like zh-CN, or a list like zh-CN,en";
+/** Whether `value` looks like a language tag (`en`, `zh-CN`). */
+export declare function isLanguageTag(value: unknown): value is string;
+/**
+ * A `--lang` value as language tags, in the canonical case
+ * (`zh-cn` is `zh-CN`). Throws an Error with the message to show when
+ * a tag isn't one.
+ */
+export declare function parseLang(text: string): string[];
+/** Chrome's own flags for the languages, for a browser the run launches. */
+export declare function langLaunchArgs(langs: string[] | undefined): string[];
+/**
+ * Has `page` prefer `langs` from now on, through a CDP session left
+ * open, since an override lasts only while the session that set it
+ * does. Applies from the tab's next document on. A failure is said
+ * on `out`, naming the step, and the tab goes on without.
+ */
+export declare function applyLang(page: Page, langs: string[] | undefined, out: (line: string) => void): Promise<void>;

package/lib/harness/browser-lang.js

@@ -0,0 +1,86 @@
+// `start --lang`: the languages the run's tabs say they prefer, as
+// `navigator.language(s)`, the `Accept-Language` header, and the
+// default locale of `Intl` (dates, numbers).
+//
+// Set per tab over CDP (the Chrome DevTools Protocol), held for the
+// tab's life by a session of its own, so it works in a shared browser
+// without touching its other tabs. That reaches the tab's own frames
+// only: cross-site iframes and workers have targets of their own, and
+// keep the browser's languages. A headless temp browser is also
+// launched with Chrome's own language flags, which reach those too,
+// and a popup's first load.
+//
+// The extension's own requests (`GM_xmlhttpRequest`, `GM_download`)
+// carry the browser's languages, not a tab's: a launched browser's
+// flags, or a connected one's own.
+/** What `--lang` takes, for its messages. */
+export const LANG_NEEDS = 'The --lang flag needs a language tag like zh-CN, or a list like zh-CN,en';
+// A language first, then subtags: Intl alone also takes private-use
+// tags (`x-foo`), which no browser sends.
+const LANGUAGE_TAG = /^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$/;
+/** Whether `value` looks like a language tag (`en`, `zh-CN`). */
+export function isLanguageTag(value) {
+    return typeof value === 'string' && LANGUAGE_TAG.test(value);
+}
+function notATag(tag) {
+    return new Error(`The --lang flag got ${tag}, which is not a language tag. It needs one like zh-CN, or a list like zh-CN,en.`);
+}
+/**
+ * A `--lang` value as language tags, in the canonical case
+ * (`zh-cn` is `zh-CN`). Throws an Error with the message to show when
+ * a tag isn't one.
+ */
+export function parseLang(text) {
+    const tags = text.split(',').map((t) => t.trim());
+    if (tags.some((t) => t === ''))
+        throw new Error(LANG_NEEDS);
+    for (const tag of tags) {
+        if (!isLanguageTag(tag))
+            throw notATag(tag);
+        try {
+            Intl.getCanonicalLocales(tag);
+        }
+        catch {
+            throw notATag(tag);
+        }
+    }
+    return [...new Set(Intl.getCanonicalLocales(tags))];
+}
+/** Chrome's own flags for the languages, for a browser the run launches. */
+export function langLaunchArgs(langs) {
+    return langs?.length ? [`--lang=${langs[0]}`, `--accept-lang=${langs.join(',')}`] : [];
+}
+/**
+ * Has `page` prefer `langs` from now on, through a CDP session left
+ * open, since an override lasts only while the session that set it
+ * does. Applies from the tab's next document on. A failure is said
+ * on `out`, naming the step, and the tab goes on without.
+ */
+export async function applyLang(page, langs, out) {
+    if (!langs?.length)
+        return;
+    let step = 'Connecting to the tab failed';
+    try {
+        const session = await page.context().newCDPSession(page);
+        // An empty userAgent keeps the browser's own, and its client hints
+        // (navigator.userAgentData); only the languages change.
+        step = 'Setting navigator.languages and Accept-Language failed';
+        await session.send('Emulation.setUserAgentOverride', { userAgent: '', acceptLanguage: langs.join(',') });
+        // Intl's. Last, as only one connection to the browser can hold it.
+        step = 'Setting Intl\'s locale failed';
+        await session.send('Emulation.setLocaleOverride', { locale: langs[0] });
+    }
+    catch (err) {
+        if (page.isClosed())
+            return;
+        const message = err.message;
+        out(/already in effect/.test(message)
+            ? `[sm-dev] Could not set the tab's locale for Intl to ${langs[0]}: Another connection to the browser already overrides the tab's locale`
+            : `[sm-dev] Could not set the tab's languages to ${langs.join(',')}: ${step} (${cdpDetail(message)})`);
+    }
+}
+// What a CDP call's error says, without Playwright's and the
+// protocol's prefixes: `Protocol error (X.y): Not allowed` is `Not allowed`.
+function cdpDetail(message) {
+    return message.replace(/^cdpSession\.send: /, '').replace(/^Protocol error \([^)]*\): /, '').split('\n')[0];
+}

package/lib/harness/browser-launch.d.ts

@@ -0,0 +1,14 @@
+/** The profile a port's browser keeps. */
+export declare function defaultProfile(port: number): string;
+/** The path with the home directory as ~, for messages. */
+export declare function withTilde(file: string): string;
+/**
+ * Why `--open-browser` can't start a browser at `endpoint`, or null: it
+ * starts one on this machine only.
+ */
+export declare function launchEndpointMistake(endpoint: string, setting?: string, starter?: string): string | null;
+/**
+ * Starts the browser at `endpoint` unless one answers there already,
+ * and says which. Throws an error saying why it couldn't.
+ */
+export declare function launchBrowser(endpoint: string, profile: string | undefined, out: (line: string) => void, muted?: boolean, headless?: boolean): Promise<void>;

package/lib/harness/browser-launch.js

@@ -0,0 +1,184 @@
+// `sm-dev --open-browser`: starts a browser that stays open after sm-dev
+// exits, with a window and a debugging port, for runs to connect to.
+// Unlike a temp browser (Playwright's own launch, which ends
+// with the run), it is spawned on its own, as a person would start it.
+//
+// - The port is `--browser`'s (default $SM_DEV_BROWSER or 9233), which
+//   is also where later commands connect, so `sm-dev --open-browser
+//   start x.user.js --detach` needs nothing else.
+// - The profile is kept, so sign-ins and extensions carry over:
+//   `~/.config/sm-dev/browser-profile-<port>`, one for each port, since
+//   only one Chrome at a time can use a profile. `--profile` picks
+//   another.
+// - Idempotent: a browser already answering on the port is used as is,
+//   whatever its profile.
+// - Google Chrome when it's installed (better at Google sign-in than
+//   other builds), else Playwright's Chromium. $SM_DEV_BROWSER_BINARY
+//   names another binary, and $SM_DEV_BROWSER_ARGS adds arguments (the
+//   tests add --headless=new).
+import { execFileSync, spawn } from 'node:child_process';
+import { existsSync, openSync, closeSync, readFileSync, readlinkSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { loadPlaywright, missingChromium } from './playwright-chromium.js';
+import { processAlive } from './runs.js';
+import { quoted } from './output-style.js';
+// How long a started browser has to open its port.
+const START_TIMEOUT_MS = 10_000;
+/** Where Google Chrome is installed, by platform, most likely first. */
+function chromeCandidates() {
+    if (process.platform === 'darwin') {
+        return ['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', path.join(os.homedir(), 'Applications/Google Chrome.app/Contents/MacOS/Google Chrome')];
+    }
+    if (process.platform === 'win32') {
+        const dirs = [process.env.PROGRAMFILES, process.env['PROGRAMFILES(X86)'], process.env.LOCALAPPDATA].filter((d) => !!d);
+        return dirs.map((d) => path.join(d, 'Google', 'Chrome', 'Application', 'chrome.exe'));
+    }
+    return ['/opt/google/chrome/chrome', '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable'];
+}
+/** The browser to start, and what to call it. */
+async function browserBinary() {
+    const chosen = process.env.SM_DEV_BROWSER_BINARY?.trim();
+    if (chosen)
+        return { file: chosen, name: path.basename(chosen) };
+    const chrome = chromeCandidates().find((f) => existsSync(f));
+    if (chrome)
+        return { file: chrome, name: 'Google Chrome' };
+    const { chromium, install } = await loadPlaywright();
+    const file = chromium.executablePath();
+    const missing = missingChromium(file, install);
+    if (missing)
+        throw new Error(`No browser to launch: Google Chrome isn't installed. ${missing}`);
+    return { file, name: 'Chromium' };
+}
+/** The profile a port's browser keeps. */
+export function defaultProfile(port) {
+    const config = process.env.XDG_CONFIG_HOME?.trim() || path.join(os.homedir(), '.config');
+    return path.join(config, 'sm-dev', `browser-profile-${port}`);
+}
+/** The path with the home directory as ~, for messages. */
+export function withTilde(file) {
+    const home = os.homedir();
+    return file === home || file.startsWith(home + path.sep) ? '~' + file.slice(home.length) : file;
+}
+async function answers(endpoint) {
+    try {
+        const res = await fetch(`${endpoint}/json/version`, { signal: AbortSignal.timeout(2000) });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Why the profile can't be used, when another browser has it: Chrome
+ * locks a profile with a `SingletonLock` link to `host-pid`, and a
+ * second browser on it hands its window to the first and exits,
+ * dropping its debugging port. Null when it's free, or when the lock
+ * can't be read (Windows keeps it differently) or is another machine's
+ * (a shared home directory): the start then fails, or Chrome asks.
+ */
+function profileInUse(dir) {
+    let owner;
+    try {
+        owner = readlinkSync(path.join(dir, 'SingletonLock'));
+    }
+    catch {
+        return null;
+    }
+    const match = /^(.*)-(\d+)$/.exec(owner);
+    if (!match || match[1] !== os.hostname() || !processAlive(Number(match[2])))
+        return null;
+    const port = debuggingPort(dir, Number(match[2]));
+    return port
+        ? `The profile ${withTilde(dir)} is in use by the browser on port ${port}. Use ${quoted(`--browser ${port}`)}, or another ${quoted('--profile')}`
+        : `The profile ${withTilde(dir)} is in use by a browser without a debugging port (pid ${match[2]}). Close it, or use another ${quoted('--profile')}`;
+}
+// Where the browser with this pid listens, if it does: the port in its
+// command line, or (for --remote-debugging-port=0) the one Chrome writes
+// in the profile.
+function debuggingPort(dir, pid) {
+    try {
+        const args = execFileSync('ps', ['-o', 'args=', '-p', String(pid)], { encoding: 'utf8' });
+        const port = /--remote-debugging-port=(\d+)/.exec(args)?.[1];
+        if (port && port !== '0')
+            return port;
+    }
+    catch {
+        // No ps (Windows), or it's gone.
+    }
+    try {
+        return readFileSync(path.join(dir, 'DevToolsActivePort'), 'utf8').split('\n')[0].trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Why `--open-browser` can't start a browser at `endpoint`, or null: it
+ * starts one on this machine only.
+ */
+export function launchEndpointMistake(endpoint, setting = '--browser', starter = 'The --open-browser flag starts a browser') {
+    const url = new URL(endpoint);
+    // Chrome's debugging port listens on 127.0.0.1 only, so not [::1];
+    // and a port is all it takes, not a path.
+    const local = ['127.0.0.1', 'localhost'].includes(url.hostname) && url.port && url.pathname === '/' && !url.search;
+    if (local)
+        return null;
+    return `${starter} on this machine, so ${setting} must be a local port, not ${endpoint.replace(/^https?:\/\//, '')}`;
+}
+/**
+ * Starts the browser at `endpoint` unless one answers there already,
+ * and says which. Throws an error saying why it couldn't.
+ */
+export async function launchBrowser(endpoint, profile, out, muted = false, headless = false) {
+    const url = new URL(endpoint);
+    const where = `${url.hostname}:${url.port}`;
+    if (await answers(endpoint)) {
+        out(`[sm-dev] A browser is already running at ${where}`);
+        return;
+    }
+    const port = Number(url.port);
+    const dir = path.resolve(profile ?? defaultProfile(port));
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const inUse = profileInUse(dir);
+    if (inUse)
+        throw new Error(inUse);
+    const { file, name } = await browserBinary();
+    const extra = process.env.SM_DEV_BROWSER_ARGS?.split(/\s+/).filter(Boolean) ?? [];
+    // Its output goes to a file in the profile, where it can be read if
+    // it fails to start.
+    const logFile = path.join(dir, 'sm-dev-browser.log');
+    const log = openSync(logFile, 'w');
+    // Why it stopped before its port opened: its exit code, or the error
+    // that kept it from starting at all (no such file, say).
+    let ended = null;
+    let child;
+    try {
+        child = spawn(file, [
+            `--remote-debugging-port=${port}`, `--user-data-dir=${dir}`,
+            '--no-first-run', '--no-default-browser-check', ...(muted ? ['--mute-audio'] : []), ...(headless ? ['--headless=new'] : []), ...extra,
+        ], { detached: true, stdio: ['ignore', log, log] });
+        child.on('exit', (code, signal) => { ended ??= `It exited (${signal ?? `code ${code}`})`; });
+        child.on('error', (err) => { ended = `It could not be started from ${file}: ${err.message}`; });
+        child.unref();
+    }
+    finally {
+        closeSync(log);
+    }
+    const deadline = Date.now() + START_TIMEOUT_MS;
+    while (!await answers(endpoint)) {
+        if (ended !== null || Date.now() > deadline) {
+            // One that's up without its port would hold the profile's lock,
+            // and the next --open-browser would be refused.
+            if (ended === null)
+                child.kill();
+            const last = readFileSync(logFile, 'utf8').trim().split('\n').filter(Boolean).at(-1);
+            const why = ended ?? `Its port didn't open within ${START_TIMEOUT_MS / 1000}s, so it was closed`;
+            throw new Error(`Could not launch ${name} at ${where}: ${why}${last ? `. Its log (${withTilde(logFile)}) ends with: ${last}` : ''}`);
+        }
+        await new Promise((r) => setTimeout(r, 100));
+    }
+    out(`[sm-dev] Launched ${name} at ${where} (profile ${withTilde(dir)})`);
+}