oh-my-customcode 0.1.0

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:
+  - docker-expert

package/templates/guides/fastapi/best-practices.md

@@ -0,0 +1,232 @@
+# FastAPI Best Practices
+
+> Source: https://fastapi.tiangolo.com/ and community patterns
+
+## Project Structure
+
+Organize by domain, not by file type:
+
+```
+src/
+├── auth/
+│   ├── router.py       # API endpoints
+│   ├── schemas.py      # Pydantic models
+│   ├── models.py       # Database models
+│   ├── service.py      # Business logic
+│   ├── dependencies.py # Route validators
+│   └── exceptions.py   # Custom exceptions
+├── users/
+│   └── ...
+├── config.py
+└── main.py
+```
+
+## Async Best Practices
+
+### I/O-Intensive Tasks
+
+```python
+# Use async def with await for non-blocking I/O
+async def fetch_user(user_id: int) -> User:
+    async with httpx.AsyncClient() as client:
+        response = await client.get(f"/api/users/{user_id}")
+        return User(**response.json())
+```
+
+### Sync I/O Operations
+
+```python
+# Use regular def - FastAPI offloads to threadpool
+def read_config() -> dict:
+    with open("config.yaml") as f:
+        return yaml.safe_load(f)
+```
+
+### CPU-Intensive Tasks
+
+```python
+# Use separate worker processes
+from celery import Celery
+
+celery_app = Celery("tasks", broker="redis://localhost")
+
+@celery_app.task
+def process_data(data: dict) -> dict:
+    # Heavy computation
+    return result
+```
+
+### Never Do This
+
+```python
+# WRONG: Blocks event loop
+async def bad_example():
+    time.sleep(5)  # Never use time.sleep in async!
+
+# CORRECT: Use asyncio.sleep
+async def good_example():
+    await asyncio.sleep(5)
+```
+
+## Pydantic Models
+
+### Custom Base Model
+
+```python
+from pydantic import BaseModel
+from datetime import datetime
+
+class AppBaseModel(BaseModel):
+    class Config:
+        from_attributes = True
+        json_encoders = {
+            datetime: lambda v: v.isoformat()
+        }
+
+class UserResponse(AppBaseModel):
+    id: int
+    email: str
+    created_at: datetime
+```
+
+### Validation
+
+```python
+from pydantic import BaseModel, EmailStr, Field, validator
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    password: str = Field(..., min_length=8)
+    age: int = Field(..., ge=18, le=120)
+
+    @validator("password")
+    def password_strength(cls, v):
+        if not any(c.isupper() for c in v):
+            raise ValueError("Password must contain uppercase")
+        return v
+```
+
+## Dependencies
+
+### Authentication
+
+```python
+from fastapi import Depends, HTTPException
+from fastapi.security import OAuth2PasswordBearer
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
+
+async def get_current_user(
+    token: str = Depends(oauth2_scheme),
+    db: AsyncSession = Depends(get_db)
+) -> User:
+    user = await verify_token(token, db)
+    if not user:
+        raise HTTPException(status_code=401)
+    return user
+
+async def get_active_user(
+    user: User = Depends(get_current_user)
+) -> User:
+    if not user.is_active:
+        raise HTTPException(status_code=403)
+    return user
+```
+
+### Database Session
+
+```python
+from sqlalchemy.ext.asyncio import AsyncSession
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+```
+
+## Error Handling
+
+```python
+# Custom exceptions
+class AuthException(Exception):
+    pass
+
+class InvalidCredentials(AuthException):
+    pass
+
+# Exception handler
+@app.exception_handler(AuthException)
+async def auth_exception_handler(request, exc):
+    return JSONResponse(
+        status_code=401,
+        content={"detail": str(exc)}
+    )
+
+# In router
+@router.post("/login")
+async def login(credentials: LoginSchema):
+    try:
+        return await auth_service.login(credentials)
+    except InvalidCredentials:
+        raise HTTPException(status_code=401, detail="Invalid credentials")
+```
+
+## API Design
+
+```python
+from fastapi import APIRouter
+
+router = APIRouter(
+    prefix="/users",
+    tags=["users"]
+)
+
+@router.get(
+    "/{user_id}",
+    response_model=UserResponse,
+    summary="Get user by ID",
+    responses={
+        404: {"model": ErrorResponse, "description": "User not found"}
+    }
+)
+async def get_user(
+    user_id: int,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+) -> UserResponse:
+    """
+    Get a specific user by their ID.
+
+    - **user_id**: The unique identifier of the user
+    """
+    user = await user_service.get(db, user_id)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    return user
+```
+
+## Testing
+
+```python
+import pytest
+from httpx import AsyncClient
+from main import app
+
+@pytest.fixture
+async def client():
+    async with AsyncClient(app=app, base_url="http://test") as ac:
+        yield ac
+
+@pytest.mark.asyncio
+async def test_create_user(client: AsyncClient):
+    response = await client.post(
+        "/users/",
+        json={"email": "test@example.com", "password": "Password123"}
+    )
+    assert response.status_code == 201
+    assert response.json()["email"] == "test@example.com"
+```

package/templates/guides/fastapi/index.yaml

@@ -0,0 +1,21 @@
+# FastAPI Guide
+
+metadata:
+  name: fastapi
+  description: FastAPI framework reference documentation
+
+source:
+  type: external
+  origin: fastapi.tiangolo.com
+  urls:
+    - https://fastapi.tiangolo.com/
+    - https://github.com/zhanymkanov/fastapi-best-practices
+  last_fetched: "2026-01-22"
+
+documents:
+  - name: best-practices
+    path: ./best-practices.md
+    description: FastAPI best practices and patterns
+
+used_by:
+  - fastapi-expert

package/templates/guides/go-backend/index.yaml

@@ -0,0 +1,26 @@
+# Go Backend Guide
+
+metadata:
+  name: go-backend
+  description: Go backend development reference documentation
+
+source:
+  type: external
+  origin: various
+  urls:
+    - https://go.dev/doc/effective_go
+    - https://github.com/golang-standards/project-layout
+    - https://github.com/uber-go/guide/blob/master/style.md
+  last_fetched: "2026-01-22"
+
+documents:
+  - name: uber-style
+    path: ./uber-style.md
+    description: Uber Go style guide
+
+  - name: project-layout
+    path: ./project-layout.md
+    description: Standard Go project layout
+
+used_by:
+  - go-backend-expert