Delfosti Docs Pipeline

Extensión de VS Code que automatiza la generación de changelog y documentación técnica en cada git push, usando Claude AI como motor de análisis.

Funciona en cualquier proyecto y stack (Node.js, .NET, PHP, Flutter, Python, etc.) porque se apoya en hooks de Git, no en herramientas específicas del lenguaje.

Qué hace

En cada git push, el pipeline ejecuta 3 fases en secuencia:

Fase	Qué genera	Dónde guarda
1 · Bitácora	Documento Markdown con análisis técnico del push (archivos, impacto, riesgos, pruebas sugeridas)	`docs/changelog/YYYY-MM-DD_HHmm_<branch>_<sha>.md`
2 · Living Docs	Actualiza o crea documentación Obsidian de los módulos afectados	`docs/02-Arquitectura/`, `docs/03-Implementación/`
3 · CHANGELOG.md	Actualiza el CHANGELOG.md ejecutivo en formato Keep a Changelog	`CHANGELOG.md` (raíz del proyecto)

Cada fase hace un auto-commit con el contenido generado. Si alguna fase falla, el push continúa normalmente sin bloquear al desarrollador.

Requisitos previos

Requisito	Versión mínima	Cómo instalar
VS Code	1.85.0+	code.visualstudio.com
Node.js	18+	nodejs.org
Git	2.x	git-scm.com
Claude Code CLI	última	`npm install -g @anthropic-ai/claude-code`

Proyectos sin Node.js (.NET, PHP, Flutter, etc.): Node.js solo se necesita para ejecutar los scripts del pipeline. No afecta las dependencias ni el build de tu proyecto. Instálalo como herramienta de desarrollo.

Instalación de la extensión

Opción A — Desde el `.vsix` (recomendado para uso interno)

# 1. Compilar y empaquetar
cd delfosti-docs-pipeline
npm install
npm run package          # genera delfosti-docs-pipeline-1.0.0.vsix

# 2. Instalar en VS Code
code --install-extension delfosti-docs-pipeline-1.0.0.vsix

O desde VS Code: Cmd+Shift+P → Extensions: Install from VSIX... → seleccionar el .vsix.

Opción B — Modo desarrollo (sin empaquetar)

cd delfosti-docs-pipeline
npm install
npm run compile          # o: npm run watch (modo observación continua)

Luego en VS Code: F5 para abrir una ventana de extensión en modo debug.

Activar en un proyecto

Una vez instalada la extensión, ábrela en VS Code y ejecuta:

Cmd+Shift+P → "Docs Pipeline: Instalar Hook"

La extensión:

Detecta si el proyecto usa Husky (.husky/) o hooks nativos de Git (.git/hooks/)
Escribe el hook en el archivo correcto
El hook queda activo para todos los git push futuros

La barra de estado muestra ✓ Docs cuando el hook está instalado o ○ Docs si no lo está.

Comandos disponibles

Comando	Descripción
`Docs Pipeline: Instalar Hook`	Instala el hook en el proyecto actual
`Docs Pipeline: Desinstalar Hook`	Elimina el hook del proyecto actual
`Docs Pipeline: Actualizar Hook`	Regenera el hook con la versión más reciente de los scripts
`Docs Pipeline: Ver Estado`	Muestra si el hook está instalado y actualizado

Configuración

Las opciones se configuran en Settings (Cmd+,) → buscar "Docs Pipeline".

Setting	Tipo	Default	Descripción
`docsPipeline.changelogEnabled`	boolean	`true`	Activa/desactiva Fase 1 (bitácora)
`docsPipeline.docsUpdateEnabled`	boolean	`true`	Activa/desactiva Fase 2 (Obsidian docs)
`docsPipeline.summaryEnabled`	boolean	`true`	Activa/desactiva Fase 3 (CHANGELOG.md)
`docsPipeline.claudeBin`	string	`""`	Ruta absoluta al binario `claude` (auto-detección si vacío)
`docsPipeline.nodeBin`	string	`""`	Ruta absoluta al binario `node` (auto-detección si vacío)

Configuración por proyecto (`.env.local`)

Puedes sobreescribir la configuración en cada proyecto creando un archivo .env.local en la raíz:

CHANGELOG_ENABLED=true
DOCS_UPDATE_ENABLED=false    # deshabilitar Obsidian docs en este proyecto
SUMMARY_ENABLED=true
CLAUDE_BIN=/ruta/absoluta/al/claude
DOCS_DEBUG=true              # mostrar respuesta raw de Claude en Fase 2
SUMMARY_DEBUG=true           # mostrar respuesta raw de Claude en Fase 3

El .env.local tiene precedencia sobre los settings de VS Code.

Cómo funciona por dentro

git push
  └── pre-push hook (.husky/pre-push o .git/hooks/pre-push)
        └── node <extensión>/scripts/generate-init.mjs <range> <ref>
              ├── [Fase 1] → claude --print (análisis del diff)
              │              → escribe docs/changelog/YYYY-MM-DD_...md
              │              → git commit --no-verify
              ├── [Fase 2] → claude --print (detección de módulos + docs existentes)
              │              → escribe/actualiza docs/...md
              │              → git commit --no-verify
              └── [Fase 3] → claude --print (resumen ejecutivo)
                             → actualiza CHANGELOG.md
                             → git commit --no-verify

Variable clave: el hook establece DOCS_PIPELINE_PROJECT_ROOT apuntando a la raíz del proyecto antes de invocar los scripts. Esto permite que los scripts (que viven dentro de la extensión) sepan dónde escribir los archivos generados.

Notas por stack

Node.js / NestJS

Funciona directamente. Si el proyecto tiene Husky, el pipeline se agrega a .husky/pre-push sin interferir con otras reglas (lint-staged, etc.).

.NET / C#

Node.js debe estar instalado como herramienta de desarrollo. Los scripts no analizan código .NET específicamente — Claude recibe el diff de Git y genera documentación basada en los cambios, independientemente del lenguaje.

PHP / Laravel

Igual que .NET. Si el proyecto usa herramientas como Composer hooks, el pipeline puede coexistir en el mismo archivo pre-push (se agrega como un bloque delimitado).

Flutter / Dart

Si el proyecto está en un mono-repo con pubspec.yaml, Node.js debe instalarse aparte. El pipeline detecta cambios en cualquier archivo del repo.

Python / Django / FastAPI

Sin consideraciones especiales. Funciona igual que en cualquier proyecto Git.

Actualizar la extensión

Cuando se publica una nueva versión:

Instalar el nuevo .vsix
La extensión detecta automáticamente que el hook instalado usa scripts de una versión anterior y muestra una notificación
Hacer clic en "Actualizar ahora" o ejecutar Docs Pipeline: Actualizar Hook

El hook en el proyecto solo referencia la ruta de la extensión — al actualizarla, los nuevos scripts entran en efecto automáticamente sin tocar el repo del proyecto.

Desinstalar

Cmd+Shift+P → "Docs Pipeline: Desinstalar Hook"

Esto elimina únicamente el bloque del pipeline del archivo hook. Si el hook tenía otras reglas (lint-staged, etc.), se conservan. Si el hook era exclusivo del pipeline, el archivo se elimina.

Para desinstalar la extensión de VS Code:

code --uninstall-extension delfosti.delfosti-docs-pipeline

Desarrollo y build

# Clonar o navegar a la carpeta
cd delfosti-docs-pipeline

# Instalar dependencias de desarrollo
npm install

# Compilar TypeScript
npm run compile

# Modo watch (recompila en cada cambio)
npm run watch

# Empaquetar como .vsix
npm run package

Estructura del proyecto

delfosti-docs-pipeline/
├── src/
│   ├── extension.ts        ← Punto de entrada, registro de comandos
│   ├── hookInstaller.ts    ← Lógica de instalación/desinstalación del hook
│   ├── nodeResolver.ts     ← Detección del binario node en el sistema
│   └── statusBar.ts        ← Indicador en la barra de estado
├── scripts/                ← Pipeline bundleado (se copia al instalar)
│   ├── generate-init.mjs          ← Orquestador principal
│   ├── 00-generate-ascii-art-enterprise.mjs
│   ├── 01-generate-changelog-bitacora.mjs
│   ├── 02-generate-living-documentation.mjs
│   └── 03-generate-changelog-summary.mjs
├── out/                    ← TypeScript compilado (generado por npm run compile)
├── package.json
├── tsconfig.json
└── .vscodeignore

Solución de problemas

El pipeline no corre en el push

Verificar que el hook está instalado: Docs Pipeline: Ver Estado
Revisar que Node.js está en PATH: node --version
Revisar que Claude Code está instalado: claude --version
Para ramas nuevas, verificar que existe una rama base (main, master, dev o qa) en el remoto

"Node.js no encontrado" al instalar

Configura la ruta manualmente en Settings → docsPipeline.nodeBin con la ruta absoluta al binario:

Windows: C:\Program Files\nodejs\node.exe
macOS/Linux: /usr/local/bin/node o la salida de which node

El hook corre pero Claude no responde

Verifica que Claude Code tiene sesión activa:

claude --print "test"

Si devuelve error, ejecuta claude para autenticarte.

Conflicto con Husky

Si tu proyecto usa Husky y el hook ya tiene reglas previas, Docs Pipeline: Instalar Hook agrega el pipeline al final del archivo .husky/pre-push sin sobreescribir las reglas existentes. El bloque queda delimitado con marcadores y puede removerse con Docs Pipeline: Desinstalar Hook.

Licencia

MIT — Delfosti Engineering Team

Delfosti Docs Pipeline

maycolz-delfosti

Delfosti Docs Pipeline

Qué hace

Requisitos previos

Instalación de la extensión

Opción A — Desde el .vsix (recomendado para uso interno)

Opción B — Modo desarrollo (sin empaquetar)

Activar en un proyecto

Comandos disponibles

Configuración

Configuración por proyecto (.env.local)

Cómo funciona por dentro

Notas por stack

Node.js / NestJS

.NET / C#

PHP / Laravel

Flutter / Dart

Python / Django / FastAPI

Actualizar la extensión

Desinstalar

Desarrollo y build

Estructura del proyecto

Solución de problemas

El pipeline no corre en el push

"Node.js no encontrado" al instalar

El hook corre pero Claude no responde

Conflicto con Husky

Licencia

Opción A — Desde el `.vsix` (recomendado para uso interno)

Configuración por proyecto (`.env.local`)