diff --git a/CLAUDE.md b/CLAUDE.md index 1eebea0..9a446b4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,6 @@ -# QTorres — Contexto para Claude Code +# Telekino — Contexto para Claude Code -> Última actualización: 2026-04-20 +> Última actualización: 2026-05-11 ## Reglas absolutas — NUNCA violar @@ -22,10 +22,11 @@ Estas reglas son inviolables. No importa qué Issue estés implementando ni qué ## Qué es este proyecto -QTorres es una alternativa open source a LabVIEW construida íntegramente en Red-Lang. El usuario construye programas arrastrando bloques y conectándolos con wires, igual que en LabVIEW. Al guardar, QTorres genera un fichero `.qvi` con código Red/View completo que al ejecutarse muestra el Front Panel como una ventana, igual que LabVIEW. +Telekino es una alternativa open source a LabVIEW construida íntegramente en Red-Lang. El usuario construye programas arrastrando bloques y conectándolos con wires, igual que en LabVIEW. Al guardar, Telekino genera un fichero `.qvi` con código Red/View completo que al ejecutarse muestra el Front Panel como una ventana, igual que LabVIEW. -**Nombre:** QTorres (por Torres Quevedo) -**Repositorio:** https://github.com/anlaco/QTorres +**Nombre:** Telekino (por Torres Quevedo y su Telekino, primer mando a distancia, 1903) +**Repositorio:** https://github.com/anlaco/Telekino (anteriormente `anlaco/QTorres`) +**Directorio de trabajo local:** `/home/alaforga/Anlaco/01-PRODUCTOS/QTorres/` (no renombrado, mantiene el path histórico) **Backlog:** https://github.com/users/anlaco/projects/1 ## Stack tecnológico @@ -43,7 +44,7 @@ Sin dependencias externas. Un solo binario. Funciona en Linux, Windows y macOS. ## Estructura del proyecto ``` -QTorres/ +Telekino/ ├── CLAUDE.md # Este fichero — contexto principal para IA ├── README.md ├── docs/ @@ -53,11 +54,11 @@ QTorres/ │ ├── PLANNING.md # Decisiones pendientes críticas │ ├── retos.md # Riesgos y dificultades │ ├── visual-spec.md # Especificación visual (documento vivo) -│ ├── tipos-de-fichero.md # Mapeo LabVIEW → QTorres +│ ├── tipos-de-fichero.md # Mapeo LabVIEW → Telekino │ ├── labview-comportamiento.md # Arquitectura LabVIEW: renderizado, modos, estilos │ └── GTK_ISSUES.md # Bugs del backend GTK en Linux ├── src/ -│ ├── qtorres.red # Punto de entrada + toolbar + ventana principal +│ ├── telekino.red # Punto de entrada + toolbar + ventana principal │ ├── graph/ │ │ ├── model.red # Modelo: make-label, make-node, make-wire, make-fp-item, set-config, find-node-by-id (635 líneas) │ │ └── blocks.red # Registro de bloques + dialecto block-def — 40 bloques @@ -118,13 +119,21 @@ QTorres/ - ~~#54 Cluster persiste campos~~ ✅ ~~#48/#50/#51 bugs menores~~ ✅ - QA-018/029: protecciones de integridad ✅ - Refactor 4A-4E: responsabilidades reorganizadas, ficheros grandes divididos ✅ -- 482 tests PASS +- 558 tests PASS -**Fase 3 — Sub-VIs y extensibilidad (en curso):** +**Fase 3 — Sub-VIs y extensibilidad ✅ COMPLETADA (excepto deudas menores):** - ~~#17 Sub-VI con connector pane~~ ✅ (pin-based connector, compile-subvi-call, runner carga contextos, btn-run sincronizado) -- ~~#18 Librería .qlib~~ ✅ (load-qlib, find-qlibs, paleta integrada, ejemplo math.qlib, 482 tests PASS) +- ~~#18 Librería .qlib~~ ✅ (load-qlib, find-qlibs, paleta integrada, ejemplo math.qlib) - ~~#64 FP como ventana maestra~~ ✅ (FP=blocking master, BD=no-wait slave, Ctrl+E toggle, títulos sincronizados, current-file en app-model) - ~~#65 Scroll en BD y FP~~ ✅ (ventanas fijas 900x600, scroll wheel + click scrollbar, límites por contenido real) +- ~~#71 Rename QTorres → Telekino~~ ✅ (src/telekino.red, repo `anlaco/Telekino` en GitHub; directorio local sigue siendo `QTorres/`) +- ~~#72 Estilo BD nodos cuadrados~~ ✅ (60x60, labels independientes, selección dashed-box, fix precedencia) +- Deudas abiertas: #28 FP standalone, #49 string auto-update, #61 cluster edición interactiva, #68 ventanas redimensionables (parte 2 de #65), #37 push/font GTK +- 558 tests PASS + +**Fase 4 — Hardware (en curso):** +- ~~#19 TCP/IP — bloques cliente estilo LabVIEW~~ ✅ (PR #70, cerrado 2026-04-21; ver `docs/tcp-api.md`) +- ⏳ #20 USBTMC, #21 Serie RS-232/485, #22 Modbus TCP + servidor, #23 DAQ **Fase 5 — UX y gestión de proyectos (planificado):** - Splash / Welcome screen (Create New VI, Open Existing, proyectos recientes) @@ -132,11 +141,11 @@ QTorres/ - Depende de: .qlib (#18) ✅ y FP como ventana maestra (#64) ✅ - **Nota:** Prototipo temprano de `.qproj` existe en `examples/ejemplo.qproj` — sirve como referencia del formato, pero sin tooling de Project Explorer aún -**Próximo paso:** Fase 4 (hardware) → Fase 4.5 (integración red-sg) → Fase 5 (UX) +**Próximo paso:** Continuar Fase 4 con #21 (Serie) o #20 (USBTMC) → Fase 4.5 (integración red-sg) → Fase 5 (UX) **Refactor 4B ✅ COMPLETADO (2026-04-17):** `compiler.red` (1255 → 18 líneas orquestador + 5 módulos) y `file-io.red` (939 → 17 líneas orquestador + 4 módulos). Todos los módulos <400 líneas excepto `file-io-serialize.red` (468) por `format-qvi` monolítica. 482/482 tests PASS. Ver `docs/refactor-4b-plan.md` para el plan original. -**Prioridad:** Fase 4 hardware antes que Fase 5 UX. Un QTorres que habla con instrumentos reales es más valioso que uno con undo/redo pulido. La Fase 4.5 (red-sg) se sitúa entre ambas como puente natural de la separación aplicación/toolkit (ver DT-030 y `docs/roadmap-9-10.md`). +**Prioridad:** Fase 4 hardware antes que Fase 5 UX. Un Telekino que habla con instrumentos reales es más valioso que uno con undo/redo pulido. La Fase 4.5 (red-sg) se sitúa entre ambas como puente natural de la separación aplicación/toolkit (ver DT-030 y `docs/roadmap-9-10.md`). **Nota sobre el fork `anlaco/red`:** Los binarios `red-cli` y `red-view` se compilan desde un fork propio del repositorio Red, mantenido en `/home/alaforga/Anlaco/01-PRODUCTOS/red/` con origen `https://github.com/anlaco/red.git`. Este fork aplica fixes GTK3 (GTK-014, GTK-003 A/B) que upstream no ha cerrado. Ver `docs/GTK_ISSUES.md` para estado de cada bug y sus commits resolutivos en el fork. El fork se sincroniza periódicamente con `red/red` upstream pero se mantiene como copia local para independencia de Red upstream. @@ -181,14 +190,14 @@ view layout [ 3. **emit** — define qué código Red genera cada bloque al compilar ### DT-005: El .qvi tiene dos secciones -1. `qvi-diagram: [...]` — cabecera gráfica (inerte para Red, usada por QTorres para reconstruir la vista) +1. `qvi-diagram: [...]` — cabecera gráfica (inerte para Red, usada por Telekino para reconstruir la vista) 2. Código Red/View generado — ejecutable directamente con `red mi-vi.qvi` ### DT-010: Runner en memoria (decisión clave) Run compila en memoria y ejecuta con `do`. Save escribe el `.qvi` al disco. Son independientes. ### DT-011: qvi-diagram es la fuente de verdad -El código generado es un artefacto. QTorres siempre recompila desde `qvi-diagram` al cargar. +El código generado es un artefacto. Telekino siempre recompila desde `qvi-diagram` al cargar. Un `.qvi` con solo `qvi-diagram` (sin código generado) es válido. ### DT-017: El tipo de VI lo determina el contexto de llamada @@ -208,7 +217,7 @@ Prototipo `base-element` + constructores `make-node`, `make-wire`. Patrón idiom Son independientes. El compilador usa `name`, la UI usa `label/text`. ### DT-027 — CRÍTICO: Concurrencia cooperativa (rate/on-time) -Red no tiene multihilo. QTorres simula concurrencia con timers de Red/View: +Red no tiene multihilo. Telekino simula concurrencia con timers de Red/View: - While Loop = timer (`face/rate` + `on-time`) que ejecuta una iteración por tick - Múltiples loops = múltiples timers independientes, Red despacha en round-robin - Event Structure = timer que comprueba cola de eventos @@ -220,7 +229,7 @@ Red no tiene multihilo. QTorres simula concurrencia con timers de Red/View: El `.qvi` generado **debe compilarse** con `red -c` a ejecutable nativo. - **PROHIBIDO** en código generado: `do` con bloques dinámicos, `load` de strings, `compose` en runtime - **PERMITIDO**: `view layout [...]` estático, funciones con nombre, `face/rate` + `on-time` -- `compose` se ejecuta en el compilador de QTorres (al generar), NO en el `.qvi` generado +- `compose` se ejecuta en el compilador de Telekino (al generar), NO en el `.qvi` generado ### DT-029: Error handling progresivo - **Nivel 0 (Fase 2)**: Error nativo de Red — programa se para. Sin cables de error. @@ -253,11 +262,11 @@ qvi-diagram: [ ## Flujo de trabajo ### Cómo trabajar un Issue -1. Leer el Issue en GitHub (`gh issue view N --repo anlaco/QTorres`) +1. Leer el Issue en GitHub (`gh issue view N --repo anlaco/Telekino`) 2. Implementar en el módulo correspondiente de `src/` 3. Verificar con los ejemplos de `examples/` 4. Ejecutar los tests (`red-cli tests/run-all.red`) y verificar que pasan -5. Cerrar el Issue cuando esté completo (`gh issue close N --repo anlaco/QTorres`) +5. Cerrar el Issue cuando esté completo (`gh issue close N --repo anlaco/Telekino`) ### Orden de los Issues (backlog) Trabajar siempre en orden de Fase. No empezar una fase sin completar la anterior. @@ -295,13 +304,13 @@ Spec visual: cada tipo implementa su aspecto según `docs/visual-spec.md`. - ~~#65 Scroll en BD y FP~~ ✅ (ventanas fijas 900x600, scrollbars draw-based, límites por contenido) **Fase 4 — Hardware:** -- #19 TCP/IP — bloques básicos cliente (tcp-connect/write/read/close) +- ~~#19 TCP/IP — bloques básicos cliente (tcp-connect/write/read/close)~~ ✅ (cerrado 2026-04-21) - #20 USBTMC — acceso genérico a instrumentos USB (/dev/usbtmc*) - #21 Puerto serie RS-232/RS-485 (Arduino, ESP32) - #22 Modbus TCP y servidor TCP/IP (depende de #19) - #23 DAQ analógico (comedi/libcomedi) -> **Nota:** NO se implementan bloques SCPI específicos. SCPI es un protocolo de comandos en texto que se envía como string vía `tcp-write` o `usbtmc-write`. Esto mantiene QTorres genérico y sirve también para Modbus, protocolos propios y cualquier otro protocolo sobre TCP/USB. +> **Nota:** NO se implementan bloques SCPI específicos. SCPI es un protocolo de comandos en texto que se envía como string vía `tcp-write` o `usbtmc-write`. Esto mantiene Telekino genérico y sirve también para Modbus, protocolos propios y cualquier otro protocolo sobre TCP/USB. **Fase 5 — UX y gestión de proyectos:** - Splash / Welcome screen (Create New VI, Open Existing, proyectos recientes) @@ -313,13 +322,13 @@ Los binarios `red-cli` y `red-view` se compilan desde el fork `https://github.co ## Ollama MCP — Delegación de tareas a modelo local -QTorres tiene un MCP server que conecta con Ollama (modelo local). Ollama tiene cargado automáticamente CLAUDE.md y el skill de Red-Lang como contexto del proyecto. +Telekino tiene un MCP server que conecta con Ollama (modelo local). Ollama tiene cargado automáticamente CLAUDE.md y el skill de Red-Lang como contexto del proyecto. ### Cuándo usar Ollama (herramienta `ollama_delegate`) **USAR para:** - **Generar código Red mecánico** — emit de bloques, funciones simples, boilerplate. Ollama tiene el SKILL.md y genera código idiomático. -- **Revisar ficheros grandes** — `ollama_review_file` o `ollama_explain_file` lee el fichero server-side sin gastar tokens de Claude. Ideal para canvas.red (2383 líneas). +- **Revisar ficheros grandes** — `ollama_review_file` o `ollama_explain_file` lee el fichero server-side sin gastar tokens de Claude. Ideal para canvas.red (1307 líneas). - **Verificar convenciones** — "¿este código cumple las reglas del proyecto?" - **Tareas repetitivas** — generar tests, formatear datos, transformar estructuras. @@ -353,7 +362,7 @@ El contexto se define en `.ollama-context.json` en la raíz del proyecto: ```json { "context_files": ["./CLAUDE.md", "./skills/red-lang/SKILL.md"], - "system_prompt": "You are a coding assistant for QTorres..." + "system_prompt": "You are a coding assistant for Telekino..." } ``` @@ -369,16 +378,16 @@ red examples/suma-basica.qvi red-cli tests/run-all.red # Ejecutar la aplicación completa -red-view src/qtorres.red +red-view src/telekino.red # Ver Issues pendientes -gh issue list --repo anlaco/QTorres --label "fase-2" +gh issue list --repo anlaco/Telekino --label "fase-2" # Ver un Issue concreto -gh issue view 14 --repo anlaco/QTorres +gh issue view 14 --repo anlaco/Telekino # Cerrar un Issue -gh issue close 14 --repo anlaco/QTorres --comment "Implementado en src/..." +gh issue close 14 --repo anlaco/Telekino --comment "Implementado en src/..." ``` ## Convenciones de código @@ -424,7 +433,7 @@ Cubre sintaxis core, View, Draw, VID, Parse, patrones idiomáticos y gotchas. | `make-fp-item`, `fp-cluster-fields`, `fp-default-label` | `model.red` | ✅ Movida | | `find-node-by-id` | `model.red` | ✅ Añadida | | `set-config` | `model.red` | ✅ Añadida | -| Lógica de `btn-run` (50+ líneas inline) | qtorres.red | ⚠️ Pendiente Fase 3 | +| Lógica de `btn-run` (50+ líneas inline) | telekino.red | ⚠️ Pendiente Fase 3 | ### Dependencia canvas.red <-> panel.red @@ -438,7 +447,7 @@ El acoplamiento es **por diseño del dominio** (FP↔BD son una unidad 1:1) y no | Fichero | Líneas | Contenido | |---------|--------|-----------| -| canvas.red | 1265 | Hit-test, CRUD, actor render-diagram | +| canvas.red | 1307 | Hit-test, CRUD, actor render-diagram | | canvas-render.red | 1050 | Constantes visuales, geometría, Draw | | canvas-dialogs.red | 516 | Diálogos de edición, paleta, SR helpers | | panel.red | 599 | Hit-test, diálogos FP, paleta FP, actor | @@ -464,9 +473,9 @@ El acoplamiento es **por diseño del dominio** (FP↔BD son una unidad 1:1) y no ### Estado global compartido -`app-model` (definido en qtorres.red) es el único modelo compartido. canvas.red, panel.red y qtorres.red lo leen y mutan a través de `face/extra`. No hay mecanismo de notificación. +`app-model` (definido en telekino.red) es el único modelo compartido. canvas.red, panel.red y telekino.red lo leen y mutan a través de `face/extra`. No hay mecanismo de notificación. ### Plan de corrección (pendiente Fase 3) 1. Centralizar conocimiento de tipos en blocks.red (hints de renderizado) -2. Extraer lógica de `btn-run` a función nombrada en qtorres.red +2. Extraer lógica de `btn-run` a función nombrada en telekino.red