doc-auditoria — MarkUP
Fecha de auditoría: 2026-06-16
Auditor: Análisis forense automatizado
Propósito: Evaluar el estado actual del sistema, identificar problemas, contradicciones, dependencias innecesarias y priorizar mejoras.
1. Contradicciones documentación vs realidad
La documentación antigua (ARCHITECTURE.md, README.md, CONTRIBUTING.md, ROADMAP.md) contenía información que ya no coincidía con la realidad del proyecto. A continuación se enumeran las contradicciones encontradas:
| # | Lo que decía la documentación antigua | Lo que realmente hay | Estado |
|---|
| 1 | El proyecto se llama multiblog-obsidian | El directorio raíz es markeup/. El package.json aún tiene "name": "multiblog-obsidian" | ⚠️ Contradicción |
| 2 | scripts/sync-obsidian.js es el watcher activo | Ese script usa chokidar y tiene la ruta hardcodeada /ruta/a/tu/vault. No se usa. El watcher real es watchexec + auto-commit.sh gestionado por launchd | ⚠️ Obsoleto |
| 3 | deploy.yml usa working-directory: multiblog-obsidian | El repo se llama markeup en local. En GitHub Actions el directorio puede crearse como markeup o multiblog-obsidian según cómo clonó GitHub | ⚠️ Posible error de build |
| 4 | ”8 archivos de documentación” | Se reestructuró a 4 y ahora 5 archivos nuevos (Junio 2026) | 🔄 Actualizado |
| 5 | ARCHITECTURE.md decía “3,058+ LOC” | El análisis real da ~3,500 LOC (nuevos componentes, grafo 3D, más CSS) | 🔄 Actualizado |
| 6 | .gitignore no incluía Syncthing ni Obsidian | Se añadieron manualmente: .stfolder/, .stignore, .stversions/, .sync-conflict*, .obsidian/ | ✅ Corregido |
| 7 | watch-native.log y watch-native-error.log no estaban en .gitignore | Se añadió watch-native*.log al .gitignore | ✅ Corregido |
¿Por qué ocurrieron estas contradicciones?
La documentación antigua no se actualizaba al mismo ritmo que el código. Cuando se migró de multiblog-obsidian a markeup, se actualizaron los archivos del proyecto pero no los documentos. Esta nueva documentación resuelve ese problema.
2. Dependencias del sistema (comprobadas)
2.1 Versiones reales instaladas en el Mac
| Dependencia | Versión real | Instalada vía |
|---|
| Node.js | 22.22.3 | Homebrew o nvm |
| npm | 10.9.8 | incluido con Node.js |
| watchexec | 2.5.1 | Homebrew (/opt/homebrew/bin/watchexec) |
| launchd | incluido en macOS | Servicio nativo (gestiona watchexec) |
| Syncthing (Mac) | [PENDIENTE: verificar versión] | App gráfica |
| Syncthing (Android) | [PENDIENTE: verificar versión] | F-Droid / Play Store |
| Git | incluido en macOS | Xcode CLI tools |
2.2 Dependencias npm (package.json real)
Producción (16 paquetes activos):
| Paquete | Versión | ¿Se usa? | Notas |
|---|
astro | ^4.0.0 | ✅ Sí | Framework principal |
@astrojs/rss | ^4.0.0 | ✅ Sí | Generación de RSS feed |
@astrojs/sitemap | ^3.0.0 | ✅ Sí | Generación de sitemap.xml |
@astrojs/tailwind | ^5.0.0 | ✅ Sí | Integración TailwindCSS |
@tailwindcss/typography | ^0.5.20 | ✅ Sí | Estilos tipográficos |
daisyui | ^4.0.0 | ✅ Sí | 6 temas de UI |
3d-force-graph | ^1.80.0 | ✅ Sí | Grafo 3D interactivo |
three | ^0.184.0 | ✅ Sí | Motor 3D (requerido por 3d-force-graph) |
three-spritetext | ^1.10.0 | ✅ Sí | Texto en sprites 3D |
pagefind | ^1.5.2 | ✅ Sí | Búsqueda full-text offline |
@pagefind/default-ui | ^1.5.2 | ✅ Sí | UI de búsqueda Pagefind |
sharp | ^0.33.5 | ✅ Sí | Optimización de imágenes |
gray-matter | ^4.0.3 | ✅ Sí | Parseo de frontmatter |
unist-util-visit | ^5.1.0 | ✅ Sí | Procesamiento de AST para wikilinks |
zod | ^4.4.3 | ✅ Sí | Validación de frontmatter |
Dependencias huérfanas o innecesarias:
| Paquete | Versión | Problema | Acción recomendada |
|---|
d3 | ^7.9.0 | ❌ No se usa. Reemplazado por 3d-force-graph (que usa Three.js) | npm uninstall d3 |
@types/d3 | ^7.4.3 | ❌ No se usa (tipos de d3) | npm uninstall @types/d3 |
gsap | ^3.15.0 | ⚠️ Probablemente no se usa. Solo aparece en package.json. No hay imports en src/ | Verificar si animated-sections.astro lo usa. Si no, npm uninstall gsap |
@types/three | ^0.184.1 | ⚠️ Redundante. Three.js incluye sus propios tipos desde v0.173+ | npm uninstall @types/three |
chokidar | ^3.5.3 | ⚠️ Solo usado por scripts/sync-obsidian.js (obsoleto) | Esperar a eliminar el script |
Total de dependencias que se podrían eliminar: 4-5 paquetes.
3. Archivos huérfanos o sospechosos
| Archivo | Problema | Acción recomendada |
|---|
nohup.out | Log del antiguo comando nohup (ya no se usa, watchexec ahora es gestionado por launchd) | Eliminar (rm nohup.out) |
watch-native.log | Log de watchexec (vacío, no contiene nada útil) | Eliminar |
watch-native-error.log | Log de error de watcher antiguo (contiene un error de sintaxis bash) | Eliminar |
public/.DS_Store | Archivo de metadatos de macOS (ya está en .gitignore) | Eliminar (rm public/.DS_Store) |
src/content/posts/img/ | Directorio con 41 imágenes que son duplicadas de las que están en public/img/ | Verificar si hay posts que referencian imágenes aquí directamente |
src/content/posts/documentacion/ | Los 5 archivos .md se procesan como posts normales en el build. Aparecen en el listado de posts y en la búsqueda | Considerar excluir de la colección o marcar como draft |
scripts/sync-obsidian.js | Script obsoleto que usa chokidar y tiene una ruta hardcodeada (/ruta/a/tu/vault) | Eliminar o actualizar |
src/content/posts/Prueba.md | Post de prueba (slug: slug, draft: true) | Eliminar si ya no se necesita |
src/content/posts/Caca.md | ⚠️ CRÍTICO: Post de prueba con draft: false. Se publicó accidentalmente en el sitio en producción | Eliminar inmediatamente |
4. Vulnerabilidades y puntos débiles
| # | Vulnerabilidad | Impacto | Solución |
|---|
| 1 | watchexec no persiste tras reinicio | Si el Mac se reinicia, la automatización se detiene | ✅ RESUELTO con launchd. Ver doc-guia sección 3.3 |
| 2 | Syncthing app en Mac debe estar abierta | Si la app de Syncthing no está corriendo, no hay sincronización. Al reiniciar, Syncthing no arranca automáticamente | Configurar Syncthing como item de login (Preferencias del Sistema → General → Items de inicio) |
| 3 | Sin sistema de alertas | Si el build falla (ZodError, red, etc.), nadie se entera hasta que alguien revisa manualmente | Configurar notificaciones de GitHub Actions (email o Slack) |
| 4 | Secrets hardcodeados en admin | ADMIN_PASSWORD = admin123, JWT_SECRET = change-me-in-production. Cualquiera que despliegue el sitio puede acceder al panel admin | Configurar como secrets en GitHub → Settings → Secrets and variables → Actions |
| 5 | Sin backups automáticos | Si el repositorio de GitHub se corrompe o elimina, se pierde todo el contenido del blog | Configurar backup automático semanal (cron + rsync a disco externo o a otro repositorio) |
| 6 | Imágenes grandes no optimizadas | Algunas imágenes pueden ser >500KB, lo que ralentiza la carga del sitio | Ejecutar npm run optimize-images periódicamente |
| 7 | Dependencia de red para publicación | Sin conexión a internet, los cambios se guardan localmente pero no se publican | No mitigable (es inherente al diseño “cloud”). Los cambios persisten hasta que haya red |
| 8 | La documentación de documentacion/ se publica como posts | Los 5 archivos aparecen en el listado de posts (/posts), en las cards y en la búsqueda | Añadir filtro en content.config.ts para excluir la carpeta, o marcar como draft: true |
Estado de vulnerabilidades resueltas
- watchexec sin persistencia → ✅ Resuelto. Se creó el servicio launchd
com.user.watchexec que arranca automáticamente al iniciar sesión y se reinicia si falla.
5. Pasos próximos (recomendados)
Corto plazo (1-2 semanas)
Medio plazo (1-3 meses)
6. Fortalezas
| # | Fortaleza | Explicación |
|---|
| 1 | Sincronización rápida | Syncthing transfiere archivos en 1-5 segundos en la misma red local. Mucho más rápido que cualquier servicio en la nube |
| 2 | Automatización sólida | watchexec + launchd + auto-commit.sh = commit automático en <2s desde que Syncthing escribe el archivo. Y persiste tras reinicios |
| 3 | Flujo completamente sin intervención | Desde que guardas en Android hasta que se publica en Cloudflare, no necesitas tocar nada. Cero intervención manual |
| 4 | Build rápido | Astro genera ~150 páginas en ~3 segundos en local y ~30-60s en GitHub Actions |
| 5 | Sin costes de infraestructura | GitHub Actions (gratis, 2000 min/mes) + Cloudflare Pages (free tier, 500 builds/mes) + Syncthing (open source) = coste mensual: 0 € |
| 6 | Stack moderno y mantenible | Astro 4, TypeScript strict, TailwindCSS, DaisyUI, Zod, Vitest, 3d-force-graph |
| 7 | Búsqueda offline | Pagefind indexa todo el contenido para búsqueda full-text sin servidor (no hay que pagar por Algoia ni Elasticsearch) |
| 8 | Grafo 3D interactivo | Visualización de relaciones entre posts con 3d-force-graph (Three.js). Relaciones basadas en wikilinks |
| 9 | 6 temas DaisyUI | Light, cupcake, corporate, dark, dim, sunset — con persistencia en localStorage. El usuario elige su tema favorito |
| 10 | Tests automatizados | Vitest con 6/6 tests pasando (getAllPosts, getPostsByCategory, getAllCategories, paginate ×3) |
| 11 | Glassmorphism unificado (Junio 2026) | Todos los botones de home, categorías, posts y grafo usan el mismo patrón: fondo transparente, blur 24-48px, bordes sutiles y transiciones suaves |
7. Debilidades
| # | Debilidad | Impacto | Mejora posible |
|---|
| 1 | watchexec no persistía tras reinicio | Había que iniciarlo manualmente | ✅ Resuelto con launchd |
| 2 | Syncthing no arranca automáticamente al iniciar sesión | Si el Mac se reinicia, hay que abrir Syncthing manualmente | Configurar como item de inicio de sesión |
| 3 | Sin alertas de fallo | Si el build falla, nadie lo sabe hasta que alguien revisa | Notificaciones de GitHub Actions |
| 4 | Secrets hardcodeados | Admin vulnerable (pass: admin123) hasta que se configuren secrets en GitHub | Configurar secrets ahora |
| 5 | Script sync-obsidian.js obsoleto | Código muerto que ocupa espacio y puede confundir a quien lea el proyecto | Eliminar o reescribir apuntando a watchexec |
8. Resumen de estado
| Dimensión | Estado | Notas |
|---|
| Build | ✅ 0 errores, ~150 páginas, ~3s | Build completo verificado (astro build + pagefind) |
| Tests | ✅ 6/6 passing | Unit tests de posts.ts (Vitest) |
| Sincronización Android→Mac | ✅ Funcional | Syncthing + watchexec + launchd verificados |
| Auto-commit | ✅ Funcional | launchd gestiona watchexec, que ejecuta auto-commit.sh |
| Persistencia tras reinicio | ✅ Resuelto | launchd (com.user.watchexec) arranca automáticamente al iniciar sesión |
| Deploy a Cloudflare | ⚠️ No verificado | Depende de GitHub Actions con secrets configurados |
| CI/CD | ⚠️ Parcial | Workflows existen pero no se ha probado deploy real |
| Admin login | ⚠️ Vulnerable | Secrets por defecto (admin123) |
| Documentación | ✅ Actualizada | 5 archivos nuevos (Junio 2026), títulos coinciden con slugs |
| Gitignore | ✅ Completo | Syncthing, Obsidian, logs ignorados |
| Dependencias | ⚠️ 4 huérfanas | d3, @types/d3, gsap (verificar), @types/three |
| UI/Glassmorphism | ✅ Unificado (Junio 2026) | Todos los botones de home, categorías y CTA con transparencia, blur 48px y bordes sutiles |
9. Notas técnicas adicionales
El build actual produce ~150 páginas
Resultado de npm run build:
# build:astro → genera dist/ con HTML estático (~150 páginas)
# build:search → pagefind indexa dist/ para búsqueda full-text
# Tiempo total: ~3 segundos en local
# Sin errores
Los tests actuales
npm test → vitest run
# 6 tests en src/lib/posts.test.ts
# getAllPosts: 1 test
# getPostsByCategory: 1 test
# getAllCategories: 1 test
# paginate: 3 tests (página 1, página 2, página vacía)
El sitio en producción
URL: https://mybrain-limpio.pages.dev
Hosting: Cloudflare Pages (CDN global)
Build: GitHub Actions (trigger en push a main)
10. Checklist de verificación post-auditoría
Documentación (completado)
Pendientes (no resueltos en esta auditoría)
