gufi-cli 0.1.21 → 0.1.23

package/CLAUDE.md

@@ -1,213 +1,128 @@
-# Gufi CLI - Documentación para Claude
+# Gufi CLI & MCP Server
 
-> **Documentación centralizada en `docs/claude/`**
+> **Para documentación de USO del CLI**, ve a `docs/mcp/`
 >
-> Este archivo es un puntero. Para documentación completa del CLI, lee:
-> - [docs/claude/06-cli.md](../../docs/claude/06-cli.md) - Comandos del CLI
-> - [docs/claude/00-index.md](../../docs/claude/00-index.md) - Overview de Gufi
-> - [docs/claude/05-automations.md](../../docs/claude/05-automations.md) - Automations
-> - [docs/claude/04-views.md](../../docs/claude/04-views.md) - Sistema de vistas
+> Este archivo es para desarrollo INTERNO del CLI (código en `tools/cli/src/`)
 
-## Quick Reference
+## Estructura del CLI
 
-```bash
-# Contexto, diagnóstico y documentación
-gufi context              # Genera contexto para Claude
-gufi doctor               # Diagnóstico del sistema
-gufi docs                 # Ver topics disponibles
-gufi docs fields          # Documentación de tipos de campo
-gufi docs errors          # Errores comunes y soluciones
-gufi docs --search "currency"  # Buscar en toda la documentación
-
-# Entornos
-gufi config               # Ver entornos
-gufi config:local         # Cambiar a localhost
-gufi config:prod          # Cambiar a producción
-
-# Módulos
-gufi modules 146          # Ver módulos
-gufi module 360 --edit    # Editar con $EDITOR
-
-# Automations
-gufi automations          # Ver scripts
-gufi automation 15 --edit # Editar script
-gufi entity:automations 4136  # Ver triggers
-
-# Vistas
-gufi view:pull 13         # Descargar
-gufi view:push            # Subir cambios
-gufi view:watch           # Auto-sync
-
-# Datos
-gufi rows m360_t16192     # Listar registros
-gufi row:create table --data '{...}'
 ```
-
-## Output JSON (para Claude/scripts)
-
-Todos los comandos de lectura soportan `--json` para output estructurado sin colores ni emojis:
-
-```bash
-gufi companies --json           # Lista companies en JSON
-gufi modules 146 --json         # Lista módulos en JSON
-gufi module 360 --json          # JSON del módulo
-gufi automations --json         # Lista automations en JSON
-gufi automation 15 --json       # Código y metadata del automation
-gufi schema --json              # Estructura de tablas en JSON
-gufi rows m360_t16192 --json    # Registros en JSON
-gufi row m360_t16192 5 --json   # Registro específico en JSON
-gufi packages --json            # Lista packages en JSON
-gufi package 14 --json          # Detalles del package en JSON
+tools/cli/
+├── src/
+│   ├── index.ts          # Entry point CLI
+│   ├── mcp.ts            # MCP Server (44 tools)
+│   ├── commands/         # Comandos CLI
+│   │   ├── context.ts    # gufi context
+│   │   ├── pull.ts       # gufi view:pull
+│   │   ├── push.ts       # gufi view:push
+│   │   ├── watch.ts      # gufi view:watch
+│   │   └── ...
+│   └── lib/
+│       ├── api.ts        # Cliente API
+│       ├── config.ts     # Gestión de config (~/.gufi/)
+│       └── sync.ts       # Sincronización de vistas
+├── package.json
+└── tsconfig.json
 ```
 
-Usar `--json` cuando necesites parsear el output programáticamente.
+## MCP Server
 
-## MCP Server (Model Context Protocol)
+El servidor MCP está en `src/mcp.ts` y expone 44 tools para que Claude interactúe con Gufi.
 
-El CLI incluye un servidor MCP que permite a Claude interactuar **directamente** con Gufi sin ejecutar comandos manualmente.
+### Tools principales (nuevos)
 
-### Configuración (una sola vez)
+- **`gufi_start`** - Entrypoint inteligente que auto-detecta contexto:
+  - Si está en gogufi/: Detecta codebase, apunta a docs/claude/
+  - Si está en carpeta de vista: Devuelve contexto de la vista
+  - Si no detecta nada: Lista packages del usuario
 
-```bash
-claude mcp add --transport stdio gufi -- gufi mcp
-```
+- **`gufi_context`** - Ahora devuelve:
+  - `summary`: Resumen ejecutivo
+  - `next_actions`: Pasos sugeridos
+  - Auto-detección de codebase y vistas locales
 
-### Tools disponibles (43 tools)
-
-**Contexto e Info (EMPEZAR AQUÍ):**
-- `gufi_context` - **USAR PRIMERO** - Genera contexto inteligente del proyecto
-- `gufi_whoami` - Usuario y entorno actual
-- `gufi_schema` - Estructura de tablas/campos
-- `gufi_docs` - **LEER DOCUMENTACIÓN** - Topics: fields, views, automations, errors, examples
-
-**Companies:**
-- `gufi_companies` - Listar companies
-- `gufi_company_create` - Crear company
-
-**Módulos (estructura de datos):**
-- `gufi_modules` - Listar módulos de una company
-- `gufi_module` - Ver JSON completo de un módulo
-- `gufi_module_update` - **Modificar módulo** (añadir campos, entidades)
-- `gufi_module_create` - Crear módulo nuevo
-
-**Automations (lógica de negocio):**
-- `gufi_automations` - Listar scripts
-- `gufi_automation` - Ver código JS de un script
-- `gufi_automation_create` - **Crear/actualizar script**
-- `gufi_entity_automations` - Ver triggers de una entidad
-- `gufi_entity_automations_update` - **Configurar triggers**
-- `gufi_automations_executions` - Ver historial de ejecuciones
-
-**Datos (CRUD):**
-- `gufi_rows` - Listar registros de una tabla
-- `gufi_row` - Ver un registro
-- `gufi_row_create` - Crear registro
-- `gufi_row_update` - Actualizar registro
-- `gufi_row_delete` - Eliminar registro
-
-**Environment Variables:**
-- `gufi_env` - Listar variables
-- `gufi_env_set` - Crear/actualizar variable
-- `gufi_env_delete` - Eliminar variable
-
-**Vistas (React/TSX):**
-- `gufi_view_files` - Ver archivos de una vista
-- `gufi_view_file_update` - **Modificar archivo de vista**
-- `gufi_view_files_update` - Modificar múltiples archivos
-
-**Packages (Marketplace):**
-- `gufi_packages` - Listar packages
-- `gufi_package` - Ver detalles
-- `gufi_package_create` - Crear package
-- `gufi_package_publish` - Publicar
-- `gufi_package_sync` - Sincronizar versión
-- `gufi_package_add_module` / `gufi_package_remove_module`
-- `gufi_package_add_view` / `gufi_package_remove_view`
-
-**Package Migrations:**
-- `gufi_package_migrations` - Listar migraciones
-- `gufi_package_migration_create` - Crear migración SQL
-- `gufi_package_entities` - Listar entidades para target_entity
-
-### Ejemplos de uso con Claude
+### Añadir un nuevo tool MCP
 
+1. **Definir tool** en array `TOOLS` (~línea 200):
+```typescript
+{
+  name: "gufi_nuevo_tool",
+  description: getDesc("gufi_nuevo_tool"),
+  inputSchema: {
+    type: "object",
+    properties: {
+      param1: { type: "string", description: "..." },
+    },
+    required: ["param1"],
+  },
+},
 ```
-Usuario: "Agrega un campo 'fecha_entrega' tipo date al módulo de pedidos"
-Claude: [usa gufi_module para leer] → [modifica JSON] → [usa gufi_module_update]
-        "Listo, agregué el campo fecha_entrega al módulo de pedidos"
-
-Usuario: "Crea un automation que envíe email cuando un pedido pase a 'enviado'"
-Claude: [usa gufi_automations para ver existentes]
-        [escribe código JS]
-        [usa gufi_automation_create]
-        [usa gufi_entity_automations_update para configurar trigger]
-        "Listo, creé el automation 'email_pedido_enviado' con trigger on_update"
-
-Usuario: "¿Cuántos clientes hay en la empresa 116?"
-Claude: [usa gufi_schema para encontrar tabla de clientes]
-        [usa gufi_rows para consultar]
-        "Hay 234 clientes en la tabla m360_t4136"
+
+2. **Añadir handler** en `toolHandlers` (~línea 870):
+```typescript
+async gufi_nuevo_tool(params: { param1: string }) {
+  // Implementación
+  return { result: "..." };
+},
 ```
 
-### Tipos de Campo (@gufi/column-types)
+3. **Añadir descripción** en `docs/mcp/tool-descriptions.json`:
+```json
+"gufi_nuevo_tool": {
+  "description": "Descripción clara del tool..."
+}
+```
 
-Al crear o actualizar datos, usa los formatos correctos:
+### Funciones helper importantes
 
-**Simples:**
-- text, email, url, barcode: `"string"`
-- number_int: `42` | number_float: `3.14` | percentage: `0.75`
-- boolean: `true/false`
-- date: `"2024-01-15"` | datetime: `"2024-01-15T10:30:00Z"` | time: `"14:30:00"`
-- select: `"value"` | relation: `123`
+- `detectIfInGufiCodebase()` - Detecta si está en el repo gogufi
+- `loadViewMetaFromCwd()` - Carga `.gufi-view.json` del directorio actual
+- `generateViewContextMcp()` - Genera contexto de una vista
+- `generatePackageContextMcp()` - Genera contexto de un package
+- `apiRequest()` - Peticiones a API con auth
+- `developerRequest()` - Peticiones a /api/developer/
 
-**Arrays:**
-- multiselect: `["value1", "value2"]`
-- users: `[16, 23]`
+## CLI Commands
 
-**JSONB (objetos complejos):**
-- currency: `{ "currency": "EUR", "amount": 150.00 }`
-- phone: `{ "prefix": "+34", "number": "612345678" }`
-- location: `{ "street": "Mayor", "number": "15", "city": "Madrid", "lat": 40.41 }`
-- file: `[{ "url": "company_130/doc.pdf", "name": "doc.pdf" }]`
+Cada comando está en `src/commands/`. Patrón común:
 
-En vistas usa `gufi.CB.*` para formatear correctamente:
 ```typescript
-gufi.CB.currency(150)     // → { currency: 'EUR', amount: 150 }
-gufi.CB.phone('612345678') // → { prefix: '+34', number: '612345678' }
-gufi.CB.date()            // → '2024-01-15' (hoy)
-gufi.CB.multiselect('a', 'b') // → ['a', 'b']
+export async function miComando(args: string[], flags: Flags) {
+  // 1. Parsear argumentos
+  // 2. Validar
+  // 3. Hacer petición API
+  // 4. Mostrar resultado
+}
 ```
 
-### Seguridad
+## Config (~/.gufi/)
 
-- Usa las credenciales del CLI (`gufi login`)
-- Solo accede a resources con permisos del usuario
-- Todo corre localmente (stdio), no hay servidor público
+```
+~/.gufi/
+├── config.json           # Credenciales y entornos
+└── gufi-dev/             # Vistas descargadas
+    └── view_13/
+        ├── .gufi-view.json   # Metadata de sync
+        ├── index.tsx
+        └── ...
+```
 
-## Comandos Esenciales
+## Testing
 
-| Quiero... | Comando |
-|-----------|---------|
-| **Contexto para Claude** | `gufi context` |
-| **Diagnóstico** | `gufi doctor` |
-| **Leer documentación** | `gufi docs fields` |
-| **Buscar en docs** | `gufi docs --search "currency"` |
-| Ver companies | `gufi companies` |
-| Ver módulos | `gufi modules 146` |
-| Editar módulo | `gufi module 360 --edit` |
-| Ver automations | `gufi automations` |
-| Desarrollar vista | `gufi view:pull 13` → `gufi view:push` |
+```bash
+cd tools/cli
+npm test
+```
 
-## Tips
+## Build
 
-1. **`gufi context`**: Úsalo al inicio de cualquier tarea
-2. **Auto-detección**: `module`, `automation`, `rows` detectan company automáticamente
-3. **--edit**: Abre en `$EDITOR`
-4. **Entornos separados**: Cada uno con sus credenciales
-5. **Auto-login**: CLI refresca tokens automáticamente
+```bash
+npm run build   # Compila TypeScript
+npm link        # Instala globalmente para testing
+```
 
-## Documentación Completa
+## Documentación
 
-Para documentación detallada de cada comando, arquitectura, y patrones, ve a:
-- `docs/claude/` - Fuente de verdad para Claude
-- `docs/guide/27-gufi-cli.md` - Guía técnica del CLI
+- **Para usuarios del CLI**: `docs/mcp/` (usado por `gufi_docs`)
+- **Para desarrollo del CLI**: Este archivo
+- **Tool descriptions**: `docs/mcp/tool-descriptions.json`

package/dist/mcp.js

@@ -122,30 +122,34 @@ async function developerRequest(path, options = {}, retry = true) {
     return res.json();
 }
 // ════════════════════════════════════════════════════════════════════════════
-// Tool Definitions
+// Tool Definitions - Descriptions loaded from docs/mcp/tool-descriptions.json
 // ════════════════════════════════════════════════════════════════════════════
+// Load tool descriptions from centralized documentation
+const TOOL_DESCRIPTIONS_PATH = path.join(DOCS_MCP_PATH, "tool-descriptions.json");
+let toolDescriptions = {};
+try {
+    const content = fs.readFileSync(TOOL_DESCRIPTIONS_PATH, "utf-8");
+    toolDescriptions = JSON.parse(content);
+}
+catch (err) {
+    console.error(`Warning: Could not load tool descriptions from ${TOOL_DESCRIPTIONS_PATH}`);
+}
+// Helper to get description from JSON or use fallback
+function getDesc(toolName, fallback = "") {
+    return toolDescriptions[toolName]?.description || fallback;
+}
 const TOOLS = [
     // ─────────────────────────────────────────────────────────────────────────
     // Context & Info
     // ─────────────────────────────────────────────────────────────────────────
+    {
+        name: "gufi_start",
+        description: getDesc("gufi_start"),
+        inputSchema: { type: "object", properties: {} },
+    },
     {
         name: "gufi_context",
-        description: `Generate intelligent context about a Gufi project. This is the FIRST tool to use when starting work on a Gufi project - it provides a complete overview of modules, entities, fields, automations, and relationships.
-
-Use cases:
-- Starting work on a package: gufi_context({ package_id: "14" })
-- Understanding a view: gufi_context({ view_id: "13" })
-- Exploring a company: gufi_context({ company_id: "116" })
-
-The context includes:
-- All modules and their entities (tables) with physical table names
-- Field definitions with types, constraints, and options
-- Available automations and their trigger types
-- DataSources mappings for views (viewSpec.mainTable, etc.)
-- Environment variables available
-- Useful CLI commands for the project
-
-Returns markdown-formatted context optimized for Claude.`,
+        description: getDesc("gufi_context"),
         inputSchema: {
             type: "object",
             properties: {
@@ -158,20 +162,12 @@ Returns markdown-formatted context optimized for Claude.`,
     },
     {
         name: "gufi_whoami",
-        description: "Get current user info and environment (local/prod). Use this to verify authentication status before making changes.",
+        description: getDesc("gufi_whoami"),
         inputSchema: { type: "object", properties: {} },
     },
     {
         name: "gufi_schema",
-        description: `Get the database schema of a company - lists all modules, entities (tables), and their fields.
-
-Returns for each entity:
-- id: Entity ID
-- name: Entity name
-- table: Physical table name (m{moduleId}_t{entityId})
-- fields: Array of {name, type, label}
-
-Use this to understand the data structure before creating queries or modifications.`,
+        description: getDesc("gufi_schema"),
         inputSchema: {
             type: "object",
             properties: {
@@ -182,26 +178,7 @@ Use this to understand the data structure before creating queries or modificatio
     },
     {
         name: "gufi_docs",
-        description: `Read documentation about Gufi. Use this when you need detailed information about specific topics.
-
-Available topics:
-- "overview" - Overview and workflow (start here)
-- "architecture" - Technical architecture
-- "modules" - Module system and entities
-- "fields" - Field types and CB builders (IMPORTANT for data operations)
-- "views" - View system, SDK, and React components
-- "automations" - Automations and worker
-- "api" - API endpoints reference
-- "packages" - Packages and marketplace
-- "errors" - Common errors and solutions
-- "examples" - Practical code examples
-
-You can also search across all docs with the search parameter.
-
-Examples:
-- gufi_docs({ topic: "fields" }) - Read about field types
-- gufi_docs({ topic: "errors" }) - Common errors and fixes
-- gufi_docs({ search: "currency" }) - Search for currency info`,
+        description: getDesc("gufi_docs"),
         inputSchema: {
             type: "object",
             properties: {
@@ -215,12 +192,12 @@ Examples:
     // ─────────────────────────────────────────────────────────────────────────
     {
         name: "gufi_companies",
-        description: "List all companies the user has access to. Returns company IDs, names, and creation dates.",
+        description: getDesc("gufi_companies"),
         inputSchema: { type: "object", properties: {} },
     },
     {
         name: "gufi_company_create",
-        description: "Create a new company. Returns the new company ID.",
+        description: getDesc("gufi_company_create"),
         inputSchema: {
             type: "object",
             properties: {
@@ -234,7 +211,7 @@ Examples:
     // ─────────────────────────────────────────────────────────────────────────
     {
         name: "gufi_modules",
-        description: "List all modules of a company. Modules define the data structure (entities, fields, relations). Returns module IDs, names, and entity counts.",
+        description: getDesc("gufi_modules"),
         inputSchema: {
             type: "object",
             properties: {
@@ -245,26 +222,7 @@ Examples:
     },
     {
         name: "gufi_module",
-        description: `Get the full JSON definition of a module. Auto-detects company from module ID.
-
-Returns the complete module structure:
-- name, displayName, icon
-- submodules[]: Array of submodules
-  - entities[]: Array of entities (tables)
-    - name, label, kind
-    - fields[]: Array of fields with type, label, required, options, etc.
-
-Field types (from @gufi/column-types):
-- Text: text, email, url, barcode
-- Numbers: number_int, number_float, percentage
-- Date/Time: date, datetime, time
-- Boolean: boolean
-- Selection: select (single), multiselect (array)
-- Relations: relation (FK), reversed_relation (virtual), users (array of user IDs)
-- Complex (JSONB): currency, phone, location, file, signature, json
-- Computed: formula, mirror
-
-Each type has specific format. Use gufi.CB.* builders for correct format.`,
+        description: getDesc("gufi_module"),
         inputSchema: {
             type: "object",
             properties: {
@@ -275,33 +233,7 @@ Each type has specific format. Use gufi.CB.* builders for correct format.`,
     },
     {
         name: "gufi_module_update",
-        description: `Update a module's JSON definition. Use this to add/modify entities, fields, relations.
-
-IMPORTANT: Always read the module first with gufi_module, modify the JSON, then update.
-
-Common modifications:
-- Add a field: Add to entity.fields array
-- Add an entity: Add to submodule.entities array
-- Modify field: Change properties like type, label, required, options
-
-Example field definition:
-{
-  "name": "fecha_entrega",
-  "type": "date",
-  "label": "Fecha de Entrega",
-  "required": false
-}
-
-For select fields, include options:
-{
-  "name": "estado",
-  "type": "select",
-  "label": "Estado",
-  "options": [
-    { "value": "pendiente", "label": "Pendiente", "color": "yellow" },
-    { "value": "completado", "label": "Completado", "color": "green" }
-  ]
-}`,
+        description: getDesc("gufi_module_update"),
         inputSchema: {
             type: "object",
             properties: {
@@ -313,28 +245,7 @@ For select fields, include options:
     },
     {
         name: "gufi_module_create",
-        description: `Create a new module in a company.
-
-Example module structure:
-{
-  "name": "inventory",
-  "displayName": "Inventario",
-  "icon": "Package",
-  "submodules": [{
-    "name": "products",
-    "label": "Productos",
-    "entities": [{
-      "name": "productos",
-      "label": "Productos",
-      "kind": "table",
-      "fields": [
-        { "name": "nombre", "type": "text", "label": "Nombre", "required": true },
-        { "name": "precio", "type": "currency", "label": "Precio" },
-        { "name": "stock", "type": "number_int", "label": "Stock" }
-      ]
-    }]
-  }]
-}`,
+        description: getDesc("gufi_module_create"),
         inputSchema: {
             type: "object",
             properties: {
@@ -349,14 +260,7 @@ Example module structure:
     // ─────────────────────────────────────────────────────────────────────────
     {
         name: "gufi_automations",
-        description: `List all automation scripts of a company. Automations are JavaScript functions that run on events.
-
-Trigger types:
-- on_create: Runs when a row is created
-- on_update: Runs when a row is updated
-- on_delete: Runs when a row is deleted
-- on_click: Manually triggered from UI buttons
-- schedule: Runs on a cron schedule`,
+        description: getDesc("gufi_automations"),
         inputSchema: {
             type: "object",
             properties: {
@@ -367,7 +271,7 @@ Trigger types:
     },
     {
         name: "gufi_automation",
-        description: "Get the JavaScript code and metadata of an automation script. Returns id, name, description, company_id, and the full JS code.",
+        description: getDesc("gufi_automation"),
         inputSchema: {
             type: "object",
             properties: {
@@ -378,32 +282,7 @@ Trigger types:
     },
     {
         name: "gufi_automation_create",
-        description: `Create or update an automation script. If a script with the same name exists, it will be updated.
-
-IMPORTANT: api.query() returns rows directly, NOT { rows }:
-  const rows = await api.query("SELECT * FROM table");  // ✅ Correct
-  const { rows } = await api.query(...);                // ❌ Wrong!
-
-Available API methods:
-- api.query(sql, params) - Execute SQL, returns rows array
-- api.getOne(table, id) - Get single row
-- api.getList(table, { filters, sort, limit }) - Get multiple rows
-- api.create(table, data) - Create row, returns { id }
-- api.update(table, id, data) - Update row
-- api.delete(table, id) - Delete row
-- api.log(message) - Log for debugging
-- api.sendEmail({ to, subject, body }) - Send email
-- api.sendWhatsApp({ to, template, params }) - Send WhatsApp
-
-Example automation:
-async function send_welcome_email({ record, api }) {
-  const { email, nombre } = record;
-  await api.sendEmail({
-    to: email,
-    subject: "Bienvenido!",
-    body: \`Hola \${nombre}, gracias por registrarte.\`
-  });
-}`,
+        description: getDesc("gufi_automation_create"),
         inputSchema: {
             type: "object",
             properties: {
@@ -417,7 +296,7 @@ async function send_welcome_email({ record, api }) {
     },
     {
         name: "gufi_entity_automations",
-        description: "Get the automation triggers configured for an entity. Shows which scripts run on create, update, delete, or click events.",
+        description: getDesc("gufi_entity_automations"),
         inputSchema: {
             type: "object",
             properties: {
@@ -428,19 +307,7 @@ async function send_welcome_email({ record, api }) {
     },
     {
         name: "gufi_entity_automations_update",
-        description: `Update the automation triggers for an entity. Configure which scripts run on which events.
-
-Example configuration:
-{
-  "on_create": ["send_welcome_email"],
-  "on_update": ["sync_to_external", "notify_changes"],
-  "on_delete": [],
-  "on_click": [
-    { "function_name": "generate_report", "label": "Generar Reporte", "icon": "FileText" }
-  ]
-}
-
-For on_click, you can specify label and icon for the button that triggers it.`,
+        description: getDesc("gufi_entity_automations_update"),
         inputSchema: {
             type: "object",
             properties: {
@@ -455,7 +322,7 @@ For on_click, you can specify label and icon for the button that triggers it.`,
     },
     {
         name: "gufi_automations_executions",
-        description: "Get the execution history of automations. Useful for debugging - shows success/failure, duration, and error messages.",
+        description: getDesc("gufi_automations_executions"),
         inputSchema: {
             type: "object",
             properties: {
@@ -471,13 +338,7 @@ For on_click, you can specify label and icon for the button that triggers it.`,
     // ─────────────────────────────────────────────────────────────────────────
     {
         name: "gufi_rows",
-        description: `List rows from a table. Table names follow the pattern m{moduleId}_t{entityId}.
-Company is auto-detected from the module ID in the table name.
-
-Supports:
-- Pagination: limit (default 20), offset (default 0)
-- Sorting: sort (field name), order (ASC/DESC)
-- Filtering: filter="field=value"`,
+        description: getDesc("gufi_rows"),
         inputSchema: {
             type: "object",
             properties: {
@@ -493,7 +354,7 @@ Supports:
     },
     {
         name: "gufi_row",
-        description: "Get a single row by ID. Returns all fields including relations and computed values.",
+        description: getDesc("gufi_row"),
         inputSchema: {
             type: "object",
             properties: {
@@ -505,35 +366,7 @@ Supports:
     },
     {
         name: "gufi_row_create",
-        description: `Create a new row in a table. Data should match the entity's field schema.
-
-Field formats (from @gufi/column-types):
-
-SIMPLE TYPES:
-- text/email/url/barcode: "string value"
-- number_int: 42 (integer)
-- number_float: 3.14 (decimal)
-- percentage: 0.75 (decimal, displayed as 75%)
-- boolean: true/false
-- date: "2024-01-15" (ISO date)
-- datetime: "2024-01-15T10:30:00Z" (ISO)
-- time: "14:30:00"
-- select: "value" (option value, not label)
-- relation: 123 (FK integer)
-
-ARRAY TYPES:
-- multiselect: ["value1", "value2"]
-- users: [16, 23] (array of user IDs)
-
-JSONB TYPES (complex objects):
-- currency: { "currency": "EUR", "amount": 150.00 }
-- phone: { "prefix": "+34", "number": "612345678" }
-- location: { "street": "Mayor", "number": "15", "city": "Madrid", "lat": 40.41, "lng": -3.70 }
-- file: [{ "url": "company_130/uuid.pdf", "name": "doc.pdf" }] or ["company_130/photo.jpg"]
-- signature: "data:image/png;base64,..." (base64 data URL)
-- json: { any: "object" }
-
-In views, use gufi.CB.* builders for correct formatting.`,
+        description: getDesc("gufi_row_create"),
         inputSchema: {
             type: "object",
             properties: {
@@ -545,20 +378,7 @@ In views, use gufi.CB.* builders for correct formatting.`,
     },
     {
         name: "gufi_row_update",
-        description: `Update an existing row. Only include fields you want to change.
-
-IMPORTANT for select/relation fields:
-When updating a select or relation field, you must update BOTH:
-- The field value: "estado": "completado"
-- The display value: "estado__display": "Completado"
-
-Example:
-{
-  "estado": "completado",
-  "estado__display": "Completado",
-  "cliente": 123,
-  "cliente__display": "Empresa ABC"
-}`,
+        description: getDesc("gufi_row_update"),
         inputSchema: {
             type: "object",
             properties: {
@@ -571,7 +391,7 @@ Example:
     },
     {
         name: "gufi_row_delete",
-        description: "Delete a row from a table. This is permanent and cannot be undone.",
+        description: getDesc("gufi_row_delete"),
         inputSchema: {
             type: "object",
             properties: {
@@ -586,7 +406,7 @@ Example:
     // ─────────────────────────────────────────────────────────────────────────
     {
         name: "gufi_env",
-        description: "List environment variables of a company. These are used in automations via process.env.KEY.",
+        description: getDesc("gufi_env"),
         inputSchema: {
             type: "object",
             properties: {
@@ -596,7 +416,7 @@ Example:
     },
     {
         name: "gufi_env_set",
-        description: "Create or update an environment variable. Used for API keys, secrets, and configuration.",
+        description: getDesc("gufi_env_set"),
         inputSchema: {
             type: "object",
             properties: {
@@ -608,7 +428,7 @@ Example:
     },
     {
         name: "gufi_env_delete",
-        description: "Delete an environment variable.",
+        description: getDesc("gufi_env_delete"),
         inputSchema: {
             type: "object",
             properties: {
@@ -622,7 +442,7 @@ Example:
     // ─────────────────────────────────────────────────────────────────────────
     {
         name: "gufi_view_files",
-        description: "Get all files of a marketplace view. Returns the React/TypeScript code, CSS, and configuration files.",
+        description: getDesc("gufi_view_files"),
         inputSchema: {
             type: "object",
             properties: {
@@ -633,7 +453,7 @@ Example:
     },
     {
         name: "gufi_view_file_update",
-        description: "Update a single file in a marketplace view. Use for modifying React components, styles, or configuration.",
+        description: getDesc("gufi_view_file_update"),
         inputSchema: {
             type: "object",
             properties: {
@@ -646,7 +466,7 @@ Example:
     },
     {
         name: "gufi_view_files_update",
-        description: "Update multiple files in a marketplace view at once. More efficient than updating one by one.",
+        description: getDesc("gufi_view_files_update"),
         inputSchema: {
             type: "object",
             properties: {
@@ -672,12 +492,12 @@ Example:
     // ─────────────────────────────────────────────────────────────────────────
     {
         name: "gufi_packages",
-        description: "List all packages owned by the user. Packages bundle modules and views for distribution in the Marketplace.",
+        description: getDesc("gufi_packages"),
         inputSchema: { type: "object", properties: {} },
     },
     {
         name: "gufi_package",
-        description: "Get detailed information about a package including its modules, views, and publication status.",
+        description: getDesc("gufi_package"),
         inputSchema: {
             type: "object",
             properties: {
@@ -688,7 +508,7 @@ Example:
     },
     {
         name: "gufi_package_create",
-        description: "Create a new package. After creation, add modules and views to it.",
+        description: getDesc("gufi_package_create"),
         inputSchema: {
             type: "object",
             properties: {
@@ -700,7 +520,7 @@ Example:
     },
     {
         name: "gufi_package_delete",
-        description: "Delete a package. Only works if the package is not published.",
+        description: getDesc("gufi_package_delete"),
         inputSchema: {
             type: "object",
             properties: {
@@ -711,7 +531,7 @@ Example:
     },
     {
         name: "gufi_package_add_module",
-        description: "Import a module into a package. The module will be snapshotted for distribution.",
+        description: getDesc("gufi_package_add_module"),
         inputSchema: {
             type: "object",
             properties: {
@@ -724,7 +544,7 @@ Example:
     },
     {
         name: "gufi_package_remove_module",
-        description: "Remove a module from a package.",
+        description: getDesc("gufi_package_remove_module"),
         inputSchema: {
             type: "object",
             properties: {
@@ -736,7 +556,7 @@ Example:
     },
     {
         name: "gufi_package_add_view",
-        description: "Add a marketplace view to a package.",
+        description: getDesc("gufi_package_add_view"),
         inputSchema: {
             type: "object",
             properties: {
@@ -748,7 +568,7 @@ Example:
     },
     {
         name: "gufi_package_remove_view",
-        description: "Remove a view from a package.",
+        description: getDesc("gufi_package_remove_view"),
         inputSchema: {
             type: "object",
             properties: {
@@ -760,7 +580,7 @@ Example:
     },
     {
         name: "gufi_package_publish",
-        description: "Publish a package to the Marketplace. Makes it available for installation by other companies.",
+        description: getDesc("gufi_package_publish"),
         inputSchema: {
             type: "object",
             properties: {
@@ -771,7 +591,7 @@ Example:
     },
     {
         name: "gufi_package_unpublish",
-        description: "Unpublish a package from the Marketplace.",
+        description: getDesc("gufi_package_unpublish"),
         inputSchema: {
             type: "object",
             properties: {
@@ -782,7 +602,7 @@ Example:
     },
     {
         name: "gufi_package_sync",
-        description: "Sync package version - updates module snapshots and increments version number.",
+        description: getDesc("gufi_package_sync"),
         inputSchema: {
             type: "object",
             properties: {
@@ -793,7 +613,7 @@ Example:
     },
     {
         name: "gufi_package_check",
-        description: "Check if package modules have changes that need syncing.",
+        description: getDesc("gufi_package_check"),
         inputSchema: {
             type: "object",
             properties: {
@@ -807,7 +627,7 @@ Example:
     // ─────────────────────────────────────────────────────────────────────────
     {
         name: "gufi_package_migrations",
-        description: "List SQL migrations for a package. Migrations run when clients update to new versions.",
+        description: getDesc("gufi_package_migrations"),
         inputSchema: {
             type: "object",
             properties: {
@@ -818,7 +638,7 @@ Example:
     },
     {
         name: "gufi_package_migration_create",
-        description: "Create a SQL migration for a package. Use placeholders: {tableName}, {entityId}, {companyId}.",
+        description: getDesc("gufi_package_migration_create"),
         inputSchema: {
             type: "object",
             properties: {
@@ -834,7 +654,7 @@ Example:
     },
     {
         name: "gufi_package_migration_delete",
-        description: "Delete a migration (only if not yet applied to any installation).",
+        description: getDesc("gufi_package_migration_delete"),
         inputSchema: {
             type: "object",
             properties: {
@@ -846,7 +666,7 @@ Example:
     },
     {
         name: "gufi_package_entities",
-        description: "List entities available in a package. Use for target_entity in migrations.",
+        description: getDesc("gufi_package_entities"),
         inputSchema: {
             type: "object",
             properties: {
@@ -927,11 +747,117 @@ async function detectCompanyFromTable(table) {
     const result = await detectCompanyFromModule(moduleId);
     return result?.companyId;
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// Context Auto-Detection Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Detect if we're inside the gogufi codebase (for internal development)
+ * Checks for presence of key directories: backend/, frontend/, tools/cli/, CLAUDE.md
+ */
+function detectIfInGufiCodebase() {
+    try {
+        const cwd = process.cwd();
+        const indicators = [
+            path.join(cwd, "backend"),
+            path.join(cwd, "frontend"),
+            path.join(cwd, "tools", "cli"),
+            path.join(cwd, "CLAUDE.md"),
+        ];
+        const matches = indicators.filter((p) => fs.existsSync(p));
+        return matches.length >= 3; // If 3+ indicators exist, it's the codebase
+    }
+    catch {
+        return false;
+    }
+}
+function loadViewMetaFromCwd() {
+    try {
+        const metaPath = path.join(process.cwd(), ".gufi-view.json");
+        if (fs.existsSync(metaPath)) {
+            return JSON.parse(fs.readFileSync(metaPath, "utf-8"));
+        }
+    }
+    catch { }
+    return null;
+}
 // Tool handler implementations
 const toolHandlers = {
     // ─────────────────────────────────────────────────────────────────────────
     // Context & Info
     // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Smart entrypoint that auto-detects context and provides guidance
+     */
+    async gufi_start() {
+        // 1. Check if we're in the gogufi codebase (internal development)
+        if (detectIfInGufiCodebase()) {
+            return {
+                detected: "gogufi_codebase",
+                summary: "You are inside the Gufi codebase. This is for INTERNAL platform development.",
+                what_to_read: {
+                    first: "docs/claude/01-critical-rules.md - MUST READ (deployment, notificaciones, traducciones)",
+                    architecture: "docs/claude/02-architecture.md",
+                    patterns: "docs/claude/07-patterns.md - Common errors and patterns",
+                },
+                important_rules: {
+                    hot_reload: "Frontend and backend auto-reload on save. DON'T restart manually.",
+                    column_types: "After libs/column-types changes: cd libs/column-types && npm run build",
+                    no_deploy: "NEVER deploy to production without explicit user request.",
+                    notifications: "Use toastSuccess/toastError from @/shared/notifications/toast (NOT shadcn)",
+                    translations: "Add to es.ts AND en.ts BEFORE using tUI()",
+                },
+                for_client_work: "If you need to work on packages/views, use: gufi_context({ package_id: 'X' })",
+            };
+        }
+        // 2. Check if we're in a view directory (.gufi-view.json)
+        const viewMeta = loadViewMetaFromCwd();
+        if (viewMeta) {
+            const context = await generateViewContextMcp(viewMeta.viewId, false);
+            return {
+                detected: "view_directory",
+                summary: `Working on view "${viewMeta.viewName}" (ID: ${viewMeta.viewId})`,
+                ...context,
+                workflow: {
+                    edit: "Edit files with your editor, changes will sync",
+                    watch: "Run: gufi view:watch (auto-syncs on save)",
+                    push: "Manual push: gufi view:push",
+                    logs: "View logs: gufi view:logs",
+                },
+            };
+        }
+        // 3. Fallback: List packages and guide
+        try {
+            const response = await developerRequest("/my-packages");
+            const packages = response.data || [];
+            return {
+                detected: "none",
+                summary: `No specific context detected. You have ${packages.length} package(s).`,
+                packages: packages.map((p) => ({
+                    id: p.pk_id,
+                    name: p.name,
+                    version: p.version,
+                    status: p.status,
+                })),
+                how_to_start: [
+                    "Get package context: gufi_context({ package_id: 'X' })",
+                    "Get view context: gufi_context({ view_id: 'Y' })",
+                    "Pull a view locally: gufi view:pull <id>",
+                    "Then gufi_start will auto-detect",
+                ],
+                if_building_new: [
+                    "Create package: gufi_package_create({ name: 'My Package' })",
+                    "Then add modules and views",
+                ],
+            };
+        }
+        catch {
+            return {
+                detected: "none",
+                summary: "Could not fetch packages. Make sure you're logged in.",
+                hint: "Run: gufi login",
+            };
+        }
+    },
     async gufi_whoami() {
         const config = loadConfig();
         return {
@@ -953,18 +879,57 @@ const toolHandlers = {
             return generateCompanyContextMcp(parseInt(params.company_id), params.full);
         }
         else {
-            // Return packages overview as fallback
+            // Auto-detect context from current directory
+            // 1. Check if we're in the gogufi codebase
+            if (detectIfInGufiCodebase()) {
+                return {
+                    type: "codebase",
+                    summary: "You are inside the Gufi codebase (gogufi/). This is for INTERNAL development of the platform.",
+                    what_to_do: {
+                        for_codebase_work: [
+                            "Read docs/claude/01-critical-rules.md FIRST (deployment rules, notificaciones, traducciones)",
+                            "Architecture: docs/claude/02-architecture.md",
+                            "Patterns & errors: docs/claude/07-patterns.md",
+                        ],
+                        for_client_work: [
+                            "To work on a specific package: gufi_context({ package_id: 'X' })",
+                            "To work on a specific view: gufi_context({ view_id: 'Y' })",
+                            "List your packages: gufi_packages()",
+                        ],
+                    },
+                    important_rules: {
+                        hot_reload: "Frontend and backend auto-reload on file save. DON'T restart manually.",
+                        column_types: "After changes to libs/column-types: cd libs/column-types && npm run build",
+                        no_deploy: "NEVER deploy to production without explicit request from user.",
+                    },
+                    docs_structure: {
+                        "docs/claude/": "For INTERNAL codebase development (you are here)",
+                        "docs/mcp/": "For platform USERS (consultants building ERPs) - used by gufi_docs tool",
+                    },
+                };
+            }
+            // 2. Check if we're in a view directory (.gufi-view.json)
+            const viewMeta = loadViewMetaFromCwd();
+            if (viewMeta) {
+                return generateViewContextMcp(viewMeta.viewId, params.full);
+            }
+            // 3. Fallback: Return packages overview
             const response = await developerRequest("/my-packages");
             const packages = response.data || [];
             return {
                 type: "packages_overview",
+                summary: `You have ${packages.length} package(s). Specify one to get detailed context.`,
                 packages: packages.map((p) => ({
                     id: p.pk_id,
                     name: p.name,
                     version: p.version,
                     status: p.status,
                 })),
-                hint: "Specify package_id, view_id, or company_id for detailed context",
+                next_actions: [
+                    "Get package context: gufi_context({ package_id: 'X' })",
+                    "Get view context: gufi_context({ view_id: 'Y' })",
+                    "Pull a view locally: gufi view:pull <id> (then gufi_context will auto-detect)",
+                ],
             };
         }
     },
@@ -1354,6 +1319,15 @@ const toolHandlers = {
                 content: f.content,
                 is_entry_point: f.is_entry_point,
             })),
+            _hint: {
+                cli_workflow: [
+                    `gufi view:pull ${params.view_id}  # Download files to local folder`,
+                    "# Edit files locally with your editor",
+                    "gufi view:push                    # Upload changes back to Gufi",
+                    "gufi view:watch                   # Auto-sync on file changes",
+                ],
+                note: "For large views, consider using CLI commands instead of MCP tools",
+            },
         };
     },
     async gufi_view_file_update(params) {
@@ -1592,8 +1566,33 @@ async function generateViewContextMcp(viewId, includeConcepts) {
             tableStructures[dsKey] = tableInfo;
         }
     }
+    // Build summary and next_actions
+    const dsCount = Object.keys(dataSources).length;
+    const autoCount = automations.length;
+    const firstTable = Object.values(dataSources)[0];
+    const summary = [
+        `View "${view.name}" (ID: ${viewId})`,
+        pkg ? `Package: "${pkg.name}"` : "Independent view",
+        dsCount > 0 ? `${dsCount} dataSource(s): ${Object.keys(dataSources).join(", ")}` : "No dataSources configured",
+        autoCount > 0 ? `${autoCount} automation(s) available` : "No automations",
+    ].join(" | ");
+    const nextActions = [];
+    // Always first: pull for local editing
+    nextActions.push(`Edit locally: gufi view:pull ${viewId} && gufi view:watch`);
+    // If has tables, suggest viewing data
+    if (firstTable) {
+        nextActions.push(`View data: gufi_rows({ table: "${firstTable}", limit: 5 })`);
+    }
+    // If has automations, suggest viewing them
+    if (autoCount > 0 && viewCompanyId) {
+        nextActions.push(`See automations: gufi_automations({ company_id: "${viewCompanyId}" })`);
+    }
+    // Always: docs for field types
+    nextActions.push(`Field types reference: gufi_docs({ topic: "fields" })`);
     const result = {
         type: "view",
+        summary,
+        next_actions: nextActions,
         view_id: viewId,
         name: view.name,
         view_type: view.view_type || "marketplace_view",
@@ -1639,8 +1638,33 @@ async function generatePackageContextMcp(packageId, includeConcepts) {
             source_module_id: mod.source_module_id,
         });
     }
+    // Build summary and next_actions
+    const summary = [
+        `Package "${pkg.name}" (ID: ${packageId})`,
+        `Version: ${pkg.version || "0.1.0"}`,
+        `Status: ${pkg.status || "draft"}`,
+        `${modulesInfo.length} module(s)`,
+        `${views.length} view(s)`,
+    ].join(" | ");
+    const nextActions = [];
+    // If has views, suggest editing one
+    if (views.length > 0) {
+        const firstView = views[0];
+        nextActions.push(`Edit a view: gufi view:pull ${firstView.view_id} && gufi view:watch`);
+        nextActions.push(`Get view context: gufi_context({ view_id: "${firstView.view_id}" })`);
+    }
+    // If has sandbox company, suggest exploring data
+    if (pkg.sandbox_company_id) {
+        nextActions.push(`Explore sandbox data: gufi_schema({ company_id: "${pkg.sandbox_company_id}" })`);
+    }
+    // If draft, suggest publishing workflow
+    if (pkg.status === "draft" || !pkg.status) {
+        nextActions.push(`When ready: gufi package:sync ${packageId} && gufi package:publish ${packageId}`);
+    }
     const result = {
         type: "package",
+        summary,
+        next_actions: nextActions,
         package_id: packageId,
         name: pkg.name,
         version: pkg.version || "0.1.0",
@@ -1714,8 +1738,35 @@ async function generateCompanyContextMcp(companyId, includeConcepts) {
             entities,
         });
     }
+    // Build summary and next_actions
+    const totalEntities = modulesInfo.reduce((acc, m) => acc + (m.entities?.length || 0), 0);
+    const summary = [
+        `Company ID: ${companyId}`,
+        `${modulesInfo.length} module(s)`,
+        `${totalEntities} table(s)`,
+        `${automations.length} automation(s)`,
+    ].join(" | ");
+    const nextActions = [];
+    // Suggest viewing data from first table
+    if (modulesInfo.length > 0 && modulesInfo[0].entities?.length > 0) {
+        const firstTable = modulesInfo[0].entities[0].table;
+        if (firstTable) {
+            nextActions.push(`View data: gufi_rows({ table: "${firstTable}", limit: 5 })`);
+        }
+    }
+    // If has modules, suggest editing one
+    if (modulesInfo.length > 0 && modulesInfo[0].id) {
+        nextActions.push(`Edit module structure: gufi_module({ module_id: "${modulesInfo[0].id}" })`);
+    }
+    // If has automations, suggest viewing them
+    if (automations.length > 0) {
+        nextActions.push(`View automation code: gufi_automation({ automation_id: "${automations[0].id}" })`);
+    }
+    nextActions.push(`Field types reference: gufi_docs({ topic: "fields" })`);
     const result = {
         type: "company",
+        summary,
+        next_actions: nextActions,
         company_id: companyId,
         modules: modulesInfo,
         automations: automations.map((a) => ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gufi-cli",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "CLI for developing Gufi Marketplace views locally with Claude Code",
   "bin": {
     "gufi": "./bin/gufi.js"