executor

type Client struct {
}

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
}

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
}

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
}

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
}