@burgan-tech/vnext-workflow-cli 1.0.1 → 1.0.3

package/README.md

@@ -53,18 +53,62 @@ npm link
 
 ---
 
+## 📄 vnext.config.json (Required)
+
+Every vNext project must have a `vnext.config.json` file in the **project root**. This file defines the domain and component paths.
+
+### Example Configuration
+
+```json
+{
+  "version": "1.0.0",
+  "domain": "core",
+  "paths": {
+    "componentsRoot": "core",
+    "tasks": "Tasks",
+    "views": "Views",
+    "functions": "Functions",
+    "extensions": "Extensions",
+    "workflows": "Workflows",
+    "schemas": "Schemas"
+  }
+}
+```
+
+### Key Properties
+
+| Property | Description |
+|----------|-------------|
+| `domain` | Domain name used for API calls (replaces config's API_DOMAIN) |
+| `paths.componentsRoot` | Root folder where all components are located |
+| `paths.tasks` | Tasks folder name under componentsRoot |
+| `paths.workflows` | Workflows folder name under componentsRoot |
+| `paths.schemas` | Schemas folder name under componentsRoot |
+| `paths.views` | Views folder name under componentsRoot |
+| `paths.functions` | Functions folder name under componentsRoot |
+| `paths.extensions` | Extensions folder name under componentsRoot |
+
+### Component Discovery
+
+The CLI scans `componentsRoot` recursively and:
+- Includes all `.json` files in subfolders
+- Ignores `.meta` folders
+- Ignores `*.diagram.json` files
+- Ignores `package*.json` and `*config*.json` files
+
+---
+
 ## ⚡ Quick Start
 
 ### Initial Configuration
 
-After installation, configure the CLI:
+After installation, navigate to your vNext project and run:
 
 ```bash
-# Set project root path (REQUIRED)
-wf config set PROJECT_ROOT /path/to/your/vnext-project
+# Go to your vNext project directory
+cd /path/to/your/vnext-project
 
-# Database settings
-wf config set DB_PASSWORD postgres
+# Database settings (if using Docker)
 wf config set USE_DOCKER true
 wf config set DOCKER_POSTGRES_CONTAINER vnext-postgres
 
@@ -72,6 +116,8 @@ wf config set DOCKER_POSTGRES_CONTAINER vnext-postgres
 wf check
 ```
 
+**Note:** The CLI automatically uses the current working directory as the project root. Just `cd` into your project folder before running commands.
+
 ### Basic Usage
 
 ```bash
@@ -93,147 +139,426 @@ wf reset
 ## 📖 Commands
 
 ### `wf check`
-Checks system status (API, DB, folders).
 
-### `wf config <action> [key] [value]`
-Configuration management:
+**Purpose**: System health check
+
+Checks and displays:
+- vnext.config.json status and domain info
+- API connection status
+- Database connection status
+- Component folders found
+
 ```bash
-wf config get              # Show all settings
-wf config get PROJECT_ROOT # Show a specific setting
-wf config set DB_PASSWORD pass # Change a setting
+wf check
 ```
 
-### `wf csx [options]`
-Converts CSX files to Base64 and embeds them in JSON files.
+---
+
+### `wf sync`
+
+**Purpose**: Add missing components to database (skip existing)
+
+**What it does**:
+1. Scans all CSX files and updates JSON files with base64 encoded content
+2. For each component JSON file:
+   - Checks if it exists in DB (by key)
+   - If **exists** → Skip (already synced)
+   - If **not exists** → Publish to API
+3. Re-initializes the system
+
+**Use when**: Initial setup, adding new components without affecting existing ones
+
 ```bash
-wf csx              # Process changed files in Git
-wf csx --all        # Process all CSX files
-wf csx --file x.csx # Process a single file
+wf sync
 ```
 
+---
+
 ### `wf update [options]`
-Updates workflows (CSX is automatically updated!).
+
+**Purpose**: Update changed components (delete + re-add)
+
+**What it does**:
+1. Finds changed CSX files (Git) and updates JSON files
+2. For each component JSON file:
+   - Checks if it exists in DB (by key)
+   - If **exists** → Delete from DB, then publish to API
+   - If **not exists** → Publish to API
+3. Re-initializes the system
+
+**Use when**: You modified existing components and want to update them
+
 ```bash
 wf update                # Process changed files in Git (CSX + JSON)
 wf update --all          # Update all (asks for confirmation)
 wf update --file x.json  # Process a single file
 ```
 
-**Process steps:**
-1. 📝 Converts changed CSX files to base64 and writes to JSON files
-2. 🗑️ Deletes existing record from DB
-3. 📤 POSTs to API
-4. ✅ Activates the workflow
-5. 🔄 Restarts the system
-
-### `wf sync`
-Updates all CSX files and adds missing ones to the database.
-```bash
-wf sync  # Update all CSX files + add missing ones
-```
+---
 
 ### `wf reset`
-Resets workflows with an interactive menu (even if there are no changes).
+
+**Purpose**: Force reset components (always delete + re-add)
+
+**What it does**:
+1. Shows interactive menu to select component type
+2. For each component JSON file:
+   - Checks if it exists in DB (by key)
+   - If **exists** → Delete from DB, then publish to API
+   - If **not exists** → Publish to API
+3. Re-initializes the system
+
+**Use when**: You need to force reset components regardless of changes
+
 ```bash
-wf reset  # Select folder from menu
+wf reset  # Select folder from interactive menu
 ```
 
-**Menu:**
+**Menu Options**:
 ```
 ? Which folder should be reset?
-❯ 🔵 Workflows (sys-flows)
-  📋 Tasks (sys-tasks)
-  📊 Schemas (sys-schemas)
-  👁️  Views (sys-views)
-  ⚙️  Functions (sys-functions)
-  🔌 Extensions (sys-extensions)
+❯ tasks (Tasks/)
+  views (Views/)
+  functions (Functions/)
+  extensions (Extensions/)
+  workflows (Workflows/)
+  schemas (Schemas/)
   ──────────────
-  🔴 ALL (All folders)
+  TUMU (All folders)
 ```
 
 ---
 
-## 💡 Usage Scenarios
+### `wf csx [options]`
 
-### 1. Changing and Updating CSX File
-```bash
-# Edit CSX file
-vim AddToCartMapping.csx
+**Purpose**: Convert CSX files to Base64 and embed in JSON files
 
-# Update in one command (CSX + JSON automatic)
-wf update
-```
+**What it does**:
+1. Finds CSX files (changed or all)
+2. Converts to Base64
+3. Updates ALL JSON files that reference the CSX file
+4. Updates ALL matching `location` references in each JSON
+
+**Use when**: You only want to update CSX content in JSONs without publishing to API
 
-### 2. Updating Only CSX (Without Writing to DB)
 ```bash
-# Convert CSX files to base64 and write to JSON files
-wf csx
+wf csx              # Process changed files in Git
+wf csx --all        # Process all CSX files
+wf csx --file x.csx # Process a single file
 ```
 
-### 3. Initial Setup / Full Sync
+---
+
+### `wf config <action> [key] [value]`
+
+**Purpose**: Configuration management
+
 ```bash
-# Update all CSX files + add missing ones
-wf sync
+wf config get              # Show all settings (active domain)
+wf config get PROJECT_ROOT # Show a specific setting
+wf config set DB_PASSWORD pass # Change a setting (on active domain)
 ```
 
-### 4. Resetting Workflows (Delete from DB and Re-add)
+**Note:** `config get` and `config set` always operate on the **active domain**. Use `wf domain use <name>` to switch domains.
+
+---
+
+### `wf domain [action] [name] [options]`
+
+**Purpose**: Multidomain management
+
+Manage multiple domain configurations. Switch between domains with a single command. All CLI commands automatically use the active domain's settings.
+
 ```bash
-# With interactive menu (RECOMMENDED)
-wf reset
+# Show active domain name
+wf domain active
 
-# Reset all
-wf update --all
+# List all domains
+wf domain list
+wf domain --list
+
+# Add a new domain
+wf domain add staging --API_BASE_URL http://staging.example.com:4201 --DB_NAME vNext_StagingDb
 
-# Single file
-wf update --file /path/to/file.json
+# Add a domain with multiple settings
+wf domain add production \
+  --API_BASE_URL http://prod.example.com:4201 \
+  --DB_NAME vNext_ProdDb \
+  --DB_HOST prod-db.example.com \
+  --DB_USER prod_user \
+  --DB_PASSWORD prod_pass
+
+# Switch active domain
+wf domain use staging
+
+# Remove a domain
+wf domain remove staging
 ```
 
+**Notes:**
+- When adding a domain, any unspecified settings are inherited from the `default` domain.
+- The `default` domain cannot be removed.
+- If the active domain is removed, the CLI automatically switches to `default`.
+
 ---
 
-## ⚙️ Configuration
+## ⚙️ Configuration Variables
 
 Config file location: `~/.config/vnext-workflow-cli/config.json`
 
-### Important Settings
-```bash
-# Project root path (REQUIRED)
-wf config set PROJECT_ROOT /path/to/project
+### Config File Format
+
+The config file uses a domain-aware structure. Each domain has its own set of configuration values:
+
+```json
+{
+  "ACTIVE_DOMAIN": "default",
+  "DOMAINS": [
+    {
+      "DOMAIN_NAME": "default",
+      "AUTO_DISCOVER": true,
+      "API_BASE_URL": "http://localhost:4201",
+      "API_VERSION": "v1",
+      "DB_HOST": "localhost",
+      "DB_PORT": 5432,
+      "DB_NAME": "vNext_WorkflowDb",
+      "DB_USER": "postgres",
+      "DB_PASSWORD": "postgres",
+      "USE_DOCKER": false,
+      "DOCKER_POSTGRES_CONTAINER": "vnext-postgres",
+      "DEBUG_MODE": false
+    }
+  ]
+}
+```
+
+### All Available Settings (Per Domain)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PROJECT_ROOT` | `process.cwd()` | **Auto.** Always uses current working directory (cannot be changed) |
+| `AUTO_DISCOVER` | `true` | Enable automatic component folder discovery |
+| `API_BASE_URL` | `http://localhost:4201` | vNext API base URL |
+| `API_VERSION` | `v1` | API version |
+| `DB_HOST` | `localhost` | PostgreSQL host |
+| `DB_PORT` | `5432` | PostgreSQL port |
+| `DB_NAME` | `vNext_WorkflowDb` | PostgreSQL database name |
+| `DB_USER` | `postgres` | PostgreSQL username |
+| `DB_PASSWORD` | `postgres` | PostgreSQL password |
+| `USE_DOCKER` | `false` | Use Docker for PostgreSQL connection |
+| `DOCKER_POSTGRES_CONTAINER` | `vnext-postgres` | Docker container name for PostgreSQL |
+| `DEBUG_MODE` | `false` | Enable debug logging |
+
+**Note:** `PROJECT_ROOT` is always the current working directory (`process.cwd()`). Simply `cd` into your project folder before running any command.
+
+### Quick Setup Examples
 
-# API settings
+```bash
+# API settings (applied to active domain)
 wf config set API_BASE_URL http://localhost:4201
 wf config set API_VERSION v1
 
-# Database settings
+# Database settings (direct connection)
 wf config set DB_HOST localhost
 wf config set DB_PORT 5432
 wf config set DB_NAME vNext_WorkflowDb
 wf config set DB_USER postgres
 wf config set DB_PASSWORD your_password
+wf config set USE_DOCKER false
 
-# Docker settings
+# Database settings (Docker)
 wf config set USE_DOCKER true
 wf config set DOCKER_POSTGRES_CONTAINER vnext-postgres
 
-# Auto discovery
+# Other settings
 wf config set AUTO_DISCOVER true
+wf config set DEBUG_MODE false
 ```
 
 ---
 
+## 💡 Usage Scenarios
+
+### 1. First Time Setup
+```bash
+# Go to your vNext project
+cd /path/to/project
+
+# Check system status
+wf check
+
+# Sync all components (add missing ones)
+wf sync
+```
+
+### 2. Daily Development - Changed Files
+```bash
+# Edit CSX or JSON files
+vim MyTask.csx
+
+# Update only changed components
+wf update
+```
+
+### 3. Update All Components
+```bash
+# Force update all components
+wf update --all
+```
+
+### 4. Reset Specific Component Type
+```bash
+# Interactive menu
+wf reset
+```
+
+### 5. Only Update CSX in JSONs (No API)
+```bash
+# Update CSX content in JSON files without publishing
+wf csx
+```
+
+### 6. Multidomain Workflow
+```bash
+# Add domains
+wf domain add domain-a --API_BASE_URL http://localhost:4201 --DB_NAME vNext_DomainA
+wf domain add domain-b --API_BASE_URL http://localhost:4221 --DB_NAME vNext_DomainB
+
+# Work on Domain A
+wf domain use domain-a
+wf check
+wf update
+
+# Switch to Domain B - config is applied automatically
+wf domain use domain-b
+wf check
+wf update
+
+# See all domains
+wf domain list
+```
+
+---
+
+## 🔄 Command Comparison
+
+| Command | DB Check | Existing Action | New Action | Use Case |
+|---------|----------|-----------------|------------|----------|
+| `sync` | Yes | Skip | Publish | Add missing components |
+| `update` | Yes | Delete + Publish | Publish | Update changed components |
+| `reset` | Yes | Delete + Publish | Publish | Force reset components |
+| `csx` | No | N/A | N/A | Only update CSX in JSONs |
+
+---
+
+## 🔀 Multidomain Support
+
+### Overview
+
+The CLI supports managing multiple domain configurations. Each domain has its own `API_BASE_URL`, `DB_NAME`, and other settings. Switch between domains with a single command.
+
+### Backward Compatibility
+
+- Existing single-domain configurations are automatically migrated to the new format.
+- A `default` domain is created with your existing settings.
+- If you don't use multidomain features, everything works exactly as before.
+- All `wf config get/set` commands continue to work (they operate on the active domain).
+
+### Migration
+
+When upgrading from an older version, the CLI automatically migrates the config file:
+
+**Before (old flat format):**
+```json
+{
+  "API_BASE_URL": "http://localhost:4201",
+  "DB_NAME": "vNext_WorkflowDb"
+}
+```
+
+**After (new domain-aware format):**
+```json
+{
+  "ACTIVE_DOMAIN": "default",
+  "DOMAINS": [
+    {
+      "DOMAIN_NAME": "default",
+      "AUTO_DISCOVER": true,
+      "API_BASE_URL": "http://localhost:4201",
+      "API_VERSION": "v1",
+      "DB_HOST": "localhost",
+      "DB_PORT": 5432,
+      "DB_NAME": "vNext_WorkflowDb",
+      "DB_USER": "postgres",
+      "DB_PASSWORD": "postgres",
+      "USE_DOCKER": false,
+      "DOCKER_POSTGRES_CONTAINER": "vnext-postgres",
+      "DEBUG_MODE": false
+    }
+  ]
+}
+```
+
+Your existing values are preserved. Any missing keys are filled in from defaults (11 keys total).
+
+No manual action is required. The migration happens automatically on first run.
+
+### Domain Commands
+
+| Command | Description |
+|---------|-------------|
+| `wf domain active` | Show active domain name |
+| `wf domain list` | List all domains with active indicator |
+| `wf domain --list` | List all domains (shorthand) |
+| `wf domain add <name> [options]` | Add a new domain |
+| `wf domain use <name>` | Switch active domain |
+| `wf domain remove <name>` | Remove a domain |
+
+### Available Options for `wf domain add`
+
+| Option | Description |
+|--------|-------------|
+| `--API_BASE_URL <url>` | API base URL |
+| `--API_VERSION <version>` | API version |
+| `--DB_HOST <host>` | Database host |
+| `--DB_PORT <port>` | Database port |
+| `--DB_NAME <name>` | Database name |
+| `--DB_USER <user>` | Database user |
+| `--DB_PASSWORD <password>` | Database password |
+| `--AUTO_DISCOVER <true/false>` | Auto discover components |
+| `--USE_DOCKER <true/false>` | Use Docker for DB |
+| `--DOCKER_POSTGRES_CONTAINER <name>` | Docker container name |
+| `--DEBUG_MODE <true/false>` | Debug mode |
+
+Unspecified options inherit from the `default` domain.
+
+---
+
 ## 🆘 Troubleshooting
 
-### "Files not found" (When using on another PC)
+### "vnext.config.json not found"
 ```bash
-# Check current config
+# Make sure you're in the correct directory
+pwd
+
+# Check if vnext.config.json exists
+ls -la vnext.config.json
+
+# Check current working directory
 wf config get PROJECT_ROOT
+```
 
-# Set new PC's path
-wf config set PROJECT_ROOT /Users/NewUser/path/to/project
+### "Files not found" (When using on another PC)
+```bash
+# Just cd into the project directory
+cd /Users/NewUser/path/to/project
 
 # Verify
 wf check
 ```
 
+**Note:** No need to set PROJECT_ROOT - just `cd` into your project folder.
+
 ### "Cannot connect to API"
 ```bash
 # Check API
@@ -346,16 +671,18 @@ vnext-workflow-cli/
 │   │   ├── check.js
 │   │   ├── config.js
 │   │   ├── csx.js
+│   │   ├── domain.js        # Multidomain management
 │   │   ├── reset.js
 │   │   ├── sync.js
 │   │   └── update.js
 │   └── lib/                 # Library modules
-│       ├── api.js
-│       ├── config.js
-│       ├── csx.js
-│       ├── db.js
-│       ├── discover.js
-│       └── workflow.js
+│       ├── api.js           # API client (publish, reinitialize)
+│       ├── config.js        # CLI configuration
+│       ├── csx.js           # CSX processing
+│       ├── db.js            # Database operations
+│       ├── discover.js      # Component discovery
+│       ├── vnextConfig.js   # vnext.config.json reader
+│       └── workflow.js      # Workflow processing
 ├── .github/
 │   └── workflows/           # GitHub Actions workflows
 │       ├── build-and-publish.yml
@@ -379,4 +706,10 @@ wf check
 
 # Run development
 npm run dev
-```
+```
+
+---
+
+## 📝 License
+
+MIT License - see [LICENSE](LICENSE) for details.