@orxataguy/tyr 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manel Andreu Pérez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,408 @@
+# Tyr Framework - Guía Completa del Proyecto
+
+**Autor:** Manel Andreu Pérez  
+**Versión:** 1.0.0  
+**Licencia:** MIT
+
+---
+
+## 📋 Descripción del Proyecto
+
+Tyr Framework es un entorno de ejecución basado en TypeScript que permite crear, ejecutar y automatizar herramientas CLI de manera declarativa.
+
+La arquitectura se construye sobre **inyección de dependencias**: el "Kernel" proporciona un contexto de ejecución donde los "Managers" exponen su funcionalidad a través de una API auto-generada. Gracias a un sistema de introspección de código, el entorno analiza tipos y documentación en tiempo real.
+
+---
+
+## 📁 Estructura del Proyecto
+
+```
+/
+├── bin/
+│   └── tyr.ts                    // Punto de entrada del CLI
+│
+├── src/
+│   ├── core/
+│   │   ├── Kernel.ts             // Motor principal de ejecución
+│   │   ├── Container.ts          // Contenedor de servicios (inyección de dependencias)
+│   │   ├── TyrError.ts           // Manejo de errores personalizado
+│   │   └── sys/
+│   │       ├── gen.ts            // Comando: generar nuevos comandos
+│   │       ├── rem.ts            // Comando: remover comandos
+│   │       └── doc.ts            // Comando: generar documentación
+│   │
+│   ├── commands/
+│   │   ├── install.tyr.ts        // Comando: instalar el framework
+│   │   └── dw.tyr.ts             // Comando: descargar dependencias
+│   │
+│   └── lib/
+│       ├── ShellManager.ts       // Ejecución de comandos shell
+│       ├── FileSystemManager.ts  // Operaciones del sistema de archivos
+│       ├── PackageManager.ts     // Gestión de paquetes (npm)
+│       ├── DockerManager.ts      // Integración con Docker
+│       ├── GitManager.ts         // Operaciones de Git
+│       ├── SystemManager.ts      // Gestión del sistema
+│       ├── SQLManager.ts         // Consultas a bases de datos MSSQL
+│       └── WebManager.ts         // Requests HTTP
+│
+├── tests/
+│   ├── commands.test.ts          // Tests de comandos (Vitest)
+│   ├── test-runner.ts            // Runner de smoke tests
+│   └── setup.ts                  // Configuración de mocks
+│
+├── config/
+│   └── map.yml                   // Configuración de comandos del framework
+│
+├── local/
+│   ├── aliases.sh                // Alias de shell personalizados
+│   └── plugins.sh                // Plugins para shell
+│
+├── package.json                  // Dependencias y scripts
+├── tsconfig.json                 // Configuración de TypeScript
+├── vitest.config.ts              // Configuración de tests
+└── html-reporter.ts              // Generador de reportes HTML
+```
+
+---
+
+## 🎯 Conceptos Clave
+
+### 1. KERNEL (`src/core/Kernel.ts`)
+
+- **Orquestador principal** del framework
+- Carga configuración desde `config/map.yml`
+- Enruta comandos hacia sus manejadores
+- Proporciona el contexto de ejecución (`TyrContext`)
+- **Métodos principales:**
+  - `boot(args)`: Inicializa el framework
+  - `handle(args)`: Ejecuta comandos
+
+### 2. CONTAINER (`src/core/Container.ts`)
+
+- Contenedor de **inyección de dependencias**
+- Instancia todos los servicios (Managers)
+- Expone interfaz `ServiceContainer` con todos los servicios
+- Implementa patrón Singleton para servicios
+
+### 3. MANAGERS (`src/lib/*.ts`)
+
+Conjunto de abstracciones sobre librerías externas. Ejecutar comando de documentación para saber más.
+
+```bash
+tyr doc
+```
+
+### 4. COMANDOS
+
+Son funciones que siguen el patrón:
+
+```typescript
+export default ({ task, fail, logger, fs, shell }: TyrContext) => {
+    return async (args: string[]) => {
+        // Lógica del comando
+    };
+};
+```
+
+Los comandos personalizados se registran en `config/map.yml`
+
+### 5. CONFIGURACIÓN (`config/map.yml`)
+
+Define los comandos disponibles:
+
+```yaml
+commands:
+  install: ./src/commands/install.tyr.ts
+  dw: ./src/commands/dw.tyr.ts
+```
+
+---
+
+## 🚀 Cómo Usar el Framework
+
+### Instalación
+
+```bash
+npm install
+npm run install        # Ejecuta el comando install
+```
+
+### Ejecutar Comandos
+
+```bash
+tyr <nombre-comando> [argumentos]
+```
+
+**Ejemplos:**
+- `tyr install` - Instala y configura el framework
+- `tyr gen micomando` - Genera un nuevo comando
+- `tyr rem micomando` - Elimina un comando
+- `tyr doc` - Genera documentación
+- `tyr dw` - Descarga dependencias
+
+### Crear un Nuevo Comando
+
+```bash
+tyr gen <nombre-comando> <nombre-archivo>
+```
+
+Se creará el archivo en `src/commands/<nombre-archivo>.tyr.ts`:
+
+```typescript
+import { TyrContext } from '../core/Kernel';
+
+export default ({ task, fail, logger, fs, shell }: TyrContext) => {
+    return async (args: string[]) => {
+        // Validar argumentos
+        if (args.length === 0) {
+            fail('Se requiere al menos un argumento');
+        }
+        
+        // Usar tareas con descripción
+        await task('Realizando acción', async () => {
+            logger.info('Procesando...');
+            // Tu lógica aquí
+        });
+        
+        logger.success('¡Listo!');
+    };
+};
+```
+
+### Eliminarc un Comando Existente
+```bash
+tyr rem <nombre-comando>
+```
+
+
+---
+
+## 🧪 Testing
+
+El framework incluye un sistema de testing completo:
+
+### Tests Unitarios (Vitest)
+
+```bash
+npm run test              # Ejecutar tests
+npm run test:watch        # Modo watch
+npm run test:ui           # UI interactivo
+npm run test:coverage     # Cobertura
+```
+
+### Smoke Tests
+
+```bash
+npm run test:smoke        # Valida que todos los comandos cargan correctamente
+```
+
+**Verifica:**
+- Comandos cargan como módulos
+- Exportan función por defecto
+- Se instancian con contexto
+- Se ejecutan sin excepciones no controladas
+
+### Mocks
+
+El archivo `tests/setup.ts` proporciona `createMockContext()` que mocka:
+- Logger
+- ShellManager
+- FileSystemManager
+- Todos los managers
+
+---
+
+## 📊 Flujo de Ejecución
+
+```
+1. Usuario ejecuta: tyr micomando arg1 arg2
+   ↓
+2. bin/tyr.ts captura el comando
+   ↓
+3. Kernel.boot() inicializa el framework
+   ↓
+4. Container.init() crea todos los Managers
+   ↓
+5. Carga config/map.yml
+   ↓
+6. Kernel.handle() recibe [micomando, arg1, arg2]
+   ↓
+7. Busca el comando en la configuración
+   ↓
+8. Importa el módulo dinámicamente
+   ↓
+9. Instancia el comando pasando TyrContext
+   ↓
+10. Ejecuta comando(args)
+    ↓
+11. Retorna resultado o error
+```
+
+---
+
+## 📦 Dependencias Principales
+
+### Runtime
+
+- **chalk** - Colores en terminal
+- **execa** - Ejecución de shell mejorada
+- **axios** - HTTP client
+- **mssql** - Driver MSSQL
+- **js-yaml** - Parser YAML
+- **inquirer** - Prompts interactivos
+- **dotenv** - Variables de entorno
+- **cheerio** - Web scraping
+- **find-config** - Búsqueda de archivos de config
+
+### Dev
+
+- **TypeScript** - Lenguaje
+- **Vitest** - Testing framework
+- **tsx** - Ejecutor TypeScript
+- **Vite** - Build tool
+- **Husky** - Git hooks
+
+---
+
+## 🔧 Configuración Importante
+
+### tsconfig.json
+- `target`: ES2020
+- `module`: ES2020
+- `moduleResolution`: node
+
+### package.json
+- `type`: module (módulos ES)
+- `bin`: { tyr: ./bin/tyr.ts }
+
+### vitest.config.ts
+- Test runner del proyecto
+- Configuración de mocks y setup
+
+---
+
+## 🎨 Patrones y Best Practices
+
+### Inyección de Dependencias
+
+```typescript
+const command = ({ logger, fs, shell }: TyrContext) => {
+    // Los managers se inyectan automáticamente
+    return async (args) => { ... };
+};
+```
+
+### Manejo de Errores
+
+- Usa `fail(message, suggestion?)` para errores controlados
+- `fail()` lanza `TyrError`
+- Los comandos pueden capturar y manejar excepciones
+
+### Tareas con Descripción
+
+```typescript
+await task('Descripción', async () => {
+    // Operación
+});
+// Muestra progreso en terminal
+```
+
+### Logging
+
+```typescript
+logger.info()     // Información general
+logger.success()  // Operación exitosa
+logger.error()    // Error (solo en debug)
+logger.warn()     // Advertencia (solo en debug)
+```
+
+### Argumentos de Comando
+
+Siempre valida los argumentos al inicio:
+
+```typescript
+if (args.length < 2) {
+    fail('Se requieren 2 argumentos', 'Sintaxis: tyr cmd arg1 arg2');
+}
+```
+
+---
+
+## 📚 Comandos Disponibles
+
+### Comandos del Sistema
+
+#### `tyr gen <nombre-comando> [archivo-salida]`
+Genera un nuevo comando con template
+- Crea archivo en `src/commands/`
+- Registra en `config/map.yml`
+
+#### `tyr rem <nombre-comando>`
+Elimina un comando
+- Borra archivo del comando
+- Elimina entrada en `config/map.yml`
+
+#### `tyr doc`
+Genera documentación completa del sistema
+- Analiza todos los comandos
+- Extrae tipos y comentarios JSDoc
+- Genera HTML interactivo
+
+### Comandos Personalizados
+
+#### `tyr install`
+Instala y configura el framework
+- Crea estructura de carpetas
+- Copia templates
+- Configura alias 'tyre' en .zshrc
+
+#### `tyr dw`
+Descarga y configura dependencias
+- Instala paquetes npm
+- Configura variables de entorno
+- Verifica instalaciones externas
+
+---
+
+## 🐛 Debugging
+
+Ejecuta con flag `--debug` para ver más información:
+
+```bash
+tyr micomando --debug
+```
+
+- Activa logging de errores y warnings
+- Muestra detalles de operaciones
+
+---
+
+## 📝 Notas de Desarrollo
+
+- El framework usa módulos ES6, asegúrate de `"type": "module"` en `package.json`
+- Los comandos deben ser `async`
+- Siempre retorna del handler o lanza error
+- Usa la inyección de dependencias, no importes managers directamente
+- Los tests usan mocks automáticos del `setup.ts`
+- El smoke test valida que todos los comandos cargan correctamente
+
+---
+
+## 🔗 Referencias Útiles
+
+Archivos principales para empezar:
+
+- [src/core/Kernel.ts](src/core/Kernel.ts) - Entender cómo funciona el motor
+- [src/core/Container.ts](src/core/Container.ts) - Ver cómo se inyectan dependencias
+- [src/commands/install.tyr.ts](src/commands/install.tyr.ts) - Ejemplo de comando completo
+- [src/core/sys/gen.ts](src/core/sys/gen.ts) - Cómo generar nuevos comandos
+- [tests/test-runner.ts](tests/test-runner.ts) - Sistema de testing
+
+---
+
+## Licencia
+
+**Autor:** Manel Andreu Pérez  
+**Versión:** 1.0.0  
+**Licencia:** MIT  
+**Tipo de proyecto:** CLI Framework para Automatización DevOps

package/bin/tyr.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'url';
+import { dirname, resolve, join } from 'path';
+import { spawn } from 'child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageRoot = resolve(__dirname, '..');
+const isWindows = process.platform === 'win32';
+
+const tsxBin = join(packageRoot, 'node_modules', '.bin', isWindows ? 'tsx.cmd' : 'tsx');
+const entry = join(__dirname, 'tyr.ts');
+
+const child = spawn(tsxBin, [entry, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    shell: isWindows
+});
+
+child.on('exit', (code) => process.exit(code ?? 0));
+child.on('error', (err) => {
+    console.error(`Error: Could not start tyr. ${err.message}`);
+    console.error(`tsx not found at: ${tsxBin}`);
+    console.error(`Try reinstalling: npm install -g tyr.framework.cli`);
+    process.exit(1);
+});

package/bin/tyr.ts

@@ -0,0 +1,14 @@
+import { Kernel } from '../src/core/Kernel.ts';
+
+(async () => {
+    try {
+        const kernel = new Kernel();
+        const args = process.argv.slice(2);
+        await kernel.boot(args);
+        await kernel.handle(args);
+    } catch (error) {
+        console.error("Error fatal:");
+        console.error(error);
+        process.exit(1);
+    }
+})();

package/config/map.yml

@@ -0,0 +1,7 @@
+settings:
+  appName: Tyr CLI
+  version: 0.1.0
+commands:
+  install: ./src/commands/install.tyr.ts
+  dw: ./src/commands/dw.tyr.ts
+  di: ./src/commands/di.tyr.ts

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@orxataguy/tyr",
+  "version": "1.0.0",
+  "type": "module",
+  "bin": {
+    "tyr": "./bin/tyr.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "config/"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:smoke": "tsx tests/test-runner.ts",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "prepare": "node -e \"const{existsSync}=require('fs');if(!process.env.CI&&existsSync('.git'))require('child_process').execSync('husky',{stdio:'inherit'})\"",
+    "release:patch": "npm version patch && git push --follow-tags",
+    "release:minor": "npm version minor && git push --follow-tags",
+    "release:major": "npm version major && git push --follow-tags",
+    "config": "node bin/tyr.js install"
+  },
+  "keywords": [
+    "CLI",
+    "scripting",
+    "system management",
+    "task scheduling",
+    "DevOps",
+    "cross-platform"
+  ],
+  "author": "Manel Andreu Pérez",
+  "license": "MIT",
+  "description": "Tyr is a TypeScript-based environment that resolves this fragmentation through the creation, execution, and automation of CLI tools. Its architecture is built on dependency injection: the \"Kernel\" provides an execution context where \"Managers\" expose their functionality via an auto-generated API. Thanks to a code introspection system, the environment analyzes types and documentation in real-time, offering the programmer a ready-to-use catalog of tools. This completely decouples command logic from underlying libraries, allowing developers to invoke complex functions without needing to manage external packages or configurations.",
+  "dependencies": {
+    "@types/inquirer": "^9.0.9",
+    "@types/mssql": "^9.1.8",
+    "axios": "^1.13.2",
+    "chalk": "^5.6.2",
+    "cheerio": "^1.1.2",
+    "dotenv": "^17.2.3",
+    "execa": "^6.1.0",
+    "find-config": "^1.0.0",
+    "inquirer": "^13.2.1",
+    "js-yaml": "^4.1.1",
+    "mssql": "^12.2.0",
+    "tsx": "^4.21.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.0.10",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "husky": "^9.1.7",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vitest": "^3.2.4"
+  }
+}

package/src/commands/di.tyr.ts

@@ -0,0 +1,113 @@
+import { TyrContext } from '../core/Kernel';
+
+export default ({ task, fail, logger, shell, db, git, fs }: TyrContext) => {
+    /**
+     * @method extractBranchName
+     * @description Extrae el nombre de rama de una URL o devuelve el nombre tal cual
+     */
+    const extractBranchName = (input: string): string => {
+        if (input.includes('/')) {
+            const parts = input.split('/');
+            return parts[parts.length - 1];
+        }
+        return input;
+    };
+
+    return async (args: string[]) => {
+
+        // Validación de argumentos
+        if (args.length === 0) {
+            fail(
+                'No se especificó la URL del cliente',
+                'Uso: clone-client <url-cliente> [url-rama-opcional]'
+            );
+        }
+
+        const clientUrl = args[0];
+        const branchUrlOrName = args[1] || null;
+
+        logger.info('Navegando al directorio de clientes...');
+        shell.cd('~/dev/wolbenvironment/dev/online-booking/htdocs/datosBroker');
+
+        const broker = await task('Buscando broker en la base de datos', async () => {
+            const result = await db.searchBrokerOnDB(clientUrl);
+
+            if (!result) {
+                fail(
+                    `No se encontró broker para la URL: ${clientUrl}`,
+                    'Verifica que la URL sea correcta y esté registrada en la BD'
+                );
+            }
+
+            logger.success(`Broker encontrado: ${result}`);
+            return result;
+        });
+
+        const brokerPath = `~/dev/wolbenvironment/dev/online-booking/htdocs/datosBroker/${broker}`;
+        const dirExists = fs.exists(brokerPath);
+
+        if (dirExists) {
+            logger.warn(`El directorio '${broker}' ya existe`);
+
+            const choice = await shell.input(
+                '¿Qué deseas hacer? (s)obrescribir / (m)antener / (r)enombrar: '
+            );
+
+            if (choice.toLowerCase() === 'm' || choice.toLowerCase() === 'mantener') {
+                logger.info('Manteniendo directorio existente. Finalizando...');
+                return;
+            } else if (choice.toLowerCase() === 'r' || choice.toLowerCase() === 'renombrar') {
+                await task('Renombrando directorio existente', async () => {
+                    await shell.exec(`mv ${broker} ${broker}.bak`);
+                    logger.success(`Directorio renombrado a: ${broker}.bak`);
+                });
+            } else if (choice.toLowerCase() === 's' || choice.toLowerCase() === 'sobrescribir') {
+                await task('Eliminando directorio existente', async () => {
+                    await shell.exec(`rm -rf ${broker}`);
+                    logger.success('Directorio eliminado');
+                });
+            } else {
+                fail('Opción no válida', 'Usa: s (sobrescribir), m (mantener) o r (renombrar)');
+            }
+        }
+
+        const repoUrl = `git@github.com:Avantio/${broker}`;
+        logger.info(`Repositorio: ${repoUrl}`);
+
+        const loader = shell.showLoader('Clonando repositorio desde GitHub...');
+
+        await task('Clonando repositorio', async () => {
+            await git.clone(repoUrl);
+            loader.stop();
+            logger.success('Repositorio clonado exitosamente');
+        }, false, () => loader.stop());
+
+        shell.cd(broker);
+
+        let branchName: string;
+
+        if (branchUrlOrName) {
+            branchName = extractBranchName(branchUrlOrName);
+            logger.info(`Rama extraída: ${branchName}`);
+        } else {
+            const answer = await shell.input('🌿 ¿Qué rama quieres usar? (nombre o URL): ');
+            branchName = extractBranchName(answer);
+        }
+
+        await task(`Cambiando a la rama: ${branchName}`, async () => {
+            if (branchName.length > 0) {
+                await shell.exec(`git checkout -b ${branchName}`);
+                logger.success(`Ahora estás en la rama: ${branchName}`);
+            } else {
+                logger.info('No se va a generar ninguna rama nueva')
+            }
+        });
+        logger.success(`Repositorio ${broker} clonado y configurado exitosamente`);
+
+    };
+};
+
+
+// export const Test = {
+//     args: []
+// }