[FEAT] enhance FastAPI-fastkit project templates and detection

- Updated project templates to include a standardized description marker "[FastAPI-fastkit templated]" in pyproject.toml files for better identification.
- Introduced a new section `[tool.fastapi-fastkit]` in pyproject.toml to indicate managed projects.
- Enhanced the `is_fastkit_project` function to detect FastAPI-fastkit projects using both the new TOML structure and legacy setup.py markers.
- Added comprehensive tests for the new detection logic, ensuring compatibility with existing templates and structures.
- Improved error handling and validation for project structure checks, particularly for templates with missing metadata files.
- Refactored tests to ensure clarity and maintainability, including checks for dependencies in pyproject.toml and legacy setup.py files.

Author: bnbong

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## v1.3.0 (Unreleased)
+
+### Maintenances
+
+- **Modernize template contract to be pyproject-first** (#42)
+  - Template inspection now accepts `pyproject.toml-tpl` (PEP 621) as the primary metadata file. A template passes structural validation as long as `tests/`, `README.md-tpl`, and **at least one** of `pyproject.toml-tpl` / `setup.py-tpl` are present. `requirements.txt-tpl` is no longer strictly required when `pyproject.toml-tpl` declares `[project].dependencies`.
+  - `_check_dependencies` consults every available source (`requirements.txt-tpl`, `pyproject.toml-tpl` `[project].dependencies`, `setup.py-tpl` `install_requires`) independently and passes if **any** one declares `fastapi`. A template with a stale `requirements.txt-tpl` is no longer rejected when its `pyproject.toml-tpl` is authoritative.
+  - `read_template_stack` gained a pyproject fallback between the existing `requirements.txt-tpl` and `setup.py-tpl` paths; legacy templates resolve dependencies exactly as before.
+  - Template authoring docs (`src/fastapi_fastkit/fastapi_project_template/README.md`, `docs/en/contributing/template-creation-guide.md`, `docs/en/reference/template-quality-assurance.md`) now describe required vs optional files under the pyproject-first contract.
+  - Added focused tests for the new rules (pyproject-only structural and dependency validation, setup.py-only legacy validation, pyproject fallback in `read_template_stack`, and `requirements.txt-tpl`-over-pyproject precedence).
+- **Pyproject-aware project identity detection** (follow-up to #42)
+  - `is_fastkit_project()` now recognises FastAPI-fastkit-managed projects from `pyproject.toml` in addition to legacy `setup.py`. Detection precedence: `[tool.fastapi-fastkit].managed = true` → `[project].description` contains the `[FastAPI-fastkit templated]` marker (case-insensitive) → `setup.py` contains `fastapi-fastkit` (case-insensitive). Keeps the pre-existing setup.py path working; the new pyproject paths prevent pyproject-only templates from being mistaken for unrelated FastAPI projects in the user's workspace.
+  - Canonical marker strings (`[FastAPI-fastkit templated]` and the `[tool.fastapi-fastkit]` table key `fastapi-fastkit`) are exported from `fastapi_fastkit.utils.main` as `FASTKIT_DESCRIPTION_MARKER` / `FASTKIT_TOOL_SECTION` so templates, metadata injection, and detection all reference the same strings.
+  - `_process_pyproject_file` idempotently ensures the description marker and `[tool.fastapi-fastkit]\nmanaged = true` section are present after placeholder replacement, providing a safety net when a template author forgets to include them.
+  - All 8 shipped `pyproject.toml-tpl` templates updated to carry `description = "[FastAPI-fastkit templated] <description>"` and a `[tool.fastapi-fastkit]` table with `managed = true`.
+
 ## v1.2.1 (2026-04-17)
 
 ### Fixes

docs/en/contributing/template-creation-guide.md

@@ -96,14 +96,29 @@ fastapi-{template-name}/
 │   ├── lint.sh-tpl             # Linting
 │   ├── run-server.sh-tpl       # Server execution
 │   └── test.sh-tpl             # Test execution
-├── requirements.txt-tpl         # ✅ Dependencies (required)
-├── setup.py-tpl                # ✅ Package setup (required)
+├── pyproject.toml-tpl           # ✅ Primary metadata (PEP 621, preferred)
+├── setup.py-tpl                # 🟡 Legacy metadata (accepted for back-compat)
+├── requirements.txt-tpl         # 🟡 Optional when pyproject declares deps
 ├── setup.cfg-tpl               # Development tools configuration
 ├── README.md-tpl               # ✅ Project documentation (required)
 ├── .env-tpl                    # Environment variables template
 └── .gitignore-tpl              # Git ignore file
 ```
 
+**Minimum required files.** A template must provide:
+
+- `tests/` directory
+- `README.md-tpl`
+- At least one metadata file: `pyproject.toml-tpl` (preferred, PEP 621) or
+  `setup.py-tpl` (legacy, still accepted)
+- A declaration of `fastapi` as a dependency in at least one of:
+  `pyproject.toml-tpl` `[project].dependencies`, `requirements.txt-tpl`, or
+  `setup.py-tpl` `install_requires`
+
+`requirements.txt-tpl` is no longer strictly required when `pyproject.toml-tpl`
+declares `[project].dependencies`. Modern templates SHOULD adopt
+`pyproject.toml-tpl` as their primary metadata file.
+
 ### File Writing Guide
 
 #### 1. Writing main.py-tpl
@@ -154,7 +169,58 @@ if __name__ == "__main__":
     uvicorn.run(app, host="0.0.0.0", port=8000)
 ```
 
-#### 2. Writing requirements.txt-tpl
+#### 2. Writing pyproject.toml-tpl (preferred)
+
+Modern templates should declare metadata and dependencies with a PEP 621
+`pyproject.toml-tpl`. At minimum the file must expose a `[project]` section with
+`name`, `version`, a `description`, and a `dependencies` list that includes
+`fastapi`. Templates must also carry two FastAPI-fastkit identity markers so
+`is_fastkit_project()` can tell generated projects apart from unrelated FastAPI
+projects in the user's workspace:
+
+- `[FastAPI-fastkit templated]` prefix in `description`
+- A dedicated `[tool.fastapi-fastkit]` table with `managed = true`
+
+Detection accepts either marker (matching is case-insensitive). Metadata
+injection will add both at project generation time if a template omits them,
+but authors should include them explicitly.
+
+```toml
+[project]
+name = "<project_name>"
+version = "0.1.0"
+description = "[FastAPI-fastkit templated] <description>"
+authors = [
+    {name = "<author>", email = "<author_email>"},
+]
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.34.0",
+    "pydantic>=2.10.0",
+    "pydantic-settings>=2.7.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "httpx>=0.28.0",
+]
+
+[tool.fastapi-fastkit]
+managed = true
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+```
+
+#### 3. Writing requirements.txt-tpl (optional)
+
+Optional when `pyproject.toml-tpl` declares `[project].dependencies`. Still
+useful for templates that prefer `pip`-only workflows.
 
 ```txt
 # FastAPI core dependencies (required)
@@ -183,7 +249,10 @@ isort==5.12.0
 mypy==1.7.1
 ```
 
-#### 3. Writing setup.py-tpl
+#### 4. Writing setup.py-tpl (legacy — optional when pyproject is present)
+
+Retained for legacy templates. New templates do not need this file if they
+ship `pyproject.toml-tpl`.
 
 ```python
 """
@@ -205,7 +274,7 @@ install_requires: list[str] = [
 setup(
     name="<project_name>",
     version="1.0.0",
-    description="[fastapi-fastkit templated] <description>",  # Required keyword
+    description="[FastAPI-fastkit templated] <description>",  # Identity marker used by is_fastkit_project()
     long_description=open("README.md").read(),
     long_description_content_type="text/markdown",
     author="<author>",
@@ -227,7 +296,7 @@ setup(
 )
 ```
 
-#### 4. Writing Test Files
+#### 5. Writing Test Files
 
 ```python
 # tests/test_items.py-tpl
@@ -299,9 +368,9 @@ The inspector automatically validates the following items:
 #### ✅ File Structure Validation
 
 - [ ] `tests/` directory exists
-- [ ] `requirements.txt-tpl` file exists
-- [ ] `setup.py-tpl` file exists
 - [ ] `README.md-tpl` file exists
+- [ ] At least one of `pyproject.toml-tpl` (preferred) or `setup.py-tpl`
+      (legacy) exists
 
 #### ✅ File Extension Validation
 
@@ -310,9 +379,10 @@ The inspector automatically validates the following items:
 
 #### ✅ Dependencies Validation
 
-- [ ] `requirements.txt-tpl` includes `fastapi`
-- [ ] `setup.py-tpl`'s `install_requires` includes `fastapi`
-- [ ] `setup.py-tpl`'s description includes `[fastapi-fastkit templated]`
+- [ ] `fastapi` is declared in at least one of:
+  - [ ] `pyproject.toml-tpl` under `[project].dependencies` (preferred)
+  - [ ] `requirements.txt-tpl`
+  - [ ] `setup.py-tpl` under `install_requires`
 
 #### ✅ FastAPI Implementation Validation
 

docs/en/reference/template-quality-assurance.md

@@ -188,14 +188,34 @@ For a template to pass inspection, it must meet these requirements:
 ### File Structure
 - Must contain a `src/` directory with Python source files
 - Python files must use `.py-tpl` extension
-- Must include a `requirements.txt-tpl` file
-- Must include a `setup.py-tpl` file
+- Must include a `tests/` directory and a `README.md-tpl` file
+- Must include **at least one** metadata file:
+  - `pyproject.toml-tpl` (preferred, PEP 621), or
+  - `setup.py-tpl` (legacy, still accepted)
+- `requirements.txt-tpl` is optional when `pyproject.toml-tpl` declares
+  `[project].dependencies`
 
 ### FastAPI Requirements
 - Must contain FastAPI app initialization
-- Must include proper dependency declarations
+- Must declare `fastapi` as a dependency in at least one of
+  `pyproject.toml-tpl` `[project].dependencies`, `requirements.txt-tpl`, or
+  `setup.py-tpl` `install_requires`
 - Must have valid Python syntax in all template files
 
+### Identity Markers
+Templates should carry FastAPI-fastkit identity markers so generated projects
+are distinguishable from unrelated FastAPI projects in the user's workspace:
+
+- `pyproject.toml-tpl` — both a `[FastAPI-fastkit templated]` prefix in
+  `description` and a `[tool.fastapi-fastkit]` table with `managed = true`.
+- `setup.py-tpl` — `[FastAPI-fastkit templated]` prefix in the `description`
+  argument to `setup()`.
+
+`is_fastkit_project()` accepts any one of these (pyproject takes precedence,
+setup.py is the legacy fallback; matching is case-insensitive). Metadata
+injection ensures the markers end up in generated projects even if a template
+forgets them.
+
 ### Quality Standards
 - All template files must be syntactically correct
 - Dependencies must be properly specified

scripts/inspect-changed-templates.py

@@ -8,12 +8,12 @@
 from pathlib import Path
 from typing import List, Set
 
+from fastapi_fastkit.backend.inspector import inspect_fastapi_template
+
 # Ensure src is importable
 PROJECT_ROOT = Path(__file__).parent.parent
 sys.path.insert(0, str(PROJECT_ROOT / "src"))
 
-from fastapi_fastkit.backend.inspector import inspect_fastapi_template
-
 TEMPLATE_DIR = PROJECT_ROOT / "src" / "fastapi_fastkit" / "fastapi_project_template"
 
 

scripts/inspect-templates.py

@@ -17,12 +17,12 @@
 from pathlib import Path
 from typing import Any, Dict, List
 
+from fastapi_fastkit.backend.inspector import inspect_fastapi_template
+
 # Add src to path to import fastapi_fastkit modules
 project_root = Path(__file__).parent.parent
 sys.path.insert(0, str(project_root / "src"))
 
-from fastapi_fastkit.backend.inspector import inspect_fastapi_template
-
 
 def get_templates_to_inspect(specific_templates: str = "") -> List[str]:
     """Get list of templates to inspect."""
@@ -119,7 +119,7 @@ def main() -> None:
     print(f"📋 Found {len(templates)} templates to inspect: {', '.join(templates)}")
     if args.verbose:
         print(f"🔧 Working directory: {os.getcwd()}")
-        print(f"📁 Template directory: src/fastapi_fastkit/fastapi_project_template/")
+        print("📁 Template directory: src/fastapi_fastkit/fastapi_project_template/")
     print("=" * 60)
 
     # Inspect each template

scripts/translate.py

@@ -302,7 +302,7 @@ def _translate_single_chunk(
     def translate(self, text: str, target_lang: str, source_lang: str = "en") -> str:
         """Translate text, automatically chunking if necessary."""
         try:
-            import openai
+            import openai  # noqa
         except ImportError:
             logger.error("OpenAI package not installed. Run: pip install openai")
             raise
@@ -316,7 +316,7 @@ def translate(self, text: str, target_lang: str, source_lang: str = "en") -> str
                 raise
 
             # If payload too large, split into chunks and translate each
-            logger.info(f"Document too large, splitting into chunks for translation...")
+            logger.info("Document too large, splitting into chunks for translation...")
             chunks = self._split_text_into_chunks(text)
             logger.info(f"Split into {len(chunks)} chunks")