create-bunspace 0.2.5 → 0.3.1

package/dist/templates/telegram-bot/docs/cli-commands.md

@@ -2,6 +2,21 @@
 
 Referencia completa de comandos CLI disponibles para gestionar el bot.
 
+## Flujo Recomendado
+
+```bash
+# 1. Setup del entorno (configura todo)
+bun run setup
+
+# 2. Doctor (verifica que todo esté correcto)
+bun run doctor
+
+# 3. Arrancar bot
+bun run dev
+```
+
+> **Setup → Doctor → Dev** es el flujo recomendado para cualquier cambio de configuración.
+
 ## Setup Command
 
 Configura el entorno del bot de forma interactiva.
@@ -38,11 +53,27 @@ bun run setup --token "123:ABC"
 
 ### Qué Hace
 
-1. **Copia** `.env.example` a `.env.{environment}`
-2. **Pregunta** por bot token, modo, y opciones
-3. **Valida** el token contra Telegram API
-4. **Configura** todos los campos necesarios
-5. **Muestra** próximos pasos
+1. **Detecta** contexto actual (qué existe, qué falta)
+2. **Pregunta** objetivo (new-bot, add-ids, create-topics, bootstrap, manual)
+3. **Ejecuta** pre-checks de validación
+4. **Configura** campos necesarios según modo seleccionado
+5. **Muestra** resumen de cambios
+6. **Sugiere** ejecutar `bun run doctor` para verificar
+
+### Siguiente Paso Recomendado
+
+Después de setup, **siempre ejecuta doctor**:
+
+```bash
+bun run doctor
+```
+
+Esto valida:
+- Token válido contra Telegram API
+- Variables de entorno configuradas
+- Dependencias instaladas
+- Puertos disponibles
+- Permisos de directorios
 
 ### Flujo Interactivo
 
@@ -370,6 +401,484 @@ bun run ngrok --environment staging
 bun run ngrok --environment production --webhook-url
 ```
 
+## Bootstrap Command
+
+Crea automáticamente un bot, grupo y topics mediante interacción con @BotFather.
+
+> **Versión Multibot**: El bootstrapper ahora soporta gestión de múltiples bots con detección de existentes y reutilización.
+
+> **Este es un "BotFather personal"** - automatiza todo el proceso de creación de bots.
+
+### Uso
+
+```bash
+bun run bootstrap
+```
+
+### Flags
+
+| Flag | Descripción | Default |
+| ---- | ----------- | ------- |
+| `-e, --environment <local\|staging\|production>` | Entorno objetivo | `local` |
+| `--bot <username>` | Bot username específico (sin @) | Prompt interactivo |
+| `--list` | Listar bots disponibles desde BotFather | `false` |
+| `--reuse` | Reutilizar configuración existente sin prompts | `false` |
+| `--force` | Forzar recreación de recursos | `false` |
+| `--skip-topics` | Skip creación de topics | `false` |
+| `--bot-name <value>` | Nombre del bot (display name) | Prompt interactivo |
+| `--bot-username <value>` | Username del bot (debe terminar en "bot") | Prompt interactivo |
+| `--group-name <value>` | Nombre del grupo/forum | Prompt interactivo |
+
+### Ejemplos
+
+```bash
+# Bootstrap interactivo completo (recomendado)
+bun run bootstrap
+
+# Listar bots disponibles desde BotFather
+bun run bootstrap --list
+
+# Bootstrap para bot específico
+bun run bootstrap --bot mybot123bot
+
+# Bootstrap con nombres pre-proveídos
+bun run bootstrap --bot-name "Mi Bot" --bot-username "mi_bot_v1" --group-name "Control Group"
+
+# Bootstrap para staging
+bun run bootstrap --environment staging
+
+# Reutilizar configuración existente sin prompts
+bun run bootstrap --reuse
+
+# Bootstrap sin crear topics
+bun run bootstrap --skip-topics
+
+# Forzar recreación de recursos
+bun run bootstrap --force
+```
+
+### Requisitos Previos
+
+Antes de ejecutar bootstrap, necesitas **credenciales MTProto API**:
+
+1. Ve a [https://my.telegram.org](https://my.telegram.org)
+2. Log in con tu número de teléfono
+3. Click en "API development tools"
+4. Llena el formulario:
+   - **App title**: My Bot App
+   - **Short name**: mybotapp
+   - **Platform**: Desktop o Web
+   - **Description**: (opcional)
+5. Click "Create application"
+6. Copia el `api_id` y `api_hash`
+
+> **Puedes guardar las credenciales** en tu `.env` para evitar re-pedirlas:
+> ```bash
+> # MTProto API Credentials (for bootstrap command)
+> TG_API_ID=12345678
+> TG_API_HASH=abc123def456789...
+> ```
+
+### Flujo Interactivo
+
+#### Paso 1: Verificación de Entorno
+
+```
+ℹ Environment file found: core/.env.local
+```
+
+#### Paso 2: Credenciales MTProto (si no están en .env)
+
+```
+📱 Telegram MTProto API Credentials
+
+To create bots and groups automatically, you need MTProto API credentials.
+
+📋 STEP-BY-STEP GUIDE:
+
+1. Open https://my.telegram.org in your browser
+2. Log in with your phone number (the same number you use in Telegram)
+3. Click on "API development tools"
+4. Fill in the form:
+   - App title: My Bot App
+   - Short name: mybotapp
+   - Platform: Desktop or Web
+   - Description: (optional)
+5. Click "Create application"
+6. Copy the api_id and api_hash from the next page
+
+? Do you want to save API credentials to .env file for future use? (Y/n)
+
+? Enter your API ID: ********
+
+? Enter your API Hash: ************************************
+```
+
+#### Paso 3: Autorización de Telegram
+
+Si es tu primera vez, te pedirá autorización:
+
+```
+🔐 Telegram Authorization Required
+This is a one-time process. Your session will be saved for future use.
+
+📝 STEP 1: Phone Number
+Enter your phone number with country code.
+Example: +34612345678 (Spain) or +12025551234 (USA)
+
+? Enter your phone number: +34612345678
+
+⏳ Sending verification code...
+Check your Telegram app for the code.
+
+📝 STEP 2: Verification Code
+Enter the code you received in Telegram.
+The code is 5-7 digits long.
+
+? Enter the code: 12345
+
+⏳ Verifying code...
+✅ Code verified!
+
+📝 STEP 3: Two-Factor Authentication (2FA)
+You have Cloud Password enabled.
+Enter your password to continue.
+
+? Enter your 2FA password: ********
+
+⏳ Verifying password...
+✅ Password verified!
+
+💾 Saving session...
+
+✅ Successfully authorized!
+Your session has been saved to: /Users/youruser/.mks-telegram-bot/session.txt
+Next time you won't need to login again.
+```
+
+> **Tu sesión se guarda automáticamente** en `~/.mks-telegram-bot/session.txt` para futuros usos.
+
+#### Paso 4: Creación del Bot
+
+```
+🚀 Complete Bot Bootstrap
+
+🤖 Step 1: Creating Bot
+
+⠋ Creating bot via @BotFather...
+✓ Bot created: @mi_bot_v1
+```
+
+#### Paso 5: Creación del Grupo/Forum
+
+```
+💬 Step 2: Creating Group/Forum
+
+⠋ Creating supergroup with forum mode...
+✓ Group created: Control Group (ID: -1001234567890)
+
+⠋ Adding bot as admin...
+✓ Bot added as admin
+```
+
+#### Paso 6: Creación de Topics
+
+```
+🧵 Step 3: Creating Topics
+
+⠋ Creating forum topics...
+✓ Created 5 topics
+  General: 1
+  Control: 2
+  Logs: 3
+  Config: 4
+  Bugs: 5
+```
+
+#### Paso 7: Actualización de Configuración
+
+```
+🔧 Step 4: Updating Configuration
+
+⠋ Updating .env file...
+✓ Updated core/.env.local
+```
+
+### Resumen Final
+
+```
+✅ Bootstrap Complete
+
+Bot Information:
+  Username: @mi_bot_v1
+  Token: 123456:ABC-...
+
+Group Information:
+  Name: Control Group
+  Chat ID: -1001234567890
+
+Topic IDs:
+  General: 1
+  Control: 2
+  Logs: 3
+  Config: 4
+  Bugs: 5
+
+✓ Your bot is now ready to use!
+
+ℹ Next steps:
+  1. Review the configuration in core/.env.local
+  2. Run: bun run dev
+  3. Send /start to your bot in Telegram
+```
+
+### Qué Hace
+
+El comando bootstrap automatiza **todo el proceso**:
+
+1. **Verifica** que el entorno existe (ejecuta `setup` si es necesario)
+2. **Obtiene** credenciales MTProto API (del .env o interactivo)
+3. **Autentica** con tu cuenta de Telegram (sesión guardada para futuro)
+4. **Crea el bot** vía @BotFather automáticamente
+5. **Crea un supergroup/forum** para el bot
+6. **Añade el bot como admin** del grupo
+7. **Crea topics** automáticamente (General, Control, Logs, Config, Bugs)
+8. **Actualiza el .env** con todos los IDs (bot token, chat ID, topic IDs)
+9. **Muestra el resumen** con próximos pasos
+
+### Variables de Entorno Configuradas
+
+Después de bootstrap, tu `.env` tendrá:
+
+```bash
+# Configurado automáticamente por bootstrap
+TG_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
+TG_CONTROL_CHAT_ID=-1001234567890
+TG_CONTROL_TOPIC_ID=2
+TG_LOG_TOPIC_ID=3
+TG_LOG_CHAT_ID=-1001234567890
+
+# MTProto credentials (si guardaste)
+TG_API_ID=12345678
+TG_API_HASH=abc123def456789...
+```
+
+### Ventajas vs Setup Manual
+
+| Feature | Bootstrap | Setup Manual |
+|---------|-----------|--------------|
+| Creación de bot | Automático (@BotFather) | Manual (hablar con @BotFather) |
+| Creación de grupo | Automático | Manual |
+| Creación de topics | Automática | Manual (o comando separado) |
+| IDs detection | Automático | Requiere auto-configure |
+| Tiempo total | ~3-5 minutos | ~10-15 minutos |
+| Interacción | Una sola vez | Varios pasos |
+
+### Troubleshooting
+
+#### Error: "Environment file not found"
+
+```bash
+# Primero ejecuta setup para crear el entorno
+bun run setup
+# Luego bootstrap
+bun run bootstrap
+```
+
+#### Error: "Authorization failed"
+
+- Verifica que tu número de teléfono sea correcto (con código de país)
+- Asegúrate de recibir el código de verificación en tu Telegram
+- Si tienes 2FA, ten tu contraseña lista
+
+#### Error: "Failed to create bot"
+
+- El username puede estar en uso (prueba otro)
+- El username debe terminar en "bot"
+- Verifica que @BotFather no esté bloqueado
+
+#### Sesión Corrupta
+
+Si tienes problemas con la sesión guardada:
+
+```bash
+# Elimina la sesión
+rm ~/.mks-telegram-bot/session.txt
+
+# Vuelve a ejecutar bootstrap (te pedirá login de nuevo)
+bun run bootstrap
+```
+
+### Seguridad
+
+- **Las credenciales MTProto** se guardan en tu `.env` (nunca en el repo, está en `.gitignore`)
+- **La sesión de Telegram** se guarda en `~/.mks-telegram-bot/session.txt` (fuera del repo)
+- **El bot token** se guarda en el `.env` del entorno correspondiente
+
+> **IMPORTANTE**: Nunca commits los archivos `.env.*` ni la sesión.
+
+## Bot Management Commands
+
+Comandos para gestionar múltiples configuraciones de bots en el mismo proyecto.
+
+> **Sistema Multibot**: Gestiona múltiples bots desde un mismo proyecto con configuraciones independientes.
+
+### `bot list`
+
+Lista todos los bots configurados en el proyecto.
+
+```bash
+bun run bot list
+```
+
+#### Output
+
+```
+📋 Configured Bots
+
+Found 2 configured bot(s):
+
+  ✓ @mybot123bot
+      Environments: local, staging, production
+      Name: My Bot
+      Created: 01/07/2025
+
+  @anotherbot456bot
+      Environments: local
+      Name: Another Bot
+      Created: 01/05/2025
+
+✓ Active bot: @mybot123bot
+```
+
+### `bot use <username>`
+
+Establece un bot como activo.
+
+```bash
+bun run bot use mybot123bot
+```
+
+#### Qué Hace
+
+- Actualiza el symlink `.active` para apuntar al bot seleccionado
+- Todos los comandos subsecuentes (`bun run dev`, `bun run start`) usarán este bot
+
+#### Output
+
+```
+✓ @mybot123bot is now the active bot
+```
+
+### `bot info <username>`
+
+Muestra información detallada de un bot específico.
+
+```bash
+bun run bot info mybot123bot
+```
+
+#### Output
+
+```
+ℹ️ Bot Information: @mybot123bot
+
+Basic Information:
+  Username: @mybot123bot
+  Active: Yes
+
+Environments:
+  Local: ✓
+  Staging: ✓
+  Production: ✓
+
+Metadata:
+  Name: My Bot
+  Created: 1/7/2025, 2:30:45 PM
+  Updated: 1/7/2025, 3:15:22 PM
+  Description: My awesome Telegram bot
+  Tags: test, demo
+
+LOCAL Configuration:
+  Token: 123456:ABC...
+  Control Chat ID: -1001234567890
+  Control Topic ID: 2
+  Log Chat ID: -1001234567890
+  Log Topic ID: 3
+
+STAGING Configuration:
+  Token: 789012:DEF...
+  Control Chat ID: -1009876543210
+  Control Topic ID: 5
+```
+
+### `bot delete <username>`
+
+Elimina la configuración de un bot.
+
+```bash
+bun run bot delete mybot123bot
+
+# Skip confirmación
+bun run bot delete mybot123bot --force
+```
+
+#### Flags
+
+| Flag | Descripción |
+| ---- | ----------- |
+| `-f, --force` | Skip confirmación prompt |
+
+#### Qué Hace
+
+- Elimina el directorio `.envs/{bot}/` completo
+- Si el bot estaba activo, limpia el symlink `.active`
+- Pide confirmación unless `--force`
+
+#### Output
+
+```
+⠋ Deleting bot '@mybot123bot'...
+✓ Bot '@mybot123bot' deleted
+ℹ Active bot cleared. Use "bun run bot use <username>" to set a new active bot.
+```
+
+### `bot migrate`
+
+Migra archivos `.env.{env}` antiguos a la nueva estructura `.envs/{bot}/{env}.env`.
+
+```bash
+bun run bot migrate
+```
+
+#### Qué Hace
+
+- Detecta archivos `.env.local`, `.env.staging`, `.env.production` en `core/`
+- Extrae el bot token para determinar el bot username
+- Crea la nueva estructura `.envs/{bot}/{env}.env`
+- Mueve las variables de entorno a los nuevos archivos
+- Crea `metadata.json` con información del bot
+- Actualiza el symlink `.active`
+- Hace backup de archivos antiguos como `.env.{env}.backup`
+
+#### Output
+
+```
+🔄 Migrate Old .env Files
+
+This command will migrate old .env.{environment} files
+to the new .envs/{bot}/{environment}.env structure.
+Old files will be backed up as .env.{environment}.backup
+
+? Do you want to proceed with migration? (Y/n)
+
+⠋ Migrating .env files...
+✓ Migration completed successfully
+
+Migrated bots:
+  @mybot123bot
+```
+
 ## Referencias
 
 - [Getting Started](./getting-started.md) - Guía de inicio