docker

type ContainerInfo struct {
	ID         string
	Image      string
	Running    bool
	StartedAt  string
	CreatedAt  string
	Labels     map[string]string
	WorkingDir string
}

type ExecRequest struct {
	// TerminalSize sets the initial PTY size [rows, columns] when TTY is true.
	TerminalSize *[2]uint
	ContainerID  string
	// Cmd is the argv passed to the container. Caller is responsible
	// for shell wrapping (string lifecycle commands wrap with /bin/sh -c
	// before reaching here).
	Cmd []string
	// User is "<uid>[:<gid>]" or a username — same as docker exec -u.
	User string
	// WorkDir is the cwd inside the container.
	WorkDir string
	// Env is appended to the container's environment for this exec.
	Env map[string]string
	// TTY allocates a pseudo-terminal. Required for interactive shells.
	TTY bool
	// Stdin / Stdout / Stderr are forwarded to/from the exec session.
	// Any of them may be nil; nil stdin sends EOF immediately, nil
	// stdout/stderr discards that stream.
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
}

type ExecResult struct {
	ExitCode int
	// Stdout / Stderr capture output IF the request did not provide
	// writers — captured-mode is the default for "did the marker check
	// succeed?" probes. When the request supplies writers, these are
	// empty.
	Stdout []byte
	Stderr []byte
}

type Host struct {
	// contains filtered or unexported fields
}

type Options struct {
	// TerminalSize is the optional lifecycle PTY size [rows, columns].
	TerminalSize *[2]uint
	// Logger receives informational messages. If nil, messages are
	// discarded — appropriate for a service or operator that handles
	// its own structured logging via context.
	Logger func(format string, args ...any)
	// Stdout / Stderr default to nil (silent). Lifecycle command output
	// is written to these unless the per-call request overrides.
	Stdout io.Writer
	Stderr io.Writer
	// StopTimeout bounds how long Stop waits for graceful shutdown
	// before SIGKILL. Defaults to 10s.
	StopTimeout time.Duration
	// RegistryAuth supplies the registry credentials sent with image
	// pulls. When nil, pulls are anonymous. A *registryauth.Store from
	// registryauth.FromEnvironment reads the docker CLI's configuration.
	RegistryAuth RegistryAuth
}

type RegistryAuth interface {
	EngineAuth(ref string) (string, error)
}

type RemoteUserUIDUpdate struct {
	// HostUID / HostGID are the IDs the in-image remoteUser should be
	// remapped to. Typically the embedder calls os.Getuid / os.Getgid
	// on linux/macOS; the package never does so itself.
	HostUID int
	HostGID int
	// DefaultOff requires an explicit updateRemoteUserUID: true in the spec.
	DefaultOff bool
}

type UpRequest struct {
	// ContainerDataFolder selects lifecycle and dotfiles marker storage.
	ContainerDataFolder string
	// ContainerSystemDataFolder selects the upstream system patch marker folder.
	ContainerSystemDataFolder string
	// GPUAvailability controls implicit hostRequirements.gpu requests. Empty means detect.
	GPUAvailability string
	// OmitConfigRemoteEnvFromMetadata omits the current config remoteEnv from new labels.
	OmitConfigRemoteEnvFromMetadata bool
	// Spec is the parsed devcontainer.json. Required.
	Spec *spec.DevContainer
	// SpecPath is the host-side path the spec was loaded from. Stored
	// in the devcontainer.config_file label so upstream tooling can
	// reverse-look-up the source file.
	SpecPath string
	// LocalWorkspace is the host-side workspace folder (absolute).
	// Required: it's the discovery key (devcontainer.local_folder
	// label) and the default bind-mount source.
	LocalWorkspace string
	// ContainerWorkspace is the path inside the container where the
	// workspace is mounted. When empty, falls back to spec
	// workspaceFolder, then "/workspaces/<basename>". Without a spec
	// workspaceFolder, a reused container's bind mounts take precedence.
	ContainerWorkspace string
	// Image is the image reference to run (use pkg/builder to produce
	// one). Up pulls it when the daemon does not have it.
	Image string
	// ImageBuilt means Image was built from this request's spec and features.
	// Its label already contains those contributions; append only runtime updates.
	ImageBuilt bool
	// SkipLifecycle suppresses all lifecycle commands for this invocation.
	SkipLifecycle bool
	// SkipPostAttach suppresses postAttachCommand for this invocation.
	SkipPostAttach bool
	// Dotfiles installs the user's dotfiles after postCreateCommand unless
	// SkipLifecycle is set.
	Dotfiles runner.Dotfiles
	// Lifecycle selects lifecycle stop points and prebuild behavior.
	Lifecycle runner.LifecycleControls
	// RemoteEnv is the caller's remote environment for lifecycle commands
	// and the dotfiles install (upstream --remote-env). The configuration's
	// remoteEnv wins for the same name, as upstream. It is not stored.
	RemoteEnv map[string]string
	// DefaultUserEnvProbe selects the shell probe when userEnvProbe is not configured.
	DefaultUserEnvProbe string
	// Secrets are secret environment variables for lifecycle commands and
	// the dotfiles install (upstream --secrets-file). They win over every
	// other layer and are never stored in container configuration, labels
	// or files.
	Secrets map[string]string

	// Features as resolved by pkg/features. Their containerEnv and
	// lifecycle commands are merged into the container.
	Features []features.Resolved
	// LocalEnv is the host environment used for ${localEnv:VAR}
	// substitution. Pass an empty map (not nil) for no host env.
	LocalEnv map[string]string
	// IDLabels, when non-empty, replace the workspace labels
	// (devcontainer.local_folder, devcontainer.config_file) as the
	// container's identity, as upstream --id-label does: Up reuses only a
	// container that carries all of them, sets exactly them on a new
	// container, and derives ${devcontainerId} from them.
	IDLabels map[string]string
	// WorkspaceMount, when non-nil, replaces the default workspace bind
	// mount (LocalWorkspace at the container workspace folder), for
	// example to mount the workspace's Git root. A spec workspaceMount
	// still wins.
	WorkspaceMount *mount.Mount
	// Mounts are added after the spec's and features' mounts, for example
	// a CLI --mount or a Git worktree's common folder. Up adds no host
	// path that is not in the spec or here.
	Mounts []mount.Mount
	// RemoteUserUIDUpdate, when non-nil, asks the host to remap the
	// container's remoteUser to HostUID/HostGID after the container
	// starts so bind-mounted files land with host-side ownership. The
	// spec's `updateRemoteUserUID: false` overrides and disables the
	// remap regardless. The package never reads os.Getuid itself —
	// embedders pass the IDs they want applied.
	RemoteUserUIDUpdate *RemoteUserUIDUpdate
	// contains filtered or unexported fields
}

type UpResult struct {
	ContainerID     string
	CreatedThisCall bool
	StartedThisCall bool
	// Phases lists the lifecycle phases that actually ran (markers may
	// have skipped some).
	PhasesRun []lifecycle.Hook
}