Steve Cliff
46 lines
3.2 KiB
Markdown
46 lines
3.2 KiB
Markdown
## Context
|
|
|
|
pcli is a Cobra-based CLI for the Planka project management API. Commands follow a `pcli <resource> <action>` pattern (e.g., `pcli board get`, `pcli card list`). The client layer already provides `ListBoards()` (via `/api/projects`) and `GetBoard(id)` (via `/api/boards/:id`), where `GetBoard` returns the board's lists and cards in the `included` block. Output is handled by `output.Print()` which dispatches to JSON envelope or table rendering based on the `--format` flag.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
- Provide a single top-level `pcli status` command that summarizes all boards, their lists, and card counts
|
|
- Reuse existing client methods with no new API endpoints
|
|
- Support both JSON and table output formats via the existing `--format` flag
|
|
- Show open card counts as the primary number, with closed cards noted separately
|
|
|
|
**Non-Goals:**
|
|
- Concurrent/parallel board fetching (sequential is sufficient for expected board counts)
|
|
- Filtering by project, board, or list (this is a full overview command)
|
|
- Showing card-level detail (names, assignees, due dates) — that's what `card list` is for
|
|
- Caching or incremental updates
|
|
|
|
## Decisions
|
|
|
|
### 1. Top-level command, not a subcommand
|
|
The `status` command will be registered directly on `rootCmd`, not under `board` or any other resource group. It's a cross-cutting summary, not a resource operation.
|
|
|
|
**Alternative considered:** `pcli board status` — rejected because the command spans all boards and is conceptually similar to `git status` as a quick overview.
|
|
|
|
### 2. Data aggregation in the command layer
|
|
The status command will call `ListBoards()` then `GetBoard(id)` for each board, aggregating card counts per list in the command handler. No new client method is needed.
|
|
|
|
**Alternative considered:** A dedicated `client.GetStatus()` method — rejected because there's no single Planka API endpoint for this; the aggregation is purely a CLI concern.
|
|
|
|
### 3. New model types for status data
|
|
A `StatusSummary` struct will hold the aggregated data, containing a slice of `BoardSummary` structs (board name + list summaries), each containing a slice of `ListSummary` structs (list name, open count, closed count). This gives both JSON and table formatters a clean data structure to work with.
|
|
|
|
**Alternative considered:** Reusing existing `Board`/`List` types with card slices — rejected because the status output is a derived summary, not raw API data.
|
|
|
|
### 4. Table output uses per-board sections
|
|
In table format, each board is rendered as a headed section with a list/cards table beneath it. A total board count line appears first. This matches the natural reading pattern for a summary view.
|
|
|
|
### 5. JSON output uses the standard envelope
|
|
JSON output wraps the `StatusSummary` in the existing `{"data": ..., "error": null}` envelope, consistent with all other commands.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- **N+1 API calls** — One `ListBoards` call plus one `GetBoard` per board. For typical usage (< 20 boards) this is fine. If it becomes a problem, concurrent fetching can be added later without changing the interface. → Mitigation: defer optimization until needed.
|
|
- **Stale data between calls** — Board state could change between sequential `GetBoard` calls. → Mitigation: acceptable for a summary view; not a transactional operation.
|