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

package/src/__tests__/screen-reader-menus.test.tsx

@@ -0,0 +1,200 @@
+/**
+ * CLI-2004 TC-06 / TC-07 — arrow-key menus become numbered lists with a typed answer.
+ *
+ * Position is the thing a reader cannot get: the `> ` cursor and the accent colour say which row is
+ * selected, and neither survives being read aloud. A spoken number does.
+ */
+
+import { render } from 'ink-testing-library';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import ConfirmPrompt, { CONFIRM_PROMPT_TYPED_LITERAL } from '../ConfirmPrompt.js';
+import MenuSelect from '../MenuSelect.js';
+import { NUMBERED_LIST_CANCEL_SUFFIX } from '../numbered-list.js';
+import PermissionPrompt from '../PermissionPrompt.js';
+import { ScreenReaderProvider } from '../screen-reader-context.js';
+
+import type { IPendingPermissionRequest } from '../types.js';
+
+/** Ink needs a tick to deliver stdin and flush a frame. */
+async function tick(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 20));
+}
+
+function renderInMode(element: React.ReactElement): ReturnType<typeof render> {
+  return render(<ScreenReaderProvider enabled={true}>{element}</ScreenReaderProvider>);
+}
+
+const ITEMS = [
+  { label: 'First option', value: 'a' },
+  { label: 'Second option', value: 'b' },
+  { label: 'Third option', value: 'c' },
+];
+
+describe('TC-06: MenuSelect as a numbered list', () => {
+  it('renders `1. `, `2. `, `3. ` rows and the authored prompt literal', async () => {
+    const { lastFrame, unmount } = renderInMode(
+      <MenuSelect title="Pick one" items={ITEMS} onSelect={vi.fn()} onBack={vi.fn()} />,
+    );
+    await tick();
+    const frame = lastFrame() ?? '';
+    unmount();
+
+    expect(frame).toContain('1. First option');
+    expect(frame).toContain('2. Second option');
+    expect(frame).toContain('3. Third option');
+    expect(frame).toContain('Enter selection (1-3)');
+    expect(frame).not.toContain('> ');
+    expect(frame).not.toMatch(/[╭╮╰╯│─]/u);
+  });
+
+  it('a cancellable menu names Escape in the same literal', async () => {
+    const { lastFrame, unmount } = renderInMode(
+      <MenuSelect title="Pick one" items={ITEMS} onSelect={vi.fn()} onBack={vi.fn()} />,
+    );
+    await tick();
+    const frame = lastFrame() ?? '';
+    unmount();
+
+    expect(frame).toContain(`Enter selection (1-3)${NUMBERED_LIST_CANCEL_SUFFIX}`);
+  });
+
+  it('typing `2` then Enter selects the SECOND option', async () => {
+    const onSelect = vi.fn();
+    const { stdin, unmount } = renderInMode(
+      <MenuSelect title="Pick one" items={ITEMS} onSelect={onSelect} onBack={vi.fn()} />,
+    );
+    await tick();
+    stdin.write('2');
+    await tick();
+    stdin.write('\r');
+    await tick();
+    unmount();
+
+    expect(onSelect).toHaveBeenCalledTimes(1);
+    expect(onSelect).toHaveBeenCalledWith('b');
+  });
+
+  it('typing `9` then Enter selects nothing and re-prints the same literal', async () => {
+    const onSelect = vi.fn();
+    const { stdin, lastFrame, unmount } = renderInMode(
+      <MenuSelect title="Pick one" items={ITEMS} onSelect={onSelect} onBack={vi.fn()} />,
+    );
+    await tick();
+    stdin.write('9');
+    await tick();
+    stdin.write('\r');
+    await tick();
+    const frame = lastFrame() ?? '';
+    unmount();
+
+    expect(onSelect).not.toHaveBeenCalled();
+    // The range IS the correction: the same literal comes back, twice in the frame.
+    expect(frame.split('Enter selection (1-3)').length - 1).toBeGreaterThanOrEqual(2);
+  });
+
+  it('keeps the bordered arrow-key menu when the mode is off', async () => {
+    const { lastFrame, unmount } = render(
+      <MenuSelect title="Pick one" items={ITEMS} onSelect={vi.fn()} onBack={vi.fn()} />,
+    );
+    await tick();
+    const frame = lastFrame() ?? '';
+    unmount();
+
+    expect(frame).toContain('> First option');
+    expect(frame).not.toContain('Enter selection');
+    expect(frame).toMatch(/[╭╮╰╯]/u);
+  });
+});
+
+describe('TC-07: PermissionPrompt and ConfirmPrompt', () => {
+  function permissionRequest(resolve: (value: unknown) => void): IPendingPermissionRequest {
+    return {
+      toolName: 'Bash',
+      toolArgs: { command: 'ls -la' },
+      resolve,
+    } as unknown as IPendingPermissionRequest;
+  }
+
+  it('renders the permission ask as a numbered list with no border', async () => {
+    const { lastFrame, unmount } = renderInMode(
+      <PermissionPrompt request={permissionRequest(vi.fn())} />,
+    );
+    await tick();
+    const frame = lastFrame() ?? '';
+    unmount();
+
+    expect(frame).toContain('permission required:');
+    expect(frame).toContain('1. Allow');
+    expect(frame).toContain('Enter selection (1-4)');
+    expect(frame).not.toMatch(/[╭╮╰╯│─]/u);
+    expect(frame).not.toContain('> ');
+  });
+
+  it('a typed number resolves the permission ask', async () => {
+    const resolve = vi.fn();
+    const { stdin, unmount } = renderInMode(
+      <PermissionPrompt request={permissionRequest(resolve)} armDelayMs={0} />,
+    );
+    await tick();
+    stdin.write('4');
+    await tick();
+    stdin.write('\r');
+    await tick();
+    unmount();
+
+    // Option 4 is Deny.
+    expect(resolve).toHaveBeenCalledWith(false);
+  });
+
+  it('ConfirmPrompt accepts `y` + Enter', async () => {
+    const onSelect = vi.fn();
+    const { stdin, lastFrame, unmount } = renderInMode(
+      <ConfirmPrompt message="Proceed?" onSelect={onSelect} />,
+    );
+    await tick();
+    expect(lastFrame() ?? '').toContain(CONFIRM_PROMPT_TYPED_LITERAL);
+    stdin.write('y');
+    await tick();
+    stdin.write('\r');
+    await tick();
+    unmount();
+
+    expect(onSelect).toHaveBeenCalledWith(0);
+  });
+
+  it('ConfirmPrompt accepts `no` + Enter', async () => {
+    const onSelect = vi.fn();
+    const { stdin, unmount } = renderInMode(
+      <ConfirmPrompt message="Proceed?" onSelect={onSelect} />,
+    );
+    await tick();
+    stdin.write('n');
+    await tick();
+    stdin.write('o');
+    await tick();
+    stdin.write('\r');
+    await tick();
+    unmount();
+
+    expect(onSelect).toHaveBeenCalledWith(1);
+  });
+
+  it('ConfirmPrompt rejects anything else without selecting', async () => {
+    const onSelect = vi.fn();
+    const { stdin, unmount } = renderInMode(
+      <ConfirmPrompt message="Proceed?" onSelect={onSelect} />,
+    );
+    await tick();
+    stdin.write('m');
+    await tick();
+    stdin.write('a');
+    await tick();
+    stdin.write('\r');
+    await tick();
+    unmount();
+
+    expect(onSelect).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/screen-reader-pacing.test.ts

@@ -0,0 +1,230 @@
+/**
+ * CLI-2004 TC-20 — the startup quiet period.
+ *
+ * The bound matters more than the default: a mistyped host timing override is
+ * how a session appears to hang forever, and a silently-swallowed value is how it appears to have no
+ * effect at all. Every rejection and every clamp is REPORTED, and this asserts the report.
+ *
+ * The last case is the one the review added: "any keypress ends the wait" is only true if something
+ * puts a TTY stdin into raw mode first, because a canonical-mode terminal delivers nothing until
+ * Enter. Asserting it against a synthetic source alone would have proved a behaviour the product
+ * does not have.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  awaitStartupQuietPeriod,
+  DEFAULT_PREPARK_MS,
+  DEFAULT_STARTUP_QUIET_MS,
+  PREPARK_MS_MAX,
+  resolvePacing,
+  STARTUP_QUIET_MS_MAX,
+} from '../screen-reader-pacing.js';
+
+const STARTUP_LABEL = 'ACME_SCREEN_READER_STARTUP_QUIET_MS';
+const PREPARK_LABEL = 'ACME_SCREEN_READER_PREPARK_MS';
+
+function startup(raw: string) {
+  return { startupQuiet: { raw, label: STARTUP_LABEL } };
+}
+
+function prepark(raw: string) {
+  return { prepark: { raw, label: PREPARK_LABEL } };
+}
+
+function collectWarnings(): { notes: string[]; warn: (message: string) => void } {
+  const notes: string[] = [];
+  return { notes, warn: (message: string): void => void notes.push(message) };
+}
+
+describe('TC-20: resolvePacing', () => {
+  it('ignores ambient Fixture Agent pacing variables without a host choice', () => {
+    vi.stubEnv('PRODUCT_SCREEN_READER_STARTUP_QUIET_MS', '0');
+    vi.stubEnv('PRODUCT_SCREEN_READER_PREPARK_MS', '0');
+    try {
+      expect(resolvePacing({ enabled: true })).toEqual({
+        startupQuietMs: DEFAULT_STARTUP_QUIET_MS,
+        preparkMs: DEFAULT_PREPARK_MS,
+      });
+    } finally {
+      vi.unstubAllEnvs();
+    }
+  });
+
+  it('returns the documented default when the host supplies no override', () => {
+    expect(resolvePacing({ enabled: true })).toEqual({
+      startupQuietMs: DEFAULT_STARTUP_QUIET_MS,
+      preparkMs: DEFAULT_PREPARK_MS,
+    });
+  });
+
+  it('honours an explicit 0 exactly — the documented way to ask for no wait', () => {
+    expect(resolvePacing({ enabled: true, overrides: startup('0') })).toEqual({
+      startupQuietMs: 0,
+      preparkMs: DEFAULT_PREPARK_MS,
+    });
+  });
+
+  it('clamps the variable to its sanity bound AND reports the clamp', () => {
+    const sink = collectWarnings();
+    const pacing = resolvePacing({
+      enabled: true,
+      overrides: startup('999999'),
+      warn: sink.warn,
+    });
+
+    expect(pacing).toEqual({ startupQuietMs: STARTUP_QUIET_MS_MAX, preparkMs: DEFAULT_PREPARK_MS });
+    expect(sink.notes).toHaveLength(1);
+    expect(sink.notes[0]).toContain(`clamping 999999 to the ${STARTUP_QUIET_MS_MAX} ms`);
+  });
+
+  it('refuses a non-numeric value with a note instead of silently treating it as 0', () => {
+    const sink = collectWarnings();
+    const pacing = resolvePacing({
+      enabled: true,
+      overrides: startup('soon'),
+      warn: sink.warn,
+    });
+
+    expect(pacing.startupQuietMs).toBe(DEFAULT_STARTUP_QUIET_MS);
+    expect(pacing.startupQuietMs).not.toBe(0);
+    expect(sink.notes[0]).toContain('ignoring "soon"');
+  });
+
+  it('resolves the wait to 0 without warnings when the mode is off', () => {
+    const sink = collectWarnings();
+    expect(resolvePacing({
+      enabled: false,
+      overrides: startup('invalid'),
+      warn: sink.warn,
+    })).toEqual({
+      startupQuietMs: 0,
+      preparkMs: 0,
+    });
+    expect(sink.notes).toEqual([]);
+  });
+});
+
+describe('TC-20: the startup quiet period', () => {
+  it('settles at its deadline when nothing is pressed', async () => {
+    vi.useFakeTimers();
+    try {
+      const settled = awaitStartupQuietPeriod(500);
+      await vi.advanceTimersByTimeAsync(500);
+      await expect(settled).resolves.toBe('elapsed');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('a keypress settles it BEFORE its deadline', async () => {
+    vi.useFakeTimers();
+    try {
+      let onData: (() => void) | undefined;
+      const keys = {
+        once: (_event: 'data', listener: () => void): void => void (onData = listener),
+        off: (): void => {},
+        resume: (): void => {},
+        pause: (): void => {},
+      };
+      const settled = awaitStartupQuietPeriod(600_000, keys);
+      await vi.advanceTimersByTimeAsync(10);
+      onData?.();
+      await expect(settled).resolves.toBe('keypress');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('resolves immediately for a 0 wait without touching the keypress source', async () => {
+    let touched = false;
+    await expect(
+      awaitStartupQuietPeriod(0, {
+        once: (): void => void (touched = true),
+        off: (): void => {},
+      }),
+    ).resolves.toBe('elapsed');
+    expect(touched).toBe(false);
+  });
+
+  it('puts a TTY stdin into raw mode for the wait and restores it — without raw mode only Enter arrives', async () => {
+    vi.useFakeTimers();
+    try {
+      const modes: boolean[] = [];
+      let onData: (() => void) | undefined;
+      const keys = {
+        once: (_event: 'data', listener: () => void): void => void (onData = listener),
+        off: (): void => {},
+        resume: (): void => {},
+        pause: (): void => {},
+        isTTY: true,
+        setRawMode: (mode: boolean): void => void modes.push(mode),
+      };
+
+      const settled = awaitStartupQuietPeriod(600_000, keys);
+      expect(modes).toEqual([true]);
+      onData?.();
+      await expect(settled).resolves.toBe('keypress');
+      expect(modes).toEqual([true, false]);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('leaves a non-TTY stdin alone — there is no raw mode to set on a pipe', async () => {
+    vi.useFakeTimers();
+    try {
+      let touchedRawMode = false;
+      const keys = {
+        once: (): void => {},
+        off: (): void => {},
+        isTTY: false,
+        setRawMode: (): void => void (touchedRawMode = true),
+      };
+      const settled = awaitStartupQuietPeriod(200, keys);
+      await vi.advanceTimersByTimeAsync(200);
+      await expect(settled).resolves.toBe('elapsed');
+      expect(touchedRawMode).toBe(false);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+describe('SCREEN-2670 TC-01: resolvePacing returns preparkMs by the same discipline', () => {
+  it('defaults to the provisional 50 and honours an explicit 0 exactly', () => {
+    expect(resolvePacing({ enabled: true }).preparkMs).toBe(50);
+    expect(resolvePacing({ enabled: true, overrides: prepark('0') }).preparkMs).toBe(0);
+    expect(resolvePacing({ enabled: true, overrides: prepark('250') }).preparkMs).toBe(250);
+  });
+
+  it('refuses a non-numeric or negative value WITH a note naming the variable', () => {
+    for (const raw of ['soon', '-5', '1.5']) {
+      const sink = collectWarnings();
+      const pacing = resolvePacing({ enabled: true, overrides: prepark(raw), warn: sink.warn });
+      expect(pacing.preparkMs).toBe(DEFAULT_PREPARK_MS);
+      expect(sink.notes).toHaveLength(1);
+      expect(sink.notes[0]).toContain(PREPARK_LABEL);
+      expect(sink.notes[0]).toContain(`"${raw}"`);
+    }
+  });
+
+  it('clamps above the bound AND reports the clamp', () => {
+    const sink = collectWarnings();
+    const pacing = resolvePacing({
+      enabled: true,
+      overrides: prepark('99999'),
+      warn: sink.warn,
+    });
+    expect(pacing.preparkMs).toBe(PREPARK_MS_MAX);
+    expect(sink.notes[0]).toContain(`clamping 99999 to the ${PREPARK_MS_MAX} ms`);
+  });
+
+  it('is 0 whenever the mode is off, regardless of the variable', () => {
+    expect(resolvePacing({ enabled: false, overrides: prepark('250') })).toEqual({
+      startupQuietMs: 0,
+      preparkMs: 0,
+    });
+  });
+});

package/src/__tests__/screen-reader-prepark-echo.test.tsx

@@ -0,0 +1,200 @@
+/**
+ * SCREEN-2670 TC-10 — the echo exemption FIRES through the real render path.
+ *
+ * TC-03 arms the flag by hand, which proves the queue honours a stamp and nothing about whether
+ * anything ever sets one. This drives a keystroke through Ink's own input path into the composed
+ * tree — keybindings, the pacing context, the composer's key handler — with the proxy as Ink's
+ * stdout, and asserts BOTH halves: the keystroke's commit leaves unparked, and the next commit that
+ * is not a keystroke (a prop change from outside the composer, and Enter — whose commit appends the
+ * prompt line) is parked. A proxy that stamped everything would pass the first half and fail the
+ * second, which is why they sit in one test.
+ */
+
+import { EventEmitter } from 'node:events';
+
+import { Box, render, Text } from 'ink';
+import React, { useState } from 'react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import CjkTextInput from '../CjkTextInput.js';
+import { KeybindingsProvider } from '../keybindings/keybindings-context.js';
+import { parseKeybindingsDocument } from '../keybindings/keybinding-registry.js';
+import { ScreenReaderPacingProvider } from '../screen-reader-pacing-context.js';
+import { createParkedStdout } from '../screen-reader-stdout.js';
+
+import type { IKeybindingsSource } from '../keybindings/node-keybindings-source.js';
+import type { IScreenReaderPacingPort } from '../screen-reader-pacing-context.js';
+import type { TParkedStdoutSource } from '../screen-reader-stdout.js';
+
+const PARK_MS = 400;
+
+class FakeTtyStdout extends EventEmitter {
+  readonly isTTY = true;
+  readonly columns = 80;
+  readonly rows = 24;
+  readonly destroyed = false;
+  readonly writable = true;
+  readonly writableEnded = false;
+  readonly writableLength = 0;
+  readonly writableNeedDrain = false;
+  readonly frames: Array<{ text: string; at: number }> = [];
+  write = (chunk: string | Uint8Array, ...rest: unknown[]): boolean => {
+    const callback = rest.find((argument) => typeof argument === 'function') as
+      ((error?: Error | null) => void) | undefined;
+    this.frames.push({ text: String(chunk), at: Date.now() });
+    callback?.(null);
+    return true;
+  };
+  asSource(): TParkedStdoutSource {
+    return this as unknown as TParkedStdoutSource;
+  }
+  textSince(index: number): string {
+    return this.frames
+      .slice(index)
+      .map((frame) => frame.text)
+      .join('');
+  }
+}
+
+class FakeStdin extends EventEmitter {
+  readonly isTTY = true;
+  private pending: string | null = null;
+  setEncoding(): void {}
+  setRawMode(): void {}
+  resume(): void {}
+  pause(): void {}
+  ref(): void {}
+  unref(): void {}
+  read(): string | null {
+    const data = this.pending;
+    this.pending = null;
+    return data;
+  }
+  send(data: string): void {
+    this.pending = data;
+    this.emit('readable');
+    this.emit('data', data);
+  }
+}
+
+function source(): IKeybindingsSource {
+  const parsed = parseKeybindingsDocument(
+    JSON.stringify({ version: 1, bindings: {} }),
+    '/tmp/keybindings.json',
+  );
+  if (!parsed.ok) throw new Error(parsed.diagnostic.message);
+  return {
+    filePath: '/tmp/keybindings.json',
+    start: async () => undefined,
+    isStarted: () => true,
+    ensureFile: async () => '/tmp/keybindings.json',
+    getSnapshot: () => parsed.snapshot,
+    subscribe: () => () => undefined,
+    dispose: () => undefined,
+  };
+}
+
+function Harness({
+  banner,
+  onSubmit,
+}: {
+  banner: string;
+  onSubmit: (value: string) => void;
+}): React.ReactElement {
+  const [value, setValue] = useState('');
+  return (
+    <Box flexDirection="column">
+      <Text>{banner}</Text>
+      <Box>
+        <Text>{'> '}</Text>
+        <CjkTextInput
+          value={value}
+          onChange={setValue}
+          onSubmit={(submitted) => {
+            // Like the real composer: submitting clears the line, so the commit repaints.
+            setValue('');
+            onSubmit(submitted);
+          }}
+          keybindingContext="chat-input"
+        />
+      </Box>
+    </Box>
+  );
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** In screen-reader mode Ink linearises each Text node; compare visible characters only. */
+const visible = (text: string): string =>
+  // eslint-disable-next-line no-control-regex -- stripping the escapes IS the point here
+  text.replace(/\x1b\[[0-9;?]*[A-Za-z]|\x1b\][^\x07]*\x07/g, '').replace(/\s+/g, ' ');
+
+let unmount: (() => void) | undefined;
+
+afterEach(() => {
+  unmount?.();
+  unmount = undefined;
+});
+
+describe('TC-10: a keystroke through the composed tree is released unparked; a non-composer commit is parked', () => {
+  it('echo leaves at once, a banner change and Enter each wait out the interval', async () => {
+    const stdout = new FakeTtyStdout();
+    const stdin = new FakeStdin();
+    const parked = createParkedStdout({ stdout: stdout.asSource(), preparkMs: PARK_MS });
+    const port: IScreenReaderPacingPort = {
+      armEchoRelease: () => parked.armEchoRelease(),
+      write: (text) => {
+        parked.write(text);
+      },
+    };
+    const submitted: string[] = [];
+    const tree = (banner: string): React.ReactElement => (
+      <KeybindingsProvider source={source()}>
+        <ScreenReaderPacingProvider port={port}>
+          <Harness banner={banner} onSubmit={(value) => submitted.push(value)} />
+        </ScreenReaderPacingProvider>
+      </KeybindingsProvider>
+    );
+    const instance = render(tree('banner 1'), {
+      stdout: parked.asInkStdout(),
+      stdin: stdin as unknown as NodeJS.ReadStream,
+      isScreenReaderEnabled: true,
+      // Ink treats a CI environment as non-interactive and defers every frame to unmount; the
+      // park only exists for interactive terminals, so say so explicitly (as the real-cursor
+      // suite does) rather than let the runner's CI variable decide what is under test.
+      interactive: true,
+      exitOnCtrlC: false,
+      patchConsole: false,
+    });
+    unmount = instance.unmount;
+
+    // First frames: the first batch is never parked; let the mount settle past one interval.
+    await sleep(PARK_MS + 100);
+    expect(stdout.textSince(0)).toContain('banner 1');
+
+    // A keystroke: its echo must be on the underlying stream well inside the interval.
+    const beforeKey = stdout.frames.length;
+    stdin.send('hey');
+    await sleep(80);
+    expect(visible(stdout.textSince(beforeKey))).toContain('hey');
+
+    // A commit that is not a keystroke, arriving inside the interval after the echo: parked until
+    // the interval since that last printable release has elapsed, then released.
+    const beforeBanner = stdout.frames.length;
+    instance.rerender(tree('banner 2'));
+    await sleep(80);
+    expect(visible(stdout.textSince(beforeBanner))).not.toContain('banner 2');
+    await sleep(PARK_MS);
+    expect(visible(stdout.textSince(beforeBanner))).toContain('banner 2');
+
+    // Enter runs through the same key handler and must NOT arm: arriving right after the banner's
+    // release, the submit commit is parked like any other transcript commit.
+    const beforeEnter = stdout.frames.length;
+    stdin.send('\r');
+    await sleep(80);
+    expect(submitted).toEqual(['hey']);
+    expect(stdout.frames.length).toBe(beforeEnter);
+    await sleep(PARK_MS);
+    expect(stdout.frames.length).toBeGreaterThan(beforeEnter);
+  }, 10_000);
+});