software

type Action string

type ActionTimeoutPolicySpec struct {
	Install   TimeoutPolicyResult `yaml:"install"`
	Upgrade   TimeoutPolicyResult `yaml:"upgrade"`
	Start     TimeoutPolicyResult `yaml:"start"`
	Stop      TimeoutPolicyResult `yaml:"stop"`
	Restart   TimeoutPolicyResult `yaml:"restart"`
	Verify    TimeoutPolicyResult `yaml:"verify"`
	Reinstall TimeoutPolicyResult `yaml:"reinstall"`
	Uninstall TimeoutPolicyResult `yaml:"uninstall"`
}

type ActionTimeoutsSpec struct {
	InstallSeconds   int `yaml:"install_seconds"`
	UpgradeSeconds   int `yaml:"upgrade_seconds"`
	StartSeconds     int `yaml:"start_seconds"`
	StopSeconds      int `yaml:"stop_seconds"`
	RestartSeconds   int `yaml:"restart_seconds"`
	VerifySeconds    int `yaml:"verify_seconds"`
	ReinstallSeconds int `yaml:"reinstall_seconds"`
	UninstallSeconds int `yaml:"uninstall_seconds"`
}

type AppOSConnectionStatus string

type ArtifactKind string

type AsyncCommandResponse struct {
	Accepted    bool           `json:"accepted"`
	OperationID string         `json:"operation_id,omitempty"`
	Phase       OperationPhase `json:"phase,omitempty"`
	Message     string         `json:"message,omitempty"`
}

type Capability string

type CapabilityCommander interface {
	// EnsureCapability installs the component backing a capability if not already installed,
	// or re-converges it if it is degraded. Idempotent for already-healthy capabilities.
	EnsureCapability(ctx context.Context, serverID string, capability Capability) (AsyncCommandResponse, error)

	// UpgradeCapability upgrades the installed component to the packaged version.
	UpgradeCapability(ctx context.Context, serverID string, capability Capability) (AsyncCommandResponse, error)

	// VerifyCapability runs a verification pass on the installed component and updates
	// the readiness projection. Safe to call on any installed component.
	VerifyCapability(ctx context.Context, serverID string, capability Capability) (AsyncCommandResponse, error)
}

type CapabilityQuerier interface {
	// ListCapabilities returns readiness status for all managed capabilities on a server.
	ListCapabilities(ctx context.Context, serverID string) ([]CapabilityStatus, error)

	// GetCapabilityStatus returns readiness status for one named capability.
	GetCapabilityStatus(ctx context.Context, serverID string, capability Capability) (CapabilityStatus, error)

	// IsCapabilityReady returns true when the capability is installed, verified, and all
	// readiness dimensions (OS, privilege, network, dependency) are satisfied.
	IsCapabilityReady(ctx context.Context, serverID string, capability Capability) (bool, error)
}

type CapabilityStatus struct {
	Capability      Capability            `json:"capability"`
	ComponentKey    ComponentKey          `json:"component_key"`
	InstalledState  InstalledState        `json:"installed_state"`
	Ready           bool                  `json:"ready"`
	ReadinessResult TargetReadinessResult `json:"readiness"`
}

type CatalogEntry struct {
	ComponentKey           ComponentKey        `yaml:"component_key"`
	TargetType             TargetType          `yaml:"target_type"`
	Label                  string              `yaml:"label"`
	Capability             Capability          `yaml:"capability"`
	ArtifactKind           ArtifactKind        `yaml:"artifact_kind"`
	TemplateRef            string              `yaml:"template_ref"`
	VersionCommand         string              `yaml:"version_command"`
	Binary                 string              `yaml:"binary"`
	ServiceName            string              `yaml:"service_name"`
	LegacyServiceNames     []string            `yaml:"legacy_service_names"`
	PackageName            string              `yaml:"package_name"`
	PackageNames           []string            `yaml:"package_names"`
	PackageRepoProfile     string              `yaml:"package_repo_profile"`
	ScriptPath             string              `yaml:"script_path"`
	ScriptURL              string              `yaml:"script_url"`
	Description            string              `yaml:"description"`
	ReadinessRequirements  []string            `yaml:"readiness_requirements"`
	RequiresAppOSBaseURL   bool                `yaml:"requires_appos_base_url"`
	FavoriteSystemdService bool                `yaml:"favorite_systemd_service"`
	Visibility             []CatalogVisibility `yaml:"visibility"`
	SupportedActions       []Action            `yaml:"supported_actions"`
}

type CatalogVisibility string

type ComponentCatalog struct {
	Components []CatalogEntry `yaml:"components"`
}

type ComponentExecutor interface {
	// Detect runs the detection step and returns the current installed state and version.
	Detect(ctx context.Context, serverID string, tpl ResolvedTemplate) (DetectionResult, error)

	// RunPreflight executes all preflight checks and returns a TargetReadinessResult.
	// A non-ok result does not indicate an executor error; the caller decides whether to proceed.
	RunPreflight(ctx context.Context, serverID string, tpl ResolvedTemplate) (TargetReadinessResult, error)

	// Install executes the install step and returns execution detail from the primary action.
	// Post-action truth must be evaluated separately via Verify or Detect by the caller.
	Install(ctx context.Context, serverID string, tpl ResolvedTemplate) (SoftwareComponentDetail, error)

	// Upgrade executes the upgrade step and returns execution detail from the primary action.
	Upgrade(ctx context.Context, serverID string, tpl ResolvedTemplate) (SoftwareComponentDetail, error)

	// Start starts the managed runtime service and returns execution detail from the control action.
	Start(ctx context.Context, serverID string, tpl ResolvedTemplate) (SoftwareComponentDetail, error)

	// Stop stops the managed runtime service and returns execution detail from the control action.
	Stop(ctx context.Context, serverID string, tpl ResolvedTemplate) (SoftwareComponentDetail, error)

	// Restart restarts the managed runtime service and returns execution detail from the control action.
	Restart(ctx context.Context, serverID string, tpl ResolvedTemplate) (SoftwareComponentDetail, error)

	// Uninstall executes the uninstall step and returns execution detail from the primary action.
	// Idempotent: if the component is already absent, returns the current absent state unchanged.
	Uninstall(ctx context.Context, serverID string, tpl ResolvedTemplate) (SoftwareComponentDetail, error)

	// Verify executes the verify step and returns the current component state.
	Verify(ctx context.Context, serverID string, tpl ResolvedTemplate) (SoftwareComponentDetail, error)

	// Reinstall re-executes the primary reinstall step and returns execution detail.
	// If the component is already healthy, returns the current healthy state unchanged.
	Reinstall(ctx context.Context, serverID string, tpl ResolvedTemplate) (SoftwareComponentDetail, error)
}

type ComponentKey string

type ComponentTemplate struct {
	TemplateKind        TemplateKind            `yaml:"template_kind"`
	Detect              DetectSpec              `yaml:"detect"`
	Preflight           PreflightSpec           `yaml:"preflight"`
	ActionTimeouts      ActionTimeoutsSpec      `yaml:"action_timeouts"`
	ActionTimeoutPolicy ActionTimeoutPolicySpec `yaml:"timeout_policy"`
	Install             InstallSpec             `yaml:"install"`
	Upgrade             UpgradeSpec             `yaml:"upgrade"`
	Uninstall           UninstallSpec           `yaml:"uninstall"`
	Verify              VerifySpec              `yaml:"verify"`
	// Reinstall is optional in YAML. When absent, ResolveTemplate defaults to reinstall strategy.
	Reinstall *ReinstallSpec `yaml:"reinstall"`
}

type DetectSpec struct {
	VersionCommand string   `yaml:"version_command"`
	InstalledHint  []string `yaml:"installed_hint"`
}

type DetectionResult struct {
	InstalledState  InstalledState `json:"installed_state"`
	DetectedVersion string         `json:"detected_version,omitempty"`
	InstallSource   InstallSource  `json:"install_source,omitempty"`
	SourceEvidence  string         `json:"source_evidence,omitempty"`
}

type FailureCode string

type HealthResolutionEvidence struct {
	ComponentKey                 ComponentKey
	InstalledState               InstalledState
	VerificationState            VerificationState
	Verification                 *SoftwareVerificationResult
	LastOperationTerminalStatus  TerminalStatus
	ReportingExpected            bool
	MetricsFreshnessState        string
	MetricsReasonCode            string
	HasMonitorConnectionEvidence bool
}

type InstallSource string

type InstallSpec struct {
	Strategy           string            `yaml:"strategy"`
	PackageName        string            `yaml:"package_name"`
	PackageNames       []string          `yaml:"package_names"`
	PackageRepoProfile string            `yaml:"package_repo_profile"`
	ScriptPath         string            `yaml:"script_path"`
	ScriptURL          string            `yaml:"script_url"`
	Env                map[string]string `yaml:"env"`
	Args               []string          `yaml:"args"`
}

type InstalledState string

type OperationPhase string

type PreflightSpec struct {
	RequireRoot    bool     `yaml:"require_root"`
	RequireNetwork bool     `yaml:"require_network"`
	VerifiedOS     []string `yaml:"verified_os"`
	ServiceManager string   `yaml:"service_manager"`
	PackageManager string   `yaml:"package_manager"`
}

type ReadinessIssueCode string

type ReinstallSpec struct {
	Strategy string `yaml:"strategy"`
}

type ResolvedTemplate struct {
	ComponentKey        ComponentKey
	TemplateRef         string
	TemplateKind        TemplateKind
	Detect              DetectSpec
	Preflight           PreflightSpec
	ActionTimeouts      ActionTimeoutsSpec
	ActionTimeoutPolicy ActionTimeoutPolicySpec
	Install             InstallSpec
	Upgrade             UpgradeSpec
	Uninstall           UninstallSpec
	Verify              VerifySpec
	Reinstall           ReinstallSpec
	SupportedActions    []Action
}

type ServiceStatus string

type SoftwareActionResponse struct {
	ComponentKey      ComponentKey      `json:"component_key"`
	Action            Action            `json:"action"`
	Result            string            `json:"result"`
	InstalledState    InstalledState    `json:"installed_state"`
	DetectedVersion   string            `json:"detected_version,omitempty"`
	PackagedVersion   string            `json:"packaged_version,omitempty"`
	VerificationState VerificationState `json:"verification_state"`
	Message           string            `json:"message,omitempty"`
	Output            string            `json:"output,omitempty"`
}

type SoftwareComponentDetail struct {
	SoftwareComponentSummary
	ServiceName  string                      `json:"service_name,omitempty"`
	BinaryPath   string                      `json:"binary_path,omitempty"`
	ConfigPath   string                      `json:"config_path,omitempty"`
	Preflight    *TargetReadinessResult      `json:"preflight,omitempty"`
	Verification *SoftwareVerificationResult `json:"verification,omitempty"`
}

type SoftwareComponentSummary struct {
	ComponentKey      ComponentKey                `json:"component_key"`
	Label             string                      `json:"label"`
	TemplateKind      TemplateKind                `json:"template_kind"`
	ArtifactKind      ArtifactKind                `json:"artifact_kind,omitempty"`
	InstalledState    InstalledState              `json:"installed_state"`
	DetectedVersion   string                      `json:"detected_version,omitempty"`
	InstallSource     InstallSource               `json:"install_source,omitempty"`
	SourceEvidence    string                      `json:"source_evidence,omitempty"`
	PackagedVersion   string                      `json:"packaged_version,omitempty"`
	VerificationState VerificationState           `json:"verification_state"`
	ServiceStatus     ServiceStatus               `json:"service_status"`
	AppOSConnection   AppOSConnectionStatus       `json:"appos_connection"`
	HealthReasons     []string                    `json:"health_reasons,omitempty"`
	AvailableActions  []Action                    `json:"available_actions,omitempty"`
	LastAction        *SoftwareDeliveryLastAction `json:"last_action,omitempty"`
}

type SoftwareDeliveryLastAction struct {
	Action string `json:"action"`
	Result string `json:"result"`
	At     string `json:"at"`
}

type SoftwareDeliveryOperation struct {
	OperationID    string         `json:"operation_id"`
	ServerID       string         `json:"server_id"`
	Capability     Capability     `json:"capability"`
	ComponentKey   ComponentKey   `json:"component_key"`
	Action         Action         `json:"action"`
	Phase          OperationPhase `json:"phase"`
	TerminalStatus TerminalStatus `json:"terminal_status"`
	FailurePhase   OperationPhase `json:"failure_phase,omitempty"`
	FailureCode    FailureCode    `json:"failure_code,omitempty"`
	FailureReason  string         `json:"failure_reason,omitempty"`
	EventLog       string         `json:"event_log,omitempty"`
	CreatedAt      string         `json:"created_at"`
	UpdatedAt      string         `json:"updated_at"`
}

type SoftwareVerificationResult struct {
	State     VerificationState `json:"state"`
	CheckedAt string            `json:"checked_at"`
	Reason    string            `json:"reason,omitempty"`
	Details   map[string]any    `json:"details,omitempty"`
}

type Subdomain string

type TargetInfo struct {
	// OS is the canonical OS name of the target, e.g. "ubuntu", "debian", "rocky".
	OS string

	// HasRoot indicates whether the executor agent has root (or equivalent) privilege.
	HasRoot bool

	// NetworkOK indicates whether the required network path is currently reachable.
	NetworkOK bool

	// ServiceManager is the detected service supervisor/runtime, e.g. "systemd" or "supervisor".
	ServiceManager string

	// PackageManager is the detected package manager, e.g. "apt".
	PackageManager string
}

type TargetReadinessResult struct {
	OK               bool     `json:"ok"`
	OSSupported      bool     `json:"os_supported"`
	PrivilegeOK      bool     `json:"privilege_ok"`
	NetworkOK        bool     `json:"network_ok"`
	DependencyReady  bool     `json:"dependency_ready"`
	ServiceManagerOK bool     `json:"service_manager_ok"`
	PackageManagerOK bool     `json:"package_manager_ok"`
	Issues           []string `json:"issues,omitempty"`
}

type TargetType string

type TemplateKind string

type TemplateRegistry struct {
	Templates map[string]ComponentTemplate `yaml:"templates"`
}

type TemplateResolver interface {
	// Resolve returns the fully resolved template for a component key.
	// Returns an error if the component key is unknown or its template_ref is not registered.
	Resolve(key ComponentKey) (ResolvedTemplate, error)
}

type TerminalStatus string

type TimeoutPolicyResult string

type UninstallSpec struct {
	Strategy           string            `yaml:"strategy"`
	PackageName        string            `yaml:"package_name"`
	PackageNames       []string          `yaml:"package_names"`
	PackageRepoProfile string            `yaml:"package_repo_profile"`
	ScriptPath         string            `yaml:"script_path"`
	ScriptURL          string            `yaml:"script_url"`
	Env                map[string]string `yaml:"env"`
	Args               []string          `yaml:"args"`
}

type UpgradeSpec struct {
	Strategy           string            `yaml:"strategy"`
	PackageName        string            `yaml:"package_name"`
	PackageNames       []string          `yaml:"package_names"`
	PackageRepoProfile string            `yaml:"package_repo_profile"`
	ScriptPath         string            `yaml:"script_path"`
	ScriptURL          string            `yaml:"script_url"`
	Env                map[string]string `yaml:"env"`
	Args               []string          `yaml:"args"`
}

type VerificationState string

type VerifySpec struct {
	Strategy    string `yaml:"strategy"`
	ServiceName string `yaml:"service_name"`
}