feat: JSON schema contract, bd ping, structured errors, import enhancements (gastownhall#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>

Author: kevglynn

cmd/bd/bootstrap_embedded_test.go

@@ -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)
 		}
 	})
 }

cmd/bd/config_embedded_test.go

@@ -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
 }
 

cmd/bd/config_nodb_embedded_test.go

@@ -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)
 	}
 }

cmd/bd/errors.go

@@ -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)

cmd/bd/errors_test.go

@@ -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")
+				}
+			}
+		})
+	}
+}