blob: 2f54cd2a9210ca39248f93e91874bb0b3e9509ed (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
|
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
TaskSamurai is a fast Terminal User Interface (TUI) for Taskwarrior written in Go. It provides a keyboard-driven table interface for task management with extensive hotkey support and real-time integration with the Taskwarrior CLI.
## Development Commands
```bash
# Build the application
mage build
# or simply
mage
# Run the application
mage run
# Run all tests
mage test
# Install to $GOPATH/bin
mage install
# Clean build artifacts
mage clean
# Run with debug logging
./tasksamurai --debug-log debug.log
# Run with custom browser command
./tasksamurai --browser-cmd chromium
# Run with disco mode (random theme changes)
./tasksamurai --disco
```
## Coding best practices
Follow the coding best practices for Go projects as per ~/git/conf/snippets/go/go-projects/gogios.md
## Architecture
### Core Components
1. **cmd/tasksamurai/main.go**: Entry point that initializes flags, creates the UI model, and starts the Bubble Tea program.
2. **internal/task/**: Taskwarrior integration layer
- Executes `task` commands for all CRUD operations
- Parses JSON export format from Taskwarrior
- Handles task filtering, sorting, and statistics calculation
- All operations require the `task` command to be available in PATH
3. **internal/ui/**: Terminal UI implementation using Bubble Tea framework
- Main model in `model.go` handles application state and message processing
- `table.go` manages the task table display
- `input.go` processes keyboard input and executes commands
- `theme.go` handles color themes and disco mode
- Search functionality with regex support in search methods
4. **internal/atable/**: Custom table widget implementation
- Provides flexible table rendering for the task display
- Handles column widths, scrolling, and cell formatting
### Key Design Patterns
- **Message-Driven Architecture**: Uses Bubble Tea's message passing for all UI updates
- **Command Pattern**: All Taskwarrior operations go through the `internal/task` package
- **MVC-like Structure**: Clear separation between data (task), view (table), and control (input handling)
### Integration Points
- **Taskwarrior CLI**: All task operations execute `task` commands via `exec.Command`
- **Terminal**: Uses ANSI escape sequences and terminal control through Bubble Tea
- **External Browser**: Opens URLs via configurable browser command
## Testing Approach
Tests are located alongside implementation files (*_test.go pattern). Key test areas:
- Task operations and JSON parsing in `internal/task/`
- UI component behavior in `internal/ui/`
- Tests create temporary directories for isolated Taskwarrior environments
- Tests check for `task` command availability and skip if not present
Run a single test file:
```bash
go test ./internal/task/task_test.go
```
Run tests for a specific package:
```bash
go test ./internal/ui/
```
## Important Implementation Notes
1. **Taskwarrior Dependency**: The application requires Taskwarrior to be installed and available in PATH. All operations fail gracefully if `task` is not available.
2. **State Management**: The UI state is managed through the main model in `internal/ui/model.go`. State updates happen through Bubble Tea messages.
3. **Error Handling**: Errors from Taskwarrior commands are displayed in the status bar at the bottom of the UI.
4. **Performance**: The table widget uses efficient rendering to handle large task lists. Only visible rows are rendered.
5. **Configuration**: User preferences like browser command and debug logging are passed via command-line flags, not configuration files.
6. **Hotkeys**: Extensive hotkey system defined in `internal/ui/input.go`. See README.md for complete reference.
|
