terminal

package
v0.13.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 10, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type DirectRenderer

type DirectRenderer interface {
	Render() string
}

DirectRenderer is an optional interface that backends can implement when their output is already rendered terminal text (e.g., tmux capture-pane). SessionView checks for this: if present, it skips the VT emulator and uses Render() directly. If absent, output goes through the VT emulator.

type KubectlExecBackend added in v0.7.0

type KubectlExecBackend struct {
	// contains filtered or unexported fields
}

KubectlExecBackend implements SessionBackend for remote K8s pod sessions. It uses `kubectl exec -it` with a real PTY (via creack/pty) to provide full interactive terminal access to a tmux session inside a pod.

func NewKubectlExec added in v0.7.0

func NewKubectlExec(podName, namespace, container string, cols, rows int) (*KubectlExecBackend, error)

NewKubectlExec starts `kubectl exec -it` with a real PTY, attaching to (or creating) a tmux session named "main" inside the pod.

func (*KubectlExecBackend) Alive added in v0.7.0

func (kb *KubectlExecBackend) Alive() bool

Alive checks if the kubectl process is still running.

func (*KubectlExecBackend) Close added in v0.7.0

func (kb *KubectlExecBackend) Close() error

Close kills the kubectl process and closes the PTY. The tmux session inside the pod continues running and can be reattached later.

func (*KubectlExecBackend) Namespace added in v0.7.0

func (kb *KubectlExecBackend) Namespace() string

Namespace returns the namespace for external reference.

func (*KubectlExecBackend) PodName added in v0.7.0

func (kb *KubectlExecBackend) PodName() string

PodName returns the pod name for external reference.

func (*KubectlExecBackend) Read added in v0.7.0

func (kb *KubectlExecBackend) Read(buf []byte) (int, error)

Read reads from the PTY. Blocks until data is available or the PTY closes. This is called from a Bubble Tea command goroutine, so blocking is fine — Bubble Tea handles key events on a separate goroutine.

func (*KubectlExecBackend) Resize added in v0.7.0

func (kb *KubectlExecBackend) Resize(cols, rows int) error

Resize changes the PTY and remote tmux window size.

func (*KubectlExecBackend) Write added in v0.7.0

func (kb *KubectlExecBackend) Write(data []byte) (int, error)

Write sends input to the PTY — keystrokes go directly to the remote session.

type OpenShellExecBackend added in v0.13.0

type OpenShellExecBackend struct {
	// contains filtered or unexported fields
}

OpenShellExecBackend implements SessionBackend for remote OpenShell sandbox sessions. It runs `openshell sandbox connect <name>` inside a real PTY (via creack/pty), giving the connect process a controlling-TTY-like environment so it behaves as a genuine interactive terminal. This mirrors the k8s KubectlExecBackend and deliberately avoids tmux: there is no detached tmux session to die, no capture-pane polling, and no send-keys injection. The sandbox itself is a gateway resource that outlives the connect process, so closing this backend (leaving the view) does not destroy the sandbox.

func NewOpenShellExec added in v0.13.0

func NewOpenShellExec(sandbox, gatewayEndpoint string, insecure bool, cols, rows int) (*OpenShellExecBackend, error)

NewOpenShellExec starts `openshell sandbox connect <sandbox>` in a real PTY. gatewayEndpoint is optional; when empty, the openshell CLI resolves its configured/selected gateway. cols/rows set the initial terminal size.

func (*OpenShellExecBackend) Alive added in v0.13.0

func (ob *OpenShellExecBackend) Alive() bool

Alive reports whether the connect process is still running.

func (*OpenShellExecBackend) Close added in v0.13.0

func (ob *OpenShellExecBackend) Close() error

Close kills the connect process and closes the PTY. The sandbox itself is a gateway resource and continues running; it can be reconnected later.

func (*OpenShellExecBackend) Read added in v0.13.0

func (ob *OpenShellExecBackend) Read(buf []byte) (int, error)

Read reads from the PTY. Blocks until data is available or the PTY closes.

func (*OpenShellExecBackend) Resize added in v0.13.0

func (ob *OpenShellExecBackend) Resize(cols, rows int) error

Resize changes the PTY window size.

func (*OpenShellExecBackend) Sandbox added in v0.13.0

func (ob *OpenShellExecBackend) Sandbox() string

Sandbox returns the sandbox name for external reference.

func (*OpenShellExecBackend) Write added in v0.13.0

func (ob *OpenShellExecBackend) Write(data []byte) (int, error)

Write sends input to the PTY — keystrokes go directly to the remote shell.

type Session

type Session struct {
	// contains filtered or unexported fields
}

Session manages a PTY-backed subprocess. It provides thread-safe read, write, and resize operations for embedding interactive terminal processes.

func Start

func Start(cmd *exec.Cmd) (*Session, error)

Start spawns a command inside a new PTY and returns a Session.

func (*Session) Alive

func (s *Session) Alive() bool

Alive returns true if the session is still open and the process has not exited.

func (*Session) Close

func (s *Session) Close() error

Close terminates the PTY session. It sends terminal reset sequences to restore standard modes, then closes the PTY file descriptor and signals the process to exit. Cleanup runs in a background goroutine so the TUI returns immediately. It is safe to call multiple times.

func (*Session) Read

func (s *Session) Read(buf []byte) (int, error)

Read reads output from the PTY. It returns io.EOF if the session is closed.

func (*Session) Resize

func (s *Session) Resize(cols, rows int) error

Resize changes the PTY window size. It is safe to call after Close.

func (*Session) Write

func (s *Session) Write(data []byte) (int, error)

Write sends input to the PTY. It returns io.EOF if the session is closed.

type SessionBackend

type SessionBackend interface {
	Read(buf []byte) (int, error)
	Write(data []byte) (int, error)
	Resize(cols, rows int) error
	Close() error
	Alive() bool
}

SessionBackend is the common interface for terminal session backends. The direct PTY backend (Session) and the tmux mirror backend (TmuxSession) both implement this interface. SessionView works with either.

type TermView

type TermView struct {
	// contains filtered or unexported fields
}

TermView wraps a charmbracelet/x/vt terminal emulator, providing a thread-safe interface for writing PTY output and rendering the screen buffer as an ANSI-styled string.

func NewTermView

func NewTermView(cols, rows int, responseSink ...io.Writer) *TermView

NewTermView creates a new TermView with the given column and row dimensions. An optional responseSink receives terminal responses (device attributes, cursor position reports, etc.) generated by the VT emulator. Pass the PTY backend so the child process gets the responses it expects. If nil, responses are discarded.

The VT emulator uses an io.Pipe for responses — writes block until read. A background goroutine drains the pipe to prevent deadlocks.

func (*TermView) Height

func (tv *TermView) Height() int

Height returns the current terminal height in rows.

func (*TermView) IsScrolled added in v0.6.0

func (tv *TermView) IsScrolled() bool

IsScrolled returns true if viewing history (not live bottom).

func (*TermView) Render

func (tv *TermView) Render() string

Render returns the current screen buffer as a string with ANSI styling. When scrolled back, it returns lines from the history buffer instead of the live terminal output. Results are cached and reused until the next Write or scroll position change.

func (*TermView) Resize

func (tv *TermView) Resize(cols, rows int)

Resize changes the dimensions of the virtual terminal.

func (*TermView) ScrollDown added in v0.6.0

func (tv *TermView) ScrollDown(n int)

ScrollDown moves the viewport down by n lines. Snaps to live at 0.

func (*TermView) ScrollUp added in v0.6.0

func (tv *TermView) ScrollUp(n int)

ScrollUp moves the viewport up by n lines.

func (*TermView) SnapToBottom added in v0.6.0

func (tv *TermView) SnapToBottom()

SnapToBottom resets scroll to live view.

func (*TermView) SnapshotHistory added in v0.9.0

func (tv *TermView) SnapshotHistory()

SnapshotHistory captures the current screen into the scroll-back buffer. Call this on a debounce timer (e.g., every 100ms) rather than on every Write, to amortise the cost of Render across bursts of PTY output.

func (*TermView) Width

func (tv *TermView) Width() int

Width returns the current terminal width in columns.

func (*TermView) Write

func (tv *TermView) Write(data []byte)

Write feeds raw PTY output into the VT emulator. This processes ANSI escape sequences and updates the internal screen buffer. History snapshots are deferred to SnapshotHistory(), which should be called on a debounce timer rather than on every write. This avoids the expensive double-Render that the old implementation performed.

type TmuxSession

type TmuxSession struct {
	// contains filtered or unexported fields
}

TmuxSession mirrors a tmux session's pane content. It polls `tmux capture-pane` for output and forwards keystrokes via `tmux send-keys`. This allows embedding any TUI (Codex) inside aimux's split view.

func AttachTmux

func AttachTmux(sessionName string, cols, rows int) (*TmuxSession, error)

AttachTmux mirrors an existing tmux session without creating it. The session is left running when Close is called.

func StartTmux

func StartTmux(cmd *exec.Cmd, cols, rows int, shell, envPrefix string) (*TmuxSession, error)

StartTmux creates a new tmux session running cmd, then mirrors it. The session is killed when Close is called.

func (*TmuxSession) Alive

func (ts *TmuxSession) Alive() bool

Alive returns true if the tmux session still exists.

func (*TmuxSession) Close

func (ts *TmuxSession) Close() error

Close stops polling. If the session was created by StartTmux, it kills the tmux session. If it was attached via AttachTmux, the session continues running.

func (*TmuxSession) Read

func (ts *TmuxSession) Read(buf []byte) (int, error)

Read returns captured pane content. Blocks until data is available or the session is closed.

func (*TmuxSession) Render

func (ts *TmuxSession) Render() string

Render returns the latest captured pane content. This implements the DirectRenderer interface, allowing SessionView to skip the VT emulator and display the tmux output directly (it's already rendered terminal text).

func (*TmuxSession) Resize

func (ts *TmuxSession) Resize(cols, rows int) error

Resize changes the tmux window dimensions.

func (*TmuxSession) SessionName

func (ts *TmuxSession) SessionName() string

SessionName returns the tmux session name for external reference.

func (*TmuxSession) Write

func (ts *TmuxSession) Write(data []byte) (int, error)

Write sends input to the tmux session via send-keys. Batches consecutive printable characters into a single tmux send-keys -l call to avoid spawning one subprocess per keystroke.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL