Remove Makefile, migrate to pure uv + PoeThePoet workflow with ty and pytest

AGENTS.md

@@ -5,40 +5,38 @@ The application code lives in `src/soco_scribbler/`. `cli.py` defines
 the Typer CLI entrypoints, `soco_scribbler.py` coordinates Sonos
 polling, logging, and destinations, and `sonos_lastfm.py` wraps the
 Last.fm client. Shared helpers sit in `config.py` and `utils.py`,
-while release metadata belongs in `pyproject.toml` and the top-level
-`Makefile`. Update `SOCO_SCRIBBLER_LOGGER.md` whenever logger
+while release metadata belongs in `pyproject.toml`. Update `SOCO_SCRIBBLER_LOGGER.md` whenever logger
 behaviour or outputs change.
 
 ## Build, Test, and Development Commands
-Run `make setup` once to create the uv virtual environment, then `make
-install` or `make install-dev` for runtime or dev dependencies. `make
-run` boots the scrobbler via `uv run -m sonos_lastfm`, and `uv run -m
-soco_scribbler.soco_scribbler scribble --stdout` exercises the local
-logger. Keep `make check-types`, `make check-ruff`, or `make
-check-all` green before pushing. Use `make clean` before rebuilding
-distributions.
+Install dependencies with `uv pip install -e ".[dev]"` which includes
+all development tools (poethepoet, ty, ruff, pytest, build). Run
+`soco-scribbler scribble --stdout` to exercise the local logger, or
+`uv run -m sonos_lastfm test` to test Last.fm connectivity. Keep
+`poe check-all` green before pushing (runs ty type checker and ruff linter).
+Use `poe clean` before rebuilding distributions.
 
 ## Coding Style & Naming Conventions
 Target Python 3.11+, 4-space indentation, and 88-character lines. CLI
 command names stay kebab-case, module and function names snake_case,
 and classes PascalCase. Document new behaviour with Google-style
-docstrings and prefer explicit type hints so mypy and ruff
+docstrings and prefer explicit type hints so ty and ruff
 succeed. Reuse platformdirs helpers when touching the filesystem.
 
 ## Testing Guidelines
-Static checks are the minimum gate: run `make check-all` plus relevant
-CLI smoke tests (`uv run -m sonos_lastfm test`, `soco-scribbler
-scribble --no-stdout`) before PRs. If you add automated tests, place
-them under `tests/` with descriptive names (`test_logger.py`) and keep
-fixtures local; install `pytest` in the uv environment only when
-needed.
+Static checks are the minimum gate: run `poe check-all` (or `poe qa` for
+comprehensive checks including formatting) plus relevant CLI smoke tests
+(`uv run -m sonos_lastfm test`, `soco-scribbler scribble --no-stdout`)
+before PRs. If you add automated tests, place them under `tests/` with
+descriptive names (`test_logger.py`) and keep fixtures local; pytest is
+already included in dev dependencies.
 
 ## Commit & Pull Request Guidelines
 Write imperative, ≤72 character commit summaries (e.g., `Add Kafka
 logger exporter`) and scope each change set narrowly. Reference issues
 with `Refs #123` in the body. PRs should describe what changed, why,
 and how it was verified, and must include any doc updates plus proof
-that `make check-all` passed.
+that `poe check-all` passed.
 
 ## Security & Configuration Tips
 Never commit `.env`, `.op_env`, or log artefacts. Use `soco-scribbler

README.md

@@ -44,30 +44,53 @@ uv add keyring keyrings.alt
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```
 
-2. Setup and run using Make commands:
+2. Clone the repository and set up the development environment:
    ```bash
-   # Setup Python environment with uv
-   make setup
+   # Clone the repository
+   git clone https://github.com/crossjam/soco-scribbler
+   cd soco-scribbler
+
+   # Install the package with development dependencies
+   uv pip install -e ".[dev]"
+
+   # Optional: Install keyring backend for secure credential storage
+   uv pip install keyring keyrings.alt
+   ```
 
-   # Install dependencies
-   make install
+### Using PoeThePoet Tasks
 
-   # For development, install additional tools (optional)
-   make install-dev
+The project uses [PoeThePoet](https://poethepoet.natn.io) as a task runner for development workflows. After installing development dependencies with `uv pip install -e ".[dev]"`, you can use `poe` commands:
 
-   # Optional: Install keyring backend for secure credential storage
-   pip install keyring keyrings.alt
-   ```
+```bash
+# QA and Code Quality tasks
+poe qa             # Run all QA checks (format, lint, typecheck)
+poe lint           # Run linter (ruff)
+poe lint-fix       # Run linter with auto-fix
+poe typecheck      # Run type checker (ty)
+poe format         # Format code with ruff
+poe format-check   # Check if code is formatted correctly
+poe test           # Run tests with pytest
+poe check-all      # Run type checking and linting
+
+# Utility tasks
+poe clean          # Clean up build artifacts
+
+# View all available tasks
+poe --help
+
+# Run a task with verbose output
+poe -v typecheck
+```
 
-   Run `make help` to see all available commands.
+All development tasks are configured in `pyproject.toml` under `[tool.poe.tasks]`.
 
 ### Building the package
 
 The project uses [`uv`](https://github.com/astral-sh/uv) to drive packaging
 workflows. You can build both the source and wheel distributions locally with:
 
 ```bash
-make build-package
+poe build-package
 ```
 
 Behind the scenes this ensures the `build` frontend is available and then runs

plans/CONVERSION_SUMMARY.md

@@ -0,0 +1,146 @@
+# Makefile to PoeThePoet Conversion Summary
+
+**Completion Date:** 2025-12-30T23:25:20.106Z  
+**Status:** ✅ Complete  
+
+## What Was Done
+
+This conversion successfully replaced the Makefile with PoeThePoet (poe), a modern Python task runner integrated with pyproject.toml. The Makefile has been completely removed.
+
+### Files Modified
+
+1. **pyproject.toml**
+   - Added `[project.optional-dependencies]` section with dev dependencies including `poethepoet>=0.24.0`, `ty>=0.1.0`, `pytest>=7.0.0`
+   - Added `[tool.poe]` configuration with `.env` file support
+   - Added `[tool.poe.tasks]` with all task definitions
+   - Organized dependencies for uv workflow
+
+2. **README.md**
+   - Updated "Using PoeThePoet Tasks" section with uv-based workflow
+   - Removed all Makefile references
+   - Documented how to install and use poe commands with uv
+
+3. **Makefile**
+   - **REMOVED**: Makefile has been completely removed from the project
+
+4. **plans/makefile-to-poethepoet-conversion.md**
+   - Created comprehensive conversion plan
+   - Documented all tasks and their mappings
+   - Included testing strategy and benefits
+
+## Task Mapping
+
+All development tasks are now managed via PoeThePoet:
+
+| Category | Tasks |
+|----------|-------|
+| Code Quality | check-types, check-ruff, check-all |
+| QA Tasks | lint, lint-fix, typecheck, format, format-check, test, qa |
+| Utility | clean |
+| Release Management | update-version, build-package, publish-package, verify-package, release |
+
+**Note:** Installation is now handled directly via uv (`uv pip install -e ".[dev]"`). The `help` task is not needed as poe provides built-in help via `poe --help`.
+
+## How to Use
+
+### Installing Dependencies
+
+```bash
+# Install uv first
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install the package with development dependencies
+uv pip install -e ".[dev]"
+```
+
+### Running Tasks
+
+```bash
+# View all available tasks
+poe --help
+
+# Run a task
+poe check-all
+
+# Run with verbose output
+poe -v check-types
+
+# Dry run to see what would be executed
+poe -d clean
+```
+
+### Task Examples
+
+```bash
+# Development workflow (all via uv and poe)
+uv pip install -e ".[dev]"  # Install with dev dependencies
+
+# QA and Code Quality (comprehensive)
+poe qa                 # Run all QA checks (format, lint, typecheck)
+poe check-all          # Run type checking and linting
+
+# Individual QA tasks
+poe lint               # Run linter (ruff)
+poe lint-fix           # Run linter with auto-fix
+poe typecheck          # Run type checker (ty)
+poe format             # Format code with ruff
+poe format-check       # Check if code is formatted correctly
+poe test               # Run tests with pytest
+
+# Utility
+poe clean              # Clean build artifacts
+
+# Release process
+poe build-package      # Build distributions
+poe release            # Full release workflow
+```
+
+## Benefits of PoeThePoet
+
+1. **Cross-platform**: Works on Windows, macOS, and Linux without requiring Make
+2. **Python-native**: Configured in pyproject.toml, the standard Python project file
+3. **Better integration**: Native support for Python virtual environments
+4. **Type safety**: Better argument validation and handling
+5. **Built-in help**: Automatic help generation and task documentation
+6. **Shell completion**: Support for bash, zsh, and fish
+7. **Environment files**: Native .env file support
+8. **Sequence tasks**: Easy task composition (e.g., check-all runs check-types and check-ruff)
+
+## Makefile Removal
+
+The Makefile has been **completely removed** from the project. All development workflows now use PoeThePoet tasks with uv for dependency management.
+
+**What was removed:**
+- Makefile with outdated references to non-existent root files
+- Installation tasks (now handled by `uv pip install -e ".[dev]"`)
+- Build tasks (now handled by poe tasks)
+
+**Migration path:**
+- Old: `make install-dev` → New: `uv pip install -e ".[dev]"`
+- Old: `make check-all` → New: `poe check-all`
+- Old: `make clean` → New: `poe clean`
+- Old: `make build-package` → New: `poe build-package`
+
+## Testing Performed
+
+- ✅ Verified poe can read pyproject.toml configuration
+- ✅ Confirmed all tasks are properly defined
+- ✅ Validated task help descriptions
+- ✅ Tested task listing with `poe --help`
+- ✅ Verified .env file support configuration
+- ✅ Confirmed sequence tasks (check-all, qa) are properly configured
+- ✅ Verified ty type checker works correctly
+- ✅ Verified pytest integration
+
+## Next Steps (Optional)
+
+1. Update CI/CD pipelines to use poe commands with uv
+2. Add shell completion setup instructions to README
+3. Consider adding more sophisticated task composition as project grows
+4. May want to add task aliases for common workflows
+
+## References
+
+- [PoeThePoet Documentation](https://poethepoet.natn.io)
+- [PoeThePoet GitHub](https://github.com/nat-n/poethepoet)
+- [Original Conversion Plan](./makefile-to-poethepoet-conversion.md)