create-bunspace 0.2.5 → 0.3.1

package/dist/templates/telegram-bot/docs/environment.md

@@ -6,12 +6,68 @@ Guía completa de configuración de variables de entorno para el bot.
 
 El template soporta múltiples entornos con archivos `.env` separados:
 
+### Estructura Multibot (Nueva)
+
+> **Sistema Multibot**: Gestiona múltiples bots desde un mismo proyecto con configuraciones independientes.
+
+El template ahora usa una estructura `.envs/` para soportar múltiples bots:
+
+```
+core/.envs/
+├── {botUsername}/
+│   ├── local.env       # Configuración local del bot
+│   ├── staging.env     # Configuración staging del bot
+│   ├── production.env  # Configuración production del bot
+│   └── metadata.json   # Metadatos del bot
+└── .active -> {botUsername}  # Symlink al bot activo
+```
+
+### Estructura Legada (Antigua)
+
+Para backwards compatibility, el template todavía soporta la estructura antigua:
+
 | Archivo | Uso | Modo | Bot Token |
 | ------- | --- | ---- | --------- |
 | `core/.env.local` | Desarrollo local | Polling | Local dev token |
 | `core/.env.staging` | Testing/Staging | Webhook | Test bot token |
 | `core/.env.production` | Producción | Webhook | Real bot token |
 
+### Selección de Bot Activo
+
+En la estructura multibot, hay tres formas de seleccionar el bot activo:
+
+#### 1. Vía Symlink .active (Automático)
+
+```bash
+bun run bot use mybot123bot
+```
+
+Esto crea/actualiza el symlink `.active` para apuntar al bot seleccionado.
+
+#### 2. Vía Variable de Entorno TG_BOT
+
+```bash
+TG_BOT=mybot123bot bun run dev
+```
+
+#### 3. Automático
+
+El bot configurado más recientemente se activa automáticamente.
+
+### Migración desde Estructura Antigua
+
+Si tienes archivos `.env.{env}` antiguos, puedes migrarlos a la nueva estructura:
+
+```bash
+bun run bot migrate
+```
+
+Este comando:
+- Detecta archivos `.env.local`, `.env.staging`, `.env.production`
+- Crea la estructura `.envs/{bot}/{env}.env`
+- Hace backup de archivos antiguos como `.env.{env}.backup`
+- Actualiza el symlink `.active`
+
 ### Selección de Entorno
 
 La variable `TG_ENV` determina cuál archivo cargar:
@@ -58,6 +114,62 @@ TG_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
 TG_MODE=polling
 ```
 
+## Variables MTProto (para Bootstrap)
+
+### `TG_API_ID`
+
+**Descripción**: API ID de Telegram para MTProto (obtenido de my.telegram.org)
+
+**Requerido para**: `bun run bootstrap` (comando de creación automática de bots)
+
+**Obtenerlo**:
+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, Short name, Platform)
+5. Click "Create application"
+6. Copia el `api_id` (número entero)
+
+**Formato**: Número entero positivo
+
+**Ejemplo**:
+```bash
+TG_API_ID=12345678
+```
+
+### `TG_API_HASH`
+
+**Descripción**: API Hash de Telegram para MTProto (obtenido de my.telegram.org)
+
+**Requerido para**: `bun run bootstrap` (comando de creación automática de bots)
+
+**Formato**: String de 32+ caracteres
+
+**Ejemplo**:
+```bash
+TG_API_HASH=abc123def456789abc123def456789ab
+```
+
+> **IMPORTANTE**: Estas credenciales son diferentes del bot token.
+> - **Bot Token** (TG_BOT_TOKEN): Para Bot API, usado en runtime
+> - **MTProto Credentials** (TG_API_ID/TG_API_HASH): Para crear bots automáticamente vía @BotFather
+
+**Uso en Bootstrap**:
+```bash
+# Con credenciales en .env, bootstrap no te las pedirá
+bun run bootstrap
+
+# Sin credenciales, bootstrap te pedirá que las ingreses
+bun run bootstrap
+# → Enter your API ID: ********
+# → Enter your API Hash: ************************************
+```
+
+**Seguridad**:
+- Guarda estas credenciales en tu `.env` (nunca en el repo)
+- Son menos sensibles que el bot token, pero aún así privadas
+- Permiten que el bootstrainer automatice la creación de bots
+
 ## Variables Webhook (si TG_MODE=webhook)
 
 ### `TG_WEBHOOK_URL`
@@ -88,6 +200,30 @@ TG_WEBHOOK_SECRET=my_secret_token_min_16_chars
 
 ## Variables de Identificación
 
+### `TG_BOT`
+
+**Descripción**: Username del bot a activar (sistema multibot)
+
+**Formato**: Bot username sin el `@`
+
+**Ejemplo**:
+```bash
+TG_BOT=mybot123bot
+```
+
+**Uso**:
+```bash
+# Arrancar bot específico
+TG_BOT=mybot123bot bun run dev
+
+# Arrancar otro bot
+TG_BOT=anotherbot456bot bun run dev
+```
+
+**Alternativas**:
+- Usar `bun run bot use <username>` para establecer bot activo permanentemente
+- El symlink `.active` se usa automáticamente si `TG_BOT` no está seteado
+
 ### `TG_ENV`
 
 **Descripción**: Entorno actual del bot
@@ -364,7 +500,7 @@ TG_MAX_RETRIES=5
 
 ### Nunca Commitear .env Files
 
-Los archivos `.env.*` contienen secrets y no deben estar en git.
+Los archivos `.env.*` y el directorio `.envs/` contienen secrets y no deben estar en git.
 
 ```gitignore
 # En .gitignore
@@ -372,6 +508,11 @@ core/.env.local
 core/.env.staging
 core/.env.production
 core/.env.*
+
+# Multibot environment directory
+core/.envs/
+core/.envs/*/
+!core/.envs/.gitkeep
 ```
 
 ### Usar .env.example
@@ -405,7 +546,50 @@ kubectl create secret generic bot-secrets --from-literal=TG_BOT_TOKEN=xxx
 
 ## Plantillas de Entorno
 
-### Desarrollo (.env.local)
+### Estructura Multibot
+
+Para sistemas multibot, cada bot tiene su propio directorio con archivos de entorno:
+
+```bash
+# core/.envs/mybot123bot/local.env
+TG_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
+TG_MODE=polling
+TG_ENV=local
+LOG_LEVEL=debug
+TG_DEBUG=true
+
+# core/.envs/mybot123bot/staging.env
+TG_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
+TG_MODE=webhook
+TG_WEBHOOK_URL=https://staging.example.com/webhook
+TG_WEBHOOK_SECRET=staging_secret_min_16_chars
+TG_ENV=staging
+LOG_LEVEL=info
+
+# core/.envs/mybot123bot/production.env
+TG_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
+TG_MODE=webhook
+TG_WEBHOOK_URL=https://bot.example.com/webhook
+TG_WEBHOOK_SECRET=super_secure_secret_min_16_chars
+TG_ENV=production
+LOG_LEVEL=warn
+TG_RATE_LIMIT=30
+
+# core/.envs/mybot123bot/metadata.json
+{
+  "name": "My Bot",
+  "description": "My awesome Telegram bot",
+  "createdAt": "2025-01-07T14:30:45.000Z",
+  "updatedAt": "2025-01-07T15:15:22.000Z",
+  "tags": ["test", "demo"]
+}
+```
+
+### Estructura Legada (Archivos Únicos)
+
+Para proyectos con un solo bot, puedes usar archivos de entorno únicos:
+
+#### Desarrollo (.env.local)
 
 ```bash
 # Required
@@ -413,12 +597,16 @@ TG_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
 TG_MODE=polling
 TG_ENV=local
 
+# MTProto (opcional - para comando bootstrap)
+# TG_API_ID=12345678
+# TG_API_HASH=abc123def456789...
+
 # Logging
 LOG_LEVEL=debug
 TG_DEBUG=true
 ```
 
-### Staging (.env.staging)
+#### Staging (.env.staging)
 
 ```bash
 # Required

package/dist/templates/telegram-bot/docs/getting-started.md

@@ -18,7 +18,11 @@ bun --version
 
 ## Paso 1: Crear el Bot en Telegram
 
-### Hablar con @BotFather
+> **OPCIÓN RECOMENDADA: Bootstrap Automático**
+>
+> Si quieres automatizar TODO el proceso (crear bot, grupo, topics), salta a [Paso 4: Bootstrap Automático](#paso-4-bootstrap-automtico).
+
+### Hablar con @BotFather (Método Manual)
 
 1. Abre Telegram y busca **@BotFather**
 2. Inicia el chat con el comando `/newbot`
@@ -61,7 +65,33 @@ Esto instala todas las dependencias del workspace:
 
 ## Paso 4: Configurar el Entorno
 
-### Opción Recomendada: Setup Interactivo
+### 🌟 Opción Recomendada: Bootstrap Multibot
+
+El template ahora soporta **múltiples bots** desde un mismo proyecto. Usa el comando `bootstrap` para configurar todo automáticamente:
+
+```bash
+# Bootstrap interactivo completo (recomendado)
+bun run bootstrap
+
+# Listar bots disponibles desde BotFather
+bun run bootstrap --list
+
+# Usar bot específico
+bun run bootstrap --bot mybot123bot
+
+# Reutilizar configuración existente sin prompts
+bun run bootstrap --reuse
+```
+
+El bootstrap te guiará paso a paso:
+
+1. **Credenciales API** (si no las tienes): Tu API ID y Hash de https://my.telegram.org
+2. **Bot Selection**: Crear nuevo bot o reutilizar uno existente
+3. **Group Selection**: Crear nuevo grupo/forum o reutilizar existente
+4. **Topics Selection**: Crear topics para organización (Control, Logs, Config, Bugs)
+5. **Listo!**: Tu bot está configurado y listo para usar
+
+### Opción Manual: Setup Interactivo
 
 ```bash
 bun run setup
@@ -75,34 +105,156 @@ El comando te preguntará:
 4. **Streaming de logs** - Opcional, para ver logs en Telegram
 5. **Comandos de control** - Opcional, para comandos admin
 
-### Opción Manual: Editar Archivo .env
+### Opción Manual Avanzada: Editar Archivo .env
 
-```bash
-cp core/.env.example core/.env.local
-nano core/.env.local
-```
-
-Edita las variables mínimas:
+> **NOTA**: El sistema ahora usa la estructura `.envs/{bot}/{environment}.env` para multibot.
 
 ```bash
+# Crear directorio para tu bot
+mkdir -p core/.envs/mybot123bot
+
+# Crear archivo de entorno local
+cat > core/.envs/mybot123bot/local.env << 'EOF'
 # Required
 TG_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
 TG_MODE=polling
 TG_ENV=local
+EOF
+```
+
+### Sistema Multibot
+
+El template soporta gestión de **múltiples bots** desde un mismo proyecto:
+
+#### Estructura de Directorios
+
+```
+core/.envs/
+├── mybot123bot/
+│   ├── local.env       # Configuración local
+│   ├── staging.env     # Configuración staging
+│   ├── production.env  # Configuración production
+│   └── metadata.json   # Metadatos del bot
+├── anotherbot456bot/
+│   ├── local.env
+│   ├── staging.env
+│   └── production.env
+└── .active -> mybot123bot  # Symlink al bot activo
+```
+
+#### Comandos de Gestión de Bots
+
+```bash
+# Listar todos los bots configurados
+bun run bot list
+
+# Establecer bot activo
+bun run bot use mybot123bot
+
+# Ver información detallada de un bot
+bun run bot info mybot123bot
+
+# Eliminar configuración de un bot
+bun run bot delete mybot123bot
+
+# Migrar .envs antiguos a nueva estructura
+bun run bot migrate
+```
+
+#### Selección de Bot Activo
+
+Hay tres formas de seleccionar el bot activo:
+
+1. **Vía symlink .active** (automático con `bot use`):
+```bash
+bun run bot use mybot123bot
+```
+
+2. **Vía variable de entorno**:
+```bash
+TG_BOT=mybot123bot bun run dev
+```
+
+3. **Automático**: El bot configurado más recientemente se activa automáticamente
+
+### Opción Automática: Bootstrap Completo (Método Anterior)
+
+> **"BotFather Personal"** - Automatiza TODO el proceso de creación
+
+Si no has creado el bot todavía, puedes usar `bootstrap` para:
+
+1. **Crear el bot automáticamente** vía @BotFather
+2. **Crear un grupo/forum** para el bot
+3. **Añadir el bot como admin** del grupo
+4. **Crear topics** automáticamente (General, Control, Logs, Config, Bugs)
+5. **Configurar todos los IDs** en el `.env`
+
+```bash
+# Requiere credenciales MTProto API (ver abajo)
+bun run bootstrap
 ```
 
+<details>
+<summary>💡 ¿Cómo obtener credenciales MTProto API?</summary>
+
+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
+5. Click "Create application"
+6. Copia el `api_id` y `api_hash`
+
+> Puedes guardar estas credenciales en tu `.env` para evitar re-pedirlas:
+> ```bash
+> # MTProto API Credentials (for bootstrap command)
+> TG_API_ID=12345678
+> TG_API_HASH=abc123def456789...
+> ```
+
+</details>
+
+**Ventajas del Bootstrap:**
+
+| Feature | Bootstrap | Manual |
+|---------|-----------|--------|
+| Tiempo total | ~3-5 minutos | ~10-15 minutos |
+| Creación de bot | Automático | Hablar con @BotFather |
+| Creación de grupo | Automático | Manual en Telegram |
+| Creación de topics | Automática | Manual o comando separado |
+| IDs detection | Automático | Requiere auto-configure |
+
+> **Ver documentación completa**: [CLI Commands - Bootstrap](./cli-commands.md#bootstrap-command)
+
 ## Paso 5: Verificar Configuración
 
+> **ALTAMENTE RECOMENDADO** después de setup
+
 ```bash
 bun run doctor
 ```
 
-Este comando diagnostica tu configuración:
+Este comando diagnostica tu configuración y valida que todo esté correcto:
 
-- ✓ Dependencias instaladas
-- ✓ Archivos .env configurados
-- ✓ Token de bot válido
-- ✓ Puertos disponibles
+### Checks que Realiza
+
+| Check | Descripción |
+| ----- | ----------- |
+| ✓ Node.js version | Versión >= 20 |
+| ✓ Bun installation | Bun está instalado |
+| ✓ Dependencies | Todas las dependencias instaladas |
+| ✓ Environment files | Archivos .env existen |
+| ✓ Environment variables | Variables requeridas seteadas |
+| ✓ Bot token validation | Token válido contra Telegram API |
+| ✓ Control commands | Configuración de comandos de control |
+| ✓ Temp directory | core/tmp es writable |
+| ✓ Logs directory | core/logs existe |
+| ✓ Port availability | Puerto 3000 disponible |
+| ✓ Git ignore | .env files excluidos de git |
+
+### Output Esperado
 
 Deberías ver:
 
@@ -195,6 +347,8 @@ Ver [Troubleshooting](./troubleshooting.mdx) para más detalles.
 
 ## Resumen Rápido
 
+### Flujo Manual (con bot ya creado)
+
 ```bash
 # 1. Clonar el template
 git clone <repo>
@@ -206,7 +360,7 @@ bun install
 # 3. Configurar entorno (setup interactivo)
 bun run setup
 
-# 4. Verificar configuración
+# 4. Verificar configuración (recomendado)
 bun run doctor
 
 # 5. Arrancar en desarrollo
@@ -216,6 +370,39 @@ bun run dev
 # Envía /start a tu bot
 ```
 
+### Flujo Automático (Bootstrap)
+
+```bash
+# 1. Clonar el template
+git clone <repo>
+cd mks-telegram-bot
+
+# 2. Instalar dependencias
+bun install
+
+# 3. Obtener credenciales MTProto (my.telegram.org)
+# TG_API_ID=12345678
+# TG_API_HASH=abc123def456789...
+
+# 4. Bootstrap automático (crea bot, grupo, topics)
+bun run bootstrap
+
+# 5. Verificar configuración (recomendado)
+bun run doctor
+
+# 6. Arrancar en desarrollo
+bun run dev
+
+# 7. Probar en Telegram
+# Envía /start a tu bot
+```
+
+> **¿Cuál usar?**
+> - **Bootstrap** - Si no has creado el bot todavía (~3-5 min total)
+> - **Manual** - Si ya tienes el token de @BotFather (~10-15 min total)
+> - **Siempre** ejecuta `bun run doctor` después del setup para verificar
+
+
 ## Referencias
 
 - **@BotFather** - [@BotFather en Telegram](https://t.me/BotFather)

package/dist/templates/telegram-bot/package.json

@@ -5,8 +5,7 @@
   "type": "module",
   "workspaces": [
     "core",
-    "packages/*",
-    "apps/*"
+    "packages/*"
   ],
   "scripts": {
     "dev": "bun run --filter @mks2508/telegram-bot-core dev",
@@ -40,10 +39,15 @@
     "typescript": "^5"
   },
   "dependencies": {
+    "@mks2508/telegram-message-builder": "0.3.1",
+    "@mks2508/telegram-bot-utils": "workspace:*",
     "@inquirer/prompts": "^8.1.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",
-    "glob": "^13.0.0"
+    "glob": "^13.0.0",
+    "ora": "^9.0.0",
+    "telegraf": "^4.16.3",
+    "telegram": "^2.26.22"
   }
 }

package/dist/templates/telegram-bot/packages/utils/package.json

@@ -2,11 +2,22 @@
   "name": "@mks2508/telegram-bot-utils",
   "version": "0.1.0",
   "type": "module",
+  "scripts": {
+    "build": "rolldown --config rolldown.config.ts && tsgo --emitDeclarationOnly",
+    "dev": "bun run --watch src/index.ts",
+    "typecheck": "tsgo --noEmit"
+  },
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "dependencies": {
     "@mks2508/better-logger": "^4.0.0",
     "@mks2508/no-throw": "^0.1.0"
+  },
+  "devDependencies": {
+    "rolldown": "^1.0.0-beta.58"
   }
 }

package/dist/templates/telegram-bot/packages/utils/rolldown.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'rolldown';
+
+export default defineConfig({
+  input: './src/index.ts',
+  output: {
+    file: './dist/index.js',
+    format: 'esm',
+    sourcemap: true,
+  },
+  external: ['@mks2508/better-logger', '@mks2508/no-throw'],
+});

package/dist/templates/telegram-bot/packages/utils/src/logger.ts

@@ -30,6 +30,7 @@ export const botLogger = component('Bot')
 export const configLogger = component('Config')
 export const commandLogger = component('Command')
 export const healthLogger = component('Health')
+export const infoLogger = component('Info')
 export const controlLogger = component('Control')
 export const streamLogger = component('LogStream')
 export const errorLogger = component('Error')

package/dist/templates/telegram-bot/packages/utils/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "declarationDir": "./dist"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/dist/templates/telegram-bot/tools/commands/doctor.ts

@@ -55,6 +55,7 @@ async function handleDoctor(): Promise<void> {
   checks.push(await checkEnvFile())
   checks.push(await checkRequiredEnvVars())
   checks.push(await checkBotToken())
+  checks.push(await checkControlCommands())
   checks.push(await checkTmpDirectory())
   checks.push(await checkLogsDirectory())
   checks.push(await checkPorts())
@@ -302,6 +303,67 @@ async function checkBotToken(): Promise<CheckResult> {
   }
 }
 
+async function checkControlCommands(): Promise<CheckResult> {
+  const envPath = join(process.cwd(), 'core', '.env.local')
+
+  if (!existsSync(envPath)) {
+    return {
+      name: 'Control commands',
+      status: 'warn',
+      message: 'No .env.local file found',
+    }
+  }
+
+  try {
+    const content = await readFile(envPath, 'utf-8')
+    const hasControlChatId = content.includes('TG_CONTROL_CHAT_ID=') && !content.includes('TG_CONTROL_CHAT_ID=#')
+
+    if (hasControlChatId) {
+      const match = content.match(/TG_CONTROL_CHAT_ID=([^\n]+)/)
+      const chatId = match?.[1]?.trim()
+
+      if (!chatId || chatId === 'your_control_chat_id_here' || chatId.startsWith('#')) {
+        return {
+          name: 'Control commands',
+          status: 'warn',
+          message: 'Control chat ID not configured',
+          details: 'Control commands (/stop, /restart) are disabled. Run: bun run setup',
+        }
+      }
+
+      const hasAuthorizedUsers = content.includes('TG_AUTHORIZED_USER_IDS=')
+
+      if (!hasAuthorizedUsers) {
+        return {
+          name: 'Control commands',
+          status: 'warn',
+          message: 'Control enabled but no authorized users',
+          details: 'Add TG_AUTHORIZED_USER_IDS to .env.local',
+        }
+      }
+
+      return {
+        name: 'Control commands',
+        status: 'pass',
+        message: 'Control commands enabled',
+      }
+    }
+
+    return {
+      name: 'Control commands',
+      status: 'warn',
+      message: 'Control commands disabled',
+      details: 'Enable with TG_CONTROL_CHAT_ID. Run: bun run setup',
+    }
+  } catch {
+    return {
+      name: 'Control commands',
+      status: 'warn',
+      message: 'Could not read .env.local',
+    }
+  }
+}
+
 async function checkTmpDirectory(): Promise<CheckResult> {
   const tmpPath = join(process.cwd(), 'core', 'tmp')