Add time track category management to the CLI and TUI

[robzolkos]

HEY users can now list and manage time-track categories from both scripts and the Calendar TUI, so category setup no longer requires the web app. This covers category management only; assigning a category while starting or stopping a timer remains deferred behind the SDK contract tracked in #205.

Review readiness: ✅ Yes
Risk: 🟡 Medium — category deletion is destructive, but the TUI requires confirmation and HEY preserves affected tracks as uncategorized.
Decision: None

✅ Change — category management is available in the CLI and Calendar TUI

Before

timetrack user
└── wants to organize completed tracks
    └── ❌ leaves the CLI/TUI for the HEY web app

After

timetrack user
└── lists categories in the CLI or opens Calendar → c
    ├── ✅ creates and renames categories
    └── ✅ deletes with an explicit TUI confirmation  ← CHANGED

The CLI adds hey timetrack categories and hey timetrack category create|rename|delete. The Calendar TUI uses the SDK's existing typed category methods, blocks overlapping writes while requests are in flight, refreshes after each mutation, and sanitizes server-provided status text before rendering it.

✅ Evidence — automated checks and a development-server interaction cover the workflow

• ✅ TUI interaction recording — opens category management, creates “Client work,” refreshes the list, and reports success against the HEY development server. The temporary category was deleted afterward.
• ✅ CLI request tests cover list/create/rename/delete paths, nested form payloads, structured summaries, and validation without network calls.
• ✅ TUI tests cover load, create, rename, confirmed delete, refresh, blocked overlapping actions, and terminal-control sanitization.
• ✅ Smoke coverage creates, discovers, renames, and deletes a real category on the development server.

GOWORK=off make check       # PASS
GOWORK=off make test-smoke  # PASS; time-track category lifecycle passed

✅ Scope — category CRUD is included; timer assignment remains separate

Included:

• CLI list/create/rename/delete commands and JSON output.
• Calendar TUI category manager and documented shortcuts.
• Unit, request, TUI, and smoke coverage; README, agent skill, API coverage, and CLI surface updates.

Preserved:

• Existing start, stop, current, and list behavior.
• Existing time tracks when a category is deleted; HEY moves them to Uncategorized.
• Existing API and SDK dependencies; there are no new packages, configuration, schema, or runtime services.

Deferred:

• timetrack start/stop --category. The API accepts category_title, while the released SDK update shape still sends category; Timetrack category support is blocked by the current SDK behavior #205 tracks that contract correction.

➖ Delivery — no migration, configuration, or rollout ordering

No migration, backfill, feature flag, configuration, credential, or deployment ordering is required. Rollback is a normal revert; category data remains server-owned and compatible with older CLI versions.

✅ Review decision — no unresolved decision; focus on command shape and TUI state boundaries

Suggested focus:

1. Whether the plural list command plus singular mutation group is the desired CLI shape.
2. The Calendar TUI's loading/mutation gate and confirmed deletion flow.

Known limitation: assigning categories to timer entries is intentionally outside this PR and remains tracked in #205.

✅ Review path — start with command behavior, then TUI state and proof

1. internal/cmd/timetrack.go — CLI command tree, validation, SDK calls, and output.
2. internal/tui/calendar.go and time_track_categories.go — Calendar integration, request gating, interaction state, and rendering.
3. CLI tests, TUI tests, and smoke test — behavior proof.
4. .surface, API-COVERAGE.md, README.md, and skills/hey/SKILL.md — public surface and documentation.

Origin and supporting links: Basecamp card · #205

[Copilot]

Pull request overview

Adds time-track category CRUD to the CLI and Calendar TUI, backed by existing HEY SDK operations.

Changes:

• Adds CLI commands for listing, creating, renaming, and deleting categories.
• Adds an interactive Calendar TUI category manager with deletion confirmation.
• Adds documentation, unit tests, and smoke coverage.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
.surface	Registers the new command surface.
API-COVERAGE.md	Documents category endpoint coverage.
README.md	Documents CLI and TUI usage.
skills/hey/SKILL.md	Adds category-management examples.
internal/cmd/timetrack.go	Implements category CLI commands.
internal/cmd/calendar_commands_test.go	Tests CLI requests and validation.
internal/tui/calendar.go	Integrates category management into Calendar.
internal/tui/calendar_test.go	Updates Calendar help tests.
internal/tui/time_track_categories.go	Implements category-manager state and rendering.
internal/tui/time_track_categories_test.go	Tests TUI category workflows.
tests/smoke/timetrack_test.go	Exercises the category lifecycle end-to-end.

Suppressed comments (1)

internal/cmd/timetrack.go:436

• The summary includes the user-supplied category title for create and rename, then writes it directly to the terminal. Control characters in the argument can therefore emit terminal control sequences. This should follow writeLabelMutation (internal/cmd/label.go:404-409) and sanitize styled output while preserving the structured summary.

		fmt.Fprintln(cmd.OutOrStdout(), summary+".")

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.