create-bunspace 0.2.5 → 0.3.0

package/dist/templates/telegram-bot/CLAUDE.md

@@ -1,9 +1,9 @@
 # CLAUDE.md - mks-telegram-bot
 
 > **Template**: Monorepo para bots de Telegram con Bun, Telegraf y TypeScript
-> **Versión**: 0.1.0
+> **Versión**: 0.3.0
 
-Template monorepo diseñado para ser usado como `bun create mks2508/mks-telegram-bot` o como GitHub template repository.
+Template monorepo diseñado para ser usado como GitHub template repository o clonado directamente.
 
 **Objetivo**: Template reutilizable para crear bots de Telegram con las mejores prácticas, tipado estricto y arquitectura modular.
 
@@ -13,13 +13,13 @@ Template monorepo diseñado para ser usado como `bun create mks2508/mks-telegram
 
 ```bash
 # Clonar o usar como template
-bun create mks2508/mks-telegram-bot my-bot
+gh repo create my-bot --template MKS2508/mks-telegram-bot
 
 # Instalar dependencias
 bun install
 
-# Configurar variables de entorno
-cp core/.env.example core/.env
+# Bootstrap interactivo (crea bot, grupo, topics)
+bunx @mks2508/telegram-bot-manager bootstrap
 
 # Desarrollo
 bun run dev
@@ -35,25 +35,7 @@ Este template tiene contextos separados por dominio:
 | ------- | --------- |
 | [CLAUDE.dev.md](./CLAUDE.dev.md) | Desarrollo, patterns, testing |
 | [CLAUDE.deploy.md](./CLAUDE.deploy.md) | Deployment, Docker, entornos |
-| [docs/](./docs/) | Documentación web (MDX, futuro) |
-
-### CLAUDE.dev.md
-
-Ver [CLAUDE.dev.md](./CLAUDE.dev.md) para:
-- Development standards y code style
-- Cómo agregar commands y middleware
-- Testing patterns
-- Result type pattern y Singleton pattern
-- Better Logger usage
-
-### CLAUDE.deploy.md
-
-Ver [CLAUDE.deploy.md](./CLAUDE.deploy.md) para:
-- Multi-environment (local, staging, production)
-- Multi-instance management
-- Docker deployment
-- ngrok integration
-- VPS deployment guide
+| [docs/](./docs/) | Documentación detallada |
 
 ---
 
@@ -61,76 +43,163 @@ Ver [CLAUDE.deploy.md](./CLAUDE.deploy.md) para:
 
 When modifying this codebase, prioritize understanding:
 
+### Core Bot (`core/`)
 - `core/src/index.ts` - Bot entry point, command registration
-- `core/src/config/env.ts` - Environment schema validation
+- `core/src/config/env.ts` - Environment schema validation, multibot loading
+- `core/src/handlers/` - Command handlers (health, control, logs, etc.)
+- `core/src/middleware/` - Telegraf middleware (auth, error, topics)
 - `core/src/utils/instance-manager.ts` - Multi-instance locking
-- `packages/utils/src/` - Shared utilities (logger, result)
 
----
+### Local CLI Tools (`tools/`)
+- `tools/commands/setup.ts` - Setup manual de entorno
+- `tools/commands/doctor.ts` - Diagnóstico de configuración
+- `tools/commands/status.ts` - Estado de instancias
+- `tools/commands/ngrok.ts` - Túnel ngrok para webhooks
 
-## Session Context Template
+### Bot Management (External Package)
 
-When starting a new session, include:
-- **User's goal**: developing vs deploying vs extending
-- **Current environment**: local/staging/production
-- **Any errors or issues encountered**: Paste error messages
+Para gestión de bots (bootstrap, configuración BotFather, multibot), usar **@mks2508/telegram-bot-manager**:
+
+```bash
+# Bootstrap completo (bot + grupo + topics)
+bunx @mks2508/telegram-bot-manager bootstrap
+
+# Listar bots desde BotFather e importar
+bunx @mks2508/telegram-bot-manager bootstrap --list
+
+# Gestión de bots configurados
+bunx @mks2508/telegram-bot-manager bot list
+bunx @mks2508/telegram-bot-manager bot use mybot123bot
+bunx @mks2508/telegram-bot-manager bot info mybot123bot
+bunx @mks2508/telegram-bot-manager bot delete mybot123bot
+
+# Configurar bot via BotFather
+bunx @mks2508/telegram-bot-manager configure commands mybot123bot
+bunx @mks2508/telegram-bot-manager configure description mybot123bot
+bunx @mks2508/telegram-bot-manager configure about mybot123bot
+bunx @mks2508/telegram-bot-manager configure name mybot123bot
+
+# Crear topics en grupo forum
+bunx @mks2508/telegram-bot-manager topics
+```
 
 ---
 
-## Monorepo Structure
+## Project Structure
 
 ```
 mks-telegram-bot/
-├── core/                 # @mks2508/telegram-bot-core
-│   ├── .env.local       # Local development
-│   ├── .env.staging     # Staging environment
-│   ├── .env.production  # Production environment
-│   ├── tmp/             # Instance lock files
-│   └── src/            # Bot source code
-├── packages/            # Shared code
-│   └── utils/          # @mks2508/telegram-bot-utils
-├── tools/               # CLI tools
-│   └── commands/       # ngrok, status
-├── apps/               # Future: examples, docs
-├── docs/               # Future MDX site
-├── Dockerfile          # Multi-stage build
-└── docker-compose.yml  # Local dev containers
+├── core/                    # @mks2508/telegram-bot-core (Bot principal)
+│   ├── .envs/              # Configuraciones multibot
+│   │   ├── {botUsername}/
+│   │   │   ├── local.env
+│   │   │   ├── staging.env
+│   │   │   ├── production.env
+│   │   │   └── metadata.json
+│   │   └── .active -> {botUsername}
+│   ├── src/
+│   │   ├── index.ts         # Entry point
+│   │   ├── config/          # Configuration & env validation (Zod)
+│   │   ├── handlers/        # Command handlers
+│   │   ├── middleware/      # Telegraf middleware
+│   │   ├── types/           # TypeScript types
+│   │   └── utils/           # Utilities (instance-manager, etc.)
+│   ├── logs/               # Log files (rotated)
+│   ├── tmp/                # Instance lock files (.pid, .lock)
+│   └── .env.example        # Template de variables
+├── tools/                  # CLI tools locales
+│   ├── index.ts            # CLI entry point
+│   └── commands/
+│       ├── setup.ts        # Setup manual interactivo
+│       ├── doctor.ts       # Diagnóstico de configuración
+│       ├── status.ts       # Estado de instancias
+│       └── ngrok.ts        # Integración ngrok
+├── docs/                   # Documentación
+│   ├── getting-started.md
+│   ├── environment.md
+│   ├── cli-commands.md
+│   ├── development.md
+│   └── troubleshooting.md
+├── apps/                   # Apps adicionales (futuro)
+├── Dockerfile              # Multi-stage build
+├── docker-compose.yml      # Containers locales
+└── package.json            # Root workspace config
 ```
 
 ---
 
-## Commands
+## Commands Reference
+
+### Local Development Commands
 
 ```bash
 # Development
 bun run dev           # Hot reload (watch mode)
 bun run start         # Production mode
 
-# CLI tools
-bun run status        # Show running instances
-bun run ngrok         # Start ngrok tunnel
-
 # Quality
-bun run typecheck     # Type check (tsgo ~10x faster)
+bun run typecheck     # Type check (tsgo - ~10x faster)
 bun run lint          # Lint (oxlint)
 bun run format        # Format (prettier)
+bun run test          # Run tests
+
+# Local CLI tools
+bun run setup         # Setup manual de entorno
+bun run setup:staging # Setup staging
+bun run setup:production # Setup production
+bun run doctor        # Diagnóstico de configuración
+bun run ngrok         # Start ngrok tunnel
+bun run cli status    # Ver instancias corriendo
+
+# Maintenance
+bun run clean:logs    # Limpiar logs y locks
+bun run clean:all     # Limpiar todo
+```
+
+### Bot Management Commands (External)
+
+```bash
+# Usar @mks2508/telegram-bot-manager via bunx/npx:
+
+# Bootstrap
+bunx @mks2508/telegram-bot-manager bootstrap          # Interactivo completo
+bunx @mks2508/telegram-bot-manager bootstrap --list   # Listar e importar bots
+bunx @mks2508/telegram-bot-manager bootstrap --auto   # Auto-generado sin prompts
+
+# Bot management
+bunx @mks2508/telegram-bot-manager bot list           # Listar bots configurados
+bunx @mks2508/telegram-bot-manager bot use <username> # Cambiar bot activo
+bunx @mks2508/telegram-bot-manager bot info <username># Info de bot
+bunx @mks2508/telegram-bot-manager bot delete <user>  # Eliminar bot
+bunx @mks2508/telegram-bot-manager bot migrate        # Migrar .env antiguos
+
+# Configure via BotFather
+bunx @mks2508/telegram-bot-manager configure commands <user>
+bunx @mks2508/telegram-bot-manager configure description <user>
+bunx @mks2508/telegram-bot-manager configure about <user>
+bunx @mks2508/telegram-bot-manager configure name <user>
+
+# Topics
+bunx @mks2508/telegram-bot-manager topics
 ```
 
 ---
 
 ## Environment Variables
 
-### Multi-Environment Support
+### Multibot Structure
 
-El proyecto soporta múltiples entornos con archivos `.env` separados:
+El proyecto soporta **gestión multibot** con estructura `.envs/`:
 
-| Archivo | Uso |
-| ------- | --- |
-| `core/.env.local` | Desarrollo local (polling mode) |
-| `core/.env.staging` | Testing con bot de test |
-| `core/.env.production` | Producción con bot real |
-
-La variable `TG_ENV` (default: `local`) determina cuál archivo cargar.
+```
+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
+```
 
 ### Required Variables
 
@@ -139,13 +208,18 @@ La variable `TG_ENV` (default: `local`) determina cuál archivo cargar.
 | `TG_BOT_TOKEN` | string | Bot token from @BotFather |
 | `TG_MODE` | enum | `polling` or `webhook` |
 
-### Instance Detection Variables
+### Optional Variables
 
 | Variable | Default | Description |
 | -------- | ------- | ----------- |
 | `TG_ENV` | `local` | Environment: local/staging/production |
 | `TG_INSTANCE_NAME` | `mks-bot` | Unique instance name for locking |
 | `TG_INSTANCE_CHECK` | `true` | Enable instance conflict detection |
+| `TG_AUTHORIZED_USER_IDS` | - | Comma-separated user IDs for control commands |
+| `TG_CONTROL_CHAT_ID` | - | Chat ID for control commands |
+| `TG_CONTROL_TOPIC_ID` | - | Topic ID for control commands |
+| `TG_LOG_CHAT_ID` | - | Chat ID for log streaming |
+| `TG_LOG_TOPIC_ID` | - | Topic ID for log streaming |
 
 ---
 
@@ -158,11 +232,9 @@ La variable `TG_ENV` (default: `local`) determina cuál archivo cargar.
 | **TypeScript** | Language | 5.9+ |
 | **tsgo** | Type-checking | native-preview |
 | **Zod** | Schema validation | 3.24+ |
-| **Better Logger** | Logging | 4.0.0 |
-| **@mks2508/no-throw** | Result type | 0.1.0 |
 | **oxlint** | Linting | latest |
 | **prettier** | Formatting | 3.4+ |
-| **commander** | CLI framework | 14.0+ |
+| **@mks2508/telegram-bot-manager** | Bot management (external) | 0.1.1+ |
 
 ---
 
@@ -176,10 +248,10 @@ La variable `TG_ENV` (default: `local`) determina cuál archivo cargar.
         ┌─────────────────┼─────────────────┐
         │                 │                 │
    ┌────▼────┐    ┌───────▼───────┐  ┌──────▼──────┐
-   │Middleware│    │   Handlers   │  │ BotManager  │
-   │ • auth   │    │ • health     │  │ InstanceMgr │
-   │ • error  │    │ • control    │  │ • stats     │
-   │ • topics │    │ • logs       │  │ • lifecycle │
+   │Middleware│    │   Handlers   │  │   Config    │
+   │ • auth   │    │ • health     │  │ • env.ts    │
+   │ • error  │    │ • control    │  │ • Zod       │
+   │ • topics │    │ • logs       │  │ validation  │
    └──────────┘    └──────────────┘  └─────────────┘
         │                                │
         └────────────┬───────────────────┘
@@ -188,6 +260,7 @@ La variable `TG_ENV` (default: `local`) determina cuál archivo cargar.
             │ InstanceManager │
             │  • acquireLock  │
             │  • releaseLock  │
+            │  • PID files    │
             └─────────────────┘
 ```
 
@@ -203,6 +276,7 @@ La variable `TG_ENV` (default: `local`) determina cuál archivo cargar.
 | `/health` | handleHealth | Bot health status |
 | `/uptime` | handleUptime | Uptime information |
 | `/stats` | handleStats | Bot statistics |
+| `/getinfo` | inline | Get User ID, Chat ID, Topic ID |
 | `/logs` | handleLogs | Log streaming status |
 
 ### Control Commands (requires auth)
@@ -220,32 +294,16 @@ La variable `TG_ENV` (default: `local`) determina cuál archivo cargar.
 
 ### Before Commit
 
-- [ ] `bun run typecheck` → 0 errores
+- [ ] `bun run typecheck` → 0 errors
 - [ ] `bun run lint` → 0 warnings, 0 errors
 - [ ] `bun test` → all tests pass (if tests exist)
-- [ ] No `console.*` (use Better Logger)
 
 ### Code Style
 
 - TypeScript strict mode enabled
 - `noUncheckedIndexedAccess: true` - arrays need undefined checks
 - Semi: false, singleQuote: true
-- Result type pattern para error handling
-
----
-
-## Documentation Web
-
-Ver [docs/](./docs/) para documentación completa (futuro MDX site con Astro/Starlight).
-
----
-
-## Future Apps
-
-El directorio `apps/` está preparado para:
-- `apps/example/` - Ejemplo de bot completo
-- `apps/docs/` - Documentación interactiva
-- `apps/cli/` - CLI extendida para gestión
+- No console.* - use structured logger
 
 ---
 
@@ -267,7 +325,7 @@ El template soporta múltiples instancias simultáneas con detección de conflic
 
 ```bash
 # Ver instancias corriendo
-bun run status
+bun run cli status
 
 # Iniciar en entorno específico
 TG_ENV=staging bun run start
@@ -275,6 +333,25 @@ TG_ENV=staging bun run start
 
 ---
 
+## Relationship with @mks2508/telegram-bot-manager
+
+Este template usa **@mks2508/telegram-bot-manager** como paquete externo para:
+
+- **Bootstrap**: Crear bots via BotFather automáticamente
+- **Group Management**: Crear grupos/forums con topics
+- **Multibot Management**: Gestionar múltiples bots configurados
+- **BotFather Configuration**: Configurar commands, description, about, name
+
+El paquete se usa via `bunx` (no se instala como dependencia):
+
+```bash
+bunx @mks2508/telegram-bot-manager <command>
+```
+
+**Documentación del paquete**: https://github.com/MKS2508/telegram-bot-manager
+
+---
+
 ## License
 
 MIT