api: human-readable references, one-shot config errors, quieter logs

[PerishCode]

Why

Dogfooding the CLI from an agent session, fetching one work item (OPEND-372) took four steps: project list for the project UUID, work-item list --all, client-side filtering by sequence_id, then get — because every command demanded UUIDs while humans (and agents reading a Plane board) hold KEY-SEQ identifiers. Two smaller papercuts compounded the cold start: an empty config surfaced its missing settings one error per run (--project → workspace → api_key), and every API call printed an ANSI-colored INFO line to stderr, which pollutes agent transcripts and piped output.

What

• Human-readable references everywhere. New commands/api/reference.rs backs every command: work-item get/update/delete and the work-item sub-resources (comment/link/relation/activity, plus the work-item page commands that landed in feat(cli): add work-item page link commands #14) take <KEY>-<SEQ> directly and make --project optional (the reference carries its project); every other --project flag and the project positional ids accept the project identifier (e.g. OPEND). Resolution reuses the workspace-scoped by-identifier endpoint that attach already shipped with; attach now shares the same parser/resolver instead of a private copy. UUID-shaped input passes through untouched, so scripted UUID flows pay no extra request.

  plane api work-item get OPEND-372            # was: 4 commands + jq
  plane api comment list --work-item OPEND-372
  plane api label list --project OPEND

• One-shot config errors. The new workspace_client helper reports a missing api_key and workspace_slug together with a plane.toml template, instead of one per run.

• Quieter default logging. The per-request calling Plane API lines drop from INFO to DEBUG; --verbose restores them.

Tests

• cargo fmt --all --check, cargo clippy --locked --workspace --all-targets -- -D warnings, cargo test --locked --workspace (99 passing, 6 new cases), plane help smoke — all green (also enforced by the pre-commit hook).

Verified against the production backend (so review can focus on the code, not re-testing):

New reference forms (read): work-item get OPEND-372 (no --project), comment list --work-item OPEND-372, work-item list --project OPEND, project get OPEND, label list --project OPEND, member list --project PLANECLI, dep ls --project PLANECLI, mixed form (UUID work-item + identifier --project), lowercase opend-372 / --project opend, and --workspace flag override.

Full write lifecycle (scratch item PLANECLI-10, deleted afterwards): identifier create → KEY-SEQ get/update → old-form UUID update → KEY-SEQ comment create → attach through the shared resolver → KEY-SEQ delete → post-delete get returns the friendly not-found error.

Backward compatibility: old-form work-item get --project <UUID> <UUID> and project list output byte-identical to the installed v0.1.2 binary (diff empty); old-form comment list / work-item list --json / UUID update all behave unchanged.

Dry-run invariant: with a workspace-only config (no api_key), --dry-run + UUID references still succeeds fully offline; --dry-run + identifier reports the missing api_key as documented below.

Error paths: unknown key (NOPE-999), unknown project identifier, UUID without --project, malformed reference — all return actionable messages; default stderr is silent and --verbose restores the request log.

Compatibility

• --dry-run stays fully offline for UUID references. Human-readable references cost one read-only resolution call first (the same trade dep add already makes to validate its target), so identifier-based --dry-run now needs an api_key. The existing dry-run unit test was updated to pin the UUID-offline invariant.
• --project became optional on work-item get/update/delete and the work-item sub-resources — additive; existing UUID invocations behave identically.
• Help text/value names moved from PROJECT_ID/WORK_ITEM_ID to PROJECT/WORK_ITEM with both forms documented.
• Default stderr no longer carries per-request INFO lines; scripts that grepped them must pass --verbose.
• The by-identifier endpoint answers 403 (not 404) for unknown keys on the production backend; both now map to a friendly "not found or not accessible" error.

Trade-off worth flagging

Non-UUID project references resolve by listing the workspace's projects and matching identifier client-side (no by-identifier endpoint exists for projects). That is one paginated list call per invocation — fine at current workspace sizes; a cache or server-side lookup can come later if it ever shows up in latency.