sourcemonkey 0.0.0-stage → 0.5.0

package/lib/harness/console-commands.d.ts

@@ -0,0 +1,463 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { BrowserContext, Dialog, Page } from '@playwright/test';
+import { type JsonLayout } from './json-output.js';
+import { type InstalledManager } from './browser-extensions.js';
+import { type ManagerName } from './managers.js';
+import type { HarnessHost } from './host.js';
+import type { PageAttachment } from './page-watch.js';
+import { type ManagerControl } from './manager-commands.js';
+import { type ParsedArgs } from './command-args.js';
+import { type PreparedScript } from './prepare.js';
+import { type RunLog } from './run-logs.js';
+import { MISTAKE_PREFIX } from './output-style.js';
+import { type SavedPageHeader } from './save-html.js';
+import { type SavedPageFile, type SavedPageStart } from './saved-pages.js';
+import { type ScriptRoots } from './checks.js';
+/**
+ * A tab the run controls: its own, or one a controlled tab opened.
+ * Named `T<n>` in every list and command.
+ */
+export interface ControlledTab {
+    /** T1 is the run's own tab; the tabs it opens count up from 2. */
+    n: number;
+    page: Page;
+    /** The page as the host knows it, to tell this tab's reports apart. */
+    link: PageAttachment;
+    /** Opened with `newtab --noscript`, or by such a tab: no scripts run in it. */
+    noScript?: boolean;
+    /** Serving a saved page, from `--from-saved`. */
+    saved?: SavedPageFile;
+    /** The page's JavaScript dialogs, for `accept` and `dismiss`. */
+    dialogs?: DialogTracker;
+    /** The number of the tab that opened this one. */
+    openedBy?: number;
+    /**
+     * Its CDP target id, for a debugging session alongside the run to
+     * name the same tab. Unset if it closed before it could be read.
+     */
+    targetId?: string | null;
+    /**
+     * Its last load failed, or its scripts never reported (said already),
+     * so the waits after it don't wait on it again.
+     */
+    stalled?: boolean;
+}
+/** ` [targetId=...]`, the tab's CDP id, for the end of a line. */
+export declare function targetIdSuffix(targetId: string | null | undefined): string;
+/**
+ * A SourceMonkey-managed script, which the run didn't push: named by
+ * its script number in SourceMonkey (`E12`), the same in every run.
+ */
+export interface OtherScript {
+    label: string;
+    name: string;
+    collection: string;
+    /** What the toolbar badge says of it on the tab it was listed for. */
+    status: string;
+    values(): Promise<Record<string, unknown>>;
+    setValues(values: Record<string, unknown>): Promise<void>;
+}
+export interface ConsoleContext {
+    host: HarnessHost;
+    /** The controlled tabs still open, T1 first. */
+    tabs: () => ControlledTab[];
+    /** The tab the page commands act on. Starts as T1; `tabs` changes it. */
+    tab?: ControlledTab;
+    /**
+     * Open a new controlled tab, at `url` or blank, for `newtab`.
+     * Absent where the caller can't open one.
+     */
+    newTab?: (url?: string, options?: {
+        noScript?: boolean;
+        saved?: SavedPageStart;
+        timeoutMs?: number;
+    }) => Promise<ControlledTab>;
+    /** Switch a tab to running no scripts, or back, for `open --noscript` / `--script`. */
+    setTabScripts?: (tab: ControlledTab, noScript: boolean) => Promise<void>;
+    /** Load another script from disk, for `load`. */
+    loadScript?: (file: string, timeoutMs?: number) => Promise<void>;
+    /** Re-read scripts from disk (all, when none are named), for `update`. */
+    updateScripts?: (scripts?: PreparedScript[], timeoutMs?: number) => Promise<void>;
+    /** The scripts this run pushed, in load order. */
+    scripts: PreparedScript[];
+    /** SourceMonkey-managed scripts (see `OtherScript`), or another manager's. */
+    others?: {
+        /** How their list is headed, before ` on T1`: `SourceMonkey-managed scripts`. */
+        kind?: string;
+        /** Those on the tab's page, as its toolbar badge lists them. */
+        onTab(tab: ControlledTab): Promise<OtherScript[]>;
+        /** One already listed, by its label (`E2`). */
+        byLabel(label: string): OtherScript | undefined;
+        /** One installed anywhere, picked from `script list`'s rows, by the extension's id. */
+        installed(id: string, label: string, name: string, collection: string): OtherScript;
+        /** `set` on one changes the person's own data, so needs `--force`. */
+        guarded: boolean;
+    };
+    /**
+     * Under another manager, which reports nothing: whether a script is
+     * active on a tab is predicted from its rules.
+     */
+    predicted?: boolean;
+    /**
+     * Under another manager: which of the run's scripts are off there, by
+     * the manager's id, all of them while its switch is off. Read again
+     * (`refresh`) before each command that shows what a tab runs.
+     */
+    predictedOff?: {
+        refresh(): Promise<void>;
+        has(extensionId: string | undefined): boolean;
+    };
+    /**
+     * Each tab's iframes and the scripts in each, read again
+     * (`loadFrames`) before each command that shows them. Without it,
+     * scripts show for the top frame only.
+     */
+    frames?: Map<ControlledTab, FrameView[]>;
+    /** One of `others` picked for `get` and `set` (`scripts E1`), in place of `current`. */
+    currentOther?: OtherScript;
+    /**
+     * The script `get` and `set` act on. Starts as the first; `scripts`
+     * changes it.
+     */
+    current?: PreparedScript;
+    /**
+     * Typed at a terminal prompt, rather than piped. A person can see
+     * what is registered, so `menu` never waits for a late one.
+     */
+    interactive?: boolean;
+    out: (line: string) => void;
+    /**
+     * The running command prints its result as JSON (`--json`), set
+     * while it runs. Only for a command with a JSON form.
+     */
+    json?: boolean;
+    /** The running command's own `--json=single` or `=multi`. */
+    jsonLayout?: JsonLayout;
+    /** Ends the run, as Ctrl-C does. */
+    stop: () => void;
+    /** The id other shells know the run by (`--run`), for `status`. */
+    runId?: string;
+    /** The run's log file (see run-log.ts), for `status`. */
+    log?: string;
+    /** Where a temp browser saves downloads, for `status`. */
+    downloadsDir?: string;
+    /** The run's browser, for `status`: `connected to browser 127.0.0.1:9233`. */
+    browser?: string;
+    /** The same, for `status --json`. */
+    browserInfo?: {
+        address: string;
+        owned: boolean;
+        headless: boolean;
+    };
+    /** The run's test collection's id, once a script was pushed, for `status --json`. */
+    testCollection?: () => string | undefined;
+    /**
+     * Where the scripts run, for `status`: `SourceMonkey extension, test
+     * collection D2-a3f9`. Read as `status` runs.
+     */
+    backend?: () => string;
+    /** The userscript manager the run works with (`--manager`); SourceMonkey when unset. */
+    managerName?: ManagerName;
+    /** ` --existing-browser [--browser <address>]` for advice to run sm-dev against the run's browser (see `browserArg`). */
+    browserArg?: string;
+    /** The managers in the browser now, for `status`; null when unknown. */
+    managers?: () => Promise<InstalledManager[] | null>;
+    /** The run's log lines, for `logs` and `wait log` (see run-logs.ts). */
+    logs?: RunLog;
+    /**
+     * The log's position when the previous command (that wasn't only a
+     * look, like `status`) began, for `wait log`: a line the command set
+     * off, logged while it waited for the page to settle, still counts.
+     * Unset before the first.
+     */
+    previousStart?: number;
+    /** SourceMonkey's collections and installed scripts, for `collection list` and `script list`. */
+    manager?: ManagerControl;
+    /** The extension's id for one of `scripts`, once pushed, for `script list`. */
+    extensionIdOf?: (script: PreparedScript) => string | undefined;
+    /** Where `validate` and `match` find local copies of `@require`s: the run's own. */
+    roots?: ScriptRoots;
+}
+/**
+ * What's wrong with a run command's words, before it runs, or null (for
+ * a name that is no run command too: that is said elsewhere). `input`:
+ * the command as typed, its name first (a block's lines after a line
+ * break), or as a sender's words. `flag`: the flag it's about, so one
+ * that belongs before the command can be said to.
+ */
+export declare function runCommandMistake(input: {
+    line: string;
+} | {
+    words: string[];
+}): {
+    error: string;
+    flag?: string;
+} | null;
+export declare function withoutQuery(url: string): string;
+export declare function waitingReminders(ctx: ConsoleContext, before: WaitingState, said: readonly string[]): string[];
+export interface WaitingState {
+    prompts: Set<string>;
+    dialogs: Map<ControlledTab, unknown>;
+}
+export declare function waitingState(ctx: ConsoleContext): WaitingState;
+/**
+ * The run command, and its subcommand, whose help `--help` asks for
+ * (`click --help`, `script save --help`), or null when it isn't asked;
+ * an error for words that name no subcommand.
+ */
+export declare function runCommandHelp(input: {
+    line: string;
+} | {
+    words: string[];
+}): {
+    command: string;
+    subcommand?: string;
+} | {
+    error: string;
+} | null;
+/**
+ * Which of the commands for what's installed a command is (`collection
+ * C3 show`, `script list`), in any spelling, with its verb, or null for
+ * another command. These need SourceMonkey but no run.
+ */
+export declare function managerCommandOf(words: string[]): {
+    command: 'collection' | 'script';
+    verb: string | undefined;
+} | null;
+/**
+ * A command line's words, as the prompt splits them (quotes kept
+ * together), for telling which command it is and where it runs.
+ */
+export declare function commandWords(line: string): string[];
+/**
+ * Whether a command line only inspects, so its output goes back to the
+ * client that sent it alone, rather than into the run's stream too. `tabs`, `scripts` and `menu` inspect when they list, and
+ * change things when they pick or fire.
+ */
+export declare function onlyInspects(line: string): boolean;
+/**
+ * Whether a command line has a JSON form (`--json`): one of
+ * `JSON_COMMANDS`, in a form that only looks (`tabs`, not `tabs T2`).
+ */
+export declare function hasJsonForm(line: string): boolean;
+/**
+ * Where a running command's output goes instead of the run's stream,
+ * while it runs: an inspecting command answers the client that sent it
+ * alone. Output the page or the scripts produce meanwhile
+ * isn't the command's, and still goes to the stream. `live` goes false
+ * when the command ends, so anything it started that prints later goes
+ * to the stream rather than a closed connection.
+ */
+export declare const commandOutput: AsyncLocalStorage<{
+    line: (line: string) => void;
+    live: boolean;
+}>;
+/** How a line saying a command was invalid starts. */
+export { MISTAKE_PREFIX };
+/**
+ * Set while a command runs, in its own async work: what it prints is
+ * its reply, not something the page or a script printed on its own,
+ * which `wait log` looks for. Lines from the page and scripts arrive
+ * through events outside it. `inspects`: the command only looks, so
+ * its reply is no part of the run's log either.
+ */
+export declare const inCommand: AsyncLocalStorage<{
+    inspects: boolean;
+}>;
+/**
+ * Run one typed line. Returns once its effect has been applied, so an
+ * agent driving this over a pipe can send the next line knowing the
+ * previous one is done. For a line a client sent: `cwd` is
+ * where the files it names are, and `words` are the sender's own words
+ * (the line is them joined by spaces), which page commands take as
+ * they are rather than splitting the line.
+ */
+export declare function runConsoleCommand(line: string, ctx: ConsoleContext, { cwd, words }?: {
+    cwd?: string;
+    words?: string[];
+}): Promise<number | boolean | void>;
+/** `runLogLabel` marked up, for output: the log's path as one. */
+export declare function runLogLabelUi(file: string, id: string | undefined): string;
+/**
+ * The `collection` and `script` commands for what's installed (`collection`
+ * alone lists). `parsed`: its words as command-args.ts reads them, the
+ * verb as `form` (`list`), what it acts on as `subject` (`C3` in
+ * `collection C3 show`). `cwd`: where a path `script install` is given
+ * is from.
+ */
+export declare function managerCommand(ctx: Pick<ConsoleContext, 'manager' | 'out' | 'json'> & Partial<ConsoleContext>, command: string, parsed: Pick<ParsedArgs, 'form' | 'subject' | 'words' | 'flags'>, cwd?: string): Promise<boolean | void>;
+/**
+ * Warns when a saved page was saved with userscripts running: their
+ * changes are in it, so running them again may apply them twice.
+ * Nothing to say for a tab that runs none.
+ */
+export declare function warnSavedUserscripts(out: (line: string) => void, given: string, header: SavedPageHeader, noScript: boolean): void;
+/**
+ * Makes `tab` serve `saved` from now on: its URL gets the file, read
+ * fresh on each load. It lasts until another saved page replaces it;
+ * loading another URL in the tab goes to the live site meanwhile.
+ */
+/**
+ * Starts serving a saved page in `tab` (`serveSaved`), first warning of
+ * the userscripts whose changes its file has, unless `runsNone`: the
+ * tab runs no scripts, or none are loaded.
+ */
+export declare function serveSavedPage(tab: ControlledTab, saved: SavedPageStart, out: (line: string) => void, runsNone: boolean): Promise<void>;
+export declare function serveSaved(tab: ControlledTab, saved: SavedPageFile, out: (line: string) => void): Promise<void>;
+/** One of a tab's iframes, with the run's scripts running in it. */
+export interface FrameView {
+    /** Its id's number: `F3` is 3. */
+    n: number;
+    /** Its parent's number, or null for a frame in the top frame. */
+    parent: number | null;
+    /** 1 for a frame in the top frame. */
+    depth: number;
+    url: string;
+    scripts: PreparedScript[];
+    /** The extension's ids for its live documents, where it says. */
+    documents: string[];
+    /** Read with `loadFrames`' details: its <iframe> isn't visible (no size, hidden). */
+    hidden?: true;
+    /** Read with `loadFrames`' details: its CDP frame id, in its target. */
+    frameId?: string;
+    /** Read with `loadFrames`' details: its CDP target, when it runs in a process of its own. */
+    targetId?: string;
+}
+/**
+ * The tabs of `tabs` that can be reloaded now. One waiting on a dialog
+ * would hang its reload, so it is left for the person, and named.
+ */
+export declare function reloadable(tabs: ControlledTab[], out: (line: string) => void): ControlledTab[];
+/**
+ * Reload one tab, saying so if it fails. False when it failed, or its
+ * scripts never reported (said already), so nothing waits on it more.
+ */
+export declare function reloadTab(tab: ControlledTab, host: HarnessHost, out: (line: string) => void, timeoutMs?: number): Promise<boolean>;
+/** Navigate one tab to `url`, as `reloadTab` reloads it. */
+export declare function gotoInTab(tab: ControlledTab, host: HarnessHost, url: string, out: (line: string) => void, timeoutMs?: number): Promise<boolean>;
+/** A script `--all` or `newtab all` opened no tab for, and why. */
+export declare function skippedScriptLine(n: number, script: PreparedScript, reason: string): string;
+/**
+ * Keeps Playwright from dismissing dialogs in `context`'s pages.
+ *
+ * - Playwright dismisses a dialog nobody listens for, on the page or its
+ *   context, in every tab it's attached to: on a connected browser, the
+ *   person's own tabs too.
+ * - And when the dialog is gone before its dismiss lands, the error is
+ *   unhandled, and ends the process.
+ * - A listener that does nothing leaves each dialog to whoever does
+ *   answer it: the person, or the run's DialogTracker in its own tabs.
+ *   Also for a Playwright client that isn't the run's own.
+ */
+export declare function leaveDialogsOpen(context: BrowserContext): void;
+/**
+ * The page's `alert`, `confirm`, `prompt` and `beforeunload` dialogs.
+ * Playwright dismisses a dialog nobody listens for, which would answer
+ * a script's `prompt` with Cancel before anyone saw it. So each one is
+ * reported and left open, for the person at the browser or a typed
+ * `accept` / `dismiss`. Only when neither can answer (a headless
+ * browser, no command input) is it dismissed, since it would otherwise
+ * hang the page for good.
+ */
+export declare class DialogTracker {
+    private readonly say;
+    private readonly visible;
+    private readonly tabRef;
+    /** The dialog open now, if any. */
+    current: Dialog | null;
+    /**
+     * Whether typed commands are, or are about to be, read, so `accept`
+     * can answer. Set before the page loads when they will be, or a
+     * prompt the script opens on load would be dismissed first.
+     */
+    commandsListening: boolean;
+    private waiters;
+    private openedCount;
+    private closedCount;
+    private currentOrdinal;
+    private constructor();
+    /**
+     * `say`: where a dialog opening is told (a run logs it as an event).
+     * `visible`: whether the browser is on screen, for a person to
+     * answer. `commandsComing`: whether typed commands will be read.
+     * `tabRef`: the tab's name for `accept` and `dismiss` to take, when
+     * the run has several tabs and a bare one could reach another.
+     */
+    static attach(page: Page, say: (text: string) => void, { visible, commandsComing, tabRef }: {
+        visible: boolean;
+        commandsComing?: boolean;
+        tabRef?: () => string | undefined;
+    }): Promise<DialogTracker>;
+    /**
+     * `work`, or true as soon as a dialog opens while it runs. A menu
+     * command that opens a dialog blocks the page, and the push that
+     * fired it with it, until the dialog is answered.
+     */
+    untilDialog(work: Promise<boolean>): Promise<boolean>;
+    /** The open dialog, now claimed by whoever answers it. */
+    take(): Dialog | null;
+    putBack(dialog: Dialog): void;
+    private closed;
+    private opened;
+}
+/**
+ * For the global --json: sends other log messages to stderr from now
+ * on, and lays results out on one line or multi-line (`layout`),
+ * rather than by whether stdout is a terminal.
+ */
+export declare function setJsonOutput(layout?: JsonLayout): void;
+/**
+ * Print one line of run output. With a prompt showing, the prompt and
+ * whatever is half-typed are erased, the line printed above them, and
+ * both redrawn with the cursor where it was, so streaming output never
+ * lands in the middle of a command being edited.
+ */
+export declare function writeOutputLine(line: string): void;
+/**
+ * Runs command lines one at a time, from whichever source: typed ones
+ * and ones sent from other shells take turns, so two never interleave.
+ * `hooks` bracket the line's own turn, not its wait for one, so output
+ * captured between them is that command's.
+ */
+/**
+ * Runs a command line, resolving to false when the command failed in
+ * a way that should stop a line of several (a `wait` that timed out).
+ */
+export type CommandRunner = (line: string, hooks?: {
+    start?: () => void;
+    end?: () => void;
+    cwd?: string;
+    words?: string[];
+    answer?: (line: string) => void;
+    interactive?: boolean;
+    json?: boolean;
+}) => Promise<number>;
+export declare function commandRunner(ctx: ConsoleContext): CommandRunner;
+/**
+ * Whether dialogs wait for a typed (or sent) `accept`, rather than
+ * being dismissed in a headless run. On while commands are read.
+ */
+export declare function setCommandsListening(tabs: ControlledTab[], listening: boolean): void;
+/** What the prompt needs from whoever runs its commands. */
+export interface PromptIO {
+    /** Prints a line, drawn around the prompt (see writeOutputLine). */
+    out: (line: string) => void;
+    /**
+     * Leaves: Ctrl-D, or Ctrl-C on an empty line. `now`: without waiting
+     * for the command running, as a second Ctrl-C asks.
+     */
+    exit: (now?: boolean) => void;
+}
+/**
+ * The `> ` prompt of `sm-dev --interactive`, reading the terminal: line
+ * editing and history (readline's own keys: arrows, Ctrl-A/E, Ctrl-U
+ * and so on), Tab completion of command names, and `... ` inside an
+ * `{{` block (see command-lines.ts), edited as one buffer at a terminal
+ * (see prompt-editor.ts). A block is one history entry, and history is
+ * kept across sessions (see prompt-history.ts). Ctrl-C clears the
+ * typed command, and on an empty line it or Ctrl-D leaves. Each command goes to `runLine` once typed, in order.
+ * Returns a function that closes the prompt.
+ */
+export declare function readPromptCommands(io: PromptIO, runLine: (line: string, hooks?: {
+    start?: () => void;
+}) => Promise<unknown>): () => void;