sourcemonkey 0.0.0-stage → 0.5.0

package/lib/harness/run.d.ts

@@ -0,0 +1,194 @@
+import type { Browser, BrowserContext, Page } from '@playwright/test';
+import { type ManagerName } from './managers.js';
+import { type LogFields, type LogSource } from './run-logs.js';
+import { type SavedPageStart } from './saved-pages.js';
+import { type SentCommand } from './runs.js';
+export interface RunOptions extends ConnectOptions {
+    files: string[];
+    /** `files` as they were typed, in the same order, for errors to name them so. */
+    given?: string[];
+    /**
+     * Each file's name as typed, `given` and those `load` adds: a file
+     * that won't prepare is named as the person named it.
+     */
+    typed?: Map<string, string>;
+    /**
+     * The pages to open, one tab each. Defaults to the first URL the first
+     * script's `@match` implies.
+     */
+    urls?: string[];
+    /**
+     * `--from-saved`: for each of `urls`, the saved page its tab serves
+     * there, or null for a live one.
+     */
+    saved?: (SavedPageStart | null)[];
+    /**
+     * Open each script's default page, one tab per distinct page, rather
+     * than one page for the first script.
+     */
+    all?: boolean;
+    /**
+     * Open no tab at startup. The typed `newtab` opens one later; tabs
+     * the person opens run none of the run's scripts.
+     */
+    noTab?: boolean;
+    /** Re-push and reload whenever a script or one of its files changes. */
+    watch?: boolean;
+    /** Seed `GM_*` storage for every script before it runs. */
+    values?: Record<string, unknown>;
+    /** The log sources the run's stream and log file show (`start --log-source`). */
+    logSources?: ReadonlySet<LogSource>;
+    collectionRoot: string;
+    localRoots: string[];
+    /** Where the stream goes: plain text, or with markup when `markup` is set. */
+    out: (line: string) => void;
+    /** Lines to `out` keep their markup (output-style.ts), for an `out` that paints them. */
+    markup?: boolean;
+    /**
+     * Logs a line of one of the log sources (see run-logs.ts), which the
+     * stream shows when its source is one it shows. Set by `run`.
+     */
+    emit?: (fields: LogFields) => void;
+    /** Resolves when the run should end (stop, a signal, --stop-after-seconds). Omit to return after the first load. */
+    until?: Promise<void>;
+    /** Called when a client's `stop` asks for the run to end. */
+    onStop?: () => void;
+    /** Called once the run has a browser connection, and so something to clean up. */
+    onConnected?: () => void;
+    /**
+     * Called once the run has started: its pages loaded and scripts
+     * started, and sent commands taken. With its id, or none when other
+     * shells can't reach it.
+     */
+    onReady?: (id: string | undefined) => void;
+    /**
+     * Called as each sent command starts and ends, and as clients start and
+     * stop following the run, for `--stop-after-idle-seconds` to count from. `watched`:
+     * whether a client follows the run now, which keeps it from going idle.
+     */
+    onActivity?: (watched: boolean) => void;
+    /** Started by `--detach`, as the run's record says, for a later `--detach` to replace. */
+    detached?: boolean;
+    /** The run's log file (see run-log.ts), linked by the run's id. */
+    log?: string;
+    /** The id `start --run` asked for, rather than the lowest free one. */
+    runId?: string;
+    /** The process id of the client that started the run (see commandMark). */
+    primaryPid?: number;
+    /** Don't wait for the tabs to settle before taking commands (`--nowait`). */
+    noWait?: boolean;
+    /** `start --timeout-seconds`, in ms: each first load, and the settling after. */
+    timeoutMs?: number;
+}
+export interface ConnectOptions {
+    /** The browser to connect to, or with `tempBrowser`, the port to launch it on. */
+    cdp?: string;
+    /**
+     * `--manager`: the userscript manager the run works with, and a
+     * `tempBrowser` loads. SourceMonkey when not given.
+     */
+    manager?: ManagerName;
+    /**
+     * A temp browser: launch a Chromium of the run's own, with the
+     * package's own build of SourceMonkey (or `manager`) loaded.
+     */
+    tempBrowser?: boolean;
+    headed?: boolean;
+    /** With `tempBrowser`: whether it has sound (false), or is muted (the default). */
+    muted?: boolean;
+    /**
+     * `--lang`: the languages the run's tabs prefer (see browser-lang.ts).
+     * A `tempBrowser` is launched with them too.
+     */
+    lang?: string[];
+    /** Resolves to give up connecting (--stop-after-seconds): ends a wait for tabs that don't answer. */
+    until?: Promise<void>;
+    /** The run's log file, which a `tempBrowser`'s downloads folder is named after. */
+    log?: string;
+}
+/**
+ * A `--browser` value as a URL Playwright can connect to: a port alone
+ * (`9222`, `:9222`) means this machine, and a host with no scheme gets
+ * `http://`. Also the key runs record their tabs under, so the port
+ * and no-scheme spellings match the URL they stand for; `localhost`
+ * and `127.0.0.1` still differ. An IPv6 host needs brackets
+ * (`[::1]:9222`), as in a URL.
+ */
+export declare function cdpEndpoint(value: string): string;
+/**
+ * Whether two `--browser` values name the same browser: as
+ * `cdpEndpoint` writes them, with `localhost` and `[::1]` the same as
+ * `127.0.0.1`.
+ */
+export declare function sameBrowser(a: string, b: string): boolean;
+/**
+ * The browser to use: `--browser` (`given`), else $SM_DEV_BROWSER, else
+ * port 9233. Empty counts as unset, so an exported-but-blank variable
+ * doesn't become `http://`.
+ */
+export declare function browserSetting(given?: string): string;
+/**
+ * ` --existing-browser`, with the address (`addressArg`), for advice to
+ * run a command against the browser at `endpoint`. Empty for a launched
+ * one (`launched`), which closes with the run, so the advice goes to
+ * the run.
+ */
+export declare function browserArg(endpoint: string, launched?: boolean): string;
+/** ` --browser <address>`, unless `endpoint` is the default browser. */
+export declare function addressArg(endpoint: string): string;
+/**
+ * Where the browser setting came from, for a message about it: the
+ * variable when `--browser` wasn't given. $SM_DEV_BROWSER used to name
+ * the Chrome binary, so a stale one shouldn't be blamed on the flag.
+ */
+export declare function browserSettingName(given: string | undefined): string;
+export interface BrowserSession {
+    browser: Browser;
+    /** The browser's CDP endpoint, a launched one's too. */
+    endpoint: string;
+    /** Launched for this run (a temp browser), and closed with it. */
+    launched: boolean;
+    /** Running without a window. */
+    headless: boolean;
+    /** Where a launched browser saves downloads. A connected one keeps its own setting. */
+    downloadsDir?: string;
+    context: BrowserContext;
+    page: Page;
+    /**
+     * Lines about the tab taken, for after the line naming the browser
+     * (`run`), or printed at once by `connectBrowser`.
+     */
+    notes: string[];
+    /**
+     * End the session: a launched browser is closed; a connected one is
+     * only disconnected, and its tabs, this page included, stay open.
+     */
+    done(): Promise<void>;
+}
+/**
+ * `runTab`: in a connected browser, open the run's tab with
+ * `openRunTab`, which closes the selected tab when an earlier,
+ * finished run opened it.
+ */
+export declare function connectBrowser(opts: ConnectOptions, out: (line: string) => void, { runTab }?: {
+    runTab?: boolean | undefined;
+}): Promise<BrowserSession | null>;
+/**
+ * The browser at `--browser` (`cdp`), with no run and no tab, for the
+ * commands that only talk to SourceMonkey (`collection list`). Null,
+ * having said why, when it couldn't connect.
+ */
+export declare function connectWithoutRun(cdp: string | undefined, out: (line: string) => void): Promise<Omit<BrowserSession, 'page'> | null>;
+export declare function run(opts: RunOptions): Promise<number>;
+/**
+ * How a sent command is headed in the log and to the clients following
+ * the run: who sent it (`primary`, the client that started the run, or
+ * `remote`, any other) and how it got it (`arg`, `stdin`, `prompt`), as
+ * `primary:arg >`. A client heads its own without the who.
+ */
+export declare function commandMark(sent: Pick<SentCommand, 'pid' | 'source'>, primaryPid: number | undefined): string;
+/**
+ * What a call into SourceMonkey throws in a run under another manager,
+ * which has no SourceMonkey to call.
+ */
+export declare function runUses(manager: ManagerName): string;