vega-framework 0.1.35__tar.gz → 0.2.1__tar.gz

{vega_framework-0.1.35 → vega_framework-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vega-framework
-Version: 0.1.35
+Version: 0.2.1
 Summary: Enterprise-ready Python framework that enforces Clean Architecture for building maintainable and scalable applications.
 License: MIT
 License-File: LICENSE
@@ -19,10 +19,10 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Dist: click (>=8.0,<9.0)
-Requires-Dist: fastapi (>=0.109,<0.110)
 Requires-Dist: jinja2 (>=3.1,<4.0)
 Requires-Dist: pydantic (>=2.0,<3.0)
 Requires-Dist: pydantic-settings (>=2.0,<3.0)
+Requires-Dist: starlette (>=0.37,<0.38)
 Requires-Dist: toml (>=0.10,<0.11)
 Requires-Dist: uvicorn (>=0.27,<0.28)
 Project-URL: Documentation, https://vega-framework.readthedocs.io
@@ -43,7 +43,7 @@ Traditional Python frameworks show you **how to build** but don't enforce **how
 - ✅ **Business Logic First** - Pure, testable, framework-independent
 - ✅ **CLI Scaffolding** - Generate entire projects and components
 - ✅ **Async Support** - Full async/await for CLI and web
-- ✅ **FastAPI & SQLAlchemy** - Built-in integrations when needed
+- ✅ **Vega Web (Starlette) & SQLAlchemy** - Built-in integrations when needed
 
 **[Read the Philosophy →](docs/explanation/philosophy.md)** to understand why architecture matters.
 
@@ -152,7 +152,7 @@ container = Container({
 
 ```bash
 vega init my-app                      # Create new project
-vega init my-api --template fastapi   # Create with FastAPI
+vega init my-api --template web       # Create with Vega Web
 vega doctor                           # Validate architecture
 vega update                           # Update framework
 ```
@@ -169,7 +169,7 @@ vega generate interactor CreateProduct
 vega generate mediator CheckoutWorkflow
 
 # Presentation layer
-vega generate router Product          # FastAPI (requires: vega add web)
+vega generate router Product          # Vega Web (requires: vega add web)
 vega generate command create-product  # CLI
 
 # Infrastructure
@@ -179,7 +179,7 @@ vega generate model Product           # SQLAlchemy (requires: vega add db)
 ### Add Features
 
 ```bash
-vega add web         # Add FastAPI web support
+vega add web         # Add Vega Web support
 vega add sqlalchemy  # Add database support
 ```
 
@@ -232,6 +232,7 @@ await UserCreated(user_id="123", email="test@test.com").publish()
 - [Patterns](docs/explanation/patterns/interactor.md) - Interactor, Mediator, Repository, Service
 
 ### Guides
+- [Use Vega Web](docs/how-to/use-vega-web.md) - Build HTTP APIs with Vega's router and middleware
 - [Building Domain Layer](docs/how-to/build-domain-layer.md) - Business logic first
 - [CLI Reference](docs/reference/cli/overview.md) - All CLI commands
 - [Events System](docs/explanation/events/overview.md) - Event-driven architecture
@@ -268,7 +269,7 @@ my-app/
 │   └── services/             # API integrations
 ├── presentation/             # User interfaces
 │   ├── cli/                  # CLI commands
-│   └── web/                  # FastAPI routes
+│   └── web/                  # Vega Web routes
 ├── config.py                 # Dependency injection
 ├── settings.py               # Configuration
 └── main.py                   # Entry point
@@ -289,7 +290,7 @@ async def create_order(request: Request):
 ```
 
 **Problems:**
-- Can't test without FastAPI, database, and Stripe
+- Can't test without the web framework, database, and Stripe
 - Can't reuse for CLI or other interfaces
 - Business rules are unclear
 - Tightly coupled to specific technologies
@@ -309,7 +310,7 @@ class PlaceOrder(Interactor[Order]):
         await payment_service.charge(...)
         return await order_repo.save(order)
 
-# ✅ FastAPI route (Presentation) - just wiring
+# ✅ Vega Web route (Presentation) - just wiring
 @router.post("/orders")
 async def create_order_api(request: CreateOrderRequest):
     return await PlaceOrder(...)

{vega_framework-0.1.35 → vega_framework-0.2.1}/README.md

@@ -11,7 +11,7 @@ Traditional Python frameworks show you **how to build** but don't enforce **how
 - ✅ **Business Logic First** - Pure, testable, framework-independent
 - ✅ **CLI Scaffolding** - Generate entire projects and components
 - ✅ **Async Support** - Full async/await for CLI and web
-- ✅ **FastAPI & SQLAlchemy** - Built-in integrations when needed
+- ✅ **Vega Web (Starlette) & SQLAlchemy** - Built-in integrations when needed
 
 **[Read the Philosophy →](docs/explanation/philosophy.md)** to understand why architecture matters.
 
@@ -120,7 +120,7 @@ container = Container({
 
 ```bash
 vega init my-app                      # Create new project
-vega init my-api --template fastapi   # Create with FastAPI
+vega init my-api --template web       # Create with Vega Web
 vega doctor                           # Validate architecture
 vega update                           # Update framework
 ```
@@ -137,7 +137,7 @@ vega generate interactor CreateProduct
 vega generate mediator CheckoutWorkflow
 
 # Presentation layer
-vega generate router Product          # FastAPI (requires: vega add web)
+vega generate router Product          # Vega Web (requires: vega add web)
 vega generate command create-product  # CLI
 
 # Infrastructure
@@ -147,7 +147,7 @@ vega generate model Product           # SQLAlchemy (requires: vega add db)
 ### Add Features
 
 ```bash
-vega add web         # Add FastAPI web support
+vega add web         # Add Vega Web support
 vega add sqlalchemy  # Add database support
 ```
 
@@ -200,6 +200,7 @@ await UserCreated(user_id="123", email="test@test.com").publish()
 - [Patterns](docs/explanation/patterns/interactor.md) - Interactor, Mediator, Repository, Service
 
 ### Guides
+- [Use Vega Web](docs/how-to/use-vega-web.md) - Build HTTP APIs with Vega's router and middleware
 - [Building Domain Layer](docs/how-to/build-domain-layer.md) - Business logic first
 - [CLI Reference](docs/reference/cli/overview.md) - All CLI commands
 - [Events System](docs/explanation/events/overview.md) - Event-driven architecture
@@ -236,7 +237,7 @@ my-app/
 │   └── services/             # API integrations
 ├── presentation/             # User interfaces
 │   ├── cli/                  # CLI commands
-│   └── web/                  # FastAPI routes
+│   └── web/                  # Vega Web routes
 ├── config.py                 # Dependency injection
 ├── settings.py               # Configuration
 └── main.py                   # Entry point
@@ -257,7 +258,7 @@ async def create_order(request: Request):
 ```
 
 **Problems:**
-- Can't test without FastAPI, database, and Stripe
+- Can't test without the web framework, database, and Stripe
 - Can't reuse for CLI or other interfaces
 - Business rules are unclear
 - Tightly coupled to specific technologies
@@ -277,7 +278,7 @@ class PlaceOrder(Interactor[Order]):
         await payment_service.charge(...)
         return await order_repo.save(order)
 
-# ✅ FastAPI route (Presentation) - just wiring
+# ✅ Vega Web route (Presentation) - just wiring
 @router.post("/orders")
 async def create_order_api(request: CreateOrderRequest):
     return await PlaceOrder(...)

{vega_framework-0.1.35 → vega_framework-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "vega-framework"
-version = "0.1.35"
+version = "0.2.1"
 description = "Enterprise-ready Python framework that enforces Clean Architecture for building maintainable and scalable applications."
 authors = ["Roberto Ferro"]
 license = "MIT"
@@ -43,7 +43,7 @@ click = "^8.0"
 jinja2 = "^3.1"
 toml = "^0.10"
 uvicorn = "^0.27"
-fastapi = "^0.109"
+starlette = "^0.37"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^7.0"
@@ -53,6 +53,7 @@ black = "^23.0"
 isort = "^5.0"
 mypy = "^1.0"
 ruff = "^0.1"
+httpx = "^0.28.1"
 
 [tool.poetry.scripts]
 vega = "vega.cli.main:cli"
@@ -81,6 +82,31 @@ testpaths = ["tests"]
 python_files = ["test_*.py"]
 python_classes = ["Test*"]
 python_functions = ["test_*"]
+# Test markers
+markers = [
+    "unit: Unit tests for individual components",
+    "functional: Functional tests for features and workflows",
+    "integration: Integration tests for component interactions",
+    "slow: Tests that take significant time to run",
+    "web: Web framework related tests",
+    "di: Dependency injection related tests",
+    "events: Event system related tests",
+]
+# Coverage settings
+addopts = [
+    "--strict-markers",
+    "--tb=short",
+    "--cov=vega",
+    "--cov-report=term-missing",
+    "--cov-report=html:htmlcov",
+    "--cov-report=xml",
+]
+# Filter warnings
+filterwarnings = [
+    "error",
+    "ignore::UserWarning",
+    "ignore::DeprecationWarning",
+]
 
 [tool.ruff]
 line-length = 100

{vega_framework-0.1.35 → vega_framework-0.2.1}/vega/cli/commands/add.py

@@ -3,7 +3,7 @@ from pathlib import Path
 
 import click
 
-from vega.cli.scaffolds import create_fastapi_scaffold, create_sqlalchemy_scaffold
+from vega.cli.scaffolds import create_vega_web_scaffold, create_sqlalchemy_scaffold
 
 
 @click.command()
@@ -13,7 +13,7 @@ def add(feature: str, path: str):
     """Add features to an existing Vega project
 
     Features:
-        web        - Add FastAPI web scaffold to the project
+        web        - Add Vega Web scaffold to the project
         sqlalchemy - Add SQLAlchemy database support (alias: db)
         db         - Alias for sqlalchemy
 
@@ -40,13 +40,13 @@ def add(feature: str, path: str):
 
 
 def add_web_feature(project_path: Path, project_name: str):
-    """Add FastAPI web scaffold to existing project"""
-    click.echo(f"\n[*] Adding FastAPI web scaffold to: {click.style(project_name, fg='green', bold=True)}\n")
+    """Add Vega Web scaffold to existing project"""
+    click.echo(f"\n[*] Adding Vega Web scaffold to: {click.style(project_name, fg='green', bold=True)}\n")
 
     # Check if presentation/web already exists
     web_dir = project_path / "presentation" / "web"
     if web_dir.exists() and (web_dir / "main.py").exists():
-        click.echo(click.style("WARNING: FastAPI scaffold already exists!", fg='yellow'))
+        click.echo(click.style("WARNING: Web scaffold already exists!", fg='yellow'))
         if not click.confirm("Do you want to overwrite existing files?"):
             click.echo("Aborted.")
             return
@@ -60,13 +60,12 @@ def add_web_feature(project_path: Path, project_name: str):
         presentation_dir.mkdir(parents=True, exist_ok=True)
         click.echo(f"  + Created presentation/")
 
-    # Create FastAPI scaffold
-    create_fastapi_scaffold(project_path, project_name, overwrite=overwrite)
+    # Create Vega Web scaffold
+    create_vega_web_scaffold(project_path, project_name, overwrite=overwrite)
 
-    click.echo(f"\n{click.style('SUCCESS: FastAPI web scaffold added!', fg='green', bold=True)}\n")
+    click.echo(f"\n{click.style('SUCCESS: Vega Web scaffold added!', fg='green', bold=True)}\n")
     click.echo("Next steps:")
-    click.echo("  1. Add FastAPI dependencies:")
-    click.echo("     poetry add fastapi uvicorn[standard]")
+    click.echo("  1. Dependencies are already included in vega-framework")
     click.echo("  2. Run the server:")
     click.echo("     vega web run --reload")
     click.echo("  3. Visit http://localhost:8000/api/health/status")

{vega_framework-0.1.35 → vega_framework-0.2.1}/vega/cli/commands/generate.py

@@ -394,13 +394,13 @@ def _register_router_in_init(project_root: Path, resource_file: str, resource_na
 
 
 def _generate_router(project_root: Path, project_name: str, name: str) -> None:
-    """Generate a FastAPI router for a resource"""
+    """Generate a Vega Web router for a resource"""
 
     # Check if web folder exists
     web_path = project_root / "presentation" / "web"
     if not web_path.exists():
         click.echo(click.style("ERROR: Web module not found", fg='red'))
-        click.echo("   Router generation requires FastAPI web module")
+        click.echo("   Router generation requires Vega Web module")
         click.echo("   Install it with: vega add web")
         return
 
@@ -440,13 +440,13 @@ def _generate_router(project_root: Path, project_name: str, name: str) -> None:
 
 
 def _generate_web_models(project_root: Path, project_name: str, name: str, is_request: bool, is_response: bool) -> None:
-    """Generate Pydantic request or response model for FastAPI"""
+    """Generate Pydantic request or response model for Vega Web"""
 
     # Check if web folder exists
     web_path = project_root / "presentation" / "web"
     if not web_path.exists():
         click.echo(click.style("ERROR: Web module not found", fg='red'))
-        click.echo("   Model generation requires FastAPI web module")
+        click.echo("   Model generation requires Vega Web module")
         click.echo("   Install it with: vega add web")
         return
 
@@ -531,13 +531,13 @@ def _generate_web_models(project_root: Path, project_name: str, name: str, is_re
 
 
 def _generate_middleware(project_root: Path, project_name: str, class_name: str, file_name: str) -> None:
-    """Generate a FastAPI middleware"""
+    """Generate a Vega Web middleware"""
 
     # Check if web folder exists
     web_path = project_root / "presentation" / "web"
     if not web_path.exists():
         click.echo(click.style("ERROR: Web module not found", fg='red'))
-        click.echo("   Middleware generation requires FastAPI web module")
+        click.echo("   Middleware generation requires Vega Web module")
         click.echo("   Install it with: vega add web")
         return
 
@@ -554,7 +554,7 @@ def _generate_middleware(project_root: Path, project_name: str, class_name: str,
     # Check if __init__.py exists
     init_file = middleware_path / "__init__.py"
     if not init_file.exists():
-        init_file.write_text('"""FastAPI Middlewares"""\n')
+        init_file.write_text('"""Vega Web Middlewares"""\n')
         click.echo(f"+ Created {click.style(str(init_file.relative_to(project_root)), fg='green')}")
 
     # Generate middleware file
@@ -589,8 +589,8 @@ def _register_middleware_in_app(project_root: Path, class_name: str, file_name:
         click.echo(click.style(f'''
 from .middleware.{file_name} import {class_name}Middleware
 
-def create_app() -> FastAPI:
-    app = FastAPI(...)
+def create_app() -> VegaApp:
+    app = VegaApp(...)
     app.add_middleware({class_name}Middleware)
     app.include_router(get_api_router())
     return app
@@ -619,9 +619,9 @@ def create_app() -> FastAPI:
             break
 
     if not import_added:
-        # Fallback: add after FastAPI import
+        # Fallback: add after VegaApp import
         for i, line in enumerate(lines):
-            if 'from fastapi import' in line:
+            if 'from vega.web import' in line:
                 lines.insert(i + 1, middleware_import)
                 lines.insert(i + 2, '')
                 break
@@ -629,8 +629,8 @@ def create_app() -> FastAPI:
     # Find create_app function and add middleware registration
     middleware_added = False
     for i, line in enumerate(lines):
-        if 'app = FastAPI(' in line:
-            # Find the end of FastAPI initialization
+        if 'app = VegaApp(' in line:
+            # Find the end of VegaApp initialization
             j = i + 1
             while j < len(lines) and not lines[j].strip().startswith('app.include_router'):
                 j += 1
@@ -649,8 +649,8 @@ def create_app() -> FastAPI:
         click.echo(click.style(f'''
 from .middleware.{file_name} import {class_name}Middleware
 
-def create_app() -> FastAPI:
-    app = FastAPI(...)
+def create_app() -> VegaApp:
+    app = VegaApp(...)
     app.add_middleware({class_name}Middleware)
     app.include_router(get_api_router())
     return app

{vega_framework-0.1.35 → vega_framework-0.2.1}/vega/cli/commands/init.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 import click
 
-from vega.cli.scaffolds import create_fastapi_scaffold
+from vega.cli.scaffolds import create_vega_web_scaffold
 from vega.cli.templates.loader import render_template
 import vega
 
@@ -104,14 +104,15 @@ def init_project(project_name: str, template: str, parent_path: str):
     click.echo(f"  + Created ARCHITECTURE.md")
 
     # Create main.py based on template
-    if template == "fastapi":
-        click.echo("\n[*] Adding FastAPI scaffold (presentation/web/)")
-        create_fastapi_scaffold(project_path, project_name)
+    # Support both "web" and "fastapi" (backward compat)
+    if template in ["web", "fastapi"]:
+        click.echo("\n[*] Adding Vega Web scaffold (presentation/web/)")
+        create_vega_web_scaffold(project_path, project_name)
 
-        # Create main.py for FastAPI project
+        # Create main.py for web project
         main_content = render_template("main.py.j2", project_name=project_name, template="fastapi")
         (project_path / "main.py").write_text(main_content)
-        click.echo(f"  + Created main.py (FastAPI entrypoint)")
+        click.echo(f"  + Created main.py (Vega Web entrypoint)")
     else:
         # Create standard main.py
         main_content = render_template("main.py.j2", project_name=project_name, template="standard")
@@ -126,9 +127,9 @@ def init_project(project_name: str, template: str, parent_path: str):
     click.echo(f"  poetry install")
     click.echo(f"  cp .env.example .env")
 
-    if template == "fastapi":
+    if template in ["web", "fastapi"]:
         click.echo(f"\nRun commands:")
-        click.echo(f"  vega web run                # Start FastAPI server (http://localhost:8000)")
+        click.echo(f"  vega web run                # Start Vega Web server (http://localhost:8000)")
         click.echo(f"  vega web run --reload       # Start with auto-reload")
         click.echo(f"  python main.py hello        # Run CLI command")
         click.echo(f"  python main.py --help       # Show all commands")

{vega_framework-0.1.35 → vega_framework-0.2.1}/vega/cli/commands/web.py

@@ -1,4 +1,4 @@
-"""Web command - Manage FastAPI web server"""
+"""Web command - Manage Vega Web server"""
 import sys
 from pathlib import Path
 
@@ -7,7 +7,7 @@ import click
 
 @click.group()
 def web():
-    """Manage FastAPI web server
+    """Manage Vega Web server
 
     Commands to manage the web server for your Vega project.
     The web module must be added to the project first using 'vega add web'.
@@ -21,7 +21,7 @@ def web():
 @click.option('--reload', is_flag=True, help='Enable auto-reload')
 @click.option('--path', default='.', help='Path to Vega project (default: current directory)')
 def run(host: str, port: int, reload: bool, path: str):
-    """Start the FastAPI web server
+    """Start the Vega Web server
 
     Examples:
         vega web run
@@ -42,7 +42,7 @@ def run(host: str, port: int, reload: bool, path: str):
     web_main = project_path / "presentation" / "web" / "main.py"
     if not web_main.exists():
         click.echo(click.style("ERROR: Web module not found", fg='red'))
-        click.echo("\nThe FastAPI web module is not available in this project.")
+        click.echo("\nThe Vega Web module is not available in this project.")
         click.echo("Add it using:")
         click.echo(click.style("  vega add web", fg='cyan', bold=True))
         sys.exit(1)
@@ -56,8 +56,9 @@ def run(host: str, port: int, reload: bool, path: str):
         import uvicorn
     except ImportError:
         click.echo(click.style("ERROR: uvicorn not installed", fg='red'))
-        click.echo("\nInstall FastAPI dependencies:")
-        click.echo(click.style("  poetry add fastapi uvicorn[standard]", fg='cyan', bold=True))
+        click.echo("\nUvicorn is required but not installed.")
+        click.echo("It should be included with vega-framework, but you can also install it with:")
+        click.echo(click.style("  poetry add uvicorn[standard]", fg='cyan', bold=True))
         sys.exit(1)
 
     # Initialize DI container first
@@ -73,7 +74,7 @@ def run(host: str, port: int, reload: bool, path: str):
     try:
         from presentation.web.main import app
     except ImportError as e:
-        click.echo(click.style("ERROR: Failed to import FastAPI app", fg='red'))
+        click.echo(click.style("ERROR: Failed to import Vega Web app", fg='red'))
         click.echo(f"\nDetails: {e}")
         click.echo("\nMake sure:")
         click.echo("  1. You are in the project directory or use --path")

{vega_framework-0.1.35 → vega_framework-0.2.1}/vega/cli/main.py

@@ -34,7 +34,7 @@ def cli():
 
 @cli.command()
 @click.argument('project_name')
-@click.option('--template', default='basic', help='Project template (basic, fastapi, ai-rag)')
+@click.option('--template', default='basic', help='Project template (basic, web, ai-rag)')
 @click.option('--path', default='.', help='Parent directory for project')
 def init(project_name, template, path):
     """
@@ -49,7 +49,7 @@ def init(project_name, template, path):
 
     Examples:
         vega init my-app
-        vega init my-api --template=fastapi
+        vega init my-api --template=web
         vega init my-ai --template=ai-rag --path=./projects
     """
     init_project(project_name, template, path)
@@ -88,8 +88,8 @@ def generate(component_type, name, path, impl, request, response):
         service     - Service interface (domain layer)
         interactor  - Use case (business logic)
         mediator    - Workflow (orchestrates use cases)
-        router      - FastAPI router (requires web module)
-        middleware  - FastAPI middleware (requires web module)
+        router      - Vega Web router (requires web module)
+        middleware  - Vega Web middleware (requires web module)
         webmodel    - Pydantic request/response models (requires web module)
         model       - SQLAlchemy model (requires sqlalchemy module)
         command     - CLI command (async by default)

vega_framework-0.2.1/vega/cli/scaffolds/__init__.py

@@ -0,0 +1,13 @@
+"""Scaffolding helpers for Vega CLI."""
+
+from .vega_web import create_vega_web_scaffold
+from .sqlalchemy import create_sqlalchemy_scaffold
+
+# Backward compatibility alias
+create_fastapi_scaffold = create_vega_web_scaffold
+
+__all__ = [
+    "create_vega_web_scaffold",
+    "create_fastapi_scaffold",  # Deprecated: use create_vega_web_scaffold
+    "create_sqlalchemy_scaffold",
+]

vega_framework-0.2.1/vega/cli/scaffolds/vega_web.py

@@ -0,0 +1,109 @@
+"""Vega Web scaffolding for new projects"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable, Iterable
+
+import click
+
+from vega.cli.templates import (
+    render_vega_app,
+    render_vega_health_route,
+    render_vega_main,
+    render_vega_routes_init_autodiscovery,
+    render_vega_user_route,
+    render_pydantic_models_init,
+    render_pydantic_user_models,
+    render_web_package_init,
+)
+
+
+def create_vega_web_scaffold(
+    project_root: Path,
+    project_name: str,
+    *,
+    overwrite: bool = False,
+    echo: Callable[[str], None] | None = None,
+) -> list[Path]:
+    """
+    Create Vega Web scaffolding under the project presentation/web/ directory.
+
+    This creates a complete web application structure using Vega's built-in
+    web framework (built on Starlette).
+
+    Args:
+        project_root: Root directory of the project
+        project_name: Name of the project
+        overwrite: Whether to overwrite existing files
+        echo: Function to print messages (defaults to click.echo)
+
+    Returns:
+        List of created file paths
+    """
+    if echo is None:
+        echo = click.echo
+
+    created: list[Path] = []
+    web_dir = project_root / "presentation" / "web"
+    routes_dir = web_dir / "routes"
+    models_dir = web_dir / "models"
+
+    files: Iterable[tuple[Path, str]] = (
+        (web_dir / "__init__.py", render_web_package_init()),
+        (web_dir / "app.py", render_vega_app(project_name)),
+        (web_dir / "main.py", render_vega_main(project_name)),
+        (routes_dir / "__init__.py", render_vega_routes_init_autodiscovery()),
+        (routes_dir / "health.py", render_vega_health_route()),
+        (routes_dir / "users.py", render_vega_user_route()),
+        (models_dir / "__init__.py", render_pydantic_models_init()),
+        (models_dir / "user_models.py", render_pydantic_user_models()),
+    )
+
+    web_dir.mkdir(parents=True, exist_ok=True)
+    routes_dir.mkdir(parents=True, exist_ok=True)
+    models_dir.mkdir(parents=True, exist_ok=True)
+
+    for path, content in files:
+        rel_path = path.relative_to(project_root)
+        if path.exists() and not overwrite:
+            echo(
+                click.style(
+                    f"WARNING: {rel_path} already exists. Skipping.",
+                    fg="yellow",
+                )
+            )
+            continue
+
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+        created.append(rel_path)
+        echo(f"+ Created {click.style(str(rel_path), fg='green')}")
+
+    echo("\n[TIP] Vega Web scaffold ready:")
+    echo("   1. poetry install  # sync dependencies (or poetry update)")
+    echo("   2. poetry run vega web run --reload")
+    echo("   3. Or: poetry run uvicorn presentation.web.main:app --reload")
+
+    return created
+
+
+def _ensure_dependency_line(lines: list[str], name: str, spec: str) -> bool:
+    """Insert dependency assignment into [tool.poetry.dependencies] if missing."""
+    header = "[tool.poetry.dependencies]"
+    try:
+        start = next(i for i, line in enumerate(lines) if line.strip() == header)
+    except StopIteration:
+        return False
+
+    end = start + 1
+    while end < len(lines) and not lines[end].startswith("["):
+        end += 1
+
+    block = lines[start + 1:end]
+    if any(line.strip().startswith(f"{name} =") for line in block):
+        return False
+
+    insertion = f"{name} = \"{spec}\"\n"
+    lines.insert(end, insertion)
+    return True