Steve Cliff
50 lines
3.1 KiB
Markdown
50 lines
3.1 KiB
Markdown
## 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/` or `output/` package? (Chose `cmd/` 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)
|