vibe-forge 0.4.0 → 0.8.2

package/context/modern-conventions.md

@@ -1,129 +1,129 @@
-# Modern Development Conventions
-
-Reference for up-to-date tooling and naming conventions. Knowledge cutoffs can cause outdated suggestions - prefer these modern approaches.
-
-## Docker & Containers
-
-### Compose (V2+, 2021)
-
-- **File name:** `compose.yml` or `compose.yaml` (NOT `docker-compose.yml`)
-- **Command:** `docker compose` (NOT `docker-compose`)
-- Compose V2 is built into Docker CLI, no separate install needed
-- `docker-compose` (hyphenated) is legacy V1
-
-```yaml
-# compose.yml (modern)
-services:
-  app:
-    build: .
-    ports:
-      - "3000:3000"
-```
-
-### Docker Best Practices
-
-- Use multi-stage builds for smaller images
-- Prefer `COPY` over `ADD` unless extracting archives
-- Use `.dockerignore` to exclude node_modules, .git, etc.
-- Pin base image versions (e.g., `node:20-alpine`, not `node:latest`)
-
-## Package Managers
-
-### Node.js
-
-- **npm:** v7+ supports workspaces, lockfile v2
-- **pnpm:** Preferred for monorepos, faster, stricter
-- **Bun:** Fast runtime + package manager, growing adoption
-
-### Python
-
-- **uv:** Modern, fast replacement for pip/pip-tools (2024+)
-- **poetry:** Dependency management + packaging
-- **pipx:** For CLI tools (don't pip install globally)
-
-## TypeScript
-
-- **Config:** `tsconfig.json` with `"moduleResolution": "bundler"` for modern bundlers
-- **Strict mode:** Always enable `"strict": true`
-- **Node types:** `@types/node` version should match Node.js version
-
-## Testing
-
-### JavaScript/TypeScript
-
-- **Vitest:** Modern, fast, Vite-native (preferred for new projects)
-- **Jest:** Still widely used, v30+ reduces deprecated deps
-- **Playwright:** E2E testing, cross-browser
-
-### Python
-
-- **pytest:** Standard, use over unittest
-- **pytest-cov:** Coverage reporting
-
-## CI/CD
-
-### GitHub Actions
-
-- Use `actions/checkout@v4`, `actions/setup-node@v4` (latest major versions)
-- Prefer `npm ci` over `npm install` in CI
-- Use job matrices for cross-platform testing
-
-## Linting & Formatting
-
-### JavaScript/TypeScript
-
-- **ESLint v9+:** Flat config (`eslint.config.js`, not `.eslintrc`)
-- **Prettier:** Code formatting (or use ESLint with stylistic rules)
-- **Biome:** Fast all-in-one linter + formatter (Rust-based)
-
-### Python
-
-- **Ruff:** Fast linter + formatter (replaces flake8, black, isort)
-- **mypy:** Type checking
-
-## API Design
-
-### REST
-
-- Use plural nouns for collections (`/users`, not `/user`)
-- HTTP methods: GET (read), POST (create), PUT/PATCH (update), DELETE
-- Status codes: 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Server Error
-
-### Authentication
-
-- **JWTs:** Short expiry + refresh tokens, store in httpOnly cookies (not localStorage)
-- **OAuth 2.0 / OIDC:** For third-party auth
-- **Passkeys/WebAuthn:** Modern passwordless option
-
-## Database
-
-### ORMs
-
-- **Prisma:** Type-safe, great DX for Node.js/TypeScript
-- **Drizzle:** Lightweight, SQL-like syntax
-- **SQLAlchemy 2.0:** Python standard (note: 2.0 syntax differs from 1.x)
-
-### Migrations
-
-- Always use migrations, never manual schema changes in production
-- Version control migration files
-
-## Frontend
-
-### React
-
-- **React 18+:** Concurrent features, Suspense
-- Prefer function components + hooks over class components
-- Use React Server Components where appropriate (Next.js 13+)
-
-### State Management
-
-- Start with React Context + useReducer
-- **Zustand:** Simple, minimal boilerplate
-- **TanStack Query:** For server state (caching, refetching)
-
-## Monorepos
-
-- **Turborepo:** Fast builds, caching
-- **Nx:** Full-featured, good for enterprise
-- **pnpm workspaces:** Native package manager support
+# Modern Development Conventions
+
+Reference for up-to-date tooling and naming conventions. Knowledge cutoffs can cause outdated suggestions - prefer these modern approaches.
+
+## Docker & Containers
+
+### Compose (V2+, 2021)
+
+- **File name:** `compose.yml` or `compose.yaml` (NOT `docker-compose.yml`)
+- **Command:** `docker compose` (NOT `docker-compose`)
+- Compose V2 is built into Docker CLI, no separate install needed
+- `docker-compose` (hyphenated) is legacy V1
+
+```yaml
+# compose.yml (modern)
+services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+```
+
+### Docker Best Practices
+
+- Use multi-stage builds for smaller images
+- Prefer `COPY` over `ADD` unless extracting archives
+- Use `.dockerignore` to exclude node_modules, .git, etc.
+- Pin base image versions (e.g., `node:20-alpine`, not `node:latest`)
+
+## Package Managers
+
+### Node.js
+
+- **npm:** v7+ supports workspaces, lockfile v2
+- **pnpm:** Preferred for monorepos, faster, stricter
+- **Bun:** Fast runtime + package manager, growing adoption
+
+### Python
+
+- **uv:** Modern, fast replacement for pip/pip-tools (2024+)
+- **poetry:** Dependency management + packaging
+- **pipx:** For CLI tools (don't pip install globally)
+
+## TypeScript
+
+- **Config:** `tsconfig.json` with `"moduleResolution": "bundler"` for modern bundlers
+- **Strict mode:** Always enable `"strict": true`
+- **Node types:** `@types/node` version should match Node.js version
+
+## Testing
+
+### JavaScript/TypeScript
+
+- **Vitest:** Modern, fast, Vite-native (preferred for new projects)
+- **Jest:** Still widely used, v30+ reduces deprecated deps
+- **Playwright:** E2E testing, cross-browser
+
+### Python
+
+- **pytest:** Standard, use over unittest
+- **pytest-cov:** Coverage reporting
+
+## CI/CD
+
+### GitHub Actions
+
+- Use `actions/checkout@v4`, `actions/setup-node@v4` (latest major versions)
+- Prefer `npm ci` over `npm install` in CI
+- Use job matrices for cross-platform testing
+
+## Linting & Formatting
+
+### JavaScript/TypeScript
+
+- **ESLint v9+:** Flat config (`eslint.config.js`, not `.eslintrc`)
+- **Prettier:** Code formatting (or use ESLint with stylistic rules)
+- **Biome:** Fast all-in-one linter + formatter (Rust-based)
+
+### Python
+
+- **Ruff:** Fast linter + formatter (replaces flake8, black, isort)
+- **mypy:** Type checking
+
+## API Design
+
+### REST
+
+- Use plural nouns for collections (`/users`, not `/user`)
+- HTTP methods: GET (read), POST (create), PUT/PATCH (update), DELETE
+- Status codes: 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Server Error
+
+### Authentication
+
+- **JWTs:** Short expiry + refresh tokens, store in httpOnly cookies (not localStorage)
+- **OAuth 2.0 / OIDC:** For third-party auth
+- **Passkeys/WebAuthn:** Modern passwordless option
+
+## Database
+
+### ORMs
+
+- **Prisma:** Type-safe, great DX for Node.js/TypeScript
+- **Drizzle:** Lightweight, SQL-like syntax
+- **SQLAlchemy 2.0:** Python standard (note: 2.0 syntax differs from 1.x)
+
+### Migrations
+
+- Always use migrations, never manual schema changes in production
+- Version control migration files
+
+## Frontend
+
+### React
+
+- **React 18+:** Concurrent features, Suspense
+- Prefer function components + hooks over class components
+- Use React Server Components where appropriate (Next.js 13+)
+
+### State Management
+
+- Start with React Context + useReducer
+- **Zustand:** Simple, minimal boilerplate
+- **TanStack Query:** For server state (caching, refetching)
+
+## Monorepos
+
+- **Turborepo:** Fast builds, caching
+- **Nx:** Full-featured, good for enterprise
+- **pnpm workspaces:** Native package manager support