provider

type Capability string

type Contact struct {
	Name  string `json:"name,omitempty" yaml:"name,omitempty" doc:"Maintainer name" maxLength:"60" example:"Jane Doe"`
	Email string `json:"email,omitempty" yaml:"email,omitempty" doc:"Maintainer email" format:"email" maxLength:"100"`
}

type Descriptor struct {
	// Name is the unique identifier for this provider. Must be lowercase with hyphens only.
	// Used to reference the provider in configurations and the registry.
	Name string `` /* 145-byte string literal not displayed */

	// DisplayName is the human-readable name shown in UIs and documentation.
	// Optional - defaults to Name if not specified.
	DisplayName string `` /* 129-byte string literal not displayed */

	// APIVersion indicates the provider API contract version (e.g., "v1").
	// Used for compatibility checking and migration support.
	APIVersion string `` /* 126-byte string literal not displayed */

	// Version is the semantic version of this provider implementation.
	// Follows semver conventions for versioning provider releases.
	Version *semver.Version `json:"version" yaml:"version" doc:"Semantic version" required:"true"`

	// Description provides a concise explanation of what the provider does.
	// Displayed in catalogs, help text, and documentation.
	Description string `` /* 144-byte string literal not displayed */

	// Schema defines the structure and validation rules for provider inputs using JSON Schema.
	// Used for input validation, documentation generation, and UI form building.
	Schema *jsonschema.Schema `json:"schema" yaml:"schema" doc:"Input schema (JSON Schema)" required:"true"`

	// OutputSchemas defines the output structure for each supported capability using JSON Schema.
	// Each capability can produce different output shapes. Required for all declared capabilities.
	// Certain capabilities have required minimum fields:
	//   - validation: must include "valid" (boolean) and "errors" (array)
	//   - authentication: must include "authenticated" (boolean) and "token" (string)
	//   - action: must include "success" (boolean)
	//   - state: must include "success" (boolean)
	//   - kubeconfig: must include "success" (boolean)
	//   - from: no required fields
	//   - transform: no required fields
	OutputSchemas map[Capability]*jsonschema.Schema `json:"outputSchemas" yaml:"outputSchemas" doc:"Output schemas per capability (JSON Schema)" required:"true"`

	// SensitiveFields lists property names that contain sensitive data and should be redacted
	// in logs, errors, and snapshot output. Replaces the old per-property IsSecret flag.
	SensitiveFields []string `` /* 126-byte string literal not displayed */

	// Decode converts validated map[string]any inputs into strongly-typed structs for internal use.
	// Called after schema validation but before Execute(). Optional - providers can work with map[string]any directly.
	// When Decode is set, the Executor calls it and passes the result directly to Execute().
	Decode func(map[string]any) (any, error) `json:"-" yaml:"-"`

	// ExtractDependencies extracts resolver dependencies from the provider's inputs.
	// Called during dependency graph building to determine execution order.
	// Optional - if nil, the generic extraction logic is used (which handles common patterns like
	// CEL expressions with _.resolverName and Go templates with {{.resolverName}}).
	// Providers should implement this when they have custom input formats or need special handling
	// (e.g., go-template provider with custom delimiters).
	// The function receives the raw inputs map and returns a slice of resolver names that are referenced.
	ExtractDependencies func(inputs map[string]any) []string `json:"-" yaml:"-"`

	// WhatIf generates a human-readable description of what the provider would do
	// with the given inputs, without executing. Optional — if nil, falls back to
	// a generic message. In solution dry-run, receives the materialized inputs
	// map (map[string]any), not the decoded struct that Execute may receive.
	WhatIf func(ctx context.Context, input any) (string, error) `json:"-" yaml:"-"`

	// Capabilities declares the execution contexts this provider supports.
	// Determines where the provider can be used (from, transform, validation, etc.).
	Capabilities []Capability `json:"capabilities" yaml:"capabilities" doc:"Supported execution contexts" minItems:"1" maxItems:"10" required:"true"`

	// WriteOperations lists operation names that mutate external state.
	// When set, the executor rejects these operations in resolver (CapabilityFrom)
	// context to prevent unsafe side effects during DAG resolution, where retries
	// and parallelism can cause duplicate writes.
	//
	// Semantics:
	//   - nil: provider cannot classify operations (no enforcement occurs).
	//     Use this for providers like exec or http where the command/request
	//     determines read vs write behavior.
	//   - empty ([]string{}): all operations are reads (everything allowed in resolvers).
	//   - populated: listed operations are blocked in resolver context.
	//
	// Superseded by Operations: prefer declaring rich OperationDescriptor entries
	// with IsWrite set. WriteOperations is retained for backward compatibility and
	// may be removed in a future major version. Use EffectiveWriteOperations to
	// read the effective write set regardless of which field is populated.
	WriteOperations []string `json:"writeOperations" yaml:"writeOperations" doc:"Operation names that mutate state" maxItems:"200"`

	// Operations declares rich, per-operation metadata (descriptions, capabilities,
	// schemas, deprecation info) for providers that expose many named operations.
	// It is additive and optional: providers may continue to use WriteOperations
	// alone. When both are set they must be consistent (see ValidateDescriptor).
	// Operation-level Capabilities must be a subset of the provider's Capabilities.
	// Per-operation schemas are documentation/discovery metadata only; the
	// provider-level Schema remains the source of truth for runtime validation.
	Operations []OperationDescriptor `json:"operations,omitempty" yaml:"operations,omitempty" doc:"Per-operation metadata" maxItems:"500"`

	// Category classifies the provider for organization in catalogs and documentation.
	// Examples: "network", "storage", "security", "utility".
	Category string `json:"category,omitempty" yaml:"category,omitempty" doc:"Classification category" maxLength:"50" example:"network"`

	// Tags are searchable keywords for discovery and filtering.
	// Used in catalog searches and provider listings.
	Tags []string `json:"tags,omitempty" yaml:"tags,omitempty" doc:"Searchable keywords" maxItems:"20"`

	// Icon is a URL to an image representing the provider.
	// Displayed in UIs and documentation alongside the provider name.
	Icon string `` /* 126-byte string literal not displayed */

	// Links provides related resources such as documentation, source code, or tutorials.
	Links []Link `json:"links,omitempty" yaml:"links,omitempty" doc:"Related links" maxItems:"10"`

	// Examples contains sample configurations demonstrating provider usage.
	// Shown in documentation and can be used for testing.
	Examples []Example `json:"examples,omitempty" yaml:"examples,omitempty" doc:"Usage examples" maxItems:"10"`

	// IsDeprecated indicates the provider should no longer be used.
	// Deprecated providers may be removed in future versions.
	IsDeprecated bool `json:"deprecated,omitempty" yaml:"deprecated,omitempty" doc:"Deprecation status"`

	// Beta indicates the provider is experimental and may have breaking changes.
	// Beta providers are not recommended for production use.
	Beta bool `json:"beta,omitempty" yaml:"beta,omitempty" doc:"Beta status"`

	// Maintainers lists the people or teams responsible for this provider.
	// Used for contact and support information.
	Maintainers []Contact `json:"maintainers,omitempty" yaml:"maintainers,omitempty" doc:"Maintainer contacts" maxItems:"10"`
}

type Example struct {
	Name        string `json:"name,omitempty" yaml:"name,omitempty" doc:"Example name" maxLength:"50" example:"Basic usage"`
	Description string `` /* 132-byte string literal not displayed */
	YAML        string `json:"yaml" yaml:"yaml" doc:"YAML example" minLength:"10" maxLength:"2000" required:"true"`
}

type IOStreams struct {
	// Out is the writer for standard output (typically os.Stdout).
	Out io.Writer `json:"-" yaml:"-" doc:"Writer for standard output"`
	// ErrOut is the writer for standard error output (typically os.Stderr).
	ErrOut io.Writer `json:"-" yaml:"-" doc:"Writer for standard error output"`
}

type IterationContext struct {
	// Item is the current element being iterated over.
	Item any `json:"item" yaml:"item" doc:"Current element in the iteration."`
	// Index is the current index in the iteration.
	Index int `json:"index" yaml:"index" doc:"Current zero-based index in the iteration." maximum:"10000" example:"0"`
	// ItemAlias is the custom variable name for the current item (empty if using default __item).
	ItemAlias string `` /* 131-byte string literal not displayed */
	// IndexAlias is the custom variable name for the current index (empty if using default __index).
	IndexAlias string `` /* 129-byte string literal not displayed */
}

type Link struct {
	Name string `json:"name,omitempty" yaml:"name,omitempty" doc:"Link name" maxLength:"30" example:"Documentation"`
	URL  string `json:"url,omitempty" yaml:"url,omitempty" doc:"Link URL" format:"uri" maxLength:"500"`
}

type OperationDescriptor struct {
	// Name is the unique operation identifier (e.g., "create_issue").
	Name string `json:"name" yaml:"name" doc:"Operation identifier" minLength:"1" maxLength:"100" required:"true"`

	// DisplayName is the human-readable operation name shown in UIs.
	DisplayName string `json:"displayName,omitempty" yaml:"displayName,omitempty" doc:"Human-readable operation name" maxLength:"100"`

	// Description explains what the operation does.
	Description string `json:"description,omitempty" yaml:"description,omitempty" doc:"Operation description" maxLength:"500"`

	// Capabilities lists the capabilities this operation supports.
	// Must be a subset of the provider's declared Capabilities.
	Capabilities []Capability `` /* 136-byte string literal not displayed */

	// IsWrite indicates the operation mutates external state.
	// Used to derive EffectiveWriteOperations when WriteOperations is unset.
	IsWrite bool `json:"isWrite,omitempty" yaml:"isWrite,omitempty" doc:"Whether the operation mutates external state"`

	// InputSchema documents operation-specific input fields (JSON Schema).
	// Documentation only; not used for runtime validation.
	InputSchema *jsonschema.Schema `json:"inputSchema,omitempty" yaml:"inputSchema,omitempty" doc:"Operation-specific input fields (JSON Schema)"`

	// OutputSchema documents the operation's output structure (JSON Schema).
	OutputSchema *jsonschema.Schema `json:"outputSchema,omitempty" yaml:"outputSchema,omitempty" doc:"Operation output (JSON Schema)"`

	// Examples contains sample usages for this operation.
	Examples []Example `json:"examples,omitempty" yaml:"examples,omitempty" doc:"Usage examples" maxItems:"10"`

	// Tags are searchable keywords for discovery and filtering.
	Tags []string `json:"tags,omitempty" yaml:"tags,omitempty" doc:"Searchable keywords" maxItems:"20"`

	// IsDeprecated indicates the operation should no longer be used.
	IsDeprecated bool `json:"deprecated,omitempty" yaml:"deprecated,omitempty" doc:"Deprecation status"`

	// DeprecationMessage provides guidance when the operation is deprecated.
	DeprecationMessage string `json:"deprecationMessage,omitempty" yaml:"deprecationMessage,omitempty" doc:"Deprecation guidance" maxLength:"300"`
}

type Output struct {
	Data     any            `json:"data" yaml:"data" doc:"Provider output data" required:"true"`
	Warnings []string       `json:"warnings,omitempty" yaml:"warnings,omitempty" doc:"Non-fatal warning messages" maxItems:"50"`
	Metadata map[string]any `json:"metadata,omitempty" yaml:"metadata,omitempty" doc:"Execution metadata"`
	// Streamed indicates that the provider already wrote its primary output
	// (e.g., stdout/stderr) directly to the terminal via IOStreams from context.
	// When true, the CLI output layer should not re-print the streamed content.
	Streamed bool `json:"streamed,omitempty" yaml:"streamed,omitempty" doc:"Whether output was already streamed to terminal"`
}

type Provider interface {
	// Descriptor returns the provider's metadata, schema, and capabilities.
	Descriptor() *Descriptor

	// Execute runs the provider logic with resolved inputs.
	// The input parameter is either:
	//   - map[string]any if Descriptor().Decode is nil
	//   - The decoded type if Descriptor().Decode is set and returns a typed struct
	// Resolver values can be accessed via ResolverContextFromContext(ctx).
	// Execution mode and dry-run flag are available via ExecutionModeFromContext(ctx) and DryRunFromContext(ctx).
	Execute(ctx context.Context, input any) (*Output, error)
}

type SchemaValidator struct{}

type SolutionMeta struct {
	// Name is the unique identifier for the solution.
	Name string `json:"name" yaml:"name" doc:"The unique name of the solution" maxLength:"256" example:"my-solution"`
	// Version is the semantic version string of the solution.
	Version string `json:"version" yaml:"version" doc:"The version of the solution" maxLength:"64" example:"1.0.0"`
	// DisplayName is the human-readable name of the solution.
	DisplayName string `` /* 134-byte string literal not displayed */
	// Description provides details about the solution's purpose.
	Description string `` /* 154-byte string literal not displayed */
	// Category classifies the solution.
	Category string `` /* 127-byte string literal not displayed */
	// Tags are searchable keywords associated with the solution.
	Tags []string `json:"tags,omitempty" yaml:"tags,omitempty" doc:"A list of tags for the solution" maxItems:"50"`
}

type ValidationError struct {
	Field      string
	Value      any
	Constraint string
	Message    string
	Actual     string
	Expected   string
}

type ValidationErrors []*ValidationError