FastAPI-fastkit 1.2.1__tar.gz → 1.4.0__tar.gz

{fastapi_fastkit-1.2.1 → fastapi_fastkit-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: FastAPI-fastkit
-Version: 1.2.1
+Version: 1.4.0
 Summary: Fast, easy-to-use starter kit for new users of Python and FastAPI
 Author-Email: bnbong <bbbong9@gmail.com>
 License: MIT
@@ -11,6 +11,7 @@ Project-URL: Changelog, https://bnbong.github.io/FastAPI-fastkit/changelog/
 Requires-Python: >=3.12
 Requires-Dist: click>=8.1.7
 Requires-Dist: rich>=13.9.2
+Requires-Dist: jinja2>=3.1
 Provides-Extra: dev
 Requires-Dist: pytest>=9.0.3; extra == "dev"
 Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
@@ -19,10 +20,11 @@ Requires-Dist: pre-commit>=4.0.1; extra == "dev"
 Requires-Dist: mypy>=1.12.0; extra == "dev"
 Requires-Dist: isort>=5.13.2; extra == "dev"
 Requires-Dist: pygments>=2.20.0; extra == "dev"
+Requires-Dist: types-pyyaml>=6.0.12.20260408; extra == "dev"
 Description-Content-Type: text/markdown
 
 <p align="center">
-    <img align="top" width="70%" src="https://bnbong.github.io/projects/img/fastkit_general_logo.png" alt="FastAPI-fastkit"/>
+    <img align="top" width="70%" src=".github/fastkit_general_logo.png" alt="FastAPI-fastkit"/>
 </p>
 <p align="center">
 <em><b>FastAPI-fastkit</b>: Fast, easy-to-use starter kit for new users of Python and FastAPI</em>
@@ -57,6 +59,8 @@ This project was inspired by the `SpringBoot initializer` & Python Django's `dja
 - **🔍 Automated template quality assurance** : Weekly automated testing ensures all templates remain functional and up-to-date
 - **🚀 Multiple project templates** : Choose from various pre-configured templates for different use cases (async CRUD, Docker, PostgreSQL, etc.)
 - **📦 Multiple package manager support** : Choose your preferred Python package manager (pip, uv, pdm, poetry) for dependency management
+- **🧾 Reproducible project configs** : Save an interactive session to a `.json` / `.toml` / `.yaml` file and replay it with `fastkit init --config`
+- **🏷️ Self-describing projects** : Every generated project records its template, preset, package manager, entrypoint and selected features in a `[tool.fastapi-fastkit]` block that `runserver` and `addroute` read back
 
 ## Installation
 
@@ -82,6 +86,12 @@ fastkit init [OPTIONS]
 - Key options:
   - `--project-name`, `--author`, `--author-email`, `--description`
   - `--package-manager` [pip|uv|pdm|poetry]
+  - `--config <path>`: create the project from a saved config file (`.json` / `.toml`, and `.yaml` when PyYAML is installed) with no prompts
+  - `--save-config <path>`: with `--interactive`, record the answers for later reuse
+  - `--dry-run`: print the files and packages that would be created, write nothing
+  - `--no-venv`: skip virtual environment creation (implies `--no-install`)
+  - `--no-install`: skip dependency installation
+  - `--yes` / `-y`: skip the "Overwrite these files?" confirmation when deploying in place
   - Stack selection: `minimal` | `standard` | `full` (interactive)
 
 ### Create a project with interactive mode
@@ -90,6 +100,7 @@ fastkit init --interactive
 ```
 - What it does: Guided step-by-step project setup with intelligent feature selection
 - Features:
+  - **Architecture preset**: `minimal` | `single-module` | `classic-layered` | `domain-starter` (default)
   - **Database selection**: PostgreSQL, MySQL, MongoDB, Redis, SQLite
   - **Authentication**: JWT, OAuth2, FastAPI-Users, Session-based
   - **Background tasks**: Celery, Dramatiq
@@ -97,14 +108,20 @@ fastkit init --interactive
   - **Monitoring**: Loguru, OpenTelemetry, Prometheus
   - **Testing**: Basic (pytest), Coverage, Advanced (with faker, factory-boy)
   - **Utilities**: CORS, Rate-Limiting, Pagination, WebSocket
+  - **Logging**: structured JSON logging with a request-id middleware
+  - **Migrations**: Alembic (async env, baseline revision)
+  - **Tooling**: ruff, pre-commit, GitHub Actions, devcontainer, Makefile (multi-select)
   - **Deployment**: Docker, docker-compose with auto-generated configs
   - **Package manager**: pip, uv, pdm, poetry
   - **Custom packages**: Add your own dependencies
-- Auto-generates:
-  - `main.py` with selected features integrated
-  - Database and authentication configuration files
-  - Docker deployment files (Dockerfile, docker-compose.yml)
+- Auto-generates (varies by preset — see [the matrix](https://bnbong.github.io/FastAPI-fastkit/reference/preset-feature-matrix/) for details):
+  - `main.py` regenerated from selected features for `minimal` / `single-module`; preserved as-shipped for `classic-layered` / `domain-starter`
+  - Database and authentication configuration files at preset-specific paths
+  - Docker deployment files (`Dockerfile`, `docker-compose.yml`) with the preset's correct uvicorn entrypoint
   - Test configuration (pytest with coverage)
+  - `/health` and `/ready` endpoints on every generated project
+  - Real working code — not just installed packages — for background tasks, caching, WebSocket, pagination, OpenTelemetry, OAuth2 and session-based auth
+  - `--dry-run` previews the exact file tree a run would create, including logging/migrations/tooling artifacts
 
 ### Create a project from a template
 ```console
@@ -114,8 +131,16 @@ fastkit startdemo [TEMPLATE] [OPTIONS]
 - Key options:
   - `--project-name`, `--author`, `--author-email`, `--description`
   - `--package-manager` [pip|uv|pdm|poetry]
+  - `--dry-run`, `--no-venv`, `--no-install`, `--yes`/`-y` — same meaning as on `init`
+  - Refuses to run if the target project directory already exists (`--dry-run` excepted)
 - Tip: List available templates with `fastkit list-templates`
 
+New in v1.4.0: `fastapi-auth-jwt` (JWT auth with refresh rotation),
+`fastapi-sqlmodel` (async SQLModel + Alembic + generic CRUD), and
+`fastapi-llm-agent` (streaming Claude agent with a tool loop).
+`fastapi-dockerized` and `fastapi-async-crud` are deprecated — they still
+work, but are no longer recommended starting points.
+
 ### Add a new route
 ```console
 fastkit addroute <project_name> <route_name>
@@ -144,9 +169,11 @@ fastkit deleteproject <project_name>
 
 For comprehensive guides and detailed usage instructions, visit our documentation:
 
+- 🧭 **[Which starter should I choose?](https://bnbong.github.io/FastAPI-fastkit/user-guide/choosing-a-starter/)** - Beginner decision guide for `startdemo` templates and interactive presets
 - 📚 **[User Guide](https://bnbong.github.io/FastAPI-fastkit/user-guide/quick-start/)** - Detailed installation and usage guides
 - 🎯 **[Tutorial](https://bnbong.github.io/FastAPI-fastkit/tutorial/getting-started/)** - Step-by-step tutorials for beginners
 - 📖 **[CLI Reference](https://bnbong.github.io/FastAPI-fastkit/user-guide/cli-reference/)** - Complete command reference
+- 🧱 **[Architecture Preset Matrix](https://bnbong.github.io/FastAPI-fastkit/reference/preset-feature-matrix/)** - Per-preset / per-feature contract for interactive generation
 - 🔍 **[Template Quality Assurance](https://bnbong.github.io/FastAPI-fastkit/reference/template-quality-assurance/)** - Automated testing and quality standards
 
 ## Contributing

{fastapi_fastkit-1.2.1 → fastapi_fastkit-1.4.0}/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-    <img align="top" width="70%" src="https://bnbong.github.io/projects/img/fastkit_general_logo.png" alt="FastAPI-fastkit"/>
+    <img align="top" width="70%" src=".github/fastkit_general_logo.png" alt="FastAPI-fastkit"/>
 </p>
 <p align="center">
 <em><b>FastAPI-fastkit</b>: Fast, easy-to-use starter kit for new users of Python and FastAPI</em>
@@ -34,6 +34,8 @@ This project was inspired by the `SpringBoot initializer` & Python Django's `dja
 - **🔍 Automated template quality assurance** : Weekly automated testing ensures all templates remain functional and up-to-date
 - **🚀 Multiple project templates** : Choose from various pre-configured templates for different use cases (async CRUD, Docker, PostgreSQL, etc.)
 - **📦 Multiple package manager support** : Choose your preferred Python package manager (pip, uv, pdm, poetry) for dependency management
+- **🧾 Reproducible project configs** : Save an interactive session to a `.json` / `.toml` / `.yaml` file and replay it with `fastkit init --config`
+- **🏷️ Self-describing projects** : Every generated project records its template, preset, package manager, entrypoint and selected features in a `[tool.fastapi-fastkit]` block that `runserver` and `addroute` read back
 
 ## Installation
 
@@ -59,6 +61,12 @@ fastkit init [OPTIONS]
 - Key options:
   - `--project-name`, `--author`, `--author-email`, `--description`
   - `--package-manager` [pip|uv|pdm|poetry]
+  - `--config <path>`: create the project from a saved config file (`.json` / `.toml`, and `.yaml` when PyYAML is installed) with no prompts
+  - `--save-config <path>`: with `--interactive`, record the answers for later reuse
+  - `--dry-run`: print the files and packages that would be created, write nothing
+  - `--no-venv`: skip virtual environment creation (implies `--no-install`)
+  - `--no-install`: skip dependency installation
+  - `--yes` / `-y`: skip the "Overwrite these files?" confirmation when deploying in place
   - Stack selection: `minimal` | `standard` | `full` (interactive)
 
 ### Create a project with interactive mode
@@ -67,6 +75,7 @@ fastkit init --interactive
 ```
 - What it does: Guided step-by-step project setup with intelligent feature selection
 - Features:
+  - **Architecture preset**: `minimal` | `single-module` | `classic-layered` | `domain-starter` (default)
   - **Database selection**: PostgreSQL, MySQL, MongoDB, Redis, SQLite
   - **Authentication**: JWT, OAuth2, FastAPI-Users, Session-based
   - **Background tasks**: Celery, Dramatiq
@@ -74,14 +83,20 @@ fastkit init --interactive
   - **Monitoring**: Loguru, OpenTelemetry, Prometheus
   - **Testing**: Basic (pytest), Coverage, Advanced (with faker, factory-boy)
   - **Utilities**: CORS, Rate-Limiting, Pagination, WebSocket
+  - **Logging**: structured JSON logging with a request-id middleware
+  - **Migrations**: Alembic (async env, baseline revision)
+  - **Tooling**: ruff, pre-commit, GitHub Actions, devcontainer, Makefile (multi-select)
   - **Deployment**: Docker, docker-compose with auto-generated configs
   - **Package manager**: pip, uv, pdm, poetry
   - **Custom packages**: Add your own dependencies
-- Auto-generates:
-  - `main.py` with selected features integrated
-  - Database and authentication configuration files
-  - Docker deployment files (Dockerfile, docker-compose.yml)
+- Auto-generates (varies by preset — see [the matrix](https://bnbong.github.io/FastAPI-fastkit/reference/preset-feature-matrix/) for details):
+  - `main.py` regenerated from selected features for `minimal` / `single-module`; preserved as-shipped for `classic-layered` / `domain-starter`
+  - Database and authentication configuration files at preset-specific paths
+  - Docker deployment files (`Dockerfile`, `docker-compose.yml`) with the preset's correct uvicorn entrypoint
   - Test configuration (pytest with coverage)
+  - `/health` and `/ready` endpoints on every generated project
+  - Real working code — not just installed packages — for background tasks, caching, WebSocket, pagination, OpenTelemetry, OAuth2 and session-based auth
+  - `--dry-run` previews the exact file tree a run would create, including logging/migrations/tooling artifacts
 
 ### Create a project from a template
 ```console
@@ -91,8 +106,16 @@ fastkit startdemo [TEMPLATE] [OPTIONS]
 - Key options:
   - `--project-name`, `--author`, `--author-email`, `--description`
   - `--package-manager` [pip|uv|pdm|poetry]
+  - `--dry-run`, `--no-venv`, `--no-install`, `--yes`/`-y` — same meaning as on `init`
+  - Refuses to run if the target project directory already exists (`--dry-run` excepted)
 - Tip: List available templates with `fastkit list-templates`
 
+New in v1.4.0: `fastapi-auth-jwt` (JWT auth with refresh rotation),
+`fastapi-sqlmodel` (async SQLModel + Alembic + generic CRUD), and
+`fastapi-llm-agent` (streaming Claude agent with a tool loop).
+`fastapi-dockerized` and `fastapi-async-crud` are deprecated — they still
+work, but are no longer recommended starting points.
+
 ### Add a new route
 ```console
 fastkit addroute <project_name> <route_name>
@@ -121,9 +144,11 @@ fastkit deleteproject <project_name>
 
 For comprehensive guides and detailed usage instructions, visit our documentation:
 
+- 🧭 **[Which starter should I choose?](https://bnbong.github.io/FastAPI-fastkit/user-guide/choosing-a-starter/)** - Beginner decision guide for `startdemo` templates and interactive presets
 - 📚 **[User Guide](https://bnbong.github.io/FastAPI-fastkit/user-guide/quick-start/)** - Detailed installation and usage guides
 - 🎯 **[Tutorial](https://bnbong.github.io/FastAPI-fastkit/tutorial/getting-started/)** - Step-by-step tutorials for beginners
 - 📖 **[CLI Reference](https://bnbong.github.io/FastAPI-fastkit/user-guide/cli-reference/)** - Complete command reference
+- 🧱 **[Architecture Preset Matrix](https://bnbong.github.io/FastAPI-fastkit/reference/preset-feature-matrix/)** - Per-preset / per-feature contract for interactive generation
 - 🔍 **[Template Quality Assurance](https://bnbong.github.io/FastAPI-fastkit/reference/template-quality-assurance/)** - Automated testing and quality standards
 
 ## Contributing

{fastapi_fastkit-1.2.1 → fastapi_fastkit-1.4.0}/pyproject.toml

@@ -8,10 +8,11 @@ authors = [
 dependencies = [
     "click>=8.1.7",
     "rich>=13.9.2",
+    "jinja2>=3.1",
 ]
 requires-python = ">=3.12"
 readme = "README.md"
-version = "1.2.1"
+version = "1.4.0"
 
 [project.license]
 text = "MIT"
@@ -31,6 +32,7 @@ dev = [
     "mypy>=1.12.0",
     "isort>=5.13.2",
     "pygments>=2.20.0",
+    "types-pyyaml>=6.0.12.20260408",
 ]
 
 [project.scripts]
@@ -52,11 +54,21 @@ addopts = [
     "--strict-config",
     "--disable-warnings",
 ]
+markers = [
+    "extended: slower end-to-end coverage, excluded from the fast feedback loop",
+    "slow: tests that shell out to real package managers or network services",
+]
+
+[tool.black]
+target-version = [
+    "py312",
+]
 
 [tool.isort]
 profile = "black"
 
 [tool.mypy]
+python_version = "3.12"
 strict = true
 
 [[tool.mypy.overrides]]

fastapi_fastkit-1.4.0/src/fastapi_fastkit/__init__.py

@@ -0,0 +1 @@
+__version__ = 'v1.4.0'

fastapi_fastkit-1.4.0/src/fastapi_fastkit/backend/inspection/__init__.py

@@ -0,0 +1,26 @@
+# --------------------------------------------------------------------------
+# Template inspection package.
+#
+# ``TemplateInspector`` generates a throwaway project from a template and runs
+# the checks defined in the sibling modules against it:
+#
+# - ``checks``      : structure, extensions, dependencies, implementation, tests
+# - ``consistency`` : Python-version pins and dependency drift
+# - ``lint``        : compileall (required) and mypy (opt-in)
+# - ``smoke``       : boots the generated app and probes /docs and /health
+# - ``strategies``  : how the template's own test suite is executed
+# - ``docker``      : Docker Compose orchestration
+# - ``freshness``   : PyPI version-lag warnings
+# - ``report``      : report construction and printing
+#
+# @author bnbong
+# --------------------------------------------------------------------------
+from .context import InspectionContext, InspectionOptions
+from .core import TemplateInspector, inspect_fastapi_template
+
+__all__ = [
+    "InspectionContext",
+    "InspectionOptions",
+    "TemplateInspector",
+    "inspect_fastapi_template",
+]

fastapi_fastkit-1.4.0/src/fastapi_fastkit/backend/inspection/checks.py

@@ -0,0 +1,349 @@
+# --------------------------------------------------------------------------
+# Static template checks: structure, file extensions, declared dependencies,
+# FastAPI implementation and the mandatory test suite.
+#
+# Every function takes an ``InspectionContext`` and returns ``True`` when the
+# check passes, appending a descriptive message to ``ctx.errors`` otherwise.
+#
+# @author bnbong
+# --------------------------------------------------------------------------
+import ast
+import os
+import tomllib
+from pathlib import Path
+from typing import List, Optional, Set, Tuple
+
+from fastapi_fastkit.backend.main import (
+    _parse_setup_dependencies,
+    find_template_core_modules,
+)
+from fastapi_fastkit.backend.package_managers.poetry_manager import (
+    _parse_pip_requirement,
+)
+from fastapi_fastkit.utils.logging import debug_log
+
+from .context import InspectionContext
+
+ALWAYS_REQUIRED_PATHS = ["tests", "README.md-tpl"]
+METADATA_CANDIDATES = ["pyproject.toml-tpl", "setup.py-tpl"]
+
+
+def extract_pyproject_dependency_names(
+    pyproject_path: Path,
+) -> Tuple[Set[str], Optional[str]]:
+    """Parse a pyproject file and return (lowercased dep names, error).
+
+    ``error`` is ``None`` on success. Returns an empty set with a descriptive
+    error string when the file is unreadable or malformed.
+    """
+    try:
+        with open(pyproject_path, "rb") as f:
+            data = tomllib.load(f)
+    except (OSError, tomllib.TOMLDecodeError, UnicodeDecodeError) as e:
+        return set(), f"Invalid pyproject.toml-tpl: {e}"
+
+    project = data.get("project", {})
+    raw_deps = project.get("dependencies", []) or []
+    if not isinstance(raw_deps, list):
+        return set(), "pyproject.toml-tpl [project].dependencies must be a list"
+
+    names: Set[str] = set()
+    for dep in raw_deps:
+        if not isinstance(dep, str) or not dep.strip():
+            continue
+        name = _parse_pip_requirement(dep)[0]
+        if name:
+            names.add(name.lower())
+    return names, None
+
+
+def parse_requirements_names(requirements_path: Path) -> Set[str]:
+    """Return the lowercased package names declared in a requirements file."""
+    with open(requirements_path, encoding="utf-8") as f:
+        lines = f.read().splitlines()
+    return {
+        _parse_pip_requirement(line)[0].lower()
+        for line in lines
+        if line.strip() and not line.strip().startswith("#")
+    }
+
+
+def check_file_structure(ctx: InspectionContext) -> bool:
+    """Check the required file and directory structure.
+
+    Modern templates may ship ``pyproject.toml-tpl`` as the primary metadata
+    file; ``setup.py-tpl`` remains accepted for backward compatibility.
+    A template must provide at least one of the two. ``requirements.txt-tpl``
+    is no longer strictly required when ``pyproject.toml-tpl`` declares
+    ``[project].dependencies``.
+    """
+    missing_required = [
+        path
+        for path in ALWAYS_REQUIRED_PATHS
+        if not (ctx.template_path / path).exists()
+    ]
+    has_metadata = any(
+        (ctx.template_path / name).exists() for name in METADATA_CANDIDATES
+    )
+
+    for path in missing_required:
+        ctx.add_error(f"Missing required path: {path}")
+    if not has_metadata:
+        ctx.add_error(
+            "Missing metadata file: expected pyproject.toml-tpl "
+            "(preferred) or setup.py-tpl"
+        )
+
+    if missing_required or not has_metadata:
+        return False
+
+    debug_log("File structure check passed", "info")
+    return True
+
+
+def check_file_extensions(ctx: InspectionContext) -> bool:
+    """Check all Python files in the template carry the .py-tpl extension."""
+    for path in ctx.template_path.rglob("*"):
+        if path.is_file() and path.suffix == ".py":
+            ctx.add_error(f"Found .py file instead of .py-tpl: {path}")
+            return False
+
+    debug_log("File extension check passed", "info")
+    return True
+
+
+def check_dependencies(ctx: InspectionContext) -> bool:
+    """Check that FastAPI is declared in at least one supported source.
+
+    All three metadata sources are consulted independently:
+
+    - ``requirements.txt-tpl``
+    - ``pyproject.toml-tpl`` ``[project].dependencies``
+    - ``setup.py-tpl`` ``install_requires``
+
+    The check passes if *any* source declares ``fastapi``, so a template
+    with a stale ``requirements.txt-tpl`` still passes when
+    ``pyproject.toml-tpl`` is authoritative.
+    """
+    req_path = ctx.template_path / "requirements.txt-tpl"
+    pyproject_path = ctx.template_path / "pyproject.toml-tpl"
+    setup_path = ctx.template_path / "setup.py-tpl"
+
+    sources_checked: List[str] = []
+    fastapi_declared = False
+
+    if req_path.exists():
+        sources_checked.append("requirements.txt-tpl")
+        try:
+            package_names = parse_requirements_names(req_path)
+        except (OSError, UnicodeDecodeError) as e:
+            ctx.add_error(f"Error reading requirements.txt-tpl: {e}")
+            return False
+        debug_log(
+            f"requirements.txt-tpl dependencies: {sorted(package_names)}", "debug"
+        )
+        fastapi_declared = fastapi_declared or "fastapi" in package_names
+
+    if pyproject_path.exists():
+        sources_checked.append("pyproject.toml-tpl")
+        package_names, parse_error = extract_pyproject_dependency_names(pyproject_path)
+        if parse_error is not None:
+            ctx.add_error(parse_error)
+            return False
+        debug_log(f"pyproject.toml-tpl dependencies: {sorted(package_names)}", "debug")
+        fastapi_declared = fastapi_declared or "fastapi" in package_names
+
+    if setup_path.exists():
+        sources_checked.append("setup.py-tpl")
+        try:
+            with open(setup_path, encoding="utf-8") as f:
+                content = f.read()
+        except (OSError, UnicodeDecodeError) as e:
+            ctx.add_error(f"Error reading setup.py-tpl: {e}")
+            return False
+        package_names = {
+            _parse_pip_requirement(dep)[0].lower()
+            for dep in _parse_setup_dependencies(content)
+            if dep
+        }
+        debug_log(f"setup.py-tpl dependencies: {sorted(package_names)}", "debug")
+        fastapi_declared = fastapi_declared or "fastapi" in package_names
+
+    if not sources_checked:
+        ctx.add_error(
+            "No dependency source found: expected one of requirements.txt-tpl, "
+            "pyproject.toml-tpl, or setup.py-tpl"
+        )
+        return False
+
+    if not fastapi_declared:
+        ctx.add_error(
+            "FastAPI dependency not found in any source ("
+            + ", ".join(sources_checked)
+            + ")"
+        )
+        return False
+
+    debug_log(
+        f"Dependencies check passed (sources: {', '.join(sources_checked)})", "info"
+    )
+    return True
+
+
+def _module_defines_fastapi_app(source: str) -> bool:
+    """Return True when ``source`` assigns a ``FastAPI(...)`` instance."""
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return False
+
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.Assign, ast.AnnAssign)):
+            continue
+        value = node.value
+        if not isinstance(value, ast.Call):
+            continue
+        func = value.func
+        name = ""
+        if isinstance(func, ast.Name):
+            name = func.id
+        elif isinstance(func, ast.Attribute):
+            name = func.attr
+        if name == "FastAPI":
+            return True
+    return False
+
+
+def check_fastapi_implementation(ctx: InspectionContext) -> bool:
+    """Check the generated project really instantiates a FastAPI application.
+
+    This is a static (AST) guard so a broken main module is reported before
+    the far more expensive smoke test boots a server.
+    """
+    try:
+        core_modules = find_template_core_modules(ctx.temp_dir)
+        debug_log(f"Found core modules: {core_modules}", "debug")
+
+        if not core_modules["main"]:
+            ctx.add_error("main.py not found in template")
+            return False
+
+        with open(core_modules["main"], encoding="utf-8") as f:
+            content = f.read()
+    except (OSError, UnicodeDecodeError) as e:
+        ctx.add_error(f"Error checking FastAPI implementation: {e}")
+        return False
+
+    if not _module_defines_fastapi_app(content):
+        ctx.add_error("FastAPI app creation not found in main.py")
+        debug_log(f"main.py content preview: {content[:200]}...", "debug")
+        return False
+
+    debug_log("FastAPI implementation check passed", "info")
+    return True
+
+
+def check_tests_present(ctx: InspectionContext) -> bool:
+    """A template must ship at least one test module.
+
+    Previously a missing ``tests/`` directory only produced a warning; an
+    untested template is now a hard failure.
+    """
+    tests_dir = ctx.template_path / "tests"
+    if not tests_dir.is_dir():
+        ctx.add_error("Missing required path: tests (templates must ship tests)")
+        return False
+
+    test_files = [
+        path
+        for path in tests_dir.rglob("*")
+        if path.is_file()
+        and path.name.startswith("test_")
+        and path.name.endswith((".py-tpl", ".py"))
+    ]
+    if not test_files:
+        ctx.add_error(
+            "No test module found under tests/: at least one test_*.py-tpl file "
+            "is required"
+        )
+        return False
+
+    debug_log(f"Test suite check passed ({len(test_files)} test files)", "info")
+    return True
+
+
+def check_no_junk_files(ctx: InspectionContext) -> bool:
+    """Reject OS/editor artifacts and build leftovers committed to a template."""
+    junk_names = {".DS_Store", "Thumbs.db", "desktop.ini", ".AppleDouble"}
+    junk_dirs = {"__pycache__", ".pytest_cache", ".mypy_cache", ".venv"}
+    found: List[str] = []
+
+    for path in ctx.template_path.rglob("*"):
+        rel = path.relative_to(ctx.template_path)
+        if path.is_dir():
+            if path.name in junk_dirs:
+                found.append(str(rel))
+        elif path.name in junk_names or path.suffix in {".pyc", ".pyo"}:
+            found.append(str(rel))
+
+    if found:
+        for item in sorted(found):
+            ctx.add_error(f"Junk file committed to template: {item}")
+        return False
+
+    debug_log("Junk file check passed", "info")
+    return True
+
+
+def check_no_placeholder_residue(ctx: InspectionContext) -> bool:
+    """Every ``<placeholder>`` must be substituted during project generation.
+
+    The inspection generates a real project from the template (copy +
+    metadata injection), so any surviving placeholder token means the
+    template declares a variable the generator does not know how to fill.
+    """
+    placeholders = [
+        "<project_name>",
+        "<author>",
+        "<author_email>",
+        "<description>",
+    ]
+    text_suffixes = {
+        ".py",
+        ".toml",
+        ".cfg",
+        ".txt",
+        ".md",
+        ".yml",
+        ".yaml",
+        ".json",
+        ".sh",
+        ".env",
+        ".ini",
+    }
+    residue: List[str] = []
+
+    for root, dirs, files in os.walk(ctx.temp_dir):
+        dirs[:] = [d for d in dirs if d not in {".venv", "venv", "__pycache__", ".git"}]
+        for file_name in files:
+            file_path = os.path.join(root, file_name)
+            suffix = Path(file_name).suffix
+            if suffix and suffix not in text_suffixes:
+                continue
+            try:
+                with open(file_path, encoding="utf-8") as f:
+                    content = f.read()
+            except (OSError, UnicodeDecodeError):
+                continue
+            hits = [token for token in placeholders if token in content]
+            if hits:
+                rel = os.path.relpath(file_path, ctx.temp_dir)
+                residue.append(f"{rel}: {', '.join(hits)}")
+
+    if residue:
+        for item in sorted(residue):
+            ctx.add_error(f"Unsubstituted placeholder in generated project: {item}")
+        return False
+
+    debug_log("Placeholder substitution check passed", "info")
+    return True