feat: set up modularized version of project with testing

AGENTS.md

@@ -0,0 +1,112 @@
+# Timesheets — Agent Guide
+
+## Project overview
+
+A Python CLI tool that parses markdown pipe-delimited timesheet tables and
+exports them to CSV for import into Odoo (or similar tools). It also supports
+a human-readable summary view.
+
+### Package layout
+
+```
+timesheets/
+├── pyproject.toml                  # package metadata, entry point, dev dependencies
+├── AGENTS.md
+└── src/timesheets/
+    ├── cli.py        # argument parsing, main() entry point
+    ├── parser.py     # markdown table parsing and row aggregation
+    ├── projects.py   # project_map.json loading and key resolution
+    ├── output.py     # CSV writing and summary printing
+    └── utils.py      # shared low-level helpers (duration parsing, formatting, etc.)
+```
+
+Tests live in `tests/`, one file per source module:
+
+```
+tests/
+├── test_utils.py
+├── test_parser.py
+├── test_projects.py
+└── test_output.py
+```
+
+---
+
+## Package manager — uv
+
+All dependency management and script execution is done via [`uv`](https://docs.astral.sh/uv/).
+Do **not** use `pip` or `python` directly.
+
+| Task | Command |
+|---|---|
+| Install / sync dependencies | `uv sync` |
+| Add a runtime dependency | `uv add <package>` |
+| Add a dev-only dependency | `uv add --dev <package>` |
+| Run the CLI | `uv run timesheets <args>` |
+| Run any Python script | `uv run python <script>` |
+
+---
+
+## CLI usage
+
+```sh
+# Print CSV to stdout (date defaults to today)
+uv run timesheets input.md
+
+# Write CSV to a file
+uv run timesheets input.md -o output.csv
+
+# Override the date (DD/MM/YY)
+uv run timesheets input.md --date 22/03/26
+
+# Use a specific project map file
+uv run timesheets input.md --map /path/to/project_map.json
+
+# Print a human-readable summary instead of CSV
+uv run timesheets input.md --summary
+
+# Read from stdin
+cat input.md | uv run timesheets -
+```
+
+`project_map.json` is auto-discovered in the current working directory if
+`--map` is not provided.
+
+---
+
+## Testing
+
+The test suite uses **pytest** with **pytest-cov** for coverage reporting.
+
+```sh
+# Run all tests
+uv run pytest
+
+# Run with coverage report
+uv run pytest --cov
+
+# Run a specific test file
+uv run pytest tests/test_parser.py
+
+# Run a specific test
+uv run pytest tests/test_parser.py::TestParseTable::test_empty_input
+```
+
+### Rules for adding or changing functionality
+
+1. **Always update or add tests** when introducing new behaviour or modifying
+   existing behaviour. Tests live in the `tests/` file that corresponds to the
+   module being changed (e.g. changes to `parser.py` → `tests/test_parser.py`).
+
+2. **Run the full test suite before finishing** and confirm it passes with no
+   failures:
+   ```sh
+   uv run pytest --cov
+   ```
+
+3. **Do not reduce coverage.** Every new function or branch should have at
+   least one test covering the happy path. Edge cases and error paths should be
+   covered where the logic is non-trivial.
+
+4. `cli.py` is intentionally excluded from unit tests — it is thin glue code.
+   All logic worth testing belongs in the other modules.