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

package/src/__tests__/cjk-text-input-flow.test.ts

@@ -0,0 +1,186 @@
+import { describe, expect, it } from 'vitest';
+import {
+  applyCjkTextInput,
+  applyCjkTextPaste,
+  createCjkTextInputFlowState,
+  syncCjkTextInputFlowState,
+} from '../flows/cjk-text-input-flow.js';
+
+describe('cjk text input flow', () => {
+  it('Given printable input When applied Then value changes at cursor', () => {
+    const result = applyCjkTextInput(
+      createCjkTextInputFlowState('ab'),
+      'c',
+      {},
+      { canPaste: true },
+    );
+
+    expect(result.state).toMatchObject({ value: 'abc', cursor: 3 });
+    expect(result.effect).toEqual({ type: 'change', value: 'abc' });
+  });
+
+  it('Given cursor in middle When backspace is applied Then previous char is removed', () => {
+    const state = { ...createCjkTextInputFlowState('abc'), cursor: 2 };
+
+    const result = applyCjkTextInput(state, '', { backspace: true }, { canPaste: true });
+
+    expect(result.state).toMatchObject({ value: 'ac', cursor: 1 });
+    expect(result.effect).toEqual({ type: 'change', value: 'ac' });
+  });
+
+  it('Given return key When applied Then submit effect contains current value', () => {
+    const result = applyCjkTextInput(
+      createCjkTextInputFlowState('hello'),
+      '',
+      { return: true },
+      { canPaste: true },
+    );
+
+    expect(result.effect).toEqual({ type: 'submit', value: 'hello' });
+  });
+
+  it('Given multiline fallback paste When applied Then paste effect is emitted', () => {
+    const result = applyCjkTextInput(
+      createCjkTextInputFlowState(''),
+      'a\nb',
+      {},
+      { canPaste: true },
+    );
+
+    expect(result.effect).toEqual({ type: 'paste', text: 'a\nb', cursor: 0 });
+  });
+
+  it('Given Ink usePaste single-line text When applied Then text is inserted at cursor', () => {
+    const state = { ...createCjkTextInputFlowState('ab'), cursor: 1 };
+
+    const result = applyCjkTextPaste(state, '한글', { canPaste: true });
+
+    expect(result.state).toMatchObject({ value: 'a한글b', cursor: 3 });
+    expect(result.effect).toEqual({ type: 'change', value: 'a한글b' });
+  });
+
+  it('Given Ink usePaste multiline text When applied Then normalized paste effect is emitted', () => {
+    const state = { ...createCjkTextInputFlowState('ab'), cursor: 1 };
+
+    const result = applyCjkTextPaste(state, 'x\r\ny\rz', { canPaste: true });
+
+    expect(result.state).toBe(state);
+    expect(result.effect).toEqual({ type: 'paste', text: 'x\ny\nz', cursor: 1 });
+  });
+
+  it('Given bracketed multiline paste When end marker arrives Then buffered paste is emitted', () => {
+    const started = applyCjkTextInput(
+      createCjkTextInputFlowState('x'),
+      '[200~hello',
+      {},
+      { canPaste: true },
+    ).state;
+    const result = applyCjkTextInput(started, '\nworld[201~', {}, { canPaste: true });
+
+    expect(result.effect).toEqual({ type: 'paste', text: 'hello\nworld', cursor: 1 });
+    expect(result.state.isPasting).toBe(false);
+  });
+
+  it('Given external value update When synced Then cursor hint is honored', () => {
+    const state = createCjkTextInputFlowState('abc');
+
+    const result = syncCjkTextInputFlowState(state, 'a[Pasted]bc', 9);
+
+    expect(result).toMatchObject({ value: 'a[Pasted]bc', cursor: 9 });
+  });
+
+  it('Given vertical navigation disabled When up arrow is applied Then cursor is unchanged', () => {
+    const state = { ...createCjkTextInputFlowState('abcdef'), cursor: 5 };
+
+    const result = applyCjkTextInput(
+      state,
+      '',
+      { upArrow: true },
+      {
+        canPaste: true,
+        enableVerticalNavigation: false,
+        availableWidth: 2,
+      },
+    );
+
+    expect(result.state).toBe(state);
+    expect(result.effect).toEqual({ type: 'none' });
+  });
+});
+
+/**
+ * CLI-2004 — `Ctrl+W` and `Ctrl+U` are NEW BINDINGS, and they are unconditional.
+ *
+ * Ink reports `Ctrl+W` as `input: 'w'` with `ctrl: true`, so before this change the keystroke fell
+ * through to the printable path and typed a literal `w` into the buffer. That is a defect on the
+ * default path, not only in screen-reader mode, so the fix is not gated on the mode — which makes it
+ * a change to today's behaviour, and these cases are where that change is pinned. What the mode adds
+ * is only the announcement, which is `InputArea`'s to render from `deleted` / `deletedScope`.
+ */
+describe('CLI-2004 — word and line deletion are default bindings, not mode-gated ones', () => {
+  it('Given Ctrl+W When applied Then the word before the cursor is deleted, not a "w" typed', () => {
+    const result = applyCjkTextInput(
+      createCjkTextInputFlowState('hello world'),
+      'w',
+      { ctrl: true },
+      { canPaste: true },
+    );
+
+    expect(result.state).toMatchObject({ value: 'hello ', cursor: 6 });
+    expect(result.effect).toEqual({
+      type: 'change',
+      value: 'hello ',
+      deleted: 'world',
+      deletedScope: 'word',
+    });
+  });
+
+  it('Given Ctrl+W with trailing spaces Then the spaces go with the word, as every shell does', () => {
+    const result = applyCjkTextInput(
+      createCjkTextInputFlowState('one two   '),
+      'w',
+      { ctrl: true },
+      { canPaste: true },
+    );
+
+    expect(result.state.value).toBe('one ');
+    expect(result.effect).toMatchObject({ deleted: 'two   ', deletedScope: 'word' });
+  });
+
+  it('Given Ctrl+U When applied Then everything before the cursor is deleted', () => {
+    const state = { ...createCjkTextInputFlowState('abc def'), cursor: 4 };
+
+    const result = applyCjkTextInput(state, 'u', { ctrl: true }, { canPaste: true });
+
+    expect(result.state).toMatchObject({ value: 'def', cursor: 0 });
+    expect(result.effect).toEqual({
+      type: 'change',
+      value: 'def',
+      deleted: 'abc ',
+      deletedScope: 'line',
+    });
+  });
+
+  it('Given a plain "w" with no ctrl Then it is still typed', () => {
+    const result = applyCjkTextInput(
+      createCjkTextInputFlowState('ne'),
+      'w',
+      {},
+      { canPaste: true },
+    );
+
+    expect(result.state.value).toBe('new');
+    expect(result.effect).toEqual({ type: 'change', value: 'new' });
+  });
+
+  it('Given the cursor at the start Then either deletion is a no-op rather than an empty change', () => {
+    const state = createCjkTextInputFlowState('');
+
+    expect(applyCjkTextInput(state, 'w', { ctrl: true }, { canPaste: true }).effect).toEqual({
+      type: 'none',
+    });
+    expect(applyCjkTextInput(state, 'u', { ctrl: true }, { canPaste: true }).effect).toEqual({
+      type: 'none',
+    });
+  });
+});

package/src/__tests__/cjk-text-input.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Tests for CjkTextInput pure utility functions.
+ *
+ * These test the input filtering and insertion logic extracted from
+ * the React component, without requiring Ink/React rendering.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  filterPrintable,
+  insertAtCursor,
+  displayOffset,
+  charIndexAtDisplayOffset,
+} from '../flows/cjk-text-input-flow.js';
+
+describe('filterPrintable', () => {
+  it('returns empty string for null input', () => {
+    expect(filterPrintable(null)).toBe('');
+  });
+
+  it('returns empty string for undefined input', () => {
+    expect(filterPrintable(undefined)).toBe('');
+  });
+
+  it('returns empty string for empty string', () => {
+    expect(filterPrintable('')).toBe('');
+  });
+
+  it('passes through normal ASCII text', () => {
+    expect(filterPrintable('hello')).toBe('hello');
+  });
+
+  it('passes through Korean characters', () => {
+    expect(filterPrintable('안녕하세요')).toBe('안녕하세요');
+  });
+
+  it('passes through emoji', () => {
+    expect(filterPrintable('🎉')).toBe('🎉');
+  });
+
+  it('filters out null byte', () => {
+    expect(filterPrintable('\x00')).toBe('');
+  });
+
+  it('filters out escape character', () => {
+    expect(filterPrintable('\x1b')).toBe('');
+  });
+
+  it('filters out DEL character', () => {
+    expect(filterPrintable('\x7f')).toBe('');
+  });
+
+  it('filters out mixed control characters, keeps printable', () => {
+    expect(filterPrintable('\x01hello\x02world\x7f')).toBe('helloworld');
+  });
+
+  it('returns empty when input is only control characters', () => {
+    expect(filterPrintable('\x00\x01\x02\x03\x1f\x7f')).toBe('');
+  });
+
+  it('handles tab character (0x09) — filtered as control', () => {
+    expect(filterPrintable('\t')).toBe('');
+  });
+
+  it('handles newline (0x0a) — filtered as control', () => {
+    expect(filterPrintable('\n')).toBe('');
+  });
+});
+
+describe('insertAtCursor', () => {
+  it('inserts at the beginning', () => {
+    const result = insertAtCursor('world', 0, 'hello ');
+    expect(result.value).toBe('hello world');
+    expect(result.cursor).toBe(6);
+  });
+
+  it('inserts at the end', () => {
+    const result = insertAtCursor('hello', 5, ' world');
+    expect(result.value).toBe('hello world');
+    expect(result.cursor).toBe(11);
+  });
+
+  it('inserts in the middle', () => {
+    const result = insertAtCursor('helo', 3, 'l');
+    expect(result.value).toBe('hello');
+    expect(result.cursor).toBe(4);
+  });
+
+  it('inserts into empty string', () => {
+    const result = insertAtCursor('', 0, 'abc');
+    expect(result.value).toBe('abc');
+    expect(result.cursor).toBe(3);
+  });
+
+  it('handles multi-character paste', () => {
+    const result = insertAtCursor('ac', 1, 'bb');
+    expect(result.value).toBe('abbc');
+    expect(result.cursor).toBe(3);
+  });
+
+  it('handles Korean character insertion', () => {
+    const result = insertAtCursor('안세요', 1, '녕하');
+    expect(result.value).toBe('안녕하세요');
+    expect(result.cursor).toBe(3);
+  });
+
+  it('handles emoji insertion', () => {
+    const result = insertAtCursor('hello world', 6, '🎉 ');
+    expect(result.value).toBe('hello 🎉 world');
+    expect(result.cursor).toBe(9);
+  });
+});
+
+describe('displayOffset', () => {
+  it('returns 0 for charIndex 0', () => {
+    expect(displayOffset([...'hello'], 0, 10)).toBe(0);
+  });
+
+  it('returns char count for ASCII within one line', () => {
+    expect(displayOffset([...'hello'], 3, 10)).toBe(3);
+  });
+
+  it('accumulates across wrap boundary', () => {
+    // "abcde" width 3: offset at index 4 = 4 (abc on line 0, de on line 1)
+    expect(displayOffset([...'abcde'], 4, 3)).toBe(4);
+  });
+
+  it('cursor before CJK char is at end of previous content', () => {
+    // "abcd한" width 5: cursor before "한" is at col 4 on line 0
+    // gap happens when "한" renders, not at cursor position
+    expect(displayOffset([...'abcd한'], 4, 5)).toBe(4);
+    // cursor after "한": 4(gap included) + 2 = 7 → but via offset: gap is at render
+    expect(displayOffset([...'abcd한'], 5, 5)).toBe(7);
+  });
+
+  it('handles pure CJK', () => {
+    // "한글" width 5: "한"=2, "글"=2 → total 4, fits on one line
+    expect(displayOffset([...'한글'], 2, 5)).toBe(4);
+  });
+
+  it('handles CJK wrapping', () => {
+    // "한글테" width 5: cursor before "테" is after "글" (offset 4)
+    // "테" doesn't fit at col 4, but cursor is BEFORE the wrap
+    expect(displayOffset([...'한글테'], 2, 5)).toBe(4);
+    // cursor after "테": gap(1) + 2 = offset 7
+    expect(displayOffset([...'한글테'], 3, 5)).toBe(7);
+  });
+});
+
+describe('charIndexAtDisplayOffset', () => {
+  it('returns 0 for offset 0', () => {
+    expect(charIndexAtDisplayOffset([...'hello'], 0, 10)).toBe(0);
+  });
+
+  it('finds correct index for ASCII', () => {
+    expect(charIndexAtDisplayOffset([...'hello'], 3, 10)).toBe(3);
+  });
+
+  it('returns text length when offset exceeds text', () => {
+    expect(charIndexAtDisplayOffset([...'hi'], 100, 10)).toBe(2);
+  });
+
+  it('round-trips with displayOffset for ASCII', () => {
+    const text = 'abcdefghij';
+    const chars = [...text];
+    const width = 4;
+    for (let i = 0; i <= chars.length; i++) {
+      const off = displayOffset(chars, i, width);
+      expect(charIndexAtDisplayOffset(chars, off, width)).toBe(i);
+    }
+  });
+
+  it('round-trips with displayOffset for CJK', () => {
+    const text = '한글테스트';
+    const chars = [...text];
+    const width = 5;
+    for (let i = 0; i <= chars.length; i++) {
+      const off = displayOffset(chars, i, width);
+      expect(charIndexAtDisplayOffset(chars, off, width)).toBe(i);
+    }
+  });
+
+  it('up arrow simulation: offset - width gives previous line position', () => {
+    // "abcdef" width 3: line 0 = "abc", line 1 = "def"
+    // cursor at index 4 (line 1, col 1) → offset = 4
+    // offset - 3 = 1 → charIndex 1 (line 0, col 1)
+    const chars = [...'abcdef'];
+    const off = displayOffset(chars, 4, 3);
+    expect(charIndexAtDisplayOffset(chars, off - 3, 3)).toBe(1);
+  });
+});

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

@@ -0,0 +1,107 @@
+/**
+ * TEST-007 / TERM-003 + TERM-004: `/shell` and `/editor` through a real terminal handoff, end-to-end
+ * in a PTY. Drives `fixtures/command-handoff-driver.tsx` (real executors + real
+ * `TerminalHandoffController`). Proves on a real TTY that the child (subshell / `$EDITOR`) receives
+ * the driver's keystrokes and the command returns cleanly — the behavior only a PTY can validate
+ * (the session command-pipeline path is covered by the framework functional tests with a fake
+ * handoff).
+ */
+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/command-handoff-driver.tsx', import.meta.url));
+const FAKE_EDITOR = fileURLToPath(new URL('./fixtures/fake-editor.sh', 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 });
+});
+
+interface IResult {
+  success: boolean;
+  message: string;
+  exitCode?: number;
+}
+
+function readResult(outputPath: string): IResult {
+  return JSON.parse(readFileSync(outputPath, 'utf8')) as IResult;
+}
+
+describe('command handoff PTY E2E', () => {
+  it(
+    '/shell runs a one-shot command on the real terminal and returns its exit code',
+    async () => {
+      const dir = realpathSync(mkdtempSync(join(tmpdir(), 'robota-shell-pty-')));
+      tempDirs.push(dir);
+      const outputPath = join(dir, 'result.json');
+      const session = spawnPtyFixture(FIXTURE, {
+        argv: ['shell', outputPath, 'IFS= read -r line; printf "SHELL_GOT:[%s]\\n" "$line"'],
+        cwd: PACKAGE_DIR,
+        // HARNESS-025: isolated HOME — the subshell must not read the developer's `~` (a real
+        // shell rc there would otherwise change what the handoff child does).
+        env: createPtyEnv(),
+      });
+      sessions.push(session);
+
+      await session.waitFor('READY canHandoff=true', 10_000);
+      await new Promise((resolve) => setTimeout(resolve, 300));
+      await session.sendKeys('shell-input', 10);
+      session.write('\r');
+      await session.waitFor('CMD_DONE', 10_000);
+      session.write('r');
+      await session.waitFor('INPUT_AFTER_HANDOFF r', 10_000);
+      expect(await session.expectExit(5_000)).toBe(0);
+
+      expect(session.snapshot()).toContain('SHELL_GOT:[shell-input]');
+      const result = readResult(outputPath);
+      expect(result.success).toBe(true);
+      expect(result.exitCode).toBe(0);
+    },
+    TEST_TIMEOUT_MS,
+  );
+
+  it(
+    '/editor opens $EDITOR on the real terminal and round-trips the composed text',
+    async () => {
+      const dir = realpathSync(mkdtempSync(join(tmpdir(), 'robota-editor-pty-')));
+      tempDirs.push(dir);
+      const outputPath = join(dir, 'result.json');
+      const session = spawnPtyFixture(FIXTURE, {
+        argv: ['editor', outputPath, ''],
+        cwd: PACKAGE_DIR,
+        // HARNESS-025: isolated HOME — only the EDITOR override comes from the test, so a real
+        // `~/.selected_editor` (or similar) on the host cannot influence the assertion.
+        env: createPtyEnv({ EDITOR: `sh ${FAKE_EDITOR}` }),
+      });
+      sessions.push(session);
+
+      await session.waitFor('READY canHandoff=true', 10_000);
+      await new Promise((resolve) => setTimeout(resolve, 300));
+      await session.sendKeys('composed-in-editor', 10);
+      session.write('\r');
+      await session.waitFor('CMD_DONE', 10_000);
+      session.write('r');
+      await session.waitFor('INPUT_AFTER_HANDOFF r', 10_000);
+      expect(await session.expectExit(5_000)).toBe(0);
+
+      const result = readResult(outputPath);
+      expect(result.success).toBe(true);
+      expect(result.message).toBe('composed-in-editor');
+    },
+    TEST_TIMEOUT_MS,
+  );
+});

package/src/__tests__/command-output-summary.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest';
+import { formatCommandOutputSummary } from '../command-output-summary.js';
+
+describe('formatCommandOutputSummary', () => {
+  it('renders short command output inline without transcript decoration', () => {
+    const summary = formatCommandOutputSummary({
+      toolName: 'Bash',
+      firstArg: 'echo hello',
+      isRunning: false,
+      result: 'success',
+      toolResultData: JSON.stringify({ success: true, output: 'hello\n', exitCode: 0 }),
+    });
+
+    expect(summary).toMatchObject({
+      status: 'success',
+      statusLabel: 'ok',
+      previewLines: ['hello'],
+      omittedLineCount: 0,
+      transcriptHint: undefined,
+    });
+  });
+
+  it('renders long command output with a bounded preview and transcript hint', () => {
+    const output = Array.from({ length: 8 }, (_, index) => `line-${index + 1}`).join('\n');
+    const summary = formatCommandOutputSummary({
+      toolName: 'Bash',
+      firstArg: 'pnpm test',
+      isRunning: false,
+      result: 'success',
+      toolResultData: JSON.stringify({ success: true, output, exitCode: 0 }),
+    });
+
+    expect(summary?.previewLines).toEqual(['line-1', 'line-2', 'line-3', 'line-4']);
+    expect(summary?.omittedLineCount).toBe(4);
+    expect(summary?.transcriptHint).toBe('... +4 lines (full output in session transcript)');
+  });
+
+  it('keeps stderr distinct when stdout and stderr are structured separately', () => {
+    const summary = formatCommandOutputSummary({
+      toolName: 'Bash',
+      firstArg: 'node script.js',
+      isRunning: false,
+      result: 'success',
+      toolResultData: JSON.stringify({
+        success: true,
+        stdout: 'ok',
+        stderr: 'warn',
+        exitCode: 0,
+      }),
+    });
+
+    expect(summary?.previewLines).toEqual(['ok', '[stderr] warn']);
+  });
+
+  it('marks non-zero exit codes as failed even when the tool transport succeeded', () => {
+    const summary = formatCommandOutputSummary({
+      toolName: 'Bash',
+      firstArg: 'exit 42',
+      isRunning: false,
+      result: 'success',
+      toolResultData: JSON.stringify({ success: true, output: '', exitCode: 42 }),
+    });
+
+    expect(summary?.status).toBe('error');
+    expect(summary?.statusLabel).toBe('exit 42');
+    expect(summary?.previewLines).toEqual([]);
+  });
+
+  it('renders no-output commands without dangling transcript hints', () => {
+    const summary = formatCommandOutputSummary({
+      toolName: 'Bash',
+      firstArg: 'true',
+      isRunning: false,
+      result: 'success',
+      toolResultData: JSON.stringify({ success: true, output: '', exitCode: 0 }),
+    });
+
+    expect(summary?.status).toBe('success');
+    expect(summary?.previewLines).toEqual([]);
+    expect(summary?.omittedLineCount).toBe(0);
+    expect(summary?.transcriptHint).toBeUndefined();
+  });
+
+  it('ignores non-command tools', () => {
+    const summary = formatCommandOutputSummary({
+      toolName: 'Read',
+      firstArg: 'file.ts',
+      isRunning: false,
+      result: 'success',
+      toolResultData: 'large file content',
+    });
+
+    expect(summary).toBeUndefined();
+  });
+});