@malamute/ai-rules 1.0.0 → 1.2.0

package/configs/_shared/.claude/rules/devops/docker.md

@@ -0,0 +1,275 @@
+---
+paths:
+  - "**/Dockerfile"
+  - "**/docker-compose*.yml"
+  - "**/.dockerignore"
+---
+
+# Docker Best Practices
+
+## Dockerfile Principles
+
+### Multi-stage Builds
+
+Always use multi-stage builds to minimize image size:
+
+```dockerfile
+# Stage 1: Build
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# Stage 2: Production
+FROM node:20-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+USER node
+EXPOSE 3000
+CMD ["node", "dist/main.js"]
+```
+
+### Layer Optimization
+
+Order from least to most frequently changed:
+
+```dockerfile
+# 1. Base image (rarely changes)
+FROM node:20-alpine
+
+# 2. System dependencies (rarely changes)
+RUN apk add --no-cache dumb-init
+
+# 3. App dependencies (changes with package.json)
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+
+# 4. App code (changes frequently)
+COPY . .
+
+# 5. Build (if needed)
+RUN npm run build
+```
+
+### Security
+
+```dockerfile
+# Use specific version, not :latest
+FROM node:20.10.0-alpine
+
+# Run as non-root user
+RUN addgroup -g 1001 appgroup && \
+    adduser -u 1001 -G appgroup -s /bin/sh -D appuser
+USER appuser
+
+# Don't expose unnecessary ports
+EXPOSE 3000
+
+# Use read-only filesystem where possible
+# (set in docker-compose or runtime)
+```
+
+## .dockerignore
+
+Always include:
+
+```
+node_modules
+npm-debug.log
+.git
+.gitignore
+.env
+.env.*
+*.md
+.vscode
+.idea
+coverage
+dist
+.nx
+tmp
+```
+
+## Docker Compose
+
+### Development
+
+```yaml
+# docker-compose.yml
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: development
+    volumes:
+      - .:/app
+      - /app/node_modules  # Prevent overwriting
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=development
+    depends_on:
+      - db
+      - redis
+
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: dev
+      POSTGRES_PASSWORD: dev
+      POSTGRES_DB: app_dev
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    ports:
+      - "5432:5432"
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+
+volumes:
+  postgres_data:
+```
+
+### Production
+
+```yaml
+# docker-compose.prod.yml
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: production
+    restart: unless-stopped
+    read_only: true
+    security_opt:
+      - no-new-privileges:true
+    environment:
+      - NODE_ENV=production
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+    deploy:
+      resources:
+        limits:
+          cpus: '1'
+          memory: 512M
+```
+
+## Framework-Specific Patterns
+
+### Node.js / NestJS / Next.js
+
+```dockerfile
+FROM node:20-alpine AS base
+RUN apk add --no-cache libc6-compat
+WORKDIR /app
+
+FROM base AS deps
+COPY package*.json ./
+RUN npm ci
+
+FROM base AS builder
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+
+FROM base AS runner
+ENV NODE_ENV=production
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 app
+COPY --from=builder --chown=app:nodejs /app/dist ./dist
+COPY --from=builder --chown=app:nodejs /app/node_modules ./node_modules
+USER app
+EXPOSE 3000
+CMD ["node", "dist/main.js"]
+```
+
+### Python / FastAPI
+
+```dockerfile
+FROM python:3.12-slim AS base
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+FROM base AS builder
+RUN pip install poetry
+WORKDIR /app
+COPY pyproject.toml poetry.lock ./
+RUN poetry export -f requirements.txt --output requirements.txt
+
+FROM base AS runner
+WORKDIR /app
+COPY --from=builder /app/requirements.txt .
+RUN pip install -r requirements.txt
+COPY . .
+RUN useradd -m appuser && chown -R appuser:appuser /app
+USER appuser
+EXPOSE 8000
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+### .NET
+
+```dockerfile
+FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
+WORKDIR /src
+COPY *.csproj ./
+RUN dotnet restore
+COPY . .
+RUN dotnet publish -c Release -o /app/publish
+
+FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
+WORKDIR /app
+COPY --from=build /app/publish .
+RUN useradd -m appuser && chown -R appuser:appuser /app
+USER appuser
+EXPOSE 8080
+ENTRYPOINT ["dotnet", "App.dll"]
+```
+
+## Health Checks
+
+Always implement health endpoints:
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+  CMD curl -f http://localhost:3000/health || exit 1
+```
+
+## Environment Variables
+
+```dockerfile
+# Build-time args
+ARG NODE_ENV=production
+ARG APP_VERSION
+
+# Runtime environment
+ENV NODE_ENV=${NODE_ENV} \
+    APP_VERSION=${APP_VERSION}
+
+# Never put secrets in Dockerfile!
+# Use: docker run -e SECRET=xxx or docker-compose with env_file
+```
+
+## Anti-patterns
+
+- Using `:latest` tag
+- Running as root
+- Copying entire context before installing deps
+- Not using multi-stage builds
+- Hardcoding secrets in Dockerfile
+- Not setting resource limits
+- Missing health checks
+- Not using .dockerignore

package/configs/_shared/.claude/rules/devops/nx.md

@@ -0,0 +1,194 @@
+---
+paths:
+  - "libs/**/*"
+  - "apps/**/*"
+  - "nx.json"
+  - "project.json"
+  - "*.ts"
+---
+
+# Nx Monorepo Rules
+
+## Project Structure
+
+```
+workspace/
+├── apps/                    # Deployable applications
+│   ├── web/                 # Main app
+│   └── web-e2e/             # E2E tests
+├── libs/                    # Reusable libraries
+│   ├── shared/              # Cross-domain (ui, util)
+│   └── [domain]/            # Domain-specific
+│       ├── feature-*/       # Smart components, pages
+│       ├── ui-*/            # Dumb/presentational components
+│       ├── data-access-*/   # State, API services
+│       └── util-*/          # Pure functions, helpers
+├── nx.json
+└── tsconfig.base.json
+```
+
+## Library Types
+
+| Type | Purpose | Can Import |
+|------|---------|------------|
+| `feature` | Smart components, routing, pages | ui, data-access, util |
+| `ui` | Presentational components | util only |
+| `data-access` | State management, API calls | util only |
+| `util` | Pure functions, types, constants | util only |
+
+## Naming Convention
+
+```
+libs/[scope]/[type]-[name]
+
+# Examples
+libs/users/feature-list        # User list page
+libs/users/ui-avatar           # Avatar component
+libs/users/data-access         # User state/API
+libs/users/util-permissions    # Permission helpers
+libs/shared/ui-button          # Shared button
+libs/shared/util-format        # Format utilities
+```
+
+## Tags & Boundaries
+
+### nx.json
+
+```json
+{
+  "targetDefaults": {
+    "build": { "dependsOn": ["^build"] },
+    "test": { "dependsOn": ["build"] }
+  }
+}
+```
+
+### project.json tags
+
+```json
+{
+  "tags": ["scope:users", "type:feature"]
+}
+```
+
+### .eslintrc.json boundaries
+
+```json
+{
+  "rules": {
+    "@nx/enforce-module-boundaries": [
+      "error",
+      {
+        "depConstraints": [
+          { "sourceTag": "type:feature", "onlyDependOnLibsWithTags": ["type:ui", "type:data-access", "type:util"] },
+          { "sourceTag": "type:ui", "onlyDependOnLibsWithTags": ["type:util"] },
+          { "sourceTag": "type:data-access", "onlyDependOnLibsWithTags": ["type:util"] },
+          { "sourceTag": "type:util", "onlyDependOnLibsWithTags": ["type:util"] },
+          { "sourceTag": "scope:shared", "onlyDependOnLibsWithTags": ["scope:shared"] },
+          { "sourceTag": "scope:users", "onlyDependOnLibsWithTags": ["scope:users", "scope:shared"] }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Dependency Flow
+
+```
+┌─────────────────────────────────────────────┐
+│                   apps/                      │
+│        (can import any lib)                  │
+└─────────────────────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────┐
+│              feature libs                    │
+│   (pages, smart components, routing)         │
+└─────────────────────────────────────────────┘
+            │                │
+            ▼                ▼
+┌──────────────────┐  ┌──────────────────┐
+│     ui libs      │  │  data-access     │
+│  (presentational)│  │  (state, API)    │
+└──────────────────┘  └──────────────────┘
+            │                │
+            └───────┬────────┘
+                    ▼
+┌─────────────────────────────────────────────┐
+│               util libs                      │
+│    (pure functions, types, constants)        │
+└─────────────────────────────────────────────┘
+```
+
+## Commands Reference
+
+| Command | Description |
+|---------|-------------|
+| `nx affected -t test` | Test affected projects |
+| `nx affected -t build` | Build affected projects |
+| `nx affected -t lint` | Lint affected projects |
+| `nx run-many -t test --all` | Test all projects |
+| `nx graph` | Visualize dependency graph |
+| `nx reset` | Clear cache |
+
+## Generator Commands
+
+| Command | Description |
+|---------|-------------|
+| `nx g @nx/angular:lib [name]` | Generate Angular library |
+| `nx g @nx/angular:component [name]` | Generate component |
+| `nx g @nx/angular:service [name]` | Generate service |
+| `nx g remove [name]` | Remove project |
+| `nx g move --project [name] [dest]` | Move project |
+
+## Import Paths
+
+Always use workspace paths, never relative imports across libs:
+
+```typescript
+// GOOD - workspace path
+import { UserService } from '@myorg/users/data-access';
+import { ButtonComponent } from '@myorg/shared/ui-button';
+
+// BAD - relative cross-lib import
+import { UserService } from '../../../users/data-access/src';
+```
+
+## Anti-patterns
+
+- Never import from `apps/` into `libs/`
+- Never create circular dependencies between libs
+- Never import `feature` into `ui` or `data-access`
+- Never import domain-specific into `shared/` scope
+- Never skip the public API (`index.ts`)
+
+## Caching
+
+Nx caches build/test results. To leverage:
+
+```json
+// nx.json
+{
+  "tasksRunnerOptions": {
+    "default": {
+      "runner": "nx/tasks-runners/default",
+      "options": {
+        "cacheableOperations": ["build", "lint", "test", "e2e"]
+      }
+    }
+  }
+}
+```
+
+## Affected Commands
+
+Always use `affected` in CI:
+
+```bash
+# Only test what changed
+nx affected -t test --base=main --head=HEAD
+
+# Only build what changed
+nx affected -t build --base=main --head=HEAD
+```

package/configs/_shared/.claude/rules/domain/backend/api-design.md

@@ -0,0 +1,203 @@
+---
+paths:
+  - "**/controllers/**"
+  - "**/routes/**"
+  - "**/routers/**"
+  - "**/endpoints/**"
+  - "**/*.controller.ts"
+  - "**/*_router.py"
+---
+
+# API Design Principles
+
+## REST Conventions
+
+### HTTP Methods
+
+| Method | Usage | Idempotent | Response |
+|--------|-------|------------|----------|
+| `GET` | Read resource(s) | Yes | 200 + data |
+| `POST` | Create resource | No | 201 + created resource |
+| `PUT` | Full update | Yes | 200 + updated resource |
+| `PATCH` | Partial update | Yes | 200 + updated resource |
+| `DELETE` | Remove resource | Yes | 204 No Content |
+
+### URL Structure
+
+```
+GET    /api/v1/users          # List users
+GET    /api/v1/users/:id      # Get single user
+POST   /api/v1/users          # Create user
+PUT    /api/v1/users/:id      # Replace user
+PATCH  /api/v1/users/:id      # Update user fields
+DELETE /api/v1/users/:id      # Delete user
+
+# Nested resources (max 2 levels)
+GET    /api/v1/users/:id/orders
+POST   /api/v1/users/:id/orders
+
+# Actions (when CRUD doesn't fit)
+POST   /api/v1/users/:id/activate
+POST   /api/v1/orders/:id/cancel
+```
+
+### Naming Rules
+
+- Use **plural nouns**: `/users`, `/orders`, `/products`
+- Use **kebab-case**: `/user-profiles`, `/order-items`
+- Avoid verbs in URLs (use HTTP methods instead)
+- Use query params for filtering: `/users?status=active&role=admin`
+
+## Response Format
+
+### Success Response
+
+```json
+{
+  "data": { ... },
+  "meta": {
+    "timestamp": "2024-01-15T10:30:00Z",
+    "requestId": "abc-123"
+  }
+}
+```
+
+### List Response with Pagination
+
+```json
+{
+  "data": [ ... ],
+  "meta": {
+    "total": 100,
+    "page": 1,
+    "pageSize": 20,
+    "totalPages": 5,
+    "hasNext": true,
+    "hasPrevious": false
+  }
+}
+```
+
+### Error Response (RFC 7807 Problem Details)
+
+```json
+{
+  "type": "https://api.example.com/errors/validation",
+  "title": "Validation Error",
+  "status": 400,
+  "detail": "One or more fields failed validation",
+  "instance": "/api/v1/users",
+  "errors": [
+    { "field": "email", "message": "Invalid email format" },
+    { "field": "age", "message": "Must be at least 18" }
+  ],
+  "traceId": "abc-123"
+}
+```
+
+## Status Codes
+
+| Code | When to Use |
+|------|-------------|
+| `200` | Successful GET, PUT, PATCH |
+| `201` | Successful POST (resource created) |
+| `204` | Successful DELETE (no content) |
+| `400` | Bad request (validation error) |
+| `401` | Unauthorized (not authenticated) |
+| `403` | Forbidden (authenticated but not allowed) |
+| `404` | Resource not found |
+| `409` | Conflict (duplicate resource) |
+| `422` | Unprocessable entity (business rule violation) |
+| `429` | Too many requests (rate limited) |
+| `500` | Internal server error |
+
+## Pagination
+
+### Offset-based (simple, for small datasets)
+
+```
+GET /api/v1/users?page=2&pageSize=20
+```
+
+### Cursor-based (performant, for large datasets)
+
+```
+GET /api/v1/users?cursor=eyJpZCI6MTAwfQ&limit=20
+```
+
+Response includes next cursor:
+```json
+{
+  "data": [...],
+  "meta": {
+    "nextCursor": "eyJpZCI6MTIwfQ",
+    "hasMore": true
+  }
+}
+```
+
+## Filtering & Sorting
+
+```
+# Filtering
+GET /api/v1/users?status=active&role=admin
+GET /api/v1/orders?createdAt[gte]=2024-01-01&createdAt[lte]=2024-12-31
+
+# Sorting
+GET /api/v1/users?sort=createdAt:desc
+GET /api/v1/users?sort=lastName:asc,firstName:asc
+
+# Field selection (sparse fieldsets)
+GET /api/v1/users?fields=id,name,email
+```
+
+## Versioning
+
+### URL Path (recommended)
+
+```
+/api/v1/users
+/api/v2/users
+```
+
+### Header-based (alternative)
+
+```
+Accept: application/vnd.api+json; version=1
+```
+
+## Rate Limiting
+
+Include headers in response:
+
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 95
+X-RateLimit-Reset: 1640000000
+Retry-After: 60  (when 429)
+```
+
+## HATEOAS (optional, for discoverability)
+
+```json
+{
+  "data": {
+    "id": "123",
+    "name": "John"
+  },
+  "links": {
+    "self": "/api/v1/users/123",
+    "orders": "/api/v1/users/123/orders",
+    "profile": "/api/v1/users/123/profile"
+  }
+}
+```
+
+## Anti-patterns
+
+- Verbs in URLs: `/api/getUsers` → `/api/users`
+- Singular nouns: `/api/user/123` → `/api/users/123`
+- Deeply nested: `/api/users/1/orders/2/items/3` → `/api/order-items/3`
+- Inconsistent casing: `/api/userProfiles` → `/api/user-profiles`
+- Returning 200 for errors
+- Exposing internal IDs or sensitive data