@plazmodium/odin 0.3.3-beta → 0.3.5-beta

package/builtin/skills/backend/golang-gin/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: golang-gin
+description: Gin HTTP web framework for building high-performance Go APIs
+category: backend
+version: "1.9+"
+compatible_with:
+  - postgresql
+  - mongodb
+  - redis
+  - rest-api
+  - grpc
+---
+
+# Go + Gin
+
+## Overview
+
+Gin is a high-performance HTTP web framework for Go. It provides routing, middleware, JSON validation, and rendering with minimal overhead.
+
+## Project Structure
+
+```
+cmd/
+├── server/
+│   └── main.go              # Entry point
+internal/
+├── config/
+│   └── config.go            # Configuration loading
+├── handler/
+│   ├── auth.go              # Auth handlers
+│   └── user.go              # User handlers
+├── middleware/
+│   ├── auth.go              # JWT middleware
+│   └── cors.go              # CORS middleware
+├── model/
+│   └── user.go              # Domain models + DB structs
+├── repository/
+│   └── user_repo.go         # Database access
+├── service/
+│   └── user_service.go      # Business logic
+└── router/
+    └── router.go            # Route registration
+```
+
+## Core Patterns
+
+### Router Setup
+
+```go
+func SetupRouter(userHandler *handler.UserHandler, authMW gin.HandlerFunc) *gin.Engine {
+    r := gin.Default()
+
+    r.Use(middleware.CORS())
+
+    api := r.Group("/api/v1")
+    {
+        auth := api.Group("/auth")
+        auth.POST("/login", userHandler.Login)
+        auth.POST("/register", userHandler.Register)
+
+        users := api.Group("/users")
+        users.Use(authMW)
+        users.GET("/:id", userHandler.GetByID)
+        users.PUT("/:id", userHandler.Update)
+    }
+
+    return r
+}
+```
+
+### Handlers
+
+```go
+type UserHandler struct {
+    service service.UserService
+}
+
+func (h *UserHandler) GetByID(c *gin.Context) {
+    id := c.Param("id")
+    user, err := h.service.GetByID(c.Request.Context(), id)
+    if err != nil {
+        c.JSON(http.StatusNotFound, gin.H{"error": "user not found"})
+        return
+    }
+    c.JSON(http.StatusOK, user)
+}
+
+// Request binding with validation
+type CreateUserRequest struct {
+    Email    string `json:"email" binding:"required,email"`
+    Password string `json:"password" binding:"required,min=8"`
+    Name     string `json:"name" binding:"required,max=100"`
+}
+
+func (h *UserHandler) Register(c *gin.Context) {
+    var req CreateUserRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+        return
+    }
+    // ... create user
+}
+```
+
+### Middleware
+
+```go
+func AuthMiddleware(secret string) gin.HandlerFunc {
+    return func(c *gin.Context) {
+        token := c.GetHeader("Authorization")
+        if token == "" {
+            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "missing token"})
+            return
+        }
+        claims, err := validateJWT(strings.TrimPrefix(token, "Bearer "), secret)
+        if err != nil {
+            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "invalid token"})
+            return
+        }
+        c.Set("userID", claims.Subject)
+        c.Next()
+    }
+}
+```
+
+## Best Practices
+
+1. **Use `internal/`** — prevents external packages from importing your business logic
+2. **Dependency injection** — pass dependencies via struct constructors, not globals
+3. **Context propagation** — always pass `c.Request.Context()` to service/repo layers
+4. **Graceful shutdown** — use `signal.NotifyContext` for clean shutdown
+5. **Error wrapping** — use `fmt.Errorf("...: %w", err)` for error chains
+6. **Structured logging** — use `slog` (Go 1.21+) or `zerolog`
+7. **Interface-based repos** — define interfaces in the consumer package, not the provider
+
+## Gotchas
+
+- **Gin's `c.JSON` doesn't return** — always `return` after error responses
+- **Binding validation tags** — `binding:"required"` only works with `ShouldBind*`
+- **Goroutine safety** — don't share `gin.Context` across goroutines; copy needed values first
+- **`c.Param` vs `c.Query`** — path params vs query strings are different methods

package/builtin/skills/backend/nodejs-express/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: nodejs-express
+description: Node.js with Express.js framework expertise for building REST APIs, middleware patterns, and server-side applications
+category: backend
+version: "4.x"
+compatible_with:
+  - postgresql
+  - prisma-orm
+  - supabase
+  - jest
+  - typescript
+---
+
+# Node.js + Express Development
+
+## Overview
+
+Express.js is a minimal, flexible Node.js web application framework providing robust features for building web and mobile applications.
+
+## Project Structure
+
+```
+src/
+├── index.ts              # Entry point
+├── app.ts                # Express app setup
+├── routes/
+│   ├── index.ts          # Route aggregator
+│   ├── auth.routes.ts    # Auth endpoints
+│   └── user.routes.ts    # User endpoints
+├── controllers/
+│   ├── auth.controller.ts
+│   └── user.controller.ts
+├── services/
+│   ├── auth.service.ts
+│   └── user.service.ts
+├── middleware/
+│   ├── auth.middleware.ts
+│   ├── error.middleware.ts
+│   └── validation.middleware.ts
+├── models/               # Database models
+├── utils/
+│   └── asyncHandler.ts   # Async error wrapper
+└── types/
+    └── index.ts          # TypeScript types
+```
+
+## Core Patterns
+
+### App Setup
+
+```typescript
+// src/app.ts
+import express from 'express';
+import cors from 'cors';
+import helmet from 'helmet';
+import { errorHandler } from './middleware/error.middleware';
+import routes from './routes';
+
+const app = express();
+
+// Security middleware
+app.use(helmet());
+app.use(cors());
+
+// Body parsing
+app.use(express.json());
+app.use(express.urlencoded({ extended: true }));
+
+// Routes
+app.use('/api/v1', routes);
+
+// Error handling (must be last)
+app.use(errorHandler);
+
+export default app;
+```
+
+### Async Handler Pattern
+
+```typescript
+// src/utils/asyncHandler.ts
+import { Request, Response, NextFunction } from 'express';
+
+type AsyncFunction = (
+  req: Request,
+  res: Response,
+  next: NextFunction
+) => Promise<any>;
+
+export const asyncHandler = (fn: AsyncFunction) => {
+  return (req: Request, res: Response, next: NextFunction) => {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+};
+```
+
+### Controller Pattern
+
+```typescript
+// src/controllers/user.controller.ts
+import { Request, Response } from 'express';
+import { asyncHandler } from '../utils/asyncHandler';
+import * as userService from '../services/user.service';
+
+export const getUsers = asyncHandler(async (req: Request, res: Response) => {
+  const users = await userService.findAll();
+  res.json({ success: true, data: users });
+});
+
+export const getUserById = asyncHandler(async (req: Request, res: Response) => {
+  const user = await userService.findById(req.params.id);
+  if (!user) {
+    res.status(404).json({ success: false, error: 'User not found' });
+    return;
+  }
+  res.json({ success: true, data: user });
+});
+```
+
+### Route Definition
+
+```typescript
+// src/routes/user.routes.ts
+import { Router } from 'express';
+import { getUsers, getUserById, createUser } from '../controllers/user.controller';
+import { authenticate } from '../middleware/auth.middleware';
+import { validate } from '../middleware/validation.middleware';
+import { createUserSchema } from '../validators/user.validator';
+
+const router = Router();
+
+router.get('/', authenticate, getUsers);
+router.get('/:id', authenticate, getUserById);
+router.post('/', authenticate, validate(createUserSchema), createUser);
+
+export default router;
+```
+
+### Error Handling Middleware
+
+```typescript
+// src/middleware/error.middleware.ts
+import { Request, Response, NextFunction } from 'express';
+
+export class AppError extends Error {
+  constructor(
+    public statusCode: number,
+    public message: string,
+    public isOperational = true
+  ) {
+    super(message);
+    Object.setPrototypeOf(this, AppError.prototype);
+  }
+}
+
+export const errorHandler = (
+  err: Error,
+  req: Request,
+  res: Response,
+  next: NextFunction
+) => {
+  if (err instanceof AppError) {
+    return res.status(err.statusCode).json({
+      success: false,
+      error: err.message
+    });
+  }
+
+  console.error('Unexpected error:', err);
+  res.status(500).json({
+    success: false,
+    error: 'Internal server error'
+  });
+};
+```
+
+### Auth Middleware
+
+```typescript
+// src/middleware/auth.middleware.ts
+import { Request, Response, NextFunction } from 'express';
+import jwt from 'jsonwebtoken';
+import { AppError } from './error.middleware';
+
+export interface AuthRequest extends Request {
+  user?: { id: string; email: string };
+}
+
+export const authenticate = (
+  req: AuthRequest,
+  res: Response,
+  next: NextFunction
+) => {
+  const authHeader = req.headers.authorization;
+
+  if (!authHeader?.startsWith('Bearer ')) {
+    throw new AppError(401, 'No token provided');
+  }
+
+  const token = authHeader.split(' ')[1];
+
+  try {
+    const decoded = jwt.verify(token, process.env.JWT_SECRET!) as {
+      id: string;
+      email: string;
+    };
+    req.user = decoded;
+    next();
+  } catch {
+    throw new AppError(401, 'Invalid token');
+  }
+};
+```
+
+## Best Practices
+
+1. **Always use asyncHandler** - Prevents unhandled promise rejections
+2. **Validate input** - Use Zod or Joi for request validation
+3. **Layer your code** - Routes → Controllers → Services → Models
+4. **Use TypeScript** - Type safety prevents runtime errors
+5. **Environment variables** - Never hardcode secrets
+6. **Error middleware last** - Must be registered after routes
+7. **Use HTTP status codes correctly** - 200, 201, 400, 401, 403, 404, 500
+
+## Common Response Format
+
+```typescript
+// Success
+{ success: true, data: {...} }
+
+// Error
+{ success: false, error: "Error message" }
+
+// Paginated
+{
+  success: true,
+  data: [...],
+  pagination: {
+    page: 1,
+    limit: 20,
+    total: 100,
+    totalPages: 5
+  }
+}
+```
+
+## Gotchas & Pitfalls
+
+- **Forgetting async error handling** - Always use asyncHandler or try-catch
+- **Middleware order matters** - Auth before routes, error handler last
+- **Not ending response** - Always call res.json(), res.send(), or next()
+- **Memory leaks** - Clean up listeners, close DB connections on shutdown
+- **CORS issues** - Configure cors() properly for your frontend domain
+
+## Integration Notes
+
+### With Prisma
+```typescript
+import { PrismaClient } from '@prisma/client';
+const prisma = new PrismaClient();
+
+// In service
+export const findAll = () => prisma.user.findMany();
+```
+
+### With Supabase
+```typescript
+import { createClient } from '@supabase/supabase-js';
+const supabase = createClient(SUPABASE_URL, SUPABASE_KEY);
+
+// In service
+export const findAll = async () => {
+  const { data, error } = await supabase.from('users').select('*');
+  if (error) throw new AppError(500, error.message);
+  return data;
+};
+```

package/builtin/skills/backend/nodejs-fastify/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: nodejs-fastify
+description: Fastify framework for building high-performance Node.js APIs with schema-based validation
+category: backend
+version: "4.x"
+compatible_with:
+  - postgresql
+  - prisma-orm
+  - mongodb
+  - redis
+  - rest-api
+  - typescript
+---
+
+# Node.js + Fastify
+
+## Overview
+
+Fastify is a high-performance Node.js web framework focused on developer experience and low overhead. It uses JSON Schema for request/response validation and serialization.
+
+## Project Structure
+
+```
+src/
+├── app.ts                   # Fastify instance + plugin registration
+├── server.ts                # Entry point (start server)
+├── plugins/
+│   ├── auth.ts              # Auth decorator/plugin
+│   └── database.ts          # DB connection plugin
+├── routes/
+│   ├── auth/
+│   │   ├── index.ts         # Route registration
+│   │   └── schema.ts        # JSON schemas
+│   └── users/
+│       ├── index.ts
+│       └── schema.ts
+├── services/
+│   └── user.service.ts      # Business logic
+├── types/
+│   └── index.ts             # TypeScript types
+└── tests/
+    └── routes/
+        └── auth.test.ts
+```
+
+## Core Patterns
+
+### App Setup
+
+```typescript
+import Fastify from 'fastify';
+
+const app = Fastify({
+  logger: true,
+  ajv: { customOptions: { removeAdditional: 'all' } },
+});
+
+// Register plugins
+await app.register(import('./plugins/database'));
+await app.register(import('./plugins/auth'));
+
+// Register routes
+await app.register(import('./routes/auth'), { prefix: '/auth' });
+await app.register(import('./routes/users'), { prefix: '/users' });
+
+export default app;
+```
+
+### Routes with Schema Validation
+
+```typescript
+import { FastifyPluginAsync } from 'fastify';
+
+const userRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.get('/:id', {
+    schema: {
+      params: { type: 'object', properties: { id: { type: 'string', format: 'uuid' } }, required: ['id'] },
+      response: {
+        200: {
+          type: 'object',
+          properties: {
+            id: { type: 'string' },
+            email: { type: 'string' },
+            name: { type: 'string' },
+          },
+        },
+      },
+    },
+    preHandler: [fastify.authenticate],
+    handler: async (request, reply) => {
+      const { id } = request.params as { id: string };
+      const user = await fastify.userService.getById(id);
+      if (!user) return reply.code(404).send({ error: 'Not found' });
+      return user;
+    },
+  });
+};
+
+export default userRoutes;
+```
+
+### Plugins (Decorators)
+
+```typescript
+import fp from 'fastify-plugin';
+
+export default fp(async (fastify) => {
+  const db = await connectToDatabase(fastify.config.DATABASE_URL);
+
+  fastify.decorate('db', db);
+  fastify.addHook('onClose', async () => { await db.close(); });
+});
+
+// Type augmentation
+declare module 'fastify' {
+  interface FastifyInstance {
+    db: Database;
+  }
+}
+```
+
+### Error Handling
+
+```typescript
+app.setErrorHandler((error, request, reply) => {
+  request.log.error(error);
+
+  if (error.validation) {
+    return reply.code(400).send({ error: 'Validation failed', details: error.validation });
+  }
+
+  reply.code(error.statusCode ?? 500).send({
+    error: error.message || 'Internal Server Error',
+  });
+});
+```
+
+## Best Practices
+
+1. **Schema-first** — define JSON Schema for all request/response; Fastify uses it for validation AND serialization (faster than manual serialization)
+2. **Encapsulation** — use plugins for encapsulated contexts; `fastify-plugin` for shared decorators
+3. **Type augmentation** — extend `FastifyInstance`/`FastifyRequest` for decorators
+4. **Autoload** — use `@fastify/autoload` to auto-register routes and plugins
+5. **Testing** — use `app.inject()` for integration tests (no real HTTP needed)
+6. **Hooks** — prefer `onRequest`/`preHandler` hooks over middleware for auth
+
+## Gotchas
+
+- **Plugin encapsulation** — decorators are scoped to the plugin unless wrapped with `fastify-plugin`
+- **Schema serialization** — response schemas strip undeclared properties (security feature, but surprising)
+- **Async/await** — always return or `await`; unhandled promise rejections crash the server
+- **Decorator timing** — decorators must be registered before routes that use them

package/builtin/skills/backend/python-django/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: python-django
+description: Django web framework patterns for building full-stack Python applications with batteries included
+category: backend
+version: "5.x"
+compatible_with:
+  - postgresql
+  - rest-api
+---
+
+# Python Django
+
+## Overview
+
+Django is a high-level Python web framework that follows the "batteries included" philosophy. It provides ORM, admin, auth, forms, and templating out of the box.
+
+## Project Structure
+
+```
+project/
+├── manage.py
+├── config/
+│   ├── settings/
+│   │   ├── base.py          # Shared settings
+│   │   ├── development.py   # Dev overrides
+│   │   └── production.py    # Prod overrides
+│   ├── urls.py              # Root URL conf
+│   └── wsgi.py
+├── apps/
+│   └── users/
+│       ├── models.py        # Database models
+│       ├── views.py         # View logic
+│       ├── serializers.py   # DRF serializers (if API)
+│       ├── urls.py          # App URL routes
+│       ├── admin.py         # Admin config
+│       ├── services.py      # Business logic
+│       ├── tests/
+│       │   ├── test_models.py
+│       │   └── test_views.py
+│       └── migrations/
+└── requirements/
+    ├── base.txt
+    └── dev.txt
+```
+
+## Core Patterns
+
+### Models
+
+```python
+from django.db import models
+from django.contrib.auth.models import AbstractUser
+
+class User(AbstractUser):
+    email = models.EmailField(unique=True)
+    bio = models.TextField(blank=True, default="")
+
+    USERNAME_FIELD = "email"
+    REQUIRED_FIELDS = ["username"]
+
+    class Meta:
+        ordering = ["-date_joined"]
+
+    def __str__(self):
+        return self.email
+```
+
+### Views (DRF)
+
+```python
+from rest_framework import viewsets, permissions, status
+from rest_framework.decorators import action
+from rest_framework.response import Response
+
+class UserViewSet(viewsets.ModelViewSet):
+    queryset = User.objects.all()
+    serializer_class = UserSerializer
+    permission_classes = [permissions.IsAuthenticated]
+
+    def get_queryset(self):
+        return self.queryset.filter(is_active=True)
+
+    @action(detail=False, methods=["get"])
+    def me(self, request):
+        serializer = self.get_serializer(request.user)
+        return Response(serializer.data)
+```
+
+### Services Layer
+
+```python
+# apps/users/services.py — keep business logic out of views
+class UserService:
+    @staticmethod
+    def create_user(email: str, password: str, **kwargs) -> User:
+        user = User.objects.create_user(email=email, password=password, **kwargs)
+        send_welcome_email.delay(user.id)  # Celery task
+        return user
+```
+
+### Querysets
+
+```python
+# Avoid N+1 queries
+users = User.objects.select_related("profile").prefetch_related("groups").filter(is_active=True)
+
+# Use F() and Q() for complex queries
+from django.db.models import F, Q
+Product.objects.filter(Q(stock__gt=0) | Q(preorder=True)).order_by(F("price").desc())
+```
+
+## Best Practices
+
+1. **Fat models, thin views** — or better: fat services, thin everything else
+2. **Custom User model** — always define one from the start (`AbstractUser`)
+3. **select_related / prefetch_related** — prevent N+1 queries
+4. **Migrations** — never edit auto-generated migrations; create new ones
+5. **Settings split** — separate base/dev/prod settings files
+6. **Signals sparingly** — prefer explicit service calls over implicit signals
+7. **Django REST Framework** — use for API projects; serializers for validation
+
+## Gotchas
+
+- **Circular imports** — use string references in ForeignKey (`"app.Model"`)
+- **Migration conflicts** — in team settings, use `--merge` to resolve
+- **QuerySet laziness** — querysets aren't evaluated until iterated; chain freely
+- **SECRET_KEY exposure** — never commit to VCS; use environment variables
+- **Timezone handling** — always use `USE_TZ = True` and `django.utils.timezone`