start-vibing-stacks 2.5.1 → 2.7.0

package/stacks/python/stack.json

@@ -2,7 +2,76 @@
   "id": "python",
   "name": "Python 3.12+",
   "icon": "🐍",
-  "runtime": "python",
+  "runtime": "Python 3.12+",
+  "minVersion": "3.12.0",
+  "packageManager": "uv|pip",
+  "extensions": [".py", ".pyi"],
+  "testExtensions": ["test_*.py", "*_test.py"],
+  "detectFiles": ["pyproject.toml", "requirements.txt", "Pipfile", "setup.py", "manage.py"],
+  "commands": {
+    "test": "pytest --tb=short",
+    "lint": "ruff check .",
+    "format": "ruff format .",
+    "serve": "uvicorn app.main:app --reload",
+    "typecheck": "mypy ."
+  },
+  "qualityGates": [
+    { "name": "mypy", "command": "mypy .", "required": true, "order": 1 },
+    { "name": "ruff", "command": "ruff check .", "required": true, "order": 2 },
+    { "name": "pytest", "command": "pytest --tb=short", "required": true, "order": 3 }
+  ],
+  "frameworks": [
+    {
+      "id": "fastapi",
+      "name": "FastAPI + Uvicorn",
+      "icon": "⚡",
+      "detectFiles": ["app/main.py"],
+      "default": true,
+      "skills": ["fastapi-patterns", "async-patterns"]
+    },
+    {
+      "id": "django",
+      "name": "Django 5+",
+      "icon": "🎸",
+      "detectFiles": ["manage.py"],
+      "skills": ["django-patterns"]
+    },
+    {
+      "id": "flask",
+      "name": "Flask",
+      "icon": "🧪",
+      "detectFiles": ["app.py", "wsgi.py"],
+      "skills": []
+    },
+    {
+      "id": "scripts",
+      "name": "Local Scripts / Automation",
+      "icon": "🤖",
+      "skills": ["scripting-automation"]
+    }
+  ],
+  "databases": [
+    { "id": "mysql", "name": "MySQL / MariaDB", "icon": "🐬", "default": true },
+    { "id": "postgresql", "name": "PostgreSQL", "icon": "🐘" },
+    { "id": "sqlite", "name": "SQLite (local)", "icon": "📦" },
+    { "id": "mongodb", "name": "MongoDB", "icon": "🍃" },
+    { "id": "none", "name": "No database", "icon": "⬜" }
+  ],
+  "frontendOptions": [
+    { "id": "react", "name": "React (SPA)", "icon": "⚛️", "frameworks": ["fastapi", "flask", "django"] },
+    { "id": "htmx", "name": "HTMX + Jinja2", "icon": "🔄", "frameworks": ["fastapi", "flask", "django"] },
+    { "id": "none", "name": "API only / CLI only", "icon": "🔌", "default": true }
+  ],
+  "deployTargets": [
+    { "id": "github", "name": "GitHub (git push)", "icon": "🐙" }
+  ],
+  "skills": [
+    "python-patterns",
+    "pydantic-validation",
+    "pytest-testing",
+    "python-performance",
+    "api-security-python"
+  ],
   "requirements": [
     {
       "name": "Python",
@@ -26,39 +95,5 @@
       },
       "versionRegex": "pip\\s+(\\d+\\.\\d+\\.?\\d*)"
     }
-  ],
-  "frameworks": [
-    { "id": "fastapi", "name": "FastAPI + Uvicorn", "icon": "⚡" },
-    { "id": "django", "name": "Django 5+", "icon": "🎸" },
-    { "id": "flask", "name": "Flask", "icon": "🧪" },
-    { "id": "vanilla", "name": "Vanilla Python", "icon": "🐍" }
-  ],
-  "databases": [
-    { "id": "postgresql", "name": "PostgreSQL", "icon": "🐘" },
-    { "id": "mysql", "name": "MySQL / MariaDB", "icon": "🐬" },
-    { "id": "mongodb", "name": "MongoDB", "icon": "🍃" },
-    { "id": "sqlite", "name": "SQLite", "icon": "📦" }
-  ],
-  "frontendOptions": [
-    { "id": "react", "name": "React (SPA)", "icon": "⚛️" },
-    { "id": "htmx", "name": "HTMX + Jinja2", "icon": "🔄" },
-    { "id": "none", "name": "API only (no frontend)", "icon": "🔌" }
-  ],
-  "deployTargets": [
-    { "id": "github", "name": "GitHub (git push)", "icon": "🐙" }
-  ],
-  "skills": [
-    "python-patterns",
-    "fastapi-patterns",
-    "django-patterns",
-    "pydantic-validation",
-    "pytest-testing",
-    "async-patterns",
-    "python-performance"
-  ],
-  "qualityGates": [
-    { "name": "mypy", "command": "mypy .", "description": "Type checking" },
-    { "name": "ruff", "command": "ruff check .", "description": "Linting" },
-    { "name": "pytest", "command": "pytest --tb=short", "description": "Tests" }
   ]
 }

package/stacks/python/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      matrix:
+        python: ['3.12']
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+
+      - name: Install uv
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: Typecheck (mypy)
+        run: uv run mypy .
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Format check (ruff)
+        run: uv run ruff format --check .
+
+      - name: Tests (pytest)
+        run: uv run pytest --tb=short --cov --cov-report=xml
+
+      - uses: codecov/codecov-action@v4
+        if: always()
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false
+
+  security:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install pip-audit
+        run: pip install pip-audit
+
+      - name: Audit dependencies
+        run: pip-audit --strict --vulnerability-service osv
+
+      - name: Gitleaks (secret scan)
+        uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/stacks/python/workflows/security.yml

@@ -0,0 +1,56 @@
+name: Security
+
+on:
+  schedule:
+    - cron: '0 4 * * 1'
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install pip-audit
+      - run: pip-audit --strict
+
+  bandit:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install bandit[toml]
+      - run: bandit -r . -ll -ii --exclude tests,test
+
+  gitleaks:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  codeql:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: github/codeql-action/init@v3
+        with:
+          languages: python
+      - uses: github/codeql-action/analyze@v3

package/templates/CLAUDE-python.md

@@ -0,0 +1,315 @@
+# {{PROJECT_NAME}}
+
+> **CHARACTER LIMIT**: Max 40,000 chars. Validate with `wc -m CLAUDE.md` before commit.
+
+## Last Change
+
+**Branch:** main
+**Date:** {{DATE}}
+**Summary:** Initial project setup with start-vibing-stacks (Python)
+
+## 30 Seconds Overview
+
+{{PROJECT_NAME}} is a Python 3.12+ project using {{FRAMEWORK}}.
+
+## Stack
+
+| Component | Technology |
+|-----------|------------|
+| Language | Python >= 3.12 |
+| Framework | {{FRAMEWORK}} |
+| Database | {{DATABASE}} |
+| Type Checking | mypy (strict) |
+| Linting | ruff |
+| Testing | pytest + pytest-asyncio |
+| Validation | Pydantic v2 |
+| HTTP Client | httpx |
+| Package Manager | uv / pip |
+
+## Architecture
+
+### FastAPI / Flask Projects
+
+```
+project/
+├── CLAUDE.md                # This file (40k char max)
+├── pyproject.toml           # Dependencies + project config
+├── .env                     # Secrets (NEVER commit)
+├── .env.example             # Template without values
+├── .claude/
+│   ├── agents/              # 6 active subagents
+│   ├── skills/              # Skill systems (auto-injected)
+│   ├── hooks/               # Validation hooks
+│   ├── config/              # Project configuration
+│   └── commands/            # Slash commands
+├── app/
+│   ├── main.py              # App entrypoint + startup
+│   ├── api/v1/
+│   │   ├── routes/          # Endpoint modules
+│   │   └── deps.py          # Dependencies (auth, db)
+│   ├── models/              # SQLAlchemy / Beanie models
+│   ├── schemas/             # Pydantic schemas
+│   ├── services/            # Business logic layer
+│   ├── core/
+│   │   ├── config.py        # Pydantic Settings (env)
+│   │   └── security.py      # Auth, hashing
+│   └── utils/               # Helpers
+├── scripts/                 # CLI scripts / automation
+├── tests/
+│   ├── conftest.py          # Shared fixtures
+│   ├── unit/
+│   └── integration/
+└── alembic/                 # DB migrations (if SQL)
+```
+
+### Local Scripts / Automation Projects
+
+```
+project/
+├── CLAUDE.md
+├── pyproject.toml
+├── .env
+├── .env.example
+├── .claude/
+├── main.py                  # CLI entry point (argparse)
+├── scripts/
+│   ├── __init__.py
+│   ├── wordpress.py         # WordPress API automation
+│   ├── ads_manager.py       # Google/Facebook/TikTok Ads
+│   └── data_sync.py         # Database sync / ETL
+├── lib/
+│   ├── __init__.py
+│   ├── config.py            # Pydantic Settings
+│   ├── http_client.py       # Reusable httpx client
+│   ├── logger.py            # Structured logging (rich)
+│   └── retry.py             # tenacity retry logic
+├── data/                    # Input/output data files
+├── logs/                    # Log files
+└── tests/
+```
+
+### Django Projects
+
+```
+project/
+├── CLAUDE.md
+├── pyproject.toml
+├── manage.py
+├── config/                  # Settings, URLs, ASGI
+├── apps/
+│   ├── users/               # Per-app: models, views, serializers, tests
+│   └── products/
+└── tests/
+```
+
+## Critical Rules
+
+### Python 3.12+ (MANDATORY)
+
+- **Type hints on ALL public functions** — parameters, returns, class attributes
+- **Pydantic v2 for all data boundaries** — API schemas, config, external data
+- **`match/case`** for complex branching (3.10+)
+- **`type` keyword** for simple type aliases (3.12+)
+- **f-strings** everywhere, never `%` or `.format()`
+- **Structural pattern matching** over nested if/elif chains
+
+### Code Organization
+
+- **Thin routes, fat services** — business logic in `services/`, not in routes/views
+- **Repository pattern** for database access — isolate queries from business logic
+- **Dependency injection** — FastAPI `Depends()`, Django class-based views
+- **One concern per module** — a file should do one thing well
+
+### Environment Variables & Secrets (MANDATORY)
+
+```python
+# CORRECT: Pydantic Settings loads from .env
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    DATABASE_URL: str
+    SECRET_KEY: str
+    API_TOKEN: str
+    model_config = {"env_file": ".env"}
+
+settings = Settings()
+```
+
+| Rule | Reason |
+|------|--------|
+| All secrets in `.env` | Never hardcode credentials |
+| `.env` in `.gitignore` | Never commit secrets |
+| `.env.example` always present | Document required variables |
+| Pydantic Settings for loading | Typed, validated, auto-parsed |
+| `--dry-run` flag for destructive scripts | Prevent accidental data loss |
+
+### Async vs Sync
+
+| Workload | Pattern |
+|----------|---------|
+| I/O-bound (HTTP, DB, files) | `async def` + `httpx` / `asyncpg` |
+| CPU-bound (parsing, computation) | `def` + `multiprocessing` / `concurrent.futures` |
+| Local scripts (simple) | Sync is fine unless hitting APIs in bulk |
+| Bulk API calls | `async def` + `asyncio.gather` + semaphore |
+
+### Database Safety
+
+- **Parameterized queries ALWAYS** — `cursor.execute(query, params)`
+- **Connection context managers** — auto-close on exit
+- **Migrations** — Alembic (FastAPI) or Django `makemigrations`
+- **Pool connections** in production — `pool_size` + `max_overflow`
+
+## Quality Gates
+
+```bash
+mypy .                    # Type checking (MUST pass)
+ruff check .              # Linting (MUST pass)
+ruff format . --check     # Format check
+pytest --tb=short         # Tests (MUST pass)
+```
+
+## FORBIDDEN
+
+### Security (CRITICAL)
+
+| Action | Reason |
+|--------|--------|
+| Hardcoded API keys/passwords | Use `.env` + Pydantic Settings |
+| Commit `.env` files | Secrets leak to repository |
+| SQL without parameterization | SQL injection |
+| Deserializing untrusted binary data | Remote code execution risk |
+| `yaml.load()` without SafeLoader | Code injection |
+| No input validation on external data | Use Pydantic models |
+| Storing plaintext passwords | Use `passlib` / `bcrypt` |
+
+### Code Quality
+
+| Action | Reason |
+|--------|--------|
+| `import *` | Explicit imports only |
+| `requests` library | Use `httpx` (modern, sync+async) |
+| `print()` for logging | Use `logging` module or `rich` |
+| No type hints on public APIs | mypy must pass |
+| Business logic in routes/views | Use services layer |
+| Bare `except Exception` | Catch specific exceptions |
+| `time.sleep()` in async code | Use `await asyncio.sleep()` |
+| Sync HTTP in async context | Blocks the event loop |
+| Global mutable state | Use dependency injection |
+| Files > 400 lines | Split into modules |
+
+### Workflow
+
+| Action | Reason |
+|--------|--------|
+| Skip tests | Quality gate blocks commit |
+| Skip type checking | mypy catches runtime errors |
+| No `.env.example` | Others can't configure project |
+| No `--dry-run` on destructive scripts | Risk of accidental data loss |
+| Commit directly to main | Use feature branches |
+
+## CLAUDE.md Update Rules
+
+### When to Update
+
+| Change Type | What to Update |
+|-------------|----------------|
+| Any file change | Last Change section |
+| New feature | 30s Overview, Architecture if needed |
+| New pattern | Add to relevant section |
+| Gotcha discovered | Add to FORBIDDEN or NRY |
+| New dependency | Update Stack table |
+
+### Last Change Format (MANDATORY)
+
+```markdown
+## Last Change
+
+**Branch:** feature/example
+**Date:** YYYY-MM-DD
+**Summary:** 1-2 sentences describing WHAT and WHY.
+```
+
+## Agent System
+
+| Agent | Purpose |
+|-------|---------|
+| research-web | Researches best practices (MANDATORY for new features) |
+| documenter | Maps files to domains, tracks what exists |
+| domain-updater | Records problems, solutions, learnings |
+| commit-manager | Manages commits and merges |
+| tester | Creates tests with pytest |
+| claude-md-compactor | Compacts CLAUDE.md when over 40k chars |
+
+### Skills
+
+| Category | Skills |
+|----------|--------|
+| **Core** | python-patterns, pydantic-validation, pytest-testing, python-performance |
+| **Framework** | fastapi-patterns, django-patterns, async-patterns, scripting-automation |
+| **UI** | ui-ux-pro-max (auto-installed for frontend projects) |
+
+## Domain Documentation
+
+### Location
+
+```
+.claude/skills/codebase-knowledge/domains/
+├── api.md
+├── database.md
+├── scripts.md
+└── ...
+```
+
+### Documentation Agents
+
+| Agent | Role | When |
+|-------|------|------|
+| **documenter** | Maps files to domains | AFTER implementation |
+| **domain-updater** | Records problems + solutions | BEFORE commit |
+
+## Workflow
+
+```
+1. TODO LIST → Create detailed task list
+2. RESEARCH → Run research agent for new features
+3. BRANCH → Create feature/ | fix/ | refactor/ | test/
+4. IMPLEMENT → Follow skills + type everything
+5. QUALITY → mypy → ruff → pytest (all must pass)
+6. DOCUMENT → Update domains + CLAUDE.md
+7. COMMIT → Conventional commit format
+```
+
+## Commit Format
+
+```
+[type]: [description]
+
+- Detail 1
+- Detail 2
+
+Generated with Claude Code
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+Types: `feat`, `fix`, `refactor`, `docs`, `chore`, `test`
+
+## NRY (Never Repeat Yourself)
+
+- Always check `.claude/skills/` before implementing patterns from scratch
+- Use `tenacity` for retry logic, not hand-rolled loops
+- Use `pydantic_settings` for env config, not `os.getenv()` manually
+- Use `httpx` for HTTP, never `urllib` or `requests`
+- Use `rich` for CLI output, not bare `print()`
+
+## Configuration
+
+Project-specific settings in `.claude/config/`:
+
+- `active-project.json` — Stack, framework, database, skills
+- `security-rules.json` — Security audit rules
+- `standards-review.json` — Imported project standards (if adapted)
+
+## Setup by start-vibing
+
+This project was set up with `npx start-vibing-stacks`.
+For updates: `npx start-vibing-stacks --force`