invoke

type BackoffFunc func(attempt int) time.Duration

type Capabilities struct {
	// TTY reports whether the target can allocate a pseudo-terminal for
	// a command (IO.TTY).
	TTY bool

	// Signals reports whether Process.Signal actually delivers signals
	// to the running process.
	Signals bool

	// SymlinkPreserve reports whether file transfers can recreate
	// symbolic links as links ([SymlinkPreserve]).
	SymlinkPreserve bool
}

type Command struct {
	// Path is the executable to run: a bare name resolved by the target
	// (via its PATH or equivalent), or a path on the target.
	Path string

	// Args are passed to the executable exactly as given, with no shell
	// interpretation. Use [Shell] to run a shell script.
	Args []string

	// Env lists additional environment variables in "KEY=VALUE" form,
	// applied over the target's base environment.
	Env []string

	// Dir is the working directory on the target. Empty means the
	// provider's default for the target.
	Dir string
}

type EntryAction int

type Environment interface {
	io.Closer

	// Start launches cmd on the target with stdio wiring its streams,
	// and returns a handle to the running process.
	//
	// The context owns the process: when ctx is canceled the provider
	// terminates the process promptly, and Wait returns an error
	// matching ctx.Err().
	Start(ctx context.Context, cmd Command, stdio IO) (Process, error)

	// LookPath resolves name to an executable path on the target,
	// searching the target's own lookup path. If the name cannot be
	// resolved, the error wraps [ErrNotFound].
	LookPath(ctx context.Context, name string) (string, error)

	// Upload copies a local file or directory tree to the target.
	// Writes are atomic per file (a failed transfer never corrupts an
	// existing destination), and missing parent directories at the
	// destination are created.
	Upload(ctx context.Context, localPath, remotePath string, opts ...TransferOption) error

	// Download copies a file or directory tree from the target to the
	// local filesystem, with the same atomicity and parent-creation
	// semantics as Upload.
	Download(ctx context.Context, remotePath, localPath string, opts ...TransferOption) error

	// OS reports the target's operating system.
	OS() TargetOS

	// Capabilities reports which optional features this target supports.
	// A declared capability works; an undeclared one fails with an error
	// wrapping [ErrNotSupported]. There is no silent middle ground.
	Capabilities() Capabilities
}

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

type ExitError struct {
	// Code is the exit status. It is -1 when the process was terminated
	// by a signal.
	Code int

	// Signal is set when the process was terminated by a signal instead
	// of exiting.
	Signal Signal

	// Stderr optionally holds a tail of the process's standard error,
	// attached by capture helpers for diagnostics. Providers leave it
	// empty when output went to the caller's own writers.
	Stderr []byte
}

type IO struct {
	// Stdin is the process's standard input. nil means the process sees
	// immediate EOF.
	Stdin io.Reader

	// Stdout receives the process's standard output. nil discards it.
	Stdout io.Writer

	// Stderr receives the process's standard error. nil discards it.
	// Ignored when TTY is set: a pseudo-terminal merges standard error
	// into standard output.
	Stderr io.Writer

	// TTY, when non-nil, allocates a pseudo-terminal for the process.
	// Providers declare PTY support via [Capabilities]; on targets
	// without it, starting a command with TTY set fails with an error
	// wrapping [ErrNotSupported].
	TTY *TTY
}

type Option func(*execConfig)

type Process interface {
	// Wait blocks until the process exits and returns its Result. It is
	// idempotent: repeated calls return the same outcome without
	// blocking again.
	//
	// The (Result, error) pair follows the package error taxonomy: nil
	// error means exit zero; an [ExitError] means the process ran and
	// terminated unsuccessfully; any other error means the process did
	// not run to completion. Cancellation and Close surface as errors
	// matching ctx.Err() or wrapping [ErrClosed] — never as ExitError.
	Wait() (Result, error)

	// Signal delivers sig to the process. It either delivers the signal
	// or returns an error (wrapping [ErrNotSupported] when the target
	// cannot deliver it); it never silently does nothing.
	//
	// What reaches the process is guaranteed. What reaches its children
	// is not, and targets differ: one that runs the command in a process
	// group of its own signals the whole group, which is what a terminal
	// does and what the local machine therefore does; one that can only
	// address a single process signals that one alone. Code that needs a
	// command's children to receive a signal should send it to them
	// rather than rely on which kind of target it is talking to.
	Signal(sig Signal) error

	// Close releases the handle, terminating the process if it is still
	// running. It is idempotent, and it unblocks any Wait in progress —
	// which then reports an error wrapping [ErrClosed], never an
	// ExitError, for a process killed by Close.
	io.Closer
}

type Result struct {
	// ExitCode is the process's exit status. It is -1 when the process
	// was terminated by a signal (the accompanying ExitError carries
	// which one).
	ExitCode int

	// Duration is the wall-clock time from process start until its exit
	// was observed. Observation can lag the exit itself by output-drain
	// time, bounded by the provider's wait timeout.
	Duration time.Duration
}

type Signal string

type SudoOption func(*sudoConfig)

type SymlinkPolicy int

type TTY struct {
	// Cols is the terminal width in character cells. Zero means the
	// default of 80.
	Cols int

	// Rows is the terminal height in character cells. Zero means the
	// default of 24.
	Rows int
}

type TargetOS string

type TransferConfig struct {
	// Mode, when non-nil, is applied to transferred files at the
	// destination (after creation, so it is umask-proof and applies on
	// overwrite too). nil preserves each source file's mode.
	Mode *fs.FileMode

	// Symlinks selects link handling; the zero value is
	// [SymlinkPreserve].
	Symlinks SymlinkPolicy

	// SkipSpecial omits FIFOs, sockets, and device files from transfers
	// instead of failing on them.
	SkipSpecial bool

	// Progress, when non-nil, receives per-file progress updates.
	Progress func(TransferProgress)
}

type TransferOption func(*TransferConfig)

type TransferProgress struct {
	// Path is the file being transferred, relative to the transfer root.
	Path string

	// Current is the number of bytes transferred so far for this file.
	Current int64

	// Total is the file's total size in bytes, or [UnknownTotal] when
	// the size is not known in advance.
	Total int64
}

type TransportError struct {
	// Op names the operation that failed: "start", "wait", "upload",
	// "download", "lookpath".
	Op string

	// Err is the underlying transport failure.
	Err error
}