feat(cli): implement CLI commands for MVC component generation and configuration

Author: marcuxyz

mvc_flask/cli.py

@@ -0,0 +1,124 @@
+"""Flask MVC CLI commands for generating MVC components.
+
+This module provides command-line tools for scaffolding MVC components
+following Flask and Python best practices.
+"""
+
+import logging
+import click
+from flask.cli import with_appcontext
+from typing import Optional
+
+from .core.generators import ControllerGenerator
+from .core.exceptions import ControllerGenerationError, InvalidControllerNameError
+from .core.config import CLIConfig
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+@click.group()
+def mvc():
+    """MVC Flask commands."""
+    pass
+
+
+@mvc.group()
+def generate():
+    """Generate MVC components."""
+    pass
+
+
+@generate.command()
+@click.argument('name')
+@click.option(
+    '--path', '-p',
+    default=CLIConfig.DEFAULT_CONTROLLERS_PATH,
+    help='Path where to create the controller'
+)
+@click.option(
+    '--force', '-f',
+    is_flag=True,
+    help='Overwrite existing controller file'
+)
+@with_appcontext
+def controller(name: str, path: str, force: bool) -> None:
+    """Generate a new controller.
+
+    Creates a new controller class with RESTful methods following Flask MVC patterns.
+    The controller will include standard CRUD operations and proper type hints.
+
+    Examples:
+        \b
+        flask mvc generate controller home
+        flask mvc generate controller user --path custom/controllers
+        flask mvc generate controller api_v1_user --force
+    """
+    try:
+        logger.info(f"Generating controller '{name}' at path '{path}'")
+
+        generator = ControllerGenerator()
+        controller_file = generator.generate(name, path, force=force)
+
+        click.echo(
+            click.style(
+                f"✓ Controller created successfully at {controller_file}",
+                fg=CLIConfig.SUCCESS_COLOR
+            )
+        )
+
+        # Provide helpful next steps
+        controller_name = name if name.endswith('_controller') else f"{name}_controller"
+        click.echo(
+            click.style(
+                "\nNext steps:",
+                fg=CLIConfig.INFO_COLOR,
+                bold=True
+            )
+        )
+        click.echo(
+            click.style(
+                "1. Add routes for your controller in your routes.py file",
+                fg=CLIConfig.INFO_COLOR
+            )
+        )
+        click.echo(
+            click.style(
+                f"2. Create templates in views/{name}/ directory",
+                fg=CLIConfig.INFO_COLOR
+            )
+        )
+        click.echo(
+            click.style(
+                f"3. Implement your business logic in {controller_name}.py",
+                fg=CLIConfig.INFO_COLOR
+            )
+        )
+
+    except (ControllerGenerationError, InvalidControllerNameError) as e:
+        logger.error(f"Controller generation failed: {e}")
+        click.echo(
+            click.style(f"✗ Error: {e}", fg=CLIConfig.ERROR_COLOR),
+            err=True
+        )
+        raise click.Abort() from e
+    except Exception as e:
+        logger.exception(f"Unexpected error during controller generation: {e}")
+        click.echo(
+            click.style(
+                f"✗ Unexpected error: {e}. Please check the logs for more details.",
+                fg=CLIConfig.ERROR_COLOR
+            ),
+            err=True
+        )
+        raise click.Abort() from e
+
+
+def init_app(app) -> None:
+    """Initialize CLI commands with Flask app.
+
+    Args:
+        app: Flask application instance
+    """
+    app.cli.add_command(mvc)

mvc_flask/core/__init__.py

@@ -0,0 +1 @@
+"""Core package for MVC Flask."""

mvc_flask/core/config.py

@@ -0,0 +1,68 @@
+"""Configuration for MVC Flask CLI."""
+
+import os
+from pathlib import Path
+from typing import Dict, Any, Optional
+
+
+class CLIConfig:
+    """Configuration settings for CLI commands."""
+
+    # Default paths
+    DEFAULT_CONTROLLERS_PATH = "app/controllers"
+    DEFAULT_VIEWS_PATH = "app/views"
+    DEFAULT_MODELS_PATH = "app/models"
+
+    # Template configuration
+    TEMPLATES_DIR = Path(__file__).parent.parent / 'templates'
+
+    # Controller template settings
+    CONTROLLER_TEMPLATE = 'base_controller.jinja2'
+
+    # File encoding
+    FILE_ENCODING = 'utf-8'
+
+    # CLI styling
+    SUCCESS_COLOR = 'green'
+    ERROR_COLOR = 'red'
+    WARNING_COLOR = 'yellow'
+    INFO_COLOR = 'blue'
+
+    # Environment variables for overriding defaults
+    ENV_PREFIX = 'FLASK_MVC_'
+
+    @classmethod
+    def get_controllers_path(cls) -> str:
+        """Get controllers path from environment or default.
+
+        Returns:
+            Controllers directory path
+        """
+        return os.getenv(
+            f'{cls.ENV_PREFIX}CONTROLLERS_PATH',
+            cls.DEFAULT_CONTROLLERS_PATH
+        )
+
+    @classmethod
+    def get_templates_dir(cls) -> Path:
+        """Get templates directory path.
+
+        Returns:
+            Templates directory path
+        """
+        custom_dir = os.getenv(f'{cls.ENV_PREFIX}TEMPLATES_DIR')
+        if custom_dir:
+            return Path(custom_dir)
+        return cls.TEMPLATES_DIR
+
+    @classmethod
+    def get_file_encoding(cls) -> str:
+        """Get file encoding from environment or default.
+
+        Returns:
+            File encoding string
+        """
+        return os.getenv(
+            f'{cls.ENV_PREFIX}FILE_ENCODING',
+            cls.FILE_ENCODING
+        )

mvc_flask/core/exceptions.py

@@ -0,0 +1,21 @@
+"""Custom exceptions for MVC Flask CLI."""
+
+
+class MVCFlaskError(Exception):
+    """Base exception for MVC Flask CLI errors."""
+    pass
+
+
+class ControllerGenerationError(MVCFlaskError):
+    """Exception raised when controller generation fails."""
+    pass
+
+
+class TemplateNotFoundError(MVCFlaskError):
+    """Exception raised when template file is not found."""
+    pass
+
+
+class InvalidControllerNameError(MVCFlaskError):
+    """Exception raised when controller name is invalid."""
+    pass

mvc_flask/core/file_handler.py

@@ -0,0 +1,55 @@
+"""File system utilities for MVC Flask CLI."""
+
+from pathlib import Path
+from typing import Optional
+
+from .exceptions import ControllerGenerationError
+
+
+class FileHandler:
+    """Handles file system operations for code generation."""
+
+    @staticmethod
+    def ensure_directory_exists(directory_path: Path) -> None:
+        """Create directory if it doesn't exist.
+
+        Args:
+            directory_path: Path to the directory to create
+        """
+        try:
+            directory_path.mkdir(parents=True, exist_ok=True)
+        except Exception as e:
+            raise ControllerGenerationError(
+                f"Failed to create directory {directory_path}: {e}"
+            ) from e
+
+    @staticmethod
+    def file_exists(file_path: Path) -> bool:
+        """Check if file exists.
+
+        Args:
+            file_path: Path to the file to check
+
+        Returns:
+            True if file exists, False otherwise
+        """
+        return file_path.exists()
+
+    @staticmethod
+    def write_file(file_path: Path, content: str) -> None:
+        """Write content to file.
+
+        Args:
+            file_path: Path to the file to write
+            content: Content to write to the file
+
+        Raises:
+            ControllerGenerationError: If file writing fails
+        """
+        try:
+            with open(file_path, 'w', encoding='utf-8') as f:
+                f.write(content)
+        except Exception as e:
+            raise ControllerGenerationError(
+                f"Failed to write file {file_path}: {e}"
+            ) from e

mvc_flask/core/generators.py

@@ -0,0 +1,83 @@
+"""Generators for MVC components."""
+
+from pathlib import Path
+from typing import Optional
+
+from .template_renderer import TemplateRenderer
+from .file_handler import FileHandler
+from .name_utils import NameUtils
+from .config import CLIConfig
+from .exceptions import ControllerGenerationError, InvalidControllerNameError
+
+
+class ControllerGenerator:
+    """Generates controller files using templates."""
+
+    def __init__(self, templates_dir: Optional[Path] = None):
+        """Initialize the controller generator.
+
+        Args:
+            templates_dir: Path to templates directory. If None, uses default location.
+        """
+        templates_dir = templates_dir or CLIConfig.get_templates_dir()
+
+        self.template_renderer = TemplateRenderer(templates_dir)
+        self.file_handler = FileHandler()
+        self.name_utils = NameUtils()
+        self.config = CLIConfig()
+
+    def generate(self, name: str, output_path: Optional[str] = None, force: bool = False) -> Path:
+        """Generate a new controller file.
+
+        Args:
+            name: Name of the controller
+            output_path: Directory where to create the controller
+            force: Whether to overwrite existing files
+
+        Returns:
+            Path to the created controller file
+
+        Raises:
+            ControllerGenerationError: If generation fails
+            InvalidControllerNameError: If controller name is invalid
+        """
+        try:
+            # Validate controller name
+            self.name_utils.validate_controller_name(name)
+
+            # Use default path if none provided
+            output_path = output_path or CLIConfig.get_controllers_path()
+
+            # Normalize names
+            controller_name = self.name_utils.normalize_controller_name(name)
+            class_name = self.name_utils.generate_class_name(controller_name)
+
+            # Prepare paths
+            output_dir = Path(output_path)
+            controller_file = output_dir / f"{controller_name}.py"
+
+            # Check if file already exists (unless force is True)
+            if not force and self.file_handler.file_exists(controller_file):
+                raise ControllerGenerationError(
+                    f"Controller '{controller_name}' already exists at {controller_file}. "
+                    f"Use --force to overwrite."
+                )
+
+            # Ensure output directory exists
+            self.file_handler.ensure_directory_exists(output_dir)
+
+            # Render template
+            content = self.template_renderer.render(
+                self.config.CONTROLLER_TEMPLATE,
+                {'class_name': class_name}
+            )
+
+            # Write file
+            self.file_handler.write_file(controller_file, content)
+
+            return controller_file
+
+        except Exception as e:
+            if isinstance(e, (ControllerGenerationError, InvalidControllerNameError)):
+                raise
+            raise ControllerGenerationError(f"Failed to generate controller: {e}") from e