oh-my-customcodex 0.1.0

package/templates/guides/docker/compose-best-practices.md

@@ -0,0 +1,284 @@
+# Docker Compose Best Practices
+
+> Source: https://docs.docker.com/compose/compose-file/best-practices/
+
+## File Structure
+
+```yaml
+version: "3.8"
+
+services:
+  # Application services
+  app:
+    ...
+
+  # Infrastructure services
+  db:
+    ...
+
+volumes:
+  # Named volumes
+
+networks:
+  # Custom networks
+```
+
+## Service Configuration
+
+### Build Configuration
+
+```yaml
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: production
+      args:
+        - NODE_ENV=production
+```
+
+### Environment Variables
+
+```yaml
+services:
+  app:
+    # From file
+    env_file:
+      - .env
+      - .env.local
+
+    # Inline
+    environment:
+      - DATABASE_URL=${DATABASE_URL}
+      - NODE_ENV=production
+```
+
+### Dependencies
+
+```yaml
+services:
+  app:
+    depends_on:
+      db:
+        condition: service_healthy
+      redis:
+        condition: service_started
+```
+
+### Health Checks
+
+```yaml
+services:
+  db:
+    image: postgres:16
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+```
+
+### Resource Limits
+
+```yaml
+services:
+  app:
+    deploy:
+      resources:
+        limits:
+          cpus: "1"
+          memory: 512M
+        reservations:
+          cpus: "0.5"
+          memory: 256M
+```
+
+## Volumes
+
+### Named Volumes
+
+```yaml
+services:
+  db:
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+volumes:
+  postgres_data:
+    driver: local
+```
+
+### Bind Mounts (Development)
+
+```yaml
+services:
+  app:
+    volumes:
+      - ./src:/app/src:ro
+      - ./config:/app/config:ro
+```
+
+## Networks
+
+### Custom Networks
+
+```yaml
+services:
+  app:
+    networks:
+      - frontend
+      - backend
+
+  db:
+    networks:
+      - backend
+
+networks:
+  frontend:
+  backend:
+    internal: true
+```
+
+## Multiple Environments
+
+### Override Files
+
+```bash
+# Base configuration
+docker-compose.yml
+
+# Development overrides
+docker-compose.override.yml
+
+# Production overrides
+docker-compose.prod.yml
+
+# Usage
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up
+```
+
+### Example: Production
+
+```yaml
+# docker-compose.prod.yml
+services:
+  app:
+    build:
+      target: production
+    restart: always
+    deploy:
+      replicas: 3
+      resources:
+        limits:
+          cpus: "1"
+          memory: 1G
+
+  db:
+    restart: always
+    volumes:
+      - /mnt/data/postgres:/var/lib/postgresql/data
+```
+
+### Example: Development
+
+```yaml
+# docker-compose.override.yml
+services:
+  app:
+    build:
+      target: development
+    volumes:
+      - ./src:/app/src
+    environment:
+      - DEBUG=true
+    ports:
+      - "3000:3000"
+      - "9229:9229"  # debugger
+```
+
+## Complete Example
+
+```yaml
+version: "3.8"
+
+services:
+  app:
+    build:
+      context: .
+      target: production
+    restart: unless-stopped
+    environment:
+      - DATABASE_URL=postgresql://user:pass@db:5432/myapp
+      - REDIS_URL=redis://redis:6379
+    ports:
+      - "8080:8080"
+    depends_on:
+      db:
+        condition: service_healthy
+      redis:
+        condition: service_started
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    deploy:
+      resources:
+        limits:
+          cpus: "2"
+          memory: 1G
+    networks:
+      - frontend
+      - backend
+
+  db:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    environment:
+      - POSTGRES_USER=user
+      - POSTGRES_PASSWORD=pass
+      - POSTGRES_DB=myapp
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U user -d myapp"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - backend
+
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    command: redis-server --appendonly yes
+    volumes:
+      - redis_data:/data
+    networks:
+      - backend
+
+  nginx:
+    image: nginx:1.25-alpine
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./nginx.conf:/etc/nginx/nginx.conf:ro
+      - ./certs:/etc/nginx/certs:ro
+    depends_on:
+      - app
+    networks:
+      - frontend
+
+volumes:
+  postgres_data:
+  redis_data:
+
+networks:
+  frontend:
+  backend:
+    internal: true
+```

package/templates/guides/docker/dockerfile-best-practices.md

@@ -0,0 +1,262 @@
+# Dockerfile Best Practices
+
+> Source: https://docs.docker.com/develop/develop-images/dockerfile_best-practices/
+
+## General Guidelines
+
+### Create Ephemeral Containers
+
+Containers should be ephemeral - can be stopped, destroyed, and rebuilt with minimal setup.
+
+### Understand Build Context
+
+```bash
+# Entire directory sent to daemon
+docker build .
+
+# Use .dockerignore to exclude files
+# .dockerignore
+.git
+node_modules
+*.md
+```
+
+### Use Multi-Stage Builds
+
+```dockerfile
+# Build stage
+FROM golang:1.21 AS builder
+WORKDIR /app
+COPY . .
+RUN go build -o myapp
+
+# Runtime stage
+FROM alpine:3.19
+COPY --from=builder /app/myapp /usr/local/bin/
+CMD ["myapp"]
+```
+
+## Dockerfile Instructions
+
+### FROM
+
+```dockerfile
+# Pin versions
+FROM ubuntu:22.04
+
+# Use digest for reproducibility
+FROM node:20@sha256:abc123...
+
+# Use official images
+FROM python:3.12-slim
+```
+
+### RUN
+
+```dockerfile
+# Combine commands
+RUN apt-get update && apt-get install -y \
+    curl \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Use BuildKit cache
+RUN --mount=type=cache,target=/root/.cache/pip \
+    pip install -r requirements.txt
+```
+
+### CMD vs ENTRYPOINT
+
+```dockerfile
+# CMD: Default command (can be overridden)
+CMD ["python", "app.py"]
+
+# ENTRYPOINT: Fixed command
+ENTRYPOINT ["python"]
+CMD ["app.py"]
+
+# Combined
+ENTRYPOINT ["/docker-entrypoint.sh"]
+CMD ["postgres"]
+```
+
+### COPY vs ADD
+
+```dockerfile
+# Prefer COPY (more explicit)
+COPY requirements.txt .
+
+# ADD only for tar extraction or URLs
+ADD archive.tar.gz /app/
+```
+
+### EXPOSE
+
+```dockerfile
+# Documentation only
+EXPOSE 8080
+EXPOSE 443/tcp
+```
+
+### ENV
+
+```dockerfile
+ENV APP_HOME=/app \
+    PATH=$APP_HOME/bin:$PATH
+
+WORKDIR $APP_HOME
+```
+
+### VOLUME
+
+```dockerfile
+# Named mount point
+VOLUME /data
+```
+
+### USER
+
+```dockerfile
+# Create non-root user
+RUN groupadd -r app && useradd -r -g app app
+USER app
+
+# Or use existing
+USER nobody
+```
+
+### WORKDIR
+
+```dockerfile
+# Always use absolute paths
+WORKDIR /app
+WORKDIR /app/src
+```
+
+### HEALTHCHECK
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost/ || exit 1
+```
+
+## Layer Optimization
+
+### Order Matters
+
+```dockerfile
+# 1. Install dependencies (changes rarely)
+COPY package.json package-lock.json ./
+RUN npm ci
+
+# 2. Copy source (changes often)
+COPY . .
+
+# 3. Build
+RUN npm run build
+```
+
+### Combine RUN Commands
+
+```dockerfile
+# Good: Single layer
+RUN apt-get update && \
+    apt-get install -y python3 && \
+    rm -rf /var/lib/apt/lists/*
+
+# Bad: Multiple layers
+RUN apt-get update
+RUN apt-get install -y python3
+RUN rm -rf /var/lib/apt/lists/*
+```
+
+## Security Best Practices
+
+### Don't Run as Root
+
+```dockerfile
+FROM node:20
+
+RUN groupadd -r nodejs && useradd -r -g nodejs nodejs
+USER nodejs
+
+COPY --chown=nodejs:nodejs . .
+```
+
+### Don't Store Secrets
+
+```dockerfile
+# Bad: Secret in image
+ENV API_KEY=secret123
+
+# Good: Pass at runtime
+# docker run -e API_KEY=secret123 myapp
+```
+
+### Use Official Images
+
+```dockerfile
+# Official and verified
+FROM nginx:1.25
+FROM postgres:16
+
+# Minimal images
+FROM gcr.io/distroless/static
+FROM alpine:3.19
+```
+
+## Example Dockerfiles
+
+### Node.js
+
+```dockerfile
+FROM node:20-slim AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:20-slim
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+USER node
+EXPOSE 3000
+CMD ["node", "dist/server.js"]
+```
+
+### Python
+
+```dockerfile
+FROM python:3.12-slim AS builder
+WORKDIR /app
+RUN pip install --user pipenv
+COPY Pipfile Pipfile.lock ./
+RUN pipenv install --system --deploy
+
+FROM python:3.12-slim
+WORKDIR /app
+COPY --from=builder /root/.local /root/.local
+COPY . .
+ENV PATH=/root/.local/bin:$PATH
+USER nobody
+EXPOSE 8000
+CMD ["gunicorn", "-b", "0.0.0.0:8000", "app:app"]
+```
+
+### Go
+
+```dockerfile
+FROM golang:1.21-alpine AS builder
+WORKDIR /app
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 GOOS=linux go build -o /app/server
+
+FROM scratch
+COPY --from=builder /app/server /server
+EXPOSE 8080
+ENTRYPOINT ["/server"]
+```

package/templates/guides/docker/index.yaml

@@ -0,0 +1,26 @@
+# Docker Guide
+
+metadata:
+  name: docker
+  description: Docker containerization reference documentation
+
+source:
+  type: external
+  origin: docker.com
+  urls:
+    - https://docs.docker.com/
+    - https://docs.docker.com/develop/develop-images/dockerfile_best-practices/
+    - https://docs.docker.com/compose/compose-file/best-practices/
+  last_fetched: "2026-01-22"
+
+documents:
+  - name: dockerfile-best-practices
+    path: ./dockerfile-best-practices.md
+    description: Dockerfile best practices
+
+  - name: compose-best-practices
+    path: ./compose-best-practices.md
+    description: Docker Compose best practices
+
+used_by:
+  - infra-docker-expert

package/templates/guides/drizzle-orm/README.md

@@ -0,0 +1,69 @@
+# Drizzle ORM: sql Template Literal Pitfalls
+
+## The Bug: Column References in Subqueries
+
+When using Drizzle ORM's `sql` template literals, `${table.column}` generates a **bare column name without the table qualifier**. This causes silent semantic errors inside aliased subqueries.
+
+### Symptom
+
+```typescript
+// Code
+sql`SELECT ${agentInvocations.errorSummary} as sub_es
+    FROM ${agentInvocations} AS ai2
+    WHERE ai2.agent_type = ${agentInvocations.agentType}`
+
+// Generated SQL (WRONG)
+SELECT "error_summary" as sub_es
+FROM "agent_invocations" AS ai2
+WHERE ai2.agent_type = "agent_type"  -- "agent_type" becomes a literal string, always true!
+```
+
+`${agentInvocations.agentType}` expands to the **quoted column name** `"agent_type"` — not the value of the column. The `WHERE` clause compares `ai2.agent_type = "agent_type"`, which SQLite treats as a string literal match — always true for rows where `agent_type` equals the string `"agent_type"`.
+
+### Why Reviewers Miss It
+
+- The code *looks* correct — you see `agentInvocations.agentType` and assume it's a column reference.
+- Drizzle's `${table.column}` syntax works fine in top-level queries where table context is unambiguous.
+- The bug only manifests inside subqueries with table aliases (`AS ai2`) — normal queries pass.
+- No compile-time error; the SQL executes but returns wrong results.
+
+## The Fix: Raw SQL for Subquery Internal References
+
+Use raw SQL strings for column references *inside* aliased subqueries. Reserve `${table.column}` only for Drizzle's top-level query builder where it resolves correctly.
+
+```typescript
+// CORRECT: raw SQL column references inside aliased subquery
+sql`SELECT ai2.error_summary as sub_es
+    FROM ${agentInvocations} AS ai2
+    WHERE ai2.agent_type = ${agentInvocations}.agent_type`
+```
+
+Note: `${agentInvocations}` (the table object itself) still correctly expands to the table name and is safe to use for the `FROM` clause. Only *column* references inside subqueries must be written as raw SQL.
+
+## Decision Table
+
+| Context | Pattern | Safe? |
+|---------|---------|-------|
+| Top-level `FROM` clause | `${table}` | ✅ Yes |
+| Top-level `WHERE` with parameterized value | `${value}` | ✅ Yes (auto-parameterized) |
+| Top-level `SELECT` column | `${table.column}` | ✅ Yes |
+| Inside aliased subquery `SELECT` | `${table.column}` | ❌ No — bare column name |
+| Inside aliased subquery `WHERE` comparison | `${table.column}` | ❌ No — string literal, not column ref |
+| Inside aliased subquery (fixed) | `alias.column_name` | ✅ Yes |
+
+## Verification
+
+Use `.toSQL()` to inspect generated SQL before running:
+
+```typescript
+const query = sql`SELECT ${agentInvocations.errorSummary} as sub_es
+    FROM ${agentInvocations} AS ai2
+    WHERE ai2.agent_type = ${agentInvocations.agentType}`
+
+console.log(query.toSQL())
+// Reveals the bare column names — catches the bug before runtime
+```
+
+## Key Takeaway
+
+> **`${table.column}` in Drizzle's `sql` template generates a bare column identifier, not a qualified reference.** Inside aliased subqueries, this breaks table-qualified comparisons. Always use raw `alias.column_name` strings inside subquery bodies.