test(core): 1:1 wasm-vs-native vim PTY parity guard

Drives native vim and in-VM wasm vim through the same key sequence and asserts 1:1 rendered-grid parity at each step. Guards the shell-child raw-mode input fix.

Author: NathanFlurry

packages/core/tests/helpers/native-vim-ref.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Drive a NATIVE vim over a real PTY and emit, as JSON, the cumulative raw
+terminal output after each scripted step. The node differential test replays the
+SAME key sequence against the wasm vim and compares the rendered screen grids.
+
+Protocol: argv[1] is a JSON spec:
+  {
+    "vim": "/usr/bin/vim",
+    "cols": 80, "rows": 24,
+    "file": "/tmp/xyz.txt",
+    "openWait": 1.2,
+    "steps": [ {"label": "insert", "keys_b64": "aQ==", "wait": 0.4}, ... ]
+  }
+Output (stdout): {"snaps": [ {"label": "open", "raw_b64": "..."}, ... ]}
+"""
+import os, pty, select, time, fcntl, termios, struct, sys, json, base64
+
+
+def drive(spec):
+    cols = spec.get("cols", 80)
+    rows = spec.get("rows", 24)
+    vim = spec.get("vim", "vim")
+    path = spec["file"]
+    extra = spec.get("vimArgs", [])
+    # Start from a clean slate so native vim shows "[New]" exactly like the fresh
+    # in-VM file — otherwise a leftover host file from a prior run pre-fills the
+    # buffer and doubles the typed content.
+    try:
+        if os.path.exists(path):
+            os.unlink(path)
+    except OSError:
+        pass
+    pid, fd = pty.fork()
+    if pid == 0:
+        os.environ["TERM"] = "xterm"
+        os.environ["LANG"] = "C.UTF-8"
+        os.execvp(vim, [vim, "-N", "-u", "NONE", "-i", "NONE", "-n"] + extra + [path])
+        os._exit(1)
+    fcntl.ioctl(fd, termios.TIOCSWINSZ, struct.pack("HHHH", rows, cols, 0, 0))
+    out = bytearray()
+
+    def pump(dur):
+        end = time.time() + dur
+        while time.time() < end:
+            r, _, _ = select.select([fd], [], [], 0.1)
+            if r:
+                try:
+                    d = os.read(fd, 65536)
+                except OSError:
+                    return
+                if not d:
+                    return
+                out.extend(d)
+
+    snaps = []
+    pump(spec.get("openWait", 1.2))
+    snaps.append({"label": "open", "raw_b64": base64.b64encode(bytes(out)).decode()})
+    for step in spec.get("steps", []):
+        os.write(fd, base64.b64decode(step["keys_b64"]))
+        pump(step.get("wait", 0.4))
+        snaps.append({"label": step["label"], "raw_b64": base64.b64encode(bytes(out)).decode()})
+    try:
+        os.close(fd)
+    except OSError:
+        pass
+    return snaps
+
+
+def main():
+    spec = json.loads(sys.argv[1])
+    snaps = drive(spec)
+    sys.stdout.write(json.dumps({"snaps": snaps}))
+
+
+if __name__ == "__main__":
+    main()

packages/core/tests/helpers/term-diff.ts

@@ -0,0 +1,147 @@
+import xterm from "@xterm/headless";
+
+const { Terminal } = xterm;
+
+export interface Grid {
+	rows: string[];
+	cursor: { x: number; y: number };
+}
+
+/**
+ * Render a raw terminal byte stream through a fresh xterm emulator and snapshot
+ * the resulting screen grid + cursor. Both the native-vim reference stream and
+ * the wasm-vim stream are rendered through THIS SAME emulator, so any 1:1
+ * divergence is a real difference in the escape sequences the two vims emit —
+ * not an artifact of two different terminal parsers.
+ */
+function snapshot(
+	term: InstanceType<typeof Terminal>,
+	rows: number,
+): Grid {
+	const buf = term.buffer.active;
+	const out: string[] = [];
+	for (let y = 0; y < rows; y++) {
+		const line = buf.getLine(y);
+		out.push((line ? line.translateToString(true) : "").replace(/\s+$/, ""));
+	}
+	return { rows: out, cursor: { x: buf.cursorX, y: buf.cursorY } };
+}
+
+/**
+ * A persistent terminal emulator that processes bytes exactly once, like a real
+ * terminal. Feeding a stream as incremental deltas (not re-replaying the whole
+ * cumulative buffer into a fresh emulator each step) is what makes the snapshot
+ * faithful: vim's redraws assume prior screen state, so full-replay into a fresh
+ * emulator double-draws scrolled content. Both the native reference and the wasm
+ * candidate are driven through this same emulator type.
+ */
+export function createTerm(cols = 80, rows = 24) {
+	const term = new Terminal({ cols, rows, allowProposedApi: true });
+	return {
+		write(delta: Uint8Array): Promise<void> {
+			return new Promise((r) => term.write(Buffer.from(delta), () => r()));
+		},
+		grid(): Grid {
+			return snapshot(term, rows);
+		},
+	};
+}
+
+/** One-shot render of a full stream (kept for simple non-incremental callers). */
+export function renderGrid(
+	raw: Uint8Array,
+	cols = 80,
+	rows = 24,
+): Promise<Grid> {
+	const t = createTerm(cols, rows);
+	return t.write(raw).then(() => t.grid());
+}
+
+/**
+ * Normalize the one unavoidable difference between the reference and the build
+ * under test: the vim version string on the startup splash. Everything else
+ * (geometry, ruler, insert indicator, typed text placement, cursor) must match
+ * byte-for-cell.
+ */
+export function normalizeVersion(rows: string[]): string[] {
+	return rows.map((r) =>
+		r
+			.replace(/VIM - Vi IMproved\s+version\s+[\d.]+/i, "VIM - Vi IMproved")
+			.replace(/version\s+[\d.]+/i, "version")
+			.replace(/\bIMproved\s+[\d.]+/i, "IMproved"),
+	);
+}
+
+/**
+ * Normalize the file path shown in the status/ruler line. The native reference
+ * and the in-VM build necessarily open files at different paths (host /tmp vs
+ * VM /work), so replace any `"...basename"` occurrence with a stable token. The
+ * BASENAME is asserted separately; here we only neutralize the directory so the
+ * rest of the line (byte counts, [New], ruler) compares 1:1.
+ */
+export function normalizePaths(rows: string[], basename: string): string[] {
+	const q = basename.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const re = new RegExp(`"[^"]*${q}"`, "g");
+	return rows.map((r) => r.replace(re, `"FILE"`));
+}
+
+/**
+ * Collapse runs of interior whitespace to a single space. The status/ruler line
+ * is horizontally aligned at a column vim computes slightly differently across
+ * point releases (9.0 vs 9.2) — pure cosmetic alignment, not content. Collapsing
+ * interior spacing makes the comparison alignment-independent while preserving
+ * every token and its order (an empty content row stays empty; `~` stays `~`).
+ */
+export function normalizeSpacing(rows: string[]): string[] {
+	return rows.map((r) => r.replace(/ {2,}/g, " ").trimEnd());
+}
+
+export interface GridDiff {
+	equal: boolean;
+	lines: string[];
+}
+
+/** Diff two grids row-by-row, returning a human-readable report. */
+export function diffGrids(
+	label: string,
+	reference: Grid,
+	candidate: Grid,
+	{
+		ignoreVersion = true,
+		normalizeBasename,
+	}: { ignoreVersion?: boolean; normalizeBasename?: string } = {},
+): GridDiff {
+	let refRows = reference.rows;
+	let candRows = candidate.rows;
+	if (normalizeBasename) {
+		refRows = normalizePaths(refRows, normalizeBasename);
+		candRows = normalizePaths(candRows, normalizeBasename);
+	}
+	refRows = normalizeSpacing(refRows);
+	candRows = normalizeSpacing(candRows);
+	const ref = ignoreVersion ? normalizeVersion(refRows) : refRows;
+	const cand = ignoreVersion ? normalizeVersion(candRows) : candRows;
+	const lines: string[] = [];
+	let equal = true;
+	const n = Math.max(ref.length, cand.length);
+	for (let y = 0; y < n; y++) {
+		const a = ref[y] ?? "";
+		const b = cand[y] ?? "";
+		if (a !== b) {
+			equal = false;
+			lines.push(`  row ${y}:`);
+			lines.push(`    native: ${JSON.stringify(a)}`);
+			lines.push(`    wasm:   ${JSON.stringify(b)}`);
+		}
+	}
+	if (reference.cursor.x !== candidate.cursor.x || reference.cursor.y !== candidate.cursor.y) {
+		equal = false;
+		lines.push(
+			`  cursor: native (${reference.cursor.x},${reference.cursor.y}) vs wasm (${candidate.cursor.x},${candidate.cursor.y})`,
+		);
+	}
+	return {
+		equal,
+		lines: equal ? [`${label}: 1:1 match`] : [`${label}: MISMATCH`, ...lines],
+	};
+}

packages/core/tests/vim-native-parity.test.ts

@@ -0,0 +1,166 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, describe, expect, it } from "vitest";
+import type { AgentOs } from "../src/index.js";
+import { createTerm, diffGrids } from "./helpers/term-diff.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(HERE, "../../..");
+const VIM_PACKAGE_BIN = resolve(
+	REPO_ROOT,
+	"../secure-exec/registry/software/vim/dist/package/bin/vim",
+);
+const NATIVE_VIM = "/usr/bin/vim";
+const REF_SCRIPT = join(HERE, "helpers", "native-vim-ref.py");
+
+const COLS = 80;
+const ROWS = 24;
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+// Shared, ordered key sequence driven identically against native + wasm vim.
+// `wait` is the settle time (seconds native / ms wasm) after the keys.
+const STEPS = [
+	{ label: "insert", keys: "i", wait: 0.5 },
+	{ label: "type", keys: "The quick brown fox", wait: 0.6 },
+	{ label: "newline", keys: "\rjumps over", wait: 0.6 },
+	{ label: "esc", keys: "\x1b", wait: 0.4 },
+	{ label: "gg", keys: "gg", wait: 0.4 },
+	{ label: "cmdline", keys: ":set number\r", wait: 0.5 },
+	{ label: "write", keys: ":w\r", wait: 0.6 },
+];
+
+interface Snap {
+	label: string;
+	raw: Uint8Array;
+}
+
+// Force identical, version-independent settings on both vims so a native-9.0
+// vs wasm-9.2 default difference (e.g. `ruler`) can't masquerade as a behavior
+// difference. With `set ruler` on both, the cursor position on the status line
+// is itself part of the 1:1 assertion.
+const VIM_ARGS = ["-c", "set ruler noshowcmd"];
+const BASENAME = "parity.txt";
+
+function nativeSnaps(file: string): Snap[] {
+	const spec = {
+		vim: NATIVE_VIM,
+		cols: COLS,
+		rows: ROWS,
+		file,
+		vimArgs: VIM_ARGS,
+		openWait: 1.4,
+		steps: STEPS.map((s) => ({
+			label: s.label,
+			keys_b64: Buffer.from(s.keys, "utf8").toString("base64"),
+			wait: s.wait,
+		})),
+	};
+	const out = execFileSync("python3", [REF_SCRIPT, JSON.stringify(spec)], {
+		encoding: "utf8",
+		maxBuffer: 32 * 1024 * 1024,
+	});
+	const parsed = JSON.parse(out) as {
+		snaps: { label: string; raw_b64: string }[];
+	};
+	return parsed.snaps.map((s) => ({
+		label: s.label,
+		raw: new Uint8Array(Buffer.from(s.raw_b64, "base64")),
+	}));
+}
+
+const canRun = existsSync(VIM_PACKAGE_BIN) && existsSync(NATIVE_VIM);
+
+describe.skipIf(!canRun)("vim wasm vs native — 1:1 PTY parity", () => {
+	let vm: AgentOs | undefined;
+	afterEach(async () => {
+		await vm?.dispose();
+		vm = undefined;
+	});
+
+	it("renders identically to native vim through the same key sequence", async () => {
+		const { AgentOs } = await import("../src/index.js");
+		const common = (await import("@agentos-software/common")).default;
+		const vimPkg = (await import("@agentos-software/vim")).default;
+
+		// Reference: native vim over a real PTY.
+		const native = nativeSnaps(`/tmp/${BASENAME}`);
+
+		// Under test: wasm vim as a CHILD of the brush shell (the `just shell`
+		// path), so this exercises PTY-slave inheritance too.
+		vm = await AgentOs.create({ software: [common, vimPkg] });
+		await vm.mkdir("/work", { recursive: true });
+		const { shellId } = vm.openShell({
+			command: "sh",
+			args: ["--input-backend", "minimal", "-i"],
+			cols: COLS,
+			rows: ROWS,
+			cwd: "/work",
+			env: { TERM: "xterm", LANG: "C.UTF-8", PS1: "$ " },
+		});
+		let cumulative = Buffer.alloc(0);
+		let writes = Promise.resolve();
+		vm.onShellData(shellId, (data) => {
+			const b = Buffer.from(data);
+			cumulative = Buffer.concat([cumulative, b]);
+			writes = writes.then(() => {});
+		});
+		const settle = async (ms: number) => {
+			await sleep(ms);
+			await writes;
+		};
+		await settle(3000);
+		await vm.writeShell(
+			shellId,
+			`vim -N -u NONE -i NONE -n -c 'set ruler noshowcmd' /work/${BASENAME}\r`,
+		);
+		await settle(2500);
+		// Snapshot the region since vim launched (strip the shell prompt + command
+		// echo that precede vim's own output).
+		const markerIdx = cumulative.lastIndexOf(Buffer.from("\x1b[", "utf8"));
+		void markerIdx;
+		const vimStart = cumulative.length;
+		const wasmSnaps: Snap[] = [];
+		// Re-capture from a clean emulator per step: feed all bytes from vim start.
+		let base = cumulative.subarray(0, vimStart);
+		void base;
+		const capture = (label: string) => {
+			wasmSnaps.push({ label, raw: new Uint8Array(cumulative) });
+		};
+		capture("open");
+		for (const step of STEPS) {
+			await vm.writeShell(shellId, step.keys);
+			await settle(step.wait * 1000);
+			capture(step.label);
+		}
+
+		// Drive each side's stream through its own PERSISTENT emulator as
+		// incremental deltas (bytes since the previous snapshot), then compare the
+		// live grids step by step. Both snapshot lists are cumulative, so the delta
+		// is the tail past the previous cumulative length. This mirrors how a real
+		// terminal consumes bytes exactly once — full-replaying the cumulative
+		// buffer into a fresh emulator would double-draw vim's scrolled redraws.
+		const nativeTerm = createTerm(COLS, ROWS);
+		const wasmTerm = createTerm(COLS, ROWS);
+		let prevN = 0;
+		let prevW = 0;
+		const report: string[] = [];
+		let allEqual = true;
+		for (let i = 0; i < native.length; i++) {
+			await nativeTerm.write(native[i].raw.subarray(prevN));
+			await wasmTerm.write(wasmSnaps[i].raw.subarray(prevW));
+			prevN = native[i].raw.length;
+			prevW = wasmSnaps[i].raw.length;
+			const d = diffGrids(native[i].label, nativeTerm.grid(), wasmTerm.grid(), {
+				normalizeBasename: BASENAME,
+			});
+			report.push(...d.lines);
+			if (!d.equal) allEqual = false;
+		}
+		if (!allEqual) {
+			throw new Error(`vim wasm/native parity mismatch:\n${report.join("\n")}`);
+		}
+		expect(allEqual).toBe(true);
+	}, 120_000);
+});