docker

type Config struct {
	// Image is the container image to use. Required.
	Image string

	// StellaHome is the stella-process-view home directory. When stellad runs
	// inside a container this is the in-container path; when it runs on the host
	// this is the host path. Used for orphan cleanup scoping, preflight checks,
	// DooD path translation, and resolving user tool binaries from the plugins
	// manifest.
	StellaHome string

	// RuntimeMode declares how the Docker daemon can access STELLA_HOME. Normally
	// auto-derived from STELLA_DOCKER_SANDBOX_MODE by NewFactory.
	RuntimeMode DockerSandboxMode

	// ContainerPathPrefix / HostPathPrefix enable bind-mount path alignment when
	// stella runs inside a container and talks to the daemon on the host (DooD).
	// Normally auto-derived from STELLA_HOME_HOST by NewFactory; only set
	// explicitly in tests or when overriding the default detection.
	ContainerPathPrefix string
	HostPathPrefix      string

	// StellaHomeVolume is the Docker named volume that backs STELLA_HOME.
	// Set this (via STELLA_HOME_VOLUME env) when stella runs inside a container
	// whose STELLA_HOME is a Docker named volume. Sandbox sessions then use
	// volume subpath mounts (requires Docker Engine 25+) instead of bind mounts,
	// so the host daemon never needs a host-filesystem-visible path.
	// Normally auto-derived from STELLA_HOME_VOLUME by NewFactory.
	StellaHomeVolume string

	// SandboxNetwork, when set, attaches sandbox containers to this Docker
	// network instead of the daemon default bridge. Required in DooD setups
	// where stellad and the sandbox are separate containers: without a shared
	// network the sandbox cannot reach stellad, so server-backed CLI commands
	// (stella task/goal, recally) fail with connection refused. Set via
	// STELLA_SANDBOX_NETWORK, otherwise auto-detected by NewFactory from the
	// network stellad's own container is on.
	SandboxNetwork string

	// ServerURL, when set, is injected into the sandbox as STELLA_SERVER_URL so
	// CLI commands inside the sandbox reach stellad over SandboxNetwork instead
	// of the default 127.0.0.1 loopback (which, inside a separate sandbox
	// container, points at nothing). Set via STELLA_SANDBOX_SERVER_URL, otherwise
	// auto-detected by NewFactory as stellad's address on SandboxNetwork.
	ServerURL string

	// UserToolBinaries are manifest-declared, user-configured CLIs that are not
	// baked into the versioned sandbox image. They are installed in a Linux
	// helper container and exposed to sessions through a Docker-managed tool
	// cache, never through host $STELLA_HOME/bin.
	// Normally auto-resolved by NewFactory from $STELLA_HOME/plugins.yaml.
	UserToolBinaries []ToolBinary
}

type DockerSandboxMode string

type PreflightConfig struct {
	StellaHome string
	Docker     Config
}

type ToolBinary struct {
	Name    string
	Tool    string // mise tool key: uv, bun, github:owner/repo, pipx:pkg, npm:pkg, http:name
	Version string
	Options map[string]any // mise tool options, using the same names as mise.toml
}