aiworker/NEXT-SESSION.md

# 📋 Próxima Sesión - Checklist Ejecutable

**Objetivo**: Completar Backend API y MCP Server básico
**Tiempo estimado**: 2-3 horas

---

## ✅ PRE-REQUISITOS (Verificar antes de empezar)

```bash
# 1. Cluster funcionando
export KUBECONFIG=~/.kube/aiworker-config
kubectl get nodes
# Debe mostrar 6 nodos Ready

# 2. Servicios corriendo
kubectl get pods -n control-plane
# mariadb-0: Running
# redis-xxx: Running

kubectl get pods -n gitea
# gitea-0: Running

# 3. Backend local
cd backend
bun --version
# 1.3.6

# 4. Gitea accesible
curl -I https://git.fuq.tv
# HTTP/2 200
```

**Si algo falla, consulta**: `CLUSTER-READY.md` y `TROUBLESHOOTING.md`

---

## 🎯 PASO 1: Verificar CI/CD (15 min)

### 1.1 Revisar último build
```bash
# Ver en Gitea Actions
open https://git.fuq.tv/admin/aiworker-backend/actions
```

**Opciones**:
- ✅ **Si build exitoso**: Continuar a paso 2
- ❌ **Si build fallido**: Ver logs, corregir, push de nuevo

### 1.2 Verificar imagen en registry
```bash
# Vía UI
open https://git.fuq.tv/admin/-/packages

# Vía API
curl https://git.fuq.tv/api/v1/packages/admin/container?type=container
```

**Debe existir**: `aiworker-backend` con tag `latest`

### 1.3 Si no hay imagen, build manual
```bash
# Desde un nodo del cluster (si Docker local no funciona)
ssh root@108.165.47.225  # worker-01

cd /tmp
git clone https://git.fuq.tv/admin/aiworker-backend.git
cd aiworker-backend

docker build -t git.fuq.tv/admin/aiworker-backend:latest .
docker login git.fuq.tv -u admin -p 7401126cfb56ab2aebba17755bdc968c20768c27
docker push git.fuq.tv/admin/aiworker-backend:latest
```

---

## 🎯 PASO 2: Implementar API Routes (45 min)

### 2.1 Crear estructura de routes
```bash
cd backend/src/api
mkdir routes

# Archivos a crear:
# - routes/projects.ts
# - routes/tasks.ts
# - routes/agents.ts
# - routes/index.ts
```

### 2.2 Implementar Projects API

**Archivo**: `src/api/routes/projects.ts`

**Endpoints necesarios**:
```typescript
GET    /api/projects          // List all
GET    /api/projects/:id      // Get one
POST   /api/projects          // Create
PATCH  /api/projects/:id      // Update
DELETE /api/projects/:id      // Delete
```

**Referencia**: `docs/02-backend/api-endpoints.md` (líneas 15-80)

**Conectar con Bun.serve()**:
```typescript
// En src/index.ts
import { handleProjectRoutes } from './api/routes/projects'

if (url.pathname.startsWith('/api/projects')) {
  return handleProjectRoutes(req, url)
}
```

### 2.3 Implementar Tasks API

**Archivo**: `src/api/routes/tasks.ts`

**Endpoints principales**:
```typescript
GET    /api/tasks             // List with filters
GET    /api/tasks/:id         // Get details
POST   /api/tasks             // Create
PATCH  /api/tasks/:id         // Update
POST   /api/tasks/:id/respond // Respond to question
```

### 2.4 Probar APIs localmente
```bash
# Terminal 1: Port-forward MariaDB
kubectl port-forward -n control-plane svc/mariadb 3306:3306 &

# Terminal 2: Port-forward Redis
kubectl port-forward -n control-plane svc/redis 6379:6379 &

# Terminal 3: Run backend
cd backend
bun run dev

# Terminal 4: Test
curl http://localhost:3000/api/health
curl http://localhost:3000/api/projects
```

---

## 🎯 PASO 3: MCP Server Básico (60 min)

### 3.1 Crear estructura MCP
```bash
mkdir -p src/services/mcp
# Archivos:
# - services/mcp/server.ts
# - services/mcp/tools.ts
# - services/mcp/handlers.ts
```

### 3.2 Implementar herramientas básicas

**Herramientas mínimas para MVP**:
1. `get_next_task` - Obtener siguiente tarea
2. `update_task_status` - Actualizar estado
3. `create_branch` - Crear rama en Gitea
4. `create_pull_request` - Crear PR

**Referencia**: `docs/05-agents/mcp-tools.md`

**Template básico**:
```typescript
// src/services/mcp/server.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js'

export class MCPServer {
  private server: Server

  constructor() {
    this.server = new Server({
      name: 'aiworker-mcp',
      version: '1.0.0'
    }, {
      capabilities: { tools: {} }
    })

    this.setupHandlers()
  }

  // Implementar handlers...
}
```

### 3.3 Conectar MCP con Bun.serve()

**Opciones**:
- **A**: Puerto separado (3100) para MCP
- **B**: Ruta `/mcp` en mismo server

**Recomendación**: Opción A (puerto 3100)

---

## 🎯 PASO 4: Integración con Gitea (30 min)

### 4.1 Cliente API de Gitea

**Archivo**: `src/services/gitea/client.ts`

**Operaciones necesarias**:
```typescript
- createRepo(name, description)
- createBranch(owner, repo, branch, from)
- createPullRequest(owner, repo, {title, body, head, base})
- mergePullRequest(owner, repo, number)
```

**Usar**:
- Axios para HTTP requests
- Base URL: `https://git.fuq.tv/api/v1`
- Token: Variable de entorno `GITEA_TOKEN`

**Referencia**: `docs/02-backend/gitea-integration.md` (líneas 10-200)

### 4.2 Test de integración
```bash
# Crear un repo de prueba vía API
bun run src/test-gitea.ts
```

---

## 🎯 PASO 5: Deploy Backend en K8s (30 min)

### 5.1 Crear manifests

**Directorio**: `k8s/backend/`

**Archivos necesarios**:
```yaml
# deployment.yaml
# service.yaml
# ingress.yaml
# secrets.yaml
```

**Template deployment**:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend
  namespace: control-plane
spec:
  replicas: 2
  selector:
    matchLabels:
      app: backend
  template:
    spec:
      imagePullSecrets:
      - name: gitea-registry
      containers:
      - name: backend
        image: git.fuq.tv/admin/aiworker-backend:latest
        ports:
        - containerPort: 3000
        - containerPort: 3100  # MCP
        env:
        - name: DB_HOST
          value: mariadb.control-plane.svc.cluster.local
        # ... más env vars
```

### 5.2 Crear secrets
```bash
kubectl create secret generic backend-secrets -n control-plane \
  --from-literal=jwt-secret=your-secret \
  --from-literal=anthropic-api-key=your-key
```

### 5.3 Deploy
```bash
kubectl apply -f k8s/backend/
kubectl get pods -n control-plane
kubectl logs -f deployment/backend -n control-plane
```

### 5.4 Crear Ingress
```yaml
# Para api.fuq.tv
host: api.fuq.tv
backend: backend:3000
```

### 5.5 Verificar
```bash
curl https://api.fuq.tv/api/health
```

---

## 🎯 PASO 6: Test End-to-End (15 min)

### 6.1 Crear proyecto vía API
```bash
curl -X POST https://api.fuq.tv/api/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test-project",
    "description": "First project"
  }'
```

### 6.2 Crear tarea
```bash
curl -X POST https://api.fuq.tv/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "xxx",
    "title": "Test task",
    "description": "First automated task"
  }'
```

### 6.3 Verificar en DB
```bash
kubectl exec -n control-plane mariadb-0 -- \
  mariadb -uaiworker -pAiWorker2026_UserPass! aiworker \
  -e "SELECT * FROM projects; SELECT * FROM tasks;"
```

---

## 📝 NOTAS IMPORTANTES

### Desarrollo Local vs K8s

**Local (desarrollo)**:
- Port-forward para MariaDB y Redis
- `bun run dev` con hot-reload
- Cambios rápidos

**K8s (testing/producción)**:
- Build → Push → Deploy
- Migrations automáticas en startup
- Logs con kubectl

### Migrations

**SIEMPRE** automáticas en el código:
```typescript
// src/index.ts
await runMigrations()  // Al inicio
```

**NUNCA** manuales con port-forward

### Secrets

**Desarrollo**: `.env` (git-ignored)
**Producción**: Kubernetes Secrets

```bash
kubectl create secret generic app-secrets -n namespace \
  --from-env-file=.env.production
```

---

## 🐛 TROUBLESHOOTING

### Si backend no arranca
```bash
# Ver logs
kubectl logs -n control-plane deployment/backend

# Verificar DB connection
kubectl exec -n control-plane mariadb-0 -- \
  mariadb -uaiworker -pAiWorker2026_UserPass! -e "SELECT 1"

# Verificar Redis
kubectl exec -n control-plane deployment/redis -- redis-cli ping
```

### Si Actions no funciona
```bash
# Ver runner
kubectl get pods -n gitea-actions
kubectl logs -n gitea-actions deployment/gitea-runner -c runner

# Restart runner
kubectl rollout restart deployment/gitea-runner -n gitea-actions
```

### Si Ingress no resuelve
```bash
# Verificar DNS
dig api.fuq.tv +short
# Debe mostrar: 108.165.47.221 y 108.165.47.203

# Verificar certificado
kubectl get certificate -n control-plane

# Logs de Ingress
kubectl logs -n ingress-nginx deployment/ingress-nginx-controller --tail=50
```

---

## ✅ CHECKLIST DE SESIÓN

Al final de cada sesión, verificar:

- [ ] Código commitado y pusheado a Gitea
- [ ] Build de CI/CD exitoso
- [ ] Pods corriendo en K8s
- [ ] Endpoints accesibles vía HTTPS
- [ ] Documentación actualizada
- [ ] Credenciales documentadas en lugar seguro
- [ ] Tests básicos pasando

---

## 🎉 META

**Completado**: Infraestructura HA + Backend base
**Próximo hito**: Backend API funcional + MCP Server
**Hito final**: Sistema completo de agentes autónomos

**¡Excelente progreso! Sigue el roadmap y lo tendrás listo pronto! 🚀**