feat: add comprehensive error messages with context for user guidance

- Enhance CLI error messages with detailed examples and suggestions
- Add contextual error messages to file system operations
- Improve OpenCode execution error reporting with debugging hints
- Add detailed troubleshooting information for all retry failures
- Enhance main loop error messages with recovery suggestions
- Provide specific guidance for common error scenarios
- Include actionable next steps in all error paths
- Fix test helpers to work with updated Logger structure

All error messages now include:
- Clear description of what went wrong
- Possible causes of the error
- Actionable steps to resolve the issue
- Context-specific hints based on error type

Signed-off-by: leocavalcante <[email protected]>

Author: leocavalcante

src/cli.zig

@@ -187,11 +187,69 @@ pub fn printVersion(file: std.fs.File) void {
 /// Format error message for CLI errors
 pub fn formatError(err: ParseError, file: std.fs.File) void {
     const msg = switch (err) {
-        ParseError.MissingRequiredArgs => "Error: Either --provider or both --planning-model and --execution-model are required\nUse -h or --help for usage information\n",
-        ParseError.UnknownOption => "Error: Unknown option\nUse -h or --help for usage information\n",
-        ParseError.UnknownProvider => "Error: Unknown provider\nAvailable providers: github, anthropic, openai, opencode\n",
-        ParseError.InvalidProjectDir => "Error: Project directory does not exist or is not accessible\n",
-        ParseError.MissingOptionValue => "Error: Option requires a value\nUse -h or --help for usage information\n",
+        ParseError.MissingRequiredArgs =>
+        \\Error: Missing required model configuration
+        \\
+        \\You must specify models using either:
+        \\  1. Provider preset:  opencoder --provider github
+        \\  2. Explicit models:  opencoder -P planning-model -E execution-model
+        \\
+        \\Available providers: github, anthropic, openai, opencode
+        \\
+        \\For detailed help, run: opencoder --help
+        \\
+        ,
+        ParseError.UnknownOption =>
+        \\Error: Unknown command-line option
+        \\
+        \\Common options:
+        \\  --provider PROVIDER    Use a provider preset
+        \\  -P, --planning-model   Specify planning model
+        \\  -E, --execution-model  Specify execution model
+        \\  -v, --verbose          Enable verbose logging
+        \\  -p, --project DIR      Set project directory
+        \\
+        \\For complete usage information, run: opencoder --help
+        \\
+        ,
+        ParseError.UnknownProvider =>
+        \\Error: Unknown provider specified
+        \\
+        \\Available providers:
+        \\  github     - GitHub Copilot models (Claude Opus 4.5 / Sonnet 4.5)
+        \\  anthropic  - Anthropic models (Claude Sonnet 4 / Haiku)
+        \\  openai     - OpenAI models (GPT-4 / GPT-4o-mini)
+        \\  opencode   - OpenCode free models (GLM-4.7 / Minimax M2.1)
+        \\
+        \\Usage: opencoder --provider <name>
+        \\Example: opencoder --provider github
+        \\
+        ,
+        ParseError.InvalidProjectDir =>
+        \\Error: Project directory not found or not accessible
+        \\
+        \\Please check that:
+        \\  1. The directory path exists
+        \\  2. You have read/write permissions
+        \\  3. The path is specified correctly
+        \\
+        \\Current directory will be used if -p/--project is not specified.
+        \\
+        \\Example: opencoder --provider github -p /path/to/project
+        \\
+        ,
+        ParseError.MissingOptionValue =>
+        \\Error: Command-line option missing required value
+        \\
+        \\Options that require values:
+        \\  --provider PROVIDER    (e.g., --provider github)
+        \\  -P MODEL               (e.g., -P anthropic/claude-sonnet-4)
+        \\  -E MODEL               (e.g., -E anthropic/claude-haiku)
+        \\  -p DIR                 (e.g., -p /path/to/project)
+        \\
+        \\For detailed help, run: opencoder --help
+        \\
+        ,
     };
     _ = file.write(msg) catch {};
 }

src/evaluator.zig

@@ -74,7 +74,7 @@ test "EvaluationResult enum values" {
 
 test "hasPendingTasks returns false for missing file" {
     const allocator = std.testing.allocator;
-    const result = hasPendingTasks("/tmp/nonexistent_plan.md", allocator);
+    const result = hasPendingTasks("/tmp/nonexistent_plan.md", allocator, 1024 * 1024);
     try std.testing.expect(!result);
 }
 
@@ -85,7 +85,7 @@ test "hasPendingTasks returns true for plan with pending tasks" {
     // Write test plan
     try fsutil.writeFile(test_path, "- [ ] Task 1\n- [x] Task 2\n");
 
-    const result = hasPendingTasks(test_path, allocator);
+    const result = hasPendingTasks(test_path, allocator, 1024 * 1024);
     try std.testing.expect(result);
 
     // Clean up
@@ -99,7 +99,7 @@ test "hasPendingTasks returns false for completed plan" {
     // Write test plan
     try fsutil.writeFile(test_path, "- [x] Task 1\n- [x] Task 2\n");
 
-    const result = hasPendingTasks(test_path, allocator);
+    const result = hasPendingTasks(test_path, allocator, 1024 * 1024);
     try std.testing.expect(!result);
 
     // Clean up

src/executor.zig

@@ -107,34 +107,46 @@ pub const Executor = struct {
         var attempt: u32 = 0;
         while (attempt < self.cfg.max_retries) : (attempt += 1) {
             if (attempt > 0) {
-                self.log.statusFmt("[Cycle {d}] Evaluating (retry {d}/{d})...", .{ cycle, attempt + 1, self.cfg.max_retries });
+                self.log.statusFmt("[Cycle {d}] Evaluation retry {d}/{d}", .{ cycle, attempt + 1, self.cfg.max_retries });
             }
 
             const result = self.runOpencode(self.cfg.planning_model, title, prompt, false);
             if (result) |output| {
                 // Check for COMPLETE or NEEDS_WORK in output
                 if (std.mem.indexOf(u8, output, "COMPLETE") != null) {
+                    self.log.logFmt("[Cycle {d}] Evaluation result: COMPLETE", .{cycle});
                     self.allocator.free(output);
                     return "COMPLETE";
                 } else if (std.mem.indexOf(u8, output, "NEEDS_WORK") != null) {
+                    self.log.logFmt("[Cycle {d}] Evaluation result: NEEDS_WORK", .{cycle});
                     self.allocator.free(output);
                     return "NEEDS_WORK";
+                } else {
+                    self.log.logErrorFmt("[Cycle {d}] Evaluation returned unexpected response", .{cycle});
+                    self.log.logError("  Expected: 'COMPLETE' or 'NEEDS_WORK'");
+                    self.log.logError("  Hint: The evaluation model may need more specific instructions");
                 }
                 self.allocator.free(output);
-            } else |_| {
-                // Error running opencode
+            } else |err| {
+                self.log.logErrorFmt("[Cycle {d}] Evaluation attempt {d} failed: {s}", .{ cycle, attempt + 1, @errorName(err) });
             }
 
             // Backoff before retry
             if (attempt + 1 < self.cfg.max_retries) {
                 const sleep_time = self.cfg.backoff_base * std.math.pow(u32, 2, attempt);
-                self.log.statusFmt("[Cycle {d}] Retrying evaluation in {d}s...", .{ cycle, sleep_time });
+                self.log.statusFmt("[Cycle {d}] Waiting {d}s before retry...", .{ cycle, sleep_time });
                 std.Thread.sleep(@as(u64, sleep_time) * std.time.ns_per_s);
             }
         }
 
         // Default to NEEDS_WORK if we couldn't determine
-        self.log.logErrorFmt("Failed to get evaluation result after {d} attempts (cycle {d}), defaulting to NEEDS_WORK", .{ self.cfg.max_retries, cycle });
+        self.log.logError("");
+        self.log.logErrorFmt("[Cycle {d}] Failed to get evaluation result after {d} attempts", .{ cycle, self.cfg.max_retries });
+        self.log.logError("  Defaulting to NEEDS_WORK to continue safely");
+        self.log.logError("  Possible causes:");
+        self.log.logError("    - Model API unavailable or rate limited");
+        self.log.logError("    - Evaluation prompt not producing expected output");
+        self.log.logError("    - Network connectivity issues");
         return "NEEDS_WORK";
     }
 
@@ -152,21 +164,35 @@ pub const Executor = struct {
 
         while (attempt < self.cfg.max_retries) : (attempt += 1) {
             if (attempt > 0) {
-                self.log.logFmt("Attempt {d}/{d}", .{ attempt + 1, self.cfg.max_retries });
+                self.log.logFmt("Retry attempt {d}/{d}", .{ attempt + 1, self.cfg.max_retries });
             }
 
             const result = self.runOpencode(model, title, prompt, continue_session);
             if (result) |output| {
                 self.allocator.free(output);
                 return .success;
             } else |err| {
-                self.log.logErrorFmt("opencode failed (attempt {d}/{d}): {s} with model '{s}'", .{ attempt + 1, self.cfg.max_retries, @errorName(err), model });
+                self.log.logErrorFmt("OpenCode execution failed (attempt {d}/{d})", .{ attempt + 1, self.cfg.max_retries });
+                self.log.logErrorFmt("  Model: {s}", .{model});
+                self.log.logErrorFmt("  Error: {s}", .{@errorName(err)});
+
+                if (attempt + 1 == self.cfg.max_retries) {
+                    // Last attempt, provide detailed troubleshooting
+                    self.log.logError("");
+                    self.log.logError("All retry attempts exhausted. Troubleshooting tips:");
+                    self.log.logError("  1. Verify 'opencode' CLI is installed: which opencode");
+                    self.log.logError("  2. Check if opencode works directly: opencode --version");
+                    self.log.logError("  3. Verify model is available: opencode models list");
+                    self.log.logError("  4. Check API credentials are configured properly");
+                    self.log.logError("  5. Review network connectivity and API rate limits");
+                    self.log.logErrorFmt("  6. Try increasing OPENCODER_MAX_RETRIES (current: {d})", .{self.cfg.max_retries});
+                }
             }
 
             // Backoff before retry
             if (attempt + 1 < self.cfg.max_retries) {
                 const sleep_time = self.cfg.backoff_base * std.math.pow(u32, 2, attempt);
-                self.log.logFmt("Retrying in {d}s...", .{sleep_time});
+                self.log.logFmt("Waiting {d}s before retry...", .{sleep_time});
                 std.Thread.sleep(@as(u64, sleep_time) * std.time.ns_per_s);
             }
         }
@@ -228,16 +254,34 @@ pub const Executor = struct {
                 if (code == 0) {
                     return stdout_list.toOwnedSlice(self.allocator);
                 }
-                self.log.logErrorFmt("opencode exited with code {d} (model: {s}, title: {s})", .{ code, model, title });
+                self.log.logErrorFmt("OpenCode process exited with non-zero status", .{});
+                self.log.logErrorFmt("  Exit code: {d}", .{code});
+                self.log.logErrorFmt("  Model: {s}", .{model});
+                self.log.logErrorFmt("  Title: {s}", .{title});
+
+                // Provide context based on exit code
+                if (code == 1) {
+                    self.log.logError("  Common causes: Invalid arguments, API authentication failure");
+                } else if (code == 2) {
+                    self.log.logError("  Common causes: Model not found, invalid model specification");
+                } else if (code >= 126 and code <= 127) {
+                    self.log.logError("  Common causes: opencode CLI not found or not executable");
+                    self.log.logError("  Hint: Verify installation with 'which opencode'");
+                }
             },
             .Signal => |sig| {
-                self.log.logErrorFmt("opencode terminated by signal {d} (model: {s}, title: {s})", .{ sig, model, title });
+                self.log.logErrorFmt("OpenCode process terminated by signal {d}", .{sig});
+                self.log.logErrorFmt("  Model: {s}", .{model});
+                self.log.logError("  This usually indicates the process was killed externally");
+                self.log.logError("  Hint: Check system resources (memory, CPU) and logs");
             },
             .Stopped => |sig| {
-                self.log.logErrorFmt("opencode stopped by signal {d} (model: {s}, title: {s})", .{ sig, model, title });
+                self.log.logErrorFmt("OpenCode process stopped by signal {d}", .{sig});
+                self.log.logErrorFmt("  Model: {s}", .{model});
             },
             .Unknown => |status| {
-                self.log.logErrorFmt("opencode terminated with unknown status {d} (model: {s}, title: {s})", .{ status, model, title });
+                self.log.logErrorFmt("OpenCode process terminated with unknown status {d}", .{status});
+                self.log.logErrorFmt("  Model: {s}", .{model});
             },
         }
 
@@ -258,6 +302,7 @@ fn createTestLogger(allocator: Allocator) !*Logger {
 
     try std.fs.cwd().makePath(temp_dir);
 
+    const main_log_path = try std.fs.path.join(allocator, &.{ temp_dir, "main.log" });
     const cycle_log_dir = try std.fs.path.join(allocator, &.{ temp_dir, "cycles" });
     const alerts_file = try std.fs.path.join(allocator, &.{ temp_dir, "alerts.log" });
 
@@ -266,6 +311,7 @@ fn createTestLogger(allocator: Allocator) !*Logger {
     const logger_ptr = try allocator.create(Logger);
     logger_ptr.* = Logger{
         .main_log = null,
+        .main_log_path = main_log_path,
         .cycle_log_dir = cycle_log_dir,
         .alerts_file = alerts_file,
         .cycle = 0,
@@ -281,6 +327,7 @@ fn destroyTestLogger(logger_ptr: *Logger, allocator: Allocator) void {
     const temp_base = std.fs.path.dirname(logger_ptr.cycle_log_dir) orelse "/tmp";
     std.fs.cwd().deleteTree(temp_base) catch {};
 
+    allocator.free(logger_ptr.main_log_path);
     allocator.free(logger_ptr.cycle_log_dir);
     allocator.free(logger_ptr.alerts_file);
     allocator.destroy(logger_ptr);

src/fs.zig

@@ -7,6 +7,14 @@ const std = @import("std");
 const fs = std.fs;
 const Allocator = std.mem.Allocator;
 
+/// File system operation errors with context
+pub const FsError = error{
+    DirectoryCreationFailed,
+    FileReadFailed,
+    FileWriteFailed,
+    FileNotAccessible,
+};
+
 /// Paths to opencoder workspace files and directories
 pub const Paths = struct {
     opencoder_dir: []const u8,
@@ -33,7 +41,13 @@ pub const Paths = struct {
 /// Initialize the .opencoder directory structure
 pub fn initDirectories(project_dir: []const u8, allocator: Allocator) !Paths {
     // Build all paths
-    const opencoder_dir = try std.fs.path.join(allocator, &.{ project_dir, ".opencoder" });
+    const opencoder_dir = std.fs.path.join(allocator, &.{ project_dir, ".opencoder" }) catch |err| {
+        if (@import("builtin").is_test == false) {
+            const stderr_file = std.fs.File{ .handle = std.posix.STDERR_FILENO };
+            _ = stderr_file.write("Error: Failed to construct .opencoder directory path\n") catch {};
+        }
+        return err;
+    };
     errdefer allocator.free(opencoder_dir);
 
     const state_file = try std.fs.path.join(allocator, &.{ opencoder_dir, "state.json" });
@@ -57,8 +71,22 @@ pub fn initDirectories(project_dir: []const u8, allocator: Allocator) !Paths {
     const history_dir = try std.fs.path.join(allocator, &.{ opencoder_dir, "history" });
     errdefer allocator.free(history_dir);
 
-    // Create directories
-    try ensureDir(opencoder_dir);
+    // Create directories with better error context
+    ensureDir(opencoder_dir) catch |err| {
+        if (@import("builtin").is_test == false) {
+            const stderr_file = std.fs.File{ .handle = std.posix.STDERR_FILENO };
+            _ = stderr_file.write("\nError: Failed to initialize workspace directory structure\n") catch {};
+            _ = stderr_file.write("\nPossible causes:\n") catch {};
+            _ = stderr_file.write("  - Insufficient permissions in project directory\n") catch {};
+            _ = stderr_file.write("  - Disk full or quota exceeded\n") catch {};
+            _ = stderr_file.write("  - File system is read-only\n") catch {};
+            _ = stderr_file.write("\nSuggested actions:\n") catch {};
+            _ = stderr_file.write("  1. Check write permissions for project directory\n") catch {};
+            _ = stderr_file.write("  2. Check disk space: df -h\n") catch {};
+            _ = stderr_file.write("  3. Try a different project directory with -p flag\n") catch {};
+        }
+        return err;
+    };
     try ensureDir(logs_dir);
     try ensureDir(cycle_log_dir);
     try ensureDir(history_dir);
@@ -79,6 +107,11 @@ pub fn initDirectories(project_dir: []const u8, allocator: Allocator) !Paths {
 pub fn ensureDir(path: []const u8) !void {
     fs.cwd().makePath(path) catch |err| {
         if (err != error.PathAlreadyExists) {
+            if (@import("builtin").is_test == false) {
+                const stderr_file = std.fs.File{ .handle = std.posix.STDERR_FILENO };
+                _ = stderr_file.write("Error: Failed to create directory\n") catch {};
+                _ = stderr_file.write("Hint: Check parent directory permissions and available disk space\n") catch {};
+            }
             return err;
         }
     };
@@ -92,16 +125,49 @@ pub fn fileExists(path: []const u8) bool {
 
 /// Read entire file contents
 pub fn readFile(path: []const u8, allocator: Allocator, max_size: usize) ![]u8 {
-    const file = try fs.cwd().openFile(path, .{});
+    const file = fs.cwd().openFile(path, .{}) catch |err| {
+        // Only print errors in non-test builds
+        if (@import("builtin").is_test == false) {
+            const stderr_file = std.fs.File{ .handle = std.posix.STDERR_FILENO };
+            _ = stderr_file.write("Error: Failed to open file\n") catch {};
+            _ = stderr_file.write("Hint: Check that the file exists and you have read permissions\n") catch {};
+        }
+        return err;
+    };
     defer file.close();
-    return try file.readToEndAlloc(allocator, max_size);
+
+    return file.readToEndAlloc(allocator, max_size) catch |err| {
+        if (@import("builtin").is_test == false) {
+            const stderr_file = std.fs.File{ .handle = std.posix.STDERR_FILENO };
+            _ = stderr_file.write("Error: Failed to read file\n") catch {};
+            if (err == error.StreamTooLong) {
+                _ = stderr_file.write("Hint: File exceeds maximum size. Consider increasing OPENCODER_MAX_FILE_SIZE\n") catch {};
+            }
+        }
+        return err;
+    };
 }
 
 /// Write contents to file
 pub fn writeFile(path: []const u8, contents: []const u8) !void {
-    const file = try fs.cwd().createFile(path, .{});
+    const file = fs.cwd().createFile(path, .{}) catch |err| {
+        if (@import("builtin").is_test == false) {
+            const stderr_file = std.fs.File{ .handle = std.posix.STDERR_FILENO };
+            _ = stderr_file.write("Error: Failed to create/open file\n") catch {};
+            _ = stderr_file.write("Hint: Check directory permissions and available disk space\n") catch {};
+        }
+        return err;
+    };
     defer file.close();
-    try file.writeAll(contents);
+
+    file.writeAll(contents) catch |err| {
+        if (@import("builtin").is_test == false) {
+            const stderr_file = std.fs.File{ .handle = std.posix.STDERR_FILENO };
+            _ = stderr_file.write("Error: Failed to write to file\n") catch {};
+            _ = stderr_file.write("Hint: Check available disk space and file system permissions\n") catch {};
+        }
+        return err;
+    };
 }
 
 /// Delete a file if it exists

src/logger.zig

@@ -412,7 +412,7 @@ test "rotate creates rotated log file" {
     defer allocator.free(logs_dir);
     try fs.cwd().makePath(logs_dir);
 
-    var log = try Logger.init(test_dir, false, allocator);
+    var log = try Logger.init(test_dir, false, allocator, 2048);
     defer log.deinit();
 
     log.log("test message");
@@ -434,7 +434,7 @@ test "cleanup removes old cycle logs" {
     defer allocator.free(cycle_dir);
     try fs.cwd().makePath(cycle_dir);
 
-    var log = try Logger.init(test_dir, false, allocator);
+    var log = try Logger.init(test_dir, false, allocator, 2048);
     defer log.deinit();
 
     const cycle_path = try std.fs.path.join(allocator, &.{ cycle_dir, "cycle_001.log" });