gufi-cli 0.1.49 → 0.1.51

package/docs/mcp/04-views.md

@@ -0,0 +1,613 @@
+# Vistas Marketplace
+
+## TL;DR
+
+```
+mi_vista/
+├── index.tsx              # OBLIGATORIO - Entry point
+├── core/
+│   ├── dataSources.ts     # OBLIGATORIO - Define tablas
+│   ├── automations.ts     # Si usa automations - declara cuáles usa
+│   └── index.tsx          # OBLIGATORIO - featureConfig
+└── views/
+    └── page.tsx           # Recomendado - Componente principal
+```
+
+**Workflow MCP completo:**
+```
+# 1. Crear la vista (es una entity de tipo marketplace_view)
+gufi_schema_modify({
+  company_id: "116",
+  operations: [{
+    op: "add_entity",
+    module: "ventas",
+    entity: { name: "mi_dashboard", label: "Mi Dashboard", kind: "marketplace_view" }
+  }]
+})
+
+# 2. Descargar template
+gufi_view_pull({ view_id: <id> })  → Descarga a ~/gufi-dev/view_<id>/
+
+# 3. Editar archivos locales
+
+# 4. Subir cambios
+gufi_view_push({ view_id: <id> })  → Sube a draft (valida ANTES de subir)
+
+# 5. Publicar
+gufi package:publish <package_id>  → Publica a producción
+```
+
+---
+
+## Archivos Obligatorios
+
+### 1. index.tsx (Entry Point)
+
+```typescript
+// index.tsx - OBLIGATORIO
+// Debe exportar featureConfig y default component
+
+export { featureConfig } from './core';
+
+import Page from './views/page';
+export default Page;
+```
+
+### 2. core/dataSources.ts (Tablas)
+
+```typescript
+// core/dataSources.ts - OBLIGATORIO
+// Define las tablas que la vista puede acceder
+
+export const dataSources = [
+  { key: 'productos', table: 'ventas.productos' },
+  { key: 'pedidos', table: 'ventas.pedidos' },
+] as const;
+```
+
+**El engine:**
+1. Lee `core/dataSources.ts` al cargar la vista
+2. Resuelve cada `table` lógico → ID físico (automático)
+3. Crea `gufi.tables = { productos: 'm308_t4135', pedidos: '...' }`
+
+### 3. core/index.tsx (Feature Config)
+
+```typescript
+// core/index.tsx - OBLIGATORIO
+import { dataSources } from './dataSources';
+import { featureInputs } from '../metadata/inputs';
+import { seedData } from '../metadata/seedData';
+
+export const featureConfig = {
+  dataSources,
+  inputs: featureInputs,
+  seedData,
+  meta: {
+    name: 'Mi Vista',
+    version: '1.0.0',
+  },
+};
+
+// Re-export dataSources
+export { dataSources };
+```
+
+---
+
+## Componente Principal
+
+### views/page.tsx
+
+```typescript
+import React, { useState, useEffect } from 'react';
+import type { FullGufiContext } from '@/sdk';
+
+interface ViewProps {
+  id: string;
+  gufi: FullGufiContext;  // REQUIRED - nunca opcional
+}
+
+export default function MiVista({ id, gufi }: ViewProps) {
+  const { tables, dataProvider, context, utils } = gufi;
+  const { toastSuccess, toastError } = utils;
+
+  const [data, setData] = useState<any[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const load = async () => {
+      try {
+        // 💜 Usar gufi.tables (IDs físicos ya resueltos)
+        const res = await dataProvider.getList({
+          resource: tables.productos,
+          pagination: { current: 1, pageSize: 100 },
+        });
+        setData(res.data);
+      } catch (err) {
+        toastError('Error cargando datos');
+      } finally {
+        setLoading(false);
+      }
+    };
+    load();
+  }, []);
+
+  if (loading) return <div className="p-4">Cargando...</div>;
+
+  return (
+    <div className="flex flex-col h-[100dvh] bg-gradient-to-br from-violet-50/40 via-white to-purple-50/40">
+      <header className="p-4 border-b">
+        <h1 className="text-lg font-semibold">Mi Vista</h1>
+      </header>
+      <main className="flex-1 overflow-auto p-4">
+        {data.map(item => (
+          <div key={item.id} className="p-4 bg-white rounded-xl border mb-2">
+            {item.nombre}
+          </div>
+        ))}
+      </main>
+    </div>
+  );
+}
+```
+
+---
+
+## gufi - Lo que recibes
+
+```typescript
+gufi = {
+  // 💜 TABLES - IDs físicos resueltos desde dataSources.ts
+  tables: {
+    productos: 'm308_t4135',  // Resuelto automáticamente
+    pedidos: 'm308_t4136',
+    // Solo tablas declaradas en dataSources.ts
+  },
+
+  // CRUD
+  dataProvider: {
+    getList({ resource, pagination, filters, sorters }),
+    getOne({ resource, id }),
+    create({ resource, variables }),
+    update({ resource, id, variables }),
+    deleteOne({ resource, id }),
+  },
+
+  // Contexto
+  context: {
+    lang,            // 'es' | 'en'
+    user,            // { id, name, email }
+    activeCompany,   // { id, name }
+    schema,          // Módulos y entidades
+  },
+
+  // Utilidades
+  utils: {
+    toastSuccess, toastError, toastInfo,
+    formatCurrency, formatDate,
+    cn, tUI,
+  },
+
+  // Column Builders
+  CB: {
+    currency(150),       // { currency: 'EUR', amount: 150 }
+    phone('612345678'),  // { prefix: '+34', number: '...' }
+    date(),              // Fecha de hoy
+  },
+
+  // 💜 Automations - Ejecutar lógica de negocio
+  automation(name, input),  // Llama automation por nombre
+
+  // Device
+  device: { isHandheld, isDesktop },
+}
+```
+
+---
+
+## Librerías Disponibles
+
+Las Custom Views pueden importar estas librerías (mockeadas/incluidas en el engine):
+
+### UI & Componentes
+
+| Librería | Import | Descripción |
+|----------|--------|-------------|
+| **Lucide Icons** | `from 'lucide-react'` | Iconos: `<Search />`, `<Plus />`, etc. |
+| **Recharts** | `from 'recharts'` | Gráficos: `LineChart`, `BarChart`, `PieChart` |
+| **UI Components** | `from '@/shared/ui'` | Button, Card, Dialog, Tabs, Select, Badge, etc. |
+| **Radix UI** | `from '@radix-ui/*'` | Primitivos accesibles |
+
+### Animaciones (Framer Motion)
+
+```typescript
+import {
+  motion,              // motion.div, motion.button, etc.
+  AnimatePresence,     // Animaciones de entrada/salida
+  useScroll,           // Track scroll position
+  useTransform,        // Mapear valores
+  useMotionValueEvent, // Escuchar cambios
+  useMotionValue,      // Crear valor reactivo
+  useSpring,           // Física de spring
+  useInView,           // Detectar visibilidad
+} from 'framer-motion';
+```
+
+**Props de animación:**
+- `initial`, `animate`, `exit` - Estados
+- `transition` - `{ duration, delay, ease }`
+- `whileHover`, `whileTap` - Interacciones
+- `whileInView`, `viewport` - Scroll reveal
+
+**Propiedades animables:** `x`, `y`, `scale`, `rotate`, `opacity`, `filter`
+
+**Ejemplo scroll animation:**
+```typescript
+const containerRef = useRef(null);
+const { scrollYProgress } = useScroll({ target: containerRef, offset: ["start start", "end end"] });
+const opacity = useTransform(scrollYProgress, [0, 0.5], [0, 1]);
+
+return (
+  <div ref={containerRef} style={{ height: '300vh' }}>
+    <motion.div style={{ opacity }} className="sticky top-0">
+      Fade in on scroll
+    </motion.div>
+  </div>
+);
+```
+
+**Ejemplo whileInView:**
+```typescript
+<motion.div
+  initial={{ opacity: 0, y: 30 }}
+  whileInView={{ opacity: 1, y: 0 }}
+  viewport={{ once: true }}
+>
+  Aparece al scroll
+</motion.div>
+```
+
+### Utilidades
+
+| Librería | Import | Descripción |
+|----------|--------|-------------|
+| **date-fns** | `from 'date-fns'` | `format`, `parseISO`, `addDays`, etc. |
+| **clsx/cn** | `from '@/shared/lib/utils'` | Merge classNames |
+| **Theme** | `from '@/shared/styles/theme'` | `THEME`, `PATTERNS` |
+| **Language** | `from '@/shared/language'` | `tUI()`, `getLang()` |
+| **Toast** | `from '@/shared/notifications/toast'` | `toastSuccess()`, `toastError()` |
+| **JsBarcode** | `from 'jsbarcode'` | Generar códigos de barras |
+
+### Hooks Gufi
+
+| Hook | Import | Descripción |
+|------|--------|-------------|
+| `useViewPreferences` | `from '@/shared/hooks'` | Persistir filtros/estado |
+| `useDebouncedValue` | `from '@/shared/hooks'` | Debounce valores |
+| `useDeviceMode` | `from '@/shared/adaptive'` | `{ isHandheld, isDesktop }` |
+| `useEntityConfig` | `from '@/sdk'` | Config de entidad |
+
+---
+
+## Desarrollo con MCP
+
+### Workflow Completo
+
+```bash
+# 1. Descargar vista a local
+gufi_view_pull({ view_id: 25 })
+# → ~/gufi-dev/view_25/
+
+# 2. Editar archivos locales con Read/Edit
+Read("~/gufi-dev/view_25/views/page.tsx")
+Edit("~/gufi-dev/view_25/views/page.tsx", ...)
+
+# 3. Subir cambios a draft
+gufi_view_push({ view_id: 25 })
+# ⚠️ VALIDA ESTRUCTURA ANTES DE SUBIR
+# Si falta index.tsx o core/dataSources.ts → BLOQUEA el push
+
+# 4. Publicar a producción (si tiene package)
+gufi package:publish <package_id>
+```
+
+### Validación Pre-Push
+
+El push ahora valida ANTES de subir:
+
+**Errores bloqueantes:**
+- Falta `index.tsx`
+- Falta `core/dataSources.ts` (o dataSources en `core/index.tsx`)
+- `index.tsx` no exporta `featureConfig`
+- `index.tsx` no tiene `export default`
+
+**Advertencias:**
+- Falta `core/index.tsx` con featureConfig
+- Falta componente en `views/`
+
+### Entornos: Local vs Producción
+
+```bash
+# Ver entorno actual
+gufi_whoami()
+
+# Cambiar entorno ANTES de push
+gufi config:local   # → http://localhost:3000
+gufi config:prod    # → https://gogufi.com
+```
+
+**IMPORTANTE:** Verifica siempre el entorno antes de hacer push.
+
+---
+
+## CRUD
+
+```typescript
+const { tables, dataProvider, CB } = gufi;
+
+// Leer lista
+const { data } = await dataProvider.getList({
+  resource: tables.productos,  // 💜 gufi.tables
+  pagination: { current: 1, pageSize: 50 },
+  filters: [{ field: 'activo', operator: 'eq', value: true }],
+  sorters: [{ field: 'nombre', order: 'asc' }],
+});
+
+// Leer uno
+const { data: producto } = await dataProvider.getOne({
+  resource: tables.productos,
+  id: 123,
+});
+
+// Crear (usar CB para campos especiales)
+await dataProvider.create({
+  resource: tables.productos,
+  variables: {
+    nombre: 'Nuevo',
+    precio: CB.currency(100),
+  },
+});
+
+// Actualizar (incluir __display para select/relation)
+await dataProvider.update({
+  resource: tables.productos,
+  id: 123,
+  variables: {
+    estado: 'completado',
+    estado__display: 'Completado',
+  },
+});
+
+// Eliminar
+await dataProvider.deleteOne({
+  resource: tables.productos,
+  id: 123,
+});
+```
+
+---
+
+## Automations desde Views
+
+Las views pueden ejecutar automations, pero **DEBEN declararlas en `core/automations.ts`**.
+
+### 1. Declarar automations (OBLIGATORIO)
+
+```typescript
+// core/automations.ts - OBLIGATORIO si la view usa automations
+export const automations = [
+  { name: 'process_payment', description: 'Crea sesión de pago en Stripe' },
+  { name: 'send_invoice', description: 'Envía factura por email' },
+] as const;
+```
+
+**Al hacer `gufi_view_push`:**
+1. El sistema detecta `core/automations.ts`
+2. Registra cada automation en `__automation_meta__` con `trigger_event='CUSTOM'`
+3. Solo las automations declaradas podrán ser ejecutadas desde la view
+
+### 2. Llamar automations desde la View
+
+```typescript
+// En la View
+const handlePayment = async () => {
+  try {
+    // 💜 Solo funciona si 'process_payment' está en core/automations.ts
+    const result = await gufi.automation('process_payment', {
+      amount: 1999,
+      customer_email: 'cliente@example.com',
+    });
+
+    if (result.url) {
+      window.location.href = result.url;
+    }
+  } catch (err) {
+    gufi.utils.toastError('Error procesando pago');
+  }
+};
+
+return <button onClick={handlePayment}>Pagar</button>;
+```
+
+### 3. Crear el script de automation
+
+```javascript
+// En la Automation (BD: __automation_scripts__)
+// Crear con: gufi_automation_scripts({ action: 'create', name: 'process_payment', code: '...' })
+async function process_payment(gufi) {
+  const { input, env } = gufi.context;
+
+  const result = await gufi.integrations.stripe.createCheckoutSession({
+    secretKey: env.STRIPE_SECRET_KEY,
+    lineItems: [{ name: 'Producto', amount: input.amount, quantity: 1 }],
+    customerEmail: input.customer_email,
+  });
+
+  return { url: result.url, sessionId: result.sessionId };
+}
+```
+
+### Flujo Completo
+
+```
+1. Crear script:         gufi_automation_scripts({ action: 'create', name: 'X' })
+2. Declarar en view:     core/automations.ts → export const automations = [{ name: 'X' }]
+3. Push view:            gufi_view_push() → Registra en __automation_meta__
+4. Llamar desde view:    gufi.automation('X', input) → Validado y ejecutado
+```
+
+### Error si no está declarada
+
+```
+Error: Automation 'X' is not declared in this view's core/automations.ts.
+Add it and push the view first.
+```
+
+**Solución:** Añadir la automation a `core/automations.ts` y hacer push.
+
+### Integraciones disponibles
+
+- `gufi.integrations.stripe.*` - Pagos
+- `gufi.integrations.nayax.*` - Vending telemetry
+- `gufi.integrations.ourvend.*` - RedPanda vending
+- `gufi.integrations.tns.*` - Contabilidad Colombia
+
+Ver integraciones: `gufi_automation_integrations()` en MCP.
+
+---
+
+## Reglas
+
+### CORRECTO
+
+```typescript
+// ✅ core/dataSources.ts existe
+export const dataSources = [
+  { key: 'productos', table: 'ventas.productos' },
+] as const;
+
+// ✅ core/automations.ts para automations
+export const automations = [
+  { name: 'mi_script', description: 'Hace algo' },
+] as const;
+
+// ✅ gufi es required
+gufi: FullGufiContext
+
+// ✅ Usar gufi.tables
+resource: gufi.tables.productos
+
+// ✅ Pasar gufi a children
+<Child gufi={gufi} />
+```
+
+### INCORRECTO
+
+```typescript
+// ❌ TABLES local (usar gufi.tables)
+const TABLES = { productos: 'ventas.productos' };
+
+// ❌ gufi opcional
+gufi?: any
+
+// ❌ IDs físicos hardcodeados
+resource: 'm308_t4136'
+
+// ❌ stores
+import { useAuthStore }
+
+// ❌ Llamar automation sin declararla
+gufi.automation('script_no_declarado', {})  // Error 403
+```
+
+---
+
+## CLI
+
+```bash
+gufi view:pull <id>       # Descargar vista
+gufi view:push            # Subir cambios (valida + sube + valida servidor)
+gufi package:publish <id> # Publicar a producción
+```
+
+---
+
+## Errores Comunes
+
+| Error | Causa | Solución |
+|-------|-------|----------|
+| `Falta archivo obligatorio: index.tsx` | No existe entry point | Crear index.tsx con exports |
+| `Falta archivo obligatorio: core/dataSources.ts` | No se definieron tablas | Crear dataSources.ts |
+| `index.tsx debe exportar featureConfig` | Falta export | Añadir `export { featureConfig } from './core'` |
+| `gufi.tables undefined` | dataSources vacío | Añadir tablas a dataSources |
+| `Cannot read context` | gufi no pasado | Pasar `gufi={gufi}` a children |
+| `Table not found` | Nombre lógico mal | Verificar modulo.entidad en schema |
+| `Push a producción en vez de local` | Entorno mal configurado | Verificar con `gufi_whoami()` |
+| `Automation 'X' is not declared` | Falta en core/automations.ts | Añadir automation a core/automations.ts y push |
+| `Declared automation script not found` | Script no existe | Crear script con gufi_automation_scripts |
+
+---
+
+## Testing de Views con gufi_view_test
+
+### Workflow Estándar
+
+```javascript
+// 1️⃣ SIEMPRE explorar primero para ver elementos disponibles
+gufi_view_test({
+  view_id: 45,
+  company_id: "116",
+  actions: [
+    {type: "closeModals"},           // Cerrar popups/newsletters
+    {type: "delay", ms: 2000},       // Esperar carga
+    {type: "explore"}                // Listar botones, links, inputs
+  ]
+})
+// → actions[2].elements = { buttons: [...], links: [...], inputs: [...] }
+
+// 2️⃣ LUEGO interactuar usando texto visible
+gufi_view_test({
+  view_id: 45,
+  company_id: "116",
+  actions: [
+    {type: "closeModals"},
+    {type: "click", selector: "text:Mi Botón"},    // Click por texto
+    {type: "delay", ms: 1000},
+    {type: "click", selector: "text:Siguiente"},
+    {type: "delay", ms: 1000}
+  ]
+})
+```
+
+### Actions Disponibles
+
+| Action | Uso | Ejemplo |
+|--------|-----|---------|
+| `explore` | Lista elementos interactivos | `{type: "explore"}` → buttons, links, inputs |
+| `closeModals` | Cierra popups/newsletters | `{type: "closeModals"}` |
+| `click` | Click por texto o CSS | `{type: "click", selector: "text:Enviar"}` |
+| `delay` | Esperar ms | `{type: "delay", ms: 1000}` |
+| `fill` | Escribir en input | `{type: "fill", selector: "input[name=email]", value: "a@b.com"}` |
+| `eval` | JavaScript custom | `{type: "eval", code: "document.title"}` |
+| `screenshot` | Captura intermedia | `{type: "screenshot"}` |
+
+### Respuesta
+
+```javascript
+{
+  success: true,
+  dom: { title, textPreview, elementCount },
+  actions: [
+    { type: "explore", elements: { buttons: [...], links: [...] } },
+    { type: "click", clicked: "Mi Botón" },
+  ],
+  screenshot: "data:image/jpeg;base64,..."
+}
+```
+
+### Reglas Clave
+
+1. **SIEMPRE `closeModals` primero** - Las vistas suelen tener popups de newsletter
+2. **SIEMPRE `explore` antes de interactuar** - Para saber qué elementos hay
+3. **Usar `text:` para clicks** - Más robusto que selectores CSS
+4. **Los resultados de eval están en `actions[n].result`**