@robota-sdk/agent-ui-terminal 3.0.0-beta.100

package/src/__tests__/terminal-capabilities.test.ts

@@ -0,0 +1,153 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  IME_CURSOR_SETTINGS,
+  TERMINAL_PROFILES,
+  REPRESENTATIVE_IME_PTY_CELLS,
+  cellLabel,
+  expectedImeCursorEnabled,
+} from './helpers/terminal-profiles.js';
+import {
+  isInteractiveColorTerminal,
+  supportsImeCursorPositioning,
+} from '../terminal-capabilities.js';
+
+const ORIG_TTY = process.stdout.isTTY;
+
+function setTty(value: boolean): void {
+  Object.defineProperty(process.stdout, 'isTTY', { value, configurable: true });
+}
+
+describe('isInteractiveColorTerminal', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    Object.defineProperty(process.stdout, 'isTTY', { value: ORIG_TTY, configurable: true });
+  });
+
+  it('NO_COLOR present disables even when empty (the SCREEN-008 regression)', () => {
+    vi.stubEnv('FORCE_COLOR', undefined);
+    setTty(true);
+    vi.stubEnv('NO_COLOR', '');
+    expect(isInteractiveColorTerminal()).toBe(false);
+    vi.stubEnv('NO_COLOR', '1');
+    expect(isInteractiveColorTerminal()).toBe(false);
+  });
+
+  it('honors FORCE_COLOR (0 → off, non-zero → on)', () => {
+    vi.stubEnv('NO_COLOR', undefined);
+    setTty(false);
+    vi.stubEnv('FORCE_COLOR', '0');
+    expect(isInteractiveColorTerminal()).toBe(false);
+    vi.stubEnv('FORCE_COLOR', '1');
+    expect(isInteractiveColorTerminal()).toBe(true);
+  });
+
+  it('falls back to stdout.isTTY when no env override', () => {
+    vi.stubEnv('NO_COLOR', undefined);
+    vi.stubEnv('FORCE_COLOR', undefined);
+    setTty(true);
+    expect(isInteractiveColorTerminal()).toBe(true);
+    setTty(false);
+    expect(isInteractiveColorTerminal()).toBe(false);
+  });
+});
+
+describe('supportsImeCursorPositioning (CLI-062)', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    Object.defineProperty(process.stdout, 'isTTY', { value: ORIG_TTY, configurable: true });
+  });
+
+  it('on for a plain interactive TTY, off for a non-TTY', () => {
+    vi.stubEnv('PRODUCT_IME_CURSOR', undefined);
+    vi.stubEnv('TERM_PROGRAM', undefined);
+    setTty(true);
+    expect(supportsImeCursorPositioning()).toBe(true);
+    setTty(false);
+    expect(supportsImeCursorPositioning()).toBe(false);
+  });
+
+  it('I5: Apple_Terminal is OFF by default (Korean-IME SIGSEGV is an Apple-side bug)', () => {
+    vi.stubEnv('PRODUCT_IME_CURSOR', undefined);
+    setTty(true);
+    vi.stubEnv('TERM_PROGRAM', 'Apple_Terminal');
+    expect(supportsImeCursorPositioning()).toBe(false);
+  });
+
+  it('I5: PRODUCT_IME_CURSOR=1 opts Apple_Terminal in explicitly', () => {
+    setTty(true);
+    vi.stubEnv('TERM_PROGRAM', 'Apple_Terminal');
+    vi.stubEnv('PRODUCT_IME_CURSOR', '1');
+    expect(supportsImeCursorPositioning({ override: true })).toBe(true);
+  });
+
+  it('ignores an ambient Fixture Agent override without a host choice', () => {
+    setTty(true);
+    vi.stubEnv('TERM_PROGRAM', 'Apple_Terminal');
+    vi.stubEnv('PRODUCT_IME_CURSOR', '1');
+    expect(supportsImeCursorPositioning()).toBe(false);
+  });
+
+  it('PRODUCT_IME_CURSOR=0 is a kill switch even on a capable terminal', () => {
+    setTty(true);
+    vi.stubEnv('TERM_PROGRAM', undefined);
+    vi.stubEnv('PRODUCT_IME_CURSOR', '0');
+    expect(supportsImeCursorPositioning({ override: false })).toBe(false);
+  });
+});
+
+/**
+ * CLI-062 terminal matrix — capability half.
+ *
+ * Terminal detection is ASSERTED here, never assumed: every emulator in the matrix is applied as
+ * the environment handshake it really exports (see helpers/terminal-profiles.ts for how each row's
+ * values were obtained), and the gate's verdict is compared against the shared expectation the pty
+ * matrix asserts behaviourally. The macOS rows (Terminal.app, iTerm2) cannot run their emulator on
+ * a non-macOS machine, but their env branch — including Apple_Terminal's default-off I5 branch —
+ * is fully exercised by stubbing the variables those terminals set.
+ */
+describe('CLI-062 terminal matrix — supportsImeCursorPositioning per terminal', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    Object.defineProperty(process.stdout, 'isTTY', { value: ORIG_TTY, configurable: true });
+  });
+
+  for (const profile of TERMINAL_PROFILES) {
+    for (const override of IME_CURSOR_SETTINGS) {
+      const expected = expectedImeCursorEnabled(profile, override);
+      it(`${cellLabel(profile, override)} → ${expected ? 'ENABLED' : 'disabled'}`, () => {
+        setTty(true);
+        // A real terminal exports only its own variables; anything the matrix does not set must
+        // be genuinely absent, or a leaked TERM_PROGRAM would silently decide the verdict.
+        for (const key of ['TERM', 'TERM_PROGRAM', 'TERM_PROGRAM_VERSION', 'COLORTERM']) {
+          vi.stubEnv(key, undefined);
+        }
+        for (const [key, value] of Object.entries(profile.env)) vi.stubEnv(key, value);
+        vi.stubEnv('PRODUCT_IME_CURSOR', override);
+
+        expect(
+          supportsImeCursorPositioning({
+            override: override === '1' ? true : override === '0' ? false : undefined,
+          }),
+        ).toBe(expected);
+      });
+    }
+  }
+
+  it('every matrix row keeps its provenance honest (measured rows name a real capture)', () => {
+    for (const profile of TERMINAL_PROFILES) {
+      expect(profile.note.length, profile.id).toBeGreaterThan(0);
+      if (profile.provenance === 'measured') {
+        expect(profile.note, profile.id).toMatch(/Captured|pty harness/);
+      }
+    }
+  });
+
+  it('keeps the process-spawning PTY tier to four boundary representatives', () => {
+    expect(REPRESENTATIVE_IME_PTY_CELLS).toEqual([
+      { profileId: 'ghostty', override: undefined },
+      { profileId: 'apple-terminal', override: undefined },
+      { profileId: 'apple-terminal', override: '1' },
+      { profileId: 'ghostty', override: '0' },
+    ]);
+  });
+});

package/src/__tests__/terminal-handoff-controller.test.ts

@@ -0,0 +1,173 @@
+/**
+ * TERM-002: unit tests for the TUI terminal-handoff controller LOGIC.
+ *
+ * The real Ink suspend/resume + child-process TTY handoff can only be validated on a live terminal
+ * (manual / User Execution evidence). These tests pin the controller's observable contract: TTY +
+ * mounted-App gating, and the suspend → clear → fn → resume order (including resume-on-throw).
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { TerminalHandoffController } from '../terminal-handoff-controller.js';
+
+const origStdin = Object.getOwnPropertyDescriptor(process.stdin, 'isTTY');
+const origStdout = Object.getOwnPropertyDescriptor(process.stdout, 'isTTY');
+
+function setTty(stdin: boolean, stdout: boolean): void {
+  Object.defineProperty(process.stdin, 'isTTY', { value: stdin, configurable: true });
+  Object.defineProperty(process.stdout, 'isTTY', { value: stdout, configurable: true });
+}
+
+afterEach(() => {
+  if (origStdin) Object.defineProperty(process.stdin, 'isTTY', origStdin);
+  if (origStdout) Object.defineProperty(process.stdout, 'isTTY', origStdout);
+});
+
+describe('TerminalHandoffController', () => {
+  it('canHandoffTerminal requires a TTY on both streams AND registered App hooks', () => {
+    const c = new TerminalHandoffController();
+    setTty(true, true);
+    expect(c.canHandoffTerminal).toBe(false); // no hooks yet
+
+    const unregister = c.registerSuspendHooks({ suspend: async () => {}, resume: () => {} });
+    expect(c.canHandoffTerminal).toBe(true);
+
+    setTty(false, true);
+    expect(c.canHandoffTerminal).toBe(false); // stdin not a TTY
+
+    setTty(true, true);
+    unregister();
+    expect(c.canHandoffTerminal).toBe(false); // App unmounted
+  });
+
+  it('runs suspend → clear → fn → resume in order', async () => {
+    const order: string[] = [];
+    const c = new TerminalHandoffController();
+    setTty(true, true);
+    c.registerSuspendHooks({
+      suspend: async () => {
+        order.push('suspend');
+      },
+      resume: () => order.push('resume'),
+    });
+    c.setInkInstance({ clear: () => order.push('clear') });
+
+    const result = await c.runWithTerminal(async () => {
+      order.push('child');
+      return 7;
+    });
+
+    expect(result).toBe(7);
+    expect(order).toEqual(['suspend', 'clear', 'child', 'resume']);
+  });
+
+  it('resumes even when the child fn throws', async () => {
+    const order: string[] = [];
+    const c = new TerminalHandoffController();
+    setTty(true, true);
+    c.registerSuspendHooks({
+      suspend: async () => void order.push('suspend'),
+      resume: () => order.push('resume'),
+    });
+
+    await expect(
+      c.runWithTerminal(async () => {
+        throw new Error('child failed');
+      }),
+    ).rejects.toThrow('child failed');
+    expect(order).toEqual(['suspend', 'resume']);
+  });
+
+  it('rejects (does not run fn) when no interactive TTY is available', async () => {
+    const c = new TerminalHandoffController();
+    setTty(false, false);
+    c.registerSuspendHooks({ suspend: async () => {}, resume: () => {} });
+    const fn = vi.fn();
+    await expect(c.runWithTerminal(fn as never)).rejects.toThrow(/unavailable/);
+    expect(fn).not.toHaveBeenCalled();
+  });
+});
+
+/** SCREEN-1992 TC-06: the negotiated terminal modes bracket the handoff. */
+describe('TerminalHandoffController terminal-mode hooks', () => {
+  it('runs preSuspend after suspend and postResume after resume, even when the child throws', async () => {
+    const order: string[] = [];
+    const c = new TerminalHandoffController();
+    setTty(true, true);
+    c.registerSuspendHooks({
+      suspend: async () => {
+        order.push('suspend');
+      },
+      resume: () => order.push('resume'),
+    });
+    c.setInkInstance({ clear: () => order.push('clear') });
+    c.setTerminalModeHooks({
+      preSuspend: () => {
+        order.push('mode-off');
+      },
+      postResume: () => {
+        order.push('mode-on');
+      },
+    });
+
+    await expect(
+      c.runWithTerminal(async () => {
+        order.push('child');
+        throw new Error('child failed');
+      }),
+    ).rejects.toThrow('child failed');
+    expect(order).toEqual(['suspend', 'mode-off', 'clear', 'child', 'resume', 'mode-on']);
+
+    c.setTerminalModeHooks(undefined);
+    order.length = 0;
+    await c.runWithTerminal(async () => order.push('child'));
+    expect(order).toEqual(['suspend', 'clear', 'child', 'resume']);
+  });
+
+  /**
+   * SCREEN-2670: `preSuspend` may be async — it drains the parked screen-reader output — and the
+   * screen is cleared only after it settles. Without the await, `clear` and the child would run
+   * while the drain was still pending, and parked frames would land on top of the child's output.
+   */
+  it('awaits an async preSuspend before clearing the screen and starting the child', async () => {
+    const order: string[] = [];
+    const c = new TerminalHandoffController();
+    setTty(true, true);
+    c.registerSuspendHooks({
+      suspend: async () => {
+        order.push('suspend');
+      },
+      resume: () => order.push('resume'),
+    });
+    c.setInkInstance({ clear: () => order.push('clear') });
+    let finishDrain: () => void = () => {};
+    const drained = new Promise<void>((resolve) => {
+      finishDrain = resolve;
+    });
+    c.setTerminalModeHooks({
+      preSuspend: async () => {
+        order.push('drain-start');
+        await drained;
+        order.push('drain-end');
+      },
+      postResume: () => {
+        order.push('mode-on');
+      },
+    });
+
+    const run = c.runWithTerminal(async () => order.push('child'));
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    // The drain has not settled: nothing past it may have run yet.
+    expect(order).toEqual(['suspend', 'drain-start']);
+    finishDrain();
+    await run;
+    expect(order).toEqual([
+      'suspend',
+      'drain-start',
+      'drain-end',
+      'clear',
+      'child',
+      'resume',
+      'mode-on',
+    ]);
+  });
+});

package/src/__tests__/terminal-handoff-pty-e2e.test.ts

@@ -0,0 +1,77 @@
+/**
+ * TEST-007 / TERM-002: real-terminal handoff, end-to-end through a PTY.
+ *
+ * Drives `fixtures/terminal-handoff-driver.tsx` (a real Ink app using the real
+ * `TerminalHandoffController` + `useTerminalHandoffSuspension`) inside a pseudo-terminal. This is the
+ * automated replacement for the former manual-only smoke: it proves on a real TTY that
+ *
+ *  1. the handoff is available (`canHandoffTerminal === true` under a PTY),
+ *  2. Ink releases raw mode so the inherited child receives the driver's keystrokes, and
+ *  3. `runWithTerminal` RETURNS after the child exits and the TUI resumes (regression guard for the
+ *     event-loop-starvation hang fixed in the controller — without the stdin release the child's
+ *     exit is never observed and the TUI hangs forever).
+ */
+import { mkdtempSync, readFileSync, rmSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { createPtyEnv } from './pty/isolated-home.js';
+import { spawnPtyFixture } from './pty/spawn-pty.js';
+
+import type { IPtyRunSession } from './pty/spawn-pty.js';
+
+const FIXTURE = fileURLToPath(new URL('./fixtures/terminal-handoff-driver.tsx', import.meta.url));
+const PACKAGE_DIR = fileURLToPath(new URL('../..', import.meta.url));
+const TEST_TIMEOUT_MS = 30_000;
+
+const tempDirs: string[] = [];
+const sessions: IPtyRunSession[] = [];
+
+afterEach(() => {
+  for (const session of sessions.splice(0)) session.dispose();
+  for (const dir of tempDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+describe('terminal handoff PTY E2E', () => {
+  it(
+    'hands the real terminal to a child, receives its input, and resumes the TUI',
+    async () => {
+      const dir = realpathSync(mkdtempSync(join(tmpdir(), 'agent-test-handoff-pty-')));
+      tempDirs.push(dir);
+      const outputPath = join(dir, 'result.json');
+
+      const session = spawnPtyFixture(FIXTURE, {
+        argv: [outputPath],
+        cwd: PACKAGE_DIR,
+        // HARNESS-025: isolated HOME — the child must not read the developer's `~`.
+        env: createPtyEnv(),
+      });
+      sessions.push(session);
+
+      await session.waitFor('READY canHandoff=true', 10_000);
+      await session.waitFor('HANDOFF_STARTED', 10_000);
+      // Let the child reach its read() before sending the line.
+      await new Promise((resolve) => setTimeout(resolve, 300));
+      await session.sendKeys('hello-from-pty', 10);
+      session.write('\r');
+
+      // The crux: the handoff must RETURN and the TUI must resume (no hang).
+      await session.waitFor('RESUMED exit=0', 10_000);
+      expect(await session.expectExit(5_000)).toBe(0);
+
+      const snapshot = session.snapshot();
+      expect(snapshot).toContain('CHILD_GOT:[hello-from-pty]');
+
+      const result = JSON.parse(readFileSync(outputPath, 'utf8')) as {
+        canHandoff: boolean;
+        exitCode: number;
+        returned: boolean;
+      };
+      expect(result).toEqual({ canHandoff: true, exitCode: 0, returned: true });
+    },
+    TEST_TIMEOUT_MS,
+  );
+});

package/src/__tests__/text-prompt-flow.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest';
+import {
+  applyTextPromptInput,
+  createTextPromptFlowState,
+  getTextPromptInputAction,
+  type ITextPromptFlowState,
+} from '../flows/text-prompt-flow.js';
+
+describe('text prompt flow', () => {
+  it('Given typed text When submit is applied Then it emits trimmed submit value', () => {
+    const typed = applyTextPromptInput(
+      createTextPromptFlowState(),
+      { type: 'insert', value: '  hello  ' },
+      { allowEmpty: false },
+    ).state;
+
+    const result = applyTextPromptInput(typed, { type: 'submit' }, { allowEmpty: false });
+
+    expect(result.effect).toEqual({ type: 'submit', value: 'hello' });
+    expect(result.state.resolved).toBe(true);
+  });
+
+  it('Given empty required text When submit is applied Then validation error stays in state', () => {
+    const result = applyTextPromptInput(
+      createTextPromptFlowState(),
+      { type: 'submit' },
+      { allowEmpty: false, validate: (value) => (value.length === 0 ? 'Required' : undefined) },
+    );
+
+    expect(result.effect).toEqual({ type: 'none' });
+    expect(result.state.error).toBe('Required');
+    expect(result.state.resolved).toBe(false);
+  });
+
+  it('Given defaultable empty text When submit is applied Then empty submit is allowed', () => {
+    const result = applyTextPromptInput(
+      createTextPromptFlowState(),
+      { type: 'submit' },
+      { allowEmpty: true },
+    );
+
+    expect(result.effect).toEqual({ type: 'submit', value: '' });
+  });
+
+  it('Given text with an error When delete or insert is applied Then the error is cleared', () => {
+    const state: ITextPromptFlowState = { value: 'ab', error: 'Invalid', resolved: false };
+
+    const deleted = applyTextPromptInput(state, { type: 'delete' }, { allowEmpty: false });
+    const inserted = applyTextPromptInput(
+      state,
+      { type: 'insert', value: 'c' },
+      { allowEmpty: false },
+    );
+
+    expect(deleted.state).toMatchObject({ value: 'a', error: undefined });
+    expect(inserted.state).toMatchObject({ value: 'abc', error: undefined });
+  });
+
+  it('Given prompt is already resolved When input is applied Then no second effect is emitted', () => {
+    const state: ITextPromptFlowState = { value: 'done', resolved: true };
+
+    const result = applyTextPromptInput(state, { type: 'submit' }, { allowEmpty: false });
+
+    expect(result.effect).toEqual({ type: 'none' });
+    expect(result.state).toBe(state);
+  });
+
+  it('Given raw Ink key info When mapped Then terminal details become prompt actions', () => {
+    expect(getTextPromptInputAction('', { escape: true })).toEqual({ type: 'cancel' });
+    expect(getTextPromptInputAction('', { return: true })).toEqual({ type: 'submit' });
+    expect(getTextPromptInputAction('', { backspace: true })).toEqual({ type: 'delete' });
+    expect(getTextPromptInputAction('x', { ctrl: false, meta: false })).toEqual({
+      type: 'insert',
+      value: 'x',
+    });
+  });
+});