term

Documentation

Overview

Package term embeds a PTY-backed shell pane inside nook.

The Pane spawns $SHELL (or sh) inside a PTY, reads stdout, and renders a scrollback buffer with a cursor on the last line. Input is forwarded to the PTY when the pane is focused. The renderer is intentionally simple: it preserves bytes verbatim (so colors, prompt sequences, and bell pass through) and tracks a flat scrollback of decoded lines.

Not a terminal emulator. We don't interpret cursor-positioning, scrollback regions, or alternate-screen mode. Commands that need a full emulator (vim, htop, less) will still draw, but layout assumptions may break. For nook's MVP this is acceptable: it covers `git push`, `go test`, `npm run`, REPLs, file operations.

Index

• type CancelMsg
• type ExitMsg
• type OutputMsg
• type Pane
  • func NewPane(t theme.Theme, root string) Pane
  • func (p Pane) Append(b []byte) Pane
  • func (p Pane) Blur() Pane
  • func (p Pane) Focus() Pane
  • func (p Pane) Focused() bool
  • func (p Pane) Lines() []string
  • func (p Pane) MarkExit(err error) Pane
  • func (p Pane) Session() *Session
  • func (p Pane) Start() (Pane, error)
  • func (p Pane) Stop() Pane
  • func (p Pane) Update(msg tea.Msg) (Pane, tea.Cmd)
  • func (p Pane) View() string
  • func (p Pane) WithSize(w, h int) Pane
• type Session
  • func New(cwd string) (*Session, error)
  • func (s *Session) Close() error
  • func (s *Session) ReadLoop(ctx context.Context, out chan<- []byte) error
  • func (s *Session) Resize(cols, rows uint16) error
  • func (s *Session) Write(b []byte) (int, error)

Types

type CancelMsg

type CancelMsg struct{}

CancelMsg is emitted on Esc-when-blurred or explicit Quit.

type ExitMsg

type ExitMsg struct {
	Err error
}

ExitMsg is emitted when the shell process exits.

type OutputMsg

type OutputMsg struct {
	Data []byte
}

OutputMsg carries a chunk of bytes from the PTY.

type Pane

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

Pane is the terminal UI model.

func NewPane

func NewPane(t theme.Theme, root string) Pane

NewPane constructs an unstarted terminal pane.

func (Pane) Append

func (p Pane) Append(b []byte) Pane

Append decodes bytes from the PTY into scrollback. Strips most ANSI escapes for the MVP renderer; future versions can preserve color/style.

func (Pane) Blur

func (p Pane) Blur() Pane

Blur sets focused=false.

func (Pane) Focus

func (p Pane) Focus() Pane

Focus sets focused=true.

func (Pane) Focused

func (p Pane) Focused() bool

Focused reports whether the pane has keyboard focus.

func (Pane) Lines

func (p Pane) Lines() []string

Lines returns the decoded scrollback.

func (Pane) MarkExit

func (p Pane) MarkExit(err error) Pane

MarkExit records process exit.

func (Pane) Session

func (p Pane) Session() *Session

Session returns the underlying PTY session (for ReadLoop wiring).

func (Pane) Start

func (p Pane) Start() (Pane, error)

Start spawns the shell. Idempotent.

func (Pane) Stop

func (p Pane) Stop() Pane

Stop kills the shell process.

func (Pane) Update

func (p Pane) Update(msg tea.Msg) (Pane, tea.Cmd)

Update routes keys.

func (Pane) View

func (p Pane) View() string

View renders the pane.

func (Pane) WithSize

func (p Pane) WithSize(w, h int) Pane

WithSize sets pane dimensions.

type Session

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

Session is a live PTY-backed shell. Use New to construct; call Close to terminate.

func New

func New(cwd string) (*Session, error)

New spawns a shell in a PTY rooted at cwd. The caller owns the returned Session and must Close it on exit.

func (*Session) Close

func (s *Session) Close() error

Close terminates the session and releases the PTY.

func (*Session) ReadLoop

func (s *Session) ReadLoop(ctx context.Context, out chan<- []byte) error

ReadLoop pumps bytes from the PTY into a channel until ctx is cancelled or the process exits. Closes the channel on exit. Suitable for wrapping into a recursive tea.Cmd via Program.Send.

func (*Session) Resize

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

Resize sends a winsize ioctl to the PTY.

func (*Session) Write

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

Write forwards bytes to the PTY.