install

type Artifact struct {
	// Path is absolute on the device (before any Installer.Root prefix).
	Path string
	// Mode is the file's permission bits.
	Mode os.FileMode
	// Content is the file body.
	Content string
	// Secret marks content that must never be logged, printed by --dry-run,
	// or written world-readable.
	Secret bool
	// Owned marks a file that should be chowned to the service user.
	Owned bool
}

type BootstrapParams struct {
	// Server is the WebSocket URL agents dial, e.g.
	// wss://cloop.example.com/api/executors/connect.
	Server string
	// Pin is the hub's SPKI fingerprint, or "" when the hub has no
	// configured certificate. An empty pin makes the script say so rather
	// than quietly install an unpinned agent.
	Pin string
	// ServiceName overrides the installed unit's name.
	ServiceName string
}

type Dir struct {
	Path string
	Mode os.FileMode
}

type Installer struct {
	// Root prefixes every path. Empty means the real filesystem root.
	// A non-empty Root also disables command execution entirely: a staged
	// install describes a device that is not this machine, so running
	// systemctl or useradd against this one would be wrong even if it
	// happened to work.
	Root string

	// Run executes a command. Nil uses exec.Command. Ignored when Root is
	// set.
	Run Runner

	// Logf receives progress messages. Nil discards them.
	Logf func(format string, args ...any)
}

type Output string

type Plan struct {
	Output Output
	Spec   Spec

	// Dirs are created before Artifacts are written.
	Dirs []Dir

	// Artifacts are the files to write.
	Artifacts []Artifact

	// Display is the operator-facing rendering for --dry-run. It never
	// contains credential material.
	Display string

	// Next lists the follow-up steps Apply performs (or that the operator
	// must perform when the plan targets a system this machine is not).
	Next []string
}

type Runner func(name string, args ...string) error

type Spec struct {
	// ServiceName names the unit, the container, the init script, the
	// system user's home and the state directory. One name so an operator
	// greps for one string.
	ServiceName string

	// User and Group own the credential file and run the process. Empty
	// defaults to ServiceName.
	User  string
	Group string

	// BinaryPath is the cloop binary on the device.
	BinaryPath string

	// StateDir holds the credential file, the agent's long-lived identity,
	// and (by default) the workload root. Empty defaults to
	// /var/lib/<ServiceName>.
	StateDir string

	// UnitDir is where the systemd unit is written. Empty defaults to
	// /etc/systemd/system.
	UnitDir string

	// InitDir is where the OutputShell init script is written. Empty defaults
	// to /etc/init.d.
	//
	// It exists for the same reason UnitDir does. Without it the shell output
	// was the one artifact in this package with no redirectable destination,
	// which made every OutputShell path untestable except against the real
	// /etc/init.d: as root a test would overwrite the host's own service
	// script, and as anyone else it failed outright.
	InitDir string

	// CredentialsFile is the 0600 file the enrollment material is written
	// to. Empty defaults to <StateDir>/enrollment.
	//
	// There is deliberately no way to put the token on the command line
	// instead: a flag that inlines a credential into ExecStart is a flag
	// that will be used, and the resulting unit is world-readable.
	CredentialsFile string

	// AgentCredential is where the agent persists the long-lived identity
	// it receives in exchange for the enrollment token. Empty defaults to
	// <StateDir>/agent.json.
	AgentCredential string

	// WorkDirRoot confines every workload on the device. Empty defaults to
	// <StateDir>/work.
	WorkDirRoot string

	// Server is the control-plane WebSocket URL the agent dials.
	Server string

	// Pin is the hub's SPKI fingerprint ("sha256:<base64>", comma-separated
	// to stage a key rotation). Empty means ordinary PKI verification, which
	// is a real downgrade — see remote.Bundle.
	Pin string

	// Bundle is the encoded enrollment bundle (server + token + pin in one
	// blob). Either this or Token must be set for a first install; both are
	// empty when re-installing over an agent that already holds a
	// credential.
	Bundle string

	// Token is a bare enrollment token, for an operator who has one without
	// a bundle.
	Token string

	// RootCAFile is a PEM bundle to trust in addition to the system store,
	// for a hub behind a private CA.
	RootCAFile string

	// MaxConcurrent bounds simultaneous workloads. Zero lets the agent
	// choose (number of CPUs).
	MaxConcurrent int

	// Labels are scheduler selectors baked into the unit.
	Labels map[string]string

	// Image is the container image for OutputDocker.
	Image string

	// NoStart installs the unit without enabling or starting it, for
	// golden-image builds where the device must not enroll until first boot.
	NoStart bool
}

type UpgradeOptions struct {
	// Source is the new cloop binary to install. Empty means the running
	// executable, which is the common case: an operator copies a new cloop to
	// the device and runs it with --upgrade.
	Source string
	// Force replaces the binary and restarts the service even when the
	// installed binary is already byte-identical. For recovering from a
	// truncated or mis-permissioned install, where the bytes match but the
	// service is not actually running the binary on disk.
	Force bool
	// DryRun performs every check and reports what would happen without
	// writing a byte or restarting anything.
	//
	// It is a real mode rather than a courtesy, because this command bounces a
	// service on a device an operator may not be able to reach again quickly.
	// The checks it runs are the expensive ones — is anything installed, does
	// the source exist, is it even a different build — so a dry run answers
	// "will this do what I think" rather than merely echoing the flags back.
	DryRun bool
}

type UpgradeResult struct {
	// Spec is the normalised spec the upgrade ran against.
	Spec Spec
	// Output is the supervision system involved.
	Output Output
	// Source is the binary that was installed from.
	Source string
	// AlreadyCurrent reports that the installed binary was byte-identical and
	// nothing was changed.
	AlreadyCurrent bool
	// BinaryReplaced reports that the service binary was rewritten.
	BinaryReplaced bool
	// Restarted reports that the service was asked to restart. False with
	// BinaryReplaced true means the service was not running, so the new binary
	// is in place and will be used whenever it is next started.
	Restarted bool
	// DryRun echoes that nothing was actually changed, so a caller cannot
	// render a result as done when it was only planned.
	DryRun bool
	// PreviousChecksum and NewChecksum are SHA-256 sums of the old and new
	// binaries, for an operator correlating a rollout across a fleet.
	//
	// "Checksum" rather than "digest" deliberately. These are content sums of a
	// public binary used to answer "are these the same bytes", not credential
	// material, so comparing them with == is correct — and the security suite's
	// constant-time scanner reads any identifier containing "digest" as a
	// secret. Naming them for what they are keeps that check meaningful instead
	// of adding an exception to it.
	PreviousChecksum string
	NewChecksum      string
}