platform

type PURL struct {
	Type       string            // package ecosystem ("brew", "deb", "winget", etc.)
	Namespace  string            // owner/group prefix (winget publisher, npm scope, Maven group ID)
	Name       string            // the package name
	Version    string            // release version
	Qualifiers map[string]string // key=value pairs (OS, arch, repository, distro)
	Subpath    string            // path within the package
}

type PackageManager interface {

	// Install converges each package to present at the requested version.
	//
	// Parameters:
	//   - `packages`: the packages to install, each carrying its resolved [PURL].
	//   - `kwargs`: opaque native-installer flags passed through verbatim per manager (e.g. `cask`).
	//
	// Returns:
	//   - `receipts`: one [Receipt] per package, in input order; a receipt's `Err` is set from the observed
	//     post-state, not the command's exit code.
	//   - `err`: non-nil when any receipt failed.
	Install(packages []PURL, kwargs map[string]any) (receipts []Receipt, err error)

	// Remove converges each package to absent.
	//
	// Parameters:
	//   - `packages`: the packages to remove, each carrying its resolved [PURL].
	//   - `kwargs`: opaque native-installer flags passed through verbatim per manager.
	//
	// Returns:
	//   - `receipts`: one [Receipt] per package, in input order.
	//   - `err`: non-nil when any receipt failed.
	Remove(packages []PURL, kwargs map[string]any) (receipts []Receipt, err error)

	// Upgrade moves each named package to the latest available version.
	//
	// Parameters:
	//   - `packages`: the packages to upgrade, each carrying its resolved [PURL].
	//   - `kwargs`: opaque native-installer flags passed through verbatim per manager.
	//
	// Returns:
	//   - `receipts`: one [Receipt] per package, in input order.
	//   - `err`: non-nil when any receipt failed.
	Upgrade(packages []PURL, kwargs map[string]any) (receipts []Receipt, err error)

	// Update forces an immediate index refresh, bypassing the automatic staleness gate.
	//
	// On a leaf it refreshes that leaf's index now — a no-op for a manager with no local index (a live-store
	// manager such as snap / flatpak / winget). On the router it fans out to every leaf.
	//
	// Returns:
	//   - `error`: aggregated per-leaf refresh failures; nil when every refresh succeeded or had nothing to do.
	Update() error

	// Installed reports whether the package identified by `p` is installed.
	//
	// Parameters:
	//   - `p`: the package [PURL] to query.
	//
	// Returns:
	//   - `bool`: true when the package is installed.
	Installed(p PURL) bool

	// Version returns the installed version of the package identified by `p`, or empty when it is not installed.
	//
	// Parameters:
	//   - `p`: the package [PURL] to query.
	//
	// Returns:
	//   - `string`: the installed version, or "" when absent.
	Version(p PURL) string

	// Available reports whether the package identified by `p` exists in the manager's index.
	//
	// Parameters:
	//   - `p`: the package [PURL] to query.
	//
	// Returns:
	//   - `bool`: true when the package is available to install.
	Available(p PURL) bool

	// Search returns up to `limit` packages whose name or description matches `query`.
	//
	// Parameters:
	//   - `query`: the search term.
	//   - `limit`: the maximum number of results; `limit` <= 0 means no limit.
	//
	// Returns:
	//   - `[]SearchResult`: the matches, each tagged with the `Manager` that produced it; nil when none match.
	Search(query string, limit int) []SearchResult

	// Present reports whether the manager's executable is on the PATH.
	//
	// Alone among the queries this asks about the manager, not a package: it is a per-machine fact, so it
	// neither varies by [PURL] nor consults an index. A [Spec] declares its managers from the detected OS and
	// distro — "Debian-family, therefore apt" — which is a statement about the platform, not about this
	// machine. Present is what closes that gap, and it does so with a PATH lookup: no subprocess, no network.
	//
	// It answers whether the tool is there, not whether an operation through it will succeed. A present
	// manager can still fail to install — a lock, a bad mirror, no privilege — and that failure belongs to
	// the operation that hits it, reported where it happens.
	//
	// Returns:
	//   - `bool`: true when the executable resolves on the PATH.
	Present() bool
}

type Platform interface {

	// OS returns the operating system family ("linux", "darwin", "windows").
	OS() string

	// Arch returns the architecture ("amd64", "arm64", "arm/v7", etc.) per Docker's vocabulary.
	Arch() string

	// Distro returns the distribution identifier ("ubuntu", "fedora", "macos", "windows", etc.).
	Distro() string

	// Version returns the OS or distro version string ("22.04", "14.5", "11", etc.). Empty when unknown.
	Version() string

	// Hostname returns the host's network hostname. Empty when unavailable.
	Hostname() string

	// DefaultConcurrency returns a reasonable concurrency level for parallel operations — typically 4 × NumCPU.
	DefaultConcurrency() int

	// DefaultPurlType returns the purl type of the platform's default native manager (e.g. "deb" on Debian).
	//
	// The veneer uses it to normalize a bare package name into a typed purl.
	DefaultPurlType() string

	// ResolvePurlType maps a caller-supplied manager prefix — a manager name or a purl type — to the canonical
	// purl type, reporting whether the prefix names a known manager on this platform.
	ResolvePurlType(prefix string) (string, bool)

	// PackageManager returns the platform's Composite router over its leaf drivers.
	PackageManager() PackageManager

	// ServiceManager returns the service manager for this platform (systemd, launchd, Service Control Manager).
	ServiceManager() ServiceManager
}

type Receipt struct {

	// Purl is the package the operation acted on; its `Type` identifies the leaf that handled it.
	Purl PURL

	// PriorVersion is the installed version observed before the operation, or "" when the package was absent.
	PriorVersion string

	// Version is the installed version observed after the operation, or "" when the package is absent (removed).
	Version string

	// Err is non-nil when the observed post-state did not reach what the package's [PURL] requested.
	Err error
}

type Result struct {
	OK     bool   // whether the command exited zero
	Stdout string // captured standard output, trailing newline trimmed
	Stderr string // captured standard error, trailing newline trimmed
	Code   int    // the process exit code (-1 when the command could not be launched)
}

type SearchResult struct {
	Name        string // the package name
	Version     string // the available version, when the manager reports one
	Description string // a short description, when the manager reports one
	Manager     string // the purl type of the leaf that produced the hit (e.g. "deb", "brew")
}

type ServiceManager interface {

	// Exists reports whether a service with the given name is registered.
	//
	// Parameters:
	//   - `name`: the service name.
	//
	// Returns:
	//   - `bool`: true when the service exists.
	Exists(name string) bool

	// IsRunning reports whether the named service is currently running.
	//
	// Parameters:
	//   - `name`: the service name.
	//
	// Returns:
	//   - `bool`: true when the service is running.
	IsRunning(name string) bool

	// IsEnabled reports whether the named service is enabled to start at boot.
	//
	// Parameters:
	//   - `name`: the service name.
	//
	// Returns:
	//   - `bool`: true when the service is enabled.
	IsEnabled(name string) bool

	// Status returns a coarse, human-facing status for the named service.
	//
	// Parameters:
	//   - `name`: the service name.
	//
	// Returns:
	//   - `string`: the status (e.g. "running", "stopped").
	Status(name string) string

	// Start starts the named service.
	//
	// Parameters:
	//   - `name`: the service name.
	//
	// Returns:
	//   - `Result`: the command result.
	Start(name string) Result

	// Stop stops the named service.
	//
	// Parameters:
	//   - `name`: the service name.
	//
	// Returns:
	//   - `Result`: the command result.
	Stop(name string) Result

	// Enable enables the named service to start at boot.
	//
	// Parameters:
	//   - `name`: the service name.
	//
	// Returns:
	//   - `Result`: the command result.
	Enable(name string) Result

	// Disable disables the named service from starting at boot.
	//
	// Parameters:
	//   - `name`: the service name.
	//
	// Returns:
	//   - `Result`: the command result.
	Disable(name string) Result

	// NeedsSudo reports whether mutating service operations require elevation.
	//
	// Returns:
	//   - `bool`: true when elevation is required.
	NeedsSudo() bool
}

type Spec struct {
	// contains filtered or unexported fields
}