gufi-cli 0.1.49 → 0.1.51

package/docs/mcp/00-overview.md

@@ -0,0 +1,329 @@
+# Gufi MCP - Overview
+
+> **15 tools** para construir ERPs con Gufi. Simple, eficiente, directo.
+
+## Que es Gufi
+
+**Gufi** es una plataforma para crear ERPs personalizados sin codigo backend:
+- Defines estructura de datos (modules) → Gufi crea tablas PostgreSQL
+- Creas vistas React → Gufi las conecta con los datos
+- Escribes automations JavaScript → Gufi las ejecuta en triggers/cron
+
+**Filosofia**: "Simple · Professional · Elegance"
+
+---
+
+## Los 15 Tools MCP
+
+### Contexto y Info (3)
+
+| Tool | Uso |
+|------|-----|
+| `gufi_context` | **SIEMPRE PRIMERO** - Obtener schema completo |
+| `gufi_whoami` | Ver usuario, entorno, empresas |
+| `gufi_docs` | Leer documentacion (topics: fields, automations, errors...) |
+
+### Schema (1)
+
+| Tool | Uso |
+|------|-----|
+| `gufi_schema_modify` | Crear/editar entities y fields (operaciones atomicas) |
+
+### Automations (5)
+
+| Tool | Uso |
+|------|-----|
+| `gufi_automation_scripts` | Scripts: list, get, create, update, delete |
+| `gufi_automation_script_test` | Testear script manualmente |
+| `gufi_automation_meta` | Triggers: ver/configurar en entidades |
+| `gufi_automation_integrations` | Ver integraciones built-in (Stripe, Nayax, etc.) |
+| `gufi_automation_executions` | Debugging: historial de ejecuciones |
+
+### Datos (1)
+
+| Tool | Uso |
+|------|-----|
+| `gufi_data` | CRUD: list, get, create, update, delete, aggregate |
+
+### Environment (1)
+
+| Tool | Uso |
+|------|-----|
+| `gufi_env` | Variables: list, set, delete |
+
+### Views (3)
+
+| Tool | Uso |
+|------|-----|
+| `gufi_view_pull` | Descargar vista a local para editar |
+| `gufi_view_push` | Subir cambios a draft |
+| `gufi_view_test` | Test en headless browser (errores, screenshot) |
+
+### Packages (1)
+
+| Tool | Uso |
+|------|-----|
+| `gufi_package` | Gestion: list, get, create, delete, add_module, remove_module, publish |
+
+---
+
+## Workflow Tipico
+
+### 1. Obtener contexto (SIEMPRE PRIMERO)
+
+```
+gufi_context({ company_id: '146' })
+```
+
+Devuelve schema completo: modulos, entidades, campos, relaciones, automations.
+
+### 2. Modificar estructura (Schema)
+
+```javascript
+// Crear entidad
+gufi_schema_modify({
+  company_id: '146',
+  operations: [{
+    op: 'add_entity',
+    module: 'ventas',
+    entity: { name: 'facturas', label: 'Facturas', kind: 'table' }
+  }]
+})
+
+// Agregar campo
+gufi_schema_modify({
+  company_id: '146',
+  operations: [{
+    op: 'add_field',
+    entity: 'ventas.facturas',
+    field: { name: 'total', type: 'currency', label: 'Total' }
+  }]
+})
+
+// Preview (dry run)
+gufi_schema_modify({
+  company_id: '146',
+  preview: true,
+  operations: [...]
+})
+```
+
+### 3. Operar datos (CRUD)
+
+```javascript
+// Listar
+gufi_data({ action: 'list', table: 'ventas.facturas', company_id: '146' })
+
+// Crear
+gufi_data({
+  action: 'create',
+  table: 'ventas.facturas',
+  company_id: '146',
+  data: { numero: 'F-001', total: 150.50 }
+})
+
+// Actualizar (IMPORTANTE: incluir __display para select/relation)
+gufi_data({
+  action: 'update',
+  table: 'ventas.facturas',
+  company_id: '146',
+  id: 123,
+  data: {
+    estado: 'pagada',
+    estado__display: 'Pagada'
+  }
+})
+
+// Eliminar
+gufi_data({ action: 'delete', table: 'ventas.facturas', company_id: '146', id: 123 })
+```
+
+### 4. Crear logica (Automations)
+
+```javascript
+// Crear script
+gufi_automation_scripts({
+  action: 'create',
+  company_id: '146',
+  name: 'enviar_factura',
+  code: `
+async function enviar_factura(gufi) {
+  const { row, env } = gufi.context;
+
+  await gufi.integrations.notifications.email({
+    to: row.cliente_email,
+    subject: 'Nueva factura',
+    html: '<p>Adjuntamos su factura.</p>',
+    user: env.EMAIL_USER,
+    pass: env.EMAIL_PASS,
+    from: env.EMAIL_FROM,
+  });
+
+  return { success: true };
+}
+`
+})
+
+// Asignar trigger a entidad
+gufi_automation_meta({
+  entity_id: '123',
+  company_id: '146',
+  automations: [
+    { trigger: 'insert', function_name: 'enviar_factura' }
+  ]
+})
+
+// Debugging
+gufi_automation_executions({ company_id: '146', script_name: 'enviar_factura' })
+```
+
+### 5. Editar vistas (Pull/Push/Test)
+
+```javascript
+// 1. Descargar a ~/gufi-dev/view_13/
+gufi_view_pull({ view_id: 13 })
+
+// 2. Editar archivos localmente con Read/Edit tools
+// ...
+
+// 3. Subir cambios a draft
+gufi_view_push({ view_id: 13, message: 'Fixed chart colors' })
+
+// 4. Testear en headless browser (OBLIGATORIO antes de publicar)
+gufi_view_test({ view_id: 13, company_id: '116' })
+
+// 5. Si todo OK, publicar package
+gufi_package({ action: 'publish', id: '19' })
+```
+
+---
+
+## Entorno: Produccion vs Dev
+
+### Cambiar entorno (forma principal)
+
+El entorno se configura **globalmente** con el CLI:
+
+```bash
+# Ver entorno actual
+gufi whoami
+
+# Cambiar a desarrollo (localhost:3000)
+gufi config:local
+gufi login
+
+# Cambiar a produccion (gogufi.com)
+gufi config:prod
+gufi login
+```
+
+Una vez configurado, **TODAS las herramientas MCP usan ese entorno automaticamente**.
+
+### Override por llamada (requiere login previo)
+
+Si ya tienes login en ambos entornos, puedes hacer override con `env`:
+
+```javascript
+// Usa el entorno configurado (default)
+gufi_context({ company_id: '146' })
+
+// Override a dev (SOLO si ya hiciste gufi config:local && gufi login antes)
+gufi_context({ company_id: '146', env: 'dev' })
+```
+
+**IMPORTANTE**: El parametro `env: 'dev'` **fallará** si no tienes credenciales guardadas para ese entorno. Primero ejecuta:
+```bash
+gufi config:local && gufi login
+```
+
+| Entorno | URL | Base de datos | Cuando usar |
+|---------|-----|---------------|-------------|
+| `prod` (default) | gogufi.com | Cloud SQL Prod | Produccion, datos reales |
+| `dev` / `local` | localhost:3000 | Cloud SQL Dev | Desarrollo, pruebas |
+
+---
+
+## Conceptos Clave
+
+### Nombres de tabla: Logicos vs Fisicos
+
+```javascript
+// CORRECTO - Nombre logico (dataProvider lo resuelve)
+gufi_data({ table: 'ventas.facturas', ... })
+
+// CORRECTO - ID fisico (cuando lo necesites)
+gufi_data({ table: 'm360_t16192', ... })
+```
+
+### Campos __display
+
+Para `select` y `relation`, actualizar AMBOS campos:
+
+```javascript
+gufi_data({
+  action: 'update',
+  data: {
+    estado: 'completado',         // Valor
+    estado__display: 'Completado' // Label visible
+  }
+})
+```
+
+### gufi.query() en automations
+
+**Devuelve rows directamente** (NO destructuring):
+
+```javascript
+// CORRECTO
+const rows = await gufi.query('SELECT * FROM tabla WHERE id = $1', [5]);
+
+// INCORRECTO
+const { rows } = await gufi.query(...); // ERROR!
+```
+
+---
+
+## Referencias Rapidas
+
+### Topics de documentacion (gufi_docs)
+
+| Topic | Contenido |
+|-------|-----------|
+| `overview` | Este archivo |
+| `architecture` | Componentes del sistema |
+| `modules` | Sistema de modulos |
+| `fields` | Tipos de campos y CB builders |
+| `views` | Vistas marketplace |
+| `automations` | Scripts y triggers |
+| `api` | API REST |
+| `packages` | Sistema de packages |
+| `errors` | Errores comunes |
+| `examples` | Ejemplos practicos |
+
+### Operaciones de gufi_schema_modify
+
+| Operacion | Descripcion |
+|-----------|-------------|
+| `add_entity` | Crear entidad |
+| `update_entity` | Modificar entidad |
+| `remove_entity` | Eliminar entidad |
+| `add_field` | Agregar campo |
+| `update_field` | Modificar campo |
+| `remove_field` | Eliminar campo |
+| `add_submodule` | Agregar seccion |
+
+### Acciones de gufi_package
+
+| Accion | Descripcion |
+|--------|-------------|
+| `list` | Listar mis packages |
+| `get` | Ver detalles de package |
+| `create` | Crear package |
+| `delete` | Eliminar package |
+| `add_module` | Agregar modulo |
+| `remove_module` | Quitar modulo |
+| `publish` | Publicar a produccion |
+
+---
+
+**Ultima actualizacion**: 2025-02-04

package/docs/mcp/01-architecture.md

@@ -0,0 +1,226 @@
+# Arquitectura de Gufi
+
+## Componentes principales
+
+### Backend (Express.js) - Puerto 3000
+
+Archivo principal: `backend/server.js`
+
+**Features organizadas en:**
+```
+backend/src/features/
+├── auth/           # Login, refresh, JWT
+├── companies/      # CRUD companies, schema
+├── modules/        # Estructura de datos (JSON -> DDL)
+├── tables/         # CRUD generico de registros
+├── automations/    # Scripts y triggers
+├── views/          # Marketplace views API
+├── marketplace/    # Developer API (packages)
+├── files/          # Upload/download GCS
+├── imports/        # Import wizard (Excel)
+├── exports/        # Export (Excel, PDF)
+├── cli/            # Endpoints para CLI
+├── push/           # Push notifications (FCM)
+├── webhooks/       # Webhooks externos
+└── ...
+```
+
+**Rutas importantes:**
+- `/api/auth/*` - Autenticacion
+- `/api/company/schema` - Schema completo
+- `/api/company/modules` - CRUD modulos
+- `/api/tables/:table/*` - CRUD registros
+- `/api/automation-scripts/*` - Scripts
+- `/api/marketplace/*` - Developer API
+- `/api/cli/*` - CLI endpoints
+
+### Frontend (React + Vite) - Puerto 5173
+
+```
+frontend/src/
+├── sdk/              # SDK centralizado (@/sdk)
+│   ├── hooks/        # useViewData, useFeatureData
+│   ├── components/   # FeatureContainer, KPICard
+│   ├── utils/        # formatNumber, groupBy
+│   └── marketplace/  # processSeedData, etc.
+├── features/
+│   ├── core_views/   # table, dashboard
+│   ├── custom_views/ # Apps custom (delivery, machines)
+│   ├── view_engine/  # ViewGateway, plugins
+│   └── view_templates/ # Templates para crear vistas
+├── pages/            # Paginas principales
+├── shared/           # Componentes compartidos
+└── stores/           # Zustand stores
+```
+
+### WebSocket Server - Puerto 4000
+
+Archivo: `websocket/server.js`
+
+**Funcionalidades:**
+- Realtime updates (PostgreSQL LISTEN/NOTIFY)
+- Code refresh para desarrollo (CLI push)
+- Developer logs (console.log de vistas)
+- Subscriptions por tabla/company
+
+**Formato mensaje:**
+```json
+{
+  "type": "subscribe",
+  "table": "m360_t16192",
+  "company_id": 116
+}
+```
+
+### Worker (pg-boss)
+
+Archivo: `backend/src/core/services/queue/pgBossWorkerV9.js`
+
+**Colas:**
+- `automation` - Ejecuta automations
+- `duplicate-company` - Duplica companies
+- `marketplace-install-package` - Instala packages
+- `geocode-batch` - Geocoding de imports
+
+**Flujo automation:**
+```
+1. Trigger (insert/update/delete) en tabla
+2. PostgreSQL NOTIFY → pg-boss job
+3. Worker ejecuta runAutomation()
+4. Resultado en automation_executions
+```
+
+### Marketplace Server
+
+Archivo: `marketplace/src/features/marketplace/views.controller.js`
+
+**Funcionalidades:**
+- Compilar vistas (esbuild)
+- Validar featureConfig
+- Gestionar versiones
+- Hot reload para desarrollo
+
+## Base de datos
+
+### Schema `core` (compartido)
+
+```sql
+-- Usuarios y auth
+core.users
+core.user_companies
+core.refresh_tokens
+
+-- Estructura
+core.modules
+core.entities
+
+-- Automations
+core.automation_scripts
+core.automation_meta
+core.automation_executions
+
+-- Marketplace
+core.marketplace_packages
+core.marketplace_views
+core.marketplace_view_files
+
+-- Config
+core.company_env_variables
+```
+
+### Schema `company_{id}` (por empresa)
+
+```sql
+-- Tablas de datos (generadas de modules)
+m{moduleId}_t{entityId}
+
+-- Cada tabla tiene:
+-- id SERIAL PRIMARY KEY
+-- created_at TIMESTAMP
+-- ... campos definidos en module JSON
+```
+
+### Schema `pgboss` (job queue)
+
+```sql
+pgboss.job       -- Jobs pendientes
+pgboss.archive   -- Jobs completados
+pgboss.schedule  -- Scheduled jobs
+```
+
+## Multi-tenancy
+
+### Aislamiento
+
+1. JWT contiene `company_id`
+2. Backend hace `SET search_path TO company_{id}, core, public`
+3. Queries se ejecutan en schema correcto automaticamente
+
+### Nombres de tabla
+
+```
+m{moduleId}_t{entityId}
+
+Ejemplos:
+- m360_t16192  (modulo 360, entidad 16192)
+- m308_t4136   (modulo 308, entidad 4136)
+```
+
+Para saber que modulo/entidad:
+```sql
+SELECT m.id as module_id, e.id as entity_id, e.name
+FROM core.modules m, jsonb_array_elements(m.json_definition->'submodules') sub,
+     jsonb_array_elements(sub->'entities') e
+WHERE m.company_id = 116;
+```
+
+## Autenticacion
+
+### JWT Flow
+
+```
+1. POST /api/auth/login { email, password }
+   -> { accessToken, refreshToken }
+
+2. Requests con: Authorization: Bearer {accessToken}
+                 X-Company-ID: {companyId}
+
+3. Token expira -> POST /api/auth/refresh
+   -> { accessToken, refreshToken }
+```
+
+### Permisos (RBAC)
+
+```javascript
+// En entity.permissions:
+{
+  "admin": "*",                    // Todo permitido
+  "manager": ["entity:view", "entity:create", "entity:update"],
+  "viewer": ["entity:view"]
+}
+
+// Permisos posibles:
+// entity:view, entity:create, entity:update, entity:delete
+// entity:import, entity:export
+```
+
+## Comunicacion entre servicios
+
+```
+Frontend <--HTTP--> Backend <--SQL--> PostgreSQL
+    |                  |                  |
+    |<---WebSocket-----|<--NOTIFY---------|
+    |                  |
+    |               Worker <--pg-boss queue
+```
+
+## Puertos por defecto
+
+| Servicio | Puerto | Descripcion |
+|----------|--------|-------------|
+| Backend | 3000 | API principal |
+| Frontend | 5173 | React dev server |
+| WebSocket | 4000 | Realtime |
+| PostgreSQL | 5432 | Base de datos |
+| Redis | 6379 | Cache (opcional) |
+| Marketplace | 3001 | Compilacion vistas |