entexto-cli 1.4.9 → 2.0.1

package/bin/entexto.js

@@ -85,6 +85,45 @@ program
     require('../lib/commands/tunnel')({ target: target || '3000' });
   });
 
+// ─── entexto create ──────────────────────────────────────────
+program
+  .command('create')
+  .description('Crear un nuevo proyecto (interactivo o con opciones)')
+  .option('-n, --name <name>',      'Nombre del proyecto')
+  .option('-t, --template <type>',  'Plantilla: blank | basic | react | fullstack | local')
+  .option('-d, --dir <path>',       'Carpeta a subir (con template=local)', '.')
+  .action(require('../lib/commands/create'));
+
+// ─── entexto domain ──────────────────────────────────────────
+program
+  .command('domain [action] [value]')
+  .description('Gestionar dominios: list | add | subdomain | verify')
+  .option('-p, --project <id>', 'ID del proyecto a vincular')
+  .action(require('../lib/commands/domain'));
+
+// ─── entexto publish ─────────────────────────────────────────
+program
+  .command('publish')
+  .description('Publicar un proyecto rápidamente')
+  .option('-i, --id <uuid>', 'UUID del proyecto a publicar')
+  .action((options) => {
+    require('../lib/commands/publish')({ uuid: options.id });
+  });
+
+// ─── entexto api ──────────────────────────────────────────────
+program
+  .command('api [action] [slug]')
+  .description('API Platform: list | create | info | collection | insert | query')
+  .option('-n, --name <name>',         'Nombre')
+  .option('-D, --description <desc>',  'Descripción')
+  .action(require('../lib/commands/api-platform'));
+
+// ─── entexto live ─────────────────────────────────────────────
+program
+  .command('live')
+  .description('Guía del Live SDK (WebRTC, videollamadas, tiempo real)')
+  .action(require('../lib/commands/live'));
+
 program.parse(process.argv);
 
 if (!process.argv.slice(2).length) {

package/docs/fullappdeploy.md

@@ -0,0 +1,657 @@
+# fullappdeploy.md — Guía Completa para Desplegar Apps con EntExto CLI
+
+> **Versión**: 2.0.0  
+> **Para**: IAs y desarrolladores que necesiten crear, configurar y desplegar una aplicación completa desde la terminal.
+
+---
+
+## 1. Instalación
+
+```bash
+npm install -g entexto-cli
+```
+
+Verifica la instalación:
+```bash
+entexto --version
+```
+
+---
+
+## 2. Autenticación
+
+```bash
+entexto login
+```
+
+Ingresa tu email y contraseña de entexto.com. El token se guarda en `~/.entexto/config.json`.
+
+**Verificar sesión:**
+```bash
+entexto whoami
+```
+
+**Cerrar sesión:**
+```bash
+entexto logout
+```
+
+---
+
+## 3. Crear un Proyecto
+
+### Modo interactivo
+```bash
+entexto create
+```
+
+El CLI te guía paso a paso:
+1. Nombre del proyecto
+2. Descripción
+3. Plantilla (blank, basic, react, fullstack, local)
+4. ¿Publicar ahora?
+5. ¿Vincular dominio/subdominio?
+
+### Con opciones directas
+```bash
+entexto create --name "Mi App" --template react
+entexto create --name "Backend" --template fullstack
+entexto create --name "Desde carpeta" --template local --dir ./mi-proyecto
+```
+
+### Plantillas disponibles
+
+| Plantilla   | Descripción |
+|-------------|-------------|
+| `blank`     | Proyecto vacío con index.html mínimo |
+| `basic`     | HTML + CSS + JS con estructura base |
+| `react`     | React con CDN (Babel + ReactDOM) listo para JSX |
+| `fullstack` | React + VFS (sistema de archivos virtual) + Live SDK preconfigurado |
+| `local`     | Sube una carpeta existente de tu disco como proyecto |
+
+---
+
+## 4. Desplegar Archivos
+
+### Deploy básico
+```bash
+entexto deploy --id <uuid> --dir ./mi-proyecto
+```
+
+### Deploy con publicación automática
+```bash
+entexto deploy --id <uuid> --dir ./mi-proyecto --publish
+```
+
+### Deploy con watch (live reload)
+```bash
+entexto deploy --id <uuid> --dir ./mi-proyecto --watch
+```
+
+### Deploy completo (sin delta)
+```bash
+entexto deploy --id <uuid> --dir ./mi-proyecto --full
+```
+
+> **Nota**: El deploy usa delta por defecto — solo sube archivos que cambiaron (basado en SHA256).
+
+---
+
+## 5. Publicar un Proyecto
+
+```bash
+entexto publish --id <uuid>
+```
+
+O selecciona de la lista interactiva:
+```bash
+entexto publish
+```
+
+Una vez publicado, el proyecto es accesible en: `https://entexto.com/p/<uuid>`
+
+---
+
+## 6. Gestión de Dominios
+
+### Listar dominios configurados
+```bash
+entexto domain list
+```
+
+### Agregar un dominio propio
+```bash
+entexto domain add midominio.com --project <id>
+```
+
+El CLI mostrará las instrucciones DNS:
+- **Opción A**: Registro A apuntando al IP del servidor
+- **Opción B**: CNAME apuntando a `entexto.com`
+- **Opción C**: CNAME apuntando al tunnel de Cloudflare
+
+### Crear un subdominio de un dominio verificado
+```bash
+entexto domain subdomain --project <id>
+```
+
+Selecciona el dominio padre y escribe el subdominio deseado (ej: `app` → `app.midominio.com`).
+
+### Verificar un dominio
+```bash
+entexto domain verify midominio.com
+```
+
+Métodos de verificación soportados:
+1. Registro A directo
+2. CNAME a cfargotunnel.com
+3. CNAME a entexto.com
+4. NS delegation (ns1/ns2.entexto.com)
+5. HTTP ping fallback
+
+---
+
+## 7. API Platform (BaaS)
+
+EntExto incluye un Backend-as-a-Service completo. Gestiona APIs REST desde la terminal.
+
+### Crear una API
+```bash
+entexto api create
+```
+
+Responde: nombre y descripción. Recibirás:
+- **Slug** para las URLs
+- **API Key** para autenticarte
+- **Base URL**: `https://api.entexto.com/v1/api/<slug>`
+
+### Listar tus APIs
+```bash
+entexto api list
+```
+
+### Ver detalle de una API
+```bash
+entexto api info <slug>
+```
+
+### Crear una colección
+```bash
+entexto api collection <slug>
+```
+
+### Insertar un documento
+```bash
+entexto api insert <slug>
+```
+
+Se abre un editor para escribir el JSON del documento.
+
+### Consultar documentos
+```bash
+entexto api query <slug>
+```
+
+### Usar la API desde código
+
+```javascript
+// Autenticación con API Key
+const resp = await fetch('https://api.entexto.com/v1/api/projects/mi-api/data/usuarios', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-API-Key': 'tu-api-key'
+  },
+  body: JSON.stringify({
+    data: { nombre: 'Juan', email: 'juan@test.com' }
+  })
+});
+
+// O con JWT
+const login = await fetch('https://api.entexto.com/v1/api/auth/login', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ email: 'tu@email.com', password: 'tu-password' })
+});
+const { token } = await login.json();
+
+const docs = await fetch('https://api.entexto.com/v1/api/projects/mi-api/data/usuarios', {
+  headers: { 'Authorization': `Bearer ${token}` }
+});
+```
+
+---
+
+## 8. Live SDK (Tiempo Real + WebRTC)
+
+### ¿Qué es?
+El Live SDK permite agregar comunicación en tiempo real a cualquier proyecto: chat, videollamadas, audio, pantalla compartida, y eventos.
+
+### Ver la guía completa
+```bash
+entexto live
+```
+
+### Uso rápido en un proyecto publicado
+
+```html
+<!-- El SDK se inyecta automáticamente en proyectos publicados -->
+<script>
+  // Crear/unirse a una sala
+  const sala = window.__entexto.live.sala('mi-sala', {
+    usuario: 'Pedro'
+  });
+
+  // Escuchar eventos
+  sala.escuchar('mensaje', (data, remitente) => {
+    console.log(remitente, 'dice:', data);
+  });
+
+  // Enviar a todos
+  sala.emitir('mensaje', { texto: 'Hola a todos' });
+
+  // Presencia
+  sala.onEntra((usuario, socketId) => {
+    console.log(usuario, 'entró');
+  });
+
+  sala.onSale((usuario, socketId) => {
+    console.log(usuario, 'salió');
+  });
+</script>
+```
+
+### Métodos disponibles
+
+| Método | Descripción |
+|--------|-------------|
+| `sala.escuchar(evento, callback)` | Escuchar un evento de la sala |
+| `sala.emitir(evento, data)` | Enviar a todos en la sala |
+| `sala.emitirA(socketId, evento, data)` | Enviar a un usuario específico |
+| `sala.onRelay(callback)` | Recibir señalización WebRTC |
+| `sala.onEntra(callback)` | Evento: usuario entró |
+| `sala.onSale(callback)` | Evento: usuario salió |
+| `sala.salir()` | Salir de la sala |
+
+### Videollamadas WebRTC
+
+```javascript
+// 1. Obtener media local
+const stream = await navigator.mediaDevices.getUserMedia({
+  video: true,
+  audio: true
+});
+
+// 2. Obtener config TURN (automático en EntExto)
+const resp = await fetch('/api/turn-config');
+const { iceServers } = await resp.json();
+
+// 3. Crear conexión WebRTC
+const pc = new RTCPeerConnection({ iceServers });
+
+// 4. Agregar tracks
+stream.getTracks().forEach(track => pc.addTrack(track, stream));
+
+// 5. Negociar via Live SDK
+pc.onicecandidate = (e) => {
+  if (e.candidate) sala.emitir('relay', { target: peerId, candidate: e.candidate });
+};
+
+pc.createOffer().then(offer => {
+  pc.setLocalDescription(offer);
+  sala.emitir('relay', { target: peerId, sdp: offer });
+});
+
+sala.onRelay((data, fromId) => {
+  if (data.sdp) {
+    pc.setRemoteDescription(data.sdp);
+    if (data.sdp.type === 'offer') {
+      pc.createAnswer().then(answer => {
+        pc.setLocalDescription(answer);
+        sala.emitir('relay', { target: fromId, sdp: answer });
+      });
+    }
+  }
+  if (data.candidate) pc.addIceCandidate(data.candidate);
+});
+```
+
+### ICE Servers
+- **STUN**: `stun:entexto.com:3478`
+- **TURN**: Credenciales automáticas desde `/api/turn-config` (HMAC-SHA1, TTL 24h)
+
+---
+
+## 9. Flujo Completo Automatizado (para IAs)
+
+Este es el flujo exacto que una IA debe seguir para crear una app completa:
+
+```bash
+# Paso 1: Login
+entexto login
+# → Ingresar email y password
+
+# Paso 2: Crear proyecto
+entexto create --name "Mi App Completa" --template fullstack
+# → Anota el UUID del proyecto creado
+
+# Paso 3: Desarrollar localmente
+# Crear archivos en una carpeta local:
+mkdir mi-app && cd mi-app
+
+# index.html - página principal
+# app.js - lógica de la aplicación  
+# styles.css - estilos
+
+# Paso 4: Deploy
+entexto deploy --id <uuid> --dir . --publish
+
+# Paso 5: Configurar dominio (opcional)
+entexto domain add miapp.com --project <project_id>
+# O crear subdominio:
+entexto domain subdomain
+
+# Paso 6: Crear API backend (opcional)
+entexto api create
+# → Nombre: "mi-app-api"
+# → Anota el slug y API Key
+
+# Paso 7: Crear colecciones de datos
+entexto api collection mi-app-api
+# → Nombre: "usuarios"
+
+entexto api collection mi-app-api
+# → Nombre: "datos"
+
+# Paso 8: Insertar datos iniciales
+entexto api insert mi-app-api
+# → Seleccionar colección → Escribir JSON
+
+# Paso 9: Agregar Live SDK al proyecto (si necesita tiempo real)
+# En index.html agregar:
+# <script src="/_entexto/live.js"></script>
+# Usar sala.escuchar/emitir para comunicación
+
+# Paso 10: Re-deploy con cambios finales
+entexto deploy --id <uuid> --dir . --publish
+```
+
+### Ejemplo: App de Chat en Tiempo Real
+
+```bash
+# Login
+entexto login
+
+# Crear proyecto
+entexto create --name "Chat App" --template basic
+
+# Crear carpeta local
+mkdir chat-app && cd chat-app
+```
+
+Crear `index.html`:
+```html
+<!DOCTYPE html>
+<html lang="es">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Chat App</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: system-ui; background: #1a1a2e; color: #eee; display: flex; flex-direction: column; height: 100vh; }
+    #chat { flex: 1; overflow-y: auto; padding: 20px; }
+    .msg { margin: 8px 0; padding: 10px 15px; background: #16213e; border-radius: 10px; max-width: 80%; }
+    .msg .user { color: #e94560; font-weight: bold; font-size: 0.85em; }
+    #form { display: flex; padding: 15px; background: #0f3460; }
+    #form input { flex: 1; padding: 12px; border: none; border-radius: 8px; background: #1a1a2e; color: #eee; font-size: 1em; }
+    #form button { padding: 12px 24px; margin-left: 10px; border: none; border-radius: 8px; background: #e94560; color: #fff; cursor: pointer; font-weight: bold; }
+  </style>
+</head>
+<body>
+  <div id="chat"></div>
+  <form id="form">
+    <input id="msg" placeholder="Escribe un mensaje..." autocomplete="off">
+    <button type="submit">Enviar</button>
+  </form>
+  <script>
+    const usuario = prompt('Tu nombre:') || 'Anónimo';
+    const sala = window.__entexto.live.sala('chat-general', { usuario });
+    const chat = document.getElementById('chat');
+
+    function addMsg(user, text) {
+      const div = document.createElement('div');
+      div.className = 'msg';
+      div.innerHTML = '<span class="user">' + user + '</span><br>' + text;
+      chat.appendChild(div);
+      chat.scrollTop = chat.scrollHeight;
+    }
+
+    sala.escuchar('mensaje', (data, remitente) => {
+      addMsg(remitente.usuario || '?', data.texto);
+    });
+
+    sala.onEntra((u) => addMsg('Sistema', u + ' se unió al chat'));
+    sala.onSale((u) => addMsg('Sistema', u + ' salió del chat'));
+
+    document.getElementById('form').addEventListener('submit', (e) => {
+      e.preventDefault();
+      const input = document.getElementById('msg');
+      const texto = input.value.trim();
+      if (!texto) return;
+      sala.emitir('mensaje', { texto });
+      addMsg(usuario, texto);
+      input.value = '';
+    });
+  </script>
+</body>
+</html>
+```
+
+```bash
+# Deploy y publicar
+entexto deploy --id <uuid> --dir . --publish
+
+# Listo! Chat funcionando en https://entexto.com/p/<uuid>
+```
+
+### Ejemplo: App con API + Base de Datos
+
+```bash
+# Crear API
+entexto api create
+# Nombre: "tienda-api"
+
+# Crear colecciones
+entexto api collection tienda-api
+# → "productos"
+
+entexto api collection tienda-api
+# → "pedidos"
+
+# Insertar productos
+entexto api insert tienda-api
+# Colección: productos
+# { "nombre": "Laptop", "precio": 999, "stock": 10 }
+```
+
+Usar desde el frontend:
+```javascript
+const API_BASE = 'https://api.entexto.com/v1/api/projects/tienda-api';
+const API_KEY = 'tu-api-key';
+
+// Listar productos
+const res = await fetch(`${API_BASE}/data/productos`, {
+  headers: { 'X-API-Key': API_KEY }
+});
+const { documents } = await res.json();
+
+// Crear pedido
+await fetch(`${API_BASE}/data/pedidos`, {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-API-Key': API_KEY
+  },
+  body: JSON.stringify({
+    data: { producto_id: '...', cantidad: 1, total: 999 }
+  })
+});
+```
+
+---
+
+## 10. Otros Comandos Útiles
+
+### Listar proyectos
+```bash
+entexto projects
+```
+
+### Descargar un proyecto
+```bash
+entexto pull --id <uuid> --dir ./descarga
+entexto clone --id <uuid>
+```
+
+### Sincronización bidireccional (live)
+```bash
+entexto sync --id <uuid> --dir .
+```
+
+### Exponer servidor local
+```bash
+entexto tunnel 3000
+```
+Tu servidor local en `localhost:3000` será accesible públicamente.
+
+---
+
+## 11. Estructura de Archivos de un Proyecto Típico
+
+```
+mi-proyecto/
+├── index.html          # Página principal (requerido)
+├── app.js              # Lógica principal
+├── styles.css          # Estilos
+├── assets/             # Imágenes, fuentes, etc.
+│   ├── logo.png
+│   └── favicon.ico
+└── server/             # Carpeta privada (no se sirve públicamente)
+    ├── game-logic.js   # Lógica del servidor
+    └── hooks.js        # Hooks de eventos
+```
+
+> **Nota**: La carpeta `server/` es privada — los archivos dentro no son accesibles desde el navegador pero sí desde la lógica del servidor (VFS).
+
+---
+
+## 12. Sistema de Archivos Virtual (VFS)
+
+Los proyectos publicados tienen acceso al VFS para leer/escribir archivos desde JavaScript:
+
+```javascript
+// Leer archivo
+const resp = await fetch('/_entexto/api/fs/leer', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ ruta: 'datos/config.json' })
+});
+const { contenido } = await resp.json();
+
+// Escribir archivo
+await fetch('/_entexto/api/fs/escribir', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ ruta: 'datos/config.json', contenido: '{"key":"value"}' })
+});
+
+// Listar archivos
+const list = await fetch('/_entexto/api/fs/listar', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ ruta: '.' })
+});
+
+// Eliminar archivo
+await fetch('/_entexto/api/fs/eliminar', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ ruta: 'datos/temp.txt' })
+});
+
+// Verificar si existe
+const exists = await fetch('/_entexto/api/fs/existe', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ ruta: 'datos/config.json' })
+});
+```
+
+---
+
+## 13. Seguridad
+
+### Autenticación
+- **CLI**: JWT almacenado localmente en `~/.entexto/config.json`
+- **API Platform**: API Key (header `X-API-Key`) o JWT
+- **Dominios**: Verificación DNS obligatoria antes de servir contenido
+
+### Buenas prácticas
+- Nunca expongas tu API Key en código del frontend público
+- Usa JWT para operaciones sensibles
+- La carpeta `server/` es privada y no se sirve al público
+- Los tokens de TURN tienen TTL de 24 horas
+- Las credenciales TURN usan HMAC-SHA1
+
+### Endpoints protegidos
+Todos los endpoints de CLI, proyectos, y dominios requieren autenticación JWT. El middleware verifica:
+1. Header `Authorization: Bearer <token>`
+2. Token válido y no expirado
+3. Usuario activo en la base de datos
+
+---
+
+## 14. Referencia Rápida de Comandos
+
+| Comando | Descripción |
+|---------|-------------|
+| `entexto login` | Iniciar sesión |
+| `entexto logout` | Cerrar sesión |
+| `entexto whoami` | Ver usuario actual |
+| `entexto create` | Crear nuevo proyecto |
+| `entexto projects` | Listar proyectos |
+| `entexto deploy` | Subir archivos |
+| `entexto publish` | Publicar proyecto |
+| `entexto pull` | Descargar proyecto |
+| `entexto clone` | Clonar proyecto |
+| `entexto sync` | Sincronización bidireccional |
+| `entexto tunnel` | Exponer servidor local |
+| `entexto domain list` | Ver dominios |
+| `entexto domain add` | Agregar dominio |
+| `entexto domain subdomain` | Crear subdominio |
+| `entexto domain verify` | Verificar DNS |
+| `entexto api list` | Listar APIs |
+| `entexto api create` | Crear nueva API |
+| `entexto api info` | Ver detalle de API |
+| `entexto api collection` | Crear colección |
+| `entexto api insert` | Insertar documento |
+| `entexto api query` | Consultar documentos |
+| `entexto live` | Guía del Live SDK |
+
+---
+
+## 15. Resolución de Problemas
+
+| Problema | Solución |
+|----------|----------|
+| "No has iniciado sesión" | Ejecuta `entexto login` |
+| Deploy falla con timeout | Usa `--full` para forzar subida completa |
+| Dominio no se verifica | Espera propagación DNS (puede tardar hasta 48h) |
+| API Key inválida | Revisa con `entexto api info <slug>` |
+| Live SDK no funciona | Asegúrate de que el proyecto esté publicado |
+| TURN no conecta | Verifica que el servidor TURN esté activo (PM2 id=2) |
+| Archivos no aparecen | Verifica que no estén en carpeta `server/` (privada) |
+
+---
+
+*Generado por entexto-cli v2.0.0 — https://entexto.com*