gufi-cli 0.1.13 → 0.1.16

package/CLAUDE.md

@@ -45,6 +45,105 @@ Ejemplo:
 
 ---
 
+## 💜 Core Database - Relaciones Importantes
+
+### Diagrama de Relaciones
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           SCHEMA: core                                       │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  companies (1)                                                              │
+│  ├── id: 116                                                                │
+│  ├── name: "Fitvending"                                                     │
+│  └── schema: "company_116"                                                  │
+│           │                                                                 │
+│           │ 1:N                                                             │
+│           ▼                                                                 │
+│  modules (N)                        users (N)                               │
+│  ├── id: 308                        ├── id: 16                              │
+│  ├── company_id: 116 ◄──────────    ├── email: "juan@gufi.es"               │
+│  ├── name: "nayax"                  └── platform_role: "admin"              │
+│  └── json_definition: {...}                  │                              │
+│           │                                  │ N:M                          │
+│           │ 1:N                              ▼                              │
+│           ▼                         company_users                           │
+│  entities (N)                       ├── user_id: 16                         │
+│  ├── id: 4136                       ├── company_id: 116                     │
+│  ├── module_id: 308 ◄───────────    └── roles: ["Admin"]                    │
+│  ├── company_id: 116                                                        │
+│  ├── name: "machines"                                                       │
+│  ├── permissions: {"Admin": "*"}    ◄── Permisos por rol                    │
+│  └── automations: [{...}]           ◄── JSONB array de triggers             │
+│           │                                                                 │
+│           │ N:1 (via script_id en automations)                              │
+│           ▼                                                                 │
+│  automation_scripts (N)                                                     │
+│  ├── id: 15                                                                 │
+│  ├── company_id: 116                                                        │
+│  ├── name: "sync_machines"                                                  │
+│  └── code: "async function..."      ◄── El JavaScript                      │
+│           │                                                                 │
+│           │ (sync automático)                                               │
+│           ▼                                                                 │
+│  automation_meta (índice para worker)                                       │
+│  automation_executions (historial)                                          │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        SCHEMA: company_116                                   │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  m308_t4136 (machines)     m308_t4137 (products)    m308_t4140 (sales)     │
+│  ├── id                    ├── id                    ├── id                 │
+│  ├── name                  ├── name                  ├── machine_id (FK)    │
+│  └── ...                   └── ...                   └── ...                │
+│                                                                             │
+│  __audit_log__ (historial de cambios)                                       │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Tablas Core Principales
+
+| Tabla | Descripción | Relaciones |
+|-------|-------------|------------|
+| `companies` | Empresas/tenants | 1 company → N modules, N users |
+| `users` | Usuarios globales | N:M con companies via company_users |
+| `company_users` | Membresía usuario-empresa | Contiene roles[] del usuario en esa company |
+| `modules` | Definición JSON de módulos | 1 module → N entities |
+| `entities` | Metadatos de tablas | Contiene permissions, automations, config |
+| `automation_scripts` | Código JavaScript | 1 script → N entities pueden usarlo |
+| `automation_meta` | Índice para worker | Generado auto desde entities.automations |
+
+### Flujo de Datos
+
+```
+Usuario hace login
+       │
+       ▼
+JWT contiene: { user_id, company_id, roles[], platform_role }
+       │
+       ▼
+Backend: SET search_path TO company_116, core;
+       │
+       ▼
+Queries van automáticamente al schema correcto
+```
+
+### IDs Importantes para CLI
+
+| Quiero trabajar con... | Necesito el ID de... | Cómo obtenerlo |
+|------------------------|---------------------|----------------|
+| Datos de una tabla | entity (tabla física: m308_t4136) | `gufi schema -c 116` |
+| Estructura de módulo | module_id | `gufi modules 116` |
+| Código de automation | script_id | `gufi automations -c 116` |
+| Triggers de una entity | entity_id | `gufi schema -c 116` |
+
+---
+
 ## Estructura de un Módulo (JSON)
 
 Un módulo es un JSON que define **toda la estructura de datos** de una funcionalidad. Gufi lee este JSON y automáticamente:
@@ -245,11 +344,11 @@ Un módulo es un JSON que define **toda la estructura de datos** de una funciona
           ],
           "automations": [
             {
-              "trigger": "on_insert",
+              "trigger": "insert",
               "function_name": "notificar_nuevo_pedido"
             },
             {
-              "trigger": "on_update",
+              "trigger": "update",
               "condition": "estado = 'confirmado'",
               "function_name": "procesar_pedido"
             },
@@ -426,10 +525,10 @@ SELECT * FROM core.automation_meta WHERE company_id = 116;
 
 | Trigger | Cuándo se ejecuta |
 |---------|-------------------|
-| `on_insert` | Al crear un registro |
-| `on_update` | Al modificar un registro |
-| `on_delete` | Al eliminar un registro |
-| `on_click` / `click` | Botón manual en la UI |
+| `insert` | Al crear un registro |
+| `update` | Al modificar un registro |
+| `delete` | Al eliminar un registro |
+| `click` / `click` | Botón manual en la UI |
 | `scheduled` | Cron job (ej: "0 9 * * *") |
 
 ### Formato de entities.automations
@@ -437,13 +536,13 @@ SELECT * FROM core.automation_meta WHERE company_id = 116;
 ```json
 [
   {
-    "trigger": "on_insert",
+    "trigger": "insert",
     "function_name": "procesar_pedido",
     "script_id": 42,
     "enabled": true
   },
   {
-    "trigger": "on_click",
+    "trigger": "click",
     "function_name": "generar_factura",
     "label": "Generar Factura",
     "enabled": true
@@ -456,7 +555,7 @@ SELECT * FROM core.automation_meta WHERE company_id = 116;
 ```javascript
 /**
  * Función: procesar_pedido
- * Trigger: on_update cuando estado = 'confirmado'
+ * Trigger: update cuando estado = 'confirmado'
  *
  * @param {Object} context - Contexto de ejecución
  * @param {Object} api - API para interactuar con el sistema
@@ -472,7 +571,7 @@ async function procesar_pedido(context, api, logger) {
     entity_id,       // ID de la entidad/tabla (ej: 4136)
     table,           // Nombre físico de tabla (ej: "m308_t4136")
     row,             // Registro actual (después del cambio)
-    old_row,         // Registro anterior (solo en on_update)
+    old_row,         // Registro anterior (solo en update)
     input,           // Input del usuario (solo en click)
     env,             // Variables de entorno de la company
     user             // Usuario que disparó el evento
@@ -667,7 +766,13 @@ Cuando descargas una view con `gufi view:pull <id>`, obtienes:
 
 ### 💜 dataSources - Declarar qué Tablas Necesita la Vista
 
-El archivo `core/dataProvider.ts` define qué tablas necesita la vista. El Developer Center lee esto y muestra UI para que el usuario asigne sus tablas.
+El archivo `core/dataProvider.ts` define qué tablas necesita la vista.
+
+**Arquitectura:**
+1. Se declaran en código (`core/dataProvider.ts`)
+2. Se editan con CLI: `gufi pull` → editar → `gufi push`
+3. Developer Center los muestra como **solo lectura**
+4. Al instalar la vista, el sistema mapea nombres lógicos automáticamente
 
 ```typescript
 // core/dataProvider.ts
@@ -734,9 +839,9 @@ export default function MiVista({ gufi }) { ... }
 export default function MiVista({ gufi }) {
   const viewSpec = gufi?.context?.viewSpec || {};
 
-  // Keys de dataSources → nombres de tabla físicos
-  const tareasTable = viewSpec.tareasTable;      // "m360_t16194"
-  const proyectosTable = viewSpec.proyectosTable; // "m360_t16200" o undefined
+  // Keys de dataSources → NOMBRES LÓGICOS (nunca IDs físicos)
+  const tareasTable = viewSpec.tareasTable;      // "tareas.asignaciones"
+  const proyectosTable = viewSpec.proyectosTable; // "tareas.proyectos" o undefined
 
   // Usar para queries
   const res = await gufi.dataProvider.getList({
@@ -1117,7 +1222,7 @@ Las vistas pueden incluir automations que se ejecutan al hacer click.
 // automations/send_notification.js
 /**
  * 💜 Automation: send_notification
- * Trigger: ON_CLICK (desde la vista)
+ * Trigger: CLICK (desde la vista)
  */
 async function send_notification(context, api, logger) {
   const { input, env } = context;
@@ -1594,6 +1699,31 @@ SELECT * FROM marketplace.package_modules WHERE package_id = 14;
 
 ## Comandos del CLI
 
+### 💜 Resumen Rápido para Claude
+
+**El CLI gestiona companies, módulos, automations y datos. Todo es dinámico - detecta la company automáticamente.**
+
+| Quiero... | Comando |
+|-----------|---------|
+| Ver companies | `gufi companies` |
+| Ver módulos de company | `gufi modules 146` |
+| Ver/editar módulo | `gufi module 360` |
+| Ver registros | `gufi rows m308_t4136` |
+| Listar scripts | `gufi automations` |
+| Ver/editar script | `gufi automation 15` |
+| **Ver índice del worker** | `gufi automations:meta` |
+| **Ver ejecuciones** | `gufi automations:executions` |
+| **Ver/editar triggers** | `gufi entity:automations 4136` |
+| **Ver mis packages** | `gufi packages` |
+| **Ver package** | `gufi package 14` |
+| **Crear package** | `gufi package:create "Nombre"` |
+| **Desarrollar view** | `gufi pull 13` → `gufi watch` → `gufi logs` |
+
+**3 cosas que saber:**
+1. **Auto-login**: `gufi login` guarda credenciales → funciona para siempre (logout NO las borra)
+2. **Auto-detección**: `module`, `automation`, `rows` detectan la company automáticamente
+3. **Sin prefijos**: `gufi pull/push/watch/logs` (no `view:pull`, etc.)
+
 ### Instalación
 
 ```bash
@@ -1633,14 +1763,14 @@ gufi companies
 # Ver módulos de una company
 gufi modules 146
 
-# Ver JSON de un módulo
-gufi module 360 -c 146
+# Ver JSON de un módulo (auto-detecta company)
+gufi module 360
 
 # Editar módulo con tu editor
-gufi module 360 -c 146 --edit
+gufi module 360 --edit
 
 # Guardar JSON a archivo
-gufi module 360 -c 146 --file modulo.json
+gufi module 360 --file modulo.json
 
 # Actualizar módulo desde archivo
 gufi module:update 360 modulo.json -c 146
@@ -1669,6 +1799,14 @@ gufi automation calcular_stock -c 116 --file script.js
 
 # Crear/actualizar automation desde archivo JS
 gufi automation:create calcular_stock script.js -c 116
+
+# 💜 Debugging - Ver índice del worker (auto-synced desde entities.automations)
+gufi automations:meta -c 116
+
+# 💜 Ver historial de ejecuciones
+gufi automations:executions -c 116
+gufi automations:executions -c 116 --limit 50
+gufi automations:executions -c 116 --script sync_nayax
 ```
 
 ### Entity Automations (Automations por Entidad)
@@ -1676,29 +1814,29 @@ gufi automation:create calcular_stock script.js -c 116
 Las automations de entidad están vinculadas a una entidad específica (tabla) y se almacenan en `core.entities.automations`.
 
 ```bash
-# Ver automations de una entidad
-gufi entity:automations 4589 -c 116
+# Ver automations de una entidad (auto-detecta company)
+gufi entity:automations 4589
 
 # Editar automations con tu editor ($EDITOR)
-gufi entity:automations 4589 -c 116 --edit
+gufi entity:automations 4589 --edit
 
 # Guardar automations a archivo JSON
-gufi entity:automations 4589 -c 116 --file automations.json
+gufi entity:automations 4589 --file automations.json
 
 # Actualizar automations desde archivo JSON
-gufi entity:automations:update 4589 automations.json -c 116
+gufi entity:automations:update 4589 automations.json
 ```
 
 **Formato del JSON de automations:**
 ```json
 [
   {
-    "trigger": "on_insert",
+    "trigger": "insert",
     "function_name": "notificar_nuevo",
     "enabled": true
   },
   {
-    "trigger": "on_click",
+    "trigger": "click",
     "function_name": "generar_factura",
     "label": "Generar Factura",
     "enabled": true
@@ -1715,10 +1853,10 @@ gufi entity:automations:update 4589 automations.json -c 116
 **Triggers disponibles:**
 | Trigger | Descripción |
 |---------|-------------|
-| `on_insert` | Al crear registro |
-| `on_update` | Al modificar registro |
-| `on_delete` | Al eliminar registro |
-| `on_click` | Botón manual en UI |
+| `insert` | Al crear registro |
+| `update` | Al modificar registro |
+| `delete` | Al eliminar registro |
+| `click` | Botón manual en UI |
 | `scheduled` | Intervalo programado |
 
 ### Environment Variables
@@ -1746,8 +1884,12 @@ gufi schema -m 360
 
 ### Row CRUD (Datos de Tablas)
 
+> 💜 **Auto-detección de Company**: El CLI detecta automáticamente a qué company pertenece una tabla
+> analizando el nombre (ej: `m308_t4136` → módulo 308 → busca en qué company está).
+> Ya no necesitas usar `-c` en la mayoría de casos.
+
 ```bash
-# Listar registros de una tabla
+# Listar registros de una tabla (auto-detecta company)
 gufi rows m360_t16192                    # Últimos 20 registros
 gufi rows m360_t16192 -l 50              # Últimos 50 registros
 gufi rows m360_t16192 -f estado=activo   # Filtrar por campo
@@ -1772,6 +1914,9 @@ gufi row:duplicate m360_t16192 123
 # Crear múltiples registros desde archivo JSON
 gufi rows:create m360_t16192 --file datos.json
 # datos.json debe ser un array: [{"nombre":"A"},{"nombre":"B"}]
+
+# Si necesitas forzar una company específica, usa -c
+gufi rows m360_t16192 -c 146
 ```
 
 ### Desarrollo de Views
@@ -1798,49 +1943,162 @@ gufi view:push
 gufi view:status
 ```
 
+### Packages del Marketplace
+
+```bash
+# Ver mis packages
+gufi packages
+
+# Ver detalles de un package (módulos, views, estado)
+gufi package 14
+
+# Crear nuevo package
+gufi package:create "Mi Package" --description "Descripción opcional"
+
+# Añadir módulo de una company al package
+gufi package:add-module 14 --company 146 --module 360
+# O interactivo (muestra companies disponibles)
+gufi package:add-module 14
+
+# Ver cambios pendientes en módulos
+gufi package:check 14
+
+# Sincronizar versión (actualiza snapshots de módulos)
+gufi package:sync 14
+
+# Publicar package al Marketplace
+gufi package:publish 14
+
+# Despublicar
+gufi package:unpublish 14
+
+# Gestionar views del package
+gufi package:views 14
+gufi package:add-view 14 <viewId>
+gufi package:remove-view 14 <packageViewId>
+
+# Eliminar módulo o package
+gufi package:remove-module 14 <moduleId>
+gufi package:delete 14
+```
+
 ### Opciones Globales
 
 | Opción | Descripción |
 |--------|-------------|
-| `-c, --company <id>` | ID de company |
+| `-c, --company <id>` | ID de company (solo para `modules`, `automations`, `*:create`) |
 | `-e, --edit` | Abrir en editor ($EDITOR) |
 | `-f, --file <path>` | Guardar a archivo |
 | `--dry-run` | Validar sin aplicar |
 | `-h, --help` | Ayuda del comando |
 
+**Auto-detección:** `module`, `module:update`, `automation`, `entity:automations`, `rows` detectan company automáticamente del ID.
+
 ---
 
 ## Tips para Claude
 
+### 💜 Flujo de Trabajo Recomendado
+
+```bash
+# 1. Primero, oriéntate
+gufi companies                    # Ver companies disponibles
+gufi modules 146                  # Ver módulos de una company
+
+# 2. Para ver/modificar datos (auto-detecta company)
+gufi rows m308_t4136              # Auto-detecta company del módulo 308
+gufi row m308_t4136 123           # Ver registro específico
+gufi row:update m308_t4136 123 --data '{"status":"done"}'
+
+# 3. Para editar estructura (módulos - auto-detecta company)
+gufi module 360 --edit            # Abre JSON en tu $EDITOR
+
+# 4. Para editar lógica (automations - auto-detecta company)
+gufi automation 15                # Busca por script_id
+gufi automation 15 --edit         # Editar código JS
+```
+
 ### Cuándo usar cada comando
 
 | El usuario quiere... | Comando |
 |---------------------|---------|
-| Ver qué companies tiene | `gufi companies` |
-| Ver estructura de una company | `gufi modules <company_id>` |
-| Ver/editar JSON de módulo | `gufi module <id> -c <company>` |
-| Ver/editar código de automation script | `gufi automation <nombre> -c <company>` |
-| Ver/editar automations de una entidad | `gufi entity:automations <entity_id> -c <company>` |
-| Desarrollar una vista | `gufi view:pull <id>`, `gufi view:watch`, `gufi view:logs` |
+| Ver companies | `gufi companies` |
+| Ver módulos de company | `gufi modules 146` |
+| Ver/editar módulo | `gufi module 360` |
+| Ver/editar automation | `gufi automation 15` |
+| Ver/editar datos | `gufi rows m308_t4136` |
+| Desarrollar vista | `gufi pull "Mi Vista"` → `gufi watch` → `gufi logs` |
+
+### Auto-detección
+
+Todo automático:
+- `gufi module 360` → detecta company del módulo
+- `gufi automation 15` → detecta company del script
+- `gufi rows m308_t4136` → detecta company de la tabla
+
+### Automations: 4 tablas que trabajan juntas
+
+```
+automation_scripts (id=15)     ← CÓDIGO JavaScript
+         │
+         └── entities.automations  ← CONFIGURACIÓN (qué trigger, cuándo ejecutar)
+                   │
+                   ▼ (sync automático)
+         automation_meta           ← ÍNDICE para worker
+                   │
+                   ▼
+         automation_executions     ← HISTORIAL de ejecuciones
+```
+
+| Tabla | Qué guarda | CLI |
+|-------|------------|-----|
+| `automation_scripts` | Código JS | `gufi automation 15` |
+| `entities.automations` | Triggers (on_insert, on_click...) | `gufi entity:automations 4136` |
+| `automation_meta` | Índice para worker (auto-sync) | `gufi automations:meta` |
+| `automation_executions` | Historial de ejecuciones | `gufi automations:executions` |
+
+**Ejemplo:** Un script puede usarse en varias entities:
+```
+script 15 "sync_nayax" → machines (on_click), products (scheduled), sales (on_insert)
+```
+
+**Flujo típico:**
+```bash
+gufi automations                # Ver scripts
+gufi automation 15 --edit       # Editar código
+gufi entity:automations 4136    # Ver/editar triggers
+gufi automations:meta           # Ver qué tiene el worker indexado (debugging)
+gufi automations:executions     # Ver historial de ejecuciones
+```
 
 ### Errores comunes
 
 | Error | Solución |
 |-------|----------|
 | "No estás logueado" | `gufi login` (guarda credenciales para auto-login) |
-| "Módulo no encontrado" | Verificar `-c <company_id>` |
+| "Módulo no encontrado" | Verificar que el ID existe con `gufi modules <company>` |
 | "Token expirado" | Automático: refresh o auto-login con credenciales guardadas |
 | "JSON inválido" | Validar estructura del JSON |
+| "API Error 404" | Verificar nombre de tabla (formato: `m{moduleId}_t{entityId}`) |
 
 ### Conceptos clave
 
 - **Multi-tenant**: Cada company = schema aislado en PostgreSQL
-- **Tablas físicas**: `m{moduleId}_t{entityId}`
+- **Tablas físicas**: `m{moduleId}_t{entityId}` (ej: `m308_t4136`)
 - **Módulos**: JSON que define estructura → Gufi crea tablas/UI
 - **Automations**: JS en DB, ejecutado por worker (pg-boss)
 - **Views**: React/TS en DB, ejecutado en frontend dinámicamente
 - **Marketplace**: Sistema de distribución de packages
 
+### Companies Importantes
+
+| ID | Nombre | Uso |
+|----|--------|-----|
+| 101 | Demo | Pruebas generales |
+| 116 | Fitvending | Producción - cliente real |
+| 146 | Gufi | Desarrollo interno |
+| 147 | Apuestas Pro | Cliente real |
+
 ---
 
 ## Links

package/dist/commands/companies.d.ts

@@ -22,7 +22,7 @@ export declare function automationsCommand(_moduleId?: string, // Ignored - kept
 options?: {
     company?: string;
 }): Promise<void>;
-export declare function automationCommand(automationName?: string, options?: {
+export declare function automationCommand(automationId?: string, options?: {
     edit?: boolean;
     company?: string;
     file?: string;
@@ -44,3 +44,14 @@ export declare function entityAutomationsCommand(entityId?: string, options?: {
 export declare function entityAutomationsUpdateCommand(entityId?: string, jsonFile?: string, options?: {
     company?: string;
 }): Promise<void>;
+/**
+ * Interactive editor for entity automations
+ */
+export declare function automationsMetaCommand(options?: {
+    company?: string;
+}): Promise<void>;
+export declare function automationsExecutionsCommand(options?: {
+    company?: string;
+    limit?: string;
+    script?: string;
+}): Promise<void>;