v0.0.1

2026-08-03 07:21:42 +02:00 · 2026-03-22 09:53:08 +00:00
commit 8703f28856
31 changed files with 4543 additions and 0 deletions
@@ -0,0 +1,25 @@
+# 01 — Project Setup
+
+## Objetivo
+Inicializar el proyecto con Bun, TypeScript, Vite, React y todas las dependencias.
+
+## Tareas
+- [ ] `bun init` con TypeScript
+- [ ] `package.json` con scripts: `dev`, `build`, `start`
+- [ ] `tsconfig.json` para server (Node/Bun) y client (React)
+- [ ] `vite.config.ts` con React plugin y proxy al server
+- [ ] Instalar dependencias:
+  - Server: `hono`, `dockerode`, `yaml`, `zod`
+  - Client: `react`, `react-dom`, `@xyflow/react`, `@dagrejs/dagre`
+  - Dev: `typescript`, `vite`, `@vitejs/plugin-react`, `tailwindcss`, `@types/dockerode`
+- [ ] Crear estructura de carpetas:
+  ```
+  src/
+  ├── server/
+  ├── client/
+  └── shared/
+  ```
+- [ ] Verificar que `bun run dev` arranca sin errores
+
+## Criterio de completado
+`bun run dev` levanta el server Hono en :9470 y sirve una página React vacía.
@@ -0,0 +1,21 @@
+# 02 — Docker Auto-Discovery
+
+## Objetivo
+Leer containers, redes y stats desde el Docker socket. Detectar conexiones automáticamente.
+
+## Tareas
+- [ ] `src/server/docker.ts` — `discoverServices()`:
+  - Lee `docker.listContainers({ all: true })`
+  - Extrae: name, image, state, status, ports, networks, project, compose_file
+- [ ] `src/server/docker.ts` — `discoverConnections()`:
+  - Lee redes y detecta qué containers comparten red
+  - Genera edges entre pares de containers en la misma red
+- [ ] `src/server/docker.ts` — `inferEdgeType()`:
+  - Heurísticas: postgres/mysql → "database", redis → "cache", nginx/traefik → "proxy", rabbit/kafka → "broker"
+- [ ] `src/shared/types.ts` — tipos compartidos: `Service`, `Connection`, `EdgeType`, `Stats`
+- [ ] Endpoint REST: `GET /api/services` y `GET /api/connections`
+- [ ] Probar que detecta correctamente los containers de ninjasagacw
+
+## Criterio de completado
+`curl http://localhost:9470/api/services` retorna JSON con todos los containers corriendo.
+`curl http://localhost:9470/api/connections` retorna las conexiones detectadas.
@@ -0,0 +1,24 @@
+# 03 — WebSocket + Stats + Docker Events
+
+## Objetivo
+Enviar datos en tiempo real al frontend via WebSocket: servicios, stats y eventos Docker.
+
+## Tareas
+- [ ] `src/server/watcher.ts` — `pollStats()`:
+  - CPU y MEM por container (solo running)
+  - Calcula cpu_percent, mem_mb, mem_percent
+- [ ] `src/server/watcher.ts` — `watchDockerEvents()`:
+  - Stream de Docker events API
+  - Filtra por Type: "container"
+  - Emite: start, stop, die, restart, health_status
+- [ ] WebSocket en `src/server/index.ts`:
+  - Bun.serve con websocket handler
+  - `broadcast()` a todos los clients conectados
+  - Polling de services + connections + stats cada 3s
+  - Docker events en tiempo real
+- [ ] `src/client/hooks/useDocker.ts`:
+  - Hook que conecta al WebSocket
+  - Mantiene estado de services, connections, stats, events
+
+## Criterio de completado
+Abrir el dashboard, la consola del browser muestra datos llegando por WebSocket cada 3s.
@@ -0,0 +1,21 @@
+# 04 — ServiceNode (nodo visual de container)
+
+## Objetivo
+Crear el componente visual que representa cada container en el grafo.
+
+## Tareas
+- [ ] `src/client/nodes/ServiceNode.tsx`:
+  - Status dot con animate-pulse (running = verde, stopped = rojo, paused = amarillo)
+  - Icono auto-detectado por imagen (postgres=🐘, redis=⚡, nginx=🔀, node=💚, python=🐍, etc.)
+  - Nombre del servicio
+  - Imagen (truncada)
+  - Puertos como badges cyan
+  - Barras de CPU/MEM con porcentaje
+  - Badge del proyecto (compose project name)
+  - Handles top/bottom para edges
+  - Dark theme: bg slate-900, bordes según estado, backdrop-blur
+- [ ] Registrar nodeTypes en React Flow
+- [ ] Probar con datos mock primero
+
+## Criterio de completado
+Se ven nodos bonitos con toda la info, pulso verde en running, rojo en stopped.
@@ -0,0 +1,26 @@
+# 05 — React Flow + Auto-Layout + Agrupación
+
+## Objetivo
+Montar el canvas de React Flow con auto-layout (dagre) y subgraphs por proyecto/compose file.
+
+## Tareas
+- [ ] `src/client/App.tsx`:
+  - React Flow con Background, Controls, MiniMap
+  - Dark theme (bg-slate-950, minimap dark)
+  - fitView al cargar
+- [ ] `src/client/engine/layout.ts`:
+  - Auto-layout con dagre respetando grupos
+  - Nodos dentro de su grupo (parentId)
+  - Posicionamiento que no se solape
+- [ ] Agrupación automática:
+  - `detectGrouping()`: si hay 1 proyecto → agrupa por compose_file, si hay múltiples → agrupa por project
+  - Nodos "group" de React Flow con borde dashed, label, fondo semi-transparente
+  - Colores distintos por grupo
+- [ ] Edges entre nodos:
+  - Usa connections del backend
+  - Label con tipo de conexión (postgres, cache, upstream, broker)
+  - Estilo: línea sólida gris con label
+- [ ] Conectar useDocker hook → actualizar nodos/edges en tiempo real
+
+## Criterio de completado
+Dashboard muestra todos los containers agrupados por proyecto/compose file, con edges entre ellos, auto-layout limpio, minimap, zoom y pan.
@@ -0,0 +1,23 @@
+# 06 — Filtrado de Proyectos (CLI + Frontend)
+
+## Objetivo
+Permitir filtrar qué proyectos se muestran, tanto por CLI como por dropdown en el frontend.
+
+## Tareas
+- [ ] CLI args en `src/server/index.ts`:
+  - `--all` → carga todos los containers
+  - `--projects=name1,name2` → filtra por com.docker.compose.project
+  - Sin flags → auto-detecta por `path.basename(process.cwd())`
+  - Filtro aplicado en `discoverServices()`
+- [ ] `src/client/panels/ProjectFilter.tsx`:
+  - Dropdown con checkboxes por proyecto
+  - "Mostrar todos" toggle
+  - Selección se guarda en localStorage
+  - Solo visible si hay más de 1 proyecto (si usó --all o --projects con varios)
+- [ ] Filtro en el frontend:
+  - Los nodos/edges se filtran en el cliente según selección
+  - Transición suave al mostrar/ocultar nodos
+
+## Criterio de completado
+`bunx alteonx-dockerflow --all` muestra todos los proyectos con dropdown para filtrar.
+`bunx alteonx-dockerflow` sin flags muestra solo el proyecto del directorio actual, sin dropdown.
@@ -0,0 +1,23 @@
+# 07 — Seguridad (AUTH_TOKEN)
+
+## Objetivo
+Proteger el dashboard con token cuando se expone en red.
+
+## Tareas
+- [ ] Lógica de bind:
+  - Sin `AUTH_TOKEN` → bind a `127.0.0.1` (solo local)
+  - Con `AUTH_TOKEN` → bind a `0.0.0.0` (acceso remoto)
+- [ ] Middleware Hono:
+  - Valida `Authorization: Bearer <token>` en toda request excepto `/` y assets
+  - 401 si token inválido
+- [ ] WebSocket auth:
+  - Valida token en el handshake
+  - Cierra conexión si no es válido
+- [ ] Pantalla de login en el frontend:
+  - Input de token, botón "Entrar"
+  - Guarda token en localStorage
+  - Lo envía en headers y WebSocket
+
+## Criterio de completado
+Sin AUTH_TOKEN: funciona sin pedir nada en localhost.
+Con AUTH_TOKEN: pide token al entrar, rechaza si es incorrecto, funciona si es correcto.
@@ -0,0 +1,29 @@
+# 08 — Polish Fase 1
+
+## Objetivo
+Pulir detalles visuales y funcionales para cerrar la Fase 1.
+
+## Tareas
+- [ ] Header del dashboard:
+  - Logo/nombre "Alteonx DockerFlow"
+  - Indicador de conexión WebSocket (verde = conectado, rojo = desconectado)
+  - Dropdown de proyecto (de tarea 06)
+- [ ] Docker events visuales:
+  - Container start → flash verde en el nodo
+  - Container stop/die → flash rojo en el nodo
+  - Container restart → flash amarillo
+- [ ] Tooltips en nodos:
+  - Hover → muestra status completo, uptime, networks
+- [ ] Edge labels legibles:
+  - No se solapen entre sí
+  - Se ocultan en zoom bajo
+- [ ] Responsive básico:
+  - Funcione en pantallas desde 1280px
+- [ ] Console log limpio (sin warnings de React/Vite)
+- [ ] README.md básico con:
+  - Qué es
+  - Quickstart (3 comandos)
+  - Screenshot placeholder
+
+## Criterio de completado
+Dashboard se ve profesional, sin bugs visuales, README funcional.