beads/internal/ui/terminal.go
Kevin Glynn 8518e71d66
feat: BD_JSON_ENVELOPE=1 opt-in for uniform JSON wrapping (#3393)
* feat: add BD_JSON_ENVELOPE=1 opt-in for uniform JSON wrapping

Follow-up to #3368 as discussed with @maphew. Adds the envelope format
that wraps all --json output as {"schema_version": N, "data": <payload>},
gated behind BD_JSON_ENVELOPE=1 to avoid breaking existing consumers.

Legacy mode (default): unchanged behavior from #3368 — objects get
schema_version injected inline, arrays pass through raw.

Envelope mode (BD_JSON_ENVELOPE=1): uniform wrapping for all types.
The original payload is untouched inside .data — no type corruption,
no field injection. A one-time deprecation notice is emitted to stderr
when --json is used without the env var.

Timeline: envelope becomes default in v2.0, with BD_JSON_ENVELOPE=0
as a temporary escape hatch for one release cycle.

Includes:
- wrapWithSchemaVersion dual-mode logic
- outputJSONError and buildJSONError envelope support
- Deprecation notice on stderr (once per process)
- Tests for both legacy and envelope modes
- Migration guide in docs/JSON_SCHEMA.md

* fix: suppress deprecation notice when stderr is not a TTY

Gate emitEnvelopeDeprecation() on ui.IsStderrTerminal() so the
"NOTE: bd --json output format will change in v2.0" message only
appears in interactive terminals. Test harnesses and pipelines
capture stderr via CombinedOutput(), and the trailing notice after
the JSON closing brace caused json.Unmarshal to fail with
"invalid character 'N' after top-level value" in 15 CI tests.

Follows the same TTY-gating pattern used by ShouldUseColor and
ShouldUseEmoji.

* fix: suppress gosec G304 false positive in hookWorkTreeRoot

The path is filepath.Join(os.Getenv("GIT_DIR"), "gitdir") — reading a
well-known git internal file from a trusted environment variable set by
git itself during hook execution. Not a user-controlled file inclusion.

This false positive causes the Lint CI check to fail on every PR in
the repo, masking real lint issues.
2026-04-21 13:24:17 -07:00

67 lines
1.9 KiB
Go

// Package ui provides terminal styling and output helpers for beads CLI.
package ui
import (
"os"
"golang.org/x/term"
)
// IsTerminal returns true if stdout is connected to a terminal (TTY).
func IsTerminal() bool {
return term.IsTerminal(int(os.Stdout.Fd()))
}
// IsStderrTerminal returns true if stderr is connected to a terminal (TTY).
// Used to suppress advisory messages (e.g. deprecation notices) when stderr
// is captured by test harnesses or piped to another process.
func IsStderrTerminal() bool {
return term.IsTerminal(int(os.Stderr.Fd()))
}
// ShouldUseColor determines if ANSI color codes should be used.
// Respects standard conventions:
// - BD_GIT_HOOK=1: disables color in git hook context (prevents OSC 11 queries, GH#1303)
// - NO_COLOR: https://no-color.org/ - disables color if set
// - CLICOLOR=0: disables color
// - CLICOLOR_FORCE: forces color even in non-TTY
// - Falls back to TTY detection
func ShouldUseColor() bool {
// Git hook context - disable color to prevent termenv OSC 11 terminal
// background queries that leak escape sequences to the terminal (GH#1303).
// Set by bd hook shim templates before calling 'bd hooks run'.
if os.Getenv("BD_GIT_HOOK") == "1" {
return false
}
// NO_COLOR standard - any value disables color
if os.Getenv("NO_COLOR") != "" {
return false
}
// CLICOLOR=0 disables color
if os.Getenv("CLICOLOR") == "0" {
return false
}
// CLICOLOR_FORCE forces color even in non-TTY
if os.Getenv("CLICOLOR_FORCE") != "" {
return true
}
// Default: use color only if stdout is a TTY
return IsTerminal()
}
// ShouldUseEmoji determines if emoji decorations should be used.
// Disabled in non-TTY mode to keep output machine-readable.
// Can be controlled with BD_NO_EMOJI environment variable.
func ShouldUseEmoji() bool {
// Explicit disable
if os.Getenv("BD_NO_EMOJI") != "" {
return false
}
// Default: use emoji only if stdout is a TTY
return IsTerminal()
}