sourcemonkey 0.0.0-stage → 0.5.0

package/lib/harness/prompt-editor.js

@@ -0,0 +1,354 @@
+// Multi-line editing for the `--interactive` prompt. readline edits one
+// line, but a `{{` block is several: here the whole block is one buffer
+// holding newlines, typed and edited in place, and sent once complete.
+//
+// - Enter inserts a newline while the buffer holds an unclosed block,
+//   and sends it otherwise. Alt-Enter always inserts one.
+// - Lines after the first are drawn after `... `.
+// - A buffer taller than the terminal is drawn as a window of rows
+//   around the cursor, scrolled as it moves, and drawn whole once sent.
+// - Up and Down move between the buffer's lines, and step through the
+//   history from its first and last line. Once they have brought back
+//   an entry, they step whole entries until another key is pressed, so
+//   a block is passed over in one step. Ctrl-P / Ctrl-N always do.
+// - Home / End and Ctrl-A / Ctrl-E go to the start and end of the line,
+//   Ctrl-U and Ctrl-K delete to them (Ctrl-Y brings it back).
+// - Esc clears the buffer, as Ctrl-C does.
+// - With `paint`, the prompts and the typed text are drawn in color.
+//
+// readline has no hooks for this. It calls these methods through the
+// instance (`_ttyWrite` for each key, `_refreshLine` to redraw,
+// `getCursorPos` for where the cursor is drawn), so they are replaced
+// on it. Its undo and kill ring are only reachable by symbol. All are
+// internal, kept by Node for compatibility; checked on Node 22.
+import readline from 'node:readline';
+/**
+ * Makes `rl` edit several lines as one buffer. `complete` says whether
+ * a buffer is ready to send, rather than inside an unclosed block.
+ * `cleared` gets the text of a buffer emptied by `clear`. `paint`
+ * colors the prompts and the typed text as they are drawn.
+ */
+export function editMultiLine(rl, continuation, complete, cleared, paint) {
+    const r = rl;
+    const ttyWrite = r._ttyWrite.bind(r);
+    const beforeEdit = internal(r, '_beforeEdit');
+    const pushToKillRing = internal(r, '_pushToKillRing');
+    const shown = (text) => text.replaceAll('\n', '\n' + continuation);
+    // Screen columns, by readline's own measure of one character.
+    const widths = new Map();
+    const charWidth = (ch, col) => {
+        if (ch === '\t')
+            return r.tabSize - (col % r.tabSize);
+        let width = widths.get(ch);
+        if (width === undefined)
+            widths.set(ch, (width = r._getDisplayPos(ch).cols));
+        return width;
+    };
+    const textWidth = (text) => {
+        let width = 0;
+        for (const ch of text)
+            width += charWidth(ch, width);
+        return width;
+    };
+    // The screen rows `text` takes from column 0, as the terminal wraps
+    // it, and the row and column just after it. A full row is followed by
+    // an empty one, where the cursor goes, as readline counts it. A wide
+    // character that doesn't fit at a row's end starts the next row.
+    // `starts`: where in `text` each row starts, for painting it.
+    const layout = (text) => {
+        const width = r.columns;
+        const rows = [''];
+        const starts = [0];
+        let col = 0;
+        let at = 0;
+        const newRow = (start) => {
+            rows.push('');
+            starts.push(start);
+            col = 0;
+        };
+        for (const ch of text) {
+            const next = at + ch.length;
+            if (ch === '\n') {
+                newRow(next);
+                at = next;
+                continue;
+            }
+            const w = charWidth(ch, col);
+            if (col + w > width)
+                newRow(at);
+            rows[rows.length - 1] += ch;
+            col += w;
+            at = next;
+            if (col >= width)
+                newRow(at);
+        }
+        return { rows, starts, row: rows.length - 1, col };
+    };
+    // The rows of `text` (a prompt, then the shown buffer) in color: the
+    // prompt and each `... ` as prompts, the rest as typed text.
+    const painted = (text, rows, starts) => {
+        if (!paint)
+            return rows;
+        const isPrompt = new Array(text.length).fill(false);
+        const mark = (from, length) => {
+            for (let i = from; i < from + length && i < text.length; i++)
+                isPrompt[i] = true;
+        };
+        mark(0, r.getPrompt().length);
+        for (let i = text.indexOf('\n'); i >= 0; i = text.indexOf('\n', i + 1))
+            mark(i + 1, continuation.length);
+        return rows.map((row, n) => {
+            let out = '';
+            let run = '';
+            let prompt = false;
+            const flush = () => {
+                if (run)
+                    out += prompt ? paint.prompt(run) : paint.text(run);
+                run = '';
+            };
+            let at = starts[n];
+            for (const ch of row) {
+                if (isPrompt[at] !== prompt) {
+                    flush();
+                    prompt = isPrompt[at];
+                }
+                run += ch;
+                at += ch.length;
+            }
+            flush();
+            return out;
+        });
+    };
+    // The first buffer row drawn, when it is taller than the terminal.
+    let top = 0;
+    // Set while a sent buffer is drawn whole.
+    let whole = false;
+    const cursorAt = () => layout(r.getPrompt() + shown(r.line.slice(0, r.cursor)));
+    // Rows count from the top row drawn, as readline and writeOutputLine
+    // take them.
+    r.getCursorPos = () => {
+        const at = cursorAt();
+        return { rows: at.row - top, cols: at.col };
+    };
+    // readline's own redraw, of the shown text and only the rows that fit.
+    r._refreshLine = () => {
+        const text = r.getPrompt() + shown(r.line);
+        const all = layout(text);
+        const at = cursorAt();
+        // One row spare, so the window never scrolls the terminal itself.
+        const height = whole ? Infinity : Math.max(1, (r.output.rows || 24) - 1);
+        if (all.rows.length <= height)
+            top = 0;
+        else {
+            if (at.row < top)
+                top = at.row;
+            if (at.row >= top + height)
+                top = at.row - height + 1;
+            top = Math.min(top, all.rows.length - height);
+        }
+        const rows = painted(text, all.rows, all.starts).slice(top, top + height);
+        const out = r.output;
+        if (r.prevRows)
+            readline.moveCursor(out, 0, -r.prevRows);
+        readline.cursorTo(out, 0);
+        readline.clearScreenDown(out);
+        // Rows are ended here rather than wrapped by the terminal, so where
+        // each starts doesn't depend on how the terminal wraps.
+        r._writeToOutput(rows.join('\r\n'));
+        readline.cursorTo(out, at.col);
+        const below = rows.length - 1 - (at.row - top);
+        if (below > 0)
+            readline.moveCursor(out, 0, -below);
+        r.prevRows = at.row - top;
+    };
+    const set = (text, cursor = text.length) => {
+        r.line = text;
+        r.cursor = cursor;
+        r._refreshLine();
+    };
+    // A change readline's undo (Ctrl-_) can take back, and deleted text
+    // its Ctrl-Y can bring back, as with its own edits.
+    const edit = (text, cursor, deleted) => {
+        beforeEdit(r.line, r.cursor);
+        if (deleted)
+            pushToKillRing(deleted);
+        set(text, cursor);
+    };
+    const insert = (text) => edit(r.line.slice(0, r.cursor) + text + r.line.slice(r.cursor), r.cursor + text.length);
+    // The start and end of the line holding `at` in the buffer.
+    const lineStart = (at = r.cursor) => (at === 0 ? 0 : r.line.lastIndexOf('\n', at - 1) + 1);
+    const lineEnd = (at = r.cursor) => {
+        const i = r.line.indexOf('\n', at);
+        return i < 0 ? r.line.length : i;
+    };
+    // The prompt's width before the line starting at `start`.
+    const promptWidth = (start) => textWidth(start === 0 ? r.getPrompt() : continuation);
+    // Up or Down a line, keeping the cursor's column on screen, and
+    // between characters. False when there is no line that way.
+    const moveLine = (up) => {
+        const start = lineStart();
+        if (up ? start === 0 : lineEnd() === r.line.length)
+            return false;
+        // Measured with the prompt, as tabs stop at screen columns.
+        const column = textWidth((start === 0 ? r.getPrompt() : continuation) + r.line.slice(start, r.cursor));
+        const target = up ? lineStart(start - 1) : lineEnd() + 1;
+        let at = target;
+        let col = promptWidth(target);
+        for (const ch of r.line.slice(target, lineEnd(target))) {
+            const w = charWidth(ch, col);
+            if (col + w > column)
+                break;
+            col += w;
+            at += ch.length;
+        }
+        set(r.line, at);
+        return true;
+    };
+    // The history, browsed here rather than by readline, which would
+    // replace a buffer with the text before the cursor when no older
+    // entry starts with it, and can't give back what was being typed.
+    // `index` is the entry shown, -1 for what was being typed (`draft`).
+    // Any other key makes the buffer, edited or not, the draft again. As
+    // readline does, a one-line draft only finds entries starting with
+    // its text before the cursor.
+    let index = -1;
+    let draft = '';
+    let prefix = '';
+    // Up / Down last brought back an entry, or the draft, and no other
+    // key since.
+    let browsing = false;
+    const browse = (older) => {
+        const entries = r.history;
+        if (index === -1) {
+            if (!older)
+                return;
+            draft = r.line;
+            prefix = draft.includes('\n') ? '' : draft.slice(0, r.cursor);
+        }
+        for (let i = index + (older ? 1 : -1); older ? i < entries.length : i >= 0; i += older ? 1 : -1) {
+            if (entries[i].startsWith(prefix) && entries[i] !== r.line) {
+                index = i;
+                browsing = true;
+                edit(entries[i], entries[i].length);
+                return;
+            }
+        }
+        if (!older) {
+            index = -1;
+            browsing = true;
+            edit(draft, draft.length);
+        }
+    };
+    function clear() {
+        if (r.line)
+            cleared?.(r.line);
+        index = -1;
+        browsing = false;
+        edit('', 0);
+    }
+    // When the last key was Enter, for the \n of a \r\n pair.
+    let returnAt = 0;
+    // Pasted text put in the buffer but not yet drawn.
+    let undrawn = false;
+    r._ttyWrite = (s, key) => {
+        const name = key?.name;
+        if (name === 'enter' && returnAt && Date.now() - returnAt <= r.crlfDelay) {
+            returnAt = 0;
+            return;
+        }
+        returnAt = name === 'return' ? Date.now() : 0;
+        const enter = name === 'return' || name === 'enter';
+        // Shift is let through: readline's own Shift-Up would browse the
+        // history its way.
+        const plain = !key?.ctrl && !key?.meta;
+        const arrow = (name === 'up' || name === 'down') && plain;
+        const historyKey = arrow || (key?.ctrl && !key.meta && (name === 'p' || name === 'n'));
+        if (!historyKey) {
+            browsing = false;
+            index = -1;
+        }
+        // readline turns `isCompletionEnabled` off for all but the last key
+        // of pasted text, and then writes each character straight out with
+        // no redraw, even when the line wraps, so its record of the rows
+        // drawn (`prevRows`) goes stale. So pasted text, and the newlines
+        // within a block, go in the buffer here, drawn once at the end.
+        const typed = typeof s === 'string' && s !== '' && !/[\x00-\x08\x0a-\x1f\x7f]/.test(s) && plain;
+        if (!r.isCompletionEnabled && (typed || (enter && plain && !complete(r.line)))) {
+            if (!undrawn)
+                beforeEdit(r.line, r.cursor);
+            const text = enter ? '\n' : s;
+            r.line = r.line.slice(0, r.cursor) + text + r.line.slice(r.cursor);
+            r.cursor += text.length;
+            undrawn = true;
+            return;
+        }
+        if (undrawn) {
+            undrawn = false;
+            r._refreshLine();
+        }
+        if (enter) {
+            if (key?.meta || !complete(r.line)) {
+                insert('\n');
+                return;
+            }
+            // Drawn whole, cursor at the end, so the terminal's scrollback
+            // keeps all of what was sent.
+            whole = true;
+            r.cursor = r.line.length;
+            r._refreshLine();
+            ttyWrite(s, key);
+            whole = false;
+            top = 0;
+            return;
+        }
+        if (arrow) {
+            if (browsing || !moveLine(name === 'up'))
+                browse(name === 'up');
+            return;
+        }
+        if (historyKey) {
+            browse(name === 'p');
+            return;
+        }
+        if (name === 'escape') {
+            clear();
+            return;
+        }
+        if ((name === 'home' && plain) || (key?.ctrl && name === 'a')) {
+            set(r.line, lineStart());
+            return;
+        }
+        if ((name === 'end' && plain) || (key?.ctrl && name === 'e')) {
+            set(r.line, lineEnd());
+            return;
+        }
+        if (key?.ctrl && name === 'u') {
+            const start = lineStart();
+            edit(r.line.slice(0, start) + r.line.slice(r.cursor), start, r.line.slice(start, r.cursor));
+            return;
+        }
+        // At a line's end, Ctrl-K joins the next line onto it, as in Emacs.
+        if (key?.ctrl && name === 'k') {
+            const end = r.cursor === lineEnd() && r.cursor < r.line.length ? r.cursor + 1 : lineEnd();
+            edit(r.line.slice(0, r.cursor) + r.line.slice(end), r.cursor, r.line.slice(r.cursor, end));
+            return;
+        }
+        // Typed at the buffer's end, readline writes the text straight out
+        // with no redraw, so in color it is redrawn to take the typed color.
+        const atEnd = typed && r.cursor === r.line.length;
+        ttyWrite(s, key);
+        if (paint && atEnd)
+            r._refreshLine();
+    };
+    return { clear };
+}
+// A readline method kept under a symbol, found by its name, or one that
+// does nothing should a Node version not have it.
+function internal(rl, name) {
+    for (let proto = Object.getPrototypeOf(rl); proto; proto = Object.getPrototypeOf(proto)) {
+        const symbol = Object.getOwnPropertySymbols(proto).find((s) => s.description === name);
+        if (symbol)
+            return (...args) => rl[symbol](...args);
+    }
+    return () => undefined;
+}

package/lib/harness/prompt-history.d.ts

@@ -0,0 +1,13 @@
+/** How many entries a session loads, and the file keeps. */
+export declare const HISTORY_SIZE = 1000;
+/** The history file, or null when history isn't kept. */
+export declare function historyFile(): string | null;
+/**
+ * The entries in the file's last `HISTORY_SIZE` lines, newest first, as
+ * readline takes them. A missing or unreadable file is no history.
+ * The file is cut back to that many lines once it holds twice as many,
+ * since each session only appends to it.
+ */
+export declare function loadHistory(file: string): string[];
+/** Adds an entry to the end of the file. Throws when it can't. */
+export declare function appendHistory(file: string, entry: string): void;

package/lib/harness/prompt-history.js

@@ -0,0 +1,89 @@
+// The `--interactive` prompt's history, kept across sessions in
+// ~/.sm-dev-history (or `SM_DEV_HISTORY`; set it empty for none).
+//
+// As in a shell with `histappend`, sessions share the file without
+// overwriting each other: each loads it when it starts, and appends
+// its own commands as they are typed. A session doesn't see another's
+// commands until it is restarted.
+//
+// One entry per line, as a JSON string, since a `{{` block is one
+// entry of several lines.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/** How many entries a session loads, and the file keeps. */
+export const HISTORY_SIZE = 1000;
+/** The history file, or null when history isn't kept. */
+export function historyFile() {
+    const chosen = process.env.SM_DEV_HISTORY;
+    if (chosen !== undefined)
+        return chosen.trim() ? path.resolve(chosen.trim()) : null;
+    return path.join(os.homedir(), '.sm-dev-history');
+}
+/**
+ * The entries in the file's last `HISTORY_SIZE` lines, newest first, as
+ * readline takes them. A missing or unreadable file is no history.
+ * The file is cut back to that many lines once it holds twice as many,
+ * since each session only appends to it.
+ */
+export function loadHistory(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const lines = text.split('\n').filter(Boolean);
+    const entries = [];
+    for (const line of lines.slice(-HISTORY_SIZE)) {
+        try {
+            const entry = JSON.parse(line);
+            if (typeof entry === 'string' && entry !== entries.at(-1))
+                entries.push(entry);
+        }
+        catch {
+            // A line cut short by a crash mid-write: skipped.
+        }
+    }
+    try {
+        if (lines.length >= 2 * HISTORY_SIZE) {
+            // Written aside and renamed, so a session reading the file never
+            // sees half of it. One appending meanwhile loses that entry.
+            const temp = `${file}.${process.pid}.tmp`;
+            try {
+                writePrivate(temp, lines.slice(-HISTORY_SIZE).join('\n') + '\n', 'w');
+                fs.renameSync(temp, file);
+            }
+            finally {
+                fs.rmSync(temp, { force: true });
+            }
+        }
+        else if (text && !text.endsWith('\n')) {
+            // End a cut-short line, so the next entry doesn't join it.
+            writePrivate(file, '\n', 'a');
+        }
+    }
+    catch {
+        // Tidying only. A file that can't be written is reported by the
+        // first appendHistory.
+    }
+    return entries.reverse();
+}
+/** Adds an entry to the end of the file. Throws when it can't. */
+export function appendHistory(file, entry) {
+    writePrivate(file, JSON.stringify(entry) + '\n', 'a');
+}
+// Every write of the file goes through here, so it stays readable only
+// by its owner: commands can hold passwords (`type`) and tokens. A
+// file's mode is only set when it is made, so it is set again here.
+function writePrivate(file, text, flag) {
+    const fd = fs.openSync(file, flag, 0o600);
+    try {
+        fs.fchmodSync(fd, 0o600);
+        fs.writeSync(fd, text);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}

package/lib/harness/rebuild-advice.d.ts

@@ -0,0 +1,6 @@
+/**
+ * How to rebuild what this sm-dev runs from, as a sentence: in the
+ * checkout itself, or in the checkout an installed copy came from and
+ * then here.
+ */
+export declare function rebuildAdvice(): string;

package/lib/harness/rebuild-advice.js

@@ -0,0 +1,39 @@
+// How to bring this sm-dev up to date, for messages that need it.
+//
+// The build records the checkout it was built from in
+// lib/build-info.json. That covers both ways sm-dev runs:
+//   - In the checkout itself (scripts/sm-dev), from its own lib/.
+//   - In a repo of userscripts, from the copy `pnpm install` took (with
+//     no src/ of its own). `pnpm install` copies the checkout's lib/ as
+//     it is, without building it first, so the fix needs a build there
+//     too.
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { quoted } from './output-style.js';
+// lib/, beside this module's lib/harness/.
+const LIB_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+/**
+ * How to rebuild what this sm-dev runs from, as a sentence: in the
+ * checkout itself, or in the checkout an installed copy came from and
+ * then here.
+ */
+export function rebuildAdvice() {
+    const source = buildSource();
+    if (!source)
+        return 'Run `pnpm run build` in SourceMonkey, and `pnpm install` again where it is installed.';
+    if (path.resolve(source, 'lib') === LIB_DIR)
+        return 'Run `pnpm run build`.';
+    return `Run ${quoted('pnpm run build')} in ${source}, then ${quoted('pnpm install')} here.`;
+}
+// The checkout lib/ was built from, or null: built before
+// build-info.json existed, or not by build.mjs, leaves nothing to go by.
+function buildSource() {
+    try {
+        const info = JSON.parse(readFileSync(path.join(LIB_DIR, 'build-info.json'), 'utf8'));
+        return typeof info.source === 'string' ? info.source : null;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,47 @@
+import { type FileHandle } from 'node:fs/promises';
+/**
+ * Where the logs go: `/tmp/sm-dev-logs-<user>` on most machines.
+ * `SM_DEV_LOGS_DIR` moves it, for tests.
+ */
+export declare function runLogsDir(): string;
+/**
+ * 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 declare function runDownloadsDir(log?: string): string;
+/**
+ * Local time as `20260408-203012-345`: SeeWhatISee's file-name
+ * timestamp. Names the log files, and starts each line in them.
+ */
+export declare function logTimestamp(ms?: number): string;
+/** A log line's timestamp and the space after it, for taking back off. */
+export declare const LOG_LINE_PREFIX: RegExp;
+/**
+ * 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 declare function createRunLog(): Promise<{
+    file: string;
+    handle: FileHandle;
+}>;
+/**
+ * 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 declare function timestampOutputLines(): void;
+/**
+ * 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 declare function runLogLabel(file: string, id: string | undefined): string;
+/**
+ * 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 declare function linkRunLog(file: string, id: string, out: (line: string) => void): Promise<void>;