---
phase: 01-foundation-configuration
plan: 02
type: execute
---

<objective>
Set up comprehensive code quality tooling with Ruff and pre-commit hooks, ensuring all quality checks run automatically before commits.

Purpose: Establish quality gates from day one so technical debt never accumulates. Modern single-tool approach with Ruff replacing 5+ legacy tools.
Output: Working pre-commit configuration with Ruff linting/formatting, pytest with coverage, and all checks passing.
</objective>

<execution_context>
~/.claude/get-shit-done/workflows/execute-phase.md
./summary.md
~/.claude/get-shit-done/references/checkpoints.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/phases/01-foundation-configuration/01-CONTEXT.md
@.planning/phases/01-foundation-configuration/01-RESEARCH.md
@.planning/phases/01-foundation-configuration/01-01-SUMMARY.md
@REQUIREMENTS.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Set up pre-commit hooks with Ruff and quality checks</name>
  <files>.pre-commit-config.yaml, pyproject.toml (update), tests/conftest.py, README.md</files>
  <action>
Create .pre-commit-config.yaml with modern tooling:

```yaml
repos:
  # Standard hooks
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: check-added-large-files
      - id: detect-private-key
      - id: check-merge-conflict
      - id: end-of-file-fixer
      - id: trailing-whitespace
      - id: check-yaml
      - id: check-json
      - id: check-toml

  # Ruff - replaces Black, isort, Flake8, pyupgrade, autoflake
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.8.4
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  # Type checking
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.13.0
    hooks:
      - id: mypy
        additional_dependencies:
          - typer
          - pydantic
          - pydantic-settings
          - httpx
          - types-requests

  # Tests with coverage
  - repo: local
    hooks:
      - id: pytest
        name: pytest
        entry: pytest --cov=n8n_cli --cov-report=term-missing --cov-fail-under=80
        language: system
        pass_filenames: false
        always_run: true
```

Update pyproject.toml with tool configurations:

```toml
[tool.ruff]
line-length = 100
target-version = "py312"

[tool.ruff.lint]
select = [
    "E",   # pycodestyle errors
    "F",   # Pyflakes
    "I",   # isort (import sorting)
    "UP",  # pyupgrade (Python version upgrades)
    "B",   # flake8-bugbear
    "C4",  # flake8-comprehensions
]

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "--strict-markers"

[tool.coverage.run]
source = ["src/n8n_cli"]
branch = true

[tool.coverage.report]
exclude_lines = [
    "pragma: no cover",
    "if __name__ == \"__main__\":",
    "if TYPE_CHECKING:",
]

[tool.mypy]
python_version = "3.12"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = false  # Start lenient, tighten later
```

Create tests/conftest.py with shared fixtures:

```python
import pytest
from pathlib import Path
from typer.testing import CliRunner

@pytest.fixture
def cli_runner():
    """Typer CLI test runner."""
    return CliRunner()

@pytest.fixture
def temp_env_file(tmp_path, monkeypatch):
    """Create temporary .env file and switch to that directory."""
    env_file = tmp_path / ".env"
    monkeypatch.chdir(tmp_path)
    return env_file
```

Create basic README.md:

```markdown
# n8n CLI

A command-line tool for managing n8n Cloud workflows.

## Installation

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

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

# Run quality checks
pre-commit run --all-files
```

## Usage

```bash
n8n --help
```
```

DO NOT use Black, isort, Flake8 separately - use Ruff only (replaces all of them).
DO NOT use commitizen or vulture from REQUIREMENTS.md - keep it simple for now.
DO NOT set coverage requirement to 87% yet - start at 80% and raise it as code grows.
Follow RESEARCH.md recommendations for Ruff configuration (10-100x faster than old tools).
  </action>
  <verify>
- pre-commit run --all-files passes all checks
- pytest --cov shows coverage report
- ruff check src/ tests/ shows no errors
- ruff format src/ tests/ makes no changes (already formatted)
  </verify>
  <done>Pre-commit hooks installed and passing, Ruff configured for linting and formatting, pytest configured with coverage, README documents setup</done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <what-built>Complete project with CLI, configuration system, tests, and quality tooling</what-built>
  <how-to-verify>
1. Install the CLI locally:
   ```bash
   pip install -e .
   ```

2. Install pre-commit hooks:
   ```bash
   pre-commit install
   ```

3. Test the CLI works:
   ```bash
   n8n --version
   n8n --help
   ```
   Expected: Version displays, help text shows

4. Run all quality checks:
   ```bash
   pre-commit run --all-files
   ```
   Expected: All hooks pass (Ruff, mypy, pytest with coverage)

5. Test configuration loading (create test .env):
   ```bash
   echo "N8N_API_KEY=test123" > .env
   echo "N8N_INSTANCE_URL=https://test.n8n.cloud" >> .env
   python -c "from n8n_cli.config import N8nConfig; c = N8nConfig.load(); print(f'Loaded: {c.api_key}')"
   ```
   Expected: Prints "Loaded: test123"

6. Verify project structure:
   ```bash
   ls -la src/n8n_cli/
   ```
   Expected: Shows __init__.py, __main__.py, cli.py, config.py

7. Check test coverage:
   ```bash
   pytest --cov --cov-report=html
   open htmlcov/index.html
   ```
   Expected: Coverage report shows >80%, all tests passing
  </how-to-verify>
  <resume-signal>Type "approved" to continue, or describe any issues encountered</resume-signal>
</task>

</tasks>

<verification>
Before declaring plan complete:
- [ ] `.pre-commit-config.yaml` exists with Ruff configuration
- [ ] `pyproject.toml` has [tool.ruff] and [tool.pytest.ini_options] sections
- [ ] `README.md` documents installation and development setup
- [ ] `pre-commit run --all-files` passes all checks
- [ ] `pytest --cov` shows >80% coverage
- [ ] `n8n --version` and `n8n --help` work when installed
</verification>

<success_criteria>

- All tasks completed
- All verification checks pass
- Pre-commit hooks installed and passing
- Quality checks automated (Ruff, mypy, pytest)
- CLI can be installed and run
- Configuration system works end-to-end
- Phase 1 complete: Foundation and configuration ready for Phase 2
</success_criteria>

<output>
After completion, create `.planning/phases/01-foundation-configuration/01-02-SUMMARY.md`:

# Phase 1 Plan 2: Quality Tooling Summary

**Pre-commit hooks and quality automation with modern Ruff tooling**

## Accomplishments

- Configured Ruff for linting and formatting (replaces Black, isort, Flake8, pyupgrade, autoflake)
- Set up pre-commit hooks with Ruff, mypy, pytest with coverage
- Created shared test fixtures in conftest.py
- Added README with development instructions
- Verified full installation and quality checks pass

## Files Created/Modified

- `.pre-commit-config.yaml` - Pre-commit configuration with Ruff, mypy, pytest
- `pyproject.toml` (updated) - Added Ruff, pytest, coverage, mypy configuration
- `tests/conftest.py` - Shared test fixtures (cli_runner, temp_env_file)
- `README.md` - Installation and development documentation

## Decisions Made

- **Ruff only**: Single tool for all linting/formatting (10-100x faster than Black+isort+Flake8)
- **80% coverage minimum**: Starting point, will raise as codebase grows
- **Lenient mypy**: `disallow_untyped_defs = false` for now, can tighten incrementally
- **No commitizen/vulture**: Simplified setup, can add later if needed

## Issues Encountered

None

## Next Phase Readiness

Phase 1 (Foundation & Configuration) is complete. Ready for Phase 2 (API Client & Core Types).

**Foundation established:**
- ✅ Modern project structure (src layout)
- ✅ Type-safe configuration system (Pydantic)
- ✅ CLI framework (Typer)
- ✅ Quality tooling (Ruff, pre-commit, pytest)
- ✅ All quality checks passing

**Next up:**
Phase 2 will build the n8n API client using httpx with proper field filtering and error handling.
</output>
