Added create and delete operations for projects and boards with validation and error handling

2026-02-17 07:47:49 +00:00
parent c03d05734a
commit c15a48cda3
15 changed files with 571 additions and 4 deletions
@@ -0,0 +1,49 @@
+## 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)