Steve Cliff
3.1 KiB
Context
The CLI currently supports read-only operations for projects and boards but lacks write operations. Users must use the web UI to create/delete projects and boards. Additionally, API permission errors return raw HTTP status codes rather than user-friendly guidance. The existing codebase has a clear separation: client layer handles API communication, cmd layer handles CLI commands and output formatting.
Current write operations (cards, comments, labels, tasks) follow a consistent pattern but do not have permission-aware error handling. The API client already returns structured APIError objects with status codes and messages.
Goals / Non-Goals
Goals:
- Enable project and board CRUD operations via CLI
- Provide clear, actionable error messages for permission failures
- Establish a reusable pattern for permission-aware error handling
- Maintain consistency with existing command structure and error handling
Non-Goals:
- Support for Trello import or multipart file uploads
- Changes to existing command behavior
- New authentication mechanisms
- Breaking changes to existing APIs
Decisions
Permission Error Translation Strategy
Chose to handle permission errors at the command layer rather than client layer. This allows context-specific messages (e.g., "requires project manager role" for board creation) while keeping the client layer focused on API communication. The friendlyAPIError helper in cmd/ package translates APIError status codes into human-readable messages.
JSON-only for Board Creation
Board creation API supports multipart/form-data for Trello import, but we're using application/json since we don't support import. This simplifies implementation and reuses the existing Do() method pattern.
Incremental Adoption
The permission error helper is added but existing commands are not modified. This allows the pattern to be proven out with the new commands before being applied elsewhere, reducing risk.
Error Message Design
Permission errors include both the operation context and specific permission requirements. For example: "create board: permission denied (requires project manager role)". This gives users clear guidance on what they need to do.
Risks / Trade-offs
[Risk] API error format changes could break the helper → Mitigation: Helper falls back to original error if status code mapping fails [Risk] Users might expect pre-flight permission checks → Mitigation: Clear error messages explain the permission requirement after the fact [Trade-off] More verbose error messages vs. brevity → Chose actionable messages that guide users to resolution
Migration Plan
No migration needed - this is additive functionality. New commands are added alongside existing ones. The permission error helper can be adopted by existing commands incrementally.
Open Questions
- Should the permission error helper live in
cmd/oroutput/package? (Chosecmd/since it's command-layer logic) - Should we add validation flags like
--dry-run? (Deferred - can add later if needed) - Should board creation support additional optional fields from the API? (Started with minimal viable set)