# Gu铆a de Uso de MRDevs Tools ## 馃殌 Inicio R谩pido ### Requisitos Previos - Git instalado en su sistema - Permisos de administrador (para algunas operaciones) - Conexi贸n a Internet ### Instalaci贸n ```bash # Clonar el repositorio cd $HOME git clone https://git.rosero.one/mrosero/devs.git # Instalar herramientas b谩sicas cd $HOME/devs bin/bootstrap.sh # Configurar SOPS para encriptaci贸n GPG (obligatorio) bin/sops_rules.sh # Actualizar el entorno (opcional) bin/update.sh ``` > **IMPORTANTE**: La configuraci贸n del arcivo de reglas de sops .sops.yaml es un paso obligatorio antes de poder utilizar la plataforma. bin/sops_rules.sh crea el archivo base de configguraci贸n sops para el proyecto. Las claves GPG del desarrollador principal debe existir en el repositorio de claves. ### Estructura de Directorios MRDevs Tools utiliza una estructura organizada que separa el c贸digo (en ~/devs) y la configuraci贸n (en directorios ocultos): #### C贸digo y scripts - `~/devs/bin/`: Scripts ejecutables y herramientas principales - `lib/`: Bibliotecas compartidas de funciones - `msg/`: Archivos de mensajes multiling眉es - `config/`: Configuraci贸n del sistema #### Configuraci贸n y datos - `~/.sounds/`: Archivos de audio para notificaciones y alertas - `~/.ollama/`: Configuraci贸n, modelos y datos para Ollama AI - `~/.vosk/`: Modelos para reconocimiento de voz local - `~/.cortana/`: Configuraci贸n y tokens para Claude Code - `~/.developer/`: Tokens y configuraciones para herramientas de desarrollo - `~/.cache/devs/`: Cach茅 de descargas y datos temporales ## 馃敡 Funcionalidades Principales ### Gesti贸n del Entorno de Desarrollo | Comando | Descripci贸n | |---------|-------------| | `bin/bootstrap.sh` | Instala herramientas b谩sicas (incluyendo oathtool, zbar, redis-cli, gum y glow) y configura la gesti贸n de contenedores | | `bin/sops_rules.sh` | Configura SOPS con clave GPG para encriptaci贸n segura de secretos (paso obligatorio tras la instalaci贸n) | | `bin/update.sh` | Actualiza el entorno de desarrollo y herramientas (incluyendo oathtool, zbar, redis-cli, gum y glow) | | `bin/npm_install.sh` | Instala NodeJS y npm de forma interactiva | | `bin/project_new.sh` | Crea un nuevo proyecto con estructura estandarizada seg煤n el tipo seleccionado | ### Herramientas de CLI Modernas MRDevs Tools integra herramientas modernas de Charm para mejorar la experiencia en la l铆nea de comandos: | Herramienta | Descripci贸n | |---------|-------------| | [Gum](https://github.com/charmbracelet/gum) | Toolkit para interfaces TUI elegantes y funcionales | | [Glow](https://github.com/charmbracelet/glow) | Renderizador de Markdown para terminal con soporte para temas y paginaci贸n | #### Interfaces de Usuario con Gum | Comando/Documento | Descripci贸n | |---------|-------------| | `docs/gum.md` | Tutorial completo para crear formularios interactivos con Gum | | `gum style` | Da formato al texto (color, negrita, etc.) | | `gum input` | Campo de entrada para texto | | `gum choose` | Men煤 de selecci贸n de opciones | | `gum confirm` | Di谩logo de confirmaci贸n (S铆/No) | ### Herramientas de IA y Productividad | Comando | Descripci贸n | |---------|-------------| | `bin/claude_install.sh` | Instala Claude Code CLI | | `bin/claude_install.sh -u` | Desinstala Claude Code CLI | | `bin/cortana_token.sh` | Gestiona la encriptaci贸n del token de Claude Code v铆a SOPS | | `bin/jarvis_token.sh` | Gestiona la encriptaci贸n del token de Jarvis v铆a SOPS | | `bin/cortana_alias.sh` | Configura alias 'cortana' para Claude Code | | `bin/cortana_unalias.sh` | Elimina el alias 'cortana' | | `bin/cortana_enable.sh` | Activa el alias 'cortana' permanentemente | | `bin/cortana_disable.sh` | Desactiva temporalmente el alias 'cortana' | | `bin/aider_install.sh` | Instala Aider CLI (asistente de c贸digo IA) | | `bin/aider_install.sh -u` | Desinstala Aider CLI | | `bin/sora_enable.sh` | Activa el alias 'sora' para Aider permanentemente | | `bin/sora_disable.sh` | Desactiva el alias 'sora' para Aider | | `bin/ai_token.sh` | Gestiona tokens de m煤ltiples proveedores de IA v铆a SOPS | | `bin/ollama_up.sh` | Inicia el servicio Ollama (IA local) con podman-compose. Crea y configura `~/.ollama/` | | `bin/ollama_down.sh` | Detiene el servicio Ollama (IA local) | | `bin/ollama.sh` | Cliente para interactuar con Ollama (auto-inicia el servicio si es necesario) | | `bin/nodered.sh` | Administra Node-RED con soporte para ejecuci贸n, monitoreo y gesti贸n completa del servicio | ### Herramientas para Editores de C贸digo | Comando | Descripci贸n | |---------|-------------| | `bin/helix_install.sh` | Instala Helix Editor con soporte multiplataforma (apt, snap, pacman, etc.) | | `bin/helix_install.sh -u` | Desinstala Helix Editor del sistema | | `bin/vscode_install.sh` | Instala Visual Studio Code con detecci贸n autom谩tica del SO y sus m茅todos de instalaci贸n | | `bin/vscode_install.sh -u` | Desinstala Visual Studio Code del sistema | | `bin/zettlr_install.sh` | Instala Zettlr Markdown Editor con detecci贸n autom谩tica del SO | | `bin/zettlr_install.sh -u` | Desinstala Zettlr Markdown Editor del sistema | ### Herramientas para Control de Versiones | Comando | Descripci贸n | |---------|-------------| | `bin/backlog.sh ` | Revierte el repositorio o archivos espec铆ficos al estado de un commit concreto | | `bin/ghadmin_install.sh` | Instala GitHub CLI (gh) con soporte multiplataforma | | `bin/gladmin_install.sh` | Instala GitLab CLI (glab) con m煤ltiples m茅todos de instalaci贸n | | `bin/fjadmin_install.sh` | Instala Forgejo CLI (berg) para administraci贸n de Forgejo/Codeberg | | `source bin/forgejo_login.sh` | Inicia/cierra sesi贸n en Forgejo usando tokens encriptados con SOPS | | `source bin/github_login.sh` | Inicia/cierra sesi贸n en GitHub usando tokens encriptados con SOPS | | `bin/cversion_token.sh` | Gestiona tokens de acceso para plataformas de control de versiones de forma segura | ### Seguridad y Acceso | Comando | Descripci贸n | |---------|-------------| | `bin/sops_rules.sh` | Configura SOPS con clave GPG para encriptaci贸n segura de secretos ([documentaci贸n](sops_rules.md)) | | `bin/qr_secret.sh` | Extrae secretos de im谩genes QR y los guarda encriptados con [SOPS](sops.md) | | `bin/vpn_install.sh` | Instala el cliente Pritunl VPN | | `bin/vpn_install.sh --update` | Actualiza el cliente VPN a la 煤ltima versi贸n | | `bin/vpn_users.sh` | Gestiona usuarios de la VPN | | `bin/vpn_check.sh` | Verifica conexi贸n a VPN y muestra el tipo de VPN activo | | `bin/gpg_init.sh` | Inicializa configuraci贸n GPG para cifrado seguro | ### Gesti贸n de Perfiles | Comando | Descripci贸n | |---------|-------------| | `bin/profile_backup.sh` | Realiza copia de seguridad del perfil del desarrollador (GPG, SSH, Git, y carpeta .developer) | | `bin/profile_restore.sh ` | Restaura perfil desde copia de seguridad | ### Desarrollo Especializado | Comando | Descripci贸n | |---------|-------------| | `bin/rate_update.py` | Actualiza tarifas por hora de diferentes tipos de programadores | | `bin/cocomo.py` | Calcula costos de proyecto usando el modelo COCOMO | ## 馃摎 Gu铆a Detallada ### Herramientas de CLI Modernas MRDevs Tools incluye soporte completo para herramientas modernas de CLI de [Charm](https://charm.sh/): #### Gum y Glow - Herramientas TUI Modernas MRDevs Tools incorpora dos potentes utilidades de [Charm](https://charm.sh/) para mejorar la experiencia de l铆nea de comandos: - **[Gum](gum.md)**: Crea interfaces TUI interactivas y elegantes para scripts de shell - **[Glow](glow.md)**: Renderiza archivos Markdown directamente en la terminal con estilos Para obtener informaci贸n detallada sobre estas herramientas, consulta su documentaci贸n espec铆fica: - [Documentaci贸n completa de Gum](gum.md) - [Documentaci贸n completa de Glow](glow.md) ### Preparaci贸n del Entorno El directorio `$HOME/devs` sirve como 谩rea principal de desarrollo donde se gestionan diversos ambientes y proyectos. Por razones de seguridad, se prioriza [podman](https://podman.io/) sobre [docker](https://www.docker.com/) como gestor de contenedores. Para agregar temporalmente los comandos de la plataforma al PATH: ```bash source ~/devs/bin/devset.sh ``` Este script detecta autom谩ticamente la ubicaci贸n correcta del directorio bin y lo agrega al PATH solo para la sesi贸n actual (no es persistente). Si desea usar Docker en lugar de Podman, debe instalarlo manualmente antes de ejecutar `bootstrap.sh`. ### Gesti贸n Avanzada de Repositorios Git ```bash # Revertir todo el repositorio a un commit espec铆fico bin/backlog.sh a1b2c3d # Recuperar solo un archivo espec铆fico desde un commit bin/backlog.sh a1b2c3d --file src/config.js # Recuperar m煤ltiples archivos usando un patr贸n bin/backlog.sh a1b2c3d --files "*.js" # Ver solo la lista de archivos modificados en un commit bin/backlog.sh a1b2c3d --list # Ver la ayuda completa del comando bin/backlog.sh --help ``` El script `backlog.sh` permite recuperar estados previos del repositorio con varias opciones de seguridad: - Crea ramas de respaldo autom谩ticamente antes de realizar cambios - Ofrece guardar cambios no confirmados en stash - Proporciona confirmaciones interactivas antes de acciones potencialmente destructivas - Incluye instrucciones para deshacer los cambios si fuera necesario ### Configuraci贸n de Herramientas de IA MRDevs Tools facilita el trabajo con herramientas de IA: #### Claude Code CLI ```bash # Instalaci贸n bin/claude_install.sh # Gesti贸n del token de forma segura bin/cortana_token.sh # Crear alias para facilitar su uso (cortana = claude) bin/cortana_alias.sh # Habilitar uso del alias permanentemente bin/cortana_enable.sh # Deshabilitar temporalmente el alias bin/cortana_disable.sh # Eliminar el alias (si es necesario) bin/cortana_unalias.sh ``` El token se encripta usando SOPS y se almacena de forma segura en `$HOME/.cortana/cortana.sops.yaml`. ##### Control por voz (Experimental) MRDevs Tools incluye un script experimental para interactuar con Claude Code mediante comandos de voz: ```bash # Ver instrucciones para instalar dependencias bin/claude_voice.py --install-deps # Para sistemas Ubuntu/Debian sudo apt install python3-pyaudio python3-pip pip install --user vosk pydub sounddevice wget # Modo interactivo b谩sico (espa帽ol por defecto) bin/claude_voice.py # Ver idiomas soportados bin/claude_voice.py --list-languages # Usar idioma espec铆fico (ingl茅s) bin/claude_voice.py --language en-us # Modo continuo (escucha hasta que digas "salir") bin/claude_voice.py --continuous # Listar dispositivos de audio disponibles bin/claude_voice.py --list-devices # Especificar dispositivo de audio por ID bin/claude_voice.py --device 1 # Ver la versi贸n de Claude Code instalada bin/claude_voice.py --version # Modificar tiempo m谩ximo de espera para respuestas (en segundos) bin/claude_voice.py --timeout 30 # Enviar texto directamente (sin voz) bin/claude_voice.py --text "C贸mo puedo crear un archivo en Python" ``` > **NOTA**: Esta funcionalidad es experimental y requiere un micr贸fono configurado correctamente. El reconocimiento de voz utiliza Vosk, una soluci贸n local que no requiere conexi贸n a Internet. La primera vez que ejecutes el script con un nuevo idioma, descargar谩 autom谩ticamente el modelo de reconocimiento correspondiente. Los archivos de sonido para notificaciones se almacenan en `~/.sounds/`. #### Aider CLI ```bash # Instalaci贸n bin/aider_install.sh # Habilitar alias para facilitar su uso (sora = aider) bin/sora_enable.sh # Deshabilitar el alias bin/sora_disable.sh # Desinstalar (si es necesario) bin/aider_install.sh -u ``` Aider es un asistente de c贸digo basado en IA que te permite colaborar con modelos de lenguaje de OpenAI directamente desde la terminal. El script de instalaci贸n utiliza el instalador oficial de Aider. #### Gestor de Tokens de IA ```bash # Gestionar tokens de diferentes proveedores de IA bin/ai_token.sh ``` El script `ai_token.sh` proporciona una forma centralizada y segura de gestionar tokens de API para m煤ltiples proveedores de IA: - Muestra un men煤 interactivo con los proveedores disponibles definidos en `bin/config/ai.tokens` - Solicita y valida el token de API de forma segura - Encripta el token usando SOPS y lo almacena en `$HOME/sops/{provider}.sops.yaml` - Incluye verificaciones de seguridad (longitud del token, caracteres v谩lidos) - Soporte completo para internacionalizaci贸n Proveedores soportados por defecto: Anthropic Claude, OpenAI ChatGPT, Google Gemini, Groq, DeepSeek, HuggingFace, Replicate, OpenRouter, Brave Search, Serper Search, Voyage RAG, Apify y m谩s. La configuraci贸n de proyectos se almacena en `bin/config/projects.dat`, donde se encuentra el nombre de la carpeta de proyectos utilizada por el sistema. ### Instalaci贸n de Editores de C贸digo #### Helix Editor Helix es un editor de c贸digo moderno similar a Vim/Neovim pero con una curva de aprendizaje m谩s amigable: ```bash # Instalaci贸n automatizada bin/helix_install.sh ``` El script detecta autom谩ticamente tu sistema operativo y utiliza el m茅todo de instalaci贸n m谩s adecuado: - En Ubuntu: Instala mediante snap para obtener la versi贸n m谩s reciente - En Arch Linux: Utiliza pacman - En Fedora: Instala a trav茅s de dnf - En otros sistemas: Descarga e instala desde el tarball oficial #### Visual Studio Code Visual Studio Code es un editor de c贸digo potente y extensible con amplio soporte para m煤ltiples lenguajes: ```bash # Instalaci贸n automatizada bin/vscode_install.sh # Desinstalaci贸n bin/vscode_install.sh -u ``` El script ofrece una instalaci贸n optimizada para cada plataforma: - En Ubuntu/Debian: Configura el repositorio oficial de Microsoft y utiliza apt - En Red Hat/Fedora: Configura el repositorio RPM y utiliza dnf - En Arch Linux: Instala desde AUR o repositorios oficiales - En macOS: Utiliza Homebrew para la instalaci贸n - En FreeBSD: Instala mediante el gestor de paquetes pkg #### Zettlr Markdown Editor Zettlr es un potente editor Markdown centrado en acad茅micos e investigadores, con funcionalidades avanzadas: ```bash # Instalaci贸n automatizada bin/zettlr_install.sh # Desinstalaci贸n bin/zettlr_install.sh -u ``` El script proporciona una instalaci贸n especializada para cada plataforma: - En Ubuntu/Debian: Descarga e instala el paquete .deb oficial - En Red Hat/Fedora: Descarga e instala el paquete .rpm oficial - En Arch Linux: Instala desde AUR con ayuda de yay - En macOS: Utiliza Homebrew para instalaci贸n - En FreeBSD: Configuraci贸n manual con AppImage (no hay soporte oficial) Caracter铆sticas del instalador: - Obtiene autom谩ticamente la 煤ltima versi贸n disponible desde GitHub - Solicita permisos de administrador cuando son necesarios - Utiliza interfaz gr谩fica para confirmaci贸n y l铆nea de comandos para instalaci贸n - Limpia archivos de configuraci贸n residuales durante la desinstalaci贸n - Proporciona informaci贸n detallada sobre las caracter铆sticas de Zettlr ### Herramientas para Control de Versiones MRDevs Tools incluye scripts para simplificar la instalaci贸n de CLIs para diferentes plataformas Git: #### GitHub CLI (gh) ```bash # Instalaci贸n automatizada bin/ghadmin_install.sh ``` El script detecta tu sistema operativo y utiliza el m茅todo de instalaci贸n m谩s adecuado: - En Debian/Ubuntu: A帽ade el repositorio oficial de GitHub y usa apt - En Red Hat/Fedora: Configura el repositorio rpm y usa dnf - En Arch Linux: Instala desde los repositorios oficiales - En macOS: Instala a trav茅s de Homebrew Para aprender a usar GitHub CLI, consulta la [documentaci贸n oficial de GitHub CLI](https://cli.github.com/manual/). #### GitLab CLI (glab) ```bash # Instalaci贸n automatizada bin/gladmin_install.sh ``` El script prioriza los m茅todos de instalaci贸n en este orden: 1. Paquetes oficiales del sistema si est谩n disponibles 2. Script oficial de instalaci贸n de GitLab 3. Gestores de paquetes como snap o Homebrew 4. Binarios precompilados o instalaci贸n v铆a Go Para aprender a usar GitLab CLI, consulta la [documentaci贸n oficial de GitLab CLI](https://gitlab.com/gitlab-org/cli/-/blob/main/docs/index.md). #### Forgejo CLI (berg) ```bash # Instalaci贸n automatizada bin/fjadmin_install.sh ``` Este script instala Forgejo CLI (berg), la herramienta de l铆nea de comandos para administrar instancias de Forgejo/Codeberg: - Verifica e instala las dependencias necesarias (como Rust y Cargo si no est谩n presentes) - Instala berg de manera optimizada para tu sistema - Configura el entorno correctamente para usar berg - Incluye instrucciones posteriores a la instalaci贸n Para aprender a usar Forgejo CLI, consulta la [documentaci贸n oficial de Forgejo/Codeberg CLI](https://codeberg.org/RobWalt/berg). #### Gesti贸n de tokens para control de versiones ```bash # Gesti贸n segura de tokens de acceso bin/cversion_token.sh ``` Este script proporciona una interfaz para gestionar tokens de acceso para diferentes plataformas: - Permite seleccionar entre Github, Gitlab y Forgejo - Solicita y valida el token de forma segura - Encripta el token con SOPS y lo almacena en ~/.developer - Incluye verificaci贸n de formato y seguridad de tokens - Gestiona autom谩ticamente permisos para archivos de tokens #### Autenticaci贸n con Forgejo y GitHub usando token encriptado ```bash # Iniciar sesi贸n en Forgejo usando el token encriptado source bin/forgejo_login.sh # Cerrar sesi贸n de Forgejo source bin/forgejo_login.sh --logout # Iniciar sesi贸n en GitHub usando el token encriptado source bin/github_login.sh # Cerrar sesi贸n de GitHub source bin/github_login.sh --logout ``` El script de Forgejo facilita la autenticaci贸n con Forgejo/Codeberg CLI (berg): - Utiliza el token almacenado y encriptado por cversion_token.sh - Desencripta autom谩ticamente el token usando SOPS - Detecta la URL de Forgejo bas谩ndose en la configuraci贸n de git - Configura la variable BERG_BASE_URL con la URL detectada - Proporciona opciones para login (por defecto) y logout El script de GitHub facilita la autenticaci贸n con GitHub CLI (gh): - Utiliza el token almacenado y encriptado por cversion_token.sh - Desencripta autom谩ticamente el token usando SOPS - Proporciona opciones para login (por defecto) y logout ### Copias de Seguridad Para respaldar configuraciones importantes: ```bash bin/profile_backup.sh ``` Esto crea un archivo ZIP en `$HOME/secure/backups` que incluye: - Configuraci贸n GPG completa - Claves SSH y configuraci贸n - Configuraci贸n Git - Carpeta .developer (para configuraciones de servidores Git) La carpeta puede contener m煤ltiples archivos de respaldo con un archivo `gpg.secret` que contiene la contrase帽a encriptada. La p茅rdida de este archivo imposibilitar谩 la restauraci贸n. Para restaurar: ```bash bin/profile_restore.sh ``` ### Creaci贸n de Proyectos Estandarizados MRDevs Tools proporciona una forma estandarizada de crear nuevos proyectos con `project_new.sh`: ```bash # Crear un nuevo proyecto bin/project_new.sh ``` El script `project_new.sh` crea proyectos con una estructura completa seg煤n el tipo seleccionado: - Solicita nombre, tipo, licencia y descripci贸n del proyecto - Crea una estructura organizada de carpetas seg煤n el tipo de proyecto - Inicializa un repositorio Git con archivo .gitignore espec铆fico - Configura archivos README.md y documentaci贸n b谩sica - Permite seleccionar el tipo de servidor Git (GitHub, GitLab, Gitea, Forgejo, None) - Genera un commit inicial autom谩tico Tipos de proyectos soportados: - Python, Node.js, PHP, Rust, C, C++, C# - Odoo, Ansible, ESP32/Arduino - COBOL y otros tipos personalizados Cada tipo de proyecto incluye: - Estructura de directorios optimizada - Archivos de configuraci贸n espec铆ficos - Archivos .gitignore personalizados - Documentaci贸n inicial b谩sica ### Gesti贸n de Tarifas y Costos MRDevs Tools incluye utilidades para la gesti贸n de tarifas y estimaci贸n de costos: #### Actualizaci贸n de Tarifas El script `rate_update.py` permite mantener actualizadas las tarifas por hora de diferentes tipos de programadores: ```bash # Actualizar tarifas faltantes bin/rate_update.py # Listar todas las tarifas disponibles bin/rate_update.py --list # Actualizar la tarifa de un tipo espec铆fico de programador bin/rate_update.py --type python # Actualizar todas las tarifas, incluso las existentes bin/rate_update.py --init ``` Las tarifas se almacenan en archivos individuales dentro de `data/rates/` (directorio sin tracking en git) y pueden ser utilizadas por otras herramientas. #### Estimaci贸n de Costos con COCOMO El script `cocomo.py` implementa el modelo COCOMO para estimar costos de proyectos de software basados en las l铆neas de c贸digo: ```bash # Calcular costo de un proyecto bin/cocomo.py --project /ruta/al/proyecto # Usar un tipo espec铆fico de programador para los costos bin/cocomo.py --project /ruta/al/proyecto --type devops # Especificar un modelo COCOMO espec铆fico bin/cocomo.py --project /ruta/al/proyecto --model embedded # Ignorar patrones adicionales de archivos bin/cocomo.py --project /ruta/al/proyecto --ignore "*.generated.js" --ignore "vendor/**" ``` El script analizar谩 el c贸digo fuente, contar谩 las l铆neas efectivas, y calcular谩 estimaciones de esfuerzo, tiempo y costos utilizando las tarifas por hora configuradas.