snow-flow 3.4.3 → 3.4.5

package/.mcp.json.template

@@ -5,7 +5,7 @@
       "args": [
         "{{PROJECT_ROOT}}/dist/mcp/servicenow-deployment-mcp.js"
       ],
-      "description": "Widget deployment (snow_deploy), update set creation, deployment validation/rollback, artifact export/import, auth diagnostics, widget preview/testing",
+      "description": "Widget deployment (snow_deploy) with COHERENCE VALIDATION - ensures HTML template, client script, server script work together perfectly. Validates data.properties sync, ng-click methods, server actions. Update set creation, deployment validation/rollback, artifact export/import, auth diagnostics, widget preview/testing",
       "env": {
         "SNOW_INSTANCE": "{{SNOW_INSTANCE}}",
         "SNOW_CLIENT_ID": "{{SNOW_CLIENT_ID}}",

package/README.md

@@ -1,635 +1,164 @@
-# Snow-Flow: ServiceNow Development Platform
+# Snow-Flow
 
-[![npm version](https://img.shields.io/npm/v/snow-flow.svg)](https://www.npmjs.com/package/snow-flow)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![CI/CD](https://github.com/groeimetai/snow-flow/actions/workflows/ci.yml/badge.svg)](https://github.com/groeimetai/snow-flow/actions/workflows/ci.yml)
-[![Downloads](https://img.shields.io/npm/dm/snow-flow.svg)](https://www.npmjs.com/package/snow-flow)
-[![Node Version](https://img.shields.io/node/v/snow-flow.svg)](https://www.npmjs.com/package/snow-flow)
-[![ServiceNow Compatible](https://img.shields.io/badge/ServiceNow-Compatible-00A1E0?logo=servicenow)](https://www.servicenow.com)
-[![GitHub Stars](https://img.shields.io/github/stars/groeimetai/snow-flow?style=social)](https://github.com/groeimetai/snow-flow)
+ServiceNow development framework with MCP (Model Context Protocol) server integration and Claude AI orchestration.
 
-Snow-Flow is an AI-powered development platform for ServiceNow that provides 180+ MCP tools and multi-agent coordination. It enables developers and administrators to interact with ServiceNow through natural language commands and automated workflows.
+## What It Is
 
-## Quick Start - One Command to Rule Them All
+Snow-Flow is a Node.js application that provides:
+- 12 MCP servers for ServiceNow operations
+- Command-line interface for task orchestration
+- Multi-agent coordination system
+- OAuth authentication for ServiceNow instances
+- Background script execution with ES5 JavaScript only
 
-### 🚀 The Swarm Command
-The simplest way to use Snow-Flow is with the swarm command. Just describe what you want in natural language:
+## Requirements
 
-```bash
-# Basic usage - no flags needed!
-snow-flow swarm "Create an incident dashboard with real-time updates"
-```
-
-This single command automatically:
-- Spawns multiple specialized AI agents
-- Discovers existing ServiceNow artifacts
-- Creates complete working solutions
-- Deploys directly to your instance
-- Handles all technical complexity
-
-More examples:
-```bash
-snow-flow swarm "Build employee onboarding workflow"
-snow-flow swarm "Create knowledge base for IT support"
-snow-flow swarm "Set up change management process"
-snow-flow swarm "Analyze last month's incident patterns"
-```
-
-## Core Functionality
-
-Snow-Flow connects directly to ServiceNow instances through OAuth 2.0 authentication and provides:
-
-- Direct API integration with ServiceNow REST endpoints
-- Multi-agent system with specialized agents for different tasks
-- Natural language interface for ServiceNow operations
-- Machine learning capabilities using TensorFlow.js
-- Process automation and workflow optimization
-- Real-time logging and token tracking for API operations
-
-### API Operation Visibility
-
-Snow-Flow displays detailed information during API calls:
+- Node.js 18 or higher
+- ServiceNow instance with OAuth configured
+- Client ID and Client Secret for authentication
+- Instance URL (format: myinstance.service-now.com)
 
-```
-⏳ Operation in progress... (2s elapsed, 150 tokens used)
-🔄 API Call: GET /api/now/table/incident (10 records)
-📊 Tokens used: 450 (in: 100, out: 350)
-✅ Operation complete in 3 seconds
-```
-
-MCP operations run in separate processes and their logs are sent to stderr for visibility in the console.
-
-## ServiceNow API Integration
-
-### Authentication
-Snow-Flow uses OAuth 2.0 for secure authentication with ServiceNow:
+## Installation
 
 ```bash
-snow-flow auth login
-# Opens ServiceNow OAuth consent screen
-# Authenticate with ServiceNow credentials
-# Token stored locally in ~/.snow-flow/auth.json
-```
-
-### Security
-- OAuth 2.0 authentication protocol
-- Respects ServiceNow ACLs and user permissions
-- Local token storage with encryption
-- No external data transmission
-- All operations logged in ServiceNow audit trails
-
-### Network Architecture
-```
-┌─────────────┐    OAuth 2.0 + REST APIs    ┌─────────────────┐
-│  Snow-Flow  │ ◄─────────────────────────► │ Your ServiceNow │
-│   (Local)   │      HTTPS Only              │    Instance     │
-└─────────────┘                              └─────────────────┘
-```
-
-## Available Tools
-
-Snow-Flow provides 180+ tools across 17 specialized MCP servers:
-
-## Complete Tool Reference
-
-### MCP Server Overview
-
-| Server | Tools | Primary Focus |
-|--------|-------|---------------|
-| servicenow-operations | 15 | CRUD operations, data management |
-| servicenow-deployment | 21 | Widget, portal, and application deployment (create & update) |
-| servicenow-platform-development | 12 | Table creation, field management |
-| servicenow-machine-learning | 15 | Neural networks, predictions, anomaly detection |
-| servicenow-reporting-analytics | 18 | Dashboards, reports, KPIs |
-| servicenow-security-compliance | 14 | Security scanning, ACLs, compliance |
-| servicenow-update-set | 10 | Change packaging, version control |
-| servicenow-automation | 22 | Business rules, scheduled jobs, ATF testing |
-| servicenow-integration | 10 | REST/SOAP, data import/export |
-| servicenow-advanced-features | 15 | Process mining, advanced analytics |
-| servicenow-knowledge-catalog | 15 | Knowledge management, service catalog |
-| servicenow-change-virtualagent-pa | 19 | Change management, virtual agent, PA |
-| servicenow-flow-workspace-mobile | 20 | Flow Designer, agent workspace, mobile |
-| servicenow-cmdb-event-hr-csm-devops | 23 | CMDB, events, HR, CSM, DevOps |
-| servicenow-performance-optimization | 8 | Query optimization, batch operations |
-| servicenow-process-intelligence | 10 | Process mining and discovery |
-| snow-flow | 12 | Orchestration, memory management |
-
-### Detailed Tool Listing by Server
-
-#### 1. ATF Testing Tools (servicenow-automation)
-| Tool | Description | ServiceNow Table |
-|------|-------------|------------------|
-| snow_create_atf_test | Create automated test | sys_atf_test |
-| snow_create_atf_test_step | Add test steps | sys_atf_step |
-| snow_execute_atf_test | Execute tests | sys_atf_test_result |
-| snow_get_atf_results | Get test results | sys_atf_test_result |
-| snow_create_atf_test_suite | Create test suite | sys_atf_test_suite |
-| snow_discover_atf_tests | Find existing tests | sys_atf_test, sys_atf_test_suite |
-
-#### 2. Knowledge Management (servicenow-knowledge-catalog)
-| Tool | Description | ServiceNow Table |
-|------|-------------|------------------|
-| snow_create_knowledge_article | Create KB article | kb_knowledge |
-| snow_search_knowledge | Search articles | kb_knowledge |
-| snow_update_knowledge_article | Update article | kb_knowledge |
-| snow_retire_knowledge_article | Retire article | kb_knowledge |
-| snow_create_knowledge_base | Create KB | kb_knowledge_base |
-| snow_discover_knowledge_bases | List KBs | kb_knowledge_base |
-| snow_get_knowledge_stats | Article statistics | kb_knowledge |
-| snow_knowledge_feedback | Manage feedback | kb_feedback |
-
-#### 3. Service Catalog (servicenow-knowledge-catalog)
-| Tool | Description | ServiceNow Table |
-|------|-------------|------------------|
-| snow_create_catalog_item | Create catalog item | sc_cat_item |
-| snow_create_catalog_variable | Create variables | item_option_new |
-| snow_create_catalog_ui_policy | Create UI policies | catalog_ui_policy |
-| snow_order_catalog_item | Submit order | sc_req_item |
-| snow_search_catalog | Search catalog | sc_cat_item |
-| snow_get_catalog_item_details | Get item details | sc_cat_item |
-| snow_discover_catalogs | List catalogs | sc_catalog |
-
-#### 4. Change Management (servicenow-change-virtualagent-pa)
-| Tool | Description | ServiceNow Table |
-|------|-------------|------------------|
-| snow_create_change_request | Create change | change_request |
-| snow_create_change_task | Create task | change_task |
-| snow_get_change_request | Get change details | change_request |
-| snow_update_change_state | Update state | change_request |
-| snow_schedule_cab_meeting | Schedule CAB | cab_meeting |
-| snow_search_change_requests | Search changes | change_request |
-
-#### 5. Virtual Agent (servicenow-change-virtualagent-pa)
-| Tool | Description | ServiceNow Table |
-|------|-------------|------------------|
-| snow_create_va_topic | Create topic | sys_cs_topic |
-| snow_create_va_topic_block | Create blocks | sys_cs_topic_block |
-| snow_get_va_conversation | Get conversation | sys_cs_conversation |
-| snow_send_va_message | Send message | sys_cs_conversation |
-| snow_handoff_to_agent | Escalate to agent | sys_cs_conversation |
-| snow_discover_va_topics | List topics | sys_cs_topic |
-
-#### 6. Performance Analytics (servicenow-change-virtualagent-pa)
-| Tool | Description | ServiceNow Table |
-|------|-------------|------------------|
-| snow_create_pa_indicator | Create KPI | pa_indicators |
-| snow_create_pa_widget | Create widget | pa_widgets |
-| snow_create_pa_breakdown | Create breakdown | pa_breakdowns |
-| snow_create_pa_threshold | Set threshold | pa_thresholds |
-| snow_get_pa_scores | Get scores | pa_scores |
-| snow_create_pa_target | Set target | pa_targets |
-| snow_analyze_pa_trends | Analyze trends | pa_scores |
-
-#### 7. Flow Designer (servicenow-flow-workspace-mobile)
-| Tool | Description | ServiceNow Table |
-|------|-------------|------------------|
-| snow_create_flow | Create flow | sys_hub_flow |
-| snow_create_flow_action | Create action | sys_hub_action_instance |
-| snow_create_subflow | Create subflow | sys_hub_sub_flow |
-| snow_add_flow_trigger | Add trigger | sys_hub_trigger_instance |
-| snow_publish_flow | Publish flow | sys_hub_flow |
-| snow_test_flow | Test flow | sys_flow_context |
-| snow_get_flow_execution_details | Get execution | sys_flow_context |
-
-#### 8. Agent Workspace (servicenow-flow-workspace-mobile)
-| Tool | Description | ServiceNow Table |
-|------|-------------|------------------|
-| snow_create_workspace | Create workspace | sys_aw_workspace |
-| snow_configure_workspace_tab | Configure tabs | sys_aw_tab |
-| snow_add_workspace_list | Add lists | sys_aw_list |
-| snow_create_workspace_form | Create forms | sys_aw_form |
-| snow_configure_workspace_ui_action | Add UI actions | sys_aw_ui_action |
-| snow_deploy_workspace | Deploy workspace | sys_aw_workspace |
-
-#### 9. Mobile Platform (servicenow-flow-workspace-mobile)
-| Tool | Description | ServiceNow Table |
-|------|-------------|------------------|
-| snow_create_mobile_app_config | Configure app | sys_mobile_config |
-| snow_configure_mobile_layout | Configure layout | sys_mobile_layout |
-| snow_create_mobile_applet | Create applet | sys_mobile_applet |
-| snow_configure_offline_tables | Offline sync | sys_mobile_offline |
-| snow_set_mobile_security | Security settings | sys_mobile_security |
-| snow_push_notification_config | Push notifications | sys_push_notification |
-| snow_deploy_mobile_app | Deploy app | sys_mobile_deployment |
-
-#### 10. CMDB & Discovery (servicenow-cmdb-event-hr-csm-devops)
-| Tool | Description | ServiceNow Table |
-|------|-------------|------------------|
-| snow_create_cmdb_ci | Create CI | cmdb_ci_* |
-| snow_create_ci_relationship | Create relationship | cmdb_rel_ci |
-| snow_discover_ci_dependencies | Find dependencies | cmdb_rel_ci |
-| snow_run_discovery | Run discovery | discovery_status |
-| snow_get_discovery_status | Get status | discovery_status |
-| snow_import_cmdb_data | Import data | sys_import_set |
-
-#### 11. Event Management (servicenow-cmdb-event-hr-csm-devops)
-| Tool | Description | ServiceNow Table |
-|------|-------------|------------------|
-| snow_create_event | Create event | em_event |
-| snow_create_alert_rule | Create rule | em_alert_rule |
-| snow_correlate_alerts | Correlate alerts | em_alert |
-| snow_get_event_metrics | Get metrics | em_event |
-
-#### 12. HR Service Delivery (servicenow-cmdb-event-hr-csm-devops)
-| Tool | Description | ServiceNow Table |
-|------|-------------|------------------|
-| snow_create_hr_case | Create HR case | sn_hr_core_case |
-| snow_manage_onboarding | Onboarding | sn_hr_core_task |
-| snow_manage_offboarding | Offboarding | sn_hr_core_task |
-| snow_get_hr_analytics | HR analytics | sn_hr_core_case |
-
-#### 13. Customer Service Management (servicenow-cmdb-event-hr-csm-devops)
-| Tool | Description | ServiceNow Table |
-|------|-------------|------------------|
-| snow_create_csm_case | Create case | sn_customerservice_case |
-| snow_manage_customer_account | Manage account | sn_customerservice_account |
-| snow_create_csm_communication | Communications | sn_customerservice_communication |
-| snow_get_customer_satisfaction | Get CSAT | sn_customerservice_csat |
-
-#### 14. DevOps (servicenow-cmdb-event-hr-csm-devops)
-| Tool | Description | ServiceNow Table |
-|------|-------------|------------------|
-| snow_create_devops_pipeline | Create pipeline | sn_devops_pipeline |
-| snow_track_deployment | Track deployment | sn_devops_deployment |
-| snow_manage_devops_change | DevOps change | sn_devops_change |
-| snow_get_velocity_metrics | Team velocity | sn_devops_velocity |
-| snow_create_devops_artifact | Build artifacts | sn_devops_artifact |
-
-### Table Operations
-The universal `snow_query_table` tool works with all ServiceNow tables:
-
-```javascript
-// Query any table with optimized performance
-snow_query_table({ 
-  table: "incident",  // Works with any table
-  query: "state!=7",
-  fields: ["number", "short_description", "priority"],
-  limit: 100
-})
-
-// Analytics mode - retrieve all records with minimal fields
-snow_query_table({ 
-  table: "incident",
-  fields: ["sys_created_on", "priority"]  // Omit limit for all records
-})
-
-// Count-only mode for large datasets
-snow_query_table({ 
-  table: "sc_request",
-  include_content: false  // Returns count only
-})
-
-// Server-side aggregation
-snow_query_table({ 
-  table: "change_request",
-  group_by: "risk",
-  order_by: "-count"
-})
+npm install -g snow-flow
 ```
 
-### Development Tools
-
-#### Supported Artifact Types (snow_deploy & snow_update)
-
-Snow-Flow supports deployment and updating of 16+ different ServiceNow artifact types:
-
-| Artifact Type | ServiceNow Table | Deploy | Update | Description |
-|---------------|------------------|--------|---------|-------------|
-| **widget** | sp_widget | ✅ | ✅ | Service Portal widgets with HTML/CSS/JS |
-| **application** | sys_app | ✅ | ✅ | Scoped applications and app stores |
-| **business_rule** | sys_script | ✅ | ✅ | Server-side business logic automation |
-| **script_include** | sys_script_include | ✅ | ✅ | Reusable server-side code libraries |
-| **ui_page** | sys_ui_page | ✅ | ✅ | Custom UI pages and interfaces |
-| **client_script** | sys_script_client | ✅ | ✅ | Client-side form and field scripts |
-| **ui_action** | sys_ui_action | ✅ | ✅ | Buttons, links, and form actions |
-| **ui_policy** | sys_ui_policy | ✅ | ✅ | Dynamic form behavior and validation |
-| **acl** | sys_security_acl | ✅ | ✅ | Access control and security rules |
-| **table** | sys_db_object | ✅ | ✅ | Custom database tables and structures |
-| **field** | sys_dictionary | ✅ | ✅ | Table fields and column definitions |
-| **workflow** | wf_workflow | ✅ | ✅ | Classic workflow processes |
-| **flow** | sys_hub_flow | ✅ | ✅ | Flow Designer automation flows |
-| **notification** | sysevent_email_action | ✅ | ✅ | Email notifications and alerts |
-| **scheduled_job** | sysauto_script | ✅ | ✅ | Scheduled background scripts |
+## Configuration
 
-#### Usage Examples
+Create `.env` file with ServiceNow credentials:
 
-```javascript
-// Deploy NEW artifacts
-await snow_deploy({
-  type: 'widget',
-  name: 'My Dashboard Widget',
-  template: '<div>My HTML</div>',
-  css: '.my-class { color: blue; }',
-  client_script: 'function() { console.log("Hello"); }'
-});
-
-await snow_deploy({
-  type: 'business_rule', 
-  name: 'Auto Assignment Rule',
-  table: 'incident',
-  when: 'before',
-  insert: true,
-  script: 'if (current.priority == "1") current.assigned_to = "admin";'
-});
-
-// Update EXISTING artifacts
-await snow_update({
-  type: 'widget',
-  identifier: 'My Dashboard Widget', // name or sys_id
-  instruction: 'Add a new chart showing priority distribution'
-});
-
-await snow_update({
-  type: 'ui_action',
-  identifier: 'close_incident',
-  config: {
-    action_name: 'Close with Resolution',
-    condition: 'current.state != 7'
-  }
-});
+```env
+SNOW_INSTANCE=your-instance.service-now.com
+SNOW_CLIENT_ID=your-client-id
+SNOW_CLIENT_SECRET=your-client-secret
 ```
 
-#### Natural Language Updates
+## MCP Servers
 
-```javascript
-// All artifact types support natural language instructions
-await snow_update({
-  type: 'notification',
-  identifier: 'incident_created',
-  instruction: 'Change subject to "High Priority Incident Created" and add escalation details'
-});
-
-await snow_update({
-  type: 'scheduled_job',
-  identifier: 'daily_cleanup',
-  instruction: 'Change schedule to run every 2 hours and add error logging'
-});
-
-await snow_update({
-  type: 'acl',
-  identifier: 'incident_read',
-  instruction: 'Add condition script to check user department'
-});
-```
+Snow-Flow includes 12 MCP servers:
 
-### Service Management
-- Incident management
-- Change management with CAB scheduling
-- Problem management
-- Request fulfillment
-- Knowledge management
-
-### Enterprise APIs
-- Performance Analytics (PA) with KPI management
-- Virtual Agent configuration
-- Agent Workspace customization
-- Mobile platform deployment
-- CMDB and Discovery
-- Event Management
-- HR Service Delivery
-- Customer Service Management
-- DevOps integration
-
-### Machine Learning
-
-Snow-Flow includes TensorFlow.js for neural network capabilities:
-
-#### Incident Classification
-Train LSTM networks on historical incident data:
-```bash
-snow-flow ml train-incident-classifier --sample-size 5000 --epochs 100
-snow-flow ml classify-incident INC0123456
-```
+1. **servicenow-deployment** - Widget and artifact deployment with coherence validation
+2. **servicenow-operations** - Table operations and queries
+3. **servicenow-automation** - Script execution and job scheduling
+4. **servicenow-platform-development** - Business rules and script includes
+5. **servicenow-integration** - REST messages and data imports
+6. **servicenow-system-properties** - System property management
+7. **servicenow-update-set** - Update set management
+8. **servicenow-development-assistant** - Code generation
+9. **servicenow-security-compliance** - Security policies
+10. **servicenow-reporting-analytics** - Reports and dashboards
+11. **servicenow-machine-learning** - ML model training
+12. **snow-flow** - Orchestration and memory management
 
-#### Change Risk Prediction
-Analyze change requests to predict implementation risk:
-```bash
-snow-flow ml train-change-risk --include-failed-changes
-snow-flow ml predict-change-risk CHG0123456
-```
+## Basic Commands
 
-#### Time Series Forecasting
-Predict future incident volumes:
+Start orchestration system:
 ```bash
-snow-flow ml forecast-incidents --days 7 --category network
+snow-flow start
 ```
 
-#### Anomaly Detection
-Detect unusual patterns using autoencoder networks:
+Create agent:
 ```bash
-snow-flow ml detect-anomalies --metric incident_patterns --sensitivity 0.9
+snow-flow agent spawn researcher
 ```
 
-### ServiceNow Native ML Integration
-
-Access ServiceNow's native ML capabilities when licensed:
-
-#### Performance Analytics ML
+Execute task:
 ```bash
-snow-flow ml performance-analytics --indicator "Incident Resolution Time" --forecast-days 90
+snow-flow task create analysis "Analyze incident patterns"
 ```
 
-#### Predictive Intelligence
+Run swarm coordination:
 ```bash
-snow-flow ml predictive-intelligence --operation similar_incidents --incident INC0123456
+snow-flow swarm "Create incident dashboard"
 ```
 
-#### Agent Intelligence
+Store data in memory:
 ```bash
-snow-flow ml agent-intelligence --task incident --id INC0123456 --auto-assign
+snow-flow memory store key "data"
 ```
 
-Note: Native ML features require appropriate ServiceNow plugin licenses (PA, PI, Agent Intelligence).
-
-## Multi-Agent System
-
-Snow-Flow includes 38 specialized agents that work together:
-
-### Agent Types
-- **Architect**: System design and architecture planning
-- **Developer**: Code generation and implementation
-- **Tester**: Test creation and execution
-- **Analyst**: Data analysis and reporting
-- **Security**: Compliance and security validation
-- **Optimizer**: Performance optimization
-- **Documenter**: Documentation generation
+## Script Execution
 
-### Coordination Modes
-- **Hierarchical**: Top-down task delegation
-- **Mesh**: Peer-to-peer collaboration
-- **Swarm**: Distributed problem solving
-- **Adaptive**: Dynamic reorganization based on task requirements
+Snow-Flow executes ServiceNow background scripts using ES5 JavaScript only:
 
-## Installation
-
-### Prerequisites
-- Node.js 18.0 or higher
-- npm 8.0 or higher
-- ServiceNow instance with admin access
-- OAuth application configured in ServiceNow
-
-### Install via npm
-```bash
-npm install -g snow-flow
-```
-
-### Initial Setup
-```bash
-# Initialize configuration
-snow-flow init
-
-# Configure authentication
-snow-flow auth login
+```javascript
+// Supported ES5 syntax
+var gr = new GlideRecord('incident');
+gr.query();
+while (gr.next()) {
+  gs.info(gr.getValue('number'));
+}
 
-# Verify connection
-snow-flow auth test
+// NOT supported (ES6+ will fail)
+const data = await fetch();  // Will fail
+let items = [];              // Will fail
+() => {}                     // Will fail
 ```
 
-### Troubleshooting: Claude Code stdio Error
+## Widget Development
 
-If you encounter a stdio/permissions error when using Snow-Flow with Claude Code:
+Widgets require coherent communication between three components:
+- Server script provides data
+- Client script handles interactions
+- HTML template displays content
 
-```bash
-# 1. Fix Claude permissions
-claude --dangerously-skip-permissions
+Server and client scripts must align on:
+- Data property names
+- Action names for requests
+- Method names for UI events
 
-# 2. Activate Claude Code
-# Open Claude Code and ensure it's activated with your account
+## Authentication
 
-# 3. Login to Claude
-# Sign in with your Claude account in the Claude Code interface
+Snow-Flow uses OAuth 2.0 for ServiceNow authentication:
+1. Configure OAuth provider in ServiceNow
+2. Set client credentials in .env
+3. Snow-Flow handles token refresh automatically
 
-# 4. Close Claude Code completely
-# Make sure Claude Code is fully closed before proceeding
+## Directory Structure
 
-# 5. Now run Snow-Flow swarm
-snow-flow swarm "Your ServiceNow task here"
 ```
-
-This resolves the common "stdio" error that occurs when Claude Code doesn't have proper permissions to communicate with MCP servers.
-
-## Usage Examples
-
-### Swarm Command (Recommended)
-```bash
-# The simplest way - just describe what you want!
-snow-flow swarm "Create incident management dashboard"
-
-# No flags needed for basic usage
-snow-flow swarm "Build service catalog for laptop requests"
-
-# Advanced usage with optional flags
-snow-flow swarm "Optimize incident resolution process" --monitor --parallel
+snow-flow/
+├── src/
+│   ├── mcp/           # MCP server implementations
+│   ├── client/        # ServiceNow API client
+│   ├── utils/         # Utility functions
+│   └── types/         # TypeScript definitions
+├── dist/              # Compiled JavaScript
+└── .mcp.json         # MCP configuration template
 ```
 
-### Natural Language Commands
-```bash
-# Create an incident dashboard
-snow-flow sparc "Create incident management dashboard with SLA tracking"
+## Error Handling
 
-# Build a workflow
-snow-flow sparc "Create employee onboarding workflow with approval steps"
+Snow-Flow operations include:
+- Automatic retry on network failures
+- Token refresh on authentication errors
+- Timeout protection (5 seconds default)
+- Error logging with context
 
-# Analyze data
-snow-flow sparc "Analyze incident resolution patterns from last quarter"
-```
+## Testing
 
-### Direct Tool Usage
+Run tests:
 ```bash
-# Query incidents
-snow-flow query --table incident --limit 10
-
-# Create a widget
-snow-flow deploy widget --name "SLA Dashboard" --template dashboard
-
-# Generate documentation
-snow-flow generate docs --scope "incident_management"
+npm test
 ```
 
-### Advanced Swarm Options
+Type checking:
 ```bash
-# With specific strategy
-snow-flow swarm "Build complete HR service portal" \
-  --strategy development \
-  --mode hierarchical \
-  --max-agents 8
-
-# Parallel analysis
-snow-flow swarm "Analyze system performance bottlenecks" \
-  --strategy analysis \
-  --mode mesh \
-  --parallel
-
-# With monitoring
-snow-flow swarm "Deploy production changes" \
-  --monitor \
-  --auto-rollback
+npm run typecheck
 ```
 
-## Configuration
-
-Configuration file location: `~/.snow-flow/.env`
-
-### Required Settings
-```env
-SNOW_INSTANCE=your-instance.service-now.com
-SNOW_CLIENT_ID=your-oauth-client-id
-SNOW_CLIENT_SECRET=your-oauth-client-secret
-```
-
-### Optional Settings
-```env
-# Timeout configuration (milliseconds)
-# SNOW_FLOW_INIT_TIMEOUT=30000
-# SNOW_FLOW_OPERATION_TIMEOUT=60000
-# SNOW_FLOW_MEMORY_TIMEOUT=5000
-
-# Agent configuration
-SNOW_FLOW_MAX_AGENTS=10
-SNOW_FLOW_AGENT_MODE=hierarchical
-
-# ML configuration
-SNOW_FLOW_ML_ENABLED=true
-SNOW_FLOW_ML_MODEL_PATH=./models
-```
+## Build
 
-## Project Structure
-```
-snow-flow/
-├── src/                 # Source code
-│   ├── agents/         # Agent implementations
-│   ├── mcp/           # MCP server implementations
-│   ├── utils/         # Utility functions
-│   └── services/      # Service layer
-├── dist/               # Compiled JavaScript
-├── memory/             # Persistent storage
-├── models/             # ML models
-└── tests/              # Test suite
+Build from source:
+```bash
+npm run build
 ```
 
-## Documentation
-
-- [API Reference](docs/api.md)
-- [Agent Documentation](docs/agents.md)
-- [MCP Tools Reference](docs/tools.md)
-- [ML Capabilities](docs/ml.md)
-- [Configuration Guide](docs/configuration.md)
+## Version
 
-## Contributing
-
-Contributions are welcome. Please read the [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
-
-## Support
-
-- GitHub Issues: [github.com/groeimetai/snow-flow/issues](https://github.com/groeimetai/snow-flow/issues)
-- Documentation: [github.com/groeimetai/snow-flow/wiki](https://github.com/groeimetai/snow-flow/wiki)
+Current version: 3.4.4
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## Acknowledgments
-
-- ServiceNow for the comprehensive REST API
-- TensorFlow.js for machine learning capabilities
-- Model Context Protocol (MCP) for tool orchestration
+MIT

package/dist/dynamic-version.js

@@ -36,7 +36,7 @@ function getDynamicVersion() {
         console.warn('Warning: Could not read version from package.json:', error);
     }
     // Fallback to hardcoded version
-    return '3.4.3';
+    return '3.4.4';
 }
 // Export a constant that uses the dynamic version
 exports.VERSION = getDynamicVersion();

package/dist/mcp/servicenow-deployment-mcp.js

@@ -4,6 +4,39 @@
  * ServiceNow Deployment MCP Server
  * Provides specialized deployment tools for ServiceNow artifacts
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
@@ -550,6 +583,36 @@ class ServiceNowDeploymentMCP {
                 this.logger.warn('⚠️ Token may lack write permissions, deployment might fail with 403');
             }
             this.logger.info('Deploying widget to ServiceNow', { name: args.name, sys_id: args.sys_id });
+            // COHERENCE VALIDATION: Check widget component consistency
+            if (args.template && args.client_script && args.server_script) {
+                try {
+                    const { widgetTemplateGenerator } = await Promise.resolve().then(() => __importStar(require('../utils/widget-template-generator')));
+                    const coherenceReport = widgetTemplateGenerator['validateCoherence']({
+                        template: args.template,
+                        css: args.css || '',
+                        serverScript: args.server_script,
+                        clientScript: args.client_script,
+                        optionSchema: args.option_schema || ''
+                    });
+                    if (!coherenceReport.isCoherent) {
+                        this.logger.warn('⚠️  Widget coherence issues detected:', {
+                            warnings: coherenceReport.warnings,
+                            suggestions: coherenceReport.suggestions
+                        });
+                        // Include coherence warnings in response (but don't fail deployment)
+                        const warningMessage = `⚠️ **Widget Coherence Warnings:**\n\n${coherenceReport.warnings.map(w => `• ${w}`).join('\n')}\n\n**Suggestions:**\n${coherenceReport.suggestions.map(s => `• ${s}`).join('\n')}\n\n*Widget will still deploy but may not function correctly.*`;
+                        // Store coherence warnings for later inclusion in response
+                        args._coherenceWarnings = warningMessage;
+                    }
+                    else {
+                        this.logger.info('✅ Widget coherence validation passed');
+                    }
+                }
+                catch (coherenceError) {
+                    this.logger.warn('Coherence validation failed:', coherenceError);
+                    // Continue with deployment even if coherence check fails
+                }
+            }
             // CHECK: If sys_id is provided, this is an UPDATE not a CREATE
             if (args.sys_id) {
                 this.logger.info('🔄 UPDATE mode detected - updating existing widget', { sys_id: args.sys_id });
@@ -587,6 +650,8 @@ class ServiceNowDeploymentMCP {
 - Deployment Context: ${args.config?.deployment_context || args.deployment_context || 'Widget update'}
 - Method: Direct update via API
 
+${args._coherenceWarnings || ''}
+
 🔗 Direct Links:
 - Widget Editor: ${widgetUrl}
 - Service Portal Designer: https://${credentials?.instance}/sp_config?id=designer
@@ -1156,6 +1221,8 @@ Use \`snow_deployment_debug\` for more information about this session.`,
 - Widget Editor: ${widgetUrl}
 - Service Portal Designer: https://${credentials?.instance}/sp_config?id=designer
 
+${args._coherenceWarnings || ''}
+
 🛠️ Deployment Info:
 - Method Used: ${deploymentMethod === 'direct_api' ? 'Direct API (preferred)' :
                                 deploymentMethod === 'table_record' ? 'Table Record (fallback)' : 'Unknown'}
@@ -1245,6 +1312,8 @@ Use \`snow_deployment_debug\` for more information about this session.`,
 - Widget Editor: ${widgetUrl}
 - Service Portal Designer: https://${credentials?.instance}/sp_config?id=designer
 
+${args._coherenceWarnings || ''}
+
 🔧 **Note**: Widget was successfully created despite receiving permission errors during verification. This is a known ServiceNow API limitation.
 
 ⚡ **Ready for Testing**

package/dist/utils/widget-template-generator.d.ts

@@ -15,6 +15,30 @@ export interface WidgetComponents {
     serverScript: string;
     clientScript: string;
     optionSchema: string;
+    coherenceReport: WidgetCoherenceReport;
+}
+export interface WidgetCoherenceReport {
+    isCoherent: boolean;
+    dataProperties: {
+        server: string[];
+        html: string[];
+        matched: string[];
+        missing: string[];
+    };
+    methods: {
+        html: string[];
+        client: string[];
+        matched: string[];
+        missing: string[];
+    };
+    serverActions: {
+        client: string[];
+        server: string[];
+        matched: string[];
+        missing: string[];
+    };
+    warnings: string[];
+    suggestions: string[];
 }
 export declare class ServiceNowWidgetTemplateGenerator {
     /**
@@ -77,6 +101,10 @@ export declare class ServiceNowWidgetTemplateGenerator {
      * Generate option schema based on widget type
      */
     private generateOptionSchema;
+    /**
+     * Validate widget coherence - ensures HTML, client script, and server script work together
+     */
+    private validateCoherence;
 }
 export declare const widgetTemplateGenerator: ServiceNowWidgetTemplateGenerator;
 //# sourceMappingURL=widget-template-generator.d.ts.map

package/dist/utils/widget-template-generator.js

@@ -13,13 +13,17 @@ class ServiceNowWidgetTemplateGenerator {
         const { instruction = '', title = 'Widget', type = 'auto' } = options;
         const detectedType = type === 'auto' ? this.detectWidgetType(instruction) : type;
         const widgetTitle = title || this.extractTitleFromInstruction(instruction);
-        return {
+        const components = {
             template: this.generateTemplate(detectedType, widgetTitle, instruction),
             css: this.generateCss(detectedType, options),
             serverScript: this.generateServerScript(detectedType, instruction),
             clientScript: this.generateClientScript(detectedType, instruction),
-            optionSchema: this.generateOptionSchema(detectedType)
+            optionSchema: this.generateOptionSchema(detectedType),
+            coherenceReport: {}
         };
+        // Generate coherence report
+        components.coherenceReport = this.validateCoherence(components);
+        return components;
     }
     /**
      * Detect widget type from instruction
@@ -1684,6 +1688,71 @@ function($scope, $http, spUtil, $timeout) {
         const allOptions = [...baseOptions, ...typeSpecificOptions];
         return JSON.stringify(allOptions, null, 2);
     }
+    /**
+     * Validate widget coherence - ensures HTML, client script, and server script work together
+     */
+    validateCoherence(components) {
+        const report = {
+            isCoherent: true,
+            dataProperties: { server: [], html: [], matched: [], missing: [] },
+            methods: { html: [], client: [], matched: [], missing: [] },
+            serverActions: { client: [], server: [], matched: [], missing: [] },
+            warnings: [],
+            suggestions: []
+        };
+        // Extract data properties from server script
+        const serverDataMatches = components.serverScript.match(/data\.(\w+)\s*=/g) || [];
+        report.dataProperties.server = serverDataMatches.map(match => match.replace(/data\.(\w+)\s*=/, '$1'));
+        // Extract data properties from HTML template
+        const htmlDataMatches = components.template.match(/\{\{data\.(\w+)[\}|\.]/g) || [];
+        report.dataProperties.html = [...new Set(htmlDataMatches.map(match => match.replace(/\{\{data\.(\w+)[\}|\.].*/, '$1')))];
+        // Find matched and missing data properties
+        report.dataProperties.matched = report.dataProperties.server.filter(prop => report.dataProperties.html.includes(prop));
+        report.dataProperties.missing = report.dataProperties.server.filter(prop => !report.dataProperties.html.includes(prop));
+        // Extract methods from HTML (ng-click)
+        const htmlMethodMatches = components.template.match(/ng-click="(\w+)\(/g) || [];
+        report.methods.html = [...new Set(htmlMethodMatches.map(match => match.replace(/ng-click="(\w+)\(/, '$1')))];
+        // Extract methods from client script ($scope.method)
+        const clientMethodMatches = components.clientScript.match(/\$scope\.(\w+)\s*=/g) || [];
+        report.methods.client = [...new Set(clientMethodMatches.map(match => match.replace(/\$scope\.(\w+)\s*=/, '$1')))];
+        // Find matched and missing methods
+        report.methods.matched = report.methods.html.filter(method => report.methods.client.includes(method));
+        report.methods.missing = report.methods.html.filter(method => !report.methods.client.includes(method));
+        // Extract client server actions
+        const clientActionMatches = components.clientScript.match(/action:\s*['"](\w+)['"]/g) || [];
+        report.serverActions.client = [...new Set(clientActionMatches.map(match => match.replace(/action:\s*['"](\w+)['"]/, '$1')))];
+        // Extract server action handlers
+        const serverActionMatches = components.serverScript.match(/input\.action\s*===?\s*['"](\w+)['"]/g) || [];
+        report.serverActions.server = [...new Set(serverActionMatches.map(match => match.replace(/input\.action\s*===?\s*['"](\w+)['"]/, '$1')))];
+        // Find matched and missing server actions
+        report.serverActions.matched = report.serverActions.client.filter(action => report.serverActions.server.includes(action));
+        report.serverActions.missing = report.serverActions.client.filter(action => !report.serverActions.server.includes(action));
+        // Generate warnings and suggestions
+        if (report.dataProperties.missing.length > 0) {
+            report.warnings.push(`Server data properties not used in HTML: ${report.dataProperties.missing.join(', ')}`);
+            report.suggestions.push(`Add {{data.${report.dataProperties.missing[0]}}} to HTML template`);
+        }
+        if (report.methods.missing.length > 0) {
+            report.warnings.push(`HTML methods not implemented in client: ${report.methods.missing.join(', ')}`);
+            report.suggestions.push(`Add $scope.${report.methods.missing[0]} = function() {} to client script`);
+        }
+        if (report.serverActions.missing.length > 0) {
+            report.warnings.push(`Client actions not handled by server: ${report.serverActions.missing.join(', ')}`);
+            report.suggestions.push(`Add if (input.action === '${report.serverActions.missing[0]}') {} to server script`);
+        }
+        // Additional coherence checks
+        if (report.dataProperties.server.length === 0) {
+            report.warnings.push('Server script does not set any data properties');
+            report.suggestions.push('Add data.items = [] or similar in server script');
+        }
+        if (components.template.includes('ng-repeat') && !components.template.includes('{{')) {
+            report.warnings.push('HTML has ng-repeat but no data bindings');
+            report.suggestions.push('Add {{item.property}} bindings inside ng-repeat');
+        }
+        // Determine overall coherence
+        report.isCoherent = report.warnings.length === 0;
+        return report;
+    }
 }
 exports.ServiceNowWidgetTemplateGenerator = ServiceNowWidgetTemplateGenerator;
 // Export singleton instance

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "snow-flow",
-  "version": "3.4.3",
-  "description": "Snow-Flow v3.4.3: BACKGROUND SCRIPTS FIRST - The 30-second debugging revolution! Primary debugging method: Use background scripts to verify EVERYTHING instantly. Universal verification script template tests tables (GlideRecord.isValid()), properties (gs.getProperty), fields, and reproduces actual errors. No more assumptions - get facts from the user's real ServiceNow environment in 30 seconds. Debug-first mentality with 200+ MCP tools across 18 specialized servers.",
+  "version": "3.4.5",
+  "description": "ServiceNow development framework with MCP server integration. Executes background scripts using ES5 JavaScript only (ServiceNow Rhino engine requirement). Provides 12 MCP servers for ServiceNow operations including widget deployment with coherence validation, table operations, script execution, and system property management.",
   "main": "dist/index.js",
   "type": "commonjs",
   "bin": {