v0.1.0rc5

.commitlintrc.json

@@ -26,6 +26,35 @@
       2,
       "never"
     ],
+    "type-min-length": [
+      2,
+      "always",
+      1
+    ],
+    "type-max-length": [
+      2,
+      "always",
+      15
+    ],
+    "scope-case": [
+      2,
+      "always",
+      "lower-case"
+    ],
+    "scope-empty": [
+      0,
+      "never"
+    ],
+    "scope-min-length": [
+      2,
+      "always",
+      1
+    ],
+    "scope-max-length": [
+      2,
+      "always",
+      20
+    ],
     "subject-case": [
       2,
       "never",
@@ -45,26 +74,92 @@
       "never",
       "."
     ],
+    "subject-min-length": [
+      2,
+      "always",
+      1
+    ],
     "subject-max-length": [
       2,
       "always",
       120
     ],
+    "subject-exclamation-mark": [
+      2,
+      "never"
+    ],
+    "header-case": [
+      0,
+      "never"
+    ],
+    "header-full-stop": [
+      2,
+      "never",
+      "."
+    ],
+    "header-min-length": [
+      2,
+      "always",
+      10
+    ],
+    "header-max-length": [
+      2,
+      "always",
+      120
+    ],
+    "header-trim": [
+      2,
+      "always"
+    ],
     "body-leading-blank": [
       2,
       "always"
     ],
-    "body-max-line-length": [
+    "body-case": [
+      0,
+      "always",
+      "lower-case"
+    ],
+    "body-empty": [
+      0,
+      "never"
+    ],
+    "body-full-stop": [
+      0,
+      "never",
+      "."
+    ],
+    "body-min-length": [
+      0,
+      "always",
       0
     ],
+    "body-max-line-length": [
+      0,
+      "always",
+      120
+    ],
     "footer-leading-blank": [
       2,
       "always"
     ],
-    "header-max-length": [
+    "footer-empty": [
+      0,
+      "never"
+    ],
+    "footer-min-length": [
+      2,
+      "always",
+      0
+    ],
+    "footer-max-line-length": [
       2,
       "always",
       120
+    ],
+    "references-empty": [
+      0,
+      "never"
     ]
   },
   "defaultIgnores": true,

.cursor/rules/core/tech-stack.mdc

@@ -0,0 +1,196 @@
+---
+alwaysApply: true
+---
+
+# Tech Stack & Dependencies
+
+## Core Runtime
+
+**Python:** 3.13+ • **Discord:** `discord-py` • **Package Manager:** `uv`
+
+## Key Configuration Files
+
+- **`pyproject.toml`** - Central config (deps, tools, scripts, build)
+- **`uv.lock`** - Dependency lock file
+- **`compose.yaml`** - Docker services (PostgreSQL 17, Adminer, hot reload)
+- **`Containerfile`** - Multi-stage Docker build
+- **`alembic.ini`** - Database migrations config
+- **`config/`** - Config examples (TOML/YAML/JSON from pydantic-settings)
+
+## Dependencies by Group
+
+**Core Runtime:**
+
+- `discord-py`, `jishaku` (Discord bot framework)
+- `sqlmodel`, `sqlalchemy`, `alembic` (Database ORM & migrations)
+- `httpx`, `aiofiles`, `aiocache`, `redis` (Async I/O)
+- `loguru`, `sentry-sdk[httpx,loguru]` (Logging & monitoring)
+- `pydantic`, `pydantic-settings` (Data validation & config)
+- `typer`, `rich`, `click` (CLI & output)
+- `pillow`, `cairosvg` (Image processing)
+
+**Development:**
+
+- `basedpyright` (Type checking - strict mode)
+- `ruff` (Linting & formatting)
+- `pre-commit` (Git hooks)
+- `pydoclint` (Docstring linting - NumPy style)
+- `yamllint`, `yamlfix` (YAML tools)
+
+**Testing:**
+
+- `pytest` + plugins (`asyncio`, `mock`, `cov`, `sugar`, `randomly`, `timeout`, `html`, `benchmark`, `alembic`, `loguru`, `parallel`, `httpx`)
+- `py-pglite[all]` (In-memory PostgreSQL for tests)
+
+**Documentation:**
+
+- `mkdocs` + `mkdocs-material`
+- `mkdocstrings` + `mkdocstrings-python`
+- `griffe` + plugins (API docs generation)
+- `pymdown-extensions` (Markdown extensions)
+
+**Type Stubs:**
+
+- `types-*` packages for external libraries
+- `asyncpg-stubs`
+- `annotated-types`
+
+See `pyproject.toml` for a more full and up to date list of dependencies.
+
+## Database Stack
+
+**ORM:** SQLModel (SQLAlchemy + Pydantic integration)
+**Migrations:** Alembic + `alembic-postgresql-enum` + `alembic-utils`
+**Drivers:** `asyncpg` (primary), `psycopg[binary,pool]` (backup)
+**Database:** PostgreSQL 17+ (Docker: `postgres:17-alpine`)
+**Testing:** `py-pglite` (in-memory PostgreSQL)
+
+## Development Tools
+
+**Code Quality:**
+
+- `ruff` - Linting & formatting (120 char line length, Python 3.13 target)
+- `basedpyright` - Strict type checking with execution environments
+- `pydoclint` - NumPy-style docstring validation
+- `pre-commit` - Automated git hooks
+
+**Testing Framework:**
+
+- `pytest` with async support and comprehensive plugins
+- Markers: `unit`, `integration`, `slow`, `database`, `async`
+- Coverage reports: terminal, XML, JSON, LCOV, HTML
+
+**Monitoring & Logging:**
+
+- `loguru` - Structured logging with rich formatting
+- `sentry-sdk` - Error tracking and performance monitoring
+- Custom logging configuration for development vs production
+
+## CLI Scripts System
+
+All scripts use `typer` and are defined in `pyproject.toml`:
+
+```bash
+# Core commands
+uv run tux start [--debug]     # Start bot
+uv run db migrate-dev          # Database operations
+uv run dev all                 # All quality checks
+uv run tests run               # Run tests with coverage
+uv run docs serve              # Documentation server
+uv run config generate         # Generate config examples
+```
+
+## Project Structure
+
+```text
+tux/
+├── src/tux/                   # Main source code
+│   ├── core/                  # Bot core (app, logging, config)
+│   ├── database/              # Models, migrations, controllers
+│   ├── services/              # Business logic services
+│   ├── modules/               # Discord cogs/commands
+│   ├── ui/                    # Embeds, views, components
+│   ├── shared/                # Utilities, constants, config
+│   └── help/                  # Help system
+├── scripts/                   # CLI scripts (typer-based)
+├── tests/                     # Test suite (unit/integration/e2e)
+├── docs/                      # MkDocs documentation
+├── config/                    # Configuration examples
+└── docker/                    # Docker-related files
+```
+
+## Development Workflow
+
+```bash
+# Setup
+uv sync                        # Install all dependencies
+cp .env.example .env          # Configure environment
+cp config/config.toml.example config/config.toml
+
+# Development
+uv run dev all                # Run all quality checks
+uv run tests quick            # Fast test run
+uv run tux start --debug      # Start bot in debug mode
+
+# Database
+uv run db migrate-dev         # Create & apply migrations
+uv run db health              # Check database connection
+
+# Documentation
+uv run docs serve             # Local preview
+uv run docs build             # Build static site
+```
+
+## Configuration System
+
+**Multi-format support:** TOML (primary), YAML, JSON, .env
+**Generation:** `pydantic-settings-export` creates examples from code
+**Validation:** Pydantic models with type safety
+**Environment:** `.env` file + environment variables
+**Regions:** Markdown docs with embedded config sections
+
+## Docker Setup
+
+**Services:**
+
+- `postgres:17-alpine` - Database
+- `adminer` - Database admin interface
+- `tux` - Bot service with hot reload
+
+**Features:**
+
+- Multi-stage builds (dev/production)
+- Non-root user security
+- Volume mounts for development
+- Health checks and restart policies
+
+## Testing Strategy
+
+**Unit Tests:** Fast, isolated, use py-pglite
+**Integration Tests:** Database interactions, service integration
+**E2E Tests:** Full workflow testing
+**Markers:** Categorize tests by type and speed
+**Coverage:** Comprehensive reporting with multiple formats
+**Async:** Full asyncio support with proper fixtures
+
+## Quality Standards
+
+- **Type Safety:** Strict basedpyright configuration
+- **Code Style:** Ruff with 120-char lines, Python 3.13 target
+- **Documentation:** NumPy-style docstrings, comprehensive API docs
+- **Testing:** High coverage, multiple test types, async support
+- **Dependencies:** Locked versions, security scanning
+- **Git:** Conventional commits, automated hooks
+
+## Best Practices
+
+1. **Dependencies:** Always use `uv`, commit `uv.lock`
+2. **Types:** Fix all type errors, use strict mode
+3. **Testing:** Use appropriate markers, maintain coverage
+4. **Documentation:** NumPy docstrings, update examples
+5. **Database:** Use migrations, test with py-pglite
+6. **Configuration:** Validate with Pydantic, support multiple formats
+7. **CLI:** Use typer for all scripts, provide help text
+8. **Docker:** Use multi-stage builds, non-root users
+9. **Monitoring:** Structured logging, error tracking
+10. **Security:** Regular dependency updates, secret management