@yoltra/devtools-cli

UI de terminal para Yoltra DevTools: inspecciona stores desde la línea de comandos.

@yoltra/devtools-cli es una aplicación de terminal hecha con React + Ink que empotra un hub de DevTools y renderiza una TUI completa para inspeccionar stores de Yoltra. Útil cuando prefieres tener el inspector en una terminal, o en una sesión SSH donde no hay navegador disponible.

#Instalación

bash

npm install -g @yoltra/devtools-cli

O ejecútalo directamente:

bash

npx @yoltra/devtools-cli

#Inicio rápido

bash

# Arranca la CLI (levanta el hub en el puerto 9800 automáticamente)
npx @yoltra/devtools-cli

# Puerto y tamaño de historial personalizados
npx @yoltra/devtools-cli --port 8900 --history-size 2000

# Un hub que exige un token (el panel presenta el mismo)
YOLTRA_DEVTOOLS_TOKEN=s3cret npx @yoltra/devtools-cli

Después, conecta el store de tu app a ese hub. transport: "websocket" lo envía al hub aunque la extensión de navegador esté instalada:

typescript

import { withDevtools } from "@yoltra/devtools-browser-agent";

withDevtools(store, { port: 9800, transport: "websocket" });

La CLI mostrará los stores conectados y los datos de eventos en vivo.

#Características

Hub de DevTools empotrado (arranca solo, y se omite si ya hay uno corriendo)
Selector de stores por pestañas para varios stores conectados
Línea de tiempo de eventos con canal y tipo
Explorador interactivo del árbol de estado
Viaje en el tiempo por los eventos registrados, para un store que permite replay
Panel de suscripciones (reducers, efectos, middleware)
Panel de métricas de rendimiento
Emisor de eventos para inyectar eventos de prueba
Navegación por teclado con gestión del foco

#Paneles

Seis paneles, en este orden. No hay atajos por panel: Tab pasa al siguiente panel y Shift+Tab al anterior.

Panel	Descripción
Events	Flujo de eventos en vivo con canal, tipo y marca de tiempo
State	Árbol de estado plegable con los valores actuales
Time Travel	Recorre los eventos registrados; solo para un store que permite replay (`allowReplay`)
Subscriptions	Reducers, efectos y middleware registrados
Metrics	Conteo de eventos, tasa, tiempo de proceso, profundidad de cola
Emit	Compone y emite eventos al store seleccionado

Tecla	Acción
`Tab` / `Shift+Tab`	Panel siguiente / anterior
`]` / `[`	Store conectado siguiente / anterior
`←` / `→`	En Time Travel: retrocede / avanza un evento
`r`	En Time Travel: vuelve al estado en vivo
`q`	Salir
`Esc`	En Emit: sale del formulario y reactiva las teclas de arriba
`Enter`	En Emit, fuera del formulario: vuelve a él

El formulario de Emit toma el teclado al abrir su pestaña. Mientras un campo tiene el foco, toda tecla de arriba se escribe en él, así que un payload como ["a"] o un canal con una q se escriben sin problema.

#Opciones de la CLI

Flag	Por defecto	Descripción
`--port`	`9800`	Puerto del servidor hub
`--history-size`	`1000`	Máximo de eventos retenidos para clientes tardíos
`--token`	ninguno	Token que el hub exige a cada cliente

--token también puede venir de la variable de entorno YOLTRA_DEVTOOLS_TOKEN, que lo mantiene fuera de la lista de procesos; si están las dos, gana el flag. El hub empotrado exige el token y el panel de terminal lo presenta, así que el mismo valor también permite a la CLI conectarse a un hub que ya corre con él. Pasa el mismo token a cada agente de store (authToken).

Estos símbolos también se exportan (parseArgs, CliArgs, CliArgsError, DEFAULT_PORT, DEFAULT_HISTORY_SIZE, TOKEN_ENV), así que una herramienta que empotre el hub puede reutilizar el mismo contrato de argumentos en vez de volver a deducirlo.

#Cómo funciona

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Tu app      │     │  CLI         │     │  TUI de Ink  │
│  (con        │ WS  │  (hub        │     │  (React +    │
│  withDevtools│────►│  empotrado)  │────►│   Ink)       │
│  )           │     │              │     │              │
└──────────────┘     └──────────────┘     └──────────────┘

La CLI arranca un DevtoolsHub empotrado (o detecta uno existente mediante probe())
La TUI de Ink se conecta al hub como extensión usando los hooks de @yoltra/devtools-ui
El agente del store de tu app se conecta al hub por WebSocket
Eventos, estado y comandos fluyen por el hub en tiempo real

La CLI son dos cosas en un proceso: un hub opcional y un panel. Arranca el hub solo cuando DevtoolsHub.probe no encuentra nada escuchando en el puerto, y la UI de terminal siempre se conecta como una extensión normal mediante HubProvider, así que se comporta igual con su propio hub que con uno que ya estaba corriendo.

Cómo la CLI inicia o reutiliza un hub. La CLI analiza sus argumentos, inicia un hub embebido solo si nadie escucha en el puerto, y renderiza una UI de terminal que se une al hub como extensión normal, mientras el agente del store de la app se conecta al mismo hub.

#Arquitectura

Archivo	Responsabilidad
`index.ts`	Punto de entrada, parseo de argumentos, ciclo de vida hub
`app.tsx`	Componente raíz de Ink con `HubProvider`
`components/StoreTabs.tsx`	Selector de stores por pestañas
`components/EventTimeline.tsx`	Registro de eventos en terminal
`components/StateTree.tsx`	Árbol de estado plegable
`components/SubscriptionsPanel.tsx`	Inventario de suscripciones
`components/MetricsDashboard.tsx`	Contadores de rendimiento
`components/EventEmitter.tsx`	Formulario de composición de eventos
`components/StatusBar.tsx`	Barra de estado de la conexión
`hooks/useKeyBindings.ts`	Gestión de atajos de teclado
`hooks/useFocusManager.ts`	Ciclado del foco entre paneles

#Paquetes relacionados

@yoltra/devtools-server: El hub que empotra esta CLI
@yoltra/devtools-ui: Hooks de React que dan lógica a la TUI
@yoltra/devtools-protocol: Formato de cable para hablar con el hub
@yoltra/devtools-browser-agent: Agente para conectar stores del navegador
@yoltra/devtools-ext: Extensión de navegador, como alternativa

#Licencia

MIT: De uso libre en proyectos comerciales y de código abierto.

Reportar un problema con esta página