moatinit

type Cmd struct {
	Argv   []string
	Dir    string    // working directory ("" = inherit)
	Env    []string  // nil = inherit the current process environment
	Stdin  io.Reader // nil = /dev/null
	Stdout io.Writer // nil = discard
	Stderr io.Writer // nil = discard

	// LogFile, when set, redirects both stdout and stderr to this file
	// (container-absolute; re-rooted like other fs paths), truncating it —
	// the Go form of `>/var/log/dockerd.log 2>&1`. Overrides Stdout/Stderr.
	LogFile string

	// Timeout, when positive, bounds the run so a hanging probe inside a
	// bounded retry loop cannot consume the loop's whole budget (plan
	// Appendix B: per-attempt timeout below the loop budget). A timed-out
	// command reports a non-zero exit code.
	Timeout time.Duration
}

type Config struct {
	ExtraHosts string // MOAT_EXTRA_HOSTS: space-separated name:target pairs for /etc/hosts
	SSHTCPAddr string // MOAT_SSH_TCP_ADDR: TCP address of the host-side SSH agent proxy

	ClaudeInit string // MOAT_CLAUDE_INIT: staging dir for ~/.claude
	CodexInit  string // MOAT_CODEX_INIT: staging dir for ~/.codex
	// CodexSubscriptionAuth gates the Codex CLI version check: when "1", the
	// staged auth.json is synthetic and only a verified Codex range can read it.
	CodexSubscriptionAuth string // MOAT_CODEX_SUBSCRIPTION_AUTH
	GeminiInit            string // MOAT_GEMINI_INIT: staging dir for ~/.gemini
	CopilotInit           string // MOAT_COPILOT_INIT: staging dir for ~/.copilot

	InitFiles string // MOAT_INIT_FILES: tab-delimited <path>\t<base64> records

	Clipboard string // MOAT_CLIPBOARD: "1" starts Xvfb :99 and exports DISPLAY

	GitUserName  string // MOAT_GIT_USER_NAME
	GitUserEmail string // MOAT_GIT_USER_EMAIL
	GitSSHGitHub string // MOAT_GIT_SSH_GITHUB: "1" sets the github.com insteadOf rewrite

	DockerDIND string // MOAT_DOCKER_DIND: "1" starts dockerd (dind mode)
	DockerGID  string // MOAT_DOCKER_GID: non-empty enables host-socket group mode

	WorkspaceVolume   string // MOAT_WORKSPACE_VOLUME: "1" populates /workspace from staging
	WorkspaceStaging  string // MOAT_WORKSPACE_STAGING: staging source (default /mnt/host-workspace)
	WorkspaceExcludes string // MOAT_WORKSPACE_EXCLUDES: newline-delimited ./-prefixed patterns

	VolumeChown string // MOAT_VOLUME_CHOWN: space-separated named-volume mount roots

	PreRun string // MOAT_PRE_RUN: hook command run in /workspace before the main command

	Home string // HOME of the entrypoint process (target home on the non-root path)
}

type Context struct {
	Sys    Sys
	Cfg    *Config
	Argv   []string  // the user command (the entrypoint's "$@")
	Stdin  io.Reader // inherited by interactive children (pre_run hook)
	Stdout io.Writer // inherited by children that surface output (pre_run hook)
	Stderr io.Writer
}

type OSSys struct {
	Root string

	// resolveTimeout bounds each DNS lookup attempt so a retry loop's total
	// budget is honored even when the resolver hangs (plan Appendix B:
	// per-attempt timeout must stay below the loop budget).
	ResolveTimeout time.Duration
}

type Phase struct {
	Name string
	Run  func(*Context) error
}

type Sys interface {
	// Identity. Lookups use pure-Go os/user (files NSS: /etc/passwd,
	// /etc/group) — parity with the script's `id`/`getent` for the standard
	// moat images; documented divergence for LDAP/SSSD-backed custom images
	// (detection only — the privilege drop itself is delegated to gosu).
	Geteuid() int
	LookupUser(name string) (User, bool)
	LookupGroupByName(name string) (gid string, ok bool)
	LookupGroupByGID(gid string) (name string, ok bool)

	// Process environment. Mirrors the shell's export/unset so that children
	// spawned later (pre_run hook, gosu, the exec'd command) inherit exactly
	// what they would have under the script.
	Getenv(key string) string
	Setenv(key, value string)
	Unsetenv(key string)
	Environ() []string

	// Filesystem.
	Stat(path string) (fs.FileInfo, error)
	MkdirAll(path string, perm fs.FileMode) error
	Chmod(path string, perm fs.FileMode) error
	Chown(path string, uid, gid int) error
	Lchown(path string, uid, gid int) error
	ReadFile(path string) ([]byte, error)
	WriteFile(path string, data []byte, perm fs.FileMode) error
	AppendFile(path string, data []byte) error
	Remove(path string) error
	CopyFilePreserving(src, dst string) error // cp -p
	CopyTreePreserving(src, dst string) error // cp -rp
	WalkDir(root string, fn fs.WalkDirFunc) error
	Getpid() int

	// RealPath maps a container-absolute path to the path a SUBPROCESS must
	// use to reach it. In production this is the identity; under an
	// injected test root it prefixes the root, so phases that hand paths to
	// tar/git/socat (argv or working directory) stay testable against the
	// same tree the filesystem methods manipulate.
	RealPath(path string) string

	// Subprocesses.
	LookPath(file string) (string, error)
	Run(c Cmd) (exitCode int, err error)
	StartDetached(c Cmd) (pid int, err error)
	ProcessAlive(pid int) bool
	Pipe(src, dst Cmd) (srcExit, dstExit int, err error)

	// DNS. ResolveIPv4First is the port of `getent ahostsv4 | awk '{print
	// $1; exit}'`; ResolveAnyFirst of the `getent hosts` fallback. Both
	// consult /etc/hosts then DNS (Go resolver) and return "" on failure.
	ResolveIPv4First(host string) string
	ResolveAnyFirst(host string) string

	Sleep(d time.Duration)

	// Exec replaces the process image (syscall.Exec). It only returns on
	// error. argv[0] is resolved via PATH when not absolute.
	Exec(argv []string, env []string) error
}

type User struct {
	UID int
	GID int
}