process

type OnOutputFunc func(typ OutputType, line []byte)

type OutputType int

type Process interface {
	// Env adds or overrides environment variables for the process.
	// Modifies the current process configuration.
	Env(vars map[string]string) Process

	// Input sets the stdin source for the process.
	// By default, processes run without stdin input.
	Input(in io.Reader) Process

	// Path sets the working directory where the process will be executed.
	Path(path string) Process

	// Quietly suppresses all process output, discarding both stdout and stderr.
	Quietly() Process

	// OnOutput registers a handler to receive stdout and stderr output
	// while the process runs. Multiple handlers may be chained depending
	// on the implementation.
	OnOutput(handler OnOutputFunc) Process

	// Run starts the process, waits for it to complete, and returns the result.
	// It returns an error if the process cannot be started or if execution fails.
	Run(name string, arg ...string) (Result, error)

	// Start begins running the process asynchronously and returns a Running
	// handle to monitor and control its execution. The caller must later
	// wait or terminate the process explicitly.
	Start(name string, arg ...string) (Running, error)

	// Timeout sets a maximum execution duration for the process.
	// If the timeout is exceeded, the process will be terminated.
	// A zero duration disables the timeout.
	Timeout(timeout time.Duration) Process

	// TTY attaches the process to a pseudo-terminal, enabling interactive
	// behavior (such as programs that require a TTY for input/output).
	TTY() Process

	// WithContext binds the process lifecycle to the provided context.
	// If the context is canceled or reaches its deadline, the process
	// will be terminated. When combined with Timeout, the earlier of
	// the two deadlines takes effect.
	WithContext(ctx context.Context) Process
}

type Result interface {
	// Successful reports whether the process exited with a zero exit code.
	Successful() bool

	// Failed reports whether the process exited with a non-zero exit code.
	Failed() bool

	// ExitCode returns the process exit code. A zero value typically
	// indicates success, while non-zero indicates failure.
	ExitCode() int

	// Output returns the full contents written to stdout by the process.
	Output() string

	// ErrorOutput returns the full contents written to stderr by the process.
	ErrorOutput() string

	// Command returns the full command string used to start the process,
	// including program name and arguments.
	Command() string

	// SeeInOutput reports whether the given substring is present
	// in the process stdout output.
	SeeInOutput(needle string) bool

	// SeeInErrorOutput reports whether the given substring is present
	// in the process stderr output.
	SeeInErrorOutput(needle string) bool
}

type Running interface {
	// PID returns the operating system process ID.
	PID() int

	// Running reports whether the process still exists according to the OS.
	//
	// NOTE: This may return true for a "zombie" process (terminated but not
	// reaped). You must eventually call Wait() to reap the process and release
	// resources. A common pattern is to poll Running() in a goroutine and then
	// call Wait() in the main flow to ensure cleanup.
	Running() bool

	// Output returns the complete stdout captured from the process so far.
	Output() string

	// ErrorOutput returns the complete stderr captured from the process so far.
	ErrorOutput() string

	// LatestOutput returns the most recent chunk of stdout produced by the process.
	// The definition of "latest" is implementation dependent.
	LatestOutput() string

	// LatestErrorOutput returns the most recent chunk of stderr produced by the process.
	// The definition of "latest" is implementation dependent.
	LatestErrorOutput() string

	// Wait blocks until the process exits and returns its final Result.
	// This call is required to reap the process and release system resources.
	Wait() Result

	// Stop attempts to gracefully stop the process by sending the provided signal
	// (defaulting to SIGTERM). If the process does not exit within the given timeout,
	// it is forcibly killed (SIGKILL).
	Stop(timeout time.Duration, sig ...os.Signal) error

	// Signal sends the given signal to the process. Returns an error if the process
	// has not been started or no longer exists.
	Signal(sig os.Signal) error
}