runtime

type CacheMount struct {
	Name          string `json:"name"`
	Description   string `json:"description"`
	HostPath      string `json:"host_path"`
	ContainerPath string `json:"container_path"` // Resolved target path in the runtime container.
	ReadOnly      bool   `json:"read_only"`
	Shallow       bool   `json:"shallow"`
}

type ConnectionInfo struct {
	AgentTarget      ConnectionTarget
	TailscaleFQDN    string
	TailscaleAuthURL string
}

type ConnectionTarget struct {
	SSHHost string
}

type DirEntry struct {
	Name  string
	IsDir bool
	// Size is the reported size in bytes; a directory reports its own metadata.
	Size int64
	// Modified is the modification time, or nil when the runtime cannot report it.
	Modified *time.Time
}

type Event struct {
	InstanceID ID
	Kind       EventKind
}

type EventFilter struct {
	MetadataKey MetadataKey
}

type EventKind string

type FetchOpts struct {
	// Commit commits the instance's pending changes before fetching, so the
	// host receives them as well.
	Commit bool
}

type FetchedBranch struct {
	// RepositoryPath is the repository's absolute path inside the runtime.
	RepositoryPath string
	// BranchName is the short local branch name, such as "main" or "caic-1".
	BranchName string
	// CommitHash is the full Git object ID of the fetched branch tip.
	CommitHash string
}

type Files interface {
	// ReadFile yields chunks of at most FileChunkSize bytes, borrowed until
	// the next iteration. Empty files yield one empty chunk. Missing files
	// yield fs.ErrNotExist. Offset is a byte offset; length -1 reads to EOF.
	// Stopping iteration releases the reader and process.
	ReadFile(ctx context.Context, id ID, path string, offset, length int64) iter.Seq2[[]byte, error]
	// FileSize returns the current regular-file size; it is not a version validator.
	FileSize(ctx context.Context, id ID, path string) (int64, error)
	// ReadDir returns immediate children of path sorted by name, capped at
	// DirEntryLimit. truncated reports that children were dropped. Missing
	// paths yield fs.ErrNotExist, non-directories ErrIsDir.
	ReadDir(ctx context.Context, id ID, path string) (entries []DirEntry, truncated bool, err error)
}

type ForkOptions struct {
	RuntimeName Name
	Metadata    Metadata
	// Repos is the full set of repositories the fork should contain: every repo
	// already in the source instance plus any new ones to add. Each names its
	// destination primary branch; the caller owns branch uniqueness.
	Repos     []ForkRepo
	Display   bool // Inherit or enable X11/VNC.
	Tailscale bool // Inherit or enable Tailscale.
	USB       bool // Inherit or enable USB.
	Sudo      bool // Inherit or enable root access (password-based sudo).
	Harness   harness.Name
	ExtraEnv  []string  // KEY=VALUE pairs for ~/.env.
	Mounts    []Mount   // Host directories bind-mounted into the fork.
	MaxCPUs   int       // Max CPU cores; 0 means use the default.
	LogWriter io.Writer // Provisioning log output.
}

type ForkRepo struct {
	// GitRoot is the absolute host git repository path (the runtime's GitRoot).
	GitRoot string
	// ContainerPath is the container path to mount a new repo at. Used only for repos
	// not already in the source instance; existing repos keep their mount.
	ContainerPath string
	// SourceBranches are the branches to carry, primary first. For a repo already
	// in the source instance these are its current branches; for a new repo they
	// are the host branches to push (empty defaults to the repo's upstream).
	SourceBranches []string
	// DestPrimary is the fork's primary branch. The caller owns its uniqueness;
	// the runtime uses it verbatim.
	DestPrimary string
}

type GitCommit struct {
	SHA          string
	Subject      string
	Decorations  string
	AuthoredDate string
	Behind       bool // Present only on the comparison branch, not in HEAD's history.
	Stat         []GitFileStat
}

type GitFileStat struct {
	Path         string
	LinesAdded   int
	LinesDeleted int
	Binary       bool
	OldSize      int64 // Byte size of the binary pre-image; zero for added paths.
	NewSize      int64 // Byte size of the binary post-image; zero for deleted paths.
}

type GitFileStatus struct {
	Path           string
	OriginalPath   string
	IndexStatus    string
	WorktreeStatus string
	LinesAdded     int
	LinesDeleted   int
	Binary         bool
	OldSize        int64 // Byte size of the binary pre-image; zero for added paths.
	NewSize        int64 // Byte size of the binary post-image; zero for deleted paths.
}

type ID string

type Instance struct {
	ID            ID
	AgentTarget   ConnectionTarget
	State         string
	Repos         []Repo
	Tailscale     bool
	TailscaleFQDN string
	USB           bool
	Display       bool
	Sudo          bool
	VNCPort       int
}

type InstanceID string

type InstanceInspect struct {
	Runtime         string
	ID              ID
	State           string
	ImageRef        string
	ImageID         string
	OS              string
	CPUArchitecture string
	CPULimit        float64
	Mounts          []Mount
	Caches          []CacheMount
}

type Inventory interface {
	List(ctx context.Context) ([]Instance, error)
	Metadata(ctx context.Context, id ID, key MetadataKey) (string, error)
	Inspect(ctx context.Context, id ID) (*InstanceInspect, error)
}

type Lifecycle interface {
	// Launch starts the runtime instance and writes connection config. It does
	// not wait for transport readiness. Repos must have branches set.
	Launch(ctx context.Context, repos []Repo, opts *StartOptions) (ID, error)
	// Connect waits for transport readiness and completes provisioning for the
	// runtime instance identified by id. It returns optional connection details.
	Connect(ctx context.Context, id ID, opts *StartOptions) (ConnectionInfo, error)
	// Stop gracefully stops the runtime instance without removing it. The
	// instance can be restarted later with Revive.
	Stop(ctx context.Context, id ID) error
	// Purge stops and removes the runtime instance identified by id.
	Purge(ctx context.Context, id ID) error
	// Revive restarts a stopped runtime instance and waits for connectivity.
	// The instance's filesystem is preserved.
	Revive(ctx context.Context, id ID) error
	// Fork snapshots a running or stopped instance and creates a new one where
	// each mapped repo is checked out on a new branch. opts.Repos names the full
	// repo set and each repo's destination primary branch.
	Fork(ctx context.Context, id ID, opts *ForkOptions) (ID, ConnectionInfo, error)
	// VNCPort returns the host port mapped to the runtime instance's VNC port.
	// Returns 0 when the instance has no display.
	VNCPort(ctx context.Context, id ID) int
	// Processes returns the list of running processes inside the runtime instance.
	Processes(ctx context.Context, id ID) ([]ProcessInfo, error)
	// Signal sends a signal to a process inside the runtime instance.
	Signal(ctx context.Context, id ID, pid int, sig string) error
}

type Metadata map[MetadataKey]string

type MetadataKey string

type Monitor interface {
	// DiskUsage returns writable-layer sizes for the requested instances in one
	// batch. Missing entries have no available measurement.
	DiskUsage(ctx context.Context, ids []ID) (map[ID]int64, error)
	WatchStats(ctx context.Context, ids []ID) (iter.Seq2[StatsSample, error], error)
	WatchEvents(ctx context.Context, filter EventFilter) (iter.Seq2[Event, error], error)
}

type Mount struct {
	HostPath      string `json:"host_path"`
	ContainerPath string `json:"container_path"` // Resolved target path in the runtime container.
	ReadOnly      bool   `json:"read_only"`
}

type Name string

type PrivilegeInfo interface {
	SudoPassword(ctx context.Context, id ID) (string, error)
}

type ProcessInfo struct {
	// PID is the process ID.
	PID int
	// PPID is the parent process ID.
	PPID int
	// PGRP is the process group ID.
	PGRP int
	// User is the effective user name.
	User string
	// State is the process state and modifiers reported by the runtime.
	State string
	// Priority is the kernel scheduling priority.
	Priority int
	// Nice is the process niceness value.
	Nice int
	// Threads is the number of threads in the process.
	Threads int
	// OpenFDs is the number of open file descriptors, or nil when unavailable.
	OpenFDs *int
	// CPU is the lifetime-average CPU percentage reported by ps (100% per core).
	CPU float64
	// Mem is the percentage of physical memory used at the time of inspection.
	Mem float64
	// RSSBytes is the resident set size in bytes.
	RSSBytes uint64
	// CPUTime is the cumulative user and system CPU time consumed by the process.
	CPUTime time.Duration
	// StartedAt is when the process started.
	StartedAt time.Time
	// Command is the full command line reported by the runtime.
	Command string
}

type Repo struct {
	GitRoot       string
	ContainerPath string
	Branch        string
	BaseBranch    string
	Remote        string
}

type Repository interface {
	TurnSnapshot(ctx context.Context, id ID, previous []FetchedBranch) ([]TurnRepository, error)
	Diff(ctx context.Context, id ID, repoIdx int, args ...string) (string, error)
	Fetch(ctx context.Context, id ID, opts FetchOpts) ([]FetchedBranch, error)
	// RefreshRefs copies cached upstream refs into the instance without moving
	// working branches or committing pending edits.
	RefreshRefs(ctx context.Context, id ID) error
	FileDiff(ctx context.Context, id ID, repoIdx int, commit, path, originalPath string) (string, error)
	RepositoryStatus(ctx context.Context, id ID, repoIdx int) (RepositoryStatus, error)
	// CompactRepositoryStatus returns the branch, divergence, working-tree
	// counts, operation, and branch-diff numstat of one repository without the
	// per-commit log, cheap enough for periodic activity-driven probes.
	CompactRepositoryStatus(ctx context.Context, id ID, repoIdx int) (RepositoryStatus, error)
}

type RepositoryOperation string

type RepositoryStatus struct {
	Branch      string
	Upstream    string
	Operation   RepositoryOperation
	Ahead       int
	Behind      int
	DiffStat    []GitFileStat
	Commits     []GitCommit
	Uncommitted []GitFileStatus
}

type Router struct {
	Runtimes []System
	ByName   map[Name]System
	// contains filtered or unexported fields
}

type StartOptions struct {
	RuntimeName       Name
	Metadata          Metadata
	BaseImage         string
	ContainerPlatform string
	Harness           harness.Name
	Caches            []CacheMount
	Mounts            []Mount
	Tailscale         bool
	USB               bool
	Display           bool
	Sudo              bool
	// MaxCPUs limits the number of CPU cores the runtime instance may use.
	// Zero means use the runtime adapter default.
	MaxCPUs int
	// GitHubToken is the resolved GitHub token to inject into the runtime
	// environment. Empty means no token is injected.
	GitHubToken string
	// ExtraEnv contains additional KEY=VALUE pairs injected into the runtime
	// environment without being represented in runtime metadata.
	ExtraEnv []string
	// LogWriter receives provisioning log lines from the runtime backend.
	// Must not be nil.
	LogWriter io.Writer
}

type Stats struct {
	Ts          time.Time
	CPUPerc     float64  // 100% is one fully busy logical CPU.
	CPUCeiling  float64  // Configured upper bound in CPU units; zero when unknown. Excludes inherited limits and process affinity.
	CPUQuota    *float64 // Explicit quota in CPU units; zero is unrestricted, nil is unknown.
	RuntimeCPUs int      // Logical CPUs on the owning runtime; zero when unknown.
	CPUError    string   // Runtime CPU metadata observation failure.
	MemUsed     uint64
	MemLimit    uint64
	MemPerc     float64
	NetRx       uint64
	NetTx       uint64
	BlockRead   uint64
	BlockWrite  uint64
	DiskUsed    int64
}

type StatsSample struct {
	InstanceID ID
	Stats      Stats
}

type System interface {
	Name() Name
	Lifecycle
	Files
	Repository
	Monitor
	Inventory
	PrivilegeInfo
}

type TurnRepository struct {
	RepoIndex int
	Status    RepositoryStatus
	Branches  []FetchedBranch
	TurnDiff  []GitFileStat
	StatusErr error
}