sourcemonkey 0.0.0-stage → 0.5.0

package/lib/harness/run-log.js

@@ -0,0 +1,140 @@
+// A run's log file: its stream, each line timestamped, to tail or read
+// back for what happened and when. The run's process writes its output
+// there. Each file is named by its start time and kept after the run
+// ends.
+//
+// Node-only, like runs.ts.
+import { randomBytes } from 'node:crypto';
+import { mkdir, open, rename, rm, symlink } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
+import { checkPrivateDir, owner } from './runs.js';
+/**
+ * Where the logs go: `/tmp/sm-dev-logs-<user>` on most machines.
+ * `SM_DEV_LOGS_DIR` moves it, for tests.
+ */
+export function runLogsDir() {
+    return process.env.SM_DEV_LOGS_DIR || path.join(os.tmpdir(), `sm-dev-logs-${owner()}`);
+}
+/**
+ * Where a temp browser run's downloads go: in the logs folder, named
+ * after the run's log when it has one, and kept after the run ends as
+ * the log is (the browser's own profile is deleted).
+ */
+export function runDownloadsDir(log) {
+    if (!log)
+        return path.join(runLogsDir(), `sm-dev-${logTimestamp()}-downloads`);
+    const { dir, name } = path.parse(log);
+    return path.join(dir, `${name}-downloads`);
+}
+/**
+ * Local time as `20260408-203012-345`: SeeWhatISee's file-name
+ * timestamp. Names the log files, and starts each line in them.
+ */
+export function logTimestamp(ms = Date.now()) {
+    const d = new Date(ms);
+    const pad = (n, width = 2) => String(n).padStart(width, '0');
+    return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}`
+        + `-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`
+        + `-${pad(d.getMilliseconds(), 3)}`;
+}
+/** A log line's timestamp and the space after it, for taking back off. */
+export const LOG_LINE_PREFIX = /^\d{8}-\d{6}-\d{3} /;
+/**
+ * Creates a new log file, `sm-dev-<timestamp>.log`. A name already
+ * taken moves the timestamp on a millisecond and tries again; created
+ * exclusively, so two runs starting together can't share one.
+ */
+export async function createRunLog() {
+    const dir = runLogsDir();
+    try {
+        await mkdir(dir, { recursive: true, mode: 0o700 });
+    }
+    catch (err) {
+        throw new Error(`Could not create the log directory ${dir}: ${err.message}`);
+    }
+    // In a shared temp directory, another user could have made it first,
+    // and then delete or swap the run links.
+    await checkPrivateDir(dir, 'log');
+    for (let ms = Date.now();; ms++) {
+        const file = path.join(dir, `sm-dev-${logTimestamp(ms)}.log`);
+        try {
+            return { file, handle: await open(file, 'wx', 0o600) };
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST') {
+                throw new Error(`Could not create the log file ${file}: ${err.message}`);
+            }
+        }
+    }
+}
+/**
+ * Starts each line this process writes to stdout and stderr with the
+ * time it was written. For the detached run, whose output is its log
+ * file. Output that bypasses the streams (a crash in Node itself)
+ * still lands in the file, unstamped.
+ */
+export function timestampOutputLines() {
+    // Shared, since both streams go to the one file.
+    let atLineStart = true;
+    for (const stream of [process.stdout, process.stderr]) {
+        const write = stream.write.bind(stream);
+        // So a character split across two byte writes survives.
+        const decoder = new StringDecoder('utf8');
+        stream.write = ((chunk, ...rest) => {
+            const text = typeof chunk === 'string' ? chunk : decoder.write(Buffer.from(chunk));
+            const stamp = logTimestamp();
+            let out = '';
+            for (const [i, part] of text.split('\n').entries()) {
+                if (i > 0) {
+                    out += '\n';
+                    atLineStart = true;
+                }
+                if (part === '')
+                    continue;
+                if (atLineStart)
+                    out += `${stamp} `;
+                atLineStart = false;
+                out += part;
+            }
+            // A string, whatever came in, so an encoding argument no longer applies.
+            const callback = rest.find((r) => typeof r === 'function');
+            return callback ? write(out, callback) : write(out);
+        });
+    }
+}
+/** The link to a run's latest log, beside it: `D1.log`. */
+function runLogLinkName(id) {
+    return `${id}.log`;
+}
+/**
+ * A log's full path, and its link's name when it has one, for printing:
+ * `/tmp/sm-dev-logs-you/sm-dev-20260926-063756-629.log (D1.log)`.
+ */
+export function runLogLabel(file, id) {
+    return id && process.platform !== 'win32' ? `${file} (${runLogLinkName(id)})` : file;
+}
+/**
+ * Points `<run id>.log`, beside the log, at it: the latest log of
+ * a run with that id, found by the id alone. Swapped in by a rename, so
+ * the link is never missing or half made. A failure only costs the
+ * link, so it is said and the run goes on.
+ */
+export async function linkRunLog(file, id, out) {
+    // A file symlink there takes admin rights or Developer Mode, so most
+    // runs would only say it failed.
+    if (process.platform === 'win32')
+        return;
+    const link = path.join(path.dirname(file), runLogLinkName(id));
+    const temp = `${link}.${randomBytes(4).toString('hex')}.tmp`;
+    try {
+        // Relative, so the pair still works if the directory is moved.
+        await symlink(path.basename(file), temp);
+        await rename(temp, link);
+    }
+    catch (err) {
+        await rm(temp, { force: true }).catch(() => undefined);
+        out(`[sm-dev] Could not link ${link} to the log: ${err.message}`);
+    }
+}

package/lib/harness/run-logs.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Where a line came from, from narrowest to broadest:
+ * - `sm`: SourceMonkey logs: the run's scripts' Log tab entries.
+ * - `event`: script and tab events sm-dev saw: starts, page loads,
+ *   errors, menu commands, dialog boxes, tabs opened.
+ * - `script`: Chrome console logs that came from the run's scripts.
+ * - `page`: full Chrome console logs, the scripts' included.
+ */
+export type LogSource = 'sm' | 'event' | 'script' | 'page';
+export declare const LOG_SOURCES: readonly LogSource[];
+/** What the stream and `logs` show unless told otherwise: all but `page`. */
+export declare const DEFAULT_LOG_SOURCES: ReadonlySet<LogSource>;
+export declare const ALL_LOG_SOURCES: ReadonlySet<LogSource>;
+/** Whether a line belongs to any of `sources`. */
+export declare function inSources(record: LogFields, sources: ReadonlySet<LogSource>): boolean;
+/** A `--log-source` value: a source, several separated by commas, or `all`. */
+export declare function parseLogSources(text: string): ReadonlySet<LogSource> | {
+    error: string;
+};
+/** A line as it's logged, before it has an ID. */
+export interface LogFields {
+    /** The source its prefix names. */
+    source: LogSource;
+    /**
+     * Other sources it belongs to, so asking for any one of them shows it:
+     * a script's throw is an event, a Log entry, and the script's own.
+     */
+    also?: LogSource[];
+    /** The console type (`log`, `warning`, ...), the Log entry's level, or the event's name. */
+    kind: string;
+    /** The tab it came from (`T<n>`'s n); none for a Log entry made outside a tab. */
+    tab?: number;
+    /** The tab's iframe it came from (`F<n>`'s n), when known. */
+    frame?: number;
+    /** The run's script it's about (`PreparedScript.id`), when known. */
+    scriptId?: string;
+    /** The line after its prefix. Can run over several lines (a stack). */
+    text: string;
+    /** False for a line only `logs` and `wait log` see: a page load, which the stream says its own way. */
+    streamed?: boolean;
+    /** Streamed whatever sources were asked for: a dialog box, which holds up the page until answered. */
+    always?: boolean;
+}
+/** A logged line. */
+export interface LogRecord extends LogFields {
+    /** Its log ID: when it arrived, in microseconds since the epoch, unique and increasing. */
+    id: number;
+}
+/**
+ * Now, in microseconds since the epoch. By the wall clock, which
+ * `--since` times are read by; `performance`'s drifts from it after a
+ * sleep. RunLog keeps IDs increasing if the clock steps back.
+ */
+export declare function nowMicros(): number;
+/** A run's log lines, for `logs` and `wait log`, and a way to hear new ones. */
+export declare class RunLog {
+    private readonly records;
+    private lastId;
+    private droppedUpTo;
+    private readonly watchers;
+    /** Logs a line: its ID given, its text cut past a length. */
+    add(fields: LogFields): LogRecord;
+    /** The lines kept, oldest first. */
+    all(): readonly LogRecord[];
+    /** The lines after `id`, oldest first. */
+    since(id: number): LogRecord[];
+    /**
+     * The position reached: the newest line's ID, or now when there's
+     * none yet. Any line after it gets a higher ID.
+     */
+    position(): number;
+    /** When lines after `id` were dropped for space: the oldest kept line's ID. */
+    lostAfter(id: number): number | undefined;
+    /** Calls `listener` with each new line, until the returned function is called. */
+    watch(listener: (record: LogRecord) => void): () => void;
+}
+/**
+ * A `--since` value as a log ID: a log ID itself, an ISO 8601 time
+ * (local without a zone), or a time of day today, local.
+ */
+export declare function parsePosition(text: string, now?: Date): number | {
+    error: string;
+};
+/** A `--tail` value: a number of lines, or a stretch of time (`30s`, `5m`). */
+export declare function parseTail(text: string): {
+    lines: number;
+} | {
+    micros: number;
+} | {
+    error: string;
+};
+/** A log ID's time of day, local: `14:05:12.678`. */
+export declare function timeOfDay(id: number): string;
+/** A log ID as ISO 8601, for JSON. */
+export declare function isoTime(id: number): string;
+export declare const logsUpTo: (id: number) => string;
+export declare const foundAt: (id: number) => string;
+export declare const searchedUpTo: (id: number) => string;
+export declare const linesLost: (oldest: number) => string;
+/** `tab`: the tab asked for (`T4`), or none for all of them. */
+export declare const noLogLines: (tab?: string) => string;
+/**
+ * What `--find` (or `wait log`'s text) matches: a plain substring, or
+ * `/regex/flags`. `shown`: how a message names it.
+ */
+export declare function textMatcher(text: string, flag?: string): {
+    matches: (line: string) => boolean;
+    shown: string;
+} | {
+    error: string;
+};
+/** `[event]`, `[script log]`, `[sm error]`, `[page warning]`. */
+export declare function sourcePrefix(record: LogFields): string;
+/** A console line as the stream shows it: cut past CONSOLE_SHOWN_CHARS. */
+export declare function shortConsoleText(text: string): string;
+/** Where a line came from: `T2`, or `T1.F3` for an iframe; '' for none. */
+export declare function lineOrigin(record: LogFields): string;
+/**
+ * A line as the stream prints it: `[T2] ` for a tab after T1, `[T1.F3] `
+ * for an iframe of any tab, its
+ * prefix, then its text, a console line cut past a length unless
+ * `whole` (`wait log` matches it whole).
+ */
+export declare function streamText(record: LogFields, whole?: boolean): string;
+/** `streamText`'s line as the stream shows it: its prefix dimmed, an error or warning in color. */
+export declare function streamLine(record: LogFields): string;
+/**
+ * Lines as `logs` prints them: the time and tab, then the prefix and
+ * text, each run of identical lines once, marked `(N times)`. In color
+ * as the stream shows them (see streamLine).
+ */
+export declare function logsLines(records: readonly LogRecord[]): string[];

package/lib/harness/run-logs.js

@@ -0,0 +1,241 @@
+// A run's log: every line the page, the scripts, SourceMonkey and the
+// run's events produce, each tagged with its source, kept run-wide for
+// `logs` and `wait log`, and streamed to the clients that asked for its
+// source. See docs/sm-dev-logs.md.
+//
+// Light, importing only output-style.ts (which imports nothing):
+// runs.ts, which the sm-dev client loads, takes the sources from here.
+import { asError, asWarning, dim, ui } from './output-style.js';
+export const LOG_SOURCES = ['sm', 'event', 'script', 'page'];
+/** What the stream and `logs` show unless told otherwise: all but `page`. */
+export const DEFAULT_LOG_SOURCES = new Set(['sm', 'event', 'script']);
+export const ALL_LOG_SOURCES = new Set(LOG_SOURCES);
+/** Whether a line belongs to any of `sources`. */
+export function inSources(record, sources) {
+    return sources.has(record.source) || (record.also ?? []).some((s) => sources.has(s));
+}
+/** A `--log-source` value: a source, several separated by commas, or `all`. */
+export function parseLogSources(text) {
+    const words = text.split(',').map((w) => w.trim()).filter(Boolean);
+    if (words.length === 1 && words[0] === 'all')
+        return ALL_LOG_SOURCES;
+    const wrong = words.find((w) => !LOG_SOURCES.includes(w));
+    if (words.length === 0 || wrong !== undefined) {
+        return { error: `The --log-source flag takes ${LOG_SOURCES.join(', ')} or all, or multiple separated by commas${wrong !== undefined ? `, not ${wrong}` : ''}` };
+    }
+    return new Set(words);
+}
+// How many lines a run keeps, oldest dropped first, and how long each
+// can be.
+const KEPT_LINES = 5000;
+const LINE_CHARS = 2000;
+/**
+ * Now, in microseconds since the epoch. By the wall clock, which
+ * `--since` times are read by; `performance`'s drifts from it after a
+ * sleep. RunLog keeps IDs increasing if the clock steps back.
+ */
+export function nowMicros() {
+    return Date.now() * 1000;
+}
+// `text`'s first `chars` UTF-16 units, one fewer rather than half an
+// emoji.
+function cutAt(text, chars) {
+    const code = text.charCodeAt(chars - 1);
+    return text.slice(0, code >= 0xd800 && code <= 0xdbff ? chars - 1 : chars);
+}
+/** A run's log lines, for `logs` and `wait log`, and a way to hear new ones. */
+export class RunLog {
+    records = [];
+    lastId = 0;
+    // The newest line dropped for space, if any.
+    droppedUpTo = 0;
+    watchers = new Set();
+    /** Logs a line: its ID given, its text cut past a length. */
+    add(fields) {
+        this.lastId = Math.max(nowMicros(), this.lastId + 1);
+        const text = fields.text.length > LINE_CHARS ? `${cutAt(fields.text, LINE_CHARS)}…` : fields.text;
+        const record = { ...fields, text, id: this.lastId };
+        this.records.push(record);
+        if (this.records.length > KEPT_LINES)
+            this.droppedUpTo = this.records.shift().id;
+        for (const watcher of [...this.watchers])
+            watcher(record);
+        return record;
+    }
+    /** The lines kept, oldest first. */
+    all() {
+        return this.records;
+    }
+    /** The lines after `id`, oldest first. */
+    since(id) {
+        // From the end: usually only the last few are wanted.
+        let i = this.records.length;
+        while (i > 0 && this.records[i - 1].id > id)
+            i--;
+        return this.records.slice(i);
+    }
+    /**
+     * The position reached: the newest line's ID, or now when there's
+     * none yet. Any line after it gets a higher ID.
+     */
+    position() {
+        if (this.lastId === 0)
+            this.lastId = nowMicros();
+        return this.lastId;
+    }
+    /** When lines after `id` were dropped for space: the oldest kept line's ID. */
+    lostAfter(id) {
+        return id < this.droppedUpTo ? this.records[0]?.id : undefined;
+    }
+    /** Calls `listener` with each new line, until the returned function is called. */
+    watch(listener) {
+        this.watchers.add(listener);
+        return () => { this.watchers.delete(listener); };
+    }
+}
+// ---------- Positions and spans ----------
+const SINCE_FORMS = 'a log ID, an ISO 8601 time such as 2026-10-03T14:05:12Z, or a time of day such as 14:05:12';
+/**
+ * A `--since` value as a log ID: a log ID itself, an ISO 8601 time
+ * (local without a zone), or a time of day today, local.
+ */
+export function parsePosition(text, now = new Date()) {
+    if (/^\d+$/.test(text))
+        return Number(text);
+    const time = /^(\d{1,2}):(\d{2})(?::(\d{2})(?:\.(\d{1,6}))?)?$/.exec(text);
+    if (time) {
+        const [, h, m, s = '0', frac = ''] = time;
+        const day = new Date(now.getFullYear(), now.getMonth(), now.getDate(), Number(h), Number(m), Number(s));
+        if (Number(h) > 23 || Number(m) > 59 || Number(s) > 59)
+            return { error: `The --since flag takes ${SINCE_FORMS}, not ${text}` };
+        return day.getTime() * 1000 + Number(frac.padEnd(6, '0'));
+    }
+    if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(text)) {
+        const ms = Date.parse(text);
+        if (!Number.isNaN(ms))
+            return ms * 1000;
+    }
+    return { error: `The --since flag takes ${SINCE_FORMS}, not ${text}` };
+}
+/** A `--tail` value: a number of lines, or a stretch of time (`30s`, `5m`). */
+export function parseTail(text) {
+    if (/^\d+$/.test(text) && Number(text) > 0)
+        return { lines: Number(text) };
+    const span = /^(\d+(?:\.\d+)?)(ms|s|m|h)$/.exec(text);
+    if (span)
+        return { micros: Math.round(Number(span[1]) * { ms: 1e3, s: 1e6, m: 6e7, h: 3.6e9 }[span[2]]) };
+    return { error: `The --tail flag takes a number of lines, or a time such as 500ms, 30s, 5m or 1h, not ${text}` };
+}
+/** A log ID's time of day, local: `14:05:12.678`. */
+export function timeOfDay(id) {
+    const d = new Date(Math.floor(id / 1000));
+    const pad = (n, width = 2) => String(n).padStart(width, '0');
+    return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${pad(d.getMilliseconds(), 3)}`;
+}
+/** A log ID as ISO 8601, for JSON. */
+export function isoTime(id) {
+    return new Date(Math.floor(id / 1000)).toISOString();
+}
+// The end-of-logs lines, which say where to pick up with --since.
+const at = (id) => `${id} (${timeOfDay(id)})`;
+export const logsUpTo = (id) => `[sm-dev] Logs up to ${at(id)}`;
+export const foundAt = (id) => `[sm-dev] Found at ${at(id)}`;
+export const searchedUpTo = (id) => `[sm-dev] Searched up to ${at(id)}`;
+export const linesLost = (oldest) => `[sm-dev] Lines before ${timeOfDay(oldest)} are no longer kept`;
+/** `tab`: the tab asked for (`T4`), or none for all of them. */
+export const noLogLines = (tab) => `[sm-dev] No log lines match ${tab ? `on tab ${tab}` : 'on any tab'}`;
+// ---------- Text to find ----------
+/**
+ * What `--find` (or `wait log`'s text) matches: a plain substring, or
+ * `/regex/flags`. `shown`: how a message names it.
+ */
+export function textMatcher(text, flag = '--find') {
+    const regex = /^\/(.+)\/([a-z]*)$/.exec(text);
+    if (!regex)
+        return { matches: (line) => line.includes(text), shown: JSON.stringify(text) };
+    let pattern;
+    try {
+        pattern = new RegExp(regex[1], regex[2]);
+    }
+    catch (err) {
+        return { error: `${text} is not a valid regular expression${flag ? ` for ${flag}` : ''}: ${err.message}` };
+    }
+    // Each line from its start: g and y otherwise carry on from where the
+    // last match ended, which would skip matches.
+    return {
+        matches: (line) => {
+            pattern.lastIndex = 0;
+            return pattern.test(line);
+        },
+        shown: text,
+    };
+}
+// ---------- How lines read ----------
+/** `[event]`, `[script log]`, `[sm error]`, `[page warning]`. */
+export function sourcePrefix(record) {
+    return record.source === 'event' ? '[event]' : `[${record.source} ${record.kind}]`;
+}
+// Longer console lines are cut in the stream, so one huge value (a
+// fetched page, a cache) doesn't bury the rest. `logs` shows them whole.
+const CONSOLE_SHOWN_CHARS = 1000;
+/** A console line as the stream shows it: cut past CONSOLE_SHOWN_CHARS. */
+export function shortConsoleText(text) {
+    if (text.length <= CONSOLE_SHOWN_CHARS)
+        return text;
+    // By code point, so an emoji isn't cut in half.
+    return `${Array.from(text).slice(0, CONSOLE_SHOWN_CHARS).join('')}... (${text.length} chars; logs shows ${text.length > LINE_CHARS ? `the first ${LINE_CHARS}` : 'it all'})`;
+}
+/** Where a line came from: `T2`, or `T1.F3` for an iframe; '' for none. */
+export function lineOrigin(record) {
+    if (record.tab === undefined)
+        return '';
+    return `T${record.tab}${record.frame !== undefined ? `.F${record.frame}` : ''}`;
+}
+/**
+ * A line as the stream prints it: `[T2] ` for a tab after T1, `[T1.F3] `
+ * for an iframe of any tab, its
+ * prefix, then its text, a console line cut past a length unless
+ * `whole` (`wait log` matches it whole).
+ */
+export function streamText(record, whole = false) {
+    const shown = record.tab !== undefined && (record.tab > 1 || record.frame !== undefined);
+    return `${shown ? `[${lineOrigin(record)}] ` : ''}${sourcePrefix(record)} ${streamBody(record, whole)}`;
+}
+// A line's text as the stream shows it: a console line cut past a
+// length unless `whole`.
+function streamBody(record, whole = false) {
+    const console = record.source === 'script' || record.source === 'page';
+    return console && !whole ? shortConsoleText(record.text) : record.text;
+}
+// A line's text in color by its level: an error's, a warning's, or as
+// is. Taken as it is, since a script or page wrote it.
+function leveledText(record, text) {
+    const level = record.source === 'event' ? (record.kind === 'threw' ? 'error' : '') : record.kind;
+    return level === 'error' ? asError(text) : level === 'warning' || level === 'warn' ? asWarning(text) : text;
+}
+/** `streamText`'s line as the stream shows it: its prefix dimmed, an error or warning in color. */
+export function streamLine(record) {
+    const shown = record.tab !== undefined && (record.tab > 1 || record.frame !== undefined);
+    return ui `${dim(`${shown ? `[${lineOrigin(record)}] ` : ''}${sourcePrefix(record)}`)} ${leveledText(record, streamBody(record))}`;
+}
+/**
+ * Lines as `logs` prints them: the time and tab, then the prefix and
+ * text, each run of identical lines once, marked `(N times)`. In color
+ * as the stream shows them (see streamLine).
+ */
+export function logsLines(records) {
+    const width = Math.max(0, ...records.map((r) => lineOrigin(r).length));
+    const head = (r) => `${lineOrigin(r).padEnd(width)}${width > 0 ? ' ' : ''}${sourcePrefix(r)}`;
+    const body = (r) => `${head(r)} ${r.text}`;
+    const lines = [];
+    for (let i = 0; i < records.length;) {
+        const r = records[i];
+        const text = body(r);
+        let end = i + 1;
+        while (end < records.length && body(records[end]) === text)
+            end++;
+        lines.push(ui `${dim(`${timeOfDay(r.id)} ${head(r)}`)} ${leveledText(r, r.text)}${end - i > 1 ? ` (${end - i} times)` : ''}`);
+        i = end;
+    }
+    return lines;
+}