sourcemonkey 0.0.0-stage → 0.5.0

package/lib/harness/tm-ids.js

@@ -0,0 +1,88 @@
+// The E-numbers sm-dev gives Tampermonkey's scripts, whose own ids are
+// uuids: one file in sm-dev's cache, `tampermonkey-ids.json`, mapping
+// each uuid to its number. A uuid is unique across browsers, so one
+// file serves them all. A number stays with its uuid for a week after
+// sm-dev last saw it, as SourceMonkey keeps its numbers after a
+// removal. See docs/sm-dev-tampermonkey.md.
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { managerCacheDir } from './manager-fetch.js';
+const KEEP_MS = 7 * 24 * 60 * 60 * 1000;
+// `SM_DEV_TM_IDS` moves it, as the tests do, to keep their scripts'
+// numbers out of the person's own file.
+function file() {
+    return process.env.SM_DEV_TM_IDS?.trim() || path.join(path.dirname(managerCacheDir()), 'tampermonkey-ids.json');
+}
+function load() {
+    try {
+        const saved = JSON.parse(readFileSync(file(), 'utf8'));
+        if (typeof saved.next === 'number' && saved.ids && typeof saved.ids === 'object')
+            return saved;
+    }
+    catch {
+        // None yet, or unreadable: numbering starts again.
+    }
+    return { next: 1, ids: {} };
+}
+/** The numbers of Tampermonkey's scripts, by uuid, read from and kept in sm-dev's cache. */
+export class TmIds {
+    saved = load();
+    byNumber = new Map();
+    constructor() {
+        this.index();
+    }
+    index() {
+        this.byNumber.clear();
+        for (const [uuid, { n }] of Object.entries(this.saved.ids))
+            this.byNumber.set(n, uuid);
+    }
+    /**
+     * 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) {
+        const now = Date.now();
+        this.saved = load();
+        let changed = false;
+        for (const uuid of uuids) {
+            const known = this.saved.ids[uuid];
+            if (known) {
+                // Kept in step only once a day: a save per listing isn't needed.
+                if (now - known.seen > 24 * 60 * 60 * 1000) {
+                    known.seen = now;
+                    changed = true;
+                }
+                continue;
+            }
+            this.saved.ids[uuid] = { n: this.saved.next++, seen: now };
+            changed = true;
+        }
+        for (const [uuid, { seen }] of Object.entries(this.saved.ids)) {
+            if (now - seen > KEEP_MS && !uuids.includes(uuid)) {
+                delete this.saved.ids[uuid];
+                changed = true;
+            }
+        }
+        if (changed)
+            this.save();
+        this.index();
+        return new Map(uuids.map((uuid) => [uuid, this.saved.ids[uuid].n]));
+    }
+    /** The number of `uuid`, when it has one. */
+    numberOf(uuid) {
+        return this.saved.ids[uuid]?.n;
+    }
+    /** The uuid number `n` was given, when it's still kept. */
+    uuidOf(n) {
+        return this.byNumber.get(n);
+    }
+    save() {
+        const to = file();
+        mkdirSync(path.dirname(to), { recursive: true });
+        // Whole or not at all, for another sm-dev reading it meanwhile.
+        const tmp = `${to}.${process.pid}.tmp`;
+        writeFileSync(tmp, `${JSON.stringify(this.saved)}\n`);
+        renameSync(tmp, to);
+    }
+}

package/lib/harness/violentmonkey.d.ts

@@ -0,0 +1,34 @@
+import type { ExternalManager, ExternalScript, InstallOptions } from './external-manager.js';
+/** Violentmonkey in one browser, over a hidden page of its own until `close`. */
+export declare class Violentmonkey implements ExternalManager {
+    private readonly page;
+    readonly extensionId: string;
+    readonly version: string;
+    readonly name: "violentmonkey";
+    readonly label: string;
+    private constructor();
+    /**
+     * Connects to VM 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<Violentmonkey>;
+    /** Makes one call. Its failure names the call and VM's version. */
+    call<R>(cmd: string, data?: unknown): Promise<R>;
+    scripts(): Promise<ExternalScript[]>;
+    texts(ids: number[]): Promise<Map<number, string>>;
+    install(code: string, options?: InstallOptions): Promise<{
+        id: number;
+        isNew: boolean;
+    }>;
+    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>;
+    scriptIdOf(url: string): number | undefined;
+    get scriptUrlPrefix(): string;
+    close(): Promise<void>;
+    private options;
+}

package/lib/harness/violentmonkey.js

@@ -0,0 +1,162 @@
+// Violentmonkey (VM), driven by the messages its own pages send its
+// background: `{cmd, data}` through `chrome.runtime.sendMessage`, from
+// a hidden page of VM's own (its options page), since VM answers no
+// other sender. Not a published API: what each call takes and gives is
+// listed in docs/sm-dev-violentmonkey.md, which the version check
+// (tests/vm-api/vm-api.spec.ts) tries against a fetched VM.
+import { installedManagers, openHiddenPage } from './browser-extensions.js';
+import { MANAGERS } from './managers.js';
+import { quoted } from './output-style.js';
+// The page the calls are sent from, as VM's manifest names it.
+const OPTIONS_PAGE = 'options/index.html';
+// Chrome's words when nothing answered a message: VM has no such call.
+const NO_ANSWER = /message port closed|Receiving end does not exist/i;
+/** Violentmonkey in one browser, over a hidden page of its own until `close`. */
+export class Violentmonkey {
+    page;
+    extensionId;
+    version;
+    name = 'violentmonkey';
+    label = MANAGERS.violentmonkey.label;
+    constructor(page, extensionId, version) {
+        this.page = page;
+        this.extensionId = extensionId;
+        this.version = version;
+    }
+    /**
+     * Connects to VM 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.violentmonkey.label;
+        const copies = (await installedManagers(endpoint)).filter((m) => m.manager === 'violentmonkey');
+        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 vm manager ${copies.length > 0 ? 'enable' : 'install'}`)}.`);
+        }
+        let page;
+        try {
+            // Once loaded: a call made while the page's own scripts start can
+            // get its answer wrapped (`[result]`), as VM's pages get theirs.
+            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 options page could not be opened: ${err.message}`, { cause: err });
+        }
+        return new Violentmonkey(page, copy.id, copy.version);
+    }
+    /** Makes one call. Its failure names the call and VM's version. */
+    async call(cmd, data) {
+        try {
+            return await this.page.evaluate(`chrome.runtime.sendMessage(${JSON.stringify({ cmd, data })})`);
+        }
+        catch (err) {
+            const why = err.message.replace(/^Error: /, '');
+            if (NO_ANSWER.test(why)) {
+                throw new Error(`${this.label} ${this.version} doesn't answer its ${cmd} call, which sm-dev uses. This version may have changed it.`, { cause: err });
+            }
+            // A refusal, or the browser not answering: VM's own error says which.
+            throw new Error(`${this.label} ${this.version}'s ${cmd} call failed: ${why}`, { cause: err });
+        }
+    }
+    async scripts() {
+        const data = await this.call('GetData', {});
+        if (!Array.isArray(data?.scripts))
+            throw new Error(`${this.label} ${this.version}'s GetData call gave no script list, which sm-dev reads. This version may have changed it.`);
+        return data.scripts.filter((s) => !s.config.removed).map((s) => scriptOf(s));
+    }
+    async texts(ids) {
+        if (ids.length === 0)
+            return new Map();
+        const codes = await this.call('GetScriptCode', ids);
+        return new Map(ids.flatMap((id) => (typeof codes?.[id] === 'string' ? [[id, codes[id]]] : [])));
+    }
+    async install(code, options = {}) {
+        const result = await this.call('ParseScript', {
+            code,
+            ...(options.id !== undefined ? { id: options.id } : {}),
+            ...(options.url !== undefined ? { url: options.url } : {}),
+            // VM would check its install URL for updates.
+            ...(options.local ? { config: { shouldUpdate: 0 } } : {}),
+            // Present, even empty, so VM waits for what it fetches itself
+            // before answering, rather than leaving it in flight.
+            require: options.files?.requires ?? {},
+            cache: Object.fromEntries(Object.entries(options.files?.resources ?? {}).map(([url, f]) => [url, `${f.contentType},${f.base64}`])),
+            bumpDate: true,
+        });
+        const id = result?.where?.id;
+        if (typeof id !== 'number')
+            throw new Error(`${this.label} ${this.version}'s ParseScript call gave no script id. This version may have changed it.`);
+        return { id, isNew: result.isNew === true };
+    }
+    async setEnabled(id, enabled) {
+        await this.call('UpdateScriptInfo', { id, config: { enabled: enabled ? 1 : 0 } });
+    }
+    async uninstall(id) {
+        await this.call('MarkRemoved', { id, removed: true });
+    }
+    async remove(ids) {
+        if (ids.length === 0)
+            return;
+        // VM removes for good only what's in its recycle bin.
+        for (const id of ids)
+            await this.call('MarkRemoved', { id, removed: true });
+        await this.call('RemoveScripts', ids);
+    }
+    async applied() {
+        return (await this.options()).isApplied !== false;
+    }
+    async setApplied(on) {
+        await this.call('SetOptions', { isApplied: on });
+    }
+    async allowFilePages() {
+        const { blacklist } = await this.options();
+        if (typeof blacklist !== 'string')
+            return false;
+        // Its default holds only this rule, one rule a line.
+        const lines = blacklist.split('\n');
+        const kept = lines.filter((line) => line.trim() !== 'file://*/*');
+        if (kept.length === lines.length)
+            return false;
+        await this.call('SetOptions', { blacklist: kept.join('\n') });
+        return true;
+    }
+    scriptIdOf(url) {
+        // `chrome-extension://<id>/<name>.user.js#<script id>`, as a frame's
+        // URL or in a stack's text.
+        const id = new RegExp(`chrome-extension://${this.extensionId}/[^\\s#]*\\.user\\.js#(\\d+)(?!\\d)`).exec(url);
+        return id ? Number(id[1]) : undefined;
+    }
+    get scriptUrlPrefix() {
+        return `chrome-extension://${this.extensionId}/`;
+    }
+    close() {
+        return this.page.close();
+    }
+    async options() {
+        return await this.call('GetAllOptions') ?? {};
+    }
+}
+function scriptOf(s) {
+    const { meta } = s;
+    return {
+        id: s.props.id,
+        name: meta.name ?? `#${s.props.id}`,
+        ...(meta.namespace ? { namespace: meta.namespace } : {}),
+        ...(meta.version ? { version: meta.version } : {}),
+        ...(meta.description ? { description: meta.description } : {}),
+        ...(meta.author ? { author: meta.author } : {}),
+        enabled: Boolean(s.config.enabled),
+        match: meta.match ?? [],
+        include: meta.include ?? [],
+        exclude: meta.exclude ?? [],
+        excludeMatch: meta.excludeMatch ?? [],
+        ...(meta.runAt ? { runAt: meta.runAt } : {}),
+        grants: meta.grant ?? [],
+        requires: meta.require ?? [],
+        resources: Object.entries(meta.resources ?? {}).map(([name, url]) => ({ name, url })),
+        ...(s.custom.lastInstallURL ? { installUrl: s.custom.lastInstallURL } : {}),
+        ...(s.props.lastUpdated ?? s.props.lastModified ? { updatedAt: s.props.lastUpdated ?? s.props.lastModified } : {}),
+    };
+}

package/lib/harness/wait.d.ts

@@ -0,0 +1,77 @@
+import type { Page } from '@playwright/test';
+import type { ConsoleContext, ControlledTab } from './console-commands.js';
+import type { HarnessHost } from './host.js';
+import type { ParsedArgs } from './command-args.js';
+/** How long a wait lasts before it says what is still busy. */
+export declare const SETTLE_TIMEOUT_MS = 5000;
+export type SettleOutcome = {
+    settled: true;
+}
+/** Still busy at the deadline: what with, as the message lists it. */
+ | {
+    settled: false;
+    busy: string[];
+}
+/** A dialog opened, which stops the page until it is answered. */
+ | {
+    settled: false;
+    dialog: true;
+}
+/** The tab closed. */
+ | {
+    settled: false;
+    closed: true;
+};
+/** Waits for `tab` to settle, up to `timeoutMs`. */
+export declare function settleTab(tab: ControlledTab, host: HarnessHost, timeoutMs?: number): Promise<SettleOutcome>;
+/**
+ * After a load, an action or `start`: each tab settling, all at once.
+ * One that doesn't in time is said, without failing anything, since
+ * what came before worked. A dialog or a closed tab says so elsewhere,
+ * and a tab whose load already gave up (`stalled`) isn't waited on
+ * again.
+ */
+export declare function settleTabs(host: HarnessHost, tabs: ControlledTab[], out: (line: string) => void, timeoutMs?: number): Promise<void>;
+/** How long a load (`open`, `reload`, the tabs `start` opens) may take. */
+export declare const LOAD_TIMEOUT_MS = 30000;
+/**
+ * A command's `--timeout-seconds` in ms, for each wait it does in place
+ * of that wait's default: undefined when not given, null (said why)
+ * when not a number of seconds.
+ */
+export declare function timeoutFlagMs(flags: Record<string, string | true>, out: (line: string) => void): number | undefined | null;
+/** A navigation whose page didn't finish loading in time. */
+export declare class PageNotLoaded extends Error {
+}
+/**
+ * Runs a navigation (`page.goto`, `page.reload`) until the new page
+ * has loaded. A page that stops its own load with `window.stop()`
+ * counts as loaded: its readyState goes to complete, but it never
+ * fires `load`, which a plain `goto` waits for until it times out.
+ * Rejects with the navigation's own error, or when the page doesn't
+ * load in time.
+ */
+export declare function loadPage(page: Page, navigate: (opts: {
+    waitUntil: 'commit';
+    timeout: number;
+}) => Promise<unknown>, timeoutMs?: number): Promise<void>;
+/** The message when `tab` didn't settle in time, as every wait says it. */
+export declare function notSettledMessage(tab: {
+    n: number;
+}, timeoutMs: number, busy: string[]): string;
+/**
+ * `wait`: until a tab settles, an element appears or goes, or an output
+ * line shows up; or a plain delay. `parsed`: its words, as its syntax
+ * reads them (command-args.ts). False when it gave up or was invalid,
+ * so a line of several commands stops there.
+ */
+export declare function waitFor(ctx: ConsoleContext, parsed: ParsedArgs): Promise<boolean>;
+/**
+ * A plain delay as typed, `100ms` or `5s` (`1.5s` too), in milliseconds;
+ * null for anything else.
+ */
+export declare function parseDelay(text: string): number | null;
+/** A duration as the messages say it: `5s`, `0.3s`. */
+export declare function seconds(ms: number): string;
+/** `work`'s result, or `timeout` once `ms` has passed. */
+export declare function within<T>(work: Promise<T>, ms: number): Promise<T | 'timeout'>;