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

package/src/__tests__/pty/spawn-pty.ts

@@ -0,0 +1,229 @@
+/**
+ * TUI-owned PTY harness (TEST-007; relocated internally by BOUNDARY-2655).
+ *
+ * One reusable pseudo-terminal driver for end-to-end tests. Spawns a process in a real PTY (via
+ * the prebuilt `@homebridge/node-pty-prebuilt-multiarch`, so Ink renders and reads input exactly as
+ * in a user terminal) and exposes per-key paced input plus marker/exit waiting. Two convenience
+ * spawners build on the core:
+ *
+ * - `spawnPty` — drive any command (e.g. the built CLI binary).
+ * - `spawnPtyFixture` — drive a TSX fixture through the `tsx/esm` import hook (no build step),
+ *   the pattern used for focused source-level E2E.
+ *
+ * Per-key pacing matters: a burst write is bundled by the terminal as a bracketed paste, which is the
+ * exact failure mode this harness exists to avoid.
+ */
+import { createRequire } from 'node:module';
+
+import { spawn } from '@homebridge/node-pty-prebuilt-multiarch';
+
+import { createPtyEnv } from './isolated-home.js';
+
+import type { IPty } from '@homebridge/node-pty-prebuilt-multiarch';
+
+// eslint-disable-next-line no-control-regex
+const ANSI_PATTERN = /\x1b\[[0-9;?]*[a-zA-Z]|\x1b\][^\x07]*\x07|\x1b[()][B0]|[\x00-\x08\x0b-\x1f]/g;
+
+const DEFAULT_PER_KEY_DELAY_MS = 35;
+const DEFAULT_WAIT_TIMEOUT_MS = 15_000;
+const DEFAULT_EXIT_TIMEOUT_MS = 10_000;
+const OUTPUT_TAIL_LENGTH = 2000;
+/** CORE-023: grace before escalating a lingering PTY child from SIGTERM to SIGKILL. */
+const PTY_KILL_GRACE_MS = 2000;
+
+export interface IPtyRunOptions {
+  command: string;
+  args: string[];
+  cwd: string;
+  /**
+   * Environment for the child. Defaults to {@link createPtyEnv} — a minimal env with an ISOLATED
+   * HOME. Build overrides with `createPtyEnv({ ... })` rather than by hand, so a caller cannot
+   * reintroduce the real `process.env.HOME` (which makes the suite depend on the host's `~`).
+   */
+  env?: NodeJS.ProcessEnv;
+  cols?: number;
+  rows?: number;
+}
+
+export interface IPtyRunSession {
+  /** Type text one key at a time (default 35ms/key — human-ish, avoids paste bundling). */
+  sendKeys(text: string, perKeyDelayMs?: number): Promise<void>;
+  /** Write bytes verbatim (no pacing) — for control sequences / single keystrokes. */
+  write(data: string): void;
+  /** Press Enter as a single keystroke (with small settle on either side). */
+  pressEnter(): Promise<void>;
+  /** Wait until the ANSI-stripped output matches; throws with a snapshot on timeout. */
+  waitFor(pattern: RegExp | string, timeoutMs?: number): Promise<void>;
+  /**
+   * Current length of the ANSI-stripped output — a mark for `waitForSince`/`snapshotSince`.
+   * The stripped output is CUMULATIVE (a transcript, not the current screen): a plain `waitFor`
+   * also matches old frames and the echo of your own typed input. Take a mark before acting, then
+   * assert only on what arrived after it.
+   */
+  outputOffset(): number;
+  /** Like `waitFor`, but matches only output that arrived after the `since` mark. */
+  waitForSince(since: number, pattern: RegExp | string, timeoutMs?: number): Promise<void>;
+  /** ANSI-stripped output that arrived after the `since` mark. */
+  snapshotSince(since: number): string;
+  /** Current ANSI-stripped output. */
+  snapshot(): string;
+  /** Current raw (un-stripped) output. */
+  raw(): string;
+  /** Wait for process exit; throws with a snapshot on timeout. */
+  expectExit(timeoutMs?: number): Promise<number>;
+  /** Force-kill / cleanup (no-op if already exited). */
+  dispose(): void;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function toRegExp(pattern: RegExp | string): RegExp {
+  if (pattern instanceof RegExp) return pattern;
+  // Escape regex metacharacters so a plain string is matched literally.
+  return new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+}
+
+/** Spawn any command in a real PTY and return a driving session. */
+export function spawnPty(options: IPtyRunOptions): IPtyRunSession {
+  let output = '';
+  let exitCode: number | undefined;
+
+  const pty: IPty = spawn(options.command, options.args, {
+    name: 'xterm-256color',
+    cols: options.cols ?? 100,
+    rows: options.rows ?? 32,
+    cwd: options.cwd,
+    // HARNESS-025: the default HOME is a throwaway directory, never the developer's real one — a
+    // Configured state and HOME are both isolated so the run cannot depend on the developer profile.
+    env: createPtyEnv(options.env ?? {}),
+  });
+
+  pty.onData((data) => {
+    output += data;
+  });
+  pty.onExit(({ exitCode: code }) => {
+    exitCode = code;
+  });
+
+  const stripped = (): string => output.replace(ANSI_PATTERN, '');
+
+  return {
+    async sendKeys(text: string, perKeyDelayMs = DEFAULT_PER_KEY_DELAY_MS): Promise<void> {
+      for (const ch of text) {
+        pty.write(ch);
+        await sleep(perKeyDelayMs);
+      }
+    },
+    write(data: string): void {
+      pty.write(data);
+    },
+    async pressEnter(): Promise<void> {
+      await sleep(120);
+      pty.write('\r');
+      await sleep(120);
+    },
+    async waitFor(pattern: RegExp | string, timeoutMs = DEFAULT_WAIT_TIMEOUT_MS): Promise<void> {
+      const regex = toRegExp(pattern);
+      const deadline = Date.now() + timeoutMs;
+      while (Date.now() < deadline) {
+        if (regex.test(stripped())) return;
+        if (exitCode !== undefined && regex.test(stripped())) return;
+        await sleep(50);
+      }
+      throw new Error(
+        `PTY waitFor timeout (${timeoutMs}ms) for ${String(regex)}\n--- snapshot ---\n${stripped().slice(-OUTPUT_TAIL_LENGTH)}`,
+      );
+    },
+    outputOffset(): number {
+      return stripped().length;
+    },
+    async waitForSince(
+      since: number,
+      pattern: RegExp | string,
+      timeoutMs = DEFAULT_WAIT_TIMEOUT_MS,
+    ): Promise<void> {
+      const regex = toRegExp(pattern);
+      const deadline = Date.now() + timeoutMs;
+      while (Date.now() < deadline) {
+        if (regex.test(stripped().slice(since))) return;
+        await sleep(50);
+      }
+      throw new Error(
+        `PTY waitForSince timeout (${timeoutMs}ms) for ${String(regex)} after offset ${since}\n--- snapshot since mark ---\n${stripped().slice(since).slice(-OUTPUT_TAIL_LENGTH)}`,
+      );
+    },
+    snapshotSince(since: number): string {
+      return stripped().slice(since);
+    },
+    snapshot: stripped,
+    raw: (): string => output,
+    async expectExit(timeoutMs = DEFAULT_EXIT_TIMEOUT_MS): Promise<number> {
+      const deadline = Date.now() + timeoutMs;
+      while (Date.now() < deadline) {
+        if (exitCode !== undefined) return exitCode;
+        await sleep(50);
+      }
+      throw new Error(
+        `PTY process did not exit within ${timeoutMs}ms\n--- snapshot ---\n${stripped().slice(-OUTPUT_TAIL_LENGTH)}`,
+      );
+    },
+    dispose(): void {
+      if (exitCode !== undefined) return;
+      try {
+        pty.kill();
+      } catch {
+        // allow-fallback: process already exited — kill on a dead pty is a no-op by design
+      }
+      // CORE-023: mirror the killProcessTree escalation pattern — a child that ignores SIGTERM
+      // is force-killed after the grace window. Keep this test-local lifecycle implementation
+      // independent of @robota-sdk/agent-process.
+      const graceTimer = setTimeout(() => {
+        if (exitCode === undefined) {
+          try {
+            pty.kill('SIGKILL');
+          } catch {
+            // allow-fallback: process exited during the grace window — SIGKILL is a no-op
+          }
+        }
+      }, PTY_KILL_GRACE_MS);
+      graceTimer.unref?.();
+    },
+  };
+}
+
+export interface ISpawnFixtureOptions {
+  /** Extra argv passed to the fixture after its path (e.g. an output JSON path). */
+  argv?: string[];
+  cwd: string;
+  env?: NodeJS.ProcessEnv;
+  cols?: number;
+  rows?: number;
+}
+
+let tsxEsmHookPath: string | undefined;
+function resolveTsxEsmHook(): string {
+  // Lazily resolved so built-CLI consumers (which never run a TSX fixture) don't require tsx.
+  tsxEsmHookPath ??= createRequire(import.meta.url).resolve('tsx/esm');
+  return tsxEsmHookPath;
+}
+
+/**
+ * Spawn a TSX fixture inside a PTY via the `tsx/esm` import hook (no build step). The fixture's own
+ * relative imports resolve from its absolute path; `cwd` controls module resolution for bare
+ * specifiers (point it at the package dir or repo root).
+ */
+export function spawnPtyFixture(
+  fixturePath: string,
+  options: ISpawnFixtureOptions,
+): IPtyRunSession {
+  return spawnPty({
+    command: process.execPath,
+    args: ['--import', resolveTsxEsmHook(), fixturePath, ...(options.argv ?? [])],
+    cwd: options.cwd,
+    ...(options.env ? { env: options.env } : {}),
+    ...(options.cols !== undefined ? { cols: options.cols } : {}),
+    ...(options.rows !== undefined ? { rows: options.rows } : {}),
+  });
+}

package/src/__tests__/pty/terminal-handoff.ptytest.ts

@@ -0,0 +1,79 @@
+/**
+ * TERM-003 / TEST-007: real-binary terminal-handoff evidence.
+ *
+ * Runs in the dedicated PTY vitest project (vitest.pty.config.ts) against the BUILT CLI binary
+ * (`pnpm --filter @robota-sdk/agent-cli build` first). Unlike the source-level fixture E2E
+ * (`terminal-handoff-pty-e2e` / `command-handoff-pty-e2e`), this drives the WHOLE user path —
+ * real CLI → real command pipeline → real `TerminalHandoffController` injected by `render.tsx` →
+ * `/shell` — through a real pseudo-terminal, simulating a user typing. It is automated
+ * user-execution-level proof: the child runs on the real terminal during the handoff and the TUI
+ * frame restores afterward (machine proxy for "no stale frame / clean resume").
+ */
+
+import { mkdtempSync, rmSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { spawnTui, writeTuiProviderSettings } from './pty-driver.js';
+
+import type { IPtySession } from './pty-driver.js';
+
+describe('terminal handoff through the real binary (TERM-003)', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'agent-handoff-pty-')));
+    writeTuiProviderSettings(projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it('TC-09: /shell runs a one-shot command on the real terminal and the TUI restores', async () => {
+    session = spawnTui({ projectDir, homeDir: join(projectDir, 'home') });
+
+    // Boot.
+    await session.waitFor(/Type a message or \/help/);
+    await session.waitFor(/Idle/);
+
+    // Run a one-shot shell command. A user-typed command is not permission-gated (that gate is for
+    // model/agent-invoked actions), so it runs directly through the handoff.
+    await session.sendKeys('/shell echo HANDOFF_REAL_OK');
+    await session.pressEnter();
+
+    // The child's output appears on the real (inherited) terminal during the handoff.
+    await session.waitFor(/HANDOFF_REAL_OK/, 20_000);
+
+    // The TUI reclaims the screen: the prompt frame redraws (clean resume, no hang).
+    await session.waitFor(/Type a message or \/help/, 20_000);
+  }, 60_000);
+
+  it('TC-04/TC-01: committed history (Static) is not re-printed after a /shell handoff (SCREEN-010 × TERM-002)', async () => {
+    session = spawnTui({ projectDir, homeDir: join(projectDir, 'home') });
+
+    await session.waitFor(/Type a message or \/help/);
+    await session.waitFor(/Idle/);
+
+    // The startup banner is committed to the terminal scrollback via a single Ink <Static> (TC-01).
+    // Count its version line; if the handoff resume re-emitted committed history, it would re-print.
+    const versionRe = /v\d+\.\d+\.\d+/g;
+    const beforeCount = (session.snapshot().match(versionRe) ?? []).length;
+    expect(beforeCount).toBeGreaterThanOrEqual(1);
+
+    await session.sendKeys('/shell echo HANDOFF_OK');
+    await session.pressEnter();
+    await session.waitFor(/HANDOFF_OK/, 20_000);
+    await session.waitFor(/Type a message or \/help/, 20_000);
+
+    // SCREEN-010 keeps <Static> mounted at a stable tree position across suspend/resume, so the
+    // committed banner is NOT re-printed on return (TC-04).
+    const afterCount = (session.snapshot().match(versionRe) ?? []).length;
+    expect(afterCount).toBe(beforeCount);
+  }, 60_000);
+});

package/src/__tests__/pty/trust-prompt.ptytest.ts

@@ -0,0 +1,134 @@
+/**
+ * Issue #3268 — an interactive start in an untrusted repository asks whether to trust it, on the
+ * BUILT binary in a real PTY. A yes records the grant and starts Trusted, so the next start does not
+ * ask; a no starts Restricted and records nothing, so the next start asks again.
+ *
+ * Runs under `test:pty` against the built CLI (`pnpm --filter @robota-sdk/agent-cli build` first).
+ */
+
+import { execFileSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { spawnTui } from './pty-driver.js';
+
+import type { IPtySession } from './pty-driver.js';
+
+const WAIT_MS = 20_000;
+const CASE_TIMEOUT_MS = 120_000;
+const QUESTION = /Trust this folder\? \[y\/N\]/;
+const READY = /Type a message or \/help/;
+
+interface IFixture {
+  readonly root: string;
+  readonly home: string;
+  readonly repo: string;
+}
+
+function makeFixture(): IFixture {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), 'agent-trust-prompt-')));
+  const home = join(root, 'home');
+  const repo = join(root, 'repo');
+  mkdirSync(join(home, 'state'), { recursive: true });
+  // Skip the first-run welcome and provider setup: neither is what this scenario observes.
+  writeFileSync(join(home, 'state', 'onboarded'), new Date().toISOString(), 'utf8');
+  writeFileSync(
+    join(home, 'state', 'settings.json'),
+    JSON.stringify({
+      currentProvider: 'anthropic',
+      providers: {
+        anthropic: { type: 'anthropic', model: 'claude-test-model', apiKey: 'pty-dummy-key' },
+      },
+    }),
+    'utf8',
+  );
+  execFileSync('git', ['init', '-q', repo]);
+  return { root, home, repo };
+}
+
+function trustedGrants(fixture: IFixture): number {
+  const store = join(fixture.home, 'state', 'workspace-trust.json');
+  if (!existsSync(store)) return 0;
+  const parsed = JSON.parse(readFileSync(store, 'utf8')) as { grants: { state: string }[] };
+  return parsed.grants.filter((grant) => grant.state === 'trusted').length;
+}
+
+async function answerAndExit(session: IPtySession, answer: 'y' | 'n'): Promise<void> {
+  await session.waitFor(QUESTION, WAIT_MS);
+  await session.sendKeys(answer);
+  await session.pressEnter();
+  await session.waitFor(READY, WAIT_MS);
+  await session.sendKeys('/exit');
+  await session.pressEnter();
+  await session.waitFor(/Exit the session\?/, WAIT_MS);
+  await session.pressEnter();
+  await session.expectExit(WAIT_MS);
+}
+
+describe('the trust question at an interactive start (issue #3268)', () => {
+  let fixture: IFixture | undefined;
+  let session: IPtySession | undefined;
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    if (fixture) rmSync(fixture.root, { recursive: true, force: true });
+    fixture = undefined;
+  });
+
+  it(
+    'a yes records the grant, and the next start is Trusted without asking',
+    async () => {
+      fixture = makeFixture();
+      session = spawnTui({ projectDir: fixture.repo, homeDir: fixture.home });
+      await answerAndExit(session, 'y');
+      expect(trustedGrants(fixture)).toBe(1);
+
+      session = spawnTui({ projectDir: fixture.repo, homeDir: fixture.home });
+      await session.waitFor(READY, WAIT_MS);
+      expect(session.snapshot()).not.toMatch(QUESTION);
+    },
+    CASE_TIMEOUT_MS,
+  );
+
+  it.each([
+    ['--safe-mode', ['--safe-mode']],
+    // A resumed or continued session keeps the store it was saved in, so it is not asked.
+    ['--continue', ['--continue']],
+  ])(
+    'does not ask with %s',
+    async (_case, args) => {
+      fixture = makeFixture();
+      session = spawnTui({ projectDir: fixture.repo, homeDir: fixture.home, args: [...args] });
+      await session.waitFor(READY, WAIT_MS);
+      expect(session.snapshot()).not.toMatch(QUESTION);
+      expect(trustedGrants(fixture)).toBe(0);
+    },
+    CASE_TIMEOUT_MS,
+  );
+
+  it(
+    'a no starts Restricted, records nothing, and the next start asks again',
+    async () => {
+      fixture = makeFixture();
+      session = spawnTui({ projectDir: fixture.repo, homeDir: fixture.home });
+      await answerAndExit(session, 'n');
+      expect(trustedGrants(fixture)).toBe(0);
+
+      session = spawnTui({ projectDir: fixture.repo, homeDir: fixture.home });
+      await session.waitFor(QUESTION, WAIT_MS);
+    },
+    CASE_TIMEOUT_MS,
+  );
+});

package/src/__tests__/pty/tui-pty.ptytest.ts

@@ -0,0 +1,65 @@
+/**
+ * Real-PTY TUI suites (CLI-074 TC-07/08).
+ *
+ * Runs in the dedicated PTY vitest project (vitest.pty.config.ts) against the
+ * BUILT CLI binary — `pnpm --filter @robota-sdk/agent-cli build` first.
+ */
+
+import { mkdtempSync, rmSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { spawnTui, writeTuiProviderSettings } from './pty-driver.js';
+
+import type { IPtySession } from './pty-driver.js';
+
+describe('TUI through a real PTY (CLI-074)', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'agent-pty-')));
+    writeTuiProviderSettings(projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it('TC-07: boots, opens slash autocomplete, and executes /help as a command', async () => {
+    session = spawnTui({ projectDir, homeDir: join(projectDir, 'home') });
+
+    // Boot: prompt + status bar render.
+    await session.waitFor(/Type a message or \/help/);
+    await session.waitFor(/Idle/);
+
+    // '/' opens the autocomplete dropdown listing commands.
+    await session.sendKeys('/');
+    await session.waitFor(/\/help\s+Show available commands/);
+
+    // Typing the rest at human key rate must stay a command, not a paste.
+    await session.sendKeys('help');
+    await session.pressEnter();
+    await session.waitFor(/Available commands|\/cost|\/clear/i, 20_000);
+    expect(session.snapshot()).not.toContain('[Pasted text');
+  }, 60_000);
+
+  it('TC-08: /exit confirms then reaches process exit within 10s', async () => {
+    session = spawnTui({ projectDir, homeDir: join(projectDir, 'home') });
+    await session.waitFor(/Type a message or \/help/);
+
+    await session.sendKeys('/exit');
+    await session.pressEnter();
+
+    // CMD-004: /exit now asks for confirmation; answer Yes (the default-highlighted option).
+    await session.waitFor(/Exit the session\?/);
+    await session.pressEnter();
+
+    const exitCode = await session.expectExit(10_000);
+    expect(exitCode).toBe(0);
+  }, 60_000);
+});

package/src/__tests__/pty-driver-dispose.test.ts

@@ -0,0 +1,43 @@
+/**
+ * INFRA-026 TC-01 — `killAndAwaitExit` (the compose behind the PTY driver's `disposeAsync`) awaits
+ * ACTUAL child exit and rejects loudly on non-exit. Unit-level with a fake session (no real PTY), so
+ * it runs in the default vitest project rather than the `*.ptytest` built-CLI project.
+ */
+import { describe, expect, it, vi } from 'vitest';
+
+import { killAndAwaitExit } from './pty/pty-driver.js';
+
+describe('killAndAwaitExit (INFRA-026 teardown compose)', () => {
+  it('signals the child (dispose) then resolves once expectExit resolves', async () => {
+    const order: string[] = [];
+    const session = {
+      dispose: vi.fn(() => {
+        order.push('dispose');
+      }),
+      expectExit: vi.fn(async (): Promise<number> => {
+        order.push('expectExit');
+        return 0;
+      }),
+    };
+
+    await expect(killAndAwaitExit(session, 1000)).resolves.toBeUndefined();
+
+    expect(session.dispose).toHaveBeenCalledTimes(1);
+    expect(session.expectExit).toHaveBeenCalledWith(1000);
+    // dispose must be signalled BEFORE we await exit.
+    expect(order).toEqual(['dispose', 'expectExit']);
+  });
+
+  it('rejects (does not swallow) when the child does not exit within the timeout', async () => {
+    const session = {
+      dispose: vi.fn(),
+      expectExit: vi.fn(async (): Promise<number> => {
+        throw new Error('PTY process did not exit within 1000ms');
+      }),
+    };
+
+    await expect(killAndAwaitExit(session, 1000)).rejects.toThrow(/did not exit/);
+    // Still signalled the child — the failure is a loud teardown defect, not a masked one.
+    expect(session.dispose).toHaveBeenCalledTimes(1);
+  });
+});