vega-framework 0.1.15__py3-none-any.whl → 0.1.17__py3-none-any.whl

vega/cli/__init__.py

@@ -1,5 +1,11 @@
 """Vega Framework CLI tools"""
 
-from vega.cli.main import cli
+# Lazy import to avoid circular dependencies when importing utilities
+def __getattr__(name: str):
+    if name == "cli":
+        from vega.cli.main import cli
+        return cli
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
 
 __all__ = ["cli"]

vega/cli/commands/generate.py

@@ -14,6 +14,8 @@ from vega.cli.templates import (
     render_fastapi_router,
     render_fastapi_middleware,
     render_sqlalchemy_model,
+    render_cli_command,
+    render_cli_command_simple,
 )
 from vega.cli.scaffolds import create_fastapi_scaffold
 
@@ -124,6 +126,8 @@ def generate_component(
         _generate_middleware(project_root, project_name, class_name, file_name)
     elif component_type == 'model':
         _generate_sqlalchemy_model(project_root, project_name, class_name, file_name)
+    elif component_type == 'command':
+        _generate_command(project_root, project_name, name, implementation)
 
 
 def _generate_entity(project_root: Path, project_name: str, class_name: str, file_name: str):
@@ -670,3 +674,137 @@ from infrastructure.models.{file_name} import {class_name}Model  # noqa: F401
         click.echo(click.style(f'''
 from infrastructure.models.{file_name} import {class_name}Model  # noqa: F401
 ''', fg='cyan'))
+
+
+def _generate_command(project_root: Path, project_name: str, name: str, is_async: str | None = None) -> None:
+    """Generate a CLI command"""
+    
+    # Check if presentation/cli exists
+    cli_path = project_root / "presentation" / "cli"
+    if not cli_path.exists():
+        cli_path.mkdir(parents=True, exist_ok=True)
+        click.echo(f"+ Created {click.style(str(cli_path.relative_to(project_root)), fg='green')}")
+    
+    # Create commands directory if it doesn't exist
+    commands_path = cli_path / "commands"
+    commands_path.mkdir(exist_ok=True)
+    
+    # Check if __init__.py exists
+    init_file = commands_path / "__init__.py"
+    if not init_file.exists():
+        init_file.write_text('"""CLI Commands"""\n')
+        click.echo(f"+ Created {click.style(str(init_file.relative_to(project_root)), fg='green')}")
+    
+    # Convert name to snake_case for command and file
+    command_name = to_snake_case(name).replace('_', '-')
+    file_name = to_snake_case(name)
+    
+    # Generate command file
+    command_file = commands_path / f"{file_name}.py"
+    
+    if command_file.exists():
+        click.echo(click.style(f"ERROR: Error: {command_file.relative_to(project_root)} already exists", fg='red'))
+        return
+    
+    # Determine if async (default is async unless explicitly set to 'sync' or 'simple')
+    use_async = is_async not in ['sync', 'simple', 'false', 'no'] if is_async else True
+    
+    # Prompt for command details
+    description = click.prompt("Command description", default=f"{name} command")
+    
+    # Ask if user wants to add options/arguments
+    add_params = click.confirm("Add options or arguments?", default=False)
+    
+    options = []
+    arguments = []
+    params_list = []
+    
+    if add_params:
+        click.echo("\nAdd options (e.g., --name, --email). Press Enter when done.")
+        while True:
+            opt_name = click.prompt("Option name (without --)", default="", show_default=False)
+            if not opt_name:
+                break
+            opt_type = click.prompt("Type", default="str", type=click.Choice(['str', 'int', 'bool']))
+            opt_required = click.confirm("Required?", default=False)
+            opt_help = click.prompt("Help text", default=f"{opt_name.replace('-', ' ').replace('_', ' ')}")
+            
+            params_list.append(opt_name.replace('-', '_'))
+            
+            opt_params = f"help='{opt_help}'"
+            if opt_required:
+                opt_params += ", required=True"
+            if opt_type != 'str':
+                if opt_type == 'bool':
+                    opt_params += ", is_flag=True"
+                else:
+                    opt_params += f", type={opt_type}"
+            
+            options.append({
+                "flag": f"--{opt_name}",
+                "params": opt_params
+            })
+        
+        click.echo("\nAdd arguments (positional). Press Enter when done.")
+        while True:
+            arg_name = click.prompt("Argument name", default="", show_default=False)
+            if not arg_name:
+                break
+            arg_required = click.confirm("Required?", default=True)
+            
+            params_list.append(arg_name)
+            
+            arg_params = "" if arg_required else ", required=False"
+            arguments.append({
+                "name": arg_name,
+                "params": arg_params
+            })
+    
+    params_signature = ", ".join(params_list) if params_list else ""
+    
+    # Ask about interactor usage
+    with_interactor = False
+    interactor_name = ""
+    if use_async:
+        with_interactor = click.confirm("Will this command use an interactor?", default=True)
+        if with_interactor:
+            interactor_name = click.prompt("Interactor name", default=f"{to_pascal_case(name)}")
+    
+    usage_example = f"python main.py {command_name}"
+    if params_list:
+        usage_example += " " + " ".join([f"--{p.replace('_', '-')}=value" if f"--{p.replace('_', '-')}" in str(options) else p for p in params_list])
+    
+    # Generate content
+    if use_async:
+        content = render_cli_command(
+            command_name=file_name,
+            description=description,
+            options=options,
+            arguments=arguments,
+            params_signature=params_signature,
+            params_list=params_list,
+            with_interactor=with_interactor,
+            usage_example=usage_example,
+            interactor_name=interactor_name,
+        )
+    else:
+        content = render_cli_command_simple(
+            command_name=file_name,
+            description=description,
+            options=options,
+            arguments=arguments,
+            params_signature=params_signature,
+            params_list=params_list,
+        )
+    
+    command_file.write_text(content)
+    click.echo(f"+ Created {click.style(str(command_file.relative_to(project_root)), fg='green')}")
+    
+    # Instructions for next steps
+    click.echo(f"\nNext steps:")
+    click.echo(f"   1. Implement your command logic in {command_file.relative_to(project_root)}")
+    click.echo(f"   2. Import and register in main.py:")
+    click.echo(click.style(f"      from presentation.cli.commands.{file_name} import {file_name}", fg='cyan'))
+    click.echo(click.style(f"      cli.add_command({file_name})", fg='cyan'))
+    if with_interactor:
+        click.echo(f"   3. Create interactor: vega generate interactor {interactor_name}")

vega/cli/commands/migrate.py

@@ -107,9 +107,9 @@ def history():
 @migrate.command()
 def init():
     """Initialize database with current schema (create tables)"""
-    import asyncio
     from pathlib import Path
     import sys
+    from vega.cli.utils import async_command
 
     # Add project root to path to allow imports
     project_root = Path.cwd()
@@ -123,13 +123,14 @@ def init():
         click.echo("Make sure you have SQLAlchemy configured in your project")
         sys.exit(1)
 
+    @async_command
     async def _init():
         click.echo("Creating database tables...")
         await db_manager.create_tables()
         click.secho("Database tables created successfully", fg='green')
 
     try:
-        asyncio.run(_init())
+        _init()
     except Exception as e:
         click.secho(f"Failed to initialize database: {e}", fg='red')
         sys.exit(1)

vega/cli/main.py

@@ -56,11 +56,11 @@ def init(project_name, template, path):
 
 @cli.command()
 @click.argument('component_type', type=click.Choice([
-    'entity', 'repository', 'repo', 'service', 'interactor', 'mediator', 'router', 'middleware', 'model'
+    'entity', 'repository', 'repo', 'service', 'interactor', 'mediator', 'router', 'middleware', 'model', 'command'
 ]))
 @click.argument('name')
 @click.option('--path', default='.', help='Project root path')
-@click.option('--impl', default=None, help='Generate infrastructure implementation for repository/service (e.g., memory, sql)')
+@click.option('--impl', default=None, help='Generate infrastructure implementation for repository/service (e.g., memory, sql) or command type (async, sync)')
 def generate(component_type, name, path, impl):
     """
     Generate a component in your Vega project.
@@ -75,6 +75,7 @@ def generate(component_type, name, path, impl):
         router      - FastAPI router (requires web module)
         middleware  - FastAPI middleware (requires web module)
         model       - SQLAlchemy model (requires sqlalchemy module)
+        command     - CLI command (async by default)
 
     Examples:
         vega generate entity Product
@@ -85,6 +86,8 @@ def generate(component_type, name, path, impl):
         vega generate router Product
         vega generate middleware Logging
         vega generate model User
+        vega generate command CreateUser
+        vega generate command ListUsers --impl sync
     """
     # Normalize 'repo' to 'repository'
     if component_type == 'repo':

vega/cli/templates/__init__.py

@@ -24,6 +24,8 @@ from .components import (
     render_alembic_env,
     render_alembic_script_mako,
     render_sqlalchemy_model,
+    render_cli_command,
+    render_cli_command_simple,
 )
 from .loader import render_template
 
@@ -53,5 +55,7 @@ __all__ = [
     "render_alembic_env",
     "render_alembic_script_mako",
     "render_sqlalchemy_model",
+    "render_cli_command",
+    "render_cli_command_simple",
     "render_template",
 ]

vega/cli/templates/cli/command.py.j2

@@ -0,0 +1,40 @@
+"""{{ description }}"""
+import click
+from vega.cli.utils import async_command
+import config  # noqa: F401 - Initialize DI container
+
+{% if with_interactor -%}
+# Import your interactors here
+# from domain.interactors.{{ interactor_name }} import {{ interactor_name }}
+{% endif %}
+
+@click.command()
+{%- for option in options %}
+@click.option('{{ option.flag }}', {{ option.params }})
+{%- endfor %}
+{%- for argument in arguments %}
+@click.argument('{{ argument.name }}'{{ argument.params }})
+{%- endfor %}
+@async_command
+async def {{ command_name }}({{ params_signature }}):
+    """
+    {{ description }}
+
+    {% if usage_example -%}
+    Usage:
+        {{ usage_example }}
+    {% endif -%}
+    """
+    {% if with_interactor -%}
+    # Example: Execute an interactor
+    # result = await MyInteractor(param=value)
+    # click.echo(f"Result: {result}")
+    {% endif -%}
+
+    # Your command implementation here
+    click.echo("{{ command_name }} executed!")
+    {% if params_signature -%}
+    {% for param in params_list -%}
+    click.echo(f"  {{ param }}: {{'{'}}{{ param }}{{'}'}}")
+    {% endfor -%}
+    {% endif %}

vega/cli/templates/cli/command_simple.py.j2

@@ -0,0 +1,19 @@
+"""{{ description }}"""
+import click
+
+
+@click.command()
+{%- for option in options %}
+@click.option('{{ option.flag }}', {{ option.params }})
+{%- endfor %}
+{%- for argument in arguments %}
+@click.argument('{{ argument.name }}'{{ argument.params }})
+{%- endfor %}
+def {{ command_name }}({{ params_signature }}):
+    """{{ description }}"""
+    click.echo("{{ command_name }} executed!")
+    {% if params_signature -%}
+    {% for param in params_list -%}
+    click.echo(f"  {{ param }}: {{'{'}}{{ param }}{{'}'}}")
+    {% endfor -%}
+    {% endif %}

vega/cli/templates/components.py

@@ -189,3 +189,51 @@ def render_sqlalchemy_model(class_name: str, table_name: str) -> str:
         class_name=class_name,
         table_name=table_name,
     )
+
+
+def render_cli_command(
+    command_name: str,
+    description: str,
+    options: list[dict],
+    arguments: list[dict],
+    params_signature: str,
+    params_list: list[str],
+    with_interactor: bool = True,
+    usage_example: str = "",
+    interactor_name: str = "",
+) -> str:
+    """Return the template for a CLI command"""
+    return render_template(
+        "command.py.j2",
+        subfolder="cli",
+        command_name=command_name,
+        description=description,
+        options=options,
+        arguments=arguments,
+        params_signature=params_signature,
+        params_list=params_list,
+        with_interactor=with_interactor,
+        usage_example=usage_example,
+        interactor_name=interactor_name,
+    )
+
+
+def render_cli_command_simple(
+    command_name: str,
+    description: str,
+    options: list[dict],
+    arguments: list[dict],
+    params_signature: str,
+    params_list: list[str],
+) -> str:
+    """Return the template for a simple CLI command (non-async)"""
+    return render_template(
+        "command_simple.py.j2",
+        subfolder="cli",
+        command_name=command_name,
+        description=description,
+        options=options,
+        arguments=arguments,
+        params_signature=params_signature,
+        params_list=params_list,
+    )

vega/cli/templates/project/ARCHITECTURE.md.j2

@@ -262,6 +262,232 @@ class StripePaymentService(PaymentService):
         pass
 ```
 
+## Development Workflow with Vega CLI
+
+Vega provides powerful CLI commands to quickly scaffold components following Clean Architecture principles. These commands help you maintain the correct architectural boundaries while accelerating development.
+
+### Generating Domain Layer Components
+
+**Entities** - Pure business objects:
+```bash
+vega generate entity User
+vega generate entity Product
+vega generate entity Order
+```
+
+**Repository Interfaces** - Data persistence abstractions:
+```bash
+vega generate repository UserRepository
+vega generate repository Product  # Auto-adds "Repository" suffix
+```
+
+**Repository with Implementation** - Create both interface and concrete implementation:
+```bash
+vega generate repository User --impl memory   # In-memory implementation
+vega generate repository User --impl sql      # SQL implementation
+vega generate repository User --impl postgres # PostgreSQL implementation
+```
+
+**Service Interfaces** - External service abstractions:
+```bash
+vega generate service EmailService
+vega generate service PaymentService
+```
+
+**Service with Implementation**:
+```bash
+vega generate service Email --impl sendgrid
+vega generate service Payment --impl stripe
+```
+
+**Interactors** - Single-purpose use cases:
+```bash
+vega generate interactor CreateUser
+vega generate interactor GetUserById
+vega generate interactor UpdateUserEmail
+vega generate interactor DeleteUser
+```
+
+### Generating Application Layer Components
+
+**Mediators** - Complex workflows:
+```bash
+vega generate mediator UserRegistrationFlow
+vega generate mediator CheckoutWorkflow
+vega generate mediator OrderProcessingPipeline
+```
+
+### Generating Infrastructure Layer Components
+
+**SQLAlchemy Models** - Database models (requires database support):
+```bash
+vega generate model User
+vega generate model Product
+vega generate model Order
+```
+
+Note: Models are automatically registered in Alembic for migrations.
+
+### Generating Presentation Layer Components
+
+**CLI Commands** - Command-line interfaces:
+```bash
+vega generate command CreateUser              # Async command (default)
+vega generate command ListUsers --impl sync   # Synchronous command
+```
+
+The generator will interactively prompt for:
+- Command description
+- Options and arguments (flags, parameters)
+- Whether to use interactors
+- Parameter types and validation
+
+**FastAPI Routers** - HTTP API endpoints (requires web support):
+```bash
+vega generate router User
+vega generate router Product
+vega generate router Order
+```
+
+**FastAPI Middleware** - Request/response processing (requires web support):
+```bash
+vega generate middleware Logging
+vega generate middleware Authentication
+vega generate middleware RateLimiting
+```
+
+### Adding Features to Existing Projects
+
+**Add FastAPI Web Support**:
+```bash
+vega add web
+```
+
+Creates complete FastAPI scaffold:
+- `presentation/web/` directory structure
+- Routes and middleware setup
+- Health check endpoints
+- App factory pattern
+
+**Add Database Support**:
+```bash
+vega add sqlalchemy  # or: vega add db
+```
+
+Adds complete database infrastructure:
+- SQLAlchemy async support
+- Alembic migrations
+- Database manager
+- Base model classes
+
+### Database Migrations Workflow
+
+After adding SQLAlchemy support, manage your database schema:
+
+```bash
+# Initialize database (creates tables)
+vega migrate init
+
+# Create migration after model changes
+vega migrate create -m "Add users table"
+vega migrate create -m "Add email_verified field to users"
+
+# Apply pending migrations
+vega migrate upgrade
+
+# Rollback last migration
+vega migrate downgrade
+
+# Check current migration status
+vega migrate current
+
+# View migration history
+vega migrate history
+```
+
+### Project Validation
+
+Validate your project structure and architecture compliance:
+
+```bash
+vega doctor
+vega doctor --path ./my-project
+```
+
+Checks for:
+- Correct folder structure
+- DI container configuration
+- Import dependencies
+- Architecture violations (e.g., domain depending on infrastructure)
+
+### Development Best Practices with CLI
+
+**1. Start with Domain Layer**:
+```bash
+# Define your entities first
+vega generate entity User
+
+# Create repository interfaces
+vega generate repository UserRepository
+
+# Implement use cases
+vega generate interactor CreateUser
+vega generate interactor GetUserById
+```
+
+**2. Add Infrastructure Implementations**:
+```bash
+# Generate repository implementation
+vega generate repository User --impl memory  # Start with in-memory
+
+# Later, add database support
+vega add sqlalchemy
+vega generate model User
+vega generate repository User --impl sql
+```
+
+**3. Build Application Workflows**:
+```bash
+# Orchestrate multiple use cases
+vega generate mediator UserRegistrationFlow
+```
+
+**4. Create Delivery Mechanisms**:
+```bash
+# CLI interface
+vega generate command create-user
+
+# Web API (add web first if not present)
+vega add web
+vega generate router User
+```
+
+**5. Validate Architecture**:
+```bash
+# Ensure clean architecture compliance
+vega doctor
+```
+
+### CLI Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `vega init <name>` | Create new Vega project |
+| `vega generate entity <Name>` | Generate domain entity |
+| `vega generate repository <Name>` | Generate repository interface |
+| `vega generate interactor <Name>` | Generate use case |
+| `vega generate mediator <Name>` | Generate workflow |
+| `vega generate command <Name>` | Generate CLI command |
+| `vega generate router <Name>` | Generate FastAPI router |
+| `vega generate model <Name>` | Generate SQLAlchemy model |
+| `vega add web` | Add FastAPI support |
+| `vega add sqlalchemy` | Add database support |
+| `vega migrate <command>` | Manage database migrations |
+| `vega doctor` | Validate project architecture |
+| `vega update` | Update Vega Framework |
+
+For complete documentation, see the [README](README.md#cli-commands).
+
 ## Dependency Injection
 
 Vega provides automatic dependency injection through decorators and a container.
@@ -507,7 +733,47 @@ class PriceCalculator:
     pass
 ```
 
-### 6. Testing
+### 6. Async CLI Commands
+
+Vega provides the `@async_command` decorator to use async/await in Click CLI commands, allowing you to execute interactors seamlessly:
+
+```python
+import click
+from vega.cli.utils import async_command
+
+@click.command()
+@click.option('--name', required=True)
+@click.option('--email', required=True)
+@async_command
+async def create_user(name: str, email: str):
+    """Create a new user via CLI"""
+    # Import config to initialize DI container
+    import config  # noqa: F401
+    from domain.interactors.create_user import CreateUser
+
+    # Execute async interactor
+    user = await CreateUser(name=name, email=email)
+    click.echo(f"Created user: {user.id} - {user.name}")
+```
+
+**Benefits:**
+- Execute async interactors directly in CLI commands
+- Same business logic works in both CLI and Web (FastAPI) contexts
+- Clean async/await syntax
+- Automatic asyncio event loop management
+
+**Alternative short syntax:**
+```python
+from vega.cli.utils import coro  # Alias for async_command
+
+@click.command()
+@coro
+async def my_command():
+    result = await MyInteractor()
+    click.echo(result)
+```
+
+### 7. Testing
 
 Vega's architecture makes testing straightforward: