@specific.dev/spectest 0.26.0 → 0.27.0

package/dist/sql.js

@@ -0,0 +1,151 @@
+// `SQL` — a drop-in for `Bun.SQL` that records every query on the test event
+// log and returns its rows inspect-wrapped, so `expect(rows[0]!.id)` links the
+// assertion back to the query in the timeline (same provenance mechanism as
+// `fetch`). Swap `new Bun.SQL(url)` → `new SQL(url)` and nothing else changes
+// at the call site; query *results* come back `Wrapped<T[]>` instead of raw
+// `T[]` (that wrapper is what carries provenance), so `.unwrap()` before feeding
+// a row value to another real client or a `===` — exactly the rule that already
+// holds for `ctx.svc.<postgres>.client`.
+//
+// This is the core primitive; the `postgres(...)` component is a thin user of
+// it (its `helpers.client` is `new SQL(url, { label })`). Open one yourself
+// whenever you stand up a database without the component — a Bun-native image
+// like timescaledb/postgis, or a connection string a fake handed back after
+// provisioning a DB at runtime.
+import { recordDb, reserveEvent, safeSerialize } from "./recorder.js";
+import { wrap } from "./inspect.js";
+/**
+ * Open an instrumented SQL client against `url`. Usable with or without `new`
+ * (`new SQL(url)` mirrors `new Bun.SQL(url)`; a constructor that returns an
+ * object yields that object). Requires the Bun runtime — it runs inside the
+ * spectest daemon.
+ */
+export const SQL = function SQL(url, opts) {
+    const bun = globalThis.Bun;
+    if (!bun?.SQL) {
+        throw new Error("SQL(url) requires the Bun runtime (Bun >= 1.2) — it runs inside the spectest daemon.");
+    }
+    return instrumentSql(new bun.SQL(url), opts?.label ?? hostLabel(url));
+};
+/** Derive a default event label from a connection URL's host. */
+function hostLabel(url) {
+    try {
+        return new URL(url).hostname || "db";
+    }
+    catch {
+        return "db";
+    }
+}
+/**
+ * Proxy a `Bun.SQL` instance so each tagged-template call and each
+ * `unsafe(...)` call emits a `db` event into the active recorder when its
+ * promise settles, and resolves to a {@link Wrapped} result. Other `Bun.SQL`
+ * methods (`.transaction`, `.array`, `.file`, …) pass through unwrapped.
+ *
+ * Exported so a client built some other way (e.g. a pool you already hold) can
+ * opt into the same instrumentation without going through {@link SQL}.
+ */
+export function instrumentSql(raw, label) {
+    const wrapResult = (result, query, params) => {
+        const started = Date.now();
+        const resv = reserveEvent();
+        return Promise.resolve(result).then((value) => {
+            const { rows, rowsTruncated, columns } = captureRows(value);
+            const seq = recordDb({
+                service: label,
+                query,
+                params: params.length > 0 ? params.map(safeSerialize) : undefined,
+                rowCount: rowCountOf(value),
+                rowsAffected: isAffectedCount(query, value) || undefined,
+                rows,
+                rowsTruncated,
+                columns,
+                durationMs: Date.now() - started,
+            }, resv);
+            return wrap(value, seq);
+        }, (err) => {
+            const e = err;
+            recordDb({
+                service: label,
+                query,
+                params: params.length > 0 ? params.map(safeSerialize) : undefined,
+                durationMs: Date.now() - started,
+                error: e?.message ?? String(err),
+            }, resv);
+            throw err;
+        });
+    };
+    const handler = {
+        apply(target, thisArg, args) {
+            const [strings, ...values] = args;
+            const query = reconstructSqlTemplate(strings, values.length);
+            const result = Reflect.apply(target, thisArg, args);
+            return wrapResult(result, query, values);
+        },
+        get(target, prop, receiver) {
+            if (prop === "unsafe") {
+                return (text, params) => {
+                    const result = target.unsafe.call(target, text, params);
+                    return wrapResult(result, text, params ?? []);
+                };
+            }
+            const v = Reflect.get(target, prop, receiver);
+            return typeof v === "function" ? v.bind(target) : v;
+        },
+    };
+    return new Proxy(raw, handler);
+}
+/** Rebuild a parameterized SQL string from a tagged-template's pieces.
+ * Bun.SQL substitutes `${value}` for `$1`, `$2`, …; we do the same so
+ * the recorded query matches what the server sees. */
+function reconstructSqlTemplate(strings, valueCount) {
+    let out = strings[0] ?? "";
+    for (let i = 0; i < valueCount; i++) {
+        out += `$${i + 1}` + (strings[i + 1] ?? "");
+    }
+    return out.trim();
+}
+function rowCountOf(value) {
+    if (value && typeof value === "object") {
+        const obj = value;
+        // Bun.SQL (postgres.js semantics): `.count` is rows RETURNED for
+        // SELECT/RETURNING queries and rows AFFECTED for other writes — where
+        // the result array itself is empty. Check it before `.length`, or a
+        // non-RETURNING `UPDATE` that touched 3 rows records a misleading 0.
+        if (typeof obj.count === "number")
+            return obj.count;
+        if (typeof obj.rowCount === "number")
+            return obj.rowCount;
+    }
+    if (Array.isArray(value))
+        return value.length;
+    return undefined;
+}
+/** True when the recorded count means "rows affected" rather than "rows
+ *  returned" — a write with no result set. Lets the dashboard render
+ *  `3 affected` instead of `3 rows` (and keeps `UPDATE … (0 rows)` from
+ *  reading as "nothing updated"). */
+function isAffectedCount(query, value) {
+    if (Array.isArray(value) && value.length > 0)
+        return false; // rows came back
+    const q = query.trimStart().slice(0, 8).toUpperCase();
+    return (q.startsWith("INSERT") ||
+        q.startsWith("UPDATE") ||
+        q.startsWith("DELETE") ||
+        q.startsWith("MERGE"));
+}
+const MAX_DB_ROWS = 50;
+function captureRows(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return {};
+    const slice = value.slice(0, MAX_DB_ROWS).map(safeSerialize);
+    const first = slice[0];
+    const columns = first && typeof first === "object" && !Array.isArray(first)
+        ? Object.keys(first)
+        : undefined;
+    return {
+        rows: slice,
+        rowsTruncated: value.length > MAX_DB_ROWS ? true : undefined,
+        columns,
+    };
+}

package/dist/terminal.d.ts

@@ -0,0 +1,161 @@
+import type { Wrapped } from "./inspect.js";
+export interface TerminalOpts {
+    /** PTY column count. Defaults to 80. */
+    cols?: number;
+    /** PTY row count. Defaults to 24. */
+    rows?: number;
+    /** Extra env vars; merged onto the container's. `TERM` defaults to
+     * `xterm-256color`. */
+    env?: Record<string, string>;
+    /**
+     * Command to run inside the container. When omitted, opens an
+     * interactive login shell (`sh -l`) — what you want for the typical
+     * "send commands, inspect output" interactive flow.
+     *
+     * When set, the command is the entrypoint and the session ends when
+     * it exits. This is what the one-shot `ctx.terminal(...)` wrapper
+     * passes through.
+     */
+    command?: string;
+    /**
+     * Hard timeout for the whole session in ms. When the session is
+     * interactive (no `command`), this defaults to undefined (no timeout)
+     * and the daemon's test-level timeout is what trips. For one-shot
+     * runs, the wrapper supplies the test's default timeout.
+     */
+    timeoutMs?: number;
+}
+/** Result of the one-shot `ctx.terminal(...)` convenience. */
+export interface TerminalResult {
+    /** Full decoded PTY output (raw bytes, ANSI escapes included). Capped. */
+    output: string;
+    exitCode: number;
+    durationMs: number;
+    /** Opaque id linking to the persisted asciicast session. */
+    sessionId: string;
+}
+/**
+ * Interactive terminal handle. Operations are sequential per terminal —
+ * concurrent `send`/`waitFor` against the same handle has no well-defined
+ * meaning since both touch the same PTY/screen buffer. Open multiple
+ * terminals for parallel sessions.
+ */
+export interface Terminal {
+    /** PTY column count this terminal was opened with. */
+    readonly cols: number;
+    /** PTY row count this terminal was opened with. */
+    readonly rows: number;
+    /** Session id linking to the asciicast record. */
+    readonly sessionId: string;
+    /**
+     * Resolves when the underlying process ends — by `close()`, by the
+     * inner command exiting, or by timeout — to a `TerminalResult` with
+     * the full captured `output` and `exitCode`. Never rejects.
+     *
+     * The result is provenance-tagged against the `exit` step, so an
+     * `expect((await term.exited).output).toContain(...)` /
+     * `expect((await term.exited).exitCode).toBe(0)` nests under the
+     * terminal in the timeline. This is how you assert on a long-lived
+     * terminal's transcript — there is no separate `output()`/`screen()`
+     * getter (use `waitFor` to observe mid-session).
+     */
+    readonly exited: Promise<Wrapped<TerminalResult>>;
+    /** Exit code if the process has exited, else `undefined`. Non-blocking
+     *  peek; unlike `exited` it records no step and isn't tagged. */
+    readonly exitCode: number | undefined;
+    /** Write raw bytes to the PTY. No newline added. */
+    send(input: string): Promise<void>;
+    /** Convenience: `send(line + "\n")`. */
+    sendLine(line: string): Promise<void>;
+    /**
+     * Press a named key. Supported names: `Enter`, `Tab`, `Backspace`,
+     * `Escape`, `Up`/`Down`/`Left`/`Right`, `Home`, `End`, `PageUp`,
+     * `PageDown`, `Delete`, and `Ctrl+<letter>` (case-insensitive).
+     * Anything else is sent as the literal string.
+     */
+    press(key: string): Promise<void>;
+    /**
+     * Poll until `matcher` resolves truthy against the rendered screen.
+     * This is the primitive for observing terminal state — race-free
+     * (it polls until the condition holds rather than reading a snapshot
+     * that may not have rendered yet) and recorded as a tied step.
+     * `matcher` can be:
+     *   - a string  → matches when the screen contains it; resolves to
+     *     the string. The wait itself is the assertion (it throws on
+     *     timeout), so no extra `expect` is needed for "contains X".
+     *   - a regex   → matches on `.test`; resolves to the match array.
+     *   - a function → `fn(screen, output)` — any truthy return resolves
+     *     and becomes the (provenance-tagged) result, so you can extract
+     *     a value and `expect(...)` on it.
+     *
+     * `description` is a short human label that shows up in the event
+     * log so timelines don't fill with anonymous waits.
+     *
+     * Defaults: 5 s total timeout, 100 ms between polls. Throws on
+     * timeout.
+     */
+    waitFor(description: string, matcher: string, opts?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<Wrapped<string>>;
+    waitFor(description: string, matcher: RegExp, opts?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<Wrapped<RegExpMatchArray>>;
+    waitFor<T = unknown>(description: string, matcher: (screen: string, output: string) => T, opts?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<Wrapped<NonNullable<Awaited<T>>>>;
+    /**
+     * Tear down. Writes Ctrl-D to stdin to nudge the shell out, then
+     * SIGKILLs after a grace period. Idempotent. Resolves to a
+     * `TerminalResult` (tagged against the `close` step) so you can assert
+     * on the transcript of a session that doesn't self-terminate. Optional
+     * — terminals are not auto-closed when a test ends.
+     */
+    close(): Promise<Wrapped<TerminalResult>>;
+}
+/**
+ * The concrete handle `openTerminal` returns. Extends the public
+ * `Terminal` with raw accessors the daemon uses internally to build
+ * `TerminalResult`s and event previews. Deliberately NOT on the public
+ * `Terminal` surface: test code observes via `waitFor` (race-free, tied)
+ * and reads the transcript from `exited`/`close`, never from an
+ * out-of-band, untracked getter.
+ */
+export interface InternalTerminal extends Terminal {
+    /** Cumulative raw PTY bytes since the session opened, capped. ANSI included. */
+    rawOutput(): string;
+    /** Rendered screen — visible rows joined by newlines, trailing
+     *  whitespace trimmed, cursor-position-aware (ANSI already applied). */
+    rawScreen(): string;
+}
+/** Sink for asciicast frames produced by this terminal. */
+export interface TerminalFrameSink {
+    pushFrame(tSec: number, data: string): void;
+    markClosed(): void;
+}
+export interface OpenTerminalArgs {
+    service: string;
+    opts?: TerminalOpts;
+    /** Asciicast frames go here; the daemon owns the session record. */
+    sink: TerminalFrameSink;
+    /** Session id (precomputed so the inline TerminalEvent can reference
+     * it before the session record is finished). */
+    sessionId: string;
+    /**
+     * When set, the daemon emits per-op events into the recorder under
+     * this session id. Mirrors `BrowserSessionRecorder.sessionId`.
+     * `null` disables per-op event recording (e.g. eval, where there's
+     * no active recorder).
+     */
+    recordEvents?: boolean;
+}
+/**
+ * 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 declare function openTerminal(args: OpenTerminalArgs): Promise<InternalTerminal>;