devcontainer

type DevcontainerBuild struct {
	Dockerfile string            `json:"dockerfile"` // Dockerfile is the path to the Dockerfile.
	Context    string            `json:"context"`    // Context is the build context directory.
	Args       map[string]string `json:"args"`       // Args holds Docker build arguments.
	Target     string            `json:"target"`     // Target selects a specific build stage.
	CacheFrom  StringSlice       `json:"cacheFrom"`  // CacheFrom lists cache sources.
	Options    []string          `json:"options"`    // Options carries additional build options.
}

type DevcontainerConfig struct {
	Name                        string             `json:"name"`                        // Name is an optional container name override.
	Image                       string             `json:"image"`                       // Image is the base image reference when not building.
	Build                       *DevcontainerBuild `json:"build"`                       // Build describes Docker build settings for the devcontainer.
	DockerComposeFile           StringSlice        `json:"dockerComposeFile"`           // DockerComposeFile lists compose files for Docker Compose mode.
	Service                     string             `json:"service"`                     // Service selects the primary compose service.
	RunServices                 []string           `json:"runServices"`                 // RunServices lists additional compose services to start.
	ShutdownAction              string             `json:"shutdownAction"`              // ShutdownAction controls container shutdown behavior.
	ForwardPorts                PortList           `json:"forwardPorts"`                // ForwardPorts lists ports to forward from the container.
	AppPort                     PortList           `json:"appPort"`                     // AppPort lists application ports for devcontainer tooling.
	ContainerEnv                map[string]string  `json:"containerEnv"`                // ContainerEnv defines environment variables set in the container.
	Mounts                      []MountSpec        `json:"mounts"`                      // Mounts defines additional mounts for the container.
	WorkspaceMount              string             `json:"workspaceMount"`              // WorkspaceMount overrides the workspace mount spec.
	WorkspaceFolder             string             `json:"workspaceFolder"`             // WorkspaceFolder sets the workspace path inside the container.
	RunArgs                     []string           `json:"runArgs"`                     // RunArgs lists extra docker run arguments.
	Privileged                  bool               `json:"privileged"`                  // Privileged requests privileged container mode.
	CapAdd                      []string           `json:"capAdd"`                      // CapAdd adds Linux capabilities.
	SecurityOpt                 []string           `json:"securityOpt"`                 // SecurityOpt supplies security options to Docker.
	Init                        *bool              `json:"init"`                        // Init controls Docker init usage.
	ContainerUser               string             `json:"containerUser"`               // ContainerUser sets the user for the container process.
	RemoteUser                  string             `json:"remoteUser"`                  // RemoteUser sets the default user for lifecycle commands.
	RemoteEnv                   map[string]string  `json:"remoteEnv"`                   // RemoteEnv defines environment variables for remote commands.
	Features                    FeatureSet         `json:"features"`                    // Features declares requested devcontainer features.
	OverrideFeatureInstallOrder []string           `json:"overrideFeatureInstallOrder"` // OverrideFeatureInstallOrder forces feature install order.
	OverrideCommand             *bool              `json:"overrideCommand"`             // OverrideCommand controls entrypoint override behavior.
	InitializeCommand           *LifecycleCommands `json:"initializeCommand"`           // InitializeCommand runs on the host before container create.
	OnCreateCommand             *LifecycleCommands `json:"onCreateCommand"`             // OnCreateCommand runs after the container is created.
	UpdateContentCommand        *LifecycleCommands `json:"updateContentCommand"`        // UpdateContentCommand runs after content updates.
	PostCreateCommand           *LifecycleCommands `json:"postCreateCommand"`           // PostCreateCommand runs after creation tasks.
	PostStartCommand            *LifecycleCommands `json:"postStartCommand"`            // PostStartCommand runs after the container starts.
	PostAttachCommand           *LifecycleCommands `json:"postAttachCommand"`           // PostAttachCommand runs after attaching to the container.
}

type FeatureMetadata struct {
	ID                   string                             `json:"id"`                   // ID is the canonical feature identifier.
	Version              string                             `json:"version"`              // Version is the feature version string.
	Name                 string                             `json:"name"`                 // Name is the human-readable feature name.
	Description          string                             `json:"description"`          // Description explains the feature behavior.
	DocumentationURL     string                             `json:"documentationURL"`     // DocumentationURL points to feature docs.
	LicenseURL           string                             `json:"licenseURL"`           // LicenseURL points to the feature license.
	Keywords             []string                           `json:"keywords"`             // Keywords lists search keywords.
	Options              map[string]FeatureOptionDefinition `json:"options"`              // Options declares configurable feature options.
	ContainerEnv         map[string]string                  `json:"containerEnv"`         // ContainerEnv exports environment variables.
	Privileged           bool                               `json:"privileged"`           // Privileged requests privileged container mode.
	Init                 *bool                              `json:"init"`                 // Init controls Docker init usage.
	CapAdd               []string                           `json:"capAdd"`               // CapAdd adds Linux capabilities.
	SecurityOpt          []string                           `json:"securityOpt"`          // SecurityOpt supplies security options.
	Entrypoint           string                             `json:"entrypoint"`           // Entrypoint points to a feature entrypoint script.
	Customizations       map[string]any                     `json:"customizations"`       // Customizations exposes editor/tooling settings.
	DependsOn            FeatureSet                         `json:"dependsOn"`            // DependsOn declares dependent features.
	InstallsAfter        []string                           `json:"installsAfter"`        // InstallsAfter lists features that should be installed first.
	LegacyIds            []string                           `json:"legacyIds"`            // LegacyIds lists legacy feature identifiers.
	Deprecated           bool                               `json:"deprecated"`           // Deprecated marks the feature as deprecated.
	Mounts               []FeatureMount                     `json:"mounts"`               // Mounts declares feature-provided mounts.
	OnCreateCommand      *LifecycleCommands                 `json:"onCreateCommand"`      // OnCreateCommand runs after container create.
	UpdateContentCommand *LifecycleCommands                 `json:"updateContentCommand"` // UpdateContentCommand runs after content update.
	PostCreateCommand    *LifecycleCommands                 `json:"postCreateCommand"`    // PostCreateCommand runs after creation tasks.
	PostStartCommand     *LifecycleCommands                 `json:"postStartCommand"`     // PostStartCommand runs after container start.
	PostAttachCommand    *LifecycleCommands                 `json:"postAttachCommand"`    // PostAttachCommand runs after attach.
}

type FeatureMount struct {
	Type   string `json:"type"`   // Type is the mount type.
	Source string `json:"source"` // Source is the mount source.
	Target string `json:"target"` // Target is the mount destination in the container.
}

type FeatureOptionDefinition struct {
	Type        string             `json:"type"`        // Type is the option type, such as string or boolean.
	Default     FeatureOptionValue `json:"default"`     // Default is the default option value.
	Enum        []string           `json:"enum"`        // Enum lists allowed values.
	Proposals   []string           `json:"proposals"`   // Proposals lists suggested values for tooling.
	Description string             `json:"description"` // Description explains the option meaning.
}

type FeatureOptionValue struct {
	String *string // String holds the string value when the option is a string.
	Bool   *bool   // Bool holds the boolean value when the option is a bool.
}

type FeatureOptions map[string]FeatureOptionValue

type FeatureReference struct {
	ID         string        // ID is the raw feature identifier string.
	Source     FeatureSource // Source indicates OCI, HTTP, or local resolution.
	Registry   string        // Registry is the OCI registry hostname when Source is OCI.
	Repository string        // Repository is the OCI repository name when Source is OCI.
	Reference  string        // Reference is the OCI tag or digest.
	URL        string        // URL is the HTTP URL when Source is HTTP.
	LocalPath  string        // LocalPath is the path when Source is local.
}

type FeatureSet map[string]FeatureOptions

type FeatureSource string

type LifecycleCommand struct {
	Shell string   // Shell is a shell-form command string.
	Exec  []string // Exec is an argv-style command array.
}

type LifecycleCommands struct {
	Single   *LifecycleCommand       // Single is the single-command form.
	Parallel []NamedLifecycleCommand // Parallel is the named command set for parallel execution.
}

type Mount struct {
	Source      string // Source is the mount source path or volume name.
	Target      string // Target is the mount destination inside the container.
	Type        string // Type is the mount type, such as bind or volume.
	ReadOnly    bool   // ReadOnly marks the mount as read-only.
	Consistency string // Consistency sets the Docker mount consistency mode.
}

type MountSpec struct {
	Raw    string // Raw holds the original string-form mount value, if provided.
	Type   string // Type is the mount type, such as bind or volume.
	Source string // Source is the mount source path or volume name.
	Target string // Target is the mount destination inside the container.
}

type NamedLifecycleCommand struct {
	Name    string           // Name is the identifier for the command entry.
	Command LifecycleCommand // Command is the lifecycle command payload.
}

type PortList []string

type ResolvedFeature struct {
	Reference         FeatureReference       // Reference is the parsed feature reference.
	Metadata          FeatureMetadata        // Metadata is the parsed feature metadata file.
	FeatureDir        string                 // FeatureDir is the resolved feature directory.
	ImageDir          string                 // ImageDir is the optional image build directory.
	Options           ResolvedFeatureOptions // Options holds resolved option values.
	DependencyKey     string                 // DependencyKey is the unique key for dependency resolution.
	DependsOnKeys     []string               // DependsOnKeys are dependency keys for required features.
	InstallsAfterIDs  []string               // InstallsAfterIDs are normalized IDs to install after.
	InstallsAfterKeys []string               // InstallsAfterKeys are resolved keys to install after.
	BaseName          string                 // BaseName is the normalized feature name.
	Tag               string                 // Tag is the OCI tag when resolved from OCI.
	CanonicalName     string                 // CanonicalName is the canonical identifier with digest.
}

type ResolvedFeatureOptions struct {
	Values     map[string]string // Values are resolved option values (defaults + overrides).
	UserValues map[string]string // UserValues are the values explicitly provided by users.
}

type ResolvedFeatures struct {
	Order        []*ResolvedFeature // Order is the installation order for features.
	ContainerEnv map[string]string  // ContainerEnv is the merged container environment.
	Mounts       []MountSpec        // Mounts are the merged mount specs.
	Privileged   bool               // Privileged indicates whether privileged mode is required.
	Init         *bool              // Init reflects merged init settings.
	CapAdd       []string           // CapAdd is the merged capability list.
	SecurityOpt  []string           // SecurityOpt is the merged security options list.
}

type ResourceLimits struct {
	CPUQuota int64  // CPUQuota is the Docker CPU quota value.
	Memory   string // Memory is the memory limit string (e.g. "1g").
}

type StartOption func(*startOptions)

type StringSlice []string