This repository has no description
Update the dev md
Nathan Herald
(Mar 19, 2026, 4:34 PM +0100)
c73ce0ce
5b29d5d2
+31
-9
+31
-9
DEVELOPMENT.md
+31
-9
DEVELOPMENT.md
···
1
1
# pty — Development Guide
2
2
3
-
A persistent terminal session manager. Run long-lived processes, detach, reconnect later — from any machine over SSH.
3
+
A persistent terminal session manager. Run long-lived processes, detach, reconnect later — from any machine over SSH. The npm package name is `ptym`; the CLI command remains `pty`.
4
4
5
5
## Objectives
6
6
···
20
20
## Quick Reference
21
21
22
22
```sh
23
-
npm install # install dependencies
24
-
npm run typecheck # typecheck with tsc (no emit)
25
-
npm test # run all tests once
26
-
npm run test:watch # run tests in watch mode
23
+
npm install # install dependencies
24
+
npm run typecheck # typecheck with tsc (no emit)
25
+
npm test # run all tests once
26
+
npm run test:watch # run tests in watch mode
27
+
npm run verify-docs # run executable examples in docs/testing.md
27
28
28
29
# Usage (during development)
29
30
npx tsx src/cli.ts run <name> -- <command> [args...]
···
34
35
npx tsx src/cli.ts list
35
36
npx tsx src/cli.ts restart <name>
36
37
npx tsx src/cli.ts kill <name>
38
+
npx tsx src/cli.ts test # run tests via vitest
39
+
npx tsx src/cli.ts test -t "pattern" # run matching tests
37
40
```
38
41
39
42
Detach from any attached/following session with **Ctrl+\\**. Press Ctrl+\\ twice quickly to send it to the process.
···
147
150
148
151
## Testing
149
152
150
-
Tests use **vitest** and live in `tests/`.
153
+
Tests use **vitest** and live in `tests/`. The `ptym/testing` library (`src/testing/`) provides a `Session` class used by the tests — see [docs/testing.md](docs/testing.md) for the full API.
151
154
152
155
- `protocol.test.ts` — Unit tests for packet encoding, decoding, and streaming reassembly (partial reads, split packets, large payloads)
156
+
- `keys.test.ts` — Unit tests for key name resolution (`resolveKey`, `parseSeqValue`)
157
+
- `sanitize.test.ts` — Unit tests for terminal sanitization escape sequences
153
158
- `integration.test.ts` — Full integration tests that spawn real PTY sessions, connect clients via sockets, and verify behavior
154
-
- `screenshot.test.ts` — Screenshot-based tests that capture terminal state (ANSI and plain text) and assert on visual output from real programs (vim, nano, ls, bash). Covers control characters, terminal resize, alternate screen buffer, multiple clients, unicode, and daemon spawning.
159
+
- `screenshot.test.ts` — Screenshot-based tests using `Session.server()` that capture terminal state (ANSI and plain text) and assert on visual output from real programs (vim, nano, ls, bash). Covers control characters, terminal resize, alternate screen buffer, multiple clients, unicode, and daemon spawning.
160
+
- `tui.test.ts` — Interactive TUI tests using `Session.spawn()` that drive the `pty` session manager UI: session list rendering, filtering, keyboard navigation, attach/detach cycles, and the create wizard.
155
161
156
162
All tests run in `/tmp/` directories to avoid polluting the project folder (e.g., vim swap files). Integration and screenshot tests use real processes and real Unix sockets. Each test creates a uniquely-named session and cleans up afterward. There is a `200ms` delay in some tests to allow xterm-headless to process async writes before checking screen state — this is a known characteristic of xterm's write pipeline, not a flaky test.
157
163
158
164
### Running tests
159
165
160
166
```sh
161
-
npm test # run once
162
-
npm run test:watch # watch mode
167
+
npm test # run once (or: pty test)
168
+
npm run test:watch # watch mode (or: pty test watch)
163
169
npx vitest run -t "peek" # run tests matching "peek"
170
+
npm run verify-docs # run executable examples in docs/testing.md
164
171
```
165
172
166
173
### node-pty on macOS
···
180
187
client.ts attach() and peek() functions
181
188
protocol.ts Packet types, encoding, decoding, PacketReader
182
189
sessions.ts Session discovery, socket/PID file management
190
+
keys.ts Key name resolution (e.g. "ctrl+c" → bytes)
191
+
spawn.ts Daemon spawning logic
192
+
tui/ Interactive session manager UI
193
+
testing/ Testing library (exported as ptym/testing)
194
+
index.ts Public re-exports
195
+
session.ts Session class (spawn + server backends)
196
+
screenshot.ts Screenshot capture helper
197
+
types.ts Screenshot, SpawnOptions, ServerOptions interfaces
183
198
tests/
184
199
protocol.test.ts
200
+
keys.test.ts
201
+
sanitize.test.ts
185
202
integration.test.ts
186
203
screenshot.test.ts
204
+
tui.test.ts
205
+
docs/
206
+
testing.md Testing library documentation (with executable examples)
207
+
scripts/
208
+
verify-docs.ts Extracts and runs doc examples via vitest
187
209
completions/
188
210
pty.bash Bash tab completion
189
211
pty.zsh Zsh tab completion