gufi-cli 0.1.49 → 0.1.51

package/docs/mcp/07-packages.md

@@ -0,0 +1,246 @@
+# Packages y Marketplace
+
+Los packages agrupan modulos y vistas para distribucion en el Marketplace.
+
+## Estructura de un package
+
+```
+Package
+├── Modules (snapshots)
+│   └── Module JSON congelado
+├── Views (referencias)
+│   └── IDs de vistas marketplace
+└── Migrations
+    └── SQL para actualizaciones
+```
+
+## Flujo de desarrollo
+
+### 1. Crear package
+
+```
+gufi_package_create({
+  name: "CRM Basico",
+  description: "Gestion de clientes y contactos"
+})
+```
+
+### 2. Agregar modulos
+
+```
+gufi_package_add_module({
+  package_id: "14",
+  company_id: "116",
+  module_id: "360"
+})
+```
+
+Esto crea un **snapshot** del modulo (copia congelada).
+
+### 3. Agregar vistas
+
+```
+gufi_package_add_view({
+  package_id: "14",
+  view_id: "13"
+})
+```
+
+### 4. Publicar
+
+```
+gufi_package_publish({ package_id: "14" })
+```
+
+## Versionado
+
+### Sincronizar cambios
+
+Cuando modificas un modulo fuente, sincroniza el snapshot:
+
+```
+gufi_package_sync({ package_id: "14" })
+```
+
+Esto:
+- Actualiza snapshots de modulos
+- Incrementa version (1.0.0 -> 1.0.1)
+
+### Verificar cambios pendientes
+
+```
+gufi_package_check({ package_id: "14" })
+
+Response:
+{
+  "has_changes": true,
+  "modules_changed": [360],
+  "current_version": "1.0.0"
+}
+```
+
+## Migraciones
+
+Cuando cambias la estructura de un modulo publicado, necesitas migraciones para actualizar instalaciones existentes.
+
+### Listar migraciones
+
+```
+gufi_package_migrations({ package_id: "14" })
+```
+
+### Crear migracion
+
+```
+gufi_package_migration_create({
+  package_id: "14",
+  description: "Add phone column to clients",
+  target_entity: "crm.clientes",
+  up_sql: "ALTER TABLE {tableName} ADD COLUMN telefono JSONB",
+  down_sql: "ALTER TABLE {tableName} DROP COLUMN telefono",
+  is_breaking: false
+})
+```
+
+**Placeholders disponibles:**
+- `{tableName}` - Nombre fisico de la tabla (m360_t4136)
+- `{entityId}` - ID de la entidad
+- `{companyId}` - ID de la company instaladora
+
+### Eliminar migracion (solo si no aplicada)
+
+```
+gufi_package_migration_delete({
+  package_id: "14",
+  migration_id: "5"
+})
+```
+
+### Ver entidades para target_entity
+
+```
+gufi_package_entities({ package_id: "14" })
+
+Response:
+[
+  { "path": "crm.clientes", "name": "Clientes", "entity_id": 4136 },
+  { "path": "crm.contactos", "name": "Contactos", "entity_id": 4137 }
+]
+```
+
+## Operaciones con MCP
+
+### Listar mis packages
+
+```
+gufi_packages()
+```
+
+### Ver detalle de package
+
+```
+gufi_package({ package_id: "14" })
+
+Response:
+{
+  "id": 14,
+  "name": "CRM Basico",
+  "version": "1.0.3",
+  "published": true,
+  "modules": [...],
+  "views": [...],
+  "installations_count": 25
+}
+```
+
+### Quitar modulo
+
+```
+gufi_package_remove_module({
+  package_id: "14",
+  module_id: "5"  // ID del module DENTRO del package
+})
+```
+
+### Quitar vista
+
+```
+gufi_package_remove_view({
+  package_id: "14",
+  package_view_id: "3"  // ID de la relacion package-view
+})
+```
+
+### Despublicar
+
+```
+gufi_package_unpublish({ package_id: "14" })
+```
+
+### Eliminar package
+
+```
+gufi_package_delete({ package_id: "14" })
+```
+
+Solo funciona si NO esta publicado.
+
+## Instalacion (para compradores)
+
+Cuando alguien instala un package:
+
+1. Se crea copia de modulos en su company
+2. Se configuran vistas con sus tablas
+3. Se ejecutan migraciones pendientes
+
+## Actualizaciones
+
+Cuando publicas nueva version:
+
+1. Instalaciones existentes ven "actualizacion disponible"
+2. Al actualizar, se ejecutan migraciones en orden
+3. Se actualizan snapshots de modulos
+
+## Precios y monetizacion
+
+El Marketplace soporta:
+- **Gratis** - Cualquiera puede instalar
+- **Pago unico** - Se cobra una vez
+- **Suscripcion** - Cobro mensual/anual
+
+Configuracion via UI de Developer Center (no via MCP).
+
+## Buenas practicas
+
+### 1. Versionado semantico
+
+- **MAJOR** (2.0.0): Cambios breaking (eliminaciones, renombres)
+- **MINOR** (1.1.0): Nuevas features compatibles
+- **PATCH** (1.0.1): Fixes y mejoras menores
+
+### 2. Migraciones seguras
+
+```sql
+-- CORRECTO: Add column (safe)
+ALTER TABLE {tableName} ADD COLUMN IF NOT EXISTS nuevo_campo TEXT;
+
+-- CUIDADO: Drop column (perdida de datos)
+ALTER TABLE {tableName} DROP COLUMN IF EXISTS campo_viejo;
+
+-- INCORRECTO: Rename (no soportado bien)
+ALTER TABLE {tableName} RENAME COLUMN viejo TO nuevo;
+```
+
+### 3. Test antes de publicar
+
+1. Instalar en company de prueba
+2. Verificar que todo funciona
+3. Probar migraciones en BD de test
+
+### 4. Documentacion
+
+Incluir en descripcion del package:
+- Que hace
+- Como configurar
+- Requisitos previos
+- Changelog de versiones

package/docs/mcp/08-common-errors.md

@@ -0,0 +1,284 @@
+# Errores Comunes y Soluciones
+
+## Datos y tipos
+
+### Currency como objeto (INCORRECTO)
+
+```javascript
+// ERROR: Formato legacy
+precio: { currency: 'EUR', amount: 150 }
+
+// CORRECTO: Solo el numero
+precio: gufi.CB.currency(150)
+// o directamente:
+precio: 150
+```
+
+Currency ahora es NUMERIC. El codigo de moneda va en el schema del campo.
+
+### Phone con formato incorrecto
+
+```javascript
+// ERROR: Formato legacy
+telefono: { country: 'ES', number: '612345678' }
+
+// CORRECTO: Usar CB.phone
+telefono: gufi.CB.phone('612345678')
+// Resultado: { prefix: '+34', number: '612345678' }
+```
+
+### Olvidar __display en updates
+
+```javascript
+// ERROR: UI no muestra el cambio
+await dataProvider.update({
+  resource: table,
+  id: 5,
+  variables: { estado: 'completado' }
+});
+
+// CORRECTO: Actualizar ambos
+await dataProvider.update({
+  resource: table,
+  id: 5,
+  variables: {
+    estado: 'completado',
+    estado__display: 'Completado'
+  }
+});
+```
+
+Aplica a: `select`, `relation`, `currency` (si tenia formato viejo)
+
+### Base64 en campos file
+
+```javascript
+// ERROR: Base64 directo
+foto: 'data:image/png;base64,iVBOR...'
+
+// CORRECTO: Subir primero, luego guardar URL
+const { url, name } = await uploadFile(file);
+foto: gufi.CB.file(url, name)
+```
+
+Solo `signature` acepta base64 directo.
+
+## Vistas
+
+### Hardcodear IDs físicos de tabla
+
+```typescript
+// ERROR: IDs físicos difíciles de leer y no portables
+const data = await dataProvider.getList({ resource: 'm360_t16192' });
+
+// CORRECTO: Usar nombres lógicos (dataProvider los resuelve automáticamente)
+const pedidosTable = 'ventas.pedidos';
+const data = await dataProvider.getList({ resource: pedidosTable });
+```
+
+### Importar stores directamente
+
+```typescript
+// ERROR: Rompe aislamiento
+import { useAuthStore } from '@/stores/useAuthStore';
+
+// CORRECTO: Usar gufi.context
+const user = gufi.context?.user;
+const company = gufi.context?.activeCompany;
+```
+
+### Toast de shadcn
+
+```typescript
+// ERROR: No es el toast de Gufi
+import { toast } from '@/components/ui/toast';
+
+// CORRECTO: Toast del SDK
+import { toastSuccess, toastError } from '@/sdk';
+toastSuccess('Guardado');
+```
+
+### Olvidar exportar featureConfig
+
+```typescript
+// ERROR: Vista no tiene dataSources
+export default function MiVista() { ... }
+
+// CORRECTO: Exportar featureConfig
+export { featureConfig } from './core/dataProvider';
+export default function MiVista() { ... }
+```
+
+## Automations
+
+### Destructuring en api.query
+
+```javascript
+// ERROR: api.query devuelve rows directamente
+const { rows } = await gufi.query("SELECT * FROM table");
+
+// CORRECTO:
+const rows = await gufi.query("SELECT * FROM table");
+```
+
+### SQL injection
+
+```javascript
+// ERROR: Interpolacion directa
+const rows = await gufi.query(`SELECT * FROM users WHERE id = ${id}`);
+
+// CORRECTO: Parametros
+const rows = await gufi.query("SELECT * FROM users WHERE id = $1", [id]);
+```
+
+### Return sin success
+
+```javascript
+// ERROR: Worker no sabe si funciono
+async function mi_automation(ctx, api, logger) {
+  // ... hacer cosas
+}
+
+// CORRECTO: Retornar estado
+async function mi_automation(ctx, api, logger) {
+  // ... hacer cosas
+  return { success: true, message: 'OK' };
+}
+```
+
+## API y autenticacion
+
+### Falta X-Company-ID
+
+```
+// ERROR: 400 Bad Request
+GET /api/company/schema
+Authorization: Bearer xxx
+
+// CORRECTO:
+GET /api/company/schema
+Authorization: Bearer xxx
+X-Company-ID: 116
+```
+
+### Token expirado
+
+```
+// Response: 401 Unauthorized
+// Solucion: Refresh token
+
+POST /api/auth/refresh
+X-Refresh-Token: {refreshToken}
+```
+
+### Sin permisos
+
+```
+// Response: 403 Forbidden
+// Causa: Usuario no tiene permiso para esa accion
+
+// Verificar permisos de la entidad:
+gufi_context({ company_id: "116" })
+// Ver permissions de cada entity
+```
+
+## Modulos
+
+### Field type incorrecto
+
+```json
+// ERROR: Tipo no existe
+{ "name": "fecha", "type": "timestamp" }
+
+// CORRECTO: Usar date (con includeTime si necesitas hora)
+{ "name": "fecha", "type": "date" }
+{ "name": "fecha_hora", "type": "date", "includeTime": true }
+```
+
+Tipos validos: `text`, `email`, `url`, `barcode`, `number`, `number_int`, `number_float`, `percentage`, `date`, `time`, `select`, `multiselect`, `boolean`, `relation`, `users`, `currency`, `phone`, `location`, `file`, `signature`, `json`, `formula`, `mirror`
+
+### Relacion sin displayField
+
+```json
+// WARNING: Muestra ID en lugar de nombre
+{
+  "name": "cliente",
+  "type": "relation",
+  "relation": { "module": "crm", "entity": "clientes" }
+}
+
+// MEJOR: Especificar displayField
+{
+  "name": "cliente",
+  "type": "relation",
+  "relation": {
+    "module": "crm",
+    "entity": "clientes",
+    "displayField": "nombre"
+  }
+}
+```
+
+### Select sin options
+
+```json
+// ERROR: No hay opciones que seleccionar
+{ "name": "estado", "type": "select" }
+
+// CORRECTO:
+{
+  "name": "estado",
+  "type": "select",
+  "options": [
+    { "value": "activo", "label": "Activo", "color": "green" },
+    { "value": "inactivo", "label": "Inactivo", "color": "gray" }
+  ]
+}
+```
+
+## Packages
+
+### Publicar sin cambios guardados
+
+```javascript
+// ERROR: Cambios no se reflejan
+
+// CORRECTO: Verificar con get antes de publicar
+gufi_package({ action: "get", id: "14" })
+// Ver has_unpublished_changes
+
+// Publicar
+gufi_package({ action: "publish", id: "14" })
+```
+
+## Debug tips
+
+### Ver logs de automation
+
+```javascript
+gufi_automation_executions({
+  company_id: "116",
+  script_name: "mi_automation",
+  limit: 5
+})
+```
+
+### Ver schema completo
+
+```javascript
+gufi_context({ company_id: "116" })
+```
+
+### Verificar configuracion
+
+```javascript
+gufi_whoami()
+```
+
+### Probar API directamente
+
+```bash
+curl -X GET "https://api.gogufi.com/api/company/schema" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Company-ID: 116"
+```