mdb-engine 0.1.6__py3-none-any.whl → 0.2.0__py3-none-any.whl

mdb_engine/cli/commands/generate.py

@@ -1,22 +1,425 @@
 """
 Generate command for CLI.
 
-Generates a template manifest.json file.
+Generates manifests and full app scaffolding.
+
+Usage:
+    # Generate manifest only (existing behavior)
+    mdb generate manifest --slug my-app --name "My App"
+
+    # Generate full app structure (new)
+    mdb generate app --slug my-app --name "My App"
+    mdb generate app --slug my-app --multi-site  # Opt-in multi-site
+    mdb generate app --slug my-app --ray         # Opt-in Ray support
 
 This module is part of MDB_ENGINE - MongoDB Engine.
 """
 
-import sys
+import json
 from pathlib import Path
-from typing import Any, Dict
+from typing import Any, Dict, List, Optional
 
 import click
 
 from ...core.manifest import CURRENT_SCHEMA_VERSION
 from ..utils import save_manifest_file
 
+# --- App Templates ---
+
+SINGLE_APP_WEB_TEMPLATE = '''"""
+{app_name} Application
+
+Single-app mode - simple and straightforward.
+Generated by MDB Engine CLI.
+"""
+
+import os
+from pathlib import Path
+
+from mdb_engine import MongoDBEngine
+
+# Initialize engine
+engine = MongoDBEngine(
+    mongo_uri=os.getenv("MONGODB_URI", "mongodb://localhost:27017"),
+    db_name=os.getenv("MONGODB_DB", "mdb_runtime"),
+)
+
+# Create FastAPI app with automatic lifecycle management
+app = engine.create_app(
+    slug="{slug}",
+    manifest=Path(__file__).parent / "manifest.json",
+)
+
+
+@app.get("/")
+async def index():
+    """Root endpoint."""
+    return {{"app": "{slug}", "status": "ok"}}
+
+
+@app.get("/health")
+async def health():
+    """Health check endpoint."""
+    return {{"status": "healthy", "app": "{slug}"}}
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+'''
+
+MULTI_SITE_WEB_TEMPLATE = '''"""
+{app_name} Application
+
+Multi-site mode with optional Ray support.
+Generated by MDB Engine CLI.
+
+Multi-site mode is auto-detected from manifest when:
+- cross_app_policy is "explicit", or
+- read_scopes includes multiple apps
+"""
+
+import os
+from pathlib import Path
+
+from mdb_engine import MongoDBEngine
+
+# Initialize engine (with optional Ray support)
+engine = MongoDBEngine(
+    mongo_uri=os.getenv("MONGODB_URI", "mongodb://localhost:27017"),
+    db_name=os.getenv("MONGODB_DB", "mdb_runtime"),
+    enable_ray={enable_ray},
+)
+
+# Create FastAPI app with automatic lifecycle management
+# Multi-site mode is auto-detected from manifest
+app = engine.create_app(
+    slug="{slug}",
+    manifest=Path(__file__).parent / "manifest.json",
+)
+
+
+@app.get("/")
+async def index():
+    """Root endpoint."""
+    # Get scoped database (token auto-retrieved)
+    db = engine.get_scoped_db("{slug}")
+    return {{"app": "{slug}", "status": "ok"}}
+
+
+@app.get("/health")
+async def health():
+    """Health check endpoint."""
+    return {{
+        "status": "healthy",
+        "app": "{slug}",
+        "ray_enabled": engine.has_ray,
+    }}
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+'''
+
+RAY_ACTOR_TEMPLATE = '''"""
+Ray Actor for {app_name}.
+
+Provides isolated processing with Ray.
+Generated by MDB Engine CLI.
+"""
+
+import logging
+from typing import Any, Dict, Optional
+
+from mdb_engine.core.ray_integration import (
+    RAY_AVAILABLE,
+    AppRayActor,
+    ray_actor_decorator,
+)
+
+logger = logging.getLogger(__name__)
+
+if RAY_AVAILABLE:
+    @ray_actor_decorator(app_slug="{slug}", isolated=True)
+    class {actor_class_name}(AppRayActor):
+        """
+        Ray actor for {app_name}.
+
+        This actor runs in an isolated environment with its own
+        database connection and state.
+        """
+
+        async def process(self, data: Dict[str, Any]) -> Dict[str, Any]:
+            """
+            Process data in isolated Ray environment.
+
+            Args:
+                data: Input data to process
+
+            Returns:
+                Processed result
+            """
+            db = await self.get_app_db()
+
+            # Example: Store and retrieve
+            # await db.items.insert_one(data)
+            # result = await db.items.find_one({{"_id": data.get("id")}})
+
+            return {{"status": "processed", "app": self.app_slug}}
+
+        async def get_stats(self) -> Dict[str, Any]:
+            """Get processing statistics."""
+            db = await self.get_app_db()
+            # count = await db.items.count_documents({{}})
+            return {{"app": self.app_slug, "count": 0}}
+else:
+    # Fallback when Ray not available
+    class {actor_class_name}:
+        """Fallback actor class when Ray is not available."""
+
+        def __init__(self, *args, **kwargs):
+            logger.warning(
+                "Ray not available - {actor_class_name} running in fallback mode"
+            )
+
+        async def process(self, data: Dict[str, Any]) -> Dict[str, Any]:
+            return {{"status": "fallback", "error": "Ray not available"}}
+'''
+
+
+# --- Generator Class ---
+
+
+class AppGenerator:
+    """
+    Generate apps with Rails-like structure.
+
+    Supports:
+    - Single-app mode (default): Simple, direct MongoDBEngine usage
+    - Multi-site mode (opt-in): MongoDBEngine with token-based auth and cross-app access
+    - Ray support (opt-in): Isolated processing environments with Ray actors
+    """
+
+    @classmethod
+    def generate(
+        cls,
+        app_slug: str,
+        app_name: str,
+        description: str = "",
+        output_dir: Path = Path("."),
+        multi_site: bool = False,
+        enable_ray: bool = False,
+        read_scopes: Optional[List[str]] = None,
+    ) -> Path:
+        """
+        Generate a new app with proper structure.
+
+        Args:
+            app_slug: App identifier (e.g., "blog", "shop")
+            app_name: Human-readable app name
+            description: App description
+            output_dir: Directory to create app in
+            multi_site: Enable multi-site mode (default: False)
+            enable_ray: Enable Ray support (default: False)
+            read_scopes: Cross-app read scopes (default: [app_slug])
+
+        Returns:
+            Path to created app directory
+        """
+        app_path = output_dir / app_slug
+
+        if app_path.exists():
+            raise click.ClickException(f"App '{app_slug}' already exists at {app_path}")
+
+        # Create directory structure
+        app_path.mkdir(parents=True, exist_ok=True)
+        (app_path / "templates").mkdir(exist_ok=True)
+
+        if enable_ray:
+            (app_path / "actors").mkdir(exist_ok=True)
+
+        # Generate manifest.json
+        manifest = cls._generate_manifest(
+            app_slug=app_slug,
+            app_name=app_name,
+            description=description,
+            multi_site=multi_site,
+            enable_ray=enable_ray,
+            read_scopes=read_scopes or [app_slug],
+        )
+        manifest_path = app_path / "manifest.json"
+        with open(manifest_path, "w") as f:
+            json.dump(manifest, f, indent=2)
+
+        # Generate web.py
+        web_content = cls._generate_web_py(
+            app_slug=app_slug,
+            app_name=app_name,
+            multi_site=multi_site,
+            enable_ray=enable_ray,
+        )
+        (app_path / "web.py").write_text(web_content)
+
+        # Generate Ray actor if enabled
+        if enable_ray:
+            actor_content = cls._generate_ray_actor(
+                app_slug=app_slug,
+                app_name=app_name,
+            )
+            (app_path / "actors" / "__init__.py").write_text(actor_content)
+
+        # Generate basic index.html template
+        index_html = cls._generate_index_html(app_name)
+        (app_path / "templates" / "index.html").write_text(index_html)
+
+        return app_path
+
+    @classmethod
+    def _generate_manifest(
+        cls,
+        app_slug: str,
+        app_name: str,
+        description: str,
+        multi_site: bool,
+        enable_ray: bool,
+        read_scopes: List[str],
+    ) -> Dict[str, Any]:
+        """Generate manifest.json content."""
+        manifest: Dict[str, Any] = {
+            "schema_version": CURRENT_SCHEMA_VERSION,
+            "slug": app_slug,
+            "name": app_name,
+            "status": "active",
+        }
+
+        if description:
+            manifest["description"] = description
+
+        # Data access configuration
+        manifest["data_access"] = {
+            "read_scopes": read_scopes,
+            "write_scope": app_slug,
+            "cross_app_policy": "explicit" if multi_site else "none",
+        }
+
+        # Auth configuration (minimal by default)
+        manifest["auth"] = {
+            "policy": {
+                "provider": "casbin",
+                "required": False,
+                "allow_anonymous": True,
+            }
+        }
 
-@click.command()
+        # Managed indexes placeholder
+        manifest["managed_indexes"] = {}
+
+        return manifest
+
+    @classmethod
+    def _generate_web_py(
+        cls,
+        app_slug: str,
+        app_name: str,
+        multi_site: bool,
+        enable_ray: bool,
+    ) -> str:
+        """Generate web.py content."""
+        if multi_site:
+            return MULTI_SITE_WEB_TEMPLATE.format(
+                app_name=app_name,
+                slug=app_slug,
+                enable_ray=str(enable_ray),
+            )
+        else:
+            return SINGLE_APP_WEB_TEMPLATE.format(
+                app_name=app_name,
+                slug=app_slug,
+            )
+
+    @classmethod
+    def _generate_ray_actor(
+        cls,
+        app_slug: str,
+        app_name: str,
+    ) -> str:
+        """Generate Ray actor content."""
+        # Convert slug to class name: my_app -> MyAppActor
+        words = app_slug.replace("-", "_").split("_")
+        actor_class_name = "".join(word.capitalize() for word in words) + "Actor"
+
+        return RAY_ACTOR_TEMPLATE.format(
+            app_name=app_name,
+            slug=app_slug,
+            actor_class_name=actor_class_name,
+        )
+
+    @classmethod
+    def _generate_index_html(cls, app_name: str) -> str:
+        """Generate basic index.html template."""
+        return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{app_name}</title>
+    <style>
+        body {{
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+            max-width: 800px;
+            margin: 0 auto;
+            padding: 2rem;
+            background: #f5f5f5;
+        }}
+        .container {{
+            background: white;
+            padding: 2rem;
+            border-radius: 8px;
+            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+        }}
+        h1 {{
+            color: #333;
+            margin-top: 0;
+        }}
+        .status {{
+            display: inline-block;
+            padding: 0.25rem 0.75rem;
+            background: #e8f5e9;
+            color: #2e7d32;
+            border-radius: 4px;
+            font-size: 0.875rem;
+        }}
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>{app_name}</h1>
+        <p class="status">Active</p>
+        <p>Welcome to your new MDB Engine app!</p>
+    </div>
+</body>
+</html>
+"""
+
+
+# --- CLI Commands ---
+
+
+@click.group()
+def generate() -> None:
+    """
+    Generate manifests and app scaffolding.
+
+    Examples:
+        mdb generate manifest --slug my-app --name "My App"
+        mdb generate app --slug my-app --name "My App"
+        mdb generate app --slug my-app --multi-site --ray
+    """
+    pass
+
+
+@generate.command("manifest")
 @click.option(
     "--slug",
     "-s",
@@ -48,7 +451,7 @@ from ..utils import save_manifest_file
     is_flag=True,
     help="Generate minimal template (basic fields only)",
 )
-def generate(
+def generate_manifest(
     slug: str,
     name: str,
     description: str,
@@ -58,10 +461,12 @@ def generate(
     """
     Generate a template manifest.json file.
 
+    This is the original generate command behavior.
+
     Examples:
-        mdb generate --slug my-app --name "My App"
-        mdb generate --slug my-app --name "My App" --output custom.json
-        mdb generate --slug my-app --name "My App" --minimal
+        mdb generate manifest --slug my-app --name "My App"
+        mdb generate manifest --slug my-app --name "My App" --output custom.json
+        mdb generate manifest --slug my-app --name "My App" --minimal
     """
     try:
         # Validate slug format
@@ -100,6 +505,137 @@ def generate(
         # Save manifest
         save_manifest_file(output, manifest)
         click.echo(click.style(f"✅ Generated manifest template: {output}", fg="green"))
-        sys.exit(0)
+
+    except click.ClickException:
+        raise
+
+
+@generate.command("app")
+@click.option(
+    "--slug",
+    "-s",
+    prompt="App slug",
+    help="App slug (lowercase alphanumeric, underscores, hyphens)",
+)
+@click.option(
+    "--name",
+    "-n",
+    prompt="App name",
+    help="Human-readable app name",
+)
+@click.option(
+    "--description",
+    "-d",
+    default="",
+    help="App description",
+)
+@click.option(
+    "--output",
+    "-o",
+    default=".",
+    type=click.Path(path_type=Path),
+    help="Output directory (default: current directory)",
+)
+@click.option(
+    "--multi-site",
+    is_flag=True,
+    help="Enable multi-site mode (token-based auth and cross-app access)",
+)
+@click.option(
+    "--ray",
+    is_flag=True,
+    help="Enable Ray support for distributed processing",
+)
+@click.option(
+    "--read-scopes",
+    "-r",
+    multiple=True,
+    help="Cross-app read scopes (can specify multiple)",
+)
+def generate_app(
+    slug: str,
+    name: str,
+    description: str,
+    output: Path,
+    multi_site: bool,
+    ray: bool,
+    read_scopes: tuple,
+) -> None:
+    """
+    Generate a full app with proper structure.
+
+    Creates a complete app directory with:
+    - manifest.json
+    - web.py (FastAPI application)
+    - templates/ directory
+    - actors/ directory (if --ray enabled)
+
+    Examples:
+        # Single-app mode (default)
+        mdb generate app --slug my-app --name "My App"
+
+        # Multi-site mode
+        mdb generate app --slug my-app --name "My App" --multi-site
+
+        # With Ray support
+        mdb generate app --slug my-app --name "My App" --ray
+
+        # Full featured
+        mdb generate app --slug my-app --name "My App" --multi-site --ray
+
+        # With cross-app read access
+        mdb generate app --slug dashboard --name "Dashboard" --multi-site \\
+            --read-scopes dashboard --read-scopes click_tracker
+    """
+    try:
+        # Validate slug format
+        if not slug or not all(c.isalnum() or c in ("_", "-") for c in slug):
+            raise click.ClickException(
+                "Invalid slug format. Use lowercase alphanumeric, underscores, or hyphens."
+            )
+
+        # Convert read_scopes tuple to list
+        scopes_list = list(read_scopes) if read_scopes else None
+
+        # Generate app
+        app_path = AppGenerator.generate(
+            app_slug=slug,
+            app_name=name,
+            description=description,
+            output_dir=output,
+            multi_site=multi_site,
+            enable_ray=ray,
+            read_scopes=scopes_list,
+        )
+
+        # Print success message
+        click.echo(click.style(f"✅ Generated app '{name}' at: {app_path}", fg="green"))
+        click.echo("")
+        click.echo("Created files:")
+        click.echo(f"  - {app_path}/manifest.json")
+        click.echo(f"  - {app_path}/web.py")
+        click.echo(f"  - {app_path}/templates/index.html")
+
+        if ray:
+            click.echo(f"  - {app_path}/actors/__init__.py")
+
+        click.echo("")
+        click.echo("Next steps:")
+        click.echo(f"  cd {app_path}")
+        click.echo("  uvicorn web:app --reload")
+
+        if multi_site:
+            click.echo("")
+            click.echo(click.style("Multi-site mode enabled:", fg="yellow"))
+            click.echo(f"  Set {slug.upper()}_SECRET environment variable for app token")
+
+        if ray:
+            click.echo("")
+            click.echo(click.style("Ray support enabled:", fg="yellow"))
+            click.echo("  Ensure Ray is running: ray start --head")
+            click.echo("  Set RAY_ADDRESS environment variable")
+
     except click.ClickException:
         raise
+    except (OSError, ValueError, KeyError, RuntimeError) as e:
+        raise click.ClickException(f"Error generating app: {e}") from e

mdb_engine/cli/commands/validate.py

@@ -42,14 +42,10 @@ def validate(manifest_file: Path, verbose: bool) -> None:
         is_valid, error_message, error_paths = validator.validate(manifest)
 
         if is_valid:
-            click.echo(
-                click.style(f"✅ Manifest '{manifest_file}' is valid!", fg="green")
-            )
+            click.echo(click.style(f"✅ Manifest '{manifest_file}' is valid!", fg="green"))
             sys.exit(0)
         else:
-            click.echo(
-                click.style(f"❌ Manifest '{manifest_file}' is invalid!", fg="red")
-            )
+            click.echo(click.style(f"❌ Manifest '{manifest_file}' is invalid!", fg="red"))
             if error_message:
                 click.echo(click.style(f"Error: {error_message}", fg="red"))
             if error_paths and verbose:
@@ -60,4 +56,4 @@ def validate(manifest_file: Path, verbose: bool) -> None:
     except click.ClickException:
         raise
     except (FileNotFoundError, ValueError, KeyError) as e:
-        raise click.ClickException(str(e))
+        raise click.ClickException(str(e)) from e

mdb_engine/cli/utils.py

@@ -30,10 +30,10 @@ def load_manifest_file(file_path: Path) -> Dict[str, Any]:
         raise click.ClickException(f"Manifest file not found: {file_path}")
 
     try:
-        with open(file_path, "r", encoding="utf-8") as f:
+        with open(file_path, encoding="utf-8") as f:
             return json.load(f)
     except json.JSONDecodeError as e:
-        raise click.ClickException(f"Invalid JSON in manifest file: {e}")
+        raise click.ClickException(f"Invalid JSON in manifest file: {e}") from e
 
 
 def save_manifest_file(file_path: Path, manifest: Dict[str, Any]) -> None:
@@ -51,7 +51,7 @@ def save_manifest_file(file_path: Path, manifest: Dict[str, Any]) -> None:
         with open(file_path, "w", encoding="utf-8") as f:
             json.dump(manifest, f, indent=2, ensure_ascii=False)
     except OSError as e:
-        raise click.ClickException(f"Failed to write manifest file: {e}")
+        raise click.ClickException(f"Failed to write manifest file: {e}") from e
 
 
 def format_manifest_output(manifest: Dict[str, Any], format_type: str) -> str:

mdb_engine/config.py

@@ -66,18 +66,12 @@ class EngineConfig:
         """
         self.mongo_uri = mongo_uri or os.getenv("MONGO_URI", "")
         self.db_name = db_name or os.getenv("DB_NAME", "")
-        self.max_pool_size = max_pool_size or int(
-            os.getenv("MONGO_MAX_POOL_SIZE", "50")
-        )
-        self.min_pool_size = min_pool_size or int(
-            os.getenv("MONGO_MIN_POOL_SIZE", "10")
-        )
+        self.max_pool_size = max_pool_size or int(os.getenv("MONGO_MAX_POOL_SIZE", "50"))
+        self.min_pool_size = min_pool_size or int(os.getenv("MONGO_MIN_POOL_SIZE", "10"))
         self.server_selection_timeout_ms = server_selection_timeout_ms or int(
             os.getenv("MONGO_SERVER_SELECTION_TIMEOUT_MS", "5000")
         )
-        self.authz_cache_ttl = authz_cache_ttl or int(
-            os.getenv("AUTHZ_CACHE_TTL", "300")
-        )
+        self.authz_cache_ttl = authz_cache_ttl or int(os.getenv("AUTHZ_CACHE_TTL", "300"))
 
     def validate(self) -> None:
         """
@@ -115,9 +109,7 @@ class EngineConfig:
             )
 
         if self.authz_cache_ttl < 0:
-            raise ValueError(
-                f"authz_cache_ttl must be >= 0, got {self.authz_cache_ttl}"
-            )
+            raise ValueError(f"authz_cache_ttl must be >= 0, got {self.authz_cache_ttl}")
 
 
 # Pydantic-based configuration (optional, only if Pydantic is available)
@@ -138,9 +130,7 @@ if PYDANTIC_AVAILABLE:
             )
         """
 
-        mongo_uri: str = Field(
-            ..., env="MONGO_URI", description="MongoDB connection URI"
-        )
+        mongo_uri: str = Field(..., env="MONGO_URI", description="MongoDB connection URI")
         db_name: str = Field(..., env="DB_NAME", description="Database name")
         max_pool_size: int = Field(
             50,
@@ -203,15 +193,11 @@ ACCESS_TOKEN_TTL: int = int(os.getenv("ACCESS_TOKEN_TTL", "900"))  # 15 minutes
 REFRESH_TOKEN_TTL: int = int(os.getenv("REFRESH_TOKEN_TTL", "604800"))  # 7 days
 """Refresh token TTL in seconds (default: 604800 / 7 days)."""
 
-TOKEN_ROTATION_ENABLED: bool = (
-    os.getenv("TOKEN_ROTATION_ENABLED", "true").lower() == "true"
-)
+TOKEN_ROTATION_ENABLED: bool = os.getenv("TOKEN_ROTATION_ENABLED", "true").lower() == "true"
 """Whether to rotate refresh tokens on each use (default: true)."""
 
 MAX_SESSIONS_PER_USER: int = int(os.getenv("MAX_SESSIONS_PER_USER", "10"))
 """Maximum number of concurrent sessions per user (default: 10)."""
 
-SESSION_INACTIVITY_TIMEOUT: int = int(
-    os.getenv("SESSION_INACTIVITY_TIMEOUT", "1800")
-)  # 30 minutes
+SESSION_INACTIVITY_TIMEOUT: int = int(os.getenv("SESSION_INACTIVITY_TIMEOUT", "1800"))  # 30 minutes
 """Session inactivity timeout in seconds (default: 1800 / 30 minutes)."""