@specific.dev/spectest 0.26.0 → 0.27.0

package/dist/terminal.js

@@ -0,0 +1,538 @@
+// Interactive terminal handle for tests. Backed by `docker exec -it`
+// inside a `script(1)` PTY wrapper so the container program sees a real
+// TTY (line discipline, ANSI escapes, isatty(1) true) while the daemon
+// drives stdin/stdout through ordinary pipes.
+//
+// We feed every byte the PTY emits into two sinks:
+//   1. A headless `@xterm/headless` Terminal that maintains the rendered
+//      screen state (cursor, scrollback, alt-screen, attributes). This is
+//      what `waitFor`'s predicate evaluates against (and what the
+//      internal `rawScreen()` returns) — the analogue of evaluating
+//      against the DOM in a Browser session.
+//   2. The asciicast frame callback the daemon hooks up to a
+//      TerminalSessionRecord. Same recording format as before; the web
+//      UI replays it with asciinema-player.
+//
+// The one-shot `ctx.terminal(service, command, opts?)` API in `index.ts`
+// is built on top of this factory — it opens a Terminal, doesn't write
+// to stdin, waits for the process to exit, and closes. So everything
+// that flows through `ctx.terminal` flows through this code too.
+//
+// PTY-on-the-host trick: the daemon runs under systemd with no controlling
+// TTY, so `docker exec -it` (the docker CLI rejects -it when its own stdin
+// isn't a TTY) needs a PTY wrapper. `script -qfc 'CMD' /dev/null` allocates
+// a PTY for CMD; we set the slave's size with `stty rows R cols C` inside
+// the wrapped command so the container app sees the cols/rows the caller
+// asked for. `script(1)` ships in util-linux which is essential on Debian,
+// so it's present in the Freestyle base image without extra apt deps.
+import { Terminal as XtermHeadless } from "@xterm/headless";
+import { recordTerminalStep, reserveEvent, truncateUtf8 } from "./recorder.js";
+import { wrap } from "./inspect.js";
+// Cap on cumulative output we keep in memory. The asciicast frames
+// grow separately (they live on the session record) and aren't bounded
+// here. Matches `TERMINAL_OUTPUT_CAP_BYTES` in daemon.ts.
+const OUTPUT_CAP_BYTES = 1024 * 1024;
+// Default scrollback for the headless emulator. Generous enough that
+// long output histories aren't lost between `screen()` calls, small
+// enough that the per-session memory cost stays bounded.
+const SCROLLBACK = 10_000;
+// Deadline for the TTY echo when recording a send/press step.
+//
+// Why we wait at all: `castTimeSec` is supposed to point at the cast
+// frame the user wants to see when they click the step. For
+// send/press, that's the frame containing the echo of what we typed.
+// The echo is a PTY round-trip (our pipe → script → container TTY →
+// kernel echo back → script → our pipe) that takes a few ms — at the
+// instant `writeStdin` returns, no frame yet exists that contains the
+// typed bytes. So we await the next ingested frame; that frame IS the
+// echo. This isn't a fixed delay — it resolves as soon as the echo
+// lands, typically <30ms.
+//
+// The timeout is a safety hatch only: if the program reads the input
+// without ever echoing (rare — would require either raw mode + no app
+// response, or a closed-fd condition), we don't want to hang the test.
+// In that case `castTimeSec` falls back to the write moment, which is
+// fine because there's no later echo frame for it to misalign with.
+const ECHO_WAIT_MS = 120;
+/**
+ * Open a PTY-backed interactive terminal in a service container.
+ *
+ * The factory itself doesn't know about `TerminalSessionRecord`s — it
+ * just calls `sink.pushFrame` for every chunk it sees and `markClosed`
+ * when the session ends. The daemon owns the record and the sink.
+ */
+export async function openTerminal(args) {
+    const { service, opts, sink, sessionId } = args;
+    const cols = opts?.cols ?? 80;
+    const rows = opts?.rows ?? 24;
+    const userEnv = opts?.env ?? {};
+    const term = userEnv.TERM ?? "xterm-256color";
+    // Build the inner docker exec invocation. With `-it` the container
+    // sees a real TTY and dockerd merges stderr into stdout, so we only
+    // need to drain one stream from the PTY.
+    const dockerArgs = ["exec", "-it"];
+    dockerArgs.push("-e", `TERM=${term}`);
+    dockerArgs.push("-e", `COLUMNS=${cols}`);
+    dockerArgs.push("-e", `LINES=${rows}`);
+    for (const [k, v] of Object.entries(userEnv)) {
+        if (k === "TERM")
+            continue;
+        dockerArgs.push("-e", `${k}=${v}`);
+    }
+    dockerArgs.push(service);
+    if (opts?.command !== undefined) {
+        dockerArgs.push("sh", "-lc", opts.command);
+    }
+    else {
+        // Login shell — gives the user a $PS1 prompt to drive interactively.
+        dockerArgs.push("sh", "-l");
+    }
+    // Quote the inner docker command for `script -c`. We pass it as a
+    // single shell string. `stty` sets the PTY slave's size to the
+    // requested cols/rows before exec'ing docker — without this, the
+    // container app would see whatever size script's parent had (often
+    // 80x24, but the daemon has none, so it's whatever util-linux picks
+    // as the fallback).
+    const inner = `stty rows ${rows} cols ${cols} 2>/dev/null; exec ${shellQuote(["docker", ...dockerArgs])}`;
+    // `script -q -f -c CMD /dev/null` runs CMD in a PTY (no preamble, flushed
+    // after each write, output discarded — we capture via stdout pipe).
+    const spawnArgs = ["script", "-qfc", inner, "/dev/null"];
+    const start = Date.now();
+    const proc = Bun.spawn(spawnArgs, {
+        stdin: "pipe",
+        stdout: "pipe",
+        stderr: "pipe",
+    });
+    // Headless screen model. `allowProposedApi` lets us call `buffer.active`
+    // safely (it's marked EXPERIMENTAL in the public typings).
+    const emu = new XtermHeadless({
+        cols,
+        rows,
+        scrollback: SCROLLBACK,
+        allowProposedApi: true,
+    });
+    let output = "";
+    let exited = false;
+    let exitCode;
+    let closed = false;
+    let resolveExit;
+    const rawExited = new Promise((res) => {
+        resolveExit = res;
+    });
+    // Cast time at the moment the process actually exited. Captured by
+    // the IIFE below so the `exit` step we record points the player at
+    // the very end of the visible session.
+    let exitCastTimeSec;
+    const decoder = new TextDecoder("utf-8", { fatal: false });
+    // Subscribers waiting for the next frame to arrive. Used by send /
+    // sendLine / press so the recorded `castTimeSec` lands on the echo's
+    // frame instead of microseconds before it.
+    const frameWaiters = [];
+    const ingest = (chunk) => {
+        const t = (Date.now() - start) / 1000;
+        sink.pushFrame(t, chunk);
+        emu.write(chunk);
+        if (output.length < OUTPUT_CAP_BYTES) {
+            const room = OUTPUT_CAP_BYTES - output.length;
+            output += chunk.length > room ? chunk.slice(0, room) : chunk;
+        }
+        if (frameWaiters.length > 0) {
+            const fns = frameWaiters.splice(0, frameWaiters.length);
+            for (const fn of fns)
+                fn();
+        }
+    };
+    /**
+     * Resolve when the next PTY frame is ingested, or after `timeoutMs`
+     * elapses — whichever comes first. Used to delay a send/press
+     * recording just long enough for the TTY echo to land on a frame, so
+     * the seek target lines up with the visible state of the screen.
+     */
+    const waitForNextFrame = (timeoutMs) => {
+        return new Promise((resolve) => {
+            let done = false;
+            const finish = () => {
+                if (done)
+                    return;
+                done = true;
+                resolve();
+            };
+            frameWaiters.push(finish);
+            setTimeout(finish, timeoutMs);
+        });
+    };
+    const drainStream = async (stream) => {
+        if (!stream)
+            return;
+        const reader = stream.getReader();
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    return;
+                if (!value || value.byteLength === 0)
+                    continue;
+                const chunk = decoder.decode(value, { stream: true });
+                if (chunk.length === 0)
+                    continue;
+                ingest(chunk);
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    };
+    // Drain stdout + stderr concurrently. `script` writes everything to
+    // stdout under `-t`, but we drain stderr anyway in case script(1)
+    // itself emits diagnostics there.
+    const stdout = proc.stdout;
+    const stderr = proc.stderr;
+    const drained = Promise.all([drainStream(stdout), drainStream(stderr)]);
+    // Race the optional session-level timeout. For interactive terminals
+    // we usually have no timeout; the wrapper for one-shot supplies one.
+    let timer;
+    if (opts?.timeoutMs && opts.timeoutMs > 0) {
+        timer = setTimeout(() => {
+            if (!exited) {
+                try {
+                    proc.kill();
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }, opts.timeoutMs);
+    }
+    // When the process exits, drain whatever's left and resolve `exited`.
+    // We don't await `drained` here — it's already running and will
+    // settle on its own; the explicit `await drained` happens in close().
+    (async () => {
+        const code = await proc.exited;
+        exited = true;
+        exitCode = code;
+        if (timer)
+            clearTimeout(timer);
+        // Let `drained` finish so the final asciicast frames land before we
+        // mark the sink closed. drainStream is bounded by the OS pipe being
+        // closed when proc exits, so this won't hang.
+        try {
+            await drained;
+        }
+        catch {
+            /* ignore */
+        }
+        // Record cast time AFTER drain, so the `exit` step we record below
+        // points the player at the very last frame (the program's final
+        // output before EOF).
+        exitCastTimeSec = (Date.now() - start) / 1000;
+        sink.markClosed();
+        resolveExit(code);
+    })();
+    // Helper to write raw bytes to the PTY. We treat stdin as binary
+    // pipes (Bun's `proc.stdin` is a Web `WritableStream<Uint8Array>` or
+    // a FileSink-like depending on the version — use the FileSink-style
+    // `write(string)` which both shapes accept).
+    const stdinWriter = proc.stdin;
+    const writeStdin = async (data) => {
+        if (exited || closed || !stdinWriter)
+            return;
+        stdinWriter.write(data);
+        try {
+            const r = stdinWriter.flush?.();
+            // FileSink.flush returns void | number; ignore the return.
+            void r;
+        }
+        catch {
+            /* ignore */
+        }
+    };
+    const renderScreen = () => {
+        const buf = emu.buffer.active;
+        const lines = [];
+        // We render only the visible viewport (cursor-position-aware): the
+        // typical mental model of "what does the user see right now".
+        const viewportTop = buf.viewportY;
+        for (let y = 0; y < emu.rows; y++) {
+            const line = buf.getLine(viewportTop + y);
+            lines.push(line ? line.translateToString(true) : "");
+        }
+        // Drop trailing empty lines so multi-line predicates aren't padded.
+        while (lines.length > 1 && lines[lines.length - 1] === "")
+            lines.pop();
+        return lines.join("\n");
+    };
+    const recordOpEvent = (action, fields, startedAt, error, reservation) => {
+        if (!args.recordEvents)
+            return undefined;
+        const preview = truncateUtf8(renderScreen());
+        // Use the SAME clock the asciicast frames use (offset from `start`,
+        // which is captured at Bun.spawn). That way the UI seeks the player
+        // directly to this value with no frame arithmetic.
+        const castTimeSec = (Date.now() - start) / 1000;
+        // Return the event seq so callers can `wrap()` their result value
+        // against it — e.g. `expect(await term.waitFor(...))` then links its
+        // assertion to this step (sourceSeq) and the UI nests it here.
+        return recordTerminalStep({
+            sessionId,
+            service,
+            action,
+            castTimeSec,
+            durationMs: Date.now() - startedAt,
+            screenPreview: preview.value,
+            screenTruncated: preview.truncated,
+            error,
+            ...fields,
+        }, reservation);
+    };
+    // Assemble the public result shape (mirrors the one-shot
+    // `ctx.terminal(...)` TerminalResult) from current capture state.
+    const buildResult = (code) => ({
+        output,
+        exitCode: code,
+        durationMs: Date.now() - start,
+        sessionId,
+    });
+    // Memoised promise behind `term.exited`. Lazily constructed on first
+    // read so the `exit` step is only recorded if the test actually
+    // awaits exit — the one-shot wrapper internally uses `rawExited`
+    // directly and so skips the step (which is what we want; the one-shot
+    // already emits a `terminal` event covering the whole lifecycle).
+    let exitedAccessor;
+    const getExited = () => {
+        if (exitedAccessor)
+            return exitedAccessor;
+        const resv = reserveEvent();
+        exitedAccessor = (async () => {
+            const code = await rawExited;
+            const result = buildResult(code);
+            // No recorder (eval/setup): there's no event to nest under, but we
+            // still wrap (with an undefined seq) so the accessor's wrapped type is
+            // honest at runtime — same as the one-shot `ctx.terminal`/`fetch` paths.
+            if (!args.recordEvents) {
+                return wrap(result, undefined);
+            }
+            const preview = truncateUtf8(renderScreen());
+            const seq = recordTerminalStep({
+                sessionId,
+                service,
+                action: "exit",
+                castTimeSec: exitCastTimeSec ?? (Date.now() - start) / 1000,
+                durationMs: 0,
+                screenPreview: preview.value,
+                screenTruncated: preview.truncated,
+                exitCode: code,
+            }, resv);
+            // Tag the whole result against the exit step so assertions on
+            // `.output` / `.exitCode` nest under the terminal in the timeline.
+            return wrap(result, seq);
+        })();
+        return exitedAccessor;
+    };
+    const handle = {
+        cols,
+        rows,
+        sessionId,
+        get exited() {
+            return getExited();
+        },
+        get exitCode() {
+            return exitCode;
+        },
+        async send(input) {
+            const t = Date.now();
+            const resv = reserveEvent();
+            const trunc = truncateUtf8(input);
+            try {
+                await writeStdin(input);
+                // Block until the echo of what we just wrote lands on a PTY
+                // frame. `writeStdin` returns the instant the bytes are in
+                // the pipe buffer; the kernel TTY echo takes a few ms to
+                // round-trip back through script + docker exec + our stdout
+                // pipe. Recording `castTimeSec` before that frame arrives
+                // would point the step's seek target at a screen state that
+                // doesn't yet show what was typed. The await resolves the
+                // moment that next frame is ingested — it's the mechanism,
+                // not a delay.
+                await waitForNextFrame(ECHO_WAIT_MS);
+                recordOpEvent("send", { text: trunc.value, textTruncated: trunc.truncated }, t, undefined, resv);
+            }
+            catch (err) {
+                const e = err;
+                recordOpEvent("send", { text: trunc.value, textTruncated: trunc.truncated }, t, e?.message ?? String(err), resv);
+                throw err;
+            }
+        },
+        async sendLine(line) {
+            const t = Date.now();
+            const resv = reserveEvent();
+            const trunc = truncateUtf8(line);
+            try {
+                await writeStdin(line + "\n");
+                await waitForNextFrame(ECHO_WAIT_MS);
+                recordOpEvent("sendLine", { text: trunc.value, textTruncated: trunc.truncated }, t, undefined, resv);
+            }
+            catch (err) {
+                const e = err;
+                recordOpEvent("sendLine", { text: trunc.value, textTruncated: trunc.truncated }, t, e?.message ?? String(err), resv);
+                throw err;
+            }
+        },
+        async press(key) {
+            const t = Date.now();
+            const resv = reserveEvent();
+            const bytes = keyToBytes(key);
+            try {
+                await writeStdin(bytes);
+                await waitForNextFrame(ECHO_WAIT_MS);
+                recordOpEvent("press", { key }, t, undefined, resv);
+            }
+            catch (err) {
+                const e = err;
+                recordOpEvent("press", { key }, t, e?.message ?? String(err), resv);
+                throw err;
+            }
+        },
+        rawOutput() {
+            return output;
+        },
+        rawScreen() {
+            return renderScreen();
+        },
+        async waitFor(description, matcher, waitOpts) {
+            const timeoutMs = waitOpts?.timeoutMs ?? 5_000;
+            const intervalMs = waitOpts?.intervalMs ?? 100;
+            const t = Date.now();
+            const resv = reserveEvent();
+            const deadline = t + timeoutMs;
+            let attempts = 0;
+            const check = () => {
+                attempts++;
+                const scr = renderScreen();
+                if (typeof matcher === "string") {
+                    return scr.includes(matcher) ? matcher : null;
+                }
+                if (matcher instanceof RegExp) {
+                    const m = scr.match(matcher);
+                    return m ?? null;
+                }
+                return matcher(scr, output);
+            };
+            while (true) {
+                const v = check();
+                if (v) {
+                    const seq = recordOpEvent("waitFor", { description, attempts, matched: true }, t, undefined, resv);
+                    // Tag the matched value so an `expect(...)` on it links its
+                    // assertion back to this waitFor step (sourceSeq) instead of
+                    // rendering as an orphan sidebar row. Mirrors how http/db/exec
+                    // results carry their op's seq. `as never` lets this single
+                    // body satisfy the three overload return types.
+                    return wrap(v, seq);
+                }
+                if (Date.now() >= deadline) {
+                    const err = `waitFor ${JSON.stringify(description)} timed out after ${timeoutMs}ms (${attempts} attempts)`;
+                    recordOpEvent("waitFor", { description, attempts, matched: false }, t, err, resv);
+                    throw new Error(err);
+                }
+                await new Promise((r) => setTimeout(r, intervalMs));
+            }
+        },
+        async close() {
+            // Use `rawExited` rather than `term.exited` everywhere we need a
+            // raw number internally — the public getter resolves to a wrapped
+            // result (and records an `exit` step on first read) which we don't
+            // want as a side-effect of internal teardown logic.
+            if (closed)
+                return buildResult(exitCode ?? (await rawExited));
+            closed = true;
+            const t = Date.now();
+            const resv = reserveEvent();
+            // Polite first: send EOF (Ctrl-D). For a login shell this exits
+            // cleanly. For a long-running command it's a no-op and we fall
+            // through to SIGKILL.
+            try {
+                await writeStdin("\x04");
+            }
+            catch {
+                /* ignore */
+            }
+            // Closing stdin signals EOF to the script wrapper too.
+            try {
+                proc.stdin?.end?.();
+            }
+            catch {
+                /* ignore */
+            }
+            // Grace period before forcibly killing.
+            const grace = 1_500;
+            const raced = await Promise.race([
+                rawExited,
+                new Promise((r) => setTimeout(() => r("timeout"), grace)),
+            ]);
+            if (raced === "timeout") {
+                try {
+                    proc.kill();
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            const code = await rawExited;
+            const result = buildResult(code);
+            const seq = recordOpEvent("close", { exitCode: code }, t, undefined, resv);
+            // Tag the result against the close step so assertions on the
+            // transcript of a non-self-terminating session nest under it.
+            return wrap(result, seq);
+        },
+    };
+    return handle;
+}
+// ────────────────────────────────────────────────────────────────────────
+// Key name → byte sequence
+// ────────────────────────────────────────────────────────────────────────
+const KEY_MAP = {
+    enter: "\r",
+    return: "\r",
+    tab: "\t",
+    backspace: "\x7f",
+    delete: "\x1b[3~",
+    escape: "\x1b",
+    esc: "\x1b",
+    up: "\x1b[A",
+    down: "\x1b[B",
+    right: "\x1b[C",
+    left: "\x1b[D",
+    home: "\x1b[H",
+    end: "\x1b[F",
+    pageup: "\x1b[5~",
+    pagedown: "\x1b[6~",
+    space: " ",
+};
+function keyToBytes(key) {
+    const norm = key.replace(/[\s_-]/g, "").toLowerCase();
+    if (KEY_MAP[norm] !== undefined)
+        return KEY_MAP[norm];
+    // Ctrl+<letter>: ASCII control char 1-26.
+    const ctrl = key.match(/^ctrl[\s_+-]+([a-z])$/i);
+    if (ctrl) {
+        const letter = ctrl[1].toLowerCase();
+        const code = letter.charCodeAt(0) - "a".charCodeAt(0) + 1;
+        return String.fromCharCode(code);
+    }
+    // Fall back to the literal string — lets callers type a single
+    // character via `press("X")` even if it's not in the table.
+    return key;
+}
+// ────────────────────────────────────────────────────────────────────────
+// Shell quoting for `script -c CMD`
+// ────────────────────────────────────────────────────────────────────────
+function shellQuote(argv) {
+    return argv
+        .map((a) => {
+        if (a.length === 0)
+            return "''";
+        if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(a))
+            return a;
+        return `'${a.replace(/'/g, `'\\''`)}'`;
+    })
+        .join(" ");
+}

package/package.json

@@ -1,19 +1,34 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./components": "./src/components/index.ts",
-    "./browser": "./src/browser.ts",
-    "./daemon": "./src/daemon.ts",
-    "./resolver": "./src/resolver.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "default": "./dist/components/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    },
+    "./daemon": {
+      "types": "./dist/daemon.d.ts",
+      "default": "./dist/daemon.js"
+    },
+    "./resolver": {
+      "types": "./dist/resolver.d.ts",
+      "default": "./dist/resolver.js"
+    }
   },
   "files": [
-    "src",
+    "dist",
     "README.md"
   ],
   "repository": {