@malamute/ai-rules 1.0.0 → 1.2.0

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

@@ -0,0 +1,284 @@
+---
+paths:
+  - "tests/**/*.py"
+  - "**/test_*.py"
+---
+
+# Flask Testing Patterns
+
+## Test Configuration
+
+```python
+# conftest.py
+import pytest
+from app import create_app, 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 runner(app):
+    """Create CLI test runner."""
+    return app.test_cli_runner()
+
+@pytest.fixture
+def db_session(app):
+    """Create database session for testing."""
+    with app.app_context():
+        db.create_all()
+        yield db.session
+        db.session.rollback()
+        db.drop_all()
+```
+
+## Testing Config
+
+```python
+# config.py
+class TestingConfig:
+    TESTING = True
+    SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:"
+    WTF_CSRF_ENABLED = False
+    SECRET_KEY = "test-secret-key"
+```
+
+## API Endpoint Tests
+
+```python
+class TestUsersAPI:
+    def test_create_user(self, client, db_session):
+        response = client.post("/api/v1/users", json={
+            "email": "test@example.com",
+            "password": "password123",
+            "name": "Test User",
+        })
+
+        assert response.status_code == 201
+        data = response.get_json()
+        assert data["email"] == "test@example.com"
+        assert "id" in data
+        assert "password" not in data
+
+    def test_create_user_duplicate_email(self, client, db_session):
+        # Create existing user
+        user = User(email="existing@example.com", name="Existing")
+        db_session.add(user)
+        db_session.commit()
+
+        response = client.post("/api/v1/users", json={
+            "email": "existing@example.com",
+            "password": "password123",
+            "name": "New User",
+        })
+
+        assert response.status_code == 409
+
+    def test_get_user_not_found(self, client):
+        response = client.get("/api/v1/users/99999")
+        assert response.status_code == 404
+
+    def test_list_users_pagination(self, client, db_session):
+        # Create users
+        for i in range(25):
+            db_session.add(User(email=f"user{i}@example.com", name=f"User {i}"))
+        db_session.commit()
+
+        response = client.get("/api/v1/users?page=2&size=10")
+
+        assert response.status_code == 200
+        data = response.get_json()
+        assert len(data["items"]) == 10
+        assert data["total"] == 25
+```
+
+## Authentication Tests
+
+```python
+@pytest.fixture
+def auth_headers(client, db_session):
+    """Create authenticated user and return headers."""
+    user = User(email="auth@example.com", name="Auth User")
+    user.set_password("password123")
+    db_session.add(user)
+    db_session.commit()
+
+    response = client.post("/api/v1/auth/login", json={
+        "email": "auth@example.com",
+        "password": "password123",
+    })
+    token = response.get_json()["access_token"]
+
+    return {"Authorization": f"Bearer {token}"}
+
+class TestAuthenticatedEndpoints:
+    def test_get_me_unauthorized(self, client):
+        response = client.get("/api/v1/users/me")
+        assert response.status_code == 401
+
+    def test_get_me_authorized(self, client, auth_headers):
+        response = client.get("/api/v1/users/me", headers=auth_headers)
+        assert response.status_code == 200
+        assert response.get_json()["email"] == "auth@example.com"
+```
+
+## Form Tests
+
+```python
+def test_login_form(client, db_session):
+    # Create user
+    user = User(email="test@example.com", name="Test")
+    user.set_password("password")
+    db_session.add(user)
+    db_session.commit()
+
+    response = client.post("/login", data={
+        "email": "test@example.com",
+        "password": "password",
+    }, follow_redirects=True)
+
+    assert response.status_code == 200
+    assert b"Dashboard" in response.data
+```
+
+## File Upload Tests
+
+```python
+from io import BytesIO
+
+def test_file_upload(client, auth_headers):
+    data = {
+        "file": (BytesIO(b"file content"), "test.txt"),
+    }
+
+    response = client.post(
+        "/api/v1/files/upload",
+        data=data,
+        content_type="multipart/form-data",
+        headers=auth_headers,
+    )
+
+    assert response.status_code == 201
+    assert response.get_json()["filename"] == "test.txt"
+```
+
+## CLI Command Tests
+
+```python
+def test_init_db_command(runner):
+    result = runner.invoke(args=["init-db"])
+    assert result.exit_code == 0
+    assert "Database initialized" in result.output
+
+def test_create_user_command(runner, db_session):
+    result = runner.invoke(args=[
+        "create-user",
+        "test@example.com",
+        "Test User",
+        "--admin",
+    ])
+
+    assert result.exit_code == 0
+    assert "Created user" in result.output
+
+    user = User.query.filter_by(email="test@example.com").first()
+    assert user is not None
+    assert user.is_admin is True
+```
+
+## Mocking External Services
+
+```python
+from unittest.mock import patch, MagicMock
+
+def test_send_email(client, db_session):
+    with patch("app.services.email.mail") as mock_mail:
+        response = client.post("/api/v1/users", json={
+            "email": "test@example.com",
+            "password": "password123",
+            "name": "Test User",
+        })
+
+        assert response.status_code == 201
+        mock_mail.send.assert_called_once()
+
+def test_external_api_call(client):
+    with patch("app.services.external.requests") as mock_requests:
+        mock_requests.get.return_value = MagicMock(
+            status_code=200,
+            json=lambda: {"data": "mocked"},
+        )
+
+        response = client.get("/api/v1/external-data")
+
+        assert response.status_code == 200
+        assert response.get_json()["data"] == "mocked"
+```
+
+## Parametrized Tests
+
+```python
+@pytest.mark.parametrize("email,expected_status", [
+    ("valid@example.com", 201),
+    ("also.valid@test.co.uk", 201),
+    ("invalid", 400),
+    ("missing@", 400),
+    ("@nodomain.com", 400),
+])
+def test_email_validation(client, email: str, expected_status: int):
+    response = client.post("/api/v1/users", json={
+        "email": email,
+        "password": "password123",
+        "name": "Test",
+    })
+
+    assert response.status_code == expected_status
+```
+
+## Test Markers
+
+```python
+# pytest.ini or pyproject.toml
+[tool.pytest.ini_options]
+markers = [
+    "slow: marks tests as slow",
+    "integration: requires database",
+]
+
+# Usage
+@pytest.mark.slow
+def test_heavy_computation():
+    ...
+
+@pytest.mark.integration
+def test_database_query(db_session):
+    ...
+
+# Run specific markers
+# pytest -m "not slow"
+# pytest -m integration
+```
+
+## Coverage Configuration
+
+```toml
+# 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/flask/.claude/settings.json

@@ -0,0 +1,33 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python *)",
+      "Bash(python3 *)",
+      "Bash(flask *)",
+      "Bash(gunicorn *)",
+      "Bash(pytest *)",
+      "Bash(ruff *)",
+      "Bash(mypy *)",
+      "Bash(alembic *)",
+      "Bash(uv *)",
+      "Bash(poetry *)",
+      "Bash(pip *)",
+      "Bash(pip3 *)",
+      "Read",
+      "Edit",
+      "Write"
+    ],
+    "deny": [
+      "Bash(rm -rf *)",
+      "Read(.env)",
+      "Read(.env.*)",
+      "Read(**/secrets/**)",
+      "Read(**/*.pem)"
+    ]
+  },
+  "env": {
+    "FLASK_DEBUG": "1",
+    "PYTHONDONTWRITEBYTECODE": "1",
+    "PYTHONUNBUFFERED": "1"
+  }
+}

package/configs/flask/CLAUDE.md

@@ -0,0 +1,166 @@
+# Flask Project Guidelines
+
+@../_shared/CLAUDE.md
+
+## Stack
+
+- Python 3.12+
+- Flask 3.0+
+- SQLAlchemy 2.0+ (sync or async)
+- Marshmallow for validation
+- pytest for testing
+- uv or poetry for dependencies
+
+## Architecture
+
+```
+src/app/
+├── __init__.py          # App factory
+├── config.py            # Configuration classes
+├── extensions.py        # Flask extensions (db, migrate, etc.)
+├── [domain]/            # Feature blueprints
+│   ├── __init__.py      # Blueprint registration
+│   ├── routes.py        # Route handlers
+│   ├── schemas.py       # Marshmallow schemas
+│   ├── models.py        # SQLAlchemy models
+│   ├── services.py      # Business logic
+│   └── repository.py    # Data access
+├── core/                # Shared utilities
+│   ├── exceptions.py
+│   └── security.py
+└── common/
+    ├── models.py        # Base models
+    └── schemas.py       # Shared schemas
+```
+
+## Flask Patterns
+
+### Application Factory
+
+```python
+from flask import Flask
+from app.extensions import db, migrate
+from app.config import config
+
+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 users_bp
+    app.register_blueprint(users_bp, url_prefix="/api/v1/users")
+
+    # Register error handlers
+    register_error_handlers(app)
+
+    return app
+```
+
+### Blueprints
+
+```python
+from flask import Blueprint, request, jsonify
+from app.users.schemas import UserCreateSchema, UserResponseSchema
+from app.users.services import UserService
+
+users_bp = Blueprint("users", __name__)
+
+@users_bp.route("/", methods=["POST"])
+def create_user():
+    schema = UserCreateSchema()
+    data = schema.load(request.get_json())
+
+    user = UserService.create(data)
+
+    return jsonify(UserResponseSchema().dump(user)), 201
+
+@users_bp.route("/<int:user_id>")
+def get_user(user_id: int):
+    user = UserService.get_by_id(user_id)
+    if not user:
+        return jsonify({"error": "User not found"}), 404
+    return jsonify(UserResponseSchema().dump(user))
+```
+
+### Extensions
+
+```python
+# extensions.py
+from flask_sqlalchemy import SQLAlchemy
+from flask_migrate import Migrate
+from flask_jwt_extended import JWTManager
+
+db = SQLAlchemy()
+migrate = Migrate()
+jwt = JWTManager()
+```
+
+## Marshmallow Schemas
+
+```python
+from marshmallow import Schema, fields, validate, 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 UserResponseSchema(Schema):
+    id = fields.Int(dump_only=True)
+    email = fields.Email()
+    name = fields.Str()
+    created_at = fields.DateTime(dump_only=True)
+```
+
+## SQLAlchemy 2.0
+
+```python
+from sqlalchemy.orm import Mapped, mapped_column
+from app.extensions import db
+
+class User(db.Model):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    email: Mapped[str] = mapped_column(unique=True, index=True)
+    hashed_password: Mapped[str]
+    name: Mapped[str] = mapped_column(db.String(100))
+    is_active: Mapped[bool] = mapped_column(default=True)
+```
+
+## Error Handling
+
+```python
+from flask import jsonify
+from werkzeug.exceptions import HTTPException
+
+def register_error_handlers(app):
+    @app.errorhandler(HTTPException)
+    def handle_http_error(error):
+        return jsonify({
+            "error": error.name,
+            "message": error.description,
+        }), error.code
+
+    @app.errorhandler(ValidationError)
+    def handle_validation_error(error):
+        return jsonify({
+            "error": "Validation Error",
+            "details": error.messages,
+        }), 400
+```
+
+## Commands
+
+```bash
+flask run                         # Dev server
+flask db upgrade                  # Run migrations
+flask db migrate -m "message"     # Generate migration
+pytest                            # Run tests
+pytest --cov=app                  # Coverage
+ruff check . && ruff format .    # Lint + format
+```