Feat: Add Error Handling and Logging Audit Report

AUDIT-ERROR-HANDLING.md

@@ -0,0 +1,97 @@
+# Error Handling & Logging Audit
+
+This document details the findings of an audit of the error handling and logging practices within the codebase.
+
+## Error Handling
+
+### Exception Handling
+
+- **Are exceptions caught appropriately?**
+  - Yes, in the Go sense, errors are generally handled and propagated up the call stack. The `pkg/` libraries correctly return errors to the caller. The `cmd/trix` application handles the final error in the `main` function.
+
+- **Generic catches hiding bugs?**
+  - No evidence of this. Error handling is explicit.
+
+- **Error information leakage?**
+  - The `pkg/` libraries are safe and do not leak sensitive information. However, the `cmd/trix` CLI prints raw error messages directly to the user, which could expose internal implementation details (e.g., function names, variable types) that are not user-friendly.
+
+### Error Recovery
+
+- **Graceful degradation?**
+  - Not applicable in the current context. The CLI tool is designed to succeed or fail.
+
+- **Retry logic with backoff?**
+  - Not implemented, and not necessary for the current functionality.
+
+- **Circuit breaker patterns?**
+  - Not implemented, and not necessary for the current functionality.
+
+### User-Facing Errors
+
+- **Helpful without exposing internals?**
+  - This is an area for improvement. The CLI prints raw errors from the underlying libraries, which is not ideal for the end-user. Errors should be caught, and user-friendly messages should be displayed, while the technical details are logged for debugging.
+
+- **Consistent error format?**
+  - The format is consistent in that it's whatever Go's `error.Error()` method returns. There is no structured error format for users.
+
+- **Localization support?**
+  - There is no support for localization of error messages.
+
+### API Errors
+
+- **Standard error response format?**
+  - Not applicable. The project is a CLI tool, not a web API.
+
+- **Appropriate HTTP status codes?**
+  - Not applicable.
+
+- **Error codes for clients?**
+  - Not applicable.
+
+## Logging
+
+### What is Logged
+
+- **Security events (auth, access)?**
+  - Nothing is currently logged.
+
+- **Errors with context?**
+  - Errors are not logged; they are printed to `stderr`. Some errors have context (e.g., `trix.Decode` wraps `ErrInvalidMagicNumber`), but this is inconsistent. The `fmt.Errorf("%w: message", err)` pattern should be used more widely to provide better context.
+
+- **Performance metrics?**
+  - Nothing is currently logged.
+
+### What Should NOT be Logged
+
+The application currently does not log anything, so there is no risk of logging sensitive information. If logging is implemented, care must be taken to avoid logging:
+- Passwords/tokens
+- Personally Identifiable Information (PII)
+- Cryptographic keys or sensitive material
+
+### Log Quality
+
+- **Structured logging (JSON)?**
+  - No logging is implemented. Structured logging would be a significant improvement for machine-parsability and analysis.
+
+- **Correlation IDs?**
+  - Not applicable for a single-run CLI tool.
+
+- **Log levels used correctly?**
+  - No logging is implemented.
+
+### Log Security
+
+- **Injection-safe?**
+  - Not applicable as there is no logging.
+
+- **Tamper-evident?**
+  - Not applicable as there is no logging.
+
+- **Retention policy?**
+  - Not applicable as there is no logging.
+
+## Summary & Recommendations
+
+- **Error Handling:** The libraries in `pkg/` follow good practices by returning errors. `cmd/trix` should be improved to intercept these errors, log the technical details, and present a clear, user-friendly message instead of the raw error string. Error wrapping should be used more consistently to add context.
+
+- **Logging:** The complete absence of logging is a major gap. A structured logging library (like `logrus` or the standard library's `slog`) should be introduced in `cmd/trix`. This would allow for different log levels (e.g., controlled by a `--verbose` flag) and provide better insight into the application's behavior, especially during failures.