usb

type Artifact struct {
	Path     string      // relative path under the output root (forward slashes)
	Contents []byte      // file contents
	Mode     fs.FileMode // 0 means 0644
}

type ArtifactSink interface {
	Add(Artifact) error
}

type BakedRenderer struct{}

type BootEntry struct {
	MenuTitle     string    // shown in the Ventoy boot menu
	BaseImage     string    // ISO/IMG filename this entry boots (operator supplies)
	Renderer      string    // provenance: renderer Name()
	Mode          Mode      // provenance: lifecycle mode
	InstallToDisk bool      // true if this entry persists the OS to the internal disk
	Injection     Injection // how the join payload attaches
}

type BuildOptions struct {
	OutputDir string   // staging directory for artifacts (required unless DryRun)
	Renderers []string // subset of fcos|ubuntu|baked; empty uses config/all
	Modes     []Mode   // subset of ephemeral|install; empty uses both
	Role      Role     // role for install entries (ephemeral always joins as agent)
	DryRun    bool     // plan only; do not resolve coordinates or write files
}

type BuildResult struct {
	OutputDir      string      `json:"output_dir,omitempty"`
	DryRun         bool        `json:"dry_run"`
	Entries        []PlanEntry `json:"entries"`
	RequiredImages []string    `json:"required_images"`
}

type Coordinates struct {
	LANServerURL     string
	TailnetServerURL string
	Token            string
	K3sVersion       string
}

type DirSink struct {
	Root string
}

type FCOSRenderer struct{}

type Injection struct {
	Kind        InjectionKind
	PayloadPath string // relative path of the payload artifact in the sink
	Notes       string // operator-facing notes (also surfaced in ventoy.json)
}

type InjectionKind string

type JoinSpec struct {
	Role       Role
	Mode       Mode
	K3sVersion string // e.g. "v1.30.4+k3s1"; empty installs the k3s default
	Pool       string // node pool label value

	// NodeNamePrefix is combined at boot with the MAC address and hostname to
	// produce a name that is unique per laptop and per boot.
	NodeNamePrefix string

	Token            string // K3s join token (prefer a dedicated agent token)
	LANServerURL     string // e.g. "https://10.0.0.5:6443"; tried first if reachable
	TailnetServerURL string // e.g. "https://100.64.0.5:6443"; Tailscale fallback
	TailscaleAuthKey string // ephemeral, ACL-tagged; empty disables Tailscale

	Ephemeral   bool // add the EphemeralLabel and run as a disposable node
	Scratch     ScratchConfig
	ExtraLabels map[string]string
	ExtraArgs   []string // appended verbatim to the k3s install args

	WiFiSSID string // optional; bring up Wi-Fi before joining (for laptops w/o Ethernet)
	WiFiPSK  string
}

type Mode string

type PlanEntry struct {
	Renderer  string `json:"renderer"`
	Mode      Mode   `json:"mode"`
	MenuTitle string `json:"menu_title"`
	BaseImage string `json:"base_image"`
	Injection string `json:"injection"`
}

type PruneOptions struct {
	TTL    time.Duration // remove NotReady ephemeral nodes whose Ready transition is older than this
	DryRun bool
}

type PruneResult struct {
	DryRun  bool     `json:"dry_run"`
	Stale   []string `json:"stale"`   // nodes selected for removal
	Removed []string `json:"removed"` // nodes actually drained+deleted
}

type Renderer interface {
	Name() string
	Modes() []Mode
	Render(spec JoinSpec, m Mode, sink ArtifactSink) ([]BootEntry, error)
}

type Role string

type ScratchConfig struct {
	Strategy    ScratchStrategy
	Source      string // for ScratchExisting: "LABEL=...", "UUID=..." or "/dev/..."
	ForceFormat bool   // allow formatting an existing partition (destructive)
}

type ScratchStrategy string

type UbuntuRenderer struct{}