beads/cmd/bd/errors.go
Kevin Glynn 0d4b979354
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>
2026-04-20 21:09:48 -07:00

177 lines
5.1 KiB
Go

package main
import (
"encoding/json"
"fmt"
"os"
)
func activeWorkspaceNotFoundError() string {
return "no active beads workspace found"
}
func activeWorkspaceNotFoundMessage() string {
return "No active beads workspace found."
}
// diagHint returns the appropriate diagnostic hint when the active beads
// workspace cannot be resolved. In embedded mode, 'bd doctor' is not
// available so the hint omits it.
func diagHint() string {
return workspaceDiagHint(true)
}
func whereDiagHint() string {
return workspaceDiagHint(false)
}
func workspaceDiagHint(includeWhere bool) string {
if includeWhere {
if isEmbeddedMode() {
return "run 'bd where' to inspect the resolved workspace, or 'bd init' to create a new database"
}
return "run 'bd where' to inspect the resolved workspace, run 'bd doctor' to diagnose, or 'bd init' to create a new database"
}
if isEmbeddedMode() {
return "check BEADS_DIR/worktree setup, or run 'bd init' to create a new database"
}
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.
//
// Pattern A from ERROR_HANDLING.md:
// - User input validation failures
// - Critical preconditions not met
// - Unrecoverable system errors
//
// Example:
//
// if err := store.CreateIssue(ctx, issue, actor); err != nil {
// FatalError("%v", err)
// }
func FatalError(format string, args ...interface{}) {
msg := fmt.Sprintf(format, args...)
if jsonOutput {
jsonStderrError(msg, "")
} else {
fmt.Fprintf(os.Stderr, "Error: %s\n", msg)
}
os.Exit(1)
}
// FatalErrorRespectJSON writes an error message and exits with code 1.
// If --json flag is set, outputs structured JSON to stdout.
// Otherwise, outputs plain text to stderr.
//
// Use this for errors in commands that support --json output.
//
// Example:
//
// if err := store.GetIssue(ctx, id); err != nil {
// FatalErrorRespectJSON("%v", err)
// }
func FatalErrorRespectJSON(format string, args ...interface{}) {
msg := fmt.Sprintf(format, args...)
if jsonOutput {
jsonStdoutError(msg, "")
} else {
fmt.Fprintf(os.Stderr, "Error: %s\n", msg)
}
os.Exit(1)
}
// FatalErrorWithHintRespectJSON writes an error message with a hint and exits.
// If --json is set, emits structured JSON to stdout so callers can parse it.
func FatalErrorWithHintRespectJSON(message, hint string) {
if jsonOutput {
jsonStdoutError(message, hint)
} else {
fmt.Fprintf(os.Stderr, "Error: %s\n", message)
fmt.Fprintf(os.Stderr, "Hint: %s\n", hint)
}
os.Exit(1)
}
// FatalErrorWithHint writes an error message with a hint to stderr and exits.
// Use this when you can provide an actionable suggestion to fix the error.
//
// Example:
//
// FatalErrorWithHint("database not found", "Run 'bd init' to create a database")
func FatalErrorWithHint(message, hint string) {
if jsonOutput {
jsonStderrError(message, hint)
} else {
fmt.Fprintf(os.Stderr, "Error: %s\n", message)
fmt.Fprintf(os.Stderr, "Hint: %s\n", hint)
}
os.Exit(1)
}
// WarnError writes a warning message to stderr and returns.
// Use this for optional operations that enhance functionality but aren't required.
//
// Pattern B from ERROR_HANDLING.md:
// - Metadata operations
// - Cleanup operations
// - Auxiliary features (git hooks, merge drivers)
//
// Example:
//
// if err := createConfigYaml(beadsDir, false); err != nil {
// WarnError("failed to create config.yaml: %v", err)
// }
func WarnError(format string, args ...interface{}) {
fmt.Fprintf(os.Stderr, "Warning: "+format+"\n", args...)
}
// CheckReadonly exits with an error if readonly mode is enabled.
// Call this at the start of write commands (create, update, close, delete, sync, etc.).
// Used by worker sandboxes that should only read beads, not modify them.
//
// Example:
//
// var createCmd = &cobra.Command{
// Run: func(cmd *cobra.Command, args []string) {
// CheckReadonly("create")
// // ... rest of command
// },
// }
func CheckReadonly(operation string) {
if readonlyMode {
FatalError("operation '%s' is not allowed in read-only mode", operation)
}
}