Diegolden

project-structure

Se lee en 7 min

Estructura del proyecto ein-cli

Este documento proporciona una descripción general completa de la estructura del proyecto ein-cli, explicando el propósito y la funcionalidad de cada componente.

📁 Directorio raíz

ein-cli/
├── main.go                    # Application entry point
├── go.mod                     # Go module definition and dependencies
├── go.sum                     # Dependency checksums (auto-generated)
├── plan.md                    # Development roadmap and implementation plan
├── PROJECT_STRUCTURE.md       # This file - project documentation
└── .gitignore                 # Git ignore rules

Archivos raíz clave

  • main.go: el punto de entrada principal que determina si se inicia el modo CLI o TUI según los argumentos de la línea de comandos.
  • go.mod: Define el módulo Go con todas las dependencias de la pila Charm (bubbletea, bubbles, lipgloss, cobra, viper)
  • plan.md: Plan de desarrollo integral con fases de implementación y decisiones de arquitectura

🖥️ Módulo CLI (cmd/)

El módulo CLI utiliza el marco Cobra para proporcionar funcionalidad de interfaz de línea de comandos.

cmd/
├── root.go                    # Root command configuration and global flags
├── api.go                     # API request commands for CLI usage
└── version.go                 # Version information command

Componentes CLI

cmd/root.go

  • Propósito: configuración del comando CLI principal y configuración global
  • Características:
    • Banderas globales (—verbose, —output, —config)
    • Carga de archivos de configuración con Viper
    • Enlace de variables de entorno
    • Estructura de mando base

cmd/api.go

  • Propósito: comandos CLI para realizar solicitudes de API directamente desde la línea de comandos
  • Características:
    • Validación del método HTTP (GET, POST, PUT, DELETE, etc.)
    • Análisis y validación de encabezados.
    • Solicitar manipulación del cuerpo.
    • Configuración de tiempo de espera
    • Actualmente muestra información de la solicitud (implementación del cliente HTTP pendiente)

cmd/version.go

  • Propósito: Mostrar versión, fecha de compilación e información de confirmación de git.
  • Características:
    • Visualización de información de versión.
    • Crear metadatos (establecidos mediante indicadores de compilación en producción)

🏗️ Módulos internos (internal/)

Los paquetes internos contienen código de aplicación privado que no pueden importar proyectos externos.

internal/
├── messages/
│   └── navigation.go          # Custom Bubbletea messages for screen navigation
└── models/
    ├── config.go              # Configuration data structures
    └── api.go                 # API request/response models

Componentes internos

internal/messages/navigation.go

  • Propósito: mensajes personalizados de Bubbletea para comunicación entre pantallas
  • Características:
    • NavigateMsg: Tipo de mensaje para solicitar cambios de pantalla
    • Rompe los ciclos de importación entre paquetes TUI

internal/models/config.go

  • Propósito: Estructuras de configuración y valores predeterminados de la aplicación
  • Características:
    • Config: Estructura de configuración principal
    • ServerConfig: configuración predeterminada del servidor (URL, tiempo de espera, encabezados)
    • ThemeConfig: preferencias del tema de la interfaz de usuario (combinación de colores, color de acento)
    • HistoryConfig: Solicitar configuración de comportamiento del historial
    • AuthConfig: Configuración de autenticación y almacenamiento de tokens
    • NewDefaultConfig(): Crea una configuración predeterminada sensata

internal/models/api.go

  • Propósito: Modelos de datos para solicitudes y respuestas de API
  • Características:
    • APIRequest: estructura completa de la solicitud (método, URL, encabezados, cuerpo, autenticación)
    • APIResponse: Datos de respuesta (estado, encabezados, cuerpo, tiempo, errores)
    • AuthInfo: información de autenticación para diferentes tipos de autenticación
    • RequestHistory: Almacenamiento de solicitudes históricas
    • HistoryEntry: pares de solicitud-respuesta individuales
    • Métodos auxiliares para verificar el código de estado (IsSuccess(), IsClientError(), etc.)

🎨 Módulo TUI (tui/)El módulo TUI utiliza la pila Charm (Bubbletea, Bubbles, Lipgloss) para proporcionar una interfaz de usuario de texto interactiva.

tui/
├── app.go                     # Main TUI application and coordinator
├── router.go                  # Screen navigation and routing system
├── keys.go                    # Global key bindings and shortcuts
├── styles/
│   ├── theme.go              # Color palette and base styles
│   └── components.go         # Component-specific styling
└── screens/
    ├── main_menu.go          # Main menu screen with navigation options
    ├── api_form.go           # API request form screen (placeholder)
    ├── settings.go           # Settings configuration screen (placeholder)
    └── help.go               # Help and documentation screen

Componentes principales de TUI

tui/app.go

  • Propósito: Aplicación TUI principal que coordina todas las pantallas y maneja el estado global
  • Características:
    • Gestión del ciclo de vida de la aplicación (Init, Update, View)
    • Registro e inicialización del modelo de pantalla.
    • Manejo y enrutamiento de mensajes globales.
    • Manejo de cambio de tamaño de ventana
    • Representación de encabezado/pie de página con rutas de navegación
    • Creación de comandos de navegación.

tui/router.go

  • Propósito: Sistema de navegación entre diferentes pantallas TUI
  • Características:
    • Enumeración de pantalla (MainMenu, APIForm, Settings, etc.)
    • Historial de navegación para la funcionalidad del botón Atrás
    • Transmisión de datos de pantalla a pantalla
    • Generación de ruta de navegación
    • Gestión de modelos para cada pantalla.

tui/keys.go

  • Propósito: Definiciones de enlace de claves centralizadas
  • Características:
    • Teclas de navegación (flechas, estilo vim j/k/h/l)
    • Teclas de acción (Entrar, Espacio, Tabulador)
    • Control de aplicaciones (salir, retroceder, ayudar)
    • Teclas de función especiales (actualizar, editar, eliminar, guardar)
    • Generación de texto de ayuda para cada enlace.

Estilo TUI (tui/styles/)

tui/styles/theme.go

  • Propósito: paleta de colores global y definiciones de estilo base
  • Características:
    • Paleta de colores: elegante tema morado con buen contraste
      • Primary: Purple (#8B5CF6), PurpleLight (#A78BFA), PurpleDark (#6D28D9)
      • Neutrals: White, Gray, GrayLight, GrayDark
      • Status: Green, Red, Orange, Blue
  • Estilos base: BaseStyle, TitleStyle, SubtitleStyle, TextStyle, HelpStyle

tui/styles/components.go

  • Propósito: Estilo específico del componente para elementos de interfaz de usuario consistentes
  • Características:
    • Estilos de menú: contenedor, elementos, selección, estados de desplazamiento
    • Estilos de formulario: contenedores de formulario, entradas, etiquetas, estados de enfoque
    • Estilos de botones: estados primario, secundario y de desplazamiento
    • Estilos de estado: éxito, error, indicadores de carga
    • Estilos de diseño: contenedores, encabezados y pies de página con el espacio adecuado

Pantallas TUI (tui/screens/)

tui/screens/main_menu.go

  • Propósito: centro de navegación principal con opciones de menú
  • Características:
    • Elementos del menú con iconos y descripciones.
    • Navegación a diferentes pantallas de aplicaciones.
    • Representación de lista personalizada con tema morado
    • Salir de la funcionalidad
    • Mensaje de bienvenida y consejos de uso.

tui/screens/api_form.go

  • Propósito: Formulario para crear y editar solicitudes de API (marcador de posición)
  • Características:
    • Navegación por el campo del formulario (Tab/Shift+Tab)
    • Seguimiento de campo y preparación de validación.
    • Integración con el modelo APIRequest
    • Implementación futura: campos de formulario completos con la biblioteca Huh

tui/screens/settings.go

  • Propósito: Interfaz de gestión de configuración (marcador de posición)
  • Características:
    • Pantalla de configuración actual
    • Vista previa de la configuración de servidor, tema, historial y autenticación
    • Implementación futura: formularios de configuración interactivos

tui/screens/help.go- Finalidad: Documentación y sistema de ayuda.

  • Características:
    • Documentación de atajos de teclado organizada por categoría
    • Consejos de uso y guía de introducción
    • Información de la aplicación y sobre la sección.
    • Texto de ayuda contextual

🔧 Patrones de arquitectura

Patrón Modelo-Vista-Actualización (MVU)

La TUI sigue la arquitectura MVU de Bubbletea:

  • Modelo: Estado y datos de la aplicación
  • Ver: funciones de renderizado que convierten el estado en cadenas
  • Actualización: manejadores de mensajes que modifican el estado

Cada pantalla es un modelo Bubbletea autónomo:

  • Gestión estatal independiente.
  • Manejo y enrutamiento de mensajes.
  • Implementación de interfaz consistente

Lógica empresarial compartida

La funcionalidad principal se comparte entre CLI y TUI:

  • Mismos modelos de configuración
  • Estructuras de solicitud de API idénticas
  • Lógica común de validación y procesamiento.

Prevención del ciclo de importación

  • Los mensajes están aislados en internal/messages/
  • Las constantes de la pantalla se definen localmente para evitar ciclos.
  • Dependencias basadas en interfaz cuando sea necesario

🎨 Principios de diseño

Elegante tema morado

  • Color de acento púrpura constante (#8B5CF6) en todas partes
  • Buenas relaciones de contraste para accesibilidad
  • Apariencia profesional con sutil elegancia.

Diseño responsivo

  • Conciencia del tamaño del terminal
  • Espaciado y acolchado adecuados
  • Dimensionamiento de componentes flexible

Teclado: navegación primero

  • Navegación estilo Vim (j/k/h/l) junto a las flechas
  • Navegación de formulario basada en pestañas
  • Atajos intuitivos con texto de ayuda

Arquitectura extensible

  • Fácil de agregar nuevas pantallas y comandos.
  • Patrones consistentes entre componentes
  • Separación limpia de preocupaciones.

🚀 Primeros pasos

Ejecutando la aplicación

# TUI Mode (interactive)
./ein-cli
 
# CLI Mode (direct commands)
./ein-cli --help
./ein-cli version
./ein-cli api GET https://httpbin.org/get

Flujo de trabajo de desarrollo

  1. Agregar nuevas pantallas: cree en tui/screens/, regístrese en tui/app.go
  2. Agregar comandos CLI: crear en cmd/, agregar al comando raíz
  3. Modelos extendidos: Modificar estructuras en internal/models/
  4. Actualizaciones de estilo: ajuste en tui/styles/ para una temática consistente

Próximos pasos

Según plan.md, las próximas fases de desarrollo implican:

  1. Implementación del cliente HTTP
  2. Componentes de formulario avanzados con Huh
  3. Solicitar historial y persistencia
  4. Gestión de la configuración
  5. Sistemas de autenticación

Esta arquitectura proporciona una base sólida para crear una herramienta cliente API integral con interfaces CLI y TUI.

Vista gráfica

Retroenlaces