beads/cmd/bd/output.go
Jacob Hausler cf2e0d9a01
feat(ready): add pagination metadata to BD_JSON_ENVELOPE=1 output when truncated (#4897)
* feat(ready): add pagination metadata to BD_JSON_ENVELOPE=1 output when truncated

bd ready --json with BD_JSON_ENVELOPE=1 now includes a "pagination" key
in the envelope when results are capped by --limit:

  {
    "schema_version": 1,
    "data": [...],
    "pagination": {"returned": 100, "total": 149, "truncated": true}
  }

Without the envelope (default bare-array mode), the existing stderr text
hint ("Showing 100 of 149 ready issues. Use --limit 0 for all...") is
unchanged. The pagination key is absent when results are not truncated,
so callers can check for its presence / the truncated field rather than
comparing returned vs total.

Fixes the silent truncation problem for programmatic consumers (gc,
agents, sweep scripts) that call bd ready --json and consume the JSON
payload from stdout — they cannot read the stderr prose hint, so they
received no signal that the list was capped.

Closes #4892

* fix(ready): emit pagination metadata on the proxied route too

runReadyProxiedServer's JSON branch called the bare outputJSON(results)
even though page.HasMore already carried enough information to detect
truncation, so BD_JSON_ENVELOPE=1 consumers on the proxied path (the
default for non-CGO/proxied builds) had no way to see the pagination
signal that the direct route already exposes. Build a PaginationMeta
with Returned/Truncated from page.HasMore && in.filter.Limit > 0 and
route through outputJSONWithPagination instead; Total is left unset
since this backend's domain page has no cheap total-count equivalent.

Adds proxied-route coverage (pagination_envelope_truncated and
pagination_envelope_not_truncated subtests) exercising the envelope
under BD_JSON_ENVELOPE=1 for both truncated and non-truncated results.

Closes the blocking item from the 2026-07-23 CHANGES_REQUESTED review
on gastownhall/beads#4897.

Agent-Signature: claude-sonnet-5-medium on behalf of maphew

---------

Co-authored-by: Jacob Hausler <jacob@hausler.cc>
Co-authored-by: matt wilkie <maphew@gmail.com>
2026-07-25 22:29:55 -07:00

135 lines
3.2 KiB
Go

package main
import (
"encoding/json"
"fmt"
"os"
"reflect"
"github.com/steveyegge/beads/internal/ui"
)
const JSONSchemaVersion = 1
// PaginationMeta carries truncation context for paginated JSON responses.
// It is included in the BD_JSON_ENVELOPE=1 output under the "pagination" key
// whenever the result set was capped by a --limit.
type PaginationMeta struct {
Returned int `json:"returned"`
Total int `json:"total,omitempty"`
Truncated bool `json:"truncated"`
}
func jsonEnvelopeEnabled() bool {
return os.Getenv("BD_JSON_ENVELOPE") == "1"
}
func outputJSON(v interface{}) error {
return outputJSONWithPagination(v, nil)
}
// outputJSONWithPagination emits v as JSON, optionally including pagination
// metadata. When BD_JSON_ENVELOPE=1 and p is non-nil, the envelope gains a
// "pagination" key so programmatic consumers can detect truncation without
// parsing stderr. When the envelope is not active, p is ignored and the
// existing stderr text hint handles the human/text path.
func outputJSONWithPagination(v interface{}, p *PaginationMeta) error {
var out interface{}
if jsonEnvelopeEnabled() && p != nil {
out = map[string]interface{}{
"schema_version": JSONSchemaVersion,
"data": v,
"pagination": p,
}
} else {
out = wrapWithSchemaVersion(v)
}
encoder := json.NewEncoder(os.Stdout)
encoder.SetIndent("", " ")
if err := encoder.Encode(out); err != nil {
return fmt.Errorf("encoding JSON: %v", err)
}
if !jsonEnvelopeEnabled() {
emitEnvelopeDeprecation()
}
return nil
}
func outputJSONRaw(v interface{}) error {
encoder := json.NewEncoder(os.Stdout)
encoder.SetIndent("", " ")
if err := encoder.Encode(v); err != nil {
return fmt.Errorf("encoding JSON: %v", err)
}
return nil
}
func wrapWithSchemaVersion(v interface{}) interface{} {
if jsonEnvelopeEnabled() {
return map[string]interface{}{
"schema_version": JSONSchemaVersion,
"data": v,
}
}
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
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/reference/json-schema.md for migration details.\n")
}
func outputJSONError(err error, code string) error {
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)
return &exitError{Code: 1}
}