ptywright 0.1.0 → 0.2.0

package/src/pty/bun_pty_adapter.ts

@@ -1,34 +0,0 @@
-import { spawn } from "bun-pty";
-import type { IPty, IPtyForkOptions } from "bun-pty";
-
-import type { PtyAdapter, PtyProcess, PtySpawnOptions } from "./pty_adapter";
-
-function toForkOptions(options: PtySpawnOptions): IPtyForkOptions {
-  return {
-    name: options.name,
-    cols: options.cols,
-    rows: options.rows,
-    cwd: options.cwd,
-    env: options.env,
-  };
-}
-
-function toPtyProcess(pty: IPty): PtyProcess {
-  return {
-    pid: pty.pid,
-    cols: pty.cols,
-    rows: pty.rows,
-    write: (data) => pty.write(data),
-    resize: (cols, rows) => pty.resize(cols, rows),
-    kill: (signal) => pty.kill(signal),
-    onData: (listener) => pty.onData(listener),
-    onExit: (listener) => pty.onExit(listener),
-  };
-}
-
-export class BunPtyAdapter implements PtyAdapter {
-  spawn(command: string, args: string[], options: PtySpawnOptions): PtyProcess {
-    const pty = spawn(command, args, toForkOptions(options));
-    return toPtyProcess(pty);
-  }
-}

package/src/pty/bun_terminal_adapter.ts

@@ -1,149 +0,0 @@
-import type { Terminal, TerminalOptions } from "bun";
-
-import type {
-  Disposable,
-  PtyAdapter,
-  PtyExitEvent,
-  PtyProcess,
-  PtySpawnOptions,
-} from "./pty_adapter";
-
-type Listener<T> = (arg: T) => void;
-
-function createDisposable<T>(set: Set<Listener<T>>, listener: Listener<T>): Disposable {
-  return {
-    dispose: () => {
-      set.delete(listener);
-    },
-  };
-}
-
-export class BunTerminalAdapter implements PtyAdapter {
-  spawn(command: string, args: string[], options: PtySpawnOptions): PtyProcess {
-    if (process.platform === "win32") {
-      throw new Error("Bun.Terminal PTY is only available on POSIX systems (Linux/macOS)");
-    }
-
-    let cols = options.cols;
-    let rows = options.rows;
-
-    const decoder = new TextDecoder();
-    const dataListeners = new Set<Listener<string>>();
-    const exitListeners = new Set<Listener<PtyExitEvent>>();
-
-    const pendingData: string[] = [];
-    let pendingExit: PtyExitEvent | null = null;
-
-    const dispatchData = (chunk: string): void => {
-      if (!chunk) return;
-      if (dataListeners.size === 0) {
-        pendingData.push(chunk);
-        if (pendingData.length > 2000) {
-          pendingData.splice(0, pendingData.length - 2000);
-        }
-        return;
-      }
-      for (const listener of dataListeners) listener(chunk);
-    };
-
-    const flushPendingDataTo = (listener: Listener<string>): void => {
-      if (pendingData.length === 0) return;
-      for (const chunk of pendingData) listener(chunk);
-    };
-
-    const dispatchExit = (event: PtyExitEvent): void => {
-      pendingExit = event;
-      for (const listener of exitListeners) listener(event);
-    };
-
-    const flushExitTo = (listener: Listener<PtyExitEvent>): void => {
-      if (!pendingExit) return;
-      listener(pendingExit);
-    };
-
-    const terminalOptions: TerminalOptions = {
-      cols,
-      rows,
-      name: options.name,
-      data: (_term, data) => {
-        const text = decoder.decode(data, { stream: true });
-        dispatchData(text);
-      },
-      exit: () => {
-        const tail = decoder.decode();
-        dispatchData(tail);
-      },
-    };
-
-    let terminal: Terminal | undefined;
-    let killed = false;
-
-    const proc = Bun.spawn([command, ...args], {
-      cwd: options.cwd,
-      env: options.env,
-      terminal: terminalOptions,
-      onExit(subprocess, exitCode, _signalCode) {
-        const tail = decoder.decode();
-        dispatchData(tail);
-
-        const signal = subprocess.signalCode ?? undefined;
-        dispatchExit({
-          exitCode: exitCode ?? (killed ? -1 : 0),
-          signal,
-        });
-      },
-    });
-
-    terminal = proc.terminal;
-    if (!terminal) {
-      throw new Error("expected Bun.spawn(..., { terminal }) to attach a PTY terminal");
-    }
-
-    // Ensure input is passed through without CR->LF translation (needed for apps that
-    // distinguish Enter (CR) from Ctrl+J (LF), e.g. Codex CLI).
-    // Note: Bun.Terminal.setRawMode only affects PTY line discipline, not the child process.
-    terminal.setRawMode(true);
-
-    return {
-      pid: proc.pid,
-      get cols() {
-        return cols;
-      },
-      get rows() {
-        return rows;
-      },
-      write: (data) => {
-        terminal?.write(data);
-      },
-      resize: (nextCols, nextRows) => {
-        cols = nextCols;
-        rows = nextRows;
-        terminal?.resize(nextCols, nextRows);
-      },
-      kill: (signal) => {
-        killed = true;
-        if (signal) {
-          proc.kill(signal as unknown as NodeJS.Signals);
-        } else {
-          proc.kill();
-        }
-        terminal?.close();
-      },
-      onData: (listener) => {
-        dataListeners.add(listener);
-        flushPendingDataTo(listener);
-        if (dataListeners.size === 1) {
-          queueMicrotask(() => {
-            pendingData.length = 0;
-          });
-        }
-        return createDisposable(dataListeners, listener);
-      },
-      onExit: (listener) => {
-        exitListeners.add(listener);
-        flushExitTo(listener);
-        return createDisposable(exitListeners, listener);
-      },
-    };
-  }
-}

package/src/pty/pty_adapter.ts

@@ -1,31 +0,0 @@
-export type PtySpawnOptions = {
-  cols: number;
-  rows: number;
-  cwd: string;
-  env: Record<string, string>;
-  name: string;
-};
-
-export type PtyExitEvent = {
-  exitCode: number;
-  signal?: number | string;
-};
-
-export type Disposable = {
-  dispose(): void;
-};
-
-export type PtyProcess = {
-  readonly pid: number;
-  readonly cols: number;
-  readonly rows: number;
-  write(data: string): void;
-  resize(cols: number, rows: number): void;
-  kill(signal?: string): void;
-  onData(listener: (data: string) => void): Disposable;
-  onExit(listener: (event: PtyExitEvent) => void): Disposable;
-};
-
-export type PtyAdapter = {
-  spawn(command: string, args: string[], options: PtySpawnOptions): PtyProcess;
-};

package/src/script/dsl.ts

@@ -1,188 +0,0 @@
-import { scriptSchema } from "./schema";
-import type { Script, ScriptStep } from "./schema";
-
-type SnapshotKey = string;
-
-type SnapshotRef<K extends SnapshotKey> = K | "last";
-
-type StepOf<T extends ScriptStep["type"]> = Extract<ScriptStep, { type: T }>;
-
-type SnapshotStep = StepOf<"snapshot">;
-type ExpectStep = StepOf<"expect">;
-type ExpectGoldenStep = StepOf<"expectGolden">;
-type ExpectMetaStep = StepOf<"expectMeta">;
-type WaitForExitStep = StepOf<"waitForExit">;
-type SendMouseStep = StepOf<"sendMouse">;
-
-type CustomStepMap = Record<string, unknown>;
-
-export class ScriptBuilder<K extends SnapshotKey = never, Steps extends CustomStepMap = {}> {
-  private readonly script: Script;
-
-  constructor(init: {
-    name?: string;
-    artifactsDir?: string;
-    launch: Script["launch"];
-    trace?: Script["trace"];
-  }) {
-    this.script = {
-      name: init.name,
-      artifactsDir: init.artifactsDir,
-      launch: init.launch,
-      trace: init.trace,
-      steps: [],
-    };
-  }
-
-  getName(): string | undefined {
-    return this.script.name;
-  }
-
-  getLaunch(): Script["launch"] {
-    return this.script.launch;
-  }
-
-  step(step: ScriptStep): this {
-    this.script.steps.push(step);
-    return this;
-  }
-
-  use<NextK extends SnapshotKey, NextSteps extends CustomStepMap = Steps>(
-    fn: (s: ScriptBuilder<K, Steps>) => ScriptBuilder<NextK, NextSteps>,
-  ): ScriptBuilder<NextK, NextSteps> {
-    return fn(this);
-  }
-
-  custom<Name extends string>(
-    name: Name,
-    ...args: Name extends keyof Steps & string
-      ? undefined extends Steps[Name]
-        ? [payload?: Steps[Name]]
-        : [payload: Steps[Name]]
-      : [payload?: unknown]
-  ): this {
-    const payload = args[0] as unknown;
-    if (payload === undefined) {
-      return this.step({ type: "custom", name });
-    }
-    return this.step({ type: "custom", name, payload });
-  }
-
-  sendText(text: string, options?: { enter?: boolean }): this {
-    return this.step({ type: "sendText", text, enter: options?.enter });
-  }
-
-  pasteText(text: string, options?: { bracketed?: boolean }): this {
-    const bracketed = options?.bracketed ?? false;
-    const payload = bracketed ? `\x1b[200~${text}\x1b[201~` : text;
-    return this.sendText(payload);
-  }
-
-  pressKey(key: string): this {
-    return this.step({ type: "pressKey", key });
-  }
-
-  sendMouse(step: Omit<SendMouseStep, "type">): this {
-    return this.step({ type: "sendMouse", ...step });
-  }
-
-  resize(cols: number, rows: number): this {
-    return this.step({ type: "resize", cols, rows });
-  }
-
-  mark(label?: string): this {
-    return this.step({ type: "mark", label });
-  }
-
-  sleep(ms: number): this {
-    return this.step({ type: "sleep", ms });
-  }
-
-  waitForText(step: Omit<StepOf<"waitForText">, "type">): this {
-    return this.step({ type: "waitForText", ...step });
-  }
-
-  waitForStableScreen(step: Omit<StepOf<"waitForStableScreen">, "type"> = {}): this {
-    return this.step({ type: "waitForStableScreen", ...step });
-  }
-
-  waitForExit(step: Omit<WaitForExitStep, "type"> = {}): this {
-    return this.step({ type: "waitForExit", ...step });
-  }
-
-  expectMeta(step: Omit<ExpectMetaStep, "type">): this {
-    return this.step({ type: "expectMeta", ...step });
-  }
-
-  snapshot<K2 extends string>(
-    step: Omit<SnapshotStep, "type"> & { saveAs: K2 },
-  ): ScriptBuilder<K | K2, Steps>;
-  snapshot(step: Omit<SnapshotStep, "type">): ScriptBuilder<K, Steps>;
-  snapshot(step: Omit<SnapshotStep, "type">): ScriptBuilder<any, Steps> {
-    this.step({ type: "snapshot", ...step });
-    return this as any;
-  }
-
-  snapshotText<K2 extends string>(
-    step: Omit<SnapshotStep, "type" | "kind"> & { saveAs: K2 },
-  ): ScriptBuilder<K | K2, Steps>;
-  snapshotText(step?: Omit<SnapshotStep, "type" | "kind">): ScriptBuilder<K, Steps>;
-  snapshotText(step: Omit<SnapshotStep, "type" | "kind"> = {}): ScriptBuilder<any, Steps> {
-    return this.snapshot({ ...step, kind: "text" } as Omit<SnapshotStep, "type">);
-  }
-
-  snapshotView<K2 extends string>(
-    step: Omit<SnapshotStep, "type" | "kind"> & { saveAs: K2 },
-  ): ScriptBuilder<K | K2, Steps>;
-  snapshotView(step?: Omit<SnapshotStep, "type" | "kind">): ScriptBuilder<K, Steps>;
-  snapshotView(step: Omit<SnapshotStep, "type" | "kind"> = {}): ScriptBuilder<any, Steps> {
-    return this.snapshot({ ...step, kind: "view" } as Omit<SnapshotStep, "type">);
-  }
-
-  snapshotAnsi<K2 extends string>(
-    step: Omit<SnapshotStep, "type" | "kind"> & { saveAs: K2 },
-  ): ScriptBuilder<K | K2, Steps>;
-  snapshotAnsi(step?: Omit<SnapshotStep, "type" | "kind">): ScriptBuilder<K, Steps>;
-  snapshotAnsi(step: Omit<SnapshotStep, "type" | "kind"> = {}): ScriptBuilder<any, Steps> {
-    return this.snapshot({ ...step, kind: "ansi" } as Omit<SnapshotStep, "type">);
-  }
-
-  snapshotViewAnsi<K2 extends string>(
-    step: Omit<SnapshotStep, "type" | "kind"> & { saveAs: K2 },
-  ): ScriptBuilder<K | K2, Steps>;
-  snapshotViewAnsi(step?: Omit<SnapshotStep, "type" | "kind">): ScriptBuilder<K, Steps>;
-  snapshotViewAnsi(step: Omit<SnapshotStep, "type" | "kind"> = {}): ScriptBuilder<any, Steps> {
-    return this.snapshot({ ...step, kind: "view_ansi" } as Omit<SnapshotStep, "type">);
-  }
-
-  snapshotGrid<K2 extends string>(
-    step: Omit<SnapshotStep, "type" | "kind"> & { saveAs: K2 },
-  ): ScriptBuilder<K | K2, Steps>;
-  snapshotGrid(step?: Omit<SnapshotStep, "type" | "kind">): ScriptBuilder<K, Steps>;
-  snapshotGrid(step: Omit<SnapshotStep, "type" | "kind"> = {}): ScriptBuilder<any, Steps> {
-    return this.snapshot({ ...step, kind: "grid" } as Omit<SnapshotStep, "type">);
-  }
-
-  expect(step: Omit<ExpectStep, "type" | "from"> & { from?: SnapshotRef<K> }): this {
-    return this.step({ type: "expect", ...(step as Omit<ExpectStep, "type">) });
-  }
-
-  expectGolden(step: Omit<ExpectGoldenStep, "type" | "from"> & { from?: SnapshotRef<K> }): this {
-    return this.step({ type: "expectGolden", ...(step as Omit<ExpectGoldenStep, "type">) });
-  }
-
-  build(): Script {
-    return scriptSchema.parse(this.script) as Script;
-  }
-}
-
-export function defineScript<K extends SnapshotKey, Steps extends CustomStepMap>(
-  build: () => ScriptBuilder<K, Steps> | Script,
-): Script {
-  const value = build();
-  const script =
-    typeof value === "object" && value && "build" in value
-      ? (value as ScriptBuilder<any, any>).build()
-      : value;
-  return scriptSchema.parse(script) as Script;
-}

package/src/script/module.ts

@@ -1,43 +0,0 @@
-import { resolve } from "node:path";
-import { pathToFileURL } from "node:url";
-
-import type { CustomStepHandler } from "./runner";
-
-function extractStepHandlers(
-  mod: Record<string, unknown>,
-): Record<string, CustomStepHandler> | undefined {
-  return (mod.steps ?? mod.customSteps ?? mod.stepHandlers) as
-    | Record<string, CustomStepHandler>
-    | undefined;
-}
-
-export async function loadScriptModule(modulePath: string): Promise<{
-  script: unknown;
-  steps?: Record<string, CustomStepHandler>;
-}> {
-  const absPath = resolve(process.cwd(), modulePath);
-  const mod = (await import(pathToFileURL(absPath).href)) as Record<string, unknown>;
-
-  const script = mod.default ?? mod.script;
-  if (!script) {
-    throw new Error(`script module must export default or 'script': ${modulePath}`);
-  }
-
-  const steps = extractStepHandlers(mod);
-
-  return { script, steps };
-}
-
-export async function loadStepHandlersModule(modulePath: string): Promise<{
-  steps: Record<string, CustomStepHandler>;
-}> {
-  const absPath = resolve(process.cwd(), modulePath);
-  const mod = (await import(pathToFileURL(absPath).href)) as Record<string, unknown>;
-  const steps = extractStepHandlers(mod);
-  if (!steps) {
-    throw new Error(
-      `steps module must export 'steps' (or customSteps/stepHandlers): ${modulePath}`,
-    );
-  }
-  return { steps };
-}

package/src/script/path.ts

@@ -1,151 +0,0 @@
-import { basename, extname, isAbsolute, resolve } from "node:path";
-
-import { loadScriptModule, loadStepHandlersModule } from "./module";
-import { runScript } from "./runner";
-import type { CustomStepHandler } from "./runner";
-import { scriptSchema } from "./schema";
-import type { Script } from "./schema";
-
-export type RunScriptPathOptions = {
-  artifactsDir?: string;
-  updateGoldens?: boolean;
-  stepsPath?: string;
-};
-
-export type RunScriptPathSuccess = {
-  ok: true;
-  scriptName: string;
-  artifactsDir: string;
-  castPath?: string;
-  reportPath?: string;
-};
-
-export type RunScriptPathFailure = {
-  ok: false;
-  error: string;
-  scriptName?: string;
-  artifactsDir?: string;
-  castPath?: string;
-  reportPath?: string;
-  failureArtifacts?: {
-    lastTextPath: string;
-    lastViewPath: string;
-    stepPath: string;
-    errorPath: string;
-  };
-};
-
-export type RunScriptPathResult = RunScriptPathSuccess | RunScriptPathFailure;
-
-export async function runScriptPath(
-  scriptPath: string,
-  options?: RunScriptPathOptions,
-): Promise<RunScriptPathResult> {
-  let scriptName: string | undefined;
-  let artifactsDir: string | undefined;
-  let castPath: string | undefined;
-  let reportPath: string | undefined;
-
-  try {
-    const ext = extname(scriptPath).toLowerCase();
-    const baseName = basename(scriptPath, extname(scriptPath));
-
-    const extraSteps = options?.stepsPath
-      ? (await loadStepHandlersModule(options.stepsPath)).steps
-      : undefined;
-
-    const loaded = await loadScriptInput(scriptPath, ext);
-    const stepsFromModule = loaded.steps;
-    const mergedSteps =
-      stepsFromModule && extraSteps
-        ? { ...stepsFromModule, ...extraSteps }
-        : (stepsFromModule ?? extraSteps);
-
-    const built = loaded.script;
-    const withName =
-      built && typeof built === "object" && !Array.isArray(built) && !("name" in built)
-        ? { ...built, name: baseName }
-        : built;
-
-    const parsed = scriptSchema.parse(withName) as Script;
-    scriptName = parsed.name ?? baseName;
-    artifactsDir = resolveArtifactsDir(parsed, scriptName, options?.artifactsDir);
-
-    const trace = parsed.trace ?? {};
-    const saveCast = trace.saveCast ?? true;
-    const saveReport = trace.saveReport ?? true;
-    castPath = saveCast
-      ? resolveArtifactPath(artifactsDir, trace.castPath ?? `${scriptName}.cast`)
-      : undefined;
-    reportPath = saveReport
-      ? resolveArtifactPath(artifactsDir, trace.reportPath ?? `${scriptName}.report.html`)
-      : undefined;
-
-    try {
-      await runScript(parsed, {
-        artifactsDir,
-        updateGoldens: options?.updateGoldens,
-        steps: mergedSteps,
-      });
-
-      return { ok: true, scriptName, artifactsDir, castPath, reportPath };
-    } catch (error) {
-      return {
-        ok: false,
-        error: (error as Error).message,
-        scriptName,
-        artifactsDir,
-        castPath,
-        reportPath,
-        failureArtifacts: {
-          lastTextPath: resolveArtifactPath(artifactsDir, "failure.last.txt"),
-          lastViewPath: resolveArtifactPath(artifactsDir, "failure.last.view.txt"),
-          stepPath: resolveArtifactPath(artifactsDir, "failure.step.json"),
-          errorPath: resolveArtifactPath(artifactsDir, "failure.error.txt"),
-        },
-      };
-    }
-  } catch (error) {
-    return {
-      ok: false,
-      error: (error as Error).message,
-      scriptName,
-      artifactsDir,
-      castPath,
-      reportPath,
-    };
-  }
-}
-
-async function loadScriptInput(
-  scriptPath: string,
-  ext: string,
-): Promise<{ script: unknown; steps?: Record<string, CustomStepHandler> }> {
-  if (ext === ".json") {
-    const raw = await Bun.file(scriptPath).text();
-    return { script: JSON.parse(raw) as unknown };
-  }
-
-  const loaded = await loadScriptModule(scriptPath);
-  const script = loaded.script;
-  if (
-    script &&
-    typeof script === "object" &&
-    "build" in script &&
-    typeof (script as { build?: unknown }).build === "function"
-  ) {
-    return { script: (script as { build: () => unknown }).build(), steps: loaded.steps };
-  }
-  return { script, steps: loaded.steps };
-}
-
-function resolveArtifactsDir(script: Script, scriptName: string, override?: string): string {
-  if (override?.trim()) return resolve(override.trim());
-  if (script.artifactsDir?.trim()) return resolve(script.artifactsDir.trim());
-  return resolve(".tmp", "runs", scriptName);
-}
-
-function resolveArtifactPath(artifactsDir: string, path: string): string {
-  if (isAbsolute(path)) return path;
-  return resolve(artifactsDir, path);
-}

package/src/script/run.ts

@@ -1,108 +0,0 @@
-import { runScriptPath } from "./path";
-
-function parseArgs(argv: string[]): {
-  scriptPath: string;
-  artifactsDir?: string;
-  stepsPath?: string;
-  updateGoldens: boolean;
-} {
-  const out: {
-    scriptPath?: string;
-    artifactsDir?: string;
-    stepsPath?: string;
-    updateGoldens: boolean;
-  } = {
-    updateGoldens: false,
-  };
-
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    const next = argv[i + 1];
-
-    if (!out.scriptPath && arg && !arg.startsWith("-")) {
-      out.scriptPath = arg;
-      continue;
-    }
-
-    if (arg === "--artifacts-dir" && next) {
-      out.artifactsDir = next;
-      i += 1;
-      continue;
-    }
-
-    if (arg === "--steps" && next) {
-      out.stepsPath = next;
-      i += 1;
-      continue;
-    }
-
-    if (arg === "--update-goldens") {
-      out.updateGoldens = true;
-      continue;
-    }
-
-    throw new Error(`unknown arg: ${arg ?? ""}`);
-  }
-
-  if (!out.scriptPath) {
-    throw new Error(
-      "Usage: bun run src/script/run.ts <file> [--artifacts-dir <dir>] [--steps <module.ts>] [--update-goldens]",
-    );
-  }
-
-  return out as {
-    scriptPath: string;
-    artifactsDir?: string;
-    stepsPath?: string;
-    updateGoldens: boolean;
-  };
-}
-
-function logLines(lines: Array<string | null | undefined>, stderr: boolean): void {
-  const filtered = lines.map((l) => l?.trim()).filter(Boolean) as string[];
-  for (const line of filtered) {
-    // eslint-disable-next-line no-console
-    (stderr ? console.error : console.log)(line);
-  }
-}
-
-if (import.meta.main) {
-  try {
-    const args = parseArgs(process.argv.slice(2));
-    const result = await runScriptPath(args.scriptPath, {
-      artifactsDir: args.artifactsDir,
-      updateGoldens: args.updateGoldens,
-      stepsPath: args.stepsPath,
-    });
-
-    if (!result.ok) {
-      logLines(
-        [
-          result.error,
-          result.artifactsDir ? `artifacts=${result.artifactsDir}` : null,
-          result.reportPath ? `report=${result.reportPath}` : null,
-          result.castPath ? `cast=${result.castPath}` : null,
-          result.failureArtifacts?.lastViewPath
-            ? `last=${result.failureArtifacts.lastViewPath}`
-            : null,
-          result.failureArtifacts?.errorPath ? `error=${result.failureArtifacts.errorPath}` : null,
-        ],
-        true,
-      );
-      process.exitCode = 1;
-    } else {
-      logLines(
-        [
-          `ok artifacts=${result.artifactsDir}`,
-          result.reportPath ? `report=${result.reportPath}` : null,
-          result.castPath ? `cast=${result.castPath}` : null,
-        ],
-        false,
-      );
-    }
-  } catch (error) {
-    // eslint-disable-next-line no-console
-    console.error((error as Error).message);
-    process.exitCode = 1;
-  }
-}