executor

Documentation

Overview

Package executor provides utilities for executing external processes with logging.

Index

• Variables
• type Client
  • func NewClient() *Client
  • func (c *Client) ExecStreamedCommand(ctx context.Context, opts *ExecStreamedOpts, name string, args ...string) error
  • func (c *Client) LookPath(file string) (string, error)
  • func (c *Client) ReadStdout(ctx context.Context, name string, args ...string) (string, error)
  • func (c *Client) Run(ctx context.Context, name string, args []string, opts *Options) *Result
  • func (c *Client) RunInRepository(ctx context.Context, caproniConfig *config.CaproniConfig, ...) error
• type CommandRunner
• type ExecStreamedOpts
• type Options
• type Result
  • func (r *Result) CombinedOutput() string

Variables

var (
	// ErrCommandFailed is returned when a command exits with a non-zero status.
	ErrCommandFailed = fmt.Errorf("command exited with non-zero status")
)

Types

type Client

type Client struct {
}

Client implements the CommandRunner interface using actual command execution. This is the production implementation that shells out to real executables.

func NewClient

func NewClient() *Client

NewClient creates a new Client that executes commands.

func (*Client) ExecStreamedCommand

func (c *Client) ExecStreamedCommand(ctx context.Context, opts *ExecStreamedOpts, name string, args ...string) error

ExecStreamedCommand executes a command with streaming output.

func (*Client) LookPath

func (c *Client) LookPath(file string) (string, error)

LookPath searches for an executable in PATH.

func (*Client) ReadStdout

func (c *Client) ReadStdout(ctx context.Context, name string, args ...string) (string, error)

ReadStdout executes a command and returns stdout as a string.

func (*Client) Run

func (c *Client) Run(ctx context.Context, name string, args []string, opts *Options) *Result

Run executes a command with custom options.

func (*Client) RunInRepository

func (c *Client) RunInRepository(
	ctx context.Context,
	caproniConfig *config.CaproniConfig,
	repoConfig *config.RepositoryConfig,
	name string,
	args []string,
	opts *ExecStreamedOpts,
) error

RunInRepository implements CommandRunner.RunInRepository. It executes a command in the repository's directory with decorators applied.

type CommandRunner

type CommandRunner interface {
	// Run executes a command with the given name and arguments.
	// Returns the complete result including stdout, stderr, exit code, and duration.
	// Opts parameter is optional - pass nil to use defaults.
	Run(ctx context.Context, name string, args []string, opts *Options) *Result

	// ReadStdout executes a command and returns stdout as a string.
	// This is designed for commands that output parseable data (JSON, etc.).
	// Stdout is not logged. Returns error if command exits with non-zero status.
	ReadStdout(ctx context.Context, name string, args ...string) (string, error)

	// ExecStreamedCommand executes a long-running command with streaming output.
	// Opts parameter is optional - pass nil to use defaults (UseScrollingArea: true).
	// Supports working directory, process naming, and scroll area control via opts.
	// Returns only exit code/error, not output.
	ExecStreamedCommand(ctx context.Context, opts *ExecStreamedOpts, name string, args ...string) error

	// LookPath searches for an executable in PATH.
	// Wrapper around exec.LookPath with consistent error wrapping.
	LookPath(file string) (string, error)

	// RunInRepository executes a command in the context of a repository with automatic decorators applied.
	// Decorators (like mise wrapper) are applied internally before execution.
	// The working directory is automatically set to the repository's directory.
	RunInRepository(
		ctx context.Context,
		caproniConfig *config.CaproniConfig,
		repoConfig *config.RepositoryConfig,
		name string,
		args []string,
		opts *ExecStreamedOpts,
	) error
}

CommandRunner defines the interface for executing external commands. This interface can be mocked for testing and can be decorated with additional functionality like environment variable injection or mise exec.

type ExecStreamedOpts

type ExecStreamedOpts struct {
	// WorkingDir is the directory to execute the command from.
	// If empty, uses the current directory.
	WorkingDir string

	// UseScrollingArea determines whether to use a scrolling pterm area for TTY output.
	// If true and stderr is a TTY, output is shown in a scrolling area.
	// If false and stderr is a TTY, output is shown with prefixed lines.
	// If stderr is not a TTY, logs are always used regardless of this setting.
	UseScrollingArea bool

	// ProcessDescriptiveName is an identifier for this process, used in log messages
	// to distinguish output from concurrent processes. It may also not be the actual process
	// that is running, if a decorator modified it, for example. The intention is to help
	// users identify an instance.
	ProcessDescriptiveName string
}

ExecStreamedOpts contains options for executing a streamed command.

type Options

type Options struct {
	// Logger is the logger to use for output. If nil, uses slog.Default()
	Logger *slog.Logger
	// LogLevel is the log level to use for stdout output. Defaults to Debug.
	LogLevel slog.Level
	// StderrLogLevel is the log level to use for stderr output. Defaults to Warn.
	StderrLogLevel slog.Level
	// DisableStreaming disables real-time output logging
	DisableStreaming bool
	// Stdin is an optional reader to pipe data to the command's stdin
	Stdin io.Reader
}

Options contains optional configuration for command execution.

type Result

type Result struct {
	// Stdout contains all stdout output lines
	Stdout []string
	// Stderr contains all stderr output lines
	Stderr []string
	// ExitCode is the exit code of the process
	ExitCode int
	// Error is any error that occurred during execution
	Error error
	// Duration is how long the command took to execute
	Duration time.Duration
}

Result contains the result of a command execution.

func (*Result) CombinedOutput

func (r *Result) CombinedOutput() string

CombinedOutput returns stdout and stderr combined as a single string.