Opt-in Telemetry Specification¶

// In pkg/props/telemetry.go (new file)

// EventType identifies the category of telemetry event.
// Defined here alongside TelemetryCollector so that commands can reference
// event type constants without importing pkg/telemetry.
// The same constants are mirrored in pkg/telemetry — since EventType is a
// string typedef, values from either package are interchangeable.
type EventType string

const (
    EventCommandInvocation EventType = "command.invocation"
    EventCommandError      EventType = "command.error"
    EventFeatureUsed       EventType = "feature.used"
    EventUpdateCheck       EventType = "update.check"
    EventUpdateApplied     EventType = "update.applied"
    EventDeletionRequest   EventType = "data.deletion_request"
)

// TelemetryCollector is the interface through which commands emit telemetry events.
// Defined here (not in pkg/telemetry) to avoid an import cycle.
// The concrete implementation is *telemetry.Collector from pkg/telemetry.
// Props.Collector is always non-nil — when telemetry is disabled it is a noop.
type TelemetryCollector interface {
    // Track records a telemetry event. No-op when the collector is disabled.
    Track(eventType EventType, name 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
    // Drop clears all buffered events and deletes any spill files without sending.
    Drop() error
}

// DeliveryMode controls the delivery guarantee for telemetry events.
type DeliveryMode string

const (
    // DeliveryAtLeastOnce deletes spill files after successful send.
    // Possible duplicates if the ack is lost; no data loss.
    DeliveryAtLeastOnce DeliveryMode = "at_least_once"
    // DeliveryAtMostOnce deletes spill files before sending.
    // Possible data loss; no duplicates.
    DeliveryAtMostOnce DeliveryMode = "at_most_once"
)

// TelemetryConfig holds tool-author telemetry declarations.
// It is embedded in Tool and specifies where and how to send telemetry.
// The end-user's opt-in state is stored in the config file under
// telemetry.enabled and telemetry.local_only — endpoints are not
// user-configurable.
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:"-"`

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

// Tool gains a Telemetry field:
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 ReleaseSource            `json:"release_source" yaml:"release_source"`
    Telemetry     TelemetryConfig          `json:"telemetry"      yaml:"telemetry"`
}

// In pkg/props/tool.go — default disabled
TelemetryCmd = FeatureCmd("telemetry")

// isDefaultEnabled: TelemetryCmd returns false (not in defaults list)

var _ props.TelemetryCollector = (*telemetry.Collector)(nil)

// EventType identifies the category of telemetry event.
// Mirrored from pkg/props — since both resolve to string, values are
// interchangeable at the interface boundary.
type EventType string

const (
    EventCommandInvocation EventType = "command.invocation"
    EventCommandError      EventType = "command.error"
    EventFeatureUsed       EventType = "feature.used"
    EventUpdateCheck       EventType = "update.check"
    EventUpdateApplied     EventType = "update.applied"
    EventDeletionRequest   EventType = "data.deletion_request"
)

// Event represents a single telemetry event.
type Event struct {
    Timestamp time.Time         `json:"timestamp"`
    Type      EventType         `json:"type"`
    Name      string            `json:"name"`
    MachineID string            `json:"machine_id"` // hashed, never raw
    ToolName  string            `json:"tool_name"`
    Version   string            `json:"version"`
    OS        string            `json:"os"`
    Arch      string            `json:"arch"`
    Metadata  map[string]string `json:"metadata,omitempty"`
}

// Backend is the interface for telemetry data sinks.
// Implementations must be safe for concurrent use.
// Send must be non-blocking or short-timeout to avoid impacting CLI performance.
type Backend interface {
    Send(ctx context.Context, events []Event) error
    Close() error
}

// DeletionRequestor sends a GDPR data deletion request for a given machine ID.
// Implementations should be best-effort — deletion cannot be guaranteed for all
// backend types.
type DeletionRequestor interface {
    RequestDeletion(ctx context.Context, machineID string) error
}

// Config holds runtime telemetry configuration read from the user's config file.
// Endpoints are not included — they are tool-author concerns set in
// props.TelemetryConfig, not user-configurable.
type Config struct {
    Enabled   bool `yaml:"enabled"`
    LocalOnly bool `yaml:"local_only"`
}

// Collector accumulates events and flushes to the backend.
// All methods are safe for concurrent use. When disabled, all operations
// are no-ops — callers do not need to check whether telemetry is enabled.
type Collector struct {
    backend      Backend
    config       Config
    toolName     string
    version      string
    machineID    string
    metadata     map[string]string
    buffer       []Event
    mu           sync.Mutex
    log          logger.Logger
    dataDir      string
    deliveryMode props.DeliveryMode
    maxBuffer    int // default 1000
}

const defaultMaxBuffer = 1000

// NewCollector creates a Collector. When cfg.Enabled is false, returns a noop
// collector so callers never need to nil-check.
func NewCollector(cfg Config, backend Backend, toolName, version string, metadata map[string]string, log logger.Logger, dataDir string, deliveryMode props.DeliveryMode) *Collector {
    if !cfg.Enabled {
        return &Collector{backend: NewNoopBackend(), log: log, maxBuffer: defaultMaxBuffer}
    }

    if deliveryMode == "" {
        deliveryMode = props.DeliveryAtLeastOnce
    }

    return &Collector{
        backend:      backend,
        config:       cfg,
        toolName:     toolName,
        version:      version,
        machineID:    HashedMachineID(),
        metadata:     metadata,
        log:          log,
        dataDir:      dataDir,
        deliveryMode: deliveryMode,
        maxBuffer:    defaultMaxBuffer,
    }
}

// Track records a telemetry event. No-op when collector is disabled.
// When the in-memory buffer reaches maxBuffer, events are spilled to disk.
func (c *Collector) Track(eventType props.EventType, name string, extra map[string]string) {
    c.mu.Lock()
    defer c.mu.Unlock()

    if c.backend == nil {
        return
    }

    merged := make(map[string]string, len(c.metadata)+len(extra))
    for k, v := range c.metadata {
        merged[k] = v
    }

    for k, v := range extra {
        merged[k] = v
    }

    c.buffer = append(c.buffer, Event{
        Timestamp: time.Now().UTC(),
        Type:      EventType(eventType),
        Name:      name,
        MachineID: c.machineID,
        ToolName:  c.toolName,
        Version:   c.version,
        OS:        runtime.GOOS,
        Arch:      runtime.GOARCH,
        Metadata:  merged,
    })

    if len(c.buffer) >= c.maxBuffer {
        c.spillToDisk()
    }
}

// Flush sends all buffered events to the backend, then clears the buffer.
// Checks for and sends spill files before flushing the current buffer.
func (c *Collector) Flush(ctx context.Context) error {
    // Send spill files first
    if err := c.flushSpillFiles(ctx); err != nil {
        c.log.Debug("failed to flush spill files", "error", err)
    }

    c.mu.Lock()
    events := make([]Event, len(c.buffer))
    copy(events, c.buffer)
    c.buffer = c.buffer[:0]
    c.mu.Unlock()

    if len(events) == 0 {
        return nil
    }

    if err := c.backend.Send(ctx, events); err != nil {
        c.log.Warn("telemetry flush failed", "error", err, "events_dropped", len(events))
        return err
    }

    c.log.Debug("telemetry flushed", "events", len(events))

    return nil
}

// Drop clears all buffered events and deletes any spill files without sending.
// Called when the user disables telemetry to ensure immediate consent withdrawal.
func (c *Collector) Drop() error {
    c.mu.Lock()
    c.buffer = c.buffer[:0]
    c.mu.Unlock()

    return c.deleteSpillFiles()
}

const (
    maxSpillFileSize = 1 << 20 // 1 MB
    maxSpillFiles    = 10
)

// spillToDisk writes the current buffer to a spill file and clears the buffer.
// Must be called with c.mu held.
func (c *Collector) spillToDisk() {
    if c.dataDir == "" {
        return
    }

    data, err := json.Marshal(c.buffer)
    if err != nil {
        c.log.Debug("failed to marshal spill data", "error", err)
        return
    }

    // Enforce per-file size cap
    if len(data) > maxSpillFileSize {
        data = data[:maxSpillFileSize]
    }

    // Enforce max spill file count — delete oldest if at limit
    c.pruneSpillFiles()

    filename := filepath.Join(c.dataDir, fmt.Sprintf("telemetry-spill-%d.json", time.Now().UnixNano()))
    if err := os.WriteFile(filename, data, 0o644); err != nil {
        c.log.Debug("failed to write spill file", "error", err)
        return
    }

    c.buffer = c.buffer[:0]
}

// flushSpillFiles reads and sends all spill files, cleaning up after successful delivery.
// Delivery mode controls whether files are deleted before or after send.
func (c *Collector) flushSpillFiles(ctx context.Context) error {
    files, err := filepath.Glob(filepath.Join(c.dataDir, "telemetry-spill-*.json"))
    if err != nil || len(files) == 0 {
        return err
    }

    sort.Strings(files) // oldest first

    for _, f := range files {
        data, err := os.ReadFile(f)
        if err != nil {
            c.log.Debug("failed to read spill file", "error", err, "file", f)
            continue
        }

        var events []Event
        if err := json.Unmarshal(data, &events); err != nil {
            c.log.Debug("failed to unmarshal spill file", "error", err, "file", f)
            os.Remove(f) // corrupt file — discard
            continue
        }

        if c.deliveryMode == props.DeliveryAtMostOnce {
            os.Remove(f) // delete before send — no duplicates, possible loss
        }

        if err := c.backend.Send(ctx, events); err != nil {
            c.log.Debug("failed to send spill file", "error", err, "file", f)
            continue // leave file for retry (at-least-once) or already deleted (at-most-once)
        }

        if c.deliveryMode == props.DeliveryAtLeastOnce {
            os.Remove(f) // delete after successful send
        }
    }

    return nil
}

// deleteSpillFiles removes all spill files. Used by Drop() on consent withdrawal.
func (c *Collector) deleteSpillFiles() error {
    files, _ := filepath.Glob(filepath.Join(c.dataDir, "telemetry-spill-*.json"))
    for _, f := range files {
        os.Remove(f)
    }
    return nil
}

// pruneSpillFiles removes the oldest spill files when the count exceeds maxSpillFiles.
// Must be called with c.mu held.
func (c *Collector) pruneSpillFiles() {
    files, _ := filepath.Glob(filepath.Join(c.dataDir, "telemetry-spill-*.json"))
    if len(files) < maxSpillFiles {
        return
    }

    sort.Strings(files)
    for _, f := range files[:len(files)-maxSpillFiles+1] {
        os.Remove(f)
    }
}

// ResolveDataDir determines the directory for telemetry data files (spill files,
// local-only logs). Uses the config directory if it exists and is writable,
// otherwise falls back to /tmp.
func ResolveDataDir(p *props.Props) string {
    if p.Config != nil {
        v := p.Config.GetViper()
        if cfgFile := v.ConfigFileUsed(); cfgFile != "" {
            dir := filepath.Dir(cfgFile)
            if info, err := os.Stat(dir); err == nil && info.IsDir() {
                // Check writability
                testFile := filepath.Join(dir, ".telemetry-write-test")
                if f, err := os.Create(testFile); err == nil {
                    f.Close()
                    os.Remove(testFile)
                    return dir
                }
            }
        }
    }

    return os.TempDir()
}

// HashedMachineID returns a privacy-preserving machine identifier derived from
// multiple system signals: OS machine ID, first non-loopback MAC address,
// hostname, and username. Each signal degrades gracefully if unavailable.
// The result is the first 8 bytes of the SHA-256 hash, encoded as 16 hex chars.
// Computed fresh on every invocation — not persisted to config.
func HashedMachineID() string {
    var parts []string

    // OS machine ID — most reliable per-installation identifier
    // Linux: /etc/machine-id, macOS: IOPlatformUUID, Windows: MachineGuid
    parts = append(parts, osMachineID())

    // First non-loopback MAC address — hardware dimension
    parts = append(parts, firstMACAddress())

    // Hostname + username — fallback signals
    hostname, _ := os.Hostname()
    parts = append(parts, hostname)

    u, _ := user.Current()
    if u != nil {
        parts = append(parts, u.Username)
    }

    raw := strings.Join(parts, ":")
    h := sha256.Sum256([]byte(raw))

    return hex.EncodeToString(h[:8]) // 16 hex chars
}

// osMachineID returns the OS-level machine identifier.
// Linux: reads /etc/machine-id
// macOS: reads IOPlatformUUID via ioreg
// Windows: reads MachineGuid from registry
// Returns "" if unavailable.
func osMachineID() string {
    // Platform-specific implementation
    // ...
}

// firstMACAddress returns the hardware address of the first non-loopback
// network interface. Returns "" if unavailable (e.g. containers with
// randomised MACs — the hash still works with reduced uniqueness).
func firstMACAddress() string {
    ifaces, err := net.Interfaces()
    if err != nil {
        return ""
    }

    for _, iface := range ifaces {
        if iface.Flags&net.FlagLoopback != 0 {
            continue
        }
        if len(iface.HardwareAddr) > 0 {
            return iface.HardwareAddr.String()
        }
    }

    return ""
}

type noopBackend struct{}

func NewNoopBackend() Backend                                      { return &noopBackend{} }
func (n *noopBackend) Send(_ context.Context, _ []Event) error     { return nil }
func (n *noopBackend) Close() error                                { return nil }

func NewStdoutBackend(w io.Writer) Backend { return &stdoutBackend{w: w} }

func (s *stdoutBackend) Send(_ context.Context, events []Event) error {
    enc := json.NewEncoder(s.w)
    enc.SetIndent("", "  ")
    return enc.Encode(events)
}

func (s *stdoutBackend) Close() error { return nil }

func NewFileBackend(path string) Backend { return &fileBackend{path: path} }

func (f *fileBackend) Send(_ context.Context, events []Event) error {
    f.mu.Lock()
    defer f.mu.Unlock()

    file, err := os.OpenFile(f.path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
    if err != nil {
        return errors.Wrap(err, "opening telemetry log")
    }

    defer file.Close()

    enc := json.NewEncoder(file)
    for _, event := range events {
        if err := enc.Encode(event); err != nil {
            return errors.Wrap(err, "writing telemetry event")
        }
    }

    return nil
}

func (f *fileBackend) Close() error { return nil }

func NewHTTPBackend(endpoint string, log logger.Logger) Backend {
    return &httpBackend{
        endpoint: endpoint,
        client:   gtbhttp.NewClient(gtbhttp.WithTimeout(5 * time.Second)),
        log:      log,
    }
}

func (h *httpBackend) Send(ctx context.Context, events []Event) error {
    body, err := json.Marshal(events)
    if err != nil {
        return errors.Wrap(err, "marshalling telemetry events")
    }

    req, err := http.NewRequestWithContext(ctx, http.MethodPost, h.endpoint, bytes.NewReader(body))
    if err != nil {
        return errors.Wrap(err, "creating telemetry request")
    }

    req.Header.Set("Content-Type", "application/json")

    resp, err := h.client.Do(req)
    if err != nil {
        return nil // silently drop — telemetry must never block the user
    }

    defer resp.Body.Close()

    if resp.StatusCode >= 400 {
        h.log.Debug("telemetry endpoint returned non-success status",
            "status", resp.StatusCode, "endpoint", h.endpoint)
    }

    return nil
}

func (h *httpBackend) Close() error { return nil }

// OTelOption configures the OTLP backend.
type OTelOption func(*otelConfig)

type otelConfig struct {
    headers  map[string]string
    insecure bool
    log      logger.Logger
}

// WithOTelHeaders sets HTTP headers sent with every OTLP request (e.g. auth tokens).
func WithOTelHeaders(headers map[string]string) OTelOption {
    return func(c *otelConfig) { c.headers = headers }
}

// WithOTelInsecure disables TLS — use only for local collectors.
func WithOTelInsecure() OTelOption {
    return func(c *otelConfig) { c.insecure = true }
}

// WithOTelLogger sets the logger for routing OTel SDK errors.
func WithOTelLogger(log logger.Logger) OTelOption {
    return func(c *otelConfig) { c.log = log }
}

// NewOTelBackend creates a Backend that exports events as OTel log records via OTLP/HTTP.
// endpoint is the base URL of the OTLP HTTP endpoint
// (e.g. "https://collector.example.com:4318").
// A custom OTel error handler is registered to route SDK errors to the provided logger.
func NewOTelBackend(ctx context.Context, endpoint string, opts ...OTelOption) (Backend, error) {
    cfg := &otelConfig{}
    for _, o := range opts {
        o(cfg)
    }

    // Register custom error handler to surface OTel SDK errors via our logger
    if cfg.log != nil {
        otel.SetErrorHandler(otel.ErrorHandlerFunc(func(err error) {
            cfg.log.Debug("OTel SDK error", "error", err)
        }))
    }

    exporterOpts := []otlploghttp.Option{
        otlploghttp.WithEndpoint(endpoint),
    }

    if cfg.insecure {
        exporterOpts = append(exporterOpts, otlploghttp.WithInsecure())
    }

    if len(cfg.headers) > 0 {
        exporterOpts = append(exporterOpts, otlploghttp.WithHeaders(cfg.headers))
    }

    exporter, err := otlploghttp.New(ctx, exporterOpts...)
    if err != nil {
        return nil, errors.Wrap(err, "creating OTLP log exporter")
    }

    provider := sdklog.NewLoggerProvider(
        sdklog.WithProcessor(sdklog.NewBatchProcessor(exporter)),
    )

    return &otelBackend{provider: provider}, nil
}

func (o *otelBackend) Send(ctx context.Context, events []Event) error {
    logger := o.provider.Logger("gtb-telemetry")

    for _, e := range events {
        var rec log.Record
        rec.SetTimestamp(e.Timestamp)
        rec.SetSeverity(log.SeverityInfo)
        rec.SetBody(log.StringValue(e.Name))
        rec.AddAttributes(
            log.String("event.type", string(e.Type)),
            log.String("tool.name", e.ToolName),
            log.String("tool.version", e.Version),
            log.String("host.arch", e.Arch),
            log.String("os.type", e.OS),
            log.String("machine.id", e.MachineID),
        )

        for k, v := range e.Metadata {
            rec.AddAttributes(log.String(k, v))
        }

        logger.Emit(ctx, rec)
    }

    return nil
}

func (o *otelBackend) Close() error {
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    return o.provider.Shutdown(ctx)
}

// HTTPDeletionRequestor sends a deletion request via HTTP POST/DELETE.
type HTTPDeletionRequestor struct {
    endpoint string
    client   *http.Client
    log      logger.Logger
}

func NewHTTPDeletionRequestor(endpoint string, log logger.Logger) DeletionRequestor {
    return &HTTPDeletionRequestor{
        endpoint: endpoint,
        client:   gtbhttp.NewClient(gtbhttp.WithTimeout(10 * time.Second)),
        log:      log,
    }
}

func (h *HTTPDeletionRequestor) RequestDeletion(ctx context.Context, machineID string) error {
    body, _ := json.Marshal(map[string]string{"machine_id": machineID})
    req, err := http.NewRequestWithContext(ctx, http.MethodPost, h.endpoint, bytes.NewReader(body))
    if err != nil {
        return errors.Wrap(err, "creating deletion request")
    }

    req.Header.Set("Content-Type", "application/json")

    resp, err := h.client.Do(req)
    if err != nil {
        return errors.Wrap(err, "sending deletion request")
    }

    defer resp.Body.Close()

    if resp.StatusCode >= 400 {
        h.log.Debug("deletion endpoint returned non-success status",
            "status", resp.StatusCode, "endpoint", h.endpoint)
        return errors.Newf("deletion request returned status %d", resp.StatusCode)
    }

    return nil
}

// EmailDeletionRequestor composes a deletion request email.
type EmailDeletionRequestor struct {
    address string
    toolName string
}

func NewEmailDeletionRequestor(address, toolName string) DeletionRequestor {
    return &EmailDeletionRequestor{address: address, toolName: toolName}
}

func (e *EmailDeletionRequestor) RequestDeletion(_ context.Context, machineID string) error {
    // Opens a mailto: link with pre-filled subject and body
    subject := fmt.Sprintf("Data Deletion Request — %s", e.toolName)
    body := fmt.Sprintf("Please delete all telemetry data associated with machine ID: %s", machineID)
    url := fmt.Sprintf("mailto:%s?subject=%s&body=%s",
        e.address,
        url.QueryEscape(subject),
        url.QueryEscape(body))
    return openURL(url) // platform-specific browser/mail client launch
}

// EventDeletionRequestor sends a data.deletion_request event through the existing
// telemetry backend. This is the universal fallback — works with any backend type.
type EventDeletionRequestor struct {
    backend Backend
}

func NewEventDeletionRequestor(backend Backend) DeletionRequestor {
    return &EventDeletionRequestor{backend: backend}
}

func (e *EventDeletionRequestor) RequestDeletion(ctx context.Context, machineID string) error {
    event := Event{
        Timestamp: time.Now().UTC(),
        Type:      EventDeletionRequest,
        Name:      "deletion_request",
        MachineID: machineID,
    }

    return e.backend.Send(ctx, []Event{event})
}

// In pkg/cmd/root/root.go — called from PersistentPreRunE

func buildTelemetryCollector(ctx context.Context, p *props.Props) *telemetry.Collector {
    dataDir := telemetry.ResolveDataDir(p)

    if p.Tool.IsDisabled(props.TelemetryCmd) {
        return telemetry.NewCollector(telemetry.Config{}, telemetry.NewNoopBackend(), p.Tool.Name, p.Version.Version, nil, p.Logger, dataDir, props.DeliveryAtLeastOnce)
    }

    cfg := telemetry.Config{
        Enabled:   p.Config.GetBool("telemetry.enabled"),
        LocalOnly: p.Config.GetBool("telemetry.local_only"),
    }

    // Env var override (non-interactive bypass — tool-name-agnostic)
    if val, ok := os.LookupEnv("TELEMETRY_ENABLED"); ok {
        cfg.Enabled, _ = strconv.ParseBool(val)
    }

    if val, ok := os.LookupEnv("TELEMETRY_LOCAL"); ok {
        cfg.LocalOnly, _ = strconv.ParseBool(val)
    }

    if !cfg.Enabled {
        return telemetry.NewCollector(telemetry.Config{}, telemetry.NewNoopBackend(), p.Tool.Name, p.Version.Version, nil, p.Logger, dataDir, props.DeliveryAtLeastOnce)
    }

    deliveryMode := p.Tool.Telemetry.DeliveryMode
    if deliveryMode == "" {
        deliveryMode = props.DeliveryAtLeastOnce
    }

    var backend telemetry.Backend

    switch {
    case p.Tool.Telemetry.Backend != nil:
        // Custom backend supplied by the tool author.
        // TelemetryConfig.Backend is func(*Props) any to avoid an import cycle
        // in pkg/props. Type-assert here in pkg/cmd/root which imports both.
        raw := p.Tool.Telemetry.Backend(p)
        b, ok := raw.(telemetry.Backend)
        if !ok {
            p.Logger.Warn("TelemetryConfig.Backend did not return a telemetry.Backend; falling back to noop")
            backend = telemetry.NewNoopBackend()
        } else {
            backend = b
        }
    case cfg.LocalOnly:
        backend = telemetry.NewFileBackend(filepath.Join(dataDir, "telemetry.log"))
    case p.Tool.Telemetry.OTelEndpoint != "":
        opts := []telemetry.OTelOption{
            telemetry.WithOTelLogger(p.Logger),
        }
        if p.Tool.Telemetry.OTelInsecure {
            opts = append(opts, telemetry.WithOTelInsecure())
        }
        if len(p.Tool.Telemetry.OTelHeaders) > 0 {
            opts = append(opts, telemetry.WithOTelHeaders(p.Tool.Telemetry.OTelHeaders))
        }
        b, err := telemetry.NewOTelBackend(ctx, p.Tool.Telemetry.OTelEndpoint, opts...)
        if err != nil {
            p.Logger.Warn("failed to initialise OTel backend, falling back to noop", "error", err)
            backend = telemetry.NewNoopBackend()
        } else {
            backend = b
        }
    case p.Tool.Telemetry.Endpoint != "":
        backend = telemetry.NewHTTPBackend(p.Tool.Telemetry.Endpoint, p.Logger)
    default:
        backend = telemetry.NewNoopBackend() // enabled but no sink configured
    }

    return telemetry.NewCollector(cfg, backend, p.Tool.Name, p.Version.Version, p.Tool.Telemetry.Metadata, p.Logger, dataDir, deliveryMode)
}

// In pkg/props/props.go
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
}

// In pkg/cmd/root/root.go — registered during root command construction
cobra.OnFinalize(func() {
    if props.Collector != nil {
        // Re-check enabled state — if user ran `telemetry disable` mid-session,
        // respect the withdrawal of consent and do not flush.
        if !props.Config.GetBool("telemetry.enabled") {
            return
        }
        ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
        defer cancel()
        _ = props.Collector.Flush(ctx)
    }
})

// pkg/cmd/telemetry/telemetry.go

func NewCmdTelemetry(p *props.Props) *cobra.Command {
    cmd := &cobra.Command{
        Use:   "telemetry",
        Short: "Manage anonymous usage telemetry",
    }

    cmd.AddCommand(newEnableCmd(p), newDisableCmd(p), newStatusCmd(p), newResetCmd(p))

    return cmd
}

func newEnableCmd(p *props.Props) *cobra.Command {
    return &cobra.Command{
        Use:   "enable",
        Short: "Enable anonymous usage telemetry",
        RunE: func(cmd *cobra.Command, _ []string) error {
            p.Config.Set("telemetry.enabled", true)

            v := p.Config.GetViper()
            if err := v.WriteConfig(); err != nil {
                if err2 := v.SafeWriteConfig(); err2 != nil {
                    return errors.Wrap(err2, "failed to write config")
                }
            }

            p.Logger.Print("Telemetry enabled. Thank you for helping improve " + p.Tool.Name + "!")
            p.Logger.Print("No personally identifiable information is collected.")

            return nil
        },
    }
}

func newDisableCmd(p *props.Props) *cobra.Command {
    return &cobra.Command{
        Use:   "disable",
        Short: "Disable usage telemetry",
        RunE: func(cmd *cobra.Command, _ []string) error {
            p.Config.Set("telemetry.enabled", false)

            v := p.Config.GetViper()
            if err := v.WriteConfig(); err != nil {
                if err2 := v.SafeWriteConfig(); err2 != nil {
                    return errors.Wrap(err2, "failed to write config")
                }
            }

            // Immediately drop all buffered and spilled events — the user's
            // withdrawal of consent is immediate and total.
            if p.Collector != nil {
                _ = p.Collector.Drop()
            }

            p.Logger.Print("Telemetry disabled. All pending events have been discarded.")

            return nil
        },
    }
}

func newStatusCmd(p *props.Props) *cobra.Command {
    return &cobra.Command{
        Use:   "status",
        Short: "Show current telemetry status",
        RunE: func(cmd *cobra.Command, _ []string) error {
            enabled := p.Config.GetBool("telemetry.enabled")
            localOnly := p.Config.GetBool("telemetry.local_only")

            switch {
            case !enabled:
                p.Logger.Print("Telemetry: disabled")
            case localOnly:
                p.Logger.Print("Telemetry: enabled (local-only)")
            default:
                p.Logger.Print("Telemetry: enabled")
            }

            p.Logger.Print("Machine ID: " + telemetry.HashedMachineID())

            return nil
        },
    }
}

func newResetCmd(p *props.Props) *cobra.Command {
    return &cobra.Command{
        Use:   "reset",
        Short: "Clear local telemetry data and request remote deletion",
        Long: "Clears all local telemetry data (buffered events, spill files, " +
            "local-only logs) and sends a data deletion request to the remote " +
            "backend. Telemetry is disabled after reset.",
        RunE: func(cmd *cobra.Command, _ []string) error {
            machineID := telemetry.HashedMachineID()

            // 1. Drop all local data
            if p.Collector != nil {
                _ = p.Collector.Drop()
            }

            // Clear local-only log if it exists
            dataDir := telemetry.ResolveDataDir(p)
            logFile := filepath.Join(dataDir, "telemetry.log")
            if _, err := os.Stat(logFile); err == nil {
                os.Remove(logFile)
            }

            // 2. Send deletion request via configured requestor
            requestor := buildDeletionRequestor(p)
            ctx, cancel := context.WithTimeout(cmd.Context(), 10*time.Second)
            defer cancel()

            if err := requestor.RequestDeletion(ctx, machineID); err != nil {
                p.Logger.Print("Deletion request could not be sent: " + err.Error())
                if p.Tool.Help.Channel != "" {
                    p.Logger.Print("Contact " + p.Tool.Help.Channel + " to request manual deletion.")
                }
            } else {
                p.Logger.Print("Deletion request sent for machine ID: " + machineID)
            }

            // 3. Disable telemetry
            p.Config.Set("telemetry.enabled", false)
            v := p.Config.GetViper()
            if err := v.WriteConfig(); err != nil {
                if err2 := v.SafeWriteConfig(); err2 != nil {
                    return errors.Wrap(err2, "failed to write config")
                }
            }

            p.Logger.Print("Local telemetry data cleared. Telemetry disabled.")

            return nil
        },
    }
}

// buildDeletionRequestor constructs the appropriate DeletionRequestor.
// Uses the tool-author's custom requestor if configured, otherwise falls back
// to sending a data.deletion_request event through the existing backend.
func buildDeletionRequestor(p *props.Props) telemetry.DeletionRequestor {
    if p.Tool.Telemetry.DeletionRequestor != nil {
        raw := p.Tool.Telemetry.DeletionRequestor(p)
        if r, ok := raw.(telemetry.DeletionRequestor); ok {
            return r
        }
        p.Logger.Warn("TelemetryConfig.DeletionRequestor did not return a telemetry.DeletionRequestor; falling back to event-based")
    }

    // Fall back to event-based deletion request through the existing backend
    // This works with any backend type — HTTP, OTLP, file, etc.
    return telemetry.NewEventDeletionRequestor(/* backend from collector */)
}