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

package/src/__tests__/render-markdown.test.ts

@@ -0,0 +1,164 @@
+import chalk from 'chalk';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { renderMarkdown } from '../render-markdown.js';
+import { DARK_DALTONIZED_THEME, DARK_THEME } from '../theme/built-in-themes.js';
+import { foreground } from '../theme/index.js';
+
+const ANSI_LIGHT_RED = '\u001b[38;5;210m';
+const ANSI_LIGHT_GREEN = '\u001b[38;5;120m';
+const ANSI_DARK_RED_BACKGROUND = '\u001b[48;5;52m';
+const ANSI_DARK_GREEN_BACKGROUND = '\u001b[48;5;22m';
+// SCREEN-2002: the rows are styled through chalk now, which closes a background+foreground pair with
+// its own paired resets instead of the blanket `ESC[0m` the hand-written escapes used. The colours
+// and their order are unchanged; this is the one recorded byte difference.
+const ANSI_RESET_FOREGROUND = '\u001b[39m';
+const ANSI_RESET_BACKGROUND = '\u001b[49m';
+const CODE_BLOCK_INDENT = '    ';
+/** Any SGR introducer — a plain block must carry none. */
+const SGR_ANY = '\u001b[';
+
+describe('renderMarkdown', () => {
+  it('renders diff fenced code blocks with addition and removal colors', () => {
+    const output = renderMarkdown(
+      ['Before', '', '```diff', '- const oldValue = true;', '+ const newValue = true;', '```'].join(
+        '\n',
+      ),
+      { color: true },
+    );
+
+    expect(output).toContain(`${ANSI_DARK_RED_BACKGROUND}${ANSI_LIGHT_RED}`);
+    expect(output).toContain(`${CODE_BLOCK_INDENT}- const oldValue = true;`);
+    expect(output).toContain(`${ANSI_DARK_GREEN_BACKGROUND}${ANSI_LIGHT_GREEN}`);
+    expect(output).toContain(`${CODE_BLOCK_INDENT}+ const newValue = true;`);
+  });
+
+  it('pads added and removed diff rows before applying background colors', () => {
+    const codeBlockWidth = 24;
+    const removedRow = `${CODE_BLOCK_INDENT}- removed`.padEnd(codeBlockWidth);
+    const addedRow = `${CODE_BLOCK_INDENT}+ added`.padEnd(codeBlockWidth);
+    const output = renderMarkdown(['```diff', '- removed', '+ added', '```'].join('\n'), {
+      color: true,
+      codeBlockWidth,
+    });
+
+    expect(output).toContain(
+      `${ANSI_DARK_RED_BACKGROUND}${ANSI_LIGHT_RED}${removedRow}${ANSI_RESET_FOREGROUND}${ANSI_RESET_BACKGROUND}`,
+    );
+    expect(output).toContain(
+      `${ANSI_DARK_GREEN_BACKGROUND}${ANSI_LIGHT_GREEN}${addedRow}${ANSI_RESET_FOREGROUND}${ANSI_RESET_BACKGROUND}`,
+    );
+  });
+
+  it('keeps diff fenced code block content readable when color is disabled', () => {
+    const output = renderMarkdown(
+      ['```diff', '- removed line', '+ added line', ' unchanged line', '```'].join('\n'),
+      { color: false },
+    );
+
+    expect(output).toContain('- removed line');
+    expect(output).toContain('+ added line');
+    expect(output).toContain(' unchanged line');
+    expect(output).not.toContain(ANSI_LIGHT_RED);
+    expect(output).not.toContain(ANSI_LIGHT_GREEN);
+    expect(output).not.toContain(ANSI_DARK_RED_BACKGROUND);
+    expect(output).not.toContain(ANSI_DARK_GREEN_BACKGROUND);
+  });
+
+  it('keeps regular fenced code blocks as code output', () => {
+    const output = renderMarkdown(['```ts', 'const value: string = "ok";', '```'].join('\n'), {
+      color: false,
+    });
+
+    expect(output).toContain('const value: string = "ok";');
+  });
+
+  /**
+   * SCREEN-2002 TC-03 — the theme reaches `cli-highlight`.
+   *
+   * This is the unit's most dependency-fragile claim, and the failure it guards against is SILENT:
+   * `cli-highlight` falls back PER KEY to its own `DEFAULT_THEME`, whose `keyword` is red and whose
+   * `addition` is green. If the theme stopped reaching it, a daltonized run would quietly get the
+   * red/green pair back with every other surface still daltonized, and nothing else in the suite
+   * would notice.
+   */
+  describe('SCREEN-2002 TC-03: syntax highlighting follows the theme', () => {
+    const TS_BLOCK = ['```ts', 'const value = 1;', '```'].join('\n');
+    const TRUECOLOR = 3;
+    const previousLevel = chalk.level;
+    afterEach(() => {
+      chalk.level = previousLevel;
+    });
+
+    const openCode = (color: string): string => foreground(color)('x').split('x')[0] ?? '';
+
+    it('colours a keyword with the theme s value, not cli-highlight s default', () => {
+      chalk.level = TRUECOLOR;
+      const daltonized = renderMarkdown(TS_BLOCK, {
+        color: true,
+        theme: DARK_DALTONIZED_THEME,
+      });
+
+      expect(daltonized).toContain(openCode(DARK_DALTONIZED_THEME.syntax.keyword));
+      // Recorded, because it bounds what this test can prove: `cli-highlight` depends on chalk 4 and
+      // resolves to its OWN instance, so `chalk.level` set here does not reach it and its per-key
+      // fallback emits nothing in-process — it is only coloured in a real terminal. The positive
+      // assertion above is therefore the whole guard; a `not.toContain` on the fallback's colour
+      // would be inert. The end-to-end colour is evidenced by the PTY scenario instead.
+      expect(DARK_THEME.syntax.keyword).not.toBe(DARK_DALTONIZED_THEME.syntax.keyword);
+    });
+
+    it('renders a code block as plain indented text when highlighting is off', () => {
+      chalk.level = TRUECOLOR;
+      const plain = renderMarkdown(TS_BLOCK, {
+        color: true,
+        theme: DARK_DALTONIZED_THEME,
+        syntaxHighlighting: false,
+      });
+
+      expect(plain).toContain(`${CODE_BLOCK_INDENT}const value = 1;`);
+      expect(plain).not.toContain(openCode(DARK_DALTONIZED_THEME.syntax.keyword));
+      expect(plain).not.toContain(SGR_ANY);
+    });
+  });
+
+  /**
+   * CLI-2004 TC-04 — the `Header: value` flattening, asserted at the single choke point every
+   * render path shares. A box-drawn grid is read aloud as its rules; the pairing is the content.
+   */
+  describe('CLI-2004 TC-04: screen-reader table flattening', () => {
+    const TABLE = ['| A | B |', '|---|---|', '| 1 | 2 |'].join('\n');
+    const BOX_DRAWING = /[\u2502\u2500\u250c\u2510\u2514\u2518\u251c\u2524\u252c\u2534\u253c]/u;
+
+    it('flattens a table to one `Header: value` line per cell in the mode', () => {
+      const output = renderMarkdown(TABLE, { color: false, screenReader: true });
+
+      const lines = output.split('\n').map((line) => line.trim());
+      expect(lines).toContain('A: 1');
+      expect(lines).toContain('B: 2');
+      expect(lines.indexOf('A: 1')).toBeLessThan(lines.indexOf('B: 2'));
+      expect(output).not.toMatch(BOX_DRAWING);
+    });
+
+    it('separates rows with a blank line so the row boundary is audible', () => {
+      const twoRows = ['| A | B |', '|---|---|', '| 1 | 2 |', '| 3 | 4 |'].join('\n');
+      const output = renderMarkdown(twoRows, { color: false, screenReader: true });
+
+      expect(output).toContain('A: 1\nB: 2\n\nA: 3\nB: 4');
+    });
+
+    it('leaves the box-drawn grid exactly as it is outside the mode', () => {
+      const output = renderMarkdown(TABLE, { color: false });
+
+      expect(output).toMatch(BOX_DRAWING);
+      expect(output).not.toContain('A: 1');
+    });
+  });
+
+  it('keeps inline markdown formatting readable', () => {
+    const output = renderMarkdown('Use **bold** and `code` here.', { color: false });
+
+    expect(output).toContain('bold');
+    expect(output).toContain('code');
+  });
+});

package/src/__tests__/rendered-markdown-styling.test.tsx

@@ -0,0 +1,98 @@
+/**
+ * SCREEN-006 × #2222: the markdown renderer's own SGR must SURVIVE to the frame.
+ *
+ * `renderMarkdown` sanitizes untrusted markdown BEFORE `marked-terminal` styles it, so the escape
+ * codes in its OUTPUT are this package's own — the theme's diff pairs, heading emphasis.
+ * Routing that output back through `SafeText` sanitizes it a second time and strips exactly those
+ * codes, and it does so silently: the text still renders, just colourless. Every assertion in
+ * `streaming-indicator.test.tsx` and the tool-diff suite is on TEXT, so all of them stay green
+ * while the colour is gone — which is how the regression reached a release.
+ *
+ * These are the assertions that go red for that, one per render site that renders markdown.
+ */
+
+import React from 'react';
+import { render } from 'ink-testing-library';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import StreamingIndicator from '../StreamingIndicator.js';
+import ToolDiffBlock from '../ToolDiffBlock.js';
+import { DARK_THEME } from '../theme/built-in-themes.js';
+import { foreground } from '../theme/index.js';
+
+import type { IDiffLine } from '@robota-sdk/agent-interface-session';
+
+/** The opening SGR a theme colour produces, for an assertion about the rendered bytes. */
+function openCode(color: string): string {
+  const [open] = foreground(color)('x').split('x');
+  return open ?? '';
+}
+
+const DIFF_LINES: IDiffLine[] = [
+  { type: 'hunk', text: '@@ -1,2 +1,2 @@', lineNumber: 1 },
+  { type: 'remove', text: 'const a = 1;', lineNumber: 1 },
+  { type: 'add', text: 'const a = 2;', lineNumber: 1 },
+];
+
+const DIFF_MARKDOWN = [
+  '```diff',
+  '@@ -1,2 +1,2 @@',
+  '- const a = 1;',
+  '+ const a = 2;',
+  '```',
+].join('\n');
+
+describe('markdown styling survives the render site (SCREEN-006)', () => {
+  let originalForceColor: string | undefined;
+  let originalNoColor: string | undefined;
+
+  beforeEach(() => {
+    // `renderMarkdown` colours only for an interactive colour terminal; the test process is not one.
+    originalForceColor = process.env.FORCE_COLOR;
+    originalNoColor = process.env.NO_COLOR;
+    delete process.env.NO_COLOR;
+    process.env.FORCE_COLOR = '1';
+  });
+
+  afterEach(() => {
+    if (originalForceColor === undefined) delete process.env.FORCE_COLOR;
+    else process.env.FORCE_COLOR = originalForceColor;
+    if (originalNoColor === undefined) delete process.env.NO_COLOR;
+    else process.env.NO_COLOR = originalNoColor;
+  });
+
+  it('ToolDiffBlock keeps the added/removed diff colours', () => {
+    const { lastFrame } = render(<ToolDiffBlock file="src/a.ts" lines={DIFF_LINES} />);
+    const frame = lastFrame() ?? '';
+
+    expect(frame).toContain('const a = 2;');
+    // SCREEN-2002: the diff colours come from the resolved theme; the default theme's values are the
+    // ones this suite pinned before the theme existed.
+    expect(frame).toContain(openCode(DARK_THEME.markdown.diffAdded));
+    expect(frame).toContain(openCode(DARK_THEME.markdown.diffRemoved));
+    expect(frame).toContain(openCode(DARK_THEME.markdown.diffHunk)); // the @@ hunk header
+  });
+
+  it('StreamingIndicator keeps the colours of a diff block in streamed text', () => {
+    const { lastFrame } = render(<StreamingIndicator text={DIFF_MARKDOWN} activeTools={[]} />);
+    const frame = lastFrame() ?? '';
+
+    expect(frame).toContain('const a = 2;');
+    expect(frame).toContain(openCode(DARK_THEME.markdown.diffAdded));
+    expect(frame).toContain(openCode(DARK_THEME.markdown.diffRemoved));
+  });
+
+  it('StreamingIndicator still sanitizes what arrives from OUTSIDE the renderer', () => {
+    // The other direction of the same boundary: `renderMarkdown` sanitizes its INPUT, so an escape
+    // sequence in the model's text is gone before `marked-terminal` ever sees it. Switching this
+    // site to `RenderedText` must not reopen that.
+    const { lastFrame } = render(
+      <StreamingIndicator text={`before]8;;https://evil.exampleclick]8;;after`} activeTools={[]} />,
+    );
+    const frame = lastFrame() ?? '';
+
+    expect(frame).not.toContain('evil.example');
+    expect(frame).not.toContain(']8;;');
+    expect(frame).toContain('before');
+  });
+});

package/src/__tests__/safe-text-boundary.test.tsx

@@ -0,0 +1,75 @@
+/**
+ * #2222: the SafeText boundary, asserted against the BYTES Ink writes to a tty — not against
+ * `lastFrame()`. Measured on PR #2212: Ink itself strips OSC 52 / OSC 0 / CSI / DCS / APC from a
+ * frame and passes SGR, OSC 8 and a bare CR, so a frame assertion is green whether or not the code
+ * sanitizes. Only the stream a real terminal would receive tells the two apart.
+ *
+ * The raw-`Text` case below is REQUIRED to leak: it is what proves the detector can answer "yes".
+ */
+
+import { Writable } from 'node:stream';
+
+import { Text as RawInkText, render } from 'ink';
+import React from 'react';
+import { describe, expect, it } from 'vitest';
+
+import { SafeText, Text } from '../SafeText.js';
+
+import type { ReactElement } from 'react';
+
+/** OSC 8 hyperlink (Ink passes it through) and a bare CR — the two markers a frame cannot show. */
+const OSC8 = ']8;;https://evil.exampleclick]8;;';
+const POISON = `before${OSC8}\rafter`;
+
+/** A stream that claims to be a tty, so Ink writes what a terminal would receive. */
+function createTtyCapture(): { stdout: NodeJS.WriteStream; bytes: () => string } {
+  const chunks: string[] = [];
+  const stream = new Writable({
+    write(chunk: Buffer | string, _encoding, callback) {
+      chunks.push(chunk.toString());
+      callback();
+    },
+  });
+  const stdout = Object.assign(stream, {
+    isTTY: true,
+    columns: 80,
+    rows: 24,
+  }) as unknown as NodeJS.WriteStream;
+  return { stdout, bytes: () => chunks.join('') };
+}
+
+async function renderToTty(element: ReactElement): Promise<string> {
+  const capture = createTtyCapture();
+  const instance = render(element, { stdout: capture.stdout, patchConsole: false });
+  await new Promise((resolve) => setTimeout(resolve, 20));
+  instance.unmount();
+  return capture.bytes();
+}
+
+describe('SafeText boundary (#2222)', () => {
+  it('a raw ink Text render LEAKS the markers to the tty stream (detector proof)', async () => {
+    const bytes = await renderToTty(<RawInkText>{POISON}</RawInkText>);
+    expect(bytes).toContain(']8;;https://evil.example');
+    expect(bytes).toContain('before');
+  });
+
+  it('SafeText removes the markers from the same payload, keeping the visible text', async () => {
+    const bytes = await renderToTty(<SafeText>{POISON}</SafeText>);
+    expect(bytes).not.toContain('evil.example');
+    expect(bytes).not.toContain(']8;;');
+    expect(bytes).toContain('before');
+    expect(bytes).toContain('after');
+  });
+
+  it('the `Text` alias call sites use is the boundary, and nested children are covered', async () => {
+    const bytes = await renderToTty(
+      <Text>
+        {'label: '}
+        <Text bold>{POISON}</Text>
+        {[POISON, 42]}
+      </Text>,
+    );
+    expect(bytes).not.toContain('evil.example');
+    expect(bytes).toContain('42');
+  });
+});

package/src/__tests__/sandbox-reaches-the-session.test.ts

@@ -0,0 +1,37 @@
+/**
+ * Issue #3242: the TUI session consults the same sandbox the shell tools run under, so a confined
+ * command the sandbox approves runs without a prompt.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { toChannelOptions } from '../render.js';
+import { buildTuiSessionOptions } from '../tui-session-options.js';
+
+import type { IRenderOptions } from '../render.js';
+
+type TSandboxClient = NonNullable<IRenderOptions['sandboxClient']>;
+
+const sandboxClient = { filesystem: 'shared', autoApproves: () => true } as unknown as TSandboxClient;
+
+function renderOptions(extra: Partial<IRenderOptions> = {}): IRenderOptions {
+  return { cwd: '/work', provider: {} as never, ...extra } as IRenderOptions;
+}
+
+describe('the TUI projection carries the sandbox client', () => {
+  it('passes the supplied sandbox through the channel into the session', () => {
+    const channel = toChannelOptions(renderOptions({ sandboxClient }));
+
+    expect((buildTuiSessionOptions(channel) as { sandboxClient?: unknown }).sandboxClient).toBe(
+      sandboxClient,
+    );
+  });
+
+  it('carries none when none was supplied', () => {
+    const channel = toChannelOptions(renderOptions());
+
+    expect(
+      (buildTuiSessionOptions(channel) as { sandboxClient?: unknown }).sandboxClient,
+    ).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,106 @@
+/**
+ * CLI-2004 TC-10 — the input area in screen-reader mode.
+ *
+ * Two things, and they fail for the same reason. The hand-drawn rules above and below the input are
+ * repainted with the line, so a reader hears a wall of dashes on every keystroke; and a word
+ * deletion leaves a reader announcing what REMAINS, which is precisely not the information wanted.
+ */
+
+import { render } from 'ink-testing-library';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import InputArea from '../InputArea.js';
+import { formatDeletionAnnouncement } from '../input-area-rules.js';
+import { ScreenReaderProvider } from '../screen-reader-context.js';
+
+async function tick(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 20));
+}
+
+function renderInput(enabled: boolean): ReturnType<typeof render> {
+  return render(
+    <ScreenReaderProvider enabled={enabled}>
+      <InputArea onSubmit={vi.fn()} isDisabled={false} />
+    </ScreenReaderProvider>,
+  );
+}
+
+describe('TC-10: the input area chrome', () => {
+  it('renders no rule line and no border in the mode', async () => {
+    const { lastFrame, unmount } = renderInput(true);
+    await tick();
+    const frame = lastFrame() ?? '';
+    unmount();
+
+    expect(frame).not.toContain('─');
+    expect(frame).not.toMatch(/[╭╮╰╯│┌┐└┘]/u);
+    expect(frame).toContain('Type a message');
+  });
+
+  it('still renders the rules when the mode is off', async () => {
+    const { lastFrame, unmount } = renderInput(false);
+    await tick();
+    const frame = lastFrame() ?? '';
+    unmount();
+
+    expect(frame).toContain('─');
+  });
+});
+
+describe('TC-10: the deletion announcement', () => {
+  it('prints `[deleted: <word>]` exactly once after a word deletion', async () => {
+    const { stdin, lastFrame, unmount } = renderInput(true);
+    await tick();
+
+    for (const char of 'hello world') {
+      stdin.write(char);
+    }
+    await tick();
+    // Ctrl+W — the word delete.
+    stdin.write('\x17');
+    await tick();
+
+    const frame = lastFrame() ?? '';
+    unmount();
+
+    const announcement = formatDeletionAnnouncement('world');
+    expect(frame).toContain(announcement);
+    expect(frame.split(announcement).length - 1).toBe(1);
+  });
+
+  it('announces the whole line for a line deletion', async () => {
+    const { stdin, lastFrame, unmount } = renderInput(true);
+    await tick();
+
+    for (const char of 'abc') {
+      stdin.write(char);
+    }
+    await tick();
+    // Ctrl+U — the line delete.
+    stdin.write('\x15');
+    await tick();
+
+    const frame = lastFrame() ?? '';
+    unmount();
+
+    expect(frame).toContain(formatDeletionAnnouncement('abc'));
+  });
+
+  it('announces nothing when the mode is off', async () => {
+    const { stdin, lastFrame, unmount } = renderInput(false);
+    await tick();
+
+    for (const char of 'hello world') {
+      stdin.write(char);
+    }
+    await tick();
+    stdin.write('\x17');
+    await tick();
+
+    const frame = lastFrame() ?? '';
+    unmount();
+
+    expect(frame).not.toContain('[deleted:');
+  });
+});

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

@@ -0,0 +1,91 @@
+/**
+ * CLI-2004 TC-05 — the role-derived, provider-invariant label vocabulary.
+ *
+ * The point of the negative assertion below is not tidiness: a label naming the vendor would make
+ * the transcript differ between `agent-provider-*` packages for the same conversation, and a reader
+ * grepping their scrollback for "assistant:" would find nothing after switching providers.
+ */
+
+import { render } from 'ink-testing-library';
+import React from 'react';
+import { describe, expect, it } from 'vitest';
+
+import { RoleLabel } from '../RoleLabel.js';
+import { ScreenReaderProvider } from '../screen-reader-context.js';
+import {
+  SCREEN_READER_LABELS,
+  screenReaderLabelForRole,
+  screenReaderLabelValues,
+} from '../screen-reader-labels.js';
+
+import type { TUniversalMessage } from '@robota-sdk/agent-core';
+
+/** Every provider package this repo ships, plus the vendor names behind them. */
+const VENDOR_WORDS = /(claude|anthropic|openai|gpt|gemini|google|llama|mistral|copilot)/i;
+
+function renderLabel(role: TUniversalMessage['role'], enabled: boolean, driverId?: string): string {
+  const label = React.createElement(
+    RoleLabel,
+    driverId === undefined ? { role } : { role, driverId },
+  );
+  const { lastFrame, unmount } = render(
+    React.createElement(ScreenReaderProvider, { enabled, children: label }),
+  );
+  const frame = lastFrame() ?? '';
+  unmount();
+  return frame;
+}
+
+describe('TC-05: the label vocabulary', () => {
+  it('covers all nine label kinds', () => {
+    expect(Object.keys(SCREEN_READER_LABELS)).toHaveLength(9);
+    expect(screenReaderLabelValues()).toEqual([
+      'you:',
+      'assistant:',
+      'thinking:',
+      'tool:',
+      'tool error:',
+      'error:',
+      'warning:',
+      'permission required:',
+      'cost:',
+    ]);
+  });
+
+  it('is entirely lowercase', () => {
+    for (const label of screenReaderLabelValues()) {
+      expect(label).toBe(label.toLowerCase());
+    }
+  });
+
+  it('names no provider or vendor', () => {
+    for (const label of screenReaderLabelValues()) {
+      expect(label).not.toMatch(VENDOR_WORDS);
+    }
+  });
+
+  it('maps every transcript role onto the vocabulary', () => {
+    expect(screenReaderLabelForRole('user')).toBe('you:');
+    expect(screenReaderLabelForRole('assistant')).toBe('assistant:');
+    expect(screenReaderLabelForRole('tool')).toBe('tool:');
+    expect(screenReaderLabelForRole('system')).toBe('warning:');
+  });
+});
+
+describe('TC-05: RoleLabel in the mode', () => {
+  it('renders `assistant:` for an assistant message — the same under every provider', () => {
+    const frame = renderLabel('assistant', true);
+    expect(frame).toContain('assistant:');
+    expect(frame).not.toMatch(VENDOR_WORDS);
+  });
+
+  it('renders `you:` for the operator, and the driver id for a co-driven turn', () => {
+    expect(renderLabel('user', true)).toContain('you:');
+    expect(renderLabel('user', true, 'peer:s-1')).toContain('peer:s-1:');
+  });
+
+  it('uses neutral visual labels when the mode is off', () => {
+    expect(renderLabel('assistant', false)).toContain('Assistant:');
+    expect(renderLabel('user', false)).toContain('You:');
+  });
+});