cli + tui to publish to leaflet (wip) & manage tasks, notes & watch/read lists 馃崈
desertthunder.dev
charm
leaflet
readability
golang
1# CLI Docs
2
3## CommandGroup Interface Pattern
4
5This section outlines the CommandGroup interface pattern for implementing CLI commands in the noteleaf application.
6
7### Core Concepts
8
9Each major command group implements the CommandGroup interface with a `Create() *cobra.Command` method. Command groups receive handlers as constructor dependencies, enabling dependency injection for testing. Handler initialization occurs centrally in main.go with `log.Fatalf` error handling to fail fast during application startup.
10
11### CommandGroup Interface
12
13interface `CommandGroup` provides a consistent contract for all command groups. Each implementation encapsulates related commands and the shared handler dependency. The Create method returns a fully configured cobra command tree.
14
15#### Implementations
16
17TaskCommands handles todo and task-related operations using TaskHandler. MovieCommand manages movie queue operations via MovieHandler.
18TVCommand handles TV show queue operations through TVHandler. NoteCommand manages note operations using NoteHandler.
19
20### Handler Lifecycle
21
22Handlers are created once in `main.go` during application startup. Initialization errors prevent application launch rather than causing runtime failures.
23Handlers persist for the application lifetime without requiring cleanup. Commands access handlers through struct fields rather than creating new instances.
24
25### Testing
26
27`CommandGroup` structs accept handlers as constructor parameters, enabling easy dependency injection of mock handlers for testing.
28Command logic can be tested independently of handler implementations. The interface allows mocking entire command groups for integration testing.
29
30### Registry
31
32`main.go` uses a registry pattern to organize command groups by category. Core commands include task, note, and media functionality.
33Management commands handle configuration, setup, and maintenance operations. The pattern provides clean separation and easy extension for new command groups.
34
35## UI and Styling System
36
37The application uses a structured color palette system located in `internal/ui/colors.go` for consistent terminal output styling.
38
39### Color Architecture
40
41The color system implements a `Key` type with 74 predefined colors from the Charm ecosystem, including warm tones (Cumin, Tang, Paprika), cool tones (Sapphire, Oceania, Zinc), and neutral grays (Pepper through Butter). Each color provides hex values via the `Hex()` method and implements Go's `color.Color` interface through `RGBA()`.
42
43### Predefined Styles
44
45Three core lipgloss styles handle common UI elements:
46
47- `TitleColorStyle` uses color 212 with bold formatting for command titles
48- `SelectedColorStyle` provides white-on-212 highlighting for selected items
49- `HeaderColorStyle` applies color 240 with bold formatting for section headers
50
51### Color Categories
52
53Colors are organized into primary, secondary, and tertiary categories are accessed through `IsPrimary()`, `IsSecondary()`, and `IsTertiary()` methods on the `Key` type.
54
55### Lipgloss Integration
56
57The styling system integrates with the Charmbracelet lipgloss library for terminal UI rendering.
58Colors from the `Key` type convert to lipgloss color values through their `Hex()` method. The predefined `TitleColorStyle`, `SelectedColorStyle`, and `HeaderColorStyle` variables provide lipgloss styles that can be applied to strings with `.Render()`.