* feat: add schema_version to all --json output (beads-5uh)
All bd commands that emit --json output now include a schema_version
field so consumers (Jawnt MCP, BeadsX, gt mail, sync scripts) can
detect format changes without silently breaking.
- Object output: schema_version injected as top-level field
- Array output: wrapped as {"schema_version": 1, "items": [...]}
- Error output: schema_version added to stderr JSON
Central implementation in outputJSON() via wrapWithSchemaVersion()
means all 272 call sites get the field automatically.
Includes:
- Unit tests for wrapping logic (object, struct, slice, nil, roundtrip)
- Updated protocol contract tests for new envelope format
- New schema_version presence test across list/ready/show
- docs/JSON_SCHEMA.md documenting the field contract per command
* feat: add ready/blocked JSON contract tests (beads-clt)
bd ready --json and bd blocked --json already return full issue objects
with dependency counts and blocked_by fields. Add protocol contract
tests to pin this behavior:
- TestJSONContract_ReadyOutputHasFullObjects: verifies dependency_count,
dependent_count fields on ready items
- TestJSONContract_BlockedOutputHasBlockedBy: verifies blocked_by and
blocked_by_count fields on blocked items
Update docs/JSON_SCHEMA.md with blocked output contract.
* feat: add bd ping lightweight health-check command (beads-8cc)
New minimal command that confirms bd can reach its database:
1. Resolves the .beads workspace
2. Opens the store (embedded or server)
3. Runs a trivial query (SearchIssues with Limit=1)
4. Reports timing breakdown
Supports --json for structured output with resolve_ms, store_ms,
query_ms, and total_ms fields. Exit 0 on success, 1 on failure.
Registered as read-only command (no auto-push, no file writes).
Includes protocol contract test for JSON output.
* feat: structured JSON errors on stderr when --json active (beads-06n)
All fatal error functions (FatalError, FatalErrorWithHint,
FatalErrorRespectJSON, FatalErrorWithHintRespectJSON) now emit
structured JSON with schema_version when --json is active:
{"schema_version": 1, "error": "message", "hint": "optional"}
Centralized via jsonStderrError() and jsonStdoutError() helpers.
Replaces ad-hoc json.MarshalIndent calls scattered across error
functions with a consistent, schema-versioned format.
Includes unit tests and updated protocol contract test verifying
schema_version presence in error JSON output.
* feat: enhance bd import with stdin, --dedup, --json (beads-c6i)
Enhance the existing bd import command for bulk JSONL ingest:
- Stdin support: bd import - reads JSONL from stdin for piped workflows
- --dedup flag: skips lines whose title matches an existing open issue
(case-insensitive) to prevent duplicate creation
- --json flag: structured output with created/skipped counts and IDs
Refactored import to use runImportFromReader() for unified file/stdin
handling. Added filterDuplicatesByTitle() for dedup logic. Updated
docs/JSON_SCHEMA.md with import output contract.
Backward compatible: existing bd import [file] and --dry-run work
exactly as before.
* fix: update tests for schema_version envelope in JSON output
Three test files expected raw JSON arrays or map[string]string, which
broke when schema_version (a number) was added to the output envelope:
- ado_test.go: parse envelope with items array instead of raw []json.RawMessage
- bootstrap_embedded_test.go: use map[string]interface{} for mixed types
- where_embedded_test.go: same map[string]interface{} fix
* fix: drop array envelope wrapping to fix 200+ test failures
The schema_version envelope was wrapping arrays as
{"schema_version": N, "items": [...]} which broke every integration
test that parses --json array output. Objects (show, create, ping)
still get schema_version injected. Arrays (list, ready, blocked)
now pass through unchanged for backwards compatibility.
Also fixes: gofmt on import.go, doc-flags reference to bd import,
uses importIssuesCore result to satisfy unparam lint.
* fix: update remaining tests for schema_version number field
config_embedded_test.go, kv_embedded_test.go, config_nodb_embedded_test.go,
and show_test.go all parsed JSON output into map[string]string but
schema_version is a number. Parse to map[string]interface{} and
skip/assert schema_version appropriately.
---------
Co-authored-by: kev <kglynn@pryoninc.com>
238 lines
7.2 KiB
Go
238 lines
7.2 KiB
Go
// json_contract_test.go — CI regression tests for --json output contracts.
|
|
//
|
|
// These tests verify that commands with --json always produce valid JSON
|
|
// and include required fields. Regressions like GH#2492, GH#2465, GH#2407,
|
|
// GH#2395 are prevented by these tests.
|
|
package protocol
|
|
|
|
import (
|
|
"encoding/json"
|
|
"strings"
|
|
"testing"
|
|
)
|
|
|
|
// TestJSONContract_ListOutputIsValidJSON verifies bd list --json always
|
|
// produces valid JSON (not mixed with tree-renderer text).
|
|
func TestJSONContract_ListOutputIsValidJSON(t *testing.T) {
|
|
t.Parallel()
|
|
w := newWorkspace(t)
|
|
w.create("JSON contract test issue")
|
|
|
|
out := w.run("list", "--json")
|
|
items := parseJSONOutput(t, out)
|
|
if len(items) == 0 {
|
|
t.Fatal("bd list --json returned no items")
|
|
}
|
|
}
|
|
|
|
// TestJSONContract_ShowOutputHasRequiredFields verifies bd show --json
|
|
// includes all required issue fields.
|
|
func TestJSONContract_ShowOutputHasRequiredFields(t *testing.T) {
|
|
t.Parallel()
|
|
w := newWorkspace(t)
|
|
id := w.create("Required fields test")
|
|
|
|
out := w.run("show", id, "--json")
|
|
items := parseJSONOutput(t, out)
|
|
if len(items) == 0 {
|
|
t.Fatal("bd show --json returned no items")
|
|
}
|
|
|
|
issue := items[0]
|
|
requiredFields := []string{"id", "title", "status", "priority", "issue_type", "created_at", "schema_version"}
|
|
for _, field := range requiredFields {
|
|
if _, ok := issue[field]; !ok {
|
|
t.Errorf("bd show --json missing required field %q", field)
|
|
}
|
|
}
|
|
}
|
|
|
|
// TestJSONContract_ReadyOutputIsValidJSON verifies bd ready --json produces
|
|
// valid JSON even when no issues are ready.
|
|
func TestJSONContract_ReadyOutputIsValidJSON(t *testing.T) {
|
|
t.Parallel()
|
|
w := newWorkspace(t)
|
|
|
|
out := w.run("ready", "--json")
|
|
var arr []map[string]any
|
|
if err := json.Unmarshal([]byte(out), &arr); err != nil {
|
|
t.Fatalf("bd ready --json produced invalid JSON: %v\nOutput:\n%s", err, out)
|
|
}
|
|
}
|
|
|
|
// TestJSONContract_CreateOutputHasID verifies bd create --json returns
|
|
// the created issue with its ID.
|
|
func TestJSONContract_CreateOutputHasID(t *testing.T) {
|
|
t.Parallel()
|
|
w := newWorkspace(t)
|
|
|
|
out := w.run("create", "Create contract test", "--description=test", "--json")
|
|
|
|
var issue map[string]any
|
|
if err := json.Unmarshal([]byte(out), &issue); err != nil {
|
|
t.Fatalf("bd create --json produced invalid JSON: %v\nOutput:\n%s", err, out)
|
|
}
|
|
|
|
assertSchemaVersion(t, issue, "bd create --json")
|
|
if _, ok := issue["id"]; !ok {
|
|
t.Error("bd create --json output missing 'id' field")
|
|
}
|
|
}
|
|
|
|
// TestJSONContract_ErrorOutputIsValidJSON verifies that errors with --json
|
|
// produce valid JSON with schema_version to stderr (not mixed text).
|
|
func TestJSONContract_ErrorOutputIsValidJSON(t *testing.T) {
|
|
t.Parallel()
|
|
w := newWorkspace(t)
|
|
|
|
// Try to show a nonexistent issue with --json
|
|
out, _ := w.runExpectError("show", "nonexistent-xyz-999", "--json")
|
|
|
|
// The output (stderr) should be valid JSON or empty
|
|
trimmed := strings.TrimSpace(out)
|
|
if trimmed == "" {
|
|
return // Empty is acceptable for errors
|
|
}
|
|
|
|
// Try to parse as JSON object
|
|
var errObj map[string]any
|
|
if err := json.Unmarshal([]byte(trimmed), &errObj); err != nil {
|
|
// Try each line — error JSON may be mixed with other stderr output
|
|
for _, line := range strings.Split(trimmed, "\n") {
|
|
line = strings.TrimSpace(line)
|
|
if line == "" {
|
|
continue
|
|
}
|
|
var lineObj map[string]any
|
|
if json.Unmarshal([]byte(line), &lineObj) == nil {
|
|
if _, hasError := lineObj["error"]; hasError {
|
|
assertSchemaVersion(t, lineObj, "bd error JSON line")
|
|
return
|
|
}
|
|
}
|
|
}
|
|
t.Logf("Note: error output not fully JSON — this is acceptable for some error paths")
|
|
} else {
|
|
if _, hasError := errObj["error"]; hasError {
|
|
assertSchemaVersion(t, errObj, "bd show error --json")
|
|
}
|
|
}
|
|
}
|
|
|
|
// TestJSONContract_CloseOutputHasStatus verifies bd close --json returns
|
|
// the updated issue with closed status.
|
|
func TestJSONContract_CloseOutputHasStatus(t *testing.T) {
|
|
t.Parallel()
|
|
w := newWorkspace(t)
|
|
id := w.create("Close contract test")
|
|
|
|
out := w.run("close", id, "--json")
|
|
items := parseJSONOutput(t, out)
|
|
if len(items) == 0 {
|
|
t.Fatal("bd close --json returned no items")
|
|
}
|
|
|
|
assertField(t, items[0], "status", "closed")
|
|
}
|
|
|
|
// TestJSONContract_ReadyOutputHasFullObjects verifies bd ready --json returns
|
|
// full issue objects with dependency counts, not just IDs (beads-clt).
|
|
func TestJSONContract_ReadyOutputHasFullObjects(t *testing.T) {
|
|
t.Parallel()
|
|
w := newWorkspace(t)
|
|
w.create("Ready full object test")
|
|
|
|
out := w.run("ready", "--json")
|
|
items := parseJSONOutput(t, out)
|
|
if len(items) == 0 {
|
|
t.Skip("no ready issues — create returned non-ready issue")
|
|
}
|
|
issue := items[0]
|
|
requiredFields := []string{"id", "title", "status", "priority", "dependency_count", "dependent_count"}
|
|
for _, field := range requiredFields {
|
|
if _, ok := issue[field]; !ok {
|
|
t.Errorf("bd ready --json item missing required field %q", field)
|
|
}
|
|
}
|
|
}
|
|
|
|
// TestJSONContract_BlockedOutputHasBlockedBy verifies bd blocked --json returns
|
|
// full issue objects with blocked_by field (beads-clt).
|
|
func TestJSONContract_BlockedOutputHasBlockedBy(t *testing.T) {
|
|
t.Parallel()
|
|
w := newWorkspace(t)
|
|
|
|
blocker := w.create("Blocker issue")
|
|
blocked := w.create("Blocked issue")
|
|
w.run("dep", "add", blocked, blocker, "--type", "blocks")
|
|
|
|
out := w.run("blocked", "--json")
|
|
items := parseJSONOutput(t, out)
|
|
|
|
var found map[string]any
|
|
for _, item := range items {
|
|
if id, ok := item["id"].(string); ok && id == blocked {
|
|
found = item
|
|
break
|
|
}
|
|
}
|
|
if found == nil {
|
|
t.Fatalf("blocked issue %s not found in bd blocked --json output", blocked)
|
|
}
|
|
|
|
requiredFields := []string{"id", "title", "status", "blocked_by_count", "blocked_by"}
|
|
for _, field := range requiredFields {
|
|
if _, ok := found[field]; !ok {
|
|
t.Errorf("bd blocked --json item missing required field %q", field)
|
|
}
|
|
}
|
|
}
|
|
|
|
// TestJSONContract_PingOutputIsValidJSON verifies bd ping --json returns
|
|
// structured health check output with timing info.
|
|
func TestJSONContract_PingOutputIsValidJSON(t *testing.T) {
|
|
t.Parallel()
|
|
w := newWorkspace(t)
|
|
|
|
out := w.run("ping", "--json")
|
|
var obj map[string]any
|
|
if err := json.Unmarshal([]byte(out), &obj); err != nil {
|
|
t.Fatalf("bd ping --json produced invalid JSON: %v\nOutput:\n%s", err, out)
|
|
}
|
|
assertSchemaVersion(t, obj, "bd ping --json")
|
|
if status, ok := obj["status"].(string); !ok || status != "ok" {
|
|
t.Errorf("bd ping --json status = %v, want ok", obj["status"])
|
|
}
|
|
if _, ok := obj["total_ms"]; !ok {
|
|
t.Error("bd ping --json missing total_ms field")
|
|
}
|
|
}
|
|
|
|
// TestJSONContract_SchemaVersionPresent verifies that schema_version is
|
|
// present in object-returning --json commands (show, create, ping).
|
|
// Array-returning commands (list, ready) do not include schema_version.
|
|
func TestJSONContract_SchemaVersionPresent(t *testing.T) {
|
|
t.Parallel()
|
|
w := newWorkspace(t)
|
|
id := w.create("Schema version test")
|
|
|
|
tests := []struct {
|
|
name string
|
|
args []string
|
|
}{
|
|
{"show", []string{"show", id, "--json"}},
|
|
{"ping", []string{"ping", "--json"}},
|
|
}
|
|
|
|
for _, tt := range tests {
|
|
t.Run(tt.name, func(t *testing.T) {
|
|
out := w.run(tt.args...)
|
|
var obj map[string]any
|
|
if err := json.Unmarshal([]byte(out), &obj); err != nil {
|
|
t.Fatalf("bd %s produced invalid JSON: %v\nOutput:\n%s",
|
|
tt.name, err, out)
|
|
}
|
|
assertSchemaVersion(t, obj, "bd "+tt.name+" --json")
|
|
})
|
|
}
|
|
}
|