feat(cybersecurity): auto-commit con 48 cambios
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -4,8 +4,14 @@
|
|||||||
{
|
{
|
||||||
"matcher": "Bash",
|
"matcher": "Bash",
|
||||||
"hooks": [
|
"hooks": [
|
||||||
{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/scripts/hook_registry_mcp.sh" },
|
{
|
||||||
{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/scripts/hook_fn_match.sh" }
|
"type": "command",
|
||||||
|
"command": "$CLAUDE_PROJECT_DIR/.claude/scripts/hook_registry_mcp.sh"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"type": "command",
|
||||||
|
"command": "$CLAUDE_PROJECT_DIR/.claude/scripts/hook_fn_match.sh"
|
||||||
|
}
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
@@ -13,23 +19,39 @@
|
|||||||
{
|
{
|
||||||
"matcher": "Bash|Edit|Write|MultiEdit|mcp__registry__.*",
|
"matcher": "Bash|Edit|Write|MultiEdit|mcp__registry__.*",
|
||||||
"hooks": [
|
"hooks": [
|
||||||
{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/scripts/hook_call_monitor.sh" }
|
{
|
||||||
|
"type": "command",
|
||||||
|
"command": "$CLAUDE_PROJECT_DIR/.claude/scripts/hook_call_monitor.sh"
|
||||||
|
}
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"matcher": "Edit|Write|MultiEdit|mcp__registry__fn_create_function",
|
"matcher": "Edit|Write|MultiEdit|mcp__registry__fn_create_function",
|
||||||
"hooks": [
|
"hooks": [
|
||||||
{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/scripts/hook_capability_tag_gate.sh" }
|
{
|
||||||
|
"type": "command",
|
||||||
|
"command": "$CLAUDE_PROJECT_DIR/.claude/scripts/hook_capability_tag_gate.sh"
|
||||||
|
}
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"UserPromptSubmit": [
|
"UserPromptSubmit": [
|
||||||
{
|
{
|
||||||
"hooks": [
|
"hooks": [
|
||||||
{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/scripts/hook_capabilities_inject.sh" },
|
{
|
||||||
{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/scripts/hook_registry_first_reminder.sh" }
|
"type": "command",
|
||||||
]
|
"command": "$CLAUDE_PROJECT_DIR/.claude/scripts/hook_capabilities_inject.sh"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"type": "command",
|
||||||
|
"command": "$CLAUDE_PROJECT_DIR/.claude/scripts/hook_registry_first_reminder.sh"
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"enabledMcpjsonServers": [
|
||||||
|
"registry",
|
||||||
|
"jupyter"
|
||||||
|
]
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -0,0 +1,7 @@
|
|||||||
|
{
|
||||||
|
"0ea5e69b-9607-4f11-b740-005e835faef6": {
|
||||||
|
"version": "2.4.0",
|
||||||
|
"created_at": "2026-06-03T17:52:16.077873+00:00",
|
||||||
|
"document_version": "2.0.0"
|
||||||
|
}
|
||||||
|
}
|
||||||
Binary file not shown.
@@ -23,7 +23,7 @@ Indice de grupos de capacidades del registry. Cada grupo agrupa >=3 funciones qu
|
|||||||
| [nlp](nlp.md) | 33 | Extraccion NLP: PDFs, OCR, chunking, GLiNER/GLiREL, dedup, agregacion de entities/relations |
|
| [nlp](nlp.md) | 33 | Extraccion NLP: PDFs, OCR, chunking, GLiNER/GLiREL, dedup, agregacion de entities/relations |
|
||||||
| [docker](docker.md) | 38 | Operar Docker desde Go/Bash: build/run/stop, compose, networks, volumes, logs, deploys |
|
| [docker](docker.md) | 38 | Operar Docker desde Go/Bash: build/run/stop, compose, networks, volumes, logs, deploys |
|
||||||
| [android](android.md) | 37 | Toolbelt Android desde WSL2: adb, emuladores AVD, APK build/install, Capacitor, logcat |
|
| [android](android.md) | 37 | Toolbelt Android desde WSL2: adb, emuladores AVD, APK build/install, Capacitor, logcat |
|
||||||
| [web-proxy](web-proxy.md) | 4 | Captura de trafico HTTP/HTTPS liviana (mitmproxy): proxy con rotacion, navegador proxeado, consulta de capturas. Alternativa ligera a ZAP/Burp |
|
| [web-proxy](web-proxy.md) | 5 | Captura de trafico HTTP/HTTPS liviana (mitmproxy): proxy con rotacion, navegador proxeado, consulta de capturas, tee del SSE de claude. Alternativa ligera a ZAP/Burp |
|
||||||
| [metabase](metabase.md) | 106 | Operar Metabase via API REST: auth, cards, dashboards, collections, snippets, permissions |
|
| [metabase](metabase.md) | 106 | Operar Metabase via API REST: auth, cards, dashboards, collections, snippets, permissions |
|
||||||
| [doctor](doctor.md) | 11 | Diagnostico read-only del registry: artefactos, servicios, drift, funciones huerfanas |
|
| [doctor](doctor.md) | 11 | Diagnostico read-only del registry: artefactos, servicios, drift, funciones huerfanas |
|
||||||
| [notebook](notebook.md) | 5 | Operar Jupyter Lab colaborativo (discover/read/exec/write/kernel) |
|
| [notebook](notebook.md) | 5 | Operar Jupyter Lab colaborativo (discover/read/exec/write/kernel) |
|
||||||
@@ -45,6 +45,7 @@ Indice de grupos de capacidades del registry. Cada grupo agrupa >=3 funciones qu
|
|||||||
| [wireguard](wireguard.md) | 7 | Instalar, configurar, operar y monitorizar mesh WireGuard hub-and-spoke: keygen, hub setup, peer add/revoke, status JSON |
|
| [wireguard](wireguard.md) | 7 | Instalar, configurar, operar y monitorizar mesh WireGuard hub-and-spoke: keygen, hub setup, peer add/revoke, status JSON |
|
||||||
| [matrix-mas](matrix-mas.md) | 5 | Migración Synapse→MAS: habilitar MSC3861, verificar login flows, parche .well-known, registro clientes OAuth2, syn2mas |
|
| [matrix-mas](matrix-mas.md) | 5 | Migración Synapse→MAS: habilitar MSC3861, verificar login flows, parche .well-known, registro clientes OAuth2, syn2mas |
|
||||||
| [mesh-3d](mesh-3d.md) | 3 | Carga y upload a GPU de meshes 3D (OBJ, GLB/glTF 2.0): loaders CPU + mesh_gpu_upload OpenGL |
|
| [mesh-3d](mesh-3d.md) | 3 | Carga y upload a GPU de meshes 3D (OBJ, GLB/glTF 2.0): loaders CPU + mesh_gpu_upload OpenGL |
|
||||||
|
| [terminal-capture](terminal-capture.md) | 6 | Automatizar y capturar el texto de una CLI/TUI interactiva via PTY headless: spawn+input scripteado (one-shot y streaming), render del layout 2D (emulador VT), strip ANSI, delta por prefijo, y parseo de la TUI de claude a datos |
|
||||||
|
|
||||||
## Como anadir grupo
|
## Como anadir grupo
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,97 @@
|
|||||||
|
---
|
||||||
|
group: e2e-messaging
|
||||||
|
description: "Criptografía extremo a extremo para bus de mensajería: identidades duales Ed25519/X25519, distribución de claves de sala con sealed box anónimo, cifrado simétrico AEAD por mensaje, y firma/verificación de mensajes."
|
||||||
|
functions:
|
||||||
|
- generate_identity_go_cybersecurity
|
||||||
|
- seal_aead_go_cybersecurity
|
||||||
|
- open_aead_go_cybersecurity
|
||||||
|
- seal_key_box_go_cybersecurity
|
||||||
|
- open_key_box_go_cybersecurity
|
||||||
|
- sign_ed25519_go_cybersecurity
|
||||||
|
- verify_ed25519_go_cybersecurity
|
||||||
|
---
|
||||||
|
|
||||||
|
## Funciones del grupo
|
||||||
|
|
||||||
|
| ID | Firma corta | Qué hace |
|
||||||
|
|---|---|---|
|
||||||
|
| `generate_identity_go_cybersecurity` | `GenerateIdentity() (Identity, error)` | Genera par Ed25519 (firma) + par X25519 (kex) para un participante |
|
||||||
|
| `seal_aead_go_cybersecurity` | `SealAEAD(key, plaintext, aad []byte) (nonce, ct []byte, err error)` | Cifra mensaje con ChaCha20-Poly1305, nonce aleatorio por llamada |
|
||||||
|
| `open_aead_go_cybersecurity` | `OpenAEAD(key, nonce, ct, aad []byte) ([]byte, error)` | Descifra y autentica; error explícito si el tag falla |
|
||||||
|
| `seal_key_box_go_cybersecurity` | `SealKeyBox(recipientKexPub, secret []byte) ([]byte, error)` | Cifra room key para un destinatario con su X25519 pubkey (sealed box anónimo) |
|
||||||
|
| `open_key_box_go_cybersecurity` | `OpenKeyBox(kexPub, kexPriv, sealedMsg []byte) ([]byte, error)` | Abre sealed box con el par X25519 propio para recuperar la room key |
|
||||||
|
| `sign_ed25519_go_cybersecurity` | `SignEd25519(priv, msg []byte) []byte` | Firma determinista Ed25519 (pura, sin I/O) |
|
||||||
|
| `verify_ed25519_go_cybersecurity` | `VerifyEd25519(pub, msg, sig []byte) bool` | Verifica firma Ed25519 (pura, sin I/O) |
|
||||||
|
|
||||||
|
## Ejemplo canónico end-to-end
|
||||||
|
|
||||||
|
```go
|
||||||
|
package main
|
||||||
|
|
||||||
|
import (
|
||||||
|
"fmt"
|
||||||
|
"log"
|
||||||
|
cs "fn-registry/functions/cybersecurity"
|
||||||
|
)
|
||||||
|
|
||||||
|
func main() {
|
||||||
|
// 1. Cada participante genera su identidad una sola vez
|
||||||
|
server, err := cs.GenerateIdentity()
|
||||||
|
if err != nil { log.Fatal(err) }
|
||||||
|
user, err := cs.GenerateIdentity()
|
||||||
|
if err != nil { log.Fatal(err) }
|
||||||
|
|
||||||
|
// 2. Servidor genera room key y la distribuye al usuario cifrada
|
||||||
|
roomKey := make([]byte, 32)
|
||||||
|
// ... llenar roomKey con crypto/rand en producción ...
|
||||||
|
sealed, err := cs.SealKeyBox(user.KexPub, roomKey)
|
||||||
|
if err != nil { log.Fatal(err) }
|
||||||
|
|
||||||
|
// 3. Usuario recupera la room key
|
||||||
|
gotKey, err := cs.OpenKeyBox(user.KexPub, user.KexPriv, sealed)
|
||||||
|
if err != nil { log.Fatal(err) }
|
||||||
|
|
||||||
|
// 4. Usuario cifra un mensaje con la room key
|
||||||
|
aad := []byte("room:sala-general:seq:1")
|
||||||
|
nonce, ct, err := cs.SealAEAD(gotKey, []byte("hola sala"), aad)
|
||||||
|
if err != nil { log.Fatal(err) }
|
||||||
|
|
||||||
|
// 5. Usuario firma el ciphertext para autenticar autoría
|
||||||
|
sig := cs.SignEd25519(user.SignPriv, ct)
|
||||||
|
|
||||||
|
// 6. Receptor verifica firma y descifra
|
||||||
|
if !cs.VerifyEd25519(user.SignPub, ct, sig) {
|
||||||
|
log.Fatal("firma inválida")
|
||||||
|
}
|
||||||
|
plain, err := cs.OpenAEAD(gotKey, nonce, ct, aad)
|
||||||
|
if err != nil { log.Fatal(err) }
|
||||||
|
fmt.Printf("recibido: %s\n", plain)
|
||||||
|
_ = server // server.SignPub publicado en directorio de participantes
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Fronteras
|
||||||
|
|
||||||
|
Este grupo cubre las primitivas criptográficas del bus, no el protocolo completo:
|
||||||
|
|
||||||
|
- **No cubre**: transporte (WebSocket, gRPC), gestión de sesiones, ratchet de claves (doble ratchet), persistencia de identidades, revocación de claves.
|
||||||
|
- **No cubre**: cifrado de archivos adjuntos (usar SealAEAD directamente con una key derivada).
|
||||||
|
- **No reemplaza**: libsodium ni libolm para implementaciones de producción de Signal/Matrix — estas funciones son el sustrato criptográfico, no el protocolo completo.
|
||||||
|
|
||||||
|
## Prerequisitos
|
||||||
|
|
||||||
|
- `golang.org/x/crypto` ya en `go.mod` (presente en fn-registry).
|
||||||
|
- `crypto/ed25519` de stdlib (Go 1.13+).
|
||||||
|
- Identidades persistidas de forma segura (keyring, HSM, archivo cifrado): este grupo no gestiona almacenamiento.
|
||||||
|
|
||||||
|
## Patrón de uso recomendado
|
||||||
|
|
||||||
|
```
|
||||||
|
GenerateIdentity() → persiste Identity por participante
|
||||||
|
SealKeyBox(kexPub, roomKey) → distribuye room key al unirse a sala
|
||||||
|
OpenKeyBox(kexPub, kexPriv) → recupera room key
|
||||||
|
SealAEAD(roomKey, msg, aad) → cifra cada mensaje
|
||||||
|
SignEd25519(signPriv, ct) → autentica autoría sobre ciphertext
|
||||||
|
VerifyEd25519(signPub, ct) → verifica antes de descifrar
|
||||||
|
OpenAEAD(roomKey, nonce, ct)→ descifra mensaje verificado
|
||||||
|
```
|
||||||
@@ -0,0 +1,86 @@
|
|||||||
|
# terminal-capture
|
||||||
|
|
||||||
|
Automatizar una CLI/TUI interactiva y capturar su texto, de forma headless, a través de un
|
||||||
|
pseudo-terminal (PTY). Cubre el ciclo completo: lanzar el proceso con un TTY real, inyectarle
|
||||||
|
input scripteado, esperar a que el render se estabilice, y convertir el stream crudo de bytes a
|
||||||
|
texto plano — bien reconstruyendo el layout 2D (TUIs con cursor absoluto), bien limpiando ANSI
|
||||||
|
de output secuencial.
|
||||||
|
|
||||||
|
Existe porque muchas CLIs (sobre todo la CLI `claude`) solo entran en su modo interactivo rico
|
||||||
|
cuando detectan un TTY; un pipe normal las degrada. El PTY es virtual, en memoria: **nunca abre
|
||||||
|
una ventana de terminal**.
|
||||||
|
|
||||||
|
## Funciones
|
||||||
|
|
||||||
|
| ID | Firma | Qué hace |
|
||||||
|
|---|---|---|
|
||||||
|
| `pty_capture_idle_go_infra` | `func PTYCaptureIdle(ctx, name string, args []string, warmup time.Duration, inputs []string, stepDelay, idle, maxDur time.Duration) (string, error)` | Lanza `name args` en un PTY (40×120), espera `warmup`, escribe cada `inputs` separado por `stepDelay`, y captura todos los bytes hasta que pasa `idle` sin output nuevo o se alcanza `maxDur`. Devuelve el stream **crudo** (ANSI intacto). One-shot. |
|
||||||
|
| `pty_capture_stream_go_infra` | `func PTYCaptureStream(ctx, name string, args []string, warmup time.Duration, inputs []string, stepDelay, snapshotInterval, idle, maxDur time.Duration) (<-chan string, error)` | Igual que `pty_capture_idle` pero emite **snapshots acumulativos** del buffer por un canal cada `snapshotInterval` — para hacer streaming de la TUI mientras renderiza. El consumidor renderiza/parsea cada snapshot. |
|
||||||
|
| `text_prefix_delta_go_core` | `func PrefixDelta(prev, curr string) string` | Devuelve la parte de `curr` que sigue al prefijo común con `prev` (delta de streaming por snapshots). Pura, compara por runas. Heurística ante reflow. |
|
||||||
|
| `vt_render_go_tui` | `func VTRender(raw string, rows, cols int) string` | Emula un terminal VT100 de `rows×cols`, alimenta `raw`, y devuelve el estado final de la pantalla como texto plano **con el layout reconstruido** (espacios reales donde el stream tenía movimientos de cursor). Pura. |
|
||||||
|
| `strip_ansi_go_core` | `func StripANSI(s string) string` | Elimina secuencias ANSI/VT100 y caracteres de control de un stream **secuencial** (logs), preservando `\n`, `\t`, `\r`. Pura. NO reconstruye layout 2D. |
|
||||||
|
| `parse_claude_tui_go_tui` | `func ParseClaudeTUI(screen string) ClaudeTUIParse` | Parsea la pantalla renderizada de la TUI de `claude` (salida de `vt_render`) y extrae los turnos (user/assistant/tool_use/tool_result) + la respuesta final (`Answer`), equivalente a lo que devolvería `claude -p`. Pura, heurística, específica de la TUI de claude. |
|
||||||
|
|
||||||
|
## Cuándo usar cada limpiador
|
||||||
|
|
||||||
|
El corazón del grupo es `pty_capture_idle` (la captura). Lo que cambia es cómo conviertes el raw a texto:
|
||||||
|
|
||||||
|
| Si la salida es… | Usa | Porque |
|
||||||
|
|---|---|---|
|
||||||
|
| Una TUI con posicionamiento absoluto (`claude`, `htop`, `dialog`) | `vt_render_go_tui` (modo screen) | Los "espacios" entre columnas eran movimientos de cursor; sin emular el grid las palabras se pegan (`2newMCPservers`). |
|
||||||
|
| Output secuencial línea a línea (logs, builds) | `strip_ansi_go_core` (modo stream) | No hay layout 2D que reconstruir; basta quitar los escape codes. |
|
||||||
|
| Quieres procesar los escape codes tú mismo | (ninguno — usa el raw) | El raw de `pty_capture_idle` ya los conserva. |
|
||||||
|
|
||||||
|
## Ejemplo canónico (end-to-end)
|
||||||
|
|
||||||
|
Capturar la respuesta de la CLI `claude` como texto con layout, en Go:
|
||||||
|
|
||||||
|
```go
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
"time"
|
||||||
|
"fn-registry/functions/infra"
|
||||||
|
"fn-registry/functions/tui"
|
||||||
|
)
|
||||||
|
|
||||||
|
func main() {
|
||||||
|
ctx := context.Background()
|
||||||
|
// Teclear el prompt y pulsar Enter como pasos separados: un "\r" pegado al
|
||||||
|
// texto lo trata claude como newline literal, no como submit.
|
||||||
|
inputs := []string{"resume el README en 3 lineas", "\r"}
|
||||||
|
raw, _ := infra.PTYCaptureIdle(ctx, "claude", nil,
|
||||||
|
4*time.Second, // warmup: deja cargar la TUI
|
||||||
|
inputs, 600*time.Millisecond,
|
||||||
|
4*time.Second, // idle: corta tras 4s de silencio
|
||||||
|
60*time.Second) // maxDur: tope duro
|
||||||
|
screen := tui.VTRender(raw, 40, 120) // reconstruye el layout 2D
|
||||||
|
print(screen)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
La app `claude_extract` (`apps/claude_extract`) empaqueta exactamente este flujo como CLI, con
|
||||||
|
modos `screen|stream|raw`, `--exec` para pipear a otro proceso, y `--cwd` para saltar el diálogo
|
||||||
|
de arranque de claude. Es el consumidor de referencia del grupo.
|
||||||
|
|
||||||
|
La app `claude_pipe` (`apps/claude_pipe`) va un paso más allá: añade `parse_claude_tui_go_tui`
|
||||||
|
al final del pipeline para devolver la respuesta de claude **como dato** con el mismo shape que
|
||||||
|
`claude -p --output-format json` (`--format json|text|turns`). Es la alternativa "parsea la TUI"
|
||||||
|
a `claude -p`, para cuando se quiere expresamente ir a través de la TUI en vez del stream-json.
|
||||||
|
|
||||||
|
## Fronteras
|
||||||
|
|
||||||
|
- **No es `claude -p`**: este grupo captura la TUI real (lo que se ve). Para interacción programática
|
||||||
|
limpia con la CLI `claude`, usa `claude_stream_go_core` (`claude -p --output-format stream-json`).
|
||||||
|
- **Linux/Unix only**: PTY POSIX (`creack/pty`). No Windows.
|
||||||
|
- **Sin color**: `vt_render` reconstruye texto y layout, no atributos de color.
|
||||||
|
- **Idle es heurístico**: TUIs con render periódico (spinners, relojes) no disparan el idle y caen
|
||||||
|
al `maxDur`. Para `claude` el spinner se detiene al terminar la respuesta, así que corta bien.
|
||||||
|
- **Dimensiones fijas 40×120**: el render debe usar el mismo tamaño que la captura o el wrapping no
|
||||||
|
cuadra.
|
||||||
|
|
||||||
|
## Notas
|
||||||
|
|
||||||
|
- Las dos funciones de limpieza son **puras**; solo `pty_capture_idle` es impura (lanza procesos).
|
||||||
|
Puras en los bordes, impura en el centro de la captura.
|
||||||
|
- `pty_capture_idle` no fija el cwd del hijo: para controlarlo, cambia el cwd del proceso que la
|
||||||
|
invoca antes de llamarla (lo que hace `claude_extract --cwd`).
|
||||||
@@ -12,6 +12,7 @@ Filtro MCP: `mcp__registry__fn_search query="" tag="web-proxy"`.
|
|||||||
| [rotate_capture_flows_py_cybersecurity](../../python/functions/cybersecurity/rotate_capture_flows.md) | `mitmdump -s rotate_capture_flows.py --set rotate_min=N --set capture_dir=DIR` | Addon de mitmproxy que trocea las capturas en archivos `traffic-YYYYmmdd-HHMMSS.mitm` por ventanas de tiempo. Hace `flush()` por flujo, asi que la captura sobrevive a un `kill -9`. |
|
| [rotate_capture_flows_py_cybersecurity](../../python/functions/cybersecurity/rotate_capture_flows.md) | `mitmdump -s rotate_capture_flows.py --set rotate_min=N --set capture_dir=DIR` | Addon de mitmproxy que trocea las capturas en archivos `traffic-YYYYmmdd-HHMMSS.mitm` por ventanas de tiempo. Hace `flush()` por flujo, asi que la captura sobrevive a un `kill -9`. |
|
||||||
| [query_mitm_flows_bash_cybersecurity](../../bash/functions/cybersecurity/query_mitm_flows.md) | `query_mitm_flows <file_or_glob> [--filter EXPR] [--har OUT]` | Consulta capturas `.mitm` guardadas: vuelca los flujos que matchean un filtro de mitmproxy, o exporta a HAR. Acepta globs de varios archivos. |
|
| [query_mitm_flows_bash_cybersecurity](../../bash/functions/cybersecurity/query_mitm_flows.md) | `query_mitm_flows <file_or_glob> [--filter EXPR] [--har OUT]` | Consulta capturas `.mitm` guardadas: vuelca los flujos que matchean un filtro de mitmproxy, o exporta a HAR. Acepta globs de varios archivos. |
|
||||||
| [launch_chromium_proxy_bash_browser](../../bash/functions/browser/launch_chromium_proxy.md) | `launch_chromium_proxy [--proxy URL] [--profile DIR] [--url URL]` | Lanza Chromium apuntando al proxy con un perfil aislado, sin contaminar la sesion normal. Maneja el CA del proxy o cae a `--ignore-certificate-errors`. |
|
| [launch_chromium_proxy_bash_browser](../../bash/functions/browser/launch_chromium_proxy.md) | `launch_chromium_proxy [--proxy URL] [--profile DIR] [--url URL]` | Lanza Chromium apuntando al proxy con un perfil aislado, sin contaminar la sesion normal. Maneja el CA del proxy o cae a `--ignore-certificate-errors`. |
|
||||||
|
| [tee_anthropic_sse_py_cybersecurity](../../python/functions/cybersecurity/tee_anthropic_sse.md) | `mitmdump -s tee_anthropic_sse.py` | Addon mitmproxy que intercepta el SSE de `POST api.anthropic.com/v1/messages` (la respuesta del modelo de la CLI claude) y emite el texto exacto token a token como NDJSON. Filtra la respuesta principal (`has_tools`) de las auxiliares (titulo/clasificador en haiku). Strip de `Accept-Encoding` para ver el SSE sin comprimir. Lo consume `apps/claude_wire`. |
|
||||||
|
|
||||||
Complementa: `port_kill_bash_infra` (limpieza de puertos ocupados).
|
Complementa: `port_kill_bash_infra` (limpieza de puertos ocupados).
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,38 @@
|
|||||||
|
package core
|
||||||
|
|
||||||
|
import (
|
||||||
|
"regexp"
|
||||||
|
"strings"
|
||||||
|
)
|
||||||
|
|
||||||
|
// ansiCSI matches CSI sequences: ESC [ ... <final byte>
|
||||||
|
// Covers colors (SGR), cursor movement, erase, etc.
|
||||||
|
var ansiCSI = regexp.MustCompile(`\x1b\[[0-9;?]*[ -/]*[@-~]`)
|
||||||
|
|
||||||
|
// ansiOSC matches OSC sequences: ESC ] ... <BEL or ST>
|
||||||
|
// Used for window titles, hyperlinks, etc.
|
||||||
|
var ansiOSC = regexp.MustCompile(`\x1b\][^\x07\x1b]*(\x07|\x1b\\)`)
|
||||||
|
|
||||||
|
// ansiEsc matches other two-character escape sequences: ESC <char>
|
||||||
|
// Covers ESC c (reset), ESC ( B, ESC ) 0, etc.
|
||||||
|
var ansiEsc = regexp.MustCompile(`\x1b[@-Z\\-_]|\x1b[()][0-9A-Za-z]`)
|
||||||
|
|
||||||
|
// StripANSI removes ANSI/VT100 terminal escape sequences from s and filters
|
||||||
|
// non-printable control characters, preserving newlines (\n), tabs (\t) and
|
||||||
|
// carriage returns (\r).
|
||||||
|
func StripANSI(s string) string {
|
||||||
|
s = ansiCSI.ReplaceAllString(s, "")
|
||||||
|
s = ansiOSC.ReplaceAllString(s, "")
|
||||||
|
s = ansiEsc.ReplaceAllString(s, "")
|
||||||
|
return strings.Map(func(r rune) rune {
|
||||||
|
// Preserve printable characters, \n (0x0A), \t (0x09), \r (0x0D).
|
||||||
|
if r == '\n' || r == '\t' || r == '\r' {
|
||||||
|
return r
|
||||||
|
}
|
||||||
|
// Drop C0 control characters (0x00-0x1F) and DEL (0x7F).
|
||||||
|
if r < 0x20 || r == 0x7F {
|
||||||
|
return -1
|
||||||
|
}
|
||||||
|
return r
|
||||||
|
}, s)
|
||||||
|
}
|
||||||
@@ -0,0 +1,55 @@
|
|||||||
|
---
|
||||||
|
name: strip_ansi
|
||||||
|
kind: function
|
||||||
|
lang: go
|
||||||
|
domain: core
|
||||||
|
version: "1.0.0"
|
||||||
|
purity: pure
|
||||||
|
signature: "func StripANSI(s string) string"
|
||||||
|
description: "Elimina secuencias de escape ANSI/VT100 de un string y filtra caracteres de control no imprimibles, preservando \\n, \\t y \\r."
|
||||||
|
tags: ["terminal", "ansi", "string", "sanitize", "terminal-capture"]
|
||||||
|
uses_functions: []
|
||||||
|
uses_types: []
|
||||||
|
returns: []
|
||||||
|
returns_optional: false
|
||||||
|
error_type: ""
|
||||||
|
imports: ["regexp", "strings"]
|
||||||
|
params:
|
||||||
|
- name: s
|
||||||
|
desc: "String que puede contener secuencias de escape de terminal (CSI, OSC, escapes simples) y/o caracteres de control."
|
||||||
|
output: "String limpio: sin secuencias ANSI ni caracteres de control, preservando saltos de línea (\\n), tabulaciones (\\t) y retornos de carro (\\r)."
|
||||||
|
tested: true
|
||||||
|
tests:
|
||||||
|
- "golden: color SGR codes"
|
||||||
|
- "edge OSC titulo de ventana"
|
||||||
|
- "edge movimientos de cursor"
|
||||||
|
- "edge string sin escapes preserva saltos de linea"
|
||||||
|
- "edge string vacio"
|
||||||
|
- "edge preserva tabs"
|
||||||
|
test_file_path: "functions/core/strip_ansi_test.go"
|
||||||
|
file_path: "functions/core/strip_ansi.go"
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ejemplo
|
||||||
|
|
||||||
|
```go
|
||||||
|
// Limpiar output de terminal con color rojo
|
||||||
|
raw := "\x1b[31mError:\x1b[0m archivo no encontrado"
|
||||||
|
clean := core.StripANSI(raw)
|
||||||
|
// clean == "Error: archivo no encontrado"
|
||||||
|
|
||||||
|
// Limpiar título de ventana OSC
|
||||||
|
raw2 := "\x1b]0;mi titulo\x07contenido real"
|
||||||
|
clean2 := core.StripANSI(raw2)
|
||||||
|
// clean2 == "contenido real"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cuando usarla
|
||||||
|
|
||||||
|
Cuando captures output de un PTY/TUI/subprocess y necesites texto plano: antes de indexar logs con ANSI en un buscador, antes de difar output de terminal, o cuando muestres salida de comando en un contexto sin soporte de escape (UI web, archivo, base de datos).
|
||||||
|
|
||||||
|
## Gotchas
|
||||||
|
|
||||||
|
- Preserva `\n`, `\t` y `\r` a propósito: el output de terminales suele tener CRLF y tabulaciones con semántica propia.
|
||||||
|
- Cubre CSI, OSC y escapes simples de dos caracteres. Secuencias DCS o PM (rarísimas) no se eliminan; si las necesitas, añade una regex adicional antes de llamar a esta función.
|
||||||
|
- Las regexes están precompiladas a nivel de paquete: no hay coste de compilación por llamada.
|
||||||
@@ -0,0 +1,53 @@
|
|||||||
|
package core
|
||||||
|
|
||||||
|
import "testing"
|
||||||
|
|
||||||
|
func TestStripANSI(t *testing.T) {
|
||||||
|
t.Run("golden: color SGR codes", func(t *testing.T) {
|
||||||
|
got := StripANSI("\x1b[31mhola\x1b[0m mundo")
|
||||||
|
want := "hola mundo"
|
||||||
|
if got != want {
|
||||||
|
t.Errorf("got %q, want %q", got, want)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("edge OSC titulo de ventana", func(t *testing.T) {
|
||||||
|
got := StripANSI("\x1b]0;mi titulo\x07texto")
|
||||||
|
want := "texto"
|
||||||
|
if got != want {
|
||||||
|
t.Errorf("got %q, want %q", got, want)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("edge movimientos de cursor", func(t *testing.T) {
|
||||||
|
got := StripANSI("linea1\x1b[2K\x1b[1Glinea2")
|
||||||
|
want := "linea1linea2"
|
||||||
|
if got != want {
|
||||||
|
t.Errorf("got %q, want %q", got, want)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("edge string sin escapes preserva saltos de linea", func(t *testing.T) {
|
||||||
|
got := StripANSI("plano\ncon\nlineas")
|
||||||
|
want := "plano\ncon\nlineas"
|
||||||
|
if got != want {
|
||||||
|
t.Errorf("got %q, want %q", got, want)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("edge string vacio", func(t *testing.T) {
|
||||||
|
got := StripANSI("")
|
||||||
|
want := ""
|
||||||
|
if got != want {
|
||||||
|
t.Errorf("got %q, want %q", got, want)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("edge preserva tabs", func(t *testing.T) {
|
||||||
|
got := StripANSI("a\tb")
|
||||||
|
want := "a\tb"
|
||||||
|
if got != want {
|
||||||
|
t.Errorf("got %q, want %q", got, want)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
@@ -0,0 +1,23 @@
|
|||||||
|
package core
|
||||||
|
|
||||||
|
// PrefixDelta returns the portion of curr that follows the longest common
|
||||||
|
// prefix (LCP) shared with prev, comparing rune-by-rune to avoid splitting
|
||||||
|
// multi-byte characters.
|
||||||
|
//
|
||||||
|
// In the monotone streaming case (curr = prev + new), this returns exactly
|
||||||
|
// the new suffix. When the text diverges mid-way (reflow), it returns
|
||||||
|
// everything from the point of divergence to the end of curr.
|
||||||
|
func PrefixDelta(prev, curr string) string {
|
||||||
|
prevRunes := []rune(prev)
|
||||||
|
currRunes := []rune(curr)
|
||||||
|
|
||||||
|
common := 0
|
||||||
|
for common < len(prevRunes) && common < len(currRunes) {
|
||||||
|
if prevRunes[common] != currRunes[common] {
|
||||||
|
break
|
||||||
|
}
|
||||||
|
common++
|
||||||
|
}
|
||||||
|
|
||||||
|
return string(currRunes[common:])
|
||||||
|
}
|
||||||
@@ -0,0 +1,63 @@
|
|||||||
|
---
|
||||||
|
name: text_prefix_delta
|
||||||
|
kind: function
|
||||||
|
lang: go
|
||||||
|
domain: core
|
||||||
|
version: "1.0.0"
|
||||||
|
purity: pure
|
||||||
|
signature: "func PrefixDelta(prev, curr string) string"
|
||||||
|
description: "Calcula el delta de streaming entre dos versiones de un texto: devuelve la porción de curr que sigue al prefijo común más largo con prev, comparando runa a runa para no partir caracteres multibyte."
|
||||||
|
tags: [string, diff, streaming, delta, terminal-capture]
|
||||||
|
uses_functions: []
|
||||||
|
uses_types: []
|
||||||
|
returns: []
|
||||||
|
returns_optional: false
|
||||||
|
error_type: ""
|
||||||
|
imports: []
|
||||||
|
params:
|
||||||
|
- name: prev
|
||||||
|
desc: "Versión anterior del texto acumulativo (snapshot anterior del stream)."
|
||||||
|
- name: curr
|
||||||
|
desc: "Versión actual del texto acumulativo (snapshot actual, normalmente extiende a prev)."
|
||||||
|
output: "La porción de curr que sigue al prefijo común con prev (el 'delta' de streaming). Devuelve cadena vacía si curr no añade nada nuevo tras el prefijo común."
|
||||||
|
tested: true
|
||||||
|
tests:
|
||||||
|
- "monotono append normal"
|
||||||
|
- "prev vacio devuelve curr completo"
|
||||||
|
- "sin cambios devuelve vacio"
|
||||||
|
- "divergencia en medio devuelve desde divergencia"
|
||||||
|
- "curr mas corto que prev devuelve vacio"
|
||||||
|
- "multibyte cafe streaming"
|
||||||
|
- "multibyte prefijo parcial antes de acento"
|
||||||
|
- "ambos vacios devuelve vacio"
|
||||||
|
- "prev no vacio curr vacio devuelve vacio"
|
||||||
|
- "determinismo misma entrada misma salida"
|
||||||
|
test_file_path: "functions/core/text_prefix_delta_test.go"
|
||||||
|
file_path: "functions/core/text_prefix_delta.go"
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ejemplo
|
||||||
|
|
||||||
|
```go
|
||||||
|
// Bucle de streaming por snapshots acumulativos:
|
||||||
|
prev := ""
|
||||||
|
snapshots := []string{"Hola", "Hola, mun", "Hola, mundo!"}
|
||||||
|
|
||||||
|
for _, curr := range snapshots {
|
||||||
|
delta := PrefixDelta(prev, curr)
|
||||||
|
if delta != "" {
|
||||||
|
fmt.Print(delta) // emite solo la parte nueva
|
||||||
|
}
|
||||||
|
prev = curr
|
||||||
|
}
|
||||||
|
// Output: Hola, mundo!
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cuando usarla
|
||||||
|
|
||||||
|
Cuando hagas streaming por snapshots acumulativos y necesites emitir solo la parte nueva de cada snapshot. Caso típico: consumir `pty_capture_stream_go_infra` donde cada captura de la TUI es un snapshot que extiende al anterior, y quieres emitir eventos `text_delta` estilo SSE/streaming sin reenviar texto ya enviado.
|
||||||
|
|
||||||
|
## Gotchas
|
||||||
|
|
||||||
|
- Compara por prefijo común, no por diff completo. Si el texto cambia en medio (reflow, borrado, sobreescritura de terminal), el delta incluye todo desde el punto de divergencia hasta el final de curr — puede re-emitir texto ya visto. Adecuado para append monótono; en streaming de TUI con reflow es heurístico, no exacto.
|
||||||
|
- Trabaja sobre runas (no bytes) para no partir caracteres UTF-8 multibyte como 'é', '中', '→'. El offset de corte siempre cae en un límite de runa válido.
|
||||||
@@ -0,0 +1,87 @@
|
|||||||
|
package core
|
||||||
|
|
||||||
|
import "testing"
|
||||||
|
|
||||||
|
func TestPrefixDelta(t *testing.T) {
|
||||||
|
tests := []struct {
|
||||||
|
name string
|
||||||
|
prev string
|
||||||
|
curr string
|
||||||
|
want string
|
||||||
|
}{
|
||||||
|
{
|
||||||
|
name: "monotono append normal",
|
||||||
|
prev: "PON",
|
||||||
|
curr: "PONG",
|
||||||
|
want: "G",
|
||||||
|
},
|
||||||
|
{
|
||||||
|
name: "prev vacio devuelve curr completo",
|
||||||
|
prev: "",
|
||||||
|
curr: "abc",
|
||||||
|
want: "abc",
|
||||||
|
},
|
||||||
|
{
|
||||||
|
name: "sin cambios devuelve vacio",
|
||||||
|
prev: "abc",
|
||||||
|
curr: "abc",
|
||||||
|
want: "",
|
||||||
|
},
|
||||||
|
{
|
||||||
|
name: "divergencia en medio devuelve desde divergencia",
|
||||||
|
prev: "abc",
|
||||||
|
curr: "abXY",
|
||||||
|
want: "XY",
|
||||||
|
},
|
||||||
|
{
|
||||||
|
name: "curr mas corto que prev devuelve vacio",
|
||||||
|
prev: "abcdef",
|
||||||
|
curr: "abc",
|
||||||
|
want: "",
|
||||||
|
},
|
||||||
|
{
|
||||||
|
name: "multibyte cafe streaming",
|
||||||
|
prev: "café",
|
||||||
|
curr: "café con leche",
|
||||||
|
want: " con leche",
|
||||||
|
},
|
||||||
|
{
|
||||||
|
name: "multibyte prefijo parcial antes de acento",
|
||||||
|
prev: "ca",
|
||||||
|
curr: "café",
|
||||||
|
want: "fé",
|
||||||
|
},
|
||||||
|
{
|
||||||
|
name: "ambos vacios devuelve vacio",
|
||||||
|
prev: "",
|
||||||
|
curr: "",
|
||||||
|
want: "",
|
||||||
|
},
|
||||||
|
{
|
||||||
|
name: "prev no vacio curr vacio devuelve vacio",
|
||||||
|
prev: "hola",
|
||||||
|
curr: "",
|
||||||
|
want: "",
|
||||||
|
},
|
||||||
|
{
|
||||||
|
name: "determinismo misma entrada misma salida",
|
||||||
|
prev: "hello world",
|
||||||
|
curr: "hello world!",
|
||||||
|
want: "!",
|
||||||
|
},
|
||||||
|
}
|
||||||
|
|
||||||
|
for _, tc := range tests {
|
||||||
|
t.Run(tc.name, func(t *testing.T) {
|
||||||
|
got := PrefixDelta(tc.prev, tc.curr)
|
||||||
|
if got != tc.want {
|
||||||
|
t.Errorf("PrefixDelta(%q, %q) = %q, want %q", tc.prev, tc.curr, got, tc.want)
|
||||||
|
}
|
||||||
|
// Verificar determinismo: segunda llamada produce el mismo resultado.
|
||||||
|
got2 := PrefixDelta(tc.prev, tc.curr)
|
||||||
|
if got != got2 {
|
||||||
|
t.Errorf("no determinista: primera=%q segunda=%q", got, got2)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,304 @@
|
|||||||
|
package cybersecurity
|
||||||
|
|
||||||
|
import (
|
||||||
|
"bytes"
|
||||||
|
"testing"
|
||||||
|
)
|
||||||
|
|
||||||
|
// --- GenerateIdentity ---
|
||||||
|
|
||||||
|
func TestGenerateIdentity(t *testing.T) {
|
||||||
|
t.Run("genera keypairs con longitudes correctas", func(t *testing.T) {
|
||||||
|
id, err := GenerateIdentity()
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("GenerateIdentity() error = %v", err)
|
||||||
|
}
|
||||||
|
if len(id.SignPub) != 32 {
|
||||||
|
t.Errorf("SignPub len = %d, want 32", len(id.SignPub))
|
||||||
|
}
|
||||||
|
if len(id.SignPriv) != 64 {
|
||||||
|
t.Errorf("SignPriv len = %d, want 64", len(id.SignPriv))
|
||||||
|
}
|
||||||
|
if len(id.KexPub) != 32 {
|
||||||
|
t.Errorf("KexPub len = %d, want 32", len(id.KexPub))
|
||||||
|
}
|
||||||
|
if len(id.KexPriv) != 32 {
|
||||||
|
t.Errorf("KexPriv len = %d, want 32", len(id.KexPriv))
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("dos llamadas producen identidades distintas", func(t *testing.T) {
|
||||||
|
id1, err1 := GenerateIdentity()
|
||||||
|
id2, err2 := GenerateIdentity()
|
||||||
|
if err1 != nil || err2 != nil {
|
||||||
|
t.Fatal("GenerateIdentity() error inesperado")
|
||||||
|
}
|
||||||
|
if bytes.Equal(id1.SignPub, id2.SignPub) {
|
||||||
|
t.Error("SignPub idénticos en dos identidades distintas")
|
||||||
|
}
|
||||||
|
if bytes.Equal(id1.KexPub, id2.KexPub) {
|
||||||
|
t.Error("KexPub idénticos en dos identidades distintas")
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- SealAEAD / OpenAEAD ---
|
||||||
|
|
||||||
|
func TestSealOpenAEAD(t *testing.T) {
|
||||||
|
key := make([]byte, 32)
|
||||||
|
for i := range key {
|
||||||
|
key[i] = byte(i + 1)
|
||||||
|
}
|
||||||
|
plaintext := []byte("mensaje secreto del bus de mensajería")
|
||||||
|
aad := []byte("room:sala-general")
|
||||||
|
|
||||||
|
t.Run("round-trip con aad", func(t *testing.T) {
|
||||||
|
nonce, ct, err := SealAEAD(key, plaintext, aad)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("SealAEAD error = %v", err)
|
||||||
|
}
|
||||||
|
got, err := OpenAEAD(key, nonce, ct, aad)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("OpenAEAD error = %v", err)
|
||||||
|
}
|
||||||
|
if !bytes.Equal(got, plaintext) {
|
||||||
|
t.Errorf("got %q, want %q", got, plaintext)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("round-trip sin aad (nil)", func(t *testing.T) {
|
||||||
|
nonce, ct, err := SealAEAD(key, plaintext, nil)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("SealAEAD error = %v", err)
|
||||||
|
}
|
||||||
|
got, err := OpenAEAD(key, nonce, ct, nil)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("OpenAEAD error = %v", err)
|
||||||
|
}
|
||||||
|
if !bytes.Equal(got, plaintext) {
|
||||||
|
t.Errorf("got %q, want %q", got, plaintext)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("error con clave de longitud incorrecta", func(t *testing.T) {
|
||||||
|
_, _, err := SealAEAD(key[:16], plaintext, nil)
|
||||||
|
if err == nil {
|
||||||
|
t.Error("esperaba error con clave de 16 bytes, got nil")
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("error de autenticacion con ciphertext modificado", func(t *testing.T) {
|
||||||
|
nonce, ct, err := SealAEAD(key, plaintext, aad)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("SealAEAD error = %v", err)
|
||||||
|
}
|
||||||
|
ct[0] ^= 0xFF // corromper el primer byte
|
||||||
|
_, err = OpenAEAD(key, nonce, ct, aad)
|
||||||
|
if err == nil {
|
||||||
|
t.Error("esperaba error de autenticación con ciphertext corrupto, got nil")
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("error de autenticacion con aad distinto", func(t *testing.T) {
|
||||||
|
nonce, ct, err := SealAEAD(key, plaintext, aad)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("SealAEAD error = %v", err)
|
||||||
|
}
|
||||||
|
_, err = OpenAEAD(key, nonce, ct, []byte("room:otra-sala"))
|
||||||
|
if err == nil {
|
||||||
|
t.Error("esperaba error de autenticación con aad distinto, got nil")
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("nonces distintos en llamadas sucesivas", func(t *testing.T) {
|
||||||
|
n1, _, err1 := SealAEAD(key, plaintext, nil)
|
||||||
|
n2, _, err2 := SealAEAD(key, plaintext, nil)
|
||||||
|
if err1 != nil || err2 != nil {
|
||||||
|
t.Fatal("SealAEAD error inesperado")
|
||||||
|
}
|
||||||
|
if bytes.Equal(n1, n2) {
|
||||||
|
t.Error("nonces iguales en dos llamadas sucesivas (no aleatorios)")
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- SealKeyBox / OpenKeyBox ---
|
||||||
|
|
||||||
|
func TestSealOpenKeyBox(t *testing.T) {
|
||||||
|
t.Run("round-trip con identidad generada", func(t *testing.T) {
|
||||||
|
id, err := GenerateIdentity()
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("GenerateIdentity error = %v", err)
|
||||||
|
}
|
||||||
|
roomKey := make([]byte, 32)
|
||||||
|
for i := range roomKey {
|
||||||
|
roomKey[i] = byte(i + 42)
|
||||||
|
}
|
||||||
|
|
||||||
|
sealed, err := SealKeyBox(id.KexPub, roomKey)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("SealKeyBox error = %v", err)
|
||||||
|
}
|
||||||
|
|
||||||
|
opened, err := OpenKeyBox(id.KexPub, id.KexPriv, sealed)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("OpenKeyBox error = %v", err)
|
||||||
|
}
|
||||||
|
if !bytes.Equal(opened, roomKey) {
|
||||||
|
t.Errorf("got %x, want %x", opened, roomKey)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("error con recipientKexPub de longitud incorrecta", func(t *testing.T) {
|
||||||
|
_, err := SealKeyBox(make([]byte, 16), []byte("secret"))
|
||||||
|
if err == nil {
|
||||||
|
t.Error("esperaba error con kexPub de 16 bytes, got nil")
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("error al abrir con clave equivocada", func(t *testing.T) {
|
||||||
|
id, _ := GenerateIdentity()
|
||||||
|
other, _ := GenerateIdentity()
|
||||||
|
sealed, err := SealKeyBox(id.KexPub, []byte("roomkey"))
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("SealKeyBox error = %v", err)
|
||||||
|
}
|
||||||
|
_, err = OpenKeyBox(other.KexPub, other.KexPriv, sealed)
|
||||||
|
if err == nil {
|
||||||
|
t.Error("esperaba error al abrir con keypair distinto, got nil")
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("error con mensaje truncado", func(t *testing.T) {
|
||||||
|
id, _ := GenerateIdentity()
|
||||||
|
_, err := OpenKeyBox(id.KexPub, id.KexPriv, []byte("corto"))
|
||||||
|
if err == nil {
|
||||||
|
t.Error("esperaba error con sealedMsg truncado, got nil")
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- SignEd25519 / VerifyEd25519 ---
|
||||||
|
|
||||||
|
func TestSignVerifyEd25519(t *testing.T) {
|
||||||
|
t.Run("firma y verificacion exitosa", func(t *testing.T) {
|
||||||
|
id, err := GenerateIdentity()
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("GenerateIdentity error = %v", err)
|
||||||
|
}
|
||||||
|
msg := []byte("evento:room_key_rotation:v2")
|
||||||
|
sig := SignEd25519(id.SignPriv, msg)
|
||||||
|
if len(sig) != 64 {
|
||||||
|
t.Errorf("sig len = %d, want 64", len(sig))
|
||||||
|
}
|
||||||
|
if !VerifyEd25519(id.SignPub, msg, sig) {
|
||||||
|
t.Error("VerifyEd25519 devolvió false para firma válida")
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("firma es determinista (misma entrada, misma firma)", func(t *testing.T) {
|
||||||
|
id, _ := GenerateIdentity()
|
||||||
|
msg := []byte("determinismo criptografico")
|
||||||
|
sig1 := SignEd25519(id.SignPriv, msg)
|
||||||
|
sig2 := SignEd25519(id.SignPriv, msg)
|
||||||
|
if !bytes.Equal(sig1, sig2) {
|
||||||
|
t.Error("Ed25519 debe ser determinista: mismas entradas deben producir misma firma")
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("falla con mensaje modificado", func(t *testing.T) {
|
||||||
|
id, _ := GenerateIdentity()
|
||||||
|
msg := []byte("mensaje original")
|
||||||
|
sig := SignEd25519(id.SignPriv, msg)
|
||||||
|
modified := []byte("mensaje modificado")
|
||||||
|
if VerifyEd25519(id.SignPub, modified, sig) {
|
||||||
|
t.Error("VerifyEd25519 devolvió true para mensaje modificado")
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("falla con clave publica incorrecta", func(t *testing.T) {
|
||||||
|
id1, _ := GenerateIdentity()
|
||||||
|
id2, _ := GenerateIdentity()
|
||||||
|
msg := []byte("autenticidad del remitente")
|
||||||
|
sig := SignEd25519(id1.SignPriv, msg)
|
||||||
|
if VerifyEd25519(id2.SignPub, msg, sig) {
|
||||||
|
t.Error("VerifyEd25519 devolvió true con clave pública de otra identidad")
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("falla con firma corrupta", func(t *testing.T) {
|
||||||
|
id, _ := GenerateIdentity()
|
||||||
|
msg := []byte("integridad")
|
||||||
|
sig := SignEd25519(id.SignPriv, msg)
|
||||||
|
sig[0] ^= 0xFF
|
||||||
|
if VerifyEd25519(id.SignPub, msg, sig) {
|
||||||
|
t.Error("VerifyEd25519 devolvió true con firma corrupta")
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- Integración: flujo completo megolm-reducido ---
|
||||||
|
|
||||||
|
func TestE2EMessagingFlow(t *testing.T) {
|
||||||
|
t.Run("flujo completo: generar identidad, distribuir clave de sala, cifrar y firmar mensaje", func(t *testing.T) {
|
||||||
|
// Servidor genera identidad
|
||||||
|
server, err := GenerateIdentity()
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("GenerateIdentity server: %v", err)
|
||||||
|
}
|
||||||
|
// Usuario genera identidad
|
||||||
|
user, err := GenerateIdentity()
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("GenerateIdentity user: %v", err)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Servidor genera clave de sala y la distribuye al usuario cifrada con su KexPub
|
||||||
|
roomKey := make([]byte, 32)
|
||||||
|
for i := range roomKey {
|
||||||
|
roomKey[i] = byte(i)
|
||||||
|
}
|
||||||
|
sealedKey, err := SealKeyBox(user.KexPub, roomKey)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("SealKeyBox: %v", err)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Usuario desella la clave de sala
|
||||||
|
gotRoomKey, err := OpenKeyBox(user.KexPub, user.KexPriv, sealedKey)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("OpenKeyBox: %v", err)
|
||||||
|
}
|
||||||
|
if !bytes.Equal(gotRoomKey, roomKey) {
|
||||||
|
t.Fatal("clave de sala distribuida no coincide")
|
||||||
|
}
|
||||||
|
|
||||||
|
// Usuario cifra un mensaje con la clave de sala
|
||||||
|
plainMsg := []byte("hola sala, este es mi primer mensaje cifrado e2e")
|
||||||
|
aad := []byte("room:sala-secreta:seq:1")
|
||||||
|
nonce, ct, err := SealAEAD(gotRoomKey, plainMsg, aad)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("SealAEAD: %v", err)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Usuario firma el ciphertext para autenticación del remitente
|
||||||
|
sig := SignEd25519(user.SignPriv, ct)
|
||||||
|
|
||||||
|
// Receptor verifica firma del remitente
|
||||||
|
if !VerifyEd25519(user.SignPub, ct, sig) {
|
||||||
|
t.Fatal("verificación de firma del remitente falló")
|
||||||
|
}
|
||||||
|
|
||||||
|
// Receptor descifra el mensaje
|
||||||
|
decrypted, err := OpenAEAD(gotRoomKey, nonce, ct, aad)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("OpenAEAD: %v", err)
|
||||||
|
}
|
||||||
|
if !bytes.Equal(decrypted, plainMsg) {
|
||||||
|
t.Errorf("mensaje descifrado %q != original %q", decrypted, plainMsg)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Servidor tiene distinta identidad que el usuario (las claves no se confunden)
|
||||||
|
if bytes.Equal(server.SignPub, user.SignPub) {
|
||||||
|
t.Error("server y user tienen la misma clave pública de firma")
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
@@ -0,0 +1,40 @@
|
|||||||
|
package cybersecurity
|
||||||
|
|
||||||
|
import (
|
||||||
|
"crypto/ed25519"
|
||||||
|
"crypto/rand"
|
||||||
|
|
||||||
|
"golang.org/x/crypto/nacl/box"
|
||||||
|
)
|
||||||
|
|
||||||
|
// Identity holds a dual keypair for a messaging participant:
|
||||||
|
// an Ed25519 keypair for signing and a X25519 keypair for key exchange.
|
||||||
|
type Identity struct {
|
||||||
|
SignPub []byte // Ed25519 public key (32 bytes)
|
||||||
|
SignPriv []byte // Ed25519 private key (64 bytes)
|
||||||
|
KexPub []byte // X25519 public key (32 bytes)
|
||||||
|
KexPriv []byte // X25519 private key (32 bytes)
|
||||||
|
}
|
||||||
|
|
||||||
|
// GenerateIdentity creates a new Identity with freshly generated Ed25519 and X25519 keypairs.
|
||||||
|
// Ed25519 keys are used for signing; X25519 keys for key exchange (sealed box).
|
||||||
|
func GenerateIdentity() (Identity, error) {
|
||||||
|
// Ed25519 keypair for message signing
|
||||||
|
signPub, signPriv, err := ed25519.GenerateKey(rand.Reader)
|
||||||
|
if err != nil {
|
||||||
|
return Identity{}, err
|
||||||
|
}
|
||||||
|
|
||||||
|
// X25519 keypair for key exchange (nacl/box uses Curve25519 internally)
|
||||||
|
kexPub, kexPriv, err := box.GenerateKey(rand.Reader)
|
||||||
|
if err != nil {
|
||||||
|
return Identity{}, err
|
||||||
|
}
|
||||||
|
|
||||||
|
return Identity{
|
||||||
|
SignPub: []byte(signPub),
|
||||||
|
SignPriv: []byte(signPriv),
|
||||||
|
KexPub: kexPub[:],
|
||||||
|
KexPriv: kexPriv[:],
|
||||||
|
}, nil
|
||||||
|
}
|
||||||
@@ -0,0 +1,53 @@
|
|||||||
|
---
|
||||||
|
name: generate_identity
|
||||||
|
kind: function
|
||||||
|
lang: go
|
||||||
|
domain: cybersecurity
|
||||||
|
version: "1.0.0"
|
||||||
|
purity: impure
|
||||||
|
signature: "func GenerateIdentity() (Identity, error)"
|
||||||
|
description: "Genera una identidad criptográfica dual con un par Ed25519 (firma) y un par X25519 (intercambio de claves). Punto de entrada obligatorio para cualquier participante en el bus de mensajería cifrado."
|
||||||
|
tags: [messaging, e2e-crypto, crypto, identity, ed25519, x25519, keygen, e2e-messaging]
|
||||||
|
uses_functions: []
|
||||||
|
uses_types: []
|
||||||
|
returns: []
|
||||||
|
returns_optional: false
|
||||||
|
error_type: "error_go_core"
|
||||||
|
imports:
|
||||||
|
- crypto/ed25519
|
||||||
|
- crypto/rand
|
||||||
|
- golang.org/x/crypto/nacl/box
|
||||||
|
params:
|
||||||
|
- name: "(ninguno)"
|
||||||
|
desc: "Sin parámetros. Usa crypto/rand como fuente de entropía del sistema."
|
||||||
|
output: "Identity{SignPub []byte, SignPriv []byte, KexPub []byte, KexPriv []byte} o error si falla el RNG del sistema."
|
||||||
|
tested: true
|
||||||
|
tests:
|
||||||
|
- "genera keypairs con longitudes correctas"
|
||||||
|
- "dos llamadas producen identidades distintas"
|
||||||
|
test_file_path: "functions/cybersecurity/e2e_messaging_crypto_test.go"
|
||||||
|
file_path: "functions/cybersecurity/generate_identity.go"
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ejemplo
|
||||||
|
|
||||||
|
```go
|
||||||
|
id, err := cybersecurity.GenerateIdentity()
|
||||||
|
if err != nil {
|
||||||
|
log.Fatal(err)
|
||||||
|
}
|
||||||
|
// id.SignPub / id.SignPriv — par Ed25519 para firmar mensajes
|
||||||
|
// id.KexPub / id.KexPriv — par X25519 para recibir claves de sala cifradas
|
||||||
|
fmt.Printf("identity pub(sign)=%x pub(kex)=%x\n", id.SignPub, id.KexPub)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cuando usarla
|
||||||
|
|
||||||
|
Al registrar un nuevo participante en el bus de mensajería: llama GenerateIdentity una sola vez por dispositivo/sesión, persiste los bytes de las cuatro claves de forma segura, y publica `SignPub` + `KexPub` en el directorio de participantes.
|
||||||
|
|
||||||
|
## Gotchas
|
||||||
|
|
||||||
|
- La función depende de `crypto/rand`; en entornos con entropía insuficiente (contenedores recién arrancados) puede bloquearse brevemente.
|
||||||
|
- `SignPriv` tiene 64 bytes (no 32): Ed25519 concatena seed (32) + clave pública (32) internamente. No truncar.
|
||||||
|
- `KexPub`/`KexPriv` son exactamente 32 bytes (Curve25519). Pasar exactamente esos slices a `SealKeyBox`/`OpenKeyBox`.
|
||||||
|
- Nunca reutilizar una identidad entre dispositivos distintos del mismo usuario sin un protocolo de clonado seguro.
|
||||||
@@ -0,0 +1,29 @@
|
|||||||
|
package cybersecurity
|
||||||
|
|
||||||
|
import (
|
||||||
|
"fmt"
|
||||||
|
|
||||||
|
"golang.org/x/crypto/chacha20poly1305"
|
||||||
|
)
|
||||||
|
|
||||||
|
// OpenAEAD decrypts a ciphertext produced by SealAEAD using ChaCha20-Poly1305.
|
||||||
|
// key must be exactly 32 bytes. nonce must match the one returned by SealAEAD.
|
||||||
|
// aad must match what was passed to SealAEAD (can be nil).
|
||||||
|
// Returns an error if authentication fails (tampered ciphertext, wrong key, or wrong aad).
|
||||||
|
func OpenAEAD(key, nonce, ciphertext, aad []byte) ([]byte, error) {
|
||||||
|
if len(key) != chacha20poly1305.KeySize {
|
||||||
|
return nil, fmt.Errorf("open_aead: key must be %d bytes, got %d", chacha20poly1305.KeySize, len(key))
|
||||||
|
}
|
||||||
|
|
||||||
|
aead, err := chacha20poly1305.New(key)
|
||||||
|
if err != nil {
|
||||||
|
return nil, fmt.Errorf("open_aead: create cipher: %w", err)
|
||||||
|
}
|
||||||
|
|
||||||
|
plaintext, err := aead.Open(nil, nonce, ciphertext, aad)
|
||||||
|
if err != nil {
|
||||||
|
return nil, fmt.Errorf("open_aead: authentication failed: %w", err)
|
||||||
|
}
|
||||||
|
|
||||||
|
return plaintext, nil
|
||||||
|
}
|
||||||
@@ -0,0 +1,62 @@
|
|||||||
|
---
|
||||||
|
name: open_aead
|
||||||
|
kind: function
|
||||||
|
lang: go
|
||||||
|
domain: cybersecurity
|
||||||
|
version: "1.0.0"
|
||||||
|
purity: impure
|
||||||
|
signature: "func OpenAEAD(key, nonce, ciphertext, aad []byte) ([]byte, error)"
|
||||||
|
description: "Descifra y autentica un ciphertext producido por SealAEAD usando ChaCha20-Poly1305. Devuelve error explícito si la autenticación falla (ciphertext alterado, clave incorrecta o AAD distinto)."
|
||||||
|
tags: [messaging, e2e-crypto, crypto, aead, chacha20poly1305, symmetric, e2e-messaging]
|
||||||
|
uses_functions: []
|
||||||
|
uses_types: []
|
||||||
|
returns: []
|
||||||
|
returns_optional: false
|
||||||
|
error_type: "error_go_core"
|
||||||
|
imports:
|
||||||
|
- golang.org/x/crypto/chacha20poly1305
|
||||||
|
params:
|
||||||
|
- name: key
|
||||||
|
desc: "Clave simétrica de exactamente 32 bytes. Debe ser la misma usada en SealAEAD."
|
||||||
|
- name: nonce
|
||||||
|
desc: "Nonce de 12 bytes devuelto por SealAEAD. Debe transmitirse junto al ciphertext."
|
||||||
|
- name: ciphertext
|
||||||
|
desc: "Ciphertext producido por SealAEAD (incluye los 16 bytes del tag Poly1305)."
|
||||||
|
- name: aad
|
||||||
|
desc: "Datos autenticados adicionales. Debe ser idéntico al aad usado en SealAEAD, o nil si se pasó nil."
|
||||||
|
output: "Plaintext descifrado, o error si la autenticación falla o la clave tiene longitud incorrecta."
|
||||||
|
tested: true
|
||||||
|
tests:
|
||||||
|
- "round-trip con aad"
|
||||||
|
- "round-trip sin aad (nil)"
|
||||||
|
- "error con clave de longitud incorrecta"
|
||||||
|
- "error de autenticacion con ciphertext modificado"
|
||||||
|
- "error de autenticacion con aad distinto"
|
||||||
|
- "nonces distintos en llamadas sucesivas"
|
||||||
|
test_file_path: "functions/cybersecurity/e2e_messaging_crypto_test.go"
|
||||||
|
file_path: "functions/cybersecurity/open_aead.go"
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ejemplo
|
||||||
|
|
||||||
|
```go
|
||||||
|
// nonce y ct vienen de SealAEAD; aad debe reconstruirse igual
|
||||||
|
aad := []byte("room:sala-general:seq:42")
|
||||||
|
plaintext, err := cybersecurity.OpenAEAD(key, nonce, ct, aad)
|
||||||
|
if err != nil {
|
||||||
|
// mensaje alterado, clave incorrecta o aad distinto — descartar
|
||||||
|
log.Printf("autenticación fallida: %v", err)
|
||||||
|
return
|
||||||
|
}
|
||||||
|
fmt.Printf("mensaje: %s\n", plaintext)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cuando usarla
|
||||||
|
|
||||||
|
Al recibir un mensaje del bus: después de resolver la room key con OpenKeyBox, llama OpenAEAD para descifrar y verificar integridad. Si devuelve error, el mensaje llegó corrupto o fue alterado en tránsito — descartar siempre, nunca procesar plaintext parcial.
|
||||||
|
|
||||||
|
## Gotchas
|
||||||
|
|
||||||
|
- El error no distingue entre "clave incorrecta", "nonce incorrecto" y "ciphertext alterado": todos devuelven el mismo error de autenticación por diseño (evita oráculos de padding).
|
||||||
|
- Si el ciphertext tiene menos de 16 bytes, la función devuelve error antes de intentar descifrar.
|
||||||
|
- El aad debe ser reconstructible por el receptor de forma independiente (no viaja en el mensaje cifrado).
|
||||||
@@ -0,0 +1,32 @@
|
|||||||
|
package cybersecurity
|
||||||
|
|
||||||
|
import (
|
||||||
|
"fmt"
|
||||||
|
|
||||||
|
"golang.org/x/crypto/nacl/box"
|
||||||
|
)
|
||||||
|
|
||||||
|
// OpenKeyBox decrypts a sealed box produced by SealKeyBox using the recipient's X25519 keypair.
|
||||||
|
// kexPub and kexPriv must each be exactly 32 bytes and correspond to the public key
|
||||||
|
// passed to SealKeyBox as recipientKexPub.
|
||||||
|
// Returns an error if decryption or authentication fails.
|
||||||
|
func OpenKeyBox(kexPub, kexPriv, sealedMsg []byte) ([]byte, error) {
|
||||||
|
if len(kexPub) != 32 {
|
||||||
|
return nil, fmt.Errorf("open_key_box: kexPub must be 32 bytes, got %d", len(kexPub))
|
||||||
|
}
|
||||||
|
if len(kexPriv) != 32 {
|
||||||
|
return nil, fmt.Errorf("open_key_box: kexPriv must be 32 bytes, got %d", len(kexPriv))
|
||||||
|
}
|
||||||
|
|
||||||
|
var pub [32]byte
|
||||||
|
var priv [32]byte
|
||||||
|
copy(pub[:], kexPub)
|
||||||
|
copy(priv[:], kexPriv)
|
||||||
|
|
||||||
|
plaintext, ok := box.OpenAnonymous(nil, sealedMsg, &pub, &priv)
|
||||||
|
if !ok {
|
||||||
|
return nil, fmt.Errorf("open_key_box: decryption failed (authentication error or corrupted message)")
|
||||||
|
}
|
||||||
|
|
||||||
|
return plaintext, nil
|
||||||
|
}
|
||||||
@@ -0,0 +1,58 @@
|
|||||||
|
---
|
||||||
|
name: open_key_box
|
||||||
|
kind: function
|
||||||
|
lang: go
|
||||||
|
domain: cybersecurity
|
||||||
|
version: "1.0.0"
|
||||||
|
purity: impure
|
||||||
|
signature: "func OpenKeyBox(kexPub, kexPriv, sealedMsg []byte) ([]byte, error)"
|
||||||
|
description: "Descifra un sealed box anónimo producido por SealKeyBox usando el par X25519 del destinatario. Devuelve error si la autenticación falla o el mensaje está corrupto."
|
||||||
|
tags: [messaging, e2e-crypto, crypto, nacl, x25519, sealed-box, key-distribution, e2e-messaging]
|
||||||
|
uses_functions: []
|
||||||
|
uses_types: []
|
||||||
|
returns: []
|
||||||
|
returns_optional: false
|
||||||
|
error_type: "error_go_core"
|
||||||
|
imports:
|
||||||
|
- golang.org/x/crypto/nacl/box
|
||||||
|
params:
|
||||||
|
- name: kexPub
|
||||||
|
desc: "Clave pública X25519 del destinatario (exactamente 32 bytes). Debe coincidir con la usada en SealKeyBox."
|
||||||
|
- name: kexPriv
|
||||||
|
desc: "Clave privada X25519 del destinatario (exactamente 32 bytes). Viene del campo KexPriv de su Identity."
|
||||||
|
- name: sealedMsg
|
||||||
|
desc: "Sealed box producido por SealKeyBox. Mínimo 48 bytes (32 overhead ephemeral + 16 tag)."
|
||||||
|
output: "Secreto descifrado (ej. room key de 32 bytes), o error si la autenticación falla, el par de claves no coincide, o el mensaje está truncado."
|
||||||
|
tested: true
|
||||||
|
tests:
|
||||||
|
- "round-trip con identidad generada"
|
||||||
|
- "error con recipientKexPub de longitud incorrecta"
|
||||||
|
- "error al abrir con clave equivocada"
|
||||||
|
- "error con mensaje truncado"
|
||||||
|
test_file_path: "functions/cybersecurity/e2e_messaging_crypto_test.go"
|
||||||
|
file_path: "functions/cybersecurity/open_key_box.go"
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ejemplo
|
||||||
|
|
||||||
|
```go
|
||||||
|
// Receptor obtiene su Identity del almacén seguro
|
||||||
|
id, _ := loadIdentityFromSecureStorage()
|
||||||
|
roomKey, err := cybersecurity.OpenKeyBox(id.KexPub, id.KexPriv, sealedMsgFromServer)
|
||||||
|
if err != nil {
|
||||||
|
log.Printf("no se pudo abrir la room key: %v", err)
|
||||||
|
return
|
||||||
|
}
|
||||||
|
// roomKey lista para usar en SealAEAD / OpenAEAD
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cuando usarla
|
||||||
|
|
||||||
|
Al recibir una distribución de clave de sala del servidor: llama OpenKeyBox con el par X25519 propio para recuperar la room key simétrica. Después de obtenerla, úsala en OpenAEAD para descifrar los mensajes de esa sala.
|
||||||
|
|
||||||
|
## Gotchas
|
||||||
|
|
||||||
|
- El error no distingue entre "clave incorrecta" y "mensaje corrupto" por diseño de seguridad.
|
||||||
|
- Si `sealedMsg` tiene menos de 48 bytes (overhead mínimo del sealed box), la función devuelve error sin intentar descifrar.
|
||||||
|
- `kexPub` y `kexPriv` deben ser el par correspondiente: pasar la pubkey de otro usuario con la privkey propia siempre falla.
|
||||||
|
- La room key recuperada es sensible: no logearla ni incluirla en mensajes de error.
|
||||||
@@ -0,0 +1,31 @@
|
|||||||
|
package cybersecurity
|
||||||
|
|
||||||
|
import (
|
||||||
|
"crypto/rand"
|
||||||
|
"fmt"
|
||||||
|
"io"
|
||||||
|
|
||||||
|
"golang.org/x/crypto/chacha20poly1305"
|
||||||
|
)
|
||||||
|
|
||||||
|
// SealAEAD encrypts plaintext with ChaCha20-Poly1305, returning a random nonce and ciphertext.
|
||||||
|
// key must be exactly 32 bytes. aad (additional authenticated data) may be nil.
|
||||||
|
// The returned nonce must be stored alongside the ciphertext and passed to OpenAEAD.
|
||||||
|
func SealAEAD(key, plaintext, aad []byte) (nonce, ciphertext []byte, err error) {
|
||||||
|
if len(key) != chacha20poly1305.KeySize {
|
||||||
|
return nil, nil, fmt.Errorf("seal_aead: key must be %d bytes, got %d", chacha20poly1305.KeySize, len(key))
|
||||||
|
}
|
||||||
|
|
||||||
|
aead, err := chacha20poly1305.New(key)
|
||||||
|
if err != nil {
|
||||||
|
return nil, nil, fmt.Errorf("seal_aead: create cipher: %w", err)
|
||||||
|
}
|
||||||
|
|
||||||
|
nonce = make([]byte, aead.NonceSize())
|
||||||
|
if _, err = io.ReadFull(rand.Reader, nonce); err != nil {
|
||||||
|
return nil, nil, fmt.Errorf("seal_aead: generate nonce: %w", err)
|
||||||
|
}
|
||||||
|
|
||||||
|
ciphertext = aead.Seal(nil, nonce, plaintext, aad)
|
||||||
|
return nonce, ciphertext, nil
|
||||||
|
}
|
||||||
@@ -0,0 +1,60 @@
|
|||||||
|
---
|
||||||
|
name: seal_aead
|
||||||
|
kind: function
|
||||||
|
lang: go
|
||||||
|
domain: cybersecurity
|
||||||
|
version: "1.0.0"
|
||||||
|
purity: impure
|
||||||
|
signature: "func SealAEAD(key, plaintext, aad []byte) (nonce, ciphertext []byte, err error)"
|
||||||
|
description: "Cifra plaintext con ChaCha20-Poly1305 usando una clave simétrica de 32 bytes. Genera un nonce aleatorio por llamada. Admite datos autenticados adicionales (AAD) para vincular contexto al cifrado sin cifrarlo."
|
||||||
|
tags: [messaging, e2e-crypto, crypto, aead, chacha20poly1305, symmetric, e2e-messaging]
|
||||||
|
uses_functions: []
|
||||||
|
uses_types: []
|
||||||
|
returns: []
|
||||||
|
returns_optional: false
|
||||||
|
error_type: "error_go_core"
|
||||||
|
imports:
|
||||||
|
- crypto/rand
|
||||||
|
- golang.org/x/crypto/chacha20poly1305
|
||||||
|
params:
|
||||||
|
- name: key
|
||||||
|
desc: "Clave simétrica de exactamente 32 bytes (256 bits). Típicamente la room key distribuida con SealKeyBox."
|
||||||
|
- name: plaintext
|
||||||
|
desc: "Bytes a cifrar. Puede ser vacío."
|
||||||
|
- name: aad
|
||||||
|
desc: "Datos autenticados adicionales (AAD): se autentican pero no se cifran. Útil para room ID, número de secuencia, etc. Puede ser nil."
|
||||||
|
output: "nonce (12 bytes aleatorios), ciphertext (plaintext cifrado + 16 bytes de tag Poly1305), o error si la clave tiene longitud incorrecta o falla el RNG."
|
||||||
|
tested: true
|
||||||
|
tests:
|
||||||
|
- "round-trip con aad"
|
||||||
|
- "round-trip sin aad (nil)"
|
||||||
|
- "error con clave de longitud incorrecta"
|
||||||
|
- "error de autenticacion con ciphertext modificado"
|
||||||
|
- "error de autenticacion con aad distinto"
|
||||||
|
- "nonces distintos en llamadas sucesivas"
|
||||||
|
test_file_path: "functions/cybersecurity/e2e_messaging_crypto_test.go"
|
||||||
|
file_path: "functions/cybersecurity/seal_aead.go"
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ejemplo
|
||||||
|
|
||||||
|
```go
|
||||||
|
key := make([]byte, 32) // en producción: room key distribuida con SealKeyBox
|
||||||
|
aad := []byte("room:sala-general:seq:42")
|
||||||
|
nonce, ct, err := cybersecurity.SealAEAD(key, []byte("hola sala"), aad)
|
||||||
|
if err != nil {
|
||||||
|
log.Fatal(err)
|
||||||
|
}
|
||||||
|
// Almacenar nonce junto al ciphertext para descifrar después
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cuando usarla
|
||||||
|
|
||||||
|
Al cifrar cada mensaje en una sala del bus: usa la room key de la sala como `key`, incluye el ID de sala y número de secuencia en `aad` para prevenir replay attacks entre salas, y transmite `nonce + ciphertext` juntos al destinatario.
|
||||||
|
|
||||||
|
## Gotchas
|
||||||
|
|
||||||
|
- El nonce es aleatorio (12 bytes): con una misma key, la probabilidad de colisión de nonces es despreciable para <2^32 mensajes, pero en escenarios de alto volumen considera rotar la room key periódicamente.
|
||||||
|
- El ciphertext es 16 bytes más largo que el plaintext (tag Poly1305).
|
||||||
|
- `aad` no viaja cifrado: el destinatario debe reconstruirlo independientemente para verificar. Si aad difiere aunque sea 1 bit, OpenAEAD falla con error de autenticación.
|
||||||
|
- Nunca reutilizar `(key, nonce)` para dos plaintexts distintos: rompe la confidencialidad de ChaCha20.
|
||||||
@@ -0,0 +1,28 @@
|
|||||||
|
package cybersecurity
|
||||||
|
|
||||||
|
import (
|
||||||
|
"crypto/rand"
|
||||||
|
"fmt"
|
||||||
|
|
||||||
|
"golang.org/x/crypto/nacl/box"
|
||||||
|
)
|
||||||
|
|
||||||
|
// SealKeyBox encrypts secret for a recipient identified by their X25519 public key,
|
||||||
|
// using an anonymous sealed box (ephemeral sender keypair, no sender authentication).
|
||||||
|
// Intended for distributing a symmetric room key to a participant.
|
||||||
|
// recipientKexPub must be exactly 32 bytes.
|
||||||
|
func SealKeyBox(recipientKexPub, secret []byte) ([]byte, error) {
|
||||||
|
if len(recipientKexPub) != 32 {
|
||||||
|
return nil, fmt.Errorf("seal_key_box: recipientKexPub must be 32 bytes, got %d", len(recipientKexPub))
|
||||||
|
}
|
||||||
|
|
||||||
|
var recipientKey [32]byte
|
||||||
|
copy(recipientKey[:], recipientKexPub)
|
||||||
|
|
||||||
|
sealed, err := box.SealAnonymous(nil, secret, &recipientKey, rand.Reader)
|
||||||
|
if err != nil {
|
||||||
|
return nil, fmt.Errorf("seal_key_box: %w", err)
|
||||||
|
}
|
||||||
|
|
||||||
|
return sealed, nil
|
||||||
|
}
|
||||||
@@ -0,0 +1,56 @@
|
|||||||
|
---
|
||||||
|
name: seal_key_box
|
||||||
|
kind: function
|
||||||
|
lang: go
|
||||||
|
domain: cybersecurity
|
||||||
|
version: "1.0.0"
|
||||||
|
purity: impure
|
||||||
|
signature: "func SealKeyBox(recipientKexPub, secret []byte) ([]byte, error)"
|
||||||
|
description: "Cifra un secreto (típicamente una room key simétrica) para un destinatario identificado por su clave pública X25519, usando un sealed box anónimo (nacl/box). El emisor no se autentica; usar SignEd25519 por separado si se necesita autenticación del remitente."
|
||||||
|
tags: [messaging, e2e-crypto, crypto, nacl, x25519, sealed-box, key-distribution, e2e-messaging]
|
||||||
|
uses_functions: []
|
||||||
|
uses_types: []
|
||||||
|
returns: []
|
||||||
|
returns_optional: false
|
||||||
|
error_type: "error_go_core"
|
||||||
|
imports:
|
||||||
|
- crypto/rand
|
||||||
|
- golang.org/x/crypto/nacl/box
|
||||||
|
params:
|
||||||
|
- name: recipientKexPub
|
||||||
|
desc: "Clave pública X25519 del destinatario (exactamente 32 bytes). Viene del campo KexPub de su Identity."
|
||||||
|
- name: secret
|
||||||
|
desc: "Bytes a cifrar. Típicamente una room key de 32 bytes, pero puede ser cualquier secreto."
|
||||||
|
output: "Sealed box cifrado (overhead: 32 bytes de ephemeral pubkey + 16 bytes de tag Poly1305), o error si recipientKexPub no tiene 32 bytes o falla el RNG."
|
||||||
|
tested: true
|
||||||
|
tests:
|
||||||
|
- "round-trip con identidad generada"
|
||||||
|
- "error con recipientKexPub de longitud incorrecta"
|
||||||
|
- "error al abrir con clave equivocada"
|
||||||
|
- "error con mensaje truncado"
|
||||||
|
test_file_path: "functions/cybersecurity/e2e_messaging_crypto_test.go"
|
||||||
|
file_path: "functions/cybersecurity/seal_key_box.go"
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ejemplo
|
||||||
|
|
||||||
|
```go
|
||||||
|
// Distribuir room key al usuario al unirse a la sala
|
||||||
|
roomKey := make([]byte, 32) // generada por el servidor de sala
|
||||||
|
sealed, err := cybersecurity.SealKeyBox(user.KexPub, roomKey)
|
||||||
|
if err != nil {
|
||||||
|
log.Fatal(err)
|
||||||
|
}
|
||||||
|
// Enviar sealed al usuario; solo él puede abrirlo con OpenKeyBox
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cuando usarla
|
||||||
|
|
||||||
|
Al distribuir una clave simétrica de sala a un nuevo participante: cifra la room key con la KexPub del destinatario antes de transmitirla. El destinatario usa OpenKeyBox para recuperarla. Combinar con SignEd25519 sobre el sealed box si se necesita autenticar que el servidor distribuyó la clave.
|
||||||
|
|
||||||
|
## Gotchas
|
||||||
|
|
||||||
|
- El sealed box es anónimo: el receptor no puede verificar quién lo generó. Firmar el sealed box con SignEd25519 si la autenticación del emisor importa.
|
||||||
|
- Overhead fijo: 48 bytes adicionales sobre el secreto (32 ephemeral pubkey + 16 tag).
|
||||||
|
- El sealed box no puede abrirse sin la clave privada X25519 correspondiente: si el usuario pierde KexPriv, la room key es irrecuperable.
|
||||||
|
- `recipientKexPub` debe tener exactamente 32 bytes; la función valida y devuelve error claro si no.
|
||||||
@@ -0,0 +1,10 @@
|
|||||||
|
package cybersecurity
|
||||||
|
|
||||||
|
import "crypto/ed25519"
|
||||||
|
|
||||||
|
// SignEd25519 signs msg with an Ed25519 private key and returns the 64-byte signature.
|
||||||
|
// priv must be a valid Ed25519 private key (64 bytes as returned by GenerateIdentity or ed25519.GenerateKey).
|
||||||
|
// This function is pure: same inputs always produce the same output (ed25519 is deterministic).
|
||||||
|
func SignEd25519(priv, msg []byte) []byte {
|
||||||
|
return ed25519.Sign(ed25519.PrivateKey(priv), msg)
|
||||||
|
}
|
||||||
@@ -0,0 +1,45 @@
|
|||||||
|
---
|
||||||
|
name: sign_ed25519
|
||||||
|
kind: function
|
||||||
|
lang: go
|
||||||
|
domain: cybersecurity
|
||||||
|
version: "1.0.0"
|
||||||
|
purity: pure
|
||||||
|
signature: "func SignEd25519(priv, msg []byte) []byte"
|
||||||
|
description: "Firma un mensaje con una clave privada Ed25519 y devuelve la firma de 64 bytes. Determinista: mismas entradas producen siempre la misma firma. Sin efectos secundarios ni I/O."
|
||||||
|
tags: [messaging, e2e-crypto, crypto, ed25519, signing, pure, e2e-messaging]
|
||||||
|
uses_functions: []
|
||||||
|
uses_types: []
|
||||||
|
returns: []
|
||||||
|
returns_optional: false
|
||||||
|
error_type: ""
|
||||||
|
imports:
|
||||||
|
- crypto/ed25519
|
||||||
|
params:
|
||||||
|
- name: priv
|
||||||
|
desc: "Clave privada Ed25519 de 64 bytes. Viene del campo SignPriv de Identity."
|
||||||
|
- name: msg
|
||||||
|
desc: "Bytes a firmar. Puede ser cualquier dato: ciphertext, evento, room key distribuida, etc."
|
||||||
|
output: "Firma Ed25519 de exactamente 64 bytes. Siempre determinista para la misma (priv, msg)."
|
||||||
|
tested: true
|
||||||
|
tests:
|
||||||
|
- "firma y verificacion exitosa"
|
||||||
|
- "firma es determinista (misma entrada, misma firma)"
|
||||||
|
- "falla con mensaje modificado"
|
||||||
|
- "falla con clave publica incorrecta"
|
||||||
|
- "falla con firma corrupta"
|
||||||
|
test_file_path: "functions/cybersecurity/e2e_messaging_crypto_test.go"
|
||||||
|
file_path: "functions/cybersecurity/sign_ed25519.go"
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ejemplo
|
||||||
|
|
||||||
|
```go
|
||||||
|
// Firmar el ciphertext de un mensaje antes de transmitirlo
|
||||||
|
sig := cybersecurity.SignEd25519(id.SignPriv, ciphertext)
|
||||||
|
// Transmitir ciphertext + sig; el receptor verifica con VerifyEd25519
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cuando usarla
|
||||||
|
|
||||||
|
Después de cifrar un mensaje con SealAEAD: firma el ciphertext (no el plaintext) con tu SignPriv para que el receptor pueda verificar la autoría con VerifyEd25519. También útil para firmar eventos de control del bus (rotación de clave, join/leave de sala).
|
||||||
@@ -0,0 +1,10 @@
|
|||||||
|
package cybersecurity
|
||||||
|
|
||||||
|
import "crypto/ed25519"
|
||||||
|
|
||||||
|
// VerifyEd25519 reports whether sig is a valid Ed25519 signature of msg under pub.
|
||||||
|
// pub must be a valid Ed25519 public key (32 bytes as returned by GenerateIdentity).
|
||||||
|
// Returns true only if the signature is authentic; false on any mismatch or invalid input.
|
||||||
|
func VerifyEd25519(pub, msg, sig []byte) bool {
|
||||||
|
return ed25519.Verify(ed25519.PublicKey(pub), msg, sig)
|
||||||
|
}
|
||||||
@@ -0,0 +1,51 @@
|
|||||||
|
---
|
||||||
|
name: verify_ed25519
|
||||||
|
kind: function
|
||||||
|
lang: go
|
||||||
|
domain: cybersecurity
|
||||||
|
version: "1.0.0"
|
||||||
|
purity: pure
|
||||||
|
signature: "func VerifyEd25519(pub, msg, sig []byte) bool"
|
||||||
|
description: "Verifica una firma Ed25519 sobre un mensaje usando la clave pública del firmante. Devuelve true solo si la firma es auténtica. Sin efectos secundarios ni I/O."
|
||||||
|
tags: [messaging, e2e-crypto, crypto, ed25519, signing, pure, e2e-messaging]
|
||||||
|
uses_functions: []
|
||||||
|
uses_types: []
|
||||||
|
returns: []
|
||||||
|
returns_optional: false
|
||||||
|
error_type: ""
|
||||||
|
imports:
|
||||||
|
- crypto/ed25519
|
||||||
|
params:
|
||||||
|
- name: pub
|
||||||
|
desc: "Clave pública Ed25519 de 32 bytes del firmante. Viene del campo SignPub de su Identity."
|
||||||
|
- name: msg
|
||||||
|
desc: "Mensaje original que fue firmado. Debe ser idéntico al pasado a SignEd25519."
|
||||||
|
- name: sig
|
||||||
|
desc: "Firma de 64 bytes producida por SignEd25519."
|
||||||
|
output: "true si la firma es válida para (pub, msg). false en cualquier otro caso: firma incorrecta, pub equivocada, msg alterado, o sig corrupta."
|
||||||
|
tested: true
|
||||||
|
tests:
|
||||||
|
- "firma y verificacion exitosa"
|
||||||
|
- "firma es determinista (misma entrada, misma firma)"
|
||||||
|
- "falla con mensaje modificado"
|
||||||
|
- "falla con clave publica incorrecta"
|
||||||
|
- "falla con firma corrupta"
|
||||||
|
test_file_path: "functions/cybersecurity/e2e_messaging_crypto_test.go"
|
||||||
|
file_path: "functions/cybersecurity/verify_ed25519.go"
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ejemplo
|
||||||
|
|
||||||
|
```go
|
||||||
|
// Receptor verifica autoría antes de descifrar
|
||||||
|
if !cybersecurity.VerifyEd25519(sender.SignPub, ciphertext, sig) {
|
||||||
|
log.Println("firma inválida: mensaje descartado")
|
||||||
|
return
|
||||||
|
}
|
||||||
|
// Solo si la firma es válida, descifrar con OpenAEAD
|
||||||
|
plaintext, err := cybersecurity.OpenAEAD(roomKey, nonce, ciphertext, aad)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cuando usarla
|
||||||
|
|
||||||
|
Al recibir un mensaje del bus: verifica la firma del remitente sobre el ciphertext antes de intentar descifrar. Devuelve false para cualquier fallo de autenticación — nunca procesar un mensaje con firma inválida.
|
||||||
@@ -0,0 +1,149 @@
|
|||||||
|
package infra
|
||||||
|
|
||||||
|
import (
|
||||||
|
"bytes"
|
||||||
|
"context"
|
||||||
|
"fmt"
|
||||||
|
"os/exec"
|
||||||
|
"sync"
|
||||||
|
"syscall"
|
||||||
|
"time"
|
||||||
|
|
||||||
|
"github.com/creack/pty"
|
||||||
|
)
|
||||||
|
|
||||||
|
// PTYCaptureIdle launches a command inside a pseudo-terminal (PTY) and captures
|
||||||
|
// all output until the terminal has been idle for at least idle duration, or
|
||||||
|
// maxDur has elapsed. Before sending inputs it waits warmup to let the process
|
||||||
|
// initialize. Between each input step it waits stepDelay.
|
||||||
|
//
|
||||||
|
// The returned string is the raw PTY output, ANSI escape sequences included.
|
||||||
|
// To turn it into plain text: use vt_render_go_tui to reconstruct the 2D screen
|
||||||
|
// layout for TUIs with absolute cursor positioning (claude, htop), or
|
||||||
|
// strip_ansi_go_core for sequential, log-like output.
|
||||||
|
func PTYCaptureIdle(
|
||||||
|
ctx context.Context,
|
||||||
|
name string,
|
||||||
|
args []string,
|
||||||
|
warmup time.Duration,
|
||||||
|
inputs []string,
|
||||||
|
stepDelay time.Duration,
|
||||||
|
idle time.Duration,
|
||||||
|
maxDur time.Duration,
|
||||||
|
) (string, error) {
|
||||||
|
cmd := exec.CommandContext(ctx, name, args...)
|
||||||
|
|
||||||
|
ptmx, err := pty.Start(cmd)
|
||||||
|
if err != nil {
|
||||||
|
return "", fmt.Errorf("pty_capture_idle: pty.Start: %w", err)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Set a reasonable terminal size so TUIs render without truncating.
|
||||||
|
if szErr := pty.Setsize(ptmx, &pty.Winsize{Rows: 40, Cols: 120}); szErr != nil {
|
||||||
|
// Non-fatal: continue even if resize fails.
|
||||||
|
_ = szErr
|
||||||
|
}
|
||||||
|
|
||||||
|
var (
|
||||||
|
mu sync.Mutex
|
||||||
|
buf bytes.Buffer
|
||||||
|
lastByte = time.Now()
|
||||||
|
)
|
||||||
|
|
||||||
|
// Reader goroutine: copy PTY output into buf and track last-byte time.
|
||||||
|
readDone := make(chan struct{})
|
||||||
|
go func() {
|
||||||
|
defer close(readDone)
|
||||||
|
tmp := make([]byte, 4096)
|
||||||
|
for {
|
||||||
|
n, rerr := ptmx.Read(tmp)
|
||||||
|
if n > 0 {
|
||||||
|
mu.Lock()
|
||||||
|
buf.Write(tmp[:n])
|
||||||
|
lastByte = time.Now()
|
||||||
|
mu.Unlock()
|
||||||
|
}
|
||||||
|
if rerr != nil {
|
||||||
|
// EIO/EOF is normal on Linux when the PTY master is closed
|
||||||
|
// after the child exits. Not a real error.
|
||||||
|
return
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}()
|
||||||
|
|
||||||
|
start := time.Now()
|
||||||
|
|
||||||
|
// Wait for warmup so the TUI/CLI has time to initialize.
|
||||||
|
select {
|
||||||
|
case <-time.After(warmup):
|
||||||
|
case <-ctx.Done():
|
||||||
|
_ = ptmx.Close()
|
||||||
|
<-readDone
|
||||||
|
mu.Lock()
|
||||||
|
out := buf.String()
|
||||||
|
mu.Unlock()
|
||||||
|
return out, fmt.Errorf("pty_capture_idle: context cancelled during warmup: %w", ctx.Err())
|
||||||
|
}
|
||||||
|
|
||||||
|
// Send inputs one by one with stepDelay between them.
|
||||||
|
for _, in := range inputs {
|
||||||
|
if _, werr := ptmx.Write([]byte(in)); werr != nil {
|
||||||
|
// PTY may have closed already; stop sending.
|
||||||
|
break
|
||||||
|
}
|
||||||
|
select {
|
||||||
|
case <-time.After(stepDelay):
|
||||||
|
case <-ctx.Done():
|
||||||
|
goto done
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
done:
|
||||||
|
// Poll until idle or maxDur.
|
||||||
|
ticker := time.NewTicker(100 * time.Millisecond)
|
||||||
|
defer ticker.Stop()
|
||||||
|
|
||||||
|
for {
|
||||||
|
select {
|
||||||
|
case <-ticker.C:
|
||||||
|
mu.Lock()
|
||||||
|
sinceLastByte := time.Since(lastByte)
|
||||||
|
mu.Unlock()
|
||||||
|
|
||||||
|
elapsed := time.Since(start)
|
||||||
|
if sinceLastByte >= idle || elapsed >= maxDur {
|
||||||
|
goto shutdown
|
||||||
|
}
|
||||||
|
case <-ctx.Done():
|
||||||
|
goto shutdown
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
shutdown:
|
||||||
|
// Close the PTY master. This signals EOF to the reader goroutine.
|
||||||
|
_ = ptmx.Close()
|
||||||
|
|
||||||
|
// Graceful shutdown: SIGTERM first, then SIGKILL after 2s.
|
||||||
|
if cmd.Process != nil {
|
||||||
|
_ = cmd.Process.Signal(syscall.SIGTERM)
|
||||||
|
killTimer := time.NewTimer(2 * time.Second)
|
||||||
|
waitCh := make(chan error, 1)
|
||||||
|
go func() { waitCh <- cmd.Wait() }()
|
||||||
|
select {
|
||||||
|
case <-waitCh:
|
||||||
|
// Process exited cleanly.
|
||||||
|
case <-killTimer.C:
|
||||||
|
_ = cmd.Process.Kill()
|
||||||
|
<-waitCh
|
||||||
|
}
|
||||||
|
killTimer.Stop()
|
||||||
|
}
|
||||||
|
|
||||||
|
<-readDone
|
||||||
|
|
||||||
|
mu.Lock()
|
||||||
|
out := buf.String()
|
||||||
|
mu.Unlock()
|
||||||
|
|
||||||
|
return out, nil
|
||||||
|
}
|
||||||
@@ -0,0 +1,83 @@
|
|||||||
|
---
|
||||||
|
name: pty_capture_idle
|
||||||
|
kind: function
|
||||||
|
lang: go
|
||||||
|
domain: infra
|
||||||
|
version: "1.0.0"
|
||||||
|
purity: impure
|
||||||
|
signature: "func PTYCaptureIdle(ctx context.Context, name string, args []string, warmup time.Duration, inputs []string, stepDelay, idle, maxDur time.Duration) (string, error)"
|
||||||
|
description: "Lanza un comando dentro de un pseudo-terminal (PTY) en memoria y captura todo su output hasta que el terminal permanece idle durante al menos `idle`, o se alcanza `maxDur`. Soporta envío de inputs interactivos tras el warmup inicial. Devuelve el output RAW con secuencias ANSI intactas."
|
||||||
|
tags: ["terminal", "pty", "tui", "capture", "automation", "terminal-capture"]
|
||||||
|
uses_functions: []
|
||||||
|
uses_types: []
|
||||||
|
returns: []
|
||||||
|
returns_optional: false
|
||||||
|
error_type: "error_go_core"
|
||||||
|
imports:
|
||||||
|
- "context"
|
||||||
|
- "time"
|
||||||
|
- "github.com/creack/pty"
|
||||||
|
tested: true
|
||||||
|
tests:
|
||||||
|
- "captura output de echo hola"
|
||||||
|
- "input interactivo con cat"
|
||||||
|
- "timeout duro con sleep 10"
|
||||||
|
test_file_path: "functions/infra/pty_capture_idle_test.go"
|
||||||
|
file_path: "functions/infra/pty_capture_idle.go"
|
||||||
|
params:
|
||||||
|
- name: ctx
|
||||||
|
desc: "Contexto de cancelación. Si se cancela, la función aborta la captura y retorna el output acumulado hasta ese momento."
|
||||||
|
- name: name
|
||||||
|
desc: "Nombre o path del ejecutable a lanzar (debe existir en PATH o ser un path absoluto)."
|
||||||
|
- name: args
|
||||||
|
desc: "Argumentos posicionales para el ejecutable. Puede ser nil o vacío."
|
||||||
|
- name: warmup
|
||||||
|
desc: "Tiempo que la función espera después de arrancar el proceso antes de enviar inputs. Permite que la TUI inicialice su render. Típico: 500ms–2s para CLIs lentas."
|
||||||
|
- name: inputs
|
||||||
|
desc: "Lista de strings a escribir al PTY en secuencia, uno por vez. Incluir '\\r' al final de cada string para simular Enter. Puede ser nil si solo se quiere observar la salida sin interactuar."
|
||||||
|
- name: stepDelay
|
||||||
|
desc: "Espera entre cada input enviado. Permite que la TUI procese y renderice la respuesta de cada paso antes de enviar el siguiente."
|
||||||
|
- name: idle
|
||||||
|
desc: "Tiempo sin nuevos bytes en el PTY que se considera 'respuesta terminada'. Cuando el terminal lleva idle sin actividad, la función retorna. Típico: 500ms–2s."
|
||||||
|
- name: maxDur
|
||||||
|
desc: "Timeout duro desde el inicio de la función. Garantiza que la función retorna aunque la TUI siga emitiendo output indefinidamente (spinners, relojes). Típico: 30s–120s."
|
||||||
|
output: "String con el output completo del terminal desde el arranque hasta la captura, incluyendo secuencias de escape ANSI. Vacío string si el proceso no produjo nada. Error si el PTY no pudo arrancar o el contexto fue cancelado durante warmup."
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ejemplo
|
||||||
|
|
||||||
|
```go
|
||||||
|
// Capturar una sesión de claude con un prompt automático
|
||||||
|
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
|
||||||
|
defer cancel()
|
||||||
|
|
||||||
|
raw, err := PTYCaptureIdle(
|
||||||
|
ctx,
|
||||||
|
"claude", nil,
|
||||||
|
2*time.Second, // warmup: esperar que claude cargue
|
||||||
|
[]string{"hola, responde PONG\r"}, // inputs: enviar mensaje + Enter
|
||||||
|
300*time.Millisecond, // stepDelay entre inputs
|
||||||
|
2*time.Second, // idle: cortar cuando lleve 2s sin output
|
||||||
|
120*time.Second, // maxDur: timeout duro
|
||||||
|
)
|
||||||
|
if err != nil {
|
||||||
|
log.Fatal(err)
|
||||||
|
}
|
||||||
|
// raw contiene el render completo con ANSI; limpiar antes de procesar texto:
|
||||||
|
// clean := StripANSI(raw) // strip_ansi_go_tui
|
||||||
|
fmt.Println(raw)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cuando usarla
|
||||||
|
|
||||||
|
Cuando necesites automatizar o scriptear una CLI interactiva que solo entra en modo interactivo si detecta un TTY real (como `claude`, `vim`, `fzf`, `htop`, `python` REPL, `psql`). El PTY hace creer al proceso que habla con un terminal real, sin abrir ninguna ventana gráfica.
|
||||||
|
|
||||||
|
## Gotchas
|
||||||
|
|
||||||
|
- **Linux/Unix only.** Usa PTY POSIX (`creack/pty`). No funciona en Windows.
|
||||||
|
- **Output RAW con ANSI.** El string devuelto contiene secuencias de escape (`\x1b[...m`, cursor moves, etc.). Para convertirlo a texto plano: usa `vt_render_go_tui` (reconstruye el layout 2D — correcto para TUIs con posicionamiento absoluto como `claude` o `htop`) o `strip_ansi_go_core` (para output secuencial tipo log). `strip_ansi` sobre una TUI con layout absoluto deja las palabras pegadas porque los espacios entre columnas eran movimientos de cursor.
|
||||||
|
- **Idle es heurístico.** Si la TUI hace render periódico (spinners, relojes en pantalla, progress bars continuas), el idle nunca se dispara y la función esperará hasta `maxDur`. Aumentar `maxDur` o matar el spinner antes de capturar.
|
||||||
|
- **El binario debe existir en PATH** (o usar path absoluto en `name`). La función devuelve error si `pty.Start` falla.
|
||||||
|
- **EIO/EOF al cerrar PTY es normal en Linux.** El goroutine lector lo absorbe silenciosamente; no se propaga como error.
|
||||||
|
- **SIGTERM → SIGKILL.** Al terminar la captura, la función envía SIGTERM al proceso y espera 2s antes de SIGKILL. Procesos que ignoran SIGTERM (como `sleep`) se matan limpiamente.
|
||||||
|
- **Tamaño de terminal fijado a 40×120.** Suficiente para la mayoría de TUIs. Si el render se ve truncado, el llamador puede hacer `pty.Setsize` adicional después de obtener el ptmx (no expuesto por esta función; para casos avanzados, reimplementar con acceso directo al ptmx).
|
||||||
@@ -0,0 +1,74 @@
|
|||||||
|
package infra
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
"strings"
|
||||||
|
"testing"
|
||||||
|
"time"
|
||||||
|
)
|
||||||
|
|
||||||
|
func TestPTYCaptureIdle(t *testing.T) {
|
||||||
|
t.Run("captura output de echo hola", func(t *testing.T) {
|
||||||
|
if testing.Short() {
|
||||||
|
t.Skip("skip en modo corto")
|
||||||
|
}
|
||||||
|
ctx := context.Background()
|
||||||
|
out, err := PTYCaptureIdle(ctx, "echo", []string{"hola"}, 100*time.Millisecond, nil, 0, 300*time.Millisecond, 5*time.Second)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("error inesperado: %v", err)
|
||||||
|
}
|
||||||
|
if !strings.Contains(out, "hola") {
|
||||||
|
t.Errorf("se esperaba 'hola' en el output, got: %q", out)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("input interactivo con cat", func(t *testing.T) {
|
||||||
|
if testing.Short() {
|
||||||
|
t.Skip("skip en modo corto: timing sensible en CI")
|
||||||
|
}
|
||||||
|
ctx := context.Background()
|
||||||
|
// cat repite stdin a stdout via PTY; el PTY hace echo del input ademas.
|
||||||
|
// "ping\r" simula Enter; la palabra "ping" debe aparecer en el output.
|
||||||
|
out, err := PTYCaptureIdle(
|
||||||
|
ctx,
|
||||||
|
"cat", nil,
|
||||||
|
200*time.Millisecond,
|
||||||
|
[]string{"ping\r"},
|
||||||
|
100*time.Millisecond,
|
||||||
|
500*time.Millisecond,
|
||||||
|
5*time.Second,
|
||||||
|
)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("error inesperado: %v", err)
|
||||||
|
}
|
||||||
|
if !strings.Contains(out, "ping") {
|
||||||
|
t.Errorf("se esperaba 'ping' en el output, got: %q", out)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("timeout duro con sleep 10", func(t *testing.T) {
|
||||||
|
if testing.Short() {
|
||||||
|
t.Skip("skip en modo corto: espera ~1s de timeout")
|
||||||
|
}
|
||||||
|
ctx := context.Background()
|
||||||
|
start := time.Now()
|
||||||
|
_, err := PTYCaptureIdle(
|
||||||
|
ctx,
|
||||||
|
"sleep", []string{"10"},
|
||||||
|
50*time.Millisecond,
|
||||||
|
nil,
|
||||||
|
0,
|
||||||
|
600*time.Millisecond,
|
||||||
|
1*time.Second,
|
||||||
|
)
|
||||||
|
elapsed := time.Since(start)
|
||||||
|
if err != nil {
|
||||||
|
// Un error de señal/exit es esperado; no falla el test.
|
||||||
|
t.Logf("error (esperado al matar sleep): %v", err)
|
||||||
|
}
|
||||||
|
// La función debe retornar en menos de 3s, no esperar los 10s del sleep.
|
||||||
|
if elapsed >= 3*time.Second {
|
||||||
|
t.Errorf("la función tardó %v, se esperaba < 3s", elapsed)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
@@ -0,0 +1,176 @@
|
|||||||
|
package infra
|
||||||
|
|
||||||
|
import (
|
||||||
|
"bytes"
|
||||||
|
"context"
|
||||||
|
"fmt"
|
||||||
|
"os/exec"
|
||||||
|
"sync"
|
||||||
|
"syscall"
|
||||||
|
"time"
|
||||||
|
|
||||||
|
"github.com/creack/pty"
|
||||||
|
)
|
||||||
|
|
||||||
|
// PTYCaptureStream launches a command inside a pseudo-terminal (PTY) and
|
||||||
|
// streams periodic snapshots of the accumulated output through a channel.
|
||||||
|
// Unlike PTYCaptureIdle, which returns the full output at the end,
|
||||||
|
// PTYCaptureStream emits the ENTIRE buffer accumulated so far on every
|
||||||
|
// snapshotInterval tick — allowing callers to observe the terminal render
|
||||||
|
// while the process is still running.
|
||||||
|
//
|
||||||
|
// The returned channel is closed when capture ends (idle/maxDur/ctx cancel).
|
||||||
|
// The last value sent before closing is always a final snapshot of the
|
||||||
|
// complete buffer, regardless of tick alignment.
|
||||||
|
//
|
||||||
|
// Callers MUST drain the channel or cancel ctx to avoid blocking the
|
||||||
|
// internal goroutine. Error is returned only if pty.Start fails.
|
||||||
|
func PTYCaptureStream(
|
||||||
|
ctx context.Context,
|
||||||
|
name string,
|
||||||
|
args []string,
|
||||||
|
warmup time.Duration,
|
||||||
|
inputs []string,
|
||||||
|
stepDelay time.Duration,
|
||||||
|
snapshotInterval time.Duration,
|
||||||
|
idle time.Duration,
|
||||||
|
maxDur time.Duration,
|
||||||
|
) (<-chan string, error) {
|
||||||
|
cmd := exec.CommandContext(ctx, name, args...)
|
||||||
|
|
||||||
|
ptmx, err := pty.Start(cmd)
|
||||||
|
if err != nil {
|
||||||
|
return nil, fmt.Errorf("pty_capture_stream: pty.Start: %w", err)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Set a reasonable terminal size so TUIs render without truncating.
|
||||||
|
if szErr := pty.Setsize(ptmx, &pty.Winsize{Rows: 40, Cols: 120}); szErr != nil {
|
||||||
|
// Non-fatal: continue even if resize fails.
|
||||||
|
_ = szErr
|
||||||
|
}
|
||||||
|
|
||||||
|
var (
|
||||||
|
mu sync.Mutex
|
||||||
|
buf bytes.Buffer
|
||||||
|
lastByte = time.Now()
|
||||||
|
)
|
||||||
|
|
||||||
|
// Reader goroutine: copy PTY output into buf and track last-byte time.
|
||||||
|
readDone := make(chan struct{})
|
||||||
|
go func() {
|
||||||
|
defer close(readDone)
|
||||||
|
tmp := make([]byte, 4096)
|
||||||
|
for {
|
||||||
|
n, rerr := ptmx.Read(tmp)
|
||||||
|
if n > 0 {
|
||||||
|
mu.Lock()
|
||||||
|
buf.Write(tmp[:n])
|
||||||
|
lastByte = time.Now()
|
||||||
|
mu.Unlock()
|
||||||
|
}
|
||||||
|
if rerr != nil {
|
||||||
|
// EIO/EOF is normal on Linux when the PTY master is closed
|
||||||
|
// after the child exits. Not a real error.
|
||||||
|
return
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}()
|
||||||
|
|
||||||
|
ch := make(chan string, 16)
|
||||||
|
|
||||||
|
// snapshot returns a copy of the current buffer contents.
|
||||||
|
snapshot := func() string {
|
||||||
|
mu.Lock()
|
||||||
|
s := buf.String()
|
||||||
|
mu.Unlock()
|
||||||
|
return s
|
||||||
|
}
|
||||||
|
|
||||||
|
// send emits a snapshot to ch, respecting ctx cancellation.
|
||||||
|
send := func(s string) bool {
|
||||||
|
select {
|
||||||
|
case ch <- s:
|
||||||
|
return true
|
||||||
|
case <-ctx.Done():
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Conducting goroutine: handles warmup, inputs, periodic snapshots,
|
||||||
|
// idle/maxDur detection, and shutdown.
|
||||||
|
go func() {
|
||||||
|
defer func() {
|
||||||
|
// Shutdown: close PTY master, SIGTERM → SIGKILL, wait reader.
|
||||||
|
_ = ptmx.Close()
|
||||||
|
if cmd.Process != nil {
|
||||||
|
_ = cmd.Process.Signal(syscall.SIGTERM)
|
||||||
|
killTimer := time.NewTimer(2 * time.Second)
|
||||||
|
waitCh := make(chan error, 1)
|
||||||
|
go func() { waitCh <- cmd.Wait() }()
|
||||||
|
select {
|
||||||
|
case <-waitCh:
|
||||||
|
// Process exited cleanly.
|
||||||
|
case <-killTimer.C:
|
||||||
|
_ = cmd.Process.Kill()
|
||||||
|
<-waitCh
|
||||||
|
}
|
||||||
|
killTimer.Stop()
|
||||||
|
}
|
||||||
|
<-readDone
|
||||||
|
// Final snapshot — always emitted so consumers get the complete state.
|
||||||
|
send(snapshot())
|
||||||
|
close(ch)
|
||||||
|
}()
|
||||||
|
|
||||||
|
start := time.Now()
|
||||||
|
|
||||||
|
// Wait for warmup so the TUI/CLI has time to initialize.
|
||||||
|
select {
|
||||||
|
case <-time.After(warmup):
|
||||||
|
case <-ctx.Done():
|
||||||
|
return
|
||||||
|
}
|
||||||
|
|
||||||
|
// Send inputs one by one with stepDelay between them.
|
||||||
|
for _, in := range inputs {
|
||||||
|
if _, werr := ptmx.Write([]byte(in)); werr != nil {
|
||||||
|
// PTY may have closed already; stop sending.
|
||||||
|
break
|
||||||
|
}
|
||||||
|
select {
|
||||||
|
case <-time.After(stepDelay):
|
||||||
|
case <-ctx.Done():
|
||||||
|
return
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Main loop: emit snapshots on ticker, cut on idle or maxDur.
|
||||||
|
ticker := time.NewTicker(snapshotInterval)
|
||||||
|
defer ticker.Stop()
|
||||||
|
|
||||||
|
for {
|
||||||
|
select {
|
||||||
|
case <-ticker.C:
|
||||||
|
// Emit current accumulated snapshot.
|
||||||
|
if !send(snapshot()) {
|
||||||
|
return
|
||||||
|
}
|
||||||
|
|
||||||
|
// Check termination conditions.
|
||||||
|
mu.Lock()
|
||||||
|
sinceLastByte := time.Since(lastByte)
|
||||||
|
mu.Unlock()
|
||||||
|
|
||||||
|
elapsed := time.Since(start)
|
||||||
|
if sinceLastByte >= idle || elapsed >= maxDur {
|
||||||
|
return
|
||||||
|
}
|
||||||
|
|
||||||
|
case <-ctx.Done():
|
||||||
|
return
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}()
|
||||||
|
|
||||||
|
return ch, nil
|
||||||
|
}
|
||||||
@@ -0,0 +1,100 @@
|
|||||||
|
---
|
||||||
|
name: pty_capture_stream
|
||||||
|
kind: function
|
||||||
|
lang: go
|
||||||
|
domain: infra
|
||||||
|
version: "1.0.0"
|
||||||
|
purity: impure
|
||||||
|
signature: "func PTYCaptureStream(ctx context.Context, name string, args []string, warmup time.Duration, inputs []string, stepDelay, snapshotInterval, idle, maxDur time.Duration) (<-chan string, error)"
|
||||||
|
description: "Lanza un comando dentro de un pseudo-terminal (PTY) y emite snapshots acumulativos del buffer de output a través de un canal, en intervalos regulares. Cada snapshot es el contenido RAW completo del PTY hasta ese instante (ANSI incluido). Permite hacer streaming del render de una TUI mientras sigue generando, sin esperar al final."
|
||||||
|
tags: ["terminal", "pty", "tui", "capture", "automation", "streaming", "terminal-capture"]
|
||||||
|
uses_functions: []
|
||||||
|
uses_types: []
|
||||||
|
returns: []
|
||||||
|
returns_optional: false
|
||||||
|
error_type: "error_go_core"
|
||||||
|
imports:
|
||||||
|
- "context"
|
||||||
|
- "time"
|
||||||
|
- "github.com/creack/pty"
|
||||||
|
tested: true
|
||||||
|
tests:
|
||||||
|
- "snapshots crecientes con pausas"
|
||||||
|
- "snapshot final siempre presente"
|
||||||
|
- "timeout duro con sleep 10"
|
||||||
|
test_file_path: "functions/infra/pty_capture_stream_test.go"
|
||||||
|
file_path: "functions/infra/pty_capture_stream.go"
|
||||||
|
params:
|
||||||
|
- name: ctx
|
||||||
|
desc: "Contexto de cancelación. Si se cancela, la goroutine interna aborta, emite el snapshot final y cierra el canal."
|
||||||
|
- name: name
|
||||||
|
desc: "Nombre o path del ejecutable a lanzar (debe existir en PATH o ser un path absoluto)."
|
||||||
|
- name: args
|
||||||
|
desc: "Argumentos posicionales para el ejecutable. Puede ser nil o vacío."
|
||||||
|
- name: warmup
|
||||||
|
desc: "Tiempo que se espera después de arrancar el proceso antes de enviar inputs. Permite que la TUI inicialice su render. Típico: 500ms–4s para CLIs lentas como claude."
|
||||||
|
- name: inputs
|
||||||
|
desc: "Lista de strings a escribir al PTY en secuencia. Incluir '\\r' al final para simular Enter. Puede ser nil si solo se quiere observar sin interactuar."
|
||||||
|
- name: stepDelay
|
||||||
|
desc: "Espera entre cada input enviado. Permite que la TUI procese y renderice la respuesta de cada paso antes de enviar el siguiente."
|
||||||
|
- name: snapshotInterval
|
||||||
|
desc: "Cada cuánto tiempo se emite un snapshot del buffer acumulado al canal. Controla la frecuencia de actualización del streaming. Valores recomendados: 100ms–300ms. Por debajo de 50ms genera mucho ruido y CPU innecesario."
|
||||||
|
- name: idle
|
||||||
|
desc: "Tiempo sin nuevos bytes en el PTY que se considera 'respuesta terminada'. Cuando el terminal lleva este tiempo sin actividad, la captura finaliza. Típico: 2s–4s para claude, 500ms para CLIs rápidas."
|
||||||
|
- name: maxDur
|
||||||
|
desc: "Timeout duro desde el inicio de la función. Garantiza que el canal se cierra aunque la TUI siga emitiendo (spinners, relojes, progress bars). Típico: 60s–120s para prompts de claude."
|
||||||
|
output: "Canal de strings (<-chan string). Cada string es el output RAW acumulado del terminal desde el arranque hasta ese instante, con secuencias ANSI intactas (no deltas). El canal se cierra cuando termina la captura; el último valor enviado antes del cierre es siempre el snapshot final completo. Error si pty.Start falla al arrancar el proceso."
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ejemplo
|
||||||
|
|
||||||
|
```go
|
||||||
|
// Streaming de una sesión claude: ver la respuesta formarse en tiempo real.
|
||||||
|
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
|
||||||
|
defer cancel()
|
||||||
|
|
||||||
|
ch, err := PTYCaptureStream(
|
||||||
|
ctx,
|
||||||
|
"claude", nil,
|
||||||
|
4*time.Second, // warmup: esperar que claude cargue
|
||||||
|
[]string{"hola, responde PONG\r"}, // inputs: enviar mensaje + Enter
|
||||||
|
300*time.Millisecond, // stepDelay entre inputs
|
||||||
|
150*time.Millisecond, // snapshotInterval: snapshot cada 150ms
|
||||||
|
4*time.Second, // idle: cortar cuando lleve 4s sin output
|
||||||
|
120*time.Second, // maxDur: timeout duro
|
||||||
|
)
|
||||||
|
if err != nil {
|
||||||
|
log.Fatal(err)
|
||||||
|
}
|
||||||
|
|
||||||
|
var lastRender string
|
||||||
|
for raw := range ch {
|
||||||
|
// Aplicar VT render para reconstruir la pantalla 2D desde ANSI.
|
||||||
|
screen := VTRender(raw) // vt_render_go_tui
|
||||||
|
// Parsear el estado actual de la respuesta de claude.
|
||||||
|
resp := ParseClaudeTUI(screen) // parse_claude_tui_go_tui
|
||||||
|
if resp.Response != lastRender {
|
||||||
|
fmt.Printf("\r[streaming] %s", resp.Response)
|
||||||
|
lastRender = resp.Response
|
||||||
|
}
|
||||||
|
}
|
||||||
|
// Al salir del for, el canal está cerrado: captura terminada.
|
||||||
|
fmt.Println("\n[done]", lastRender)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cuando usarla
|
||||||
|
|
||||||
|
Cuando quieras observar el render de una TUI **mientras sigue generando** — por ejemplo, ver la respuesta de `claude` formarse en tiempo real en lugar de esperar al final. Cada snapshot del canal es el estado completo de la pantalla en ese instante; aplica `vt_render_go_tui` + `parse_claude_tui_go_tui` para extraer texto interpretado de cada frame.
|
||||||
|
|
||||||
|
Para captura one-shot (solo quieres el output final), usa `pty_capture_idle_go_infra` — más simple, sin goroutina consumidora.
|
||||||
|
|
||||||
|
## Gotchas
|
||||||
|
|
||||||
|
- **Linux/Unix only.** Usa PTY POSIX (`creack/pty`). No funciona en Windows.
|
||||||
|
- **Snapshots ACUMULATIVOS, no deltas.** Cada string del canal es el buffer completo desde el inicio, no solo los bytes nuevos. Para calcular lo nuevo en cada tick: `delta := snapshot[len(prevSnapshot):]` — o usa `text_prefix_delta_go_core` si existe. El consumidor decide si quiere el frame completo o el incremento.
|
||||||
|
- **El consumidor DEBE drenar el canal o cancelar ctx.** Si el canal (capacidad 16) se llena y el consumidor deja de leer, la goroutina interna se bloquea. Patrón seguro: `for range ch {}` en goroutina separada si no se necesita el contenido.
|
||||||
|
- **La TUI re-renderiza el frame entero.** El buffer crudo crece monotónicamente en bytes, pero el render VT interpretado puede no ser monótono (la TUI puede limpiar la pantalla y re-dibujar). Comparar `VTRender(snapshot)` frame a frame para detectar cambios reales.
|
||||||
|
- **snapshotInterval < 50ms genera ruido.** El output ANSI de una TUI activa puede cambiar miles de veces por segundo; muestrear muy rápido satura el canal con frames casi idénticos y consume CPU innecesariamente.
|
||||||
|
- **Idle es heurístico.** Si la TUI tiene spinners o progress bars que emiten bytes continuamente, `idle` nunca se dispara y la función espera hasta `maxDur`. Subir `maxDur` o detener el spinner antes de capturar.
|
||||||
|
- **EIO/EOF al cerrar PTY es normal en Linux.** El goroutine lector lo absorbe silenciosamente.
|
||||||
|
- **SIGTERM → SIGKILL.** Al terminar, se envía SIGTERM y se espera 2s antes de SIGKILL.
|
||||||
@@ -0,0 +1,120 @@
|
|||||||
|
package infra
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
"strings"
|
||||||
|
"testing"
|
||||||
|
"time"
|
||||||
|
)
|
||||||
|
|
||||||
|
func TestPTYCaptureStream(t *testing.T) {
|
||||||
|
|
||||||
|
t.Run("snapshots crecientes con pausas", func(t *testing.T) {
|
||||||
|
if testing.Short() {
|
||||||
|
t.Skip("skip en modo corto: timing sensible")
|
||||||
|
}
|
||||||
|
ctx := context.Background()
|
||||||
|
// bash -lc imprime A, pausa 0.3s, B, pausa 0.3s, C, pausa 0.3s.
|
||||||
|
// Con snapshotInterval 100ms e idle 400ms debería recibir varios snapshots
|
||||||
|
// y el último debe contener A, B y C.
|
||||||
|
ch, err := PTYCaptureStream(
|
||||||
|
ctx,
|
||||||
|
"bash", []string{"-lc", "printf A; sleep 0.3; printf B; sleep 0.3; printf C; sleep 0.3"},
|
||||||
|
50*time.Millisecond, // warmup
|
||||||
|
nil, // inputs
|
||||||
|
0, // stepDelay
|
||||||
|
100*time.Millisecond, // snapshotInterval
|
||||||
|
400*time.Millisecond, // idle
|
||||||
|
5*time.Second, // maxDur
|
||||||
|
)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("error inesperado al arrancar: %v", err)
|
||||||
|
}
|
||||||
|
|
||||||
|
var snapshots []string
|
||||||
|
for s := range ch {
|
||||||
|
snapshots = append(snapshots, s)
|
||||||
|
}
|
||||||
|
|
||||||
|
if len(snapshots) < 2 {
|
||||||
|
t.Errorf("se esperaban >=2 snapshots, got %d", len(snapshots))
|
||||||
|
}
|
||||||
|
|
||||||
|
// Snapshots deben ser acumulativos (monótonos en longitud).
|
||||||
|
for i := 1; i < len(snapshots); i++ {
|
||||||
|
if len(snapshots[i]) < len(snapshots[i-1]) {
|
||||||
|
t.Errorf("snapshot[%d] len=%d < snapshot[%d] len=%d — no acumulativo",
|
||||||
|
i, len(snapshots[i]), i-1, len(snapshots[i-1]))
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// El último snapshot debe contener A, B y C.
|
||||||
|
last := snapshots[len(snapshots)-1]
|
||||||
|
for _, want := range []string{"A", "B", "C"} {
|
||||||
|
if !strings.Contains(last, want) {
|
||||||
|
t.Errorf("último snapshot no contiene %q: %q", want, last)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("snapshot final siempre presente", func(t *testing.T) {
|
||||||
|
if testing.Short() {
|
||||||
|
t.Skip("skip en modo corto")
|
||||||
|
}
|
||||||
|
ctx := context.Background()
|
||||||
|
// Output instantáneo; con idle 300ms el canal cierra rápido.
|
||||||
|
ch, err := PTYCaptureStream(
|
||||||
|
ctx,
|
||||||
|
"bash", []string{"-lc", "printf HOLA"},
|
||||||
|
50*time.Millisecond,
|
||||||
|
nil,
|
||||||
|
0,
|
||||||
|
150*time.Millisecond, // snapshotInterval
|
||||||
|
300*time.Millisecond, // idle
|
||||||
|
5*time.Second,
|
||||||
|
)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("error inesperado: %v", err)
|
||||||
|
}
|
||||||
|
|
||||||
|
var last string
|
||||||
|
for s := range ch {
|
||||||
|
last = s
|
||||||
|
}
|
||||||
|
|
||||||
|
if !strings.Contains(last, "HOLA") {
|
||||||
|
t.Errorf("último snapshot no contiene 'HOLA': %q", last)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("timeout duro con sleep 10", func(t *testing.T) {
|
||||||
|
if testing.Short() {
|
||||||
|
t.Skip("skip en modo corto: espera ~1s de timeout")
|
||||||
|
}
|
||||||
|
ctx := context.Background()
|
||||||
|
start := time.Now()
|
||||||
|
ch, err := PTYCaptureStream(
|
||||||
|
ctx,
|
||||||
|
"sleep", []string{"10"},
|
||||||
|
50*time.Millisecond,
|
||||||
|
nil,
|
||||||
|
0,
|
||||||
|
200*time.Millisecond, // snapshotInterval
|
||||||
|
600*time.Millisecond, // idle
|
||||||
|
1*time.Second, // maxDur duro en 1s
|
||||||
|
)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("error inesperado al arrancar: %v", err)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Drenar completamente el canal.
|
||||||
|
for range ch {
|
||||||
|
}
|
||||||
|
|
||||||
|
elapsed := time.Since(start)
|
||||||
|
// La función debe retornar en menos de 3s, no esperar los 10s del sleep.
|
||||||
|
if elapsed >= 3*time.Second {
|
||||||
|
t.Errorf("la función tardó %v, se esperaba < 3s", elapsed)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
@@ -0,0 +1,390 @@
|
|||||||
|
package tui
|
||||||
|
|
||||||
|
import (
|
||||||
|
"regexp"
|
||||||
|
"strings"
|
||||||
|
"unicode"
|
||||||
|
)
|
||||||
|
|
||||||
|
// Unicode markers used by the Claude Code TUI.
|
||||||
|
const (
|
||||||
|
markerUser = '❯' // U+276F — user prompt
|
||||||
|
markerAssistant = '●' // U+25CF — assistant response / tool call
|
||||||
|
markerToolResult = '⎿' // U+23BF — tool result
|
||||||
|
markerProgress = '✻' // U+273B — progress indicator (ignore)
|
||||||
|
markerBoxTL = '╭' // U+256D — top-left box corner (banner start)
|
||||||
|
markerBoxBL = '╰' // U+2570 — bottom-left box corner (banner end)
|
||||||
|
markerBoxBR = '╯' // U+256F — bottom-right box corner (banner end)
|
||||||
|
markerHRule = '─' // U+2500 — horizontal rule
|
||||||
|
)
|
||||||
|
|
||||||
|
// reToolUse matches "Identifier(anything)" — a tool_use line.
|
||||||
|
var reToolUse = regexp.MustCompile(`^([A-Za-z_][A-Za-z0-9_]*)\((.*)\)\s*$`)
|
||||||
|
|
||||||
|
// reProgress matches Claude's generation status/spinner line by its stable
|
||||||
|
// signature: "(Ns … tokens" or "esc to interrupt". Used when the line still
|
||||||
|
// carries that suffix, e.g. "✽ Whatchamacalliting… (2s · ↓ 1 tokens · esc to interrupt)".
|
||||||
|
var reProgress = regexp.MustCompile(`\(\d+s\b[^)]*tokens?\b|esc to interrupt`)
|
||||||
|
|
||||||
|
// reSpinner matches the spinner line by STRUCTURE rather than by its (infinite,
|
||||||
|
// ever-changing) gerund word: a non-alphanumeric glyph (✻ ✽ ✢ ✶ ✺ …) followed by
|
||||||
|
// a single word and a horizontal ellipsis, e.g. "✽ Forging…" or "✶ Puzzling…".
|
||||||
|
// This catches early frames that don't yet show the "(Ns · tokens)" suffix. The
|
||||||
|
// caller guards known turn markers (●/❯/⎿) so a legitimate answer ending in "…"
|
||||||
|
// is not misclassified.
|
||||||
|
var reSpinner = regexp.MustCompile(`^\s*[^\p{L}\p{N}\s]\s+\p{L}[\p{L}'’\-]*…`)
|
||||||
|
|
||||||
|
// ClaudeTurnRole classifies each turn/block extracted from the screen.
|
||||||
|
type ClaudeTurnRole string
|
||||||
|
|
||||||
|
const (
|
||||||
|
// ClaudeTurnUser is a message typed by the user (line starting with "❯ ").
|
||||||
|
ClaudeTurnUser ClaudeTurnRole = "user"
|
||||||
|
// ClaudeTurnAssistant is a response block from the assistant.
|
||||||
|
ClaudeTurnAssistant ClaudeTurnRole = "assistant"
|
||||||
|
// ClaudeTurnToolUse is a tool invocation "● ToolName(args)".
|
||||||
|
ClaudeTurnToolUse ClaudeTurnRole = "tool_use"
|
||||||
|
// ClaudeTurnToolResult is a result line "⎿ ..." following a tool_use.
|
||||||
|
ClaudeTurnToolResult ClaudeTurnRole = "tool_result"
|
||||||
|
)
|
||||||
|
|
||||||
|
// ClaudeTurn is a single conversation block extracted from the rendered screen.
|
||||||
|
type ClaudeTurn struct {
|
||||||
|
Role ClaudeTurnRole `json:"role"`
|
||||||
|
Text string `json:"text"` // textual content (multiline joined with \n)
|
||||||
|
ToolName string `json:"tool_name,omitempty"` // only for tool_use
|
||||||
|
}
|
||||||
|
|
||||||
|
// ClaudeTUIParse is the result of parsing one captured Claude TUI screen.
|
||||||
|
type ClaudeTUIParse struct {
|
||||||
|
Turns []ClaudeTurn `json:"turns"` // all visible turns in order
|
||||||
|
Answer string `json:"answer"` // assistant reply to the last user turn (like `claude -p`)
|
||||||
|
}
|
||||||
|
|
||||||
|
// ParseClaudeTUI parses the rendered text of a Claude Code TUI screen and
|
||||||
|
// extracts the conversation turns and the final assistant answer.
|
||||||
|
//
|
||||||
|
// The screen is expected to be the output of VTRender applied to a PTY
|
||||||
|
// capture of the claude CLI. Heuristics handle the welcome banner, status
|
||||||
|
// bar, progress lines and multi-line continuations.
|
||||||
|
func ParseClaudeTUI(screen string) ClaudeTUIParse {
|
||||||
|
lines := strings.Split(screen, "\n")
|
||||||
|
|
||||||
|
// --- Step 1: strip the welcome banner (box drawn with ╭...╰/╯) ---
|
||||||
|
lines = stripBanner(lines)
|
||||||
|
|
||||||
|
// --- Step 2: strip the status bar at the bottom ---
|
||||||
|
lines = stripStatusBar(lines)
|
||||||
|
|
||||||
|
// --- Step 3: collect turns from the remaining lines ---
|
||||||
|
turns := extractTurns(lines)
|
||||||
|
|
||||||
|
// --- Step 4: compute Answer from turns ---
|
||||||
|
answer := computeAnswer(turns)
|
||||||
|
|
||||||
|
return ClaudeTUIParse{Turns: turns, Answer: answer}
|
||||||
|
}
|
||||||
|
|
||||||
|
// stripBanner removes the welcome banner block from the top of the lines
|
||||||
|
// slice. The banner is a Unicode box that starts with a line containing ╭
|
||||||
|
// and ends with a line containing ╰ or ╯.
|
||||||
|
func stripBanner(lines []string) []string {
|
||||||
|
// Find a banner start (╭) in the first ~15 lines.
|
||||||
|
startIdx := -1
|
||||||
|
for i := 0; i < len(lines) && i < 15; i++ {
|
||||||
|
if strings.ContainsRune(lines[i], markerBoxTL) {
|
||||||
|
startIdx = i
|
||||||
|
break
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if startIdx < 0 {
|
||||||
|
return lines
|
||||||
|
}
|
||||||
|
|
||||||
|
// Find the matching close (╰ or ╯) after the start.
|
||||||
|
for i := startIdx; i < len(lines); i++ {
|
||||||
|
if strings.ContainsRune(lines[i], markerBoxBL) || strings.ContainsRune(lines[i], markerBoxBR) {
|
||||||
|
return lines[i+1:]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return lines
|
||||||
|
}
|
||||||
|
|
||||||
|
// isHRule returns true when the line consists mostly of ─ (U+2500) characters
|
||||||
|
// — at least 40 of them and the line has no other significant content.
|
||||||
|
func isHRule(line string) bool {
|
||||||
|
count := 0
|
||||||
|
for _, r := range line {
|
||||||
|
if r == markerHRule {
|
||||||
|
count++
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return count >= 40
|
||||||
|
}
|
||||||
|
|
||||||
|
// isStatusBarLine returns true for lines that belong to the Claude status bar
|
||||||
|
// (CTX:, IN:, OUT:, Total:, Limits:, $, "← for agents", etc.).
|
||||||
|
func isStatusBarLine(line string) bool {
|
||||||
|
trimmed := strings.TrimSpace(line)
|
||||||
|
if trimmed == "" {
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
prefixes := []string{
|
||||||
|
"CTX:", "IN:", "OUT:", "Total:", "Limits:", "$", "← for agents",
|
||||||
|
}
|
||||||
|
for _, p := range prefixes {
|
||||||
|
if strings.Contains(trimmed, p) {
|
||||||
|
return true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
|
||||||
|
// stripStatusBar removes the status bar at the bottom of the lines slice.
|
||||||
|
// Strategy: scan from the bottom upward. The footer looks like:
|
||||||
|
//
|
||||||
|
// <hrule>
|
||||||
|
// ❯ (empty prompt)
|
||||||
|
// <hrule>
|
||||||
|
// <status lines with CTX: / $0.xxx / ← for agents ...>
|
||||||
|
//
|
||||||
|
// We look for the LAST hrule that is followed by an empty-prompt line and
|
||||||
|
// another hrule, and discard everything from that hrule onward.
|
||||||
|
// Additionally, any trailing status-bar-flavored lines are dropped first.
|
||||||
|
func stripStatusBar(lines []string) []string {
|
||||||
|
if len(lines) == 0 {
|
||||||
|
return lines
|
||||||
|
}
|
||||||
|
|
||||||
|
// Trim trailing blank lines first.
|
||||||
|
end := len(lines)
|
||||||
|
for end > 0 && strings.TrimSpace(lines[end-1]) == "" {
|
||||||
|
end--
|
||||||
|
}
|
||||||
|
lines = lines[:end]
|
||||||
|
|
||||||
|
// Remove explicit status-bar lines from the bottom.
|
||||||
|
for len(lines) > 0 && isStatusBarLine(lines[len(lines)-1]) {
|
||||||
|
lines = lines[:len(lines)-1]
|
||||||
|
}
|
||||||
|
|
||||||
|
// Now find the pattern: hrule / empty-❯ / hrule and cut there.
|
||||||
|
// Scan from the bottom upward.
|
||||||
|
for i := len(lines) - 1; i >= 2; i-- {
|
||||||
|
if !isHRule(lines[i]) {
|
||||||
|
continue
|
||||||
|
}
|
||||||
|
// Check that lines[i-1] is the empty prompt "❯" (optional surrounding spaces).
|
||||||
|
mid := strings.TrimSpace(lines[i-1])
|
||||||
|
if mid != string([]rune{markerUser}) && mid != string([]rune{markerUser, ' '}) {
|
||||||
|
// Also allow a completely empty line (prompt area can be blank).
|
||||||
|
if mid != "" {
|
||||||
|
continue
|
||||||
|
}
|
||||||
|
}
|
||||||
|
// Check lines[i-2] is also an hrule.
|
||||||
|
if isHRule(lines[i-2]) {
|
||||||
|
// Cut from lines[i-2] onward.
|
||||||
|
lines = lines[:i-2]
|
||||||
|
break
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Trim trailing blank lines again after stripping.
|
||||||
|
for len(lines) > 0 && strings.TrimSpace(lines[len(lines)-1]) == "" {
|
||||||
|
lines = lines[:len(lines)-1]
|
||||||
|
}
|
||||||
|
|
||||||
|
return lines
|
||||||
|
}
|
||||||
|
|
||||||
|
// firstRune returns the first non-space rune in s, or 0 if s is blank.
|
||||||
|
func firstRune(s string) rune {
|
||||||
|
for _, r := range s {
|
||||||
|
if !unicode.IsSpace(r) {
|
||||||
|
return r
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return 0
|
||||||
|
}
|
||||||
|
|
||||||
|
// isMarkerLine returns true when the line starts with one of the recognised
|
||||||
|
// turn markers (❯, ●, ⎿, ✻).
|
||||||
|
func isMarkerLine(line string) bool {
|
||||||
|
r := firstRune(line)
|
||||||
|
return r == markerUser || r == markerAssistant || r == markerToolResult || r == markerProgress
|
||||||
|
}
|
||||||
|
|
||||||
|
// isProgressLine reports whether the line is a Claude generation status/spinner
|
||||||
|
// line (the animated "✻/✽ Word… (Ns · ↓ N tokens · esc to interrupt)" indicator).
|
||||||
|
// The glyph and the gerund word change on every frame, so it is detected by
|
||||||
|
// structure/signature, never by the specific word. These lines are noise and must
|
||||||
|
// never be folded into an assistant answer — critical when capturing frames
|
||||||
|
// mid-generation (streaming), where a different "loading" word appears each tick.
|
||||||
|
func isProgressLine(line string) bool {
|
||||||
|
r := firstRune(line)
|
||||||
|
if r == markerProgress {
|
||||||
|
return true
|
||||||
|
}
|
||||||
|
// Known turn markers are never progress, even if they end in "…".
|
||||||
|
if r == markerUser || r == markerAssistant || r == markerToolResult {
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
return reProgress.MatchString(line) || reSpinner.MatchString(line)
|
||||||
|
}
|
||||||
|
|
||||||
|
// isBreakLine reports whether the line should end an assistant/user/tool
|
||||||
|
// continuation: either a turn marker or a progress/spinner line.
|
||||||
|
func isBreakLine(line string) bool {
|
||||||
|
return isMarkerLine(line) || isProgressLine(line)
|
||||||
|
}
|
||||||
|
|
||||||
|
// textAfterMarker returns the text that follows the first occurrence of
|
||||||
|
// marker in line, trimmed of leading spaces.
|
||||||
|
func textAfterMarker(line string, marker rune) string {
|
||||||
|
idx := strings.IndexRune(line, marker)
|
||||||
|
if idx < 0 {
|
||||||
|
return ""
|
||||||
|
}
|
||||||
|
rest := line[idx+len(string(marker)):]
|
||||||
|
return strings.TrimLeft(rest, " ")
|
||||||
|
}
|
||||||
|
|
||||||
|
// extractTurns scans lines and groups them into ClaudeTurn slices.
|
||||||
|
func extractTurns(lines []string) []ClaudeTurn {
|
||||||
|
var turns []ClaudeTurn
|
||||||
|
|
||||||
|
i := 0
|
||||||
|
for i < len(lines) {
|
||||||
|
line := lines[i]
|
||||||
|
|
||||||
|
// Progress/spinner lines are noise in any position — skip early so they
|
||||||
|
// are never folded into an assistant continuation (matters for streaming).
|
||||||
|
if isProgressLine(line) {
|
||||||
|
i++
|
||||||
|
continue
|
||||||
|
}
|
||||||
|
|
||||||
|
r := firstRune(line)
|
||||||
|
|
||||||
|
switch r {
|
||||||
|
case markerProgress:
|
||||||
|
// ✻ lines are noise — skip (also covered by isProgressLine above).
|
||||||
|
i++
|
||||||
|
|
||||||
|
case markerUser:
|
||||||
|
text := textAfterMarker(line, markerUser)
|
||||||
|
if text == "" {
|
||||||
|
// Empty prompt — skip.
|
||||||
|
i++
|
||||||
|
continue
|
||||||
|
}
|
||||||
|
// Collect continuation lines (indented, non-marker, non-empty).
|
||||||
|
i++
|
||||||
|
for i < len(lines) {
|
||||||
|
cont := lines[i]
|
||||||
|
if isBreakLine(cont) || strings.TrimSpace(cont) == "" {
|
||||||
|
break
|
||||||
|
}
|
||||||
|
text += "\n" + strings.TrimRight(cont, " ")
|
||||||
|
i++
|
||||||
|
}
|
||||||
|
turns = append(turns, ClaudeTurn{Role: ClaudeTurnUser, Text: strings.TrimRight(text, " ")})
|
||||||
|
|
||||||
|
case markerAssistant:
|
||||||
|
body := textAfterMarker(line, markerAssistant)
|
||||||
|
i++
|
||||||
|
|
||||||
|
// Determine if this is a tool_use or assistant text.
|
||||||
|
if m := reToolUse.FindStringSubmatch(body); m != nil {
|
||||||
|
// tool_use — do NOT collect continuation lines.
|
||||||
|
turns = append(turns, ClaudeTurn{
|
||||||
|
Role: ClaudeTurnToolUse,
|
||||||
|
Text: body,
|
||||||
|
ToolName: m[1],
|
||||||
|
})
|
||||||
|
} else {
|
||||||
|
// assistant text — collect continuation lines.
|
||||||
|
for i < len(lines) {
|
||||||
|
cont := lines[i]
|
||||||
|
if isBreakLine(cont) {
|
||||||
|
break
|
||||||
|
}
|
||||||
|
trimmed := strings.TrimSpace(cont)
|
||||||
|
if trimmed == "" {
|
||||||
|
// A single blank line may separate paragraphs; peek ahead.
|
||||||
|
// If the next non-blank line is also a continuation, keep it.
|
||||||
|
j := i + 1
|
||||||
|
for j < len(lines) && strings.TrimSpace(lines[j]) == "" {
|
||||||
|
j++
|
||||||
|
}
|
||||||
|
if j < len(lines) && !isBreakLine(lines[j]) {
|
||||||
|
// Include the blank line(s) as paragraph separator.
|
||||||
|
body += "\n"
|
||||||
|
i = j
|
||||||
|
continue
|
||||||
|
}
|
||||||
|
break
|
||||||
|
}
|
||||||
|
body += "\n" + strings.TrimRight(cont, " ")
|
||||||
|
i++
|
||||||
|
}
|
||||||
|
turns = append(turns, ClaudeTurn{
|
||||||
|
Role: ClaudeTurnAssistant,
|
||||||
|
Text: strings.TrimRight(body, " \n"),
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
case markerToolResult:
|
||||||
|
text := textAfterMarker(line, markerToolResult)
|
||||||
|
// Also accept └ as alias (some terminals substitute).
|
||||||
|
if text == "" {
|
||||||
|
text = textAfterMarker(line, '└')
|
||||||
|
}
|
||||||
|
i++
|
||||||
|
// Collect continuation lines for the tool result.
|
||||||
|
for i < len(lines) {
|
||||||
|
cont := lines[i]
|
||||||
|
if isBreakLine(cont) || strings.TrimSpace(cont) == "" {
|
||||||
|
break
|
||||||
|
}
|
||||||
|
text += "\n" + strings.TrimRight(cont, " ")
|
||||||
|
i++
|
||||||
|
}
|
||||||
|
turns = append(turns, ClaudeTurn{
|
||||||
|
Role: ClaudeTurnToolResult,
|
||||||
|
Text: strings.TrimRight(text, " "),
|
||||||
|
})
|
||||||
|
|
||||||
|
default:
|
||||||
|
// Blank or unrecognised line — skip.
|
||||||
|
i++
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
return turns
|
||||||
|
}
|
||||||
|
|
||||||
|
// computeAnswer finds the last user turn and concatenates all assistant
|
||||||
|
// (non-tool_use, non-tool_result) turns that follow it.
|
||||||
|
// If there is no user turn, concatenates all assistant turns.
|
||||||
|
func computeAnswer(turns []ClaudeTurn) string {
|
||||||
|
lastUserIdx := -1
|
||||||
|
for i, t := range turns {
|
||||||
|
if t.Role == ClaudeTurnUser {
|
||||||
|
lastUserIdx = i
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
var parts []string
|
||||||
|
start := 0
|
||||||
|
if lastUserIdx >= 0 {
|
||||||
|
start = lastUserIdx + 1
|
||||||
|
}
|
||||||
|
for _, t := range turns[start:] {
|
||||||
|
if t.Role == ClaudeTurnAssistant {
|
||||||
|
parts = append(parts, t.Text)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return strings.TrimSpace(strings.Join(parts, "\n"))
|
||||||
|
}
|
||||||
@@ -0,0 +1,67 @@
|
|||||||
|
---
|
||||||
|
name: parse_claude_tui
|
||||||
|
kind: function
|
||||||
|
lang: go
|
||||||
|
domain: tui
|
||||||
|
version: "1.0.0"
|
||||||
|
purity: pure
|
||||||
|
signature: "func ParseClaudeTUI(screen string) ClaudeTUIParse"
|
||||||
|
description: "Parsea el texto renderizado de la pantalla de la TUI de Claude Code y extrae los turnos de la conversación (user, assistant, tool_use, tool_result) y la respuesta final del asistente. Equivalente a lo que devolvería `claude -p` pero operando sobre el render visual."
|
||||||
|
tags: [terminal-capture, claude, tui, parse, conversation]
|
||||||
|
uses_functions:
|
||||||
|
- vt_render_go_tui
|
||||||
|
uses_types:
|
||||||
|
- claude_turn_go_tui
|
||||||
|
- claude_tui_parse_go_tui
|
||||||
|
returns:
|
||||||
|
- claude_tui_parse_go_tui
|
||||||
|
returns_optional: false
|
||||||
|
error_type: ""
|
||||||
|
imports: []
|
||||||
|
params:
|
||||||
|
- name: screen
|
||||||
|
desc: "Texto renderizado de la pantalla de la TUI de Claude Code, producido por VTRender(raw, rows, cols). Debe incluir el contenido visible completo: banner opcional, conversación y status bar opcional."
|
||||||
|
output: "ClaudeTUIParse con los turnos visibles en orden (Role, Text, ToolName) y Answer — la concatenación de los bloques assistant que siguen al último turno user, equivalente al output de `claude -p`."
|
||||||
|
tested: true
|
||||||
|
tests:
|
||||||
|
- "golden screen — banner + status bar + single Q&A"
|
||||||
|
- "multiline assistant response"
|
||||||
|
- "tool_use + tool_result + final assistant text"
|
||||||
|
- "multi-turn — answer from last user only"
|
||||||
|
- "no banner no status bar — minimal screen"
|
||||||
|
- "determinism — same input produces same output"
|
||||||
|
test_file_path: "functions/tui/parse_claude_tui_test.go"
|
||||||
|
file_path: "functions/tui/parse_claude_tui.go"
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ejemplo
|
||||||
|
|
||||||
|
```go
|
||||||
|
// Pipeline completo: PTY capture → VTRender → ParseClaudeTUI → usar .Answer
|
||||||
|
import (
|
||||||
|
"fmt"
|
||||||
|
"fn-registry/functions/infra"
|
||||||
|
"fn-registry/functions/tui"
|
||||||
|
)
|
||||||
|
|
||||||
|
raw, _ := infra.PtyCaptureIdle("claude", []string{}, 40, 220, 8000)
|
||||||
|
screen := tui.VTRender(raw, 40, 220)
|
||||||
|
result := tui.ParseClaudeTUI(screen)
|
||||||
|
|
||||||
|
fmt.Println(result.Answer) // imprime la respuesta final del asistente
|
||||||
|
|
||||||
|
for _, turn := range result.Turns {
|
||||||
|
fmt.Printf("[%s] %s\n", turn.Role, turn.Text)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cuando usarla
|
||||||
|
|
||||||
|
Cuando captures la TUI de `claude` con `pty_capture_idle_go_infra` + `vt_render_go_tui` y necesites extraer la respuesta como dato estructurado (equivalente a `claude -p`) en vez de procesar el render visual crudo. Úsala para agentes que lanzan `claude` como subproceso TUI y quieren leer la respuesta sin requerir modo headless.
|
||||||
|
|
||||||
|
## Gotchas
|
||||||
|
|
||||||
|
- **Heurístico y dependiente del layout de la TUI de Claude Code**: si Claude cambia los marcadores (`❯`, `●`, `⎿`, `✻`) o el formato del banner/status-bar, el parser puede dejar de funcionar sin aviso.
|
||||||
|
- **Solo ve lo visible en el grid**: `VTRender` reconstruye únicamente lo que cabe en el terminal emulado (rows × cols). Respuestas largas que hacen scroll hacia arriba se truncan por arriba — no hay scrollback. Para respuestas largas, aumentar `rows` en `VTRender` o usar `claude -p` directamente.
|
||||||
|
- **tool_use/tool_result best-effort**: la TUI colapsa algunos bloques de herramientas. Los `ToolName` y textos de `tool_result` pueden quedar incompletos si la TUI los trunca con `…`.
|
||||||
|
- **Answer asume captura post-respuesta**: `PtyCaptureIdle` debe haberse disparado DESPUÉS de que la respuesta terminó de renderizarse (el spinner `✻` desapareció). Si se captura durante el streaming, `Answer` puede estar incompleto.
|
||||||
@@ -0,0 +1,214 @@
|
|||||||
|
package tui
|
||||||
|
|
||||||
|
import (
|
||||||
|
"testing"
|
||||||
|
)
|
||||||
|
|
||||||
|
// goldenScreen is the exact sample screen from the spec.
|
||||||
|
const goldenScreen = `╭─── Claude Code v2.1.161 ─────────────────────────────────────────────────────────────────────────────────────────────╮
|
||||||
|
│ │ Tips for getting started │
|
||||||
|
│ Welcome back Enmanuel! │ Run /init to create a CLAUDE.md file with instructions for Cla… │
|
||||||
|
│ │ ─────────────────────────────────────────────────────────────── │
|
||||||
|
│ ▐▛███▜▌ │ What's new │
|
||||||
|
│ ▝▜█████▛▘ │ ` + "`OTEL_RESOURCE_ATTRIBUTES`" + ` values are now included as labels o… │
|
||||||
|
│ ▘▘ ▝▝ │ ` + "`claude agents`" + ` rows now show ` + "`done/total`" + ` before the detail w… │
|
||||||
|
│ Opus 4.8 (1M context) with xh… · Claude Max · │ ` + "`/mcp`" + ` now collapses claude.ai connectors you've never signed … │
|
||||||
|
│ gutierenmanuel15@gmail.com's Organization │ /release-notes for more │
|
||||||
|
│ ~/fn_registry │ │
|
||||||
|
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
|
||||||
|
|
||||||
|
|
||||||
|
❯ responde unicamente con la palabra PONG, sin explicaciones
|
||||||
|
|
||||||
|
● PONG
|
||||||
|
|
||||||
|
✻ Crunched for 2s
|
||||||
|
|
||||||
|
|
||||||
|
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
|
||||||
|
❯
|
||||||
|
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
|
||||||
|
Opus 4.8 (1M context) │ CTX: █░░░░░░░░░ 11% (107k/1.0M) │ IN:6k OUT:5 (cache:17k) │ ⎇ master [~4 ?28 ↑1] │ 22:26
|
||||||
|
$0.565 │ +0/-0 │ Total: ↓107k/↑5 │ Limits: 5h:6% →02:40 │ 7d:11% →Sun 17:00 │ ⏱ 7s │ ~/fn_registry
|
||||||
|
← for agents`
|
||||||
|
|
||||||
|
func TestParseClaudeTUI(t *testing.T) {
|
||||||
|
t.Run("golden screen — banner + status bar + single Q&A", func(t *testing.T) {
|
||||||
|
got := ParseClaudeTUI(goldenScreen)
|
||||||
|
|
||||||
|
if got.Answer != "PONG" {
|
||||||
|
t.Errorf("Answer = %q, want %q", got.Answer, "PONG")
|
||||||
|
}
|
||||||
|
if len(got.Turns) != 2 {
|
||||||
|
t.Errorf("len(Turns) = %d, want 2", len(got.Turns))
|
||||||
|
for i, turn := range got.Turns {
|
||||||
|
t.Logf(" Turns[%d]: role=%s text=%q", i, turn.Role, turn.Text)
|
||||||
|
}
|
||||||
|
return
|
||||||
|
}
|
||||||
|
if got.Turns[0].Role != ClaudeTurnUser {
|
||||||
|
t.Errorf("Turns[0].Role = %q, want %q", got.Turns[0].Role, ClaudeTurnUser)
|
||||||
|
}
|
||||||
|
wantUserText := "responde unicamente con la palabra PONG, sin explicaciones"
|
||||||
|
if got.Turns[0].Text != wantUserText {
|
||||||
|
t.Errorf("Turns[0].Text = %q, want %q", got.Turns[0].Text, wantUserText)
|
||||||
|
}
|
||||||
|
if got.Turns[1].Role != ClaudeTurnAssistant {
|
||||||
|
t.Errorf("Turns[1].Role = %q, want %q", got.Turns[1].Role, ClaudeTurnAssistant)
|
||||||
|
}
|
||||||
|
if got.Turns[1].Text != "PONG" {
|
||||||
|
t.Errorf("Turns[1].Text = %q, want %q", got.Turns[1].Text, "PONG")
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("multiline assistant response", func(t *testing.T) {
|
||||||
|
screen := `❯ explica brevemente
|
||||||
|
|
||||||
|
● linea uno
|
||||||
|
linea dos`
|
||||||
|
got := ParseClaudeTUI(screen)
|
||||||
|
if len(got.Turns) != 2 {
|
||||||
|
t.Fatalf("len(Turns) = %d, want 2; turns: %+v", len(got.Turns), got.Turns)
|
||||||
|
}
|
||||||
|
wantText := "linea uno\nlinea dos"
|
||||||
|
if got.Turns[1].Text != wantText {
|
||||||
|
t.Errorf("Turns[1].Text = %q, want %q", got.Turns[1].Text, wantText)
|
||||||
|
}
|
||||||
|
if !contains(got.Answer, "linea uno") || !contains(got.Answer, "linea dos") {
|
||||||
|
t.Errorf("Answer %q should contain both continuation lines", got.Answer)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("tool_use + tool_result + final assistant text", func(t *testing.T) {
|
||||||
|
screen := `❯ pregunta
|
||||||
|
|
||||||
|
● Read(main.go)
|
||||||
|
|
||||||
|
⎿ Read 50 lines
|
||||||
|
|
||||||
|
● aqui esta el resumen`
|
||||||
|
got := ParseClaudeTUI(screen)
|
||||||
|
|
||||||
|
if len(got.Turns) != 4 {
|
||||||
|
t.Fatalf("len(Turns) = %d, want 4; turns: %+v", len(got.Turns), got.Turns)
|
||||||
|
}
|
||||||
|
if got.Turns[0].Role != ClaudeTurnUser {
|
||||||
|
t.Errorf("Turns[0].Role = %q", got.Turns[0].Role)
|
||||||
|
}
|
||||||
|
if got.Turns[1].Role != ClaudeTurnToolUse {
|
||||||
|
t.Errorf("Turns[1].Role = %q, want tool_use", got.Turns[1].Role)
|
||||||
|
}
|
||||||
|
if got.Turns[1].ToolName != "Read" {
|
||||||
|
t.Errorf("Turns[1].ToolName = %q, want Read", got.Turns[1].ToolName)
|
||||||
|
}
|
||||||
|
if got.Turns[2].Role != ClaudeTurnToolResult {
|
||||||
|
t.Errorf("Turns[2].Role = %q, want tool_result", got.Turns[2].Role)
|
||||||
|
}
|
||||||
|
if got.Turns[3].Role != ClaudeTurnAssistant {
|
||||||
|
t.Errorf("Turns[3].Role = %q, want assistant", got.Turns[3].Role)
|
||||||
|
}
|
||||||
|
// Answer must be ONLY the assistant text, not the tool_use.
|
||||||
|
if got.Answer != "aqui esta el resumen" {
|
||||||
|
t.Errorf("Answer = %q, want %q", got.Answer, "aqui esta el resumen")
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("multi-turn — answer from last user only", func(t *testing.T) {
|
||||||
|
screen := `❯ primera pregunta
|
||||||
|
|
||||||
|
● primera respuesta
|
||||||
|
|
||||||
|
❯ segunda pregunta
|
||||||
|
|
||||||
|
● segunda respuesta`
|
||||||
|
got := ParseClaudeTUI(screen)
|
||||||
|
if len(got.Turns) != 4 {
|
||||||
|
t.Fatalf("len(Turns) = %d, want 4; turns: %+v", len(got.Turns), got.Turns)
|
||||||
|
}
|
||||||
|
if got.Answer != "segunda respuesta" {
|
||||||
|
t.Errorf("Answer = %q, want %q", got.Answer, "segunda respuesta")
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("no banner no status bar — minimal screen", func(t *testing.T) {
|
||||||
|
screen := "❯ hola\n\n● mundo"
|
||||||
|
got := ParseClaudeTUI(screen)
|
||||||
|
if len(got.Turns) != 2 {
|
||||||
|
t.Fatalf("len(Turns) = %d, want 2; turns: %+v", len(got.Turns), got.Turns)
|
||||||
|
}
|
||||||
|
if got.Answer != "mundo" {
|
||||||
|
t.Errorf("Answer = %q, want %q", got.Answer, "mundo")
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("determinism — same input produces same output", func(t *testing.T) {
|
||||||
|
first := ParseClaudeTUI(goldenScreen)
|
||||||
|
second := ParseClaudeTUI(goldenScreen)
|
||||||
|
if first.Answer != second.Answer {
|
||||||
|
t.Errorf("non-deterministic: %q != %q", first.Answer, second.Answer)
|
||||||
|
}
|
||||||
|
if len(first.Turns) != len(second.Turns) {
|
||||||
|
t.Errorf("non-deterministic turns count: %d != %d", len(first.Turns), len(second.Turns))
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
// TestParseClaudeTUI_Spinner verifies that the generation spinner — which shows a
|
||||||
|
// DIFFERENT random gerund word on every frame ("Whatchamacalliting", "Forging",
|
||||||
|
// "Puzzling", "Crunched"...) — is never folded into the answer, regardless of the
|
||||||
|
// word, the glyph, or whether the "(Ns · tokens)" suffix is present yet.
|
||||||
|
func TestParseClaudeTUI_Spinner(t *testing.T) {
|
||||||
|
cases := []struct {
|
||||||
|
name string
|
||||||
|
screen string
|
||||||
|
want string
|
||||||
|
}{
|
||||||
|
{
|
||||||
|
name: "spinner with tokens suffix glued after answer",
|
||||||
|
screen: "❯ di PONG\n\n● PONG\n\n✽ Whatchamacalliting… (2s · ↓ 1 tokens · esc to interrupt)\n",
|
||||||
|
want: "PONG",
|
||||||
|
},
|
||||||
|
{
|
||||||
|
name: "spinner early frame, no suffix yet, different word",
|
||||||
|
screen: "❯ di HOLA\n\n● HOLA\n\n✶ Puzzling…\n",
|
||||||
|
want: "HOLA",
|
||||||
|
},
|
||||||
|
{
|
||||||
|
name: "classic crunched line",
|
||||||
|
screen: "❯ x\n\n● respuesta\n\n✻ Crunched for 4s\n",
|
||||||
|
want: "respuesta",
|
||||||
|
},
|
||||||
|
{
|
||||||
|
name: "spinner BEFORE the answer block (mid-generation snapshot)",
|
||||||
|
screen: "❯ pregunta\n\n✽ Forging… (1s · ↑ 3 tokens · esc to interrupt)\n\n● respuesta parcial\n",
|
||||||
|
want: "respuesta parcial",
|
||||||
|
},
|
||||||
|
{
|
||||||
|
name: "assistant line ending in ellipsis is NOT treated as spinner",
|
||||||
|
screen: "❯ x\n\n● la historia continua…\n",
|
||||||
|
want: "la historia continua…",
|
||||||
|
},
|
||||||
|
}
|
||||||
|
for _, tc := range cases {
|
||||||
|
t.Run(tc.name, func(t *testing.T) {
|
||||||
|
got := ParseClaudeTUI(tc.screen)
|
||||||
|
if got.Answer != tc.want {
|
||||||
|
t.Errorf("Answer = %q, want %q", got.Answer, tc.want)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func contains(s, sub string) bool {
|
||||||
|
return len(sub) == 0 || (len(s) >= len(sub) && (s == sub ||
|
||||||
|
len(s) > 0 && containsStr(s, sub)))
|
||||||
|
}
|
||||||
|
|
||||||
|
func containsStr(s, sub string) bool {
|
||||||
|
for i := 0; i <= len(s)-len(sub); i++ {
|
||||||
|
if s[i:i+len(sub)] == sub {
|
||||||
|
return true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return false
|
||||||
|
}
|
||||||
@@ -0,0 +1,54 @@
|
|||||||
|
package tui
|
||||||
|
|
||||||
|
import (
|
||||||
|
"strings"
|
||||||
|
|
||||||
|
"github.com/hinshun/vt10x"
|
||||||
|
)
|
||||||
|
|
||||||
|
// VTRender emulates a terminal of size cols×rows, feeds raw into it,
|
||||||
|
// and returns the resulting screen as plain text preserving the visual layout.
|
||||||
|
//
|
||||||
|
// Unlike strip_ansi which removes escape sequences from sequential output,
|
||||||
|
// VTRender correctly handles TUIs that use absolute cursor positioning
|
||||||
|
// (ESC[row;colH, ESC[colG, etc.) by maintaining a 2D grid and reconstructing
|
||||||
|
// real spaces between columns.
|
||||||
|
//
|
||||||
|
// Defaults: rows<=0 → 40, cols<=0 → 120.
|
||||||
|
// Trailing spaces on each line are trimmed. Trailing empty lines are removed.
|
||||||
|
func VTRender(raw string, rows, cols int) string {
|
||||||
|
if rows <= 0 {
|
||||||
|
rows = 40
|
||||||
|
}
|
||||||
|
if cols <= 0 {
|
||||||
|
cols = 120
|
||||||
|
}
|
||||||
|
|
||||||
|
// Create a fresh terminal emulator for each call — no shared state.
|
||||||
|
term := vt10x.New(vt10x.WithSize(cols, rows))
|
||||||
|
term.Write([]byte(raw)) //nolint:errcheck // Write on vt10x never returns a meaningful error
|
||||||
|
|
||||||
|
// String() returns all rows joined by '\n', one row per terminal line.
|
||||||
|
// Each row is exactly `cols` runes wide (padded with NUL/space for empty cells).
|
||||||
|
raw = term.String()
|
||||||
|
|
||||||
|
lines := strings.Split(raw, "\n")
|
||||||
|
|
||||||
|
// Trim trailing spaces from every line (cells that were never written
|
||||||
|
// contain NUL '\x00' in some versions, so we trim both NUL and space).
|
||||||
|
for i, line := range lines {
|
||||||
|
// Replace NUL characters (unwritten cells) with spaces first.
|
||||||
|
line = strings.ReplaceAll(line, "\x00", " ")
|
||||||
|
lines[i] = strings.TrimRight(line, " ")
|
||||||
|
}
|
||||||
|
|
||||||
|
// Remove trailing empty lines — the TUI probably only used the top portion
|
||||||
|
// of the grid. Keep intermediate empty lines (real visual separators).
|
||||||
|
last := len(lines) - 1
|
||||||
|
for last >= 0 && lines[last] == "" {
|
||||||
|
last--
|
||||||
|
}
|
||||||
|
lines = lines[:last+1]
|
||||||
|
|
||||||
|
return strings.Join(lines, "\n")
|
||||||
|
}
|
||||||
@@ -0,0 +1,64 @@
|
|||||||
|
---
|
||||||
|
name: vt_render
|
||||||
|
kind: function
|
||||||
|
lang: go
|
||||||
|
domain: tui
|
||||||
|
version: "1.0.0"
|
||||||
|
purity: pure
|
||||||
|
signature: "func VTRender(raw string, rows, cols int) string"
|
||||||
|
description: "Emula un terminal virtual de tamaño cols×rows, alimenta raw (stream con secuencias ANSI/VT100 incluyendo posicionamiento absoluto de cursor) y devuelve el estado final de la pantalla como texto plano que preserva el layout visual. A diferencia de strip_ansi, reconstruye espacios reales entre columnas posicionadas con movimientos de cursor absolutos."
|
||||||
|
tags: ["terminal", "vt100", "tui", "render", "ansi", "screen", "terminal-capture"]
|
||||||
|
uses_functions: []
|
||||||
|
uses_types: []
|
||||||
|
returns: []
|
||||||
|
returns_optional: false
|
||||||
|
error_type: ""
|
||||||
|
imports:
|
||||||
|
- "github.com/hinshun/vt10x"
|
||||||
|
- "strings"
|
||||||
|
tested: true
|
||||||
|
tests:
|
||||||
|
- "layout absoluto basico A y B separados por movimiento de cursor"
|
||||||
|
- "dos palabras separadas por movimiento de columna no aparecen pegadas"
|
||||||
|
- "texto multilinea simple con CRLF"
|
||||||
|
- "trim de filas vacias al final de grid grande"
|
||||||
|
- "determinismo misma entrada misma salida"
|
||||||
|
- "defaults rows y cols al pasar cero"
|
||||||
|
test_file_path: "functions/tui/vt_render_test.go"
|
||||||
|
file_path: "functions/tui/vt_render.go"
|
||||||
|
params:
|
||||||
|
- name: raw
|
||||||
|
desc: "Stream crudo de bytes de terminal, con secuencias de escape ANSI/VT100 intactas (colores, cursor moves, borrados de línea, scroll). Típicamente la salida de pty_capture_idle_go_infra."
|
||||||
|
- name: rows
|
||||||
|
desc: "Número de filas del terminal virtual. Debe coincidir con el tamaño de PTY usado al capturar. Si <=0 usa 40 como default."
|
||||||
|
- name: cols
|
||||||
|
desc: "Número de columnas del terminal virtual. Debe coincidir con el ancho de PTY usado al capturar. Si <=0 usa 120 como default."
|
||||||
|
output: "Texto plano multilínea con el layout visual de la pantalla: espacios reales entre columnas, sin trailing spaces por línea, sin filas vacías finales. Las líneas vacías intermedias se conservan (son separación visual real)."
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ejemplo
|
||||||
|
|
||||||
|
```go
|
||||||
|
// Capturar output crudo de una TUI (ej. claude CLI) con el PTY del mismo tamaño.
|
||||||
|
raw, _ := pty_capture_idle("claude", []string{"--help"}, 40, 120, 2*time.Second, 10*time.Second)
|
||||||
|
|
||||||
|
// Renderizar el grid final como texto plano.
|
||||||
|
screen := tui.VTRender(raw, 40, 120)
|
||||||
|
fmt.Println(screen)
|
||||||
|
// Salida: texto con columnas alineadas, igual a lo que se vería en pantalla.
|
||||||
|
// Ejemplo real: "foo bar" si foo y bar estaban separados por ESC[10G.
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cuando usarla
|
||||||
|
|
||||||
|
Úsala cuando captures el output crudo de una TUI con layout absoluto (claude CLI, htop, dialog, ncurses) y `strip_ansi_go_core` te deje las palabras pegadas (ej. "2newMCPservers"). Contrasta con `strip_ansi_go_core` y `strip_ansi_go_tui`, que sirven para output secuencial tipo logs donde no hay movimientos de cursor absolutos. Si el stream tiene `ESC[row;colH` o `ESC[colG`, este es el correcto.
|
||||||
|
|
||||||
|
Librería emuladora usada: `github.com/hinshun/vt10x` (vt10x v0.0.0-20220301184237-5011da428d02). Implementa VT10x completo sin CGO. API: `vt10x.New(vt10x.WithSize(cols, rows))` + `Write([]byte)` + `String()`.
|
||||||
|
|
||||||
|
## Gotchas
|
||||||
|
|
||||||
|
- **Tamaño debe coincidir**: rows×cols deben ser iguales a los que se usaron al capturar (pty_capture_idle usa 40×120 por defecto). Si no coinciden, el wrapping del texto no cuadra y las columnas se descuadran.
|
||||||
|
- **Solo texto, sin color**: la función vuelca únicamente los caracteres (rune de cada celda). Los atributos de color se pierden — es texto plano.
|
||||||
|
- **Solo estado final del grid**: si la TUI hizo scroll durante su ejecución, solo se ve el estado final de las 40 filas visibles. El historial de scroll no está disponible.
|
||||||
|
- **Emojis y caracteres de doble ancho**: algunos caracteres Unicode (emojis, CJK) ocupan 2 columnas visualmente pero solo 1 celda en el grid de vt10x, lo que puede descuadrar columnas en TUIs que los usan.
|
||||||
|
- **NUL en celdas vacías**: las celdas no escritas contienen `\x00` en algunas versiones del emulador. La función los reemplaza por espacio antes del trim, pero si el raw contiene NUL intencional, se trataría como espacio.
|
||||||
@@ -0,0 +1,114 @@
|
|||||||
|
package tui
|
||||||
|
|
||||||
|
import (
|
||||||
|
"strings"
|
||||||
|
"testing"
|
||||||
|
)
|
||||||
|
|
||||||
|
func TestVTRender(t *testing.T) {
|
||||||
|
t.Run("layout absoluto basico A y B separados por movimiento de cursor", func(t *testing.T) {
|
||||||
|
// ESC[1;5H mueve el cursor a fila 1 columna 5 (1-indexed).
|
||||||
|
// Resultado esperado: 'A' en col 1, espacios, 'B' en col 5.
|
||||||
|
out := VTRender("A\x1b[1;5HB", 2, 10)
|
||||||
|
lines := strings.Split(out, "\n")
|
||||||
|
if len(lines) == 0 {
|
||||||
|
t.Fatalf("resultado vacio")
|
||||||
|
}
|
||||||
|
first := lines[0]
|
||||||
|
if len(first) < 5 {
|
||||||
|
t.Fatalf("linea demasiado corta: %q", first)
|
||||||
|
}
|
||||||
|
if first[0] != 'A' {
|
||||||
|
t.Errorf("esperaba 'A' en columna 0, got %q en linea %q", string(first[0]), first)
|
||||||
|
}
|
||||||
|
if first[4] != 'B' {
|
||||||
|
t.Errorf("esperaba 'B' en columna 4 (0-indexed), got %q en linea %q", string(first[4]), first)
|
||||||
|
}
|
||||||
|
// Verificar que hay espacios entre A y B (no están pegadas).
|
||||||
|
if strings.Contains(first, "AB") {
|
||||||
|
t.Errorf("A y B estan pegadas en %q, deberían estar separadas", first)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("dos palabras separadas por movimiento de columna no aparecen pegadas", func(t *testing.T) {
|
||||||
|
// ESC[10G mueve el cursor a la columna 10 (1-indexed) de la línea actual.
|
||||||
|
out := VTRender("foo\x1b[10Gbar", 2, 20)
|
||||||
|
lines := strings.Split(out, "\n")
|
||||||
|
if len(lines) == 0 {
|
||||||
|
t.Fatalf("resultado vacio")
|
||||||
|
}
|
||||||
|
first := lines[0]
|
||||||
|
if strings.Contains(first, "foobar") {
|
||||||
|
t.Errorf("foo y bar estan pegadas: %q — esperaba espacios entre ellas", first)
|
||||||
|
}
|
||||||
|
if !strings.Contains(first, "foo") {
|
||||||
|
t.Errorf("no encontre 'foo' en %q", first)
|
||||||
|
}
|
||||||
|
if !strings.Contains(first, "bar") {
|
||||||
|
t.Errorf("no encontre 'bar' en %q", first)
|
||||||
|
}
|
||||||
|
// foo en col 0-2, bar en col 9-11 (columna 10 es 0-indexed 9).
|
||||||
|
if len(first) < 12 {
|
||||||
|
t.Fatalf("linea demasiado corta para verificar: %q", first)
|
||||||
|
}
|
||||||
|
// Debe haber al menos un espacio entre foo y bar.
|
||||||
|
fooEnd := strings.Index(first, "foo") + 3
|
||||||
|
barStart := strings.Index(first, "bar")
|
||||||
|
if barStart <= fooEnd {
|
||||||
|
t.Errorf("bar empieza en %d pero foo termina en %d — sin separacion en %q", barStart, fooEnd, first)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("texto multilinea simple con CRLF", func(t *testing.T) {
|
||||||
|
out := VTRender("linea1\r\nlinea2", 5, 40)
|
||||||
|
if !strings.Contains(out, "linea1") {
|
||||||
|
t.Errorf("no encontre 'linea1' en %q", out)
|
||||||
|
}
|
||||||
|
if !strings.Contains(out, "linea2") {
|
||||||
|
t.Errorf("no encontre 'linea2' en %q", out)
|
||||||
|
}
|
||||||
|
lines := strings.Split(out, "\n")
|
||||||
|
// linea1 y linea2 deben estar en líneas distintas.
|
||||||
|
found1, found2 := -1, -1
|
||||||
|
for i, l := range lines {
|
||||||
|
if strings.Contains(l, "linea1") {
|
||||||
|
found1 = i
|
||||||
|
}
|
||||||
|
if strings.Contains(l, "linea2") {
|
||||||
|
found2 = i
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if found1 == found2 {
|
||||||
|
t.Errorf("linea1 y linea2 estan en la misma linea (%d) de la salida: %q", found1, out)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("trim de filas vacias al final de grid grande", func(t *testing.T) {
|
||||||
|
// Input corto en un grid de 40 filas — no debe producir 40 lineas.
|
||||||
|
out := VTRender("hola", 40, 120)
|
||||||
|
count := strings.Count(out, "\n")
|
||||||
|
if count >= 3 {
|
||||||
|
t.Errorf("demasiadas lineas (%d) para 'hola' en grid de 40 filas: %q", count, out)
|
||||||
|
}
|
||||||
|
if !strings.Contains(out, "hola") {
|
||||||
|
t.Errorf("no encontre 'hola' en %q", out)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("determinismo misma entrada misma salida", func(t *testing.T) {
|
||||||
|
input := "foo\x1b[10Gbar\r\n\x1b[2;1Hbaz"
|
||||||
|
out1 := VTRender(input, 10, 40)
|
||||||
|
out2 := VTRender(input, 10, 40)
|
||||||
|
if out1 != out2 {
|
||||||
|
t.Errorf("resultados distintos:\nout1=%q\nout2=%q", out1, out2)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
t.Run("defaults rows y cols al pasar cero", func(t *testing.T) {
|
||||||
|
// Verificar que no entra en pánico con valores <= 0.
|
||||||
|
out := VTRender("test", 0, 0)
|
||||||
|
if !strings.Contains(out, "test") {
|
||||||
|
t.Errorf("no encontre 'test' con defaults (rows=0,cols=0): %q", out)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
@@ -40,6 +40,7 @@ require (
|
|||||||
github.com/clipperhouse/displaywidth v0.9.0 // indirect
|
github.com/clipperhouse/displaywidth v0.9.0 // indirect
|
||||||
github.com/clipperhouse/stringish v0.1.1 // indirect
|
github.com/clipperhouse/stringish v0.1.1 // indirect
|
||||||
github.com/clipperhouse/uax29/v2 v2.5.0 // indirect
|
github.com/clipperhouse/uax29/v2 v2.5.0 // indirect
|
||||||
|
github.com/creack/pty v1.1.24 // indirect
|
||||||
github.com/danieljoos/wincred v1.2.3 // indirect
|
github.com/danieljoos/wincred v1.2.3 // indirect
|
||||||
github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
|
github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
|
||||||
github.com/go-faster/city v1.0.1 // indirect
|
github.com/go-faster/city v1.0.1 // indirect
|
||||||
@@ -49,6 +50,7 @@ require (
|
|||||||
github.com/godbus/dbus/v5 v5.2.2 // indirect
|
github.com/godbus/dbus/v5 v5.2.2 // indirect
|
||||||
github.com/google/flatbuffers v25.1.24+incompatible // indirect
|
github.com/google/flatbuffers v25.1.24+incompatible // indirect
|
||||||
github.com/gorilla/css v1.0.1 // indirect
|
github.com/gorilla/css v1.0.1 // indirect
|
||||||
|
github.com/hinshun/vt10x v0.0.0-20220301184237-5011da428d02 // indirect
|
||||||
github.com/jackc/pgpassfile v1.0.0 // indirect
|
github.com/jackc/pgpassfile v1.0.0 // indirect
|
||||||
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
|
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
|
||||||
github.com/jackc/puddle/v2 v2.2.2 // indirect
|
github.com/jackc/puddle/v2 v2.2.2 // indirect
|
||||||
|
|||||||
@@ -40,6 +40,8 @@ github.com/clipperhouse/stringish v0.1.1 h1:+NSqMOr3GR6k1FdRhhnXrLfztGzuG+VuFDfa
|
|||||||
github.com/clipperhouse/stringish v0.1.1/go.mod h1:v/WhFtE1q0ovMta2+m+UbpZ+2/HEXNWYXQgCt4hdOzA=
|
github.com/clipperhouse/stringish v0.1.1/go.mod h1:v/WhFtE1q0ovMta2+m+UbpZ+2/HEXNWYXQgCt4hdOzA=
|
||||||
github.com/clipperhouse/uax29/v2 v2.5.0 h1:x7T0T4eTHDONxFJsL94uKNKPHrclyFI0lm7+w94cO8U=
|
github.com/clipperhouse/uax29/v2 v2.5.0 h1:x7T0T4eTHDONxFJsL94uKNKPHrclyFI0lm7+w94cO8U=
|
||||||
github.com/clipperhouse/uax29/v2 v2.5.0/go.mod h1:Wn1g7MK6OoeDT0vL+Q0SQLDz/KpfsVRgg6W7ihQeh4g=
|
github.com/clipperhouse/uax29/v2 v2.5.0/go.mod h1:Wn1g7MK6OoeDT0vL+Q0SQLDz/KpfsVRgg6W7ihQeh4g=
|
||||||
|
github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s=
|
||||||
|
github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE=
|
||||||
github.com/danieljoos/wincred v1.2.3 h1:v7dZC2x32Ut3nEfRH+vhoZGvN72+dQ/snVXo/vMFLdQ=
|
github.com/danieljoos/wincred v1.2.3 h1:v7dZC2x32Ut3nEfRH+vhoZGvN72+dQ/snVXo/vMFLdQ=
|
||||||
github.com/danieljoos/wincred v1.2.3/go.mod h1:6qqX0WNrS4RzPZ1tnroDzq9kY3fu1KwE7MRLQK4X0bs=
|
github.com/danieljoos/wincred v1.2.3/go.mod h1:6qqX0WNrS4RzPZ1tnroDzq9kY3fu1KwE7MRLQK4X0bs=
|
||||||
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
|
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
|
||||||
@@ -74,6 +76,8 @@ github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
|
|||||||
github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
|
github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
|
||||||
github.com/gorilla/css v1.0.1 h1:ntNaBIghp6JmvWnxbZKANoLyuXTPZ4cAMlo6RyhlbO8=
|
github.com/gorilla/css v1.0.1 h1:ntNaBIghp6JmvWnxbZKANoLyuXTPZ4cAMlo6RyhlbO8=
|
||||||
github.com/gorilla/css v1.0.1/go.mod h1:BvnYkspnSzMmwRK+b8/xgNPLiIuNZr6vbZBTPQ2A3b0=
|
github.com/gorilla/css v1.0.1/go.mod h1:BvnYkspnSzMmwRK+b8/xgNPLiIuNZr6vbZBTPQ2A3b0=
|
||||||
|
github.com/hinshun/vt10x v0.0.0-20220301184237-5011da428d02 h1:AgcIVYPa6XJnU3phs104wLj8l5GEththEw6+F79YsIY=
|
||||||
|
github.com/hinshun/vt10x v0.0.0-20220301184237-5011da428d02/go.mod h1:Q48J4R4DvxnHolD5P8pOtXigYlRuPLGl6moFx3ulM68=
|
||||||
github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
|
github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
|
||||||
github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
|
github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
|
||||||
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
|
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
|
||||||
|
|||||||
@@ -0,0 +1,95 @@
|
|||||||
|
---
|
||||||
|
name: tee_anthropic_sse
|
||||||
|
kind: function
|
||||||
|
lang: py
|
||||||
|
domain: cybersecurity
|
||||||
|
version: "1.0.0"
|
||||||
|
purity: impure
|
||||||
|
signature: "class AnthropicSSETee — mitmproxy addon loaded via mitmdump -s"
|
||||||
|
description: "Addon de mitmproxy que intercepta el stream SSE de la API de Anthropic (/v1/messages) y emite cada evento significativo a stdout como NDJSON en tiempo real. Cada interaccion de la CLI claude dispara una o varias llamadas a /v1/messages; el addon las etiqueta con stream_id, model y has_tools para que el consumidor pueda distinguir la respuesta principal (claude-opus-X con tools) de las auxiliares (titulo/clasificador en haiku sin tools). Las funciones puras split_sse_events y event_to_ndjson son testeables sin mitmproxy."
|
||||||
|
tags: [web-proxy, claude, mitmproxy, sse, streaming, anthropic, cybersecurity]
|
||||||
|
uses_functions: []
|
||||||
|
uses_types: []
|
||||||
|
returns: []
|
||||||
|
returns_optional: false
|
||||||
|
error_type: "error_go_core"
|
||||||
|
imports: ["json", "os", "sys", "mitmproxy"]
|
||||||
|
tested: true
|
||||||
|
tests:
|
||||||
|
- "split buffer completo devuelve 8 bloques"
|
||||||
|
- "split bloques contienen event y data"
|
||||||
|
- "split buffer cortado preserva incompleto"
|
||||||
|
- "split resto mas continuacion reconstruye evento"
|
||||||
|
- "split buffer vacio"
|
||||||
|
- "split evento unico sin separador final"
|
||||||
|
- "text delta p"
|
||||||
|
- "text delta ong"
|
||||||
|
- "message stop con stop holder previo"
|
||||||
|
- "ping devuelve lista vacia"
|
||||||
|
- "content block start text devuelve vacio"
|
||||||
|
- "content block start tool use"
|
||||||
|
- "tool json delta"
|
||||||
|
- "json invalido en data devuelve vacio"
|
||||||
|
- "bloque sin data devuelve vacio"
|
||||||
|
- "integracion secuencia completa produce pong y stop"
|
||||||
|
- "integracion stream id se propaga"
|
||||||
|
- "integracion determinismo"
|
||||||
|
test_file_path: "python/functions/cybersecurity/tests/test_tee_anthropic_sse.py"
|
||||||
|
file_path: "python/functions/cybersecurity/tee_anthropic_sse.py"
|
||||||
|
params:
|
||||||
|
- name: mitmdump_invocation
|
||||||
|
desc: "No recibe argumentos directos. Se carga con `mitmdump -s tee_anthropic_sse.py`. El puerto del proxy se controla con el flag -p de mitmdump (ej. -p 8901). La flag -q suprime el log de mitmdump en stderr dejando solo el NDJSON en stdout."
|
||||||
|
- name: FN_WIRE_ONLY_TOOLS
|
||||||
|
desc: "Variable de entorno opcional. Si vale '1', suprime los streams cuyo request body no incluye el array 'tools' (llamadas auxiliares de titulo/clasificador que usan haiku). Por defecto (sin la env) emite todos los streams etiquetados con stream_id, model y has_tools para que el consumidor filtre."
|
||||||
|
output: "NDJSON a stdout, un objeto JSON por linea (flush inmediato). Tipos de linea: message_start{stream_id,model,has_tools} al inicio de cada stream; text_delta{stream_id,text} por cada fragmento de texto del modelo; tool_use_start{stream_id,tool_name,tool_id} cuando el modelo inicia una herramienta; tool_json_delta{stream_id,partial_json} por cada fragmento de argumentos JSON de la herramienta; message_stop{stream_id,stop_reason} al finalizar el stream. stderr recibe solo mensajes de diagnóstico del addon (errores, warnings), nunca NDJSON."
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ejemplo
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Terminal 1: lanzar mitmproxy como proxy de interceptacion
|
||||||
|
# -q suprime el log de mitmdump; solo se ve el NDJSON en stdout
|
||||||
|
mitmdump -p 8901 \
|
||||||
|
-s python/functions/cybersecurity/tee_anthropic_sse.py \
|
||||||
|
-q
|
||||||
|
|
||||||
|
# Terminal 2: lanzar claude por el proxy
|
||||||
|
# NODE_EXTRA_CA_CERTS hace que el runtime Node de claude confie en la CA de mitmproxy
|
||||||
|
export HTTPS_PROXY=http://127.0.0.1:8901
|
||||||
|
export NODE_EXTRA_CA_CERTS="$HOME/.mitmproxy/mitmproxy-ca-cert.pem"
|
||||||
|
claude -p "di hola"
|
||||||
|
|
||||||
|
# Salida en stdout de mitmdump (Terminal 1):
|
||||||
|
# {"type": "message_start", "stream_id": 1, "model": "claude-haiku-4-5", "has_tools": false}
|
||||||
|
# {"type": "text_delta", "stream_id": 1, "text": "H"}
|
||||||
|
# {"type": "text_delta", "stream_id": 1, "text": "ola"}
|
||||||
|
# {"type": "message_stop", "stream_id": 1, "stop_reason": "end_turn"}
|
||||||
|
# ...
|
||||||
|
# {"type": "message_start", "stream_id": 2, "model": "claude-opus-4-8", "has_tools": true}
|
||||||
|
# {"type": "text_delta", "stream_id": 2, "text": "Hola"}
|
||||||
|
# ...
|
||||||
|
|
||||||
|
# Filtrar solo la respuesta principal (has_tools=true) con jq:
|
||||||
|
mitmdump -p 8901 -s python/functions/cybersecurity/tee_anthropic_sse.py -q \
|
||||||
|
| jq -c 'select(.has_tools == true or .stream_id != null and (.type == "text_delta"))'
|
||||||
|
|
||||||
|
# O usar la variable de entorno para que el addon ya filtre en origen:
|
||||||
|
FN_WIRE_ONLY_TOOLS=1 mitmdump -p 8901 \
|
||||||
|
-s python/functions/cybersecurity/tee_anthropic_sse.py -q
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cuando usarla
|
||||||
|
|
||||||
|
Cuando quieras el texto exacto que el modelo genera en tiempo real desde una sesion claude (TUI interactiva o `claude -p`), interceptando la red, sin parsear el render de la terminal ni depender de warmup/idle de la TUI. Util para: capturar la salida del modelo para procesado downstream (logging estructurado, metricas de tokens, replay), observar tool_use en construccion (argumentos parciales), o depurar la diferencia entre streams principales y auxiliares en una misma sesion TUI.
|
||||||
|
|
||||||
|
## Gotchas
|
||||||
|
|
||||||
|
- **Descompresion via strip de Accept-Encoding**: el hook `request` elimina el header `Accept-Encoding` de las llamadas a `/v1/messages` para que la API responda con el SSE SIN comprimir. Esto es obligatorio: el modo streaming de mitmproxy (`flow.response.stream`) entrega al tee los bytes CRUDOS del cuerpo, que si vinieran con `Content-Encoding: gzip`/`br` nunca contendrian el delimitador `\n\n` de eventos SSE (se veria binario) y no se emitiria ningun delta. Verificado empiricamente el 2026-06-04: sin el strip, solo se emitia `message_start`; con el strip, los `text_delta` salen correctamente. La alternativa (un decompresor de streaming con estado por flujo) es mas fragil. El coste es unos bytes extra en el salto local, irrelevante.
|
||||||
|
- **NO usar `--set stream_large_bodies`**: el modo streaming se activa con `flow.response.stream = func` en `responseheaders`, sin necesidad de ese flag. Ademas `stream_large_bodies=N` bajo rompe el acceso a `flow.request.content` (necesario para `has_tools`), porque tambien streamea el cuerpo del request y deja de bufferearlo.
|
||||||
|
- **Requiere mitmproxy + CA confiada por claude**: la CA de mitmproxy (`~/.mitmproxy/mitmproxy-ca-cert.pem`) debe estar configurada en `NODE_EXTRA_CA_CERTS` para que el runtime Node de la CLI claude acepte el certificado MITM. Sin esto, claude rechaza la conexion con error de TLS. Instalar mitmproxy: `uv tool install mitmproxy` o `pip install mitmproxy`. claude tambien respeta `HTTPS_PROXY` para enrutar su trafico por el proxy.
|
||||||
|
- **Una interaccion TUI dispara varias /v1/messages**: la respuesta real del usuario usa el modelo principal (p.ej. claude-opus-4-8) y su request body incluye el array `tools` con las herramientas de Claude Code. Las llamadas auxiliares (generador de titulo, clasificador) usan claude-haiku y su request NO lleva `tools`. Usa `has_tools=true` o `FN_WIRE_ONLY_TOOLS=1` para aislar la respuesta principal y no mezclar streams.
|
||||||
|
- **Solo funciona mientras claude no haga TLS pinning**: hoy (2026-06-04) la CLI claude no hace certificate pinning, por lo que el MITM funciona con `NODE_EXTRA_CA_CERTS`. Si una version futura de claude añade pinning, el addon dejara de interceptar.
|
||||||
|
- **Es trafico de tu propia cuenta y maquina**: el addon captura unicamente el trafico local que tu proxy intercepta. No hay acceso a otras cuentas ni sesiones remotas. El NDJSON se emite solo a stdout local.
|
||||||
|
- **El endpoint puede cambiar**: la CLI claude hoy usa `POST /v1/messages?beta=true`. El addon filtra por prefix `/v1/messages` para tolerar variantes de query string, pero si Anthropic cambia la ruta base en versiones futuras del protocolo, actualizar el check en `responseheaders`.
|
||||||
|
- **Chunks parciales**: el addon mantiene un buffer por stream para manejar eventos SSE partidos entre chunks TCP. Si mitmdump se mata con SIGKILL durante un stream activo, el ultimo bloque incompleto del buffer se descarta (no se emite un message_stop artificial).
|
||||||
|
- **stdout debe ser exclusivamente NDJSON**: no añadir prints de debug a stdout; redirigir diagnosticos a stderr. Si se canaliza la salida a `jq` u otro parser, cualquier linea no-JSON rompe el pipeline.
|
||||||
@@ -0,0 +1,278 @@
|
|||||||
|
"""mitmproxy addon that tees Anthropic SSE streams to stdout as NDJSON.
|
||||||
|
|
||||||
|
Load with: mitmdump -p 8901 -s tee_anthropic_sse.py -q
|
||||||
|
|
||||||
|
For each POST /v1/messages response that streams text/event-stream, the addon
|
||||||
|
emits one NDJSON line per meaningful SSE event to stdout:
|
||||||
|
|
||||||
|
{"type":"message_start","stream_id":1,"model":"claude-opus-4-8","has_tools":true}
|
||||||
|
{"type":"text_delta","stream_id":1,"text":"Hello"}
|
||||||
|
{"type":"tool_use_start","stream_id":1,"tool_name":"Bash","tool_id":"toolu_01..."}
|
||||||
|
{"type":"tool_json_delta","stream_id":1,"partial_json":"{\"command\":\"ls"}
|
||||||
|
{"type":"message_stop","stream_id":1,"stop_reason":"end_turn"}
|
||||||
|
|
||||||
|
stdout is EXCLUSIVELY NDJSON — suitable for piping. All addon diagnostics go
|
||||||
|
to stderr.
|
||||||
|
|
||||||
|
Set FN_WIRE_ONLY_TOOLS=1 to suppress streams whose request body has no "tools"
|
||||||
|
array (title generators, classifiers, etc.).
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import json
|
||||||
|
import os
|
||||||
|
import sys
|
||||||
|
from typing import Iterator
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Pure helpers — testable without mitmproxy
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def split_sse_events(buf: bytes) -> tuple[list[str], bytes]:
|
||||||
|
"""Split a byte buffer into complete SSE event blocks and a leftover tail.
|
||||||
|
|
||||||
|
SSE events are separated by a blank line (``\\n\\n``). Any bytes after
|
||||||
|
the last complete event are returned unchanged as *leftover* so they can
|
||||||
|
be prepended to the next chunk.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
buf: Raw bytes accumulated from one or more SSE chunks.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
A 2-tuple ``(events, leftover)`` where *events* is a list of complete
|
||||||
|
event block strings (without the trailing ``\\n\\n``) and *leftover*
|
||||||
|
is the remaining bytes that do not yet form a complete event.
|
||||||
|
"""
|
||||||
|
text = buf.decode("utf-8", errors="replace")
|
||||||
|
# Split on the blank-line delimiter that separates SSE events.
|
||||||
|
parts = text.split("\n\n")
|
||||||
|
# The last element is either empty (buffer ended exactly on \n\n) or an
|
||||||
|
# incomplete event that must be carried forward.
|
||||||
|
complete = [p for p in parts[:-1] if p.strip()]
|
||||||
|
leftover_str = parts[-1]
|
||||||
|
return complete, leftover_str.encode("utf-8")
|
||||||
|
|
||||||
|
|
||||||
|
def event_to_ndjson(
|
||||||
|
event_block: str,
|
||||||
|
stream_id: int,
|
||||||
|
stop_holder: dict,
|
||||||
|
) -> list[dict]:
|
||||||
|
"""Parse one SSE event block and return zero or more NDJSON dicts.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
event_block: A single SSE event block string (the content between two
|
||||||
|
``\\n\\n`` separators), e.g. ``"event: content_block_delta\\ndata: {...}"``.
|
||||||
|
stream_id: Monotonic integer that identifies the current stream.
|
||||||
|
stop_holder: A mutable dict used to carry ``stop_reason`` across calls.
|
||||||
|
The caller passes the same dict for all events of one stream; this
|
||||||
|
function writes ``stop_holder["stop_reason"]`` on ``message_delta``
|
||||||
|
events and reads it on ``message_stop``.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
A (possibly empty) list of dicts ready to be JSON-serialised as NDJSON.
|
||||||
|
"""
|
||||||
|
event_type = ""
|
||||||
|
data_str = ""
|
||||||
|
|
||||||
|
for line in event_block.splitlines():
|
||||||
|
if line.startswith("event:"):
|
||||||
|
event_type = line[len("event:"):].strip()
|
||||||
|
elif line.startswith("data:"):
|
||||||
|
data_str = line[len("data:"):].strip()
|
||||||
|
|
||||||
|
if not data_str:
|
||||||
|
return []
|
||||||
|
|
||||||
|
try:
|
||||||
|
data = json.loads(data_str)
|
||||||
|
except json.JSONDecodeError:
|
||||||
|
return []
|
||||||
|
|
||||||
|
results: list[dict] = []
|
||||||
|
|
||||||
|
if event_type == "content_block_delta":
|
||||||
|
delta = data.get("delta", {})
|
||||||
|
delta_type = delta.get("type", "")
|
||||||
|
if delta_type == "text_delta":
|
||||||
|
results.append(
|
||||||
|
{
|
||||||
|
"type": "text_delta",
|
||||||
|
"stream_id": stream_id,
|
||||||
|
"text": delta.get("text", ""),
|
||||||
|
}
|
||||||
|
)
|
||||||
|
elif delta_type == "input_json_delta":
|
||||||
|
results.append(
|
||||||
|
{
|
||||||
|
"type": "tool_json_delta",
|
||||||
|
"stream_id": stream_id,
|
||||||
|
"partial_json": delta.get("partial_json", ""),
|
||||||
|
}
|
||||||
|
)
|
||||||
|
|
||||||
|
elif event_type == "content_block_start":
|
||||||
|
cb = data.get("content_block", {})
|
||||||
|
if cb.get("type") == "tool_use":
|
||||||
|
results.append(
|
||||||
|
{
|
||||||
|
"type": "tool_use_start",
|
||||||
|
"stream_id": stream_id,
|
||||||
|
"tool_name": cb.get("name", ""),
|
||||||
|
"tool_id": cb.get("id", ""),
|
||||||
|
}
|
||||||
|
)
|
||||||
|
# content_block_start for text blocks → nothing to emit
|
||||||
|
|
||||||
|
elif event_type == "message_delta":
|
||||||
|
delta = data.get("delta", {})
|
||||||
|
reason = delta.get("stop_reason")
|
||||||
|
if reason:
|
||||||
|
stop_holder["stop_reason"] = reason
|
||||||
|
|
||||||
|
elif event_type == "message_stop":
|
||||||
|
results.append(
|
||||||
|
{
|
||||||
|
"type": "message_stop",
|
||||||
|
"stream_id": stream_id,
|
||||||
|
"stop_reason": stop_holder.get("stop_reason", "end_turn"),
|
||||||
|
}
|
||||||
|
)
|
||||||
|
|
||||||
|
return results
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# mitmproxy addon
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
class AnthropicSSETee:
|
||||||
|
"""mitmproxy addon: tee Anthropic /v1/messages SSE streams to stdout.
|
||||||
|
|
||||||
|
One instance is shared across all intercepted flows. Each SSE stream gets
|
||||||
|
a monotonically increasing ``stream_id`` so the consumer can correlate
|
||||||
|
lines from concurrent or sequential streams.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self) -> None:
|
||||||
|
self._stream_counter: int = 0
|
||||||
|
self._wire_only_tools: bool = os.environ.get("FN_WIRE_ONLY_TOOLS", "") == "1"
|
||||||
|
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
# mitmproxy hooks
|
||||||
|
# ------------------------------------------------------------------
|
||||||
|
|
||||||
|
def request(self, flow) -> None: # noqa: ANN001
|
||||||
|
"""Called when a request is received (before it is sent upstream).
|
||||||
|
|
||||||
|
For the target /v1/messages endpoint, strip the Accept-Encoding header so
|
||||||
|
the API responds with an uncompressed SSE stream. Otherwise the streaming
|
||||||
|
tee would see gzip/brotli bytes (which never contain the ``\\n\\n`` event
|
||||||
|
delimiter) and a stateful streaming decompressor would be required. The
|
||||||
|
extra bytes on the local hop are irrelevant; claude still parses the SSE
|
||||||
|
normally.
|
||||||
|
"""
|
||||||
|
req = flow.request
|
||||||
|
if req.method == "POST" and req.path.startswith("/v1/messages"):
|
||||||
|
req.headers.pop("accept-encoding", None)
|
||||||
|
|
||||||
|
def responseheaders(self, flow) -> None: # noqa: ANN001
|
||||||
|
"""Called when response headers are received (before body).
|
||||||
|
|
||||||
|
If the flow is a streaming Anthropic messages endpoint, activate
|
||||||
|
mitmproxy's streaming mode and attach the tee function so the response
|
||||||
|
body is forwarded to claude in real time while we parse it.
|
||||||
|
"""
|
||||||
|
req = flow.request
|
||||||
|
resp = flow.response
|
||||||
|
|
||||||
|
# Filter: must be POST /v1/messages (with or without query params)
|
||||||
|
if req.method != "POST":
|
||||||
|
return
|
||||||
|
if not req.path.startswith("/v1/messages"):
|
||||||
|
return
|
||||||
|
|
||||||
|
# Filter: response must be SSE
|
||||||
|
ct = resp.headers.get("content-type", "")
|
||||||
|
if "event-stream" not in ct:
|
||||||
|
return
|
||||||
|
|
||||||
|
# Parse request body for metadata
|
||||||
|
try:
|
||||||
|
body = json.loads(req.content or b"{}")
|
||||||
|
except (json.JSONDecodeError, Exception):
|
||||||
|
# Cannot parse body — skip this flow without breaking the proxy
|
||||||
|
print(
|
||||||
|
f"[tee_anthropic_sse] WARN: could not parse request body for {req.path}",
|
||||||
|
file=sys.stderr,
|
||||||
|
flush=True,
|
||||||
|
)
|
||||||
|
return
|
||||||
|
|
||||||
|
model: str = body.get("model", "unknown")
|
||||||
|
has_tools: bool = bool(body.get("tools"))
|
||||||
|
|
||||||
|
# Optionally suppress non-tool streams (title/classifier calls)
|
||||||
|
if self._wire_only_tools and not has_tools:
|
||||||
|
return
|
||||||
|
|
||||||
|
self._stream_counter += 1
|
||||||
|
stream_id = self._stream_counter
|
||||||
|
|
||||||
|
# Emit the stream-start event so the consumer knows what is coming
|
||||||
|
_emit({"type": "message_start", "stream_id": stream_id, "model": model, "has_tools": has_tools})
|
||||||
|
|
||||||
|
# Build the per-stream tee closure and hand it to mitmproxy
|
||||||
|
flow.response.stream = _make_tee(stream_id)
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Private helpers
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def _emit(obj: dict) -> None:
|
||||||
|
"""Write one NDJSON line to stdout (flush immediately)."""
|
||||||
|
print(json.dumps(obj), flush=True)
|
||||||
|
|
||||||
|
|
||||||
|
def _make_tee(stream_id: int):
|
||||||
|
"""Return a mitmproxy streaming function for a single SSE stream.
|
||||||
|
|
||||||
|
The returned callable is assigned to ``flow.response.stream`` and will be
|
||||||
|
called by mitmproxy for each chunk of the response body. It MUST return
|
||||||
|
the chunk unchanged so claude receives the full stream.
|
||||||
|
"""
|
||||||
|
buf: bytearray = bytearray()
|
||||||
|
stop_holder: dict = {}
|
||||||
|
|
||||||
|
def tee(chunk: bytes) -> bytes:
|
||||||
|
nonlocal buf
|
||||||
|
buf.extend(chunk)
|
||||||
|
try:
|
||||||
|
events, leftover = split_sse_events(bytes(buf))
|
||||||
|
buf = bytearray(leftover)
|
||||||
|
for block in events:
|
||||||
|
for obj in event_to_ndjson(block, stream_id, stop_holder):
|
||||||
|
_emit(obj)
|
||||||
|
except Exception as exc: # noqa: BLE001
|
||||||
|
print(
|
||||||
|
f"[tee_anthropic_sse] ERROR in tee for stream {stream_id}: {exc}",
|
||||||
|
file=sys.stderr,
|
||||||
|
flush=True,
|
||||||
|
)
|
||||||
|
# Always return the original chunk — claude must receive its stream
|
||||||
|
return chunk
|
||||||
|
|
||||||
|
return tee
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# mitmproxy entrypoint
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
addons = [AnthropicSSETee()]
|
||||||
@@ -0,0 +1,283 @@
|
|||||||
|
"""Tests para las funciones puras de tee_anthropic_sse.
|
||||||
|
|
||||||
|
Cubre split_sse_events y event_to_ndjson sin necesitar mitmproxy.
|
||||||
|
"""
|
||||||
|
|
||||||
|
import os
|
||||||
|
import sys
|
||||||
|
|
||||||
|
sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
|
||||||
|
|
||||||
|
from tee_anthropic_sse import split_sse_events, event_to_ndjson
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# SSE fixture — captura real de la API de Anthropic
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
_RAW_SSE = (
|
||||||
|
b"event: message_start\n"
|
||||||
|
b'data: {"type":"message_start","message":{"model":"claude-opus-4-8","id":"msg_x",'
|
||||||
|
b'"type":"message","role":"assistant","content":[],"stop_reason":null}}\n'
|
||||||
|
b"\n"
|
||||||
|
b"event: content_block_start\n"
|
||||||
|
b'data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}\n'
|
||||||
|
b"\n"
|
||||||
|
b"event: ping\n"
|
||||||
|
b'data: {"type": "ping"}\n'
|
||||||
|
b"\n"
|
||||||
|
b"event: content_block_delta\n"
|
||||||
|
b'data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"P"}}\n'
|
||||||
|
b"\n"
|
||||||
|
b"event: content_block_delta\n"
|
||||||
|
b'data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"ONG"}}\n'
|
||||||
|
b"\n"
|
||||||
|
b"event: content_block_stop\n"
|
||||||
|
b'data: {"type":"content_block_stop","index":0}\n'
|
||||||
|
b"\n"
|
||||||
|
b"event: message_delta\n"
|
||||||
|
b'data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},'
|
||||||
|
b'"usage":{"output_tokens":5}}\n'
|
||||||
|
b"\n"
|
||||||
|
b"event: message_stop\n"
|
||||||
|
b'data: {"type":"message_stop"}\n'
|
||||||
|
b"\n"
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# split_sse_events
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_split_buffer_completo_devuelve_8_bloques():
|
||||||
|
"""Con el buffer completo devuelve los 8 bloques y leftover vacio."""
|
||||||
|
events, leftover = split_sse_events(_RAW_SSE)
|
||||||
|
assert len(events) == 8
|
||||||
|
assert leftover == b""
|
||||||
|
|
||||||
|
|
||||||
|
def test_split_bloques_contienen_event_y_data():
|
||||||
|
"""Cada bloque contiene las lineas event: y data: esperadas."""
|
||||||
|
events, _ = split_sse_events(_RAW_SSE)
|
||||||
|
assert "event: message_start" in events[0]
|
||||||
|
assert "event: ping" in events[2]
|
||||||
|
assert "event: message_stop" in events[7]
|
||||||
|
|
||||||
|
|
||||||
|
def test_split_buffer_cortado_preserva_incompleto():
|
||||||
|
"""Con un buffer cortado a la mitad de un evento, devuelve solo los completos."""
|
||||||
|
# Encontrar la SEGUNDA aparicion de content_block_delta (quinto evento en total)
|
||||||
|
first_occ = _RAW_SSE.find(b"event: content_block_delta\ndata:")
|
||||||
|
second_occ = _RAW_SSE.find(b"event: content_block_delta\ndata:", first_occ + 1)
|
||||||
|
# Cortar en medio del data: del segundo content_block_delta
|
||||||
|
cut_buf = _RAW_SSE[:second_occ + 20]
|
||||||
|
|
||||||
|
events, leftover = split_sse_events(cut_buf)
|
||||||
|
# Debe haber exactamente 4 eventos completos:
|
||||||
|
# message_start, content_block_start, ping, primer content_block_delta
|
||||||
|
assert len(events) == 4
|
||||||
|
# El leftover no debe estar vacio (el segundo delta queda a medias)
|
||||||
|
assert len(leftover) > 0
|
||||||
|
|
||||||
|
|
||||||
|
def test_split_resto_mas_continuacion_reconstruye_evento():
|
||||||
|
"""Concatenar leftover + continuacion reconstituye el evento cortado."""
|
||||||
|
# Cortar justo antes del \n\n que cierra el primer delta
|
||||||
|
cut_point = _RAW_SSE.find(b"\n\nevent: content_block_delta\n", 100)
|
||||||
|
first_half = _RAW_SSE[:cut_point + 1] # termina dentro del separador
|
||||||
|
second_half = _RAW_SSE[cut_point + 1:]
|
||||||
|
|
||||||
|
events1, leftover1 = split_sse_events(first_half)
|
||||||
|
combined = leftover1 + second_half
|
||||||
|
events2, leftover2 = split_sse_events(combined)
|
||||||
|
|
||||||
|
# La union debe cubrir todos los bloques del segundo tramo
|
||||||
|
all_events = events1 + events2
|
||||||
|
assert len(all_events) == 8
|
||||||
|
assert leftover2 == b""
|
||||||
|
|
||||||
|
|
||||||
|
def test_split_buffer_vacio():
|
||||||
|
"""Buffer vacio devuelve lista vacia y leftover vacio."""
|
||||||
|
events, leftover = split_sse_events(b"")
|
||||||
|
assert events == []
|
||||||
|
assert leftover == b""
|
||||||
|
|
||||||
|
|
||||||
|
def test_split_evento_unico_sin_separador_final():
|
||||||
|
"""Un evento sin separador final queda como leftover."""
|
||||||
|
chunk = b"event: ping\ndata: {\"type\":\"ping\"}"
|
||||||
|
events, leftover = split_sse_events(chunk)
|
||||||
|
assert events == []
|
||||||
|
assert b"ping" in leftover
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# event_to_ndjson
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_text_delta_p():
|
||||||
|
"""content_block_delta text_delta 'P' -> [{type:text_delta, stream_id:1, text:'P'}]."""
|
||||||
|
block = (
|
||||||
|
"event: content_block_delta\n"
|
||||||
|
'data: {"type":"content_block_delta","index":0,'
|
||||||
|
'"delta":{"type":"text_delta","text":"P"}}'
|
||||||
|
)
|
||||||
|
result = event_to_ndjson(block, 1, {})
|
||||||
|
assert result == [{"type": "text_delta", "stream_id": 1, "text": "P"}]
|
||||||
|
|
||||||
|
|
||||||
|
def test_text_delta_ong():
|
||||||
|
"""content_block_delta text_delta 'ONG' -> text 'ONG'."""
|
||||||
|
block = (
|
||||||
|
"event: content_block_delta\n"
|
||||||
|
'data: {"type":"content_block_delta","index":0,'
|
||||||
|
'"delta":{"type":"text_delta","text":"ONG"}}'
|
||||||
|
)
|
||||||
|
result = event_to_ndjson(block, 1, {})
|
||||||
|
assert result == [{"type": "text_delta", "stream_id": 1, "text": "ONG"}]
|
||||||
|
|
||||||
|
|
||||||
|
def test_message_stop_con_stop_holder_previo():
|
||||||
|
"""message_stop con stop_holder ya cargado -> stop_reason end_turn."""
|
||||||
|
stop_holder: dict = {}
|
||||||
|
|
||||||
|
# Primero simular message_delta para poblar el holder
|
||||||
|
delta_block = (
|
||||||
|
"event: message_delta\n"
|
||||||
|
'data: {"type":"message_delta","delta":{"stop_reason":"end_turn",'
|
||||||
|
'"stop_sequence":null},"usage":{"output_tokens":5}}'
|
||||||
|
)
|
||||||
|
event_to_ndjson(delta_block, 1, stop_holder)
|
||||||
|
assert stop_holder.get("stop_reason") == "end_turn"
|
||||||
|
|
||||||
|
# Ahora message_stop
|
||||||
|
stop_block = (
|
||||||
|
"event: message_stop\n"
|
||||||
|
'data: {"type":"message_stop"}'
|
||||||
|
)
|
||||||
|
result = event_to_ndjson(stop_block, 1, stop_holder)
|
||||||
|
assert result == [{"type": "message_stop", "stream_id": 1, "stop_reason": "end_turn"}]
|
||||||
|
|
||||||
|
|
||||||
|
def test_ping_devuelve_lista_vacia():
|
||||||
|
"""ping -> []."""
|
||||||
|
block = "event: ping\ndata: {\"type\": \"ping\"}"
|
||||||
|
result = event_to_ndjson(block, 1, {})
|
||||||
|
assert result == []
|
||||||
|
|
||||||
|
|
||||||
|
def test_content_block_start_text_devuelve_vacio():
|
||||||
|
"""content_block_start para un bloque de texto -> []."""
|
||||||
|
block = (
|
||||||
|
"event: content_block_start\n"
|
||||||
|
'data: {"type":"content_block_start","index":0,'
|
||||||
|
'"content_block":{"type":"text","text":""}}'
|
||||||
|
)
|
||||||
|
result = event_to_ndjson(block, 1, {})
|
||||||
|
assert result == []
|
||||||
|
|
||||||
|
|
||||||
|
def test_content_block_start_tool_use():
|
||||||
|
"""content_block_start tool_use -> tool_use_start con name e id."""
|
||||||
|
block = (
|
||||||
|
"event: content_block_start\n"
|
||||||
|
'data: {"type":"content_block_start","index":1,'
|
||||||
|
'"content_block":{"type":"tool_use","id":"toolu_01abc","name":"Bash"}}'
|
||||||
|
)
|
||||||
|
result = event_to_ndjson(block, 2, {})
|
||||||
|
assert result == [
|
||||||
|
{
|
||||||
|
"type": "tool_use_start",
|
||||||
|
"stream_id": 2,
|
||||||
|
"tool_name": "Bash",
|
||||||
|
"tool_id": "toolu_01abc",
|
||||||
|
}
|
||||||
|
]
|
||||||
|
|
||||||
|
|
||||||
|
def test_tool_json_delta():
|
||||||
|
"""content_block_delta input_json_delta -> tool_json_delta."""
|
||||||
|
# Construir el bloque SSE con json.dumps para que el partial_json quede
|
||||||
|
# correctamente escapado dentro del JSON del campo data:
|
||||||
|
import json as _json
|
||||||
|
data_payload = {
|
||||||
|
"type": "content_block_delta",
|
||||||
|
"index": 1,
|
||||||
|
"delta": {
|
||||||
|
"type": "input_json_delta",
|
||||||
|
"partial_json": '{"command":"ls',
|
||||||
|
},
|
||||||
|
}
|
||||||
|
block = "event: content_block_delta\ndata: " + _json.dumps(data_payload)
|
||||||
|
result = event_to_ndjson(block, 3, {})
|
||||||
|
assert result == [
|
||||||
|
{
|
||||||
|
"type": "tool_json_delta",
|
||||||
|
"stream_id": 3,
|
||||||
|
"partial_json": '{"command":"ls',
|
||||||
|
}
|
||||||
|
]
|
||||||
|
|
||||||
|
|
||||||
|
def test_json_invalido_en_data_devuelve_vacio():
|
||||||
|
"""Linea data: con JSON invalido -> [] (sin excepcion)."""
|
||||||
|
block = "event: content_block_delta\ndata: {esto no es json"
|
||||||
|
result = event_to_ndjson(block, 1, {})
|
||||||
|
assert result == []
|
||||||
|
|
||||||
|
|
||||||
|
def test_bloque_sin_data_devuelve_vacio():
|
||||||
|
"""Bloque sin linea data: -> []."""
|
||||||
|
block = "event: content_block_stop\n"
|
||||||
|
result = event_to_ndjson(block, 1, {})
|
||||||
|
assert result == []
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# Integración del parseo: secuencia completa produce PONG + message_stop
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
def test_integracion_secuencia_completa_produce_pong_y_stop():
|
||||||
|
"""Los 8 bloques en orden producen text_delta 'P'+'ONG' y un message_stop end_turn."""
|
||||||
|
events, leftover = split_sse_events(_RAW_SSE)
|
||||||
|
assert leftover == b""
|
||||||
|
|
||||||
|
stop_holder: dict = {}
|
||||||
|
all_ndjson: list[dict] = []
|
||||||
|
for block in events:
|
||||||
|
all_ndjson.extend(event_to_ndjson(block, 1, stop_holder))
|
||||||
|
|
||||||
|
text_deltas = [o for o in all_ndjson if o["type"] == "text_delta"]
|
||||||
|
message_stops = [o for o in all_ndjson if o["type"] == "message_stop"]
|
||||||
|
|
||||||
|
concatenated = "".join(d["text"] for d in text_deltas)
|
||||||
|
assert concatenated == "PONG"
|
||||||
|
|
||||||
|
assert len(message_stops) == 1
|
||||||
|
assert message_stops[0]["stop_reason"] == "end_turn"
|
||||||
|
assert message_stops[0]["stream_id"] == 1
|
||||||
|
|
||||||
|
|
||||||
|
def test_integracion_stream_id_se_propaga():
|
||||||
|
"""stream_id se propaga correctamente a todos los eventos emitidos."""
|
||||||
|
events, _ = split_sse_events(_RAW_SSE)
|
||||||
|
stop_holder: dict = {}
|
||||||
|
for block in events:
|
||||||
|
for obj in event_to_ndjson(block, 42, stop_holder):
|
||||||
|
assert obj["stream_id"] == 42
|
||||||
|
|
||||||
|
|
||||||
|
def test_integracion_determinismo():
|
||||||
|
"""Parsear el mismo buffer dos veces produce exactamente el mismo resultado."""
|
||||||
|
def parse_all(stream_id: int) -> list[dict]:
|
||||||
|
evs, _ = split_sse_events(_RAW_SSE)
|
||||||
|
holder: dict = {}
|
||||||
|
result: list[dict] = []
|
||||||
|
for b in evs:
|
||||||
|
result.extend(event_to_ndjson(b, stream_id, holder))
|
||||||
|
return result
|
||||||
|
|
||||||
|
assert parse_all(1) == parse_all(1)
|
||||||
@@ -0,0 +1,25 @@
|
|||||||
|
---
|
||||||
|
name: identity
|
||||||
|
lang: go
|
||||||
|
domain: cybersecurity
|
||||||
|
version: "1.0.0"
|
||||||
|
algebraic: product
|
||||||
|
definition: |
|
||||||
|
type Identity struct {
|
||||||
|
SignPub []byte
|
||||||
|
SignPriv []byte
|
||||||
|
KexPub []byte
|
||||||
|
KexPriv []byte
|
||||||
|
}
|
||||||
|
description: "Identidad criptográfica dual de un participante en el bus de mensajería. Contiene un par Ed25519 para firma (SignPub/SignPriv) y un par X25519 para intercambio de claves (KexPub/KexPriv)."
|
||||||
|
tags: [messaging, e2e-crypto, crypto, identity, ed25519, x25519, e2e-messaging]
|
||||||
|
uses_types: []
|
||||||
|
file_path: "functions/cybersecurity/generate_identity.go"
|
||||||
|
---
|
||||||
|
|
||||||
|
## Notas
|
||||||
|
|
||||||
|
- `SignPub` (32 bytes) y `SignPriv` (64 bytes): par Ed25519. SignPriv concatena seed (32) + pubkey (32).
|
||||||
|
- `KexPub` (32 bytes) y `KexPriv` (32 bytes): par Curve25519 para sealed box anónimo.
|
||||||
|
- Generado exclusivamente con `GenerateIdentity()`. No construir manualmente.
|
||||||
|
- Publicar solo `SignPub` + `KexPub` en el directorio de participantes; nunca las claves privadas.
|
||||||
@@ -0,0 +1,27 @@
|
|||||||
|
---
|
||||||
|
name: claude_tui_parse
|
||||||
|
lang: go
|
||||||
|
domain: tui
|
||||||
|
version: "1.0.0"
|
||||||
|
algebraic: product
|
||||||
|
definition: |
|
||||||
|
type ClaudeTUIParse struct {
|
||||||
|
Turns []ClaudeTurn `json:"turns"`
|
||||||
|
Answer string `json:"answer"`
|
||||||
|
}
|
||||||
|
description: "Resultado del parseo de una pantalla capturada de la TUI de Claude Code. Turns contiene todos los bloques de conversación visibles en orden (user, assistant, tool_use, tool_result). Answer es la concatenación de los bloques assistant que siguen al último turno user — equivalente al output de `claude -p`."
|
||||||
|
tags: [terminal-capture, claude, tui, conversation]
|
||||||
|
uses_types:
|
||||||
|
- claude_turn_go_tui
|
||||||
|
file_path: "functions/tui/parse_claude_tui.go"
|
||||||
|
---
|
||||||
|
|
||||||
|
## Notas
|
||||||
|
|
||||||
|
`Answer` se calcula así:
|
||||||
|
1. Localizar el último turno con `Role == user`.
|
||||||
|
2. Concatenar con `\n` el `Text` de todos los turnos `assistant` (no `tool_use`, no `tool_result`) que aparecen después.
|
||||||
|
3. Si no hay ningún turno `user`, concatenar todos los `assistant`.
|
||||||
|
4. Hacer trim del resultado.
|
||||||
|
|
||||||
|
Este valor es el equivalente programático de lo que imprime `claude -p` cuando la respuesta termina. Es vacío si la pantalla capturada no contiene respuesta del asistente (por ejemplo, captura prematura durante el streaming).
|
||||||
@@ -0,0 +1,36 @@
|
|||||||
|
---
|
||||||
|
name: claude_turn
|
||||||
|
lang: go
|
||||||
|
domain: tui
|
||||||
|
version: "1.0.0"
|
||||||
|
algebraic: product
|
||||||
|
definition: |
|
||||||
|
type ClaudeTurnRole string
|
||||||
|
|
||||||
|
const (
|
||||||
|
ClaudeTurnUser ClaudeTurnRole = "user"
|
||||||
|
ClaudeTurnAssistant ClaudeTurnRole = "assistant"
|
||||||
|
ClaudeTurnToolUse ClaudeTurnRole = "tool_use"
|
||||||
|
ClaudeTurnToolResult ClaudeTurnRole = "tool_result"
|
||||||
|
)
|
||||||
|
|
||||||
|
type ClaudeTurn struct {
|
||||||
|
Role ClaudeTurnRole `json:"role"`
|
||||||
|
Text string `json:"text"`
|
||||||
|
ToolName string `json:"tool_name,omitempty"`
|
||||||
|
}
|
||||||
|
description: "Un bloque de la conversación extraído de la pantalla renderizada de la TUI de Claude Code. El campo Role clasifica el tipo de turno; Text contiene el contenido textual (multilinea unido con \\n); ToolName solo se rellena cuando Role == tool_use."
|
||||||
|
tags: [terminal-capture, claude, tui, conversation]
|
||||||
|
uses_types: []
|
||||||
|
file_path: "functions/tui/parse_claude_tui.go"
|
||||||
|
---
|
||||||
|
|
||||||
|
## Notas
|
||||||
|
|
||||||
|
`ClaudeTurnRole` es un string enum con cuatro valores:
|
||||||
|
- `user` — mensaje escrito por el usuario (línea que empieza con `❯`).
|
||||||
|
- `assistant` — bloque de texto de respuesta del asistente (línea que empieza con `●` y no es una llamada a herramienta).
|
||||||
|
- `tool_use` — llamada a herramienta `● ToolName(args)`. `ToolName` contiene el identificador de la herramienta.
|
||||||
|
- `tool_result` — resultado de herramienta `⎿ ...`. Asociado al `tool_use` inmediatamente anterior.
|
||||||
|
|
||||||
|
El tipo vive en `functions/tui/parse_claude_tui.go` junto al resto de la función, en el mismo paquete `tui`.
|
||||||
Reference in New Issue
Block a user