Merge pull request #40 from bnbong/dev

[RELEASE, DOCS, FIX] Fix fastkit init flow, address security advisories & review findings

Author: bnbong

docs/en/contributing/code-guidelines.md

@@ -144,20 +144,20 @@ def validate_email(e):
 
 ```python
 # Good ✅
-class ProjectTemplate:
-    """Represents a FastAPI project template."""
+class SomeClass:
+    """Represents example class of FastAPI-fastkit."""
     pass
 
-class TemplateValidationError(Exception):
-    """Raised when template validation fails."""
+class SomeClassValidationError(Exception):
+    """Raised when example class validation fails."""
     pass
 
 class UserInputHandler:
     """Handles user input validation and processing."""
     pass
 
 # Bad ❌
-class Template:
+class Class:
     pass
 
 class Error(Exception):
@@ -409,6 +409,10 @@ def test_file_creation_with_permission_error(mock_open):
 
 ### Import Organization
 
+!!! note
+
+    `isort` formatter will automatically organize imports, so you can organize imports easily just run `bash scripts/format.sh`.
+
 1. **Standard library** imports first
 2. **Third-party** imports second
 3. **Local application** imports last
@@ -705,7 +709,9 @@ ci:
     autoupdate_commit_msg: ⬆ [pre-commit.ci] pre-commit autoupdate
 ```
 
-> **Note:** Pre-commit hooks use isolated Python environments (`language: python`).
+!!! note
+
+    Pre-commit hooks use isolated Python environments (`language: python`).
 
 ### IDE Configuration
 

docs/en/contributing/development-setup.md

@@ -35,7 +35,9 @@ This single command:
 - Sets up pre-commit hooks
 - Configures development tools
 
-> **Note:** You should create and activate a virtual environment before running this command.
+!!! note
+
+    You should create and activate a virtual environment before running this command.
 
 ## Manual Setup
 
@@ -95,7 +97,7 @@ pre-commit installed at .git/hooks/pre-commit
 
 ```console
 $ fastkit --version
-FastAPI-fastkit version 1.0.0-dev
+fastapi-fastkit, version 1.2.0
 
 $ python -m pytest tests/
 ======================== test session starts ========================
@@ -112,6 +114,25 @@ tests/test_templates.py::test_template_listing PASSED
 
 The development environment includes several tools to maintain code quality:
 
+### One-liner Commands
+
+using Makefile:
+
+```console
+$ make format lint
+Running isort...
+Running black...
+Running mypy...
+✅ All checks passed!
+```
+
+using provided scripts:
+
+```console
+$ ./scripts/format.sh
+$ ./scripts/lint.sh
+```
+
 ### Code Formatting
 
 **Black** - Code formatter:
@@ -328,25 +349,23 @@ FastAPI-fastkit/
 
 ### Key Directories
 
-**`src/fastapi_fastkit/`** - Main package source code
-- **`cli.py`** - Main CLI entry point
-- **`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_backends/`** - Backend-specific tests
-- **`test_cli_operations/`** - CLI operation tests
-- **`test_templates/`** - Template system tests
-
-**`docs/`** - Documentation (MkDocs)
-- User guides, tutorials, and API reference
+- **`src/fastapi_fastkit/`** - Main package source code
+    - **`cli.py`** - Main CLI entry point
+    - **`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_backends/`** - Backend-specific tests
+    - **`test_cli_operations/`** - CLI operation tests
+    - **`test_templates/`** - Template system tests
+- **`docs/`** - Documentation (MkDocs)
+    - User guides, tutorials, and API reference
 
 ## Development Workflow
 
@@ -370,10 +389,10 @@ Edit code, add features, fix bugs...
 <div class="termy">
 
 ```console
-$ make check-all test
+$ make dev-check
 Running all quality checks...
 Running all tests...
-✅ All checks and tests passed!
+✅ All tests passed!
 ```
 
 </div>
@@ -445,18 +464,6 @@ $ python -m pytest --cov=src --cov-report=html
 
 </div>
 
-**Watch mode for development:**
-
-<div class="termy">
-
-```console
-$ make test-watch
-# or
-$ ptw tests/
-```
-
-</div>
-
 ### Writing Tests
 
 When adding new features, always include tests:
@@ -530,7 +537,7 @@ def test_full_project_creation_workflow(tmp_path):
 <div class="termy">
 
 ```console
-$ make docs-serve
+$ make serve-docs
 INFO     -  Building documentation...
 INFO     -  Cleaning site directory
 INFO     -  Documentation built in 0.43 seconds
@@ -544,7 +551,7 @@ INFO     -  [14:30:00] Serving on http://127.0.0.1:8000/
 <div class="termy">
 
 ```console
-$ make docs-build
+$ make build-docs
 INFO     -  Building documentation...
 INFO     -  Documentation built in 0.43 seconds
 ```
@@ -582,6 +589,8 @@ $ fastkit new-feature --option value
     Use `--help` to see all available options.
 ````
 
+For detailed reference about using `mkdocs-material`, see [mkdocs-material documentation](https://squidfunk.github.io/mkdocs-material/reference/admonitions/).
+
 ## Code Style Guidelines
 
 ### Python Code Style
@@ -717,19 +726,18 @@ $ pip install -e .
 
 ### Getting Help
 
-- **GitHub Issues**: Report bugs and request features
-- **GitHub Discussions**: Ask questions and share ideas
+- **[GitHub Issues](https://github.com/bnbong/FastAPI-fastkit/issues)**: Report bugs and request features
+- **[GitHub Discussions](https://github.com/bnbong/FastAPI-fastkit/discussions)**: Ask questions and share ideas
 - **Documentation**: Check the [User Guide](../user-guide/installation.md)
 
 ## Contributing Guidelines
 
 ### Before Submitting a PR
 
-1. **Run all checks:** `make check-all test`
+1. **Run all checks:** `make dev-check`
 2. **Update documentation** if needed
 3. **Add tests** for new features
-4. **Update CHANGELOG.md**
-5. **Follow commit message conventions**
+4. **Follow commit message conventions**
 
 ### Commit Message Format
 
@@ -793,15 +801,15 @@ $ git push origin v1.2.0
 
 Now that your development environment is set up:
 
-1. **Explore the codebase** to understand the architecture
+1. **[Explore the codebase](https://github.com/bnbong/FastAPI-fastkit/tree/main/src/fastapi_fastkit)** to understand the architecture
 2. **Run the test suite** to ensure everything works
-3. **Pick an issue** from GitHub to work on
-4. **Join discussions** to connect with other contributors
+3. **Pick an [issue](https://github.com/bnbong/FastAPI-fastkit/issues)** from GitHub to work on
+4. **Join [discussions](https://github.com/bnbong/FastAPI-fastkit/discussions)** to connect with other contributors
 
 Happy coding! 🚀
 
 !!! tip "Development Tips"
-    - Use `make check-all` before committing
+    - Use `make dev-check` before committing
     - Write tests first (TDD approach)
     - Keep commits small and focused
     - Update documentation with new features

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

@@ -15,6 +15,7 @@ Adding a new template follows a 5-step process:
 ## 📋 Step 1: Planning & Design
 
 ### Define Template Purpose
+
 Before creating a new template, answer these questions:
 
 - **What is the unique value of this template?**
@@ -34,6 +35,7 @@ Examples:
 - `fastapi-auth-jwt` (JWT authentication template)
 
 ### Technology Stack Planning
+
 Pre-define the main technologies to include:
 
 ```yaml
@@ -226,6 +228,7 @@ setup(
 ```
 
 #### 4. Writing Test Files
+
 ```python
 # tests/test_items.py-tpl
 """
@@ -285,32 +288,39 @@ 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.
+!!! 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:
 
 #### ✅ File Structure Validation
+
 - [ ] `tests/` directory exists
 - [ ] `requirements.txt-tpl` file exists
 - [ ] `setup.py-tpl` file exists
 - [ ] `README.md-tpl` file exists
 
 #### ✅ File Extension Validation
+
 - [ ] All Python files use `.py-tpl` extension
 - [ ] No `.py` extension files exist
 
 #### ✅ 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 Implementation Validation
+
 - [ ] `FastAPI` import exists in `main.py-tpl`
 - [ ] App creation like `app = FastAPI()` exists in `main.py-tpl`
 
 #### ✅ Test Execution Validation
+
 - [ ] Virtual environment creation successful
 - [ ] Dependencies installation successful
 - [ ] All pytest tests pass
@@ -345,7 +355,7 @@ New templates are **automatically discovered** and tested without manual configu
 4. ✅ **Comprehensive Validation**: Structure, metadata, and functionality checks
 
 **What This Means for You:**
-- 🚀 **No Additional Test Files**: Your template is tested automatically
+- 🚀 **No Additional Test Files at `FastAPI-fastkit`'s main source testcases**: Your template is tested automatically
 - ⚡ **Faster Development**: Focus on template content, not test setup
 - 🛡️ **Quality Assurance**: Consistent testing across all templates
 - 🔄 **CI/CD Integration**: Automatic testing in pull requests
@@ -374,18 +384,21 @@ $ fastkit startdemo your-template-name --package-manager uv
 In addition to automated validation, manually check the following items:
 
 #### 🔧 Code Quality
+
 - [ ] Code follows PEP 8 style guide
 - [ ] Appropriate type hints usage
 - [ ] Meaningful variable and function names
 - [ ] Proper comments and docstrings
 
 #### 🏗️ Architecture
+
 - [ ] Separation of concerns (API, business logic, data access separation)
 - [ ] Reusable component design
 - [ ] Scalable structure
 - [ ] Security best practices applied
 
 #### 📚 Documentation
+
 - [ ] README.md-tpl follows PROJECT_README_TEMPLATE.md format
 - [ ] Installation and execution methods specified
 - [ ] API documentation (OpenAPI/Swagger)
@@ -430,7 +443,7 @@ Write a brief description and use cases for your new template here.
 ### PR Title and Description
 
 ```
-[FEAT] Add fastapi-{template-name} template
+[TEMPLATE] Add fastapi-{template-name} template
 
 ## Overview
 Adds a new {purpose} template.
@@ -465,23 +478,28 @@ Closes #issue-number
 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!
+!!! note
+
+    You'll receive automatic PR comments with validation results. Check these before requesting a review!
 
 ## 🎯 Best Practices
 
 ### Security Considerations
+
 - Manage sensitive information with environment variables
 - Proper CORS configuration
 - Input data validation
 - SQL injection prevention
 
 ### Performance Optimization
+
 - Utilize asynchronous processing
 - Optimize database queries
 - Appropriate caching strategies
 - Response compression settings
 
 ### Maintainability
+
 - Clear code structure
 - Comprehensive test coverage
 - Detailed documentation

docs/en/contributing/translation-guide.md

@@ -186,7 +186,7 @@ The script will create a Pull Request with the translations. Review the PR:
 3. Ensure code examples remain unchanged
 4. Check for language-specific issues
 
-### 4. Approve and Merge
+### 4. Approve and Merge (for maintainers)
 
 Once the translation is verified: