@malamute/ai-rules 1.0.0

package/configs/python/.claude/rules/flask.md

@@ -0,0 +1,332 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Flask Rules
+
+## Application Factory
+
+```python
+from flask import Flask
+from flask_sqlalchemy import SQLAlchemy
+from flask_migrate import Migrate
+
+db = SQLAlchemy()
+migrate = Migrate()
+
+def create_app(config_name: str = "development") -> Flask:
+    app = Flask(__name__)
+    app.config.from_object(config[config_name])
+
+    # Initialize extensions
+    db.init_app(app)
+    migrate.init_app(app, db)
+
+    # Register blueprints
+    from app.users import bp as users_bp
+    from app.auth import bp as auth_bp
+
+    app.register_blueprint(users_bp, url_prefix="/api/v1/users")
+    app.register_blueprint(auth_bp, url_prefix="/api/v1/auth")
+
+    # Register error handlers
+    register_error_handlers(app)
+
+    return app
+```
+
+## Blueprints
+
+```python
+from flask import Blueprint, request, jsonify
+from http import HTTPStatus
+
+bp = Blueprint("users", __name__)
+
+@bp.get("/")
+def list_users():
+    """List all users with pagination."""
+    page = request.args.get("page", 1, type=int)
+    per_page = request.args.get("per_page", 20, type=int)
+
+    pagination = User.query.paginate(page=page, per_page=per_page)
+
+    return jsonify({
+        "items": [user.to_dict() for user in pagination.items],
+        "total": pagination.total,
+        "page": pagination.page,
+        "pages": pagination.pages,
+    })
+
+
+@bp.get("/<int:user_id>")
+def get_user(user_id: int):
+    """Get a user by ID."""
+    user = db.get_or_404(User, user_id)
+    return jsonify(user.to_dict())
+
+
+@bp.post("/")
+def create_user():
+    """Create a new user."""
+    data = request.get_json()
+
+    # Validation
+    errors = validate_user_data(data)
+    if errors:
+        return jsonify({"errors": errors}), HTTPStatus.BAD_REQUEST
+
+    user = User(
+        email=data["email"],
+        name=data["name"],
+    )
+    user.set_password(data["password"])
+
+    db.session.add(user)
+    db.session.commit()
+
+    return jsonify(user.to_dict()), HTTPStatus.CREATED
+
+
+@bp.put("/<int:user_id>")
+def update_user(user_id: int):
+    """Update a user."""
+    user = db.get_or_404(User, user_id)
+    data = request.get_json()
+
+    if "email" in data:
+        user.email = data["email"]
+    if "name" in data:
+        user.name = data["name"]
+
+    db.session.commit()
+    return jsonify(user.to_dict())
+
+
+@bp.delete("/<int:user_id>")
+def delete_user(user_id: int):
+    """Delete a user."""
+    user = db.get_or_404(User, user_id)
+    db.session.delete(user)
+    db.session.commit()
+    return "", HTTPStatus.NO_CONTENT
+```
+
+## Models with Flask-SQLAlchemy
+
+```python
+from datetime import datetime
+from werkzeug.security import generate_password_hash, check_password_hash
+from app import db
+
+class TimestampMixin:
+    created_at = db.Column(db.DateTime, default=datetime.utcnow)
+    updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+class User(TimestampMixin, db.Model):
+    __tablename__ = "users"
+
+    id = db.Column(db.Integer, primary_key=True)
+    email = db.Column(db.String(256), unique=True, nullable=False, index=True)
+    password_hash = db.Column(db.String(256), nullable=False)
+    name = db.Column(db.String(100))
+    role = db.Column(db.String(50), default="user")
+
+    # Relationships
+    posts = db.relationship("Post", back_populates="author", lazy="dynamic")
+
+    def set_password(self, password: str) -> None:
+        self.password_hash = generate_password_hash(password)
+
+    def check_password(self, password: str) -> bool:
+        return check_password_hash(self.password_hash, password)
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "email": self.email,
+            "name": self.name,
+            "role": self.role,
+            "created_at": self.created_at.isoformat(),
+        }
+```
+
+## Error Handling
+
+```python
+from flask import jsonify
+from werkzeug.exceptions import HTTPException
+
+def register_error_handlers(app: Flask) -> None:
+
+    @app.errorhandler(HTTPException)
+    def handle_http_exception(error: HTTPException):
+        return jsonify({
+            "error": error.name,
+            "message": error.description,
+        }), error.code
+
+    @app.errorhandler(ValidationError)
+    def handle_validation_error(error: ValidationError):
+        return jsonify({
+            "error": "Validation Error",
+            "message": str(error),
+            "details": error.errors,
+        }), HTTPStatus.BAD_REQUEST
+
+    @app.errorhandler(Exception)
+    def handle_generic_exception(error: Exception):
+        app.logger.exception("Unhandled exception")
+        return jsonify({
+            "error": "Internal Server Error",
+            "message": "An unexpected error occurred",
+        }), HTTPStatus.INTERNAL_SERVER_ERROR
+```
+
+## Authentication with Flask-JWT-Extended
+
+```python
+from flask_jwt_extended import (
+    JWTManager,
+    create_access_token,
+    create_refresh_token,
+    jwt_required,
+    get_jwt_identity,
+    current_user,
+)
+
+jwt = JWTManager()
+
+@jwt.user_identity_loader
+def user_identity_lookup(user: User) -> int:
+    return user.id
+
+@jwt.user_lookup_loader
+def user_lookup_callback(_jwt_header, jwt_data) -> User | None:
+    identity = jwt_data["sub"]
+    return User.query.get(identity)
+
+# Auth blueprint
+auth_bp = Blueprint("auth", __name__)
+
+@auth_bp.post("/login")
+def login():
+    data = request.get_json()
+    user = User.query.filter_by(email=data["email"]).first()
+
+    if not user or not user.check_password(data["password"]):
+        return jsonify({"error": "Invalid credentials"}), HTTPStatus.UNAUTHORIZED
+
+    return jsonify({
+        "access_token": create_access_token(identity=user),
+        "refresh_token": create_refresh_token(identity=user),
+    })
+
+@auth_bp.post("/refresh")
+@jwt_required(refresh=True)
+def refresh():
+    user = current_user
+    return jsonify({
+        "access_token": create_access_token(identity=user),
+    })
+
+# Protected route
+@bp.get("/me")
+@jwt_required()
+def get_current_user():
+    return jsonify(current_user.to_dict())
+```
+
+## Request Validation with Marshmallow
+
+```python
+from marshmallow import Schema, fields, validate, ValidationError, post_load
+
+class UserCreateSchema(Schema):
+    email = fields.Email(required=True)
+    password = fields.Str(required=True, validate=validate.Length(min=8))
+    name = fields.Str(required=True, validate=validate.Length(min=1, max=100))
+
+class UserUpdateSchema(Schema):
+    email = fields.Email()
+    name = fields.Str(validate=validate.Length(max=100))
+
+class UserResponseSchema(Schema):
+    id = fields.Int(dump_only=True)
+    email = fields.Email()
+    name = fields.Str()
+    created_at = fields.DateTime(dump_only=True)
+
+# Usage in route
+@bp.post("/")
+def create_user():
+    schema = UserCreateSchema()
+    try:
+        data = schema.load(request.get_json())
+    except ValidationError as err:
+        return jsonify({"errors": err.messages}), HTTPStatus.BAD_REQUEST
+
+    # Create user...
+```
+
+## Configuration
+
+```python
+import os
+
+class Config:
+    SECRET_KEY = os.environ.get("SECRET_KEY", "dev-secret-key")
+    SQLALCHEMY_TRACK_MODIFICATIONS = False
+    JWT_SECRET_KEY = os.environ.get("JWT_SECRET_KEY", "jwt-secret")
+    JWT_ACCESS_TOKEN_EXPIRES = timedelta(hours=1)
+
+class DevelopmentConfig(Config):
+    DEBUG = True
+    SQLALCHEMY_DATABASE_URI = os.environ.get(
+        "DATABASE_URL", "sqlite:///dev.db"
+    )
+
+class ProductionConfig(Config):
+    DEBUG = False
+    SQLALCHEMY_DATABASE_URI = os.environ["DATABASE_URL"]
+
+class TestingConfig(Config):
+    TESTING = True
+    SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:"
+
+config = {
+    "development": DevelopmentConfig,
+    "production": ProductionConfig,
+    "testing": TestingConfig,
+}
+```
+
+## CLI Commands
+
+```python
+import click
+from flask.cli import with_appcontext
+
+@app.cli.command("seed-db")
+@with_appcontext
+def seed_db():
+    """Seed the database with initial data."""
+    admin = User(email="admin@example.com", name="Admin", role="admin")
+    admin.set_password("admin123")
+    db.session.add(admin)
+    db.session.commit()
+    click.echo("Database seeded!")
+
+@app.cli.command("create-admin")
+@click.argument("email")
+@click.password_option()
+@with_appcontext
+def create_admin(email: str, password: str):
+    """Create an admin user."""
+    user = User(email=email, role="admin")
+    user.set_password(password)
+    db.session.add(user)
+    db.session.commit()
+    click.echo(f"Admin {email} created!")
+```

package/configs/python/.claude/rules/testing.md

@@ -0,0 +1,374 @@
+---
+paths:
+  - "tests/**/*.py"
+  - "**/test_*.py"
+  - "**/*_test.py"
+---
+
+# Python Testing Rules
+
+## pytest Structure
+
+```
+tests/
+├── conftest.py                 # Shared fixtures
+├── unit/
+│   ├── test_services.py
+│   └── test_utils.py
+├── integration/
+│   ├── test_repositories.py
+│   └── test_database.py
+└── e2e/
+    ├── test_users_api.py
+    └── test_auth_api.py
+```
+
+## Fixtures (conftest.py)
+
+### FastAPI Fixtures
+
+```python
+import pytest
+from httpx import AsyncClient, ASGITransport
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.orm import sessionmaker
+
+from app.main import app
+from app.database import Base, get_db
+from app.config import settings
+
+# Test database
+TEST_DATABASE_URL = "sqlite+aiosqlite:///./test.db"
+
+@pytest.fixture(scope="session")
+def event_loop():
+    """Create event loop for async tests."""
+    import asyncio
+    loop = asyncio.new_event_loop()
+    yield loop
+    loop.close()
+
+@pytest.fixture(scope="session")
+async def engine():
+    """Create test database engine."""
+    engine = create_async_engine(TEST_DATABASE_URL, echo=False)
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    yield engine
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.drop_all)
+    await engine.dispose()
+
+@pytest.fixture
+async def db_session(engine):
+    """Create a new database session for each test."""
+    async_session = sessionmaker(
+        engine, class_=AsyncSession, expire_on_commit=False
+    )
+    async with async_session() as session:
+        yield session
+        await session.rollback()
+
+@pytest.fixture
+async def client(db_session):
+    """Create test client with overridden dependencies."""
+    async def override_get_db():
+        yield db_session
+
+    app.dependency_overrides[get_db] = override_get_db
+
+    async with AsyncClient(
+        transport=ASGITransport(app=app),
+        base_url="http://test",
+    ) as client:
+        yield client
+
+    app.dependency_overrides.clear()
+
+@pytest.fixture
+async def authenticated_client(client, db_session):
+    """Client with authentication token."""
+    # Create test user
+    user = User(email="test@example.com", name="Test")
+    user.set_password("password123")
+    db_session.add(user)
+    await db_session.commit()
+
+    # Get token
+    response = await client.post("/api/v1/auth/login", json={
+        "email": "test@example.com",
+        "password": "password123",
+    })
+    token = response.json()["access_token"]
+
+    client.headers["Authorization"] = f"Bearer {token}"
+    return client
+```
+
+### Flask Fixtures
+
+```python
+import pytest
+from app import create_app, db as _db
+
+@pytest.fixture(scope="session")
+def app():
+    """Create application for testing."""
+    app = create_app("testing")
+    return app
+
+@pytest.fixture
+def client(app):
+    """Create test client."""
+    return app.test_client()
+
+@pytest.fixture
+def db(app):
+    """Create database for testing."""
+    with app.app_context():
+        _db.create_all()
+        yield _db
+        _db.drop_all()
+
+@pytest.fixture
+def session(db):
+    """Create database session."""
+    connection = db.engine.connect()
+    transaction = connection.begin()
+
+    session = db.session
+    yield session
+
+    session.close()
+    transaction.rollback()
+    connection.close()
+```
+
+## Unit Tests
+
+```python
+import pytest
+from unittest.mock import AsyncMock, MagicMock
+
+from app.users.service import UserService
+from app.users.schemas import UserCreate
+
+class TestUserService:
+    @pytest.fixture
+    def mock_repository(self):
+        return AsyncMock()
+
+    @pytest.fixture
+    def service(self, mock_repository):
+        return UserService(repository=mock_repository)
+
+    async def test_create_user_success(self, service, mock_repository):
+        # Arrange
+        user_data = UserCreate(
+            email="test@example.com",
+            password="password123",
+            name="Test User",
+        )
+        mock_repository.get_by_email.return_value = None
+        mock_repository.create.return_value = User(
+            id=1,
+            email=user_data.email,
+            name=user_data.name,
+        )
+
+        # Act
+        result = await service.create(user_data)
+
+        # Assert
+        assert result.email == user_data.email
+        mock_repository.create.assert_called_once()
+
+    async def test_create_user_email_exists_raises(self, service, mock_repository):
+        # Arrange
+        user_data = UserCreate(
+            email="existing@example.com",
+            password="password123",
+            name="Test",
+        )
+        mock_repository.get_by_email.return_value = User(id=1, email=user_data.email)
+
+        # Act & Assert
+        with pytest.raises(EmailAlreadyExistsError):
+            await service.create(user_data)
+```
+
+## Integration Tests (API)
+
+### FastAPI Tests
+
+```python
+import pytest
+from httpx import AsyncClient
+
+class TestUsersAPI:
+    async def test_create_user(self, client: AsyncClient):
+        # Arrange
+        user_data = {
+            "email": "new@example.com",
+            "password": "password123",
+            "name": "New User",
+        }
+
+        # Act
+        response = await client.post("/api/v1/users", json=user_data)
+
+        # Assert
+        assert response.status_code == 201
+        data = response.json()
+        assert data["email"] == user_data["email"]
+        assert "id" in data
+        assert "password" not in data
+
+    async def test_create_user_invalid_email(self, client: AsyncClient):
+        # Arrange
+        user_data = {
+            "email": "invalid",
+            "password": "password123",
+            "name": "Test",
+        }
+
+        # Act
+        response = await client.post("/api/v1/users", json=user_data)
+
+        # Assert
+        assert response.status_code == 422
+        assert "email" in response.json()["detail"][0]["loc"]
+
+    async def test_get_user_not_found(self, client: AsyncClient):
+        response = await client.get("/api/v1/users/99999")
+        assert response.status_code == 404
+
+    async def test_list_users_with_pagination(self, client: AsyncClient, db_session):
+        # Arrange - create 25 users
+        for i in range(25):
+            user = User(email=f"user{i}@example.com", name=f"User {i}")
+            db_session.add(user)
+        await db_session.commit()
+
+        # Act
+        response = await client.get("/api/v1/users?page=2&size=10")
+
+        # Assert
+        assert response.status_code == 200
+        data = response.json()
+        assert len(data["items"]) == 10
+        assert data["total"] == 25
+        assert data["page"] == 2
+
+    async def test_protected_route_unauthorized(self, client: AsyncClient):
+        response = await client.get("/api/v1/users/me")
+        assert response.status_code == 401
+
+    async def test_protected_route_authorized(self, authenticated_client: AsyncClient):
+        response = await authenticated_client.get("/api/v1/users/me")
+        assert response.status_code == 200
+        assert "email" in response.json()
+```
+
+### Flask Tests
+
+```python
+import pytest
+
+class TestUsersAPI:
+    def test_create_user(self, client):
+        response = client.post("/api/v1/users", json={
+            "email": "new@example.com",
+            "password": "password123",
+            "name": "New User",
+        })
+
+        assert response.status_code == 201
+        assert response.json["email"] == "new@example.com"
+
+    def test_get_user(self, client, session):
+        # Create user
+        user = User(email="test@example.com", name="Test")
+        session.add(user)
+        session.commit()
+
+        response = client.get(f"/api/v1/users/{user.id}")
+
+        assert response.status_code == 200
+        assert response.json["id"] == user.id
+```
+
+## Parametrized Tests
+
+```python
+import pytest
+
+@pytest.mark.parametrize("email,expected_valid", [
+    ("valid@example.com", True),
+    ("also.valid@example.co.uk", True),
+    ("invalid", False),
+    ("missing@", False),
+    ("@nodomain.com", False),
+])
+def test_email_validation(email: str, expected_valid: bool):
+    schema = UserCreateSchema()
+    if expected_valid:
+        result = schema.load({"email": email, "password": "12345678", "name": "Test"})
+        assert result["email"] == email
+    else:
+        with pytest.raises(ValidationError):
+            schema.load({"email": email, "password": "12345678", "name": "Test"})
+
+@pytest.mark.parametrize("password,should_pass", [
+    ("short", False),
+    ("longenough", True),
+    ("12345678", True),
+])
+def test_password_validation(password: str, should_pass: bool):
+    ...
+```
+
+## Markers
+
+```python
+# pytest.ini or pyproject.toml
+[tool.pytest.ini_options]
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "integration: marks tests that require database",
+    "e2e: marks end-to-end tests",
+]
+
+# Usage
+@pytest.mark.slow
+async def test_heavy_computation():
+    ...
+
+@pytest.mark.integration
+async def test_database_query():
+    ...
+
+# Run specific markers
+# pytest -m "not slow"
+# pytest -m integration
+```
+
+## Coverage
+
+```bash
+# Run with coverage
+pytest --cov=app --cov-report=html --cov-report=term-missing
+
+# Coverage config in pyproject.toml
+[tool.coverage.run]
+source = ["app"]
+omit = ["*/tests/*", "*/__init__.py"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]
+fail_under = 80
+```

package/configs/python/.claude/settings.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python *)",
+      "Bash(uvicorn *)",
+      "Bash(fastapi *)",
+      "Bash(flask *)",
+      "Bash(pytest *)",
+      "Bash(ruff *)",
+      "Bash(mypy *)",
+      "Bash(alembic *)",
+      "Bash(uv *)",
+      "Bash(poetry *)",
+      "Bash(pip *)"
+    ],
+    "deny": []
+  }
+}