# Todo CLI

A powerful command-line todo manager with time tracking, project management, and comprehensive reporting.

## TL;DR

```bash
# Install
pip install -e .

# Add a task and start tracking time
todo add "My first task"
todo start 1

# When done
todo stop
todo done 1

# See all your todos
todo list
```

That's it! You're tracking tasks with time. Run `todo --help` for more.

## Features

- ✅ **Task Management** - Add, edit, delete, and organize tasks
- ⏱️ **Time Tracking** - Track time spent on tasks with start/stop timers
- 📁 **Project Organization** - Group tasks into projects with full CRUD operations
- 🔍 **Smart Filtering** - Filter tasks by project, status, priority, and tags
- 📊 **Reports** - Daily, weekly, and project-based time reports
- 📤 **Export** - Export to JSON, CSV, or Markdown
- 🎨 **Interactive Mode** - Full-featured TUI for task management
- ⚙️ **Configurable** - Customize priorities, date formats, colors, and more
- 🚀 **Performance** - Optimized database queries with comprehensive indexing
- 🧪 **Well-Tested** - 87% test coverage with 313+ tests

## Installation

```bash
pip install -e .
```

**For existing users:** If you have an existing todo database, it will be automatically migrated to the new schema. See [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md) for details.

## Quick Start

### Basic Task Management

```bash
# Add a task
todo add "Write documentation"

# Add with priority and tags
todo add "Fix bug #123" -p p0 --tags bug urgent

# Add with due date
todo add "Submit report" --due 2025-12-31

# List all active tasks
todo list

# List with filters
todo list --status doing
todo list --project myapp

# Mark as done
todo done 1
```

### Project Management

```bash
# Create a project
todo project create "My App" --description "Mobile app development" --color cyan

# List all projects
todo project list

# Show project details and statistics
todo project show "My App"

# Add tasks to a project
todo add "Design login screen" -P "My App"

# Filter tasks by project
todo list --project "My App"

# Archive a project
todo project archive "My App"

# Delete a project (tasks remain unassigned)
todo project delete "My App"
```

### Time Tracking

```bash
# Start tracking time on a task
todo start 1

# Check what's currently being tracked
todo active

# Stop tracking
todo stop

# View time spent when marking done
todo done 1
```

### Reports

```bash
# Daily report (time spent today)
todo report daily

# Weekly report (time spent this week)
todo report weekly

# Project overview (all projects with stats)
todo report project

# Specific project report
todo report project "My App"
```

### Export

```bash
# Export to JSON
todo export json todos.json

# Export to CSV
todo export csv todos.csv

# Export to Markdown
todo export md todos.md

# Export specific project
todo export json myapp.json --project "My App"
```

## Commands

### Task Commands

- `add` - Add a new todo
  ```bash
  todo add "Task description" [-p PRIORITY] [-P PROJECT] [--tags TAG...] [--due DATE]
  ```

- `list` - List todos with optional filters
  ```bash
  todo list [--project PROJECT] [--status STATUS] [--all]
  ```

- `show` - Show detailed information about a todo
  ```bash
  todo show <id>
  ```

- `done` - Mark todo as complete
  ```bash
  todo done <id>
  ```

- `delete` - Delete a todo
  ```bash
  todo delete <id> [--force]
  ```

- `edit` - Edit a todo's properties
  ```bash
  todo edit <id> [--task TEXT] [--priority PRIORITY] [--project PROJECT] [--tags TAG...]
  ```

- `status` - Change todo status (todo/doing/done)
  ```bash
  todo status <id> <status>
  ```

### Project Commands

- `project create` - Create a new project
  ```bash
  todo project create <name> [--description TEXT] [--color COLOR]
  ```

- `project list` - List all projects with statistics
  ```bash
  todo project list [--archived]
  ```

- `project show` - Show project details and task breakdown
  ```bash
  todo project show <name>
  ```

- `project edit` - Edit project properties
  ```bash
  todo project edit <name> [--name NEW_NAME] [--description TEXT] [--color COLOR]
  ```

- `project archive` - Archive a project (hide from active list)
  ```bash
  todo project archive <name>
  ```

- `project unarchive` - Restore an archived project
  ```bash
  todo project unarchive <name>
  ```

- `project delete` - Delete a project (tasks become unassigned)
  ```bash
  todo project delete <name>
  ```

### Time Tracking Commands

- `start` - Start time tracking on a task
  ```bash
  todo start <id>
  ```

- `stop` - Stop time tracking
  ```bash
  todo stop [<id>]
  ```

- `active` - Show currently tracking task
  ```bash
  todo active
  ```

### Reporting & Export

- `report` - Generate time reports
  ```bash
  todo report daily [--date DATE]
  todo report weekly [--date DATE]
  todo report project [PROJECT_NAME]
  ```

- `export` - Export todos to various formats
  ```bash
  todo export <format> [output_file] [--project PROJECT] [--include-done]
  ```
  Supported formats: `json`, `csv`, `md`/`markdown`

### Other Commands

- `stats` - Show overall statistics
  ```bash
  todo stats
  ```

- `interactive` - Launch interactive mode (TUI)
  ```bash
  todo interactive
  ```

- `config` - View or modify configuration
  ```bash
  todo config show
  todo config set <key> <value>
  todo config path
  ```

- `version` - Show version information
  ```bash
  todo version
  ```

## Configuration

Customize Todo CLI behavior through the config file (`~/.config/todo-cli/config.yaml`):

```yaml
# Default priority for new tasks (p0, p1, p2, p3)
default_priority: p2

# Date format (YYYY-MM-DD, MM/DD/YYYY, DD/MM/YYYY)
date_format: YYYY-MM-DD

# Time format (24h, 12h)
time_format: 24h

# Color scheme (auto, none)
color_scheme: auto

# Confirm before deleting tasks
confirm_delete: true

# Auto-start timer when adding tasks
auto_start_on_add: false

# Show completed tasks in list by default
show_completed_in_list: false
```

View and modify configuration:

```bash
# Show all configuration
todo config show

# Set a value
todo config set default_priority p1
todo config set confirm_delete false

# Show config file location
todo config path
```

## Interactive Mode

Launch a full-featured terminal UI with `todo interactive`:

- **Menu-driven interface** - Navigate with arrow keys
- **All commands available** - Add, edit, delete, start/stop timers
- **Real-time updates** - See changes immediately
- **Keyboard shortcuts** - Fast command execution
- **Command aliases** - `l` for list, `d` for done, etc.

## Database & Migrations

Todo CLI uses SQLite for data storage with automatic schema migrations.

**Default database location:** `~/.local/share/todo-cli/todos.db`

**Automatic migrations:** When you upgrade Todo CLI, your database is automatically migrated to the latest schema version. Backups are created before each migration.

**For existing users:** See [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md) for details on upgrading from older versions.

## Performance

Todo CLI is designed for speed:

- ✅ List 1000 tasks: <100ms
- ✅ Filter by project: <100ms
- ✅ Project statistics: <200ms
- ✅ Comprehensive database indexing for optimal query performance

See [docs/performance.md](docs/performance.md) for detailed benchmarks.

## Development

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=todo_cli --cov-report=term-missing

# Run specific test file
pytest tests/test_projects.py

# Run performance benchmarks
pytest tests/test_performance.py
```

### Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing guidelines, and contribution workflow.

## Project Structure

```
todo-cli/
├── todo_cli/           # Main package
│   ├── main.py         # CLI entry point and commands
│   ├── database.py     # Database operations
│   ├── projects.py     # Project management
│   ├── migrations.py   # Database migrations
│   ├── models.py       # Data models
│   ├── config.py       # Configuration management
│   ├── display.py      # Terminal output formatting
│   ├── reports.py      # Report generation
│   ├── export.py       # Export functionality
│   └── interactive.py  # Interactive mode
├── tests/              # Test suite (313+ tests, 87% coverage)
├── docs/               # Documentation
│   ├── architecture.md # System architecture and design
│   └── performance.md  # Performance benchmarks
├── README.md           # This file
├── CONTRIBUTING.md     # Development guide
└── MIGRATION_GUIDE.md  # Migration instructions
```

## Roadmap

### Epic 1: Foundation ✅ (Complete)
- ✅ Project management with full CRUD operations
- ✅ Database schema v1 with migrations
- ✅ Smart filtering by project, status, priority
- ✅ Performance optimization and benchmarking
- ✅ Comprehensive test coverage (87%)

### Epic 2: Sub-tasks (Planned)
- Hierarchical task relationships
- Tree view for task lists
- Parent-child task dependencies
- Nested time tracking

### Epic 3: KANBAN Board (Planned)
- Visual board view (Todo/Doing/Done columns)
- Drag-and-drop task movement (TUI)
- Column customization
- Workflow automation

### Epic 4: Cycles & Sprints (Planned)
- Sprint/iteration management
- Cycle-based task organization
- Sprint planning and retrospectives
- Burndown charts

## License

See [LICENSE](LICENSE) file for details.

## Support

- **Documentation:** See [docs/](docs/) directory
- **Issues:** Report bugs or request features via GitHub Issues
- **Contributing:** See [CONTRIBUTING.md](CONTRIBUTING.md)

## Changelog

### v1.1.0-alpha (Epic 1 Release)

**New Features:**
- Project management with create, list, show, edit, archive, delete operations
- Project-based task filtering with `--project` flag
- Database schema v1 with automatic migrations
- Comprehensive performance optimizations (all queries <200ms)
- Project statistics and reporting

**Improvements:**
- Added 313+ tests with 87% coverage
- Comprehensive database indexing for optimal performance
- Enhanced filtering capabilities (project + status combinations)
- Backward compatibility with legacy project strings

**Migration:**
- Existing databases automatically migrated to v1 schema
- Legacy project strings converted to project references
- See MIGRATION_GUIDE.md for details

---

Built with ❤️ using Python, Typer, and Rich.
