red64-cli 0.3.0 → 0.6.0

package/framework/stacks/javascript/conventions.md

@@ -0,0 +1,268 @@
+# Development Conventions
+
+General development practices, workflow, and operational standards for JavaScript/Node.js projects.
+
+---
+
+## Philosophy
+
+- **Predictable process**: Consistent workflows reduce friction and errors
+- **Automated enforcement**: Linters and CI catch what humans miss
+- **Observable systems**: If you cannot see it, you cannot fix it
+- **Documentation as code**: Keep docs next to the code they describe
+
+---
+
+## Git Workflow
+
+### Branch Strategy
+
+```
+main              # Production-ready, always deployable
+  |-- feat/...    # Feature branches (short-lived)
+  |-- fix/...     # Bug fix branches
+  |-- chore/...   # Maintenance, dependency updates
+```
+
+### Branch Naming
+
+```bash
+feat/add-user-registration
+fix/duplicate-email-validation
+chore/upgrade-fastify
+refactor/extract-payment-service
+```
+
+**Pattern**: `{type}/{short-description}` with lowercase and hyphens.
+
+---
+
+## Commit Conventions
+
+### Conventional Commits
+
+```
+feat: add user registration endpoint
+fix: prevent duplicate email registration
+refactor: extract password hashing to utility module
+test: add integration tests for payment flow
+docs: update API authentication guide
+chore: upgrade zod to v4
+ci: add lint check to CI pipeline
+```
+
+### Types
+
+| Type | Description |
+|------|-------------|
+| `feat` | New feature or capability |
+| `fix` | Bug fix |
+| `refactor` | Code change that neither fixes nor adds |
+| `test` | Adding or updating tests |
+| `docs` | Documentation only |
+| `chore` | Maintenance, dependencies, tooling |
+| `ci` | CI/CD configuration changes |
+| `perf` | Performance improvement |
+
+**Rule**: One logical change per commit. If the commit message needs "and", split it.
+
+---
+
+## Project Structure
+
+```
+project-root/
+  src/
+    index.js                 # Application entry point
+    app.js                   # Framework setup (Express/Fastify)
+    config.js                # Environment configuration
+    routes/
+      users.js
+      orders.js
+    services/
+      user-service.js
+      order-service.js
+    repositories/
+      user-repo.js
+    middleware/
+      auth.js
+      error-handler.js
+      validate.js
+    errors.js                # Custom error classes
+    logger.js                # Logger configuration
+  tests/
+    unit/
+    integration/
+    fixtures/
+    setup.js
+  eslint.config.js
+  vitest.config.js
+  package.json
+  .env.example
+  .gitignore
+  .prettierrc
+```
+
+---
+
+## ESM Module System
+
+```json
+// package.json
+{
+  "type": "module"
+}
+```
+
+```javascript
+// GOOD: ESM
+import { readFile } from 'node:fs/promises';
+import express from 'express';
+export function createApp() { /* ... */ }
+
+// BAD: CJS (avoid in new projects)
+const { readFile } = require('fs/promises');
+module.exports = { createApp };
+```
+
+### ESM Gotchas
+
+```javascript
+// No __dirname in ESM -- use import.meta
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Relative imports MUST include file extensions
+import { userService } from './services/user-service.js';  // .js required
+```
+
+---
+
+## Environment Configuration
+
+### Using dotenv + Zod
+
+```javascript
+// src/config.js
+import 'dotenv/config';
+import { z } from 'zod';
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'staging', 'production']).default('development'),
+  PORT: z.coerce.number().default(3000),
+  DATABASE_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32),
+  REDIS_URL: z.string().url().default('redis://localhost:6379'),
+});
+
+const parsed = envSchema.safeParse(process.env);
+if (!parsed.success) {
+  console.error('Invalid environment variables:', parsed.error.format());
+  process.exit(1);
+}
+
+export const config = Object.freeze(parsed.data);
+```
+
+### Rules
+- Never commit `.env` files with real values
+- Always commit `.env.example` with placeholder values
+- Fail fast on missing required variables (no defaults for secrets)
+
+---
+
+## Logging with pino
+
+```javascript
+// src/logger.js
+import pino from 'pino';
+import { config } from './config.js';
+
+export const logger = pino({
+  level: config.NODE_ENV === 'production' ? 'info' : 'debug',
+  transport: config.NODE_ENV !== 'production'
+    ? { target: 'pino-pretty', options: { colorize: true } }
+    : undefined,
+});
+```
+
+```javascript
+// GOOD: Structured key-value pairs
+logger.info({ userId: 42, email: 'a@b.com' }, 'user_created');
+logger.error({ orderId: 123, provider: 'stripe', err }, 'payment_failed');
+
+// BAD: String interpolation
+logger.info(`User ${userId} created with email ${email}`);
+```
+
+---
+
+## API Design Patterns
+
+```javascript
+// RESTful conventions
+GET    /api/v1/users           // List users
+POST   /api/v1/users           // Create user
+GET    /api/v1/users/:id       // Get user
+PATCH  /api/v1/users/:id       // Update user
+DELETE /api/v1/users/:id       // Delete user
+```
+
+### Response Formats
+
+```javascript
+// Success (single resource)
+{ "data": { "id": 1, "name": "Alice" } }
+
+// Success (collection)
+{ "data": [...], "meta": { "total": 100, "page": 1, "limit": 20 } }
+
+// Error
+{ "error": { "code": "NOT_FOUND", "message": "User not found", "details": {} } }
+```
+
+---
+
+## Dependency Management
+
+```bash
+pnpm add fastify zod              # Add dependency
+pnpm add -D vitest eslint         # Add dev dependency
+pnpm audit                        # Check vulnerabilities
+pnpm outdated                     # Check for updates
+```
+
+### engines Field
+
+```json
+{
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}
+```
+
+---
+
+## Health Checks
+
+```javascript
+app.get('/health', (req, res) => {
+  res.json({ status: 'ok', timestamp: new Date().toISOString() });
+});
+
+app.get('/health/ready', async (req, res) => {
+  try {
+    await db.query('SELECT 1');
+    res.json({ status: 'ready', database: 'connected' });
+  } catch {
+    res.status(503).json({ status: 'not_ready', database: 'disconnected' });
+  }
+});
+```
+
+---
+
+_Conventions reduce cognitive load. Follow them consistently so the team can focus on solving problems, not debating style._

package/framework/stacks/javascript/error-handling.md

@@ -0,0 +1,216 @@
+# Error Handling Patterns
+
+Structured error handling for Node.js applications with custom exceptions, framework-specific middleware, and observability.
+
+---
+
+## Philosophy
+
+- **Fail fast**: Validate inputs early, throw immediately on invalid state
+- **Typed exceptions**: Custom error hierarchy over generic `Error`
+- **Centralized handling**: Error middleware at the API boundary, not scattered try/catch
+- **Structured logging**: Machine-readable logs with context, not `console.log`
+- **User-safe messages**: Never expose stack traces or internal details to clients
+
+---
+
+## Custom Error Hierarchy
+
+### Base Errors
+
+```javascript
+// src/errors.js
+export class AppError extends Error {
+  constructor(message, { code = 'INTERNAL_ERROR', statusCode = 500, details = {} } = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(resource, identifier) {
+    super(`${resource} not found: ${identifier}`, {
+      code: 'NOT_FOUND',
+      statusCode: 404,
+      details: { resource, identifier },
+    });
+  }
+}
+
+export class ConflictError extends AppError {
+  constructor(message, details = {}) {
+    super(message, { code: 'CONFLICT', statusCode: 409, details });
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(message, fieldErrors = {}) {
+    super(message, {
+      code: 'VALIDATION_ERROR',
+      statusCode: 422,
+      details: { fieldErrors },
+    });
+  }
+}
+
+export class AuthenticationError extends AppError {
+  constructor(message = 'Authentication required') {
+    super(message, { code: 'UNAUTHENTICATED', statusCode: 401 });
+  }
+}
+
+export class AuthorizationError extends AppError {
+  constructor(message = 'Insufficient permissions') {
+    super(message, { code: 'FORBIDDEN', statusCode: 403 });
+  }
+}
+
+export class ExternalServiceError extends AppError {
+  constructor(service, message) {
+    super(`External service error (${service}): ${message}`, {
+      code: 'EXTERNAL_SERVICE_ERROR',
+      statusCode: 502,
+      details: { service },
+    });
+  }
+}
+```
+
+---
+
+## Centralized Error Handler (Express)
+
+```javascript
+// src/middleware/error-handler.js
+import { AppError } from '../errors.js';
+import { logger } from '../logger.js';
+
+export function errorHandler(err, req, res, _next) {
+  if (err instanceof AppError) {
+    logger.warn({ code: err.code, message: err.message, path: req.path });
+    return res.status(err.statusCode).json({
+      error: { code: err.code, message: err.message, details: err.details },
+    });
+  }
+
+  // Zod validation errors
+  if (err.name === 'ZodError') {
+    return res.status(422).json({
+      error: { code: 'VALIDATION_ERROR', message: 'Request validation failed', details: { issues: err.issues } },
+    });
+  }
+
+  // Unknown errors -- never expose internals
+  logger.error({ message: 'Unhandled error', error: err.message, stack: err.stack, path: req.path });
+  return res.status(500).json({
+    error: { code: 'INTERNAL_ERROR', message: 'An unexpected error occurred' },
+  });
+}
+```
+
+---
+
+## Fastify Error Handling
+
+```javascript
+app.setErrorHandler((error, request, reply) => {
+  if (error instanceof AppError) {
+    request.log.warn({ code: error.code, message: error.message });
+    return reply.status(error.statusCode).send({
+      error: { code: error.code, message: error.message, details: error.details },
+    });
+  }
+
+  if (error.validation) {
+    return reply.status(422).send({
+      error: { code: 'VALIDATION_ERROR', message: 'Request validation failed', details: { issues: error.validation } },
+    });
+  }
+
+  request.log.error({ error: error.message, stack: error.stack });
+  return reply.status(500).send({
+    error: { code: 'INTERNAL_ERROR', message: 'An unexpected error occurred' },
+  });
+});
+```
+
+---
+
+## Async Error Handling
+
+```javascript
+// GOOD: try/catch at the right level
+async function processOrder(orderId) {
+  const order = await orderRepo.findById(orderId);
+  if (!order) {
+    throw new NotFoundError('Order', orderId);
+  }
+
+  try {
+    await paymentClient.charge(order.totalCents, order.paymentToken);
+  } catch (err) {
+    throw new ExternalServiceError('payment', err.message);
+  }
+
+  order.status = 'paid';
+  return orderRepo.save(order);
+}
+
+// BAD: Wrapping everything in try/catch and swallowing
+async function processOrder(orderId) {
+  try {
+    const order = await orderRepo.findById(orderId);
+    // ... 50 lines of logic ...
+  } catch (err) {
+    console.log(err);  // Swallowed, no rethrow
+  }
+}
+```
+
+---
+
+## Process-Level Error Handlers
+
+```javascript
+// src/index.js -- register at application startup
+process.on('unhandledRejection', (reason) => {
+  logger.error({ message: 'Unhandled promise rejection', reason: reason instanceof Error ? reason.message : reason });
+  process.exit(1);
+});
+
+process.on('uncaughtException', (error) => {
+  logger.fatal({ message: 'Uncaught exception', error: error.message, stack: error.stack });
+  process.exit(1);
+});
+
+// Graceful shutdown
+function gracefulShutdown(signal) {
+  logger.info({ message: 'Shutdown signal received', signal });
+  server.close(() => process.exit(0));
+  setTimeout(() => process.exit(1), 10_000);
+}
+
+process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+```
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Correct Approach |
+|---|---|---|
+| `catch (err) {}` | Silently swallows errors | Log and re-throw or handle specifically |
+| `throw 'something'` | No stack trace, not an Error object | Always `throw new Error(...)` or custom class |
+| Nested try/catch everywhere | Hard to read, hides control flow | Centralized error middleware |
+| `console.log(err)` in catch | No structure, lost in production | Use structured logger (pino) |
+| Stack traces in API responses | Security risk | Return error codes and user-safe messages |
+| Mixing callbacks and promises | Inconsistent error propagation | Use async/await consistently |
+
+---
+
+_Errors are data. Classify them, log them with context, and present them consistently. Never swallow exceptions silently._

package/framework/stacks/javascript/feedback.md

@@ -0,0 +1,80 @@
+# Feedback Configuration
+
+Project-specific commands for automated feedback during JavaScript/Node.js implementation.
+
+---
+
+## Test Commands
+
+Commands to run tests during implementation. The agent will use these to verify code changes.
+
+```yaml
+# Primary test command (REQUIRED)
+test: npx vitest run
+
+# Test with coverage report
+test_coverage: npx vitest run --coverage
+
+# Run specific test file (use {file} as placeholder)
+test_file: npx vitest run {file}
+
+# Watch mode (development)
+test_watch: npx vitest
+```
+
+---
+
+## Linting Commands
+
+Commands for code quality checks.
+
+```yaml
+# Primary lint command
+lint: npx eslint .
+
+# Lint with auto-fix
+lint_fix: npx eslint . --fix
+
+# Format check
+format_check: npx prettier --check .
+
+# Format fix
+format_fix: npx prettier --write .
+```
+
+---
+
+## Build / Syntax Check Commands
+
+```yaml
+# Syntax check (Node.js built-in)
+build: node --check src/index.js
+
+# Check all source files
+build_all: find src -name '*.js' -exec node --check {} +
+```
+
+---
+
+## Development Server
+
+```yaml
+# Start dev server (with watch mode)
+dev_server: node --watch src/index.js
+
+# Dev server port
+dev_port: 3000
+
+# Dev server base URL
+dev_url: http://localhost:3000
+```
+
+---
+
+## Notes
+
+- Uses Vitest as the primary test runner (Jest-compatible API, native ESM)
+- ESLint with flat config (`eslint.config.js`) for linting
+- Prettier for formatting (separate from ESLint)
+- Node.js `--watch` flag provides built-in file watching (stable in Node.js 22+)
+- For Biome projects, replace lint + format commands with `npx biome check .`

package/framework/stacks/javascript/tech.md

@@ -0,0 +1,114 @@
+# Technology Stack
+
+## Architecture
+
+Modern Node.js application with ESM-first design. Fastify or Express as web framework, PostgreSQL for persistence, Redis for caching and queues, Docker for deployment.
+
+---
+
+## Core Technologies
+
+- **Runtime**: Node.js 22+ (LTS)
+- **Package Manager**: pnpm (fast, disk-efficient) or npm
+- **Module System**: ESM (`"type": "module"` in package.json)
+- **Web Framework**: Fastify (performance-first) or Express (ecosystem) or Hono (edge/serverless)
+- **Database**: PostgreSQL with pg or postgres.js
+- **ORM/Query Builder**: Drizzle ORM (SQL-first) or Prisma (DX-first)
+- **Validation**: Zod (TypeScript-aligned) or Joi (mature, standalone)
+
+---
+
+## Key Libraries
+
+### Web & API
+- **Fastify**: High-performance web framework with schema-based validation
+- **Express**: Minimalist framework with massive middleware ecosystem
+- **Hono**: Ultrafast framework for edge/serverless (Cloudflare Workers, Deno, Bun)
+- **cors**: Cross-origin resource sharing middleware
+- **helmet**: Security headers middleware
+
+### Database & Storage
+- **Drizzle ORM**: SQL-first, zero-dependency ORM with TypeScript schema-as-code
+- **Prisma**: Full-featured ORM with declarative schema and migrations
+- **postgres.js**: Fastest PostgreSQL client for Node.js
+- **ioredis**: Redis client with cluster support
+
+### Validation & Serialization
+- **Zod**: TypeScript-first schema validation with inference
+- **Joi**: Battle-tested validation library
+- **ajv**: JSON Schema validator (used internally by Fastify)
+
+### Background Tasks
+- **BullMQ**: Redis-based queue for job processing
+- **node-cron**: Lightweight cron scheduler
+
+### Deployment
+- **Docker**: Containerized deployment
+- **Docker Compose**: Multi-service local development
+- **PM2**: Process manager for production Node.js
+
+---
+
+## Runtime Alternatives
+
+| Runtime | Use Case | Notes |
+|---------|----------|-------|
+| **Node.js 22+** | Default, production-proven | LTS until April 2027, native TS support (flag) |
+| **Bun** | Performance-critical, fast scripts | Built-in bundler, test runner, package manager |
+| **Deno** | Security-first, standards-aligned | Built-in TypeScript, permissions model, npm compat |
+
+**Default**: Node.js 22 LTS. Use Bun or Deno when their specific advantages are needed.
+
+---
+
+## Development Environment
+
+### Required Tools
+- Node.js 22+ (see `.node-version` or `.nvmrc`)
+- pnpm or npm
+- PostgreSQL 16+
+- Redis 7+
+- Docker & Docker Compose
+
+### Common Commands
+```bash
+# Environment setup
+pnpm install                           # Install dependencies
+pnpm run db:migrate                    # Run migrations
+
+# Dev server
+pnpm run dev                           # Start with watch mode
+node --watch src/index.js              # Built-in watch mode
+
+# Tests
+pnpm run test                          # All tests (Vitest)
+npx vitest run tests/unit/             # Unit tests only
+npx vitest run --coverage              # With coverage
+
+# Code quality
+npx eslint .                           # Lint
+npx prettier --check .                 # Format check
+npx prettier --write .                 # Format fix
+
+# Docker
+docker compose up -d                   # Start services
+docker compose logs -f app             # Follow app logs
+```
+
+---
+
+## Key Technical Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| **ESM over CJS** | Modern standard, tree-shaking, top-level await, aligns with browser JS |
+| **pnpm over npm** | 3x faster installs, strict dependency resolution, disk-efficient |
+| **Fastify over Express** | 2-3x faster, built-in schema validation, better async support |
+| **Drizzle over Prisma** | Zero binary deps, SQL-first, tiny bundle, edge-compatible |
+| **Zod over Joi** | TypeScript inference, composable schemas, smaller bundle |
+| **Vitest over Jest** | Native ESM, faster execution, Vite-powered HMR in watch mode |
+| **Biome as alternative** | Single tool for lint + format, Rust speed, zero config |
+
+---
+
+_Document standards and patterns, not every dependency. See `coding-style.md` for detailed JavaScript conventions._