feat: add daily report

.github/workflows/ci.yml

@@ -25,11 +25,14 @@ jobs:
       - name: Install dependencies
         run: uv sync --dev
 
-      - name: Run tests
-        run: uv run pytest
+      - name: Run tests with coverage
+        run: uv run pytest --cov=timetracker_utils --cov-report=term-missing --cov-report=xml
 
       - name: Lint with ruff
         run: uv run ruff check .
 
       - name: Type check with mypy
         run: uv run mypy .
+
+      - name: Security audit with pip-audit
+        run: uv run pip-audit

.gitignore

@@ -6,48 +6,19 @@ temp.*
 *.lock
 !uv.lock
 
-# AI IDEs & Editors
-.aider/
-.aider.chat.history.md
-.blackbox/
-.cline/
-.cline_docs/
-.codium/
-.codeium/
-.continue/
-.copilot/
-.cursor/
-.cursor-server/
-.devin/
-.lm-studio/
-.lovable/
-.phind/
-.supermaven/
-.tabnine/
-.v0/
-.windsurf/
-
-# AI Agent Frameworks & CLI Tools
-.antigravity
-.autogpt
-.gpt-engineer/
-
-# AI Model Runners
-.ollama/
+/.*
+!.gitignore
+!.github
+!.devin
+!.env.example
 
 # AI Agent Outputs & State Files
-.agent_state/
-.agentic/
 agent_artifacts/
 agent_logs/
 agent_output/
 agent_memory/
 
 # AI Tool Cache & Config
-.ai_cache/
-.ai_tmp/
-.llm/
-.llm_cache/
 conversation_history/
 
 # Local Model Files
@@ -118,11 +89,6 @@ dmypy.json
 *.swp
 *.swo
 *~
-.DS_Store
-.emacs.desktop
-.idea/
-.vim/
-.vscode/
 
 # Merge Conflicts
 *.orig
@@ -131,14 +97,12 @@ dmypy.json
 # OS
 Thumbs.db
 
-# Secrets & Configuration
-.env
-.env.local
-.env.*.local
-
 # Project Specific
 *.db
 *.log
 *.sqlite
 *.sqlite3
 debug.log
+.env
+.env.local
+.env.*.local

AGENTS.md

@@ -1,4 +1,4 @@
-# Agent Instructions: python-package-template
+# Agent Instructions: timetracker-utils
 
 ## Quick Start
 1. **Setup:** Run `uv sync --dev` before major work sessions
@@ -14,21 +14,28 @@
 | Testing | pytest |
 | Linting & Formatting | ruff |
 | Type Checking | mypy |
+| Security Audit | pip-audit |
 
 ## Project Structure
 ```
-python_package_template/
-  ├── config.py          (Pydantic models)
-  ├── hello.py           (Business logic)
-  └── cli.py             (Typer CLI)
+timetracker-utils/
+  ├── timetracker_utils/
+  │   ├── cli.py              (Typer CLI interface)
+  │   ├── config.py           (Pydantic config model)
+  │   ├── database.py         (SQLite persistence)
+  │   ├── datetime_utils.py   (Timezone conversion)
+  │   ├── report.py           (Report generation)
+  │   ├── time_cop.py         (TimeCop CSV parsing)
+  │   ├── simple_time_tracker.py (Simple Time Tracker parsing)
+  │   └── base_tracker.py     (Base tracker class)
 tests/                   (Pytest suite)
 pyproject.toml           (Dependencies & tool config)
 ```
 
 ## Essential Directives
 
 ### Code Standards
-- **Type Hints:** Required on ALL function signatures and class members. Enforce strictly with mypy.
+- **Type Hints:** Required on ALL function signatures and class members. Enforce strictly with mypy. Avoid using `# type: ignore` comments to suppress mypy errors; fix the underlying type issues instead.
 - **Docstrings:** Google-style format for all public APIs.
 - **Logging:** Use `logging` module only; never `print()`.
 - **Relative Paths:** Never use absolute paths in code.
@@ -40,7 +47,7 @@ pyproject.toml           (Dependencies & tool config)
 
 ### Testing & Quality
 - **Test Coverage:** Every code change requires corresponding tests in `tests/`.
-- **Validation Before Commit:** Run the full suite: `uv run pytest`, `uv run ruff check .`, `uv run mypy .`.
+- **Validation Before Commit:** Run the full suite: `uv run pytest`, `uv run ruff check .`, `uv run mypy .`, `uv run pip-audit`.
 
 ### Operational Constraints
 - **No Interactive Prompts:** Mock or bypass any interactive commands.
@@ -57,5 +64,6 @@ uv run pytest                           # Run tests
 uv run ruff check .                     # Lint
 uv run ruff format .                    # Auto-format
 uv run mypy .                           # Type check
-uv run hello-world hello  # Test CLI
+uv run pip-audit                        # Security audit
+uv run timetracker --version            # Test CLI
 ```

README.md

@@ -17,6 +17,7 @@ This package processes CSV time tracking exports (in the TimeCop format), valida
   3. **Conflict detection**: Non-blank conflicting values raise a `MergeConflictError`
 - **Timezone conversion**: Display timestamps in any IANA or abbreviation timezone (ET, PT, UTC, etc.)
 - **Round-trip CSV export**: Export the entire database back to TimeCop-format CSV
+- **Daily reports**: Generate text or interactive bar chart reports for single dates or date ranges, with breakdowns by activity, tags, and categories
 - **CLI interface**: Full-featured command-line interface via Typer
 
 ## Installation
@@ -72,8 +73,32 @@ uv run timetracker export --config tests/timetracker.yml --format timecop timeco
 
 # Export the database back to Simple Time Tracker CSV
 uv run timetracker export --config tests/timetracker.yml --format stt stt_export.csv
+
+# Generate a daily report for a specific date
+uv run timetracker report --config tests/timetracker.yml --date 2026-04-13
+
+# Generate a report for a date range
+uv run timetracker report --config tests/timetracker.yml --date 2026-04-13:2026-04-15
+
+# Generate an interactive bar chart report (requires matplotlib and display)
+uv run timetracker report --config tests/timetracker.yml --date 2026-04-13 --type bar
 ```
 
+#### Report Command Options
+
+The `report` command generates daily or range reports with breakdowns by activity, tags, and categories:
+
+- **Date format**: Use `yyyy-mm-dd` for single dates or `yyyy-mm-dd:yyyy-mm-dd` for inclusive date ranges
+- **Output types**:
+  - `text` (default): Displays formatted tables with time and percentage breakdowns
+  - `bar`: Interactive matplotlib bar charts with navigation (requires display server)
+- **Breakdowns**: Reports show total time with breakdowns for:
+  - Activities (project/task names)
+  - Tags (user-defined labels)
+  - Categories (groupings)
+
+**Note**: Bar chart reports require matplotlib and a display server (`$DISPLAY` or `$WAYLAND_DISPLAY`). Use `--type text` for terminal-only environments.
+
 ### Python API
 
 ```python
@@ -165,6 +190,9 @@ uv run ruff format .
 
 # Type check
 uv run mypy .
+
+# Security audit
+uv run pip-audit
 ```
 
 ## Technology Stack
@@ -179,11 +207,33 @@ uv run mypy .
 | Testing           | pytest        |
 | Linting           | ruff          |
 | Type Checking     | mypy          |
+| Security Audit    | pip-audit     |
 
 ## License
 
 MIT
 
+## Agent Instructions
+
+This project includes AGENTS.md with instructions for AI agents working on this codebase. The instructions enforce:
+
+- **Code Standards**: Type hints on all functions, Google-style docstrings, logging over print()
+- **Quality Validation**: Automated pytest, ruff, mypy, and pip-audit checks before commits
+- **Development Workflow**: uv for dependency management, proper testing patterns
+- **Project Structure**: Consistent organization with separation of concerns
+
+## Python Best Practices Used
+
+- ✅ **Type hints**: All functions and classes use type annotations
+- ✅ **Docstrings**: Clear descriptions of modules, classes, and functions
+- ✅ **Project structure**: Proper package layout with separation of concerns
+- ✅ **Testing**: Comprehensive test coverage with pytest
+- ✅ **Configuration**: Externalized config using pydantic BaseModel
+- ✅ **Linting**: Code quality checks with ruff
+- ✅ **Dependency management**: Explicit dependencies in pyproject.toml
+- ✅ **Security**: Automated vulnerability scanning with pip-audit
+- ✅ **Python versions**: Supports Python 3.10+
+
 ## Author
 
 AlexAndrewsAI <alex.andrews.ai@protonmail.com>

pyproject.toml

@@ -17,17 +17,18 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.13",  # Added
+    "Programming Language :: Python :: 3.13",
 ]
 
 dependencies = [
+    "matplotlib>=3.0",
     "pandas>=2.3.3",
     "pydantic>=2.0",
     "pyyaml>=6.0.3",
     "typer>=0.12.0",
 ]
 
-[dependency-groups]  # uv-specific feature for grouping optional dependencies
+[dependency-groups]
 dev = [
     "pytest>=7.0",
     "ruff",
@@ -36,6 +37,7 @@ dev = [
     "pandas-stubs>=2.3.3.260113",
     "uv>=0.11.21",
     "types-pyyaml>=6.0.12.20260518",
+    "pip-audit",
 ]
 
 [project.scripts]
@@ -53,9 +55,6 @@ build-backend = "hatchling.build"
 [tool.hatch.version]  # Configures hatch to read version from __init__.py
 path = "timetracker_utils/__init__.py"
 
-[tool.hatch.build.targets.wheel]
-packages = ["timetracker_utils"]
-
 [tool.ruff]
 line-length = 88
 target-version = "py310"