UniPty

Runtime-neutral PTY for Node, Bun, and Deno — one public contract, developer-selectable Backends.

English | 简体中文

Node, Bun, and Deno each expose a different PTY substrate — different installation models, I/O representations, lifecycle semantics, and native deployment constraints. UniPty turns that into one small, honest contract: applications pick a Backend explicitly, and all substrate variation stays behind a Core-owned seam. No implicit shell execution, no silent fallback to pipes, no runtime substitution.

Install

Core plus one Backend of your choice — the package you install is the engine you get:

Not sure which engine? The capability matrix under Choosing a Backend below tells you exactly what each one gives you.

Quickstart

import { UniPty } from "unipty";
import { createNodePtyBackend } from "@unipty/backend-node-pty";

const backend = await createNodePtyBackend(); // one-time readiness
const unipty = new UniPty({ backend });

const pty = unipty.spawn(["/bin/sh", "-i"], {
  cwd: process.cwd(),
  terminal: { cols: 120, rows: 40 },
});

for await (const text of pty.stream({ encoding: "utf8" })) {
  process.stdout.write(text);
}
pty.write("echo hello\n"); // boolean Write Readiness — see the contract table
pty.resize(80, 24); // character cells only
pty.terminate(); // request, never cascades into close
pty.close(); // transport close, never kills the child
const { exitCode, signal } = await pty.exited; // independent observation

Swapping engines is a one-line change — everything above is identical on every route: createZigptyBackend() (zigpty), createBunBackend() (bun), or createDenoSigmaPtyFfiBackend() (deno). Engine-specific behavior (options, permissions, capability differences) is documented in each package's README.

The contract at a glance

Everything you can call, and exactly what it promises:

Four behaviors most often trip people up, by design:

• Structured launch — Bun-style spawn(argv, options) with a non-empty argv vector. No string-command overload, no implicit shell; metacharacters are ordinary data.
• Representation-selecting streams — pty.stream({ encoding: "utf8" | "bytes" }). UTF-8 views prefer native text and otherwise decode bytes incrementally; bytes views yield native bytes only — re-encoded text is never claimed as raw output.
• Boolean Write Readiness — write() returning false means "pause and await drain()", never "retry"; saturation rejects one whole value with a typed backpressure failure. Never partial, never silent.
• Non-cascading lifecycle — close() never kills the child, terminate() never closes the transport, and exited survives both. unipty.dispose() blocks new spawns and waits for live PTYs before releasing the Backend exactly once.

Choosing a Backend

Official routes

The Node routes adapt third-party libraries — neither is a native Node runtime API, and the docs never claim otherwise. Deno is runtime metadata for the last route, not its implementation identity.

Capability differences (what the engines actually give you)

The public contract is identical on every route — structured argv, geometry and resize, write readiness with drain and whole-value saturation rejection, non-cascading close/terminate, bootstrap buffering, common error codes. The engines underneath are not. This matrix is the honest difference surface to consult before choosing a route: ✓ works out of the box, ⚠ needs an option or carries a documented limitation, ✗ not provided.

Exec failures are an exit observation (never a spawn exception) on every route, and per-adapter details live in each package's README.

Acquiring a Backend

Manual import is the first-class path — Core never needs the acquisition layer:

const backend = await createBunBackend(); // or any official factory
const unipty = new UniPty({ backend });

For deterministic discovery, @unipty/backend stages the work: pure resolution (no imports), metadata-only inspection (no initialization), then selected-candidate initialization whose failures are terminal and structured:

import { autoResolveUniPtyBackend } from "@unipty/backend";

const backend = await autoResolveUniPtyBackend({
  candidates: ["@unipty/backend-node-pty"], // ordered preference
  from: import.meta.url, // caller-rooted base
});

Bundled deployments supply an explicit immutable manifest instead (defineUniPtyBackendManifest()), generated by unipty-helper-backend manifest --candidate <pkg> --out backend-manifest.ts. See the acquisition README for the full staged contract.

Architecture (the 60-second version)

application code
   │  public contract (spawn / stream / write / resize / lifecycle / exited)
   ▼
UniPty Core ──── owns every observable behaviour: views, conversion,
   │             bootstrap buffering, backpressure, errors, lifecycle state
   ▼
Ready Backend ── one injected, already-ready object per UniPty instance
   │             (native loading / connection / negotiation finished first)
   ▼
real PTY on node-pty / zigpty / Bun.Terminal / @sigma/pty-ffi

Design principles worth knowing before reading the code:

• Substrate honesty. Every adapter documents its substrate's real behaviour (kill-and-close primitives, unbounded internal buffers, signal opacity) instead of papering over it; support claims are evidence-gated — a tuple is verified only with a full public-contract pass against the installed artifact, and the release catalog is the sole source of that truth.
• No hidden policy. No implicit shell, no silent fallback to pipes, no second plugin registry, no capability/asset protocol. Extension points are explicit: Backend wrappers and opaque capability tokens (pty.capability(token), matched by object identity).

The full design narrative lives in 架构设计.md（中文）.

Packages

Conformance & compatibility evidence

Every support claim flows through one seam: the public conformance suite runs against installed package artifacts (packed, installed into an isolated consumer, driven only through public exports). A full native pass emits one positive Verification Evidence record; a deterministic aggregator validates identity/tuple/commit uniqueness and emits the release catalog, which the documentation site consumes unchanged. Failures stay CI diagnostics — they never become permanent "unsupported" claims. The per-tuple truth for the current release is the compatibility catalog.

Local run:

pnpm --filter @unipty/conformance run conformance --backend node-pty --emit-evidence

Documentation map

Where to go next, by intent:

Roadmap note: v1 is PTY-focused; persistence, reconnect, and remote hosts belong to replaceable Backends and wrappers, not a second plugin lifecycle.

Development

corepack pnpm install
pnpm build && pnpm typecheck && pnpm test
pnpm --filter @unipty/backend-zigpty test   # zigpty suite (real PTYs)
pnpm --filter @unipty/backend-bun test      # Bun suite (needs Bun)
cd packages/backend-deno-sigma__pty-ffi && deno test -A test/   # Deno suite
pnpm check:arch                             # package-graph ownership rules

License

MIT