Initial commit

2025-11-29 18:29:07 +08:00
commit 8b4a1b1a99
75 changed files with 18583 additions and 0 deletions
--- a/skills/project-scaffolding/reference/INDEX.md
+++ b/skills/project-scaffolding/reference/INDEX.md
@@ -0,0 +1,203 @@
+# Project Scaffolder Reference
+
+Complete reference for Grey Haven project scaffolding - conventions, specifications, and tooling.
+
+---
+
+## Navigation
+
+| Reference | Description |
+|-----------|-------------|
+| [Grey Haven Conventions](grey-haven-conventions.md) | Naming, structure, and code standards |
+| [Scaffold Specifications](scaffold-specifications.md) | Technical specs for each scaffold type |
+| [Tooling Configurations](tooling-configurations.md) | Config files for Vite, Wrangler, pytest, etc. |
+
+---
+
+## Quick Reference
+
+### Grey Haven Stack
+
+| Layer | Technology | Use Case |
+|-------|------------|----------|
+| **Frontend** | React + Vite + TanStack | Web applications |
+| **Backend** | Cloudflare Workers + Hono | REST/GraphQL APIs |
+| **Database** | PlanetScale PostgreSQL (or D1) | Relational data |
+| **Validation** | Zod (TS), Pydantic (Python) | Type-safe validation |
+| **Testing** | Vitest (TS), pytest (Python) | Unit & integration tests |
+| **Deployment** | Cloudflare Pages + Workers | Global edge deployment |
+
+### Naming Conventions
+
+```
+Components:     PascalCase   (Button, UserProfile)
+Files:          kebab-case   (user-profile.tsx, api-client.ts)
+Variables:      camelCase    (userId, isActive)
+Constants:      UPPER_SNAKE  (API_URL, MAX_RETRIES)
+Database:       snake_case   (user_profiles, api_keys)
+Routes:         kebab-case   (/api/user-profiles)
+```
+
+### Folder Structure
+
+```
+src/
+├── routes/        # API endpoints or page routes
+├── components/    # Reusable UI components
+├── services/      # Business logic
+├── utils/         # Pure helper functions
+├── types/         # TypeScript type definitions
+└── lib/           # Third-party integrations
+
+tests/             # Mirror src/ structure
+├── routes/
+├── components/
+└── services/
+```
+
+### Configuration Standards
+
+**TypeScript Projects**:
+- Strict mode enabled
+- ESLint with recommended rules
+- Prettier for formatting
+- Vitest for testing
+- Path aliases (`@/` for src/)
+
+**Python Projects**:
+- Python 3.11+
+- uv for package management
+- Ruff for linting
+- mypy for type checking
+- pytest for testing
+
+---
+
+## Scaffold Templates
+
+### Minimum Files Required
+
+**Cloudflare Worker**:
+- wrangler.toml
+- package.json
+- tsconfig.json
+- src/index.ts
+- tests/
+
+**React App**:
+- package.json
+- vite.config.ts
+- tsconfig.json
+- src/main.tsx
+- src/routes/
+- tests/
+
+**Python API**:
+- pyproject.toml
+- app/main.py
+- app/schemas/
+- app/models/
+- tests/
+
+---
+
+## Tooling Versions
+
+### Recommended Versions (2024)
+
+```json
+{
+  "typescript": "^5.3.0",
+  "vite": "^5.0.0",
+  "react": "^18.2.0",
+  "hono": "^4.0.0",
+  "wrangler": "^3.25.0",
+  "vitest": "^1.2.0"
+}
+```
+
+```toml
+# Python (pyproject.toml)
+[project]
+requires-python = ">=3.11"
+dependencies = [
+  "fastapi[standard]>=0.109.0",
+  "pydantic>=2.5.0",
+  "uvicorn>=0.27.0"
+]
+```
+
+---
+
+## Best Practices
+
+### DO
+
+- ✅ Use TypeScript strict mode
+- ✅ Include tests in scaffold
+- ✅ Configure linting and formatting
+- ✅ Add .gitignore
+- ✅ Include README with setup instructions
+- ✅ Add CI/CD configuration
+- ✅ Use environment variables for secrets
+- ✅ Include health check endpoint
+
+### DON'T
+
+- ❌ Commit node_modules or .venv
+- ❌ Hard-code secrets or API keys
+- ❌ Skip type definitions
+- ❌ Omit error handling
+- ❌ Forget database migrations
+- ❌ Skip documentation
+
+---
+
+## Deployment Checklist
+
+### Pre-Deployment
+
+- [ ] All tests passing
+- [ ] TypeScript/mypy checks pass
+- [ ] Linting passes
+- [ ] Environment variables configured
+- [ ] Database migrations applied
+- [ ] Secrets set in production
+- [ ] Build succeeds
+- [ ] Health check endpoint working
+
+### Post-Deployment
+
+- [ ] Health check returns 200
+- [ ] API endpoints accessible
+- [ ] Database connections working
+- [ ] Authentication functioning
+- [ ] Monitoring enabled
+- [ ] Error tracking active
+- [ ] Logs accessible
+
+---
+
+## Common Issues
+
+### Issue: TypeScript errors after scaffold
+
+**Solution**: Run `npm install` and ensure tsconfig.json is correct
+
+### Issue: Wrangler fails to deploy
+
+**Solution**: Check wrangler.toml config and Cloudflare authentication
+
+### Issue: Database connection fails
+
+**Solution**: Verify connection string and database credentials
+
+### Issue: Tests fail after scaffold
+
+**Solution**: Check test setup and mock configuration
+
+---
+
+**Total References**: 3 comprehensive guides
+**Coverage**: Conventions, specifications, configurations
+**Standards**: Production-ready Grey Haven stack