cmd

Documentation

Overview

Package cmd defines the CLI commands for Portal.

Package cmd defines the CLI commands for Portal.

Index

• Variables
• func Execute() error
• type AllPaneLister
• type AttachConnector
  • func (ac *AttachConnector) Connect(name string) error
• type AttachDeps
• type BootstrapDeps
• type BootstrapWarningsSink
  • func (s *BootstrapWarningsSink) Add(w bootstrap.Warning)
  • func (s *BootstrapWarningsSink) Drain() []bootstrap.Warning
  • func (s *BootstrapWarningsSink) EmitTo(w io.Writer)
• type CleanDeps
• type HooksDeps
• type KillDeps
• type ListDeps
• type OpenDeps
• type PathOpener
  • func (po *PathOpener) Open(resolvedPath string, command []string) error
• type SessionConnector
• type SessionKiller
• type SessionLister
• type SessionValidator
• type StateCleanupDeps
• type StructuralKeyResolver
• type SwitchClienter
• type SwitchConnector
  • func (sc *SwitchConnector) Connect(name string) error
• type UsageError
  • func NewUsageError(msg string) *UsageError
  • func (e *UsageError) Error() string

Variables

var ErrHydrateTimeout = errors.New("fifo open timeout")

ErrHydrateTimeout is returned by openFIFOWithTimeout when the blocking open did not complete within the supplied timeout. The 3-second default is set by hydrateTimeout; tests use shorter values.

var ErrStatusUnhealthy = errors.New("")

ErrStatusUnhealthy is returned by `portal state status` when the daemon is not running, the last save is older than the staleness threshold, or recent warnings exist in portal.log. The message is intentionally empty so cobra (with SilenceErrors=true) prints no extra banner — the user has already seen the rendered status; the error exists solely to drive a non-zero process exit.

Functions

func Execute

func Execute() error

Execute runs the root command. When PersistentPreRunE (or any subcommand in the chain) returns a *bootstrap.FatalError, Execute writes the fatal's UserMessage as a single line to fatalErrorStderr before returning the error. Callers (main.go) translate the returned error into the process exit code; Execute itself does not call os.Exit so tests can drive the FatalError path without subprocess fanout.

Types

type AllPaneLister

type AllPaneLister interface {
	ListAllPanes() ([]string, error)
}

AllPaneLister returns the structural keys for all panes across all tmux sessions. Each key uses the format session_name:window_index.pane_index.

type AttachConnector

type AttachConnector struct{}

AttachConnector connects to a session by exec-ing tmux attach-session. Used when Portal is running outside tmux (bare shell).

func (*AttachConnector) Connect

func (ac *AttachConnector) Connect(name string) error

Connect replaces the current process with tmux attach-session.

type AttachDeps

type AttachDeps struct {
	Connector SessionConnector
	Validator SessionValidator
}

AttachDeps allows injecting dependencies for testing.

type BootstrapDeps

type BootstrapDeps struct {
	// Orchestrator is the test seam for bootstrap. When nil, runBootstrap
	// short-circuits to a (false, nil, nil) result so tests indifferent
	// to bootstrap can leave it unset.
	Orchestrator bootstrap.Runner

	// Client is exposed in cmd.Context() under tmuxClientKey so downstream
	// commands (list, attach, kill, …) can look it up.
	Client *tmux.Client

	// RegisterHooks is invoked after the orchestrator returns to register
	// Portal's global tmux hook table on the live client. Production
	// default is tmux.RegisterPortalHooks.
	RegisterHooks func(*tmux.Client) error

	// ForceMemoise opts the test into the production sync.Once gate. By
	// default tests bypass the gate so subtests that swap mocks do not
	// have to reset shared package state between Execute() calls. Only
	// the dedicated memoisation test sets this to true.
	ForceMemoise bool
}

BootstrapDeps allows injecting bootstrap dependencies for testing.

Orchestrator is the test seam — implementations of bootstrap.Runner whose Run is invoked by PersistentPreRunE. Client populates the tmuxClientKey context value (helpers like tmuxClient(cmd) panic without it). RegisterHooks is the seam for Portal's global tmux hook registration; when nil (production default), tmux.RegisterPortalHooks is used.

type BootstrapWarningsSink

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

BootstrapWarningsSink accumulates soft bootstrap warnings emitted by the orchestrator. Two consumers drain it:

• The CLI path (PersistentPreRunE for non-TUI commands) calls EmitTo to flush every buffered line to stderr before RunE executes.
• The TUI path (openTUI; Phase 6 task 6-10) drains the sink AFTER the loading page dismisses so direct stderr writes do not corrupt the Bubble Tea alt-screen rendering.

All operations are safe under concurrent use; the orchestrator runs in PersistentPreRunE on the main goroutine but consumers may drain from other goroutines (Bubble Tea runs Update/View off the main goroutine in some flows).

func (*BootstrapWarningsSink) Add

func (s *BootstrapWarningsSink) Add(w bootstrap.Warning)

Add appends a single warning to the sink. Safe for concurrent use.

func (*BootstrapWarningsSink) Drain

func (s *BootstrapWarningsSink) Drain() []bootstrap.Warning

Drain returns every buffered warning and clears the sink atomically. Safe for concurrent use; concurrent callers receive disjoint slices. Returns a nil slice when the sink is empty.

func (*BootstrapWarningsSink) EmitTo

func (s *BootstrapWarningsSink) EmitTo(w io.Writer)

EmitTo drains the sink and writes every warning's lines to w in orchestrator-observation order, one line per Fprintln. Safe for concurrent use — Drain's atomicity guarantees no warning is emitted twice across concurrent EmitTo callers. Delegates to warning.WriteLines so the CLI and TUI paths produce byte-identical stderr output.

type CleanDeps

type CleanDeps struct {
	AllPaneLister AllPaneLister
}

CleanDeps holds injectable dependencies for the clean command. When nil, real implementations are used.

type HooksDeps

type HooksDeps struct {
	KeyResolver StructuralKeyResolver
}

HooksDeps allows injecting dependencies for testing.

type KillDeps

type KillDeps struct {
	Killer    SessionKiller
	Validator SessionValidator
}

KillDeps allows injecting dependencies for testing.

type ListDeps

type ListDeps struct {
	Lister SessionLister
	IsTTY  func() bool
}

ListDeps allows injecting dependencies for testing.

type OpenDeps

type OpenDeps struct {
	AliasLookup  resolver.AliasLookup
	Zoxide       resolver.ZoxideQuerier
	DirValidator resolver.DirValidator
}

OpenDeps allows injecting dependencies for testing.

type PathOpener

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

PathOpener handles creating a new tmux session from a resolved path. It branches on insideTmux: inside tmux creates detached then switches; outside tmux uses exec handoff with -A flag.

func (*PathOpener) Open

func (po *PathOpener) Open(resolvedPath string, command []string) error

Open creates a session at the given path and connects to it. When command is non-nil, it is passed through to session creation for execution as a tmux shell-command.

type SessionConnector

type SessionConnector interface {
	Connect(name string) error
}

SessionConnector connects the user to a tmux session. The implementation differs based on whether Portal is inside or outside tmux.

type SessionKiller

type SessionKiller interface {
	KillSession(name string) error
}

SessionKiller kills a tmux session by name.

type SessionLister

type SessionLister interface {
	ListSessions() ([]tmux.Session, error)
}

SessionLister queries tmux for running sessions.

type SessionValidator

type SessionValidator interface {
	HasSession(name string) bool
}

SessionValidator checks whether a tmux session exists by name.

type StateCleanupDeps

type StateCleanupDeps struct {
	Client     *tmux.Client
	Unregister func(*tmux.Client) error
	Logger     *state.Logger
}

StateCleanupDeps allows injecting test dependencies for the state cleanup command. When nil, real implementations are used: a tmux.Client built on RealCommander, tmux.UnregisterPortalHooks for hook removal, and a best-effort non-rotating *state.Logger for portal.log entries. When non-nil, Client must be supplied; Unregister is optional and falls back to tmux.UnregisterPortalHooks; Logger is optional (a nil *state.Logger is a valid no-op).

type StructuralKeyResolver

type StructuralKeyResolver interface {
	ResolveStructuralKey(paneID string) (string, error)
}

StructuralKeyResolver resolves a tmux pane ID (e.g. "%3") to its structural key (e.g. "my-session:0.0") by querying tmux for session name, window index, and pane index.

type SwitchClienter

type SwitchClienter interface {
	SwitchClient(name string) error
}

SwitchClienter defines the interface for switching tmux clients.

type SwitchConnector

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

SwitchConnector connects to a session by issuing tmux switch-client. Used when Portal is running inside an existing tmux session.

func (*SwitchConnector) Connect

func (sc *SwitchConnector) Connect(name string) error

Connect switches the current tmux client to the named session.

type UsageError

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

UsageError represents an invalid usage error that should exit with code 2.

func NewUsageError

func NewUsageError(msg string) *UsageError

NewUsageError creates a new UsageError with the given message.

func (*UsageError) Error

func (e *UsageError) Error() string

Error returns the error message.