@codihaus/claude-skills 1.0.0

package/skills/dev-coding-backend/SKILL.md

@@ -0,0 +1,361 @@
+---
+name: dev-coding-backend
+description: Backend implementation patterns and workflows
+version: 1.2.0
+---
+
+# /dev-coding-backend - Backend Implementation
+
+> **Skill Awareness**: See `skills/_registry.md` for all available skills.
+> - **Loaded by**: `/dev-coding` when API/schema work needed
+> - **References**: Load tech-specific from `references/` (directus.md, prisma.md, etc.)
+> - **After**: Frontend uses API contract documented here
+> - **After**: `/dev-test` auto-runs to verify API via network requests
+
+Backend-specific patterns for API, schema, and data layer implementation.
+
+## When Loaded
+
+This skill is loaded by `/dev-coding` when:
+- Spec requires API endpoints
+- Spec requires schema/database changes
+- Spec requires backend logic
+
+## Workflow
+
+### Step 1: Understand Backend Requirements
+
+From the UC spec, extract:
+
+```markdown
+## Backend Requirements Checklist
+
+[ ] Schema changes needed?
+    - New collections/tables
+    - New fields on existing
+    - Relations to add
+
+[ ] API endpoints needed?
+    - Method + Path
+    - Request body
+    - Response shape
+    - Auth required?
+
+[ ] Business logic?
+    - Validation rules
+    - Calculations
+    - Side effects (emails, notifications)
+
+[ ] External integrations?
+    - Third-party APIs
+    - Webhooks
+    - File storage
+```
+
+### Step 2: Schema First (if needed)
+
+**Order matters:** Schema before API
+
+```
+1. Design schema based on spec
+2. Create/modify collections or tables
+3. Set up relations
+4. Configure permissions/roles
+5. Verify schema is correct
+```
+
+**Verification:**
+```bash
+# For Directus - check collection exists
+curl "$DIRECTUS_URL/items/{collection}?limit=1" \
+  -H "Authorization: Bearer $TOKEN"
+
+# For Prisma - run migration
+npx prisma migrate dev
+
+# For SQL - verify table
+psql -c "\\d {table_name}"
+```
+
+### Step 3: API Implementation
+
+**For each endpoint in spec:**
+
+```
+1. Create route/handler file
+2. Implement request parsing
+3. Add validation
+4. Implement business logic
+5. Handle errors
+6. Return response
+```
+
+**Follow project patterns** (from scout):
+- File location (routes/, api/, controllers/)
+- Naming convention
+- Error handling pattern
+- Response format
+
+### Step 4: API Patterns
+
+#### REST Conventions
+
+```
+GET    /api/{resource}        → List
+GET    /api/{resource}/:id    → Get one
+POST   /api/{resource}        → Create
+PUT    /api/{resource}/:id    → Update (full)
+PATCH  /api/{resource}/:id    → Update (partial)
+DELETE /api/{resource}/:id    → Delete
+```
+
+#### Request Validation
+
+```typescript
+// Always validate input
+const schema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+});
+
+const result = schema.safeParse(req.body);
+if (!result.success) {
+  return res.status(400).json({
+    error: 'Validation failed',
+    details: result.error.issues
+  });
+}
+```
+
+#### Error Handling
+
+```typescript
+// Consistent error format
+{
+  "error": "Error message for client",
+  "code": "ERROR_CODE",
+  "details": {} // Optional additional info
+}
+
+// HTTP status codes
+200 - Success
+201 - Created
+400 - Bad request (validation)
+401 - Unauthorized
+403 - Forbidden
+404 - Not found
+409 - Conflict
+500 - Server error
+```
+
+#### Authentication Check
+
+```typescript
+// Verify auth before processing
+if (!req.user) {
+  return res.status(401).json({ error: 'Unauthorized' });
+}
+
+// Check permissions
+if (!req.user.permissions.includes('create:posts')) {
+  return res.status(403).json({ error: 'Forbidden' });
+}
+```
+
+### Step 5: Verification
+
+**Test each endpoint:**
+
+```bash
+# Test with curl
+curl -X POST http://localhost:3000/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"test@test.com","password":"password123"}'
+
+# Expected: 200 with token
+# Or: 401 with error message
+```
+
+**Verification checklist:**
+```
+[ ] Endpoint responds
+[ ] Correct status codes
+[ ] Response matches spec
+[ ] Validation rejects bad input
+[ ] Auth required endpoints reject anonymous
+[ ] Error messages are helpful but not leaky
+```
+
+### Step 6: Document for Frontend
+
+After backend complete, document what frontend needs:
+
+```markdown
+## API Ready for Frontend
+
+### POST /api/auth/login
+- **Auth**: None (public)
+- **Request**: `{ email: string, password: string }`
+- **Success (200)**: `{ token: string, user: { id, email, name } }`
+- **Errors**:
+  - 400: Invalid input
+  - 401: Invalid credentials
+
+### GET /api/users/me
+- **Auth**: Bearer token required
+- **Request**: None
+- **Success (200)**: `{ id, email, name, role }`
+- **Errors**:
+  - 401: No/invalid token
+```
+
+### Step 7: Hand Off to Testing
+
+After full implementation (backend + frontend), `/dev-coding` auto-triggers `/dev-test` which:
+
+```
+1. Navigate to UI (triggers API calls)
+2. Capture network requests
+3. Check for 4xx/5xx responses
+4. Report API failures
+```
+
+**What /dev-test catches for backend:**
+- 400 Bad Request (validation failures)
+- 401 Unauthorized (auth issues)
+- 403 Forbidden (permission issues)
+- 404 Not Found (wrong endpoints)
+- 500 Server Error (backend bugs)
+- CORS errors (misconfigured)
+- Timeout errors (slow queries)
+
+**Example test failure:**
+```markdown
+[Network] POST /api/auth/login returned 500
+Response: {"error":"Internal server error"}
+Likely cause: Database connection or missing env var
+```
+
+## Common Patterns
+
+### Database Query Patterns
+
+```typescript
+// Pagination
+const page = parseInt(req.query.page) || 1;
+const limit = parseInt(req.query.limit) || 10;
+const offset = (page - 1) * limit;
+
+const items = await db.items.findMany({
+  skip: offset,
+  take: limit,
+  orderBy: { createdAt: 'desc' }
+});
+
+// Filtering
+const where = {};
+if (req.query.status) {
+  where.status = req.query.status;
+}
+
+// Include relations
+const post = await db.posts.findUnique({
+  where: { id },
+  include: { author: true, comments: true }
+});
+```
+
+### Transaction Pattern
+
+```typescript
+// When multiple operations must succeed together
+await db.$transaction(async (tx) => {
+  const user = await tx.users.create({ data: userData });
+  await tx.profiles.create({ data: { userId: user.id } });
+  await tx.settings.create({ data: { userId: user.id } });
+  return user;
+});
+```
+
+### Soft Delete Pattern
+
+```typescript
+// Don't actually delete, mark as deleted
+await db.posts.update({
+  where: { id },
+  data: {
+    deletedAt: new Date(),
+    status: 'deleted'
+  }
+});
+
+// Query excludes deleted
+const posts = await db.posts.findMany({
+  where: { deletedAt: null }
+});
+```
+
+## Security Checklist
+
+```
+[ ] Input validated before use
+[ ] SQL/NoSQL injection prevented (use parameterized queries)
+[ ] Auth checked on protected routes
+[ ] Permissions verified for actions
+[ ] Sensitive data not logged
+[ ] Passwords hashed (never plain text)
+[ ] Rate limiting on auth endpoints
+[ ] CORS configured correctly
+[ ] No secrets in code (use env vars)
+```
+
+## Debugging
+
+### API Not Responding
+
+```bash
+# Check if server running
+curl http://localhost:3000/health
+
+# Check logs
+tail -f logs/server.log
+
+# Check port in use
+lsof -i :3000
+```
+
+### Database Issues
+
+```bash
+# Check connection
+npx prisma db pull  # Prisma
+psql -c "SELECT 1"  # PostgreSQL
+
+# Check migrations
+npx prisma migrate status
+```
+
+### Auth Issues
+
+```bash
+# Test token validity
+curl http://localhost:3000/api/users/me \
+  -H "Authorization: Bearer $TOKEN"
+
+# Decode JWT (for debugging only)
+echo $TOKEN | cut -d. -f2 | base64 -d
+```
+
+## Tech-Specific References
+
+Load additional patterns based on detected tech:
+
+| Tech | Reference File |
+|------|---------------|
+| Directus | `references/directus.md` |
+| Node/Express | `references/node.md` |
+| Prisma | `references/prisma.md` |
+| PostgreSQL | `references/postgresql.md` |
+| Supabase | `references/supabase.md` |
+
+These files contain tech-specific patterns, gotchas, and best practices. Add them as your projects use different stacks.