beads/cmd/bd/output.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

134 lines
3.7 KiB
Go

package main
import (
"encoding/json"
"fmt"
"os"
"reflect"
"github.com/steveyegge/beads/internal/ui"
)
// JSONSchemaVersion is the current version of the bd JSON output schema.
// Consumers can check this field to detect format changes. Bump when
// fields are added, renamed, or removed from any --json output.
const JSONSchemaVersion = 1
// jsonEnvelopeEnabled returns true when BD_JSON_ENVELOPE=1 is set,
// opting into the uniform {"schema_version": N, "data": <payload>}
// envelope for all --json output. This will become the default in v2.0.
func jsonEnvelopeEnabled() bool {
return os.Getenv("BD_JSON_ENVELOPE") == "1"
}
// outputJSON outputs data as pretty-printed JSON to stdout.
//
// When BD_JSON_ENVELOPE=1: all output is wrapped uniformly as
// {"schema_version": N, "data": <original>}. The original payload
// is untouched inside .data — no type corruption, no injection.
//
// Legacy mode (default): objects get schema_version injected as a
// top-level field; arrays pass through unchanged.
func outputJSON(v interface{}) {
wrapped := wrapWithSchemaVersion(v)
encoder := json.NewEncoder(os.Stdout)
encoder.SetIndent("", " ")
if err := encoder.Encode(wrapped); err != nil {
FatalError("encoding JSON: %v", err)
}
if !jsonEnvelopeEnabled() {
emitEnvelopeDeprecation()
}
}
// outputJSONRaw outputs data without schema_version wrapping.
// Use for internal/machine-only output that should not be versioned.
func outputJSONRaw(v interface{}) {
encoder := json.NewEncoder(os.Stdout)
encoder.SetIndent("", " ")
if err := encoder.Encode(v); err != nil {
FatalError("encoding JSON: %v", err)
}
}
// wrapWithSchemaVersion wraps output with schema_version metadata.
//
// Envelope mode (BD_JSON_ENVELOPE=1): all output wrapped uniformly as
// {"schema_version": N, "data": <original>}. Type-safe for all payload
// types including map[string]string and slices.
//
// Legacy mode: objects get schema_version injected inline; arrays and
// slices pass through unchanged for backwards compatibility.
func wrapWithSchemaVersion(v interface{}) interface{} {
if jsonEnvelopeEnabled() {
return map[string]interface{}{
"schema_version": JSONSchemaVersion,
"data": v,
}
}
// Legacy mode: inline injection for objects, passthrough for arrays.
if v == nil {
return map[string]interface{}{"schema_version": JSONSchemaVersion}
}
rv := reflect.ValueOf(v)
for rv.Kind() == reflect.Ptr {
rv = rv.Elem()
}
if rv.Kind() == reflect.Slice || rv.Kind() == reflect.Array {
return v
}
data, err := json.Marshal(v)
if err != nil {
return v
}
var m map[string]interface{}
if err := json.Unmarshal(data, &m); err != nil {
return v
}
m["schema_version"] = JSONSchemaVersion
return m
}
var envelopeDeprecationEmitted bool
// emitEnvelopeDeprecation prints a one-time deprecation notice to stderr
// when --json output is used without BD_JSON_ENVELOPE=1.
func emitEnvelopeDeprecation() {
if envelopeDeprecationEmitted || !ui.IsStderrTerminal() {
return
}
envelopeDeprecationEmitted = true
fmt.Fprintf(os.Stderr,
"NOTE: bd --json output format will change in v2.0. "+
"Set BD_JSON_ENVELOPE=1 to opt in early. "+
"See docs/JSON_SCHEMA.md for migration details.\n")
}
// outputJSONError outputs an error as JSON to stderr and exits with code 1.
func outputJSONError(err error, code string) {
var errObj interface{}
base := map[string]interface{}{
"error": err.Error(),
}
if code != "" {
base["code"] = code
}
if jsonEnvelopeEnabled() {
errObj = map[string]interface{}{
"schema_version": JSONSchemaVersion,
"data": base,
}
} else {
base["schema_version"] = JSONSchemaVersion
errObj = base
}
encoder := json.NewEncoder(os.Stderr)
encoder.SetIndent("", " ")
_ = encoder.Encode(errObj)
os.Exit(1)
}