Re-indexar la Biblioteca manualmente

When to use (pre-condiciones)

Ejecutar este runbook cuando el cron /etc/cron.d/bib-reindex de Staging falle o no se haya ejecutado. Síntomas típicos:

• Log cron-bib-reindex.log con [ERROR] (exit=-1073741510 o exit=1 para alguna app).
• MCP devuelve 503: error code: 1102 durante push de alguna app (conocido para blueprints, ver Known issues).
• compute_communities no ejecutó porque total_failed > 0.
• Índice de Biblioteca desactualizado en workspace tras deploy o cambio de código.

Prerequisites

• SSH al servidor Hetzner Staging como root.
• /opt/bib-reindex/.token con permisos 600 y BIB_MCP_TOKEN válido.
• /opt/crearack-pro clonado con deploy key en /root/.ssh/github_crearack.
• python3 (3.12+) y git en PATH.
• Script scripts/bib_ast.py presente en el repo.

Steps

1. Conectar a Staging y posicionarse en el repo:

   ssh root@<staging-host>
   cd /opt/crearack-pro

2. Revisar el log para identificar apps fallidas:

   tail -50 /opt/bib-reindex/cron-bib-reindex.log

   Buscar [ERROR] y [STDERR] posteriores. MCP error 503 sugiere sobrecarga transitoria; reintento suele bastar.

3. Cargar token en sesión:

   export BIB_MCP_TOKEN="$(tr -d '\r\n' < /opt/bib-reindex/.token)"

   Verificar: echo ${#BIB_MCP_TOKEN} debe dar >0.

4. Actualizar código (si no hay cambios locales no commiteados):

   export GIT_SSH_COMMAND="ssh -i /root/.ssh/github_crearack -o StrictHostKeyChecking=no"
   git pull --rebase origin main

   Si hay cambios locales: git status para decidir.

5. Re-indexar todas las apps:

   for app in core racks blueprints terminal network monitoring signage; do
     echo "=== $app ==="
     python3 scripts/bib_ast.py --push --apps "$app"
     echo "Exit: $?"
   done

   Si solo una falló: python3 scripts/bib_ast.py --push --apps blueprints.

6. Lanzar compute_communities si todas las apps terminaron con exit 0:

   curl -sS -X POST \
     -H "Authorization: Bearer $BIB_MCP_TOKEN" \
     -H "Content-Type: application/json" \
     --max-time 60 \
     -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"bib_compute_communities","arguments":{"max_iterations":50,"min_community_size":3}},"id":1}' \
     https://workspace.crearack.com/api/mcp

   Respuesta HTTP 200 = éxito.

Verification

• Log confirma [OK] para todas las apps con conteos coherentes (referencia: terminal ~596, monitoring ~545, core ~292).
• Script imprime Nodes: N y Edges: N por stderr; si ambos 0 con exit 0, el MCP aceptó payload pero no insertó nada (script sale con código 3 — investigar).
• Opcionalmente consultar MCP con bib_stats o bib_list_runs para confirmar frescura.

Rollback (N/A — reindex es idempotente)

Re-indexación completamente idempotente: bib_ast.py --push --apps <app> usa replace_app para apps individuales, eliminando nodos obsoletos y reinsertando grafo completo de esa app. Sin riesgo de corrupción por ejecuciones repetidas.

Known issues

• MCP error 503 / 1102 (blueprints, 2026-04-17): fallo transitorio del Worker MCP. Reintentando 18 min después, indexó correctamente.
• exit=-1073741510 (terminal, 2026-04-21 09:37): código de terminación forzada (OOM killer, timeout cron, SIGTERM). Si se reproduce, comprobar memoria disponible y ajustar límites.
• Cambios locales sin commitear: cron avisa con [WARN] y omite git pull, indexando código del disco. Intencional pero puede causar discrepancias si hay WIP en Staging.

Véase también

• [[concept—biblioteca—supercontexto]]
• [[incident—20260421—task-scheduler-spof]]