cmp-standards 2.6.0 → 2.8.0-alpha

package/standards/infrastructure/cloud-database.md

@@ -1,287 +1,287 @@
-# Infraestructura de Base de Datos Cloud
-
-## Stack Recomendado (100% Gratuito)
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    ARQUITECTURA CLOUD                        │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
-│  │   Turso     │  │  Upstash    │  │  Upstash    │         │
-│  │  (SQLite)   │  │  (Vector)   │  │  (Redis)    │         │
-│  │             │  │             │  │             │         │
-│  │ • Tareas    │  │ • Embeddings│  │ • Cache     │         │
-│  │ • Mejoras   │  │ • Semantic  │  │ • Sessions  │         │
-│  │ • Sesiones  │  │   Search    │  │ • Config    │         │
-│  │ • Memorias  │  │             │  │             │         │
-│  └─────────────┘  └─────────────┘  └─────────────┘         │
-│        │                │                │                  │
-│        └────────────────┼────────────────┘                  │
-│                         │                                   │
-│                         ▼                                   │
-│              ┌─────────────────────┐                        │
-│              │   MCP Server        │                        │
-│              │ (Vercel Edge)       │                        │
-│              └─────────────────────┘                        │
-│                         │                                   │
-│                         ▼                                   │
-│              ┌─────────────────────┐                        │
-│              │   Claude Code       │                        │
-│              └─────────────────────┘                        │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## Turso (SQLite Edge)
-
-**Propósito**: Base de datos principal para tareas, mejoras, memorias.
-
-### Free Tier
-- 500M rows read/mes
-- 10M rows written/mes
-- 5GB storage
-- 100 databases
-- Sin tarjeta de crédito
-
-### Setup
-
-```bash
-# Instalar CLI
-brew install tursodatabase/tap/turso
-
-# Login
-turso auth login
-
-# Crear database
-turso db create cmp-memory
-
-# Obtener URL
-turso db show cmp-memory --url
-# → libsql://cmp-memory-username.turso.io
-
-# Crear token
-turso db tokens create cmp-memory
-```
-
-### Configuración
-
-```typescript
-// src/db/turso-client.ts
-import { createClient } from '@libsql/client'
-import { drizzle } from 'drizzle-orm/libsql'
-
-export function createTursoDB() {
-  const client = createClient({
-    url: process.env.TURSO_DATABASE_URL!,
-    authToken: process.env.TURSO_AUTH_TOKEN!
-  })
-
-  return drizzle(client)
-}
-```
-
-### Variables de Entorno
-
-```env
-TURSO_DATABASE_URL=libsql://cmp-memory-username.turso.io
-TURSO_AUTH_TOKEN=eyJ...
-```
-
-## Upstash Vector
-
-**Propósito**: Búsqueda semántica de memorias y contexto.
-
-### Free Tier
-- 200M vectors
-- 1GB data/metadata
-- 10K queries/día
-- Built-in embeddings
-
-### Setup
-
-```bash
-# Crear en dashboard: https://console.upstash.com/vector
-# Obtener UPSTASH_VECTOR_REST_URL y UPSTASH_VECTOR_REST_TOKEN
-```
-
-### Configuración
-
-```typescript
-// src/db/vector-client.ts
-import { Index } from '@upstash/vector'
-
-export const vectorIndex = new Index({
-  url: process.env.UPSTASH_VECTOR_REST_URL!,
-  token: process.env.UPSTASH_VECTOR_REST_TOKEN!
-})
-
-// Insertar con embedding automático
-await vectorIndex.upsert({
-  id: 'mem_123',
-  data: 'Este es el contenido de la memoria...',
-  metadata: {
-    type: 'memory',
-    domain: 'video-studio',
-    createdAt: new Date().toISOString()
-  }
-})
-
-// Buscar por similitud
-const results = await vectorIndex.query({
-  data: 'buscar memorias sobre video',
-  topK: 5,
-  includeMetadata: true
-})
-```
-
-### Variables de Entorno
-
-```env
-UPSTASH_VECTOR_REST_URL=https://abc-xyz.upstash.io
-UPSTASH_VECTOR_REST_TOKEN=AXxx...
-```
-
-## Upstash Redis
-
-**Propósito**: Cache de configuración y sesiones activas.
-
-### Free Tier
-- 10K commands/día
-- 256MB storage
-- Global replication
-
-### Setup
-
-```bash
-# Crear en dashboard: https://console.upstash.com/redis
-# Obtener UPSTASH_REDIS_REST_URL y UPSTASH_REDIS_REST_TOKEN
-```
-
-### Configuración
-
-```typescript
-// src/db/redis-client.ts
-import { Redis } from '@upstash/redis'
-
-export const redis = new Redis({
-  url: process.env.UPSTASH_REDIS_REST_URL!,
-  token: process.env.UPSTASH_REDIS_REST_TOKEN!
-})
-
-// Cache de config (TTL 1 hora)
-await redis.set('config:SWARMSCALE', config, { ex: 3600 })
-
-// Leer config
-const cached = await redis.get('config:SWARMSCALE')
-
-// Sesiones activas
-await redis.hset('sessions:active', {
-  [sessionId]: JSON.stringify(sessionData)
-})
-```
-
-### Variables de Entorno
-
-```env
-UPSTASH_REDIS_REST_URL=https://def-uvw.upstash.io
-UPSTASH_REDIS_REST_TOKEN=AYyy...
-```
-
-## Migración desde PlanetScale/Railway
-
-### Estrategia
-
-1. **Fase 1**: Dual-write (escribir a ambos)
-2. **Fase 2**: Read from Turso, write to both
-3. **Fase 3**: Full migration, keep PlanetScale as backup
-
-### Script de Migración
-
-```typescript
-// scripts/migrate-to-turso.ts
-import { db as planetscale } from './db/planetscale'
-import { db as turso } from './db/turso'
-
-async function migrate() {
-  console.log('Fetching memories from PlanetScale...')
-
-  const memories = await planetscale.query.devItems.findMany({
-    where: eq(devItems.system, 'SWARMSCALE')
-  })
-
-  console.log(`Found ${memories.length} memories`)
-
-  // Batch insert to Turso
-  for (const batch of chunk(memories, 100)) {
-    await turso.insert(devItems).values(batch)
-    console.log(`Migrated ${batch.length} items`)
-  }
-
-  console.log('Migration complete!')
-}
-```
-
-## Costos Estimados
-
-| Uso | Turso | Vector | Redis | Total |
-|-----|-------|--------|-------|-------|
-| Desarrollo | $0 | $0 | $0 | **$0** |
-| Producción pequeña | $0 | $0 | $0 | **$0** |
-| Producción media | $4.99 | $0 | $0 | **$4.99** |
-| Producción alta | $29 | $60 | $10 | **$99** |
-
-## Configuración Completa
-
-```env
-# .env.cloud
-
-# Turso (SQLite)
-TURSO_DATABASE_URL=libsql://cmp-memory-username.turso.io
-TURSO_AUTH_TOKEN=eyJ...
-
-# Upstash Vector
-UPSTASH_VECTOR_REST_URL=https://abc-xyz.upstash.io
-UPSTASH_VECTOR_REST_TOKEN=AXxx...
-
-# Upstash Redis
-UPSTASH_REDIS_REST_URL=https://def-uvw.upstash.io
-UPSTASH_REDIS_REST_TOKEN=AYyy...
-
-# Embeddings (para generar si no usas built-in de Upstash)
-OPENAI_API_KEY=sk-...
-```
-
-## Package Dependencies
-
-```json
-{
-  "dependencies": {
-    "@libsql/client": "^0.5.0",
-    "@upstash/vector": "^1.0.0",
-    "@upstash/redis": "^1.28.0",
-    "drizzle-orm": "^0.30.0"
-  }
-}
-```
-
-## Fallback Strategy
-
-Si un servicio falla, tener fallback:
-
-```typescript
-async function getMemories(query: string) {
-  try {
-    // Primary: Upstash Vector (semantic search)
-    return await vectorIndex.query({ data: query, topK: 10 })
-  } catch (error) {
-    console.error('Vector search failed, falling back to SQL')
-
-    // Fallback: Turso (SQL LIKE search)
-    return await turso.query.devItems.findMany({
-      where: like(devItems.content, `%${query}%`),
-      limit: 10
-    })
-  }
-}
-```
+# Infraestructura de Base de Datos Cloud
+
+## Stack Recomendado (100% Gratuito)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    ARQUITECTURA CLOUD                        │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
+│  │   Turso     │  │  Upstash    │  │  Upstash    │         │
+│  │  (SQLite)   │  │  (Vector)   │  │  (Redis)    │         │
+│  │             │  │             │  │             │         │
+│  │ • Tareas    │  │ • Embeddings│  │ • Cache     │         │
+│  │ • Mejoras   │  │ • Semantic  │  │ • Sessions  │         │
+│  │ • Sesiones  │  │   Search    │  │ • Config    │         │
+│  │ • Memorias  │  │             │  │             │         │
+│  └─────────────┘  └─────────────┘  └─────────────┘         │
+│        │                │                │                  │
+│        └────────────────┼────────────────┘                  │
+│                         │                                   │
+│                         ▼                                   │
+│              ┌─────────────────────┐                        │
+│              │   MCP Server        │                        │
+│              │ (Vercel Edge)       │                        │
+│              └─────────────────────┘                        │
+│                         │                                   │
+│                         ▼                                   │
+│              ┌─────────────────────┐                        │
+│              │   Claude Code       │                        │
+│              └─────────────────────┘                        │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Turso (SQLite Edge)
+
+**Propósito**: Base de datos principal para tareas, mejoras, memorias.
+
+### Free Tier
+- 500M rows read/mes
+- 10M rows written/mes
+- 5GB storage
+- 100 databases
+- Sin tarjeta de crédito
+
+### Setup
+
+```bash
+# Instalar CLI
+brew install tursodatabase/tap/turso
+
+# Login
+turso auth login
+
+# Crear database
+turso db create cmp-memory
+
+# Obtener URL
+turso db show cmp-memory --url
+# → libsql://cmp-memory-username.turso.io
+
+# Crear token
+turso db tokens create cmp-memory
+```
+
+### Configuración
+
+```typescript
+// src/db/turso-client.ts
+import { createClient } from '@libsql/client'
+import { drizzle } from 'drizzle-orm/libsql'
+
+export function createTursoDB() {
+  const client = createClient({
+    url: process.env.TURSO_DATABASE_URL!,
+    authToken: process.env.TURSO_AUTH_TOKEN!
+  })
+
+  return drizzle(client)
+}
+```
+
+### Variables de Entorno
+
+```env
+TURSO_DATABASE_URL=libsql://cmp-memory-username.turso.io
+TURSO_AUTH_TOKEN=eyJ...
+```
+
+## Upstash Vector
+
+**Propósito**: Búsqueda semántica de memorias y contexto.
+
+### Free Tier
+- 200M vectors
+- 1GB data/metadata
+- 10K queries/día
+- Built-in embeddings
+
+### Setup
+
+```bash
+# Crear en dashboard: https://console.upstash.com/vector
+# Obtener UPSTASH_VECTOR_REST_URL y UPSTASH_VECTOR_REST_TOKEN
+```
+
+### Configuración
+
+```typescript
+// src/db/vector-client.ts
+import { Index } from '@upstash/vector'
+
+export const vectorIndex = new Index({
+  url: process.env.UPSTASH_VECTOR_REST_URL!,
+  token: process.env.UPSTASH_VECTOR_REST_TOKEN!
+})
+
+// Insertar con embedding automático
+await vectorIndex.upsert({
+  id: 'mem_123',
+  data: 'Este es el contenido de la memoria...',
+  metadata: {
+    type: 'memory',
+    domain: 'video-studio',
+    createdAt: new Date().toISOString()
+  }
+})
+
+// Buscar por similitud
+const results = await vectorIndex.query({
+  data: 'buscar memorias sobre video',
+  topK: 5,
+  includeMetadata: true
+})
+```
+
+### Variables de Entorno
+
+```env
+UPSTASH_VECTOR_REST_URL=https://abc-xyz.upstash.io
+UPSTASH_VECTOR_REST_TOKEN=AXxx...
+```
+
+## Upstash Redis
+
+**Propósito**: Cache de configuración y sesiones activas.
+
+### Free Tier
+- 10K commands/día
+- 256MB storage
+- Global replication
+
+### Setup
+
+```bash
+# Crear en dashboard: https://console.upstash.com/redis
+# Obtener UPSTASH_REDIS_REST_URL y UPSTASH_REDIS_REST_TOKEN
+```
+
+### Configuración
+
+```typescript
+// src/db/redis-client.ts
+import { Redis } from '@upstash/redis'
+
+export const redis = new Redis({
+  url: process.env.UPSTASH_REDIS_REST_URL!,
+  token: process.env.UPSTASH_REDIS_REST_TOKEN!
+})
+
+// Cache de config (TTL 1 hora)
+await redis.set('config:SWARMSCALE', config, { ex: 3600 })
+
+// Leer config
+const cached = await redis.get('config:SWARMSCALE')
+
+// Sesiones activas
+await redis.hset('sessions:active', {
+  [sessionId]: JSON.stringify(sessionData)
+})
+```
+
+### Variables de Entorno
+
+```env
+UPSTASH_REDIS_REST_URL=https://def-uvw.upstash.io
+UPSTASH_REDIS_REST_TOKEN=AYyy...
+```
+
+## Migración desde PlanetScale/Railway
+
+### Estrategia
+
+1. **Fase 1**: Dual-write (escribir a ambos)
+2. **Fase 2**: Read from Turso, write to both
+3. **Fase 3**: Full migration, keep PlanetScale as backup
+
+### Script de Migración
+
+```typescript
+// scripts/migrate-to-turso.ts
+import { db as planetscale } from './db/planetscale'
+import { db as turso } from './db/turso'
+
+async function migrate() {
+  console.log('Fetching memories from PlanetScale...')
+
+  const memories = await planetscale.query.devItems.findMany({
+    where: eq(devItems.system, 'SWARMSCALE')
+  })
+
+  console.log(`Found ${memories.length} memories`)
+
+  // Batch insert to Turso
+  for (const batch of chunk(memories, 100)) {
+    await turso.insert(devItems).values(batch)
+    console.log(`Migrated ${batch.length} items`)
+  }
+
+  console.log('Migration complete!')
+}
+```
+
+## Costos Estimados
+
+| Uso | Turso | Vector | Redis | Total |
+|-----|-------|--------|-------|-------|
+| Desarrollo | $0 | $0 | $0 | **$0** |
+| Producción pequeña | $0 | $0 | $0 | **$0** |
+| Producción media | $4.99 | $0 | $0 | **$4.99** |
+| Producción alta | $29 | $60 | $10 | **$99** |
+
+## Configuración Completa
+
+```env
+# .env.cloud
+
+# Turso (SQLite)
+TURSO_DATABASE_URL=libsql://cmp-memory-username.turso.io
+TURSO_AUTH_TOKEN=eyJ...
+
+# Upstash Vector
+UPSTASH_VECTOR_REST_URL=https://abc-xyz.upstash.io
+UPSTASH_VECTOR_REST_TOKEN=AXxx...
+
+# Upstash Redis
+UPSTASH_REDIS_REST_URL=https://def-uvw.upstash.io
+UPSTASH_REDIS_REST_TOKEN=AYyy...
+
+# Embeddings (para generar si no usas built-in de Upstash)
+OPENAI_API_KEY=sk-...
+```
+
+## Package Dependencies
+
+```json
+{
+  "dependencies": {
+    "@libsql/client": "^0.5.0",
+    "@upstash/vector": "^1.0.0",
+    "@upstash/redis": "^1.28.0",
+    "drizzle-orm": "^0.30.0"
+  }
+}
+```
+
+## Fallback Strategy
+
+Si un servicio falla, tener fallback:
+
+```typescript
+async function getMemories(query: string) {
+  try {
+    // Primary: Upstash Vector (semantic search)
+    return await vectorIndex.query({ data: query, topK: 10 })
+  } catch (error) {
+    console.error('Vector search failed, falling back to SQL')
+
+    // Fallback: Turso (SQL LIKE search)
+    return await turso.query.devItems.findMany({
+      where: like(devItems.content, `%${query}%`),
+      limit: 10
+    })
+  }
+}
+```