@alchemy.run/sigil 0.0.0-alpha.4 → 0.0.0-alpha.6

package/src/testing/terminal.ts

@@ -0,0 +1,349 @@
+// End-to-end terminal testing: launch an app in a real PTY wired to a real
+// terminal emulator engine (Ghostty's VT core or xterm.js), then interact
+// and assert Playwright-style — locators, auto-waiting, key presses.
+import { randomUUID } from "node:crypto";
+
+import {
+  createEmulator,
+  type Emulator,
+  type EmulatorCell,
+  type EmulatorName,
+} from "#/testing/emulators.ts";
+import { keyToSequence } from "#/testing/keys.ts";
+import { connectLiveClient, currentTestName } from "#/testing/live.ts";
+
+export type LaunchOptions = {
+  /**
+	Which emulator engine answers the app's terminal queries and interprets
+	its output.
+
+	@default "ghostty"
+	*/
+  emulator?: EmulatorName;
+
+  columns?: number;
+  rows?: number;
+
+  /**
+	The emulated OS color scheme at startup (Ghostty engine only).
+
+	@default "dark"
+	*/
+  colorScheme?: "dark" | "light";
+
+  cwd?: string;
+  env?: Record<string, string>;
+};
+
+export type WaitForOptions = {
+  /**
+	@default 5000
+	*/
+  timeout?: number;
+
+  /**
+	Wait for the text to appear (`"visible"`, default) or disappear
+	(`"hidden"`).
+	*/
+  state?: "visible" | "hidden";
+};
+
+export type TerminalLocator = {
+  /**
+	Whether the text is on the visible screen right now.
+	*/
+  isVisible: () => boolean;
+
+  /**
+	The full screen line containing the match, if any.
+	*/
+  line: () => string | undefined;
+
+  /**
+	Waits (polling) until the text appears — or disappears with
+	`state: "hidden"`. Throws with a screen dump on timeout.
+	*/
+  waitFor: (options?: WaitForOptions) => Promise<void>;
+
+  description: string;
+};
+
+export type TerminalApp = {
+  readonly emulator: EmulatorName;
+
+  /**
+	The visible screen as right-trimmed lines.
+	*/
+  lines: () => string[];
+
+  /**
+	The visible screen as one string, trailing blank lines removed.
+	*/
+  text: () => string;
+
+  getByText: (text: string | RegExp) => TerminalLocator;
+
+  /**
+	Polls until the predicate holds. Throws with a screen dump on timeout.
+	*/
+  waitFor: (predicate: () => boolean, options?: { timeout?: number }) => Promise<void>;
+
+  /**
+	Presses named keys in order: `press("Tab", "Enter")`, `press("Ctrl+C")`.
+	Keys are spaced out slightly, like real typing, so each key's effect
+	(focus moves, state updates) lands before the next one.
+	*/
+  press: (...keys: string[]) => Promise<void>;
+
+  /**
+	Types text verbatim.
+	*/
+  type: (text: string) => void;
+
+  resize: (columns: number, rows: number) => void;
+
+  /**
+	Flips the emulated OS color scheme (Ghostty engine only) — the app
+	receives a real color scheme report if it enabled them.
+	*/
+  setColorScheme: (scheme: "dark" | "light") => void;
+
+  cellAt: (x: number, y: number) => EmulatorCell | undefined;
+
+  cursor: () => { x: number; y: number };
+
+  /**
+	Everything the app has written, unprocessed.
+	*/
+  output: () => string;
+
+  /**
+	The exit code once the app has exited.
+	*/
+  exitCode: () => number | undefined;
+
+  waitForExit: (options?: { timeout?: number }) => Promise<number>;
+
+  /**
+	Kills the app (if still running) and disposes the emulator.
+	*/
+  close: () => void;
+};
+
+const defaultTimeout = 5000;
+const pollInterval = 25;
+
+const screenDump = (emulator: Emulator): string =>
+  ["", "── screen ──", ...emulator.lines().map((line) => `│${line}`), "────────────"].join("\n");
+
+const poll = async (
+  check: () => boolean,
+  timeout: number,
+  onTimeout: () => Error,
+): Promise<void> => {
+  const deadline = Date.now() + timeout;
+  for (;;) {
+    if (check()) {
+      return;
+    }
+
+    if (Date.now() > deadline) {
+      throw onTimeout();
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, pollInterval));
+  }
+};
+
+/**
+Launches a command inside a PTY attached to a real terminal emulator engine.
+
+```ts
+const app = await launchTerminal(["node", "--import=tsx", "examples/router/index.ts"]);
+await app.getByText("Home").waitFor();
+app.press("Tab", "Enter");
+await app.getByText("Users").waitFor();
+app.close();
+```
+
+A string command runs through `sh -c`.
+*/
+export const launchTerminal = async (
+  command: string | string[],
+  {
+    emulator: emulatorName = "ghostty",
+    columns = 100,
+    rows = 30,
+    colorScheme = "dark",
+    cwd = process.cwd(),
+    env = {},
+  }: LaunchOptions = {},
+): Promise<TerminalApp> => {
+  const zigpty = await import("zigpty").catch((error) => {
+    throw new Error(
+      'The "zigpty" package is required to launch terminal apps. Install it as a dev dependency: pnpm add -D zigpty',
+      { cause: error },
+    );
+  });
+
+  const emulator = await createEmulator(emulatorName, { columns, rows, colorScheme });
+
+  const argv = Array.isArray(command) ? command : ["/bin/sh", "-c", command];
+  // Tests should behave like a user's interactive truecolor session, even on
+  // CI — both emulator engines understand 24-bit SGR.
+  const childEnv: Record<string, string> = {
+    ...(process.env as Record<string, string>),
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    COLORTERM: "truecolor",
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    NODE_NO_WARNINGS: "1",
+    ...env,
+  };
+  delete childEnv["CI"];
+  const child = zigpty.spawn(argv[0], argv.slice(1), {
+    name: "xterm-256color",
+    cols: columns,
+    rows,
+    cwd,
+    env: childEnv,
+  });
+
+  let output = "";
+  let exitCode: number | undefined;
+  let closed = false;
+
+  // Mirror the session to the live hub (explorer /live page) when one is
+  // configured, so the run can be watched in the browser as it happens.
+  const live = connectLiveClient();
+  const liveId = randomUUID();
+  if (live) {
+    const commandTitle = Array.isArray(command) ? command.join(" ") : command;
+    live.send({ type: "start", id: liveId, title: commandTitle, columns, rows });
+    // Inside Vitest, relabel with the test that launched this session.
+    void currentTestName().then((name) => {
+      if (name) {
+        live.send({ type: "title", id: liveId, title: name });
+      }
+    });
+  }
+
+  child.onData((data: string | Buffer) => {
+    if (closed) {
+      return;
+    }
+
+    const chunk = typeof data === "string" ? data : data.toString("latin1");
+    output += chunk;
+    emulator.feed(chunk);
+    live?.send({ type: "data", id: liveId, data: chunk });
+  });
+
+  emulator.onResponse((data) => {
+    if (exitCode === undefined) {
+      child.write(data);
+    }
+  });
+
+  child.onExit(({ exitCode: code }: { exitCode: number }) => {
+    exitCode = code;
+    live?.send({ type: "end", id: liveId, code });
+  });
+
+  const lines = (): string[] => emulator.lines();
+
+  const getByText = (matcher: string | RegExp): TerminalLocator => {
+    const description = typeof matcher === "string" ? JSON.stringify(matcher) : String(matcher);
+    const findLine = (): string | undefined =>
+      lines().find((line) =>
+        typeof matcher === "string" ? line.includes(matcher) : matcher.test(line),
+      );
+
+    return {
+      description,
+      isVisible: () => findLine() !== undefined,
+      line: findLine,
+      waitFor: async ({ timeout = defaultTimeout, state = "visible" }: WaitForOptions = {}) => {
+        const check =
+          state === "visible" ? () => findLine() !== undefined : () => findLine() === undefined;
+        await poll(check, timeout, () =>
+          state === "visible"
+            ? new Error(`Timed out waiting for ${description} to appear.${screenDump(emulator)}`)
+            : new Error(
+                `Timed out waiting for ${description} to disappear.${screenDump(emulator)}`,
+              ),
+        );
+      },
+    };
+  };
+
+  return {
+    emulator: emulatorName,
+    lines,
+    text: () => lines().join("\n").replace(/\n+$/, ""),
+    getByText,
+    waitFor: async (predicate, { timeout = defaultTimeout } = {}) => {
+      await poll(
+        predicate,
+        timeout,
+        () => new Error(`Timed out waiting for condition.${screenDump(emulator)}`),
+      );
+    },
+    press: async (...keys) => {
+      for (const key of keys) {
+        const outputBefore = output.length;
+        child.write(keyToSequence(key));
+        // Wait for the key's effect to render before the next key — a fixed
+        // gap flakes under load when a re-render (e.g. a focus move) hasn't
+        // committed yet. Keys without visible effect give up after the cap.
+        const deadline = Date.now() + 500;
+        while (Date.now() < deadline && output.length === outputBefore) {
+          await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+
+        await new Promise((resolve) => setTimeout(resolve, 15));
+      }
+    },
+    type: (text) => {
+      child.write(text);
+    },
+    resize: (nextColumns, nextRows) => {
+      child.resize(nextColumns, nextRows);
+      emulator.resize(nextColumns, nextRows);
+    },
+    setColorScheme: (scheme) => {
+      if (!emulator.setColorScheme) {
+        throw new Error(`The ${emulatorName} emulator cannot change color scheme.`);
+      }
+
+      emulator.setColorScheme(scheme);
+    },
+    cellAt: emulator.cellAt,
+    cursor: emulator.cursor,
+    output: () => output,
+    exitCode: () => exitCode,
+    waitForExit: async ({ timeout = defaultTimeout } = {}) => {
+      await poll(
+        () => exitCode !== undefined,
+        timeout,
+        () => new Error(`Timed out waiting for the app to exit.${screenDump(emulator)}`),
+      );
+      return exitCode!;
+    },
+    close: () => {
+      if (closed) {
+        return;
+      }
+
+      closed = true;
+      if (exitCode === undefined) {
+        try {
+          child.kill();
+        } catch {}
+        live?.send({ type: "end", id: liveId, code: undefined });
+      }
+
+      live?.close();
+      emulator.dispose();
+    },
+  };
+};

package/src/testing/vitest.ts

@@ -0,0 +1,157 @@
+// Vitest as an embedded engine: the explorer UI drives test discovery and
+// runs through vitest's Node API and streams state changes out through a
+// reporter, instead of shelling out to the CLI or the stock UI.
+export type SerializedTask = {
+  id: string;
+  name: string;
+  type: "suite" | "test";
+  state: string | undefined;
+  duration: number | undefined;
+  errors: string[];
+  tasks: SerializedTask[];
+};
+
+export type TestEngine = {
+  /**
+	The current task tree (files → suites → tests) with results.
+	*/
+  tree: () => SerializedTask[];
+
+  running: () => boolean;
+
+  /**
+	Runs everything under the repo's test dir. Fire-and-forget; progress
+	arrives via `onUpdate`.
+	*/
+  runAll: () => void;
+
+  /**
+	Reruns a single file, suite, or test by task id.
+	*/
+  runTask: (id: string) => void;
+
+  onUpdate: (listener: () => void) => () => void;
+
+  close: () => Promise<void>;
+};
+
+type VitestTask = {
+  id: string;
+  name: string;
+  type: string;
+  filepath?: string;
+  result?: { state?: string; duration?: number; errors?: Array<{ message?: string }> };
+  tasks?: VitestTask[];
+};
+
+const serializeTask = (task: VitestTask): SerializedTask => ({
+  id: task.id,
+  name: task.name,
+  type: task.type === "test" ? "test" : "suite",
+  state: task.result?.state,
+  duration: task.result?.duration,
+  errors: (task.result?.errors ?? [])
+    .map((error) => error.message ?? "")
+    .filter((message) => message.length > 0),
+  tasks: (task.tasks ?? []).map(serializeTask),
+});
+
+/**
+Creates a live Vitest instance scoped to the repo's own `test/` directory.
+Set any environment the test workers should inherit (e.g. `SIGIL_LIVE_URL`
+for live terminal mirroring) before calling this.
+*/
+export const createVitestEngine = async (): Promise<TestEngine> => {
+  const { createVitest } = await import("vitest/node").catch((error) => {
+    throw new Error(
+      'The "vitest" package is required for the test engine. Install it as a dev dependency: pnpm add -D vitest',
+      { cause: error },
+    );
+  });
+
+  const listeners = new Set<() => void>();
+  let running = false;
+  let notifyTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const notify = (): void => {
+    // Reporter hooks fire densely during a run; coalesce.
+    notifyTimer ??= setTimeout(() => {
+      notifyTimer = undefined;
+      for (const listener of listeners) {
+        listener();
+      }
+    }, 80);
+  };
+
+  const reporter = {
+    onTestRunStart: () => {
+      running = true;
+      notify();
+    },
+    onTestRunEnd: () => {
+      running = false;
+      notify();
+    },
+    onTestModuleCollected: notify,
+    onTestModuleEnd: notify,
+    onTestSuiteResult: notify,
+    onTestCaseResult: notify,
+  };
+
+  const ctx = await createVitest("test", { watch: true, reporters: [reporter] });
+
+  const isRelevant = (moduleId: string): boolean =>
+    moduleId.includes("/test/") && !moduleId.includes(".vendor");
+
+  const relevantSpecifications = async () =>
+    (await ctx.globTestSpecifications()).filter((specification) =>
+      isRelevant(specification.moduleId),
+    );
+
+  // Populate the tree up front without running anything.
+  await ctx.collect(["test/"]);
+  notify();
+
+  return {
+    tree: () =>
+      ctx.state
+        .getFiles()
+        .filter((file) => isRelevant((file as VitestTask).filepath ?? ""))
+        .map((file) => serializeTask(file as VitestTask)),
+    running: () => running,
+    runAll: () => {
+      if (running) {
+        return;
+      }
+
+      void relevantSpecifications()
+        .then((specifications) => ctx.runTestSpecifications(specifications, false))
+        .catch(() => {
+          running = false;
+          notify();
+        });
+    },
+    runTask: (id) => {
+      if (running) {
+        return;
+      }
+
+      // Present at runtime (the stock UI uses it) but absent from the
+      // public Vitest type.
+      const runner = ctx as unknown as { rerunTask: (taskId: string) => Promise<unknown> };
+      void Promise.resolve(runner.rerunTask(id)).catch(() => {
+        running = false;
+        notify();
+      });
+    },
+    onUpdate: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    close: async () => {
+      await ctx.close();
+    },
+  };
+};

package/src/transform-adapter.ts

@@ -0,0 +1,14 @@
+import { styledCharsFromTokens, type StyledChar, tokenize } from "#/ansi/tokenize.ts";
+
+export type AnsiTransformer = (text: string, line: number) => string;
+
+/** The single ANSI compatibility boundary used by Transform and external styled strings. */
+export function transformAnsiLine(
+  serializedSubtree: string,
+  lineIndex: number,
+  transformers: readonly AnsiTransformer[],
+): readonly StyledChar[] {
+  let transformed = serializedSubtree;
+  for (const transformer of transformers) transformed = transformer(transformed, lineIndex);
+  return styledCharsFromTokens(tokenize(transformed));
+}

package/src/wrap-text.ts

@@ -6,6 +6,10 @@ import { type Styles } from "#/styles.ts";
 export const wrapTextCache = new QuickLRU<string, string>({ maxSize: 4096 });
 
 export const wrapText = (text: string, maxWidth: number, wrapType: Styles["textWrap"]): string => {
+  if (wrapType === "none") {
+    return text;
+  }
+
   const cacheKey = text + String(maxWidth) + String(wrapType);
   const cachedText = wrapTextCache.get(cacheKey);
 

package/dist/sgr-CMfEpjSk.d.ts

@@ -1,91 +0,0 @@
-//#region src/ansi/sgr.d.ts
-type StylePair = {
-  readonly open: string;
-  readonly close: string;
-};
-declare const modifierCodes: {
-  readonly reset: readonly [0, 0];
-  readonly bold: readonly [1, 22];
-  readonly dim: readonly [2, 22];
-  readonly italic: readonly [3, 23];
-  readonly underline: readonly [4, 24];
-  readonly overline: readonly [53, 55];
-  readonly inverse: readonly [7, 27];
-  readonly hidden: readonly [8, 28];
-  readonly strikethrough: readonly [9, 29];
-};
-declare const colorCodes: {
-  readonly black: readonly [30, 39];
-  readonly red: readonly [31, 39];
-  readonly green: readonly [32, 39];
-  readonly yellow: readonly [33, 39];
-  readonly blue: readonly [34, 39];
-  readonly magenta: readonly [35, 39];
-  readonly cyan: readonly [36, 39];
-  readonly white: readonly [37, 39];
-  readonly blackBright: readonly [90, 39];
-  readonly gray: readonly [90, 39];
-  readonly grey: readonly [90, 39];
-  readonly redBright: readonly [91, 39];
-  readonly greenBright: readonly [92, 39];
-  readonly yellowBright: readonly [93, 39];
-  readonly blueBright: readonly [94, 39];
-  readonly magentaBright: readonly [95, 39];
-  readonly cyanBright: readonly [96, 39];
-  readonly whiteBright: readonly [97, 39];
-};
-declare const bgColorCodes: {
-  readonly bgBlack: readonly [40, 49];
-  readonly bgRed: readonly [41, 49];
-  readonly bgGreen: readonly [42, 49];
-  readonly bgYellow: readonly [43, 49];
-  readonly bgBlue: readonly [44, 49];
-  readonly bgMagenta: readonly [45, 49];
-  readonly bgCyan: readonly [46, 49];
-  readonly bgWhite: readonly [47, 49];
-  readonly bgBlackBright: readonly [100, 49];
-  readonly bgGray: readonly [100, 49];
-  readonly bgGrey: readonly [100, 49];
-  readonly bgRedBright: readonly [101, 49];
-  readonly bgGreenBright: readonly [102, 49];
-  readonly bgYellowBright: readonly [103, 49];
-  readonly bgBlueBright: readonly [104, 49];
-  readonly bgMagentaBright: readonly [105, 49];
-  readonly bgCyanBright: readonly [106, 49];
-  readonly bgWhiteBright: readonly [107, 49];
-};
-type ModifierName = keyof typeof modifierCodes;
-type ForegroundColorName = keyof typeof colorCodes;
-type BackgroundColorName = keyof typeof bgColorCodes;
-type StyleName = ModifierName | ForegroundColorName | BackgroundColorName;
-declare const modifierNames: ModifierName[];
-declare const foregroundColorNames: ForegroundColorName[];
-declare const backgroundColorNames: BackgroundColorName[];
-/**
-Named SGR styles as `{open, close}` escape sequence pairs.
-*/
-declare const styles: Record<StyleName, StylePair>;
-/**
-Raw SGR code numbers: open code → close code.
-*/
-declare const codes: ReadonlyMap<number, number>;
-declare const foreground: {
-  close: string;
-  ansi: (code: number) => string;
-  ansi256: (code: number) => string;
-  ansi16m: (red: number, green: number, blue: number) => string;
-};
-declare const background: {
-  close: string;
-  ansi: (code: number) => string;
-  ansi256: (code: number) => string;
-  ansi16m: (red: number, green: number, blue: number) => string;
-};
-declare const rgbToAnsi256: (red: number, green: number, blue: number) => number;
-declare const hexToRgb: (hex: string) => [number, number, number];
-declare const hexToAnsi256: (hex: string) => number;
-declare const ansi256ToAnsi: (code: number) => number;
-declare const rgbToAnsi: (red: number, green: number, blue: number) => number;
-declare const hexToAnsi: (hex: string) => number;
-//#endregion
-export { rgbToAnsi256 as _, StylePair as a, backgroundColorNames as c, foregroundColorNames as d, hexToAnsi as f, rgbToAnsi as g, modifierNames as h, StyleName as i, codes as l, hexToRgb as m, ForegroundColorName as n, ansi256ToAnsi as o, hexToAnsi256 as p, ModifierName as r, background as s, BackgroundColorName as t, foreground as u, styles as v };