agent

type Agent struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description"`
	Homepage    string `json:"homepage,omitempty"`
	Repository  string `json:"repository,omitempty"`
}

type Filter struct {
	// AgentID limits results to a specific agent (singular convenience).
	AgentID string

	// AgentIDs limits results to specific agents (multiple).
	AgentIDs []string

	// Method limits results to a specific installation method (singular convenience).
	Method InstallMethod

	// Methods limits results to specific installation methods (multiple).
	Methods []InstallMethod

	// HasUpdate filters to only installations with updates available.
	HasUpdate *bool

	// IsGlobal filters to only global or local installations.
	IsGlobal *bool

	// Query performs a text search across agent names and IDs.
	Query string
}

type InstallMethod string

type Installation struct {
	AgentID          string            `json:"agent_id"`
	AgentName        string            `json:"agent_name"`
	Method           InstallMethod     `json:"install_method"`
	InstalledVersion Version           `json:"installed_version"`
	LatestVersion    *Version          `json:"latest_version,omitempty"`
	ExecutablePath   string            `json:"executable_path"`
	InstallPath      string            `json:"install_path,omitempty"`
	IsGlobal         bool              `json:"is_global"`
	DetectedAt       time.Time         `json:"detected_at"`
	LastChecked      time.Time         `json:"last_checked"`
	Metadata         map[string]string `json:"metadata,omitempty"`
}

type ListOptions struct {
	Filter    *Filter
	SortBy    SortField
	SortOrder SortOrder
	Limit     int
	Offset    int
}

type ObservableRegistry interface {
	Registry

	// Subscribe adds an observer to receive events.
	Subscribe(observer RegistryObserver)

	// Unsubscribe removes an observer.
	Unsubscribe(observer RegistryObserver)
}

type Registry interface {
	// List returns all detected agent installations.
	List(ctx context.Context) ([]Installation, error)

	// Get returns a specific installation by unique key.
	Get(ctx context.Context, key string) (*Installation, error)

	// GetByAgent returns all installations of a specific agent.
	GetByAgent(ctx context.Context, agentID string) ([]Installation, error)

	// GetByMethod returns all installations using a specific method.
	GetByMethod(ctx context.Context, method InstallMethod) ([]Installation, error)

	// Register adds or updates an installation.
	Register(ctx context.Context, installation Installation) error

	// Unregister removes an installation.
	Unregister(ctx context.Context, key string) error

	// Refresh re-detects all agents.
	Refresh(ctx context.Context) error

	// Count returns the number of registered installations.
	Count(ctx context.Context) (int, error)

	// CountWithUpdates returns the number of installations with available updates.
	CountWithUpdates(ctx context.Context) (int, error)
}

type RegistryEvent struct {
	Type         RegistryEventType `json:"type"`
	Installation *Installation     `json:"installation,omitempty"`
	Error        error             `json:"error,omitempty"`
}

type RegistryEventType string

type RegistryObserver interface {
	OnRegistryEvent(event RegistryEvent)
}

type RegistryOptions struct {
	// AutoRefresh enables automatic periodic refresh of agent detection.
	AutoRefresh bool

	// RefreshInterval specifies how often to refresh when AutoRefresh is enabled.
	RefreshInterval int // in seconds

	// IncludeHidden includes hidden agents in listings.
	IncludeHidden bool

	// PlatformFilter limits detection to specific platforms.
	PlatformFilter []string
}

type Release struct {
	Version     Version   `json:"version"`
	Title       string    `json:"title"`
	Body        string    `json:"body"`
	Highlights  []string  `json:"highlights,omitempty"`
	PublishedAt time.Time `json:"published_at"`
	URL         string    `json:"url,omitempty"`
}

type SortField string

type SortOrder string

type Status string

type UpdateInfo struct {
	Installation Installation `json:"installation"`
	FromVersion  Version      `json:"from_version"`
	ToVersion    Version      `json:"to_version"`
	Changelog    string       `json:"changelog,omitempty"`
	ReleaseNotes []Release    `json:"release_notes,omitempty"`
	PublishedAt  time.Time    `json:"published_at,omitempty"`
}

type Version struct {
	Major      int    `json:"major"`
	Minor      int    `json:"minor"`
	Patch      int    `json:"patch"`
	Prerelease string `json:"prerelease,omitempty"`
	Build      string `json:"build,omitempty"`
	Raw        string `json:"raw"`
}

type VersionConstraint struct {
	Operator string  `json:"operator"` // =, >, >=, <, <=, ~, ^
	Version  Version `json:"version"`
}

type VersionRange struct {
	From Version `json:"from"`
	To   Version `json:"to"`
}