[FIX] fix fastkit init flow, add failure takeover logic

Author: bnbong

docs/en/reference/faq.md

@@ -194,9 +194,9 @@ Interactive mode allows you to select from a comprehensive feature catalog:
 The interactive mode automatically generates:
 
 - `main.py` with selected features integrated
-- Database and authentication configuration files
-- Docker deployment files (Dockerfile, docker-compose.yml)
-- Test configuration (pytest with coverage)
+- Database and authentication configuration files when the selected options support code generation (e.g. PostgreSQL/MySQL/SQLite/MongoDB for databases, JWT/FastAPI-Users for authentication); other options install the necessary packages only
+- Deployment files matching the selected deployment option (`Dockerfile` when `Docker` is selected, `docker-compose.yml` when `docker-compose` is selected)
+- Test configuration based on the selected testing option (coverage settings are included only when `Coverage` or `Advanced` is selected)
 
 ### Q: How do I see available features for interactive mode?
 

src/fastapi_fastkit/backend/main.py

@@ -185,6 +185,7 @@ def inject_project_metadata(
             description,
         )
         _process_config_file(core_modules.get("config", ""), project_name)
+        _process_main_file(core_modules.get("main", ""), project_name)
 
         print_success("Project metadata injected successfully")
 
@@ -235,6 +236,40 @@ def _process_setup_file(
         raise BackendExceptions(f"Failed to process setup.py: {e}")
 
 
+def _process_main_file(main_py: str, project_name: str) -> None:
+    """
+    Replace project name placeholders in the template main.py file.
+
+    Some templates (e.g. fastapi-single-module) inline the project name directly
+    in main.py rather than reading it from a settings module, so the placeholder
+    must be substituted here as well.
+
+    :param main_py: Path to main.py file
+    :param project_name: Project name
+    """
+    if not main_py or not os.path.exists(main_py):
+        return
+
+    try:
+        with open(main_py, "r", encoding="utf-8") as f:
+            content = f.read()
+
+        if "<project_name>" not in content:
+            return
+
+        content = content.replace("<project_name>", project_name)
+
+        with open(main_py, "w", encoding="utf-8") as f:
+            f.write(content)
+
+        debug_log("Injected project name into main.py", "info")
+        print_info("Injected project name into main.py")
+
+    except (OSError, UnicodeDecodeError) as e:
+        debug_log(f"Error processing main.py: {e}", "error")
+        raise BackendExceptions(f"Failed to process main.py: {e}")
+
+
 def _process_config_file(config_py: str, project_name: str) -> None:
     """
     Process config file and inject project name.

src/fastapi_fastkit/backend/package_managers/poetry_manager.py

@@ -185,12 +185,35 @@ def generate_dependency_file(
             # Create dependencies section for Poetry
             deps_section = ""
             for dep in dependencies:
-                # Convert pip-style to poetry-style
+                # Split off version specifier (only == is converted to Poetry's pinned
+                # form; other specifiers fall back to "*").
                 if "==" in dep:
-                    name, version = dep.split("==", 1)
-                    deps_section += f'{name} = "{version}"\n'
+                    name_part, version = dep.split("==", 1)
+                    version_str = version.strip()
                 else:
-                    deps_section += f'{dep} = "*"\n'
+                    name_part, version_str = dep, "*"
+
+                name_part = name_part.strip()
+
+                # Extract optional extras, e.g. "redis[hiredis]" -> ("redis", ["hiredis"]).
+                extras: list[str] = []
+                if "[" in name_part and name_part.endswith("]"):
+                    bare_name, _, extras_part = name_part.partition("[")
+                    extras = [
+                        extra.strip()
+                        for extra in extras_part[:-1].split(",")
+                        if extra.strip()
+                    ]
+                    name_part = bare_name.strip()
+
+                if extras:
+                    extras_str = ", ".join(f'"{extra}"' for extra in extras)
+                    deps_section += (
+                        f'{name_part} = {{version = "{version_str}", '
+                        f"extras = [{extras_str}]}}\n"
+                    )
+                else:
+                    deps_section += f'{name_part} = "{version_str}"\n'
 
             # Create basic pyproject.toml content for Poetry
             pyproject_content = f"""[tool.poetry]

src/fastapi_fastkit/backend/project_builder/config_generator.py

@@ -488,7 +488,7 @@ def _generate_dockerfile(self) -> str:
         content.append("")
         content.append("# Run application")
         content.append(
-            "CMD ['uvicorn', 'src.main:app', '--host', '0.0.0.0', '--port', '8000']"
+            'CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]'
         )
         content.append("")
 

src/fastapi_fastkit/cli.py

@@ -43,9 +43,28 @@
     validate_email,
 )
 
+from . import __version__
+
 console = utils_console
 
-from . import __version__
+
+def _cleanup_failed_project(
+    project_dir: str, user_workspace: str, create_project_folder: bool
+) -> None:
+    """
+    Clean up a partially created project after an error.
+
+    Only deletes a freshly created project folder. When the project was deployed
+    in-place (create_project_folder=False), project_dir equals the user's workspace,
+    and removing it would destroy unrelated files, so no cleanup is performed.
+    """
+    if not create_project_folder:
+        return
+    if not project_dir or not os.path.exists(project_dir):
+        return
+    if os.path.abspath(project_dir) == os.path.abspath(user_workspace):
+        return
+    shutil.rmtree(project_dir, ignore_errors=True)
 
 
 @click.group()
@@ -483,18 +502,17 @@ def init(
             if testing_type != "None":
                 test_config_content = generator.generate_test_config()
                 if test_config_content:
-                    test_config_path = os.path.join(project_dir, "tests", "conftest.py")
-                    os.makedirs(os.path.dirname(test_config_path), exist_ok=True)
+                    test_config_path = os.path.join(project_dir, "pytest.ini")
                     with open(test_config_path, "w") as f:
                         f.write(test_config_content)
 
             # Generate Docker files if deployment selected
             deployment = config.get("deployment", [])
             if deployment and deployment != ["None"]:
                 generator.generate_docker_files()
-                print_success(f"Generated Docker deployment files")
+                print_success("Generated Docker deployment files")
 
-            print_success(f"Generated configuration files for selected stack")
+            print_success("Generated configuration files for selected stack")
 
             # Create virtual environment and install dependencies
             venv_path = create_venv_with_manager(project_dir, package_manager)
@@ -514,8 +532,9 @@ def init(
                 logger = get_logger()
                 logger.exception(f"Error during project creation in init: {str(e)}")
             print_error(f"Error during project creation: {str(e)}")
-            if os.path.exists(project_dir):
-                shutil.rmtree(project_dir, ignore_errors=True)
+            _cleanup_failed_project(
+                project_dir, settings.USER_WORKSPACE, create_project_folder
+            )
 
         return
 
@@ -662,8 +681,9 @@ def init(
             logger = get_logger()
             logger.exception(f"Error during project creation in init: {str(e)}")
         print_error(f"Error during project creation: {str(e)}")
-        if os.path.exists(project_dir):
-            shutil.rmtree(project_dir, ignore_errors=True)
+        _cleanup_failed_project(
+            project_dir, settings.USER_WORKSPACE, create_project_folder
+        )
 
 
 @fastkit_cli.command()
@@ -930,9 +950,9 @@ def runserver(
         logger.exception(f"FileNotFoundError when starting server: {e}")
         if venv_python:
             print_error(
-                f"Failed to run Python from the virtual environment. Make sure uvicorn is installed in the project's virtual environment."
+                "Failed to run Python from the virtual environment. Make sure uvicorn is installed in the project's virtual environment."
             )
         else:
             print_error(
-                f"uvicorn not found. Make sure it's installed in your system Python."
+                "uvicorn not found. Make sure it's installed in your system Python."
             )

src/fastapi_fastkit/core/settings.py

@@ -102,7 +102,7 @@ class FastkitConfig:
             "MySQL": ["pymysql", "aiomysql", "sqlalchemy", "alembic"],
             "MongoDB": ["motor", "beanie"],
             "Redis": ["redis[hiredis]", "aioredis"],
-            "SQLite": ["sqlalchemy", "alembic"],
+            "SQLite": ["sqlalchemy", "aiosqlite", "alembic"],
             "None": [],
         },
         "authentication": {

tests/test_backends/test_main.py

@@ -186,8 +186,7 @@ def test_inject_project_metadata(self) -> None:
         # given
         # Create setup.py file
         setup_py = self.project_path / "setup.py"
-        setup_py.write_text(
-            """
+        setup_py.write_text("""
 from setuptools import setup
 
 setup(
@@ -196,8 +195,7 @@ def test_inject_project_metadata(self) -> None:
     author_email="<author_email>",
     description="<description>",
 )
-"""
-        )
+""")
 
         # Create config file
         config_py = self.project_path / "config.py"
@@ -222,6 +220,30 @@ def test_inject_project_metadata(self) -> None:
         config_content = config_py.read_text()
         assert 'PROJECT_NAME = "test-project"' in config_content
 
+    def test_inject_project_metadata_replaces_placeholder_in_main(self) -> None:
+        """Main module placeholders (single-module template) must be substituted."""
+        # given
+        src_dir = self.project_path / "src"
+        src_dir.mkdir()
+        main_py = src_dir / "main.py"
+        main_py.write_text(
+            'from fastapi import FastAPI\n\napp = FastAPI(title="<project_name>")\n'
+        )
+
+        # when
+        inject_project_metadata(
+            str(self.project_path),
+            "my-single-module",
+            "Test Author",
+            "test@example.com",
+            "desc",
+        )
+
+        # then
+        main_content = main_py.read_text()
+        assert "<project_name>" not in main_content
+        assert 'title="my-single-module"' in main_content
+
     @patch("fastapi_fastkit.backend.main.find_template_core_modules")
     def test_inject_project_metadata_with_exception(
         self, mock_find_modules: MagicMock
@@ -248,8 +270,7 @@ def test_read_template_stack(self) -> None:
         template_path = Path(tempfile.mkdtemp())
         try:
             setup_py_tpl = template_path / "setup.py-tpl"
-            setup_py_tpl.write_text(
-                """
+            setup_py_tpl.write_text("""
 from setuptools import setup
 
 install_requires: list[str] = [
@@ -262,8 +283,7 @@ def test_read_template_stack(self) -> None:
     name="test",
     install_requires=install_requires,
 )
-"""
-            )
+""")
 
             # when
             result = read_template_stack(str(template_path))
@@ -393,16 +413,14 @@ def test_process_setup_file_success(self) -> None:
         """Test _process_setup_file function with successful processing."""
         # given
         setup_py = self.project_path / "setup.py"
-        setup_py.write_text(
-            """
+        setup_py.write_text("""
 setup(
     name="<project_name>",
     author="<author>",
     author_email="<author_email>",
     description="<description>",
 )
-"""
-        )
+""")
 
         # when
         _process_setup_file(

tests/test_backends/test_package_managers.py

@@ -912,6 +912,44 @@ def test_generate_dependency_file_error(self) -> None:
             with pytest.raises(BackendExceptions):
                 self.manager.generate_dependency_file(["fastapi"])
 
+    def test_generate_dependency_file_with_extras_is_valid_toml(self) -> None:
+        """Dependencies with extras must be emitted as inline tables, not bare keys."""
+        import tomllib
+
+        deps = [
+            "redis[hiredis]",
+            "python-jose[cryptography]==3.3.0",
+            "fastapi-users[sqlalchemy]",
+            "fastapi==0.104.1",
+            "uvicorn",
+        ]
+        self.manager.generate_dependency_file(
+            deps,
+            project_name="test-project",
+            author="Test Author",
+            author_email="test@example.com",
+            description="Test description",
+        )
+
+        pyproject_file = Path(self.temp_dir) / "pyproject.toml"
+        content = pyproject_file.read_text()
+
+        # Must parse as valid TOML - this is what previously broke poetry install.
+        parsed = tomllib.loads(content)
+        deps_table = parsed["tool"]["poetry"]["dependencies"]
+
+        assert deps_table["redis"] == {"version": "*", "extras": ["hiredis"]}
+        assert deps_table["python-jose"] == {
+            "version": "3.3.0",
+            "extras": ["cryptography"],
+        }
+        assert deps_table["fastapi-users"] == {
+            "version": "*",
+            "extras": ["sqlalchemy"],
+        }
+        assert deps_table["fastapi"] == "0.104.1"
+        assert deps_table["uvicorn"] == "*"
+
     @patch("subprocess.run")
     def test_add_dependency_success(self, mock_run: Mock) -> None:
         """Test successful dependency addition with Poetry."""

tests/test_backends/test_project_builder_config_generator.py

@@ -3,6 +3,10 @@
 #
 # @author bnbong bbbong9@gmail.com
 # --------------------------------------------------------------------------
+import json
+import tempfile
+from pathlib import Path
+
 import pytest
 
 from fastapi_fastkit.backend.project_builder.config_generator import (
@@ -332,6 +336,41 @@ def test_generate_test_config_coverage(self) -> None:
         assert "[coverage:run]" in content
 
 
+class TestGenerateDockerFiles:
+    """Test cases for generate_docker_files method."""
+
+    def test_generated_dockerfile_uses_exec_form_cmd(self) -> None:
+        """Dockerfile CMD must be JSON exec form, not shell form with single quotes."""
+        # given
+        with tempfile.TemporaryDirectory() as tmp:
+            config = {"deployment": ["Docker"]}
+            generator = DynamicConfigGenerator(config, tmp)
+
+            # when
+            generator.generate_docker_files()
+
+            # then
+            dockerfile = Path(tmp) / "Dockerfile"
+            assert dockerfile.exists()
+            content = dockerfile.read_text()
+
+            # Find the CMD line and validate it parses as JSON array (exec form)
+            cmd_lines = [
+                line for line in content.splitlines() if line.startswith("CMD ")
+            ]
+            assert len(cmd_lines) == 1
+            cmd_payload = cmd_lines[0][len("CMD ") :]
+
+            # Single quotes are Docker shell form; exec form requires double quotes.
+            assert "'" not in cmd_payload, (
+                "Generated Dockerfile CMD still uses single quotes (shell form): "
+                f"{cmd_payload!r}"
+            )
+            parsed = json.loads(cmd_payload)
+            assert parsed[0] == "uvicorn"
+            assert "src.main:app" in parsed
+
+
 class TestHelperMethods:
     """Test cases for helper methods."""