Documentation
¶
Overview ¶
Package system provides CommandRunner implementations for executing external commands. The canonical CommandRunner interface is defined in core/interfaces; this package provides concrete runners and decorator builders.
Index ¶
- type BufferingRunner
- func (b *BufferingRunner) Captured() []byte
- func (b *BufferingRunner) Exists(name string) bool
- func (b *BufferingRunner) RequireTool(name, installHint string) error
- func (b *BufferingRunner) Run(ctx context.Context, dir, name string, args ...string) error
- func (b *BufferingRunner) RunBuffered(ctx context.Context, dir, name string, args ...string) CmdResult
- func (b *BufferingRunner) RunBufferedWithEnv(ctx context.Context, dir string, extraEnv []string, name string, ...) CmdResult
- func (b *BufferingRunner) RunWithEnv(ctx context.Context, dir string, extraEnv []string, name string, ...) error
- type Builder
- type CmdResult
- type CommandRunner
- type LogFunc
- type Runner
- func (d *Runner) Exists(name string) bool
- func (d *Runner) RequireTool(name, installHint string) error
- func (d *Runner) Run(ctx context.Context, dir, name string, args ...string) error
- func (d *Runner) RunBuffered(ctx context.Context, dir, name string, args ...string) interfaces.CmdResult
- func (d *Runner) RunBufferedWithEnv(ctx context.Context, dir string, extraEnv []string, name string, ...) interfaces.CmdResult
- func (d *Runner) RunWithEnv(ctx context.Context, dir string, extraEnv []string, name string, ...) error
- type RunnerOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BufferingRunner ¶
type BufferingRunner struct {
// contains filtered or unexported fields
}
BufferingRunner wraps a CommandRunner, using buffered execution for Run and RunWithEnv. Output is replayed to stderr/stdout immediately (real-time developer feedback) AND accumulated for later retrieval via Captured(), which populates StepResult.Detail with failure diagnostics.
Use NewQuietBufferingRunner when steps run concurrently to prevent interleaved terminal output.
func NewBufferingRunner ¶
func NewBufferingRunner(inner CommandRunner) *BufferingRunner
NewBufferingRunner wraps inner and replays command output to the terminal.
func NewQuietBufferingRunner ¶
func NewQuietBufferingRunner(inner CommandRunner) *BufferingRunner
NewQuietBufferingRunner wraps inner and captures output without terminal replay.
func (*BufferingRunner) Captured ¶
func (b *BufferingRunner) Captured() []byte
Captured returns all accumulated stdout/stderr from commands run through this runner. Safe to call after the step completes.
func (*BufferingRunner) Exists ¶
func (b *BufferingRunner) Exists(name string) bool
Exists delegates to the inner runner.
func (*BufferingRunner) RequireTool ¶
func (b *BufferingRunner) RequireTool(name, installHint string) error
RequireTool delegates to the inner runner.
func (*BufferingRunner) Run ¶
Run executes a command via RunBuffered, replays output to the terminal, and captures it for later retrieval.
func (*BufferingRunner) RunBuffered ¶
func (b *BufferingRunner) RunBuffered( ctx context.Context, dir, name string, args ...string, ) CmdResult
RunBuffered delegates to the inner runner and captures the output.
func (*BufferingRunner) RunBufferedWithEnv ¶
func (b *BufferingRunner) RunBufferedWithEnv( ctx context.Context, dir string, extraEnv []string, name string, args ...string, ) CmdResult
RunBufferedWithEnv delegates to the inner runner with extra environment variables and captures the output.
func (*BufferingRunner) RunWithEnv ¶
func (b *BufferingRunner) RunWithEnv( ctx context.Context, dir string, extraEnv []string, name string, args ...string, ) error
RunWithEnv executes a command with extra environment variables.
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder constructs a decorated CommandRunner using a fluent API. Decorators are applied inside-out: base -> hook -> timeout -> logging -> dry-run.
func NewBuilder ¶
func NewBuilder(base CommandRunner) *Builder
NewBuilder creates a new Builder wrapping the given base CommandRunner.
func (*Builder) Build ¶
func (b *Builder) Build() CommandRunner
Build constructs the decorated CommandRunner. Decorators are applied inside-out: base -> hook -> timeout -> logging -> dry-run.
func (*Builder) WithDryRun ¶
WithDryRun adds a dry-run decorator that logs what would be executed without actually running commands.
func (*Builder) WithHook ¶
func (b *Builder) WithHook(hook interfaces.CmdHook) *Builder
WithHook adds a hook decorator that fires CmdHook lifecycle callbacks (OnStart, OnSuccess, OnFailure) around every command execution.
func (*Builder) WithLogging ¶
WithLogging adds a logging decorator that logs command name, args, directory, duration, and error after each call.
type CmdResult ¶
type CmdResult = interfaces.CmdResult
CmdResult is a type alias for interfaces.CmdResult.
type CommandRunner ¶
type CommandRunner = interfaces.CommandRunner
CommandRunner is a type alias for interfaces.CommandRunner. system.CommandRunner and interfaces.CommandRunner are identical types; no cast or conversion is needed at any call site.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner implements CommandRunner using real command execution. Run and RunWithEnv stream the child's stdout/stderr to the configured writers (WithOutput) — by default the process's os.Stdout/os.Stderr as they are at Run time, so terminal output flows directly to the user.
func NewRunner ¶
func NewRunner(opts ...RunnerOption) *Runner
NewRunner creates a Runner for real command execution, configured by opts.
func (*Runner) RequireTool ¶
RequireTool returns an error if the named binary is not on PATH.
func (*Runner) RunBuffered ¶
func (d *Runner) RunBuffered( ctx context.Context, dir, name string, args ...string, ) interfaces.CmdResult
RunBuffered executes a command with stdout/stderr captured into buffers.
type RunnerOption ¶ added in v0.3.0
type RunnerOption func(*Runner)
RunnerOption configures a Runner at construction.
func WithOutput ¶ added in v0.3.0
func WithOutput(stdout, stderr io.Writer) RunnerOption
WithOutput streams a child's stdout to stdout and its stderr to stderr instead of the process's own stdio — for a caller that owns the process stdout (a stdio protocol server) or captures output. A nil writer keeps that stream's default. The buffered calls (RunBuffered*) capture into their result and are unaffected.
Source Files