feat: JSON schema contract, bd ping, structured errors, import enhancements (#3368)

* 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>
This commit is contained in:
Kevin Glynn 2026-04-21 00:09:48 -04:00 • committed by GitHub
commit 0d4b979354
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
16 changed files with 826 additions and 146 deletions

View file

@ -68,18 +68,18 @@ func TestBootstrapNoWorkspace(t *testing.T) {
t.Fatalf("expected JSON object in output, got: %s", out)
}
var payload map[string]string
var payload map[string]interface{}
if err := json.Unmarshal([]byte(s[start:]), &payload); err != nil {
t.Fatalf("parse bootstrap JSON: %v\n%s", err, s)
}
if payload["action"] != "none" {
t.Fatalf("action = %q, want %q", payload["action"], "none")
if action, _ := payload["action"].(string); action != "none" {
t.Fatalf("action = %q, want %q", action, "none")
}
if payload["reason"] != activeWorkspaceNotFoundError() {
t.Fatalf("reason = %q, want %q", payload["reason"], activeWorkspaceNotFoundError())
if reason, _ := payload["reason"].(string); reason != activeWorkspaceNotFoundError() {
t.Fatalf("reason = %q, want %q", reason, activeWorkspaceNotFoundError())
}
if !strings.Contains(payload["suggestion"], "bd where") {
t.Fatalf("suggestion should mention bd where, got: %q", payload["suggestion"])
if suggestion, _ := payload["suggestion"].(string); !strings.Contains(suggestion, "bd where") {
t.Fatalf("suggestion should mention bd where, got: %q", suggestion)
}
})
}

View file

@ -55,10 +55,19 @@ func bdConfigListJSON(t *testing.T, bd, dir string) map[string]string {
if start < 0 {
t.Fatalf("no JSON object in config list output: %s", s)
}
var m map[string]string
if err := json.Unmarshal([]byte(s[start:]), &m); err != nil {
var raw map[string]interface{}
if err := json.Unmarshal([]byte(s[start:]), &raw); err != nil {
t.Fatalf("parse config list JSON: %v\n%s", err, s)
}
m := make(map[string]string, len(raw))
for k, v := range raw {
if k == "schema_version" {
continue
}
if sv, ok := v.(string); ok {
m[k] = sv
}
}
return m
}

View file

@ -152,14 +152,14 @@ func TestEmbeddedConfigValidateJSONNoWorkspaceWritesStdout(t *testing.T) {
t.Fatalf("expected JSON error on stdout only, got stderr:\n%s", stderr)
}
var payload map[string]string
var payload map[string]interface{}
if err := json.Unmarshal([]byte(stdout), &payload); err != nil {
t.Fatalf("parse config validate --json output: %v\nstdout:\n%s", err, stdout)
}
if payload["error"] != activeWorkspaceNotFoundError() {
t.Fatalf("error = %q, want %q", payload["error"], activeWorkspaceNotFoundError())
if errField, _ := payload["error"].(string); errField != activeWorkspaceNotFoundError() {
t.Fatalf("error = %q, want %q", errField, activeWorkspaceNotFoundError())
}
if !strings.Contains(payload["hint"], "bd where") {
t.Fatalf("expected hint to mention bd where, got %q", payload["hint"])
if hint, _ := payload["hint"].(string); !strings.Contains(hint, "bd where") {
t.Fatalf("expected hint to mention bd where, got %q", hint)
}
}

View file

@ -38,6 +38,37 @@ func workspaceDiagHint(includeWhere bool) string {
return "check BEADS_DIR/worktree setup, run 'bd doctor' to diagnose, or run 'bd init' to create a new database"
}
// jsonStderrError writes a structured JSON error to stderr when --json is active.
// All JSON errors include schema_version for consumer compatibility.
func jsonStderrError(message, hint string) {
obj := map[string]interface{}{
"schema_version": JSONSchemaVersion,
"error": message,
}
if hint != "" {
obj["hint"] = hint
}
encoder := json.NewEncoder(os.Stderr)
encoder.SetIndent("", " ")
_ = encoder.Encode(obj)
}
// jsonStdoutError writes a structured JSON error to stdout when --json is active.
// Used by FatalErrorRespectJSON and FatalErrorWithHintRespectJSON where
// callers expect errors on stdout (e.g., bd show nonexistent-id --json).
func jsonStdoutError(message, hint string) {
obj := map[string]interface{}{
"schema_version": JSONSchemaVersion,
"error": message,
}
if hint != "" {
obj["hint"] = hint
}
encoder := json.NewEncoder(os.Stdout)
encoder.SetIndent("", " ")
_ = encoder.Encode(obj)
}
// FatalError writes an error message to stderr and exits with code 1.
// Use this for fatal errors that prevent the command from completing.
//
@ -54,8 +85,7 @@ func workspaceDiagHint(includeWhere bool) string {
func FatalError(format string, args ...interface{}) {
msg := fmt.Sprintf(format, args...)
if jsonOutput {
data, _ := json.MarshalIndent(map[string]string{"error": msg}, "", " ")
fmt.Fprintln(os.Stderr, string(data))
jsonStderrError(msg, "")
} else {
fmt.Fprintf(os.Stderr, "Error: %s\n", msg)
}
@ -76,8 +106,7 @@ func FatalError(format string, args ...interface{}) {
func FatalErrorRespectJSON(format string, args ...interface{}) {
msg := fmt.Sprintf(format, args...)
if jsonOutput {
data, _ := json.MarshalIndent(map[string]string{"error": msg}, "", " ") // json.MarshalIndent on simple maps does not fail in practice
fmt.Println(string(data))
jsonStdoutError(msg, "")
} else {
fmt.Fprintf(os.Stderr, "Error: %s\n", msg)
}
@ -88,7 +117,7 @@ func FatalErrorRespectJSON(format string, args ...interface{}) {
// If --json is set, emits structured JSON to stdout so callers can parse it.
func FatalErrorWithHintRespectJSON(message, hint string) {
if jsonOutput {
outputJSON(map[string]string{"error": message, "hint": hint})
jsonStdoutError(message, hint)
} else {
fmt.Fprintf(os.Stderr, "Error: %s\n", message)
fmt.Fprintf(os.Stderr, "Hint: %s\n", hint)
@ -104,8 +133,7 @@ func FatalErrorWithHintRespectJSON(message, hint string) {
// FatalErrorWithHint("database not found", "Run 'bd init' to create a database")
func FatalErrorWithHint(message, hint string) {
if jsonOutput {
data, _ := json.MarshalIndent(map[string]string{"error": message, "hint": hint}, "", " ")
fmt.Fprintln(os.Stderr, string(data))
jsonStderrError(message, hint)
} else {
fmt.Fprintf(os.Stderr, "Error: %s\n", message)
fmt.Fprintf(os.Stderr, "Hint: %s\n", hint)

55
cmd/bd/errors_test.go Normal file
View file

@ -0,0 +1,55 @@
package main
import (
"encoding/json"
"testing"
)
func TestJsonStderrError_StructuredOutput(t *testing.T) {
tests := []struct {
name string
message string
hint string
}{
{"message_only", "database not found", ""},
{"message_with_hint", "database not found", "Run 'bd init' to create one"},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
obj := map[string]interface{}{
"schema_version": JSONSchemaVersion,
"error": tt.message,
}
if tt.hint != "" {
obj["hint"] = tt.hint
}
data, err := json.Marshal(obj)
if err != nil {
t.Fatalf("marshal: %v", err)
}
var parsed map[string]interface{}
if err := json.Unmarshal(data, &parsed); err != nil {
t.Fatalf("unmarshal: %v", err)
}
if parsed["schema_version"] != float64(JSONSchemaVersion) {
t.Errorf("schema_version = %v, want %d", parsed["schema_version"], JSONSchemaVersion)
}
if parsed["error"] != tt.message {
t.Errorf("error = %v, want %s", parsed["error"], tt.message)
}
if tt.hint != "" {
if parsed["hint"] != tt.hint {
t.Errorf("hint = %v, want %s", parsed["hint"], tt.hint)
}
} else {
if _, ok := parsed["hint"]; ok {
t.Errorf("hint should not be present when empty")
}
}
})
}
}

View file

@ -1,56 +1,74 @@
package main
import (
"bufio"
"context"
"encoding/json"
"fmt"
"io"
"os"
"path/filepath"
"strings"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/beads"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/types"
)
var importCmd = &cobra.Command{
Use: "import [file]",
Short: "Import issues from a JSONL file into the database",
Use: "import [file|-]",
Short: "Import issues from a JSONL file or stdin into the database",
Long: `Import issues from a JSONL file (newline-delimited JSON) into the database.
If no file is specified, imports from .beads/issues.jsonl (the git-tracked
export). This is the incremental counterpart to 'bd export': new issues are
created and existing issues are updated (upsert semantics).
export). Use "-" to read from stdin. This is the incremental counterpart to
'bd export': new issues are created and existing issues are updated (upsert
semantics).
Memory records (lines with "_type":"memory") are automatically detected and
imported as persistent memories (equivalent to 'bd remember'). This makes
'bd export | bd import' a full round-trip for both issues and memories.
This command makes the git-tracked JSONL portable again — after 'git pull'
brings new issues, 'bd import' loads them into the local Dolt database.
Each JSONL line should map to an issue with at minimum "title". Optional
fields: description, issue_type (type), priority, acceptance_criteria.
EXAMPLES:
bd import # Import from .beads/issues.jsonl
bd import backup.jsonl # Import from a specific file
bd import --dry-run # Show what would be imported`,
bd import - # Read JSONL from stdin
cat issues.jsonl | bd import - # Pipe JSONL from another tool
bd import --dry-run # Show what would be imported
bd import --dedup # Skip issues with duplicate titles
bd import --json # Structured output with created IDs`,
GroupID: "sync",
RunE: runImport,
}
var (
importDryRun bool
importDedup bool
)
func init() {
importCmd.Flags().BoolVar(&importDryRun, "dry-run", false, "Show what would be imported without importing")
importCmd.Flags().BoolVar(&importDedup, "dedup", false, "Skip lines whose title matches an existing open issue")
rootCmd.AddCommand(importCmd)
}
func runImport(cmd *cobra.Command, args []string) error {
ctx := rootCtx
fromStdin := len(args) > 0 && args[0] == "-"
if fromStdin {
return runImportFromReader(ctx, os.Stdin, "stdin")
}
// Determine source file
var jsonlPath string
if len(args) > 0 {
jsonlPath = args[0]
} else {
// Default: .beads/issues.jsonl (or .beads/global-issues.jsonl with --global)
beadsDir := beads.FindBeadsDir()
if beadsDir == "" {
return fmt.Errorf("%s — %s", activeWorkspaceNotFoundError(), diagHint())
@ -62,44 +80,194 @@ func runImport(cmd *cobra.Command, args []string) error {
}
}
// Check file exists
info, err := os.Stat(jsonlPath)
if err != nil {
return fmt.Errorf("cannot read %s: %w", jsonlPath, err)
}
if info.Size() == 0 {
if jsonOutput {
outputJSON(importResultJSON{Source: jsonlPath})
return nil
}
fmt.Fprintf(os.Stderr, "Empty file: %s\n", jsonlPath)
return nil
}
if importDryRun {
fmt.Fprintf(os.Stderr, "Would import from: %s (%d bytes)\n", jsonlPath, info.Size())
return nil
f, err := os.Open(jsonlPath) //nolint:gosec // G304: CLI argument
if err != nil {
return fmt.Errorf("cannot open %s: %w", jsonlPath, err)
}
defer f.Close()
// store is the global Dolt store, opened by main.go's PersistentPreRunE
return runImportFromReader(ctx, f, jsonlPath)
}
type importResultJSON struct {
Source string `json:"source"`
Created int `json:"created"`
Skipped int `json:"skipped"`
DedupHits int `json:"dedup_skipped,omitempty"`
Memories int `json:"memories,omitempty"`
IDs []string `json:"ids,omitempty"`
DryRun bool `json:"dry_run,omitempty"`
}
func runImportFromReader(ctx context.Context, r io.Reader, source string) error {
if store == nil {
return fmt.Errorf("no database — run 'bd init' or 'bd bootstrap' first")
}
result, err := importFromLocalJSONLFull(ctx, store, jsonlPath)
if err != nil {
return fmt.Errorf("import failed: %w", err)
scanner := bufio.NewScanner(r)
scanner.Buffer(make([]byte, 0, 1024*1024), 64*1024*1024)
var issues []*types.Issue
var memories []memoryRecord
for scanner.Scan() {
line := scanner.Text()
if line == "" {
continue
}
var peek map[string]json.RawMessage
if err := json.Unmarshal([]byte(line), &peek); err != nil {
return fmt.Errorf("failed to parse JSONL line: %w", err)
}
if rawType, ok := peek["_type"]; ok {
var typeStr string
if err := json.Unmarshal(rawType, &typeStr); err == nil && typeStr == "memory" {
var mem memoryRecord
if err := json.Unmarshal([]byte(line), &mem); err != nil {
return fmt.Errorf("failed to parse memory record: %w", err)
}
if mem.Key != "" && mem.Value != "" {
memories = append(memories, mem)
}
continue
}
}
var issue types.Issue
if err := json.Unmarshal([]byte(line), &issue); err != nil {
return fmt.Errorf("failed to parse issue from JSONL: %w", err)
}
if issue.Status == "tombstone" {
continue
}
if _, hasWisp := peek["wisp"]; hasWisp && !issue.Ephemeral {
var wisp bool
if err := json.Unmarshal(peek["wisp"], &wisp); err == nil && wisp {
issue.Ephemeral = true
}
}
issue.SetDefaults()
issues = append(issues, &issue)
}
if err := scanner.Err(); err != nil {
return fmt.Errorf("failed to scan JSONL: %w", err)
}
commitMsg := fmt.Sprintf("bd import: %d issues", result.Issues)
// Dedup: skip issues whose title matches an existing open issue
dedupHits := 0
if importDedup && len(issues) > 0 {
issues, dedupHits = filterDuplicatesByTitle(ctx, store, issues)
}
result := importResultJSON{
Source: source,
DedupHits: dedupHits,
DryRun: importDryRun,
}
if importDryRun {
result.Created = len(issues)
result.Memories = len(memories)
result.Skipped = dedupHits
if jsonOutput {
outputJSON(result)
return nil
}
fmt.Fprintf(os.Stderr, "Would import %d issues and %d memories from %s", len(issues), len(memories), source)
if dedupHits > 0 {
fmt.Fprintf(os.Stderr, " (%d duplicates skipped)", dedupHits)
}
fmt.Fprintln(os.Stderr)
return nil
}
// Import memories
for _, mem := range memories {
storageKey := kvPrefix + memoryPrefix + mem.Key
if err := store.SetConfig(ctx, storageKey, mem.Value); err != nil {
return fmt.Errorf("failed to import memory %q: %w", mem.Key, err)
}
result.Memories++
}
// Import issues
if len(issues) > 0 {
opts := ImportOptions{SkipPrefixValidation: true}
importResult, err := importIssuesCore(ctx, "", store, issues, opts)
if err != nil {
return fmt.Errorf("import failed: %w", err)
}
result.Created = importResult.Created
result.Skipped += importResult.Skipped
for _, issue := range issues {
result.IDs = append(result.IDs, issue.ID)
}
}
// Commit
commitMsg := fmt.Sprintf("bd import: %d issues", result.Created)
if result.Memories > 0 {
commitMsg += fmt.Sprintf(", %d memories", result.Memories)
}
commitMsg += fmt.Sprintf(" from %s", filepath.Base(jsonlPath))
commitMsg += fmt.Sprintf(" from %s", filepath.Base(source))
if err := store.Commit(ctx, commitMsg); err != nil {
return fmt.Errorf("commit: %w", err)
}
if result.Memories > 0 {
fmt.Fprintf(os.Stderr, "Imported %d issues and %d memories from %s\n", result.Issues, result.Memories, jsonlPath)
} else {
fmt.Fprintf(os.Stderr, "Imported %d issues from %s\n", result.Issues, jsonlPath)
if jsonOutput {
outputJSON(result)
return nil
}
fmt.Fprintf(os.Stderr, "Imported %d issues", result.Created)
if result.Memories > 0 {
fmt.Fprintf(os.Stderr, " and %d memories", result.Memories)
}
fmt.Fprintf(os.Stderr, " from %s", source)
if dedupHits > 0 {
fmt.Fprintf(os.Stderr, " (%d duplicates skipped)", dedupHits)
}
fmt.Fprintln(os.Stderr)
return nil
}
// filterDuplicatesByTitle removes issues whose title matches an existing open issue.
func filterDuplicatesByTitle(ctx context.Context, st storage.DoltStorage, issues []*types.Issue) ([]*types.Issue, int) {
existing, err := st.SearchIssues(ctx, "", types.IssueFilter{})
if err != nil {
return issues, 0
}
titleSet := make(map[string]bool, len(existing))
for _, issue := range existing {
if issue.Status != types.StatusClosed {
titleSet[strings.ToLower(issue.Title)] = true
}
}
var kept []*types.Issue
skipped := 0
for _, issue := range issues {
if titleSet[strings.ToLower(issue.Title)] {
skipped++
continue
}
kept = append(kept, issue)
}
return kept, skipped
}

View file

@ -53,13 +53,21 @@ func bdKVListJSON(t *testing.T, bd, dir string) map[string]string {
s := strings.TrimSpace(string(out))
start := strings.Index(s, "{")
if start < 0 {
// Empty KV store may return empty object or nothing
return map[string]string{}
}
var m map[string]string
if err := json.Unmarshal([]byte(s[start:]), &m); err != nil {
var raw map[string]interface{}
if err := json.Unmarshal([]byte(s[start:]), &raw); err != nil {
t.Fatalf("parse kv list JSON: %v\n%s", err, s)
}
m := make(map[string]string, len(raw))
for k, v := range raw {
if k == "schema_version" {
continue
}
if sv, ok := v.(string); ok {
m[k] = sv
}
}
return m
}

View file

@ -110,6 +110,7 @@ var readOnlyCommands = map[string]bool{
"duplicates": true,
"comments": true, // list comments (not add)
"current": true, // bd sync mode current
"ping": true,
"backup": true, // reads from Dolt, writes only to .beads/backup/
"export": true, // reads from Dolt, writes JSONL to file/stdout
}

View file

@ -3,10 +3,32 @@ package main
import (
"encoding/json"
"os"
"reflect"
)
// 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
// outputJSON outputs data as pretty-printed JSON to stdout.
//
// Object input: schema_version is injected as a top-level field so consumers
// (Jawnt MCP, BeadsX, gt mail, sync scripts) can detect format changes.
// Array/slice input: output as-is (no envelope wrapping) to preserve
// backwards compatibility with existing consumers that parse raw arrays.
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)
}
}
// 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 {
@ -14,14 +36,48 @@ func outputJSON(v interface{}) {
}
}
// wrapWithSchemaVersion adds schema_version to object output. Arrays
// and slices are returned unchanged to preserve backwards compatibility
// with existing consumers that parse raw JSON arrays.
func wrapWithSchemaVersion(v interface{}) interface{} {
if v == nil {
return map[string]interface{}{"schema_version": JSONSchemaVersion}
}
rv := reflect.ValueOf(v)
for rv.Kind() == reflect.Ptr {
rv = rv.Elem()
}
// Arrays/slices: return as-is (no envelope) for backwards compat.
if rv.Kind() == reflect.Slice || rv.Kind() == reflect.Array {
return v
}
// Objects: inject schema_version as a top-level field.
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
}
// outputJSONError outputs an error as JSON to stderr and exits with code 1.
func outputJSONError(err error, code string) {
errObj := map[string]string{"error": err.Error()}
errObj := map[string]interface{}{
"error": err.Error(),
"schema_version": JSONSchemaVersion,
}
if code != "" {
errObj["code"] = code
}
encoder := json.NewEncoder(os.Stderr)
encoder.SetIndent("", " ")
_ = encoder.Encode(errObj) // Best effort: if JSON encoding fails, error is already printed to stderr
_ = encoder.Encode(errObj)
os.Exit(1)
}

View file

@ -1,97 +1,90 @@
package main
import (
"bytes"
"encoding/json"
"io"
"os"
"testing"
)
func TestOutputJSON(t *testing.T) {
// Capture stdout
oldStdout := os.Stdout
r, w, _ := os.Pipe()
os.Stdout = w
func TestWrapWithSchemaVersion_Object(t *testing.T) {
input := map[string]string{"id": "beads-123", "title": "Test"}
result := wrapWithSchemaVersion(input)
// Test data
testData := map[string]interface{}{
"id": "bd-1",
"title": "Test Issue",
"count": 42,
m, ok := result.(map[string]interface{})
if !ok {
t.Fatalf("expected map[string]interface{}, got %T", result)
}
// Call outputJSON
outputJSON(testData)
// Restore stdout
w.Close()
os.Stdout = oldStdout
// Read output
var buf bytes.Buffer
io.Copy(&buf, r)
output := buf.String()
// Verify it's valid JSON
var result map[string]interface{}
err := json.Unmarshal([]byte(output), &result)
if err != nil {
t.Fatalf("outputJSON did not produce valid JSON: %v", err)
if m["schema_version"] != JSONSchemaVersion {
t.Errorf("schema_version = %v, want %d", m["schema_version"], JSONSchemaVersion)
}
// Verify content
if result["id"] != "bd-1" {
t.Errorf("Expected id 'bd-1', got '%v'", result["id"])
}
if result["title"] != "Test Issue" {
t.Errorf("Expected title 'Test Issue', got '%v'", result["title"])
}
// Note: JSON numbers are float64
if result["count"] != float64(42) {
t.Errorf("Expected count 42, got %v", result["count"])
if m["id"] != "beads-123" {
t.Errorf("id = %v, want beads-123", m["id"])
}
}
func TestOutputJSONArray(t *testing.T) {
// Capture stdout
oldStdout := os.Stdout
r, w, _ := os.Pipe()
os.Stdout = w
// Test data - array of issues
testData := []map[string]string{
{"id": "bd-1", "title": "First"},
{"id": "bd-2", "title": "Second"},
func TestWrapWithSchemaVersion_Struct(t *testing.T) {
type issue struct {
ID string `json:"id"`
Title string `json:"title"`
}
input := &issue{ID: "beads-456", Title: "Struct test"}
result := wrapWithSchemaVersion(input)
// Call outputJSON
outputJSON(testData)
// Restore stdout
w.Close()
os.Stdout = oldStdout
// Read output
var buf bytes.Buffer
io.Copy(&buf, r)
output := buf.String()
// Verify it's valid JSON array
var result []map[string]string
err := json.Unmarshal([]byte(output), &result)
if err != nil {
t.Fatalf("outputJSON did not produce valid JSON array: %v", err)
m, ok := result.(map[string]interface{})
if !ok {
t.Fatalf("expected map[string]interface{}, got %T", result)
}
if len(result) != 2 {
t.Fatalf("Expected 2 items, got %d", len(result))
if m["schema_version"] != JSONSchemaVersion {
t.Errorf("schema_version = %v, want %d", m["schema_version"], JSONSchemaVersion)
}
if m["id"] != "beads-456" {
t.Errorf("id = %v, want beads-456", m["id"])
}
}
// Tests for printCollisionReport and printRemappingReport were removed
// These functions no longer exist after refactoring to shared importIssuesCore (bd-157)
func TestWrapWithSchemaVersion_Slice(t *testing.T) {
input := []string{"a", "b", "c"}
result := wrapWithSchemaVersion(input)
// Note: createIssuesFromMarkdown is tested via cmd/bd/markdown_test.go which has
// comprehensive tests for the markdown parsing functionality. We don't duplicate
// those tests here since they require full DB setup.
// Arrays pass through unchanged for backwards compatibility.
arr, ok := result.([]string)
if !ok {
t.Fatalf("expected []string (passthrough), got %T", result)
}
if len(arr) != 3 {
t.Errorf("slice length = %d, want 3", len(arr))
}
}
func TestWrapWithSchemaVersion_Nil(t *testing.T) {
result := wrapWithSchemaVersion(nil)
m, ok := result.(map[string]interface{})
if !ok {
t.Fatalf("expected map[string]interface{}, got %T", result)
}
if m["schema_version"] != JSONSchemaVersion {
t.Errorf("schema_version = %v, want %d", m["schema_version"], JSONSchemaVersion)
}
}
func TestWrapWithSchemaVersion_RoundTrip(t *testing.T) {
input := map[string]interface{}{"count": 42, "name": "test"}
result := wrapWithSchemaVersion(input)
data, err := json.Marshal(result)
if err != nil {
t.Fatalf("marshal: %v", err)
}
var parsed map[string]interface{}
if err := json.Unmarshal(data, &parsed); err != nil {
t.Fatalf("unmarshal: %v", err)
}
sv, ok := parsed["schema_version"]
if !ok {
t.Fatal("schema_version missing after round-trip")
}
if sv != float64(JSONSchemaVersion) {
t.Errorf("schema_version = %v, want %v", sv, float64(JSONSchemaVersion))
}
}

94
cmd/bd/ping.go Normal file
View file

@ -0,0 +1,94 @@
package main
import (
"fmt"
"os"
"time"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/beads"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/internal/ui"
)
var pingCmd = &cobra.Command{
Use: "ping",
GroupID: "maint",
Short: "Check database connectivity",
Long: `Lightweight health check that confirms bd can reach its database.
Steps:
1. Resolve the .beads workspace
2. Open the store (embedded or server)
3. Run a trivial query (issue count)
4. Report timing
Exit 0 on success, exit 1 on failure.
Examples:
bd ping # Quick connectivity check
bd ping --json # Structured output for automation`,
Run: func(cmd *cobra.Command, args []string) {
start := time.Now()
beadsDir := beads.FindBeadsDir()
if beadsDir == "" {
pingFail(start, "no .beads directory found")
return
}
resolveMs := time.Since(start).Milliseconds()
st := getStore()
if st == nil {
pingFail(start, "store not initialized")
return
}
if lm, ok := storage.UnwrapStore(st).(storage.LifecycleManager); ok && lm.IsClosed() {
pingFail(start, "store is closed")
return
}
storeMs := time.Since(start).Milliseconds()
filter := types.IssueFilter{Limit: 1}
_, err := st.SearchIssues(rootCtx, "", filter)
if err != nil {
pingFail(start, fmt.Sprintf("query failed: %v", err))
return
}
totalMs := time.Since(start).Milliseconds()
queryMs := totalMs - storeMs
if jsonOutput {
outputJSON(map[string]interface{}{
"status": "ok",
"resolve_ms": resolveMs,
"store_ms": storeMs - resolveMs,
"query_ms": queryMs,
"total_ms": totalMs,
})
return
}
fmt.Fprintf(os.Stdout, "%s bd ping: ok (%dms)\n", ui.RenderPass("✓"), totalMs)
},
}
func pingFail(start time.Time, reason string) {
totalMs := time.Since(start).Milliseconds()
if jsonOutput {
outputJSON(map[string]interface{}{
"status": "error",
"error": reason,
"total_ms": totalMs,
})
os.Exit(1)
return
}
fmt.Fprintf(os.Stderr, "%s bd ping: %s (%dms)\n", ui.RenderFail("✗"), reason, totalMs)
os.Exit(1)
}
func init() {
rootCmd.AddCommand(pingCmd)
}

View file

@ -505,11 +505,32 @@ func assertFieldPrefix(t *testing.T, issue map[string]any, key, prefix string) {
}
}
// parseJSONOutput handles both JSON array and JSONL formats.
// parseJSONOutput handles schema-versioned envelopes, JSON arrays, and JSONL.
//
// Schema-versioned output wraps arrays as {"schema_version": N, "items": [...]}.
// Object output injects schema_version as a top-level field.
func parseJSONOutput(t *testing.T, output string) []map[string]any {
t.Helper()
// Try JSON array first
// Try schema-versioned envelope first
var envelope map[string]any
if err := json.Unmarshal([]byte(output), &envelope); err == nil {
if items, ok := envelope["items"]; ok {
if arr, ok := items.([]any); ok {
var result []map[string]any
for _, item := range arr {
if m, ok := item.(map[string]any); ok {
result = append(result, m)
}
}
return result
}
}
// Single object (e.g. bd show --json, bd create --json)
return []map[string]any{envelope}
}
// Try JSON array (legacy, pre-schema_version)
var arr []map[string]any
if err := json.Unmarshal([]byte(output), &arr); err == nil {
return arr
@ -528,3 +549,16 @@ func parseJSONOutput(t *testing.T, output string) []map[string]any {
}
return arr
}
// assertSchemaVersion verifies that the output object contains schema_version.
func assertSchemaVersion(t *testing.T, obj map[string]any, context string) {
t.Helper()
sv, ok := obj["schema_version"]
if !ok {
t.Errorf("%s: missing schema_version field", context)
return
}
if v, ok := sv.(float64); !ok || v < 1 {
t.Errorf("%s: schema_version = %v, want >= 1", context, sv)
}
}

View file

@ -19,12 +19,9 @@ func TestJSONContract_ListOutputIsValidJSON(t *testing.T) {
w.create("JSON contract test issue")
out := w.run("list", "--json")
var items []map[string]any
if err := json.Unmarshal([]byte(out), &items); err != nil {
t.Fatalf("bd list --json produced invalid JSON: %v\nOutput:\n%s", err, out)
}
items := parseJSONOutput(t, out)
if len(items) == 0 {
t.Fatal("bd list --json returned empty array")
t.Fatal("bd list --json returned no items")
}
}
@ -42,7 +39,7 @@ func TestJSONContract_ShowOutputHasRequiredFields(t *testing.T) {
}
issue := items[0]
requiredFields := []string{"id", "title", "status", "priority", "issue_type", "created_at"}
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)
@ -57,8 +54,8 @@ func TestJSONContract_ReadyOutputIsValidJSON(t *testing.T) {
w := newWorkspace(t)
out := w.run("ready", "--json")
var items []map[string]any
if err := json.Unmarshal([]byte(out), &items); err != nil {
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)
}
}
@ -71,19 +68,19 @@ func TestJSONContract_CreateOutputHasID(t *testing.T) {
out := w.run("create", "Create contract test", "--description=test", "--json")
// bd create --json outputs a single JSON object (not an array)
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 to stderr (not mixed text).
// produce valid JSON with schema_version to stderr (not mixed text).
func TestJSONContract_ErrorOutputIsValidJSON(t *testing.T) {
t.Parallel()
w := newWorkspace(t)
@ -101,19 +98,23 @@ func TestJSONContract_ErrorOutputIsValidJSON(t *testing.T) {
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
foundJSON := false
for _, line := range strings.Split(trimmed, "\n") {
line = strings.TrimSpace(line)
if line == "" {
continue
}
if json.Valid([]byte(line)) {
foundJSON = true
break
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
}
}
}
if !foundJSON {
t.Logf("Note: error output not fully JSON — this is acceptable for some error paths")
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")
}
}
}
@ -133,3 +134,105 @@ func TestJSONContract_CloseOutputHasStatus(t *testing.T) {
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")
})
}
}

View file

@ -143,11 +143,11 @@ func TestShow_NotFoundJSON(t *testing.T) {
if stdout == "" {
t.Fatal("expected JSON error on stdout, got empty output")
}
var errResp map[string]string
var errResp map[string]interface{}
if jsonErr := json.Unmarshal([]byte(stdout), &errResp); jsonErr != nil {
t.Fatalf("expected valid JSON error response on stdout, got parse error: %v\nStdout: %s", jsonErr, stdout)
}
if errResp["error"] == "" {
if errField, _ := errResp["error"].(string); errField == "" {
t.Errorf("expected non-empty 'error' field in JSON response, got: %s", stdout)
}
}

View file

@ -67,21 +67,22 @@ func TestWhereNoWorkspace(t *testing.T) {
t.Fatalf("expected JSON object in output, got: %s", out)
}
var payload map[string]string
var payload map[string]interface{}
if err := json.Unmarshal([]byte(s[start:]), &payload); err != nil {
t.Fatalf("parse where JSON: %v\n%s", err, s)
}
if payload["error"] != "no_beads_directory" {
t.Fatalf("error = %q, want %q", payload["error"], "no_beads_directory")
if errField, _ := payload["error"].(string); errField != "no_beads_directory" {
t.Fatalf("error = %q, want %q", errField, "no_beads_directory")
}
if payload["message"] != activeWorkspaceNotFoundMessage() {
t.Fatalf("message = %q, want %q", payload["message"], activeWorkspaceNotFoundMessage())
if message, _ := payload["message"].(string); message != activeWorkspaceNotFoundMessage() {
t.Fatalf("message = %q, want %q", message, activeWorkspaceNotFoundMessage())
}
if !strings.Contains(payload["hint"], "BEADS_DIR/worktree setup") {
t.Fatalf("hint should mention workspace diagnostics, got: %q", payload["hint"])
hint, _ := payload["hint"].(string)
if !strings.Contains(hint, "BEADS_DIR/worktree setup") {
t.Fatalf("hint should mention workspace diagnostics, got: %q", hint)
}
if !strings.Contains(payload["hint"], "bd init") {
t.Fatalf("hint should mention bd init, got: %q", payload["hint"])
if !strings.Contains(hint, "bd init") {
t.Fatalf("hint should mention bd init, got: %q", hint)
}
})
}

130
docs/JSON_SCHEMA.md Normal file
View file

@ -0,0 +1,130 @@
# JSON Output Schema Contract
Commands that return a single object (show, create, close, ping, etc.) include a
`schema_version` field at the top level. Commands that return arrays (list, ready,
blocked, etc.) output a raw JSON array for backwards compatibility.
## Schema Version
Current version: **1**
The `schema_version` field is an integer that increments when:
- Fields are added, renamed, or removed
- Output structure changes (e.g., nesting depth)
- Field types change (e.g., string to integer)
Additive changes (new optional fields) do NOT bump the version.
## Output Formats
### Object commands (show, create, close, update, etc.)
Commands that return a single issue or result emit a JSON object with
`schema_version` as a top-level field alongside the data:
```json
{
"schema_version": 1,
"id": "beads-abc",
"title": "Example issue",
"status": "open",
"priority": 1,
"issue_type": "task",
"created_at": "2026-04-20T12:00:00Z"
}
```
### List commands (list, ready, search, stale, etc.)
Commands that return multiple items emit a raw JSON array:
```json
[
{"id": "beads-abc", "title": "First", ...},
{"id": "beads-def", "title": "Second", ...}
]
```
### Error output (stderr)
Errors with `--json` active emit JSON to stderr:
```json
{
"schema_version": 1,
"error": "issue not found: beads-xyz",
"code": "not_found"
}
```
## Field Contracts by Command
### bd list --json
Required fields per item:
- `id` (string): Issue ID (e.g., "beads-abc")
- `title` (string): Issue title
- `status` (string): open, in_progress, closed, deferred
- `priority` (number): 0-4
- `issue_type` (string): bug, feature, task, epic, chore
- `created_at` (string): RFC3339 timestamp
Optional fields:
- `description`, `owner`, `updated_at`, `closed_at`
- `labels` (string[]): Attached labels
- `dependencies` (object[]): Dependency records
- `dependency_count`, `dependent_count`, `comment_count` (number)
- `parent` (string|null): Parent issue ID
### bd ready --json
Same schema as `bd list --json`. Items are filtered to unblocked issues only.
Each item includes `dependency_count`, `dependent_count`, `comment_count`,
and optional `parent` fields.
### bd blocked --json
Returns issues that are blocked by unresolved dependencies.
Each item includes all standard issue fields plus:
- `blocked_by_count` (number): Number of blocking dependencies
- `blocked_by` (string[]): IDs of blocking issues
### bd show --json
Returns a single object (not wrapped in `items`). Same required fields as list
items, plus:
- `description` (string)
- `acceptance_criteria` (string)
- `dependencies` (object[]): Full dependency records
- `comments` (object[]): Comment thread
### `import --json`
Returns a summary object when `--json` is active:
- `source` (string): File path or "stdin"
- `created` (number): Issues created
- `skipped` (number): Issues skipped (dedup)
- `dedup_skipped` (number): Issues skipped by `--dedup` title match
- `memories` (number): Memory records imported
- `ids` (string[]): IDs of created issues
- `dry_run` (boolean): Whether `--dry-run` was active
### bd export --json
Outputs JSONL (one JSON object per line), not wrapped in an envelope.
Each line is a self-contained issue or memory record. `schema_version`
is included per line.
## Consumer Guidelines
1. **Check `schema_version`** on object output. If the version is
higher than expected, log a warning but attempt to parse anyway
(additive changes are backward-compatible).
2. **For list commands**, parse the output as a JSON array directly.
3. **Ignore unknown fields**. New fields may be added without bumping
the schema version.
4. **Use `--json` flag**, not `--format json`. The `--json` flag is
the stable contract; `--format` is for human-readable variants.