djangx 1.5.5__py3-none-any.whl → 1.5.7__py3-none-any.whl

djangx/management/commands/startproject.py

@@ -1,10 +1,14 @@
 from dataclasses import dataclass
-from enum import StrEnum
 from pathlib import Path
+from typing import Final
 
 from christianwhocodes.core import ExitCode, Version
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from rich.prompt import Confirm, Prompt
 
 from ... import PKG_DISPLAY_NAME, PKG_NAME, PROJECT_DIR, PROJECT_INIT_NAME
+from ...enums import DatabaseBackend, PresetType
 
 __all__ = ["initialize"]
 
@@ -12,30 +16,34 @@ __all__ = ["initialize"]
 # Configuration & Templates
 # ============================================================================
 
-
-class PresetType(StrEnum):
-    """Available project presets."""
-
-    DEFAULT = "default"
-    VERCEL = "vercel"
+# VCS and common items that shouldn't prevent initialization
+SAFE_DIRECTORY_ITEMS: Final[set[str]] = {
+    ".git",
+    ".gitignore",
+    ".gitattributes",
+    ".hg",
+    ".hgignore",
+    "LICENSE",
+    "LICENSE.txt",
+    "LICENSE.md",
+}
 
 
 @dataclass(frozen=True)
 class _ProjectDependencies:
     """Manages project dependencies."""
 
-    base: tuple[str, ...] = (
-        "pillow>=12.1.0",
-        "psycopg[binary,pool]>=3.3.2",
-    )
+    base: tuple[str, ...] = ("pillow>=12.1.0",)
     dev: tuple[str, ...] = ("djlint>=1.36.4", "ruff>=0.15.0")
+    postgresql: tuple[str, ...] = ("psycopg[binary,pool]>=3.3.2",)
     vercel: tuple[str, ...] = ("vercel>=0.3.8",)
 
-    def get_for_preset(self, preset: PresetType) -> list[str]:
-        """Get dependencies for a specific preset.
+    def get_for_config(self, preset: PresetType, database: DatabaseBackend) -> list[str]:
+        """Get dependencies for a specific configuration.
 
         Args:
             preset: The preset type.
+            database: The database backend.
 
         Returns:
             List of dependency strings including base dependencies.
@@ -43,6 +51,11 @@ class _ProjectDependencies:
         deps = list(self.base)
         deps.append(f"{PKG_NAME}>={Version.get(PKG_NAME)[0]}")
 
+        # Add database-specific dependencies
+        if database == DatabaseBackend.POSTGRESQL:
+            deps.extend(self.postgresql)
+
+        # Add preset-specific dependencies
         if preset == PresetType.VERCEL:
             deps.extend(self.vercel)
 
@@ -55,7 +68,7 @@ class _TemplateManager:
     @staticmethod
     def gitignore() -> str:
         """Generate .gitignore content."""
-        return """
+        return f"""
 # Python-generated files
 __pycache__/
 *.py[oc]
@@ -79,8 +92,8 @@ wheels/
 # Environment variables files
 /.env*
 
-# SQLite database file
-/db.sqlite3
+# {DatabaseBackend.SQLITE3.value.capitalize()} database file
+/db.{DatabaseBackend.SQLITE3.value}
 """.strip()
 
     @staticmethod
@@ -98,12 +111,19 @@ A new project built with {PKG_DISPLAY_NAME}.
 """.strip()
 
     @staticmethod
-    def pyproject_toml(preset: PresetType, dependencies: list[str]) -> str:
+    def pyproject_toml(
+        preset: PresetType,
+        database: DatabaseBackend,
+        dependencies: list[str],
+        use_postgres_env_vars: bool = False,
+    ) -> str:
         """Generate pyproject.toml content.
 
         Args:
             preset: The preset type.
+            database: The database backend.
             dependencies: List of project dependencies.
+            use_postgres_env_vars: Whether to use env vars for PostgreSQL config.
 
         Returns:
             Formatted pyproject.toml content.
@@ -112,15 +132,25 @@ A new project built with {PKG_DISPLAY_NAME}.
         deps_formatted = ",\n    ".join(f'"{dep}"' for dep in dependencies)
         dev_deps_formatted = ",\n    ".join(f'"{dep}"' for dep in deps.dev)
 
-        # Preset-specific tool configuration
+        # Build tool configuration based on preset and database
+        tool_config_parts: list[str] = []
+
+        # Database configuration
+        if database == DatabaseBackend.POSTGRESQL:
+            tool_config_parts.append(
+                f'db = {{ backend = "{DatabaseBackend.POSTGRESQL.value}", use-vars = {str(use_postgres_env_vars).lower()} }}'
+            )
+
+        # Storage configuration (Vercel-specific)
+        if preset == PresetType.VERCEL:
+            tool_config_parts.append(
+                'storage = { backend = "vercel", blob-token = "keep-your-vercel-blob-token-secret-in-env" }'
+            )
+
+        # Format the tool config section
         tool_config = ""
-        match preset:
-            case PresetType.VERCEL:
-                tool_config = (
-                    '\nstorage = { backend = "vercel", blob-token = "your-vercel-blob-token" }\n'
-                )
-            case _:
-                pass
+        if tool_config_parts:
+            tool_config = "\n" + "\n".join(tool_config_parts) + "\n"
 
         return f"""[project]
 name = "{PROJECT_INIT_NAME}"
@@ -168,21 +198,47 @@ class HomeView(TemplateView):
     template_name = "home/index.html"
 """
 
+    @staticmethod
+    def home_index_html() -> str:
+        """Generate home app index.html content."""
+        return """{% extends "ui/index.html" %}
+
+{% load org %}
+
+{% block title %}
+  <title>Welcome - {% org "name" %} App</title>
+{% endblock title %}
+
+{% block fonts %}
+  <link href="https://fonts.googleapis.com" rel="preconnect" />
+  <link href="https://fonts.gstatic.com" rel="preconnect" crossorigin />
+  <link href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100;0,300;0,400;0,500;0,700;0,900;1,100;1,300;1,400;1,500;1,700;1,900&family=Raleway:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;0,800;0,900;1,100;1,200;1,300;1,400;1,500;1,600;1,700;1,800;1,900&family=Mulish:ital,wght@0,200;0,300;0,400;0,500;0,600;0,700;0,800;0,900;1,200;1,300;1,400;1,500;1,600;1,700;1,800;1,900&display=swap"
+        rel="stylesheet" />
+{% endblock fonts %}
+
+{% block main %}
+  <main>
+    <section class="container-full py-8">
+    </section>
+  </main>
+{% endblock main %}
+"""
+
     @staticmethod
     def tailwind_css() -> str:
         """Generate Tailwind CSS content."""
-        return """@import "tailwindcss";
+        return f"""@import "tailwindcss";
 
 /* =============================================================================
    SOURCE FILES
    ============================================================================= */
-@source "../../../../.venv/**/djangx/ui/templates/ui/**/*.html";
+@source "../../../../.venv/**/{PKG_NAME}/ui/templates/ui/**/*.html";
 @source "../../../templates/home/**/*.html";
 
 /* =============================================================================
    THEME CONFIGURATION
    ============================================================================= */
-@theme {
+@theme {{
   /* ---------------------------------------------------------------------------
      TYPOGRAPHY
      --------------------------------------------------------------------------- */
@@ -221,147 +277,229 @@ class HomeView(TemplateView):
   --color-nav-dropdown-bg: #2e2e2e; /* Dropdown background */
   --color-nav-dropdown: #d9d9d9; /* Dropdown text color */
   --color-nav-dropdown-hover: #ff4d4f; /* Dropdown hover state */
-}
+}}
 
 /* =============================================================================
    LIGHT THEME OVERRIDES
    ============================================================================= */
-@theme light {
+@theme light {{
   --color-background: rgba(41, 41, 41, 0.8);
   --color-surface: #484848;
-}
+}}
 
 /* =============================================================================
    DARK THEME OVERRIDES
    ============================================================================= */
-@theme dark {
+@theme dark {{
   --color-background: #060606;
   --color-surface: #252525;
   --color-default: #ffffff;
   --color-heading: #ffffff;
-}
+}}
 
 /* =============================================================================
    UTILITY CLASSES
    ============================================================================= */
-@layer utilities {
+@layer utilities {{
   /* Full-width container */
-  .container-full {
+  .container-full {{
     @apply mx-auto w-full px-8;
-  }
+  }}
 
   /* Responsive container (Mobile→SM→MD→LG→XL→2XL: 100%→92%→83%→80%→75%→1400px max) */
-  .container {
+  .container {{
     @apply mx-auto w-full px-8 sm:w-11/12 sm:px-4 md:w-5/6 lg:w-4/5 xl:w-3/4 xl:px-0 2xl:max-w-[1400px];
-  }
-}
+  }}
+}}
 
 /* =============================================================================
    BASE STYLES - Global element styling
    ============================================================================= */
-@layer base {
-  :root {
+@layer base {{
+  :root {{
     @apply scroll-smooth;
-  }
+  }}
 
-  body {
+  body {{
     @apply bg-background text-default font-default antialiased;
-  }
+  }}
 
   h1,
   h2,
   h3,
   h4,
   h5,
-  h6 {
+  h6 {{
     @apply text-heading font-heading text-balance;
-  }
+  }}
 
-  a {
+  a {{
     @apply text-accent no-underline transition-colors duration-200 ease-in-out;
-  }
+  }}
 
-  a:hover {
+  a:hover {{
     color: color-mix(in srgb, var(--color-accent), white 15%);
-  }
-}
+  }}
+}}
 """
 
 
 # ============================================================================
-# File Generators
+# File Management
 # ============================================================================
 
 
+class _FileTracker:
+    """Tracks files and directories created during initialization for rollback."""
+
+    def __init__(self):
+        """Initialize the file tracker."""
+        self._created_paths: list[Path] = []
+
+    def track(self, path: Path) -> None:
+        """Track a created file or directory.
+
+        Args:
+            path: The path that was created.
+        """
+        if path not in self._created_paths:
+            self._created_paths.append(path)
+
+    def cleanup_all(self) -> None:
+        """Remove all tracked files and directories in reverse order of creation."""
+        from shutil import rmtree
+
+        # Reverse order to remove files before their parent directories
+        for path in reversed(self._created_paths):
+            try:
+                if path.exists():
+                    if path.is_dir():
+                        rmtree(path)
+                    else:
+                        path.unlink()
+            except Exception:
+                # Best effort cleanup - don't raise on cleanup failures
+                pass
+
+        self._created_paths.clear()
+
+
 class _ProjectFileWriter:
     """Handles file writing operations for project initialization."""
 
-    def __init__(self, project_dir: Path):
+    def __init__(self, project_dir: Path, console: Console, tracker: _FileTracker):
         """Initialize the file writer.
 
         Args:
             project_dir: The project directory path.
+            console: Rich console for output.
+            tracker: File tracker for rollback support.
         """
         self.project_dir = project_dir
+        self.console = console
+        self.tracker = tracker
 
-    def write(self, filename: str, content: str) -> None:
-        """Write content to a file.
+    def write_if_not_exists(self, filename: str, content: str) -> bool:
+        """Write content to a file only if it doesn't exist.
 
         Args:
             filename: Name of the file to create.
             content: Content to write.
 
+        Returns:
+            True if file was created, False if it already existed.
+
         Raises:
             IOError: If file cannot be written.
             PermissionError: If lacking permission to write.
         """
         file_path = self.project_dir / filename
+
+        if file_path.exists():
+            return False
+
         file_path.write_text(content.strip(), encoding="utf-8")
+        self.tracker.track(file_path)
+        return True
 
-    def write_to_path(self, path: Path, content: str) -> None:
-        """Write content to a specific path.
+    def write_to_path_if_not_exists(self, path: Path, content: str) -> bool:
+        """Write content to a specific path only if it doesn't exist.
 
         Args:
             path: Full path to the file.
             content: Content to write.
 
+        Returns:
+            True if file was created, False if it already existed.
+
         Raises:
             IOError: If file cannot be written.
             PermissionError: If lacking permission to write.
         """
+        if path.exists():
+            return False
+
         path.write_text(content.strip(), encoding="utf-8")
+        self.tracker.track(path)
+        return True
 
-    def ensure_dir(self, path: Path) -> None:
+    def ensure_dir(self, path: Path) -> bool:
         """Ensure a directory exists.
 
         Args:
             path: Directory path to create.
+
+        Returns:
+            True if directory was created, False if it already existed.
         """
+        if path.exists():
+            return False
+
         path.mkdir(parents=True, exist_ok=True)
+        self.tracker.track(path)
+        return True
+
+
+# ============================================================================
+# Home App Creator
+# ============================================================================
 
 
 class _HomeAppCreator:
     """Creates the default 'home' Django application."""
 
-    def __init__(self, project_dir: Path, writer: _ProjectFileWriter, templates: _TemplateManager):
+    def __init__(
+        self,
+        project_dir: Path,
+        writer: _ProjectFileWriter,
+        templates: _TemplateManager,
+        console: Console,
+    ):
         """Initialize the home app creator.
 
         Args:
             project_dir: The project directory path.
             writer: File writer instance.
             templates: Template manager instance.
+            console: Rich console for output.
         """
         self.project_dir = project_dir
         self.writer = writer
         self.templates = templates
+        self.console = console
         self.home_dir = project_dir / "home"
 
     def create(self) -> None:
         """Create the home app with all necessary files and directories."""
-        from django.core.management import call_command
+        # Check if home app already exists
+        if self.home_dir.exists():
+            self.console.print(
+                "[yellow]Home app directory already exists, skipping app creation[/yellow]"
+            )
+            return
 
         # Create the Django app structure
-        call_command("startapp", "home")
+        self._create_app_structure()
 
         # Create app files
         self._create_urls()
@@ -369,15 +507,36 @@ class _HomeAppCreator:
         self._create_templates()
         self._create_static_files()
 
+    def _create_app_structure(self) -> None:
+        """Create the basic Django app structure using startapp command."""
+        from django.core.management import call_command
+
+        try:
+            call_command("startapp", "home")
+            # Track the created directory
+            self.writer.tracker.track(self.home_dir)
+        except Exception as e:
+            raise IOError(f"Failed to create home app: {e}") from e
+
     def _create_urls(self) -> None:
         """Create urls.py for the home app."""
         urls_path = self.home_dir / "urls.py"
-        self.writer.write_to_path(urls_path, self.templates.home_urls())
+        if self.writer.write_to_path_if_not_exists(urls_path, self.templates.home_urls()):
+            pass  # File was created
+        else:
+            self.console.print("[dim]urls.py already exists, skipping[/dim]")
 
     def _create_views(self) -> None:
         """Create views.py for the home app."""
         views_path = self.home_dir / "views.py"
-        self.writer.write_to_path(views_path, self.templates.home_views())
+        # Only overwrite if it's the default Django startapp content
+        if views_path.exists():
+            content = views_path.read_text(encoding="utf-8")
+            # Check if it's the default Django views.py (contains only imports or is minimal)
+            if len(content.strip()) < 100:  # Default Django file is very short
+                views_path.write_text(self.templates.home_views().strip(), encoding="utf-8")
+        else:
+            self.writer.write_to_path_if_not_exists(views_path, self.templates.home_views())
 
     def _create_templates(self) -> None:
         """Create template directory structure and files."""
@@ -385,7 +544,7 @@ class _HomeAppCreator:
         self.writer.ensure_dir(templates_dir)
 
         index_path = templates_dir / "index.html"
-        self.writer.write_to_path(index_path, "")
+        self.writer.write_to_path_if_not_exists(index_path, self.templates.home_index_html())
 
     def _create_static_files(self) -> None:
         """Create static directory structure and CSS files."""
@@ -393,7 +552,7 @@ class _HomeAppCreator:
         self.writer.ensure_dir(static_dir)
 
         css_path = static_dir / "tailwind.css"
-        self.writer.write_to_path(css_path, self.templates.tailwind_css())
+        self.writer.write_to_path_if_not_exists(css_path, self.templates.tailwind_css())
 
 
 # ============================================================================
@@ -415,6 +574,7 @@ class _ProjectInitializer:
         project_dir: Path,
         dependencies: _ProjectDependencies | None = None,
         templates: _TemplateManager | None = None,
+        console: Console | None = None,
     ):
         """Initialize the project initializer.
 
@@ -422,22 +582,54 @@ class _ProjectInitializer:
             project_dir: The directory where the project will be created.
             dependencies: Dependency manager (uses default if None).
             templates: Template manager (uses default if None).
+            console: Rich console for output (creates new if None).
         """
         self.project_dir = Path(project_dir)
         self.dependencies = dependencies or _ProjectDependencies()
         self.templates = templates or _TemplateManager()
-        self.writer = _ProjectFileWriter(self.project_dir)
+        self.console = console or Console()
+        self.tracker = _FileTracker()
+        self.writer = _ProjectFileWriter(self.project_dir, self.console, self.tracker)
 
-    def _validate_directory(self) -> None:
+    def _validate_directory(self, force: bool = False) -> None:
         """Validate that the directory is suitable for initialization.
 
+        Args:
+            force: Skip validation and proceed regardless.
+
         Raises:
-            ProjectInitializationError: If directory is not empty.
+            ProjectInitializationError: If directory contains non-VCS files and user declines.
         """
-        if any(self.project_dir.iterdir()):
-            raise ProjectInitializationError(
-                f"Directory is not empty. Please choose an empty directory to start a new {PKG_DISPLAY_NAME} project."
-            )
+        if force:
+            return
+
+        existing_items = list(self.project_dir.iterdir())
+        if not existing_items:
+            return
+
+        # Filter out safe items
+        problematic_items = [
+            item for item in existing_items if item.name not in SAFE_DIRECTORY_ITEMS
+        ]
+
+        if not problematic_items:
+            # Only safe items present - proceed without prompting
+            return
+
+        # Show what exists and ask for confirmation
+        items_list = "\n  - ".join(item.name for item in problematic_items)
+
+        self.console.print(f"[yellow]Directory is not empty. Found:[/yellow]\n  - {items_list}\n")
+
+        should_proceed = Confirm.ask(
+            f"Initialize {PKG_DISPLAY_NAME} project anyway? "
+            "This will skip existing files and create new ones",
+            default=False,
+            console=self.console,
+        )
+
+        if not should_proceed:
+            raise ProjectInitializationError("Initialization cancelled by user.")
 
     def _get_preset_choice(self, preset: str | None = None) -> PresetType:
         """Get the user's preset choice or validate the provided one.
@@ -451,8 +643,6 @@ class _ProjectInitializer:
         Raises:
             ValueError: If preset is invalid.
         """
-        from rich.prompt import Prompt
-
         if preset:
             try:
                 return PresetType(preset)
@@ -460,99 +650,340 @@ class _ProjectInitializer:
                 valid_presets = [p.value for p in PresetType]
                 raise ValueError(
                     f"Invalid preset '{preset}'. Must be one of: {', '.join(valid_presets)}"
-                )
+                ) from None
 
         choice = Prompt.ask(
             "Choose a preset",
             choices=[p.value for p in PresetType],
             default=PresetType.DEFAULT.value,
+            console=self.console,
         )
         return PresetType(choice)
 
-    def _create_core_files(self, preset: PresetType) -> None:
+    def _get_postgres_config_choice(self, preset: PresetType) -> bool:
+        """Get whether to use environment variables for PostgreSQL.
+
+        Args:
+            preset: The preset type (Vercel always uses env vars).
+
+        Returns:
+            True if using environment variables, False for pg_service/pgpass files.
+        """
+        # Vercel requires environment variables (no filesystem access)
+        if preset == PresetType.VERCEL:
+            return True
+
+        # For default preset, let user choose
+        self.console.print("\n[bold]PostgreSQL Configuration Method:[/bold]")
+        self.console.print("  • [cyan]Environment variables[/cyan]: Store credentials in .env file")
+        self.console.print(
+            "  • [cyan]PostgreSQL service files[/cyan]: Use pg_service.conf and .pgpass"
+        )
+
+        use_env_vars = Confirm.ask(
+            "Use environment variables for PostgreSQL configuration?",
+            default=True,
+            console=self.console,
+        )
+
+        return use_env_vars
+
+    def _get_database_choice(
+        self, preset: PresetType, database: str | None = None
+    ) -> tuple[DatabaseBackend, bool]:
+        """Get the user's database choice and PostgreSQL config method.
+
+        Args:
+            preset: The preset type (Vercel requires PostgreSQL).
+            database: Optional database to use without prompting.
+
+        Returns:
+            Tuple of (database backend, use_env_vars_for_postgres).
+
+        Raises:
+            ValueError: If database is invalid or incompatible with preset.
+        """
+        # Vercel preset requires PostgreSQL (no file system access on Vercel)
+        if preset == PresetType.VERCEL:
+            if database and database != DatabaseBackend.POSTGRESQL:
+                raise ValueError(f"Vercel preset requires PostgreSQL database (got: {database})")
+            return DatabaseBackend.POSTGRESQL, True  # Always use env vars with Vercel
+
+        # If database explicitly provided, validate it
+        if database:
+            try:
+                db_backend = DatabaseBackend(database)
+            except ValueError:
+                valid_databases = [db.value for db in DatabaseBackend]
+                raise ValueError(
+                    f"Invalid database '{database}'. Must be one of: {', '.join(valid_databases)}"
+                ) from None
+
+            # Ask about PostgreSQL config method if applicable
+            use_env_vars = (
+                self._get_postgres_config_choice(preset)
+                if db_backend == DatabaseBackend.POSTGRESQL
+                else False
+            )
+            return db_backend, use_env_vars
+
+        # Interactive prompt for default preset
+        choice = Prompt.ask(
+            "Choose a database",
+            choices=[db.value for db in DatabaseBackend],
+            default=DatabaseBackend.SQLITE3.value,
+            console=self.console,
+        )
+        db_backend = DatabaseBackend(choice)
+
+        # Ask about PostgreSQL config method if applicable
+        use_env_vars = (
+            self._get_postgres_config_choice(preset)
+            if db_backend == DatabaseBackend.POSTGRESQL
+            else False
+        )
+        return db_backend, use_env_vars
+
+    def _create_core_files(
+        self, preset: PresetType, database: DatabaseBackend, use_postgres_env_vars: bool
+    ) -> None:
         """Create core project configuration files.
 
         Args:
             preset: The preset type to use.
+            database: The database backend to use.
+            use_postgres_env_vars: Whether to use env vars for PostgreSQL config.
 
         Raises:
             IOError: If files cannot be created.
         """
-        dependencies = self.dependencies.get_for_preset(preset)
-
-        self.writer.write("pyproject.toml", self.templates.pyproject_toml(preset, dependencies))
-        self.writer.write(".gitignore", self.templates.gitignore())
-        self.writer.write("README.md", self.templates.readme())
-
-    def _configure_preset_files(self, preset: PresetType) -> None:
+        dependencies = self.dependencies.get_for_config(preset, database)
+
+        # Create files only if they don't exist
+        files_to_create = {
+            "pyproject.toml": self.templates.pyproject_toml(
+                preset, database, dependencies, use_postgres_env_vars
+            ),
+            ".gitignore": self.templates.gitignore(),
+            "README.md": self.templates.readme(),
+        }
+
+        for filename, content in files_to_create.items():
+            if self.writer.write_if_not_exists(filename, content):
+                pass  # File was created
+            else:
+                self.console.print(f"[dim]{filename} already exists, skipping[/dim]")
+
+    def _configure_preset_files_and_env_example(self, preset: PresetType) -> None:
         """Configure files based on the chosen preset.
 
         Args:
             preset: The preset configuration to apply.
+
+        Raises:
+            IOError: If preset-specific file generation fails.
         """
-        if preset == PresetType.VERCEL:
-            # Import here to avoid circular dependencies
-            from .generators import ServerFileGenerator, VercelFileGenerator
+        from subprocess import CalledProcessError, run
 
-            VercelFileGenerator().create()
-            ServerFileGenerator().create()
+        try:
+            match preset:
+                case PresetType.VERCEL:
+                    # Only generate vercel.json if it doesn't exist
+                    if not (self.project_dir / "vercel.json").exists():
+                        run(
+                            [PKG_NAME, "generate", "-f", "vercel", "-y"],
+                            cwd=self.project_dir,
+                            check=True,
+                            capture_output=True,
+                        )
+                        # Track the created file
+                        self.tracker.track(self.project_dir / "vercel.json")
+                    else:
+                        self.console.print("[dim]vercel.json already exists, skipping[/dim]")
+
+                    # Only generate api/server.py if it doesn't exist
+                    server_path = self.project_dir / "api" / "server.py"
+                    if not server_path.exists():
+                        run(
+                            [PKG_NAME, "generate", "-f", "server", "-y"],
+                            cwd=self.project_dir,
+                            check=True,
+                            capture_output=True,
+                        )
+                        # Track the created files
+                        self.tracker.track(self.project_dir / "api")
+                    else:
+                        self.console.print("[dim]api/server.py already exists, skipping[/dim]")
+                case _:
+                    # Future presets will be added here
+                    pass
+
+        except CalledProcessError as e:
+            error_msg = e.stderr.decode() if e.stderr else str(e)
+            raise IOError(f"Failed to generate preset-specific files: {error_msg}") from e
+        except FileNotFoundError as e:
+            raise IOError(
+                f"Command '{PKG_NAME}' not found. Ensure {PKG_DISPLAY_NAME} is properly installed."
+            ) from e
+
+        # Only generate .env.example file if it doesn't exist
+        env_example_path = self.project_dir / ".env.example"
+        if not env_example_path.exists():
+            try:
+                run(
+                    [PKG_NAME, "generate", "-f", "env", "-y"],
+                    cwd=self.project_dir,
+                    check=True,
+                    capture_output=True,
+                )
+                # Track the created file
+                self.tracker.track(env_example_path)
+            except CalledProcessError as e:
+                error_msg = e.stderr.decode() if e.stderr else str(e)
+                raise IOError(f"Failed to generate .env file: {error_msg}") from e
+            except FileNotFoundError as e:
+                raise IOError(
+                    f"Command '{PKG_NAME}' not found. Ensure {PKG_DISPLAY_NAME} is properly installed."
+                ) from e
+        else:
+            self.console.print("[dim].env.example already exists, skipping[/dim]")
 
     def _create_home_app(self) -> None:
         """Create the default home application."""
-        home_creator = _HomeAppCreator(self.project_dir, self.writer, self.templates)
+        home_creator = _HomeAppCreator(self.project_dir, self.writer, self.templates, self.console)
         home_creator.create()
 
-    def create(self, preset: str | None = None) -> ExitCode:
+    def _show_next_steps(
+        self, preset: PresetType, database: DatabaseBackend, use_postgres_env_vars: bool
+    ) -> None:
+        """Display next steps for the user after successful initialization.
+
+        Args:
+            preset: The preset that was used.
+            database: The database backend that was chosen.
+            use_postgres_env_vars: Whether using env vars for PostgreSQL.
+        """
+        from rich.panel import Panel
+
+        next_steps = [
+            "1. Install dependencies: [bold cyan]uv sync[/bold cyan]",
+            "2. Copy [bold].env.example[/bold] to [bold].env[/bold] and configure",
+        ]
+
+        step_num = 3
+
+        # Database-specific instructions
+        if database == DatabaseBackend.POSTGRESQL:
+            if use_postgres_env_vars:
+                next_steps.append(
+                    f"{step_num}. Configure PostgreSQL connection in [bold].env[/bold]"
+                )
+            else:
+                next_steps.append(
+                    f"{step_num}. Configure PostgreSQL connection using [bold]pg_service.conf[/bold] and [bold].pgpass[/bold] files"
+                )
+            step_num += 1
+
+        # Preset-specific instructions
+        if preset == PresetType.VERCEL:
+            next_steps.append(f"{step_num}. Configure Vercel blob token in [bold].env[/bold]")
+            step_num += 1
+
+        next_steps.append(
+            f"{step_num}. Run development server: [bold cyan]uv run djx runserver[/bold cyan]"
+        )
+
+        panel = Panel(
+            "\n".join(next_steps),
+            title=f"[bold green]✓ {PKG_DISPLAY_NAME} project initialized successfully![/bold green]",
+            border_style="green",
+            padding=(1, 2),
+        )
+
+        self.console.print("\n")
+        self.console.print(panel)
+
+    def create(
+        self, preset: str | None = None, database: str | None = None, force: bool = False
+    ) -> ExitCode:
         """Execute the full project initialization workflow.
 
         Args:
             preset: Optional preset to use without prompting.
+            database: Optional database backend to use without prompting.
+            force: Skip directory validation.
 
         Returns:
             ExitCode indicating success or failure.
         """
-        from christianwhocodes.io import Text, print
-
         try:
-            # Validate directory is empty
-            self._validate_directory()
+            # Validate directory is empty or acceptable
+            self._validate_directory(force=force)
 
             # Get and validate preset choice
             chosen_preset = self._get_preset_choice(preset)
 
-            # Create core configuration files
-            self._create_core_files(chosen_preset)
-
-            # Configure preset-specific files
-            self._configure_preset_files(chosen_preset)
-
-            # Create default app
-            self._create_home_app()
-
-            print(
-                f"✓ {PKG_DISPLAY_NAME} project initialized successfully!",
-                Text.SUCCESS,
+            # Get and validate database choice
+            chosen_database, use_postgres_env_vars = self._get_database_choice(
+                chosen_preset, database
             )
+
+            with Progress(
+                SpinnerColumn(),
+                TextColumn("[progress.description]{task.description}"),
+                console=self.console,
+                transient=True,
+            ) as progress:
+                # Create core configuration files
+                task = progress.add_task("Creating project files...", total=None)
+                self._create_core_files(chosen_preset, chosen_database, use_postgres_env_vars)
+                progress.update(task, completed=True)
+
+                # Configure preset-specific files
+                task = progress.add_task("Configuring preset files...", total=None)
+                self._configure_preset_files_and_env_example(chosen_preset)
+                progress.update(task, completed=True)
+
+                # Create default app
+                task = progress.add_task("Creating home app...", total=None)
+                self._create_home_app()
+                progress.update(task, completed=True)
+
+            self._show_next_steps(chosen_preset, chosen_database, use_postgres_env_vars)
             return ExitCode.SUCCESS
 
         except KeyboardInterrupt:
-            print("\nProject initialization cancelled.", Text.WARNING)
+            self.tracker.cleanup_all()
+            self.console.print(
+                "\n[yellow]Project initialization cancelled. Cleaned up partial files.[/yellow]"
+            )
             return ExitCode.ERROR
 
         except ProjectInitializationError as e:
-            print(str(e), Text.WARNING)
+            # User declined to proceed - no cleanup needed since nothing was created
+            self.console.print(f"[yellow]{e}[/yellow]")
             return ExitCode.ERROR
 
         except ValueError as e:
-            print(f"Configuration error: {e}", Text.ERROR)
+            self.tracker.cleanup_all()
+            self.console.print(
+                f"[red]Configuration error:[/red] {e}\n[yellow]Cleaned up partial files.[/yellow]"
+            )
             return ExitCode.ERROR
 
         except (IOError, PermissionError) as e:
-            print(f"File system error: {e}", Text.ERROR)
+            self.tracker.cleanup_all()
+            self.console.print(
+                f"[red]File system error:[/red] {e}\n[yellow]Cleaned up partial files.[/yellow]"
+            )
             return ExitCode.ERROR
 
         except Exception as e:
-            print(f"Unexpected error during initialization: {e}", Text.ERROR)
+            self.tracker.cleanup_all()
+            self.console.print(
+                f"[red]Unexpected error during initialization:[/red] {e}\n"
+                f"[yellow]Cleaned up partial files.[/yellow]"
+            )
             return ExitCode.ERROR
 
 
@@ -561,13 +992,29 @@ class _ProjectInitializer:
 # ============================================================================
 
 
-def initialize(preset: str | None = None) -> ExitCode:
-    """Main entry point for project initialization.
+def initialize(
+    preset: str | None = None, database: str | None = None, force: bool = False
+) -> ExitCode:
+    f"""Main entry point for project initialization.
+
+    Creates a new project with the specified preset and database configuration.
 
     Args:
         preset: Optional preset to use without prompting.
+            Available presets: 'default', 'vercel'.
+        database: Optional database backend to use without prompting.
+            Available databases: '{DatabaseBackend.SQLITE3.value}', '{DatabaseBackend.POSTGRESQL.value}'.
+            Note: Vercel preset requires PostgreSQL.
+        force: Skip directory validation and proceed even if directory is not empty.
 
     Returns:
-        ExitCode indicating success or failure.
+        ExitCode.SUCCESS if initialization completed successfully,
+        ExitCode.ERROR otherwise.
+
+    Example:
+        >>> initialize(preset="vercel")  # Will auto-select {DatabaseBackend.POSTGRESQL.value} due to Vercel preset requirement
+        >>> initialize(database="{DatabaseBackend.POSTGRESQL.value}")  # Default preset with {DatabaseBackend.POSTGRESQL.value}
+        >>> initialize(preset="default", database="{DatabaseBackend.SQLITE3.value}")  # Default preset with {DatabaseBackend.SQLITE3.value}
+        >>> initialize(force=True)
     """
-    return _ProjectInitializer(PROJECT_DIR).create(preset=preset)
+    return _ProjectInitializer(PROJECT_DIR).create(preset=preset, database=database, force=force)