* 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>
135 lines
3.2 KiB
Go
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}
|
|
}
|