cli-task-manager-ronel 1.0.0
A production-ready CLI task management application with colors, priorities, and statistics
Requires Python: >=3.8

# CLI Task Manager

A production-ready, feature-rich command-line task management application with colorful output, comprehensive testing, and advanced features.

## Features

### Core Functionality
- Add Tasks - Create tasks with titles, priorities, and due dates
- List Tasks - View all tasks in a formatted, colored table
- Complete Tasks - Mark tasks as done with timestamps
- Delete Tasks - Remove tasks permanently
- Update Tasks - Modify task titles
- Filter Tasks - Show tasks by status (pending/in_progress/completed)

### Advanced Features (Phase 6)
- Search - Find tasks by keyword
- Priorities - Set task priority (low/medium/high)
- Due Dates - Assign and track deadlines
- Statistics - View comprehensive task analytics
- Colorful Output - Cross-platform colored terminal
- 90%+ Test Coverage - Comprehensive unit tests

## Color Scheme

| Color | Usage | Example |
|-------|-------|---------|
| Green | Success, Completed | Task added, Completed |
| Red | Errors, High Priority | Task not found, High |
| Yellow | Warnings, Pending, Medium | Warning, Medium |
| Blue | Info, In Progress, Low | Info, Low |
| Cyan | Info messages | Task counts |

## Installation
```bash
git clone <your-repo-url>
cd task-manager
pip install -r requirements.txt
```

### Requirements
- Python 3.8+
- tabulate>=0.9.0 - Table formatting
- colorama>=0.4.6 - Cross-platform colors
- pytest>=7.4.0 - Testing framework
- pytest-cov>=4.0.0 - Coverage reporting

## Quick Start
```bash
python main.py add "Buy groceries"
python main.py add "Complete report" --priority high --due 2026-01-15
python main.py list
python main.py list --status pending
python main.py search "groceries"
python main.py complete 1
python main.py priority 2 high
python main.py due 2 2026-01-20
python main.py stats
python main.py delete 3
```

## Commands Reference

### Add Task
```bash
python main.py add "Task title" [--priority low|medium|high] [--due YYYY-MM-DD]
```

Examples:
```bash
python main.py add "Buy milk"
python main.py add "Finish project" --priority high
python main.py add "Submit report" --priority high --due 2026-01-20
```

### List Tasks
```bash
python main.py list [--status pending|in_progress|completed]
```

Examples:
```bash
python main.py list
python main.py list --status completed
```

### Complete Task
```bash
python main.py complete <task_id>
```

### Delete Task
```bash
python main.py delete <task_id>
```

### Update Task
```bash
python main.py update <task_id> "New title"
```

### Search Tasks
```bash
python main.py search "keyword"
```

### Set Priority
```bash
python main.py priority <task_id> low|medium|high
```

### Set Due Date
```bash
python main.py due <task_id> YYYY-MM-DD
```

### View Statistics
```bash
python main.py stats
```

## Statistics Example
```bash
$ python main.py stats

Task Statistics

Status Overview:
   Total Tasks: 5
   Pending: 2 (40%)
   In Progress: 1 (20%)
   Completed: 2 (40%)

Priority:
   High: 2

Due Dates:
   Due Today: 1
   Overdue: 0

Performance:
   Avg. Completion Time: 2.5 days
```

## Running Tests
```bash
pytest
pytest --cov
pytest --cov --cov-report=term-missing
pytest tests/test_task_manager.py
pytest --cov --cov-report=html
```

Expected Coverage: 90%+

## Project Structure
```
task-manager/
├── main.py              # CLI entry point
├── task_manager.py      # Core business logic
├── file_handler.py      # JSON operations & migration
├── constants.py         # Configuration & colors
├── ui_helpers.py        # Color utility functions
├── tasks.json           # Data storage (auto-created)
├── requirements.txt     # Dependencies
├── pyproject.toml       # Pytest configuration
├── README.md            # Documentation
└── tests/               # Unit tests
    ├── conftest.py      # Pytest fixtures
    ├── test_file_handler.py
    ├── test_task_manager.py
    └── test_main.py
```

## Task Data Structure
```json
{
  "version": "2.0",
  "last_updated": "2026-01-11 10:00:00",
  "tasks": [
    {
      "id": 1,
      "title": "Buy groceries",
      "status": "pending",
      "priority": "medium",
      "due_date": "2026-01-15",
      "created_at": "2026-01-11 09:00:00",
      "completed_at": null
    }
  ]
}
```

## Data Migration

The application automatically migrates old task formats to the new schema.

Old Format (v1.0):
```json
[
  {
    "id": 1,
    "title": "Task",
    "status": "pending",
    "created_at": "2026-01-10"
  }
]
```

New Format (v2.0) automatically adds:
- priority (default: "medium")
- due_date (default: null)
- completed_at (default: null)
- Version metadata

## Validation Rules

- Title Length: 1-200 characters
- Task ID: Positive integers only
- Priority: low, medium, or high
- Due Date: YYYY-MM-DD format
- Status: pending, in_progress, or completed

## Disabling Colors

Colors are automatically disabled when:
- Output is redirected (> file.txt)
- Terminal doesn't support colors

Manual disable in constants.py:
```python
USE_COLORS = False
```

## Example Session
```bash
$ python main.py add "Buy groceries" --priority high --due 2026-01-15
Task added successfully (ID: 1)
   "Buy groceries"
   Priority: high
   Due: 2026-01-15

$ python main.py add "Write documentation" --priority medium
Task added successfully (ID: 2)
   "Write documentation"
   Priority: medium

$ python main.py list

+----+----------------------+-----------+-----------+------------+---------------------+
| ID | Title                | Status    | Priority  | Due Date   | Created At          |
+====+======================+===========+===========+============+=====================+
|  1 | Buy groceries        | Pending   | High      | 2026-01-15 | 2026-01-11 10:00:00 |
|  2 | Write documentation  | Pending   | Medium    | -          | 2026-01-11 10:01:00 |
+----+----------------------+-----------+-----------+------------+---------------------+

Total tasks: 2

$ python main.py complete 1
Task 1 marked as completed!
   "Buy groceries"

$ python main.py search "doc"
Found 1 task(s) matching: "doc"

+----+----------------------+-----------+-----------+
| ID | Title                | Status    | Priority  |
+====+======================+===========+===========+
|  2 | Write documentation  | Pending   | Medium    |
+----+----------------------+-----------+-----------+

$ python main.py stats

Task Statistics

Status Overview:
   Total Tasks: 2
   Pending: 1 (50%)
   In Progress: 0 (0%)
   Completed: 1 (50%)

Priority:
   High: 1

Due Dates:
   Due Today: 0
   Overdue: 0

Performance:
   Avg. Completion Time: 0.0 days
```

## Testing Guide

### Install Test Dependencies
```bash
pip install -r requirements.txt
```

### Run Tests
```bash
pytest
pytest -v
pytest --cov
pytest --cov --cov-report=term-missing
pytest --cov --cov-report=html
```

### Expected Test Output
```bash
$ pytest -v

================================ test session starts =================================
collected 25 items

tests/test_file_handler.py::test_read_empty_file PASSED                        [  4%]
tests/test_file_handler.py::test_write_and_read_tasks PASSED                   [  8%]
tests/test_file_handler.py::test_read_corrupted_json PASSED                    [ 12%]
tests/test_task_manager.py::test_add_task_success PASSED                       [ 52%]
tests/test_task_manager.py::test_complete_task_success PASSED                  [ 68%]
tests/test_task_manager.py::test_search_tasks_found PASSED                     [ 92%]

================================ 25 passed in 1.23s ==================================
```

### Coverage Report Example
```bash
$ pytest --cov --cov-report=term-missing

---------- coverage: platform win32, python 3.11.0 -----------
Name                    Stmts   Miss  Cover   Missing
-----------------------------------------------------
constants.py               45      2    96%   12-13
file_handler.py            78      4    95%   23, 67, 89, 103
main.py                    56      8    86%   72-76, 95-98
task_manager.py           145      8    94%   45, 78, 112, 156
ui_helpers.py              82      5    94%   34, 67, 89, 112
-----------------------------------------------------
TOTAL                     406     27    93%
```

## Example tasks.json (Schema v2.0)
```json
{
  "version": "2.0",
  "last_updated": "2026-01-11 14:30:00",
  "tasks": [
    {
      "id": 1,
      "title": "Buy groceries",
      "status": "completed",
      "priority": "high",
      "due_date": "2026-01-15",
      "created_at": "2026-01-11 09:00:00",
      "completed_at": "2026-01-11 12:30:00"
    },
    {
      "id": 2,
      "title": "Write documentation",
      "status": "in_progress",
      "priority": "medium",
      "due_date": "2026-01-20",
      "created_at": "2026-01-11 10:00:00",
      "completed_at": null
    },
    {
      "id": 3,
      "title": "Review pull requests",
      "status": "pending",
      "priority": "low",
      "due_date": null,
      "created_at": "2026-01-11 11:00:00",
      "completed_at": null
    }
  ]
}
```

## Success Checklist

- Phase 1 - Foundation (add, list)
- Phase 2 - Complete & delete features
- Phase 3 - Refactoring & status filtering
- Phase 4 - Color polish & cross-platform support
- Phase 5 - Testing & validation (90%+ coverage)
- Phase 6 - Advanced features (search, priority, stats)

### Verification Commands
```bash
pytest
pytest --cov
python main.py add "Test"
python main.py list
python main.py search "test"
python main.py priority 1 high
python main.py stats
```

## Deployment Checklist

- All tests pass (pytest)
- Coverage >= 90% (pytest --cov)
- No syntax errors (python -m py_compile *.py)
- README is complete
- requirements.txt is up to date
- Example tasks.json provided
- Color output tested on target platform
- Data migration tested with old files

## Tips & Tricks

### Batch Operations
```bash
python main.py add "Task 1" --priority high
python main.py add "Task 2" --priority medium
python main.py add "Task 3" --due 2026-01-20
```

### Viewing Specific Task Types
```bash
python main.py list --status pending
python main.py list --status completed
```

### Backup Your Data
```bash
cp tasks.json tasks.backup.json
cp tasks.backup.json tasks.json
```

## Troubleshooting

### Colors Not Showing
- Ensure colorama is installed: pip install colorama
- Check terminal supports colors
- Verify USE_COLORS = True in constants.py

### Tests Failing
- Install test dependencies: pip install pytest pytest-cov
- Ensure you're in the project directory
- Check Python version >= 3.8

### File Permission Errors
- Ensure write permissions in project directory
- Try running with elevated permissions (if necessary)

### Invalid Date Format
- Use YYYY-MM-DD format: 2026-01-15
- Don't use slashes or other separators

## Version History

- v1.0 - Foundation (add, list)
- v2.0 - Complete & delete features
- v3.0 - Refactoring & status filtering
- v4.0 - Color polish
- v5.0 - Testing & validation
- v6.0 - Advanced features (search, priority, due dates, stats)

## Future Enhancements

- Task categories/tags
- Recurring tasks
- Task notes/descriptions
- Export to CSV/PDF
- Undo/redo operations
- Task dependencies
- Time tracking
- Multi-user support

## License

MIT License - Feel free to use and modify!

---

Built with Python
Production-Ready | Fully Tested | Feature-Rich

Status: Production Ready
Test Coverage: 93%
All Features: Working