todo list items

TODO.md

@@ -6,194 +6,199 @@ This document outlines the bugs, issues, and improvements that need to be addres
 
 ### Error Handling and User Experience
 
-- [ ] **Missing Cobra usage printing after errors**: Commands should print usage information when they fail due to incorrect arguments or usage. Need to configure `SilenceUsage: false` and `SilenceErrors: false` on cobra commands.
 
-- [ ] **Inconsistent error messages**: Error messages need standardization and should be user-friendly. Many errors currently expose internal implementation details.
+- [ ] **1. Inappropriate Cobra usage printing**: Commands currently print usage information for all errors, including internal program failures. Usage should only be printed when the user provides incorrect arguments or invalid commands, not when the program encounters internal errors (like file system issues, crypto failures, etc.).
 
-- [ ] **Missing validation for vault names**: Vault names should be validated against a safe character set to prevent filesystem issues.
+- [ ] **2. Inconsistent error messages**: Error messages need standardization and should be user-friendly. Many errors currently expose internal implementation details.
 
-- [ ] **No graceful handling of corrupted state**: If key files are corrupted or missing, the tool should provide clear error messages and recovery suggestions.
+- [ ] **3. Missing validation for vault names**: Vault names should be validated against a safe character set to prevent filesystem issues.
+
+- [ ] **4. No graceful handling of corrupted state**: If key files are corrupted or missing, the tool should provide clear error messages and recovery suggestions.
+
+- [ ] **5.** When GODEBUG contains 'berlin.sneak.pkg.secret', output structured
+debug data to STDERR.  use log/slog.  if stderr is not a tty, output jsonl.  if
+it is a tty, output colorized structured log data in a format similar to
+printf's %#v format.  create a debug logging function that calls a helper
+function to see if the debug logging is enabled, and returns immediately if it
+is not.
 
 ### Core Functionality Bugs
 
-- [ ] Multiple vaults using the same mnemonic will derive the same long-term
-keys.  Adding additional vaults with the same mnemonic should increment the
-index value used.  The mnemonic should be double sha256 hashed and the hash
-value stored in the vault metadata along with the index value (starting at zero)
-and when additional vaults are added with the same mnemonic (as determined by
-hash) then the index value should be incremented.  The README should be updated
-to document this behavior.
+- [ ] **5. Multiple vaults using the same mnemonic will derive the same long-term keys**: Adding additional vaults with the same mnemonic should increment the index value used. The mnemonic should be double sha256 hashed and the hash value stored in the vault metadata along with the index value (starting at zero) and when additional vaults are added with the same mnemonic (as determined by hash) then the index value should be incremented. The README should be updated to document this behavior.
 
-- [ ] **Directory structure inconsistency**: The README and test script reference different directory structures:
+- [ ] **6. Directory structure inconsistency**: The README and test script reference different directory structures:
   - Current code uses `unlock.d/` but documentation shows `unlock-keys.d/`
   - Secret files use inconsistent naming (`secret.age` vs `value.age`)
 
-- [ ] **Symlink handling on non-Unix systems**: The symlink resolution in `resolveVaultSymlink()` may fail on Windows or in certain environments.
+- [ ] **7. Symlink handling on non-Unix systems**: The symlink resolution in `resolveVaultSymlink()` may fail on Windows or in certain environments.
 
-- [ ] **Missing current unlock key initialization**: When creating vaults, no default unlock key is selected, which can cause operations to fail.
+- [ ] **8. Missing current unlock key initialization**: When creating vaults, no default unlock key is selected, which can cause operations to fail.
 
-- [ ] **Race conditions in file operations**: Multiple concurrent operations could corrupt the vault state due to lack of file locking.
+- [ ] **9. Race conditions in file operations**: Multiple concurrent operations could corrupt the vault state due to lack of file locking.
 
 ### Security Issues
 
-- [ ] **Insecure temporary file handling**: Temporary files containing sensitive data may not be properly cleaned up or secured.
+- [ ] **10. Insecure temporary file handling**: Temporary files containing sensitive data may not be properly cleaned up or secured.
 
-- [ ] **Missing secure memory clearing**: Sensitive data in memory (passphrases, keys) should be cleared after use.
+- [ ] **11. Missing secure memory clearing**: Sensitive data in memory (passphrases, keys) should be cleared after use.
 
-- [ ] **Weak default permissions**: Some files may be created with overly permissive default permissions.
+- [ ] **12. Weak default permissions**: Some files may be created with overly permissive default permissions.
 
 ## Important (Should be fixed before release)
 
 ### User Interface Improvements
 
-- [ ] **Add confirmation prompts for destructive operations**: Operations like `keys rm` and vault deletion should require confirmation.
+- [ ] **13. Add confirmation prompts for destructive operations**: Operations like `keys rm` and vault deletion should require confirmation.
 
-- [ ] **Improve progress indicators**: Long operations (key generation, encryption) should show progress.
+- [ ] **14. Improve progress indicators**: Long operations (key generation, encryption) should show progress.
 
-- [ ] **Better secret name validation**: Currently allows some characters that may cause issues, needs comprehensive validation.
+- [ ] **15. Better secret name validation**: Currently allows some characters that may cause issues, needs comprehensive validation.
 
-- [ ] **Add `--help` examples**: Command help should include practical examples for each operation.
+- [ ] **16. Add `--help` examples**: Command help should include practical examples for each operation.
 
 ### Command Implementation Gaps
 
-- [ ] **`secret keys rm` not fully implemented**: Based on test output, this command may not be working correctly.
+- [ ] **17. `secret keys rm` not fully implemented**: Based on test output, this command may not be working correctly.
 
-- [ ] **`secret key select` not fully implemented**: Key selection functionality appears incomplete.
+- [ ] **18. `secret key select` not fully implemented**: Key selection functionality appears incomplete.
 
-- [ ] **Missing vault deletion command**: No way to delete vaults that are no longer needed.
+- [ ] **19. Missing vault deletion command**: No way to delete vaults that are no longer needed.
 
-- [ ] **No secret deletion command**: Missing `secret rm <secret-name>` functionality.
+- [ ] **20. No secret deletion command**: Missing `secret rm <secret-name>` functionality.
 
-- [ ] **Missing secret history/versioning**: No way to see previous versions of secrets or restore old values.
+- [ ] **21. Missing secret history/versioning**: No way to see previous versions of secrets or restore old values.
 
 ### Configuration and Environment
 
-- [ ] **Global configuration not fully implemented**: The `configuration.json` file structure exists but isn't used consistently.
+- [ ] **22. Global configuration not fully implemented**: The `configuration.json` file structure exists but isn't used consistently.
 
-- [ ] **Missing environment variable validation**: Environment variables should be validated for format and security.
+- [ ] **23. Missing environment variable validation**: Environment variables should be validated for format and security.
 
-- [ ] **No configuration file validation**: JSON configuration files should be validated against schemas.
+- [ ] **24. No configuration file validation**: JSON configuration files should be validated against schemas.
 
 ### PGP Integration Issues
 
-- [ ] **Incomplete PGP unlock key implementation**: The `--keyid` parameter processing may not be fully working.
+- [ ] **25. Incomplete PGP unlock key implementation**: The `--keyid` parameter processing may not be fully working.
 
-- [ ] **Missing GPG agent integration**: Should detect and use existing GPG agent when available.
+- [ ] **26. Missing GPG agent integration**: Should detect and use existing GPG agent when available.
 
-- [ ] **No validation of GPG key existence**: Should verify the specified GPG key exists before creating PGP unlock keys.
+- [ ] **27. No validation of GPG key existence**: Should verify the specified GPG key exists before creating PGP unlock keys.
 
 ### Cross-Platform Issues
 
-- [ ] **macOS Keychain error handling**: Better error messages when biometric authentication fails or isn't available.
+- [ ] **28. macOS Keychain error handling**: Better error messages when biometric authentication fails or isn't available.
 
-- [ ] **Windows path handling**: File paths may not work correctly on Windows systems.
+- [ ] **29. Windows path handling**: File paths may not work correctly on Windows systems.
 
-- [ ] **XDG compliance on Linux**: Should respect `XDG_CONFIG_HOME` and other XDG environment variables.
+- [ ] **30. XDG compliance on Linux**: Should respect `XDG_CONFIG_HOME` and other XDG environment variables.
 
 ## Trivial (Nice to have)
 
 ### Code Quality
 
-- [ ] **Add more comprehensive unit tests**: Current test coverage could be improved, especially for error conditions.
+- [ ] **31. Add more comprehensive unit tests**: Current test coverage could be improved, especially for error conditions.
 
-- [ ] **Reduce code duplication**: Several functions have similar patterns that could be refactored.
+- [ ] **32. Reduce code duplication**: Several functions have similar patterns that could be refactored.
 
-- [ ] **Improve function documentation**: Many functions lack proper Go documentation comments.
+- [ ] **33. Improve function documentation**: Many functions lack proper Go documentation comments.
 
-- [ ] **Add static analysis**: Integrate tools like `staticcheck`, `golangci-lint` with more linters.
+- [ ] **34. Add static analysis**: Integrate tools like `staticcheck`, `golangci-lint` with more linters.
 
 ### Performance Optimizations
 
-- [ ] **Cache unlock key operations**: Avoid re-reading unlock key metadata on every operation.
+- [ ] **35. Cache unlock key operations**: Avoid re-reading unlock key metadata on every operation.
 
-- [ ] **Optimize file I/O**: Batch file operations where possible to reduce syscalls.
+- [ ] **36. Optimize file I/O**: Batch file operations where possible to reduce syscalls.
 
-- [ ] **Add connection pooling for HSM operations**: For hardware security module operations.
+- [ ] **37. Add connection pooling for HSM operations**: For hardware security module operations.
 
 ### User Experience Enhancements
 
-- [ ] **Add shell completion**: Bash/Zsh completion for commands and secret names.
+- [ ] **38. Add shell completion**: Bash/Zsh completion for commands and secret names.
 
-- [ ] **Colored output**: Use colors to improve readability of lists and error messages.
+- [ ] **39. Colored output**: Use colors to improve readability of lists and error messages.
 
-- [ ] **Add `--quiet` flag**: Option to suppress non-essential output.
+- [ ] **40. Add `--quiet` flag**: Option to suppress non-essential output.
 
-- [ ] **Smart secret name suggestions**: When a secret name is not found, suggest similar names.
+- [ ] **41. Smart secret name suggestions**: When a secret name is not found, suggest similar names.
 
 ### Additional Features
 
-- [ ] **Secret templates**: Predefined templates for common secret types (database URLs, API keys, etc.).
+- [ ] **42. Secret templates**: Predefined templates for common secret types (database URLs, API keys, etc.).
 
-- [ ] **Bulk operations**: Import/export multiple secrets at once.
+- [ ] **43. Bulk operations**: Import/export multiple secrets at once.
 
-- [ ] **Secret sharing**: Secure sharing of secrets between vaults or users.
+- [ ] **44. Secret sharing**: Secure sharing of secrets between vaults or users.
 
-- [ ] **Audit logging**: Log all secret access and modifications.
+- [ ] **45. Audit logging**: Log all secret access and modifications.
 
-- [ ] **Integration tests for hardware features**: Automated testing of Keychain and GPG functionality.
+- [ ] **46. Integration tests for hardware features**: Automated testing of Keychain and GPG functionality.
 
 ### Documentation
 
-- [ ] **Man pages**: Generate and install proper Unix man pages.
+- [ ] **47. Man pages**: Generate and install proper Unix man pages.
 
-- [ ] **API documentation**: Document the internal API for potential library use.
+- [ ] **48. API documentation**: Document the internal API for potential library use.
 
-- [ ] **Migration guide**: Document how to migrate from other secret managers.
+- [ ] **49. Migration guide**: Document how to migrate from other secret managers.
 
-- [ ] **Security audit documentation**: Document security assumptions and threat model.
+- [ ] **50. Security audit documentation**: Document security assumptions and threat model.
 
 ## Architecture Improvements
 
 ### Code Structure
 
-- [ ] **Consistent interface implementation**: Ensure all unlock key types properly implement the UnlockKey interface.
+- [ ] **51. Consistent interface implementation**: Ensure all unlock key types properly implement the UnlockKey interface.
 
-- [ ] **Better separation of concerns**: Some functions in CLI do too much and should be split.
+- [ ] **52. Better separation of concerns**: Some functions in CLI do too much and should be split.
 
-- [ ] **Improved error types**: Create specific error types instead of using generic `fmt.Errorf`.
+- [ ] **53. Improved error types**: Create specific error types instead of using generic `fmt.Errorf`.
 
 ### Testing Infrastructure
 
-- [ ] **Mock filesystem consistency**: Ensure mock filesystem behavior matches real filesystem in all cases.
+- [ ] **54. Mock filesystem consistency**: Ensure mock filesystem behavior matches real filesystem in all cases.
 
-- [ ] **Integration test isolation**: Tests should not affect each other or the host system.
+- [ ] **55. Integration test isolation**: Tests should not affect each other or the host system.
 
-- [ ] **Performance benchmarks**: Add benchmarks for crypto operations and file I/O.
+- [ ] **56. Performance benchmarks**: Add benchmarks for crypto operations and file I/O.
 
 ## Technical Debt
 
-- [ ] **Remove unused code**: Clean up any dead code or unused imports.
+- [ ] **57. Remove unused code**: Clean up any dead code or unused imports.
 
-- [ ] **Standardize JSON schemas**: Create proper JSON schemas for all configuration files.
+- [ ] **58. Standardize JSON schemas**: Create proper JSON schemas for all configuration files.
 
-- [ ] **Improve error propagation**: Many functions swallow important context in error messages.
+- [ ] **59. Improve error propagation**: Many functions swallow important context in error messages.
 
-- [ ] **Consistent naming conventions**: Some variables and functions use inconsistent naming.
+- [ ] **60. Consistent naming conventions**: Some variables and functions use inconsistent naming.
 
 ## Development Workflow
 
-- [ ] **Add pre-commit hooks**: Ensure code quality and formatting before commits.
+- [ ] **61. Add pre-commit hooks**: Ensure code quality and formatting before commits.
 
-- [ ] **Continuous integration**: Set up CI/CD pipeline with automated testing.
+- [ ] **62. Continuous integration**: Set up CI/CD pipeline with automated testing.
 
-- [ ] **Release automation**: Automate the build and release process.
+- [ ] **63. Release automation**: Automate the build and release process.
 
-- [ ] **Dependency management**: Regular updates and security scanning of dependencies.
+- [ ] **64. Dependency management**: Regular updates and security scanning of dependencies.
 
 ---
 
 ## Priority Assessment
 
-**Critical items** block the 1.0 release and must be fixed for basic functionality and security.
+**Critical items** (1-12) block the 1.0 release and must be fixed for basic functionality and security.
 
-**Important items** should be addressed for a polished user experience but don't block the release.
+**Important items** (13-30) should be addressed for a polished user experience but don't block the release.
 
-**Trivial items** are enhancements that can be addressed in future releases.
+**Trivial items** (31-50) are enhancements that can be addressed in future releases.
+
+**Architecture and Infrastructure** (51-64) are longer-term improvements for maintainability and development workflow.
 
 ## Estimated Timeline
 
-- Critical: 2-3 weeks
-- Important: 3-4 weeks  
-- Trivial: Ongoing post-1.0
+- Critical (1-12): 2-3 weeks
+- Important (13-30): 3-4 weeks  
+- Trivial (31-50): Ongoing post-1.0
+- Architecture/Infrastructure (51-64): Ongoing post-1.0
 
 Total estimated time to 1.0: 5-7 weeks with focused development effort.