diff --git a/engdocs/ERROR_HANDLING.md b/engdocs/ERROR_HANDLING.md index e394c8c02..37ebbaccd 100644 --- a/engdocs/ERROR_HANDLING.md +++ b/engdocs/ERROR_HANDLING.md @@ -1,6 +1,6 @@ # Error Handling Guidelines -Last reviewed: 2026-07-07 +Last reviewed: 2026-10-05 Freshness source: `cmd/bd/*.go`, especially command error exits and JSON error helpers in `cmd/bd/errors.go`. @@ -47,7 +47,8 @@ every `defer`), and `main()` maps the sentinel to exit code 1. **Narrow exceptions still using `os.Exit`:** process-level gates that run before or outside the `RunE` error path — e.g. `CheckReadonly`, which aborts a blocked -command after flushing metrics first. A handful of pre-existing direct +command after flushing metrics first (exit 1 in read-only mode, +`ExitMigrationFrozen` under a migration freeze). A handful of pre-existing direct `os.Exit(1)` calls also remain inside handler bodies; new command code should return a `HandleError*` value instead of adding more. @@ -67,7 +68,7 @@ return a `HandleError*` value instead of adding more. **Example:** ```go -if err := createConfigYaml(beadsDir, false); err != nil { +if err := createConfigYaml(beadsDir, false, ""); err != nil { fmt.Fprintf(os.Stderr, "Warning: failed to create config.yaml: %v\n", err) // Non-fatal - continue anyway } @@ -80,10 +81,9 @@ if err := createConfigYaml(beadsDir, false); err != nil { - Core functionality still works **Files using this pattern:** -- `cmd/bd/init.go` (lines 155-157, 161-163, 167-169, 188-190, 236-238, 272-274, etc.) -- `cmd/bd/sync.go` (lines 156, 257, 281, 329, 335, 720-722, 740, 743, 752, 762) -- `cmd/bd/create.go` (lines 333-334, 340-341) -- `cmd/bd/sync.go` *(handles Dolt sync operations)* +- `cmd/bd/init.go` — search for `"Warning: failed` (config.yaml, `.gitignore`, + git exclude, and tracking-metadata writes) +- `cmd/bd/create.go`, `cmd/bd/gc.go` — search for `WarnError(` --- @@ -107,9 +107,7 @@ _ = os.Remove(tempPath) - Primary error already reported **Files using this pattern:** -- `cmd/bd/init.go` (line 209, 326-327) -- `cmd/bd/sync.go` (lines 696-698) -- `cmd/bd/sync.go` *(sync cleanup)* +- `cmd/bd/init.go` — search for `_ = store.Close()` - Dozens of other locations throughout the codebase --- @@ -166,7 +164,7 @@ if err != nil { ### Creating Auxiliary Config Files → Pattern B (Warn) ```go -if err := createConfigYaml(localBeadsDir, false); err != nil { +if err := createConfigYaml(localBeadsDir, false, ""); err != nil { fmt.Fprintf(os.Stderr, "Warning: failed to create config.yaml: %v\n", err) // Non-fatal - continue anyway } @@ -186,8 +184,8 @@ defer func() { ### Optional Metadata Updates → Pattern B (Warn) ```go -if err := store.SetMetadata(ctx, "last_import_hash", currentHash); err != nil { - fmt.Fprintf(os.Stderr, "Warning: failed to update last_import_hash: %v\n", err) +if err := store.SetLocalMetadata(ctx, "bd_version", Version); err != nil { + fmt.Fprintf(os.Stderr, "Warning: failed to write bd_version local metadata: %v\n", err) } ``` @@ -205,7 +203,7 @@ if err := store.CreateIssue(ctx, issue, actor); err != nil { ```go // BAD: Same type of operation handled differently -if err := createConfigYaml(dir, false); err != nil { +if err := createConfigYaml(dir, false, ""); err != nil { fmt.Fprintf(os.Stderr, "Warning: %v\n", err) // Warns } if err := createReadme(dir); err != nil { @@ -216,7 +214,7 @@ if err := createReadme(dir); err != nil { ```go // GOOD: Consistent pattern for similar operations -if err := createConfigYaml(dir, false); err != nil { +if err := createConfigYaml(dir, false, ""); err != nil { fmt.Fprintf(os.Stderr, "Warning: failed to create config.yaml: %v\n", err) } if err := createReadme(dir); err != nil { @@ -285,15 +283,10 @@ defer store.Close() if err := store.SetConfig(ctx, "issue_prefix", prefix); err != nil { return HandleError("failed to set issue prefix: %v", err) } - -if err := syncbranch.Set(ctx, store, branch); err != nil { - return HandleError("failed to set sync branch: %v", err) -} ``` **Examples:** - `issue_prefix` - Defines how all issue IDs are generated -- `sync.branch` - Critical for git synchronization workflow **Rationale:** These settings are prerequisites for basic operation. Without them, the system cannot function correctly. A failure here indicates a serious problem (e.g., filesystem issues, database corruption). @@ -303,28 +296,25 @@ Tracking metadata **enhances functionality** but the system works without it: ```go // Pattern B: Warn and continue -if err := store.SetMetadata(ctx, "bd_version", Version); err != nil { - fmt.Fprintf(os.Stderr, "Warning: failed to store version metadata: %v\n", err) +// bd_version is clone-local state, so it goes through SetLocalMetadata. +if err := store.SetLocalMetadata(ctx, "bd_version", Version); err != nil { + fmt.Fprintf(os.Stderr, "Warning: failed to write bd_version local metadata: %v\n", err) // Non-fatal - continue anyway } -if err := store.SetMetadata(ctx, "repo_id", repoID); err != nil { - fmt.Fprintf(os.Stderr, "Warning: failed to set repo_id: %v\n", err) -} - -if err := store.SetMetadata(ctx, "last_import_hash", hash); err != nil { - fmt.Fprintf(os.Stderr, "Warning: failed to update last_import_hash: %v\n", err) +// verifyMetadata writes the field, reads it back, and warns on failure. +if verifyMetadata(ctx, store, "repo_id", repoID) && !quiet { + fmt.Printf(" Repository ID: %s\n", repoID[:8]) } ``` **Examples:** - `bd_version` - Enables version mismatch warnings on upgrades - `repo_id` / `clone_id` - Helps with collision detection across clones -- `last_import_hash` - Optimizes staleness detection (falls back to mtime if unavailable) **Rationale:** System degrades gracefully if tracking metadata is unavailable. Core functionality (creating issues, importing data) still works. Failures here might indicate temporary issues (e.g., read-only filesystem) that shouldn't block the entire operation. -**See also:** `cmd/bd/init.go` lines 206-272 for detailed inline documentation of this distinction. +**See also:** the `CONFIGURATION METADATA` and `TRACKING METADATA` comment blocks in `cmd/bd/init.go` for inline documentation of this distinction. ### File Permission Errors @@ -378,6 +368,11 @@ func HandleErrorWithHintRespectJSON(message, hint string) error // Exit 1 with no message, when the error was already reported func SilentExit() error +// Proxied-server capability refusals: a nil error passes through as nil, a +// *ProxyCapabilityError is rendered (JSON-aware) with its own exit code, and +// any other error falls back to HandleErrorRespectJSON +func HandleProxyCapabilityError(err error) error + // Pattern B — prints "Warning: ..." to stderr and returns nothing func WarnError(format string, args ...interface{}) ``` @@ -393,4 +388,3 @@ func WarnError(format string, args ...interface{}) - `cmd/bd/errors.go` - The `HandleError*` / `WarnError` / `SilentExit` helpers and the `exitError` sentinel that `main()` maps to an exit code - `cmd/bd/defer.go` - Clean example of Pattern A: `return HandleError(...)` from a `RunE` with `SilenceUsage`/`SilenceErrors` set - `cmd/bd/init.go` - Examples of all three patterns -- `cmd/bd/sync.go` - Examples of Pattern B for metadata operations and Pattern C for cleanup operations