Patto CLI

Herramienta de línea de comandos para trabajar con Patto Bot Template. Facilita la inicialización de proyectos y la generación de comandos, subcomandos, grupos y plugins para tu bot de Discord.

📋 Tabla de Contenidos

• Características
• Instalación
• Comandos Disponibles
  • init
  • generate
• Ejemplos de Uso
• Estructura del Proyecto
• Testing
• Contribuir
• Licencia

✨ Características

• 🚀 Inicialización rápida: Crea proyectos nuevos desde el template oficial
• 🎨 Generación de código: Crea comandos, subcomandos, grupos y plugins automáticamente
• ✅ Validaciones integradas: Nombres en kebab-case, prevención de path traversal
• 📦 Modular: Arquitectura limpia y fácil de mantener
• 🧪 Testeado: 30+ tests cubriendo toda la funcionalidad
• 🎯 TypeScript: Desarrollado completamente en TypeScript
• 🔧 Flexible: Opciones para archivos unificados o separados

📦 Instalación

Global (Recomendado)

npm install -g patto-cli

Local (Desarrollo)

npm install --save-dev patto-cli

Uso directo con npx

npx patto-cli <comando>

🎯 Comandos Disponibles

init - Inicializar Proyecto

Crea un nuevo proyecto de Patto Bot desde el template oficial.

patto init [nombre-proyecto]

Opciones:

• nombre-proyecto: Nombre del proyecto (opcional, se pedirá interactivamente)

Características:

• ✓ Preserva mayúsculas/minúsculas en nombres de carpeta
• ✓ Convierte a kebab-case para package.json
• ✓ Clona el repositorio oficial
• ✓ Instala dependencias automáticamente
• ✓ Operaciones git silenciosas

Ejemplo:

patto init MiBot
# Crea: ./MiBot/
# package.json name: "mi-bot"

generate - Generar Código

Genera comandos, subcomandos, grupos de subcomandos o plugins automáticamente.

Subcomandos disponibles:

• command (alias: c)
• subcommand (alias: s)
• subcommand-group (alias: g)
• plugin (alias: p)

command - Generar Comando

Genera un comando básico para el bot.

patto generate command -n <name> [opciones]
# o usando alias
patto g c -n <name> [opciones]

Opciones:

• -n, --name <name>: Nombre del comando (kebab-case) [requerido]
• -u, --unified: Crear archivo unificado (sin separar definition y command)
• -d, --description <text>: Descripción del comando

Ejemplos:

# Comando básico con archivos separados
patto generate command -n ping

# Comando unificado con descripción
patto g c -n help -u -d "Muestra ayuda del bot"

# Comando en carpeta anidada
patto generate command -n utils/calculator

Genera:

src/
├── commands/
│   └── ping.command.ts          # Implementación
└── definitions/
    └── ping.definition.ts       # Decorador y definición

subcommand - Generar Subcomando

Genera un subcomando para un comando existente.

patto generate subcommand -n <name> -p <parent> [opciones]
# o usando alias
patto g s -n <name> -p <parent> [opciones]

Opciones:

• -n, --name <name>: Nombre del subcomando (kebab-case) [requerido]
• -p, --parent <parent>: Comando padre (kebab-case) [requerido]
• -u, --unified: Crear archivo unificado
• -d, --description <text>: Descripción del subcomando

Ejemplos:

# Subcomando básico
patto generate subcommand -n list -p user

# Con descripción
patto g s -n ban -p admin -d "Banea un usuario"

Genera:

src/
├── commands/
│   └── user-list.command.ts
└── definitions/
    └── user-list.definition.ts

Nombre del archivo: {parent}-{name}.command.ts
Clase: {Parent}{Name}Command

subcommand-group - Generar Grupo

Genera un grupo de subcomandos (nivel 3 de anidación).

patto generate subcommand-group -n <name> -p <parent> -s <subcommand> [opciones]
# o usando alias
patto g g -n <name> -p <parent> -s <subcommand> [opciones]

Opciones:

• -n, --name <name>: Nombre del grupo (kebab-case) [requerido]
• -p, --parent <parent>: Comando padre (kebab-case) [requerido]
• -s, --subcommand <subcommand>: Subcomando (kebab-case) [requerido]
• -u, --unified: Crear archivo unificado
• -d, --description <text>: Descripción del grupo

Ejemplos:

# Grupo de subcomandos
patto generate subcommand-group -n tools -p admin -s manage

# Con descripción
patto g g -n roles -p server -s config -d "Gestión de roles"

Genera:

src/
├── commands/
│   └── admin-manage-tools.command.ts
└── definitions/
    └── admin-manage-tools.definition.ts

Nombre del archivo: {parent}-{subcommand}-{name}.command.ts
Clase: {Parent}{Subcommand}{Name}Command

plugin - Generar Plugin

Genera un plugin y lo registra automáticamente en src/config/plugins.config.ts.

patto generate plugin -n <name> [opciones]
# o usando alias
patto g p -n <name> [opciones]

Opciones:

• -n, --name <name>: Nombre del plugin (kebab-case) [requerido]
• --folder <folder>: Carpeta específica donde se aplicará (PluginScope.Folder)
• --global: Aplicar a carpeta y subcarpetas (PluginScope.DeepFolder)

Ejemplos:

# Plugin básico (PluginScope.Specified)
patto generate plugin -n logger

# Plugin para carpeta específica
patto g p -n auth-check --folder commands

# Plugin global para carpeta y subcarpetas
patto generate plugin -n rate-limiter --global --folder api

# Plugin en subcarpeta
patto g p -n utils/validator

Genera:

src/
├── plugins/
│   └── logger.plugin.ts         # Clase del plugin
└── config/
    └── plugins.config.ts        # ← Actualizado automáticamente

Registro automático: El comando agrega automáticamente:

1. Import del plugin al inicio del archivo
2. Código de registro al final del archivo

💡 Ejemplos de Uso

Crear un bot completo desde cero

# 1. Inicializar proyecto
patto init MiSuperBot
cd MiSuperBot

# 2. Generar comandos básicos
patto g c -n ping -d "Verifica latencia del bot"
patto g c -n help -d "Muestra comandos disponibles"

# 3. Generar comando con subcomandos
patto g c -n user -d "Gestión de usuarios"
patto g s -n info -p user -d "Información de usuario"
patto g s -n avatar -p user -d "Avatar de usuario"

# 4. Generar comando admin con grupos
patto g c -n admin -d "Comandos administrativos"
patto g s -n manage -p admin -d "Gestión del servidor"
patto g g -n roles -p admin -s manage -d "Gestión de roles"
patto g g -n channels -p admin -s manage -d "Gestión de canales"

# 5. Generar plugins
patto g p -n auth-middleware --folder commands
patto g p -n logger --global
patto g p -n utils/validator

Estructura resultante:

MiSuperBot/
├── src/
│   ├── commands/
│   │   ├── ping.command.ts
│   │   ├── help.command.ts
│   │   ├── user.command.ts
│   │   ├── user-info.command.ts
│   │   ├── user-avatar.command.ts
│   │   ├── admin.command.ts
│   │   ├── admin-manage.command.ts
│   │   ├── admin-manage-roles.command.ts
│   │   └── admin-manage-channels.command.ts
│   ├── definitions/
│   │   └── [archivos .definition.ts correspondientes]
│   ├── plugins/
│   │   ├── auth-middleware.plugin.ts
│   │   ├── logger.plugin.ts
│   │   └── utils/
│   │       └── validator.plugin.ts
│   └── config/
│       └── plugins.config.ts
└── package.json

📁 Estructura del Proyecto

patto-cli/
├── src/
│   ├── commands/
│   │   ├── generate/              # Comandos de generación modulares
│   │   │   ├── command.ts         # Generador de comandos
│   │   │   ├── subcommand.ts      # Generador de subcomandos
│   │   │   ├── subcommand-group.ts # Generador de grupos
│   │   │   ├── plugin.ts          # Generador de plugins
│   │   │   └── README.md          # Documentación
│   │   ├── generate.ts            # Orquestador principal
│   │   └── init.ts                # Comando de inicialización
│   ├── templates/
│   │   ├── command.decorator.template
│   │   ├── subcommand.decorator.template
│   │   ├── subcommand.group.decorator.template
│   │   └── plugins/
│   │       ├── plugin.template
│   │       └── register-plugin.template
│   ├── types.ts                   # Tipos TypeScript
│   ├── utils.ts                   # Utilidades
│   ├── loader.ts                  # Cargador de comandos
│   └── index.ts                   # Entry point
├── tests/
│   └── generate/                  # Tests modulares
│       ├── command.test.ts
│       ├── subcommand.test.ts
│       ├── subcommand-group.test.ts
│       ├── plugin.test.ts
│       └── README.md
├── dist/                          # Archivos compilados
├── package.json
├── tsconfig.json
└── README.md

🧪 Testing

El proyecto cuenta con una suite completa de tests utilizando Vitest.

Ejecutar tests

# Todos los tests
npm test

# Tests específicos
npm test command.test.ts
npm test subcommand.test.ts
npm test subcommand-group.test.ts
npm test plugin.test.ts

# Watch mode
npm test -- --watch

Cobertura de tests

• Total: 30 tests
• Command: 10 tests
• Subcommand: 5 tests
• Subcommand Group: 6 tests
• Plugin: 9 tests

Todos los tests están pasando ✅

Qué se testea

• ✅ Creación correcta de archivos
• ✅ Contenido generado
• ✅ Validaciones de nombres (kebab-case)
• ✅ Prevención de path traversal
• ✅ Manejo de archivos duplicados
• ✅ Funcionamiento de aliases
• ✅ Registro automático de plugins
• ✅ Opciones de comandos

🔒 Validaciones

Patto CLI incluye validaciones estrictas para garantizar la calidad del código generado:

Nombres en kebab-case

✅ patto g c -n my-command       # Correcto
❌ patto g c -n MyCommand        # Error: debe ser kebab-case
❌ patto g c -n my_command       # Error: solo guiones permitidos
❌ patto g c -n "my command"     # Error: sin espacios

Prevención de path traversal

✅ patto g c -n utils/helper     # Correcto: subcarpeta válida
❌ patto g c -n ../../../hack    # Protegido: se sanitiza automáticamente

Archivos duplicados

✅ patto g c -n new-command      # Correcto: archivo no existe
❌ patto g c -n new-command      # Error: archivo ya existe

🎨 Convenciones de Código

Nombres de archivos

• Comandos: {name}.command.ts (kebab-case)
• Definiciones: {name}.definition.ts (kebab-case)
• Plugins: {name}.plugin.ts (kebab-case)

Nombres de clases

• Comandos: {Name}Command (PascalCase)
• Definiciones: {Name}Definition (PascalCase)
• Plugins: {Name}Plugin (PascalCase)

Imports

• Comandos: @/commands/
• Definiciones: @/definitions/
• Plugins: @/plugins/

🤝 Contribuir

¡Las contribuciones son bienvenidas! Por favor lee nuestra Guía de Contribución antes de enviar un Pull Request.

Proceso de contribución

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

Desarrollo local

# Clonar el repositorio
git clone https://github.com/HormigaDev/patto-cli.git
cd patto-cli

# Instalar dependencias
npm install

# Ejecutar tests
npm test

# Compilar
npm run build

# Ejecutar en modo desarrollo
npm start init MiBot

📝 Licencia

Este proyecto está bajo la Licencia MIT. Ver el archivo LICENSE para más detalles.

👤 Autor

HormigaDev

• Email: [email protected]
• GitHub: @HormigaDev

🔗 Enlaces

• Patto Bot Template
• Documentación del Template
• Reportar un Bug
• Solicitar una Feature

🙏 Agradecimientos

• A todos los contribuidores del proyecto
• A la comunidad de Discord.js

¿Te gusta Patto CLI? ⭐ Dale una estrella en GitHub!