stdio

type Config struct {
	// Command is the MCP server executable: either an absolute path, or a bare
	// name resolved on PATH. It is never a shell string — this transport does
	// not have a shell to give it to — and a relative path is rejected, because
	// what it names depends on a working directory the caller did not state.
	//
	// It is resolved once, by New, so a command that does not exist is a
	// configuration error at construction rather than a connection failure
	// later.
	Command string
	// Args are the command's arguments, passed to execve as separate strings.
	// An argument may carry a secret, so args never appear in RedactedOrigin or
	// in any error this package produces.
	Args []string
	// Dir is the child's working directory. It must be absolute if set; empty
	// means this process's working directory.
	Dir string
	// Env is the child's environment allowlist. The zero value gives the child
	// no environment at all.
	Env EnvAllowlist
	// Launcher creates the process. Nil means a plain argv exec, with the child
	// leading its own process group. A host that confines its servers supplies
	// its own; see ProcessLauncher.
	Launcher ProcessLauncher
	// StderrLimit bounds the child's captured stderr, in bytes. Zero selects
	// DefaultStderrLimit; a negative value is a configuration error. The
	// capture keeps the most recent bytes and drops the rest.
	StderrLimit int
}

type EnvAllowlist struct {
	// Vars are explicit name/value pairs. A name here wins over the same name
	// in PassThrough.
	Vars []Var
	// PassThrough names variables to copy from this process's environment, if
	// they are set. An unset name is simply absent from the child; it is not an
	// error, because "PATH if there is one" is a legitimate thing to ask for.
	PassThrough []string
}

type ExitStatus struct {
	// Code is the exit status, or -1 when a signal ended the process.
	Code int
	// Signal names the signal that ended the process ("terminated",
	// "killed", ...), and is empty when the process exited on its own.
	Signal string
}

type Process interface {
	// Pid reports the process id, for diagnostics only.
	Pid() int
	// Terminate asks the process, and everything it spawned, to shut down.
	Terminate() error
	// Kill destroys the process, and everything it spawned, unconditionally.
	Kill() error
	// Wait blocks until the process has exited and been reaped, and reports how
	// it ended. It is called exactly once. A non-nil error means the process
	// could not be reaped — a non-zero exit is a status, not an error.
	Wait() (ExitStatus, error)
}

type ProcessLauncher interface {
	Start(ctx context.Context, spec ProcessSpec) (Process, error)
}

type ProcessSpec struct {
	// Path is the absolute path of the executable to run. It has already been
	// resolved (via PATH if the configured command was a bare name).
	Path string
	// Args are the arguments after the program name, exactly as os/exec takes
	// them. They are untrusted display-wise — an argument may carry a secret —
	// so a launcher must not log them.
	Args []string
	// Dir is the child's working directory. Empty means the parent's.
	Dir string
	// Env is the child's complete environment, built from an allowlist. An
	// empty (but non-nil) Env means the child gets no environment at all; a
	// launcher must never substitute the parent's for it.
	Env []string
	// Stdin, Stdout and Stderr are the child's three streams. Stdin and Stdout
	// are the MCP transport and carry nothing else. The launcher passes them to
	// the child and does not read, write or close them.
	Stdin  *os.File
	Stdout *os.File
	Stderr *os.File
}

type Var struct {
	// Name is the variable name. It must be non-empty and contain no '=' or
	// NUL byte.
	Name string
	// Value is the value, which may be a secret: it is never logged, never put
	// in an error, and never part of RedactedOrigin.
	Value string
}