@malamute/ai-rules 1.0.0 → 1.2.0

package/configs/flask/.claude/rules/error-handlers.md

@@ -0,0 +1,278 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Flask Error Handling
+
+## HTTP Error Handlers
+
+```python
+from flask import jsonify, render_template
+from werkzeug.exceptions import HTTPException
+
+# JSON API error handler
+@app.errorhandler(HTTPException)
+def handle_http_exception(error):
+    return jsonify({
+        "error": error.name,
+        "message": error.description,
+        "status_code": error.code,
+    }), error.code
+
+# Specific error handlers
+@app.errorhandler(404)
+def not_found(error):
+    if request.accept_mimetypes.accept_json:
+        return jsonify({"error": "Not found"}), 404
+    return render_template("errors/404.html"), 404
+
+@app.errorhandler(500)
+def internal_error(error):
+    db.session.rollback()  # Rollback failed transaction
+    return jsonify({"error": "Internal server error"}), 500
+
+@app.errorhandler(429)
+def rate_limit_exceeded(error):
+    return jsonify({
+        "error": "Rate limit exceeded",
+        "retry_after": error.description,
+    }), 429
+```
+
+## Custom Exception Classes
+
+```python
+class AppException(Exception):
+    """Base exception for application errors."""
+    status_code = 500
+    error_code = "INTERNAL_ERROR"
+    message = "An unexpected error occurred"
+
+    def __init__(self, message: str = None, payload: dict = None):
+        super().__init__()
+        self.message = message or self.message
+        self.payload = payload
+
+    def to_dict(self) -> dict:
+        rv = {
+            "error": self.error_code,
+            "message": self.message,
+        }
+        if self.payload:
+            rv["details"] = self.payload
+        return rv
+
+class NotFoundError(AppException):
+    status_code = 404
+    error_code = "NOT_FOUND"
+    message = "Resource not found"
+
+class ValidationError(AppException):
+    status_code = 400
+    error_code = "VALIDATION_ERROR"
+    message = "Validation failed"
+
+class UnauthorizedError(AppException):
+    status_code = 401
+    error_code = "UNAUTHORIZED"
+    message = "Authentication required"
+
+class ForbiddenError(AppException):
+    status_code = 403
+    error_code = "FORBIDDEN"
+    message = "Access denied"
+
+class ConflictError(AppException):
+    status_code = 409
+    error_code = "CONFLICT"
+    message = "Resource already exists"
+
+# Register handler
+@app.errorhandler(AppException)
+def handle_app_exception(error):
+    response = jsonify(error.to_dict())
+    response.status_code = error.status_code
+    return response
+
+# Usage
+@users_bp.route("/<int:user_id>")
+def get_user(user_id: int):
+    user = User.query.get(user_id)
+    if not user:
+        raise NotFoundError(f"User {user_id} not found")
+    return jsonify(UserSchema().dump(user))
+```
+
+## Marshmallow Validation Errors
+
+```python
+from marshmallow import ValidationError as MarshmallowValidationError
+
+@app.errorhandler(MarshmallowValidationError)
+def handle_validation_error(error):
+    return jsonify({
+        "error": "VALIDATION_ERROR",
+        "message": "Input validation failed",
+        "details": error.messages,
+    }), 400
+
+# Usage
+@users_bp.route("/", methods=["POST"])
+def create_user():
+    schema = UserCreateSchema()
+    data = schema.load(request.get_json())  # Raises ValidationError if invalid
+    user = UserService.create(data)
+    return jsonify(UserSchema().dump(user)), 201
+```
+
+## SQLAlchemy Errors
+
+```python
+from sqlalchemy.exc import IntegrityError, SQLAlchemyError
+
+@app.errorhandler(IntegrityError)
+def handle_integrity_error(error):
+    db.session.rollback()
+
+    # Parse constraint violation
+    if "unique constraint" in str(error.orig).lower():
+        return jsonify({
+            "error": "DUPLICATE_ENTRY",
+            "message": "A record with this value already exists",
+        }), 409
+
+    return jsonify({
+        "error": "DATABASE_ERROR",
+        "message": "Database constraint violation",
+    }), 400
+
+@app.errorhandler(SQLAlchemyError)
+def handle_db_error(error):
+    db.session.rollback()
+    app.logger.error(f"Database error: {error}")
+    return jsonify({
+        "error": "DATABASE_ERROR",
+        "message": "A database error occurred",
+    }), 500
+```
+
+## Logging Errors
+
+```python
+import logging
+import traceback
+
+@app.errorhandler(Exception)
+def handle_unexpected_error(error):
+    # Log full traceback
+    app.logger.error(
+        "Unhandled exception",
+        extra={
+            "error": str(error),
+            "traceback": traceback.format_exc(),
+            "path": request.path,
+            "method": request.method,
+            "user_id": g.get("user_id"),
+        },
+    )
+
+    # Return generic error to client
+    if app.debug:
+        return jsonify({
+            "error": "INTERNAL_ERROR",
+            "message": str(error),
+            "traceback": traceback.format_exc(),
+        }), 500
+
+    return jsonify({
+        "error": "INTERNAL_ERROR",
+        "message": "An unexpected error occurred",
+    }), 500
+```
+
+## Blueprint Error Handlers
+
+```python
+users_bp = Blueprint("users", __name__)
+
+# Only handles errors from this blueprint
+@users_bp.errorhandler(404)
+def user_not_found(error):
+    return jsonify({
+        "error": "USER_NOT_FOUND",
+        "message": "The requested user was not found",
+    }), 404
+
+# App-level handler is fallback
+@app.errorhandler(404)
+def generic_not_found(error):
+    return jsonify({
+        "error": "NOT_FOUND",
+        "message": "Resource not found",
+    }), 404
+```
+
+## Error Response Format
+
+```python
+from dataclasses import dataclass
+from typing import Any
+
+@dataclass
+class ErrorResponse:
+    error: str
+    message: str
+    status_code: int
+    details: dict[str, Any] | None = None
+    request_id: str | None = None
+
+    def to_dict(self) -> dict:
+        data = {
+            "error": self.error,
+            "message": self.message,
+        }
+        if self.details:
+            data["details"] = self.details
+        if self.request_id:
+            data["request_id"] = self.request_id
+        return data
+
+def error_response(
+    error: str,
+    message: str,
+    status_code: int,
+    details: dict = None,
+) -> tuple:
+    response = ErrorResponse(
+        error=error,
+        message=message,
+        status_code=status_code,
+        details=details,
+        request_id=g.get("request_id"),
+    )
+    return jsonify(response.to_dict()), status_code
+```
+
+## Abort with Custom Response
+
+```python
+from flask import abort
+
+@users_bp.route("/<int:user_id>")
+def get_user(user_id: int):
+    user = User.query.get(user_id)
+    if not user:
+        abort(404, description="User not found")
+    return jsonify(UserSchema().dump(user))
+
+# Or with custom response
+from werkzeug.exceptions import NotFound
+
+@users_bp.route("/<int:user_id>")
+def get_user(user_id: int):
+    user = User.query.get(user_id)
+    if not user:
+        raise NotFound(f"User with ID {user_id} not found")
+    return jsonify(UserSchema().dump(user))
+```

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

@@ -0,0 +1,278 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Flask Extensions Patterns
+
+## Extension Initialization
+
+```python
+# GOOD - Lazy initialization (extensions.py)
+from flask_sqlalchemy import SQLAlchemy
+from flask_migrate import Migrate
+from flask_jwt_extended import JWTManager
+from flask_cors import CORS
+from flask_mail import Mail
+
+db = SQLAlchemy()
+migrate = Migrate()
+jwt = JWTManager()
+cors = CORS()
+mail = Mail()
+
+# In factory (app/__init__.py)
+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)
+    jwt.init_app(app)
+    cors.init_app(app)
+    mail.init_app(app)
+
+    return app
+
+# BAD - Eager initialization
+from flask import Flask
+from flask_sqlalchemy import SQLAlchemy
+
+app = Flask(__name__)
+db = SQLAlchemy(app)  # Can't use different configs!
+```
+
+## Flask-SQLAlchemy
+
+```python
+from app.extensions import db
+from sqlalchemy.orm import Mapped, mapped_column
+
+class User(db.Model):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    email: Mapped[str] = mapped_column(unique=True, index=True)
+    name: Mapped[str] = mapped_column(db.String(100))
+    is_active: Mapped[bool] = mapped_column(default=True)
+
+    # Relationships
+    orders: Mapped[list["Order"]] = db.relationship(back_populates="user")
+
+# Usage in routes
+@users_bp.route("/")
+def list_users():
+    users = db.session.scalars(db.select(User).where(User.is_active)).all()
+    return jsonify(UserSchema(many=True).dump(users))
+```
+
+## Flask-Migrate
+
+```python
+# migrations/env.py is auto-generated
+# Commands:
+# flask db init        - Initialize migrations
+# flask db migrate -m "Add users table"
+# flask db upgrade     - Apply migrations
+# flask db downgrade   - Rollback last migration
+# flask db current     - Show current revision
+# flask db history     - Show migration history
+```
+
+## Flask-JWT-Extended
+
+```python
+from flask_jwt_extended import (
+    create_access_token,
+    create_refresh_token,
+    jwt_required,
+    current_user,
+    get_jwt_identity,
+)
+
+# Configure in factory
+app.config["JWT_SECRET_KEY"] = os.environ["JWT_SECRET_KEY"]
+app.config["JWT_ACCESS_TOKEN_EXPIRES"] = timedelta(hours=1)
+app.config["JWT_REFRESH_TOKEN_EXPIRES"] = timedelta(days=30)
+
+# User loader callback
+@jwt.user_lookup_loader
+def user_lookup_callback(_jwt_header, jwt_data):
+    identity = jwt_data["sub"]
+    return User.query.get(identity)
+
+# Login endpoint
+@auth_bp.route("/login", methods=["POST"])
+def login():
+    data = LoginSchema().load(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"}), 401
+
+    access_token = create_access_token(identity=user.id)
+    refresh_token = create_refresh_token(identity=user.id)
+
+    return jsonify({
+        "access_token": access_token,
+        "refresh_token": refresh_token,
+    })
+
+# Protected endpoint
+@users_bp.route("/me")
+@jwt_required()
+def get_current_user():
+    return jsonify(UserSchema().dump(current_user))
+
+# Refresh token
+@auth_bp.route("/refresh", methods=["POST"])
+@jwt_required(refresh=True)
+def refresh():
+    identity = get_jwt_identity()
+    access_token = create_access_token(identity=identity)
+    return jsonify({"access_token": access_token})
+```
+
+## Flask-CORS
+
+```python
+from flask_cors import CORS
+
+# Global CORS
+cors.init_app(app, resources={
+    r"/api/*": {
+        "origins": ["https://example.com"],
+        "methods": ["GET", "POST", "PUT", "DELETE"],
+        "allow_headers": ["Authorization", "Content-Type"],
+    }
+})
+
+# Blueprint-specific CORS
+CORS(users_bp, origins=["https://admin.example.com"])
+
+# Route-specific
+from flask_cors import cross_origin
+
+@app.route("/public")
+@cross_origin(origins="*")
+def public_endpoint():
+    return jsonify({"public": True})
+```
+
+## Flask-Mail
+
+```python
+from flask_mail import Message
+from app.extensions import mail
+
+def send_welcome_email(user: User):
+    msg = Message(
+        subject="Welcome!",
+        sender="noreply@example.com",
+        recipients=[user.email],
+    )
+    msg.body = f"Hello {user.name}, welcome to our platform!"
+    msg.html = render_template("emails/welcome.html", user=user)
+
+    mail.send(msg)
+
+# Async email sending
+from threading import Thread
+
+def send_async_email(app, msg):
+    with app.app_context():
+        mail.send(msg)
+
+def send_email_async(msg):
+    Thread(target=send_async_email, args=(current_app._get_current_object(), msg)).start()
+```
+
+## Flask-Caching
+
+```python
+from flask_caching import Cache
+
+cache = Cache()
+
+# Configuration
+app.config["CACHE_TYPE"] = "redis"
+app.config["CACHE_REDIS_URL"] = os.environ["REDIS_URL"]
+app.config["CACHE_DEFAULT_TIMEOUT"] = 300
+
+cache.init_app(app)
+
+# Usage
+@users_bp.route("/<int:user_id>")
+@cache.cached(timeout=60, key_prefix="user")
+def get_user(user_id: int):
+    user = User.query.get_or_404(user_id)
+    return jsonify(UserSchema().dump(user))
+
+# Memoize (cache with arguments)
+@cache.memoize(timeout=300)
+def get_user_stats(user_id: int) -> dict:
+    return calculate_stats(user_id)
+
+# Clear cache
+cache.delete("user")
+cache.delete_memoized(get_user_stats, user_id)
+```
+
+## Flask-Limiter
+
+```python
+from flask_limiter import Limiter
+from flask_limiter.util import get_remote_address
+
+limiter = Limiter(
+    key_func=get_remote_address,
+    default_limits=["100 per hour"],
+    storage_uri="redis://localhost:6379",
+)
+
+limiter.init_app(app)
+
+# Route-specific limits
+@auth_bp.route("/login", methods=["POST"])
+@limiter.limit("5 per minute")
+def login():
+    ...
+
+# Blueprint limits
+limiter.limit("50 per hour")(users_bp)
+
+# Exempt from limits
+@app.route("/health")
+@limiter.exempt
+def health():
+    return jsonify({"status": "ok"})
+```
+
+## Flask-Login (Session-Based)
+
+```python
+from flask_login import LoginManager, login_user, logout_user, login_required, current_user
+
+login_manager = LoginManager()
+login_manager.login_view = "auth.login"
+
+@login_manager.user_loader
+def load_user(user_id):
+    return User.query.get(int(user_id))
+
+# Login
+@auth_bp.route("/login", methods=["POST"])
+def login():
+    user = authenticate(request.form["email"], request.form["password"])
+    if user:
+        login_user(user, remember=True)
+        return redirect(url_for("main.index"))
+    return render_template("login.html", error="Invalid credentials")
+
+# Protected route
+@main_bp.route("/dashboard")
+@login_required
+def dashboard():
+    return render_template("dashboard.html", user=current_user)
+```

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

@@ -0,0 +1,171 @@
+# Flask Rules
+
+## Activation
+
+```yaml
+paths:
+  - "**/*.py"
+```
+
+## Application Factory
+
+```python
+# GOOD - Application factory pattern
+def create_app(config_name: str = "development") -> Flask:
+    app = Flask(__name__)
+    app.config.from_object(config[config_name])
+
+    db.init_app(app)
+    register_blueprints(app)
+
+    return app
+
+# BAD - Global app instance
+app = Flask(__name__)  # Hard to test, can't have multiple configs
+```
+
+## Blueprints
+
+```python
+# GOOD - Organized blueprints
+from flask import Blueprint
+
+users_bp = Blueprint("users", __name__)
+
+@users_bp.route("/", methods=["GET"])
+def list_users():
+    ...
+
+# Register in factory
+app.register_blueprint(users_bp, url_prefix="/api/v1/users")
+
+# BAD - All routes in one file
+@app.route("/api/v1/users")
+@app.route("/api/v1/posts")
+@app.route("/api/v1/comments")  # Messy, hard to maintain
+```
+
+## Request Handling
+
+```python
+# GOOD - Validate input with schemas
+from marshmallow import ValidationError
+
+@users_bp.route("/", methods=["POST"])
+def create_user():
+    try:
+        data = UserCreateSchema().load(request.get_json())
+    except ValidationError as e:
+        return jsonify({"errors": e.messages}), 400
+
+    user = user_service.create(data)
+    return jsonify(UserResponseSchema().dump(user)), 201
+
+# BAD - Direct access without validation
+@users_bp.route("/", methods=["POST"])
+def create_user():
+    data = request.get_json()
+    user = User(email=data["email"])  # No validation!
+    db.session.add(user)
+    db.session.commit()
+    return jsonify(user.to_dict())
+```
+
+## Context Management
+
+```python
+# GOOD - Use application context
+with app.app_context():
+    db.create_all()
+
+# GOOD - Use test request context
+with app.test_request_context():
+    url = url_for("users.get_user", user_id=1)
+
+# BAD - Access outside context
+db.create_all()  # RuntimeError: No application context
+```
+
+## Configuration
+
+```python
+# GOOD - Class-based config
+class Config:
+    SECRET_KEY = os.environ.get("SECRET_KEY", "dev-key")
+    SQLALCHEMY_TRACK_MODIFICATIONS = False
+
+class DevelopmentConfig(Config):
+    DEBUG = True
+    SQLALCHEMY_DATABASE_URI = "sqlite:///dev.db"
+
+class ProductionConfig(Config):
+    DEBUG = False
+    SQLALCHEMY_DATABASE_URI = os.environ["DATABASE_URL"]
+
+config = {
+    "development": DevelopmentConfig,
+    "production": ProductionConfig,
+    "testing": TestingConfig,
+}
+
+# BAD - Hardcoded config
+app.config["SECRET_KEY"] = "hardcoded-secret"  # Never do this
+```
+
+## Testing
+
+```python
+# GOOD - Test client fixture
+import pytest
+
+@pytest.fixture
+def app():
+    app = create_app("testing")
+    return app
+
+@pytest.fixture
+def client(app):
+    return app.test_client()
+
+@pytest.fixture
+def db_session(app):
+    with app.app_context():
+        db.create_all()
+        yield db.session
+        db.drop_all()
+
+def test_create_user(client):
+    response = client.post("/api/v1/users", json={
+        "email": "test@example.com",
+        "password": "password123",
+        "name": "Test User",
+    })
+    assert response.status_code == 201
+    assert response.json["email"] == "test@example.com"
+```
+
+## Extensions Pattern
+
+```python
+# GOOD - Lazy initialization
+# extensions.py
+from flask_sqlalchemy import SQLAlchemy
+from flask_migrate import Migrate
+
+db = SQLAlchemy()
+migrate = Migrate()
+
+# __init__.py
+def create_app():
+    app = Flask(__name__)
+    db.init_app(app)
+    migrate.init_app(app, db)
+    return app
+
+# BAD - Eager initialization
+from flask import Flask
+from flask_sqlalchemy import SQLAlchemy
+
+app = Flask(__name__)
+db = SQLAlchemy(app)  # Can't use different configs
+```