devcontainer

type AttachOptions struct {
	// LocalEnv overrides os.Environ() for the substituter's localEnv
	// pass. Nil means use the current process environment.
	LocalEnv map[string]string
}

type ComposeBackend int

type DownOptions struct {
	// Remove, when true, removes the container after stopping it. Default
	// false leaves the container in stopped state for fast subsequent Up.
	Remove bool

	// RemoveVolumes, when true with Remove, also removes anonymous volumes
	// the container created. Has no effect when Remove is false.
	RemoveVolumes bool

	// Events optionally receives structured engine events for the duration
	// of this Down call (container.stopped, container.removed). See package
	// events (experimental until v1.0.0).
	//
	// Ownership: the caller owns the channel. The engine only writes —
	// it never closes the channel. The caller MUST NOT close it before
	// Down returns.
	Events chan<- events.Event
}

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

type EngineOptions struct {
	// Runtime is the container backend. Required.
	Runtime runtime.Runtime

	// FeatureStore overrides the default feature store. Default:
	// feature.NewDiskStore with the cache and auth options below. Tests
	// substitute this with an in-memory store; production callers
	// usually leave it nil and configure via FeatureCacheDir / OCIKeychain
	// instead.
	FeatureStore feature.Store

	// FeatureCacheDir overrides the default OCI / HTTPS feature cache
	// location (os.UserCacheDir()/devcontainer-go/features). Ignored if
	// FeatureStore is set explicitly.
	FeatureCacheDir string

	// OCIKeychain provides credentials for OCI feature pulls. Nil falls
	// back to authn.DefaultKeychain (ambient docker config / env vars /
	// credential helpers). Callers with short-lived registry tokens
	// (e.g. ECR via STS, GCR via metadata-server) supply a custom
	// Keychain that returns fresh credentials per call. Ignored if
	// FeatureStore is set explicitly.
	OCIKeychain authn.Keychain

	// FeatureDownloadHeaders are additional headers to send on HTTPS
	// feature fetches. Ignored if FeatureStore is set explicitly.
	FeatureDownloadHeaders map[string]string

	// FeatureHTTPSClient overrides the default *http.Client for HTTPS
	// feature fetches. Tests use this to drive httptest servers.
	// Ignored if FeatureStore is set explicitly.
	FeatureHTTPSClient *http.Client

	// StrictFeatureVersionMatch controls how the engine decides whether
	// a feature recorded in a base image's devcontainer.metadata label
	// satisfies the request. Default false (permissive: id match plus
	// baked semver >= requested). True requires byte-level equality on
	// the resolved digest — for reproducible builds. See
	// design/features.md §10.3.
	StrictFeatureVersionMatch bool

	// HostExecutor enables host-side spec hooks (initializeCommand,
	// future secretsCommand). Nil means host hooks return a
	// *LifecycleError wrapping ErrHostExecutorNotConfigured, since
	// host execution is opt-in and security-sensitive — see
	// HostExecutor docs.
	HostExecutor HostExecutor

	// ComposeBackend selects how compose-source devcontainers are
	// brought up. ComposeBackendShellout (default) uses the legacy
	// runtime.ComposeRuntime sub-interface, which on docker shells
	// out to the `docker compose` v2 plugin. ComposeBackendNative
	// uses the runtime-agnostic compose.Orchestrator under compose/
	// driving runtime.Runtime primitives directly (no shellout, no
	// compose plugin dependency, works on every backend that
	// satisfies the §4 primitive surface).
	//
	// See design/compose-native.md §10 for the rollout schedule:
	// Shellout stays default until a confirmed-green release on
	// Native; then the default flips and the shellout path is
	// deleted.
	ComposeBackend ComposeBackend
}

type ExecOptions struct {
	Cmd        []string
	Env        map[string]string
	User       string
	WorkingDir string
	Tty        bool
	Stdin      io.Reader
	Stdout     io.Writer
	Stderr     io.Writer

	// SkipUserEnvProbe, when true, makes Exec bypass the merge of
	// probedEnv AND cfg.RemoteEnv into the process environment.
	// Only opts.Env (after substitution) plus whatever the runtime
	// inherits from the container reaches the exec'd process.
	//
	// Default false: every Exec inherits both probedEnv (so PATH and
	// other vars set by the user's rc files are visible — nvm/asdf/
	// feature-installed tools just work) and RemoteEnv (the
	// devcontainer.json author's declared env).
	//
	// Set this for callers that need a clean, deterministic
	// environment — internal probes, low-level fs operations,
	// DiscoverPath-style helpers that read raw container env.
	SkipUserEnvProbe bool

	// EmitEvents, when true and Events is non-nil, sends ExecStartEvent
	// and ExecCompletedEvent for this call. Default false: hot-loop
	// callers (readiness probes that run hundreds of execs per minute)
	// would otherwise drown the events channel.
	EmitEvents bool

	// Events optionally receives ExecStartEvent / ExecCompletedEvent for
	// this call. Used only when EmitEvents is true. See package events
	// (experimental until v1.0.0).
	//
	// Ownership: the caller owns the channel. The engine only writes —
	// it never closes the channel. The caller MUST NOT close it before
	// Exec returns.
	Events chan<- events.Event
}

type ExecResult struct {
	ExitCode int
	Stdout   string // populated only if ExecOptions.Stdout was nil
	Stderr   string // populated only if ExecOptions.Stderr was nil
}

type HostCommand struct {
	// Shell is a single shell command line (`sh -c <Shell>` style).
	// Mutually exclusive with Exec.
	Shell string

	// Exec is a literal argv invocation (no shell). Mutually
	// exclusive with Shell.
	Exec []string

	// Env is merged on top of the host process environment.
	// Implementations decide whether to filter the inherited host
	// env (e.g. drop secrets) or pass it through.
	Env map[string]string

	// WorkingDir is the host directory to run in. Empty leaves the
	// choice to the executor; the engine populates this with the
	// workspace's LocalWorkspaceFolder for spec hooks.
	WorkingDir string
}

type HostExecResult struct {
	ExitCode int
	Stdout   string
	Stderr   string
}

type HostExecutor interface {
	// ExecHost runs a host-side command. The executor is responsible
	// for the shell / exec dispatch (HostCommand.Shell vs
	// HostCommand.Exec — exactly one is set), environment merging,
	// and working-directory selection. Cancellation via ctx must
	// propagate to the spawned process.
	//
	// Return a non-nil error only for executor-internal failures
	// (process couldn't start, I/O error). A non-zero command exit
	// is reported via HostExecResult.ExitCode with a nil error so
	// the engine can wrap it consistently with container-side
	// execution.
	ExecHost(ctx context.Context, cmd HostCommand) (HostExecResult, error)
}

type LifecycleError struct {
	Phase    config.LifecyclePhase
	ExitCode int
	Stdout   string
	Stderr   string
	Cause    error
}

type PullPolicy string

type ResolveOptions struct {
	// LocalWorkspaceFolder is the absolute host path containing the project.
	// Required.
	LocalWorkspaceFolder string

	// ConfigPath is the absolute path to the devcontainer.json file. If
	// empty, Resolve looks for:
	//   <LocalWorkspaceFolder>/.devcontainer/devcontainer.json
	//   <LocalWorkspaceFolder>/.devcontainer.json
	// in that order.
	ConfigPath string

	// LocalEnv overrides os.Environ() for ${localEnv:*} resolution.
	// Nil means use the current process environment.
	LocalEnv map[string]string

	// DevcontainerIDFunc lets callers customize the workspace id derivation.
	// Nil uses config.DevcontainerID(LocalWorkspaceFolder, ConfigPath).
	DevcontainerIDFunc func(localWorkspaceFolder, configPath string) string
}

type ResolvedConfig = config.ResolvedConfig

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

type UpOptions struct {
	// LocalWorkspaceFolder is the absolute host path to the project. Required.
	LocalWorkspaceFolder string

	// ConfigPath is the absolute path to devcontainer.json. If empty,
	// discovered under LocalWorkspaceFolder per Resolve's rules.
	ConfigPath string

	// LocalEnv overrides os.Environ() for ${localEnv:*} resolution.
	// Nil means use the current process environment.
	LocalEnv map[string]string

	// Recreate, when true, stops + removes any existing container with our
	// label and creates a fresh one. Default false: an existing stopped
	// container is restarted (preserving in-container state); an existing
	// running container is attached to.
	Recreate bool

	// PullPolicy controls image pulling. Default IfNotPresent.
	PullPolicy PullPolicy

	// Events optionally receives structured engine events for the duration
	// of this Up call (config resolved, feature resolve, build/pull
	// progress, container lifecycle, spec lifecycle phases). Drop-on-full;
	// the engine never blocks on send. See package events for the type
	// surface (experimental until v1.0.0).
	//
	// Ownership: the caller owns the channel. The engine only writes —
	// it never closes the channel. The caller MUST NOT close it before
	// Up returns; closing a channel while the engine is still sending
	// races with the engine's send and will panic. Close after Up
	// returns (or simply leave the channel open and let it be GC'd).
	Events chan<- events.Event

	// SkipLifecycle, when true, suppresses automatic invocation of
	// devcontainer lifecycle phases (onCreate, postCreate, etc.) from
	// Up. Phases can still be run explicitly via Engine.RunLifecycle.
	// Default false: Up runs the full configured lifecycle.
	SkipLifecycle bool

	// RunInitializeCommand, when true, runs the host-side initializeCommand
	// before container creation. Default false because the spec lets
	// devcontainer.json execute arbitrary host commands; opt-in only.
	// Note: v1 initialize execution is a stub that returns an error;
	// real host execution requires caller-supplied wiring (PRD §11).
	RunInitializeCommand bool

	// RunSecretsCommand, when true, runs the host-side secretsCommand
	// before container creation and merges its stdout (parsed as
	// key=value lines) into the container's environment. Default false
	// for the same reason as RunInitializeCommand: arbitrary host
	// execution is opt-in. Requires EngineOptions.HostExecutor to be
	// set; otherwise a *LifecycleError wrapping
	// ErrHostExecutorNotConfigured is returned.
	//
	// Only applied on fresh container creation. On reattach the
	// existing container's env is already baked, so re-running
	// secretsCommand would have no effect and we skip it; callers
	// wanting a refresh should pass Recreate=true.
	RunSecretsCommand bool

	// ExtraMounts are appended to the mounts derived from devcontainer.json.
	// They layer on top of cfg.WorkspaceMount and cfg.Mounts and are
	// preserved across reattach (they only apply on fresh container
	// creation, since reattach inherits the original container's mounts).
	// For compose sources, only Type == runtime.MountBind entries are
	// honored — other mount types are silently dropped to match the
	// devcontainer.json `mounts` semantics.
	ExtraMounts []runtime.MountSpec

	// ExtraContainerEnv is merged into the container's environment, layered
	// on top of cfg.ContainerEnv. Entries here are baked into the container
	// at start time, so every subsequent exec — including lifecycle scripts
	// and feature install — inherits them. Use this for callers that need
	// to inject host-derived env (PATH overrides, proxy vars, short-lived
	// auth tokens) without mutating devcontainer.json.
	ExtraContainerEnv map[string]string
	// contains filtered or unexported fields
}

type Workspace struct {
	ID WorkspaceID

	// Config is the resolved devcontainer.json. Full after Up; minimal
	// after Attach — see the type-level docs for the field breakdown.
	Config    *config.ResolvedConfig
	Container *runtime.ContainerDetails
	// contains filtered or unexported fields
}

type WorkspaceID string