ultra-dex 3.2.0 → 3.4.0

package/README.md

@@ -2,23 +2,31 @@
 
 > Scaffold Ultra-Dex projects from the command line, now with **AI-powered plan generation** and **God Mode** autonomous agents.
 
-## What's New in v3.2.0 (Professional Purple)
+## What's New in v3.4.0 (Survival Mode)
 
 ```bash
+# 🧠 Auto-sync CONTEXT.md from codebase (eliminates manual updates)
+npx ultra-dex sync --brain
+
+# 🐳 Execute code in Docker sandbox
+npx ultra-dex exec "console.log('safe!')" --lang javascript
+
+# 🔍 Semantic search with vector embeddings
+npx ultra-dex search "user authentication" --index
+
+# 🐙 GitHub integration (issues → tasks, auto-PR)
+npx ultra-dex github sync
+npx ultra-dex github pr --from-swarm
+
 # 🤖 Autonomous agent swarms with parallel execution
 npx ultra-dex swarm "Build user authentication" --parallel
 
 # 🔄 Start the Active Kernel (MCP + WebSocket + Dashboard)
 npx ultra-dex serve
 
-# 🧠 Structural Graph Health Check
-npx ultra-dex check
-
-# 🖥️ Live Dashboard with Brain Visualization
-npx ultra-dex dashboard
-
-# 🛠️ Self-Healing CI/CD Monitor
-npx ultra-dex ci-monitor --port 3003
+# 📊 Health monitoring and metrics
+npx ultra-dex health
+npx ultra-dex metrics
 ```
 
 ## First 10 Minutes
@@ -156,10 +164,37 @@ npx ultra-dex check
 ANTHROPIC_API_KEY=sk-ant-...  # Claude (recommended for complex tasks)
 OPENAI_API_KEY=sk-...         # OpenAI
 GOOGLE_AI_KEY=...             # Gemini
+OLLAMA_HOST=http://localhost:11434  # Ollama (local AI)
 ULTRA_DEX_DEFAULT_PROVIDER=claude # Default AI provider
 ```
 
-## All Commands (38+)
+## Local AI with Ollama
+
+Ultra-Dex supports Ollama for fully local, private AI operations:
+
+```bash
+# 1. Install Ollama (https://ollama.ai)
+curl -fsSL https://ollama.ai/install.sh | sh
+
+# 2. Pull a model
+ollama pull llama3.2
+ollama pull codellama
+
+# 3. Use with Ultra-Dex
+npx ultra-dex generate "Your idea" --provider ollama --model codellama
+
+# For agent swarms with local AI
+npx ultra-dex swarm "Build user auth" --provider ollama
+```
+
+**Supported Ollama Models:**
+- `llama3.2` - General tasks
+- `codellama` - Code generation (recommended)
+- `mistral` - Fast, efficient
+- `mixtral` - Best quality for local
+- Any model available via `ollama list`
+
+## All Commands (44+)
 
 | Command | Description |
 |---------|-------------|
@@ -201,6 +236,13 @@ ULTRA_DEX_DEFAULT_PROVIDER=claude # Default AI provider
 | `pack` | Bundle agents and rules |
 | `run` | Execute agent task |
 | `diff` | Compare plan vs implemented code |
+| `exec` | **NEW** Execute code in Docker sandbox |
+| `search` | **NEW** Semantic codebase search |
+| `github` | **NEW** GitHub sync (issues, PRs) |
+| `cloud` | **NEW** Team collaboration server |
+| `metrics` | **NEW** Show CLI metrics |
+| `health` | **NEW** System health check |
+| `debug` | **NEW** Debug information |
 
 ## Links
 

package/assets/cursor-rules/18-webhooks.mdc

@@ -0,0 +1,52 @@
+# Webhook Implementation Rules
+
+## Webhook Endpoint Design
+- Use POST method for incoming webhooks
+- Validate webhook signatures (HMAC-SHA256)
+- Return 200 immediately, process async
+- Implement idempotency with event IDs
+
+## Security
+```typescript
+// Verify webhook signature
+async function verifyWebhook(req: Request, secret: string) {
+  const signature = req.headers.get('x-signature-256');
+  const body = await req.text();
+  const expected = crypto
+    .createHmac('sha256', secret)
+    .update(body)
+    .digest('hex');
+  return crypto.timingSafeEqual(
+    Buffer.from(signature || ''),
+    Buffer.from(`sha256=${expected}`)
+  );
+}
+```
+
+## Retry Strategy
+- Implement exponential backoff (1s, 2s, 4s, 8s, 16s)
+- Max 5 retry attempts
+- Store failed webhooks for manual retry
+- Log all webhook attempts with correlation IDs
+
+## Event Processing
+```typescript
+// Idempotent webhook handler
+async function handleWebhook(event: WebhookEvent) {
+  const existing = await db.webhookEvent.findUnique({
+    where: { eventId: event.id }
+  });
+  if (existing) return { status: 'duplicate' };
+
+  await db.$transaction([
+    db.webhookEvent.create({ data: { eventId: event.id } }),
+    processEvent(event)
+  ]);
+}
+```
+
+## Outbound Webhooks
+- Queue outbound webhooks with job processor
+- Include timestamp and signature in headers
+- Support webhook URL validation before saving
+- Implement circuit breaker for failing endpoints

package/assets/cursor-rules/19-cron-jobs.mdc

@@ -0,0 +1,61 @@
+# Cron & Scheduled Jobs Rules
+
+## Job Scheduling Patterns
+- Use cron expressions for recurring jobs
+- Store job definitions in database, not code
+- Implement job locking for distributed systems
+- Track job execution history
+
+## Implementation
+```typescript
+// Next.js API route with Vercel Cron
+// vercel.json: { "crons": [{ "path": "/api/cron/daily", "schedule": "0 0 * * *" }] }
+
+export async function GET(req: Request) {
+  // Verify cron secret
+  const authHeader = req.headers.get('authorization');
+  if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
+    return new Response('Unauthorized', { status: 401 });
+  }
+
+  // Execute with timeout protection
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 55000);
+
+  try {
+    await runDailyTasks({ signal: controller.signal });
+    return Response.json({ success: true });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+```
+
+## Job Locking
+```typescript
+// Prevent concurrent execution
+async function withJobLock(jobName: string, fn: () => Promise<void>) {
+  const lock = await db.jobLock.create({
+    data: {
+      name: jobName,
+      lockedAt: new Date(),
+      expiresAt: new Date(Date.now() + 60000)
+    }
+  }).catch(() => null);
+
+  if (!lock) return { skipped: true };
+
+  try {
+    await fn();
+    return { success: true };
+  } finally {
+    await db.jobLock.delete({ where: { name: jobName } });
+  }
+}
+```
+
+## Monitoring
+- Log job start/end with duration
+- Alert on job failures or timeouts
+- Track job queue depth
+- Implement dead letter queue for failed jobs

package/assets/cursor-rules/20-rate-limiting.mdc

@@ -0,0 +1,59 @@
+# Rate Limiting Rules
+
+## Strategy Selection
+- Token bucket for API endpoints
+- Sliding window for auth attempts
+- Fixed window for simple limits
+- Leaky bucket for smoothing bursts
+
+## Implementation
+```typescript
+// Redis-based rate limiter
+import { Ratelimit } from '@upstash/ratelimit';
+import { Redis } from '@upstash/redis';
+
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, '10 s'),
+  analytics: true,
+  prefix: 'api',
+});
+
+// Middleware
+export async function rateLimitMiddleware(req: Request) {
+  const ip = req.headers.get('x-forwarded-for') ?? '127.0.0.1';
+  const { success, limit, reset, remaining } = await ratelimit.limit(ip);
+
+  if (!success) {
+    return new Response('Rate limit exceeded', {
+      status: 429,
+      headers: {
+        'X-RateLimit-Limit': limit.toString(),
+        'X-RateLimit-Remaining': remaining.toString(),
+        'X-RateLimit-Reset': reset.toString(),
+        'Retry-After': Math.ceil((reset - Date.now()) / 1000).toString(),
+      },
+    });
+  }
+}
+```
+
+## Tiered Limits
+```typescript
+const RATE_LIMITS = {
+  free: { requests: 100, window: '1 h' },
+  pro: { requests: 1000, window: '1 h' },
+  enterprise: { requests: 10000, window: '1 h' },
+};
+
+async function getRateLimit(userId: string) {
+  const user = await getUser(userId);
+  return RATE_LIMITS[user.plan];
+}
+```
+
+## Headers to Return
+- `X-RateLimit-Limit`: Total allowed requests
+- `X-RateLimit-Remaining`: Requests left in window
+- `X-RateLimit-Reset`: Unix timestamp when limit resets
+- `Retry-After`: Seconds until retry (on 429)

package/assets/cursor-rules/21-logging.mdc

@@ -0,0 +1,58 @@
+# Structured Logging Rules
+
+## Log Levels
+- ERROR: System failures, requires immediate action
+- WARN: Unexpected but recoverable situations
+- INFO: Business events, request lifecycle
+- DEBUG: Detailed diagnostic information
+
+## Structured Format
+```typescript
+import pino from 'pino';
+
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  formatters: {
+    level: (label) => ({ level: label }),
+  },
+  timestamp: pino.stdTimeFunctions.isoTime,
+  base: {
+    service: 'ultra-dex',
+    version: process.env.VERSION,
+    env: process.env.NODE_ENV,
+  },
+});
+
+// Usage
+logger.info({ userId, action: 'login' }, 'User logged in');
+logger.error({ err, requestId }, 'Payment failed');
+```
+
+## Request Context
+```typescript
+// Add request ID to all logs
+import { AsyncLocalStorage } from 'async_hooks';
+
+const requestContext = new AsyncLocalStorage<{ requestId: string }>();
+
+export function withRequestId(req: Request, fn: () => Promise<Response>) {
+  const requestId = req.headers.get('x-request-id') || crypto.randomUUID();
+  return requestContext.run({ requestId }, fn);
+}
+
+export function getRequestId() {
+  return requestContext.getStore()?.requestId;
+}
+```
+
+## What to Log
+- Request: method, path, user, duration, status
+- Errors: stack, context, correlation ID
+- Business: user actions, state changes, payments
+- Never log: passwords, tokens, PII, credit cards
+
+## Log Aggregation
+- Use JSON format for machine parsing
+- Send to centralized service (Datadog, Logtail, Axiom)
+- Set up alerts for error rate spikes
+- Implement log sampling for high-volume endpoints

package/assets/cursor-rules/22-caching.mdc

@@ -0,0 +1,70 @@
+# Caching Strategy Rules
+
+## Cache Layers
+1. Browser cache (Cache-Control headers)
+2. CDN/Edge cache (Vercel, Cloudflare)
+3. Application cache (Redis, in-memory)
+4. Database cache (query cache, materialized views)
+
+## HTTP Caching
+```typescript
+// Next.js cache headers
+export async function GET() {
+  const data = await fetchData();
+
+  return Response.json(data, {
+    headers: {
+      'Cache-Control': 'public, s-maxage=60, stale-while-revalidate=300',
+    },
+  });
+}
+
+// Static pages
+export const revalidate = 3600; // ISR: revalidate every hour
+```
+
+## Redis Caching
+```typescript
+import { Redis } from '@upstash/redis';
+
+const redis = Redis.fromEnv();
+
+async function getCached<T>(
+  key: string,
+  fetcher: () => Promise<T>,
+  ttl = 3600
+): Promise<T> {
+  const cached = await redis.get<T>(key);
+  if (cached) return cached;
+
+  const fresh = await fetcher();
+  await redis.set(key, fresh, { ex: ttl });
+  return fresh;
+}
+
+// Usage
+const user = await getCached(
+  `user:${userId}`,
+  () => db.user.findUnique({ where: { id: userId } }),
+  300
+);
+```
+
+## Cache Invalidation
+```typescript
+// Event-driven invalidation
+async function updateUser(userId: string, data: UpdateData) {
+  await db.user.update({ where: { id: userId }, data });
+
+  // Invalidate related caches
+  await redis.del(`user:${userId}`);
+  await redis.del(`user:${userId}:profile`);
+  await redis.del(`team:${data.teamId}:members`);
+}
+```
+
+## Cache Patterns
+- Cache-aside: App manages cache
+- Write-through: Write to cache + DB
+- Write-behind: Write to cache, async DB
+- Read-through: Cache fetches on miss

package/assets/cursor-rules/23-forms.mdc

@@ -0,0 +1,67 @@
+# Form Handling Rules
+
+## Server Actions (Next.js 15)
+```typescript
+'use server';
+
+import { z } from 'zod';
+import { revalidatePath } from 'next/cache';
+
+const schema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2).max(100),
+});
+
+export async function createUser(formData: FormData) {
+  const parsed = schema.safeParse({
+    email: formData.get('email'),
+    name: formData.get('name'),
+  });
+
+  if (!parsed.success) {
+    return { error: parsed.error.flatten().fieldErrors };
+  }
+
+  await db.user.create({ data: parsed.data });
+  revalidatePath('/users');
+  return { success: true };
+}
+```
+
+## Client Form Component
+```tsx
+'use client';
+
+import { useActionState } from 'react';
+import { createUser } from './actions';
+
+export function CreateUserForm() {
+  const [state, formAction, pending] = useActionState(createUser, null);
+
+  return (
+    <form action={formAction}>
+      <input name="email" type="email" required />
+      {state?.error?.email && <p className="error">{state.error.email}</p>}
+
+      <input name="name" required />
+      {state?.error?.name && <p className="error">{state.error.name}</p>}
+
+      <button disabled={pending}>
+        {pending ? 'Creating...' : 'Create User'}
+      </button>
+    </form>
+  );
+}
+```
+
+## Validation
+- Client: HTML5 validation + real-time feedback
+- Server: Always re-validate with Zod
+- Sanitize: Strip HTML, trim whitespace
+- Rate limit: Form submissions per IP
+
+## File Uploads
+- Use presigned URLs for large files
+- Validate file type on both client and server
+- Set maximum file size limits
+- Scan uploads for malware in production

package/assets/cursor-rules/24-file-upload.mdc

@@ -0,0 +1,78 @@
+# File Upload Rules
+
+## Presigned URL Pattern
+```typescript
+// Server action to get upload URL
+'use server';
+
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+
+const s3 = new S3Client({ region: process.env.AWS_REGION });
+
+export async function getUploadUrl(filename: string, contentType: string) {
+  const key = `uploads/${crypto.randomUUID()}/${filename}`;
+
+  const command = new PutObjectCommand({
+    Bucket: process.env.S3_BUCKET,
+    Key: key,
+    ContentType: contentType,
+  });
+
+  const url = await getSignedUrl(s3, command, { expiresIn: 3600 });
+  return { url, key };
+}
+```
+
+## Client Upload
+```typescript
+async function uploadFile(file: File) {
+  // 1. Get presigned URL
+  const { url, key } = await getUploadUrl(file.name, file.type);
+
+  // 2. Upload directly to S3
+  await fetch(url, {
+    method: 'PUT',
+    body: file,
+    headers: { 'Content-Type': file.type },
+  });
+
+  // 3. Save reference to database
+  await saveFileReference(key);
+}
+```
+
+## Validation
+```typescript
+const ALLOWED_TYPES = ['image/jpeg', 'image/png', 'image/webp', 'application/pdf'];
+const MAX_SIZE = 10 * 1024 * 1024; // 10MB
+
+function validateFile(file: File) {
+  if (!ALLOWED_TYPES.includes(file.type)) {
+    throw new Error('Invalid file type');
+  }
+  if (file.size > MAX_SIZE) {
+    throw new Error('File too large');
+  }
+}
+```
+
+## Image Processing
+```typescript
+// Process uploaded images
+import sharp from 'sharp';
+
+async function processImage(buffer: Buffer) {
+  return sharp(buffer)
+    .resize(1200, 1200, { fit: 'inside', withoutEnlargement: true })
+    .webp({ quality: 80 })
+    .toBuffer();
+}
+```
+
+## Security
+- Validate MIME type server-side (don't trust Content-Type)
+- Generate random filenames to prevent enumeration
+- Serve uploads from separate domain/CDN
+- Set Content-Disposition: attachment for downloads
+- Scan files with antivirus in production

package/assets/cursor-rules/25-websockets.mdc

@@ -0,0 +1,100 @@
+# WebSocket & Real-time Rules
+
+## Connection Management
+```typescript
+// Server setup with ws
+import { WebSocketServer } from 'ws';
+
+const wss = new WebSocketServer({ port: 8080 });
+const clients = new Map<string, WebSocket>();
+
+wss.on('connection', (ws, req) => {
+  const userId = authenticateFromHeaders(req);
+  if (!userId) return ws.close(4001, 'Unauthorized');
+
+  clients.set(userId, ws);
+
+  ws.on('message', (data) => handleMessage(userId, data));
+  ws.on('close', () => clients.delete(userId));
+  ws.on('error', (err) => console.error('WS error:', err));
+
+  // Heartbeat
+  ws.isAlive = true;
+  ws.on('pong', () => { ws.isAlive = true; });
+});
+
+// Ping interval
+setInterval(() => {
+  wss.clients.forEach((ws) => {
+    if (!ws.isAlive) return ws.terminate();
+    ws.isAlive = false;
+    ws.ping();
+  });
+}, 30000);
+```
+
+## Message Protocol
+```typescript
+interface WSMessage {
+  type: string;
+  payload: unknown;
+  timestamp: number;
+  correlationId?: string;
+}
+
+function handleMessage(userId: string, data: Buffer) {
+  const message: WSMessage = JSON.parse(data.toString());
+
+  switch (message.type) {
+    case 'subscribe':
+      subscribeToChannel(userId, message.payload.channel);
+      break;
+    case 'unsubscribe':
+      unsubscribeFromChannel(userId, message.payload.channel);
+      break;
+    default:
+      sendError(userId, 'Unknown message type');
+  }
+}
+```
+
+## Broadcasting
+```typescript
+// Pub/sub with Redis for horizontal scaling
+import { Redis } from 'ioredis';
+
+const pub = new Redis(process.env.REDIS_URL);
+const sub = new Redis(process.env.REDIS_URL);
+
+sub.subscribe('notifications');
+sub.on('message', (channel, message) => {
+  const { userIds, data } = JSON.parse(message);
+  userIds.forEach((userId: string) => {
+    clients.get(userId)?.send(JSON.stringify(data));
+  });
+});
+
+export function broadcast(userIds: string[], data: unknown) {
+  pub.publish('notifications', JSON.stringify({ userIds, data }));
+}
+```
+
+## Client Reconnection
+```typescript
+function createReconnectingSocket(url: string) {
+  let ws: WebSocket;
+  let reconnectDelay = 1000;
+
+  function connect() {
+    ws = new WebSocket(url);
+    ws.onopen = () => { reconnectDelay = 1000; };
+    ws.onclose = () => {
+      setTimeout(connect, reconnectDelay);
+      reconnectDelay = Math.min(reconnectDelay * 2, 30000);
+    };
+  }
+
+  connect();
+  return { send: (data: unknown) => ws.send(JSON.stringify(data)) };
+}
+```