props

type AssetMap map[string]fs.FS

type AssetProvider interface {
	GetAssets() Assets
}

type Assets interface {
	fs.FS
	fs.ReadDirFS
	fs.GlobFS
	fs.StatFS

	Slice() []fs.FS
	Names() []string
	Get(name string) fs.FS
	Register(name string, fs fs.FS)
	For(names ...string) Assets
	Merge(others ...Assets) Assets
	Exists(name string) (fs.FS, error)
	Mount(f fs.FS, prefix string)
}

type ConfigProvider interface {
	GetConfig() config.Containable
}

type CoreProvider interface {
	LoggerProvider
	ConfigProvider
	FileSystemProvider
}

type DeliveryMode string

type ErrorHandlerProvider interface {
	GetErrorHandler() errorhandling.ErrorHandler
}

type EventType string

type Feature struct {
	Cmd     FeatureCmd `json:"cmd" yaml:"cmd"`
	Enabled bool       `json:"enabled" yaml:"enabled"`
}

type FeatureCmd string

type FeatureState func([]Feature) []Feature

type FileSystemProvider interface {
	GetFS() afero.Fs
}

type LoggerProvider interface {
	GetLogger() logger.Logger
}

type LoggingConfigProvider interface {
	LoggerProvider
	ConfigProvider
}

type Props struct {
	Tool         Tool
	Logger       logger.Logger
	Config       config.Containable
	Assets       Assets
	FS           afero.Fs
	Version      version.Version
	ErrorHandler errorhandling.ErrorHandler
	Collector    TelemetryCollector // always non-nil; noop when telemetry disabled
}

type ReleaseSource struct {
	Type    string `json:"type"    yaml:"type"`
	Host    string `json:"host"    yaml:"host"`
	Owner   string `json:"owner"   yaml:"owner"`
	Repo    string `json:"repo"    yaml:"repo"`
	Private bool   `json:"private" yaml:"private"`
	// Params holds provider-specific configuration key/value pairs.
	// Keys use snake_case. Valid keys are documented per provider.
	Params map[string]string `json:"params,omitempty" yaml:"params,omitempty"`
}

type TelemetryCollector interface {
	// Track records a telemetry event. No-op when the collector is disabled.
	Track(eventType EventType, name string, extra map[string]string)
	// TrackCommand records a command invocation with duration and exit code.
	TrackCommand(name string, durationMs int64, exitCode int, extra map[string]string)
	// TrackCommandExtended records a command invocation with full context including
	// arguments and error message. When ExtendedCollection is disabled on the
	// collector, args and errMsg are silently dropped — callers do not need to
	// check the flag themselves.
	TrackCommandExtended(name string, args []string, durationMs int64, exitCode int, errMsg string, extra map[string]string)
	// Flush sends all buffered events to the backend and clears the buffer.
	// Checks for and sends spill files before flushing the current buffer.
	Flush(ctx context.Context) error
	// Close flushes pending events and shuts down the backend gracefully.
	// Must be called on process exit to ensure backends like OTLP flush
	// their internal batch queues.
	Close(ctx context.Context) error
	// Drop clears all buffered events and deletes any spill files without sending.
	Drop() error
}

type TelemetryConfig struct {
	// Endpoint is the HTTP JSON endpoint to POST events to.
	// Ignored when OTelEndpoint is set or when Backend is non-nil.
	Endpoint string `json:"endpoint,omitempty" yaml:"endpoint,omitempty"`

	// OTelEndpoint is the OTLP/HTTP base URL (e.g. "https://collector:4318").
	// Takes precedence over Endpoint when set.
	OTelEndpoint string `json:"otel_endpoint,omitempty" yaml:"otel_endpoint,omitempty"`

	// OTelHeaders are HTTP headers sent with every OTLP request (e.g. auth tokens).
	OTelHeaders map[string]string `json:"otel_headers,omitempty" yaml:"otel_headers,omitempty"`

	// OTelInsecure disables TLS for the OTLP endpoint — use only for local collectors.
	OTelInsecure bool `json:"otel_insecure,omitempty" yaml:"otel_insecure,omitempty"`

	// Backend is an optional factory for a custom telemetry backend.
	// Typed as func(*Props) any to avoid importing pkg/telemetry from pkg/props.
	// The returned value must implement telemetry.Backend — pkg/cmd/root performs
	// the type assertion. Takes precedence over Endpoint and OTelEndpoint when set.
	// Not serialisable — set programmatically in tool setup.
	Backend func(*Props) any `json:"-" yaml:"-"`

	// DeletionRequestor is an optional factory for a custom GDPR deletion requestor.
	// Typed as func(*Props) any to avoid importing pkg/telemetry from pkg/props.
	// The returned value must implement telemetry.DeletionRequestor — pkg/cmd/root
	// performs the type assertion. If nil, falls back to sending a
	// data.deletion_request event through the existing backend.
	// Not serialisable — set programmatically in tool setup.
	DeletionRequestor func(*Props) any `json:"-" yaml:"-"`

	// ForceEnabled bypasses the user consent prompt and enables telemetry
	// unconditionally. The telemetry enable/disable/reset commands remain
	// functional so users can still inspect status, but collection cannot be
	// turned off. Intended for enterprise tools deployed in controlled
	// environments where telemetry is a contractual requirement.
	// When set, the first-run consent prompt is suppressed.
	ForceEnabled bool `json:"force_enabled,omitempty" yaml:"force_enabled,omitempty"`

	// ExtendedCollection enables collection of command arguments and error messages
	// in telemetry events. Default: false. When false, args and errors are never
	// recorded regardless of what callers pass to TrackCommandExtended.
	//
	// Enable this only in closed enterprise environments where users are
	// contractually bound by security policies. In public-facing tools, leave
	// this disabled to preserve user privacy.
	ExtendedCollection bool `json:"extended_collection,omitempty" yaml:"extended_collection,omitempty"`

	// DeliveryMode controls the delivery guarantee. Default: DeliveryAtLeastOnce.
	DeliveryMode DeliveryMode `json:"delivery_mode,omitempty" yaml:"delivery_mode,omitempty"`

	// Metadata is additional key/value pairs included in every event.
	// Useful for custom dimensions like environment name or deployment tier.
	Metadata map[string]string `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

type Tool struct {
	Name        string                   `json:"name" yaml:"name"`
	Summary     string                   `json:"summary" yaml:"summary"`
	Description string                   `json:"description" yaml:"description"`
	Features    []Feature                `json:"features" yaml:"features"`
	Help        errorhandling.HelpConfig `json:"-" yaml:"-"`

	// ReleaseSource is the source of truth for the tool's releases (GitHub or GitLab)
	ReleaseSource ReleaseSource `json:"release_source" yaml:"release_source"`

	// Telemetry holds tool-author telemetry configuration.
	// Zero-value is safe — tools that don't set it are unaffected.
	Telemetry TelemetryConfig `json:"telemetry" yaml:"telemetry"`
}

type ToolMetadataProvider interface {
	GetTool() Tool
}

type VersionProvider interface {
	GetVersion() version.Version
}