Released v1

2026-02-12 10:37:19 +00:00
commit b07572fed5
77 changed files with 19518 additions and 0 deletions
@@ -0,0 +1,45 @@
+## 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.