Script de sincronización (sync-vault)

El script scripts/sync-vault.ts es el puente entre el vault de Obsidian y la wiki. Se ejecuta con Bun y no requiere intervención de IA.

---

Uso

Las tareas están disponibles tanto vía mise (canónico) como vía bun directamente:

# Con mise (recomendado — usa el entorno gestionado)
mise run sync:dry   # previsualizar sin escribir nada
mise run sync       # ejecutar la sincronización

# Con bun directamente (equivalente)
bun run sync:dry
bun run sync

Tareas mise disponibles

Tarea	Descripción
mise run sync	Sync mature notes from the Obsidian vault to the wiki
mise run sync:dry	Preview the sync without writing anything

Definidas en mise.toml:

[tasks.sync]
description = "Sync mature notes from the Obsidian vault to the wiki"
run         = "bun run scripts/sync-vault.ts"

[tasks."sync:dry"]
description = "Preview the sync without writing anything"
run         = "bun run scripts/sync-vault.ts --dry-run"

Variables de entorno

Variable	Default	Descripción
VAULT_ROOT	../wiedii-documentation	Ruta al vault de Obsidian
DOCS_ROOT	./docs	Ruta al directorio docs/ del wiki

---

Fuente de verdad

El vault es siempre la fuente de verdad. Los archivos en docs/ son artefactos derivados — nunca deben editarse directamente. Si alguien lo hace, el script detecta la divergencia y restaura el archivo desde el vault en la siguiente ejecución.

---

Qué hace el script

El script ejecuta cinco fases en cada corrida:

Fase 1 — Detección de cambios vault-side

Lee el manifest (.sync-manifest.json) que guarda un hash del contenido de cada nota en el momento en que fue promovida. Compara ese hash contra el contenido actual del vault.

Si el vault fue editado tras la promoción:

• La nota regresa automáticamente a estado: maduro
• Se elimina del manifest
• La tarjeta vuelve a la columna "Maduro" en el kanban
• El script reporta qué notas requieren re-auditoría

Fase 2 — Construcción del mapa de wikilinks

Escanea todos los archivos existentes en docs/ para construir una tabla de resolución de wikilinks. Esto permite que las referencias nombre-de-nota se conviertan correctamente a rutas relativas de Docusaurus, incluyendo notas promovidas en ejecuciones anteriores.

Fase 2b — Detección de drift wiki-side

Para cada nota promovido cuyo vault no cambió (sobrevivió la Fase 1), el script:

1. Lee el vault y renderiza el contenido que debería tener el archivo en docs/
2. Lo compara contra el archivo real en docs/
3. Si difieren → el archivo de docs/ fue editado directamente → lo restaura desde el vault automáticamente

Esto garantiza que docs/ es siempre un artefacto derivado del vault, sin posibilidad de divergencia silenciosa.

Fase 3 — Migración de notas con estado: maduro

Escanea las carpetas del vault configuradas en FOLDER_MAP buscando notas con estado: maduro. Para cada una:

1. Limpia el frontmatter (elimina campos de Obsidian como estado, autor, creada, destino)
2. Añade sidebar_label con el título para Docusaurus
3. Convierte wikilinks nombre a rutas Markdown relativas
4. Escribe el archivo en docs/<sección>/
5. Actualiza el vault: estado: maduro → estado: promovido
6. Registra el hash en el manifest

Fase 4 — Persistencia

• Guarda el manifest actualizado (.sync-manifest.json)
• Actualiza el kanban: mueve las tarjetas promovidas a la columna "Promovido"

---

El manifest

.sync-manifest.json es un archivo JSON versionado en el repo del wiki. Registra qué notas fueron sincronizadas y el hash de su contenido en el momento de la sincronización.

{
  "version": 1,
  "synced": {
    "04-estandares/SOLID.md": {
      "hash": "1a2b3c4d",
      "wikiPath": "estandares/solid.md"
    }
  }
}

Por qué versionarlo: Si no estuviera en git, cada desarrollador que clonara el repo perdería el historial de qué se sincronizó. El manifest debe acompañar los commits junto con los archivos de docs/ que produjo.

Qué hashea: Solo el title y el cuerpo de la nota. Ignora campos volátiles del frontmatter (estado, modificada, etc.) para que cambios de metadatos internos de Obsidian no disparen una re-auditoría innecesaria.

---

Carpetas del vault que se sincronizan

Carpeta en vault	Sección en wiki
00-wiki/	contribuir/
01-onboarding/	onboarding/
02-herramientas/	herramientas/
03-entorno-local/	entorno-local/
04-estandares/	estandares/
05-politicas-desarrollo/	politicas/

Las carpetas _Inbox, _Plantillas y similares nunca se sincronizan, independientemente del estado de las notas que contengan.

---

Conversión de formato

Frontmatter

Campos que se eliminan antes de escribir en el wiki:

estado · autor · creada · modificada · destino · wiki_slug
skill_name · skill_description · todo_normalizacion

Campos que se añaden automáticamente:

sidebar_label: "Título de la nota"   # tomado del campo `title`

Wikilinks

Los wikilinks de Obsidian se convierten a enlaces Markdown relativos:

Obsidian	Wiki
nombre-nota	[nombre-nota](../seccion/nombre-nota.md)
Texto visible	[Texto visible](../seccion/nombre-nota.md)
nombre-nota	[nombre-nota](../seccion/nombre-nota.md#sección)

Si el wikilink apunta a una nota que no existe en el wiki (todavía en borrador), se convierte a texto plano.

---

Integración con Lefthook

El hook pre-push corre automáticamente sync:dry antes de cada push. Muestra si hay notas pendientes de promover, pero no bloquea el push — es solo informativo.

# lefthook.yaml (extracto)
pre-push:
  commands:
    sync-vault:
      run: mise exec -- bun run sync:dry

---

Notas que el script no toca nunca

• Archivos que empiezan con _ (_Index.md, _Plantillas, etc.)
• Notas con estado: borrador o sin campo estado
• Notas fuera de las carpetas configuradas en FOLDER_MAP
• El propio kanban (kanban-estados-vault.md)