Initial commit

2025-11-30 08:46:40 +08:00
commit 66f1bf4fb0
33 changed files with 6059 additions and 0 deletions
--- a/skills/django-setup/README.md
+++ b/skills/django-setup/README.md
@@ -0,0 +1,144 @@
+# Django Setup Skill (HTTPS Development)
+
+**For HTTPS-only Django projects using mkcert SSL certificates.**
+
+## Skill Overview
+
+This skill sets up Django projects specifically for **HTTPS local development**, which is required for:
+- WebAuthn/Passkeys (MFA)
+- Secure cookies
+- Service workers
+- Modern browser APIs
+
+## Key Features
+
+- ✅ **Automatic Python version selection** - Uses highest available 3.8-3.13, installs 3.13 if none found
+- ✅ **HTTPS by default** - Integrated mkcert setup
+- ✅ **Core dependencies** - Django, python-dotenv, djangorestframework, django-cors-headers; adds `uvicorn[standard]` for SSL serving
+- ✅ **Uvicorn ASGI server** - With SSL support
+- ✅ **Manual, guided setup** - No automation scripts, full control
+
+## Progressive Disclosure Structure
+
+```
+django-setup/
+├── SKILL.md                   # ⭐ Core skill (HTTPS-focused)
+├── README.md                  # This file
+│
+├── platform-https/            # 🔒 mkcert + Uvicorn setup per OS
+│   ├── mkcert-https-setup-macos.md
+│   ├── mkcert-https-setup-linux.md
+│   └── mkcert-https-setup-windows.md
+│
+├── platform-install/          # 📦 Platform-specific Python installation
+│   ├── macos.md
+│   ├── linux-ubuntu.md
+│   ├── linux-fedora.md
+│   └── windows.md
+│
+├── troubleshooting/           # 🔧 Problem-solving guides
+│   ├── venv-issues.md
+│   ├── pip-problems.md
+│   └── django-errors.md
+│
+└── examples/                 # 📋 Templates
+    └── .gitignore-template
+```
+
+## What's Different from Standard Django Setup?
+
+| Standard Django | This Skill |
+|----------------|------------|
+| HTTP only (port 8000) | HTTPS with mkcert |
+| `python manage.py runserver` | `./run.sh` / `run.bat` (Uvicorn with SSL) |
+| No SSL certificates | SSL certs in `certs/` |
+| Optional HTTPS | HTTPS required |
+| Any dependencies | Focused: Django, dotenv, DRF, django-cors-headers + uvicorn |
+
+## Quick Setup Flow
+
+1. **Check/install Python 3.8-3.13** (uses highest, installs 3.13 if needed)
+2. **Create venv** with selected Python version
+3. **Install core dependencies** (Django, python-dotenv, djangorestframework, django-cors-headers)
+4. **Create Django project** (`django-admin startproject backend .`)
+5. **Set up mkcert HTTPS + Uvicorn** (platform-https guides install `uvicorn[standard]`, generate certs, create run script)
+6. **Configure settings.py for CORS/CSRF** (adds corsheaders middleware & allowed origins)
+7. **Add health + CSRF helper endpoints** (`api/health`, `api/csrf`)
+8. **Run migrations** (`python manage.py migrate`)
+9. **Optional VS Code launch config** (`.vscode/launch.json`)
+10. **Test with HTTPS** (`./run.sh` or `run.bat` → `https://localhost:8000`)
+
+## Why These Dependencies?
+
+Authentication packages (allauth, etc.) are **intentionally excluded** and should be added later via the `django-allauth-config` skill to keep the base setup lean. `django-cors-headers` is included because the skill configures CORS/CSRF for a typical HTTPS frontend, and `uvicorn[standard]` is used to serve Django over SSL in development.
+
+**Core dependencies:**
+```bash
+pip install Django python-dotenv djangorestframework django-cors-headers
+```
+
+**HTTPS server:**
+```bash
+pip install 'uvicorn[standard]'
+```
+
+**Add authentication later:**
+```bash
+# Use django-allauth-config skill
+pip install django-allauth[socialaccount,mfa] django-cors-headers
+```
+
+## Integration with Other Skills
+
+This skill integrates with:
+
+- **mkcert-https-setup** - SSL certificate setup (referenced inline via platform-https guides)
+- **django-allauth-config** - Add authentication after base setup
+
+## Token Efficiency
+
+**Core SKILL.md:** ~2,500 tokens (HTTPS-focused, no automation)
+**Platform guides:** ~400-600 tokens (loaded only when needed)
+**Troubleshooting:** ~300-500 tokens (loaded only on errors)
+
+**Average context usage:** ~2,800 tokens
+**Compared to v1.0 monolithic:** 65% reduction
+
+## Usage
+
+```bash
+# User says: "Set up Django project for HTTPS"
+# Claude loads: django-project-setup skill
+# Guides through: Python → venv → Django → mkcert → test HTTPS
+```
+
+## Final Project Structure
+
+```
+project-root/
+├── backend/                  # Django project
+├── backend/views.py          # Health + CSRF token endpoints
+├── certs/                    # mkcert SSL certificates
+│   ├── localhost+2.pem
+│   └── localhost+2-key.pem
+├── venv/                     # Virtual environment
+├── .gitignore
+├── db.sqlite3                # Database
+├── manage.py
+├── requirements.txt          # Django, dotenv, DRF, cors-headers, uvicorn
+├── run.sh                    # HTTPS server script (macOS/Linux)
+├── run.bat                   # HTTPS server script (Windows)
+└── .vscode/launch.json       # Optional VS Code debug config
+```
+
+## Version History
+
+- **v3.0.0** - HTTPS-only, mkcert integration, uvicorn server, CORS/CSRF defaults, minimal automation
+- **v2.0.0** - Progressive disclosure with bundled content (deprecated)
+- **v1.0.0** - Initial monolithic skill (deprecated)
+
+## Security Notes
+
+🔒 **Local development only** - mkcert certificates only work on your machine
+🔐 **Never commit** - `certs/`, `*.pem`, `.env` must be in `.gitignore`
+⚠️ **Production** - Use real SSL certificates (Let's Encrypt, etc.)