v1alpha1

type ArgDefinition struct {
	// Type specifies the expected data type for this argument.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Enum=string;integer;boolean;number;object;array
	Type string `json:"type" yaml:"type"`

	// Required indicates whether this argument must be provided.
	// +kubebuilder:default=false
	Required bool `json:"required,omitempty" yaml:"required,omitempty"`

	// Default provides a default value if the argument is not specified.
	Default *runtime.RawExtension `json:"default,omitempty" yaml:"default,omitempty"`

	// Description explains the purpose and usage of this argument.
	// +kubebuilder:validation:MaxLength=500
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
}

type ClientCredentialsSecretRef struct {
	// Name is the name of the Kubernetes Secret.
	// Required.
	Name string `json:"name" yaml:"name"`

	// Namespace is the Kubernetes namespace where the secret is located.
	// If not specified, defaults to the MCPServer's namespace.
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`

	// ClientIDKey is the key in the secret data that contains the client ID.
	// Defaults to "client-id" if not specified.
	// +kubebuilder:default="client-id"
	ClientIDKey string `json:"clientIdKey,omitempty" yaml:"clientIdKey,omitempty"`

	// ClientSecretKey is the key in the secret data that contains the client secret.
	// Defaults to "client-secret" if not specified.
	// +kubebuilder:default="client-secret"
	ClientSecretKey string `json:"clientSecretKey,omitempty" yaml:"clientSecretKey,omitempty"`
}

type HealthCheckConfig struct {
	// Enabled controls whether health checking is active.
	// +kubebuilder:default=false
	Enabled bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`

	// Interval specifies how often to perform health checks.
	// +kubebuilder:validation:Pattern="^[0-9]+(ns|us|ms|s|m|h)$"
	// +kubebuilder:default="30s"
	Interval string `json:"interval,omitempty" yaml:"interval,omitempty"`

	// FailureThreshold sets the number of failures before marking unhealthy.
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:default=3
	FailureThreshold int `json:"failureThreshold,omitempty" yaml:"failureThreshold,omitempty"`

	// SuccessThreshold sets the number of successes to mark healthy.
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:default=1
	SuccessThreshold int `json:"successThreshold,omitempty" yaml:"successThreshold,omitempty"`
}

type HealthCheckExpectation struct {
	// Success indicates whether the tool call should succeed.
	Success *bool `json:"success,omitempty" yaml:"success,omitempty"`

	// JSONPath defines JSON path conditions to check in the result.
	JSONPath map[string]*runtime.RawExtension `json:"jsonPath,omitempty" yaml:"jsonPath,omitempty"`
}

type HealthCheckToolCall struct {
	// Tool specifies the name of the tool to execute.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Tool string `json:"tool" yaml:"tool"`

	// Args provides arguments for the tool execution (supports templating).
	Args map[string]*runtime.RawExtension `json:"args,omitempty" yaml:"args,omitempty"`

	// Expect defines positive health check expectations.
	Expect *HealthCheckExpectation `json:"expect,omitempty" yaml:"expect,omitempty"`

	// ExpectNot defines negative health check expectations.
	ExpectNot *HealthCheckExpectation `json:"expectNot,omitempty" yaml:"expectNot,omitempty"`
}

type LifecycleTools struct {
	// Start tool configuration for starting service instances.
	// +kubebuilder:validation:Required
	Start ToolCall `json:"start" yaml:"start"`

	// Stop tool configuration for stopping service instances.
	// +kubebuilder:validation:Required
	Stop ToolCall `json:"stop" yaml:"stop"`

	// Restart tool configuration for restarting service instances.
	Restart *ToolCall `json:"restart,omitempty" yaml:"restart,omitempty"`

	// HealthCheck tool configuration for health checking.
	HealthCheck *HealthCheckToolCall `json:"healthCheck,omitempty" yaml:"healthCheck,omitempty"`

	// Status tool configuration for querying service status.
	Status *ToolCall `json:"status,omitempty" yaml:"status,omitempty"`
}

type MCPServer struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   MCPServerSpec   `json:"spec,omitempty"`
	Status MCPServerStatus `json:"status,omitempty"`
}

type MCPServerAuth struct {
	// Type specifies the authentication type.
	// Supported values:
	//   - "oauth": OAuth 2.0/OIDC authentication
	//   - "teleport": Teleport Application Access with Machine ID certificates
	//   - "none": No authentication
	// +kubebuilder:validation:Enum=oauth;teleport;none
	// +kubebuilder:default=none
	Type string `json:"type,omitempty" yaml:"type,omitempty"`

	// ForwardToken enables ID token forwarding for SSO.
	// When true, muster forwards the user's ID token to this server instead of
	// triggering a separate OAuth flow. The downstream server must be configured
	// to trust muster's client ID in its TrustedAudiences.
	// +kubebuilder:default=false
	ForwardToken bool `json:"forwardToken,omitempty" yaml:"forwardToken,omitempty"`

	// RequiredAudiences specifies additional audience(s) that the forwarded ID token
	// should contain. When ForwardToken is true, muster will request these audiences
	// from the upstream IdP (e.g., Dex) using cross-client scopes.
	//
	// This is used when the downstream server requires tokens with specific audiences,
	// for example when forwarding tokens to Kubernetes for OIDC authentication:
	//   requiredAudiences:
	//     - "dex-k8s-authenticator"
	//
	// At user authentication, muster collects all requiredAudiences from MCPServers
	// with forwardToken: true and requests them all from the IdP.
	RequiredAudiences []string `json:"requiredAudiences,omitempty" yaml:"requiredAudiences,omitempty"`

	// TokenExchange enables SSO via RFC 8693 Token Exchange for cross-cluster SSO.
	// When configured, muster exchanges its local token for a token valid on the
	// remote cluster's Identity Provider (e.g., Dex).
	//
	// Use TokenExchange when:
	//   - The remote cluster has its own Dex instance
	//   - The remote Dex is configured with an OIDC connector for muster's Dex
	//   - You need a token issued by the remote cluster's IdP (not just forwarded)
	//
	// Token exchange takes precedence over ForwardToken if both are configured.
	TokenExchange *TokenExchangeConfig `json:"tokenExchange,omitempty" yaml:"tokenExchange,omitempty"`

	// Teleport configures Teleport authentication for accessing private installations.
	// This is only used when Type is "teleport".
	//
	// When configured, muster uses Teleport Machine ID certificates to establish
	// mutual TLS connections to MCP servers accessible via Teleport Application Access.
	Teleport *TeleportAuthConfig `json:"teleport,omitempty" yaml:"teleport,omitempty"`
}

type MCPServerList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []MCPServer `json:"items"`
}

type MCPServerSpec struct {
	// Type specifies how this MCP server should be executed.
	// Supported values: "stdio" for local processes, "streamable-http" for HTTP-based servers, "sse" for Server-Sent Events
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Enum=stdio;streamable-http;sse
	Type string `json:"type" yaml:"type"`

	// ToolPrefix is an optional prefix that will be prepended to all tool names
	// provided by this MCP server. This helps avoid naming conflicts when multiple
	// servers provide tools with similar names.
	// +kubebuilder:validation:Pattern="^[a-zA-Z][a-zA-Z0-9_-]*$"
	ToolPrefix string `json:"toolPrefix,omitempty" yaml:"toolPrefix,omitempty"`

	// Description provides a human-readable description of this MCP server's purpose.
	// +kubebuilder:validation:MaxLength=500
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// AutoStart determines whether this MCP server should be automatically started
	// when the muster system initializes or when dependencies become available.
	// +kubebuilder:default=false
	AutoStart bool `json:"autoStart,omitempty" yaml:"autoStart,omitempty"`

	// Command specifies the executable path for stdio type servers.
	// This field is required when Type is "stdio".
	Command string `json:"command,omitempty" yaml:"command,omitempty"`

	// Args specifies the command line arguments for stdio type servers.
	// This field is only available when Type is "stdio".
	Args []string `json:"args,omitempty" yaml:"args,omitempty"`

	// URL is the endpoint where the remote MCP server can be reached
	// This field is required when Type is "streamable-http" or "sse".
	// Examples: http://mcp-server:8080/mcp, https://api.example.com/mcp
	// +kubebuilder:validation:Pattern=`^https?://[^\s/$.?#].[^\s]*$`
	URL string `json:"url,omitempty" yaml:"url,omitempty"`

	// Env contains environment variables to set for the MCP server.
	// For stdio servers, these are passed to the process when it is started.
	// For remote servers, these can be used for authentication or configuration.
	Env map[string]string `json:"env,omitempty" yaml:"env,omitempty"`

	// Headers contains HTTP headers to send with requests to remote MCP servers.
	// This field is only relevant when Type is "streamable-http" or "sse".
	Headers map[string]string `json:"headers,omitempty" yaml:"headers,omitempty"`

	// Auth configures authentication behavior for this MCP server.
	// This is only relevant for remote servers (streamable-http or sse).
	Auth *MCPServerAuth `json:"auth,omitempty" yaml:"auth,omitempty"`

	// Timeout specifies the connection timeout for remote operations (in seconds)
	// +kubebuilder:default=30
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=300
	Timeout int `json:"timeout,omitempty" yaml:"timeout,omitempty"`
}

type MCPServerStateValue string

type MCPServerStatus struct {
	// State represents the high-level infrastructure state of the MCP server.
	// This is independent of user session state (authentication, connection status).
	//
	// For stdio servers: Running, Starting, Stopped, Failed
	// For remote servers: Connected, Auth Required, Connecting, Disconnected, Failed
	// +kubebuilder:validation:Enum=Running;Starting;Stopped;Connected;Auth Required;Connecting;Disconnected;Failed
	State MCPServerStateValue `json:"state,omitempty" yaml:"state,omitempty"`

	// LastError contains any error message from the most recent server operation.
	// Note: Per-user authentication errors are tracked in the Session Registry,
	// not here. This field only contains infrastructure-level errors.
	LastError string `json:"lastError,omitempty" yaml:"lastError,omitempty"`

	// LastConnected indicates when the server was last successfully connected
	LastConnected *metav1.Time `json:"lastConnected,omitempty" yaml:"lastConnected,omitempty"`

	// RestartCount tracks how many times this server has been restarted (stdio only)
	RestartCount int `json:"restartCount,omitempty" yaml:"restartCount,omitempty"`

	// ConsecutiveFailures tracks the number of consecutive connection failures.
	// This is used for exponential backoff and to identify unreachable servers.
	// Reset to 0 when a connection succeeds.
	ConsecutiveFailures int `json:"consecutiveFailures,omitempty" yaml:"consecutiveFailures,omitempty"`

	// LastAttempt indicates when the last connection attempt was made.
	// Used with ConsecutiveFailures to implement exponential backoff.
	LastAttempt *metav1.Time `json:"lastAttempt,omitempty" yaml:"lastAttempt,omitempty"`

	// NextRetryAfter indicates the earliest time when the next retry should be attempted.
	// This is calculated based on exponential backoff from ConsecutiveFailures.
	NextRetryAfter *metav1.Time `json:"nextRetryAfter,omitempty" yaml:"nextRetryAfter,omitempty"`

	// Conditions represent the latest available observations of the MCPServer's current state.
	// Standard condition types:
	//   - Ready: True if infrastructure is reachable (process running or TCP connectable)
	Conditions []metav1.Condition `json:"conditions,omitempty" yaml:"conditions,omitempty"`
}

type ServiceClass struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   ServiceClassSpec   `json:"spec,omitempty"`
	Status ServiceClassStatus `json:"status,omitempty"`
}

type ServiceClassList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []ServiceClass `json:"items"`
}

type ServiceClassSpec struct {
	// Description provides a human-readable description of this ServiceClass.
	// +kubebuilder:validation:MaxLength=1000
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Args defines the argument schema for service instantiation.
	Args map[string]ArgDefinition `json:"args,omitempty" yaml:"args,omitempty"`

	// ServiceConfig defines the core service configuration template.
	// +kubebuilder:validation:Required
	ServiceConfig ServiceConfig `json:"serviceConfig" yaml:"serviceConfig"`
}

type ServiceClassStatus struct {
	// Valid indicates whether the ServiceClass spec passes structural validation.
	Valid bool `json:"valid,omitempty" yaml:"valid,omitempty"`

	// ValidationErrors contains any spec validation error messages.
	ValidationErrors []string `json:"validationErrors,omitempty" yaml:"validationErrors,omitempty"`

	// ReferencedTools lists all tools mentioned in the ServiceClass lifecycle definitions.
	// This is informational only; actual availability depends on the user's session.
	// See ADR 007 for details on session-scoped tool visibility.
	ReferencedTools []string `json:"referencedTools,omitempty" yaml:"referencedTools,omitempty"`

	// Conditions represent the latest available observations.
	Conditions []metav1.Condition `json:"conditions,omitempty" yaml:"conditions,omitempty"`
}

type ServiceConfig struct {
	// DefaultName provides a template for generating service instance names.
	DefaultName string `json:"defaultName,omitempty" yaml:"defaultName,omitempty"`

	// Dependencies lists other ServiceClasses that must be available.
	Dependencies []string `json:"dependencies,omitempty" yaml:"dependencies,omitempty"`

	// LifecycleTools defines the tools for service lifecycle management.
	// +kubebuilder:validation:Required
	LifecycleTools LifecycleTools `json:"lifecycleTools" yaml:"lifecycleTools"`

	// HealthCheck configures health monitoring for service instances.
	HealthCheck *HealthCheckConfig `json:"healthCheck,omitempty" yaml:"healthCheck,omitempty"`

	// Timeout configures timeouts for various operations.
	Timeout *TimeoutConfig `json:"timeout,omitempty" yaml:"timeout,omitempty"`

	// Outputs defines template-based outputs for service instances.
	Outputs map[string]string `json:"outputs,omitempty" yaml:"outputs,omitempty"`
}

type TeleportAuthConfig struct {
	// IdentitySecretName is the name of the Kubernetes Secret containing
	// tbot identity files. The secret should contain: tlscert, key, teleport-application-ca.pem
	// (matching tbot's application output type).
	// Required when running in Kubernetes mode.
	// Example: tbot-identity-output
	IdentitySecretName string `json:"identitySecretName,omitempty" yaml:"identitySecretName,omitempty"`

	// IdentitySecretNamespace is the Kubernetes namespace where the identity
	// secret is located. Defaults to the MCPServer's namespace if not specified.
	IdentitySecretNamespace string `json:"identitySecretNamespace,omitempty" yaml:"identitySecretNamespace,omitempty"`

	// IdentityDir is the directory containing Teleport identity files.
	// Used in filesystem mode when certificates are mounted directly.
	// Example: /var/run/tbot/identity
	IdentityDir string `json:"identityDir,omitempty" yaml:"identityDir,omitempty"`

	// AppName is the Teleport application name for routing.
	// This is used to identify which Teleport-protected application to connect to.
	// Example: mcp-kubernetes
	AppName string `json:"appName,omitempty" yaml:"appName,omitempty"`
}

type TimeoutConfig struct {
	// Create timeout for service creation operations.
	// +kubebuilder:validation:Pattern="^[0-9]+(ns|us|ms|s|m|h)$"
	Create string `json:"create,omitempty" yaml:"create,omitempty"`

	// Delete timeout for service deletion operations.
	// +kubebuilder:validation:Pattern="^[0-9]+(ns|us|ms|s|m|h)$"
	Delete string `json:"delete,omitempty" yaml:"delete,omitempty"`

	// HealthCheck timeout for individual health check operations.
	// +kubebuilder:validation:Pattern="^[0-9]+(ns|us|ms|s|m|h)$"
	HealthCheck string `json:"healthCheck,omitempty" yaml:"healthCheck,omitempty"`
}

type TokenExchangeConfig struct {
	// Enabled determines whether token exchange should be attempted.
	// +kubebuilder:default=false
	Enabled bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`

	// DexTokenEndpoint is the URL used to connect to the remote cluster's Dex token endpoint.
	// This may differ from the issuer URL when access goes through a proxy (e.g., Teleport).
	// Required when Enabled is true.
	// Example: https://dex.cluster-b.example.com/token (direct)
	// Example: https://dex-cluster.proxy.example.com/token (via proxy)
	// +kubebuilder:validation:Pattern=`^https://[^\s/$.?#].[^\s]*$`
	DexTokenEndpoint string `json:"dexTokenEndpoint,omitempty" yaml:"dexTokenEndpoint,omitempty"`

	// ExpectedIssuer is the expected issuer URL in the exchanged token's "iss" claim.
	// This should match the remote Dex's configured issuer URL.
	// When access goes through a proxy, this differs from DexTokenEndpoint.
	// If not specified, the issuer is derived from DexTokenEndpoint (backward compatible).
	// Example: https://dex.cluster-b.example.com
	// +kubebuilder:validation:Pattern=`^https://[^\s/$.?#].[^\s]*$`
	ExpectedIssuer string `json:"expectedIssuer,omitempty" yaml:"expectedIssuer,omitempty"`

	// ConnectorID is the ID of the OIDC connector on the remote Dex that
	// trusts the local cluster's Dex.
	// Required when Enabled is true.
	// Example: "cluster-a-dex"
	// +kubebuilder:validation:Pattern="^[a-zA-Z][a-zA-Z0-9_-]*$"
	ConnectorID string `json:"connectorId,omitempty" yaml:"connectorId,omitempty"`

	// Scopes are the scopes to request for the exchanged token.
	// +kubebuilder:default="openid profile email groups"
	Scopes string `json:"scopes,omitempty" yaml:"scopes,omitempty"`

	// ClientCredentialsSecretRef references a Kubernetes Secret containing
	// client credentials for authenticating with the remote Dex's token endpoint.
	// This is required when the remote Dex requires client authentication for
	// token exchange (RFC 8693).
	//
	// The secret should contain:
	//   - client-id: The OAuth client ID registered on the remote Dex
	//   - client-secret: The OAuth client secret for authentication
	//
	// Example secret:
	//
	//	apiVersion: v1
	//	kind: Secret
	//	metadata:
	//	  name: grizzly-token-exchange-credentials
	//	  namespace: muster
	//	type: Opaque
	//	stringData:
	//	  client-id: muster-token-exchange
	//	  client-secret: <secret-value>
	ClientCredentialsSecretRef *ClientCredentialsSecretRef `json:"clientCredentialsSecretRef,omitempty" yaml:"clientCredentialsSecretRef,omitempty"`
}

type ToolCall struct {
	// Tool specifies the name of the tool to execute.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Tool string `json:"tool" yaml:"tool"`

	// Args provides arguments for the tool execution (supports templating).
	Args map[string]*runtime.RawExtension `json:"args,omitempty" yaml:"args,omitempty"`

	// Outputs maps tool result paths to variable names for later use.
	Outputs map[string]string `json:"outputs,omitempty" yaml:"outputs,omitempty"`
}

type Workflow struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   WorkflowSpec   `json:"spec,omitempty"`
	Status WorkflowStatus `json:"status,omitempty"`
}

type WorkflowCondition struct {
	// Tool specifies the name of the tool to execute for condition evaluation.
	// Optional when FromStep is used.
	Tool string `json:"tool,omitempty" yaml:"tool,omitempty"`

	// Args provides the arguments to pass to the condition tool.
	Args map[string]*runtime.RawExtension `json:"args,omitempty" yaml:"args,omitempty"`

	// FromStep specifies the step ID to reference for condition evaluation.
	FromStep string `json:"fromStep,omitempty" yaml:"fromStep,omitempty"`

	// Expect defines positive health check expectations.
	Expect *WorkflowConditionExpectation `json:"expect,omitempty" yaml:"expect,omitempty"`

	// ExpectNot defines negative health check expectations.
	ExpectNot *WorkflowConditionExpectation `json:"expectNot,omitempty" yaml:"expectNot,omitempty"`
}

type WorkflowConditionExpectation struct {
	// Success indicates whether the tool call should succeed.
	Success *bool `json:"success,omitempty" yaml:"success,omitempty"`

	// JsonPath defines JSON path conditions to check in the result.
	JsonPath map[string]*runtime.RawExtension `json:"jsonPath,omitempty" yaml:"jsonPath,omitempty"`
}

type WorkflowList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []Workflow `json:"items"`
}

type WorkflowSpec struct {
	// Description provides a human-readable description of the workflow's purpose.
	// +kubebuilder:validation:MaxLength=1000
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Args defines the argument schema for workflow execution validation.
	Args map[string]ArgDefinition `json:"args,omitempty" yaml:"args,omitempty"`

	// Steps defines the sequence of workflow steps defining the execution flow.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinItems=1
	Steps []WorkflowStep `json:"steps" yaml:"steps"`
}

type WorkflowStatus struct {
	// Valid indicates whether the Workflow spec passes structural validation.
	Valid bool `json:"valid,omitempty" yaml:"valid,omitempty"`

	// ValidationErrors contains any spec validation error messages.
	ValidationErrors []string `json:"validationErrors,omitempty" yaml:"validationErrors,omitempty"`

	// ReferencedTools lists all tools mentioned in the Workflow steps.
	// This is informational only; actual availability depends on the user's session.
	// See ADR 007 for details on session-scoped tool visibility.
	ReferencedTools []string `json:"referencedTools,omitempty" yaml:"referencedTools,omitempty"`

	// StepCount is the number of steps in the workflow.
	StepCount int `json:"stepCount,omitempty" yaml:"stepCount,omitempty"`

	// Conditions represent the latest available observations of the workflow's state.
	Conditions []metav1.Condition `json:"conditions,omitempty" yaml:"conditions,omitempty"`
}

type WorkflowStep struct {
	// ID is the unique identifier for this step within the workflow.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Pattern="^[a-zA-Z0-9_-]+$"
	// +kubebuilder:validation:MaxLength=63
	ID string `json:"id" yaml:"id"`

	// Tool specifies the name of the tool to execute for this step.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Tool string `json:"tool" yaml:"tool"`

	// Args provides arguments for the tool execution (supports templating).
	Args map[string]*runtime.RawExtension `json:"args,omitempty" yaml:"args,omitempty"`

	// Condition defines an optional condition that determines whether this step should execute.
	Condition *WorkflowCondition `json:"condition,omitempty" yaml:"condition,omitempty"`

	// Store indicates whether to store the step result for use in later steps.
	// +kubebuilder:default=false
	Store bool `json:"store,omitempty" yaml:"store,omitempty"`

	// AllowFailure defines if in case of an error the next step is executed or not.
	// +kubebuilder:default=false
	AllowFailure bool `json:"allowFailure,omitempty" yaml:"allowFailure,omitempty"`

	// Outputs defines how step results should be stored and made available to subsequent steps.
	Outputs map[string]*runtime.RawExtension `json:"outputs,omitempty" yaml:"outputs,omitempty"`

	// Description provides human-readable documentation for this step's purpose.
	// +kubebuilder:validation:MaxLength=500
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
}