ports

type AuthProvider interface {
	// GetCredentials returns username and password for a registry.
	GetCredentials(ctx context.Context, registry string) (username, password string, err error)
}

type CapabilityAnalyzer interface {
	ExtractCapabilities(profile entities.ProfileReader) map[string]*sdkEntities.GrantSet
}

type CapabilityCollector interface {
	CollectRequiredCapabilities(ctx context.Context, profile entities.ProfileReader, runtime PluginRuntime, pluginDir string) (map[string]*sdkEntities.GrantSet, error)
}

type CapabilityGatekeeperPort interface {
	GrantCapabilities(
		required *sdkEntities.GrantSet,
		capabilityInfo map[string]CapabilityInfo,
		trustAll bool,
	) (*sdkEntities.GrantSet, error)
}

type CapabilityGranter interface {
	GrantCapabilities(ctx context.Context, required map[string]*sdkEntities.GrantSet, trustAll bool) (map[string]*sdkEntities.GrantSet, error)
}

type CapabilityInfo struct {
	PluginName     string
	IsProfileBased bool
	IsBroad        bool
}

type Closer interface {
	io.Closer
}

type DataRedactor interface {
	Redact(input string) string
}

type EmbeddedPluginSource interface {
	// Get returns the file path to an embedded plugin.
	// Returns empty string if not found.
	Get(name string) string

	// List returns names of all embedded plugins.
	List() []string
}

type EngineFactory interface {
	CreateEngine(ctx context.Context, profile entities.ProfileReader, grantedCaps map[string]*sdkEntities.GrantSet, pluginDir string, filters dto.FilterOptions, execution dto.ExecutionOptions, skipSchemaValidation bool) (ExecutionEngine, error)
}

type ExecutionEngine interface {
	Execute(ctx context.Context, profile entities.ProfileReader) (*execution.ExecutionResult, error)
	Close(ctx context.Context) error
}

type FetchOptions struct {
	// Headers contains custom HTTP headers (e.g., Authorization).
	Headers map[string]string

	// MaxSize limits the response body size in bytes.
	// Default: 10MB if zero.
	MaxSize int64

	// Timeout for the fetch operation.
	// Default: 30s if zero.
	Timeout time.Duration

	// MaxRetries for transient failures (429, 5xx).
	// Default: 3 if zero.
	MaxRetries int

	// Insecure allows invalid TLS certificates when true.
	Insecure bool

	// AllowPrivateNetwork permits fetching from private IP ranges.
	// Default: false (blocked with warning).
	AllowPrivateNetwork bool
}

type FetchResult struct {
	// ContentHash is the SHA256 digest of the content.
	ContentHash values.Digest

	// ETag is the HTTP ETag header value for cache validation.
	ETag string

	// ContentType is the response Content-Type header.
	ContentType string

	// FinalURL is the URL after any redirects.
	FinalURL string

	// Content is the raw profile YAML content.
	Content []byte

	// RedirectCount is the number of redirects followed.
	RedirectCount int
}

type GrantStore interface {
	Load() (*sdkEntities.GrantSet, error)
	Save(grants *sdkEntities.GrantSet) error
	ConfigPath() string
}

type IntegrityVerifier interface {
	// VerifySignature checks the signature of a plugin in the registry.
	VerifySignature(ctx context.Context, ref values.PluginReference) (*SignatureResult, error)

	// Sign signs a plugin artifact (for publishing).
	Sign(ctx context.Context, ref values.PluginReference) error
}

type LockfileRepository interface {
	// Load reads a lockfile from the given path.
	// Returns nil, nil if lockfile doesn't exist.
	Load(ctx context.Context, path string) (*entities.Lockfile, error)

	// Save writes a lockfile to the given path.
	Save(ctx context.Context, lockfile *entities.Lockfile, path string) error

	// Exists checks if a lockfile exists at the given path.
	Exists(ctx context.Context, path string) (bool, error)
}

type OutputFormatter interface {
	Format(result *execution.ExecutionResult) error
}

type OutputFormatterFactory interface {
	// Create returns a formatter for the given format name.
	// options is implementation-specific (typically output.FactoryOptions).
	// Returns error if format is unknown.
	Create(format string, writer io.Writer, options interface{}) (OutputFormatter, error)

	// SupportedFormats returns list of available format names.
	SupportedFormats() []string
}

type OutputWriter interface {
	Write(ctx context.Context, data []byte, dest string) error
}

type Plugin interface {
	// Describe returns plugin metadata including declared capabilities.
	Describe(ctx context.Context) (*PluginInfo, error)
}

type PluginDigester interface {
	// DigestBytes computes SHA-256 of raw bytes.
	DigestBytes(data []byte) string

	// DigestFile computes SHA-256 of a file.
	DigestFile(ctx context.Context, path string) (string, error)
}

type PluginDirectoryResolver interface {
	ResolvePluginDir(ctx context.Context) (string, error)
}

type PluginInfo struct {
	Capabilities *sdkEntities.GrantSet
	Name         string
	Version      string
	Description  string
}

type PluginRegistry interface {
	// Pull downloads a plugin artifact from the registry.
	Pull(ctx context.Context, ref values.PluginReference) (*dto.PluginArtifactDTO, error)

	// Push uploads a plugin artifact to the registry.
	Push(ctx context.Context, artifact *dto.PluginArtifactDTO) error

	// Resolve resolves a reference to its content digest.
	Resolve(ctx context.Context, ref values.PluginReference) (values.Digest, error)
}

type PluginRepository interface {
	// Find retrieves a cached plugin by reference.
	Find(ctx context.Context, ref values.PluginReference) (*entities.Plugin, string, error)

	// Store persists a plugin with its WASM binary.
	// Returns the path to the stored WASM file.
	Store(ctx context.Context, plugin *entities.Plugin, wasm io.Reader) (string, error)

	// List returns all cached plugins.
	List(ctx context.Context) ([]*entities.Plugin, error)

	// Prune removes old versions, keeping only the specified number.
	Prune(ctx context.Context, keepVersions int) error

	// Delete removes a specific plugin from cache.
	Delete(ctx context.Context, ref values.PluginReference) error
}

type PluginRuntime interface {
	// LoadPlugin compiles and caches a plugin from WASM bytes.
	LoadPlugin(ctx context.Context, name string, wasmBytes []byte) (Plugin, error)

	// Close releases runtime resources.
	Close(ctx context.Context) error
}

type PluginRuntimeFactory interface {
	// NewRuntime creates a new plugin runtime with optional configuration.
	// Accepts functional options for capabilities, redaction, memory limits, and caching.
	NewRuntime(ctx context.Context, opts ...RuntimeOption) (PluginRuntime, error)
}

type ProfileAuthProvider interface {
	// GetAuthHeader returns the Authorization header value for the given URL.
	// Returns empty string if no auth is configured for this URL.
	GetAuthHeader(ctx context.Context, url string) (string, error)
}

type ProfileCacheRepository interface {
	// Find retrieves a cached profile by reference.
	// Returns nil if not found.
	Find(ctx context.Context, ref values.ProfileReference) (*entities.ProfileCacheEntry, error)

	// Store persists a profile cache entry.
	Store(ctx context.Context, entry *entities.ProfileCacheEntry) error

	// List returns all cached profiles.
	List(ctx context.Context) ([]*entities.ProfileCacheEntry, error)

	// Delete removes a specific profile from cache.
	Delete(ctx context.Context, ref values.ProfileReference) error

	// Prune removes profiles older than the specified duration.
	// Returns the number of entries removed.
	Prune(ctx context.Context, maxAge time.Duration) (int, error)
}

type ProfileFetcher interface {
	// Fetch retrieves profile content from the given reference.
	// Returns the fetch result containing content, hash, and metadata.
	Fetch(ctx context.Context, ref values.ProfileReference, opts FetchOptions) (*FetchResult, error)
}

type ProfileLoader interface {
	LoadProfile(path string) (*entities.Profile, error)
	// LoadProfileWithCLIVars loads a profile and merges CLI variables before substitution.
	// CLI variables override profile variables at the same path.
	LoadProfileWithCLIVars(path string, cliVars map[string]interface{}) (*entities.Profile, error)
	// LoadProfileWithOptions loads a profile with CLI variables and remote fetch options.
	// remoteOpts configures behavior for remote profile fetching (refresh, timeout, etc.).
	LoadProfileWithOptions(path string, cliVars map[string]interface{}, remoteOpts RemoteLoadOptions) (*entities.Profile, error)
}

type ProfileTrustChecker interface {
	// RequiresTrust returns true if the profile path requires trust verification.
	RequiresTrust(path string) bool

	// IsTrusted returns true if the URL matches a trusted source pattern.
	IsTrusted(url string) bool

	// PromptForTrust prompts the user to trust a remote profile.
	// Returns true if trusted, false if denied, or error for non-interactive mode.
	PromptForTrust(
		ctx context.Context,
		url string,
		requiredCaps map[string]*sdkEntities.GrantSet,
		trustFlag bool,
	) (bool, error)
}

type ProfileValidator interface {
	Validate(profile *entities.Profile) error
	ValidateWithSchemas(ctx context.Context, profile *entities.Profile, runtime PluginRuntime) error
}

type Prompter interface {
	IsInteractive() bool
	PromptForCapability(req sdkEntities.CapabilityRequest) (granted bool, always bool, err error)
	PromptForCapabilities(reqs []sdkEntities.CapabilityRequest) (*sdkEntities.GrantSet, error)
	FormatNonInteractiveError(missing *sdkEntities.GrantSet) error
}

type RemoteLoadOptions struct {
	// Refresh forces cache bypass for remote profiles.
	Refresh bool
	// AllowPrivateNetwork permits fetching from private IPs.
	AllowPrivateNetwork bool
	// Insecure skips TLS validation for remote profiles.
	Insecure bool
	// Timeout for remote fetch operations.
	Timeout time.Duration
}

type RuntimeOption any

type SecretResolver interface {
	// Resolve returns the secret value by name.
	// The resolved value is automatically tracked for redaction.
	Resolve(name string) (string, error)
}

type SensitiveValueProvider interface {
	// Track registers a sensitive value to be protected (redacted).
	Track(value string)

	// AllValues returns all tracked sensitive values.
	AllValues() []string
}

type SignatureResult struct {
	SignedAt        time.Time
	Signer          string
	TransparencyLog string
	Certificate     []byte
	Verified        bool
}

type SystemConfigProvider interface {
	LoadConfig(ctx context.Context, path string) (*system.Config, error)
}

type VersionResolver interface {
	// Resolve converts a version constraint to an exact version.
	// Examples:
	//   "@1.0"   -> "1.0.x" (latest 1.0.x)
	//   "^1.2.0" -> "1.x.x >= 1.2.0"
	//   "~1.2.3" -> "1.2.x >= 1.2.3"
	Resolve(constraint string, available []string) (string, error)
}