gufi-cli 0.1.50 → 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/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
  */
@@ -1806,11 +1804,6 @@ const toolHandlers = {
             // 💜 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 });
-            // 💜 Migrate: if old path exists (~/gufi-dev/view_<id>/), remove it
-            const oldViewDir = path.join(LOCAL_VIEWS_DIR, `view_${viewId}`);
-            if (fs.existsSync(oldViewDir)) {
-                fs.rmSync(oldViewDir, { recursive: true, force: true });
-            }
             // 💜 Get latest snapshot for version tracking
             let latestSnapshot;
             try {
@@ -1890,7 +1883,6 @@ const toolHandlers = {
         }
         // 💜 Try to get company_id from view metadata if not provided
         if (!companyId && useLocal) {
-            // Try new path first (company_*/view_*)
             const companyDirs = fs.existsSync(LOCAL_VIEWS_DIR)
                 ? fs.readdirSync(LOCAL_VIEWS_DIR).filter(d => d.startsWith("company_"))
                 : [];
@@ -1906,18 +1898,6 @@ const toolHandlers = {
                     break;
                 }
             }
-            // Fallback: old path (view_*)
-            if (!companyId) {
-                const oldMetaPath = path.join(LOCAL_VIEWS_DIR, `view_${viewId}`, ".gufi-view.json");
-                if (fs.existsSync(oldMetaPath)) {
-                    try {
-                        const meta = JSON.parse(fs.readFileSync(oldMetaPath, "utf-8"));
-                        if (meta.company_id)
-                            companyId = String(meta.company_id);
-                    }
-                    catch { /* ignore */ }
-                }
-            }
         }
         if (!companyId) {
             throw new Error("company_id is required. Pass it as parameter or pull the view first.");
@@ -1925,12 +1905,8 @@ const toolHandlers = {
         let files = [];
         let lastPulledSnapshot;
         if (useLocal) {
-            // 💜 CLI: Read from ~/gufi-dev/company_<id>/view_<id>/ (or legacy ~/gufi-dev/view_<id>/)
-            let viewDir = path.join(LOCAL_VIEWS_DIR, `company_${companyId}`, `view_${viewId}`);
-            if (!fs.existsSync(viewDir)) {
-                // Fallback to old path
-                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. Run gufi_view_pull({ view_id: ${viewId}, company_id: '${companyId}' }) first.`);
             }
@@ -2055,9 +2031,7 @@ const toolHandlers = {
         }
         // 💜 Update local metadata with new snapshot number (for version tracking)
         if (useLocal && result.snapshot) {
-            let viewDir = path.join(LOCAL_VIEWS_DIR, `company_${companyId}`, `view_${viewId}`);
-            if (!fs.existsSync(viewDir))
-                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 {

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.