@malamute/ai-rules 1.0.0 → 1.3.0

package/configs/flask/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
+```

package/configs/flask/rules/configuration.md

@@ -0,0 +1,281 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Flask Configuration Patterns
+
+## Class-Based Configuration
+
+```python
+# config.py
+import os
+from datetime import timedelta
+
+class Config:
+    """Base configuration."""
+    SECRET_KEY = os.environ.get("SECRET_KEY", "dev-secret-key")
+    SQLALCHEMY_TRACK_MODIFICATIONS = False
+
+    # JWT
+    JWT_SECRET_KEY = os.environ.get("JWT_SECRET_KEY", SECRET_KEY)
+    JWT_ACCESS_TOKEN_EXPIRES = timedelta(hours=1)
+    JWT_REFRESH_TOKEN_EXPIRES = timedelta(days=30)
+
+    # Mail
+    MAIL_SERVER = os.environ.get("MAIL_SERVER", "localhost")
+    MAIL_PORT = int(os.environ.get("MAIL_PORT", 587))
+    MAIL_USE_TLS = True
+
+class DevelopmentConfig(Config):
+    """Development configuration."""
+    DEBUG = True
+    SQLALCHEMY_DATABASE_URI = os.environ.get(
+        "DATABASE_URL",
+        "postgresql://localhost/app_dev"
+    )
+    SQLALCHEMY_ECHO = True  # Log SQL queries
+
+class TestingConfig(Config):
+    """Testing configuration."""
+    TESTING = True
+    SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:"
+    WTF_CSRF_ENABLED = False
+
+class ProductionConfig(Config):
+    """Production configuration."""
+    DEBUG = False
+    SQLALCHEMY_DATABASE_URI = os.environ["DATABASE_URL"]
+
+    # Security
+    SESSION_COOKIE_SECURE = True
+    SESSION_COOKIE_HTTPONLY = True
+    SESSION_COOKIE_SAMESITE = "Lax"
+
+config = {
+    "development": DevelopmentConfig,
+    "testing": TestingConfig,
+    "production": ProductionConfig,
+    "default": DevelopmentConfig,
+}
+```
+
+## Loading Configuration
+
+```python
+# app/__init__.py
+from flask import Flask
+from config import config
+
+def create_app(config_name: str = None) -> Flask:
+    if config_name is None:
+        config_name = os.environ.get("FLASK_CONFIG", "development")
+
+    app = Flask(__name__)
+    app.config.from_object(config[config_name])
+
+    # Load additional config from file
+    app.config.from_pyfile("config.py", silent=True)
+
+    # Load from environment variable pointing to file
+    app.config.from_envvar("APP_CONFIG_FILE", silent=True)
+
+    return app
+```
+
+## Environment Variables
+
+```python
+# .env (development)
+FLASK_APP=app
+FLASK_CONFIG=development
+SECRET_KEY=your-secret-key
+DATABASE_URL=postgresql://user:pass@localhost/app_dev
+REDIS_URL=redis://localhost:6379/0
+
+# Load with python-dotenv
+from dotenv import load_dotenv
+load_dotenv()
+
+# Or in create_app
+def create_app(config_name: str = None) -> Flask:
+    load_dotenv()
+    ...
+```
+
+## Pydantic Settings (Recommended)
+
+```python
+from pydantic_settings import BaseSettings
+from functools import lru_cache
+
+class Settings(BaseSettings):
+    # App
+    app_name: str = "My App"
+    debug: bool = False
+    secret_key: str
+
+    # Database
+    database_url: str
+
+    # Redis
+    redis_url: str = "redis://localhost:6379/0"
+
+    # JWT
+    jwt_secret_key: str | None = None
+    jwt_access_token_expires: int = 3600  # seconds
+
+    # Mail
+    mail_server: str = "localhost"
+    mail_port: int = 587
+    mail_username: str | None = None
+    mail_password: str | None = None
+
+    class Config:
+        env_file = ".env"
+        env_file_encoding = "utf-8"
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()
+
+settings = get_settings()
+
+# Usage in app
+def create_app() -> Flask:
+    app = Flask(__name__)
+
+    app.config["SECRET_KEY"] = settings.secret_key
+    app.config["SQLALCHEMY_DATABASE_URI"] = settings.database_url
+    app.config["DEBUG"] = settings.debug
+
+    return app
+```
+
+## Configuration Validation
+
+```python
+def validate_config(app: Flask):
+    """Validate required configuration."""
+    required = [
+        "SECRET_KEY",
+        "SQLALCHEMY_DATABASE_URI",
+    ]
+
+    missing = [key for key in required if not app.config.get(key)]
+
+    if missing:
+        raise RuntimeError(f"Missing required config: {', '.join(missing)}")
+
+    # Validate SECRET_KEY strength in production
+    if not app.debug:
+        if len(app.config["SECRET_KEY"]) < 32:
+            raise RuntimeError("SECRET_KEY must be at least 32 characters in production")
+
+def create_app(config_name: str = None) -> Flask:
+    app = Flask(__name__)
+    app.config.from_object(config[config_name])
+    validate_config(app)
+    return app
+```
+
+## Instance Configuration
+
+```python
+# instance/config.py (not in version control)
+SECRET_KEY = "your-production-secret"
+SQLALCHEMY_DATABASE_URI = "postgresql://prod-db/app"
+
+# Load instance config
+app = Flask(__name__, instance_relative_config=True)
+app.config.from_pyfile("config.py", silent=True)
+```
+
+## Configuration by Feature
+
+```python
+class Config:
+    # Core
+    SECRET_KEY = os.environ["SECRET_KEY"]
+
+    # Database
+    SQLALCHEMY_DATABASE_URI = os.environ["DATABASE_URL"]
+    SQLALCHEMY_TRACK_MODIFICATIONS = False
+    SQLALCHEMY_ENGINE_OPTIONS = {
+        "pool_size": 10,
+        "pool_recycle": 3600,
+        "pool_pre_ping": True,
+    }
+
+    # Cache
+    CACHE_TYPE = "redis"
+    CACHE_REDIS_URL = os.environ.get("REDIS_URL")
+    CACHE_DEFAULT_TIMEOUT = 300
+
+    # Session
+    SESSION_TYPE = "redis"
+    SESSION_REDIS = redis.from_url(os.environ.get("REDIS_URL"))
+    PERMANENT_SESSION_LIFETIME = timedelta(days=7)
+
+    # Security
+    SESSION_COOKIE_SECURE = True
+    SESSION_COOKIE_HTTPONLY = True
+    SESSION_COOKIE_SAMESITE = "Lax"
+
+    # CORS
+    CORS_ORIGINS = os.environ.get("CORS_ORIGINS", "").split(",")
+
+    # Uploads
+    MAX_CONTENT_LENGTH = 16 * 1024 * 1024  # 16MB
+    UPLOAD_FOLDER = os.environ.get("UPLOAD_FOLDER", "/tmp/uploads")
+
+    # Logging
+    LOG_LEVEL = os.environ.get("LOG_LEVEL", "INFO")
+    LOG_FORMAT = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+```
+
+## Runtime Configuration Access
+
+```python
+from flask import current_app
+
+@users_bp.route("/config-example")
+def config_example():
+    # Access config in routes
+    debug = current_app.config["DEBUG"]
+    app_name = current_app.config.get("APP_NAME", "Default")
+
+    return jsonify({
+        "debug": debug,
+        "app_name": app_name,
+    })
+
+# In services
+class EmailService:
+    def __init__(self):
+        self.server = current_app.config["MAIL_SERVER"]
+        self.port = current_app.config["MAIL_PORT"]
+```
+
+## Configuration for Extensions
+
+```python
+def configure_extensions(app: Flask):
+    """Configure Flask extensions."""
+    # SQLAlchemy
+    app.config.setdefault("SQLALCHEMY_TRACK_MODIFICATIONS", False)
+
+    # JWT
+    app.config.setdefault("JWT_TOKEN_LOCATION", ["headers"])
+    app.config.setdefault("JWT_HEADER_NAME", "Authorization")
+    app.config.setdefault("JWT_HEADER_TYPE", "Bearer")
+
+    # CORS
+    app.config.setdefault("CORS_SUPPORTS_CREDENTIALS", True)
+
+def create_app(config_name: str = None) -> Flask:
+    app = Flask(__name__)
+    app.config.from_object(config[config_name])
+    configure_extensions(app)
+    return app
+```