diff --git a/.github/workflows/template-pr-inspection.yml b/.github/workflows/template-pr-inspection.yml
new file mode 100644
index 0000000..3b7e192
--- /dev/null
+++ b/.github/workflows/template-pr-inspection.yml
@@ -0,0 +1,104 @@
+name: Template PR Inspection
+
+on:
+ pull_request:
+ paths:
+ - 'src/fastapi_fastkit/fastapi_project_template/**'
+ types:
+ - opened
+ - synchronize
+
+permissions:
+ contents: read
+ pull-requests: write
+
+jobs:
+ inspect-changed-templates:
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+ with:
+ fetch-depth: 0 # Fetch all history for git diff
+
+ - name: Set up Python
+ uses: actions/setup-python@v4
+ with:
+ python-version: "3.12"
+
+ - name: Setup PDM
+ uses: pdm-project/setup-pdm@v4
+
+ - name: Install dependencies
+ run: pdm install -G dev
+
+ - name: Setup UV
+ uses: astral-sh/setup-uv@v7
+
+ - name: Verify Docker and Compose
+ run: |
+ docker --version
+ docker compose version
+
+ - name: Inspect changed templates
+ run: pdm run python scripts/inspect-changed-templates.py
+
+ - name: Create or Update PR Comment
+ if: always()
+ uses: actions/github-script@v7
+ with:
+ script: |
+ const marker = '';
+ const success = '${{ job.status }}' === 'success';
+
+ const successBody = `${marker}
+ ✅ **Template Inspection Passed**
+
+ All changed templates have been validated successfully.
+
+ ---
+ *Last updated: ${new Date().toISOString()}*`;
+
+ const failureBody = `${marker}
+ ❌ **Template Inspection Failed**
+
+ Please check the workflow logs for details on what needs to be fixed.
+
+ [View Logs](${context.payload.repository.html_url}/actions/runs/${context.runId})
+
+ ---
+ *Last updated: ${new Date().toISOString()}*`;
+
+ const body = success ? successBody : failureBody;
+
+ // Find existing bot comment
+ const { data: comments } = await github.rest.issues.listComments({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ issue_number: context.issue.number
+ });
+
+ const botComment = comments.find(comment =>
+ comment.body.includes(marker)
+ );
+
+ if (botComment) {
+ // Update existing comment
+ await github.rest.issues.updateComment({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ comment_id: botComment.id,
+ body: body
+ });
+ console.log('Updated existing comment');
+ } else {
+ // Create new comment
+ await github.rest.issues.createComment({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ issue_number: context.issue.number,
+ body: body
+ });
+ console.log('Created new comment');
+ }
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 1878a45..d07939e 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,10 +1,8 @@
# See https://pre-commit.com for more information
# See https://pre-commit.com/hooks.html for more hooks
-default_language_version:
- python: python3.12
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
- rev: v3.2.0
+ rev: v6.0.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
@@ -15,29 +13,48 @@ repos:
hooks:
- id: format
name: format
- entry: bash scripts/format.sh
- language: system
+ entry: black --config pyproject.toml --check .
+ language: python
+ types: [python]
+ additional_dependencies: ['black>=24.10.0']
+ pass_filenames: false
+
+ - id: isort-check
+ name: isort check
+ entry: isort --sp pyproject.toml --check-only --diff .
+ language: python
+ types: [python]
+ additional_dependencies: ['isort>=5.13.2']
pass_filenames: false
- - id: lint
- name: lint
- entry: bash scripts/lint.sh
- language: system
+ - id: isort-fix
+ name: isort fix
+ entry: isort --sp pyproject.toml .
+ language: python
+ types: [python]
+ additional_dependencies: ['isort>=5.13.2']
pass_filenames: false
- - id: coverage-test
- name: coverage test
- entry: bash scripts/coverage-report.sh
- language: system
+ - id: black-fix
+ name: black fix
+ entry: black --config pyproject.toml .
+ language: python
types: [python]
+ additional_dependencies: ['black>=24.10.0']
pass_filenames: false
- - id: inspect-templates
- name: inspect changed fastapi templates
- entry: python scripts/inspect-changed-templates.py
- language: system
+ - id: mypy
+ name: mypy
+ entry: mypy --config-file pyproject.toml src
+ language: python
+ types: [python]
+ additional_dependencies:
+ - mypy>=1.12.0
+ - rich>=13.9.2
+ - click>=8.1.7
+ - pyyaml>=6.0.0
+ - types-PyYAML>=6.0.12
pass_filenames: false
- stages: [commit]
ci:
autofix_commit_msg: 🎨 [pre-commit.ci] Auto format from pre-commit.com hooks
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1228c85..be9d12c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -290,6 +290,16 @@ template-name/
FastAPI-fastkit includes **automated template testing** that provides comprehensive validation:
+#### ✅ CI/CD Template Inspection
+
+When you submit a PR that modifies template files, the **Template PR Inspection** workflow automatically runs:
+
+- 🔍 **Automatic Trigger**: Runs when files in `src/fastapi_fastkit/fastapi_project_template/` are modified
+- ✅ **Validation**: Inspects changed templates using `inspect-changed-templates.py`
+- 💬 **PR Feedback**: Posts success/failure comments directly on your PR
+
+Additionally, a **Weekly Template Inspection** runs every Wednesday to validate all templates.
+
#### ✅ Automatic Template Testing
**Zero Configuration Required:**
diff --git a/docs/en/contributing/code-guidelines.md b/docs/en/contributing/code-guidelines.md
index 9ec1de1..30e8f62 100644
--- a/docs/en/contributing/code-guidelines.md
+++ b/docs/en/contributing/code-guidelines.md
@@ -645,27 +645,68 @@ We use pre-commit hooks to enforce standards:
```yaml
# .pre-commit-config.yaml
repos:
- - repo: https://github.com/psf/black
- rev: 23.1.0
+- repo: https://github.com/pre-commit/pre-commit-hooks
+ rev: v6.0.0
hooks:
- - id: black
+ - id: trailing-whitespace
+ - id: end-of-file-fixer
+ - id: check-yaml
+ - id: check-toml
- - repo: https://github.com/pycqa/isort
- rev: 5.12.0
+- repo: local
hooks:
- - id: isort
-
- - repo: https://github.com/pycqa/flake8
- rev: 6.0.0
- hooks:
- - id: flake8
-
- - repo: https://github.com/pre-commit/mirrors-mypy
- rev: v1.0.1
- hooks:
- - id: mypy
+ - id: format
+ name: format
+ entry: black --config pyproject.toml --check .
+ language: python
+ types: [python]
+ additional_dependencies: ['black>=24.10.0']
+ pass_filenames: false
+
+ - id: isort-check
+ name: isort check
+ entry: isort --sp pyproject.toml --check-only --diff .
+ language: python
+ types: [python]
+ additional_dependencies: ['isort>=5.13.2']
+ pass_filenames: false
+
+ - id: isort-fix
+ name: isort fix
+ entry: isort --sp pyproject.toml .
+ language: python
+ types: [python]
+ additional_dependencies: ['isort>=5.13.2']
+ pass_filenames: false
+
+ - id: black-fix
+ name: black fix
+ entry: black --config pyproject.toml .
+ language: python
+ types: [python]
+ additional_dependencies: ['black>=24.10.0']
+ pass_filenames: false
+
+ - id: mypy
+ name: mypy
+ entry: mypy --config-file pyproject.toml src
+ language: python
+ types: [python]
+ additional_dependencies:
+ - mypy>=1.12.0
+ - rich>=13.9.2
+ - click>=8.1.7
+ - pyyaml>=6.0.0
+ - types-PyYAML>=6.0.12
+ pass_filenames: false
+
+ci:
+ autofix_commit_msg: 🎨 [pre-commit.ci] Auto format from pre-commit.com hooks
+ autoupdate_commit_msg: ⬆ [pre-commit.ci] pre-commit autoupdate
```
+> **Note:** Pre-commit hooks use isolated Python environments (`language: python`).
+
### IDE Configuration
Recommended VS Code settings:
@@ -673,7 +714,6 @@ Recommended VS Code settings:
```json
{
"python.linting.enabled": true,
- "python.linting.flake8Enabled": true,
"python.linting.mypyEnabled": true,
"python.formatting.provider": "black",
"python.sortImports.path": "isort",
diff --git a/docs/en/contributing/development-setup.md b/docs/en/contributing/development-setup.md
index ec02e86..672e3bf 100644
--- a/docs/en/contributing/development-setup.md
+++ b/docs/en/contributing/development-setup.md
@@ -31,11 +31,12 @@ Installing pre-commit hooks...
This single command:
-- Creates a virtual environment
-- Installs all dependencies
+- Installs the package in editable mode with dev dependencies
- Sets up pre-commit hooks
- Configures development tools
+> **Note:** You should create and activate a virtual environment before running this command.
+
## Manual Setup
If you prefer manual setup or the Makefile doesn't work on your system:
@@ -139,17 +140,6 @@ Fixing import order in src/main.py
### Code Linting
-**flake8** - Style guide enforcement:
-
-
-
-```console
-$ flake8 src/ tests/
-src/main.py:45:80: E501 line too long (82 > 79 characters)
-```
-
-
-
**mypy** - Type checking:
@@ -171,6 +161,8 @@ The project Makefile provides convenient commands for common development tasks:
|---------|-------------|
| `make install` | Install package in production mode |
| `make install-dev` | Install package with development dependencies |
+| `make install-test` | Install package for testing (uninstall + reinstall) |
+| `make uninstall` | Uninstall the package |
| `make clean` | Clean build artifacts and cache files |
### Code Quality Commands
@@ -178,29 +170,32 @@ The project Makefile provides convenient commands for common development tasks:
| Command | Description |
|---------|-------------|
| `make format` | Format code with black and isort |
-| `make lint` | Run flake8 linting |
-| `make type-check` | Run mypy type checking |
-| `make security` | Run bandit security checks |
-| `make check-all` | Run all quality checks |
+| `make format-check` | Check code formatting without making changes |
+| `make lint` | Run all linting checks (isort, black, mypy) |
### Testing Commands
| Command | Description |
|---------|-------------|
| `make test` | Run all tests |
-| `make test-unit` | Run unit tests only |
-| `make test-integration` | Run integration tests only |
+| `make test-verbose` | Run tests with verbose output |
| `make test-coverage` | Run tests with coverage report |
| `make coverage-report` | Generate detailed coverage report (FORMAT=html/xml/json/all) |
-| `make test-watch` | Run tests in watch mode |
+
+### Template Inspection Commands
+
+| Command | Description |
+|---------|-------------|
+| `make inspect-templates` | Run template inspection on all templates |
+| `make inspect-templates-verbose` | Run template inspection with verbose output |
+| `make inspect-template` | Inspect specific template(s) (TEMPLATES parameter) |
### Documentation Commands
| Command | Description |
|---------|-------------|
-| `make docs-serve` | Serve documentation locally |
-| `make docs-build` | Build documentation |
-| `make docs-deploy` | Deploy documentation to GitHub Pages |
+| `make serve-docs` | Serve documentation locally |
+| `make build-docs` | Build documentation |
### Translation Commands
@@ -214,12 +209,10 @@ The project Makefile provides convenient commands for common development tasks:
```console
# Format code and run all checks
-$ make format lint type-check security
-Running black...
+$ make format lint
Running isort...
-Running flake8...
+Running black...
Running mypy...
-Running bandit...
✅ All checks passed!
# Run tests with coverage
@@ -255,58 +248,101 @@ Running: python scripts/translate.py --target-lang ko --api-provider github --mo
Understanding the project structure is crucial for development:
-```
+```bash
FastAPI-fastkit/
├── src/
-│ └── fastapi_fastkit/
-│ ├── __init__.py
-│ ├── cli.py # CLI command implementations
-│ │ ├── __init__.py
-│ │ ├── init.py # Project initialization
-│ │ ├── addroute.py # Route addition
-│ │ ├── startdemo.py # Template demos
-│ │ └── runserver.py # Development server
-│ ├── templates/ # Project templates
-│ │ ├── __init__.py
-│ │ └── manager.py # Template management
-│ ├── utils/ # Utility functions
-│ │ ├── __init__.py
-│ │ ├── files.py # File operations
-│ │ ├── validation.py # Input validation
-│ │ └── formatting.py # Output formatting
-│ └── fastapi_project_template/ # Default template
-│ ├── src/
-│ ├── tests/
-│ └── requirements.txt
-├── tests/
-│ ├── __init__.py
-│ ├── test_cli.py # CLI testing
-│ ├── test_commands/ # Command-specific tests
-│ ├── test_templates/ # Template testing
-│ ├── test_utils/ # Utility testing
-│ └── conftest.py # Test configuration
-├── docs/ # Documentation
-├── scripts/ # Development scripts
-├── requirements.txt # Production dependencies
-├── requirements-dev.txt # Development dependencies
-├── setup.py # Package configuration
-├── Makefile # Development commands
-├── .pre-commit-config.yaml # Pre-commit configuration
-├── pyproject.toml # Project metadata
-└── README.md
+│ ├── fastapi_fastkit/
+│ │ ├── __main__.py # Entry point of the application
+│ │ ├── backend/
+│ │ │ ├── inspector.py # FastAPI-fastkit template inspector
+│ │ │ ├── interactive/
+│ │ │ │ ├── config_builder.py # Configuration builder for interactive mode
+│ │ │ │ ├── prompts.py # Prompts for interactive mode
+│ │ │ │ ├── selectors.py # Selectors logic for interactive mode
+│ │ │ │ └── validators.py # User input validators for interactive mode
+│ │ │ ├── main.py # Backend's logic entry point
+│ │ │ ├── package_managers/
+│ │ │ │ ├── base.py # Base class for package managers
+│ │ │ │ ├── factory.py # Factory for package managers
+│ │ │ │ ├── pdm_manager.py # PDM package manager
+│ │ │ │ ├── pip_manager.py # pip package manager
+│ │ │ │ ├── poetry_manager.py # Poetry package manager
+│ │ │ │ └── uv_manager.py # uv package manager
+│ │ │ ├── project_builder/
+│ │ │ │ ├── config_generator.py # Configuration generator for project builder
+│ │ │ │ └── dependency_collector.py # Dependency collector for project builder
+│ │ │ └── transducer.py # Transducer for project builder
+│ │ ├── cli.py # FastAPI-fastkit main CLI entry point
+│ │ ├── core/
+│ │ │ ├── exceptions.py # Exception handling
+│ │ │ └── settings.py # Settings configuration
+│ │ ├── fastapi_project_template/
+│ │ │ ├── PROJECT_README_TEMPLATE.md # fastkit template project base README file
+│ │ │ ├── README.md # fastkit template README
+│ │ │ ├── fastapi-async-crud/
+│ │ │ ├── fastapi-custom-response/
+│ │ │ ├── fastapi-default/
+│ │ │ ├── fastapi-dockerized/
+│ │ │ ├── fastapi-empty/
+│ │ │ ├── fastapi-mcp/
+│ │ │ ├── fastapi-psql-orm/
+│ │ │ ├── fastapi-single-module/
+│ │ │ └── modules/
+│ │ │ ├── api/
+│ │ │ │ └── routes/
+│ │ │ ├── crud/
+│ │ │ └── schemas/
+│ │ ├── py.typed
+│ │ └── utils/
+│ │ ├── logging.py # Logging configuration
+│ │ └── main.py # FastAPI-fastkit main entry point
+│ └── logs
+├── tests
+│ ├── conftest.py # pytest configuration
+│ ├── test_backends/
+│ ├── test_cli_operations/
+│ ├── test_core.py
+│ ├── test_rich/
+│ ├── test_templates/
+│ └── test_utils.py
+├── uv.lock
+├── docs/ # Documentation
+├── scripts/ # Development scripts
+├── mkdocs.yml
+├── overrides/ # mkdocs overrides
+├── pdm.lock
+├── pyproject.toml
+├── requirements-docs.txt # requirements for documentation
+├── requirements.txt # requirements for development
+├── CHANGELOG.md
+├── CITATION.cff
+├── CODE_OF_CONDUCT.md
+├── CONTRIBUTING.md
+├── LICENSE
+├── MANIFEST.in
+├── Makefile
+├── README.md
+├── SECURITY.md
+└── env.example # environment example(configures translation AI model env vars)
```
### Key Directories
**`src/fastapi_fastkit/`** - Main package source code
- **`cli.py`** - Main CLI entry point
-- **`commands/`** - Individual command implementations
-- **`templates/`** - Template management system
+- **`backend/`** - Core backend logic
+ - **`inspector.py`** - Template inspector
+ - **`interactive/`** - Interactive mode components (prompts, selectors, validators)
+ - **`package_managers/`** - Package manager implementations (pip, uv, pdm, poetry)
+ - **`project_builder/`** - Project building utilities
+ - **`transducer.py`** - Template transducer
+- **`core/`** - Core configuration and exceptions
+- **`fastapi_project_template/`** - Project templates (fastapi-default, fastapi-async-crud, etc.)
- **`utils/`** - Shared utility functions
**`tests/`** - Test suite
-- **`test_cli.py`** - CLI integration tests
-- **`test_commands/`** - Command-specific unit tests
+- **`test_backends/`** - Backend-specific tests
+- **`test_cli_operations/`** - CLI operation tests
- **`test_templates/`** - Template system tests
**`docs/`** - Documentation (MkDocs)
@@ -351,11 +387,10 @@ Pre-commit hooks will automatically run:
```console
$ git add .
$ git commit -m "Add new FastAPI template with authentication"
-black....................................................................Passed
-isort....................................................................Passed
-flake8...................................................................Passed
+format...................................................................Passed
+isort-check..............................................................Passed
+black-fix................................................................Passed
mypy.....................................................................Passed
-bandit...................................................................Passed
[feature/add-new-template abc1234] Add new FastAPI template with authentication
```
@@ -603,6 +638,7 @@ For development, you can set these environment variables:
| `FASTKIT_DEV_MODE` | Enable development features | `False` |
| `FASTKIT_TEMPLATE_DIR` | Custom template directory | Built-in templates |
| `FASTKIT_CONFIG_DIR` | Configuration directory | `~/.fastkit` |
+| `TRANSLATION_API_KEY` | Translation API key (put Github PAT when using [Github AI model provider](https://github.com/marketplace/models/azure-openai)) | `None` |
@@ -616,6 +652,8 @@ DEBUG: Available templates: ['fastapi-default', ...]
+For other environment variable settings, refer to the [@settings.py](https://github.com/bnbong/FastAPI-fastkit/blob/main/src/fastapi_fastkit/core/settings.py) module.
+
## Troubleshooting
### Common Issues
diff --git a/docs/en/contributing/template-creation-guide.md b/docs/en/contributing/template-creation-guide.md
index e6036ca..d384a70 100644
--- a/docs/en/contributing/template-creation-guide.md
+++ b/docs/en/contributing/template-creation-guide.md
@@ -285,6 +285,8 @@ make inspect-template TEMPLATES="fastapi-your-template"
python scripts/inspect-templates.py --templates "fastapi-your-template" --verbose
```
+> **Note:** When you submit a PR, the **Template PR Inspection** workflow will automatically run and validate your template changes. You'll receive feedback directly on your PR.
+
### Validation Checklist
The inspector automatically validates the following items:
@@ -456,11 +458,15 @@ Closes #issue-number
### Review Process
1. **Automated Validation**: GitHub Actions automatically validates the template
+ - **Template PR Inspection**: Runs `inspect-changed-templates.py` on PRs modifying templates
+ - **Weekly Inspection**: Full template validation every Wednesday
2. **Code Review**: Maintainers and community review the code
3. **Testing**: Template is tested in various environments
4. **Documentation Review**: Review documentation accuracy and completeness
5. **Approval & Merge**: Merge to main branch when all requirements are satisfied
+> 💡 **Tip:** You'll receive automatic PR comments with validation results. Check these before requesting a review!
+
## 🎯 Best Practices
### Security Considerations
diff --git a/env.example b/env.example
index c2c3cbd..38543a7 100644
--- a/env.example
+++ b/env.example
@@ -5,10 +5,11 @@
# Get your API key from:
# - OpenAI: https://platform.openai.com/api-keys
# - Anthropic: https://console.anthropic.com/settings/keys
+# - GitHub (for --api-provider github, use a Personal Access Token): https://github.com/settings/tokens
+#
+# The translation script will look for a token in TRANSLATION_API_KEY by default.
+# When using the GitHub provider, you can either:
+# - Put your GitHub Personal Access Token in TRANSLATION_API_KEY, or
+# - Set GITHUB_TOKEN with your GitHub Personal Access Token instead.
TRANSLATION_API_KEY=your-api-key-here
-
-# Optional: Set default API provider (openai or anthropic)
-# DEFAULT_TRANSLATION_PROVIDER=openai
-
-# Optional: GitHub token for PR creation (if not using gh cli)
-# GITHUB_TOKEN=your-github-token
+# GITHUB_TOKEN=your-github-personal-access-token-here