@malamute/ai-rules 1.0.0 → 1.2.0

package/configs/fastapi/CLAUDE.md

@@ -0,0 +1,144 @@
+# FastAPI Project Guidelines
+
+@../_shared/CLAUDE.md
+
+## Stack
+
+- Python 3.12+
+- FastAPI 0.115+ (Pydantic v2 by default)
+- SQLAlchemy 2.0+ (async support)
+- Pydantic v2 for validation
+- pytest + httpx for testing
+- uv or poetry for dependencies
+
+## Architecture
+
+```
+src/app/
+├── main.py              # Entry point
+├── config.py            # Settings (pydantic-settings)
+├── database.py          # DB session, engine
+├── [domain]/            # Feature modules
+│   ├── router.py        # API endpoints
+│   ├── schemas.py       # Pydantic models (request/response)
+│   ├── models.py        # SQLAlchemy models
+│   ├── service.py       # Business logic
+│   ├── repository.py    # Data access
+│   └── dependencies.py  # Route dependencies
+├── core/                # Shared utilities
+│   ├── exceptions.py
+│   └── security.py
+└── common/
+    ├── models.py        # Base models
+    └── schemas.py       # Shared schemas
+```
+
+## FastAPI Patterns
+
+### Dependency Injection
+
+```python
+from typing import Annotated
+from fastapi import Depends
+
+CurrentUser = Annotated[User, Depends(get_current_user)]
+DbSession = Annotated[AsyncSession, Depends(get_db)]
+
+@router.get("/users/me")
+async def get_me(user: CurrentUser, db: DbSession) -> UserResponse:
+    return await user_service.get_profile(db, user.id)
+```
+
+### Lifespan (not `on_event`)
+
+```python
+from contextlib import asynccontextmanager
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    app.state.db = await create_engine()
+    app.state.redis = await aioredis.from_url(settings.redis_url)
+    yield
+    # Shutdown
+    await app.state.db.dispose()
+    await app.state.redis.close()
+
+app = FastAPI(lifespan=lifespan)
+```
+
+### Response Models
+
+```python
+@router.get(
+    "/users/{user_id}",
+    response_model=UserResponse,
+    status_code=status.HTTP_200_OK,
+)
+async def get_user(user_id: int, db: DbSession) -> User:
+    user = await user_repo.get(db, user_id)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    return user
+```
+
+## Pydantic v2
+
+```python
+from pydantic import BaseModel, ConfigDict, Field, EmailStr
+
+class UserBase(BaseModel):
+    email: EmailStr
+    name: str = Field(min_length=1, max_length=100)
+
+class UserCreate(UserBase):
+    password: str = Field(min_length=8)
+
+class UserResponse(UserBase):
+    id: int
+    model_config = ConfigDict(from_attributes=True)
+```
+
+## SQLAlchemy 2.0
+
+```python
+from sqlalchemy.orm import Mapped, mapped_column, DeclarativeBase
+
+class Base(DeclarativeBase):
+    pass
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    email: Mapped[str] = mapped_column(unique=True, index=True)
+    hashed_password: Mapped[str]
+    is_active: Mapped[bool] = mapped_column(default=True)
+```
+
+## Error Handling
+
+```python
+class AppException(Exception):
+    def __init__(self, status_code: int, detail: str):
+        self.status_code = status_code
+        self.detail = detail
+
+@app.exception_handler(AppException)
+async def app_exception_handler(request: Request, exc: AppException):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"error": exc.detail},
+    )
+```
+
+## Commands
+
+```bash
+uvicorn app.main:app --reload    # Dev server
+pytest                            # Run tests
+pytest --cov=app                  # Coverage
+ruff check . && ruff format .    # Lint + format
+alembic upgrade head             # Run migrations
+alembic revision --autogenerate  # Generate migration
+```

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

@@ -0,0 +1,208 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Flask Blueprint Patterns
+
+## Basic Blueprint
+
+```python
+# GOOD - organized blueprint
+from flask import Blueprint, request, jsonify
+
+users_bp = Blueprint("users", __name__)
+
+@users_bp.route("/", methods=["GET"])
+def list_users():
+    """List all users."""
+    users = UserService.get_all()
+    return jsonify(UserSchema(many=True).dump(users))
+
+@users_bp.route("/", methods=["POST"])
+def create_user():
+    """Create a new user."""
+    schema = UserCreateSchema()
+    data = schema.load(request.get_json())
+    user = UserService.create(data)
+    return jsonify(UserSchema().dump(user)), 201
+
+@users_bp.route("/<int:user_id>")
+def get_user(user_id: int):
+    """Get user by ID."""
+    user = UserService.get_by_id(user_id)
+    if not user:
+        return jsonify({"error": "User not found"}), 404
+    return jsonify(UserSchema().dump(user))
+```
+
+## Blueprint Registration
+
+```python
+# app/__init__.py
+from flask import Flask
+
+def create_app(config_name: str = "development") -> Flask:
+    app = Flask(__name__)
+    app.config.from_object(config[config_name])
+
+    # Register blueprints
+    from app.users import users_bp
+    from app.auth import auth_bp
+    from app.products import products_bp
+
+    app.register_blueprint(users_bp, url_prefix="/api/v1/users")
+    app.register_blueprint(auth_bp, url_prefix="/api/v1/auth")
+    app.register_blueprint(products_bp, url_prefix="/api/v1/products")
+
+    return app
+```
+
+## Blueprint with Resources
+
+```python
+# app/users/__init__.py
+from flask import Blueprint
+
+users_bp = Blueprint("users", __name__)
+
+# Import routes after blueprint creation to avoid circular imports
+from app.users import routes  # noqa: E402, F401
+```
+
+```python
+# app/users/routes.py
+from app.users import users_bp
+from app.users.schemas import UserSchema, UserCreateSchema
+from app.users.services import UserService
+
+@users_bp.route("/", methods=["GET"])
+def list_users():
+    ...
+```
+
+## Nested Blueprints
+
+```python
+# API versioning with nested blueprints
+api_v1 = Blueprint("api_v1", __name__, url_prefix="/api/v1")
+api_v2 = Blueprint("api_v2", __name__, url_prefix="/api/v2")
+
+# Register child blueprints
+api_v1.register_blueprint(users_bp, url_prefix="/users")
+api_v1.register_blueprint(products_bp, url_prefix="/products")
+
+api_v2.register_blueprint(users_v2_bp, url_prefix="/users")
+
+# Register with app
+app.register_blueprint(api_v1)
+app.register_blueprint(api_v2)
+```
+
+## Blueprint-Specific Error Handlers
+
+```python
+users_bp = Blueprint("users", __name__)
+
+@users_bp.errorhandler(404)
+def user_not_found(error):
+    return jsonify({"error": "User not found"}), 404
+
+@users_bp.errorhandler(ValidationError)
+def validation_error(error):
+    return jsonify({"error": "Validation failed", "details": error.messages}), 400
+```
+
+## Blueprint Hooks
+
+```python
+users_bp = Blueprint("users", __name__)
+
+@users_bp.before_request
+def before_user_request():
+    """Run before every request to this blueprint."""
+    # Verify API key, log request, etc.
+    if not verify_api_key(request.headers.get("X-API-Key")):
+        return jsonify({"error": "Invalid API key"}), 401
+
+@users_bp.after_request
+def after_user_request(response):
+    """Run after every request to this blueprint."""
+    response.headers["X-Blueprint"] = "users"
+    return response
+```
+
+## Blueprint URL Builders
+
+```python
+from flask import url_for
+
+# Build URL for blueprint route
+url = url_for("users.get_user", user_id=1)  # /api/v1/users/1
+
+# With external URL
+url = url_for("users.get_user", user_id=1, _external=True)
+# https://example.com/api/v1/users/1
+```
+
+## Blueprint Templates
+
+```python
+# Blueprint with templates
+users_bp = Blueprint(
+    "users",
+    __name__,
+    template_folder="templates",
+    static_folder="static",
+)
+
+@users_bp.route("/profile")
+def profile():
+    return render_template("users/profile.html")  # From blueprint's templates/
+```
+
+## Blueprint Context Processor
+
+```python
+@users_bp.context_processor
+def user_context():
+    """Add variables to all templates rendered by this blueprint."""
+    return {
+        "current_user": get_current_user(),
+        "user_count": User.query.count(),
+    }
+```
+
+## Class-Based Views with Blueprints
+
+```python
+from flask.views import MethodView
+
+class UserAPI(MethodView):
+    def get(self, user_id: int | None = None):
+        if user_id is None:
+            return jsonify(UserSchema(many=True).dump(User.query.all()))
+        user = User.query.get_or_404(user_id)
+        return jsonify(UserSchema().dump(user))
+
+    def post(self):
+        data = UserCreateSchema().load(request.get_json())
+        user = UserService.create(data)
+        return jsonify(UserSchema().dump(user)), 201
+
+    def put(self, user_id: int):
+        user = User.query.get_or_404(user_id)
+        data = UserUpdateSchema().load(request.get_json())
+        user = UserService.update(user, data)
+        return jsonify(UserSchema().dump(user))
+
+    def delete(self, user_id: int):
+        user = User.query.get_or_404(user_id)
+        UserService.delete(user)
+        return "", 204
+
+# Register view
+user_view = UserAPI.as_view("user_api")
+users_bp.add_url_rule("/", view_func=user_view, methods=["GET", "POST"])
+users_bp.add_url_rule("/<int:user_id>", view_func=user_view, methods=["GET", "PUT", "DELETE"])
+```

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

@@ -0,0 +1,285 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Flask CLI Commands
+
+## Basic Commands
+
+```python
+import click
+from flask import Flask
+from flask.cli import with_appcontext
+
+app = Flask(__name__)
+
+@app.cli.command("init-db")
+@with_appcontext
+def init_db_command():
+    """Initialize the database."""
+    db.create_all()
+    click.echo("Database initialized.")
+
+@app.cli.command("seed")
+@with_appcontext
+def seed_command():
+    """Seed the database with sample data."""
+    from app.seeds import seed_all
+    seed_all()
+    click.echo("Database seeded.")
+
+# Usage:
+# flask init-db
+# flask seed
+```
+
+## Commands with Arguments
+
+```python
+@app.cli.command("create-user")
+@click.argument("email")
+@click.argument("name")
+@click.option("--admin", is_flag=True, help="Make user an admin")
+@with_appcontext
+def create_user_command(email: str, name: str, admin: bool):
+    """Create a new user."""
+    user = User(email=email, name=name, is_admin=admin)
+    db.session.add(user)
+    db.session.commit()
+    click.echo(f"Created user: {user.email} (admin={admin})")
+
+# Usage:
+# flask create-user john@example.com "John Doe"
+# flask create-user admin@example.com "Admin" --admin
+```
+
+## Commands with Options
+
+```python
+@app.cli.command("export-users")
+@click.option("--format", type=click.Choice(["json", "csv"]), default="json")
+@click.option("--output", "-o", type=click.Path(), default="users.json")
+@click.option("--active-only", is_flag=True, help="Export only active users")
+@with_appcontext
+def export_users_command(format: str, output: str, active_only: bool):
+    """Export users to a file."""
+    query = User.query
+    if active_only:
+        query = query.filter(User.is_active == True)
+
+    users = query.all()
+
+    if format == "json":
+        data = UserSchema(many=True).dump(users)
+        with open(output, "w") as f:
+            json.dump(data, f, indent=2)
+    elif format == "csv":
+        # CSV export logic
+        pass
+
+    click.echo(f"Exported {len(users)} users to {output}")
+
+# Usage:
+# flask export-users --format csv -o users.csv --active-only
+```
+
+## Command Groups
+
+```python
+@app.cli.group()
+def user():
+    """User management commands."""
+    pass
+
+@user.command("create")
+@click.argument("email")
+@click.argument("name")
+@with_appcontext
+def user_create(email: str, name: str):
+    """Create a new user."""
+    user = User(email=email, name=name)
+    db.session.add(user)
+    db.session.commit()
+    click.echo(f"Created: {user.email}")
+
+@user.command("delete")
+@click.argument("email")
+@click.confirmation_option(prompt="Are you sure?")
+@with_appcontext
+def user_delete(email: str):
+    """Delete a user."""
+    user = User.query.filter_by(email=email).first()
+    if not user:
+        click.echo(f"User not found: {email}", err=True)
+        return
+
+    db.session.delete(user)
+    db.session.commit()
+    click.echo(f"Deleted: {email}")
+
+@user.command("list")
+@click.option("--limit", default=10)
+@with_appcontext
+def user_list(limit: int):
+    """List users."""
+    users = User.query.limit(limit).all()
+    for user in users:
+        click.echo(f"{user.id}: {user.email} ({user.name})")
+
+# Usage:
+# flask user create john@example.com "John"
+# flask user delete john@example.com
+# flask user list --limit 20
+```
+
+## Blueprint Commands
+
+```python
+# In blueprint
+from flask import Blueprint
+
+users_bp = Blueprint("users", __name__, cli_group="users")
+
+@users_bp.cli.command("sync")
+@with_appcontext
+def sync_users():
+    """Sync users from external source."""
+    # Sync logic
+    click.echo("Users synced")
+
+# Usage:
+# flask users sync
+```
+
+## Progress Bars
+
+```python
+@app.cli.command("migrate-data")
+@with_appcontext
+def migrate_data_command():
+    """Migrate data with progress bar."""
+    records = OldModel.query.all()
+
+    with click.progressbar(records, label="Migrating") as bar:
+        for record in bar:
+            new_record = migrate_record(record)
+            db.session.add(new_record)
+
+    db.session.commit()
+    click.echo("Migration complete!")
+```
+
+## Colored Output
+
+```python
+@app.cli.command("check")
+@with_appcontext
+def check_command():
+    """Check application health."""
+    # Database
+    try:
+        db.session.execute("SELECT 1")
+        click.secho("✓ Database: OK", fg="green")
+    except Exception as e:
+        click.secho(f"✗ Database: {e}", fg="red")
+
+    # Redis
+    try:
+        redis_client.ping()
+        click.secho("✓ Redis: OK", fg="green")
+    except Exception as e:
+        click.secho(f"✗ Redis: {e}", fg="red")
+
+    # External API
+    try:
+        response = requests.get(f"{API_URL}/health", timeout=5)
+        response.raise_for_status()
+        click.secho("✓ External API: OK", fg="green")
+    except Exception as e:
+        click.secho(f"✗ External API: {e}", fg="yellow")
+```
+
+## Interactive Prompts
+
+```python
+@app.cli.command("setup")
+def setup_command():
+    """Interactive setup wizard."""
+    click.echo("Welcome to the setup wizard!")
+
+    # Text input
+    app_name = click.prompt("Application name", default="My App")
+
+    # Password input
+    secret = click.prompt("Secret key", hide_input=True)
+
+    # Choice
+    env = click.prompt(
+        "Environment",
+        type=click.Choice(["development", "staging", "production"]),
+        default="development",
+    )
+
+    # Confirmation
+    if click.confirm("Save configuration?"):
+        save_config(app_name=app_name, secret=secret, env=env)
+        click.echo("Configuration saved!")
+    else:
+        click.echo("Aborted.")
+```
+
+## Async Commands (Flask 2.0+)
+
+```python
+import asyncio
+
+@app.cli.command("async-task")
+@with_appcontext
+def async_task_command():
+    """Run async task."""
+    asyncio.run(run_async_task())
+
+async def run_async_task():
+    async with aiohttp.ClientSession() as session:
+        async with session.get("https://api.example.com/data") as response:
+            data = await response.json()
+            click.echo(f"Fetched {len(data)} records")
+```
+
+## Custom CLI Script
+
+```python
+# manage.py
+import click
+from app import create_app, db
+
+app = create_app()
+
+@click.group()
+def cli():
+    """Management script."""
+    pass
+
+@cli.command()
+def runserver():
+    """Run development server."""
+    app.run(debug=True)
+
+@cli.command()
+@click.option("--drop", is_flag=True, help="Drop tables first")
+def initdb(drop: bool):
+    """Initialize database."""
+    with app.app_context():
+        if drop:
+            db.drop_all()
+        db.create_all()
+        click.echo("Database initialized.")
+
+if __name__ == "__main__":
+    cli()
+
+# Usage:
+# python manage.py runserver
+# python manage.py initdb --drop
+```