@termfleet/terminal

Framework-neutral terminal transport and durable tmux session primitives shared by Termfleet and embedders such as Supercode.

The package owns terminal attachment lifetimes. Closing an attachment releases its WebSocket, PTY client, listeners, timers, and file descriptors; it does not terminate the durable tmux session. Session termination remains a separate, explicit operation controlled by the embedding host.

Exports are split by environment without splitting the package:

• @termfleet/terminal/client.js — browser-safe terminal WebSocket client and wire contract.
• @termfleet/terminal/attach.js — Node CLI attachment loop with deterministic TTY restoration and Ctrl-b d detach.
• @termfleet/terminal/tmux.js — Node tmux session, capture, input, and ownership primitives.
• @termfleet/terminal/tmux-stream.js — Node PTY-to-WebSocket attachment with idempotent handle cleanup.

@homebridge/node-pty-prebuilt-multiarch and ws are optional peers because browser-only consumers need neither. A host importing tmux-stream.js must provide both.

The tmux helpers accept an optional socket everywhere, so applications can use an isolated tmux server instead of touching the user's default server. Created sessions can carry an app-namespaced ownership mark; discovery does not claim or terminate unmarked sessions. Terminal attachment is intentionally separate from session termination: disposing a viewer only detaches its ephemeral PTY client and releases all handles.

@termfleet/terminal/local-terminal.js opens a structured command in the user's macOS Terminal without constructing AppleScript from caller data. Every program, argument, working directory, and environment value is POSIX-quoted before the fixed AppleScript receives it as a single argv value. Unsupported platforms fail honestly instead of guessing a terminal emulator.

createSession accepts a structured { program, arguments } command plus an environment map. Arguments are passed directly without constructing a shell command, and the credential bootstrap deletes itself before the command starts.