runner

type Handle interface {
	// Wait blocks until the process exits and returns its captured output.
	Wait() (Result, error)
	// Signal delivers signal to the process. Once the process has already
	// been waited on, it reports an error (never a panic) rather than
	// signalling an unrelated, possibly-reused pid.
	Signal(signal os.Signal) error
	// Pid reports the started process's process id.
	Pid() int
}

type Real struct{}

type Result struct {
	Stdout string
	Stderr string
	// CombinedOutput is populated only when RunOptions.CaptureCombined is set.
	CombinedOutput string
	ExitCode       int
}

type RunOptions struct {
	// CaptureCombined sends stdout and stderr to one pipe and preserves their
	// observed order, as exec.Cmd.CombinedOutput does. When set, the capture
	// is returned in Result.CombinedOutput instead of Stdout and Stderr.
	CaptureCombined bool
	// Env overrides the child's environment. Nil inherits the calling
	// process's own environment, matching os/exec.Cmd's own default when
	// Env is left nil. RunWithInput does the same; Real.Run supplies
	// console.Env() instead.
	Env []string
	// Stdin is written to the child's stdin before its output is read, like
	// RunWithInput's input. Nil/empty gives the child no stdin (the same as
	// Run).
	Stdin []byte
	// WaitDelay bounds how long RunOpts waits for the child's I/O pipes to
	// drain after the process itself has exited (os/exec.Cmd.WaitDelay).
	// Zero uses the underlying implementation's own default -- Real inherits
	// internal/process's, not zero/unbounded -- so a caller that genuinely
	// needs a specific bound (a package-manager launcher that hands off to a
	// grandchild and exits early) sets one explicitly rather than relying on
	// whatever internal/process happens to default to today.
	WaitDelay time.Duration
	// StdoutLimit, when positive, caps the standard output RunOpts buffers:
	// the first write that would pass it is refused, nothing beyond the cap
	// is ever held, the child is stopped by its closed pipe or by ctx, and
	// RunOpts returns ErrOutputTooLarge with Result.Stdout holding only what
	// fitted. It does not apply with CaptureCombined.
	StdoutLimit int
	// DiscardStderr sends the child's standard error to the null device
	// instead of buffering it: Result.Stderr stays empty. For a caller that
	// runs a child it does not trust and must neither hold nor surface what
	// that child prints there.
	DiscardStderr bool
}

type Runner interface {
	// Run starts name with args in dir, waits for it to exit, and returns
	// its captured stdout, stderr and exit status.
	Run(ctx context.Context, dir, name string, args ...string) (Result, error)
	// RunWithInput is Run with input written to the child's stdin before its
	// output is read. See the package doc's note on why this exists
	// alongside Run rather than folding input into it.
	RunWithInput(ctx context.Context, dir string, input []byte, name string, args ...string) (Result, error)
	// RunOpts is Run with a RunOptions value: a per-call environment,
	// stdin, and/or WaitDelay. See the package doc's note on RunOpts.
	RunOpts(ctx context.Context, dir string, opts RunOptions, name string, args ...string) (Result, error)
	// Start begins name with args in dir and returns a Handle without
	// waiting for it to exit.
	Start(ctx context.Context, dir, name string, args ...string) (Handle, error)
	// Detach starts name with args in dir as a process that outlives the
	// caller, and reports its process id.
	Detach(dir, name string, args ...string) (pid int, err error)
	// Interactive starts name with args in dir with stdio passed through to
	// the caller's own, and waits for it to exit.
	Interactive(ctx context.Context, dir, name string, args ...string) error
}