mirror of
https://github.com/oven-sh/bun
synced 2026-02-02 15:08:46 +00:00
feat: add Bun.Terminal API for pseudo-terminal (PTY) support (#25415)
## Summary
This PR adds a new `Bun.Terminal` API for creating and managing
pseudo-terminals (PTYs), enabling interactive terminal applications in
Bun.
### Features
- **Standalone Terminal**: Create PTYs directly with `new
Bun.Terminal(options)`
- **Spawn Integration**: Spawn processes with PTY attached via
`Bun.spawn({ terminal: options })`
- **Full PTY Control**: Write data, resize, set raw mode, and handle
callbacks
## Examples
### Basic Terminal with Spawn (Recommended)
```typescript
const proc = Bun.spawn(["bash"], {
terminal: {
cols: 80,
rows: 24,
data(terminal, data) {
// Handle output from the terminal
process.stdout.write(data);
},
exit(terminal, code, signal) {
console.log(`Process exited with code ${code}`);
},
},
});
// Write commands to the terminal
proc.terminal.write("echo Hello from PTY!\n");
proc.terminal.write("exit\n");
await proc.exited;
proc.terminal.close();
```
### Interactive Shell
```typescript
// Create an interactive shell that mirrors to stdout
const proc = Bun.spawn(["bash", "-i"], {
terminal: {
cols: process.stdout.columns || 80,
rows: process.stdout.rows || 24,
data(term, data) {
process.stdout.write(data);
},
},
});
// Forward stdin to the terminal
process.stdin.setRawMode(true);
for await (const chunk of process.stdin) {
proc.terminal.write(chunk);
}
```
### Running Interactive Programs (vim, htop, etc.)
```typescript
const proc = Bun.spawn(["vim", "file.txt"], {
terminal: {
cols: process.stdout.columns,
rows: process.stdout.rows,
data(term, data) {
process.stdout.write(data);
},
},
});
// Handle terminal resize
process.stdout.on("resize", () => {
proc.terminal.resize(process.stdout.columns, process.stdout.rows);
});
// Forward input
process.stdin.setRawMode(true);
for await (const chunk of process.stdin) {
proc.terminal.write(chunk);
}
```
### Capturing Colored Output
```typescript
const chunks: Uint8Array[] = [];
const proc = Bun.spawn(["ls", "--color=always"], {
terminal: {
data(term, data) {
chunks.push(data);
},
},
});
await proc.exited;
proc.terminal.close();
// Output includes ANSI color codes
const output = Buffer.concat(chunks).toString();
console.log(output);
```
### Standalone Terminal (Advanced)
```typescript
const terminal = new Bun.Terminal({
cols: 80,
rows: 24,
data(term, data) {
console.log("Received:", data.toString());
},
});
// Use terminal.stdin as the fd for child process stdio
const proc = Bun.spawn(["bash"], {
stdin: terminal.stdin,
stdout: terminal.stdin,
stderr: terminal.stdin,
});
terminal.write("echo hello\n");
// Clean up
terminal.close();
```
### Testing TTY Detection
```typescript
const proc = Bun.spawn([
"bun", "-e",
"console.log('isTTY:', process.stdout.isTTY)"
], {
terminal: {},
});
// Output: isTTY: true
```
## API
### `Bun.spawn()` with `terminal` option
```typescript
const proc = Bun.spawn(cmd, {
terminal: {
cols?: number, // Default: 80
rows?: number, // Default: 24
name?: string, // Default: "xterm-256color"
data?: (terminal: Terminal, data: Uint8Array) => void,
exit?: (terminal: Terminal, code: number, signal: string | null) => void,
drain?: (terminal: Terminal) => void,
}
});
// Access the terminal
proc.terminal.write(data);
proc.terminal.resize(cols, rows);
proc.terminal.setRawMode(enabled);
proc.terminal.close();
// Note: proc.stdin, proc.stdout, proc.stderr return null when terminal is used
```
### `new Bun.Terminal(options)`
```typescript
const terminal = new Bun.Terminal({
cols?: number,
rows?: number,
name?: string,
data?: (terminal, data) => void,
exit?: (terminal, code, signal) => void,
drain?: (terminal) => void,
});
terminal.stdin; // Slave fd (for child process)
terminal.stdout; // Master fd (for reading)
terminal.closed; // boolean
terminal.write(data);
terminal.resize(cols, rows);
terminal.setRawMode(enabled);
terminal.ref();
terminal.unref();
terminal.close();
await terminal[Symbol.asyncDispose]();
```
## Implementation Details
- Uses `openpty()` to create pseudo-terminal pairs
- Properly manages file descriptor lifecycle with reference counting
- Integrates with Bun's event loop via `BufferedReader` and
`StreamingWriter`
- Supports `await using` syntax for automatic cleanup
- POSIX only (Linux, macOS) - not available on Windows
## Test Results
- 80 tests passing
- Covers: construction, writing, reading, resize, raw mode, callbacks,
spawn integration, error handling, GC safety
## Changes
- `src/bun.js/api/bun/Terminal.zig` - Terminal implementation
- `src/bun.js/api/bun/Terminal.classes.ts` - Class definition for
codegen
- `src/bun.js/api/bun/subprocess.zig` - Added terminal field and getter
- `src/bun.js/api/bun/js_bun_spawn_bindings.zig` - Terminal option
parsing
- `src/bun.js/api/BunObject.classes.ts` - Terminal getter on Subprocess
- `packages/bun-types/bun.d.ts` - TypeScript types
- `docs/runtime/child-process.mdx` - Documentation
- `test/js/bun/terminal/terminal.test.ts` - Comprehensive tests
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Jarred Sumner <jarred@jarredsumner.com>
This commit is contained in:
robobun
@@ -315,6 +315,109 @@ if (typeof Bun !== "undefined") {
|
||||
|
||||
---
|
||||
|
||||
## Terminal (PTY) support
|
||||
|
||||
For interactive terminal applications, you can spawn a subprocess with a pseudo-terminal (PTY) attached using the `terminal` option. This makes the subprocess think it's running in a real terminal, enabling features like colored output, cursor movement, and interactive prompts.
|
||||
|
||||
```ts
|
||||
const proc = Bun.spawn(["bash"], {
|
||||
terminal: {
|
||||
cols: 80,
|
||||
rows: 24,
|
||||
data(terminal, data) {
|
||||
// Called when data is received from the terminal
|
||||
process.stdout.write(data);
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
// Write to the terminal
|
||||
proc.terminal.write("echo hello\n");
|
||||
|
||||
// Wait for the process to exit
|
||||
await proc.exited;
|
||||
|
||||
// Close the terminal
|
||||
proc.terminal.close();
|
||||
```
|
||||
|
||||
When the `terminal` option is provided:
|
||||
|
||||
- The subprocess sees `process.stdout.isTTY` as `true`
|
||||
- `stdin`, `stdout`, and `stderr` are all connected to the terminal
|
||||
- `proc.stdin`, `proc.stdout`, and `proc.stderr` return `null` — use the terminal instead
|
||||
- Access the terminal via `proc.terminal`
|
||||
|
||||
### Terminal options
|
||||
|
||||
| Option | Description | Default |
|
||||
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ |
|
||||
| `cols` | Number of columns | `80` |
|
||||
| `rows` | Number of rows | `24` |
|
||||
| `name` | Terminal type for PTY configuration (set `TERM` env var separately via `env` option) | `"xterm-256color"` |
|
||||
| `data` | Callback when data is received `(terminal, data) => void` | — |
|
||||
| `exit` | Callback when PTY stream closes (EOF or error). `exitCode` is PTY lifecycle status (0=EOF, 1=error), not subprocess exit code. Use `proc.exited` for process exit. | — |
|
||||
| `drain` | Callback when ready for more data `(terminal) => void` | — |
|
||||
|
||||
### Terminal methods
|
||||
|
||||
The `Terminal` object returned by `proc.terminal` has the following methods:
|
||||
|
||||
```ts
|
||||
// Write data to the terminal
|
||||
proc.terminal.write("echo hello\n");
|
||||
|
||||
// Resize the terminal
|
||||
proc.terminal.resize(120, 40);
|
||||
|
||||
// Set raw mode (disable line buffering and echo)
|
||||
proc.terminal.setRawMode(true);
|
||||
|
||||
// Keep event loop alive while terminal is open
|
||||
proc.terminal.ref();
|
||||
proc.terminal.unref();
|
||||
|
||||
// Close the terminal
|
||||
proc.terminal.close();
|
||||
```
|
||||
|
||||
### Reusable Terminal
|
||||
|
||||
You can create a terminal independently and reuse it across multiple subprocesses:
|
||||
|
||||
```ts
|
||||
await using terminal = new Bun.Terminal({
|
||||
cols: 80,
|
||||
rows: 24,
|
||||
data(term, data) {
|
||||
process.stdout.write(data);
|
||||
},
|
||||
});
|
||||
|
||||
// Spawn first process
|
||||
const proc1 = Bun.spawn(["echo", "first"], { terminal });
|
||||
await proc1.exited;
|
||||
|
||||
// Reuse terminal for another process
|
||||
const proc2 = Bun.spawn(["echo", "second"], { terminal });
|
||||
await proc2.exited;
|
||||
|
||||
// Terminal is closed automatically by `await using`
|
||||
```
|
||||
|
||||
When passing an existing `Terminal` object:
|
||||
|
||||
- The terminal can be reused across multiple spawns
|
||||
- You control when to close the terminal
|
||||
- The `exit` callback fires when you call `terminal.close()`, not when each subprocess exits
|
||||
- Use `proc.exited` to detect individual subprocess exits
|
||||
|
||||
This is useful for running multiple commands in sequence through the same terminal session.
|
||||
|
||||
<Note>Terminal support is only available on POSIX systems (Linux, macOS). It is not available on Windows.</Note>
|
||||
|
||||
---
|
||||
|
||||
## Blocking API (`Bun.spawnSync()`)
|
||||
|
||||
Bun provides a synchronous equivalent of `Bun.spawn` called `Bun.spawnSync`. This is a blocking API that supports the same inputs and parameters as `Bun.spawn`. It returns a `SyncSubprocess` object, which differs from `Subprocess` in a few ways.
|
||||
@@ -407,6 +510,7 @@ namespace SpawnOptions {
|
||||
timeout?: number;
|
||||
killSignal?: string | number;
|
||||
maxBuffer?: number;
|
||||
terminal?: TerminalOptions; // PTY support (POSIX only)
|
||||
}
|
||||
|
||||
type Readable =
|
||||
@@ -435,10 +539,11 @@ namespace SpawnOptions {
|
||||
}
|
||||
|
||||
interface Subprocess extends AsyncDisposable {
|
||||
readonly stdin: FileSink | number | undefined;
|
||||
readonly stdout: ReadableStream<Uint8Array> | number | undefined;
|
||||
readonly stderr: ReadableStream<Uint8Array> | number | undefined;
|
||||
readonly readable: ReadableStream<Uint8Array> | number | undefined;
|
||||
readonly stdin: FileSink | number | undefined | null;
|
||||
readonly stdout: ReadableStream<Uint8Array<ArrayBuffer>> | number | undefined | null;
|
||||
readonly stderr: ReadableStream<Uint8Array<ArrayBuffer>> | number | undefined | null;
|
||||
readonly readable: ReadableStream<Uint8Array<ArrayBuffer>> | number | undefined | null;
|
||||
readonly terminal: Terminal | undefined;
|
||||
readonly pid: number;
|
||||
readonly exited: Promise<number>;
|
||||
readonly exitCode: number | null;
|
||||
@@ -465,6 +570,28 @@ interface SyncSubprocess {
|
||||
pid: number;
|
||||
}
|
||||
|
||||
interface TerminalOptions {
|
||||
cols?: number;
|
||||
rows?: number;
|
||||
name?: string;
|
||||
data?: (terminal: Terminal, data: Uint8Array<ArrayBuffer>) => void;
|
||||
/** Called when PTY stream closes (EOF or error). exitCode is PTY lifecycle status (0=EOF, 1=error), not subprocess exit code. */
|
||||
exit?: (terminal: Terminal, exitCode: number, signal: string | null) => void;
|
||||
drain?: (terminal: Terminal) => void;
|
||||
}
|
||||
|
||||
interface Terminal extends AsyncDisposable {
|
||||
readonly stdin: number;
|
||||
readonly stdout: number;
|
||||
readonly closed: boolean;
|
||||
write(data: string | BufferSource): number;
|
||||
resize(cols: number, rows: number): void;
|
||||
setRawMode(enabled: boolean): void;
|
||||
ref(): void;
|
||||
unref(): void;
|
||||
close(): void;
|
||||
}
|
||||
|
||||
interface ResourceUsage {
|
||||
contextSwitches: {
|
||||
voluntary: number;
|
||||
|
||||
Reference in New Issue
Block a user