Script · bib_ingest_claude_method.mjs

Ruta: scripts/bib_ingest_claude_method.mjs
Runtime: Node.js 20 (ESM)
Propósito: Indexar los 49 documentos .md del repositorio privado CreaRackSL/claude-method en el corpus del Bibliotecario (grafo bib_* en D1), habilitando al Oráculo de EL para responder sobre el método del equipo.

Responsabilidad

Cierra el gap de conocimiento identificado en la sesión 73: el Oráculo podía consultar el workspace pero no el método (harness, biblioteca de prompts, agentes globales, footguns, workflow, onboarding). Este script registra esos 49 docs y sus chunks vectorizados.

Pipeline de dos fases

Phase A: bib_register_doc (secuencial, 1 por doc)
  → Obtiene node_id por doc
  → Map: relPath → node_id

Phase B: bib_index_chunks (batch de 200)
  → Construye chunks con node_id asignado
  → Llamadas en lote hasta agotar allChunks[]

La separación en dos fases existe porque bib_index_docs (batch) no retorna node_id individuales — necesarios para que bib_index_chunks asocie correctamente cada chunk a su doc en el grafo.

Interfaz CLI

--root <path>       Directorio raíz del repo claude-method (default: ../../claude-method)
--push              Modo push real al MCP. Sin él, solo dry-run/output.
--mcp-url <url>     URL del endpoint MCP (o env BIB_MCP_URL)
--mcp-token <tok>   Bearer token MCP (o env BIB_MCP_TOKEN / MCP_TOKEN)
--output <file>     Escribe payload debug JSON en <file> (sin push)
--stats             Imprime estadísticas por categoría y doc_type en stderr

Variables de entorno

Lógica de descubrimiento de archivos

walkDir() recursivo excluye: node_modules, .git, dist, build, .cache.
Solo procesa archivos .md — los .ts del repo se ignoran (ya indexados por bib_ast_ts).

Frontmatter parser

Parser manual sin dependencias externas. Compatible con el frontmatter YAML mínimo de claude-method:

• --- opening + \n--- closing
• Extrae pares key: value (des-quotea " y ')
• Sin frontmatter → meta: {}, todo el raw es body

Derivación de metadatos

deriveCategory(relPath)

deriveDocType(relPath)

Chunker — buildChunks(body)

Parámetros:

• CHUNK_MIN_WORDS = 100 — umbral mínimo para emitir chunk independiente
• CHUNK_SOFT_MAX_WORDS = 800 — límite blando para sub-splittear

Algoritmo:

1. Doc total < 800 palabras → [{heading: '', content: body}]
2. Split por líneas ^## (H2, excluye H3)
3. Secciones < 100 palabras se acumulan con la siguiente
4. Secciones > 800 palabras → splitByParagraphs() (sub-chunks por \n\n)
5. Sin H2 → chunk único

Output: Array<{heading: string, content: string}>

Los chunks finales para MCP llevan estructura:

{
  "node_id": "<id>",
  "title": "<doc_title> · <heading>",
  "content": "<text>",
  "source_path": "claude-method/<relPath>",
  "source_type": "doc",
  "app": "claude-method",
  "metadata": {
    "section": "<heading|null>",
    "doc_path": "claude-method/<relPath>",
    "category": "<category>",
    "doc_type": "<docType>"
  }
}

Namespace D1

Todos los file_path usan prefijo claude-method/ para evitar colisiones con docs del workspace que comparten nombres (ej: guides/QUICK_START.md).

Códigos de salida

Invocado por

• CI: .github/workflows/bib-reindex-claude-method.yml (cron 00:30 UTC, workflow_dispatch)
• Local: desarrollo/debug directo con node scripts/bib_ingest_claude_method.mjs

Véase también

• [[feature—oraculo—fase2-claude-method]]
• [[entity—ci—workflow—bib-ingest-claude-method]]