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 `json:"apiVersion" yaml:"apiVersion" doc:"Provider API version" example:"v1" pattern:"^v[0-9]+$" required:"true"`

	// 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 `json:"description" yaml:"description" doc:"Provider description" minLength:"10" maxLength:"500" required:"true"`

	// 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)
	//   - 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:"-"`

	// MockBehavior describes what the provider does during dry-run/mock execution.
	// Should explain the simulated behavior without side effects.
	MockBehavior string `json:"mockBehavior" yaml:"mockBehavior" doc:"Dry-run behavior description" minLength:"10" maxLength:"500" required:"true"`

	// 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" required:"true"`

	// 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 `json:"icon,omitempty" yaml:"icon,omitempty" doc:"Icon URL" format:"uri" maxLength:"500"`

	// 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"`

	// Deprecated: This field indicates the provider should no longer be used.
	// Deprecated providers may be removed in future versions.
	Deprecated 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 `json:"description,omitempty" yaml:"description,omitempty" doc:"Example description" maxLength:"300"`
	YAML        string `json:"yaml" yaml:"yaml" doc:"YAML example" minLength:"10" maxLength:"2000" required:"true"`
}

type ExecutionMetrics struct {
	ExecutionCount  uint64 `json:"executionCount" yaml:"executionCount" doc:"Total number of executions"`
	SuccessCount    uint64 `json:"successCount" yaml:"successCount" doc:"Number of successful executions"`
	FailureCount    uint64 `json:"failureCount" yaml:"failureCount" doc:"Number of failed executions"`
	TotalDurationNs uint64 `json:"totalDurationNs" yaml:"totalDurationNs" doc:"Total execution duration in nanoseconds"`
	LastExecutionNs uint64 `json:"lastExecutionNs" yaml:"lastExecutionNs" doc:"Timestamp of last execution in nanoseconds since epoch"`
}

type ExecutionResult struct {
	// Provider is the provider that was executed
	Provider Provider `json:"provider" yaml:"provider" doc:"The provider that was executed"`

	// Output is the validated output from the provider
	Output Output `json:"output" yaml:"output" doc:"The validated output from the provider"`

	// DryRun indicates whether this was a dry-run execution
	DryRun bool `json:"dryRun" yaml:"dryRun" doc:"Whether this was a dry-run execution"`

	// ExecutionDuration is the total time taken to execute the provider
	ExecutionDuration time.Duration `json:"executionDuration" yaml:"executionDuration" doc:"The total time taken to execute the provider" example:"1000000000"`

	// ResolvedInputs are the inputs after resolution (for debugging)
	ResolvedInputs map[string]any `json:"resolvedInputs,omitempty" yaml:"resolvedInputs,omitempty" doc:"The resolved inputs (for debugging)"`
}

type Executor struct {
	// contains filtered or unexported fields
}

type ExecutorOption func(*Executor)

type IOStreams struct {
	// Out is the writer for standard output (typically os.Stdout).
	Out io.Writer
	// ErrOut is the writer for standard error output (typically os.Stderr).
	ErrOut io.Writer
}

type InputResolver struct {
	// contains filtered or unexported fields
}

type InputValue struct {
	Literal any                        `json:"literal,omitempty" yaml:"literal,omitempty" doc:"Direct static value"`
	Rslvr   string                     `json:"rslvr,omitempty" yaml:"rslvr,omitempty" doc:"Resolver binding (e.g., 'environment')"`
	Expr    celexp.Expression          `json:"expr,omitempty" yaml:"expr,omitempty" doc:"CEL expression to evaluate"`
	Tmpl    gotmpl.GoTemplatingContent `json:"tmpl,omitempty" yaml:"tmpl,omitempty" doc:"Go template to render"`
}

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."`
	// ItemAlias is the custom variable name for the current item (empty if using default __item).
	ItemAlias string `json:"itemAlias,omitempty" yaml:"itemAlias,omitempty" doc:"Custom variable name for current item."`
	// IndexAlias is the custom variable name for the current index (empty if using default __index).
	IndexAlias string `json:"indexAlias,omitempty" yaml:"indexAlias,omitempty" doc:"Custom variable name for current index."`
}

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 Metrics struct {
	// contains filtered or unexported fields
}

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 Registry struct {
	// contains filtered or unexported fields
}

type RegistryOption func(*registryOptions)

type SchemaValidator struct{}

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

type ValidationErrors []*ValidationError