create-bunspace 0.1.0

package/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

package/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/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"]