feat(telemetry): opt-in scaffold, default OFF (spec 20)

go.mod

@@ -20,6 +20,7 @@ require (
 	github.com/go-playground/validator/v10 v10.30.3
 	github.com/goccy/go-yaml v1.19.2
 	github.com/gofrs/flock v0.13.0
+	github.com/google/uuid v1.6.0
 	github.com/jackc/pgx/v5 v5.10.0
 	github.com/moby/moby/api v1.54.2
 	github.com/moby/moby/client v0.4.1
@@ -75,7 +76,6 @@ require (
 	github.com/go-playground/universal-translator v0.18.1 // indirect
 	github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
 	github.com/godbus/dbus/v5 v5.2.2 // indirect
-	github.com/google/uuid v1.6.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect

internal/cli/root.go

@@ -105,6 +105,7 @@ func NewRootCmd(opts Options) *cobra.Command {
 		newSelfCmd(g),
 		newStoreCmd(g),
 		newAliasCmd(g),
+		newTelemetryCmd(g),
 		newVersionCmd(),
 	)
 	addStubCommands(root, g)

internal/cli/stubs.go

@@ -36,6 +36,5 @@ func addStubCommands(root *cobra.Command, _ *GlobalOpts) {
 		stub("logs", "Stream service logs", "v2 (spec 16)"),
 		stub("dashboard", "Live TUI cockpit", "v2 (spec 16)"),
 		stub("ide", "Generate devcontainer/.code-workspace/launch configs", "v2 (spec 17)"),
-		stub("telemetry", "Opt-in usage telemetry (default OFF)", "a later release (spec 20)"),
 	)
 }

internal/cli/telemetry.go

@@ -0,0 +1,175 @@
+package cli
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"github.com/open-source-cloud/devstack/internal/store"
+	"github.com/open-source-cloud/devstack/internal/telemetry"
+	"github.com/open-source-cloud/devstack/internal/version"
+)
+
+// newTelemetryCmd wires `telemetry status|enable|disable|show` — the opt-in,
+// default-OFF usage-telemetry scaffold (spec 20). Consent is persisted in the
+// global $DEVSTACK_HOME config.yaml (never committed, never in the ledger). This
+// build is SHIP-EMPTY: no real endpoint is wired, so even when enabled the only
+// sink is the no-op sink and nothing leaves the machine.
+func newTelemetryCmd(g *GlobalOpts) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "telemetry",
+		Short: "Opt-in anonymous usage telemetry (default OFF)",
+		Long: "Opt-in anonymous usage telemetry (spec 20).\n\n" +
+			"Telemetry is DEFAULT OFF and strictly opt-in: nothing is collected or sent\n" +
+			"until you run `telemetry enable`. This build is ship-empty — no network\n" +
+			"endpoint is wired, so even when enabled nothing leaves your machine. Only\n" +
+			"coarse, non-identifying counters would ever be sent (see `telemetry show`):\n" +
+			"command name, flag names, ok/error outcome, an error category enum, a\n" +
+			"bucketed duration, os/arch, whether WSL2, the tool version, and a random\n" +
+			"install id. Never paths, repo names, secrets, env values, or error strings.",
+	}
+	cmd.AddCommand(
+		newTelemetryStatusCmd(g),
+		newTelemetryEnableCmd(g),
+		newTelemetryDisableCmd(g),
+		newTelemetryShowCmd(g),
+	)
+	return cmd
+}
+
+func newTelemetryStatusCmd(g *GlobalOpts) *cobra.Command {
+	return &cobra.Command{
+		Use:   "status",
+		Short: "Show whether telemetry is enabled and where it would send",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			consent, err := store.TelemetryConsent()
+			if err != nil {
+				return err
+			}
+			endpoint := telemetry.DefaultEndpoint
+			if g.JSON {
+				return writeJSON(cmd, map[string]any{
+					"enabled":    consent.Enabled,
+					"installId":  consent.InstallID,
+					"consentAt":  consent.ConsentAt,
+					"endpoint":   endpoint,
+					"shipEmpty":  endpoint == "",
+					"configPath": store.ConfigPath(),
+				})
+			}
+			if g.Quiet {
+				return nil
+			}
+			w := cmd.OutOrStdout()
+			state := "disabled"
+			if consent.Enabled {
+				state = "enabled"
+			}
+			fmt.Fprintf(w, "telemetry: %s (default OFF)\n", state)
+			if endpoint == "" {
+				fmt.Fprintf(w, "  endpoint: (none — ship-empty; nothing is ever sent)\n")
+			} else {
+				fmt.Fprintf(w, "  endpoint: %s\n", endpoint)
+			}
+			if consent.InstallID != "" {
+				fmt.Fprintf(w, "  install id: %s\n", consent.InstallID)
+			}
+			fmt.Fprintf(w, "  config: %s\n", store.ConfigPath())
+			fmt.Fprintf(w, "run `%s telemetry show` to see the exact event that would be sent\n", rootName(cmd))
+			return nil
+		},
+	}
+}
+
+func newTelemetryEnableCmd(g *GlobalOpts) *cobra.Command {
+	return &cobra.Command{
+		Use:   "enable",
+		Short: "Opt in to anonymous usage telemetry",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			consent, err := store.SetTelemetry(true)
+			if err != nil {
+				return err
+			}
+			if g.JSON {
+				return writeJSON(cmd, map[string]any{"enabled": true, "installId": consent.InstallID})
+			}
+			if g.Quiet {
+				return nil
+			}
+			w := cmd.OutOrStdout()
+			fmt.Fprintf(w, "telemetry enabled. install id: %s\n", consent.InstallID)
+			if telemetry.DefaultEndpoint == "" {
+				fmt.Fprintf(w, "note: this build is ship-empty — no endpoint is wired, so nothing is actually sent yet.\n")
+			}
+			fmt.Fprintf(w, "disable any time with `%s telemetry disable`.\n", rootName(cmd))
+			return nil
+		},
+	}
+}
+
+func newTelemetryDisableCmd(g *GlobalOpts) *cobra.Command {
+	return &cobra.Command{
+		Use:   "disable",
+		Short: "Opt out of usage telemetry (honored on the next invocation)",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			if _, err := store.SetTelemetry(false); err != nil {
+				return err
+			}
+			if g.JSON {
+				return writeJSON(cmd, map[string]any{"enabled": false})
+			}
+			if g.Quiet {
+				return nil
+			}
+			fmt.Fprintln(cmd.OutOrStdout(), "telemetry disabled.")
+			return nil
+		},
+	}
+}
+
+func newTelemetryShowCmd(g *GlobalOpts) *cobra.Command {
+	return &cobra.Command{
+		Use:   "show",
+		Short: "Print the exact event that would be sent (performs no network I/O)",
+		Long: "Print, byte-for-byte, the exact event devstack would send for a synthetic\n" +
+			"invocation. This is the trust primitive: it performs ZERO network I/O and\n" +
+			"lets you verify nothing sensitive is collected. It is the exhaustive\n" +
+			"allowlist — there is no free-form field that could carry a path or secret.",
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			consent, err := store.TelemetryConsent()
+			if err != nil {
+				return err
+			}
+			// A synthetic sample so `show` works whether or not telemetry is on.
+			sample := telemetry.NewEvent(telemetry.EventInput{
+				Command:     "up",
+				Flags:       []string{"--build"},
+				Err:         nil,
+				Duration:    1840 * time.Millisecond,
+				ToolVersion: version.Version,
+				InstallID:   consent.InstallID,
+			})
+			if g.JSON {
+				return writeJSON(cmd, map[string]any{
+					"enabled":  consent.Enabled,
+					"endpoint": telemetry.DefaultEndpoint,
+					"event":    sample,
+				})
+			}
+			w := cmd.OutOrStdout()
+			endpoint := telemetry.DefaultEndpoint
+			if endpoint == "" {
+				endpoint = "(none — ship-empty; nothing is ever sent)"
+			}
+			fmt.Fprintf(w, "endpoint: %s\n", endpoint)
+			fmt.Fprintf(w, "enabled:  %v\n", consent.Enabled)
+			fmt.Fprintln(w, "the exact event that would be sent (allowlist — no paths/secrets/PII):")
+			return writeJSON(cmd, sample)
+		},
+	}
+}

internal/cli/telemetry_test.go

@@ -0,0 +1,112 @@
+package cli
+
+import (
+	"encoding/json"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestTelemetryRegistered(t *testing.T) {
+	root := NewRootCmd(Options{})
+	// The stub must be gone: telemetry is now a real command group.
+	for _, sub := range []string{"status", "enable", "disable", "show"} {
+		c, _, err := root.Find([]string{"telemetry", sub})
+		if err != nil || c.Name() != sub || c.RunE == nil {
+			t.Errorf("telemetry %s not registered as a real command: %v", sub, err)
+		}
+	}
+}
+
+func TestTelemetryStatusDefaultOff(t *testing.T) {
+	t.Setenv("DEVSTACK_HOME", filepath.Join(t.TempDir(), ".devstack"))
+
+	out, err := runCmd(t, "telemetry", "status", "--json")
+	if err != nil {
+		t.Fatalf("telemetry status: %v\n%s", err, out)
+	}
+	var res struct {
+		Enabled   bool   `json:"enabled"`
+		Endpoint  string `json:"endpoint"`
+		ShipEmpty bool   `json:"shipEmpty"`
+		InstallID string `json:"installId"`
+	}
+	if err := json.Unmarshal([]byte(out), &res); err != nil {
+		t.Fatalf("bad json: %v\n%s", err, out)
+	}
+	if res.Enabled {
+		t.Error("telemetry must report OFF by default")
+	}
+	if res.Endpoint != "" || !res.ShipEmpty {
+		t.Errorf("ship-empty: endpoint=%q shipEmpty=%v", res.Endpoint, res.ShipEmpty)
+	}
+	if res.InstallID != "" {
+		t.Errorf("a disabled install must carry no install id, got %q", res.InstallID)
+	}
+}
+
+func TestTelemetryEnableDisableRoundTripCLI(t *testing.T) {
+	t.Setenv("DEVSTACK_HOME", filepath.Join(t.TempDir(), ".devstack"))
+
+	// enable
+	out, err := runCmd(t, "telemetry", "enable", "--json")
+	if err != nil {
+		t.Fatalf("enable: %v\n%s", err, out)
+	}
+	var en struct {
+		Enabled   bool   `json:"enabled"`
+		InstallID string `json:"installId"`
+	}
+	if err := json.Unmarshal([]byte(out), &en); err != nil {
+		t.Fatalf("bad json: %v\n%s", err, out)
+	}
+	if !en.Enabled || en.InstallID == "" {
+		t.Fatalf("enable json = %+v; want enabled with install id", en)
+	}
+
+	// status reflects it
+	out, _ = runCmd(t, "telemetry", "status", "--json")
+	if !strings.Contains(out, `"enabled": true`) {
+		t.Errorf("status should report enabled after enable:\n%s", out)
+	}
+
+	// disable
+	if out, err := runCmd(t, "telemetry", "disable", "--json"); err != nil {
+		t.Fatalf("disable: %v\n%s", err, out)
+	}
+	out, _ = runCmd(t, "telemetry", "status", "--json")
+	if !strings.Contains(out, `"enabled": false`) {
+		t.Errorf("status should report disabled after disable:\n%s", out)
+	}
+}
+
+// TestTelemetryShowNoPII asserts `telemetry show` prints only allowlisted fields —
+// no path/secret/PII — mirroring the spec-04 no-secret-in-output guardrail.
+func TestTelemetryShowNoPII(t *testing.T) {
+	t.Setenv("DEVSTACK_HOME", filepath.Join(t.TempDir(), ".devstack"))
+
+	out, err := runCmd(t, "telemetry", "show", "--json")
+	if err != nil {
+		t.Fatalf("telemetry show: %v\n%s", err, out)
+	}
+	var res struct {
+		Endpoint string         `json:"endpoint"`
+		Event    map[string]any `json:"event"`
+	}
+	if err := json.Unmarshal([]byte(out), &res); err != nil {
+		t.Fatalf("bad json: %v\n%s", err, out)
+	}
+	if res.Endpoint != "" {
+		t.Errorf("ship-empty show should print an empty endpoint, got %q", res.Endpoint)
+	}
+	allowed := map[string]bool{
+		"command": true, "flags": true, "outcome": true, "error_category": true,
+		"duration_ms": true, "os": true, "arch": true, "is_wsl2": true,
+		"tool_version": true, "install_id": true,
+	}
+	for k := range res.Event {
+		if !allowed[k] {
+			t.Errorf("telemetry show event carried un-allowlisted key %q", k)
+		}
+	}
+}