sourcemonkey 0.0.0-stage → 0.5.0

package/lib/harness/stuck-tabs.js

@@ -0,0 +1,131 @@
+// Tabs whose page doesn't answer, found before `sm-dev start` connects.
+//
+// Playwright's connection isn't ready until it has set up every tab in
+// the browser, and a tab showing a dialog (alert, confirm, prompt, or a
+// "leave site?" prompt) answers nothing until the dialog is closed: not
+// even the call that would report the dialog. So one such tab of the
+// person's holds up the run until Playwright gives up.
+//
+// No call reports a dialog that opened before the connection asking,
+// or answers one (Page.handleJavaScriptDialog says none is showing), so
+// each tab is asked for something trivial, on a connection of its own,
+// and one that stays quiet is named. That can also be a page busy in a
+// long script. (A page paused in the debugger still answers.)
+// How long a page gets to answer, and the browser to take the side
+// connection.
+const ANSWER_MS = 2000;
+const CONNECT_MS = 5000;
+// How often the tabs that didn't are asked again.
+const RECHECK_MS = 1000;
+/**
+ * The browser's tabs whose pages don't answer, of `only` when given.
+ * Throws when the browser itself can't be reached: the caller's own
+ * connect then says so.
+ */
+export async function stuckTabs(endpoint, only) {
+    // A `ws://` endpoint is the browser's own connection already.
+    const url = /^wss?:/i.test(endpoint) ? endpoint
+        : (await (await fetch(`${endpoint}/json/version`, { signal: AbortSignal.timeout(CONNECT_MS) })).json()).webSocketDebuggerUrl;
+    const ws = new WebSocket(url);
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('The browser\'s debugging connection did not open')), CONNECT_MS);
+        ws.onopen = () => {
+            clearTimeout(timer);
+            resolve(undefined);
+        };
+        ws.onerror = () => {
+            clearTimeout(timer);
+            reject(new Error('The browser\'s debugging connection could not be opened'));
+        };
+    }).catch((err) => {
+        ws.close();
+        throw err;
+    });
+    let nextId = 1;
+    const pending = new Map();
+    // Dropped, the connection answers nothing more, which would look like
+    // every tab not responding: the check fails instead.
+    let dropped = false;
+    ws.onclose = () => { dropped = true; };
+    ws.onmessage = (e) => {
+        const msg = JSON.parse(String(e.data));
+        if (msg.id !== undefined)
+            pending.get(msg.id)?.(msg);
+    };
+    // A command's reply, or null when none came within `ms`.
+    const call = (method, params, sessionId, ms = ANSWER_MS) => new Promise((resolve) => {
+        const id = nextId++;
+        const timer = setTimeout(() => {
+            pending.delete(id);
+            resolve(null);
+        }, ms);
+        pending.set(id, (msg) => {
+            clearTimeout(timer);
+            pending.delete(id);
+            resolve(msg);
+        });
+        ws.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
+    });
+    try {
+        const listed = await call('Target.getTargets', {});
+        const targets = (listed?.result?.targetInfos ?? []);
+        const pages = targets.filter((t) => t.type === 'page' && (!only || only.has(t.targetId)));
+        const stuck = await Promise.all(pages.map(async (t) => {
+            const attached = await call('Target.attachToTarget', { targetId: t.targetId, flatten: true });
+            const sessionId = attached?.result?.sessionId;
+            // Closed meanwhile, or not attachable: Playwright won't wait on it.
+            if (!sessionId)
+                return null;
+            const answer = await call('Runtime.evaluate', { expression: '1' }, sessionId);
+            void call('Target.detachFromTarget', { sessionId }, undefined, 500);
+            return answer ? null : { targetId: t.targetId, title: t.title, url: t.url };
+        }));
+        if (dropped)
+            throw new Error('The browser\'s debugging connection closed');
+        return stuck.filter((t) => t !== null);
+    }
+    finally {
+        ws.close();
+    }
+}
+/**
+ * Waits until every tab's page answers, saying which don't and why they
+ * might not. True at once when they all do, and when the browser can't
+ * be reached (the connect that follows says so). False when `until`
+ * resolves first (--stop-after-seconds, or the run's output closing).
+ */
+export async function waitForStuckTabs(endpoint, out, until) {
+    let stuck;
+    try {
+        stuck = await stuckTabs(endpoint);
+    }
+    catch {
+        return true;
+    }
+    if (stuck.length === 0)
+        return true;
+    let stopped = false;
+    void until?.then(() => { stopped = true; });
+    out(stuck.length === 1
+        ? 'A tab is not responding, so sm-dev can\'t connect to the browser over CDP:'
+        : 'Some tabs are not responding, so sm-dev can\'t connect to the browser over CDP:');
+    // Chrome titles a page without one by its address.
+    for (const t of stuck)
+        out(`  ${t.title && !t.url.endsWith(t.title) ? `${t.title}  ` : ''}${t.url}`);
+    out(stuck.length === 1
+        ? 'It may have a dialog open, or a busy page. Answer the dialog or close the tab to continue (Ctrl-C to abort).'
+        : 'They may have a dialog open, or a busy page. Answer the dialogs or close the tabs to continue (Ctrl-C to abort).');
+    while (stuck.length > 0) {
+        await Promise.race([new Promise((r) => setTimeout(r, RECHECK_MS)), until]);
+        if (stopped)
+            return false;
+        try {
+            stuck = await stuckTabs(endpoint, new Set(stuck.map((t) => t.targetId)));
+        }
+        catch {
+            return true;
+        }
+    }
+    out('Every tab is responding now. Connecting.');
+    return true;
+}

package/lib/harness/tab-refs.d.ts

@@ -0,0 +1,20 @@
+import type { Dialog } from '@playwright/test';
+import type { ConsoleContext, ControlledTab } from './console-commands.js';
+/** Where the page commands have no tab to act on; also `start --notab`'s start. */
+export declare const NO_TABS = "[sm-dev] No tabs are active. Use `newtab` to open one.";
+export declare const TAB_ARG: RegExp;
+export declare function tabName(tab: ControlledTab): string;
+export declare function currentTab(ctx: ConsoleContext): ControlledTab | undefined;
+/**
+ * The tab a typed argument names: `T2`, or its CDP target id (or the
+ * start of one, if only one open tab's id starts that way), bare or as
+ * the output shows it (`[targetId=...]`).
+ */
+export declare function pickTab(ctx: ConsoleContext, input: string): ControlledTab | null;
+export declare function dialogKind(dialog: Dialog): string;
+/**
+ * What to say when `waiting` has a dialog open and a command can't go
+ * on until it's answered. `accept` and `dismiss` act on the current tab
+ * (`current`), so another tab's needs picking first.
+ */
+export declare function dialogWaitingMessage(waiting: ControlledTab, current: ControlledTab | undefined): string;

package/lib/harness/tab-refs.js

@@ -0,0 +1,80 @@
+// Naming and picking a run's tabs, for the commands that take one
+// (console-commands.ts, wait.ts): `T2`, its target id,
+// the current tab, and what to say when one is stopped on a dialog.
+import { MISTAKE_PREFIX, quoted } from './output-style.js';
+/** Where the page commands have no tab to act on; also `start --notab`'s start. */
+export const NO_TABS = '[sm-dev] No tabs are active. Use `newtab` to open one.';
+// A tab named before a page command's own words: `T2`, or an id as the
+// output shows one. A bare hex prefix isn't taken, since it could be a
+// selector.
+export const TAB_ARG = /^(\[?targetId=\S+|[Tt]\d+)$/i;
+export function tabName(tab) {
+    return `T${tab.n}`;
+}
+// The tab the page commands act on. One that has closed gives way to
+// T1, said once so a command doesn't land somewhere unexpected.
+export function currentTab(ctx) {
+    const open = ctx.tabs();
+    if (ctx.tab && !open.includes(ctx.tab)) {
+        // With none left, the command's own reply says so.
+        if (open[0])
+            ctx.out(`[sm-dev] ${tabName(ctx.tab)} has closed, so the page commands now act on ${tabName(open[0])}`);
+        ctx.tab = undefined;
+    }
+    // Remembered, so the tab closing later is noted as above.
+    ctx.tab ??= open[0];
+    return ctx.tab;
+}
+// Enough of a target id to be taken for one rather than a slip.
+const MIN_TARGET_ID_PREFIX = 6;
+/**
+ * The tab a typed argument names: `T2`, or its CDP target id (or the
+ * start of one, if only one open tab's id starts that way), bare or as
+ * the output shows it (`[targetId=...]`).
+ */
+export function pickTab(ctx, input) {
+    // As copied from the output: `targetId=ABC...`, brackets and all.
+    const arg = input.replace(/^\[?targetId=([0-9a-f]+)\]?$/i, '$1');
+    if (arg.length >= MIN_TARGET_ID_PREFIX && /^[0-9a-f]+$/i.test(arg)) {
+        const upper = arg.toUpperCase();
+        const hits = ctx.tabs().filter((t) => t.targetId?.toUpperCase().startsWith(upper));
+        if (hits.length === 1)
+            return hits[0];
+        if (hits.length > 1) {
+            ctx.out(`[sm-dev] Multiple tabs have target ids starting with ${arg} (${hits.map(tabName).join(', ')}). Give more of it.`);
+            return null;
+        }
+        // Only a number could still be a tab slip (`2` for `T2`).
+        if (!/^\d+$/.test(arg)) {
+            ctx.out(`[sm-dev] No open tab's target id starts with ${quoted(arg)}. Use ${quoted('tabs')} to list them.`);
+            return null;
+        }
+    }
+    const m = /^[Tt](\d+)$/.exec(arg);
+    if (!m) {
+        // A bare number is the likely slip, and has an obvious fix.
+        ctx.out(/^\d+$/.test(arg)
+            ? `${MISTAKE_PREFIX}Tabs are named T1, T2 and so on. Did you mean ${quoted(`T${arg}`)}?`
+            : `${MISTAKE_PREFIX}${quoted(arg)} is not a tab. Tabs are named T1, T2 and so on; use ${quoted('tabs')} to list them.`);
+        return null;
+    }
+    const tab = ctx.tabs().find((t) => t.n === Number(m[1]));
+    if (!tab)
+        ctx.out(`[sm-dev] There is no open tab T${m[1]}. Use ${quoted('tabs')} to list them.`);
+    return tab ?? null;
+}
+export function dialogKind(dialog) {
+    const type = dialog.type();
+    return `${/^[aeiou]/.test(type) ? 'an' : 'a'} ${type}`;
+}
+/**
+ * What to say when `waiting` has a dialog open and a command can't go
+ * on until it's answered. `accept` and `dismiss` act on the current tab
+ * (`current`), so another tab's needs picking first.
+ */
+export function dialogWaitingMessage(waiting, current) {
+    const kind = dialogKind(waiting.dialogs.current);
+    return waiting === current
+        ? `The page is waiting on ${kind} dialog. Use ${quoted('accept')} or ${quoted('dismiss')} first.`
+        : `${tabName(waiting)} is waiting on ${kind} dialog. Use ${quoted(`accept ${tabName(waiting)}`)} or ${quoted(`dismiss ${tabName(waiting)}`)} first.`;
+}

package/lib/harness/tampermonkey.d.ts

@@ -0,0 +1,71 @@
+import { type ExternalManager, type ExternalScript, type InstallOptions } from './external-manager.js';
+/** Tampermonkey in one browser, over a hidden page of its own until `close`. */
+export declare class Tampermonkey implements ExternalManager {
+    private readonly page;
+    readonly extensionId: string;
+    readonly version: string;
+    readonly name: "tampermonkey";
+    readonly label: string;
+    private readonly ids;
+    private readonly layouts;
+    private listed?;
+    private constructor();
+    /**
+     * Connects to TM in the browser at `endpoint`. Throws saying why when
+     * it isn't installed and enabled there. `browserArg`: the flags
+     * that name the browser in the advice (see `browserArg` in run.ts).
+     */
+    static open(endpoint: string, browserArg?: string): Promise<Tampermonkey>;
+    /**
+     * Makes one call. TM gives no answer to a call it doesn't know, so
+     * one without an answer fails naming the call and TM's version.
+     */
+    call<R>(method: string, fields?: Record<string, unknown>): Promise<R>;
+    private list;
+    private listAnew;
+    private changed;
+    private numberOf;
+    private uuidOf;
+    scripts(): Promise<ExternalScript[]>;
+    texts(ids: number[]): Promise<Map<number, string>>;
+    install(code: string, options?: InstallOptions): Promise<{
+        id: number;
+        isNew: boolean;
+    }>;
+    private mustSaveQuietly;
+    setEnabled(id: number, enabled: boolean): Promise<void>;
+    uninstall(id: number): Promise<void>;
+    remove(ids: number[]): Promise<void>;
+    applied(): Promise<boolean>;
+    setApplied(on: boolean): Promise<void>;
+    allowFilePages(): Promise<boolean>;
+    matching(url: string): Promise<number[]>;
+    scriptIdOf(url: string): number | undefined;
+    get scriptUrlPrefix(): string;
+    /**
+     * Notes the `@require` files one of the run's scripts was installed
+     * with, in order, as `remapStack` needs them: TM runs a script's code
+     * after one line of its own and its `@require` files, joined by
+     * newlines, with the script's first line on their last.
+     */
+    noteRequires(id: number, requires: {
+        url: string;
+        source: string;
+    }[]): void;
+    /** `text` with the run's scripts' stack lines pointed at the lines of their own files. */
+    remapStack(text: string): string;
+    close(): Promise<void>;
+    private settings;
+    private scriptOf;
+}
+/**
+ * `code` as TM is given it. A script saved from TM's dashboard has no
+ * URL of its own, so TM can't resolve a relative `@require` or
+ * `@resource`; each one is rewritten to the URL it resolves to from
+ * `url`, a local file's under `sm-dev.invalid`. Each line rewritten is
+ * kept as it was in a comment at the end, before sm-dev's mark, which
+ * `restoredText` puts back.
+ */
+export declare function rewrittenText(code: string, url: string): string;
+/** `text` with the header lines `rewrittenText` changed as they were, and without its comments. */
+export declare function restoredText(text: string): string;

package/lib/harness/tampermonkey.js

@@ -0,0 +1,356 @@
+// Tampermonkey (TM), driven by the messages its own dashboard sends its
+// background: `{method, ...}` through `chrome.runtime.sendMessage`,
+// from a hidden page of TM's own (`options.html`), since TM answers no
+// other sender. Not a published API: what each call takes and gives is
+// listed in docs/sm-dev-tampermonkey.md, which the version check
+// (tests/tm-api/tm-api.spec.ts) tries against a fetched TM.
+import { installedManagers, openHiddenPage } from './browser-extensions.js';
+import { installUrlOf } from './external-manager.js';
+import { MANAGERS } from './managers.js';
+import { withoutMark } from './script-mark.js';
+import { TmIds } from './tm-ids.js';
+import { getValue, getValues, parseHeader } from '../userscript-header.js';
+import { quoted } from './output-style.js';
+const OPTIONS_PAGE = 'options.html';
+// How long one listing of every script, code included, answers again.
+// A command asks for the list, then the texts, then the count, so this
+// saves reading them all three times. Any call that changes something
+// drops it.
+const LIST_REUSE_MS = 1000;
+// The calls that only read, so keep the listing.
+const READS = new Set(['loadTree', 'determineScriptsToRun']);
+// The comment keeping a header line sm-dev rewrote, as it was, by its
+// line's index: `// sm-dev was: 5 // @require lib.js`. Written before
+// sm-dev's mark (script-mark.ts), at the end, so no line moves.
+// `[^\n]`, not `.`, so a line's `\r` (a CRLF file) stays with it.
+const WAS = /^\/\/ sm-dev was: (\d+) ([^\n]*)$/;
+/** Tampermonkey in one browser, over a hidden page of its own until `close`. */
+export class Tampermonkey {
+    page;
+    extensionId;
+    version;
+    name = 'tampermonkey';
+    label = MANAGERS.tampermonkey.label;
+    ids = new TmIds();
+    // How far each of the run's scripts' lines are moved, by uuid (see `noteRequires`).
+    layouts = new Map();
+    listed;
+    constructor(page, extensionId, version) {
+        this.page = page;
+        this.extensionId = extensionId;
+        this.version = version;
+    }
+    /**
+     * Connects to TM in the browser at `endpoint`. Throws saying why when
+     * it isn't installed and enabled there. `browserArg`: the flags
+     * that name the browser in the advice (see `browserArg` in run.ts).
+     */
+    static async open(endpoint, browserArg = '') {
+        const label = MANAGERS.tampermonkey.label;
+        const copies = (await installedManagers(endpoint)).filter((m) => m.manager === 'tampermonkey');
+        const copy = copies.find((m) => m.enabled);
+        if (!copy) {
+            throw new Error(`${label} is ${copies.length > 0 ? 'turned off' : 'not installed'} in this browser. Use ${quoted(`sm-dev${browserArg} --manager tm manager ${copies.length > 0 ? 'enable' : 'install'}`)}.`);
+        }
+        let page;
+        try {
+            page = await openHiddenPage(endpoint, `chrome-extension://${copy.id}/${OPTIONS_PAGE}`, 'document.readyState === "complete" && typeof chrome?.runtime?.sendMessage === "function"');
+        }
+        catch (err) {
+            throw new Error(`${label} ${copy.version}'s dashboard could not be opened: ${err.message}`, { cause: err });
+        }
+        return new Tampermonkey(page, copy.id, copy.version);
+    }
+    /**
+     * Makes one call. TM gives no answer to a call it doesn't know, so
+     * one without an answer fails naming the call and TM's version.
+     */
+    async call(method, fields = {}) {
+        if (!READS.has(method))
+            this.listed = undefined;
+        let answer;
+        try {
+            answer = await this.page.evaluate(`chrome.runtime.sendMessage(${JSON.stringify({ method, ...fields })})`);
+        }
+        catch (err) {
+            throw new Error(`${this.label} ${this.version}'s ${method} call failed: ${err.message.replace(/^Error: /, '')}`, { cause: err });
+        }
+        if (answer === undefined || answer === null) {
+            throw new Error(`${this.label} ${this.version} doesn't answer its ${method} call, which sm-dev uses. This version may have changed it.`);
+        }
+        const error = answer.error;
+        if (error)
+            throw new Error(`${this.label} ${this.version}'s ${method} call failed: ${String(error)}`);
+        return answer;
+    }
+    // Every installed script, with its text as TM keeps it.
+    list() {
+        if (this.listed && Date.now() - this.listed.at < LIST_REUSE_MS)
+            return this.listed.scripts;
+        const scripts = this.listAnew();
+        this.listed = { at: Date.now(), scripts };
+        // A failed listing isn't kept for the next.
+        scripts.catch(() => {
+            if (this.listed?.scripts === scripts)
+                this.listed = undefined;
+        });
+        return scripts;
+    }
+    async listAnew() {
+        const tree = await this.call('loadTree', { referrer: 'options.scripts.userscripts', complete: true });
+        if (!Array.isArray(tree.items))
+            throw this.changed('loadTree', 'no script list');
+        // The rest are the dashboard's own entries.
+        const scripts = tree.items.filter((i) => typeof i?.uuid === 'string');
+        this.ids.numbersOf(scripts.map((s) => s.uuid));
+        return scripts;
+    }
+    changed(method, what) {
+        return new Error(`${this.label} ${this.version}'s ${method} call gave ${what}, which sm-dev reads. This version may have changed it.`);
+    }
+    numberOf(uuid) {
+        return this.ids.numberOf(uuid) ?? this.ids.numbersOf([uuid]).get(uuid);
+    }
+    uuidOf(id) {
+        const uuid = this.ids.uuidOf(id);
+        if (!uuid)
+            throw new Error(`There is no script E${id} in ${this.label}`);
+        return uuid;
+    }
+    async scripts() {
+        return (await this.list()).map((s) => this.scriptOf(s));
+    }
+    async texts(ids) {
+        if (ids.length === 0)
+            return new Map();
+        const wanted = new Set(ids);
+        return new Map((await this.list()).flatMap((s) => {
+            const id = this.numberOf(s.uuid);
+            return wanted.has(id) && typeof s.code === 'string' ? [[id, restoredText(s.code)]] : [];
+        }));
+    }
+    async install(code, options = {}) {
+        await this.mustSaveQuietly();
+        const header = parseHeader(code);
+        const name = header ? getValue(header, 'name') : undefined;
+        // TM keeps any number of scripts of one name and namespace; sm-dev
+        // replaces as Violentmonkey does, keeping to one.
+        let uuid = options.id !== undefined ? this.uuidOf(options.id) : undefined;
+        if (uuid === undefined && header && name !== undefined) {
+            const namespace = getValue(header, 'namespace') ?? '';
+            uuid = (await this.list()).find((s) => s.name === name && (s.namespace ?? '') === namespace)?.uuid;
+        }
+        const text = options.url ? rewrittenText(code, options.url) : code;
+        const saved = await this.call('saveScript', {
+            ...(uuid !== undefined ? { uuid } : { uuid: 'new', new_script: true }),
+            code: text,
+            reload: false,
+        });
+        if (typeof saved.uuid !== 'string' || !saved.installed)
+            throw this.changed('saveScript', 'no installed script');
+        for (const [url, source] of Object.entries(options.files?.requires ?? {})) {
+            await this.call('saveExternal', { uuid: saved.uuid, url, code: source, mimetype: 'text/javascript' });
+        }
+        // A resource is kept as a string of its bytes, one character each.
+        for (const [url, { contentType, base64 }] of Object.entries(options.files?.resources ?? {})) {
+            await this.call('saveExternal', { uuid: saved.uuid, url, code: Buffer.from(base64, 'base64').toString('latin1'), mimetype: contentType || 'application/octet-stream' });
+        }
+        return { id: this.numberOf(saved.uuid), isNew: uuid === undefined };
+    }
+    // TM saves without asking only with its Easy save setting on, as it
+    // is by default; otherwise each save waits on a page no one sees.
+    async mustSaveQuietly() {
+        if ((await this.settings()).editor_easySave === false) {
+            throw new Error(`${this.label}'s Easy save setting is off, so it would ask before each save. Turn it on in ${this.label}'s settings (Editor, shown in the Advanced config mode), then try again.`);
+        }
+    }
+    async setEnabled(id, enabled) {
+        await this.call('modifyScriptOptions', { uuid: this.uuidOf(id), enabled, reload: false });
+    }
+    async uninstall(id) {
+        await this.call('saveScript', { uuid: this.uuidOf(id), code: null, reload: false });
+    }
+    async remove(ids) {
+        if (ids.length === 0)
+            return;
+        await this.call('purgeScripts', { uuids: ids.map((id) => this.uuidOf(id)) });
+    }
+    async applied() {
+        return (await this.settings()).enabled !== false;
+    }
+    async setApplied(on) {
+        await this.call('setOption', { name: 'enabled', value: on });
+    }
+    async allowFilePages() {
+        // Chrome's own file access setting decides, which sm-dev leaves.
+        return false;
+    }
+    async matching(url) {
+        const { scripts } = await this.call('determineScriptsToRun', { url });
+        if (!Array.isArray(scripts))
+            throw this.changed('determineScriptsToRun', 'no script list');
+        return scripts.filter((s) => typeof s === 'string').map((uuid) => this.numberOf(uuid));
+    }
+    scriptIdOf(url) {
+        // `chrome-extension://<id>/userscript.html?name=<name>.user.js&id=<uuid>`,
+        // as a frame's URL or in a stack's text.
+        const uuid = new RegExp(`chrome-extension://${this.extensionId}/userscript\\.html\\?\\S*?\\bid=([0-9a-f-]{36})`).exec(url)?.[1];
+        return uuid === undefined ? undefined : this.ids.numberOf(uuid);
+    }
+    get scriptUrlPrefix() {
+        return `chrome-extension://${this.extensionId}/`;
+    }
+    /**
+     * Notes the `@require` files one of the run's scripts was installed
+     * with, in order, as `remapStack` needs them: TM runs a script's code
+     * after one line of its own and its `@require` files, joined by
+     * newlines, with the script's first line on their last.
+     */
+    noteRequires(id, requires) {
+        const joined = requires.map((r) => r.source).join('\n');
+        this.layouts.set(this.uuidOf(id), {
+            offset: 1 + newlines(joined),
+            requires: requires.map((r) => ({ url: r.url, lines: newlines(r.source) + 1 })),
+        });
+    }
+    /** `text` with the run's scripts' stack lines pointed at the lines of their own files. */
+    remapStack(text) {
+        if (this.layouts.size === 0)
+            return text;
+        const ref = new RegExp(`(chrome-extension://${this.extensionId}/userscript\\.html\\?\\S*?\\bid=([0-9a-f-]{36})):(\\d+):(\\d+)`, 'g');
+        return text.replace(ref, (all, url, uuid, line, col) => {
+            const layout = this.layouts.get(uuid);
+            if (!layout)
+                return all;
+            const n = Number(line);
+            if (n - layout.offset >= 1)
+                return `${url}:${n - layout.offset}:${col}`;
+            // In a `@require` file: its line, counted from the line after TM's own.
+            let at = n - 1;
+            for (const r of layout.requires) {
+                if (at >= 1 && at <= r.lines)
+                    return `${r.url}:${at}:${col}`;
+                at -= r.lines;
+            }
+            return all;
+        });
+    }
+    close() {
+        return this.page.close();
+    }
+    async settings() {
+        const tree = await this.call('loadTree', { referrer: 'options' });
+        if (!tree.options)
+            throw this.changed('loadTree', 'no settings');
+        return tree.options;
+    }
+    scriptOf(s) {
+        const id = this.numberOf(s.uuid);
+        // The dependencies as the script's own header gives them, before
+        // sm-dev's rewrite.
+        const header = typeof s.code === 'string' ? parseHeader(restoredText(s.code)) : null;
+        const runAt = s.options?.run_at ?? s.options?.override?.orig_run_at;
+        return {
+            id,
+            name: s.name ?? s.uuid,
+            ...(s.namespace ? { namespace: s.namespace } : {}),
+            ...(s.version ? { version: s.version } : {}),
+            ...(s.description ? { description: s.description } : {}),
+            ...(s.author ? { author: s.author } : {}),
+            enabled: s.enabled !== false,
+            match: s.matches ?? [],
+            include: s.includes ?? [],
+            exclude: s.excludes ?? [],
+            excludeMatch: [],
+            ...(runAt ? { runAt } : {}),
+            grants: s.grant ?? [],
+            requires: header ? getValues(header, 'require') : [],
+            resources: header ? getValues(header, 'resource').flatMap((v) => {
+                const [name, url] = v.split(/\s+/, 2);
+                return name && url ? [{ name, url }] : [];
+            }) : [],
+            ...(s.fileURL || s.downloadURL ? { installUrl: (s.fileURL || s.downloadURL) } : {}),
+            ...(s.lastModified ? { updatedAt: s.lastModified } : {}),
+        };
+    }
+}
+function newlines(text) {
+    return text.split('\n').length - 1;
+}
+/**
+ * `code` as TM is given it. A script saved from TM's dashboard has no
+ * URL of its own, so TM can't resolve a relative `@require` or
+ * `@resource`; each one is rewritten to the URL it resolves to from
+ * `url`, a local file's under `sm-dev.invalid`. Each line rewritten is
+ * kept as it was in a comment at the end, before sm-dev's mark, which
+ * `restoredText` puts back.
+ */
+export function rewrittenText(code, url) {
+    const body = withoutMark(code);
+    const markLine = code.slice(body.length);
+    const lines = body.split('\n');
+    const was = [];
+    let inHeader = false;
+    for (let i = 0; i < lines.length; i++) {
+        // Without a CRLF file's `\r`, which goes back after.
+        const cr = lines[i].endsWith('\r') ? '\r' : '';
+        const line = lines[i].slice(0, lines[i].length - cr.length);
+        // The same loose markers `userscript-header.ts` accepts.
+        if (/\/\/[ \t]*==UserScript==/.test(line))
+            inHeader = true;
+        else if (/\/\/[ \t]*==\/UserScript==/.test(line))
+            break;
+        if (!inHeader)
+            continue;
+        const tag = /^(\s*\/\/\s*@(require|resource)\s+)(\S+\s+)?(\S+)(.*)$/.exec(line);
+        if (!tag)
+            continue;
+        const [, lead, kind, name = '', value, rest] = tag;
+        // `@require` takes no name: a second word there is the URL's own.
+        if (kind === 'require' && name)
+            continue;
+        const resolved = resolvedUrl(value, url);
+        if (resolved === value)
+            continue;
+        lines[i] = `${lead}${name}${resolved}${rest}${cr}`;
+        was.push(`// sm-dev was: ${i} ${line}${cr}`);
+    }
+    if (was.length === 0)
+        return code;
+    const rewritten = lines.join('\n');
+    return `${rewritten}${rewritten.endsWith('\n') ? '' : '\n'}${was.join('\n')}\n${markLine}`;
+}
+// Where a dependency's URL resolves to from the script's, a local
+// file's under sm-dev.invalid. The same as given when it can't be
+// resolved, which TM then reports itself.
+function resolvedUrl(value, base) {
+    let href;
+    try {
+        href = new URL(value, base).href;
+    }
+    catch {
+        return value;
+    }
+    return installUrlOf(href);
+}
+/** `text` with the header lines `rewrittenText` changed as they were, and without its comments. */
+export function restoredText(text) {
+    const lines = text.split('\n');
+    const kept = [];
+    const was = new Map();
+    for (const line of lines) {
+        const m = WAS.exec(line);
+        if (m)
+            was.set(Number(m[1]), m[2]);
+        else
+            kept.push(line);
+    }
+    if (was.size === 0)
+        return text;
+    // The comments come after every line they name, so dropping them
+    // moves none of those.
+    for (const [i, line] of was)
+        if (i < kept.length)
+            kept[i] = line;
+    return kept.join('\n');
+}

package/lib/harness/tm-ids.d.ts

@@ -0,0 +1,18 @@
+/** The numbers of Tampermonkey's scripts, by uuid, read from and kept in sm-dev's cache. */
+export declare class TmIds {
+    private saved;
+    private readonly byNumber;
+    constructor();
+    private index;
+    /**
+     * The numbers of `uuids`, the scripts installed now, giving each new
+     * one the next number. Saves the file when anything changed, read
+     * again first so another sm-dev's numbers aren't lost.
+     */
+    numbersOf(uuids: string[]): Map<string, number>;
+    /** The number of `uuid`, when it has one. */
+    numberOf(uuid: string): number | undefined;
+    /** The uuid number `n` was given, when it's still kept. */
+    uuidOf(n: number): string | undefined;
+    private save;
+}