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:

Campo	Descripción
`file_path`	Ruta relativa al repo
`title`	Primera línea `# Título` del archivo
`doc_type`	Clasificado por heurísticas de path (`rules`, `readme`, `changelog`, `release_notes`, `task`, `agent`, `context`, `prompt`, `documentation`, `script`, `other`)
`category`	Sub-categoría dentro del tipo
`content_hash`	SHA-256 del contenido
`sections`	Títulos `##` y `###` encontrados
`mentions_apps`	Apps Django mencionadas (`core`, `racks`, `monitoring`, `network`, `signage`, `terminal`, `blueprints`)
`word_count`	Número de palabras

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:

git pull --rebase para asegurar scripts actualizados (no fatal si falla)
Ejecuta bib_openapi.py --push (autodetectando container)
Ejecuta bib_docs.py --push independientemente del resultado de openapi (errores no bloquean)
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

Tipo de nodo	Antes	Después
AST (module, class, fn, method)	Refrescado cada 10 min ✅	Sin cambios
`endpoint` (≈496 nodos)	Stale días/semanas ❌	Refrescado cada hora ✅
`schema` (≈416 nodos)	Stale días/semanas ❌	Refrescado cada hora ✅
`doc` (≈168 nodos)	Stale días/semanas ❌	Refrescado cada hora ✅
`js_module` (≈145 nodos)	Stale días/semanas ❌	Fuera de scope (pendiente)

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

Archivo	Estado	Líneas
`scripts/bib_openapi.py`	NUEVO	+191
`scripts/bib_docs.py`	NUEVO	+269
`scripts/cron-bib-reindex.sh`	MODIFICADO	+54

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]]