create-bunspace 0.1.0

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

@@ -0,0 +1,280 @@
+# CLAUDE.md - mks-telegram-bot
+
+> **Template**: Monorepo para bots de Telegram con Bun, Telegraf y TypeScript
+> **Versión**: 0.1.0
+
+Template monorepo diseñado para ser usado como `bun create mks2508/mks-telegram-bot` o como GitHub template repository.
+
+**Objetivo**: Template reutilizable para crear bots de Telegram con las mejores prácticas, tipado estricto y arquitectura modular.
+
+---
+
+## Quick Start
+
+```bash
+# Clonar o usar como template
+bun create mks2508/mks-telegram-bot my-bot
+
+# Instalar dependencias
+bun install
+
+# Configurar variables de entorno
+cp core/.env.example core/.env
+
+# Desarrollo
+bun run dev
+```
+
+---
+
+## Contextos Especializados
+
+Este template tiene contextos separados por dominio:
+
+| Archivo | Propósito |
+| ------- | --------- |
+| [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
+
+---
+
+## Critical Files for Claude
+
+When modifying this codebase, prioritize understanding:
+
+- `core/src/index.ts` - Bot entry point, command registration
+- `core/src/config/env.ts` - Environment schema validation
+- `core/src/utils/instance-manager.ts` - Multi-instance locking
+- `packages/utils/src/` - Shared utilities (logger, result)
+
+---
+
+## Session Context Template
+
+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
+
+---
+
+## Monorepo 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
+```
+
+---
+
+## 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 lint          # Lint (oxlint)
+bun run format        # Format (prettier)
+```
+
+---
+
+## Environment Variables
+
+### Multi-Environment Support
+
+El proyecto soporta múltiples entornos con archivos `.env` separados:
+
+| 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.
+
+### Required Variables
+
+| Variable | Tipo | Description |
+| -------- | ---- | ----------- |
+| `TG_BOT_TOKEN` | string | Bot token from @BotFather |
+| `TG_MODE` | enum | `polling` or `webhook` |
+
+### Instance Detection 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 |
+
+---
+
+## Technology Stack
+
+| Tool | Purpose | Version |
+| ---- | ------- | ------- |
+| **Bun** | Runtime & package manager | 1.3+ |
+| **Telegraf** | Telegram Bot API | 4.16+ |
+| **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+ |
+
+---
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Telegram API (Telegraf)                 │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+        ┌─────────────────┼─────────────────┐
+        │                 │                 │
+   ┌────▼────┐    ┌───────▼───────┐  ┌──────▼──────┐
+   │Middleware│    │   Handlers   │  │ BotManager  │
+   │ • auth   │    │ • health     │  │ InstanceMgr │
+   │ • error  │    │ • control    │  │ • stats     │
+   │ • topics │    │ • logs       │  │ • lifecycle │
+   └──────────┘    └──────────────┘  └─────────────┘
+        │                                │
+        └────────────┬───────────────────┘
+                     │
+            ┌────────▼────────┐
+            │ InstanceManager │
+            │  • acquireLock  │
+            │  • releaseLock  │
+            └─────────────────┘
+```
+
+---
+
+## Bot Commands
+
+### Public Commands
+
+| Command | Handler | Description |
+| ------- | ------- | ----------- |
+| `/start` | inline | Welcome message |
+| `/health` | handleHealth | Bot health status |
+| `/uptime` | handleUptime | Uptime information |
+| `/stats` | handleStats | Bot statistics |
+| `/logs` | handleLogs | Log streaming status |
+
+### Control Commands (requires auth)
+
+| Command | Handler | Description |
+| ------- | ------- | ----------- |
+| `/stop` | handleStop | Graceful shutdown |
+| `/restart` | handleRestart | Restart with stats reset |
+| `/mode` | handleMode | Switch polling/webhook |
+| `/webhook` | handleWebhook | Show webhook config |
+
+---
+
+## Development Workflow
+
+### Before Commit
+
+- [ ] `bun run typecheck` → 0 errores
+- [ ] `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
+
+---
+
+## Deployment
+
+### Docker
+
+```bash
+# Build image
+docker build -t mks-telegram-bot .
+
+# Run with docker-compose
+docker-compose up bot-production
+```
+
+### Multi-Instance
+
+El template soporta múltiples instancias simultáneas con detección de conflictos:
+
+```bash
+# Ver instancias corriendo
+bun run status
+
+# Iniciar en entorno específico
+TG_ENV=staging bun run start
+```
+
+---
+
+## License
+
+MIT

package/dist/templates/telegram-bot/Dockerfile

@@ -0,0 +1,46 @@
+# Build stage
+FROM oven/bun:1.3 AS builder
+WORKDIR /app
+
+# Copy package files
+COPY package.json bun.lock ./
+COPY core/package.json core/
+
+# Install dependencies
+RUN bun install --frozen-lockfile
+
+# Copy TypeScript config and source
+COPY tsconfig.json ./
+COPY core/tsconfig.json core/
+COPY core/src core/src
+
+# Production stage
+FROM oven/bun:1.3 AS production
+WORKDIR /app
+
+# Copy node_modules from builder
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/core/node_modules ./core/node_modules
+
+# Copy source and config files
+COPY --from=builder /app/core/src ./core/src
+COPY --from=builder /app/core/package.json ./core/
+COPY --from=builder /app/core/tsconfig.json ./core/
+
+# Create necessary directories
+RUN mkdir -p /app/core/tmp /app/core/logs
+
+# Set environment variables
+ENV TG_ENV=production
+ENV NODE_ENV=production
+ENV TG_MODE=webhook
+
+# Healthcheck
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+  CMD bun run cli status || exit 1
+
+# Expose webhook port
+EXPOSE 3000
+
+# Run the bot
+CMD ["bun", "run", "start"]

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

@@ -0,0 +1,245 @@
+# mks-telegram-bot
+
+> Template monorepo para bots de Telegram con Bun, Telegraf y TypeScript
+
+[![Use this template](https://github.com/MKS2508/mks-telegram-bot/generate)](https://github.com/MKS2508/mks-telegram-bot/generate)
+
+Template listo para producción con soporte multi-entorno, multi-instancia, y las mejores prácticas de desarrollo.
+
+## Quick Start (5 min)
+
+### 1. Crear el Bot
+
+Habla con [@BotFather](https://t.me/BotFather) en Telegram:
+
+```
+/newbot
+→ Nombre: MyBot
+→ Username: my_awesome_bot
+→ Copia el token (ej: 123456:ABC-DEF1234...)
+```
+
+### 2. Instalar y Configurar
+
+```bash
+# Usar el template
+# Click en "Use this template" arriba → Create a new repository
+# O con CLI: gh repo create my-bot --template MKS2508/mks-telegram-bot
+
+# Clonar tu nuevo repo
+git clone https://github.com/TU_USUARIO/my-bot.git
+cd my-bot
+
+# Instalar dependencias
+bun install
+
+# Setup interactivo (crea .env.local)
+bun run setup
+```
+
+El comando `setup` te preguntará:
+- Bot token (pega el token de @BotFather)
+- Modo (polling para desarrollo)
+- Chat IDs opcionales
+
+### 3. Arrancar en Desarrollo
+
+```bash
+bun run dev
+```
+
+### 4. Probar
+
+Envía `/start` o `/health` a tu bot en Telegram.
+
+## Comandos CLI
+
+| Comando | Descripción |
+| ------- | ----------- |
+| `bun run setup` | Configuración interactiva de entorno |
+| `bun run setup:staging` | Setup para entorno staging |
+| `bun run setup:production` | Setup para producción |
+| `bun run doctor` | Diagnóstico de configuración |
+| `bun run cli status` | Ver instancias corriendo |
+| `bun run ngrok` | ngrok con webhook auto-config |
+
+## Scripts de Desarrollo
+
+| Script | Descripción |
+| ------ | ----------- |
+| `bun run dev` | Hot reload (development) |
+| `bun run start` | Production start |
+| `bun run build` | Typecheck + lint |
+| `bun run test` | Ejecutar tests |
+| `bun run typecheck` | Type-check con tsgo |
+| `bun run lint` | Lint con oxlint |
+
+## Documentación
+
+| Documento | Descripción |
+| --------- | ----------- |
+| [Getting Started](./docs/getting-started.md) | Guía de inicio paso a paso |
+| [Environment](./docs/environment.md) | Variables de entorno |
+| [CLI Commands](./docs/cli-commands.md) | Comandos CLI disponibles |
+| [Development](./docs/development.md) | Flujo de desarrollo |
+| [Troubleshooting](./docs/troubleshooting.md) | Problemas comunes |
+
+**Documentación adicional:**
+- [CLAUDE.md](./CLAUDE.md) - Entry point principal
+- [CLAUDE.dev.md](./CLAUDE.dev.md) - Guía de desarrollo
+- [CLAUDE.deploy.md](./CLAUDE.deploy.md) - Deployment y entornos
+
+## Estructura del Monorepo
+
+```
+mks-telegram-bot/
+├── core/              # Bot principal (@mks2508/telegram-bot-core)
+│   ├── src/
+│   │   ├── index.ts      # Entry point
+│   │   ├── config/       # Configuration & env validation
+│   │   ├── handlers/     # Command handlers
+│   │   ├── middleware/   # Telegraf middleware
+│   │   ├── types/        # TypeScript types & Result pattern
+│   │   └── utils/        # Utilities (bot-manager, instance-manager)
+│   └── .env.example      # Template de variables de entorno
+├── packages/utils/      # Utilidades compartidas (@mks2508/telegram-bot-utils)
+│   └── src/
+│       ├── logger.ts     # Better Logger setup
+│       └── result.ts     # Result type pattern
+├── tools/              # CLI tools
+│   └── commands/
+│       ├── setup.ts     # Interactive setup
+│       ├── doctor.ts    # Diagnostics
+│       ├── status.ts    # Instance status
+│       └── ngrok.ts     # ngrok integration
+├── docs/               # Documentación
+│   ├── getting-started.md
+│   ├── environment.md
+│   ├── cli-commands.md
+│   ├── development.md
+│   ├── troubleshooting.md
+│   └── examples/       # Ejemplos de código
+└── apps/               # Apps de ejemplo (futuro)
+```
+
+## Stack Tecnológico
+
+| Herramienta | Versión | Uso |
+| ----------- | ------ | --- |
+| **Bun** | 1.3+ | Runtime & package manager |
+| **TypeScript** | 5.9+ | Lenguaje |
+| **Telegraf** | 4.16+ | Telegram Bot API |
+| **Zod** | 3.24+ | Schema validation |
+| **Better Logger** | 4.0.0 | Logging |
+| **@mks2508/no-throw** | 0.1.0 | Result type pattern |
+| **tsgo** | native-preview | Type checking |
+| **oxlint** | latest | Linting |
+| **prettier** | 3.4+ | Formatting |
+
+## Features
+
+### Core
+- ✅ Result type pattern para error handling sin excepciones
+- ✅ TypeScript strict mode con tipado completo
+- ✅ Soporte polling y webhook modes
+- ✅ Configuración centralizada con Zod validation
+- ✅ Singleton pattern para BotManager y Config
+
+### Multi-Entorno
+- ✅ Soporte para local, staging, production
+- ✅ Archivos `.env.{environment}` separados
+- ✅ Selección vía `TG_ENV`
+- ✅ Setup CLI interactivo
+
+### Multi-Instancia
+- ✅ Lock management con archivos PID
+- ✅ Detección de conflictos
+- ✅ Status CLI para ver instancias
+- ✅ Doctor CLI para diagnóstico
+
+### Logging System
+Tres destinos de logging usando Better Logger 4.0.0:
+
+1. **Console** - Colored output con preset cyberpunk
+2. **File** - Logs persistentes con rotación automática
+3. **Telegram** - Streaming a chat con buffering
+
+### Bot Commands
+
+**Public Commands**:
+- `/start` - Welcome message
+- `/health` - Health check
+- `/uptime` - Uptime info
+- `/stats` - Statistics
+- `/logs` - Log streaming status
+
+**Control Commands** (requieren autorización):
+- `/stop` - Graceful shutdown
+- `/restart` - Restart con stats reset
+- `/mode` - Switch polling/webhook
+- `/webhook` - Webhook configuration
+
+## Development Workflow
+
+### Setup Inicial
+
+```bash
+# Instalar dependencias
+bun install
+
+# Setup interactivo
+bun run setup
+
+# Verificar configuración
+bun run doctor
+
+# Arrancar en desarrollo
+bun run dev
+```
+
+### Antes de Commitear
+
+```bash
+# Verificar tipo y lint
+bun run build
+
+# Ejecutar tests
+bun test
+
+# O usar precommit
+bun run precommit
+```
+
+### Code Style
+
+- TypeScript strict mode
+- Semi: false, singleQuote: true
+- Result type pattern para error handling
+- Better Logger para logging (no console.*)
+
+## Examples
+
+Ver [`docs/examples/`](./docs/examples/) para ejemplos completos:
+
+- [Simple Command](./docs/examples/simple-command.md) - Crear comandos
+- [Auth Middleware](./docs/examples/middleware-auth.md) - Middleware de autenticación
+- [Webhook Setup](./docs/examples/webhook-setup.md) - Configurar webhook
+
+## Deployment
+
+El template incluye configuración para:
+
+- **Docker** - Dockerfile multi-stage incluido
+- **VPS** - Guía para deployment en VPS
+- **ngrok** - Integración para testing local
+- **Multi-entorno** - local, staging, production
+
+Ver [CLAUDE.deploy.md](./CLAUDE.deploy.md) para guía completa de deployment.
+
+## License
+
+MIT
+
+## Autor
+
+[@mks2508](https://github.com/mks2508)