@orxataguy/tyr 1.0.7 → 1.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orxataguy/tyr",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "type": "module",
   "bin": {
     "tyr": "./bin/tyr.js"
@@ -49,6 +49,7 @@
     "find-config": "^1.0.0",
     "inquirer": "^13.2.1",
     "js-yaml": "^4.1.1",
+    "mongodb": "^7.2.0",
     "mssql": "^12.2.0",
     "tsx": "^4.21.0"
   },

package/src/core/Kernel.ts

@@ -11,6 +11,7 @@ import rem from './sys/rem';
 import doc from './sys/doc';
 import ai from './sys/ai';
 import config from './sys/config';
+import help from './sys/help';
 
 import { TyrError } from './TyrError';
 
@@ -126,6 +127,20 @@ export class Kernel {
             return;
         }
 
+        // --help / -h: lista todos los comandos disponibles con su documentación
+        if (commandName === '--help' || commandName === '-h') {
+            const helpContext = {
+                ...this.container.get(),
+                frameworkRoot: this.frameworkRoot,
+                userRoot: this.userRoot,
+                run: async () => {},
+                task: async <T>(_: string, action: () => Promise<T> | T) => action(),
+                fail: (msg: string) => { throw new Error(msg); },
+            } as any;
+            await help(helpContext)(args.slice(1));
+            return;
+        }
+
         const runInternal = async (cmd: string, cmdArgs: string[] = []) => {
             await this.handle([cmd, ...cmdArgs]);
         };

package/src/core/sys/help.ts

@@ -0,0 +1,149 @@
+import fs from 'fs';
+import path from 'path';
+import { TyrContext } from '../Kernel';
+
+interface CommandDoc {
+    name: string;
+    description: string;
+    usage: string;
+}
+
+/**
+ * Extrae el primer bloque JSDoc de un archivo .tyr.ts y lo parsea
+ * en descripción y ejemplos de uso.
+ */
+function parseCommandDoc(filePath: string): CommandDoc {
+    const fileName = path.basename(filePath, '.tyr.ts');
+    const content = fs.readFileSync(filePath, 'utf-8');
+
+    const match = content.match(/\/\*\*([\s\S]*?)\*\//);
+    if (!match) {
+        return { name: fileName, description: '', usage: '' };
+    }
+
+    // Limpiar cada línea: eliminar el * inicial y espacios
+    const lines = match[1]
+        .split('\n')
+        .map(line => line.replace(/^\s*\*\s?/, '').trimEnd());
+
+    // Separar en descripción y bloque "Uso:"
+    const usoIndex = lines.findIndex(l => /^uso:/i.test(l.trim()));
+
+    let description = '';
+    let usage = '';
+
+    if (usoIndex !== -1) {
+        description = lines
+            .slice(0, usoIndex)
+            .filter(l => l.trim() !== '')
+            .join('\n')
+            .trim();
+
+        usage = lines
+            .slice(usoIndex + 1)
+            .filter(l => l.trim() !== '')
+            .map(l => l.trim())
+            .join('\n')
+            .trim();
+    } else {
+        description = lines.filter(l => l.trim() !== '').join('\n').trim();
+    }
+
+    return { name: fileName, description, usage };
+}
+
+export default function help({ userRoot }: TyrContext) {
+    return async (_args: string[]) => {
+        const commandsDir = path.join(userRoot, 'commands');
+
+        // ── ANSI ──────────────────────────────────────────────────────────
+        const reset  = '\x1b[0m';
+        const bold   = '\x1b[1m';
+        const dim    = '\x1b[2m';
+        const cyan   = '\x1b[36m';
+        const green  = '\x1b[32m';
+        const yellow = '\x1b[33m';
+        const gray   = '\x1b[90m';
+        const white  = '\x1b[37m';
+        // ──────────────────────────────────────────────────────────────────
+
+        const separator = `${gray}  ${'─'.repeat(50)}${reset}`;
+
+        console.log('');
+        console.log(`  ${bold}${cyan}tyr${reset}  ${white}Comandos disponibles${reset}`);
+        console.log(separator);
+        console.log('');
+
+        // Flags y comandos built-in del framework
+        const builtins = [
+            { name: '--help',    description: 'Muestra este listado de comandos.',          usage: 'tyr --help' },
+            { name: '--version', description: 'Muestra la versión instalada de tyr.',       usage: 'tyr --version' },
+            { name: '--config',  description: 'Configura tyr por primera vez.',             usage: 'tyr --config' },
+            { name: '--update',  description: 'Actualiza ~/.tyr desde el repositorio git.', usage: 'tyr --update' },
+            { name: '--upgrade', description: 'Actualiza el paquete npm de tyr.',           usage: 'tyr --upgrade' },
+            { name: 'gen',       description: 'Genera un nuevo comando a partir de una descripción con IA.', usage: 'tyr gen <nombre> "<descripción>"' },
+            { name: 'doc',       description: 'Levanta la documentación del framework en el navegador.', usage: 'tyr doc' },
+        ];
+
+        console.log(`  ${bold}${yellow}Framework${reset}`);
+        console.log('');
+
+        for (const cmd of builtins) {
+            console.log(`  ${bold}${green}${cmd.name.padEnd(14)}${reset}${dim}${cmd.description}${reset}`);
+            console.log(`  ${' '.repeat(14)}${gray}${cmd.usage}${reset}`);
+            console.log('');
+        }
+
+        // Comandos de usuario en ~/.tyr/commands/
+        if (!fs.existsSync(commandsDir)) {
+            console.log(separator);
+            console.log(`  ${yellow}No se encontró la carpeta de comandos: ${commandsDir}${reset}`);
+            console.log('');
+            return;
+        }
+
+        const files = fs.readdirSync(commandsDir)
+            .filter(f => f.endsWith('.tyr.ts'))
+            .sort();
+
+        if (files.length === 0) {
+            console.log(separator);
+            console.log(`  ${dim}No hay comandos en ${commandsDir}${reset}`);
+            console.log('');
+            return;
+        }
+
+        console.log(separator);
+        console.log('');
+        console.log(`  ${bold}${yellow}Comandos de usuario${reset}  ${gray}(~/.tyr/commands/)${reset}`);
+        console.log('');
+
+        for (const file of files) {
+            const doc = parseCommandDoc(path.join(commandsDir, file));
+
+            console.log(`  ${bold}${green}${doc.name}${reset}`);
+
+            if (doc.description) {
+                for (const line of doc.description.split('\n')) {
+                    console.log(`  ${dim}${line}${reset}`);
+                }
+            } else {
+                console.log(`  ${gray}Sin descripción${reset}`);
+            }
+
+            if (doc.usage) {
+                console.log('');
+                console.log(`  ${gray}  Uso:${reset}`);
+                for (const line of doc.usage.split('\n')) {
+                    console.log(`  ${cyan}    ${line}${reset}`);
+                }
+            }
+
+            console.log('');
+        }
+
+        console.log(separator);
+        console.log(`  ${dim}Genera un comando nuevo con ${cyan}tyr gen <nombre> "<qué debe hacer>"${reset}`);
+        console.log('');
+    };
+}

package/src/lib/MongoManager.ts

@@ -0,0 +1,176 @@
+import { MongoClient, Db, Document, Filter, UpdateFilter, InsertOneResult, InsertManyResult, UpdateResult, DeleteResult, WithId, OptionalUnlessRequiredId, FindOptions } from 'mongodb';
+
+/**
+ * @class MongoManager
+ * @description Conector con MongoDB que gestiona el ciclo de vida de la conexión y expone un CRUD genérico.
+ */
+export class MongoManager {
+  private client!: MongoClient;
+  private db!: Db;
+  private connected = false;
+
+  constructor() {}
+
+  private async init(): Promise<void> {
+    if (!this.connected) {
+      const uri = process.env.MONGO_URI || 'mongodb://localhost:27017';
+      const dbName = process.env.MONGO_DATABASE || '';
+
+      this.client = new MongoClient(uri);
+      await this.client.connect();
+      this.db = this.client.db(dbName);
+      this.connected = true;
+    }
+  }
+
+  private async close(): Promise<void> {
+    if (this.connected && this.client) {
+      await this.client.close();
+      this.connected = false;
+    }
+  }
+
+  /**
+   * @method insertOne
+   * @description Inserta un documento en la colección indicada.
+   * @param {string} collection - Nombre de la colección.
+   * @param {Document} document - Documento a insertar.
+   * @returns {Promise<InsertOneResult>} Resultado de la inserción.
+   * @example
+   * const result = await mongo.insertOne('users', { name: 'Ana', age: 30 });
+   */
+  public async insertOne<T extends Document>(collection: string, document: OptionalUnlessRequiredId<T>): Promise<InsertOneResult<T>> {
+    await this.init();
+    const result = await this.db.collection<T>(collection).insertOne(document);
+    await this.close();
+    return result;
+  }
+
+  /**
+   * @method insertMany
+   * @description Inserta múltiples documentos en la colección indicada.
+   * @param {string} collection - Nombre de la colección.
+   * @param {Document[]} documents - Array de documentos a insertar.
+   * @returns {Promise<InsertManyResult>} Resultado de la inserción.
+   * @example
+   * const result = await mongo.insertMany('users', [{ name: 'Ana' }, { name: 'Luis' }]);
+   */
+  public async insertMany<T extends Document>(collection: string, documents: OptionalUnlessRequiredId<T>[]): Promise<InsertManyResult<T>> {
+    await this.init();
+    const result = await this.db.collection<T>(collection).insertMany(documents);
+    await this.close();
+    return result;
+  }
+
+  /**
+   * @method findOne
+   * @description Busca el primer documento que coincida con el filtro.
+   * @param {string} collection - Nombre de la colección.
+   * @param {Filter<Document>} filter - Filtro de búsqueda.
+   * @param {FindOptions} [options] - Opciones adicionales (proyección, etc.).
+   * @returns {Promise<WithId<T> | null>} El documento encontrado o null.
+   * @example
+   * const user = await mongo.findOne('users', { name: 'Ana' });
+   */
+  public async findOne<T extends Document>(collection: string, filter: Filter<T>, options?: FindOptions): Promise<WithId<T> | null> {
+    await this.init();
+    const result = await this.db.collection<T>(collection).findOne(filter, options);
+    await this.close();
+    return result;
+  }
+
+  /**
+   * @method find
+   * @description Busca todos los documentos que coincidan con el filtro.
+   * @param {string} collection - Nombre de la colección.
+   * @param {Filter<Document>} filter - Filtro de búsqueda. Usa {} para traer todos los documentos.
+   * @param {FindOptions} [options] - Opciones adicionales (proyección, límite, etc.).
+   * @returns {Promise<WithId<T>[]>} Array de documentos encontrados.
+   * @example
+   * const users = await mongo.find('users', { age: { $gte: 18 } });
+   */
+  public async find<T extends Document>(collection: string, filter: Filter<T>, options?: FindOptions): Promise<WithId<T>[]> {
+    await this.init();
+    const result = await this.db.collection<T>(collection).find(filter, options).toArray();
+    await this.close();
+    return result;
+  }
+
+  /**
+   * @method updateOne
+   * @description Actualiza el primer documento que coincida con el filtro.
+   * @param {string} collection - Nombre de la colección.
+   * @param {Filter<Document>} filter - Filtro para identificar el documento.
+   * @param {UpdateFilter<Document>} update - Operación de actualización (ej: { $set: { field: value } }).
+   * @returns {Promise<UpdateResult>} Resultado de la actualización.
+   * @example
+   * const result = await mongo.updateOne('users', { name: 'Ana' }, { $set: { age: 31 } });
+   */
+  public async updateOne<T extends Document>(collection: string, filter: Filter<T>, update: UpdateFilter<T>): Promise<UpdateResult<T>> {
+    await this.init();
+    const result = await this.db.collection<T>(collection).updateOne(filter, update);
+    await this.close();
+    return result;
+  }
+
+  /**
+   * @method updateMany
+   * @description Actualiza todos los documentos que coincidan con el filtro.
+   * @param {string} collection - Nombre de la colección.
+   * @param {Filter<Document>} filter - Filtro para identificar los documentos.
+   * @param {UpdateFilter<Document>} update - Operación de actualización.
+   * @returns {Promise<UpdateResult>} Resultado de la actualización.
+   * @example
+   * const result = await mongo.updateMany('users', { active: false }, { $set: { active: true } });
+   */
+  public async updateMany<T extends Document>(collection: string, filter: Filter<T>, update: UpdateFilter<T>): Promise<UpdateResult<T>> {
+    await this.init();
+    const result = await this.db.collection<T>(collection).updateMany(filter, update);
+    await this.close();
+    return result;
+  }
+
+  /**
+   * @method deleteOne
+   * @description Elimina el primer documento que coincida con el filtro.
+   * @param {string} collection - Nombre de la colección.
+   * @param {Filter<Document>} filter - Filtro para identificar el documento.
+   * @returns {Promise<DeleteResult>} Resultado de la eliminación.
+   * @example
+   * const result = await mongo.deleteOne('users', { name: 'Ana' });
+   */
+  public async deleteOne<T extends Document>(collection: string, filter: Filter<T>): Promise<DeleteResult> {
+    await this.init();
+    const result = await this.db.collection<T>(collection).deleteOne(filter);
+    await this.close();
+    return result;
+  }
+
+  /**
+   * @method deleteMany
+   * @description Elimina todos los documentos que coincidan con el filtro.
+   * @param {string} collection - Nombre de la colección.
+   * @param {Filter<Document>} filter - Filtro para identificar los documentos.
+   * @returns {Promise<DeleteResult>} Resultado de la eliminación.
+   * @example
+   * const result = await mongo.deleteMany('users', { active: false });
+   */
+  public async deleteMany<T extends Document>(collection: string, filter: Filter<T>): Promise<DeleteResult> {
+    await this.init();
+    const result = await this.db.collection<T>(collection).deleteMany(filter);
+    await this.close();
+    return result;
+  }
+}
+
+/**
+ * @object MongoManagerTests
+ * @description Parámetros de pruebas para validar la funcionalidad de MongoManager.
+ */
+export const MongoManagerTests = {
+  // insertOne: { collection: 'test', document: { name: 'test_doc', value: 1 } },
+  // findOne: { collection: 'test', filter: { name: 'test_doc' } },
+  // find: { collection: 'test', filter: {} },
+  // updateOne: { collection: 'test', filter: { name: 'test_doc' }, update: { $set: { value: 2 } } },
+  // deleteOne: { collection: 'test', filter: { name: 'test_doc' } },
+};