@wringer/terminal 0.0.0-stage → 0.0.0

package/src/key-names.ts

@@ -0,0 +1,47 @@
+// Each key name an agent may press, mapped to the name of its key in the engine's key table.
+export const keyNames: Readonly<Record<string, string>> = buildKeyNames();
+
+function buildKeyNames(): Record<string, string> {
+  const names: Record<string, string> = {
+    enter: 'ENTER',
+    tab: 'TAB',
+    space: 'SPACE',
+    backspace: 'BACKSPACE',
+    escape: 'ESCAPE',
+    delete: 'DELETE',
+    insert: 'INSERT',
+    home: 'HOME',
+    end: 'END',
+    pageup: 'PAGE_UP',
+    pagedown: 'PAGE_DOWN',
+    up: 'ARROW_UP',
+    down: 'ARROW_DOWN',
+    left: 'ARROW_LEFT',
+    right: 'ARROW_RIGHT',
+    '`': 'BACKQUOTE',
+    '\\': 'BACKSLASH',
+    '[': 'BRACKET_LEFT',
+    ']': 'BRACKET_RIGHT',
+    ',': 'COMMA',
+    '=': 'EQUAL',
+    '-': 'MINUS',
+    '.': 'PERIOD',
+    "'": 'QUOTE',
+    ';': 'SEMICOLON',
+    '/': 'SLASH',
+  };
+
+  for (const letter of 'abcdefghijklmnopqrstuvwxyz') {
+    names[letter] = letter.toUpperCase();
+  }
+
+  for (const digit of '0123456789') {
+    names[digit] = `DIGIT_${digit}`;
+  }
+
+  for (let number = 1; number <= 24; number += 1) {
+    names[`f${String(number)}`] = `F${String(number)}`;
+  }
+
+  return names;
+}

package/src/parse-ghostty-layout.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+
+const memberSchema = z.record(z.string(), z.number());
+const enumSchema = z.object({ values: memberSchema });
+const usizeSchema = z.union([z.literal(4), z.literal(8)]);
+
+const layoutSchema = z.object({
+  abi: z.object({ usize_size: usizeSchema }),
+  types: z.record(z.string(), z.unknown()),
+});
+
+export interface GhosttyLayout {
+  readonly usizeSize: 4 | 8;
+
+  // The value of one member of an enum the library describes, such as `GhosttyKey` and `ENTER`.
+  readonly enumValue: (enumName: string, member: string) => number;
+}
+
+// The library describes its own ABI as JSON, so the binding reads each enum value and the size of
+// `usize` from it and hard-codes none.
+export function parseGhosttyLayout(json: string): GhosttyLayout {
+  const parsed: unknown = JSON.parse(json);
+  const layout = layoutSchema.parse(parsed);
+
+  return {
+    usizeSize: layout.abi.usize_size,
+    enumValue: (enumName, member) => {
+      const described = enumSchema.parse(layout.types[enumName]);
+      const members = described.values;
+      const value = members[member];
+
+      if (value === undefined) {
+        throw new Error(`The library's ${enumName} has no member ${member}.`);
+      }
+
+      return value;
+    },
+  };
+}

package/src/parse-key.ts

@@ -0,0 +1,83 @@
+import { keyNames } from './key-names.ts';
+import type { KeyInput, KeyMods } from './screen-engine.ts';
+
+const modifierNames: Readonly<Record<string, keyof KeyMods>> = {
+  ctrl: 'ctrl',
+  control: 'ctrl',
+  alt: 'alt',
+  option: 'alt',
+  shift: 'shift',
+  super: 'super',
+  cmd: 'super',
+};
+
+const keyAliases: Readonly<Record<string, string>> = {
+  esc: 'escape',
+  return: 'enter',
+  del: 'delete',
+  ins: 'insert',
+  pgup: 'pageup',
+  pgdn: 'pagedown',
+  ' ': 'space',
+};
+
+const modifierPrefix = /^(?<name>[a-z]+)\+(?=.)/u;
+
+// Turns `ctrl+c`, `alt+x`, `shift+tab`, `f5` or `up` into a key event, or null for a name the
+// driver does not know. A capital letter is the shifted key.
+export function parseKey(spec: string): KeyInput | null {
+  const mods = { shift: false, ctrl: false, alt: false, super: false };
+  let rest = spec;
+
+  for (let match = modifierPrefix.exec(rest); match !== null; match = modifierPrefix.exec(rest)) {
+    const modifier = modifierNames[match.groups?.['name']?.toLowerCase() ?? ''];
+
+    if (modifier === undefined) {
+      return null;
+    }
+
+    mods[modifier] = true;
+    rest = rest.slice(match[0].length);
+  }
+
+  const isCapital = /^[A-Z]$/u.test(rest);
+  const lowered = rest.toLowerCase();
+  const key = keyAliases[lowered] ?? lowered;
+
+  if (!Object.hasOwn(keyNames, key)) {
+    return null;
+  }
+
+  const held = { ...mods, shift: mods.shift || isCapital };
+
+  if (isShiftedSymbol(key, held)) {
+    return null;
+  }
+
+  const text = pickKeyText(key, held);
+
+  return text === undefined ? { key, mods: held } : { key, mods: held, text };
+}
+
+// The character that shift gives a digit or a symbol key depends on the keyboard layout, so the
+// driver can't name the text the encoder needs. Without that text, the encoder sends no bytes.
+function isShiftedSymbol(key: string, mods: KeyMods): boolean {
+  return mods.shift && !mods.ctrl && !mods.alt && !mods.super && /^[^a-z]$/u.test(key);
+}
+
+// A key that no ctrl, alt or super modifies types its character, so the encoder needs that text.
+function pickKeyText(key: string, mods: KeyMods): string | undefined {
+  if (mods.ctrl || mods.alt || mods.super) {
+    return undefined;
+  }
+
+  if (key === 'space') {
+    return ' ';
+  }
+
+  if (key.length !== 1) {
+    return undefined;
+  }
+
+  return mods.shift ? key.toUpperCase() : key;
+}

package/src/pick-session.ts

@@ -0,0 +1,47 @@
+export interface SessionSummary {
+  readonly id: string;
+  readonly running: boolean;
+}
+
+export type SessionPick =
+  | { readonly kind: 'found'; readonly id: string }
+  | { readonly kind: 'refused'; readonly message: string; readonly hint: string };
+
+// With no id asked for, the one running session answers. When none runs, the one session that
+// ended answers, so its last screen stays readable.
+export function pickSession(
+  sessions: readonly SessionSummary[],
+  requested: string | undefined,
+): SessionPick {
+  if (requested !== undefined) {
+    return sessions.some((session) => session.id === requested)
+      ? { kind: 'found', id: requested }
+      : {
+          kind: 'refused',
+          message: `This run has no terminal session ${requested}.`,
+          hint: 'Run `terminal list` for the sessions, or `terminal start <program>` for a new one.',
+        };
+  }
+
+  const running = sessions.filter((session) => session.running);
+  const candidates = running.length > 0 ? running : sessions;
+  const [only] = candidates;
+
+  if (only === undefined) {
+    return {
+      kind: 'refused',
+      message: 'This run has no terminal session.',
+      hint: 'Run `terminal start <program>` first.',
+    };
+  }
+
+  if (candidates.length > 1) {
+    return {
+      kind: 'refused',
+      message: `More than one terminal session ${running.length > 0 ? 'runs' : 'exists'}: ${candidates.map((session) => session.id).join(', ')}.`,
+      hint: 'Pass --session with one of them.',
+    };
+  }
+
+  return { kind: 'found', id: only.id };
+}

package/src/pick-unwrapped-text.ts

@@ -0,0 +1,47 @@
+// Joins each run of soft-wrapped rows into one line. Each logical line takes as many rows as it
+// needs to reach its length. Only the rows from `totalRows - rows` down are the screen, and a line
+// that began above them keeps its visible part.
+export function pickUnwrappedText(
+  wrappedText: string,
+  logicalLines: readonly string[],
+  totalRows: number,
+  rows: number,
+): string {
+  const physicalRows = wrappedText.split('\n');
+  const top = Math.max(0, totalRows - rows);
+  const lines: string[] = [];
+  let next = 0;
+
+  for (const logical of logicalLines) {
+    const first = next;
+    const lineRows: string[] = [];
+    let rest = logical;
+
+    // The formatter trims the spaces that end a row, so a space at a wrap boundary is missing from
+    // the row. The logical line still holds it: the spaces between two rows' text, less the ones
+    // that begin the next row, ended this row.
+    do {
+      const row = physicalRows[next] ?? rest;
+      const nextRow = physicalRows[next + 1];
+
+      rest = rest.slice(row.length);
+      next += 1;
+
+      const between = rest.length - rest.trimStart().length;
+      const leading = nextRow === undefined ? 0 : nextRow.length - nextRow.trimStart().length;
+      const trailing = rest.trim() === '' ? '' : ' '.repeat(Math.max(0, between - leading));
+
+      rest = rest.slice(trailing.length);
+
+      lineRows.push(row + trailing);
+    } while (rest.trim() !== '' && next < physicalRows.length);
+
+    const visible = lineRows.slice(Math.max(first, top) - first);
+
+    if (visible.length > 0) {
+      lines.push(visible.join(''));
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/pick-visible-text.ts

@@ -0,0 +1,8 @@
+// The formatter prints every row the terminal holds, scrollback included, and drops the blank rows
+// at the end. The screen is the last `rows` physical rows, so the text starts at row
+// `totalRows - rows`.
+export function pickVisibleText(text: string, totalRows: number, rows: number): string {
+  const top = Math.max(0, totalRows - rows);
+
+  return text.split('\n').slice(top).join('\n');
+}

package/src/read-ghostty-module.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+
+export const ghosttyWasmURL = new URL('../ghostty/ghostty-vt.wasm', import.meta.url);
+
+const ghosttyManifestURL = new URL('../ghostty/ghostty-vt.json', import.meta.url);
+
+const manifestSchema = z.strictObject({
+  tag: z.string(),
+  commit: z.string(),
+  zig: z.string(),
+  optimize: z.string(),
+  sha256: z.string(),
+});
+
+export async function readGhosttyManifest(): Promise<z.infer<typeof manifestSchema>> {
+  const manifest: unknown = await Bun.file(ghosttyManifestURL).json();
+
+  return manifestSchema.parse(manifest);
+}
+
+// Compiles the library once, so each session only instantiates it.
+export async function readGhosttyModule(): Promise<WebAssembly.Module> {
+  const bytes = await Bun.file(ghosttyWasmURL).arrayBuffer();
+
+  return WebAssembly.compile(bytes);
+}

package/src/read-ghostty-text.ts

@@ -0,0 +1,56 @@
+import type { WasmBridge } from './create-wasm-bridge.ts';
+
+// Prints the terminal's rows as plain text, scrollback included, with the blank rows at the end
+// dropped.
+export function readGhosttyText(bridge: WasmBridge, terminal: number, unwrap = false): string {
+  const formatter = bridge.createHandle(
+    (slot) => bridge.call('ghostty_formatter_terminal_new', 0, slot, terminal),
+    'create the formatter',
+  );
+
+  const plain = bridge.layout.enumValue('GhosttyFormatterFormat', 'PLAIN');
+  const emitOption = bridge.layout.enumValue('GhosttyFormatterOption', 'EMIT');
+
+  bridge.withScratch(4, (pointer) => {
+    new DataView(bridge.memory.buffer).setInt32(pointer, plain, true);
+
+    bridge.expectSuccess(
+      bridge.call('ghostty_formatter_set', formatter, emitOption, pointer),
+      'set the formatter',
+    );
+  });
+
+  if (unwrap) {
+    const unwrapOption = bridge.layout.enumValue('GhosttyFormatterOption', 'UNWRAP');
+
+    bridge.withScratch(1, (pointer) => {
+      new DataView(bridge.memory.buffer).setUint8(pointer, 1);
+
+      bridge.expectSuccess(
+        bridge.call('ghostty_formatter_set', formatter, unwrapOption, pointer),
+        'set the formatter to unwrap',
+      );
+    });
+  }
+
+  const outPointer = bridge.call('ghostty_wasm_alloc_opaque');
+  const lengthPointer = bridge.call('ghostty_wasm_alloc', bridge.layout.usizeSize);
+
+  bridge.expectSuccess(
+    bridge.call('ghostty_formatter_format_alloc', formatter, 0, outPointer, lengthPointer),
+    'format the screen',
+  );
+
+  const textPointer = bridge.call('ghostty_wasm_take_opaque', outPointer);
+
+  const length = new DataView(bridge.memory.buffer).getUint32(lengthPointer, true);
+  const bytes = new Uint8Array(bridge.memory.buffer, textPointer, length);
+  const text = new TextDecoder().decode(bytes);
+
+  bridge.call('ghostty_free', 0, textPointer, length);
+  bridge.call('ghostty_wasm_free_opaque', outPointer);
+  bridge.call('ghostty_wasm_free', lengthPointer, bridge.layout.usizeSize);
+  bridge.call('ghostty_formatter_free', formatter);
+
+  return text;
+}

package/src/screen-engine.ts

@@ -0,0 +1,41 @@
+export interface KeyMods {
+  readonly shift: boolean;
+  readonly ctrl: boolean;
+  readonly alt: boolean;
+  readonly super: boolean;
+}
+
+// One key event. `key` is a name from `keyNames`, and `text` is what the key types when no
+// modifier but shift is held.
+export interface KeyInput {
+  readonly key: string;
+  readonly mods: KeyMods;
+  readonly text?: string | undefined;
+}
+
+// Rows and columns count from 0, from the top left of the screen.
+export interface CursorState {
+  readonly row: number;
+  readonly col: number;
+  readonly visible: boolean;
+}
+
+interface ScreenSize {
+  readonly cols: number;
+  readonly rows: number;
+}
+
+// The screen a program draws on. An engine takes the bytes the program wrote and answers what a
+// reader sees, and turns a key into the bytes the program expects under its current modes.
+export interface ScreenEngine {
+  readonly write: (bytes: Uint8Array) => void;
+  readonly resize: (size: ScreenSize) => void;
+  readonly text: () => string;
+
+  // The screen text with each soft-wrapped line joined, so a value that wrapped across rows reads
+  // whole. A line can be longer than the columns, and its row index no longer matches the cursor's.
+  readonly unwrappedText: () => string;
+  readonly cursor: () => CursorState;
+  readonly encodeKey: (key: KeyInput) => Uint8Array;
+  readonly dispose: () => void;
+}

package/src/session-service-contract.ts

@@ -0,0 +1,83 @@
+import { z } from 'zod';
+
+const sessionIDSchema = z.string().min(1).optional();
+
+const matchSchema = z.strictObject({
+  row: z.number().int().nonnegative(),
+  col: z.number().int().nonnegative(),
+});
+
+export const screenSchema = z.strictObject({
+  text: z.string(),
+  cursor: z.strictObject({
+    row: z.number().int().nonnegative(),
+    col: z.number().int().nonnegative(),
+    visible: z.boolean(),
+  }),
+  cols: z.number().int().positive(),
+  rows: z.number().int().positive(),
+});
+
+const sessionOnlySchema = z.strictObject({ session: z.string() });
+
+export const sessionInfoSchema = z.strictObject({
+  session: z.string(),
+  program: z.string(),
+  pid: z.number().int(),
+  running: z.boolean(),
+  exitCode: z.number().int().nullable(),
+});
+
+// The sessions service crosses from the CLI to the run's supervisor as untyped JSON, so the client
+// parses each answer and the supervisor parses each request against this one table.
+export const sessionServiceContract = {
+  start: {
+    args: z.strictObject({ program: z.string().min(1) }),
+    result: z.strictObject({ session: z.string(), pid: z.number().int() }),
+  },
+  type: {
+    args: z.strictObject({ session: sessionIDSchema, text: z.string() }),
+    result: sessionOnlySchema,
+  },
+  press: {
+    args: z.strictObject({ session: sessionIDSchema, keys: z.array(z.string().min(1)).min(1) }),
+    result: sessionOnlySchema,
+  },
+  wait: {
+    args: z.strictObject({
+      session: sessionIDSchema,
+      text: z.string().min(1).optional(),
+      regex: z.string().min(1).optional(),
+      timeoutMs: z.number().int().positive(),
+    }),
+    result: z.strictObject({
+      session: z.string(),
+      match: matchSchema.nullable(),
+      screen: screenSchema,
+    }),
+  },
+  screen: {
+    args: z.strictObject({ session: sessionIDSchema }),
+    result: z.strictObject({ session: z.string(), screen: screenSchema }),
+  },
+  stop: {
+    args: z.strictObject({ session: sessionIDSchema }),
+    result: z.strictObject({ session: z.string(), exitCode: z.number().int() }),
+  },
+  list: {
+    args: z.null(),
+    result: z.strictObject({ sessions: z.array(sessionInfoSchema) }),
+  },
+};
+
+type SessionServiceContract = typeof sessionServiceContract;
+
+export type SessionMethod = keyof SessionServiceContract;
+
+export type SessionArgs<Method extends SessionMethod> = z.output<
+  SessionServiceContract[Method]['args']
+>;
+
+export type SessionResult<Method extends SessionMethod> = z.output<
+  SessionServiceContract[Method]['result']
+>;

package/src/start-terminal-sessions.ts

@@ -0,0 +1,152 @@
+import { resolve } from 'node:path';
+import { WringerError } from '@wringer/core';
+import type { ServiceInstance } from '@wringer/core';
+import { createGhosttyEngine } from './create-ghostty-engine.ts';
+import { createTerminalSession } from './create-terminal-session.ts';
+import type { TerminalSession } from './create-terminal-session.ts';
+import { pickSession } from './pick-session.ts';
+import type { SessionSummary } from './pick-session.ts';
+import { toSessionServiceMethods } from './to-session-service-methods.ts';
+
+interface ProgramConfig {
+  readonly command: readonly string[];
+  readonly env?: Readonly<Record<string, string>> | undefined;
+  readonly cwd?: string | undefined;
+}
+
+export interface TerminalSessionsOptions {
+  readonly programs: Readonly<Record<string, ProgramConfig>>;
+  readonly cols: number;
+  readonly rows: number;
+  readonly module: WebAssembly.Module;
+
+  // A relative program `cwd` starts here.
+  readonly root: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly rawLogPath: (sessionID: string) => string;
+  readonly reportError: (message: string) => void;
+}
+
+// Every program a run starts lives here until the run stops, so a screen keeps its state between
+// commands. The service answers only for the programs the target names.
+export function startTerminalSessions(options: TerminalSessionsOptions): ServiceInstance {
+  const sessions = new Map<string, TerminalSession>();
+  const started = new Map<string, number>();
+
+  const summarize = (): SessionSummary[] =>
+    [...sessions.values()].map((session) => ({ id: session.id, running: session.isRunning() }));
+
+  const getSession = (requested: string | undefined): TerminalSession => {
+    const pick = pickSession(summarize(), requested);
+
+    if (pick.kind === 'refused') {
+      throw new WringerError('usage', { message: pick.message, hint: pick.hint });
+    }
+
+    const session = sessions.get(pick.id);
+
+    if (session === undefined) {
+      throw new WringerError('internal', { message: `Session ${pick.id} is not kept.` });
+    }
+
+    return session;
+  };
+
+  return {
+    methods: toSessionServiceMethods({
+      start: async (args) => {
+        const program = Object.hasOwn(options.programs, args.program)
+          ? options.programs[args.program]
+          : undefined;
+
+        if (program === undefined) {
+          throw new WringerError('usage', {
+            message: `The target has no terminal program ${args.program}.`,
+            hint: `Name one of: ${Object.keys(options.programs).join(', ')}.`,
+          });
+        }
+
+        const count = (started.get(args.program) ?? 0) + 1;
+
+        started.set(args.program, count);
+
+        const id = `${args.program}-${String(count)}`;
+
+        const session = await createTerminalSession({
+          id,
+          program: args.program,
+          argv: program.command,
+          cwd: resolve(options.root, program.cwd ?? '.'),
+          env: { ...options.env, ...program.env },
+          cols: options.cols,
+          rows: options.rows,
+          engine: createGhosttyEngine({
+            module: options.module,
+            cols: options.cols,
+            rows: options.rows,
+          }),
+          rawLogPath: options.rawLogPath(id),
+          reportError: options.reportError,
+        });
+
+        sessions.set(id, session);
+
+        return { session: id, pid: session.pid };
+      },
+      type: (args) => {
+        const session = getSession(args.session);
+
+        session.writeText(args.text);
+
+        return Promise.resolve({ session: session.id });
+      },
+      press: (args) => {
+        const session = getSession(args.session);
+
+        session.writeKeys(args.keys);
+
+        return Promise.resolve({ session: session.id });
+      },
+      wait: async (args, signal) => {
+        const session = getSession(args.session);
+
+        const pattern =
+          args.regex === undefined
+            ? { kind: 'text' as const, text: args.text ?? '' }
+            : { kind: 'regex' as const, source: args.regex };
+
+        const result = await session.waitForScreen(pattern, args.timeoutMs, signal);
+
+        return { session: session.id, ...result };
+      },
+      screen: (args) => {
+        const session = getSession(args.session);
+
+        return Promise.resolve({ session: session.id, screen: session.readScreen() });
+      },
+      stop: async (args) => {
+        const session = getSession(args.session);
+
+        return { session: session.id, exitCode: await session.stop() };
+      },
+      list: () =>
+        Promise.resolve({
+          sessions: [...sessions.values()].map((session) => ({
+            session: session.id,
+            program: session.program,
+            pid: session.pid,
+            running: session.isRunning(),
+            exitCode: session.readExitCode(),
+          })),
+        }),
+    }),
+    stop: async () => {
+      await Promise.all(
+        [...sessions.values()].map(async (session) => {
+          await session.stop();
+          await session.dispose();
+        }),
+      );
+    },
+  };
+}