exec

type CommonExecutor struct{}

type Executor interface {
	// Command replaces the standard library os/exec method, allowing mock implementations to
	// control Cmd creation in addition to Cmd execution.
	//
	// Tests may need to use it when asserting mocking a method's (e.g. Buffered) return values
	// and also asserting PipelineResult.Cmd contents. This is because PipelineResult.Cmd is a map
	// indexed by the executed os/exec.Cmd. A mock Command will allow the method (e.g. Buffered)
	// to execute, and also index PipelineResult.Cmd, will the exact same pointer.
	Command(name string, arg ...string) *std_exec.Cmd

	// CommandContext replaces the standard library os/exec method, allowing mock implementations to
	// control Cmd creation in addition to Cmd execution.
	//
	// Tests may need to use it when asserting mocking a method's (e.g. Buffered) return values
	// and also asserting PipelineResult.Cmd contents. This is because PipelineResult.Cmd is a map
	// indexed by the executed os/exec.Cmd. A mock Command will allow the method (e.g. Buffered)
	// to execute, and also index PipelineResult.Cmd, will the exact same pointer.
	CommandContext(ctx context.Context, name string, arg ...string) *std_exec.Cmd

	// Buffered returns standard output/error in addition to the exit code.
	//
	// - Assumes all commands in the pipeline share the passed context.
	// - Return error should be used to determine overall pipeline success.
	//   Per-process results are stored in the return PipelineResult.Cmd map.
	// - If multiple commands are passed, standard out/error between them will be piped.
	// - Returned stdout is only from cmds[len(cmds)-1].
	// - Returned stderr is from all commands. Its ordering is not guaranteed, but per-command stderr
	//   is available in PipelineResult.Cmd Result values.
	Buffered(ctx context.Context, cmds ...*std_exec.Cmd) (stdout *bytes.Buffer, stderr *bytes.Buffer, res PipelineResult, err error)

	// Standard allows standard in, out, and error to be customized.
	//
	// - Assumes all commands in the pipeline share the passed context.
	// - Return error should be used to determine overall pipeline success.
	//   Per-process results are stored in the return PipelineResult.Cmd map.
	// - If multiple commands are passed, standard out/error between them will be piped.
	// - Input stdin will be piped to the first input exec.Cmd.
	// - Input stdout receives only from cmds[len(cmds)-1].
	// - Input stderr receives from all commands. Its ordering is not guaranteed, but per-command stderr
	//   is available in PipelineResult.Cmd Result values.
	Standard(ctx context.Context, stdout io.Writer, stderr io.Writer, stdin io.Reader, cmds ...*std_exec.Cmd) (res PipelineResult, err error)

	// Pty runs the command in a pseudo-terminal and returns an error only if the command fails to start.
	Pty(cmd *std_exec.Cmd) error
}

type PipelineResult struct {
	// Cmd stores more detail about each process executed in the pipeline.
	Cmd map[*std_exec.Cmd]Result
}

type Result struct {
	Code int

	// Pid supports concerns like verifying the process exited.
	Pid int

	// Pgid supports concerns like verifying the process group exited.
	//
	// Values are NOT pre-negated, e.g. for syscall.Kill.
	Pgid int

	Stdout *bytes.Buffer
	Stderr *bytes.Buffer

	Err error
}