md

type AgentPaths struct {
	// Description is a short human-readable label for the harness (e.g.
	// "Claude Code"). Displayed in settings UI.
	Description string
	// ReadOnly mounts all paths in this group read-only.
	ReadOnly bool

	HomePaths       []string
	XDGConfigPaths  []string
	LocalSharePaths []string
	LocalStatePaths []string
}

type CacheMount struct {
	// Name identifies the cache in progress output and Docker build contexts.
	// It must match [a-z0-9][a-z0-9-]*, e.g. "go-mod".
	Name string
	// Description is a short human-readable label for the cache group (e.g.
	// "Go module cache"). Displayed in settings UI.
	Description string
	// HostPath is the absolute path on the host. "~" and "~/" resolve to the
	// host user's home directory.
	HostPath string
	// ContainerPath is the path inside the container. "~" and "~/" resolve to
	// the container user's home directory via [ResolveContainerPath]. When empty,
	// it mirrors a home-relative HostPath via [ResolveMountTarget].
	ContainerPath string
	// ReadOnly copies the cache into the image as root-owned, non-writable files.
	ReadOnly bool
	// Shallow copies only top-level files from HostPath, ignoring
	// subdirectories. Useful for directories like ~/.android where only a few
	// files (debug.keystore, adbkey) are needed but subdirectories (avd/,
	// cache/) are large and unwanted.
	Shallow bool
}

type Client struct {
	// Paths.
	Home          string
	XDGConfigHome string
	XDGDataHome   string
	XDGStateHome  string

	// SSH key paths.
	HostKeyPath string // ~/.config/md/ssh_host_ed25519_key (generated)
	UserKeyPath string // ~/.ssh/md

	// Runtime is the Docker or Podman runtime.
	Runtime containers.Runtime

	// Logger receives md package logs. It must be non-nil.
	Logger *slog.Logger

	// ControlMaster enables SSH ControlMaster connection multiplexing.
	// When true, SSH connections are shared via a persistent socket,
	// reducing connection overhead. Disabled by default because stale
	// sockets can cause connectivity issues that are hard to diagnose.
	ControlMaster bool

	// Tokens.
	GithubToken string // GitHub API token for Docker build secrets.
	// TailscaleAPIKey is the Tailscale API key for auth key generation and device deletion.
	//
	// It is necessary to setup ephemeral nodes. The key must be rotated every 90 days.
	//
	// See https://tailscale.com/docs/reference/tailscale-api and
	// https://tailscale.com/docs/features/ephemeral-nodes
	TailscaleAPIKey string

	// DigestCacheTTL controls how long remote image digest lookups are cached.
	// When zero, caching is disabled and the registry is queried on every start.
	DigestCacheTTL time.Duration
	// contains filtered or unexported fields
}

type Container struct {
	// Client is the client that created this container.
	*Client

	// Logger receives logs for this container. It includes the cntr attribute.
	Logger *slog.Logger
	// Repos are the git repositories in this container. Repos[0] is the
	// primary; the rest are pushed alongside it. Each repo's ContainerPath
	// gives the absolute destination path.
	// Label: md.repos (base64-encoded JSON)
	Repos []Repo
	// Name is the Docker container name (e.g. "md-myrepo-main").
	Name string
	// State is the Docker container state (e.g. "running", "exited").
	State string
	// CreatedAt is when the container was created.
	CreatedAt time.Time
	// Labels contains all Docker/Podman labels observed on the container.
	Labels map[string]string
	// Display indicates the container was started with X11/VNC enabled.
	// Label: md.display
	Display bool
	// Tailscale indicates the container was started with Tailscale networking.
	// Label: md.tailscale
	Tailscale bool
	// USB indicates the container was started with USB passthrough.
	// Label: md.usb
	USB bool
	// Sudo indicates root access via sudo is enabled.
	// Label: md.sudo
	Sudo bool
	// SSHPort is the host port mapped to the container's SSH port.
	// Set by Launch; available immediately after Launch returns.
	SSHPort int32
	// VNCPort is the host port mapped to the container's VNC port, if display is enabled.
	// Set by Launch; available immediately after Launch returns. Zero if display is disabled.
	VNCPort int32
	// contains filtered or unexported fields
}

type DiffOpts struct {
	// Args are extra arguments forwarded to git diff, for example "--stat".
	Args []string
	// Full reports the whole branch, from the merge base with its upstream,
	// instead of only the work not yet integrated into the host branch.
	Full bool
}

type FetchOpts struct {
	// Provider generates the commit message when Commit is set. A nil Provider
	// uses a fixed message.
	Provider genai.Provider
	// ContextTokens is the selected model's context window. Zero uses the
	// commit-message generator default.
	ContextTokens int
	// Commit stages and commits the container's pending changes before
	// fetching, so the host receives them as well. Leave it unset to observe
	// the container without changing its history or its working tree.
	Commit bool
	// NoVerify passes --no-verify to the container commit, skipping the
	// pre-commit and commit-msg hooks. It has no effect unless Commit is set.
	NoVerify bool
}

type FetchedBranch struct {
	// BranchName is the short local branch name in the container, such as
	// "main" or "caic-1".
	BranchName string
	// CommitHash is the full Git object ID of the fetched branch tip.
	CommitHash string
}

type ForkOpts struct {
	// Repos is the full set of repositories the fork should contain. It must
	// include an entry for every repo in the source container (identified by
	// GitRoot); additional entries are new repos initialized in the fork and
	// pushed from the host. Fork fails if a source-container repo is missing, if
	// GitRoots are duplicated, or if a DestPrimary is empty.
	Repos []ForkRepo
	// Display enables X11/VNC virtual display on the forked container.
	Display bool
	// Tailscale enables Tailscale networking on the forked container.
	Tailscale bool
	// USB enables USB device passthrough on the forked container.
	USB bool
	// Sudo enables root access via sudo on the forked container.
	Sudo bool
	// Labels are additional Docker labels (key=value) applied to the forked container.
	Labels []string
	// Quiet suppresses informational output.
	Quiet bool
	// ExtraEnv holds environment updates to inject into the container's ~/.env.
	// Entries use KEY=VALUE to set a value or KEY= to remove one. Values are
	// shell-quoted before writing, so they may contain spaces and newlines.
	ExtraEnv []string
	// Mounts lists host directories to bind-mount into the running container.
	// Missing host directories are rejected before the runtime is invoked.
	Mounts []Mount
	// MaxCPUs limits the number of CPU cores the forked container may use.
	// Passed as --cpus to docker/podman. Zero means no limit.
	// Use [DefaultMaxCPUs] to calculate a default from the runtime CPU count.
	MaxCPUs int
	// ExtraRunArgs are additional arguments passed verbatim to the
	// container runtime's "run" command. Not portable across runtimes.
	ExtraRunArgs []string
}

type ForkRepo struct {
	// GitRoot is the absolute path of the host git repository. Fork matches it
	// against the source container's repos: a match is re-branched from the
	// snapshot, a non-match is initialized in the fork and pushed from the host.
	GitRoot string
	// SourceBranches are the branches to carry, primary first. For a repo present
	// in the source container it must equal the branches recorded on that repo
	// (Fork validates this). For a new repo it is the host branches to push; if
	// empty, it defaults to the repo's default upstream branch.
	SourceBranches []string
	// ContainerPath is the absolute container path to mount a new repo at. It is
	// used only for repos not already in the source container (existing repos
	// keep the snapshot's mount path). When empty, it defaults to
	// /home/user/src/<basename>.
	ContainerPath string
	// TagRegexp selects tags for a new repo. Existing source repos retain their
	// persisted tag selection.
	TagRegexp string
	// DestPrimary is the fork's primary branch, created from SourceBranches[0].
	// It must not be one of the repo's mapped branches, since Fork force-resets
	// the destination host branch. Fork does not check it against other
	// containers' branches or unrelated local refs, so the caller still owns
	// uniqueness there. Additional (non-primary) branches keep their source
	// names.
	DestPrimary string
}

type Harness string

type InspectInfo struct {
	Runtime      string
	ID           string
	Name         string
	State        string
	ImageRef     string
	ImageID      string
	Platform     string
	OS           string
	Architecture string
	CPULimit     float64 // Explicit quota in CPU units; zero means unrestricted.
	CPUSet       []int   // Sorted configured logical CPU IDs; empty means inherited.
	Mounts       []Mount
	Caches       []CacheMount
}

type Mount struct {
	// HostPath is the absolute path on the host. "~" and "~/" resolve to the
	// host user's home directory.
	HostPath string
	// ContainerPath is the path inside the container. "~" and "~/" resolve to
	// the container user's home directory via [ResolveContainerPath]. When empty,
	// it mirrors a home-relative HostPath via [ResolveMountTarget].
	ContainerPath string
	// ReadOnly mounts the host path read-only.
	ReadOnly bool
}

type Platform string

type PullOpts struct {
	// Provider generates the commit message. A nil Provider uses a fixed message.
	Provider genai.Provider
	// ContextTokens is the selected model's context window. Zero uses the
	// commit-message generator default.
	ContextTokens int
	// NoVerify passes --no-verify to the container commit, skipping the
	// pre-commit and commit-msg hooks.
	NoVerify bool
}

type Repo struct {
	// GitRoot is the absolute path to the git repository root on the host.
	GitRoot string `json:"git_root"`
	// Branches lists the git branches to push into the container.
	// Branches[0] is the primary branch (checked out in the working tree,
	// used for container naming). Branches[1:] are also available as local
	// branches. Each branch tracks the same upstream as its host branch.
	Branches []string `json:"branches"`
	// ContainerPath is the absolute destination path inside the
	// container, e.g. "/home/user/src/github/caic". When empty,
	// populateContainerPath fills it from filepath.Base(GitRoot).
	// When two repos share the same basename, resolveContainerPaths
	// disambiguates using relative paths from /home/user/src.
	// Callers may set it explicitly to override.
	ContainerPath string `json:"container_path,omitempty"`
	// Remotes lists the host remotes whose cached branches are mirrored into the container.
	Remotes []string `json:"remotes,omitempty"`
	// TagRegexp selects host tags to mirror into the container. Empty selects no tags.
	TagRegexp string `json:"tag_regexp,omitempty"`
	// DefaultRemote is the host's default git remote. When empty, the upstream
	// remote tracked by local main or master takes precedence over origin.
	DefaultRemote string `json:"default_remote,omitempty"`
	// DefaultBranch is the default branch for DefaultRemote.
	DefaultBranch string `json:"default_branch,omitempty"`
}

type Runtime string

type StartOpts struct {
	// BaseImage is the full Docker image reference (e.g.
	// "ghcr.io/caic-xyz/md-user:v0.7.1" or "myregistry/custom:tag"). When empty,
	// DefaultBaseImage is used.
	BaseImage string
	// Platform is the Linux container platform, e.g. "linux/amd64" or
	// "linux/arm64". Empty means use the host's native platform.
	Platform string
	// GitObjectCopyMinBytes is the minimum object store size for copying Git
	// objects into a new container before the initial push. Zero uses the
	// default, -1 disables copying, and 1 includes every nonempty object store.
	GitObjectCopyMinBytes int64
	// Display enables X11/VNC virtual display (port 5901).
	Display bool
	// Tailscale enables Tailscale networking inside the container.
	//
	// It is recommended to set Client.TailscaleAPIKey to enable ephemeral nodes. If Client.TailscaleAPIKey is
	// not set, the node will not be ephemeral. Instead, an authentication URL will be printed back by md.
	Tailscale bool
	// TailscaleAuthKey is a pre-authorized Tailscale auth key.
	//
	// When empty and Tailscale is true, Client.TailscaleAPIKey is used to generate an authentication key.
	//
	// The tailnet policy must allow "tag:md".
	//
	// https://tailscale.com/docs/features/access-control/auth-keys
	TailscaleAuthKey string
	// USB enables USB device passthrough (Linux only).
	USB bool
	// Sudo enables password-based sudo for the user account. A random
	// password is generated per container and stored as a container label;
	// retrieve it with `md sudo-password`. Defaults to false.
	Sudo bool
	// Caches lists host directories to COPY into the image at build time.
	// Use well-known names from [WellKnownCaches] or construct [CacheMount]
	// values directly. Paths that do not exist on the host are silently skipped.
	Caches []CacheMount
	// Mounts lists host directories to bind-mount into the running container.
	// Missing host directories are rejected before the runtime is invoked.
	Mounts []Mount
	// Labels are additional Docker labels (key=value) applied to the container.
	Labels []string
	// Quiet suppresses informational output during startup.
	Quiet bool
	// ExtraEnv holds environment updates to inject into the container's ~/.env.
	// Entries use KEY=VALUE to set a value or KEY= to remove one. Values are
	// shell-quoted before writing, so they may contain spaces and newlines.
	ExtraEnv []string
	// MaxCPUs limits the number of CPU cores the container may use.
	// Passed as --cpus to docker/podman. Zero means no limit.
	// Use [DefaultMaxCPUs] to calculate a default from the runtime CPU count.
	MaxCPUs int
	// ExtraRunArgs are additional arguments passed verbatim to the
	// container runtime's "run" command. Not portable across runtimes.
	ExtraRunArgs []string
	// contains filtered or unexported fields
}

type StartResult struct {
	// TailscaleFQDN is the Tailscale FQDN assigned to the container, if any.
	TailscaleFQDN string
	// TailscaleAuthURL is the Tailscale auth URL when no pre-auth key was provided.
	TailscaleAuthURL string
}

type WarmupOpts struct {
	// BaseImage is the full Docker image reference. When empty,
	// DefaultBaseImage+":latest" is used.
	BaseImage string
	// Platform is the Linux container platform. Empty means use the host's
	// native platform.
	Platform string
	// Caches lists host directories to COPY into the image at build time.
	Caches []CacheMount
	// Quiet suppresses informational output.
	Quiet bool
	// Force rebuilds the specialized image even when its inputs are unchanged.
	Force bool
}