Documentation
¶
Index ¶
- Constants
- Variables
- func BaseImageTag() string
- func BuildArgv(spec RunSpec, fs FS, lookPath func(string) (string, error)) []string
- func BuildImage(ctx context.Context, configDir string, noCache bool, verbose bool, ...) error
- func BuildSystemPrompt(c config.Config, cellCfg cfg.CellConfig) string
- func ChangedBuildFiles(configDir string) ([]string, bool)
- func DiffBuildFile(configDir, name string) string
- func DiscoverStacks(ctx context.Context, configDir string, out io.Writer) ([]string, error)
- func DockerfileChanged(configDir string) bool
- func EnsureNetwork(ctx context.Context) error
- func ImageExists(ctx context.Context, tag string) bool
- func ImageVersions(ctx context.Context) (base, user string)
- func LocalImageID(ctx context.Context) (string, error)
- func PullImage(ctx context.Context, tag string, verbose bool) error
- func RemoveOrphanedContainer(ctx context.Context, name string) error
- func StackImageTag(stack string) string
- func UpdateFlakeLock(ctx context.Context, configDir string, lockOnly bool, verbose bool, ...) error
- func UserImageTag() string
- type FS
- type FSFunc
- type ImageMetadata
- type RunSpec
Constants ¶
const (
// DefaultRegistry is the fallback registry prefix for devcell images.
DefaultRegistry = "public.ecr.aws/w1l3v2k8/devcell"
)
Variables ¶
var Registry = DefaultRegistry
Registry is the active container registry. Set via cfg.ResolvedRegistry() at startup; defaults to DefaultRegistry.
Functions ¶
func BaseImageTag ¶
func BaseImageTag() string
BaseImageTag returns the base image tag used in scaffold FROM, allowing override via DEVCELL_BASE_IMAGE env var (local dev, CI, tests).
func BuildArgv ¶
BuildArgv constructs the full docker run argv for the given spec. It is pure given injectable FS and LookPath.
func BuildImage ¶
func BuildImage(ctx context.Context, configDir string, noCache bool, verbose bool, out io.Writer) error
BuildImage runs docker build to build UserImageTag from configDir. verbose=true streams plain-text output to out; verbose=false suppresses all docker output (quiet mode) and captures stderr to out for error replay. --pull is always passed so Docker checks for a newer base image digest and busts the layer cache when the upstream image has been updated.
func BuildSystemPrompt ¶ added in v0.3.0
func BuildSystemPrompt(c config.Config, cellCfg cfg.CellConfig) string
BuildSystemPrompt generates the --append-system-prompt content for Claude Code. It describes the container environment, bind mounts, and host path mappings so Claude understands its runtime context.
func ChangedBuildFiles ¶ added in v0.4.0
ChangedBuildFiles returns which build context files are newer than the image. Returns the list of changed file names and true if any changed.
func DiffBuildFile ¶ added in v0.4.0
DiffBuildFile returns a unified diff between the local build context file and the version baked into the image. Returns "" if the file isn't in the image (e.g. Dockerfile) or if they're identical. Uses docker cp to extract.
func DiscoverStacks ¶ added in v0.4.0
DiscoverStacks runs nix flake lock + discovers available stacks from the locked devcell input inside a Docker container. Returns stack names (e.g. "base", "go"). Falls back to nil on error (caller should use hardcoded defaults).
func DockerfileChanged ¶
DockerfileChanged reports whether any build-input file in configDir (Dockerfile, flake.nix) is newer than the user image. Returns true when the user image doesn't exist or inspect fails.
func EnsureNetwork ¶
EnsureNetwork creates the devcell-network docker network if it doesn't exist.
func ImageExists ¶
ImageExists returns true if a Docker image with the given tag exists locally.
func ImageVersions ¶ added in v0.3.0
ImageVersions reads build metadata from the user image. Returns (base, user) strings for backward compatibility with callers.
func LocalImageID ¶
LocalImageID returns the full image ID (sha256:...) of the user image. Used to pin the running container to the exact image just built, rather than the mutable tag which could race with a concurrent build.
func PullImage ¶ added in v0.4.0
PullImage attempts to pull a Docker image. Returns nil on success. When verbose is true, docker pull output is streamed to os.Stderr.
func RemoveOrphanedContainer ¶
RemoveOrphanedContainer removes a stopped container with the given name if it exists. Returns nil if the container doesn't exist or was successfully removed. Returns an error if the container is currently running.
func StackImageTag ¶ added in v0.4.0
StackImageTag returns the registry tag for a pre-built stack image. e.g. "go" → "ghcr.io/dimmkirr/devcell:v1.2.3-go"
func UpdateFlakeLock ¶ added in v0.3.0
func UpdateFlakeLock(ctx context.Context, configDir string, lockOnly bool, verbose bool, out io.Writer) error
UpdateFlakeLock runs nix flake lock (or update) inside a temp base container with configDir bind-mounted. When lockOnly is true, runs "nix flake lock" (resolves inputs, generates lock if missing, doesn't update existing pins). When lockOnly is false, runs "nix flake update" (pulls latest for all inputs).
func UserImageTag ¶
func UserImageTag() string
UserImageTag returns the per-session user image tag. Format: devcell-user:<session> (e.g. devcell-user:main). Override with DEVCELL_USER_IMAGE env var (used by tests).
Types ¶
type ImageMetadata ¶ added in v0.4.0
type ImageMetadata struct {
BaseImage string `json:"base_image"`
Stack string `json:"stack"`
Modules []string `json:"modules"`
GitCommit string `json:"git_commit"`
BuildDate string `json:"build_date"`
Packages int `json:"packages"`
}
ImageMetadata holds structured build metadata from /etc/devcell/metadata.json.
func ImageMetadataFromContainer ¶ added in v0.4.0
func ImageMetadataFromContainer(ctx context.Context) ImageMetadata
ImageMetadataFromContainer reads /etc/devcell/metadata.json from the user image. Falls back to legacy base-image-version + user-image-version files.
func ParseImageMetadata ¶ added in v0.4.0
func ParseImageMetadata(data []byte) ImageMetadata
ParseImageMetadata parses JSON into ImageMetadata. Returns zero value on error.
type RunSpec ¶
type RunSpec struct {
Config config.Config
CellCfg cfg.CellConfig
Binary string
DefaultFlags []string
UserArgs []string
Debug bool // pass DEVCELL_DEBUG=true into the container
Image string // image ID or tag to run; defaults to UserImageTag
ExtraEnv map[string]string // additional env vars injected by the command handler
InheritEnv []string // env var names to inherit from host (passed as -e KEY with no value)
Getenv func(string) string // env lookup; defaults to os.Getenv when nil
}
RunSpec holds everything needed to build the docker run argv.
Source Files