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 BootstrapPolicy struct {
	// AutoInitialise, when true and the init feature is enabled, runs a
	// non-interactive init (writing the default config) instead of failing when
	// no config file is found, then continues with the freshly written config.
	AutoInitialise bool `json:"auto_initialise,omitempty" yaml:"auto_initialise,omitempty"`

	// SkipConfigCheck lists commands whose missing-config hard-fail is relaxed
	// to a tolerant load: the pre-run falls back to the embedded default config
	// rather than erroring, so the command's own PreRunE can manage bootstrap.
	// An entry matches a command when it equals either the command's Name() or
	// its full CommandPath() (e.g. "studio" or "krites studio") — the latter
	// disambiguates same-named commands at different tree levels. A command may
	// also be marked via the setup.SkipConfigCheck annotation; either mechanism
	// relaxes the check.
	SkipConfigCheck []string `json:"skip_config_check,omitempty" yaml:"skip_config_check,omitempty"`

	// AuxiliaryCommands lists commands that take the root pre-run's auxiliary
	// fast path: the framework bootstrap — config load, telemetry consent,
	// collector wiring, update check — is skipped entirely (only the --debug
	// flag is still honoured for logging). Cobra's own generated help,
	// completion and __complete commands take this path automatically; the
	// list lets a downstream tool extend the set (e.g. for its own
	// bootstrap-free plumbing commands) without a framework release.
	//
	// This is stronger than SkipConfigCheck: an auxiliary command runs with
	// props.Config left nil, so it must read nothing from configuration.
	// Entries match a command's Name() or full CommandPath(), the same
	// semantics as SkipConfigCheck.
	AuxiliaryCommands []string `json:"auxiliary_commands,omitempty" yaml:"auxiliary_commands,omitempty"`
}

type ConfigLayer string

type ConfigProvider interface {
	GetConfig() *config.Store
}

type DeliveryMode = telemetrytypes.DeliveryMode

type EventType = telemetrytypes.EventType

type Feature struct {
	ID      FeatureID `json:"cmd"     yaml:"cmd"`
	Enabled bool      `json:"enabled" yaml:"enabled"`
}

type FeatureDescriptor struct {
	// ID is the feature's identity and its config/manifest name.
	ID FeatureID
	// ConstName is the exported Go identifier naming this feature's constant,
	// as it must appear in generated source (e.g. "AiCmd").
	//
	// It cannot be derived from ID — "mcp" yields "McpCmd", not "MvpCmd" — and
	// the generator emits it verbatim, so it is carried rather than computed.
	// A feature with no exported constant cannot be scaffolded.
	ConstName string
	// ConstPackage is the import path of the package declaring ConstName.
	//
	// Built-in constants live in props, but a plugin's do not — the forge
	// features are declared by pkg/setup/forge — and generated source must
	// qualify the reference correctly. Carrying the path here is what keeps a
	// feature's generator handling a property of its registration rather than a
	// special case somewhere downstream.
	ConstPackage string
	// Kind classifies the feature. See [FeatureKind].
	Kind FeatureKind
	// Default reports whether the feature is enabled when a tool expresses no
	// preference. Only [KindBuiltin] may set it — see [ErrPluginDefaultOn].
	Default bool
}

type FeatureID string

type FeatureKind string

type FeatureState func([]Feature) []Feature

type LoggerProvider interface {
	GetLogger() logger.Logger
}

type NoopCollector struct{}

type Option func(*Props)

type Props struct {
	Tool   Tool
	Logger logger.Logger
	// Config is the live configuration store. It owns reloads, so it is the
	// thing to hold; a *config.View taken from it is pinned to one snapshot and
	// goes stale the moment the file changes.
	//
	// Read through Config.View(), which is the read surface. Where several
	// values must agree with each other, use Config.With so they all resolve
	// against the same snapshot rather than straddling a reload.
	Config       *config.Store
	Assets       Assets
	FS           afero.Fs
	Version      version.Version
	ErrorHandler errorhandling.ErrorHandler
	// Collector is always non-nil once the root command tree is built: the
	// bootstrap defaults it to a NoopCollector and later replaces it with the
	// resolved *telemetry.Collector. Consumers may call it unconditionally.
	Collector TelemetryCollector
}

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 SigningConfig struct {
	// EmbeddedKeys are ASCII-armored public keys baked into the binary,
	// typically via //go:embed in an internal trustkeys package. They are
	// the embedded trust anchor the SelfUpdater uses to verify the
	// signature over checksums.txt. Not serialised — keys are compile-time
	// build artefacts, never runtime config.
	EmbeddedKeys [][]byte `json:"-" yaml:"-"`

	// RequireChecksum is the tool author's baseline for checksum enforcement,
	// consulted when neither config nor environment supplies one. It is a
	// pointer so "unset" is distinguishable from "explicitly false": nil
	// leaves the framework default (permissive), and a tool wanting
	// fail-closed verification from day one sets it true.
	//
	// It lives here, beside the other tool-author baselines, rather than as a
	// package variable in pkg/setup. The framework constructs the updater, so
	// a tool cannot pass an option to it — but it does own its Props, and
	// process-wide mutable state is not a configuration mechanism. Runtime
	// config (`update.require_checksum`) still overrides it.
	RequireChecksum *bool `json:"-" yaml:"-"`
}

type SlackHelp struct {
	Team    string `json:"team" yaml:"team"`
	Channel string `json:"channel" yaml:"channel"`
}

type TeamsHelp struct {
	Team    string `json:"team" yaml:"team"`
	Channel string `json:"channel" yaml:"channel"`
}

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
	// BackendInfo returns a human-readable description of the active backend
	// (e.g. "otlp (otlp-gateway-prod-gb-south-1.grafana.net)", "noop", "file").
	BackendInfo() string
	// 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
	// Enabled reports whether the collector is actively collecting (as opposed
	// to a no-op disabled collector). Reflects the resolved decision from
	// config, env override, or tool-author ForceEnabled.
	Enabled() bool
}

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

	// Bootstrap groups config-bootstrap lifecycle policy — auto-initialisation
	// and per-command relaxation of the missing-config gate. Zero value is
	// safe and reproduces historical behaviour. See BootstrapPolicy.
	Bootstrap BootstrapPolicy `json:"bootstrap,omitempty" yaml:"bootstrap,omitempty"`

	// ConfigLayers declares which layers of the configuration stack this tool
	// wires. Empty means "unstated" and resolves to DefaultConfigLayers — the
	// set the framework wired before this became declarable — so an existing
	// tool keeps resolving exactly as it did. See ResolveConfigLayers.
	ConfigLayers []ConfigLayer `json:"config_layers,omitempty" yaml:"config_layers,omitempty"`

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

	// ReleaseProvider, when non-nil, is the release backend the self-update
	// subsystem uses, taking precedence over ReleaseSource.Type registry
	// lookup. It is a runtime-only dependency-injection seam — for tests
	// (see go/forge/test) and custom/embedded providers — and is
	// never serialised. Production tools leave it nil and are resolved from the
	// release registry by ReleaseSource.Type as before. An explicit
	// setup.WithReleaseProvider option takes precedence over this field.
	ReleaseProvider forge.Provider `json:"-" yaml:"-"`

	// UpdatePolicy is the tool author's baseline self-update posture
	// (disabled / prompt / enabled). The zero value normalises to
	// UpdatePolicyDisabled — the framework default — so a tool does not
	// force updates out of the box. Overridable at runtime by the
	// `update.policy` config key. See ResolveUpdatePolicy.
	UpdatePolicy UpdatePolicy `json:"update_policy,omitempty" yaml:"update_policy,omitempty"`

	// UpdateCheckInterval is the tool author's baseline throttle between
	// self-update checks. The zero value means "use the framework default"
	// (setup.DefaultCheckInterval, 24h) — it is NOT interpreted as
	// "check every run". Overridable at runtime by the `update.check_interval`
	// config key (where "0"/"0s" does mean every run). See
	// setup.ResolveCheckInterval.
	UpdateCheckInterval time.Duration `json:"update_check_interval,omitempty" yaml:"update_check_interval,omitempty"`

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

	// Signing holds tool-author self-update signature configuration.
	// Zero-value is safe — verification stays dormant until keys and/or
	// require_signature are configured.
	Signing SigningConfig `json:"-" yaml:"-"`

	// EnvPrefix is the environment variable prefix used by the config package.
	// When set, only env vars starting with this prefix (e.g., "GTB_") are
	// considered for config overrides. Empty means no prefix (all env vars match).
	EnvPrefix string `json:"env_prefix,omitempty" yaml:"env_prefix,omitempty"`

	// InstallHint is shown when a feature requires a full release binary
	// (e.g. embedded docs) that the running binary lacks. Set it to your
	// tool's recommended installation command. When empty, a generic
	// message referencing Name is shown — the framework never assumes a
	// particular installer.
	InstallHint string `json:"install_hint,omitempty" yaml:"install_hint,omitempty"`
}

type ToolMetadataProvider interface {
	GetTool() Tool
}

type UpdatePolicy string