create-bunspace 0.1.0

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

@@ -0,0 +1,356 @@
+# CLAUDE.deploy.md - Guía de Deployment
+
+> **Parte de**: [CLAUDE.md](./CLAUDE.md) | Ver también: [CLAUDE.dev.md](./CLAUDE.dev.md)
+
+Guía de deployment para multi-entorno y multi-instancia.
+
+**Documentación relacionada**:
+- [docs/deployment/docker.mdx](./docs/deployment/docker.mdx)
+- [docs/deployment/vps.mdx](./docs/deployment/vps.mdx)
+- [docs/deployment/environments.mdx](./docs/deployment/environments.mdx)
+
+---
+
+## Multi-Environment Architecture
+
+El template soporta múltiples entornos con archivos `.env` separados:
+
+### Archivos de Entorno
+
+| 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 Entorno
+
+La variable `TG_ENV` determina cuál archivo cargar:
+
+```bash
+# Default: local (carga .env.local)
+bun run start
+
+# Staging
+TG_ENV=staging bun run start
+
+# Production
+TG_ENV=production bun run start
+```
+
+---
+
+## Multi-Instance Management
+
+### Sistema de Lock
+
+El `InstanceManager` previene conflictos usando archivos PID/LOCK en `core/tmp/`:
+
+```
+core/tmp/
+├── mks-bot-local.pid     # Process ID
+├── mks-bot-local.lock    # Lock data (JSON)
+├── mks-bot-staging.pid
+└── mks-bot-staging.lock
+```
+
+### Contenido del Lock File
+
+```json
+{
+  "pid": 12345,
+  "instanceId": "1734567890-abc123",
+  "environment": "production",
+  "instanceName": "mks-bot-prod",
+  "startTime": "2025-01-06T10:30:00.000Z",
+  "nodeVersion": "v1.3.0",
+  "cwd": "/app"
+}
+```
+
+### Detección de Conflictos
+
+Al iniciar, el bot verifica si otra instancia está corriendo:
+
+- **Si está corriendo**: Error `INSTANCE_CONFLICT` con detalles
+- **Si no está corriendo**: Remueve lock stale y continua
+- **Si está deshabilitado**: `TG_INSTANCE_CHECK=false` salta verificación
+
+### Ver Instancias Corriendo
+
+```bash
+# Ver todas las instancias
+bun run status
+
+# Output como JSON
+bun run cli status --json
+```
+
+**Output**:
+```
+┌─────────┬───────────────┬───────────────────┬─────────────┬────────┐
+│ (index) │     PID       │   Environment     │     Name     │ Status │
+├─────────┼───────────────┼───────────────────┼─────────────┼────────┤
+│    0    │    12345      │    'production'   │ 'mks-bot...' │'✓ Run' │
+│    1    │    12346      │    'staging'      │ 'mks-bot...' │'✓ Run' │
+└─────────┴───────────────┴───────────────────┴─────────────┴────────┘
+```
+
+---
+
+## Docker Deployment
+
+### Dockerfile Multi-Stage
+
+El template incluye un Dockerfile multi-stage:
+
+```dockerfile
+# Build stage
+FROM oven/bun:1.3 AS builder
+WORKDIR /app
+COPY package.json bun.lock ./
+COPY core/package.json core/
+RUN bun install --frozen-lockfile
+COPY core/src core/src
+
+# Production stage
+FROM oven/bun:1.3 AS production
+WORKDIR /app
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/core/node_modules ./core/node_modules
+COPY --from=builder /app/core/src ./core/src
+RUN mkdir -p /app/core/tmp /app/core/logs
+ENV TG_ENV=production
+ENV NODE_ENV=production
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+  CMD bun run cli status || exit 1
+EXPOSE 3000
+CMD ["bun", "run", "start"]
+```
+
+### Docker Compose
+
+```yaml
+version: '3.8'
+
+services:
+  bot-local:
+    build: .
+    container_name: mks-bot-local
+    environment:
+      - TG_ENV=local
+    env_file:
+      - core/.env.local
+    volumes:
+      - ./core/src:/app/core/src:ro
+      - ./core/logs:/app/core/logs
+    command: bun run --watch src/index.ts
+
+  bot-staging:
+    build: .
+    container_name: mks-bot-staging
+    environment:
+      - TG_ENV=staging
+    env_file:
+      - core/.env.staging
+    ports:
+      - "3001:3000"
+
+  bot-production:
+    build: .
+    container_name: mks-bot-prod
+    environment:
+      - TG_ENV=production
+    env_file:
+      - core/.env.production
+    ports:
+      - "3000:3000"
+    restart: unless-stopped
+```
+
+### Build y Run
+
+```bash
+# Build imagen
+docker build -t mks-telegram-bot .
+
+# Run con docker-compose
+docker-compose up bot-production
+
+# Ver logs
+docker-compose logs -f bot-production
+
+# Ver healthcheck
+docker inspect mks-bot-prod | jq '.[0].State.Health'
+```
+
+---
+
+## ngrok Integration
+
+### ngrock para Testing Local
+
+El comando `ngrok` tiene soporte multi-entorno:
+
+```bash
+# Development con ngrok (local environment)
+bun run ngrok --environment local --start-bot
+
+# Staging con ngrok (test bot)
+bun run ngrok --environment staging --webhook-url
+
+# Force start aunque haya conflicto
+bun run ngrok --environment production --force
+```
+
+### Opciones Disponibles
+
+| Opción | Default | Descripción |
+| ------ | ------- | ----------- |
+| `-p, --port <port>` | `3000` | Puerto a forward |
+| `-e, --environment <env>` | `local` | Entorno: local/staging/production |
+| `-w, --webhook-url` | `false` | Auto-update webhook URL en .env |
+| `-s, --start-bot` | `false` | Auto-start bot después de ngrok |
+| `-f, --force` | `false` | Force start aún si hay conflicto |
+
+### Flujo con --environment
+
+1. Carga el archivo `.env.{environment}` correspondiente
+2. Detecta conflictos con instancias existentes
+3. Inicia ngrok tunnel
+4. Opcionalmente actualiza `TG_WEBHOOK_URL` en el .env
+5. Opcionalmente inicia el bot con `TG_ENV` configurado
+
+---
+
+## VPS Deployment
+
+### Preparar VPS
+
+1. **Instalar dependencias**:
+   ```bash
+   curl -fsSL https://bun.sh/install | bash
+   ```
+
+2. **Clonar repositorio**:
+   ```bash
+   git clone <repo-url>
+   cd mks-telegram-bot
+   bun install
+   ```
+
+3. **Configurar entorno**:
+   ```bash
+   cp core/.env.example core/.env.production
+   nano core/.env.production
+   ```
+
+4. **Crear servicio systemd** (opcional):
+   ```ini
+   [Unit]
+   Description=mks-telegram-bot
+   After=network.target
+
+   [Service]
+   Type=simple
+   User=botuser
+   WorkingDirectory=/app/mks-telegram-bot
+   Environment="TG_ENV=production"
+   ExecStart=/usr/local/bin/bun run start
+   Restart=always
+
+   [Install]
+   WantedBy=multi-user.target
+   ```
+
+### Deployment con Docker (Recomendado)
+
+```bash
+# Build y taggear imagen
+docker build -t mks-telegram-bot:latest .
+docker tag mks-telegram-bot:latest registry.example.com/mks-bot:latest
+
+# Push a registry (opcional)
+docker push registry.example.com/mks-bot:latest
+
+# En VPS
+docker pull registry.example.com/mks-bot:latest
+docker run -d \
+  --name mks-bot-prod \
+  --restart unless-stopped \
+  -p 3000:3000 \
+  --env-file core/.env.production \
+  registry.example.com/mks-bot:latest
+```
+
+---
+
+## Troubleshooting Deployment
+
+### Bot Doesn't Respond
+
+1. Check `TG_BOT_TOKEN` is valid
+2. Verify bot is running (`bun run status`)
+3. Check `TG_AUTHORIZED_USER_IDS` for control commands
+
+### Webhook Not Working
+
+1. Verify `TG_WEBHOOK_URL` is HTTPS and publicly accessible
+2. Check `TG_WEBHOOK_SECRET` matches (min 16 chars)
+3. Verify firewall allows incoming connections
+
+### Instance Conflict
+
+**Error**: `INSTANCE_CONFLICT - Another instance is already running`
+
+**Solutions**:
+1. Stop the existing instance: `bun run cli kill <instance_name>`
+2. Use a different instance name in your `.env` file
+3. Disable instance check: `TG_INSTANCE_CHECK=false` (not recommended)
+4. Remove stale lock files: `rm -f core/tmp/*.lock core/tmp/*.pid`
+
+### Docker Issues
+
+```bash
+# Ver logs del container
+docker logs mks-bot-prod
+
+# Entrar al container
+docker exec -it mks-bot-prod /bin/sh
+
+# Ver healthcheck
+docker inspect mks-bot-prod | jq '.[0].State.Health'
+```
+
+### ngrok Tunnel Not Working
+
+1. Verify ngrok is installed: `ngrok version`
+2. Check ngrok is not already running on port 4040
+3. Use `--force` flag if conflict detected
+4. Check port is available: `lsof -i :3000`
+
+---
+
+## Environment Variables Reference
+
+### Variables de Entorno
+
+| Variable | Default | Descripción |
+| -------- | ------- | ----------- |
+| `TG_ENV` | `local` | Environment: local/staging/production |
+| `TG_BOT_TOKEN` | required | Bot token from @BotFather |
+| `TG_MODE` | `polling` | `polling` or `webhook` |
+| `TG_WEBHOOK_URL` | - | Public HTTPS webhook URL |
+| `TG_WEBHOOK_SECRET` | - | Secret token for validation |
+| `TG_INSTANCE_NAME` | `mks-bot` | Unique instance name for locking |
+| `TG_INSTANCE_CHECK` | `true` | Enable instance conflict detection |
+| `LOG_LEVEL` | `info` | Log verbosity |
+| `TG_DEBUG` | `false` | Enable debug mode |
+
+---
+
+## Ver También
+
+- [CLAUDE.md](./CLAUDE.md) - Entry point principal
+- [CLAUDE.dev.md](./CLAUDE.dev.md) - Desarrollo y patterns
+- [README.md](./README.md) - Quick start del proyecto

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

@@ -0,0 +1,266 @@
+# CLAUDE.dev - Guía de Desarrollo
+
+> **Parte de**: [CLAUDE.md](./CLAUDE.md) | Ver también: [CLAUDE.deploy.md](./CLAUDE.deploy.md)
+
+Guía de desarrollo para extender y modificar el bot template.
+
+**Documentación relacionada**:
+- [docs/development/setup.mdx](./docs/development/setup.mdx)
+- [docs/development/patterns.mdx](./docs/development/patterns.mdx)
+
+---
+
+## Development Standards
+
+### Code Style
+
+- TypeScript strict mode enabled
+- `noUncheckedIndexedAccess: true` - arrays need undefined checks
+- Semi: false, singleQuote: true
+- Result type pattern para error handling
+- Better Logger para logging (no console.*)
+
+### Before Commit Checklist
+
+- [ ] `bun run typecheck` → 0 errores
+- [ ] `bun run lint` → 0 warnings, 0 errors
+- [ ] `bun test` → all tests pass
+- [ ] No `console.*` statements
+- [ ] Código formateado (`bun run format:check`)
+
+---
+
+## Agregando Commands
+
+### 1. Crear Handler
+
+**Archivo**: `core/src/handlers/mycommand.ts`
+
+```typescript
+import type { Context } from 'telegraf'
+
+export async function handleMyCommand(ctx: Context): Promise<void> {
+  await ctx.reply('Respuesta del comando')
+}
+```
+
+### 2. Registrar en Bot
+
+**Archivo**: `core/src/index.ts`
+
+```typescript
+import { handleMyCommand } from './handlers/mycommand.js'
+bot.command('mycommand', handleMyCommand)
+```
+
+---
+
+## Agregando Middleware
+
+### 1. Crear Middleware
+
+**Archivo**: `core/src/middleware/custom.ts`
+
+```typescript
+import type { Context, Middleware } from 'telegraf'
+
+export function customMiddleware(): Middleware<Context> {
+  return async (ctx, next) => {
+    // Pre-processing
+    await next()
+    // Post-processing
+  }
+}
+```
+
+### 2. Registrar Middleware
+
+**Archivo**: `core/src/index.ts`
+
+```typescript
+import { customMiddleware } from './middleware/custom.js'
+bot.use(customMiddleware())
+```
+
+---
+
+## Patterns
+
+### Result Type Pattern
+
+Railway-oriented programming para error handling sin excepciones:
+
+```typescript
+import { ok, err, type Result, botError } from './types/result.js'
+
+function divide(a: number, b: number): Result<number> {
+  if (b === 0) {
+    return err(botError('INVALID_ARGS', 'Cannot divide by zero'))
+  }
+  return ok(a / b)
+}
+
+const result = divide(10, 2)
+if (result.ok) {
+  console.log(result.value) // 5
+} else {
+  console.error(result.error.message)
+}
+```
+
+**Utilities disponibles**: `ok`, `err`, `isOk`, `isErr`, `unwrap`, `unwrapOr`, `map`, `mapErr`, `flatMap`, `tap`, `tapErr`, `match`, `collect`, `all`
+
+### Singleton Pattern
+
+- `BotManager` - Lifecycle y stats
+- `LogStreamer` - Buffer de logs
+- `InstanceManager` - Lock management
+- `Config` - Cached configuration
+
+---
+
+## Logging System
+
+### Usar Better Logger
+
+```typescript
+import { botLogger, kv, badge, colorText, colors } from './middleware/logging.js'
+
+botLogger.info('Información')
+botLogger.success('Operación exitosa')
+botLogger.warn('Advertencia')
+botLogger.error('Error', error)
+```
+
+### Crear Logger Especializado
+
+```typescript
+import { component } from '@mks2508/better-logger'
+
+const myLogger = component('MyModule')
+myLogger.info('Módulo iniciado')
+```
+
+### Formatting Avanzado
+
+```typescript
+// Key-Value formatting
+botLogger.info(kv({ user: '123', action: 'start' }))
+
+// Badge
+botLogger.info(badge('CMD', 'rounded'))
+
+// Colored text
+botLogger.success(colorText('Success', colors.success))
+
+// Duration
+const { formatDuration } = await import('./middleware/logging.js')
+botLogger.info(formatDuration(1234)) // "1.2s"
+```
+
+---
+
+## Testing
+
+### Escribiendo Tests
+
+Usa `bun test` con sintaxis similar a Jest:
+
+```typescript
+import { describe, test, expect } from 'bun:test'
+
+describe('Mi Módulo', () => {
+  test('debe hacer algo', () => {
+    const result = miFuncion()
+    expect(result).toBe('expected')
+  })
+})
+```
+
+### Archivos de Test
+
+- **Nombre**: `*.test.ts` o `*.spec.ts`
+- **Ubicación**: Junto al archivo que testean
+- **Ejemplo**: `core/src/types/result.test.ts`
+
+### Ejecutar Tests
+
+```bash
+bun test              # Ejecutar todos
+bun test --verbose    # Output detallado
+bun test --watch      # Watch mode
+bun test path/to/test.ts  # Test específico
+```
+
+---
+
+## Environment Variables (Desarrollo)
+
+### Archivo: `core/.env.example`
+
+Variables requeridas para desarrollo:
+
+| Variable | Descripción |
+| -------- | ----------- |
+| `TG_BOT_TOKEN` | Token from @BotFather |
+| `TG_MODE` | `polling` o `webhook` |
+| `LOG_LEVEL` | `debug`, `info`, `warn`, `error` |
+| `TG_DEBUG` | Habilitar debug mode |
+| `TG_INSTANCE_CHECK` | Habilitar detección de instancias |
+
+---
+
+## Troubleshooting Development
+
+### Typecheck Errors
+
+```bash
+# Ejecutar typecheck detallado
+tsgo --traceback
+```
+
+### Tests Fallan
+
+```bash
+# Ejecutar tests con output detallado
+bun test --verbose
+
+# Ejecutar solo un archivo de test
+bun test core/src/types/result.test.ts
+```
+
+### Bot No Responde
+
+1. Verificar `TG_BOT_TOKEN` es válido
+2. Chequear `/health` command
+3. Verificar `TG_AUTHORIZED_USER_IDS` para control commands
+
+---
+
+## Quick Reference
+
+### Comandos de Desarrollo
+
+```bash
+bun run dev           # Watch mode
+bun run typecheck     # Type check
+bun run lint          # Lint check
+bun run format        # Format code
+bun test              # Run tests
+```
+
+### Archivos Clave para Desarrollo
+
+- `core/src/index.ts` - Entry point, command registration
+- `core/src/handlers/` - Command handlers
+- `core/src/middleware/` - Telegraf middleware
+- `core/src/config/` - Configuration and env validation
+- `packages/utils/src/` - Shared utilities
+
+---
+
+## Ver También
+
+- [CLAUDE.md](./CLAUDE.md) - Entry point principal
+- [CLAUDE.deploy.md](./CLAUDE.deploy.md) - Deployment y entornos
+- [README.md](./README.md) - Quick start del proyecto