sourcemonkey 0.0.0-stage → 0.5.0

package/lib/harness/runs.js

@@ -0,0 +1,726 @@
+// The runs `sm-dev start` began on this machine, and how another shell
+// reaches one: `sm-dev list`, `sm-dev stop`, and the commands sent to
+// a run (`sm-dev status`, or piped to `sm-dev`'s stdin).
+//
+// Each run writes a record file and listens on a socket of its own,
+// both named by its id (`D1`). A run has no terminal to type into:
+// every command comes from a client over the socket, runs as a typed
+// command would, and its output comes back (see RunClient).
+//
+// Node-only: no Playwright, so `list`, `stop` and the commands sent to
+// a run work anywhere.
+import { randomBytes } from 'node:crypto';
+import { lstat, mkdir, readdir, readFile, rename, rm, rmdir, writeFile } from 'node:fs/promises';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { STDERR_LINE } from './json-output.js';
+import { err as errorLine, escapeMarkup, heading, id as idRole, markupLines, plainLine, quoted, roleCell, tableLines, textCell, url } from './output-style.js';
+import { LOG_SOURCES } from './run-logs.js';
+import { DEFAULT_MANAGER, MANAGERS } from './managers.js';
+/**
+ * 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 function owner() {
+    let name;
+    try {
+        name = os.userInfo().username;
+    }
+    catch {
+        name = process.env.USER ?? process.env.USERNAME;
+    }
+    const safe = name?.replace(/[^\w.-]/g, '_');
+    if (safe)
+        return safe;
+    const uid = process.getuid?.();
+    return uid !== undefined ? String(uid) : 'user';
+}
+// `SM_DEV_RUNS_DIR` moves it, for tests to keep out of real runs' way.
+function runsDir() {
+    return process.env.SM_DEV_RUNS_DIR || path.join(os.tmpdir(), `sm-dev-runs-${owner()}`);
+}
+function recordPath(id) {
+    return path.join(runsDir(), `${id}.json`);
+}
+// Windows has no socket files; a named pipe stands in.
+function socketPath(id) {
+    return process.platform === 'win32'
+        ? `\\\\.\\pipe\\sm-dev-${owner()}-${id}`
+        : path.join(runsDir(), `${id}.sock`);
+}
+// Runs are named D1, D2, as tabs are T1 and menu commands M1: the
+// lowest number free when the run starts, so they stay short to type.
+// A number is reused once its run has ended. `start --run` can name one
+// instead: `D` and then letters, digits, `_` or `-`. Kept short, since
+// the id is part of the socket's path, which has a length limit.
+const RUN_ID = /^(?:[Dd](\d{1,32})|D([0-9A-Za-z_-]{1,32}))$/;
+/** Where `start` records the tabs it opened, for a later run to reuse. */
+export function runTabsPath() {
+    return path.join(runsDir(), 'run-tabs.json');
+}
+/**
+ * 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 function runIdOf(typed) {
+    const m = RUN_ID.exec(typed);
+    if (!m)
+        return null;
+    return m[1] !== undefined ? `D${BigInt(m[1])}` : `D${m[2]}`;
+}
+export function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM: it exists, under another user.
+        return err.code === 'EPERM';
+    }
+}
+/**
+ * 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 async function ownRunsDir() {
+    const dir = runsDir();
+    try {
+        await mkdir(dir, { recursive: true, mode: 0o700 });
+    }
+    catch (err) {
+        throw new Error(`Could not create the runs directory ${dir}: ${err.message}`);
+    }
+    await checkRunsDir();
+    return dir;
+}
+/**
+ * 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 async function checkRunsDir() {
+    return checkPrivateDir(runsDir(), 'runs');
+}
+/**
+ * `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 async function checkPrivateDir(dir, what) {
+    let info;
+    try {
+        info = await lstat(dir);
+    }
+    catch {
+        return null;
+    }
+    const uid = process.getuid?.();
+    if (!info.isDirectory() || (uid !== undefined && info.uid !== uid)) {
+        throw new Error(`The ${what} directory ${dir} belongs to another user`);
+    }
+    if (uid !== undefined && (info.mode & 0o022) !== 0) {
+        throw new Error(`The ${what} directory ${dir} can be written by other users. Remove it, and sm-dev makes a private one.`);
+    }
+    return dir;
+}
+const SOURCES = ['arg', 'stdin', 'prompt'];
+// How long a sender gets to take the last of the output once the run
+// ends its connection, before the run drops it and exits anyway.
+const CLOSE_WAIT_MS = 1000;
+/** A run's end of the registry: its record file and its socket. */
+export class RunControl {
+    record;
+    server;
+    sockets = new Set();
+    // Record writes, one at a time, so an older one never lands last.
+    writes = Promise.resolve();
+    closed = false;
+    constructor(record, server) {
+        this.record = record;
+        this.server = server;
+    }
+    /**
+     * 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 async open(fields, handle, wanted) {
+        await ownRunsDir();
+        const server = net.createServer();
+        const id = wanted === undefined ? await claimId(server) : await claimNamedId(server, wanted);
+        const record = { id, ...fields };
+        const control = new RunControl(record, server);
+        server.on('connection', (socket) => control.serve(socket, handle));
+        // Nothing keeps the process alive for a listener alone: the run
+        // ends on its own terms.
+        server.unref();
+        try {
+            await writeRecord(record);
+        }
+        catch (err) {
+            server.close();
+            throw new Error(`Could not write the run's record ${recordPath(record.id)}: ${err.message}`);
+        }
+        return control;
+    }
+    get id() {
+        return this.record.id;
+    }
+    /** Records changed scripts or tabs, for `sm-dev list`. */
+    update(changes) {
+        this.record = { ...this.record, ...changes };
+        this.writes = this.writes.then(() => (this.closed ? undefined : writeRecord(this.record))).catch(() => undefined);
+        return this.writes;
+    }
+    /** Unregisters the run, and ends every connection still open. */
+    async close() {
+        this.closed = true;
+        await this.writes;
+        await rm(recordPath(this.record.id), { force: true }).catch(() => undefined);
+        for (const socket of this.sockets)
+            socket.end();
+        // Not waited on for good: a sender that never closes its end would
+        // otherwise hold the run open.
+        const closed = new Promise((resolve) => this.server.close(() => resolve()));
+        const timer = setTimeout(() => {
+            for (const socket of this.sockets)
+                socket.destroy();
+        }, CLOSE_WAIT_MS);
+        await closed;
+        clearTimeout(timer);
+    }
+    /**
+     * 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.
+     */
+    serve(socket, handle) {
+        this.sockets.add(socket);
+        // A client that goes away mid-reply is no concern of the run's.
+        socket.on('error', () => undefined);
+        // From the hello: whether the client paints markup itself.
+        let markup = false;
+        const reply = (line) => {
+            if (!socket.destroyed && socket.writable) {
+                // The client reads line by line, so markup goes as lines that each
+                // stand alone, each keeping a `--json` stderr tag the whole had.
+                const tag = line.startsWith(STDERR_LINE) ? STDERR_LINE : '';
+                const body = line.slice(tag.length);
+                const lines = (markup ? markupLines(body) : plainLine(body).split('\n')).map((l) => tag + l);
+                socket.write(lines.join('\n') + '\n');
+            }
+        };
+        let unfollow = null;
+        socket.on('close', () => {
+            this.sockets.delete(socket);
+            unfollow?.();
+        });
+        let buffered = '';
+        // One command at a time, in order; none after one the run holds.
+        let queue = Promise.resolve();
+        let held = false;
+        // The client's, from its hello.
+        let pid;
+        socket.setEncoding('utf8');
+        socket.on('data', (chunk) => {
+            buffered += chunk;
+            const lines = buffered.split('\n');
+            buffered = lines.pop();
+            for (const text of lines) {
+                let message;
+                try {
+                    message = JSON.parse(text.replace(/\r$/, ''));
+                }
+                catch {
+                    // Not a client's message.
+                    continue;
+                }
+                if (message.hello) {
+                    if (typeof message.hello.pid === 'number')
+                        pid = message.hello.pid;
+                    markup = message.hello.markup === true;
+                    const { logSources } = message.hello;
+                    const sources = Array.isArray(logSources) ? new Set(logSources.filter((s) => LOG_SOURCES.includes(s))) : undefined;
+                    if (message.hello.follow === true && !unfollow)
+                        unfollow = handle.follow(reply, sources);
+                    continue;
+                }
+                if (typeof message.line !== 'string')
+                    continue;
+                const line = message.line;
+                const sent = {
+                    cwd: typeof message.cwd === 'string' ? message.cwd : undefined,
+                    words: Array.isArray(message.words) && message.words.every((w) => typeof w === 'string') ? message.words : undefined,
+                    source: SOURCES.includes(message.source) ? message.source : 'arg',
+                    pid,
+                    follows: unfollow !== null,
+                    json: message.json === true,
+                };
+                queue = queue.then(async () => {
+                    if (held)
+                        return;
+                    try {
+                        const code = await handle.command(line, reply, sent);
+                        if (code === 'hold')
+                            held = true;
+                        else
+                            reply(doneLine(code));
+                    }
+                    catch (err) {
+                        reply(`[sm-dev] ${errorLine(err.message)}`);
+                        reply(doneLine(1));
+                    }
+                });
+            }
+        });
+    }
+}
+// The lowest free id, taken by listening on its socket: only one
+// process can, so two runs starting together never get the same one.
+// The record is written after, so `list` never shows a run it can't
+// reach yet.
+async function claimId(server) {
+    for (let n = 1;; n++) {
+        const id = `D${n}`;
+        if (await listenOn(server, socketPath(id)))
+            return id;
+        // In use, or a socket file a killed run left, which nothing listens
+        // on. Windows pipes leave no such file.
+        if (process.platform !== 'win32' && await takeStale(server, id))
+            return id;
+    }
+}
+// `start --run`'s id: taken as the lowest free one is, or refused when
+// a run holds it still.
+async function claimNamedId(server, id) {
+    if (await listenOn(server, socketPath(id)))
+        return id;
+    if (process.platform !== 'win32' && await takeStale(server, id))
+        return id;
+    throw new Error(`Run ${quoted(id)} is running already`);
+}
+// The longest socket path the system takes, in bytes, with room for
+// the NUL: `sun_path` is 108 bytes on Linux and 104 on macOS.
+const MAX_SOCKET_PATH = process.platform === 'linux' ? 107 : 103;
+// Listens on `where`: false when something already holds it.
+async function listenOn(server, where) {
+    // Too long, it would be cut short, and fail as though it were taken.
+    if (process.platform !== 'win32' && Buffer.byteLength(where) > MAX_SOCKET_PATH) {
+        throw new Error(`A run's socket path can have at most ${MAX_SOCKET_PATH} bytes, and ${where} is longer. Set ${quoted('SM_DEV_RUNS_DIR')} to a shorter directory.`);
+    }
+    try {
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(where, () => {
+                server.off('error', reject);
+                resolve();
+            });
+        });
+        return true;
+    }
+    catch (err) {
+        if (err.code === 'EADDRINUSE')
+            return false;
+        throw new Error(`Could not listen on ${where}: ${err.message}`);
+    }
+}
+// Clears a killed run's socket file and listens there instead. Under a
+// lock held until the listen, since between one run finding the file
+// dead and deleting it, another could clear it and start listening,
+// and then lose its live socket to the delete. A lock already held, or
+// left by a run killed while holding it, only means trying the next
+// number.
+async function takeStale(server, id) {
+    const lock = path.join(runsDir(), `${id}.clearing`);
+    try {
+        await mkdir(lock);
+    }
+    catch {
+        return false;
+    }
+    try {
+        if (await listening(id) !== false)
+            return false;
+        await rm(socketPath(id), { force: true });
+        return await listenOn(server, socketPath(id));
+    }
+    finally {
+        await rmdir(lock).catch(() => undefined);
+    }
+}
+// Written whole under a name of its own and renamed into place, so
+// `list` never reads half a file.
+async function writeRecord(record) {
+    const file = recordPath(record.id);
+    const temp = `${file}.${randomBytes(4).toString('hex')}.tmp`;
+    await writeFile(temp, JSON.stringify(record) + '\n', { mode: 0o600 });
+    await rename(temp, file);
+}
+// Deletes an ended run's files. Each is checked first, since a new run
+// may have taken the id meanwhile: the record only if it still names
+// the old pid, the socket only if nothing listens on it.
+async function forget(id, pid) {
+    try {
+        const record = JSON.parse(await readFile(recordPath(id), 'utf8'));
+        if (record.pid === pid)
+            await rm(recordPath(id), { force: true });
+    }
+    catch {
+        // Gone already, or unreadable: nothing to delete.
+    }
+    if (process.platform !== 'win32' && await listening(id) === false) {
+        await rm(socketPath(id), { force: true }).catch(() => undefined);
+    }
+}
+// Nothing listens on the run's socket: it has ended, even if its pid
+// has since gone to another process.
+function goneCode(err) {
+    const code = err.code;
+    return code === 'ENOENT' || code === 'ECONNREFUSED';
+}
+// Whether a run's socket takes a connection. A connection that sends no
+// line runs nothing in the run.
+function listening(id) {
+    return new Promise((resolve) => {
+        const socket = net.connect(socketPath(id));
+        socket.on('connect', () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.on('error', (err) => resolve(goneCode(err) ? false : 'unknown'));
+    });
+}
+/**
+ * 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 async function liveRuns() {
+    const dir = await checkRunsDir();
+    if (!dir)
+        return [];
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const runs = [];
+    // Only runs' records: the directory holds other state too.
+    await Promise.all(names.filter((n) => n.endsWith('.json') && runIdOf(n.slice(0, -'.json'.length)) === n.slice(0, -'.json'.length)).map(async (name) => {
+        const id = name.slice(0, -'.json'.length);
+        let record;
+        try {
+            record = JSON.parse(await readFile(path.join(dir, name), 'utf8'));
+        }
+        catch {
+            // Unreadable is as good as gone: nothing could reach it.
+            return;
+        }
+        if (processAlive(record.pid) && await listening(id) !== false)
+            runs.push(record);
+        else
+            await forget(id, record.pid);
+    }));
+    return runs.sort((a, b) => a.started - b.started);
+}
+/**
+ * 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 const COMMAND_DONE = '\u0000sm-dev:done';
+function doneLine(code) {
+    return `${COMMAND_DONE} ${code}`;
+}
+/** A connection's failure when the run has ended, or was never there. */
+export 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 class RunClient {
+    id;
+    socket;
+    out;
+    buffered = '';
+    pending = null;
+    closedBy = null;
+    /** Settles once the connection has closed, from either end. */
+    ended;
+    end;
+    constructor(id, socket, out) {
+        this.id = id;
+        this.socket = socket;
+        this.out = out;
+        this.ended = new Promise((resolve) => { this.end = resolve; });
+        socket.on('data', (chunk) => {
+            this.buffered += chunk;
+            const lines = this.buffered.split('\n');
+            this.buffered = lines.pop();
+            for (const l of lines)
+                this.take(l);
+        });
+        socket.on('close', () => {
+            if (this.buffered)
+                this.take(this.buffered);
+            this.buffered = '';
+            this.closedBy ??= 'run';
+            // A command the run closed on (stop) is done; any other was cut
+            // off by the run ending.
+            const pending = this.pending;
+            this.pending = null;
+            if (pending) {
+                const stopping = /^\s*stop\s*$/.test(pending.line);
+                // Only when the run went; not when this end let go (Ctrl-C).
+                if (!stopping && this.closedBy === 'run')
+                    this.out(`[sm-dev] Run ${this.id} ended before the command was done`);
+                pending.resolve(stopping ? 0 : 1);
+            }
+            this.end();
+        });
+    }
+    /**
+     * 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, out, { follow = false, logSources, markup = false } = {}) {
+        return new Promise((resolve, reject) => {
+            const socket = net.connect(socketPath(id));
+            socket.setEncoding('utf8');
+            const early = (err) => {
+                reject(goneCode(err) ? new RunGoneError(`Run ${id} has ended`) : new Error(`Run ${id} could not be reached: ${err.message}`));
+            };
+            socket.once('error', early);
+            socket.once('connect', () => {
+                socket.off('error', early);
+                // Lost later, it is said when a command was waiting on it.
+                socket.on('error', () => undefined);
+                // Which client this is, for the run to name where its commands came from.
+                // With `markup`, lines come with it, for writeOutputLine to paint.
+                socket.write(JSON.stringify({ hello: { follow, pid: process.pid, ...(markup ? { markup } : {}), ...(logSources ? { logSources: [...logSources] } : {}) } }) + '\n');
+                resolve(new RunClient(id, socket, out));
+            });
+        });
+    }
+    /** Whether the connection is still open. */
+    get open() {
+        return this.closedBy === null;
+    }
+    /**
+     * 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, { words, source = 'arg', json = false, rewrite } = {}) {
+        if (!this.open) {
+            this.out(`[sm-dev] Run ${this.id} has ended`);
+            return Promise.resolve(1);
+        }
+        return new Promise((resolve) => {
+            this.pending = { resolve, line, ...(rewrite ? { rewrite } : {}) };
+            this.socket.write(JSON.stringify({ line, cwd: process.cwd(), words, source, ...(json ? { json } : {}) }) + '\n');
+        });
+    }
+    /**
+     * 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 = false } = {}) {
+        if (this.closedBy === null)
+            this.closedBy = 'client';
+        if (force) {
+            this.socket.destroy();
+            return this.ended;
+        }
+        this.socket.end();
+        const timer = setTimeout(() => this.socket.destroy(), CLOSE_WAIT_MS);
+        return this.ended.finally(() => clearTimeout(timer));
+    }
+    take(line) {
+        if (!line.startsWith(COMMAND_DONE)) {
+            this.out(this.pending?.rewrite ? this.pending.rewrite(line) : line);
+            return;
+        }
+        const pending = this.pending;
+        this.pending = null;
+        pending?.resolve(Number(line.slice(COMMAND_DONE.length).trim()) || 0);
+    }
+}
+/**
+ * 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 async function sendLine(id, line, out, signal, words, markup = false) {
+    const client = await RunClient.open(id, out, { markup });
+    const abort = () => { void client.close({ force: true }); };
+    signal?.addEventListener('abort', abort, { once: true });
+    try {
+        const code = await Promise.race([
+            client.send(line, { words }),
+            new Promise((_, reject) => signal?.addEventListener('abort', () => reject(new Error(`Stopped waiting on run ${id}`)), { once: true })),
+        ]);
+        await client.close();
+        return code;
+    }
+    finally {
+        signal?.removeEventListener('abort', abort);
+    }
+}
+// How long a run gets to answer `stop`, and once it has,
+// how long to finish ending (a tab stopped on a dialog takes a while to
+// let go). Past either, it is sent SIGTERM, and given the first again
+// to go.
+const STOP_WAIT_MS = 15_000;
+const TEARDOWN_WAIT_MS = 60_000;
+/**
+ * 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 async function stopRun(record, out, markup = false) {
+    const abort = new AbortController();
+    // It answers `stop` with a line straight away, then ends.
+    let answered = false;
+    const sent = sendLine(record.id, 'stop', (line) => {
+        answered = true;
+        out(line);
+    }, abort.signal, undefined, markup).then(() => 'closed', (err) => (err instanceof RunGoneError ? 'gone' : 'failed'));
+    let outcome = await within(sent, STOP_WAIT_MS);
+    if (outcome === 'timeout' && answered)
+        outcome = await within(sent, TEARDOWN_WAIT_MS);
+    // Closed without that first line: whatever took it, it wasn't a run
+    // ending.
+    if (outcome === 'closed' && !answered)
+        outcome = 'failed';
+    // So a connection still open can't keep this process alive.
+    abort.abort();
+    if (outcome === 'gone') {
+        await forget(record.id, record.pid);
+        out(`[sm-dev] Run ${record.id} had already ended`);
+        return true;
+    }
+    if (outcome === 'closed' && await exited(record.pid, STOP_WAIT_MS))
+        return true;
+    try {
+        process.kill(record.pid, 'SIGTERM');
+    }
+    catch {
+        // Gone meanwhile.
+    }
+    if (await exited(record.pid, STOP_WAIT_MS)) {
+        out(`[sm-dev] Run ${record.id} ${answered ? 'did not finish ending' : 'did not answer'}, so it was sent SIGTERM, and has ended`);
+        return true;
+    }
+    out(`[sm-dev] Run ${record.id} (pid ${record.pid}) has not ended, even after SIGTERM`);
+    return false;
+}
+// `work`'s result, or `timeout` if it takes longer than `ms`.
+async function within(work, ms) {
+    let timer;
+    try {
+        return await Promise.race([work, new Promise((resolve) => { timer = setTimeout(() => resolve('timeout'), ms); })]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function exited(pid, ms) {
+    const deadline = Date.now() + ms;
+    while (processAlive(pid)) {
+        if (Date.now() >= deadline)
+            return false;
+        await sleep(100);
+    }
+    return true;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// Past this many, `list` names the first few and counts the rest.
+const LISTED_SCRIPTS = 3;
+/**
+ * `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 function runTable(records, now = Date.now(), { markup = false } = {}) {
+    const rows = [
+        ['Run', 'PID', 'Uptime', 'Browser', 'Manager', 'Tabs', 'Scripts'].map((text) => roleCell(heading, text)),
+        ...records.map((r) => {
+            const names = r.scripts.map((s) => path.basename(s));
+            const shown = names.slice(0, LISTED_SCRIPTS).map((n) => roleCell(url, n));
+            if (names.length > LISTED_SCRIPTS)
+                shown.push(textCell(`(${names.length - LISTED_SCRIPTS} more)`));
+            const browser = browserLabel(r);
+            const where = browserAddress(r);
+            return [
+                roleCell(idRole, r.id),
+                textCell(String(r.pid)),
+                textCell(uptime(now - r.started)),
+                { plain: browser, styled: url(where) + escapeMarkup(browser.slice(where.length)) },
+                textCell(MANAGERS[r.manager ?? DEFAULT_MANAGER].label),
+                textCell(r.tabs === undefined ? '-' : String(r.tabs)),
+                shown.length > 0
+                    ? { plain: shown.map((c) => c.plain).join(', '), styled: shown.map((c) => c.styled).join(', ') }
+                    : textCell('-'),
+            ];
+        }),
+    ];
+    return tableLines(rows, { markup });
+}
+// A run's browser address, without its scheme.
+function browserAddress(r) {
+    return r.browser.replace(/^https?:\/\//, '');
+}
+/**
+ * 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 function browserLabel(r) {
+    const marks = [r.owned && 'owned', r.headless && 'headless'].filter(Boolean);
+    const where = browserAddress(r);
+    return marks.length > 0 ? `${where} (${marks.join(', ')})` : where;
+}
+/**
+ * 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 function browserSentence(r, how = 'connected to') {
+    const marks = [r.owned && 'owned', r.headless && 'headless'].filter(Boolean);
+    return `${how} ${[...marks, 'browser'].join(' ')} ${browserAddress(r)}`;
+}
+function uptime(ms) {
+    const s = Math.max(0, Math.floor(ms / 1000));
+    if (s < 60)
+        return `${s}s`;
+    if (s < 3600)
+        return `${Math.floor(s / 60)}m`;
+    return `${Math.floor(s / 3600)}h${String(Math.floor((s % 3600) / 60)).padStart(2, '0')}m`;
+}