FastAPI-fastkit 1.3.0__tar.gz → 1.4.1__tar.gz

{fastapi_fastkit-1.3.0 → fastapi_fastkit-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: FastAPI-fastkit
-Version: 1.3.0
+Version: 1.4.1
 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
 
@@ -78,17 +82,27 @@ $ pip install FastAPI-fastkit
 ```console
 fastkit init [OPTIONS]
 ```
-- What it does: Scaffolds an empty FastAPI project, creates a virtual environment, installs dependencies
+> [!TIP]
+> Scaffolds an empty FastAPI project, creates a virtual environment, installs dependencies
+
 - 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
 ```console
 fastkit init --interactive
 ```
-- What it does: Guided step-by-step project setup with intelligent feature selection
+> [!TIP]
+> 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
@@ -98,23 +112,33 @@ 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 (varies by preset — see [the matrix](https://bnbong.github.io/FastAPI-fastkit/reference/preset-feature-matrix/) for details):
+- 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
 fastkit startdemo [TEMPLATE] [OPTIONS]
 ```
-- What it does: Creates a project from a template (e.g., `fastapi-default`) and installs dependencies
+> [!TIP]
+> Creates a project from a template (e.g., `fastapi-default`) and installs dependencies
+
 - 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`
 
 ### Add a new route
@@ -136,6 +160,25 @@ fastkit runserver [OPTIONS]
 fastkit list-templates
 ```
 
+Available templates:
+
+| Template | Description | Notes |
+|---|---|---|
+| [`fastapi-default`](src/fastapi_fastkit/fastapi_project_template/fastapi-default/README.md-tpl) | Simple FastAPI project with a classic layered layout | Good first choice |
+| [`fastapi-empty`](src/fastapi_fastkit/fastapi_project_template/fastapi-empty/README.md-tpl) | Minimal FastAPI template | Base for `minimal` preset |
+| [`fastapi-single-module`](src/fastapi_fastkit/fastapi_project_template/fastapi-single-module/README.md-tpl) | Single-file FastAPI app | Base for `single-module` preset |
+| [`fastapi-domain-starter`](src/fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/README.md-tpl) | Domain-oriented, pyproject-first starter for medium-sized APIs | Base for `domain-starter` preset |
+| [`fastapi-auth-jwt`](src/fastapi_fastkit/fastapi_project_template/fastapi-auth-jwt/README.md-tpl) | JWT authentication with refresh-token rotation, argon2 hashing and scopes | New in v1.4.0 |
+| [`fastapi-sqlmodel`](src/fastapi_fastkit/fastapi_project_template/fastapi-sqlmodel/README.md-tpl) | Async SQLModel + Alembic migrations + generic CRUD with pagination | New in v1.4.0 |
+| [`fastapi-llm-agent`](src/fastapi_fastkit/fastapi_project_template/fastapi-llm-agent/README.md-tpl) | Streaming Claude chat agent (SSE) with a tool-call loop | New in v1.4.0 |
+| [`fastapi-mcp`](src/fastapi_fastkit/fastapi_project_template/fastapi-mcp/README.md-tpl) | FastAPI app exposed as an MCP server | |
+| [`fastapi-psql-orm`](src/fastapi_fastkit/fastapi_project_template/fastapi-psql-orm/README.md-tpl) | Item management API with PostgreSQL, SQLModel, Alembic and docker-compose | Requires Docker |
+| [`fastapi-custom-response`](src/fastapi_fastkit/fastapi_project_template/fastapi-custom-response/README.md-tpl) | Item management API with a custom response envelope, error handling and pagination | |
+| [`fastapi-async-crud`](src/fastapi_fastkit/fastapi_project_template/fastapi-async-crud/README.md-tpl) | Async item management API | **Deprecated** — use `fastapi-sqlmodel` |
+| [`fastapi-dockerized`](src/fastapi_fastkit/fastapi_project_template/fastapi-dockerized/README.md-tpl) | Dockerized item management API | **Deprecated** — use `fastapi-default` with the Docker option in `init --interactive` |
+
+Deprecated templates still work but are no longer recommended starting points. See [Which starter should I choose?](https://bnbong.github.io/FastAPI-fastkit/user-guide/choosing-a-starter/) for a decision guide.
+
 ### Delete a project
 ```console
 fastkit deleteproject <project_name>

{fastapi_fastkit-1.3.0 → fastapi_fastkit-1.4.1}/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
 
@@ -55,17 +57,27 @@ $ pip install FastAPI-fastkit
 ```console
 fastkit init [OPTIONS]
 ```
-- What it does: Scaffolds an empty FastAPI project, creates a virtual environment, installs dependencies
+> [!TIP]
+> Scaffolds an empty FastAPI project, creates a virtual environment, installs dependencies
+
 - 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
 ```console
 fastkit init --interactive
 ```
-- What it does: Guided step-by-step project setup with intelligent feature selection
+> [!TIP]
+> 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
@@ -75,23 +87,33 @@ 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 (varies by preset — see [the matrix](https://bnbong.github.io/FastAPI-fastkit/reference/preset-feature-matrix/) for details):
+- 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
 fastkit startdemo [TEMPLATE] [OPTIONS]
 ```
-- What it does: Creates a project from a template (e.g., `fastapi-default`) and installs dependencies
+> [!TIP]
+> Creates a project from a template (e.g., `fastapi-default`) and installs dependencies
+
 - 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`
 
 ### Add a new route
@@ -113,6 +135,25 @@ fastkit runserver [OPTIONS]
 fastkit list-templates
 ```
 
+Available templates:
+
+| Template | Description | Notes |
+|---|---|---|
+| [`fastapi-default`](src/fastapi_fastkit/fastapi_project_template/fastapi-default/README.md-tpl) | Simple FastAPI project with a classic layered layout | Good first choice |
+| [`fastapi-empty`](src/fastapi_fastkit/fastapi_project_template/fastapi-empty/README.md-tpl) | Minimal FastAPI template | Base for `minimal` preset |
+| [`fastapi-single-module`](src/fastapi_fastkit/fastapi_project_template/fastapi-single-module/README.md-tpl) | Single-file FastAPI app | Base for `single-module` preset |
+| [`fastapi-domain-starter`](src/fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/README.md-tpl) | Domain-oriented, pyproject-first starter for medium-sized APIs | Base for `domain-starter` preset |
+| [`fastapi-auth-jwt`](src/fastapi_fastkit/fastapi_project_template/fastapi-auth-jwt/README.md-tpl) | JWT authentication with refresh-token rotation, argon2 hashing and scopes | New in v1.4.0 |
+| [`fastapi-sqlmodel`](src/fastapi_fastkit/fastapi_project_template/fastapi-sqlmodel/README.md-tpl) | Async SQLModel + Alembic migrations + generic CRUD with pagination | New in v1.4.0 |
+| [`fastapi-llm-agent`](src/fastapi_fastkit/fastapi_project_template/fastapi-llm-agent/README.md-tpl) | Streaming Claude chat agent (SSE) with a tool-call loop | New in v1.4.0 |
+| [`fastapi-mcp`](src/fastapi_fastkit/fastapi_project_template/fastapi-mcp/README.md-tpl) | FastAPI app exposed as an MCP server | |
+| [`fastapi-psql-orm`](src/fastapi_fastkit/fastapi_project_template/fastapi-psql-orm/README.md-tpl) | Item management API with PostgreSQL, SQLModel, Alembic and docker-compose | Requires Docker |
+| [`fastapi-custom-response`](src/fastapi_fastkit/fastapi_project_template/fastapi-custom-response/README.md-tpl) | Item management API with a custom response envelope, error handling and pagination | |
+| [`fastapi-async-crud`](src/fastapi_fastkit/fastapi_project_template/fastapi-async-crud/README.md-tpl) | Async item management API | **Deprecated** — use `fastapi-sqlmodel` |
+| [`fastapi-dockerized`](src/fastapi_fastkit/fastapi_project_template/fastapi-dockerized/README.md-tpl) | Dockerized item management API | **Deprecated** — use `fastapi-default` with the Docker option in `init --interactive` |
+
+Deprecated templates still work but are no longer recommended starting points. See [Which starter should I choose?](https://bnbong.github.io/FastAPI-fastkit/user-guide/choosing-a-starter/) for a decision guide.
+
 ### Delete a project
 ```console
 fastkit deleteproject <project_name>

{fastapi_fastkit-1.3.0 → fastapi_fastkit-1.4.1}/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.3.0"
+version = "1.4.1"
 
 [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]]
@@ -116,14 +128,15 @@ directory = "htmlcov"
 [dependency-groups]
 docs = [
     "mkdocs>=1.6.1",
-    "mkdocs-material>=9.6.15",
+    "mkdocs-material>=9.7.7",
     "mdx-include>=1.4.2",
     "mkdocs-static-i18n>=1.3.0",
     "pyyaml>=6.0.3",
     "types-PyYAML>=6.0.12.20250915",
     "pygments>=2.20.0",
     "requests>=2.33.0",
-    "pymdown-extensions>=10.17.2",
+    "idna>=3.15",
+    "pymdown-extensions>=11.0.1",
 ]
 translation = [
     "openai>=2.8.1",

fastapi_fastkit-1.4.1/src/fastapi_fastkit/__init__.py

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

fastapi_fastkit-1.4.1/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.1/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