estentor

estentor

Biblioteca en Go para construir consolas interactivas: prompt, registro de comandos, ayuda que se escribe sola, historial con sugerencia en gris, edición de línea, tablas alineadas, banner de bienvenida e indicador de carga.

Una sola dependencia, y del equipo de Go: golang.org/x/term, para el modo crudo de la terminal.

idas> help

  clear (cls)          limpia la pantalla
  equipos              muestra una tabla de ejemplo
  exit (quit, salir)   sale de la consola
  help (?)             lista los comandos disponibles

Guías de uso

Este README es la visión de conjunto. Para el detalle de cada pieza:

• La consola y sus comandos
• Tablas

Instalar

go get github.com/MarcosGiojiho/estentor

Necesita Go 1.26 o posterior. El paquete se llama estentor; el tipo principal, Consola.

Uso mínimo

package main

import "github.com/MarcosGiojiho/estentor"

func main() {
    estentor.Nueva("miapp").Arrancar()
}

Eso ya te da un prompt miapp> con clear, help y exit funcionando.

Para que un main pueda salir con código distinto de cero cuando la entrada falla, ArrancarCon(ctx) devuelve error:

if err := c.ArrancarCon(context.Background()); err != nil {
    fmt.Fprintln(os.Stderr, err)
    os.Exit(1)
}

Devuelve nil en las salidas limpias: ErrSalir, Ctrl-D, fin de la entrada o contexto cancelado.

Probar el ejemplo

cd estentor
go run ./cmd/ejemplo

Desde la raíz del proyecto. Los banners salen de cmd/ejemplo/banners/, y con -banners <carpeta> se le puede dar otra. Si no la encuentra, avisa por stderr y arranca sin banner.

Trae equipos, equipo <ip> —que completa las IPs con el tabulador y entra en su contexto—, escanear para ver una tarea de fondo, eco, y registrar <fichero> para volcar la sesión.

---

Consola

c := estentor.Nueva("idas")
c.Arrancar()

Nueva deja la consola leyendo de la entrada estándar y escribiendo en la salida estándar. Arrancar muestra un banner y ejecuta lo que se escriba, hasta que un comando devuelve ErrSalir o se acaba la entrada (Ctrl-D).

Campos que se pueden tocar:

Campo	Qué es
Nombre	lo que sale en el prompt
Entrada	de dónde lee. Por defecto os.Stdin
Salida	dónde escribe. Por defecto os.Stdout
Banners	textos de bienvenida, se muestra uno al azar
Variables	valores que se sustituyen en los textos
Prompt	función que compone el prompt. Por defecto nombre>
Color	ColorAuto, ColorSiempre o ColorNunca
Pegado	PegadoAuto o PegadoNunca: si lo pegado es texto o teclas
NoRecordar	qué líneas no entran en el historial
MaxLinea	lo más larga que puede ser una línea. Por defecto 1 MB

Entrada y Salida son io.Reader e io.Writer, así que se pueden cambiar por lo que sea. Es lo que permite probar la consola sin teclear nada:

c.Entrada = strings.NewReader("help\nexit\n")
c.Salida = &bytes.Buffer{}

Si lo que pones guarda lo escrito en un buffer —un bufio.Writer—, la consola lo vacía sola antes de quedarse esperando a que teclees y al cerrarse. Sin eso el prompt no aparecía hasta que el buffer se llenara, y parecía colgada.

Comandos

c.Registrar(estentor.Comando{
    Nombre:    "eco",
    Sinonimos: []string{"echo"},
    Ayuda:     "repite lo que se le pase",
    Ejecutar: func(ctx context.Context, args []string) error {
        if len(args) == 0 {
            return errors.New("falta el texto")
        }
        fmt.Fprintln(c.Salida, strings.Join(args, " "))
        return nil
    },
})

• Con una terminal de verdad hay historial, edición de línea y sugerencia en gris sacada del historial, que la flecha derecha acepta. Y tabulador para completar el nombre del comando: si casan varios avanza hasta lo común, y al segundo tabulador seguido te lista cuáles eran, sin tocar tu línea.
• El tabulador completa también los argumentos, si el comando dice cuáles con Completar. Lo que se teclea largo no es escanear, son sus argumentos.
• help <comando> enseña su ficha, sacada de Uso y Ayuda. Y Args comprueba cuántos argumentos hacen falta antes de ejecutar, con estentor.Exactamente(n) o estentor.AlMenos(n), para no volver a escribir esa comprobación en cada comando.
• help se construye solo. Cualquier comando registrado aparece en la ayuda con su descripción, ordenado y alineado. No hay ninguna lista que mantener.
• Los sinónimos funcionan igual que el nombre, pero en la ayuda salen junto a él en vez de como entradas aparte.
• El error no lleva el nombre del comando. La consola le pone delante eco: , así que si lo renombras el mensaje se corrige solo.
• Registrar un nombre que ya existe lo sustituye, así que se pueden reemplazar help o exit por versiones propias.

Salir

Un comando termina la consola devolviendo estentor.ErrSalir:

Ejecutar: func([]string) error {
    return estentor.ErrSalir
},

No es un fallo: es la forma de decir «hemos acabado», igual que io.EOF señala el final de una lectura sin ser un error. La consola lo distingue con errors.Is, así que se puede envolver con %w sin romper nada.

De fábrica

Comando	Sinónimos	Qué hace
clear	cls	limpia la pantalla y el historial de desplazamiento
help	?	lista los comandos
set		lista, enseña o guarda una variable
unset		quita una variable
back	atras	sale del contexto actual
jobs	trabajos	lista las tareas de fondo
kill	cancelar	pide a una tarea que pare
exit	quit, salir	termina

Tablas

Tabla no depende de la consola: se construye aparte y se puede usar en cualquier programa.

t := estentor.NuevaTabla("IP", "Referencia", "Estado")
t.Fila("10.20.0.41", "6ES7 516-3AN02-0AB0", "responde")
t.Fila("10.20.0.88", "AS228T-A", "responde")

fmt.Println(t)     // en cualquier programa
c.Tabla(t)         // o en la salida de la consola

  IP          Referencia           Estado
  ----------  -------------------  --------
  10.20.0.41  6ES7 516-3AN02-0AB0  responde
  10.20.0.88  AS228T-A             responde

• Cumple fmt.Stringer, así que fmt.Println, %v y %s la pintan solos. También hay Escribir(w io.Writer).
• Fila devuelve la tabla, así que se pueden encadenar llamadas.
• Los anchos se miden en columnas de terminal, no en bytes ni en caracteres: los acentos (también en NFD), la ñ y el CJK de ancho doble no descuadran las columnas.
• Los anchos se recalculan al pintar, así que una tabla se puede modificar y volver a imprimir sin que se descuadre.
• Una fila con menos celdas que cabeceras se completa con huecos; las celdas que sobran se ignoran.
• Sangria son los espacios de la izquierda. Por defecto dos.

Y se puede modificar, buscar dentro y ordenar:

t.Celda(0, 2, "sin identificar")   // cambia una celda; crece si no existe
t.CambiarFila(1, "10.20.0.88", "AS228T-A", "responde")
t.InsertarFila(0, "10.20.0.1", "?", "?")
t.BorrarFila(2)                     // false si esa fila no existía
t.Limpiar()                         // quita las filas, deja las cabeceras

valor, existe := t.Obtener(0, 2)    // nunca revienta
i := t.Buscar(0, "10.20.0.88")      // índice, o -1 si no está
i = t.BuscarSi(func(fila []string) bool {
    return strings.HasPrefix(fila[0], "10.20.")
})
sub := t.Filtrar(func(fila []string) bool {
    return fila[2] == "responde"    // tabla nueva, no toca la original
})
t.Ordenar(0)                        // estable

Celda y CambiarFila hacen crecer la tabla si la posición no existe, así que se puede rellenar por coordenadas sin preparar nada. Y a diferencia de indexar t.Filas a mano, nunca revientan.

Detalle completo en docs/tablas.md.

Color

fmt.Fprintln(c.Salida, c.Pintar("no se pudo", estentor.Rojo))
fmt.Fprintln(c.Salida, c.Pintar("listo", estentor.Verde, estentor.Negrita))

En automático se pinta solo con terminal de verdad, y respeta NO_COLOR y TERM=dumb. Los errores ya salen en rojo de fábrica.

Y en hexadecimal, degradando solo a la paleta de 256 si la terminal no admite 24 bits:

c.Pintar("critico", estentor.Hex("#ff5555"))

Las tablas se colorean por reglas, y los códigos no descuadran las columnas: el cálculo de anchos los descuenta.

t.ColorearCabeceras(estentor.Negrita)
t.ColorearColumnaEntera(0, estentor.Cian)
t.Colorear("responde", estentor.Verde)
t.Colorear("sin identificar", estentor.Hex("#ff8800"))

Detalle en docs/tablas.md.

Indicador de carga

parar := c.Cargando("Cargando {nombre} para {usuario}")
cargar()          // el trabajo real de arranque
parar()

Pinta [|] Cargando idas para marcos girando, y al llamar a parar() borra la línea entera.

Si la salida no es una terminal —redirigida a un fichero o a otro programa— no gira: escribe el texto una vez y ya está, para no llenar el log de basura.

Banners

banners, err := estentor.BannersDeCarpeta("banners")
if err != nil {
    fmt.Fprintf(os.Stderr, "aviso: %v\n", err)   // avisa...
}
c.Banners = banners                              // ...y arranca con los que haya

Lee los .txt de una carpeta y al arrancar muestra uno al azar. Para añadir uno propio basta con dejar un fichero ahí: no hay que tocar código ni recompilar.

Devuelve los que sí pudo leer y el error de los que no, a la vez. Un .txt sin permisos no se lleva por delante a los buenos: te dice cuál falló y sigues con el resto. Por eso el ejemplo avisa y continúa en vez de rendirse.

También se pueden poner a mano: c.Banners = []string{"..."}.

Variables

En los banners y en los textos de carga, lo que vaya entre llaves se sustituye:

Bienvenido a {nombre}, {usuario}
conectado desde {host}

De fábrica vienen {nombre} (el de la consola), {usuario} y {host}. Se pueden añadir más:

c.Variables["version"] = "0.1"

Una variable que no existe se deja tal cual, así que si escribes {usuraio} lo verás en pantalla en vez de un hueco vacío y el error salta a la vista.

Y se pueden poner desde el prompt con set, que escribe en el mismo sitio. Lo que tecleas se expande antes de ejecutarse, así que sirven en cualquier comando:

idas> set objetivo 10.20.0.41
idas 10.20.0.41> eco el objetivo es {objetivo}
el objetivo es 10.20.0.41

La sustitución ocurre después de partir la línea, así que un valor con espacios sigue siendo un solo argumento.

Para escribir la marca tal cual, una barra invertida delante:

idas> conectar \{objetivo}
conectar {objetivo}

Doblar la llave no escapa, y es a propósito: {{7*7}} es una carga de prueba contra plantillas de servidor y tiene que llegar al comando tal y como la tecleaste.

Contexto en pila

set se aplica al nivel donde estás, y lo que pones dentro se va al salir:

idas> set puerto 502
idas> equipo 10.20.0.41
idas 10.20.0.41> set puerto 102     ← tapa al de fuera, no lo pisa
idas 10.20.0.41> back
idas> set puerto
puerto = 502                        ← intacto

Es lo que arregla el problema de msfconsole, donde el almacén es global y lo que pones para un módulo se filtra al siguiente. set a secas dice de qué nivel sale cada valor.

Detalle en docs/consola.md.

También está c.Expandir(texto) para sustituirlas en cualquier otro sitio.

Ctrl-C

Hace dos cosas distintas según dónde estés:

• Escribiendo una línea: la descarta y vuelve a pedir. No cierra la consola.
• Con un comando en marcha: le cancela el contexto que ya recibe.

Ejecutar: func(ctx context.Context, args []string) error {
    for _, ip := range rango {
        if err := ctx.Err(); err != nil {
            return err          // Ctrl-C llega por aquí
        }
        escanear(ip)
    }
    return nil
}

Cancelar es pedir, no obligar: un comando que no mire su contexto seguirá hasta el final. Por eso el segundo Ctrl-C vuelve a ser el de siempre y mata el proceso — si atrapáramos también ese, un comando que ignora su contexto dejaría la consola sin forma de salir.

Por debajo, mientras corre un comando la terminal sale del modo crudo. Es lo que hace que Ctrl-C vuelva a generar una señal: en modo crudo no genera ninguna, es el byte 3, y mientras el comando corre no hay nadie leyéndolo. De paso, lo que teclees mientras tanto lo guarda la propia terminal y aparece en el prompt siguiente, en vez de perderse.

Sin terminal —una tubería, un fichero, un test— nada de esto se activa, y SIGINT sigue matando el proceso, que es lo que espera cualquiera que meta esto en un script.

Buscar en el historial

Ctrl-R busca hacia atrás por subcadena. Otro Ctrl-R salta a la anterior que también case, Intro la ejecuta y Ctrl-C cancela la búsqueda dejando la línea como estaba.

t> (buscar)'motivo': set motivo acordado con produccion

El prompt cambia mientras buscas, y dice sin resultado cuando no encuentra nada en vez de quedarse callado enseñando algo viejo.

Moverse por palabras

Ctrl-W borra la palabra de atrás, Alt-B / Ctrl-← y Alt-F / Ctrl-→ mueven, y Alt-D borra la de delante. Entre «un carácter» y «toda la línea» no había nada, y con un comando de 120 caracteres eso son 40 pulsaciones de flecha.

Una palabra es un trozo entre espacios, y nada más. Es una decisión: bash corta además por puntuación en Alt-B, y aquí 10.20.0.0/24 serían cinco palabras. Predecible gana a cómodo.

Historial entre sesiones

El historial vive en memoria, y la biblioteca no decide dónde se guarda:

if f, err := os.Open(ruta); err == nil {
    _ = c.CargarHistorial(f)
    f.Close()
}

c.Arrancar()

if f, err := os.OpenFile(ruta, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0o600); err == nil {
    _ = c.GuardarHistorial(f)
    f.Close()
}

Sin esto, cada arranque empieza de cero — y no solo pierdes la flecha arriba: la sugerencia en gris mira el historial antes que los nombres de comando, así que sin persistencia solo sabe media cosa.

El 0600 no es decorativo. Esto escribe a disco lo que tecleas, y en una consola de auditoría eso son objetivos y rangos de red de un cliente. Para dejar cosas fuera:

c.NoRecordar = func(linea string) bool {
    return strings.Contains(linea, "--clave")
}

Se filtra al entrar, no al guardar, así que lo filtrado tampoco sale por la flecha arriba ni por la sugerencia.

Pegar texto

Lo que pegas entra como texto, no como teclas: los saltos de línea no ejecutan nada, el tabulador no completa y un Ctrl-C dentro no interrumpe. Pegas una lista de IPs, la revisas, y entonces pulsas Intro.

Como la línea de edición es una sola, los saltos pegados se quedan en espacios. Es lo único que puede verse ahí.

Se apaga con c.Pegado = estentor.PegadoNunca, y entonces pegar vuelve a ser teclear muy rápido. Está por una lección ajena: GNU readline lo trae activado desde la 8.1, pero CPython y FRR tuvieron que desactivarlo porque rompía a quien pegaba una configuración contando con que los saltos la fueran ejecutando.

Volcar la sesión a un fichero

parar := c.Registrando(f)   // desde un comando, con la consola en marcha
defer parar()

Guarda las preguntas y las respuestas: las líneas tecleadas con su prompt, la salida de los comandos y los avisos de las tareas de fondo, sin códigos de color. Con 0600, que es una sesión real contra sistemas de alguien.

Tareas de fondo

c.Lanzar("escaneo", func(ctx context.Context) error { ... })

jobs lista y kill N pide parar. Lo que costaba no eran las goroutines: una tarea que escribe mientras tecleas aparta tu línea, escribe encima y la repinta, con el cursor donde estaba.

Cancelar es pedir, no obligar: una tarea que no mire su contexto seguirá hasta el final.

Lo que no hace

Para que no lo descubras tecleando. Nada de esto está previsto hoy, y algunas cosas son decisiones y otras deudas:

Copiar la Consola. Trabaja siempre con el puntero que devuelve Nueva. Copiarla por valor comparte el registro de comandos con la original y deja los comandos de fábrica escribiendo en la salida de la primera. go vet lo avisa.

Cancelar no interrumpe una lectura en curso. ArrancarCon(ctx) cierra la consola desde fuera, pero si la cancelación llega mientras se está esperando a que alguien teclee, no se nota hasta que teclee.

Redimensionar la ventana a mitad de línea. El ancho de la terminal se vuelve a preguntar al empezar cada línea, no dentro de una: si estiras la ventana con un comando largo a medio escribir, se descuadra hasta que pulses Intro.

Estructura

estentor/
├── consola.go              la consola, los comandos, el registro y los banners
├── editor.go               el editor de línea propio
├── teclas.go               decodificador de teclas y secuencias de escape
├── tabla.go                tablas, independientes de la consola
├── color.go                estilos, hexadecimales y detección de terminal
├── contexto.go             la pila de niveles
├── trabajos.go             las tareas de fondo
├── *_test.go               al lado del código: Go lo exige
├── docs/                   las guías de uso
└── cmd/
    ├── ejemplo/            aplicación de ejemplo, con sus banners
    └── analizar/           el analizador del proyecto

El código de la biblioteca vive en la raíz del módulo, que es la convención de Go para un repositorio que es una biblioteca: se importa con la ruta a secas, sin un /pkg ni un /internal por el medio.

Comprobar el código

Todo de golpe:

go run ./cmd/analizar

Encadena formato, go vet, golangci-lint con 19 analizadores y los tests con detector de carreras y cobertura.

Dos cosas a propósito:

• Está en Go y no en un script. Funciona igual en Linux, macOS y Windows, y no pide instalar nada: si tienes el proyecto, tienes Go.
• Ejecuta siempre todos los pasos, aunque alguno falle, y resume al final. Un análisis que se para en el primer problema te hace dar una vuelta por cada uno.

Si golangci-lint no está instalado, lo dice y sigue, y el resumen distingue SIN COMPROBAR de FALLA. No dar por bueno lo que no se ha mirado.

Con -cobertura abre además el informe línea a línea en el navegador:

go run ./cmd/analizar -cobertura

Suelto:

gofmt -l .           # ficheros mal formateados. Vacío = bien
go build ./...       # ¿compila todo?
go vet ./...         # fallos que compilan pero están mal
go test -race ./...  # los tests, buscando carreras de datos
go doc github.com/MarcosGiojiho/estentor   # la documentación del código

golangci-lint se instala con brew install golangci-lint. La configuración está en .golangci.yml, y cada exclusión lleva escrito su motivo, porque una exclusión sin justificar es como se oxida un linter hasta que nadie lo mira.

Cubre lo que buscarías en una herramienta tipo SonarQube —duplicación con dupl, complejidad con gocognit y gocyclo, seguridad con gosec— sin servidor ni contenedor. Lo que no da es historial entre commits ni puerta de calidad, y eso empieza a hacer falta con varias personas o un CI, no aquí.

Licencia

Apache License 2.0. Ver LICENSE.