Biblioteca: Reindexación de extras — scripts bib_openapi + bib_docs y modo --extras-only en cron (s50)

Contexto y motivación

El panel de workspace mostraba el aviso persistente:

“Biblioteca: Cobertura baja — 2517 stale de 3958 nodos”

Causa raíz: el cron de reindexación (cron-bib-reindex.sh) solo procesaba nodos de tipo AST (módulos, clases, funciones, métodos) cada 10 minutos. Los nodos de tipo endpoint (≈496), schema (≈416), doc (≈168) y js_module (≈145) —aproximadamente 1.225 nodos— quedaban stale durante días o semanas al no ser tocados por ningún proceso automatizado.

Este commit (s50, 2026-05-05) resuelve el problema añadiendo dos scripts nuevos y un tercer modo al cron.

Nuevos scripts

scripts/bib_openapi.py

Extrae el spec OpenAPI de CreaRack Pro directamente desde el container Django web via docker exec, llamando al método interno api.get_openapi_schema() (Django Ninja no expone /api/openapi.json en este proyecto).

Capacidades:

• Autodetecta el container web activo (docker ps --filter "name=web-1"):
  • PROD: crearack-pro-zcmvsl-web-1
  • STAGE: crearackpro-crearackpro-oyvenu-web-1
• Postea el schema completo al handler MCP bib_index_openapi
• Estado actual: 413 paths · 500 operations · 199 schemas
• Flags: --push (postea al MCP), --output <file> (solo extrae), --stats (resumen numérico), --container <nombre> (override del container)

Patrón de autenticación: idéntico a bib_ast.py — env var BIB_MCP_TOKEN + URL MCP + unwrap defensivo de errores (Regla 15: HTTP 200 ≠ éxito).

scripts/bib_docs.py

Escanea todos los archivos *.md del repositorio (excluyendo node_modules, .git, dist, build, __pycache__, .venv, staticfiles, etc.) y postea los metadatos al handler MCP bib_index_docs.

Metadatos extraídos por documento:

Estado actual: 37 docs detectados en CreaRack-Pro.

Modificación: scripts/cron-bib-reindex.sh

Se añade un tercer modo de ejecución al script cron existente:

Modos disponibles:
  (sin flags)         → AST: reindexación de módulos, clases, funciones (cada 10 min)
  --communities-only  → Recalcula comunidades del grafo (diario, cron separado)
  --extras-only       → bib_openapi + bib_docs en cascada (objetivo: 1x/hora)

Comportamiento de --extras-only:

1. git pull --rebase para asegurar scripts actualizados (no fatal si falla)
2. Ejecuta bib_openapi.py --push (autodetectando container)
3. Ejecuta bib_docs.py --push independientemente del resultado de openapi (errores no bloquean)
4. Logs separados por fase con timestamps

Pendiente (paso siguiente): añadir entrada en /etc/cron.d/bib-reindex de STAGE con "30 * * * *" tras validación manual con --extras-only.

Impacto esperado

La cobertura de nodos frescos debería subir desde ~36% hacia >90% una vez activado el cron en STAGE y PROD.

Regla 15 (patrón defensivo)

Ambos scripts implementan el patrón “HTTP 200 ≠ éxito”:

# Unwrap del inner JSON de respuesta MCP
content_block = result.get("result", {}).get("content", [])
inner = json.loads(content_block[0].get("text", "{}"))
errors = inner.get("errors") or []
if errors:
    sys.exit(2)

Si el handler MCP acepta el payload pero no toca ningún nodo (created=0, updated=0), el script sale con código 3 (error, no silencioso).

Archivos tocados

Véase también

• [[runbook—biblioteca—bib-reindex]]
• [[concept—biblioteca—knowledge-graph]]
• [[feature—biblioteca—bib-ast-indexing]]
• [[decision—20260505—bib-extras-only-cron]]
• [[runbook—infra—rotate-mcp-token]]