# Development Setup

Complete guide to setting up a Prisme development environment.

## Prerequisites

### Required

- **Python 3.13+**: Check with `python --version`
- **uv**: Install from [astral.sh/uv](https://docs.astral.sh/uv/)
- **Git**: For version control

### Optional

- **Docker**: For integration and Docker tests (`pytest -m docker`)
- **PostgreSQL**: For database tests (SQLite is used by default)

## Installation

### 1. Clone the Repository

```bash
git clone https://github.com/Lasse-numerous/prisme.git
cd prisme
```

### 2. Install Dependencies

```bash
# Install all dependencies including dev and docs
uv sync --all-extras
```

This installs:
- Core dependencies (pydantic, click, jinja2, rich)
- Dev dependencies (pytest, ruff, mypy, pre-commit)
- Docs dependencies (mkdocs, mkdocs-material)

### 3. Install Git Hooks

```bash
uv run pre-commit install --hook-type pre-commit --hook-type commit-msg --hook-type pre-push
```

This sets up:
- **Pre-commit**: Auto-fix formatting (ruff, trailing whitespace, YAML validation)
- **Commit-msg**: Validate [Conventional Commits](https://www.conventionalcommits.org/) format
- **Pre-push**: Run linting, type checking, and tests before pushing

All hooks are Python-based via [pre-commit](https://pre-commit.com/) — no Node.js required.

### 4. Verify Installation

```bash
# Run tests
uv run pytest

# Run linting
uv run ruff check .

# Run type checking
uv run mypy src

# Build docs
uv run mkdocs build --strict
```

## IDE Setup

### VS Code

Recommended extensions:

```json
{
  "recommendations": [
    "ms-python.python",
    "ms-python.vscode-pylance",
    "charliermarsh.ruff",
    "tamasfe.even-better-toml"
  ]
}
```

Settings for the workspace:

```json
{
  "python.defaultInterpreterPath": ".venv/bin/python",
  "python.analysis.typeCheckingMode": "basic",
  "[python]": {
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit"
    },
    "editor.defaultFormatter": "charliermarsh.ruff"
  },
  "ruff.organizeImports": true
}
```

### PyCharm

1. Open the project
2. Configure Python interpreter: `.venv/bin/python`
3. Enable ruff integration (Settings > Tools > Ruff)
4. Enable mypy integration (Settings > Tools > Mypy)

## Project Structure

```
prisme/
├── src/prisme/              # Main package source
│   ├── __init__.py          # Package exports
│   ├── cli.py               # CLI commands (Click, 67+ commands)
│   ├── spec/                # Specification models
│   │   ├── stack.py         # StackSpec, DatabaseConfig, GeneratorConfig
│   │   ├── model.py         # ModelSpec, RelationshipSpec
│   │   ├── fields.py        # FieldSpec, FieldType, FilterOperator
│   │   ├── exposure.py      # REST/GraphQL/MCP/Frontend exposure
│   │   ├── auth.py          # AuthConfig, Role, APIKeyConfig
│   │   ├── design.py        # DesignSystemConfig, ThemePreset
│   │   ├── infrastructure.py # TraefikConfig
│   │   ├── overrides.py     # DeliveryOverrides, FrontendOverrides
│   │   └── validators.py    # Cross-model validation
│   ├── generators/          # Code generators (31 classes)
│   │   ├── base.py          # Base classes, FileStrategy enum
│   │   ├── backend/         # 11 backend generators
│   │   ├── frontend/        # 15 frontend generators
│   │   ├── infrastructure/  # 1 infrastructure generator
│   │   └── testing/         # 2 test generators
│   ├── templates/jinja2/    # 282 Jinja2 templates
│   ├── utils/               # Spec loading, template rendering, file handling
│   ├── tracking/            # Manifest & override tracking
│   ├── docker/              # Docker Compose, Traefik proxy
│   ├── deploy/              # Hetzner/Terraform deployment
│   ├── devcontainer/        # Dev container lifecycle
│   ├── ci/                  # CI/CD workflow generation
│   ├── config/              # Prism configuration
│   ├── migration/           # Database migration utilities
│   ├── planning/            # Planning utilities
│   ├── project/             # Project scaffolding
│   └── dx/                  # Developer experience utilities
├── tests/                   # Test suite (130+ files)
│   ├── conftest.py          # Shared fixtures
│   ├── spec/                # Spec model tests
│   ├── generators/          # Generator tests (backend, frontend, infrastructure)
│   ├── cli/                 # CLI tests
│   ├── e2e/                 # End-to-end tests
│   ├── docker/              # Docker integration tests
│   ├── deploy/              # Deployment tests
│   ├── devcontainer/        # Dev container tests
│   ├── tracking/            # Manifest & override tests
│   └── ...                  # ci, config, dx, migration, planning
├── docs/                    # User-facing documentation (mkdocs)
├── dev/                     # Internal development docs (roadmap, issues, plans)
├── .claude/skills/          # AI agent skill definitions
├── pyproject.toml           # Project config (ruff, mypy, pytest, semantic-release)
├── CLAUDE.md                # Claude Code session context
├── CONTRIBUTING.md          # Contribution guide
└── spec.md                  # Full specification document
```

## Common Tasks

### Running Tests

```bash
# All tests (excludes slow, e2e by default)
uv run pytest

# With coverage
uv run pytest --cov

# Specific file
uv run pytest tests/spec/test_models.py

# Specific test
uv run pytest tests/spec/test_models.py::test_model_spec_validation

# Include slow tests
uv run pytest -m slow

# Include e2e tests
uv run pytest -m e2e

# Docker tests (requires Docker)
uv run pytest -m docker

# Verbose output
uv run pytest -v
```

### Linting

```bash
# Check for issues
uv run ruff check .

# Auto-fix issues
uv run ruff check . --fix

# Check formatting
uv run ruff format --check .

# Auto-format
uv run ruff format .
```

### Type Checking

```bash
# Check all source
uv run mypy src

# Check specific file
uv run mypy src/prisme/cli.py
```

### Documentation

```bash
# Serve with hot reload
uv run mkdocs serve

# Build static site
uv run mkdocs build --strict

# Open in browser
open http://localhost:8000
```

### Running the CLI

```bash
# Run CLI commands during development
uv run prisme --help
uv run prisme create test-project
uv run prisme generate
```

## Environment Variables

For testing and development:

| Variable | Description | Default |
|----------|-------------|---------|
| `PRISM_DEBUG` | Enable debug logging | `false` |
| `PRISM_TEST_DB` | Test database URL | `sqlite:///:memory:` |

## Troubleshooting

### Virtual Environment Issues

```bash
# Recreate virtual environment
rm -rf .venv
uv sync --all-extras
```

### Import Errors

Ensure you're using the virtual environment:

```bash
# Check which Python
which python

# Should be: /path/to/prisme/.venv/bin/python
```

### Test Database Issues

```bash
# Run tests with SQLite (no external DB needed)
uv run pytest

# Or set test database explicitly
PRISM_TEST_DB=sqlite:///:memory: uv run pytest
```

### Documentation Build Errors

```bash
# Install docs dependencies explicitly
uv sync --extra docs

# Build with verbose output
uv run mkdocs build -v
```

### Pre-commit Hook Issues

```bash
# Reinstall hooks
uv run pre-commit install --hook-type pre-commit --hook-type commit-msg --hook-type pre-push

# Run hooks manually against all files
uv run pre-commit run --all-files

# Update hook versions
uv run pre-commit autoupdate
```

## Next Steps

- Read the [Contributing Guide](contributing.md)
- Understand the [Architecture](../architecture/index.md)
- Check open [Issues](https://github.com/Lasse-numerous/prisme/issues)
