Script · bib_ingest_claude_method.mjs — Indexador de claude-method en el corpus Bibliotecario

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

Variable	Descripción
`BIB_MCP_URL`	URL base del endpoint MCP
`BIB_MCP_TOKEN`	Token Bearer (alternativa a `MCP_TOKEN`)
`MCP_TOKEN`	Token Bearer (fallback)
`CF_ACCESS_CLIENT_ID`	Header `CF-Access-Client-Id` para Cloudflare Access
`CF_ACCESS_CLIENT_SECRET`	Header `CF-Access-Client-Secret`
`BIBLIOTECARIO_PAUSADO`	Si `'true'`, el script aborta con exit 0 (toggle global)

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)`

Path	Categoría generada
`onboarding/shared-memory/*`	`onboarding-shared-memory`
`biblioteca/*`	`biblioteca`
`global-skills/*`	`global-skills`
`global-agents/*`	`global-agents`
`agents/*`	`agents`
raíz (sin directorio)	`root`
otro `<dir>/`	`<dir>` (guides, harness, workflow, templates…)

`deriveDocType(relPath)`

Condición	`doc_type`
`onboarding/shared-memory/`	`memory`
`global-skills/` o `*.../SKILL.md`	`skill`
`global-agents/` o `agents/`	`agent`
`guides/`	`guide`
`workflow/`	`workflow`
`biblioteca/` o `harness/`	`reference`
`templates/`	`template`
`onboarding/`	`guide`
Default	`doc`

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:

Doc total < 800 palabras → [{heading: '', content: body}]
Split por líneas ^## (H2, excluye H3)
Secciones < 100 palabras se acumulan con la siguiente
Secciones > 800 palabras → splitByParagraphs() (sub-chunks por \n\n)
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

Exit	Condición
`0`	Éxito o `BIBLIOTECARIO_PAUSADO=true`
`1`	Error fatal no capturado (`main().catch`)
`2`	Root inexistente o falta `--mcp-url`/`--mcp-token` con `--push`
`3`	Phase A registró 0 docs con `docs_total > 0` (posible auth/schema issue)

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