codeninja 2.0.0

package/tasks/generate-database.task.md

@@ -0,0 +1,168 @@
+---
+type: task
+name: generate-database
+agent: nodejs-agent
+---
+
+# File: config/database.js
+
+## Purpose
+Establishes and exports the database connection for the service. All
+model files import this module to run queries. The implementation differs
+based on `context.db.type` — one file is generated per project, not one
+per database type. The agent reads the db type from context and generates
+the correct implementation.
+
+---
+
+## Dependencies to Import
+
+- `../logger/logging` — imported as `log`. Used for connection error
+  logging and query error logging.
+
+Additionally, one database driver is imported based on `context.db.type`:
+- If `postgresql` → import `{ Pool }` from `pg`
+- If `mysql` → import `mysql2/promise` and create a pool using
+  `mysql2.createPool()`
+- If `mongodb` → import `mongoose`
+
+Never import more than one driver. Only the driver matching
+`context.db.type` is imported.
+
+---
+
+## Implementation by Database Type
+
+---
+
+### PostgreSQL (context.db.type == "postgresql")
+
+**Pool creation**:
+Create a `new Pool` instance with these configuration keys all read
+from process.env:
+- `user` from `process.env.DATABASE_USER`
+- `host` from `process.env.DATABASE_HOST`
+- `database` from `process.env.DATABASE_NAME`
+- `password` from `process.env.DATABASE_PASSWORD`
+- `port` from `process.env.DATABASE_PORT`
+- `ssl` set to `{ rejectUnauthorized: false }` — required for most
+  hosted PostgreSQL providers including AWS RDS and Supabase.
+
+**Pool error handler**:
+Register a listener on the pool's `error` event using `pool.on('error',
+callback)`. The callback receives the error object. Inside the callback:
+log at critical level with the message "Error establishing PostgreSQL
+connection" and the error object. Then call `process.exit(-1)`.
+This handles unexpected errors on idle clients in the pool — without
+this handler, such errors would be unhandled rejections and crash the
+process silently.
+
+**logFormattedQuery(queryText, params)**:
+Internal helper function. Not exported.
+Purpose: reconstructs the SQL query string with parameter placeholders
+replaced by their actual values, for use in error logs only. Never used
+to actually execute queries — parameterized queries are always used for
+execution.
+Takes `queryText` (the SQL string with `$1`, `$2` placeholders) and
+`params` (the values array).
+Uses a regex replace on the pattern `\$(\d+)` to find each placeholder.
+For each match, read the corresponding value from params at index
+`(matched_number - 1)`.
+Format the value:
+- If null or undefined → replace with the string `NULL`
+- If a string → wrap in single quotes: `'value'`
+- Any other type → use the value as-is (numbers, booleans)
+Returns the reconstructed query string. Used only in error log messages.
+
+**query(text, params)**:
+Async function. The primary export used by all model files.
+Parameters:
+- `text` — the SQL query string with `$1`, `$2` parameter placeholders
+- `params` — array of values. Defaults to empty array if not provided.
+
+Flow:
+1. Call `pool.query(text, params)` inside a try/catch.
+2. On success — return the result object directly. The result has
+   `rows` (array of row objects) and `rowCount` (number of affected
+   rows) which callers destructure as needed.
+3. On error — log at error level with the message "DATABASE QUERY ERROR",
+   including the formatted query from `logFormattedQuery(text, params)`
+   and the error object. Then re-throw the error. Model functions are
+   responsible for catching query errors.
+
+**Export**:
+```
+module.exports = { query, pool }
+```
+`pool` is exported for use in transaction scenarios where the caller
+needs to acquire a client directly and manage BEGIN/COMMIT/ROLLBACK
+manually.
+
+---
+
+### MySQL (context.db.type == "mysql")
+
+**Pool creation**:
+Call `mysql2.createPool()` with these configuration keys all from
+process.env:
+- `host` from `process.env.DATABASE_HOST`
+- `user` from `process.env.DATABASE_USER`
+- `password` from `process.env.DATABASE_PASSWORD`
+- `database` from `process.env.DATABASE_NAME`
+- `port` from `process.env.DATABASE_PORT`
+- `waitForConnections: true`
+- `connectionLimit: 10`
+- `queueLimit: 0`
+
+**logFormattedQuery(queryText, params)**:
+Same purpose as PostgreSQL version but uses `?` placeholders instead
+of `$1` style. Replace each `?` in sequence with its corresponding
+param value, applying the same null/string/other formatting rules.
+
+**query(text, params)**:
+Same async pattern as PostgreSQL. Call `pool.execute(text, params)`.
+Returns `[rows, fields]` — destructure and return `{ rows, rowCount:
+rows.length }` to give callers a consistent interface matching the
+PostgreSQL result shape.
+On error — same log pattern and re-throw.
+
+**Export**:
+```
+module.exports = { query, pool }
+```
+
+---
+
+### MongoDB (context.db.type == "mongodb")
+
+**Connection**:
+Call `mongoose.connect()` with the connection string constructed from
+process.env values:
+`mongodb://${process.env.DATABASE_USER}:${process.env.DATABASE_PASSWORD}
+@${process.env.DATABASE_HOST}:${process.env.DATABASE_PORT}/
+${process.env.DATABASE_NAME}`
+Options: `{ useNewUrlParser: true, useUnifiedTopology: true }`
+
+Wrap in an async immediately-invoked function. On connection success —
+log at info level. On error — log at critical level and call
+`process.exit(-1)`.
+
+**Export**:
+```
+module.exports = mongoose
+```
+Model files import mongoose directly and define their own schemas.
+No `query` wrapper is needed for MongoDB — each model uses mongoose
+model methods directly.
+
+---
+
+## What This File Does NOT Do
+
+- Does not hardcode any connection values — all from process.env
+- Does not define any data models or schemas — those live in
+  module _model.js files
+- Does not retry failed connections — process exits on critical
+  connection failure
+- Does not export raw connection strings — only the pool or
+  connection object

package/tasks/generate-docker-compose.task.md

@@ -0,0 +1,298 @@
+---
+type: task
+name: generate-docker-compose
+agent: global-agent
+---
+
+# File: docker-compose.yml
+
+## Purpose
+Orchestrates all services in the project (NodeJS APIs, ReactJS frontends,
+databases, Redis) in a unified Docker environment. Generated once per
+repository and updated as new services are added.
+
+---
+
+## Generation Logic
+
+### When to Generate
+- First `@initialize-project` in the repo (no docker-compose.yml exists)
+- Any subsequent `@initialize-project` that adds a new service
+
+### When to Update
+- New service initialized → add service definition
+- Service port changed → update ports mapping
+- Database type changed → update db service definition
+
+---
+
+## Template Structure
+
+```yaml
+version: '3.8'
+
+services:
+  # Database service (if context.db.type exists)
+  {db_service_name}:
+    image: {db_image}
+    container_name: {project_name}-{db_type}
+    environment:
+      {db_env_vars}
+    ports:
+      - "{db_port}:{db_internal_port}"
+    volumes:
+      - {db_data_volume}:/var/lib/{db_volume_path}
+      - ./database/{db_type}/migrations:/docker-entrypoint-initdb.d:ro
+    networks:
+      - {project_name}-network
+    healthcheck:
+      test: {db_healthcheck}
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  # Redis service (always included for NodeJS services)
+  redis:
+    image: redis:7-alpine
+    container_name: {project_name}-redis
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis-data:/data
+    networks:
+      - {project_name}-network
+    command: redis-server --appendonly yes
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 3s
+      retries: 5
+
+  # NodeJS services (one per service in context.services where type == nodejs)
+  {service_name}:
+    build:
+      context: ./{service_name}
+      dockerfile: Dockerfile
+    container_name: {project_name}-{service_name}
+    environment:
+      - NODE_ENV=production
+      - DB_HOST={db_service_name}
+      - DB_PORT={db_internal_port}
+      - DB_NAME=${DB_NAME}
+      - DB_USER=${DB_USER}
+      - DB_PASS=${DB_PASS}
+      - REDIS_HOST=redis
+      - REDIS_PORT=6379
+      - KEY=${KEY}
+      - IV=${IV}
+      - API_KEY=${API_KEY}
+    ports:
+      - "{service_port}:{service_port}"
+    volumes:
+      - ./{service_name}/logger/logs:/app/logger/logs
+      - ./{service_name}/pem:/app/pem
+      - ./{service_name}/images:/app/images
+    depends_on:
+      {db_service_name}:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    networks:
+      - {project_name}-network
+    restart: unless-stopped
+
+  # ReactJS services (one per service in context.services where type == reactjs)
+  {frontend_service_name}:
+    build:
+      context: ./{frontend_service_name}
+      dockerfile: Dockerfile
+    container_name: {project_name}-{frontend_service_name}
+    environment:
+      - REACT_APP_BASE_URL=http://{linked_service_name}:{linked_service_port}/api/v1/
+      - REACT_APP_API_KEY=${REACT_APP_API_KEY}
+      - REACT_APP_KEY=${REACT_APP_KEY}
+      - REACT_APP_IV=${REACT_APP_IV}
+    ports:
+      - "{frontend_port}:80"
+    depends_on:
+      - {linked_service_name}
+    networks:
+      - {project_name}-network
+    restart: unless-stopped
+
+networks:
+  {project_name}-network:
+    driver: bridge
+
+volumes:
+  {db_data_volume}:
+  redis-data:
+```
+
+---
+
+## Variable Substitution Rules
+
+### Project-level
+- `{project_name}` → `context.project_name` (lowercase, hyphens)
+
+### Database service
+- `{db_service_name}` → `postgres` | `mysql` | `mongo`
+- `{db_image}` → `postgres:15-alpine` | `mysql:8` | `mongo:7`
+- `{db_type}` → `context.db.type`
+- `{db_port}` → `context.db.port`
+- `{db_internal_port}` → 5432 (postgres) | 3306 (mysql) | 27017 (mongo)
+- `{db_data_volume}` → `postgres-data` | `mysql-data` | `mongo-data`
+- `{db_volume_path}` → `postgresql/data` | `mysql` | `mongodb`
+
+### Database environment variables
+**PostgreSQL:**
+```yaml
+POSTGRES_DB: ${DB_NAME}
+POSTGRES_USER: ${DB_USER}
+POSTGRES_PASSWORD: ${DB_PASS}
+```
+
+**MySQL:**
+```yaml
+MYSQL_DATABASE: ${DB_NAME}
+MYSQL_USER: ${DB_USER}
+MYSQL_PASSWORD: ${DB_PASS}
+MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASS}
+```
+
+**MongoDB:**
+```yaml
+MONGO_INITDB_ROOT_USERNAME: ${DB_USER}
+MONGO_INITDB_ROOT_PASSWORD: ${DB_PASS}
+MONGO_INITDB_DATABASE: ${DB_NAME}
+```
+
+### Database health checks
+**PostgreSQL:**
+```yaml
+test: ["CMD-SHELL", "pg_isready -U ${DB_USER} -d ${DB_NAME}"]
+```
+
+**MySQL:**
+```yaml
+test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u${DB_USER}", "-p${DB_PASS}"]
+```
+
+**MongoDB:**
+```yaml
+test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
+```
+
+### NodeJS services
+For each service in `context.services` where `type == "nodejs"`:
+- `{service_name}` → service key from context.services
+- `{service_port}` → `context.services[<service_name>].port`
+
+### ReactJS services
+For each service in `context.services` where `type == "reactjs"`:
+- `{frontend_service_name}` → service key
+- `{frontend_port}` → `context.services[<service_name>].port`
+- `{linked_service_name}` → `context.services[<service_name>].linked_service`
+- `{linked_service_port}` → `context.services[<linked_service>].port`
+
+---
+
+## File Location
+
+Write to: `<repository_root>/docker-compose.yml`
+
+---
+
+## Companion File: .env.docker
+
+Also generate `.env.docker` at repository root:
+
+```env
+# Database credentials
+DB_NAME={context.db.name}
+DB_USER={context.db.user}
+DB_PASS=your_secure_password_here
+DB_ROOT_PASS=your_root_password_here
+
+# Service keys (from first NodeJS service)
+KEY={encryption_key}
+IV={encryption_iv}
+API_KEY={api_key}
+
+# ReactJS keys (inherited from linked service)
+REACT_APP_API_KEY={api_key}
+REACT_APP_KEY={encryption_key}
+REACT_APP_IV={encryption_iv}
+```
+
+And `.env.docker.example` with blanked values.
+
+---
+
+## Update Strategy
+
+### If docker-compose.yml already exists:
+1. Read existing file
+2. Parse services section
+3. Add new service definition for the newly initialized service
+4. Update networks and volumes if needed
+5. Write back to disk
+
+### If this is the first service:
+Generate the complete file with all sections.
+
+---
+
+## Dependencies
+
+- Requires at least one service in `context.services`
+- Requires `context.db` to be populated (for NodeJS/database projects)
+- Can be generated after all service Dockerfiles are created
+
+---
+
+## Usage Commands (added to README)
+
+```bash
+# Start all services
+docker-compose --env-file .env.docker up -d
+
+# Start specific service
+docker-compose --env-file .env.docker up -d auth
+
+# View logs
+docker-compose logs -f auth
+
+# Stop all services
+docker-compose down
+
+# Rebuild after code changes
+docker-compose build auth
+docker-compose up -d auth
+
+# Full reset (removes volumes)
+docker-compose down -v
+```
+
+---
+
+## Security Notes
+
+- `.env.docker` should be in `.gitignore` (secrets never committed)
+- `.env.docker.example` is committed (structure without values)
+- Database passwords must be strong in production
+- Service-to-service communication happens on internal network only
+- External access only through exposed ports
+
+---
+
+## Production Considerations
+
+For production deployment, this compose file should be:
+1. Split into `docker-compose.yml` (base) + `docker-compose.prod.yml` (overrides)
+2. Use Docker secrets instead of environment variables
+3. Add resource limits (CPU, memory)
+4. Add logging drivers
+5. Use external volumes for data persistence
+6. Add traefik/nginx for reverse proxy and SSL

package/tasks/generate-dockerfile.task.md

@@ -0,0 +1,126 @@
+---
+type: task
+name: generate-dockerfile
+agent: nodejs-agent
+---
+
+# File: Dockerfile
+
+## Purpose
+Generates a multi-stage production-ready Dockerfile for the NodeJS service.
+Uses Alpine Linux for minimal image size and includes only production
+dependencies in the final image.
+
+---
+
+## Template
+
+```dockerfile
+# Stage 1: Build dependencies
+FROM node:18-alpine AS builder
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install all dependencies (including devDependencies for build if needed)
+RUN npm ci
+
+# Copy application code
+COPY . .
+
+# Stage 2: Production image
+FROM node:18-alpine
+
+# Install dumb-init for proper signal handling
+RUN apk add --no-cache dumb-init
+
+# Create app user for security (don't run as root)
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S nodejs -u 1001
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install only production dependencies
+RUN npm ci --only=production && npm cache clean --force
+
+# Copy built application from builder stage
+COPY --from=builder --chown=nodejs:nodejs /app .
+
+# Create necessary directories with proper permissions
+RUN mkdir -p logger/logs pem images && \
+    chown -R nodejs:nodejs logger/logs pem images
+
+# Switch to non-root user
+USER nodejs
+
+# Expose the service port
+EXPOSE {port}
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
+  CMD node -e "require('http').get('http://localhost:{port}/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))"
+
+# Use dumb-init to handle signals properly
+ENTRYPOINT ["dumb-init", "--"]
+
+# Start the application
+CMD ["node", "app.js"]
+```
+
+---
+
+## Variable Substitutions
+
+Replace these placeholders with context values:
+- `{port}` → `context.current_init.port` or `context.services[<service_name>].port`
+
+---
+
+## File Location
+
+Write to: `<service_name>/Dockerfile`
+
+---
+
+## Dependencies
+
+- Requires `package.json` to exist (Wave 1)
+- Requires `app.js` to exist (Wave 5)
+- Can be generated in Wave 6 (post-completion)
+
+---
+
+## What This Dockerfile Does
+
+1. **Multi-stage build** — reduces final image size by 40-60%
+2. **Alpine Linux** — minimal base image (~5MB vs ~150MB for full node)
+3. **Non-root user** — security best practice
+4. **dumb-init** — proper signal handling for graceful shutdowns
+5. **Health check** — container orchestration support
+6. **Production dependencies only** — no devDependencies in final image
+7. **Layer caching** — package.json copied before app code for faster rebuilds
+
+---
+
+## Security Features
+
+- Runs as non-root user (nodejs:nodejs with UID 1001)
+- No unnecessary packages installed
+- Proper file permissions for writable directories
+- Health check endpoint at `/health` (assumes route exists)
+
+---
+
+## Notes
+
+- The health check assumes a `/health` route exists on the service.
+  If not present, the nodejs-agent should generate a basic health
+  route in the default module during initialization.
+- Image size will be approximately 120-150MB depending on dependencies
+- Build time is optimized through layer caching — changing app code
+  does not invalidate the npm install layer

package/tasks/generate-dockerignore.task.md

@@ -0,0 +1,123 @@
+---
+type: task
+name: generate-dockerignore
+agent: nodejs-agent
+---
+
+# File: .dockerignore
+
+## Purpose
+Excludes unnecessary files and directories from the Docker build context,
+reducing build time and final image size. Mirrors .gitignore but with
+additional Docker-specific exclusions.
+
+---
+
+## Template
+
+```
+# Dependencies
+node_modules/
+npm-debug.log
+yarn-error.log
+package-lock.json
+
+# Environment files (will be provided at runtime)
+.env
+.env.*
+!.env.example
+
+# Logs
+logger/logs/
+*.log
+
+# Development files
+.vscode/
+.idea/
+.cursor/
+*.swp
+*.swo
+*~
+
+# Testing
+coverage/
+.nyc_output/
+*.test.js
+*.spec.js
+__tests__/
+
+# Documentation
+README.md
+docs/
+*.md
+!package.json
+
+# Git
+.git/
+.gitignore
+.gitattributes
+
+# Docker
+Dockerfile
+.dockerignore
+docker-compose*.yml
+
+# OS files
+.DS_Store
+Thumbs.db
+.cache/
+
+# Build artifacts
+dist/
+build/
+
+# IDE configs
+.codeninja/
+
+# Demo files
+enc_dec.html
+enc_dec.php
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+```
+
+---
+
+## File Location
+
+Write to: `<service_name>/.dockerignore`
+
+---
+
+## Dependencies
+
+None — can be generated in Wave 1 alongside .gitignore
+
+---
+
+## What This File Does
+
+1. **Excludes node_modules** — will be installed fresh in container
+2. **Excludes .env** — environment variables passed at runtime
+3. **Excludes logs** — logs are written at runtime, not baked into image
+4. **Excludes development files** — IDE configs, test files, docs
+5. **Excludes .codeninja** — agent system not needed in production
+
+---
+
+## Security Benefits
+
+- `.env` files never accidentally copied into image
+- Development-only secrets (.cursor, .vscode configs) excluded
+- Smaller attack surface (fewer files in image)
+
+---
+
+## Performance Benefits
+
+- Faster builds (smaller context sent to Docker daemon)
+- Better layer caching (changes to excluded files don't invalidate layers)
+- Smaller final image size