management

type BulkOperationResult struct {
	Total      int               `json:"total"`      // Total servers processed
	Successful int               `json:"successful"` // Number of successful operations
	Failed     int               `json:"failed"`     // Number of failed operations
	Errors     map[string]string `json:"errors"`     // Map of server name to error message
}

type EventEmitter interface {
	EmitServersChanged(reason string, extra map[string]any)
}

type RuntimeOperations interface {
	EnableServer(serverName string, enabled bool) error
	RestartServer(serverName string) error
	GetAllServers() ([]map[string]interface{}, error)
	BulkEnableServers(serverNames []string, enabled bool) (map[string]error, error)
	GetServerTools(serverName string) ([]map[string]interface{}, error)
	GetToolApproval(serverName, toolName string) (*storage.ToolApprovalRecord, error)
	TriggerOAuthLogin(serverName string) error
	// TriggerOAuthLoginQuick returns browser status immediately (Spec 020 fix)
	TriggerOAuthLoginQuick(serverName string) (*core.OAuthStartResult, error)
	TriggerOAuthLogout(serverName string) error
	RefreshOAuthToken(serverName string) error
}

type SecurityScanEnricher interface {
	GetSecurityScanSummary(ctx context.Context, serverName string) *contracts.SecurityScanSummary
}

type Service interface {

	// ListServers returns all configured servers with their current status and aggregate statistics.
	// This method respects configuration gates but never blocks read operations.
	ListServers(ctx context.Context) ([]*contracts.Server, *contracts.ServerStats, error)

	// GetServerLogs retrieves recent log entries for a specific server.
	// The tail parameter controls how many recent entries to return.
	// Returns empty slice if server doesn't exist or has no logs.
	GetServerLogs(ctx context.Context, name string, tail int) ([]contracts.LogEntry, error)

	// EnableServer enables or disables a specific upstream server.
	// This operation respects disable_management and read_only configuration gates.
	// Emits "servers.changed" event on successful state change.
	EnableServer(ctx context.Context, name string, enabled bool) error

	// RestartServer stops and restarts the connection to a specific upstream server.
	// This operation respects disable_management and read_only configuration gates.
	// Emits "servers.changed" event on successful restart.
	RestartServer(ctx context.Context, name string) error

	// RestartAll restarts all configured servers sequentially.
	// Returns detailed results including success/failure counts and per-server errors.
	// Continues on partial failures, collecting all errors in the result.
	// This operation respects disable_management and read_only configuration gates.
	RestartAll(ctx context.Context) (*BulkOperationResult, error)

	// EnableAll enables all configured servers.
	// Returns detailed results including success/failure counts and per-server errors.
	// This operation respects disable_management and read_only configuration gates.
	EnableAll(ctx context.Context) (*BulkOperationResult, error)

	// DisableAll disables all configured servers.
	// Returns detailed results including success/failure counts and per-server errors.
	// This operation respects disable_management and read_only configuration gates.
	DisableAll(ctx context.Context) (*BulkOperationResult, error)

	// Doctor aggregates health diagnostics from all system components.
	// Returns comprehensive health information including:
	// - Upstream server connection errors
	// - OAuth authentication requirements
	// - Missing secrets referenced in configuration
	// - Docker daemon status (if isolation is enabled)
	// - General runtime warnings
	// Target completion time: <3 seconds for 20 servers.
	Doctor(ctx context.Context) (*contracts.Diagnostics, error)

	// AuthStatus returns detailed OAuth authentication status for a specific server.
	// Returns nil if server doesn't use OAuth or doesn't exist.
	AuthStatus(ctx context.Context, name string) (*contracts.AuthStatus, error)

	// GetServerTools retrieves all available tools for a specific upstream MCP server.
	// Delegates to runtime's GetServerTools() which reads from StateView cache.
	// This is a read-only operation that completes in <10ms (in-memory cache read).
	// Returns empty array if server has no tools.
	// Returns error if server name is empty, server not found, or server not connected.
	GetServerTools(ctx context.Context, name string) ([]map[string]interface{}, error)

	// TriggerOAuthLogin initiates an OAuth 2.x authentication flow for a specific server.
	// Delegates to upstream manager's StartManualOAuth() which launches browser-based flow.
	// This operation respects disable_management and read_only configuration gates.
	// Emits "servers.changed" event on successful OAuth completion.
	// Method returns immediately after starting OAuth flow (actual completion is asynchronous).
	// Returns error if server name is empty, server not found, config gates block operation,
	// or server doesn't support OAuth.
	TriggerOAuthLogin(ctx context.Context, name string) error

	// TriggerOAuthLoginQuick initiates OAuth 2.x authentication flow and returns browser status immediately.
	// Unlike TriggerOAuthLogin which runs fully async, this returns actual browser_opened status.
	// Used by HTTP handler to return accurate OAuthStartResponse (Spec 020 fix).
	TriggerOAuthLoginQuick(ctx context.Context, name string) (*core.OAuthStartResult, error)

	// TriggerOAuthLogout clears OAuth token and disconnects a specific server.
	// This operation respects disable_management and read_only configuration gates.
	// Emits "servers.changed" event on successful logout.
	// Returns error if server name is empty, server not found, config gates block operation,
	// or server doesn't support OAuth.
	TriggerOAuthLogout(ctx context.Context, name string) error

	// LogoutAllOAuth clears OAuth tokens for all OAuth-enabled servers.
	// Returns BulkOperationResult with success/failure counts.
	// This operation respects disable_management and read_only configuration gates.
	LogoutAllOAuth(ctx context.Context) (*BulkOperationResult, error)

	// SetScanSummaryEnricher wires the SecurityScanEnricher used by
	// ListServers to populate Server.SecurityScan. The scanner is constructed
	// later in the boot sequence than the management service, so this is a
	// setter rather than a constructor parameter. Optional — callers without
	// a scanner can skip the call and ListServers will return SecurityScan=nil.
	SetScanSummaryEnricher(e SecurityScanEnricher)
}