tmuxexec

package
v0.71.0 Latest Latest
Warning

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

 Go to latest Published: Nov 5, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package tmuxexec implements the tmux terminal multiplexer adapter.

Index

Constants

View Source 
const LaunchPendingOption = "@hive-launch-pending"

LaunchPendingOption marks resources that have not committed a Hive launch.

Variables

View Source 
var ErrCommandExited = errors.New("tmux window command exited during startup")

ErrCommandExited matches a CommandExitedError with errors.Is.

View Source 
var ErrInvalidLaunchPhase = fmt.Errorf("not a valid LaunchPhase, try [%s]", strings.Join(_LaunchPhaseNames, ", "))
View Source 
var ErrInvalidPaneLaunchState = fmt.Errorf("not a valid PaneLaunchState, try [%s]", strings.Join(_PaneLaunchStateNames, ", "))

Functions

func LaunchPhaseNames added in v0.63.0 

func LaunchPhaseNames() []string

LaunchPhaseNames returns a list of possible string values of LaunchPhase.

func PaneLaunchStateNames added in v0.63.0 

func PaneLaunchStateNames() []string

PaneLaunchStateNames returns a list of possible string values of PaneLaunchState.

Types

type CleanupError added in v0.63.0 

type CleanupError struct {
	Resources []string
	Err       error
}

CleanupError reports resources that could not be removed after a failed launch.

func (*CleanupError) Error added in v0.63.0 

func (e *CleanupError) Error() string

func (*CleanupError) Unwrap added in v0.63.0 

func (e *CleanupError) Unwrap() error

type Client 

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

Client implements tmux operations over a Runner.

func New 

func New(log zerolog.Logger, runner Runner) *Client

New creates a tmux client.

func NewDefault 

func NewDefault(log zerolog.Logger) *Client

NewDefault creates a client that invokes the tmux executable.

func (*Client) AddWindows 

func (c *Client) AddWindows(ctx context.Context, target multiplexer.Target, windows []multiplexer.WindowSpec) error

AddWindows adds windows to an existing tmux session.

func (*Client) AttachOrSwitch 

func (c *Client) AttachOrSwitch(ctx context.Context, target multiplexer.Target, streams multiplexer.AttachStreams) error

AttachOrSwitch switches the active client inside tmux or attaches outside tmux. Window and pane selection is best-effort and ordered so the selected target is visible on entry: attach-session blocks until detach, so selection runs before it, while switch-client returns immediately, so selection runs after it.

func (*Client) Available 

func (c *Client) Available() bool

Available reports whether tmux is available.

func (*Client) CapturePane 

func (c *Client) CapturePane(ctx context.Context, target multiplexer.Target, opts multiplexer.CaptureOptions) (string, error)

CapturePane captures pane text.

func (*Client) CreateSession 

func (c *Client) CreateSession(ctx context.Context, spec multiplexer.SessionSpec) error

CreateSession creates a tmux session from a declarative specification.

func (*Client) CurrentSession 

func (c *Client) CurrentSession(ctx context.Context) (multiplexer.Target, error)

CurrentSession returns the current tmux session, or an empty target outside tmux.

func (*Client) HasSession 

func (c *Client) HasSession(ctx context.Context, target multiplexer.Target) (bool, error)

HasSession reports whether a tmux session exists.

func (*Client) InspectPane 

func (c *Client) InspectPane(ctx context.Context, target multiplexer.Target) (multiplexer.Pane, error)

InspectPane returns one resolved pane.

func (*Client) KillSession 

func (c *Client) KillSession(ctx context.Context, target multiplexer.Target) error

KillSession kills a tmux session.

func (*Client) KillWindow 

func (c *Client) KillWindow(ctx context.Context, target multiplexer.Target) error

KillWindow kills one qualified tmux window.

func (*Client) ListPanes 

func (c *Client) ListPanes(ctx context.Context) ([]multiplexer.Pane, error)

ListPanes returns every pane visible to the current tmux server. A row that does not parse costs only that pane, because callers treat an error as every pane gone. It is an error only when no row parses, as a format that tmux and this package disagree on would produce.

func (*Client) OpenSession 

func (c *Client) OpenSession(ctx context.Context, spec multiplexer.SessionSpec, selection multiplexer.Target) (multiplexer.LaunchResult, error)

OpenSession creates a missing session or opens an existing one. For an existing session, selection names the window or pane to show on entry.

func (*Client) Paste 

func (c *Client) Paste(ctx context.Context, target multiplexer.Target, text []byte, opts multiplexer.PasteOptions) (retErr error)

Paste loads bytes into a private tmux buffer and pastes it into a pane.

func (*Client) RenameSession 

func (c *Client) RenameSession(ctx context.Context, target multiplexer.Target, newName string) error

RenameSession renames a tmux session. It succeeds when the old session is gone and the new one exists: Hive Desktop renames tmux itself before it asks the session service, which may run in the daemon, to rename the row.

func (*Client) ResolveTarget 

func (c *Client) ResolveTarget(ctx context.Context, raw string) (multiplexer.Pane, error)

ResolveTarget resolves a tmux target into a qualified pane.

func (*Client) SendKey 

func (c *Client) SendKey(ctx context.Context, target multiplexer.Target, key multiplexer.NamedKey) error

SendKey sends one validated tmux named-key token.

func (*Client) SendLiteral 

func (c *Client) SendLiteral(ctx context.Context, target multiplexer.Target, text string) error

SendLiteral sends text without interpreting it as key names.

type CommandExitedError added in v0.63.0 

type CommandExitedError struct {
	Session      string
	Window       string
	Pane         string
	Command      string
	Status       int
	Signal       string
	Lost         bool
	Output       string
	Truncated    bool
	CaptureError error
}

CommandExitedError reports a failed or lost pane during session startup. Output is a best-effort terminal excerpt, not a separate stderr stream. Its message leaves out the session name because a LaunchError, which names the session, always wraps it.

func (*CommandExitedError) Error added in v0.63.0 

func (e *CommandExitedError) Error() string

func (*CommandExitedError) Is added in v0.63.0 

func (e *CommandExitedError) Is(target error) bool

func (*CommandExitedError) NotFound added in v0.63.0 

func (e *CommandExitedError) NotFound() bool

NotFound reports the shell's command-not-found exit status.

type ExecRunnerOptions 

type ExecRunnerOptions struct {
	// Binary resolves the tmux executable for each command. Nil uses PATH.
	Binary func(context.Context) (string, error)
	// Environ returns the child environment. Nil inherits the process environment.
	Environ func(context.Context) []string
	// PrepareArgs can add server-selection arguments before execution.
	PrepareArgs func([]string) []string
}

ExecRunnerOptions configures an executable-backed Runner.

type LaunchError added in v0.63.0 

type LaunchError struct {
	Session string
	Phase   LaunchPhase
	// AddedWindows is true when the launch added windows to a session that
	// already existed, so the session itself did not fail.
	AddedWindows bool
	Err          error
}

LaunchError preserves the failed phase and all command and cleanup causes.

func (*LaunchError) Error added in v0.63.0 

func (e *LaunchError) Error() string

func (*LaunchError) Unwrap added in v0.63.0 

func (e *LaunchError) Unwrap() error

type LaunchPhase added in v0.63.0 

type LaunchPhase string

LaunchPhase identifies the phase of a bounded tmux launch. ENUM(allocating, launching, observing, finalizing, committed, rolling_back, failed, cleanup_incomplete) 

const (
	// LaunchPhaseAllocating is a LaunchPhase of type allocating.
	LaunchPhaseAllocating LaunchPhase = "allocating"
	// LaunchPhaseLaunching is a LaunchPhase of type launching.
	LaunchPhaseLaunching LaunchPhase = "launching"
	// LaunchPhaseObserving is a LaunchPhase of type observing.
	LaunchPhaseObserving LaunchPhase = "observing"
	// LaunchPhaseFinalizing is a LaunchPhase of type finalizing.
	LaunchPhaseFinalizing LaunchPhase = "finalizing"
	// LaunchPhaseCommitted is a LaunchPhase of type committed.
	LaunchPhaseCommitted LaunchPhase = "committed"
	// LaunchPhaseRollingBack is a LaunchPhase of type rolling_back.
	LaunchPhaseRollingBack LaunchPhase = "rolling_back"
	// LaunchPhaseFailed is a LaunchPhase of type failed.
	LaunchPhaseFailed LaunchPhase = "failed"
	// LaunchPhaseCleanupIncomplete is a LaunchPhase of type cleanup_incomplete.
	LaunchPhaseCleanupIncomplete LaunchPhase = "cleanup_incomplete"
)

func ParseLaunchPhase added in v0.63.0 

func ParseLaunchPhase(name string) (LaunchPhase, error)

ParseLaunchPhase attempts to convert a string to a LaunchPhase.

func (LaunchPhase) AppendText added in v0.63.0 

func (x LaunchPhase) AppendText(b []byte) ([]byte, error)

AppendText appends the textual representation of itself to the end of b (allocating a larger slice if necessary) and returns the updated slice.

Implementations must not retain b, nor mutate any bytes within b[:len(b)].

func (LaunchPhase) IsValid added in v0.63.0 

func (x LaunchPhase) IsValid() bool

IsValid provides a quick way to determine if the typed value is part of the allowed enumerated values

func (LaunchPhase) MarshalText added in v0.63.0 

func (x LaunchPhase) MarshalText() ([]byte, error)

MarshalText implements the text marshaller method.

func (LaunchPhase) String added in v0.63.0 

func (x LaunchPhase) String() string

String implements the Stringer interface.

func (*LaunchPhase) UnmarshalText added in v0.63.0 

func (x *LaunchPhase) UnmarshalText(text []byte) error

UnmarshalText implements the text unmarshaller method.

type PaneLaunchState added in v0.63.0 

type PaneLaunchState string

PaneLaunchState identifies a pane's observed startup outcome. ENUM(allocated, spawned, running, completed, exit_pending, failed, lost) 

const (
	// PaneLaunchStateAllocated is a PaneLaunchState of type allocated.
	PaneLaunchStateAllocated PaneLaunchState = "allocated"
	// PaneLaunchStateSpawned is a PaneLaunchState of type spawned.
	PaneLaunchStateSpawned PaneLaunchState = "spawned"
	// PaneLaunchStateRunning is a PaneLaunchState of type running.
	PaneLaunchStateRunning PaneLaunchState = "running"
	// PaneLaunchStateCompleted is a PaneLaunchState of type completed.
	PaneLaunchStateCompleted PaneLaunchState = "completed"
	// PaneLaunchStateExitPending is a PaneLaunchState of type exit_pending.
	PaneLaunchStateExitPending PaneLaunchState = "exit_pending"
	// PaneLaunchStateFailed is a PaneLaunchState of type failed.
	PaneLaunchStateFailed PaneLaunchState = "failed"
	// PaneLaunchStateLost is a PaneLaunchState of type lost.
	PaneLaunchStateLost PaneLaunchState = "lost"
)

func ParsePaneLaunchState added in v0.63.0 

func ParsePaneLaunchState(name string) (PaneLaunchState, error)

ParsePaneLaunchState attempts to convert a string to a PaneLaunchState.

func (PaneLaunchState) AppendText added in v0.63.0 

func (x PaneLaunchState) AppendText(b []byte) ([]byte, error)

AppendText appends the textual representation of itself to the end of b (allocating a larger slice if necessary) and returns the updated slice.

Implementations must not retain b, nor mutate any bytes within b[:len(b)].

func (PaneLaunchState) IsValid added in v0.63.0 

func (x PaneLaunchState) IsValid() bool

IsValid provides a quick way to determine if the typed value is part of the allowed enumerated values

func (PaneLaunchState) MarshalText added in v0.63.0 

func (x PaneLaunchState) MarshalText() ([]byte, error)

MarshalText implements the text marshaller method.

func (PaneLaunchState) String added in v0.63.0 

func (x PaneLaunchState) String() string

String implements the Stringer interface.

func (*PaneLaunchState) UnmarshalText added in v0.63.0 

func (x *PaneLaunchState) UnmarshalText(text []byte) error

UnmarshalText implements the text unmarshaller method.

type Runner 

type Runner interface {
	Available() bool
	Capture(ctx context.Context, args ...string) (stdout, stderr []byte, err error)
	Input(ctx context.Context, input io.Reader, args ...string) (stdout, stderr []byte, err error)
	Interactive(ctx context.Context, streams multiplexer.AttachStreams, args ...string) error
}

Runner executes tmux operations in captured, input-bearing, or interactive mode.

func NewExecRunner 

func NewExecRunner(options ExecRunnerOptions) Runner

NewExecRunner creates a Runner that invokes a configurable tmux executable.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.