builder

type Builder struct {
	Resolver   *features.Resolver
	Downloader *vscode.Downloader
}

type Options struct {
	// Spec supplies an already loaded configuration. When set, Build and Generate
	// use this snapshot instead of reading SpecPath or discovering another file.
	// The caller must keep it immutable for the duration of the call. Path retains
	// the original configuration location for relative build and feature paths.
	Spec *spec.DevContainer
	// SpecPath is an explicit path to a devcontainer.json. When empty,
	// Workspace is searched for the conventional locations.
	SpecPath string
	// Workspace is the workspace folder the spec was authored for. It
	// is used as the default build context root and to discover the
	// spec when SpecPath is empty.
	Workspace string
	// FeatureBaseDir overrides the directory used to resolve relative
	// local feature references. Empty means the devcontainer.json
	// directory.
	FeatureBaseDir string
	// FeatureLockfile is the invocation's lockfile snapshot. The caller publishes
	// it after the complete command succeeds, including up's lifecycle work.
	FeatureLockfile *features.LockfileState

	// Tags applied to the produced image.
	Tags []string
	// Platforms (e.g., "linux/amd64", "linux/arm64"). The BuildKit
	// engine builds a manifest-list image when more than one is given.
	// --load is incompatible with multi-platform.
	Platforms []string
	// BuildKitAddress selects a separate BuildKit. Empty falls back to
	// BUILDKIT_HOST, then to the Docker daemon's built-in BuildKit.
	BuildKitAddress string
	// Docker is the Engine API client used to reach the daemon. When
	// nil, one is created from the standard DOCKER_* environment.
	Docker *dockerclient.Client
	// RegistryAuth supplies the registry credentials of the call: the
	// BuildKit session and push, OCI feature downloads, and base image
	// configuration reads. When nil, BuildKit reads the docker CLI's
	// configuration (registryauth.FromEnvironment), and feature downloads
	// and image configuration reads use the Builder's Resolver.OCI client.
	RegistryAuth buildkit.RegistryAuth
	// BuildArgs / Labels.
	BuildArgs map[string]string
	Labels    map[string]string
	// CacheFrom / CacheTo cache specs in `docker build` form, e.g.
	// "type=registry,ref=...".
	CacheFrom []string
	CacheTo   []string

	// Push uploads the result to the registry described by Tags.
	Push bool
	// Load loads the result into the Docker daemon's image store.
	Load bool
	// NoCache disables the build cache.
	NoCache bool
	// Pull always re-pulls referenced images.
	Pull bool
	// Progress one of "auto" | "plain" | "tty" | "rawjson".
	Progress string
	// Output is a buildx exporter specification or a local destination path.
	Output string
	// OutputWriter receives archive output when dest is "-" or omitted.
	OutputWriter io.Writer
	// OutputDir, when non-empty, requests filesystem export to this
	// path.
	OutputDir string

	// SkipFeatures disables feature resolution and installation.
	SkipFeatures bool
	// SkipFeatureAutoMapping disables upstream's legacy feature ID mapping.
	SkipFeatureAutoMapping bool
	// Metadata controls only newly persisted feature/config contributions.
	Metadata metadata.CollectOptions
	// OmitSyntaxDirective ignores authored Dockerfile syntax directives and
	// omits the directive from the generated inspection Dockerfile.
	OmitSyntaxDirective bool
	// InstallVSCodeServer stages the VS Code server into the image.
	// Off by default: editors that attach install their own server.
	InstallVSCodeServer bool
	// SkipImageMetaResolve disables the registry roundtrip that
	// inherits ENV/USER/WORKDIR and metadata from the base image.
	// A locally supplied Docker image is still inspected for metadata labels.
	SkipImageMetaResolve bool

	// VSCode controls server resolution. Zero value = stable, current
	// platform, latest commit.
	VSCode vscode.Spec

	// WorkDir is where intermediate artifacts (the generated build
	// context) are written. When empty, a directory under os.TempDir()
	// is used.
	WorkDir string
	// UserDataFolder contains private staging folders when WorkDir is unset.
	UserDataFolder string
	// KeepWorkDir keeps the working directory for inspection after the
	// build. Default removes it.
	KeepWorkDir bool

	// Logger receives informational messages.
	Logger func(format string, args ...any)
	// Stdout / Stderr are forwarded to the build engine.
	Stdout io.Writer
	Stderr io.Writer
}

type Result struct {
	// FinalDockerfile is the path to the inspection-only wrapper
	// Dockerfile.
	FinalDockerfile string
	// ContextDir is the on-disk build context (features + vscode
	// tarball staging directory).
	ContextDir string
	// VSCodeServer reports details on the staged server, if any.
	VSCodeServer *vscode.Result
	// Features is the resolved feature list in install order.
	Features []features.Resolved
}