runtime

type ContainerInfo struct {
	ID        string    `json:"id"`
	Name      string    `json:"name"`
	Image     string    `json:"image"`
	Status    string    `json:"status"`
	StartedAt time.Time `json:"startedAt"`
}

type ImageInfo struct {
	// Repository is the full image repository name (e.g. "gsoci.azurecr.io/giantswarm/klaus-toolchains/go").
	Repository string `json:"repository"`
	// Tag is the image tag (e.g. "1.0.0").
	Tag string `json:"tag"`
	// ID is the image ID (short hash).
	ID string `json:"id"`
	// CreatedSince is a human-readable relative time (e.g. "2 hours ago").
	CreatedSince string `json:"createdSince"`
	// Size is a human-readable image size (e.g. "500MB").
	Size string `json:"size"`
}

type RunOptions struct {
	// Name is the container name.
	Name string
	// Image is the container image reference.
	Image string
	// Detach runs the container in background.
	Detach bool
	// User overrides the container user (e.g. "1000:1000").
	// This is essential for bind mounts so the container process matches
	// the host UID that owns the mounted files.
	User string
	// EnvVars are environment variables to set.
	EnvVars map[string]string
	// Volumes are bind mount specifications.
	Volumes []Volume
	// Ports maps host ports to container ports.
	Ports map[int]int
	// ExtraHosts adds custom host-to-IP mappings (--add-host).
	// Each entry is "hostname:ip" (e.g. "host.docker.internal:host-gateway").
	ExtraHosts []string
}

type Runtime interface {
	// Name returns the runtime name ("docker" or "podman").
	Name() string
	// Run starts a new container and returns its ID.
	Run(ctx context.Context, opts RunOptions) (string, error)
	// Stop stops a running container.
	Stop(ctx context.Context, name string) error
	// Remove removes a container.
	Remove(ctx context.Context, name string) error
	// Status returns the container status ("running", "exited", "created", etc.)
	// or an empty string if the container doesn't exist.
	Status(ctx context.Context, name string) (string, error)
	// Inspect returns detailed container information.
	Inspect(ctx context.Context, name string) (*ContainerInfo, error)
	// Logs streams container logs to stdout/stderr. If follow is true, it
	// streams continuously until interrupted. If tail > 0, only the last N
	// lines are shown.
	Logs(ctx context.Context, name string, follow bool, tail int) error
	// LogsCapture returns container log lines as a string instead of
	// streaming to stdout. Useful for programmatic consumers (e.g. MCP tools).
	LogsCapture(ctx context.Context, name string, tail int) (string, error)
	// Pull pulls a container image, streaming progress to w.
	Pull(ctx context.Context, image string, w io.Writer) error
	// Images lists locally cached container images matching the given reference
	// filter pattern (e.g. "*klaus-*"). If filter is empty, all images are returned.
	Images(ctx context.Context, filter string) ([]ImageInfo, error)
}

type Volume struct {
	// HostPath is the path on the host.
	HostPath string
	// ContainerPath is the path inside the container.
	ContainerPath string
	// ReadOnly marks the mount as read-only.
	ReadOnly bool
}