resolverprofile

type Applier interface {
	// DetectHost returns the real facts about this machine (forwarder on PATH,
	// systemd-resolved active, elevation) for an accurate render. It never needs
	// privileges.
	DetectHost() Host
	// Apply executes r.Apply in order. Returns ErrNeedsRoot (wrapped) when the
	// plan mutates system state and the process is not privileged - the caller
	// then prints the exact block instead.
	Apply(r Rendered) error
	// Revert executes r.Revert in order; guards make it idempotent (safe twice,
	// safe when nothing was ever applied).
	Revert(r Rendered) error
}

type FileSpec struct {
	Path    string      `json:"path"`
	Content string      `json:"content"`
	Mode    fs.FileMode `json:"-"`
}

type Host struct {
	// ResolvedActive: systemd-resolved is running (Linux only).
	ResolvedActive bool
	// ForwarderPath/ForwarderKind: a USABLE local DoH forwarder (Linux DoH needs
	// one - systemd-resolved cannot speak DoH). Kind is "cloudflared",
	// "dnscrypt-proxy", or "".
	ForwarderPath string
	ForwarderKind string
	// ForwarderVersion is the detected version of that forwarder ("2.0.45",
	// "2.1.7"); the render adapts the emitted config to what the shipped
	// version actually accepts (stock Ubuntu 24.04 ships dnscrypt-proxy 2.0.45,
	// which FATALs on the 2.1 config key - proven live).
	ForwarderVersion string
	// ForwarderRejected explains a forwarder that was found but cannot serve
	// (e.g. cloudflared >= 2026.2.0, which removed proxy-dns); rendered as a
	// note so "install a forwarder" guidance never reads as blind.
	ForwarderRejected string
	// Elevated: root (euid 0) / an elevated shell.
	Elevated bool
}

type Mode string

type Profile struct {
	Mode Mode
	// OS is the render target: a GOOS - linux | windows | darwin.
	OS string
	// DohTemplate is the DoH URL - the public keyless endpoint or the per-tenant
	// keyed one (the token in the path is a resolve-only device credential).
	DohTemplate string
	// ResolverIPs are the dedicated per-tenant :53 resolver /128s (usually one).
	ResolverIPs []string
	// MatchDomains says which names route through Whisper; ["."] (the default
	// when empty) means everything.
	MatchDomains []string
	// SearchDomains are real suffix SEARCH domains: the list the OS APPENDS to a
	// bare hostname, so `ping db-01` reaches db-01.<suffix>. It is a different
	// thing from MatchDomains, which only says which names ROUTE to Whisper -
	// systemd-resolved's "~example.com" is routing-only and never completes a
	// bare name, which is why the search-domain support had to add this rather than reuse the
	// field that looked like it. Empty means the OS keeps whatever
	// search list it already had; we only ever ADD ours.
	SearchDomains []string
	// AppleProfileURL, when set, is the CMS-SIGNED .mobileconfig URL for this
	// profile's token (keyed darwin renders download it instead of generating an
	// unsigned local plist).
	AppleProfileURL string
}

type Rendered struct {
	OS         string `json:"os"`
	Mode       Mode   `json:"mode"`
	DoHURL     string `json:"doh_url,omitempty"`
	ResolverIP string `json:"resolver_ip,omitempty"`
	// Summary is the one-line human description of what apply will do.
	Summary string `json:"summary"`
	Apply   []Step `json:"apply"`
	Revert  []Step `json:"revert"`
	// Notes carry the plain-spoken caveats (plaintext :53, the macOS approval
	// step, a missing forwarder's install line) - stated, never hidden.
	Notes []string `json:"notes,omitempty"`
}

type Step struct {
	// File writes File.Path with File.Content (creating parent dirs).
	File *FileSpec `json:"file,omitempty"`
	// Cmd is an argv executed directly (no shell) - the precise form.
	Cmd []string `json:"cmd,omitempty"`
	// Shell is a shell-language line (PowerShell on windows, sh on unix) for
	// actions that are inherently shell-shaped; displayed and applied verbatim.
	Shell string `json:"shell,omitempty"`
	// Remove deletes a file (missing is fine - idempotent).
	Remove string `json:"remove,omitempty"`
	// WaitFor blocks (bounded) until host:port answers a TCP connect - the
	// server template's "never leave DNS half-configured" gate.
	WaitFor string `json:"wait_for,omitempty"`
	// IfPresent runs the step only when this path exists.
	IfPresent string `json:"if_present,omitempty"`
	// IfAbsent runs the step only when this path does NOT exist.
	IfAbsent string `json:"if_absent,omitempty"`
}