Steve Cliff
67 lines
3.0 KiB
Markdown
67 lines
3.0 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
PCLI is a Go CLI tool for interacting with the Planka (v2.0) project management API. It uses the Cobra framework with minimal dependencies (only Cobra + standard library).
|
|
|
|
## Build & Test Commands
|
|
|
|
```bash
|
|
go build -o pcli . # Build for development
|
|
./build.sh # Multi-platform release build (linux/darwin/windows)
|
|
./test.sh # Integration tests (requires live Planka instance)
|
|
```
|
|
|
|
Integration tests require `PLANKA_URL` and `PLANKA_API_KEY` environment variables pointing to a running Planka instance.
|
|
|
|
There is no unit test suite or linter configured — tests are shell-based integration tests in `test.sh`.
|
|
|
|
## Architecture
|
|
|
|
**Entry point**: `main.go` → `cmd.Execute()`
|
|
|
|
**Package layout**:
|
|
- `cmd/` — Cobra command definitions, one file per resource (project.go, board.go, card.go, etc.)
|
|
- `client/` — HTTP API client, one file per resource matching cmd/ structure
|
|
- `model/types.go` — All domain types (Project, Board, Card, List, Label, Task, Comment, etc.)
|
|
- `output/output.go` — Dual-format output: JSON envelope (`{data, error}`) or human-readable table via tabwriter
|
|
- `logging/logging.go` — slog-based structured JSON logging to stderr
|
|
|
|
**Command hierarchy**: `pcli <resource> <action>` (e.g., `pcli card create --list <id> --name "task"`)
|
|
|
|
**Key patterns**:
|
|
- Global flags (`--format`, `--url`, `--api-key`, `--log-level`) set in `cmd/root.go` PersistentPreRunE, which validates config and initializes the API client
|
|
- Client methods follow `List*/Get*/Create*/Update*/Delete*` naming
|
|
- API responses use typed structs with included relationships (e.g., board responses include lists and cards)
|
|
- `friendlyAPIError()` in `cmd/errors.go` translates HTTP status codes to contextual messages
|
|
- `DoWithFallback` in client supports trying alternate API endpoint patterns
|
|
- Output uses reflection-based table rendering per type
|
|
|
|
**Configuration**: Environment variables `PLANKA_URL` and `PLANKA_API_KEY`, overridable via CLI flags.
|
|
|
|
## Adding a New Resource
|
|
|
|
1. Define model structs in `model/types.go`
|
|
2. Add client methods in `client/<resource>.go`
|
|
3. Add command definitions in `cmd/<resource>.go` with subcommands (list, get, create, update, delete)
|
|
4. Wire the parent command into `root.go` init()
|
|
|
|
## Planka Sync
|
|
|
|
**IMPORTANT**
|
|
After completing any opsx workflow (/opsx:new, /opsx:ff, /opsx:continue,
|
|
/opsx:apply, /opsx:verify, /opsx:archive, /opsx:bulk-archive), automatically
|
|
reconcile Planka board state by running the sync script:
|
|
|
|
```bash
|
|
PROJECT_NAME=$(yq -r '.planka.project' project.yaml)
|
|
BOARD_NAME=$(yq -r '.planka.board' project.yaml)
|
|
kanban-project-sync --project "$PROJECT_NAME" --board "$BOARD_NAME" --background
|
|
```
|
|
|
|
The script handles concurrency (flock-based locking with coalescing pending queue).
|
|
If the script is not on PATH or fails, log a brief warning and continue.
|
|
Never block or retry — Planka sync is best-effort.
|