snow-flow 1.1.73 → 1.1.75

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

@@ -1073,6 +1073,17 @@ Use \`snow_deployment_debug\` for more information about this session.`,
                     ],
                 };
             }
+            // Ensure we have a flow definition
+            if (!args.flow_definition) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: '❌ Flow deployment failed: No flow_definition provided.\n\n💡 You need to provide a flow_definition with activities.\n\nExample:\n```json\n{\n  "name": "approval_flow",\n  "flow_definition": {\n    "activities": [\n      {\n        "id": "activity_1",\n        "name": "Check Condition",\n        "type": "condition"\n      }\n    ]\n  }\n}\n```\n\nOr use snow_create_flow with natural language for easier flow creation.',
+                        },
+                    ],
+                };
+            }
             const flowType = args.flow_type || 'flow';
             this.logger.info(`Deploying ${flowType} to ServiceNow`, { name: args.name, type: flowType });
             // Validate flow definition first if requested
@@ -2760,6 +2771,17 @@ Use \`snow_preview_widget\` to see a detailed preview of the widget rendering.`,
                     ]
                 };
             }
+            // Check if definition is null or undefined
+            if (!definition) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `❌ Flow validation failed: No definition provided.\n\n💡 Please provide a flow definition with activities.\n\nExample:\n\`\`\`json\n{\n  "activities": [\n    {\n      "id": "activity_1",\n      "name": "Send Notification",\n      "type": "notification"\n    }\n  ]\n}\n\`\`\``
+                        }
+                    ]
+                };
+            }
             const issues = [];
             const warnings = [];
             const info = [];
@@ -2768,13 +2790,13 @@ Use \`snow_preview_widget\` to see a detailed preview of the widget rendering.`,
             // Handle multiple JSON structure variations: top-level, nested in "flow", nested in "flow_definition"
             let workingDefinition = definition;
             // Check if we have a nested structure like { "flow": { "steps": [...] } }
-            if (definition.flow && typeof definition.flow === 'object') {
+            if (definition && definition.flow && typeof definition.flow === 'object') {
                 workingDefinition = definition.flow;
                 corrections.push('✅ Processing nested flow structure (definition.flow)');
                 info.push('💡 Detected nested flow definition format - extracting flow content');
             }
             // Check if we have nested flow_definition
-            if (definition.flow_definition && typeof definition.flow_definition === 'object') {
+            if (definition && definition.flow_definition && typeof definition.flow_definition === 'object') {
                 workingDefinition = definition.flow_definition;
                 corrections.push('✅ Processing nested flow_definition structure');
             }
@@ -3665,6 +3687,11 @@ Use \`snow_preview_widget\` to see a detailed preview of the widget rendering.`,
     async unifiedDeploy(args) {
         try {
             this.logger.info('Starting unified deployment', args);
+            // CRITICAL: Check authentication FIRST before any deployment
+            const isAuthenticated = await this.oauth.isAuthenticated();
+            if (!isAuthenticated) {
+                throw new types_js_1.McpError(types_js_1.ErrorCode.InvalidRequest, 'Not authenticated. Run "snow-flow auth login" first.');
+            }
             const { type, instruction, config, auto_update_set = true, fallback_strategy = 'manual_steps', permission_escalation = 'auto_request', deployment_context } = args;
             // Step 1: Ensure Update Set session if requested
             let updateSetSession = null;
@@ -3722,10 +3749,16 @@ Use \`snow_preview_widget\` to see a detailed preview of the widget rendering.`,
                         try {
                             const escalationResult = await this.requestPermissionEscalation(error, strategy.scope);
                             if (escalationResult.granted) {
-                                // Retry with escalated permissions
-                                deploymentResult = await this.attemptDirectDeployment(type, deploymentConfig, strategy.scope);
+                                // Use new scope if provided by escalation
+                                const effectiveScope = escalationResult.newScope || strategy.scope;
+                                this.logger.info('Retrying with escalated permissions', {
+                                    originalScope: strategy.scope,
+                                    newScope: effectiveScope
+                                });
+                                // Retry with escalated permissions and potentially new scope
+                                deploymentResult = await this.attemptDirectDeployment(type, deploymentConfig, effectiveScope);
                                 if (deploymentResult.success) {
-                                    return this.formatSuccessResponse(deploymentResult, strategy.scope, updateSetSession, 'escalated');
+                                    return this.formatSuccessResponse(deploymentResult, effectiveScope, updateSetSession, 'escalated');
                                 }
                             }
                         }
@@ -3773,13 +3806,127 @@ Use individual deployment tools like \`snow_deploy_${args.type}\` with manual co
      * Process natural language instruction into deployment configuration
      */
     async processNaturalLanguageInstruction(type, instruction) {
-        // For flows, delegate to flow composer
+        // For flows, create a proper flow structure
         if (type === 'flow') {
-            // This would call the flow composer MCP, but for now return a basic structure
+            // Extract flow name from instruction
+            const flowName = this.extractNameFromInstruction(instruction);
+            // Create a basic flow definition based on the instruction
+            // This is a simplified version - in production, this would call the flow composer
+            const lowerInstruction = instruction.toLowerCase();
+            // Determine trigger type
+            let triggerType = 'manual';
+            let triggerTable = '';
+            if (lowerInstruction.includes('new service catalog request') ||
+                lowerInstruction.includes('new catalog request')) {
+                triggerType = 'record_created';
+                triggerTable = 'sc_request';
+            }
+            else if (lowerInstruction.includes('new incident')) {
+                triggerType = 'record_created';
+                triggerTable = 'incident';
+            }
+            else if (lowerInstruction.includes('updated') || lowerInstruction.includes('changes')) {
+                triggerType = 'record_updated';
+            }
+            // Create activities based on instruction
+            const activities = [];
+            let activityId = 1;
+            // Check for approval requirement
+            if (lowerInstruction.includes('approval') || lowerInstruction.includes('approve')) {
+                // Check for condition
+                if (lowerInstruction.includes('if') &&
+                    (lowerInstruction.includes('monitor') || lowerInstruction.includes('display') ||
+                        lowerInstruction.includes('screen') || lowerInstruction.includes('lcd'))) {
+                    // Add condition activity
+                    activities.push({
+                        id: `activity_${activityId++}`,
+                        name: 'Check Item Type',
+                        type: 'condition',
+                        condition: 'current.cat_item.name.toLowerCase().includes("monitor") || current.cat_item.name.toLowerCase().includes("display") || current.cat_item.name.toLowerCase().includes("screen") || current.cat_item.name.toLowerCase().includes("lcd")',
+                        outputs: {
+                            condition_met: true
+                        }
+                    });
+                }
+                // Add approval activity
+                activities.push({
+                    id: `activity_${activityId++}`,
+                    name: 'Request Approval',
+                    type: 'approval',
+                    approval_type: 'user',
+                    approvers: lowerInstruction.includes('admin') ? 'admin' : 'assignment_group.manager',
+                    inputs: {
+                        record: '${trigger.current}',
+                        approvers: lowerInstruction.includes('admin') ? 'admin' : 'assignment_group.manager'
+                    },
+                    outputs: {
+                        approval_state: '${approval.state}',
+                        approval_comments: '${approval.comments}'
+                    }
+                });
+                // Add wait for approval if mentioned
+                if (lowerInstruction.includes('wait for approval')) {
+                    activities.push({
+                        id: `activity_${activityId++}`,
+                        name: 'Wait for Approval',
+                        type: 'wait',
+                        wait_type: 'approval',
+                        inputs: {
+                            approval_record: '${activity_' + (activityId - 2) + '.approval_id}'
+                        }
+                    });
+                }
+            }
+            // Add update status if mentioned
+            if (lowerInstruction.includes('update') && lowerInstruction.includes('status')) {
+                activities.push({
+                    id: `activity_${activityId++}`,
+                    name: 'Update Request Status',
+                    type: 'update_record',
+                    table: triggerTable || 'sc_request',
+                    inputs: {
+                        record: '${trigger.current}',
+                        fields: {
+                            state: '${activity_' + (activityId - 2) + '.approval_state === "approved" ? "approved" : "rejected"}'
+                        }
+                    }
+                });
+            }
+            // Create flow definition
+            const flowDefinition = {
+                name: flowName,
+                description: instruction,
+                table: triggerTable,
+                trigger: {
+                    type: triggerType,
+                    table: triggerTable,
+                    condition: ''
+                },
+                activities: activities.length > 0 ? activities : [{
+                        id: 'activity_1',
+                        name: 'Log Action',
+                        type: 'log',
+                        message: 'Flow executed for: ' + instruction,
+                        level: 'info'
+                    }],
+                connections: []
+            };
+            // Generate connections between activities
+            for (let i = 0; i < activities.length - 1; i++) {
+                flowDefinition.connections.push({
+                    from: activities[i].id,
+                    to: activities[i + 1].id,
+                    type: 'always'
+                });
+            }
             return {
-                name: this.extractNameFromInstruction(instruction),
+                name: flowName,
                 description: instruction,
-                instruction: instruction
+                flow_definition: flowDefinition,
+                table: triggerTable,
+                trigger_type: triggerType,
+                condition: '',
+                active: true
             };
         }
         // For widgets, delegate to widget composer  
@@ -3788,6 +3935,10 @@ Use individual deployment tools like \`snow_deploy_${args.type}\` with manual co
                 name: this.extractNameFromInstruction(instruction),
                 title: this.extractNameFromInstruction(instruction),
                 description: instruction,
+                template: '<div>Widget placeholder - implement with proper template</div>',
+                css: '',
+                server_script: '',
+                client_script: '',
                 instruction: instruction
             };
         }
@@ -3838,13 +3989,128 @@ Use individual deployment tools like \`snow_deploy_${args.type}\` with manual co
      * Request permission escalation
      */
     async requestPermissionEscalation(error, scope) {
-        // This would integrate with the permission escalation system
-        // For now, return a structured response
+        this.logger.info('Attempting permission escalation', { error: error.message, scope });
+        // Determine required roles based on error message and scope
+        const requiredRoles = this.extractRequiredRoles(error, scope);
+        // Try multiple escalation strategies
+        const escalationStrategies = [
+            {
+                name: 'scoped_deployment',
+                description: 'Switch to scoped application deployment',
+                attempt: async () => {
+                    if (scope === 'global' && requiredRoles.includes('admin')) {
+                        // Fallback to scoped application
+                        this.logger.info('Attempting scoped deployment as fallback');
+                        return {
+                            granted: true,
+                            message: 'Switching to scoped application deployment (no global admin required)',
+                            newScope: 'x_custom_app'
+                        };
+                    }
+                    return { granted: false };
+                }
+            },
+            {
+                name: 'personal_scope',
+                description: 'Use personal developer scope',
+                attempt: async () => {
+                    if (scope !== 'personal') {
+                        this.logger.info('Attempting personal scope deployment');
+                        return {
+                            granted: true,
+                            message: 'Using personal developer scope for deployment',
+                            newScope: 'x_personal_dev'
+                        };
+                    }
+                    return { granted: false };
+                }
+            },
+            {
+                name: 'update_set_only',
+                description: 'Create in Update Set without direct deployment',
+                attempt: async () => {
+                    this.logger.info('Falling back to Update Set only creation');
+                    return {
+                        granted: true,
+                        message: 'Creating artifact definition in Update Set (manual import required)',
+                        newScope: 'update_set',
+                        requiresManualStep: true
+                    };
+                }
+            }
+        ];
+        // Try each escalation strategy
+        for (const strategy of escalationStrategies) {
+            try {
+                const result = await strategy.attempt();
+                if (result.granted) {
+                    return {
+                        granted: true,
+                        message: `${strategy.description}: ${result.message}`,
+                        ...result
+                    };
+                }
+            }
+            catch (err) {
+                this.logger.warn(`Escalation strategy ${strategy.name} failed`, err);
+            }
+        }
+        // If all strategies fail, provide detailed manual guidance
         return {
             granted: false,
-            message: `Permission escalation requested for ${scope} scope. Contact your ServiceNow administrator.`
+            message: this.generatePermissionGuidance(requiredRoles, scope, error)
         };
     }
+    /**
+     * Extract required roles from error message
+     */
+    extractRequiredRoles(error, scope) {
+        const message = error instanceof Error ? error.message : String(error);
+        const roles = [];
+        // Common role patterns in ServiceNow errors
+        if (message.includes('admin') || message.includes('administrator')) {
+            roles.push('admin');
+        }
+        if (message.includes('global') || scope === 'global') {
+            roles.push('global_admin');
+        }
+        if (message.includes('system_administrator')) {
+            roles.push('system_administrator');
+        }
+        if (message.includes('app_creator')) {
+            roles.push('app_creator');
+        }
+        return roles.length > 0 ? roles : ['admin']; // Default to admin if no specific role found
+    }
+    /**
+     * Generate detailed permission guidance
+     */
+    generatePermissionGuidance(roles, scope, error) {
+        const credentials = this.oauth.loadCredentials();
+        const instance = credentials?.then(c => c?.instance) || 'your-instance';
+        return `
+🔐 **Permission Escalation Required**
+
+**Required Roles**: ${roles.join(', ')}
+**Attempted Scope**: ${scope}
+
+**Option 1: Request Role Assignment**
+1. Navigate to: https://${instance}/nav_to.do?uri=sys_user.do?sys_id=<your_user_sys_id>
+2. Go to "Roles" related list
+3. Add roles: ${roles.join(', ')}
+
+**Option 2: Use Delegated Development**
+1. Create artifact in personal scope first
+2. Have admin promote to ${scope} scope
+3. Command: \`snow_deploy --scope personal\`
+
+**Option 3: Manual Import via Update Set**
+1. Export the generated Update Set XML
+2. Import as admin user
+3. Preview and commit the Update Set
+
+**Error Details**: ${error.message || error}`;
+    }
     /**
      * Format successful deployment response
      */
@@ -3881,7 +4147,19 @@ Your artifact has been deployed and is ready for testing.` : ''}
      * Generate manual deployment steps as fallback
      */
     async generateManualDeploymentSteps(type, config, error, updateSetSession) {
-        const steps = this.generateTypeSpecificManualSteps(type, config);
+        const credentials = await this.oauth.loadCredentials();
+        const instance = credentials?.instance || 'your-instance';
+        const steps = await this.generateTypeSpecificManualSteps(type, config, instance);
+        // Generate Update Set XML if available
+        let updateSetXml = '';
+        if (updateSetSession) {
+            try {
+                updateSetXml = await this.generateUpdateSetXML(type, config, updateSetSession);
+            }
+            catch (xmlError) {
+                this.logger.warn('Failed to generate Update Set XML', xmlError);
+            }
+        }
         return {
             content: [{
                     type: 'text',
@@ -3890,42 +4168,123 @@ Your artifact has been deployed and is ready for testing.` : ''}
 🚨 **Deployment Error**: ${error instanceof Error ? error.message : String(error)}
 
 ${updateSetSession ? `📋 **Update Set Ready**: ${updateSetSession.name} (${updateSetSession.update_set_id})
-✅ Manual changes will be automatically tracked in this Update Set.` : ''}
+✅ Manual changes will be automatically tracked in this Update Set.
+🔗 **Update Set URL**: https://${instance}/sys_update_set.do?sys_id=${updateSetSession.update_set_id}` : ''}
 
-🔧 **Manual Deployment Steps:**
+🔧 **Manual Deployment Steps with Direct URLs:**
 
 ${steps}
 
+${updateSetXml ? `📄 **Update Set XML Generated**
+Copy this XML to import the artifact:
+\`\`\`xml
+${updateSetXml.substring(0, 500)}...
+\`\`\`
+💡 Full XML saved to: update_set_${updateSetSession.update_set_id}.xml` : ''}
+
 📊 **After Manual Deployment:**
 ${updateSetSession ? '- Changes are automatically tracked in your active Update Set' : '- Consider creating an Update Set to track your changes'}
 - Test thoroughly in your development environment
 - Complete Update Set when ready for deployment
 
-💡 **Alternative**: Try individual deployment tools like \`snow_deploy_${type}\` with specific parameters.`
+💡 **Quick Actions:**
+- 🔧 Retry with different scope: \`snow_deploy --type ${type} --scope personal\`
+- 📋 Check permissions: \`snow_auth_diagnostics\`
+- 🚀 Use wizard mode: \`snow_${type}_wizard\``
                 }]
         };
     }
     /**
      * Generate type-specific manual steps
      */
-    generateTypeSpecificManualSteps(type, config) {
+    async generateTypeSpecificManualSteps(type, config, instance) {
         switch (type) {
             case 'widget':
-                return `1. Navigate to Service Portal > Widgets in ServiceNow
-2. Click "New" to create a new widget
-3. Set Name: ${config.name || 'Your Widget Name'}
-4. Set Title: ${config.title || config.name || 'Your Widget Title'}
-5. Add HTML template, CSS, and client script as needed
-6. Save and test the widget
-7. Add to a portal page for testing`;
+                return `1. **Open Service Portal Widgets**
+   🔗 URL: https://${instance}/nav_to.do?uri=%2F$sp_widget.do%3Fsys_id%3D-1%26sysparm_stack%3D$sp_widget_list.do
+   
+2. **Click "New" Button** (Top right of the page)
+   📸 Look for: Blue "New" button in the header
+   
+3. **Fill in Widget Details:**
+   - **Name**: ${config.name || 'your_widget_name'} (internal identifier)
+   - **ID**: ${config.id || config.name?.toLowerCase().replace(/\s+/g, '_') || 'widget_id'}
+   - **Title**: ${config.title || 'Your Widget Title'} (display name)
+   - **Description**: ${config.description || 'Widget created via Snow-Flow'}
+   
+4. **Add Widget Code:**
+   **HTML Template** tab:
+   \`\`\`html
+   ${config.template || '<div>Your HTML here</div>'}
+   \`\`\`
+   
+   **CSS - SCSS** tab:
+   \`\`\`css
+   ${config.css || '/* Your styles here */'}
+   \`\`\`
+   
+   **Client Script** tab:
+   \`\`\`javascript
+   ${config.client_script || 'function() {\n  var c = this;\n  // Your client code\n}'}
+   \`\`\`
+   
+   **Server Script** tab:
+   \`\`\`javascript
+   ${config.server_script || '(function() {\n  // Your server code\n})();'}
+   \`\`\`
+
+5. **Save the Widget**
+   - Click "Submit" or use Ctrl+S / Cmd+S
+   - Note the sys_id from the URL for tracking
+
+6. **Test Your Widget**
+   🔗 Test Page URL: https://${instance}/$sp.do?id=widget_editor&sys_id=YOUR_WIDGET_SYS_ID
+   
+7. **Add to Portal Page**
+   🔗 Page Designer: https://${instance}/nav_to.do?uri=%2F$sp_page.do`;
             case 'flow':
-                return `1. Navigate to Process Automation > Flow Designer in ServiceNow
-2. Click "New" > "Flow" (or "Subflow" if applicable)
-3. Set Name: ${config.name || 'Your Flow Name'}
-4. Configure trigger based on your requirements
-5. Add activities and logic as needed
-6. Save and activate the flow
-7. Test with sample data`;
+                return `1. **Open Flow Designer**
+   🔗 URL: https://${instance}/nav_to.do?uri=%2Fflow_designer.do
+   
+2. **Create New Flow**
+   - Click the "+" button or "New" in the top menu
+   - Select "Flow" (not Subflow or Action)
+   
+3. **Configure Flow Properties:**
+   - **Name**: ${config.name || 'approval_flow'}
+   - **Description**: ${config.description || 'Flow created via Snow-Flow'}
+   - **Application**: ${config.application || 'Global'}
+   - **Protection**: None (for development)
+   
+4. **Set Up Trigger** (Step 1 in Flow Designer):
+   - Click "Add a trigger"
+   - Select: "${config.trigger_type || 'Record Created'}"
+   - Table: ${config.table || 'Service Catalog Request [sc_request]'}
+   ${config.condition ? `- Condition: ${config.condition}` : ''}
+   
+5. **Add Flow Logic** (Example for approval flow):
+   a. **Add Approval Action**:
+      - Click "+" after trigger
+      - Search "Approval" 
+      - Select "Ask for Approval"
+      - Approver: ${config.approver || 'Manager of Requested for'}
+      
+   b. **Add Condition**:
+      - Click "+" → "Flow Logic" → "If"
+      - Condition: Approval State = Approved
+      
+   c. **Add Actions in "Then" branch**:
+      - Update Request: State = Approved
+      - Send Notification: To requester
+   
+6. **Save and Activate**
+   - Click "Save" (top right)
+   - Click "Activate" to make flow live
+   
+7. **Test Your Flow**
+   🔗 Test Execution: https://${instance}/nav_to.do?uri=%2Fsys_flow_context_list.do
+   - Create a test ${config.table || 'request'} record
+   - Monitor execution in Flow Designer`;
             case 'application':
                 return `1. Navigate to System Applications > Applications in ServiceNow
 2. Click "New" to create a new application