cmdrunner

Documentation

Overview

Package cmdrunner provides context-aware external command execution.

This package wraps os/exec to provide command execution with proper context support for cancellation and timeouts. All commands are executed with structured error handling via apperrors.CommandError.

Functions

RunCommandContext executes a command with stdout/stderr connected to the terminal, suitable for interactive commands or those with visible output:

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
err := cmdrunner.RunCommandContext(ctx, "/path/to/dir", "git", "status")

RunCommandOutputContext executes a command and captures its combined output, suitable for commands whose output needs to be processed:

output, err := cmdrunner.RunCommandOutputContext(ctx, ".", "git", "rev-parse", "HEAD")

Timeout Handling

The package defines default timeout constants:

• DefaultTimeout: 30 seconds for general commands
• DefaultOutputTimeout: 5 seconds for output-capturing commands

When a command times out, the returned error will have Timeout set to true in the apperrors.CommandError struct.

Index

• Constants
• func RunCommandContext(ctx context.Context, dir string, command string, args ...string) error
• func RunCommandOutputContext(ctx context.Context, dir string, command string, args ...string) (string, error)

Constants

const (
	DefaultTimeout       = core.TimeoutDefault
	DefaultOutputTimeout = core.TimeoutShort
)

Default timeouts for command execution. These reference the centralized timeout constants in core package.

Functions

func RunCommandContext

func RunCommandContext(ctx context.Context, dir string, command string, args ...string) error

RunCommandContext executes a command with the given context. The context should be used to control cancellation and timeouts.

Security: Arguments are passed directly to exec.CommandContext (not shell-interpreted), preventing command injection. The command parameter should be a trusted executable name, not user input. Arguments in args are safely escaped by the Go runtime.

func RunCommandOutputContext

func RunCommandOutputContext(ctx context.Context, dir string, command string, args ...string) (string, error)

RunCommandOutputContext executes a command and returns its output. The context should be used to control cancellation and timeouts.

Security: Arguments are passed directly to exec.CommandContext (not shell-interpreted), preventing command injection. The command parameter should be a trusted executable name, not user input. Arguments in args are safely escaped by the Go runtime.