@wringer/terminal 0.0.0-stage → 0.0.0

package/src/build-text-keys.ts

@@ -0,0 +1,66 @@
+import { keyNames } from './key-names.ts';
+import type { KeyInput } from './screen-engine.ts';
+
+// Turns text into the key events that type it on a US keyboard. A character that no key types,
+// such as an accented letter, is one event with no key and that text.
+export function buildTextKeys(text: string): KeyInput[] {
+  return Array.from(text, (character) => buildCharacterKey(character));
+}
+
+const shiftedSymbols: Readonly<Record<string, string>> = {
+  '!': '1',
+  '@': '2',
+  '#': '3',
+  $: '4',
+  '%': '5',
+  '^': '6',
+  '&': '7',
+  '*': '8',
+  '(': '9',
+  ')': '0',
+  _: '-',
+  '+': '=',
+  '{': '[',
+  '}': ']',
+  '|': '\\',
+  ':': ';',
+  '"': "'",
+  '<': ',',
+  '>': '.',
+  '?': '/',
+  '~': '`',
+};
+
+const noMods = { shift: false, ctrl: false, alt: false, super: false };
+
+function buildCharacterKey(character: string): KeyInput {
+  if (character === '\n' || character === '\r') {
+    return { key: 'enter', mods: noMods };
+  }
+
+  if (character === '\t') {
+    return { key: 'tab', mods: noMods };
+  }
+
+  if (character === ' ') {
+    return { key: 'space', mods: noMods, text: ' ' };
+  }
+
+  const lowered = character.toLowerCase();
+
+  if (lowered !== character && Object.hasOwn(keyNames, lowered)) {
+    return { key: lowered, mods: { ...noMods, shift: true }, text: character };
+  }
+
+  const base = shiftedSymbols[character];
+
+  if (base !== undefined) {
+    return { key: base, mods: { ...noMods, shift: true }, text: character };
+  }
+
+  if (Object.hasOwn(keyNames, character)) {
+    return { key: character, mods: noMods, text: character };
+  }
+
+  return { key: 'unidentified', mods: noMods, text: character };
+}

package/src/call-sessions.ts

@@ -0,0 +1,22 @@
+import type { ServiceCaller } from '@wringer/core';
+import type { z } from 'zod';
+import { sessionServiceContract } from './session-service-contract.ts';
+import type { SessionArgs, SessionMethod, SessionResult } from './session-service-contract.ts';
+
+// Indexing this mapped type by a method keeps that method's result type, which indexing the
+// contract's own type loses to a union of every result.
+type SessionResultSchemas = {
+  readonly [Method in SessionMethod]: { readonly result: z.ZodType<SessionResult<Method>> };
+};
+
+const resultSchemas: SessionResultSchemas = sessionServiceContract;
+
+export async function callSessions<Method extends SessionMethod>(
+  sessions: ServiceCaller,
+  method: Method,
+  args: SessionArgs<Method>,
+): Promise<SessionResult<Method>> {
+  const answer = await sessions.call(method, args);
+
+  return resultSchemas[method].result.parse(answer);
+}

package/src/create-ghostty-engine.ts

@@ -0,0 +1,104 @@
+import { createWasmBridge } from './create-wasm-bridge.ts';
+import type { WasmBridge } from './create-wasm-bridge.ts';
+import { encodeGhosttyKey } from './encode-ghostty-key.ts';
+import { pickUnwrappedText } from './pick-unwrapped-text.ts';
+import { pickVisibleText } from './pick-visible-text.ts';
+import { readGhosttyText } from './read-ghostty-text.ts';
+import type { CursorState, ScreenEngine } from './screen-engine.ts';
+
+export interface GhosttyEngineOptions {
+  readonly module: WebAssembly.Module;
+  readonly cols: number;
+  readonly rows: number;
+}
+
+const cellWidthPx = 8;
+const cellHeightPx = 16;
+
+// Runs libghostty-vt as WASM with no imports. Each engine owns one instance, so its memory and its
+// terminal die with it. The key encoder reads the terminal's live modes, so a key follows what the
+// program asked for, such as the kitty keyboard protocol.
+export function createGhosttyEngine(options: GhosttyEngineOptions): ScreenEngine {
+  const bridge = createWasmBridge(options.module);
+
+  const terminal = bridge.createHandle(
+    (slot) => bridge.call('ghostty_terminal_new', 0, slot, options.cols, options.rows),
+    'create the terminal',
+  );
+
+  const encoder = bridge.createHandle(
+    (slot) => bridge.call('ghostty_key_encoder_new', 0, slot),
+    'create the key encoder',
+  );
+
+  const keyEvent = bridge.createHandle(
+    (slot) => bridge.call('ghostty_key_event_new', 0, slot),
+    'create the key event',
+  );
+
+  return {
+    write: (bytes) => {
+      bridge.withScratch(bytes.length, (pointer) => {
+        new Uint8Array(bridge.memory.buffer).set(bytes, pointer);
+
+        bridge.call('ghostty_terminal_vt_write', terminal, pointer, bytes.length);
+      });
+    },
+    resize: (size) => {
+      bridge.expectSuccess(
+        bridge.call(
+          'ghostty_terminal_resize',
+          terminal,
+          size.cols,
+          size.rows,
+          cellWidthPx,
+          cellHeightPx,
+        ),
+        'resize the terminal',
+      );
+    },
+    text: () =>
+      pickVisibleText(
+        readGhosttyText(bridge, terminal),
+        readTerminalValue(bridge, terminal, 'TOTAL_ROWS', 4).getUint32(0, true),
+        readTerminalValue(bridge, terminal, 'ROWS', 2).getUint16(0, true),
+      ),
+    unwrappedText: () =>
+      pickUnwrappedText(
+        readGhosttyText(bridge, terminal),
+        readGhosttyText(bridge, terminal, true).split('\n'),
+        readTerminalValue(bridge, terminal, 'TOTAL_ROWS', 4).getUint32(0, true),
+        readTerminalValue(bridge, terminal, 'ROWS', 2).getUint16(0, true),
+      ),
+    cursor: (): CursorState => ({
+      row: readTerminalValue(bridge, terminal, 'CURSOR_Y', 2).getUint16(0, true),
+      col: readTerminalValue(bridge, terminal, 'CURSOR_X', 2).getUint16(0, true),
+      visible: readTerminalValue(bridge, terminal, 'CURSOR_VISIBLE', 1).getUint8(0) !== 0,
+    }),
+    encodeKey: (key) => encodeGhosttyKey(bridge, { encoder, keyEvent, terminal }, key),
+    dispose: () => {
+      bridge.call('ghostty_key_event_free', keyEvent);
+      bridge.call('ghostty_key_encoder_free', encoder);
+      bridge.call('ghostty_terminal_free', terminal);
+    },
+  };
+}
+
+// Copies the value out, because the library's memory may move when it grows.
+function readTerminalValue(
+  bridge: WasmBridge,
+  terminal: number,
+  member: string,
+  size: number,
+): DataView {
+  const data = bridge.layout.enumValue('GhosttyTerminalData', member);
+
+  return bridge.withScratch(size, (pointer) => {
+    bridge.expectSuccess(
+      bridge.call('ghostty_terminal_get', terminal, data, pointer),
+      `read ${member}`,
+    );
+
+    return new DataView(bridge.memory.buffer.slice(pointer, pointer + size));
+  });
+}

package/src/create-raw-log.ts

@@ -0,0 +1,49 @@
+import { open } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { createDirectory } from '@wringer/core';
+
+export interface RawLog {
+  readonly write: (bytes: Uint8Array) => void;
+
+  // Resolves once every write has landed, so a stop leaves the whole log on disk.
+  readonly close: () => Promise<void>;
+}
+
+// Appends the bytes a program wrote, in order, to one file. A failed write is reported once, and
+// the log keeps trying later writes, so a full disk never stops the session.
+export async function createRawLog(
+  path: string,
+  reportError: (message: string) => void,
+): Promise<RawLog> {
+  await createDirectory(dirname(path));
+
+  const handle = await open(path, 'a');
+
+  let pending: Promise<void> = Promise.resolve();
+  let failed = false;
+
+  const append = async (previous: Promise<void>, bytes: Uint8Array): Promise<void> => {
+    await previous;
+
+    try {
+      await handle.write(bytes);
+    } catch (error) {
+      if (!failed) {
+        failed = true;
+
+        reportError(`The raw terminal log ${path} stopped: ${String(error)}`);
+      }
+    }
+  };
+
+  return {
+    write: (bytes) => {
+      pending = append(pending, Uint8Array.from(bytes));
+    },
+    close: async () => {
+      await pending;
+
+      await handle.close();
+    },
+  };
+}

package/src/create-terminal-session.ts

@@ -0,0 +1,231 @@
+import { constants } from 'node:os';
+import { WringerError } from '@wringer/core';
+import { buildTextKeys } from './build-text-keys.ts';
+import { createRawLog } from './create-raw-log.ts';
+import { findScreenMatch } from './find-screen-match.ts';
+import type { ScreenMatch, ScreenPattern } from './find-screen-match.ts';
+import { parseKey } from './parse-key.ts';
+import type { KeyInput, ScreenEngine } from './screen-engine.ts';
+
+interface Screen {
+  // Each line a program wrapped across rows is one line here, so a scrub sees a value whole.
+  readonly text: string;
+  readonly cursor: { readonly row: number; readonly col: number; readonly visible: boolean };
+  readonly cols: number;
+  readonly rows: number;
+}
+
+interface WaitResult {
+  readonly match: ScreenMatch | null;
+  readonly screen: Screen;
+}
+
+export interface TerminalSession {
+  readonly id: string;
+  readonly program: string;
+  readonly pid: number;
+  readonly isRunning: () => boolean;
+  readonly readExitCode: () => number | null;
+  readonly readScreen: () => Screen;
+  readonly writeText: (text: string) => void;
+  readonly writeKeys: (names: readonly string[]) => void;
+  readonly waitForScreen: (
+    pattern: ScreenPattern,
+    timeoutMs: number,
+    signal: AbortSignal,
+  ) => Promise<WaitResult>;
+  readonly stop: () => Promise<number>;
+
+  // Frees the engine; the session answers no screen after it.
+  readonly dispose: () => Promise<void>;
+}
+
+export interface TerminalSessionOptions {
+  readonly id: string;
+  readonly program: string;
+  readonly argv: readonly string[];
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly cols: number;
+  readonly rows: number;
+  readonly engine: ScreenEngine;
+  readonly rawLogPath: string;
+  readonly reportError: (message: string) => void;
+}
+
+const termGraceMs = 2000;
+
+// How long the end of a program waits for the last bytes of its output.
+const drainMs = 500;
+
+// Runs one program in a pseudo-terminal of the given size. Everything the program writes goes to
+// the screen engine and to a raw log, and a waiter wakes after each chunk.
+export async function createTerminalSession(
+  options: TerminalSessionOptions,
+): Promise<TerminalSession> {
+  const rawLog = await createRawLog(options.rawLogPath, options.reportError);
+
+  const listeners = new Set<() => void>();
+
+  const drained = Promise.withResolvers<void>();
+
+  const wake = (): void => {
+    for (const listener of listeners) {
+      listener();
+    }
+  };
+
+  let ended = false;
+
+  const subprocess = Bun.spawn([...options.argv], {
+    cwd: options.cwd,
+    env: { ...options.env },
+    terminal: {
+      cols: options.cols,
+      rows: options.rows,
+      data: (_terminal, data) => {
+        options.engine.write(data);
+        rawLog.write(data);
+
+        wake();
+      },
+      exit: () => {
+        drained.resolve();
+      },
+    },
+  });
+
+  const markEnded = async (): Promise<void> => {
+    await subprocess.exited;
+
+    await Promise.race([drained.promise, Bun.sleep(drainMs)]);
+
+    ended = true;
+
+    wake();
+  };
+
+  void markEnded();
+
+  const readScreen = (): Screen => ({
+    text: options.engine.unwrappedText(),
+    cursor: options.engine.cursor(),
+    cols: options.cols,
+    rows: options.rows,
+  });
+
+  const isRunning = (): boolean => !ended;
+
+  const write = (keys: readonly KeyInput[]): void => {
+    if (ended) {
+      throw new WringerError('check-failed', {
+        message: `Session ${options.id} has exited, so it takes no input.`,
+        hint: 'Run `terminal screen` for its last screen, or `terminal start` for a new session.',
+      });
+    }
+
+    const chunks = keys.map((key) => options.engine.encodeKey(key));
+
+    for (const chunk of chunks) {
+      subprocess.terminal?.write(chunk);
+    }
+  };
+
+  return {
+    id: options.id,
+    program: options.program,
+    pid: subprocess.pid,
+    isRunning,
+    readExitCode: () => (ended ? readExitCode(subprocess) : null),
+    readScreen,
+    writeText: (text) => {
+      write(buildTextKeys(text));
+    },
+    writeKeys: (names) => {
+      write(names.map((name) => getKey(name)));
+    },
+    waitForScreen: async (pattern, timeoutMs, signal) => {
+      const deadline = AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]);
+
+      for (;;) {
+        const screen = readScreen();
+        const match = findScreenMatch(options.engine.text(), pattern);
+
+        if (match !== null || ended || deadline.aborted) {
+          return { match, screen };
+        }
+
+        await waitForChange(listeners, deadline);
+      }
+    },
+    stop: async () => {
+      if (!ended) {
+        subprocess.kill('SIGTERM');
+
+        const exited = await Promise.race([
+          subprocess.exited.then(() => true),
+          Bun.sleep(termGraceMs).then(() => false),
+        ]);
+
+        if (!exited) {
+          subprocess.kill('SIGKILL');
+        }
+
+        await subprocess.exited;
+      }
+
+      subprocess.terminal?.close();
+      ended = true;
+
+      return readExitCode(subprocess);
+    },
+    dispose: async () => {
+      options.engine.dispose();
+
+      await rawLog.close();
+    },
+  };
+}
+
+function readExitCode(subprocess: Bun.Subprocess): number {
+  if (subprocess.exitCode !== null) {
+    return subprocess.exitCode;
+  }
+
+  const signal = subprocess.signalCode;
+
+  if (signal === null) {
+    return 128;
+  }
+
+  return 128 + (typeof signal === 'number' ? signal : constants.signals[signal]);
+}
+
+function getKey(name: string): KeyInput {
+  const key = parseKey(name);
+
+  if (key === null) {
+    throw new WringerError('usage', {
+      message: `The driver does not know the key ${name}.`,
+      hint: 'Name a key such as enter, esc, tab, up, f5, ctrl+c or alt+x. Type a shifted symbol, such as !, with type --text.',
+    });
+  }
+
+  return key;
+}
+
+async function waitForChange(listeners: Set<() => void>, deadline: AbortSignal): Promise<void> {
+  const changed = Promise.withResolvers<void>();
+
+  const listener = (): void => {
+    changed.resolve();
+  };
+
+  listeners.add(listener);
+  deadline.addEventListener('abort', listener, { once: true });
+
+  await changed.promise;
+
+  listeners.delete(listener);
+  deadline.removeEventListener('abort', listener);
+}

package/src/create-wasm-bridge.ts

@@ -0,0 +1,85 @@
+import { WringerError } from '@wringer/core';
+import { z } from 'zod';
+import { parseGhosttyLayout } from './parse-ghostty-layout.ts';
+import type { GhosttyLayout } from './parse-ghostty-layout.ts';
+
+export interface WasmBridge {
+  readonly layout: GhosttyLayout;
+  readonly memory: WebAssembly.Memory;
+  readonly call: (name: string, ...args: number[]) => number;
+
+  // Runs `use` with a buffer of `size` bytes in the library's memory, and frees it after.
+  readonly withScratch: <Result>(size: number, use: (pointer: number) => Result) => Result;
+  readonly expectSuccess: (result: number, what: string) => void;
+
+  // Calls a constructor that writes a handle to a slot, and returns the handle.
+  readonly createHandle: (create: (slot: number) => number, what: string) => number;
+}
+
+const instanceSchema = z.looseObject({ memory: z.instanceof(WebAssembly.Memory) });
+const resultSchema = z.number().default(0);
+
+// Instantiates the library, which takes no imports, and wraps its exports. A call that returns
+// nothing answers 0.
+export function createWasmBridge(module: WebAssembly.Module): WasmBridge {
+  const instance = new WebAssembly.Instance(module, {});
+
+  const memory = instanceSchema.parse(instance.exports).memory;
+
+  const call = (name: string, ...args: number[]): number => {
+    const exported: unknown = instance.exports[name];
+
+    if (typeof exported !== 'function') {
+      throw new WringerError('internal', { message: `The terminal engine has no export ${name}.` });
+    }
+
+    return resultSchema.parse(Reflect.apply(exported, undefined, args));
+  };
+
+  const layout = parseGhosttyLayout(readLayoutJSON(memory, call));
+  const success = layout.enumValue('GhosttyResult', 'SUCCESS');
+
+  const expectSuccess = (result: number, what: string): void => {
+    if (result !== success) {
+      throw new WringerError('internal', { message: `The terminal engine failed to ${what}.` });
+    }
+  };
+
+  return {
+    layout,
+    memory,
+    call,
+    expectSuccess,
+    withScratch: (size, use) => {
+      const pointer = call('ghostty_wasm_alloc', size);
+
+      try {
+        return use(pointer);
+      } finally {
+        call('ghostty_wasm_free', pointer, size);
+      }
+    },
+    createHandle: (create, what) => {
+      const slot = call('ghostty_wasm_alloc_opaque');
+
+      expectSuccess(create(slot), what);
+
+      const handle = call('ghostty_wasm_take_opaque', slot);
+
+      call('ghostty_wasm_free_opaque', slot);
+
+      return handle;
+    },
+  };
+}
+
+function readLayoutJSON(
+  memory: WebAssembly.Memory,
+  call: (name: string, ...args: number[]) => number,
+): string {
+  const start = call('ghostty_type_json');
+
+  const bytes = new Uint8Array(memory.buffer, start);
+
+  return new TextDecoder().decode(bytes.subarray(0, bytes.indexOf(0)));
+}

package/src/encode-ghostty-key.ts

@@ -0,0 +1,94 @@
+import { WringerError } from '@wringer/core';
+import type { WasmBridge } from './create-wasm-bridge.ts';
+import { keyNames } from './key-names.ts';
+import type { KeyInput } from './screen-engine.ts';
+
+export interface KeyHandles {
+  readonly encoder: number;
+  readonly keyEvent: number;
+  readonly terminal: number;
+}
+
+const modBits = { shift: 1, ctrl: 2, alt: 4, super: 8 } as const;
+
+// Encodes one key press under the terminal's live modes, and returns the bytes to send.
+export function encodeGhosttyKey(
+  bridge: WasmBridge,
+  handles: KeyHandles,
+  key: KeyInput,
+): Uint8Array {
+  const ghosttyName = keyNames[key.key] ?? 'UNIDENTIFIED';
+
+  if (ghosttyName === 'UNIDENTIFIED' && key.key !== 'unidentified') {
+    throw new WringerError('usage', { message: `The key ${key.key} is not one the driver knows.` });
+  }
+
+  const mods =
+    (key.mods.shift ? modBits.shift : 0) |
+    (key.mods.ctrl ? modBits.ctrl : 0) |
+    (key.mods.alt ? modBits.alt : 0) |
+    (key.mods.super ? modBits.super : 0);
+
+  const unshifted = key.key.length === 1 ? (key.key.codePointAt(0) ?? 0) : 0;
+  const keyCode = bridge.layout.enumValue('GhosttyKey', ghosttyName);
+  const press = bridge.layout.enumValue('GhosttyKeyAction', 'PRESS');
+
+  bridge.expectSuccess(
+    bridge.call('ghostty_key_encoder_set_from_terminal', handles.encoder, handles.terminal),
+    'sync the key encoder',
+  );
+
+  bridge.call('ghostty_key_event_set_action', handles.keyEvent, press);
+  bridge.call('ghostty_key_event_set_key', handles.keyEvent, keyCode);
+  bridge.call('ghostty_key_event_set_mods', handles.keyEvent, mods);
+  bridge.call('ghostty_key_event_set_consumed_mods', handles.keyEvent, 0);
+  bridge.call('ghostty_key_event_set_unshifted_codepoint', handles.keyEvent, unshifted);
+
+  writeKeyText(bridge, handles.keyEvent, new TextEncoder().encode(key.text ?? ''));
+
+  return readEncodedKey(bridge, handles);
+}
+
+// The library takes its string as a pointer to a pointer and a length.
+function writeKeyText(bridge: WasmBridge, keyEvent: number, text: Uint8Array): void {
+  bridge.withScratch(text.length + 8, (pointer) => {
+    const textPointer = text.length === 0 ? 0 : pointer + 8;
+
+    const view = new DataView(bridge.memory.buffer);
+
+    new Uint8Array(bridge.memory.buffer).set(text, pointer + 8);
+
+    view.setUint32(pointer, textPointer, true);
+    view.setUint32(pointer + 4, text.length, true);
+
+    bridge.expectSuccess(
+      bridge.call('ghostty_key_event_set_utf8', keyEvent, pointer),
+      'set the key text',
+    );
+  });
+}
+
+// Far longer than any key sequence.
+const maxKeyBytes = 64;
+
+function readEncodedKey(bridge: WasmBridge, handles: KeyHandles): Uint8Array {
+  return bridge.withScratch(maxKeyBytes + bridge.layout.usizeSize, (pointer) => {
+    const writtenPointer = pointer + maxKeyBytes;
+
+    bridge.expectSuccess(
+      bridge.call(
+        'ghostty_key_encoder_encode',
+        handles.encoder,
+        handles.keyEvent,
+        pointer,
+        maxKeyBytes,
+        writtenPointer,
+      ),
+      'encode the key',
+    );
+
+    const written = new DataView(bridge.memory.buffer).getUint32(writtenPointer, true);
+
+    return new Uint8Array(bridge.memory.buffer.slice(pointer, pointer + written));
+  });
+}

package/src/find-screen-match.ts

@@ -0,0 +1,37 @@
+export type ScreenPattern =
+  | { readonly kind: 'text'; readonly text: string }
+  | { readonly kind: 'regex'; readonly source: string };
+
+export interface ScreenMatch {
+  readonly row: number;
+  readonly col: number;
+}
+
+// The first match in reading order, as the row and the column of its first character, both from 0.
+// The pattern's regex is checked when the command is parsed, so a bad one here matches nothing.
+export function findScreenMatch(text: string, pattern: ScreenPattern): ScreenMatch | null {
+  const lines = text.split('\n');
+
+  if (pattern.kind === 'text') {
+    return findInLines(lines, (line) => line.indexOf(pattern.text));
+  }
+
+  const regex = new RegExp(pattern.source, 'u');
+
+  return findInLines(lines, (line) => line.search(regex));
+}
+
+function findInLines(
+  lines: readonly string[],
+  locate: (line: string) => number,
+): ScreenMatch | null {
+  for (const [row, line] of lines.entries()) {
+    const col = locate(line);
+
+    if (col >= 0) {
+      return { row, col };
+    }
+  }
+
+  return null;
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export { terminal } from './terminal.ts';
+
+export type {
+  TerminalClient,
+  TerminalScreen,
+  TerminalSessionInfo,
+  TerminalStartRequest,
+  TerminalWaitRequest,
+} from './terminal.ts';
+
+export type { CursorState, KeyInput, KeyMods, ScreenEngine } from './screen-engine.ts';