4runr-os 2.9.33 → 2.9.35

package/apps/gateway/.dockerignore

@@ -0,0 +1,11 @@
+# Exclude client-side packages that aren't needed on server
+packages/os-cli
+packages/cli
+packages/cli-tool
+packages/cli-tool-standalone
+
+# Exclude other client-side files
+4runr-os-enhanced.ts
+4runr-os.ts
+run-os.ps1
+

package/apps/gateway/.eslintrc.json

@@ -0,0 +1,28 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 2022,
+    "sourceType": "module"
+  },
+  "plugins": ["@typescript-eslint"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "off",
+    "@typescript-eslint/no-unused-vars": "warn",
+    "@typescript-eslint/no-non-null-assertion": "off"
+  },
+  "env": {
+    "node": true,
+    "es2022": true
+  },
+  "ignorePatterns": [
+    "**/__tests__/**",
+    "**/*.test.ts",
+    "dist/**"
+  ]
+}
+

package/apps/gateway/DEPLOYMENT.md

@@ -0,0 +1,426 @@
+# Deployment Guide
+
+Complete guide for deploying the 4Runr Gateway to production.
+
+## Table of Contents
+
+1. [Prerequisites](#prerequisites)
+2. [Pre-Deployment Checklist](#pre-deployment-checklist)
+3. [Environment Setup](#environment-setup)
+4. [Database Setup](#database-setup)
+5. [Deployment Methods](#deployment-methods)
+6. [Post-Deployment Verification](#post-deployment-verification)
+7. [Rollback Procedures](#rollback-procedures)
+8. [Scaling](#scaling)
+
+## Prerequisites
+
+### Infrastructure Requirements
+
+- **PostgreSQL 12+**: For persistent storage
+- **Redis 6+**: For queue, rate limiting, and idempotency
+- **Docker & Docker Compose**: For containerized deployment (recommended)
+- **Node.js 18+**: For direct deployment (alternative)
+
+### Security Requirements
+
+- Strong database passwords
+- Secure JWT secrets (min 32 characters)
+- Encryption keys for sensitive data
+- SSL/TLS certificates for HTTPS
+- Firewall rules configured
+
+### Network Requirements
+
+- Port 3000: Gateway API (or configure reverse proxy)
+- Port 5432: PostgreSQL (internal only)
+- Port 6379: Redis (internal only)
+
+## Pre-Deployment Checklist
+
+- [ ] All environment variables configured
+- [ ] Database migrations tested
+- [ ] Secrets generated and stored securely
+- [ ] Health checks configured
+- [ ] Monitoring and alerting set up
+- [ ] Backup strategy in place
+- [ ] Rollback plan documented
+- [ ] Load testing completed
+- [ ] Security audit performed
+
+## Environment Setup
+
+### 1. Generate Secure Secrets
+
+```bash
+# Generate JWT secret
+openssl rand -base64 32
+
+# Generate encryption key
+openssl rand -base64 32
+
+# Generate API keys (if using memory mode)
+openssl rand -hex 32
+```
+
+### 2. Create Production Environment File
+
+```bash
+cd infra
+cp env.example .env.production
+```
+
+Edit `.env.production` with production values:
+
+```bash
+NODE_ENV=production
+GATEWAY_PERSISTENCE=postgres
+DATABASE_URL=postgresql://user:strong-password@db-host:5432/4runr_gateway
+REDIS_URL=redis://redis-host:6379
+
+AUTH_ENABLED=true
+AUTH_MODE=mixed
+JWT_SECRET=<generated-secret>
+JWT_ALG=HS256
+
+RATE_LIMIT_ENABLED=true
+RATE_LIMIT_MAX=100
+RATE_LIMIT_WINDOW_MS=60000
+
+SENTINEL_STORE_PLAIN=false
+SENTINEL_MODE=live
+SENTINEL_SHIELD_MODE=enforce
+
+LOG_LEVEL=warn
+```
+
+### 3. Store Secrets Securely
+
+**DO NOT** commit secrets to version control. Use:
+- Environment variable management (AWS Secrets Manager, HashiCorp Vault, etc.)
+- Docker secrets
+- Kubernetes secrets
+- CI/CD secret management
+
+## Database Setup
+
+### 1. Create Database
+
+```sql
+CREATE DATABASE 4runr_gateway;
+CREATE USER 4runr WITH PASSWORD 'strong-password';
+GRANT ALL PRIVILEGES ON DATABASE 4runr_gateway TO 4runr;
+```
+
+### 2. Run Migrations
+
+```bash
+cd apps/gateway
+pnpm db:generate
+pnpm db:migrate
+```
+
+Or via Docker:
+```bash
+docker-compose -f infra/docker-compose.prod.yml run --rm gateway pnpm db:migrate
+```
+
+### 3. Seed Initial Data (Optional)
+
+```bash
+# Seed API key
+pnpm seed:api-key
+```
+
+## Deployment Methods
+
+### Method 1: Docker Compose (Recommended)
+
+**Best for**: Single server deployments, small to medium scale
+
+1. **Build and start:**
+```bash
+cd infra
+docker-compose -f docker-compose.prod.yml up -d --build
+```
+
+2. **Verify services:**
+```bash
+docker-compose -f docker-compose.prod.yml ps
+docker-compose -f docker-compose.prod.yml logs -f gateway
+```
+
+3. **Check health:**
+```bash
+curl http://localhost:3000/health
+curl http://localhost:3000/ready
+```
+
+### Method 2: Kubernetes
+
+**Best for**: Large scale, high availability
+
+1. **Create namespace:**
+```bash
+kubectl create namespace 4runr-gateway
+```
+
+2. **Create secrets:**
+```bash
+kubectl create secret generic gateway-secrets \
+  --from-literal=jwt-secret='your-secret' \
+  --from-literal=database-url='postgresql://...' \
+  --namespace=4runr-gateway
+```
+
+3. **Deploy:**
+```bash
+kubectl apply -f k8s/gateway-deployment.yaml
+kubectl apply -f k8s/gateway-service.yaml
+```
+
+### Method 3: Direct Node.js
+
+**Best for**: Development, custom deployments
+
+1. **Build:**
+```bash
+cd apps/gateway
+pnpm install
+pnpm build
+```
+
+2. **Start:**
+```bash
+NODE_ENV=production node dist/index.js
+```
+
+Or use PM2:
+```bash
+pm2 start dist/index.js --name gateway
+pm2 save
+pm2 startup
+```
+
+## Post-Deployment Verification
+
+### 1. Health Checks
+
+```bash
+# Liveness
+curl http://your-server/health
+# Expected: {"status":"ok"}
+
+# Readiness
+curl http://your-server/ready
+# Expected: {"ready":true,"checks":{...}}
+
+# Startup
+curl http://your-server/startup
+# Expected: {"started":true}
+```
+
+### 2. API Functionality
+
+```bash
+# Create a run
+curl -X POST http://your-server/api/runs \
+  -H "x-api-key: your-key" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Test Run", "input": {}}'
+
+# List runs
+curl http://your-server/api/runs \
+  -H "x-api-key: your-key"
+
+# Check metrics
+curl http://your-server/metrics
+```
+
+### 3. Monitor Logs
+
+```bash
+# Docker
+docker-compose -f infra/docker-compose.prod.yml logs -f gateway
+
+# Kubernetes
+kubectl logs -f deployment/gateway -n 4runr-gateway
+
+# PM2
+pm2 logs gateway
+```
+
+### 4. Check Metrics
+
+Access Prometheus metrics at `/metrics` and verify:
+- HTTP request counts
+- Run creation/start/completion rates
+- Error rates
+- Queue job metrics
+- Rate limit hits
+
+## Rollback Procedures
+
+### Quick Rollback (Docker Compose)
+
+```bash
+cd infra
+
+# Stop current version
+docker-compose -f docker-compose.prod.yml down
+
+# Switch to previous version
+git checkout <previous-version-tag>
+
+# Rebuild and start
+docker-compose -f docker-compose.prod.yml up -d --build
+```
+
+### Database Rollback
+
+If migrations need to be rolled back:
+
+```bash
+cd apps/gateway
+pnpm prisma migrate resolve --rolled-back <migration-name>
+```
+
+**Warning**: Only rollback migrations if you're certain no data depends on them.
+
+### Configuration Rollback
+
+```bash
+# Restore previous environment file
+cp .env.production.backup .env.production
+
+# Restart services
+docker-compose -f docker-compose.prod.yml restart gateway
+```
+
+## Scaling
+
+### Horizontal Scaling
+
+The gateway is stateless and can be scaled horizontally:
+
+```bash
+# Docker Compose (multiple instances)
+docker-compose -f docker-compose.prod.yml up -d --scale gateway=3
+
+# Kubernetes
+kubectl scale deployment gateway --replicas=3 -n 4runr-gateway
+```
+
+### Load Balancing
+
+Use a load balancer (nginx, HAProxy, AWS ALB) in front of multiple gateway instances:
+
+```nginx
+upstream gateway {
+    least_conn;
+    server gateway1:3000;
+    server gateway2:3000;
+    server gateway3:3000;
+}
+```
+
+### Database Scaling
+
+- Use connection pooling (Prisma handles this)
+- Consider read replicas for read-heavy workloads
+- Monitor connection counts
+
+### Redis Scaling
+
+- Use Redis Cluster for high availability
+- Configure Redis Sentinel for failover
+- Monitor memory usage
+
+## Monitoring & Alerting
+
+### Key Metrics to Monitor
+
+- **HTTP Request Rate**: Requests per second
+- **Error Rate**: 4xx and 5xx errors
+- **Response Time**: p50, p95, p99 latencies
+- **Queue Depth**: Number of jobs waiting
+- **Database Connections**: Active connections
+- **Memory Usage**: Container/node memory
+- **CPU Usage**: Container/node CPU
+
+### Recommended Alerts
+
+- Error rate > 1%
+- Response time p95 > 1s
+- Queue depth > 1000
+- Database connections > 80% of max
+- Memory usage > 80%
+- Health check failures
+
+## Backup & Recovery
+
+### Database Backups
+
+```bash
+# Daily backup script
+pg_dump -h db-host -U 4runr 4runr_gateway > backup-$(date +%Y%m%d).sql
+
+# Restore
+psql -h db-host -U 4runr 4runr_gateway < backup-20231119.sql
+```
+
+### Configuration Backups
+
+```bash
+# Backup environment file
+cp .env.production .env.production.backup
+
+# Backup docker-compose
+cp docker-compose.prod.yml docker-compose.prod.yml.backup
+```
+
+## Security Hardening
+
+### Production Security Checklist
+
+- [ ] HTTPS enabled (TLS 1.2+)
+- [ ] Security headers configured
+- [ ] Secrets stored securely (not in code)
+- [ ] Database access restricted (firewall)
+- [ ] Redis access restricted (firewall)
+- [ ] Rate limiting enabled
+- [ ] Authentication required
+- [ ] Error messages masked in production
+- [ ] Logging configured (no sensitive data)
+- [ ] Regular security updates
+
+### SSL/TLS Setup
+
+Use a reverse proxy (nginx, Traefik) for SSL termination:
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name api.yourdomain.com;
+    
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+    
+    location / {
+        proxy_pass http://gateway:3000;
+    }
+}
+```
+
+## Troubleshooting
+
+See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for common deployment issues.
+
+## Support
+
+For deployment issues:
+- Check logs: `docker-compose logs gateway`
+- Verify health: `curl http://localhost/health`
+- Review metrics: `curl http://localhost/metrics`
+- See troubleshooting guide
+

package/apps/gateway/Dockerfile

@@ -0,0 +1,122 @@
+FROM node:20-slim AS base
+WORKDIR /workspace
+RUN apt-get update && apt-get install -y ca-certificates curl && rm -rf /var/lib/apt/lists/*
+
+FROM base AS deps
+RUN apt-get update && apt-get install -y python3 make g++ openssl libssl-dev && rm -rf /var/lib/apt/lists/*
+COPY pnpm-workspace.yaml package.json tsconfig.json ./
+# Copy .npmrc if it exists (optional - create empty if missing)
+COPY apps/gateway ./apps/gateway
+# Copy packages directory but we'll remove client-side ones immediately
+COPY packages ./packages
+# Remove client-side packages BEFORE pnpm reads the workspace (os-cli depends on unpublished @4runr/devkit)
+RUN rm -rf packages/os-cli packages/cli packages/cli-tool packages/cli-tool-standalone packages/devkit || true
+COPY prisma ./prisma
+COPY src ./src
+# Create .npmrc if it doesn't exist (pnpm will work without it)
+RUN touch .npmrc || true
+RUN corepack enable && corepack prepare pnpm@9.12.1 --activate
+# Set node-linker to hoisted for flat node_modules structure
+RUN pnpm config set node-linker hoisted
+# Skip Prisma generation during install (we'll generate it in build if needed)
+ENV PRISMA_SKIP_POSTINSTALL_GENERATE=1
+RUN pnpm install --filter @4runr/shared --filter @4runr/sentinel --filter @4runr/gateway --workspace-root
+
+FROM deps AS build
+# Clean shared and sentinel package dists to ensure fresh build with updated types
+RUN rm -rf packages/shared/dist packages/shared/.tsbuildinfo packages/sentinel/dist packages/sentinel/.tsbuildinfo
+RUN pnpm --filter @4runr/shared run build
+RUN pnpm --filter @4runr/sentinel run build
+# Generate Prisma client before building gateway
+# Use dummy DATABASE_URL for generation (just needs schema, not actual connection)
+# Prisma schema is at /workspace/prisma/schema.prisma
+RUN cd /workspace/apps/gateway && \
+    export DATABASE_URL="postgresql://dummy:dummy@localhost:5432/dummy" && \
+    pnpm db:generate && \
+    (test -d node_modules/.prisma/client || test -d ../../node_modules/.prisma/client) && \
+    echo "✓ Prisma client generated" || echo "✗ Prisma client generation failed"
+# Compile root src/crypto folder (used by gateway routes)
+# Create a temporary tsconfig for compiling just the crypto folder
+RUN mkdir -p dist/src/crypto && \
+    echo '{"compilerOptions":{"target":"ES2022","module":"ES2022","moduleResolution":"bundler","esModuleInterop":true,"skipLibCheck":true,"outDir":"dist/src/crypto","rootDir":"src/crypto"},"include":["src/crypto/envelope.ts"]}' > /tmp/crypto-tsconfig.json && \
+    npx tsc --project /tmp/crypto-tsconfig.json 2>&1 | head -10 && \
+    test -f dist/src/crypto/envelope.js && echo "✓ Compiled envelope.js" || echo "⚠ envelope.js compilation may have failed"
+
+RUN rm -rf apps/gateway/dist && \
+    pnpm --filter @4runr/gateway run build && \
+    (test -f apps/gateway/dist/index.js || test -f apps/gateway/dist/apps/gateway/src/index.js) && \
+    echo "✓ Gateway build completed successfully" || \
+    (echo "✗ Build failed: index.js not found" && exit 1)
+
+FROM base AS runner
+WORKDIR /workspace
+RUN apt-get update && apt-get install -y openssl ca-certificates curl && rm -rf /var/lib/apt/lists/*
+# Copy package files, config, and built artifacts
+COPY --from=build /workspace/package.json ./package.json
+COPY --from=build /workspace/pnpm-workspace.yaml ./pnpm-workspace.yaml
+# .npmrc is optional - create empty if it doesn't exist
+RUN touch .npmrc || true
+COPY --from=build /workspace/packages ./packages
+COPY --from=build /workspace/apps/gateway/package.json ./apps/gateway/package.json
+COPY --from=build /workspace/apps/gateway/dist ./apps/gateway/dist
+# Copy public directory (static files like dashboard)
+COPY --from=deps /workspace/apps/gateway/public ./apps/gateway/public
+# Copy node_modules from build stage (hoisted node-linker creates flat structure)
+# Use --chown to set ownership during copy to avoid breaking symlinks
+COPY --from=build --chown=node:node /workspace/node_modules ./node_modules
+# Copy Prisma schema (needed for runtime client generation if needed)
+COPY --from=build /workspace/prisma ./prisma
+# Copy src directory (contains crypto and memory-db for AI providers)
+COPY --from=build /workspace/src ./src
+# Copy compiled crypto (if it was compiled)
+RUN mkdir -p dist/src && (cp -r /workspace/dist/src/* dist/src/ 2>/dev/null || echo "Note: No compiled src found")
+# Verify Prisma client was copied (could be in root node_modules with hoisted linker)
+RUN (test -d node_modules/.prisma/client || test -d apps/gateway/node_modules/.prisma/client) && \
+    echo "✓ Prisma client found" || \
+    echo "⚠ Prisma client not found - checking..." && \
+    find node_modules -name ".prisma" -type d 2>/dev/null | head -5 || \
+    echo "⚠ Will generate Prisma client at runtime if needed"
+# Verify shared package is accessible
+RUN test -d packages/shared/dist && echo "✓ shared/dist exists" || echo "✗ shared/dist missing"
+RUN test -f packages/shared/dist/index.js && echo "✓ shared/dist/index.js exists" || echo "✗ shared/dist/index.js missing"
+# Check if @4runr/shared exists and if it's a symlink
+# If not, create it (symlinks don't need special ownership)
+RUN if [ ! -L node_modules/@4runr/shared ] && [ ! -d node_modules/@4runr/shared ]; then \
+        echo "✗ @4runr/shared NOT found in node_modules, creating symlink..."; \
+        mkdir -p node_modules/@4runr && \
+        ln -s ../../packages/shared node_modules/@4runr/shared && \
+        echo "✓ Created symlink: node_modules/@4runr/shared -> ../../packages/shared"; \
+    fi
+# Verify the shared package's package.json exists (for ESM resolution)
+RUN test -f node_modules/@4runr/shared/package.json && echo "✓ @4runr/shared/package.json exists" || echo "✗ @4runr/shared/package.json missing"
+# Verify the package.json has the correct exports field for ESM resolution
+RUN node -e "try { const pkg = require('./node_modules/@4runr/shared/package.json'); if (pkg.exports && pkg.exports['.']) { console.log('✓ package.json exports field configured correctly'); } else { console.error('✗ package.json missing exports field'); process.exit(1); } } catch(e) { console.error('✗ Error reading shared package.json:', e.message); process.exit(1); }"
+# Verify Sentinel package is accessible
+RUN test -d packages/sentinel/dist && echo "✓ sentinel/dist exists" || echo "✗ sentinel/dist missing"
+RUN test -f packages/sentinel/dist/index.js && echo "✓ sentinel/dist/index.js exists" || echo "✗ sentinel/dist/index.js missing"
+# Check if @4runr/sentinel exists and if it's a symlink
+# If not, create it (symlinks don't need special ownership)
+RUN if [ ! -L node_modules/@4runr/sentinel ] && [ ! -d node_modules/@4runr/sentinel ]; then \
+        echo "✗ @4runr/sentinel NOT found in node_modules, creating symlink..."; \
+        mkdir -p node_modules/@4runr && \
+        ln -s ../../packages/sentinel node_modules/@4runr/sentinel && \
+        echo "✓ Created symlink: node_modules/@4runr/sentinel -> ../../packages/sentinel"; \
+    fi
+# Verify the Sentinel package's package.json exists (for ESM resolution)
+RUN test -f node_modules/@4runr/sentinel/package.json && echo "✓ @4runr/sentinel/package.json exists" || echo "✗ @4runr/sentinel/package.json missing"
+# Verify the package.json has the correct exports field for ESM resolution
+RUN node -e "try { const pkg = require('./node_modules/@4runr/sentinel/package.json'); if (pkg.exports && pkg.exports['.']) { console.log('✓ Sentinel package.json exports field configured correctly'); } else { console.error('✗ Sentinel package.json missing exports field'); process.exit(1); } } catch(e) { console.error('✗ Error reading Sentinel package.json:', e.message); process.exit(1); }"
+# Verify fastify exists (should be directly in node_modules with hoisted node-linker)
+RUN test -d node_modules/fastify && echo "✓ fastify found in node_modules" || \
+    (echo "✗ fastify NOT found!" && ls -la node_modules/ | head -40)
+RUN test -f node_modules/fastify/package.json && echo "✓ fastify package.json exists" || echo "✗ fastify package.json missing"
+# Test Node.js ESM resolution from the gateway dist directory
+RUN cd apps/gateway/dist && \
+    node --input-type=module -e "import('fastify').then(() => console.log('✓ Node.js can resolve fastify from dist')).catch(e => console.error('✗ Cannot resolve:', e.message))" || \
+    echo "Testing from workspace root:" && \
+    cd /workspace && \
+    node --input-type=module -e "import('fastify').then(() => console.log('✓ Node.js can resolve fastify from root')).catch(e => console.error('✗ Cannot resolve from root:', e.message))"
+USER node
+WORKDIR /workspace
+# Run from workspace root - Node.js ESM should find node_modules at /workspace/node_modules
+CMD ["node", "apps/gateway/dist/apps/gateway/src/index.js"]

package/apps/gateway/Dockerfile.bak

@@ -0,0 +1,41 @@
+FROM node:18-alpine AS base
+
+# Install dependencies only when needed
+FROM base AS deps
+RUN apk add --no-cache libc6-compat
+WORKDIR /app
+
+# Install dependencies based on the preferred package manager
+COPY package.json ./
+RUN npm install
+
+# Rebuild the source code only when needed
+FROM base AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+# Build the application
+RUN npm run build
+
+# Production image, copy all the files and run the app
+FROM base AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 4runr
+
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package.json ./package.json
+
+USER 4runr
+
+EXPOSE 3000
+
+ENV PORT=3000
+ENV HOST=0.0.0.0
+
+CMD ["node", "dist/index.js"]