gufi-cli 0.1.49 → 0.1.51

package/dist/commands/docs.js

@@ -9,12 +9,8 @@
  */
 import * as fs from "fs";
 import * as path from "path";
-import { fileURLToPath } from "url";
 import chalk from "chalk";
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-// docs/mcp path relative to CLI
-const DOCS_MCP_PATH = path.resolve(__dirname, "../../../../docs/mcp");
+import { DOCS_MCP_PATH } from "../lib/docs-resolver.js";
 // Topic to file mapping
 const TOPIC_FILES = {
     overview: { file: "00-overview.md", description: "Overview and workflow" },

package/dist/lib/docs-resolver.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Resolves documentation paths for both development (monorepo) and global install.
+ *
+ * - Global install: docs are bundled at <pkg>/docs/
+ * - Development:    docs live at <monorepo>/docs/
+ */
+export declare const DOCS_MCP_PATH: string;
+export declare const DOCS_DEV_GUIDE_PATH: string;

package/dist/lib/docs-resolver.js

@@ -0,0 +1,27 @@
+/**
+ * Resolves documentation paths for both development (monorepo) and global install.
+ *
+ * - Global install: docs are bundled at <pkg>/docs/
+ * - Development:    docs live at <monorepo>/docs/
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Package root: from dist/lib/ go up 2 levels
+const PKG_ROOT = path.resolve(__dirname, "../..");
+function resolveDocsPath(subdir) {
+    // 1. Package-local (global install): <pkg>/docs/<subdir>
+    const localPath = path.join(PKG_ROOT, "docs", subdir);
+    if (fs.existsSync(localPath))
+        return localPath;
+    // 2. Monorepo (development): <pkg>/../../docs/<subdir>
+    const monorepoPath = path.resolve(PKG_ROOT, "../../docs", subdir);
+    if (fs.existsSync(monorepoPath))
+        return monorepoPath;
+    // Fallback to local path (will fail gracefully downstream)
+    return localPath;
+}
+export const DOCS_MCP_PATH = resolveDocsPath("mcp");
+export const DOCS_DEV_GUIDE_PATH = resolveDocsPath("dev-guide");

package/dist/lib/security.js

@@ -114,6 +114,11 @@ const ALLOWED_PATTERNS = [
     // CSRF token reading from cookies - legitimate security practice
     /csrf-token/i,
     /getCsrfToken/,
+    // Auth cookie management - legitimate for ecommerce auth
+    /strong_store_auth/,
+    /setAuthCookie/,
+    /clearAuthCookie/,
+    /document\.cookie/,
 ];
 /**
  * Scan a file for suspicious patterns

package/dist/mcp.js

@@ -48,10 +48,8 @@ const COLUMN_TYPE_NAMES = [
 // For ES modules __dirname equivalent
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-// docs/mcp path relative to CLI
-const DOCS_MCP_PATH = path.resolve(__dirname, "../../../docs/mcp");
-// docs/dev-guide path for integration docs
-const DOCS_DEV_GUIDE_PATH = path.resolve(__dirname, "../../../docs/dev-guide");
+// Docs paths - resolved for both global install and monorepo dev
+import { DOCS_MCP_PATH, DOCS_DEV_GUIDE_PATH } from "./lib/docs-resolver.js";
 /**
  * Parse frontmatter from markdown content
  */
@@ -502,22 +500,24 @@ const SCHEMA_CACHE_TTL = 5 * 60 * 1000; // 5 minutes
 const PHYSICAL_TABLE_RE = /^m\d+_t\d+$/;
 /**
  * Get company schema (cached)
+ * Returns { schema, error } - error is set if fetch failed
  */
 async function getCompanySchema(companyId, env) {
     // Include env in cache key to avoid mixing schemas from different environments
     const cacheKey = `${companyId}:${env || 'prod'}`;
     const cached = schemaCache.get(cacheKey);
     if (cached && Date.now() - cached.timestamp < SCHEMA_CACHE_TTL) {
-        return cached.schema;
+        return { schema: cached.schema };
     }
     try {
         const data = await apiRequest("/api/cli/schema", {}, companyId, true, env);
         schemaCache.set(cacheKey, { schema: data, timestamp: Date.now() });
-        return data;
+        return { schema: data };
     }
     catch (err) {
-        console.error(`[MCP] Failed to get schema for company ${companyId}:`, err.message);
-        return null;
+        const errorMsg = err.message;
+        console.error(`[MCP] Failed to get schema for company ${companyId}:`, errorMsg);
+        return { schema: null, error: errorMsg };
     }
 }
 /**
@@ -538,19 +538,20 @@ async function resolveTableName(tableName, companyId, env) {
         throw new Error(`Invalid table name: "${tableName}". Use physical (m123_t456) or logical (module.entity) format`);
     }
     const [moduleName, entityName] = parts;
-    const schema = await getCompanySchema(companyId, env);
+    const { schema, error } = await getCompanySchema(companyId, env);
     if (!schema?.modules) {
-        throw new Error(`Cannot resolve logical table name "${tableName}": schema not available. Use physical name (m123_t456) instead`);
+        const reason = error || "unknown error";
+        throw new Error(`Cannot resolve logical table name "${tableName}": ${reason}`);
     }
     // Find module and entity
     for (const mod of schema.modules) {
         const modMatch = mod.name?.toLowerCase() === moduleName.toLowerCase() ||
-            mod.label?.toLowerCase() === moduleName.toLowerCase();
+            mod.display_name?.toLowerCase() === moduleName.toLowerCase();
         if (!modMatch)
             continue;
         for (const ent of mod.entities || []) {
             const entMatch = ent.name?.toLowerCase() === entityName.toLowerCase() ||
-                ent.label?.toLowerCase() === entityName.toLowerCase();
+                ent.display_name?.toLowerCase() === entityName.toLowerCase();
             if (entMatch) {
                 // Found! Build physical name from entity ID
                 const moduleId = mod.id;
@@ -856,20 +857,20 @@ Solo Admin y Consultant pueden gestionar endpoints.`,
         name: "gufi_view_pull",
         description: `📥 Download view files to local directory for editing.
 
-Downloads to: ~/gufi-dev/view_<id>/
+Downloads to: ~/gufi-dev/company_<id>/view_<id>/
 
 After pulling, use Read/Edit tools to work with local files.
 Then use gufi_view_push to upload changes.
 
-Example: gufi_view_pull({ view_id: 13 })`,
+Example: gufi_view_pull({ view_id: 13, company_id: '150' })`,
         inputSchema: {
             type: "object",
             properties: {
                 view_id: { type: "number", description: "View ID to pull" },
-                company_id: { type: "string", description: "Company ID (required for company-specific views)" },
+                company_id: { type: "string", description: "Company ID (required)" },
                 env: ENV_PARAM,
             },
-            required: ["view_id"],
+            required: ["view_id", "company_id"],
         },
     },
     // 📤 Push local changes to draft
@@ -1453,9 +1454,9 @@ const toolHandlers = {
         let tableName = null;
         // Resolve entity if provided (optional for standalone scripts)
         if (entity) {
-            const schema = await getCompanySchema(company_id, env);
+            const { schema, error } = await getCompanySchema(company_id, env);
             if (!schema?.modules) {
-                throw new Error("Cannot get schema. Make sure company_id is correct.");
+                throw new Error(`Cannot get schema: ${error || "unknown error"}`);
             }
             // Parse entity (module.entity format)
             const parts = entity.split(".");
@@ -1466,13 +1467,13 @@ const toolHandlers = {
             // Find module and entity IDs
             for (const mod of schema.modules) {
                 const modMatch = mod.name?.toLowerCase() === moduleName.toLowerCase() ||
-                    mod.label?.toLowerCase() === moduleName.toLowerCase();
+                    mod.display_name?.toLowerCase() === moduleName.toLowerCase();
                 if (!modMatch)
                     continue;
                 moduleId = mod.id;
                 for (const ent of mod.entities || []) {
                     const entMatch = ent.name?.toLowerCase() === entityName.toLowerCase() ||
-                        ent.label?.toLowerCase() === entityName.toLowerCase();
+                        ent.display_name?.toLowerCase() === entityName.toLowerCase();
                     if (entMatch) {
                         tableId = ent.id;
                         tableName = `m${moduleId}_t${tableId}`;
@@ -1785,7 +1786,9 @@ const toolHandlers = {
     // ─────────────────────────────────────────────────────────────────────────
     async gufi_view_pull(params) {
         const viewId = params.view_id;
-        const companyId = params.company_id;
+        const companyId = params.company_id != null ? String(params.company_id) : undefined;
+        if (!companyId)
+            throw new Error("company_id is required for view pull");
         const env = params.env;
         const useLocal = canWriteLocal();
         // Get view info
@@ -1798,8 +1801,8 @@ const toolHandlers = {
         const filesResponse = await apiRequest(`/api/marketplace/views/${viewId}/files`, {}, companyId, true, env);
         const files = Array.isArray(filesResponse) ? filesResponse : (filesResponse.data || []);
         if (useLocal) {
-            // 💜 CLI: Save to ~/gufi-dev/view_<id>/
-            const viewDir = path.join(LOCAL_VIEWS_DIR, `view_${viewId}`);
+            // 💜 CLI: Save to ~/gufi-dev/company_<id>/view_<id>/
+            const viewDir = path.join(LOCAL_VIEWS_DIR, `company_${companyId}`, `view_${viewId}`);
             fs.mkdirSync(viewDir, { recursive: true });
             // 💜 Get latest snapshot for version tracking
             let latestSnapshot;
@@ -1823,9 +1826,10 @@ const toolHandlers = {
             const meta = {
                 viewId,
                 viewName: `view_${viewId}`,
+                company_id: Number(companyId),
                 packageId: view.package_id || 0,
                 lastSync: new Date().toISOString(),
-                lastPulledSnapshot: latestSnapshot, // 💜 For version conflict detection
+                lastPulledSnapshot: latestSnapshot,
                 files: fileMeta,
             };
             fs.writeFileSync(path.join(viewDir, ".gufi-view.json"), JSON.stringify(meta, null, 2));
@@ -1837,7 +1841,7 @@ const toolHandlers = {
                 local_path: viewDir,
                 storage: "local",
                 files_count: files.length,
-                _hint: `📥 View downloaded to ${viewDir}/. Use Read/Edit tools to modify files. Then gufi_view_push({ view_id: ${viewId}, env: '${env || 'prod'}' }) to upload.`,
+                _hint: `📥 View downloaded to ${viewDir}/. Use Read/Edit tools to modify files. Then gufi_view_push({ view_id: ${viewId}, company_id: '${companyId}' }) to upload.`,
             };
         }
         else {
@@ -1871,33 +1875,42 @@ const toolHandlers = {
     },
     async gufi_view_push(params) {
         const viewId = params.view_id;
-        let companyId = params.company_id;
+        let companyId = params.company_id != null ? String(params.company_id) : undefined;
         const env = params.env;
         const useLocal = canWriteLocal();
+        if (!viewId) {
+            throw new Error("view_id is required");
+        }
         // 💜 Try to get company_id from view metadata if not provided
-        if (!companyId && viewId && useLocal) {
-            const metaPath = path.join(LOCAL_VIEWS_DIR, `view_${viewId}`, ".gufi-view.json");
-            if (fs.existsSync(metaPath)) {
-                try {
-                    const meta = JSON.parse(fs.readFileSync(metaPath, "utf-8"));
-                    if (meta.company_id)
-                        companyId = String(meta.company_id);
+        if (!companyId && useLocal) {
+            const companyDirs = fs.existsSync(LOCAL_VIEWS_DIR)
+                ? fs.readdirSync(LOCAL_VIEWS_DIR).filter(d => d.startsWith("company_"))
+                : [];
+            for (const cd of companyDirs) {
+                const metaPath = path.join(LOCAL_VIEWS_DIR, cd, `view_${viewId}`, ".gufi-view.json");
+                if (fs.existsSync(metaPath)) {
+                    try {
+                        const meta = JSON.parse(fs.readFileSync(metaPath, "utf-8"));
+                        if (meta.company_id)
+                            companyId = String(meta.company_id);
+                    }
+                    catch { /* ignore */ }
+                    break;
                 }
-                catch { /* ignore */ }
             }
         }
-        if (!viewId) {
-            throw new Error("view_id is required");
+        if (!companyId) {
+            throw new Error("company_id is required. Pass it as parameter or pull the view first.");
         }
         let files = [];
-        let lastPulledSnapshot; // 💜 For version conflict detection
+        let lastPulledSnapshot;
         if (useLocal) {
-            // 💜 CLI: Read from ~/gufi-dev/view_<id>/
-            const viewDir = path.join(LOCAL_VIEWS_DIR, `view_${viewId}`);
+            // 💜 CLI: Read from ~/gufi-dev/company_<id>/view_<id>/
+            const viewDir = path.join(LOCAL_VIEWS_DIR, `company_${companyId}`, `view_${viewId}`);
             if (!fs.existsSync(viewDir)) {
-                throw new Error(`View directory not found: ${viewDir}. Run gufi_view_pull first.`);
+                throw new Error(`View directory not found. Run gufi_view_pull({ view_id: ${viewId}, company_id: '${companyId}' }) first.`);
             }
-            // 💜 Read metadata for version tracking (backend handles the check)
+            // 💜 Read metadata for version tracking
             const metaPath = path.join(viewDir, ".gufi-view.json");
             if (fs.existsSync(metaPath)) {
                 try {
@@ -2018,7 +2031,7 @@ const toolHandlers = {
         }
         // 💜 Update local metadata with new snapshot number (for version tracking)
         if (useLocal && result.snapshot) {
-            const viewDir = path.join(LOCAL_VIEWS_DIR, `view_${viewId}`);
+            const viewDir = path.join(LOCAL_VIEWS_DIR, `company_${companyId}`, `view_${viewId}`);
             const metaPath = path.join(viewDir, ".gufi-view.json");
             if (fs.existsSync(metaPath)) {
                 try {
@@ -2556,7 +2569,7 @@ function findTableInModulesMcp(modules, tableName) {
                         fields: (ent.fields || []).map((f) => ({
                             name: f.name,
                             type: f.type,
-                            label: f.label,
+                            display_name: f.display_name,
                             required: f.required || false,
                             options: f.options?.map((o) => o.value || o),
                         })),

package/docs/dev-guide/1-01-architecture.md

@@ -0,0 +1,358 @@
+---
+id: architecture
+title: "Architecture Overview"
+description: "How Gufi is built and why"
+icon: Layers
+category: dev
+part: 1
+---
+
+# Architecture Overview
+
+How Gufi is built and why
+
+## System Architecture
+
+Gufi follows a modern microservices architecture optimized for multi-tenancy, real-time updates, and developer experience.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         CLIENTS                                 │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
+│  │  Web App │  │ Mobile   │  │   CLI    │  │   API    │        │
+│  │ (React)  │  │  (PWA)   │  │  (Node)  │  │ Clients  │        │
+│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘        │
+│       │             │             │             │               │
+└───────┼─────────────┼─────────────┼─────────────┼───────────────┘
+        │             │             │             │
+        ▼             ▼             ▼             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      LOAD BALANCER                              │
+└───────────────────────────┬─────────────────────────────────────┘
+                            │
+        ┌───────────────────┼───────────────────┐
+        │                   │                   │
+        ▼                   ▼                   ▼
+┌───────────────┐  ┌───────────────┐  ┌───────────────┐
+│  Backend ERP  │  │  Marketplace  │  │   WebSocket   │
+│   (Express)   │  │   Backend     │  │    Server     │
+│    :3000      │  │    :3003      │  │    :4000      │
+└───────┬───────┘  └───────┬───────┘  └───────┬───────┘
+        │                  │                   │
+        └──────────────────┼───────────────────┘
+                           │
+        ┌──────────────────┴──────────────────┐
+        │                                      │
+        ▼                                      ▼
+┌───────────────┐                    ┌───────────────┐
+│  PostgreSQL   │                    │     Redis     │
+│  (Primary DB) │                    │    (Cache)    │
+└───────────────┘                    └───────────────┘
+        │
+        ▼
+┌───────────────┐
+│    Worker     │
+│   (pg-boss)   │
+└───────────────┘
+```
+
+## Core Services
+
+### Backend ERP (Port 3000)
+
+The main API server handling:
+
+- Authentication and authorization
+- CRUD operations for all entities
+- Module and schema management
+- File uploads and storage
+- Business logic and validations
+
+**Tech Stack:**
+- Node.js with Express
+- JWT + HttpOnly cookie authentication
+- Zod for validation
+- pg (node-postgres) for database
+
+### Marketplace Backend (Port 3003)
+
+Handles marketplace-specific operations:
+
+- Package publishing and versioning
+- View code storage and retrieval
+- Developer accounts and billing
+- Cross-company module installations
+
+**Key Endpoints:**
+- `/packages` - Package CRUD
+- `/views` - Custom view management
+- `/developer` - Developer portal API
+
+### WebSocket Server (Port 4000)
+
+Real-time communication:
+
+- LISTEN/NOTIFY from PostgreSQL
+- Broadcasts changes to connected clients
+- Room-based subscriptions per company/table
+- Presence tracking
+
+**Protocol:**
+- Native WebSocket (not Socket.IO)
+- JSON message format
+- Heartbeat for connection health
+
+### Worker (pg-boss)
+
+Background job processing:
+
+- Scheduled automations
+- Email sending
+- Heavy computations
+- Data synchronization
+- External API calls
+
+**Features:**
+- Persistent job queue in PostgreSQL
+- Retry with exponential backoff
+- Dead letter queue for failures
+- Monitoring and alerting
+
+## Frontend Architecture
+
+### React Application
+
+Built with modern React patterns:
+
+```
+frontend/src/
+├── features/           # Feature-based organization
+│   ├── auth/          # Login, registration
+│   ├── tables/        # Table views and editing
+│   ├── modules/       # Module management
+│   └── ...
+├── shared/            # Shared components
+│   ├── ui/           # Base UI components
+│   ├── views/        # View system components
+│   ├── dialogs/      # Dialog components
+│   └── hooks/        # Custom hooks
+├── stores/           # Zustand state stores
+├── contexts/         # React contexts
+└── sdk/              # Gufi SDK for views
+```
+
+### State Management
+
+| Store | Purpose |
+|---|---|
+| **authStore** | User session, tokens |
+| **schemaStore** | Company schema cache |
+| **permissionsStore** | Permission cache |
+| **uiStore** | UI state (sidebar, dialogs) |
+
+Using Zustand for simple, type-safe state management.
+
+### Data Fetching
+
+Using Refine framework:
+
+- Automatic CRUD hooks
+- Caching and invalidation
+- Optimistic updates
+- Pagination helpers
+
+## Database Architecture
+
+### PostgreSQL as Core
+
+Why PostgreSQL:
+
+- JSONB for flexible schemas
+- Row-level security
+- LISTEN/NOTIFY for real-time
+- Excellent performance
+- Strong ACID compliance
+
+### Multi-Tenant Schema
+
+```
+PostgreSQL Instance
+├── core (schema)           # Platform data
+│   ├── users               # All users
+│   ├── companies           # All companies
+│   ├── modules             # Module definitions
+│   ├── entities            # Entity definitions
+│   └── automation_scripts  # Shared scripts
+│
+├── company_1 (schema)      # Company 1 data
+│   ├── m1_t1               # Module 1, Entity 1
+│   ├── m1_t2               # Module 1, Entity 2
+│   ├── __audit_log__       # Audit trail
+│   └── ...
+│
+├── company_2 (schema)      # Company 2 data
+│   └── ...
+└── ...
+```
+
+### Table Naming Convention
+
+Physical tables use IDs:
+
+```
+m{moduleId}_t{entityId}
+
+Example: m360_t4589
+         └── Module 360, Entity 4589
+```
+
+Logical names (products, customers) map to physical names via schema.
+
+## API Design
+
+### RESTful Endpoints
+
+```
+GET    /api/tables/:tableId           # List records
+GET    /api/tables/:tableId/:rowId    # Get record
+POST   /api/tables/:tableId           # Create record
+PUT    /api/tables/:tableId/:rowId    # Update record
+DELETE /api/tables/:tableId/:rowId    # Delete record
+```
+
+### Authentication Flow
+
+```
+1. Login → POST /api/auth/login
+   ← Access token (15min) + Refresh cookie (7days)
+
+2. API Request → GET /api/... + Authorization: Bearer {token}
+   ← Data response
+
+3. Token Expiring → POST /api/auth/refresh
+   ← New access token
+```
+
+### Response Format
+
+Success:
+```json
+{
+  "data": { ... },
+  "meta": {
+    "total": 100,
+    "page": 1,
+    "pageSize": 20
+  }
+}
+```
+
+Error:
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Price must be positive",
+    "details": { "field": "price" }
+  }
+}
+```
+
+## Security Model
+
+### Layers of Security
+
+1. **Network**: HTTPS, WAF, Rate limiting
+2. **Authentication**: JWT, refresh tokens, 2FA
+3. **Authorization**: Role-based, entity-level
+4. **Data**: Row-level security, tenant isolation
+5. **Audit**: Complete change tracking
+
+### Tenant Isolation
+
+Each request:
+
+```
+1. Extract company_id from JWT
+2. SET search_path TO company_{id}
+3. Execute query (sees only company data)
+4. RESET search_path
+```
+
+No cross-tenant queries possible at database level.
+
+## Caching Strategy
+
+### Redis Cache Layers
+
+| Layer | TTL | Purpose |
+|---|---|---|
+| **Schema** | 5 min | Company schemas |
+| **Permissions** | 1 min | User permissions |
+| **Queries** | 30 sec | Expensive queries |
+| **Sessions** | 7 days | User sessions |
+
+### Cache Invalidation
+
+Event-driven invalidation:
+
+```
+Record Changed → Invalidate related caches
+               → Notify WebSocket
+               → Clients refetch
+```
+
+## Deployment
+
+### Container Architecture
+
+```yaml
+services:
+  frontend:
+    image: gufi/frontend
+    ports: [5173, 8080]
+
+  backend:
+    image: gufi/backend
+    ports: [3000]
+    depends_on: [db, redis]
+
+  websocket:
+    image: gufi/websocket
+    ports: [4000]
+    depends_on: [db, redis]
+
+  worker:
+    image: gufi/worker
+    depends_on: [db, redis]
+
+  db:
+    image: postgres:15
+    volumes: [db_data]
+
+  redis:
+    image: redis:7
+```
+
+### Scaling
+
+| Component | Scale Strategy |
+|---|---|
+| Frontend | Horizontal (CDN + replicas) |
+| Backend | Horizontal (load balanced) |
+| WebSocket | Horizontal (Redis pub/sub) |
+| Worker | Horizontal (pg-boss handles) |
+| PostgreSQL | Vertical + Read replicas |
+| Redis | Cluster mode |
+
+## Performance Targets
+
+| Metric | Target |
+|---|---|
+| API Response (P95) | < 100ms |
+| Page Load | < 2s |
+| Time to Interactive | < 3s |
+| WebSocket Latency | < 50ms |
+| Database Query | < 50ms |
+
+Monitored continuously with alerting on degradation.