sourcemonkey 0.0.0-stage → 0.5.0

package/lib/harness/runs.d.ts

@@ -0,0 +1,229 @@
+import { type LogSource } from './run-logs.js';
+import { type ManagerName } from './managers.js';
+/** What `sm-dev list` shows for a run, as its record file holds it. */
+export interface RunRecord {
+    id: string;
+    pid: number;
+    /** When it started, in epoch milliseconds. */
+    started: number;
+    /** The browser's CDP endpoint (`launched` from an older sm-dev). */
+    browser: string;
+    /** A browser the run launched, which closes when the run ends. */
+    owned?: boolean;
+    /** A browser without a window. */
+    headless?: boolean;
+    /** The loaded scripts' full paths. `list` shows their file names. */
+    scripts: string[];
+    /** How many tabs it controls, where it keeps count. */
+    tabs?: number;
+    /** Started by `start --detach`, and so replaced by the next one. */
+    detached?: boolean;
+    /** The run's log file (see run-log.ts). */
+    log?: string;
+    /** The userscript manager it works with (`--manager`), when not SourceMonkey. */
+    manager?: ManagerName;
+}
+/**
+ * Who the runs belong to, in the directory and pipe names, so two
+ * users on one machine neither see nor clash with each other's runs:
+ * the user name, kept to characters a file name can take. The uid when
+ * there is no name: `os.userInfo()` throws for a uid with no passwd
+ * entry, as in a container run with `--user`.
+ */
+export declare function owner(): string;
+/** Where `start` records the tabs it opened, for a later run to reuse. */
+export declare function runTabsPath(): string;
+/**
+ * A typed run id in its usual form (`d2` is `D2`, `D02` is `D2`), or
+ * null if it isn't one. Named ones are taken as typed.
+ */
+export declare function runIdOf(typed: string): string | null;
+export declare function processAlive(pid: number): boolean;
+/**
+ * The directory for sm-dev's state across runs, made private to its
+ * user: the runs' records and sockets, and `start`'s tab records. Created
+ * when missing.
+ */
+export declare function ownRunsDir(): Promise<string>;
+/**
+ * The directory, checked before anything in it is trusted, or null
+ * when there is none yet. In a shared temp directory another user could
+ * have made it first, or be able to write in it, and then plant records
+ * whose pids `stop` would signal; such a directory is refused.
+ */
+export declare function checkRunsDir(): Promise<string | null>;
+/**
+ * `dir`, or null when it doesn't exist; refused when another user owns
+ * it or can write in it. `what` names it in the message (`runs`, `log`).
+ */
+export declare function checkPrivateDir(dir: string, what: string): Promise<string | null>;
+/** Where a client's command came from: its command line, piped input, or its prompt. */
+export type CommandSource = 'arg' | 'stdin' | 'prompt';
+/** How a command came: the sender's directory and words, and its connection. */
+export interface SentCommand {
+    /** Where the files the command names are. */
+    cwd?: string;
+    /** The words as the sender's shell gave them. */
+    words?: string[];
+    /** Where the sender got it. `prompt`: typed by a person, rather than scripted. */
+    source: CommandSource;
+    /** The sending client's process id, as its hello gave it. */
+    pid?: number;
+    /** The connection gets the run's whole stream already (see `RunClient`). */
+    follows?: boolean;
+    /** The sender's global --json: commands with a JSON form print it. */
+    json?: boolean;
+}
+/**
+ * What a run does with a command a client sent: `reply` receives its
+ * output, until the returned promise settles with its exit code. `hold`
+ * keeps the connection open, and `reply` receiving, until the run
+ * closes it, as `stop` does so the sender sees the run end.
+ */
+export type SentLineHandler = (line: string, reply: (line: string) => void, sent: SentCommand) => Promise<number | 'hold'>;
+/** A run's handlers for its connections. */
+export interface RunHandlers {
+    command: SentLineHandler;
+    /**
+     * A connection that asked for the run's stream: `reply` receives each
+     * line the run prints from now on, until the returned function is
+     * called. `logSources`: the log sources it asked to see, in place of
+     * the run's own.
+     */
+    follow: (reply: (line: string) => void, logSources?: ReadonlySet<LogSource>) => () => void;
+}
+/** A run's end of the registry: its record file and its socket. */
+export declare class RunControl {
+    private record;
+    private readonly server;
+    private readonly sockets;
+    private writes;
+    private closed;
+    private constructor();
+    /**
+     * Takes the run's id, registers it and starts listening. Throws when
+     * that fails; the run goes on without, but can't be reached from
+     * another shell.
+     */
+    static open(fields: Omit<RunRecord, 'id'>, handle: RunHandlers, wanted?: string): Promise<RunControl>;
+    get id(): string;
+    /** Records changed scripts or tabs, for `sm-dev list`. */
+    update(changes: Partial<Pick<RunRecord, 'scripts' | 'tabs'>>): Promise<void>;
+    /** Unregisters the run, and ends every connection still open. */
+    close(): Promise<void>;
+    /**
+     * A client's connection: JSON messages, a line each. The first may be
+     * `{"hello": {"follow": true, "pid": 123, "logSources": ["sm", ...], "markup": true}}`:
+     * the run's whole stream, of those log sources if given, which client
+     * it is, and that it takes lines with markup (output-style.ts), which
+     * others get as plain text. Then commands, `{"line": ..., "cwd": ...,
+     * "words": [...], "source": "arg"}`, each
+     * answered with its output and then a `COMMAND_DONE` line with its
+     * exit code before the next is taken.
+     */
+    private serve;
+}
+/**
+ * The runs active now, oldest first. A record whose process has gone
+ * (killed, or its machine rebooted), or whose socket nothing listens on
+ * (its pid reused since), is deleted on the way.
+ */
+export declare function liveRuns(): Promise<RunRecord[]>;
+/**
+ * The start of the line a run sends after each command's output, with
+ * its exit code after it, for the client to take rather than print.
+ * Starts with a NUL, which no line of output does.
+ */
+export declare const COMMAND_DONE = "\0sm-dev:done";
+/** A connection's failure when the run has ended, or was never there. */
+export declare class RunGoneError extends Error {
+}
+/**
+ * A client's connection to a run, which it sends its commands over, one
+ * at a time. `follow`: also receive everything the run prints from now
+ * on, between commands too, as a person watching the run would. Output
+ * goes to `out` as it arrives, in the order the run printed it.
+ */
+export declare class RunClient {
+    readonly id: string;
+    private readonly socket;
+    private readonly out;
+    private buffered;
+    private pending;
+    private closedBy;
+    /** Settles once the connection has closed, from either end. */
+    readonly ended: Promise<void>;
+    private end;
+    private constructor();
+    /**
+     * Connects to run `id`, passing each line it sends to `out`. `markup`:
+     * lines come with their markup (output-style.ts), for an `out` that
+     * paints them; otherwise as plain text.
+     */
+    static open(id: string, out: (line: string) => void, { follow, logSources, markup }?: {
+        follow?: boolean;
+        logSources?: ReadonlySet<LogSource>;
+        markup?: boolean;
+    }): Promise<RunClient>;
+    /** Whether the connection is still open. */
+    get open(): boolean;
+    /**
+     * Sends one command (one line, or a {{ block's several), and
+     * resolves to its exit code once it is done. `words`: the sender's own,
+     * as its shell gave them. `rewrite`: changes each line that arrives
+     * while it runs.
+     */
+    send(line: string, { words, source, json, rewrite }?: {
+        words?: string[];
+        source?: CommandSource;
+        json?: boolean;
+        rewrite?: (line: string) => string;
+    }): Promise<number>;
+    /**
+     * Closes the connection; the run goes on. `force`: at once, not
+     * waiting for the run to take the last of it, for a client done
+     * waiting. A run that doesn't answer is let go after a moment anyway.
+     */
+    close({ force }?: {
+        force?: boolean | undefined;
+    }): Promise<void>;
+    private take;
+}
+/**
+ * Sends one command to a run over a connection of its own, passing each
+ * line of its output to `out` as it arrives, and resolves to its exit
+ * code. `signal` drops the connection, for a sender done waiting.
+ * `markup`: lines come with their markup, for an `out` that paints them.
+ */
+export declare function sendLine(id: string, line: string, out: (line: string) => void, signal?: AbortSignal, words?: string[], markup?: boolean): Promise<number>;
+/**
+ * Ends a run as its `stop` would, passing on what it prints as it ends.
+ * One that doesn't answer, or doesn't finish ending in time, is sent
+ * SIGTERM: it ends one that never got the `stop` as Ctrl-C would, and
+ * kills one stuck ending. A run found to have ended already is never
+ * signalled, since its pid may be another process's by now. Resolves to
+ * whether the run has gone. `markup`: as for sendLine.
+ */
+export declare function stopRun(record: RunRecord, out: (line: string) => void, markup?: boolean): Promise<boolean>;
+/**
+ * `sm-dev list`'s table: a heading row, then a row per run, in aligned
+ * columns. Scripts are listed by file name, the first few and a count
+ * of the rest, so the total shows without a column of its own. `-` is
+ * none, or no tab count for a run that keeps none. `markup`: lines
+ * marked up for color (output-style.ts), for printing; otherwise plain,
+ * as an error message needs them.
+ */
+export declare function runTable(records: RunRecord[], now?: number, { markup }?: {
+    markup?: boolean;
+}): string[];
+/**
+ * A run's browser as `list` shows it: `127.0.0.1:9233`, with
+ * `(owned, headless)` after it when so. `status` words it as a
+ * sentence (see `browserSentence`).
+ */
+export declare function browserLabel(r: Pick<RunRecord, 'browser' | 'owned' | 'headless'>): string;
+/**
+ * A run's browser as `status` says it: `connected to owned headless
+ * browser 127.0.0.1:9233`. `how` changes the first words (`launched`).
+ */
+export declare function browserSentence(r: Pick<RunRecord, 'browser' | 'owned' | 'headless'>, how?: string): string;