props

type AssetMap map[string]fs.FS

type AssetProvider interface {
	GetAssets() *Assets
}

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

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 ConfigSource struct {
	// Name is unique in the stack, a config key segment and a command word:
	// it names the slot's layer, its settings and `init config <name>`.
	Name string `json:"name" yaml:"name"`
	// Kind picks the adapter: vault, consul, aws-s3, file, ...
	Kind string `json:"kind" yaml:"kind"`
	// Required, when nil, is true: an unreachable or unconfigured slot stops
	// the tool (spec 0204 D6).
	Required *bool `json:"required,omitempty" yaml:"required,omitempty"`
	// Writable, when nil, is the kind's default, which is read-only for every
	// kind but keychain (spec 0204 D7, D12).
	Writable *bool `json:"writable,omitempty" yaml:"writable,omitempty"`
}

type ConfigSourceState string

type ConfigSourceStatus struct {
	Slot  ConfigSource
	State ConfigSourceState
	// Writable and Sensitive are the built layer's, after the slot's own
	// writable setting and the kind's default.
	Writable  bool
	Sensitive bool
	// Credential names the link of the slot's credential chain that answered,
	// as its factory reported it; empty when the kind reports none.
	Credential string
	// Err is why an unavailable slot was left out.
	Err string
}

type ConfigSpec struct {
	// Layers is the stack by name, lowest precedence first: the order is the
	// precedence. Empty resolves to DefaultConfigLayers.
	Layers []ConfigLayer `json:"layers,omitempty" yaml:"layers,omitempty"`

	// Format is the format of the tool's own config file, the one init writes
	// and config set edits: yaml, toml, json or hcl. Empty is yaml. A format
	// other than yaml must be linked (spec 0204 D2).
	Format string `json:"format,omitempty" yaml:"format,omitempty"`

	// Sources are the config source slots the tool declares, each placed by
	// name in Layers (spec 0204 D15). Where each connects is runtime
	// configuration under config.sources.<name>, never declared here.
	Sources []ConfigSource `json:"sources,omitempty" yaml:"sources,omitempty"`

	// KeyCase is how every Store the tool builds compares keys. Empty is
	// folded (spec 0209 D1).
	KeyCase KeyCase `json:"key_case,omitempty" yaml:"key_case,omitempty"`
}

type DeliveryMode = telemetrytypes.DeliveryMode

type Enumerator interface {
	Descriptors() []features.Descriptor
}

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
	// Dynamic reports whether a flag backend may override the static state at
	// evaluation time (spec 0199 D7). Every built-in is static.
	Dynamic bool
	// Order places a non-builtin feature among its kind: features with an
	// Order sort by it after the built-ins, features without one sort after
	// those by kind and ID. The forges use it so a chooser lists them as the
	// framework intends (GitHub first, the default backend) rather than
	// alphabetically. Zero means unordered.
	Order int
}

type FeatureID = features.ID

type FeatureKind = features.Kind

type FeatureState func([]Feature) []Feature

type IO interface {
	In() io.Reader
	Out() io.Writer
	Err() io.Writer
	// Interactive reports whether In is a terminal a person is typing at.
	Interactive() bool
	// Accessible reports whether forms should run as line prompts rather than
	// a TUI: a screen reader, TERM=dumb, or a test.
	Accessible() bool
}

type KeyCase string

type LoggerProvider interface {
	GetLogger() logger.Logger
}

type MCPConfig struct {
	Mode MCPMode `json:"mode,omitempty" yaml:"mode,omitempty"`
}

type MCPMode string

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.Info
	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
	// IO is this invocation's streams and whether a person is at them. Nil
	// reads as StdIO{}, the process's; the root fills it from the command once
	// (spec 0198 D1). Read through GetIO.
	IO IO
	// Features is what this tool has: the resolved enabled state of every
	// feature this binary declared, and the contributions of the enabled ones
	// (spec 0199 D3). New resolves it from a snapshot of the default registry
	// and Tool.Features; ApplyDefaults does the same for a literal Props. Every
	// static decision (which commands exist, what doctor inventories) reads it.
	Features features.Set
	// Flags answers whether a feature is on for a request. It defaults to
	// Features (every answer static); a service wires a features.Dynamic over a
	// backend for the features that opt in (spec 0199 D10).
	Flags features.Evaluator
	// LogLevel is the level the root's --debug and the config's log.level
	// move, for a command that builds its own slog handler (the MCP server
	// does: its stdout carries the protocol, so it logs to stderr on its own
	// handler). Per root, like everything else here (spec 0202 D4). Read
	// through GetLogLevel.
	LogLevel *slog.LevelVar
	// SourceStatuses is how each declared config source slot fared when the
	// root built the store, in declared order (spec 0204 D10).
	SourceStatuses []ConfigSourceStatus
	// contains filtered or unexported fields
}

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"`
	// BaseURL is the static release channel's one setting (spec 0203 D1): the
	// HTTPS location the pointer and the per-tag manifests are published under.
	// Read only when Type is ReleaseSourceStatic; the forge fields are unused then.
	BaseURL string `json:"base_url,omitempty" yaml:"base_url,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:"-"`

	// AnchorOnlyKeys are ASCII-armored public keys that join the trust set,
	// and so the embedded-versus-WKD cross-check, but never validate a
	// release signature. A rotation-authority key published beside the
	// release keys belongs here rather than in EmbeddedKeys.
	AnchorOnlyKeys [][]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 StdIO struct {
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
	// AccessibleMode asks for line prompts; the root's --accessible flag and
	// GTB_ACCESSIBLE set it.
	AccessibleMode bool
}

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

	// Config declares the tool's configuration stack and its order. See
	// ConfigSpec and ResolveConfigLayers.
	Config ConfigSpec `json:"config,omitempty" yaml:"config,omitempty"`

	// ConfigLayers declares which layers of the configuration stack this tool
	// wires, resolved in the framework's order whatever order it lists.
	//
	// Deprecated: use Config.Layers, whose order is the precedence (spec 0204
	// D13).
	ConfigLayers []ConfigLayer `json:"config_layers,omitempty" yaml:"config_layers,omitempty"`
	// MCP is the publication mode of the tool's MCP server; the zero value is
	// compact. See MCPConfig.
	MCP MCPConfig `json:"mcp,omitempty" yaml:"mcp,omitempty"`

	// ReleaseSource is the source of truth for the tool's releases; see
	// ReleaseSource for the supported types.
	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.
	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