feat: honor DO_NOT_TRACK as a metrics opt-out (#4938)

* feat: Honor DO_NOT_TRACK as a metrics opt-out

Honor the cross-tool DO_NOT_TRACK standard (https://donottrack.sh/) as an
alias for BD_DISABLE_METRICS. The standard defines a single environment
variable that "clearly and unambiguously expresses a user's wish to opt out
of ... usage reporting, anonymous or not" and instructs authors to "disable
all tracking" when DO_NOT_TRACK is set, alongside existing opt-out mechanisms.

* fix(metrics): make DO_NOT_TRACK a disable-only opt-out

Maintainer review of PR #4938 found DO_NOT_TRACK was wired as a
bidirectional alias of BD_DISABLE_METRICS (`return !envTruthyValue(v)`),
so a falsey or empty value (DO_NOT_TRACK=0/false/"") was treated as a
decisive re-enable that overrode a saved `bd metrics off` — inverting
the stated opt-out intent for values the donottrack.sh standard never
asks tools to treat as opt-in.

Make DO_NOT_TRACK disable-only: only a truthy value opts out; a
falsey/empty value falls through to the user's saved preference.
BD_DISABLE_METRICS stays the higher-precedence bidirectional override.
Keep the `bd metrics` status/on/off override notes consistent by
reporting DO_NOT_TRACK as the effective override only when truthy, so a
falsey DO_NOT_TRACK no longer prints a misleading "overrides your saved
config" note.

Document the disable-only semantics in AGENT_INSTRUCTIONS.md and add
regression tests: falsey/empty DO_NOT_TRACK must not re-enable a saved
metrics-off, BD_DISABLE_METRICS still re-enables bidirectionally, and
the override-reporting helper names the effective var with correct
precedence.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Eddie the Engineer <ci@beads.test>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Matthew 2026-07-22 03:35:20 +12:00 • committed by GitHub
commit 5526d670d8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 262 additions and 8 deletions

View file

@ -503,7 +503,12 @@ collected. Events are written under `~/.beads/eventsData` and POSTed to
Metrics are enabled by default (opt-out). The friendliest way to see or change
them is `bd metrics` (`bd metrics on` / `bd metrics off` / `bd metrics example`),
which takes effect on the next command with no restart. `BD_DISABLE_METRICS=1`
still works as a one-off, shell-scoped override.
still works as a one-off, shell-scoped override. The cross-tool
[`DO_NOT_TRACK`](https://donottrack.sh/) standard is honored as a disable-only
opt-out: `DO_NOT_TRACK=1` opts out, while a falsey or empty value
(`DO_NOT_TRACK=0`, `false`, or unset-but-present) falls through to your saved
`bd metrics` preference instead of forcing metrics back on. `BD_DISABLE_METRICS`
is the bidirectional override and takes precedence when both are set.
## Questions?

View file

@ -86,7 +86,7 @@ func metricsTestEnv(home string, extra ...string) []string {
base := bdEnv(home)
out := make([]string, 0, len(base)+len(extra)+1)
for _, e := range base {
if strings.HasPrefix(e, "BD_DISABLE_METRICS=") {
if strings.HasPrefix(e, "BD_DISABLE_METRICS=") || strings.HasPrefix(e, "DO_NOT_TRACK=") {
continue
}
out = append(out, e)

View file

@ -1699,6 +1699,14 @@ func resolveMetricsEnabled() bool {
if v, ok := os.LookupEnv(metrics.EnvDisableMetrics); ok {
return !envTruthyValue(v)
}
// DO_NOT_TRACK is a disable-only alias: a truthy value opts out, but a
// falsey or empty value (DO_NOT_TRACK=0/false/"") must fall through to the
// user's saved preference instead of forcing metrics back on over a saved
// `bd metrics off`. Only BD_DISABLE_METRICS (checked first) is a
// bidirectional override.
if v, ok := os.LookupEnv(metrics.EnvDoNotTrack); ok && envTruthyValue(v) {
return false
}
// Consent is the user's own global choice: resolve it from the user-global
// config only, never merged project/BEADS_DIR config. Otherwise a
// repository's .beads/config.yaml (highest viper precedence) could re-enable

View file

@ -137,11 +137,27 @@ func metricsEnabledByConfig() bool {
return !config.MetricsDisabledByUserConfig()
}
// warnIfMetricsEnvOverride tells the user when BD_DISABLE_METRICS is set and
// would override the config they just changed, so the toggle never silently
// metricsEnvOverride returns the metrics opt-out env var in effect for this
// shell, if any, preferring BD_DISABLE_METRICS over its DO_NOT_TRACK alias.
// BD_DISABLE_METRICS is a bidirectional override, so it counts whenever it is
// set. DO_NOT_TRACK is disable-only: a falsey or empty DO_NOT_TRACK falls
// through to saved config and overrides nothing, so it is reported as an active
// override only when truthy — matching resolveMetricsEnabled.
func metricsEnvOverride() (name, value string, ok bool) {
if v, found := os.LookupEnv(metrics.EnvDisableMetrics); found {
return metrics.EnvDisableMetrics, v, true
}
if v, found := os.LookupEnv(metrics.EnvDoNotTrack); found && envTruthyValue(v) {
return metrics.EnvDoNotTrack, v, true
}
return "", "", false
}
// warnIfMetricsEnvOverride tells the user when an environment override is set
// and would override the config they just changed, so the toggle never silently
// does nothing.
func warnIfMetricsEnvOverride(cmd *cobra.Command, wantDisabled bool) {
v, ok := os.LookupEnv(metrics.EnvDisableMetrics)
name, v, ok := metricsEnvOverride()
if !ok {
return
}
@ -152,7 +168,7 @@ func warnIfMetricsEnvOverride(cmd *cobra.Command, wantDisabled bool) {
fmt.Fprintf(cmd.ErrOrStderr(),
"\nNote: %s=%s is set in your environment and overrides this for the current shell.\n"+
" Your config preference is saved; unset %s to let it take effect.\n",
metrics.EnvDisableMetrics, v, metrics.EnvDisableMetrics)
name, v, name)
}
func runMetricsStatus(cmd *cobra.Command) {
@ -177,11 +193,11 @@ func runMetricsStatus(cmd *cobra.Command) {
}
// Surface the env override if it disagrees with the saved config.
if v, ok := os.LookupEnv(metrics.EnvDisableMetrics); ok {
if name, v, ok := metricsEnvOverride(); ok {
if envTruthyValue(v) == metricsEnabledByConfig() {
fmt.Fprintf(cmd.ErrOrStderr(),
"\nNote: %s=%s is overriding your saved config (which is %q) for this shell.\n",
metrics.EnvDisableMetrics, v, map[bool]string{true: "on", false: "off"}[metricsEnabledByConfig()])
name, v, map[bool]string{true: "on", false: "off"}[metricsEnabledByConfig()])
}
}
}

View file

@ -10,6 +10,7 @@ import (
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/config"
"github.com/steveyegge/beads/internal/metrics"
)
// TestMetricsOnOffWritesUserConfig verifies `bd metrics on/off` persists the
@ -282,3 +283,226 @@ func TestFirstRunNoticeSuppressedByContext(t *testing.T) {
}
})
}
// TestResolveMetricsEnabledHonorsDoNotTrack verifies the cross-tool DO_NOT_TRACK
// standard (https://donottrack.sh/) is honored as a disable-only opt-out: a
// truthy DO_NOT_TRACK opts out, a falsey or empty DO_NOT_TRACK falls through to
// the (here default-enabled) config rather than force-enabling, and
// BD_DISABLE_METRICS takes precedence when both are set. The guard that a falsey
// DO_NOT_TRACK must not re-enable a saved `bd metrics off` lives in
// TestResolveMetricsDoNotTrackIsDisableOnly.
func TestResolveMetricsEnabledHonorsDoNotTrack(t *testing.T) {
home := t.TempDir()
t.Setenv("HOME", home)
t.Setenv("USERPROFILE", home)
t.Setenv("XDG_CONFIG_HOME", filepath.Join(home, ".config"))
t.Setenv("BEADS_TEST_IGNORE_REPO_CONFIG", "1")
for _, key := range []string{metrics.EnvDisableMetrics, metrics.EnvDoNotTrack} {
if orig, ok := os.LookupEnv(key); ok {
_ = os.Unsetenv(key)
t.Cleanup(func() { _ = os.Setenv(key, orig) })
}
}
config.ResetForTesting()
t.Cleanup(config.ResetForTesting)
if err := config.Initialize(); err != nil {
t.Fatalf("config.Initialize: %v", err)
}
if !metricsEnabledByConfig() {
t.Fatalf("precondition: metrics should be enabled by default config")
}
cases := []struct {
name string
disableEnv *string
doNotTrack *string
wantEnabled bool
}{
{name: "no env uses config default", wantEnabled: true},
{name: "DO_NOT_TRACK=1 disables", doNotTrack: strPtr("1"), wantEnabled: false},
{name: "DO_NOT_TRACK=true disables", doNotTrack: strPtr("true"), wantEnabled: false},
{name: "DO_NOT_TRACK=0 falls through to config (enabled here)", doNotTrack: strPtr("0"), wantEnabled: true},
{name: "DO_NOT_TRACK empty falls through to config (enabled here)", doNotTrack: strPtr(""), wantEnabled: true},
{name: "BD_DISABLE_METRICS=0 wins over DO_NOT_TRACK=1", disableEnv: strPtr("0"), doNotTrack: strPtr("1"), wantEnabled: true},
{name: "BD_DISABLE_METRICS=1 wins over DO_NOT_TRACK=0", disableEnv: strPtr("1"), doNotTrack: strPtr("0"), wantEnabled: false},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
if tc.disableEnv != nil {
t.Setenv(metrics.EnvDisableMetrics, *tc.disableEnv)
}
if tc.doNotTrack != nil {
t.Setenv(metrics.EnvDoNotTrack, *tc.doNotTrack)
}
if got := resolveMetricsEnabled(); got != tc.wantEnabled {
t.Errorf("resolveMetricsEnabled() = %v, want %v", got, tc.wantEnabled)
}
})
}
}
// TestResolveMetricsDoNotTrackIsDisableOnly is the regression guard for the
// PR #4938 review finding that a falsey DO_NOT_TRACK could re-enable telemetry
// over an explicit opt-out. With a saved `bd metrics off`, DO_NOT_TRACK=0,
// false, or empty must fall through to that saved-off preference and never turn
// metrics back on. BD_DISABLE_METRICS stays a bidirectional override that can
// re-enable.
func TestResolveMetricsDoNotTrackIsDisableOnly(t *testing.T) {
home := t.TempDir()
t.Setenv("HOME", home)
t.Setenv("USERPROFILE", home)
t.Setenv("XDG_CONFIG_HOME", filepath.Join(home, ".config"))
t.Setenv("BEADS_TEST_IGNORE_REPO_CONFIG", "1")
for _, key := range []string{metrics.EnvDisableMetrics, metrics.EnvDoNotTrack} {
if orig, ok := os.LookupEnv(key); ok {
_ = os.Unsetenv(key)
t.Cleanup(func() { _ = os.Setenv(key, orig) })
}
}
// Persist `bd metrics off` to the user-global config before initializing.
userCfgDir := filepath.Join(home, ".config", "bd")
if err := os.MkdirAll(userCfgDir, 0o755); err != nil {
t.Fatalf("mkdir user config dir: %v", err)
}
if err := os.WriteFile(filepath.Join(userCfgDir, "config.yaml"),
[]byte("metrics:\n disabled: true\n"), 0o600); err != nil {
t.Fatalf("write user config: %v", err)
}
config.ResetForTesting()
t.Cleanup(config.ResetForTesting)
if err := config.Initialize(); err != nil {
t.Fatalf("config.Initialize: %v", err)
}
if metricsEnabledByConfig() {
t.Fatalf("precondition: saved config should be metrics-off")
}
cases := []struct {
name string
disableEnv *string
doNotTrack *string
wantEnabled bool
}{
{name: "saved-off, no env stays off", wantEnabled: false},
{name: "DO_NOT_TRACK=0 does not re-enable saved-off", doNotTrack: strPtr("0"), wantEnabled: false},
{name: "DO_NOT_TRACK=false does not re-enable saved-off", doNotTrack: strPtr("false"), wantEnabled: false},
{name: "DO_NOT_TRACK empty does not re-enable saved-off", doNotTrack: strPtr(""), wantEnabled: false},
{name: "DO_NOT_TRACK=1 keeps saved-off disabled", doNotTrack: strPtr("1"), wantEnabled: false},
{name: "BD_DISABLE_METRICS=0 re-enables saved-off (bidirectional)", disableEnv: strPtr("0"), wantEnabled: true},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
if tc.disableEnv != nil {
t.Setenv(metrics.EnvDisableMetrics, *tc.disableEnv)
}
if tc.doNotTrack != nil {
t.Setenv(metrics.EnvDoNotTrack, *tc.doNotTrack)
}
if got := resolveMetricsEnabled(); got != tc.wantEnabled {
t.Errorf("resolveMetricsEnabled() = %v, want %v", got, tc.wantEnabled)
}
})
}
}
// TestMetricsEnvOverrideReporting locks the env-override reporting contract that
// backs the `bd metrics` status/on/off notes: BD_DISABLE_METRICS is preferred
// when both are set, a truthy DO_NOT_TRACK is named as the effective override,
// and a disable-only falsey DO_NOT_TRACK is not reported as an override at all
// (it overrides nothing, so a note would be misleading).
func TestMetricsEnvOverrideReporting(t *testing.T) {
for _, key := range []string{metrics.EnvDisableMetrics, metrics.EnvDoNotTrack} {
if orig, ok := os.LookupEnv(key); ok {
_ = os.Unsetenv(key)
t.Cleanup(func() { _ = os.Setenv(key, orig) })
}
}
cases := []struct {
name string
disableEnv *string
doNotTrack *string
wantName string // "" means no override should be reported
}{
{name: "no env reports nothing", wantName: ""},
{name: "DO_NOT_TRACK=1 is reported", doNotTrack: strPtr("1"), wantName: metrics.EnvDoNotTrack},
{name: "DO_NOT_TRACK=0 is not reported", doNotTrack: strPtr("0"), wantName: ""},
{name: "DO_NOT_TRACK empty is not reported", doNotTrack: strPtr(""), wantName: ""},
{name: "BD_DISABLE_METRICS preferred over DO_NOT_TRACK", disableEnv: strPtr("1"), doNotTrack: strPtr("1"), wantName: metrics.EnvDisableMetrics},
{name: "BD_DISABLE_METRICS=0 is reported (bidirectional)", disableEnv: strPtr("0"), wantName: metrics.EnvDisableMetrics},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
if tc.disableEnv != nil {
t.Setenv(metrics.EnvDisableMetrics, *tc.disableEnv)
}
if tc.doNotTrack != nil {
t.Setenv(metrics.EnvDoNotTrack, *tc.doNotTrack)
}
name, _, ok := metricsEnvOverride()
if tc.wantName == "" {
if ok {
t.Errorf("metricsEnvOverride() reported %q, want no override", name)
}
return
}
if !ok || name != tc.wantName {
t.Errorf("metricsEnvOverride() = (%q, ok=%v), want name %q", name, ok, tc.wantName)
}
})
}
}
// TestWarnIfMetricsEnvOverrideNamesActiveVar verifies the toggle warning names
// the actually-effective override variable dynamically (regression guard for the
// helper refactor that replaced a hard-coded BD_DISABLE_METRICS string), and
// that a disable-only falsey DO_NOT_TRACK produces no warning.
func TestWarnIfMetricsEnvOverrideNamesActiveVar(t *testing.T) {
for _, key := range []string{metrics.EnvDisableMetrics, metrics.EnvDoNotTrack} {
if orig, ok := os.LookupEnv(key); ok {
_ = os.Unsetenv(key)
t.Cleanup(func() { _ = os.Setenv(key, orig) })
}
}
// The user is turning metrics on, so a truthy disable env disagrees and warns.
warn := func() string {
var buf bytes.Buffer
cmd := &cobra.Command{}
cmd.SetOut(&buf)
cmd.SetErr(&buf)
warnIfMetricsEnvOverride(cmd, false)
return buf.String()
}
t.Run("names DO_NOT_TRACK when it is the override", func(t *testing.T) {
t.Setenv(metrics.EnvDoNotTrack, "1")
got := warn()
if !strings.Contains(got, "DO_NOT_TRACK") {
t.Errorf("warning = %q, want it to name DO_NOT_TRACK", got)
}
if strings.Contains(got, "BD_DISABLE_METRICS") {
t.Errorf("warning = %q, should not name BD_DISABLE_METRICS when only DO_NOT_TRACK is set", got)
}
})
t.Run("prefers BD_DISABLE_METRICS when both set", func(t *testing.T) {
t.Setenv(metrics.EnvDisableMetrics, "1")
t.Setenv(metrics.EnvDoNotTrack, "1")
if got := warn(); !strings.Contains(got, "BD_DISABLE_METRICS") {
t.Errorf("warning = %q, want it to name BD_DISABLE_METRICS", got)
}
})
t.Run("falsey DO_NOT_TRACK does not warn", func(t *testing.T) {
t.Setenv(metrics.EnvDoNotTrack, "0")
if got := warn(); got != "" {
t.Errorf("warning = %q, want no warning for disable-only falsey DO_NOT_TRACK", got)
}
})
}

View file

@ -16,6 +16,7 @@ const (
EnvDisableMetrics = "BD_DISABLE_METRICS"
EnvDisableEventFlush = "BD_DISABLE_EVENT_FLUSH"
EnvDoNotTrack = "DO_NOT_TRACK"
DefaultEndpoint = "https://gastownhall-eventsapi.com/mp/collect"
)