runner

type Dotfiles struct {
	// Repository is a Git URL or container path. A value without ":" that
	// does not start with "/", "./" or "../" is a GitHub owner/repository.
	Repository string
	// InstallCommand runs in the clone. Empty runs the first file of
	// install.sh, install, bootstrap.sh, bootstrap, script/bootstrap,
	// setup.sh, setup, script/setup; without one, dotfiles are linked to ~.
	InstallCommand string
	// TargetPath is the clone location; empty means DefaultDotfilesTargetPath.
	// The shell expands it, so "~" names the remote user's home.
	TargetPath string
}

type DotfilesOutcome string

type ExecRequest struct {
	// TerminalSize allocates a lifecycle PTY of [rows, columns]; nil uses pipes.
	TerminalSize *[2]uint
	// Cmd is the argv passed to the container. Lifecycle string
	// commands are wrapped with /bin/sh -c by the runner before they
	// reach the Execer.
	Cmd []string
	// User is the in-container user to run as ("uid[:gid]" or a
	// username). Empty means the container's default.
	User string
	// WorkDir is the cwd inside the container. Empty means the
	// container's default.
	WorkDir string
	// Env is layered on top of the container's existing environment
	// for this exec.
	Env map[string]string
	// Stdin / Stdout / Stderr are forwarded to/from the exec session.
	// nil stdin sends EOF immediately. nil stdout/stderr signals the
	// Execer that the runner wants captured output in the result.
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
}

type ExecResult struct {
	ExitCode int
	// Stdout / Stderr are populated only when the corresponding writer
	// in the request was nil.
	Stdout []byte
	Stderr []byte
}

type Execer interface {
	Exec(ctx context.Context, req ExecRequest) (*ExecResult, error)
}

type LifecycleControls struct {
	SkipNonBlocking        bool
	Prebuild               bool
	StopForPersonalization bool
	WaitFor                string
}

type Options struct {
	// TerminalSize supplies the lifecycle PTY size [rows, columns].
	TerminalSize *[2]uint
	// Logger receives informational messages ("running postCreate
	// [from devcontainer.json]", "skipping ... marker up to date").
	// nil discards.
	Logger func(format string, args ...any)
	// Stdout / Stderr are the default sinks for lifecycle command
	// output. Per-parallel-command output is captured and replayed
	// here under a banner — no interleaving — matching upstream's
	// printMode='off' behavior.
	Stdout io.Writer
	Stderr io.Writer
}

type PhaseResult struct {
	Phase lifecycle.Phase
	Ran   bool
}

type ProbeOptions struct {
	CanPatchSystemConfig bool
	// contains filtered or unexported fields
}

type RunResult struct {
	// Result is the terminal reason; empty if the lifecycle run failed.
	Result StopReason
	Phases []PhaseResult
	// Dotfiles reports the dotfiles step; a failure there is not an error.
	Dotfiles DotfilesOutcome
}

type Runtime struct {
	// User is the lifecycle command user (typically dc.RemoteUser).
	// May be empty: the Execer falls back to the container's default.
	User string
	// Workdir is the cwd lifecycle commands run in.
	Workdir string
	// Env is layered on top of the container env for every lifecycle
	// exec.
	Env map[string]string
	// CreatedAt is the ISO-8601 timestamp marker for WhenOnce phases.
	// On docker, this is ContainerJSON.Created; on kubernetes,
	// pod.CreationTimestamp serialized to RFC3339Nano. Any stable
	// per-creation string works as long as it changes when the
	// container is recreated.
	CreatedAt string
	// StartedAt is the marker for WhenStart phases. Docker uses
	// State.StartedAt; kubernetes uses pod.Status.StartTime. Must
	// change every time the container restarts so postStart re-runs.
	StartedAt string
	// UserDataFolder is the in-container directory that holds the
	// per-hook marker files. Use lifecycle.UserDataFolder(homeDir, "")
	// to get the default.
	UserDataFolder string
	// Dotfiles, when its Repository is set, installs the user's dotfiles
	// after postCreateCommand, once per container. Leave it zero when
	// lifecycle commands are skipped, as upstream does.
	Dotfiles Dotfiles
	// Lifecycle selects stop points and prebuild marker behavior.
	Lifecycle LifecycleControls
}

type StopReason string