snow-flow 1.4.28 → 1.4.30

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/cli.js CHANGED
@@ -86,158 +86,6 @@ function checkFlowDeprecation(command, objective) {
86
86
  process.exit(1);
87
87
  }
88
88
  }
89
- // Helper function to deploy XML to ServiceNow
90
- async function deployXMLToServiceNow(xmlFile, options = {}) {
91
- const oauth = new snow_oauth_js_1.ServiceNowOAuth();
92
- let tokens;
93
- try {
94
- tokens = await oauth.getStoredTokens();
95
- }
96
- catch (error) {
97
- cliLogger.error('❌ Failed to get authentication tokens:', error);
98
- cliLogger.error('Please run: snow-flow auth login');
99
- return false;
100
- }
101
- if (!tokens || !tokens.accessToken) {
102
- cliLogger.error('❌ Not authenticated. Please run: snow-flow auth login');
103
- return false;
104
- }
105
- try {
106
- // Initialize ServiceNow client
107
- const client = new servicenow_client_js_1.ServiceNowClient();
108
- // Read XML file
109
- if (!(0, fs_2.existsSync)(xmlFile)) {
110
- cliLogger.error(`❌ XML file not found: ${xmlFile}`);
111
- return false;
112
- }
113
- cliLogger.info('📄 Reading XML file...');
114
- const xmlContent = await fs_1.promises.readFile(xmlFile, 'utf-8');
115
- // Import XML as remote update set
116
- cliLogger.info('📤 Importing XML to ServiceNow...');
117
- const importResponse = await client.makeRequest({
118
- method: 'POST',
119
- url: '/api/now/table/sys_remote_update_set',
120
- headers: {
121
- 'Content-Type': 'application/xml',
122
- 'Accept': 'application/json'
123
- },
124
- data: xmlContent
125
- });
126
- if (!importResponse.result || !importResponse.result.sys_id) {
127
- throw new Error('Failed to import XML update set');
128
- }
129
- const remoteUpdateSetId = importResponse.result.sys_id;
130
- cliLogger.info(`✅ XML imported successfully (sys_id: ${remoteUpdateSetId})`);
131
- // Load the update set
132
- cliLogger.info('🔄 Loading update set...');
133
- await client.makeRequest({
134
- method: 'PUT',
135
- url: `/api/now/table/sys_remote_update_set/${remoteUpdateSetId}`,
136
- data: {
137
- state: 'loaded'
138
- }
139
- });
140
- // Find the loaded update set
141
- const loadedResponse = await client.makeRequest({
142
- method: 'GET',
143
- url: '/api/now/table/sys_update_set',
144
- params: {
145
- sysparm_query: `remote_sys_id=${remoteUpdateSetId}`,
146
- sysparm_limit: 1
147
- }
148
- });
149
- if (!loadedResponse.result || loadedResponse.result.length === 0) {
150
- throw new Error('Failed to find loaded update set');
151
- }
152
- const updateSetId = loadedResponse.result[0].sys_id;
153
- const updateSetName = loadedResponse.result[0].name;
154
- cliLogger.info(`✅ Update set loaded: ${updateSetName}`);
155
- // Preview if requested
156
- if (options.preview !== false) {
157
- cliLogger.info('🔍 Previewing update set...');
158
- await client.makeRequest({
159
- method: 'POST',
160
- url: `/api/now/table/sys_update_set/${updateSetId}/preview`
161
- });
162
- // Check preview results
163
- const previewProblems = await client.makeRequest({
164
- method: 'GET',
165
- url: '/api/now/table/sys_update_preview_problem',
166
- params: {
167
- sysparm_query: `update_set=${updateSetId}`,
168
- sysparm_limit: 100
169
- }
170
- });
171
- if (previewProblems.result && previewProblems.result.length > 0) {
172
- cliLogger.warn('\n⚠️ Preview found problems:');
173
- previewProblems.result.forEach((p) => {
174
- cliLogger.warn(` - ${p.type}: ${p.description}`);
175
- });
176
- if (options.commit !== false) {
177
- cliLogger.warn('\n⚠️ Skipping auto-commit due to preview problems');
178
- cliLogger.info('📋 Review and resolve problems in ServiceNow, then commit manually');
179
- return false;
180
- }
181
- }
182
- else {
183
- cliLogger.info('✅ Preview successful - no problems found');
184
- }
185
- // Commit if clean and requested
186
- if (options.commit !== false && (!previewProblems.result || previewProblems.result.length === 0)) {
187
- cliLogger.info('🚀 Committing update set...');
188
- await client.makeRequest({
189
- method: 'POST',
190
- url: `/api/now/table/sys_update_set/${updateSetId}/commit`
191
- });
192
- cliLogger.info('\n✅ Update Set committed successfully!');
193
- cliLogger.info('📍 Navigate to Flow Designer > Designer to see your flow');
194
- cliLogger.info('\n🎉 Deployment complete!');
195
- return true;
196
- }
197
- }
198
- return true;
199
- }
200
- catch (error) {
201
- cliLogger.error('\n❌ Deployment failed:');
202
- // Detailed error handling for 400 errors
203
- if (error.response?.status === 400) {
204
- cliLogger.error(` Status: ${error.response.status} Bad Request`);
205
- if (error.response.data) {
206
- cliLogger.error(` Message: ${error.response.data.error?.message || error.response.data.message || 'Unknown error'}`);
207
- if (error.response.data.error?.detail) {
208
- cliLogger.error(` Detail: ${error.response.data.error.detail}`);
209
- }
210
- if (error.response.data.error?.fields) {
211
- cliLogger.error(' Missing or invalid fields:');
212
- Object.entries(error.response.data.error.fields).forEach(([field, msg]) => {
213
- cliLogger.error(` - ${field}: ${msg}`);
214
- });
215
- }
216
- }
217
- }
218
- else if (error.response?.status === 401) {
219
- cliLogger.error(' Status: 401 Unauthorized - Authentication failed');
220
- cliLogger.error(' Your OAuth token may be expired. Please run: snow-flow auth login');
221
- }
222
- else if (error.response?.status === 403) {
223
- cliLogger.error(' Status: 403 Forbidden - Insufficient permissions');
224
- cliLogger.error(' You need admin or update_set_admin role to import update sets');
225
- }
226
- else if (error.response) {
227
- cliLogger.error(` Status: ${error.response.status}`);
228
- cliLogger.error(` Message: ${error.response.data?.error?.message || error.response.statusText}`);
229
- }
230
- else {
231
- cliLogger.error(` ${error instanceof Error ? error.message : String(error)}`);
232
- }
233
- cliLogger.info('\n💡 Troubleshooting tips:');
234
- cliLogger.info(' 1. Check your authentication: snow-flow auth status');
235
- cliLogger.info(' 2. Verify XML file format is correct');
236
- cliLogger.info(' 3. Ensure you have required permissions in ServiceNow');
237
- cliLogger.info(' 4. Check ServiceNow system logs for more details');
238
- return false;
239
- }
240
- }
241
89
  // Swarm command - the main orchestration command with EVERYTHING
242
90
  program
243
91
  .command('swarm <objective>')
@@ -2197,24 +2045,6 @@ program
2197
2045
  console.log('❌ Invalid action. Use: login, logout, or status');
2198
2046
  }
2199
2047
  });
2200
- // Deploy XML command
2201
- program
2202
- .command('deploy-xml <xmlFile>')
2203
- .description('Deploy XML update set to ServiceNow (auto-import, preview, and commit)')
2204
- .option('--no-preview', 'Skip preview step')
2205
- .option('--no-commit', 'Skip auto-commit (preview only)')
2206
- .action(async (xmlFile, options) => {
2207
- console.log(`\n📦 Deploying XML Update Set: ${xmlFile}`);
2208
- console.log('='.repeat(60));
2209
- // Use the shared deploy function
2210
- const success = await deployXMLToServiceNow(xmlFile, {
2211
- preview: options.preview,
2212
- commit: options.commit
2213
- });
2214
- if (!success) {
2215
- process.exit(1);
2216
- }
2217
- });
2218
2048
  // Initialize Snow-Flow project
2219
2049
  program
2220
2050
  .command('init')
@@ -2311,7 +2141,6 @@ program
2311
2141
  memory <action> Memory operations
2312
2142
  auth <action> Authentication management
2313
2143
  mcp <action> Manage ServiceNow MCP servers
2314
- deploy-xml <file> Deploy XML update set to ServiceNow
2315
2144
  help Show this help
2316
2145
 
2317
2146
  🎯 Example Usage:
@@ -2321,7 +2150,6 @@ program
2321
2150
  snow-flow mcp status # Check MCP server status
2322
2151
  snow-flow swarm "create a widget for incident management"
2323
2152
  snow-flow swarm "create approval flow" # 🔧 Auto-detects Flow Designer and uses XML!
2324
- snow-flow deploy-xml flow-update-sets/my_flow.xml # 🚀 Auto-import to ServiceNow!
2325
2153
  snow-flow spawn widget-builder --name "IncidentWidget"
2326
2154
  snow-flow monitor --duration 120
2327
2155
  snow-flow memory store "project" "incident_system"
@@ -2799,648 +2627,6 @@ Built with the power of Claude AI and the ServiceNow platform. Special thanks to
2799
2627
  await fs_1.promises.writeFile((0, path_1.join)(targetDir, 'memory/agents/README.md'), '# Agent Memory\n\nThis directory contains persistent memory for ServiceNow agents.');
2800
2628
  await fs_1.promises.writeFile((0, path_1.join)(targetDir, 'servicenow/README.md'), '# ServiceNow Artifacts\n\nThis directory contains generated ServiceNow development artifacts.');
2801
2629
  }
2802
- async function createSparcFiles(targetDir) {
2803
- const sparcModes = [
2804
- 'orchestrator', 'coder', 'researcher', 'tdd', 'architect', 'reviewer',
2805
- 'debugger', 'tester', 'analyzer', 'optimizer', 'documenter', 'designer',
2806
- 'innovator', 'swarm-coordinator', 'memory-manager', 'batch-executor', 'workflow-manager'
2807
- ];
2808
- for (const mode of sparcModes) {
2809
- const content = `# SPARC ${mode.charAt(0).toUpperCase() + mode.slice(1)} Mode
2810
-
2811
- ## Overview
2812
- Specialized ${mode} capabilities for ServiceNow development.
2813
-
2814
- ## Purpose
2815
- Provide ${mode} expertise for ServiceNow projects.
2816
-
2817
- ## Usage
2818
- \`\`\`bash
2819
- snow-flow sparc ${mode} "your task description"
2820
- \`\`\`
2821
-
2822
- This mode provides specialized ${mode} capabilities for ServiceNow development projects.
2823
- `;
2824
- await fs_1.promises.writeFile((0, path_1.join)(targetDir, `.claude/commands/sparc/${mode}.md`), content);
2825
- }
2826
- // Create additional swarm documentation files
2827
- console.log('📋 Creating swarm patterns documentation...');
2828
- // Create swarm-patterns.md
2829
- const swarmPatternsContent = `# Swarm Command Patterns - MCP-FIRST Workflow
2830
-
2831
- ## 🎯 Primary Interface: snow-flow swarm
2832
-
2833
- The swarm command is your primary interface for ServiceNow development. It uses the Queen Agent backend to orchestrate multiple specialized agents through Claude Code.
2834
-
2835
- ## Basic Widget Creation
2836
- \`\`\`bash
2837
- snow-flow swarm "create incident dashboard widget"
2838
- snow-flow swarm "build responsive widget with Chart.js for incident analytics"
2839
- snow-flow swarm "create service portal widget for hardware requests"
2840
- \`\`\`
2841
-
2842
- ## Flow Development
2843
- \`\`\`bash
2844
- snow-flow swarm "create approval workflow for equipment requests"
2845
- snow-flow swarm "build multi-step approval flow with email notifications"
2846
- snow-flow swarm "create automated incident escalation workflow"
2847
- \`\`\`
2848
-
2849
- ## Complex Integration
2850
- \`\`\`bash
2851
- snow-flow swarm "integrate ServiceNow with Slack notifications"
2852
- snow-flow swarm "create REST API integration with external ticketing system"
2853
- snow-flow swarm "build bi-directional sync with Microsoft Teams"
2854
- \`\`\`
2855
-
2856
- ## Testing Patterns
2857
- \`\`\`bash
2858
- snow-flow swarm "test existing flows and create comprehensive test report"
2859
- snow-flow swarm "validate all widgets in service portal for mobile responsiveness"
2860
- snow-flow swarm "performance test catalog item workflows"
2861
- \`\`\`
2862
-
2863
- ## Application Development
2864
- \`\`\`bash
2865
- snow-flow swarm "create complete ITSM solution with custom tables"
2866
- snow-flow swarm "build employee onboarding application with approval flows"
2867
- snow-flow swarm "develop asset management system with automated workflows"
2868
- \`\`\`
2869
-
2870
- ## Advanced Patterns with Options
2871
-
2872
- ### Disable Auto-Deploy for Testing
2873
- \`\`\`bash
2874
- snow-flow swarm "test new widget locally" --no-auto-deploy --no-live-testing
2875
- \`\`\`
2876
-
2877
- ### Enable Permission Escalation
2878
- \`\`\`bash
2879
- snow-flow swarm "create global enterprise workflow" --auto-permissions
2880
- \`\`\`
2881
-
2882
- ### Parallel Execution for Large Projects
2883
- \`\`\`bash
2884
- snow-flow swarm "migrate 50 workflows from legacy system" --parallel --max-agents 8
2885
- \`\`\`
2886
-
2887
- ### Monitor Real-Time Progress
2888
- \`\`\`bash
2889
- snow-flow swarm "complex ITSM implementation" --monitor
2890
- \`\`\`
2891
-
2892
- ## 🔐 MCP-FIRST Workflow
2893
-
2894
- Every swarm command follows this mandatory workflow:
2895
-
2896
- 1. **Authentication Check**: Validates ServiceNow OAuth credentials
2897
- 2. **Smart Discovery**: Finds existing artifacts to prevent duplication
2898
- 3. **Live Development**: Creates real artifacts in ServiceNow
2899
- 4. **Update Set Tracking**: All changes tracked for deployment
2900
-
2901
- ## 💡 Best Practices
2902
-
2903
- - Start simple: Let the Queen Agent determine complexity
2904
- - Use natural language: Describe what you want, not how to build it
2905
- - Trust the defaults: Intelligent features are enabled automatically
2906
- - Monitor progress: Use --monitor for long-running tasks
2907
-
2908
- ## 🎯 Common Success Patterns
2909
-
2910
- ### Pattern 1: Quick Widget
2911
- \`\`\`bash
2912
- snow-flow swarm "simple dashboard widget"
2913
- # Queen Agent will:
2914
- # - Spawn widget-creator agent
2915
- # - Create HTML/CSS/JS
2916
- # - Deploy to ServiceNow
2917
- # - Test automatically
2918
- \`\`\`
2919
-
2920
- ### Pattern 2: Complex Flow
2921
- \`\`\`bash
2922
- snow-flow swarm "multi-department approval workflow with dynamic routing"
2923
- # Queen Agent will:
2924
- # - Spawn flow-builder, tester, and security agents
2925
- # - Design flow architecture
2926
- # - Implement with conditions
2927
- # - Test all paths
2928
- # - Validate permissions
2929
- \`\`\`
2930
-
2931
- ### Pattern 3: Full Application
2932
- \`\`\`bash
2933
- snow-flow swarm "complete HR onboarding system"
2934
- # Queen Agent will:
2935
- # - Spawn app-architect, flow-builder, widget-creator, tester
2936
- # - Design data model
2937
- # - Create tables and relationships
2938
- # - Build UI components
2939
- # - Implement workflows
2940
- # - Test end-to-end
2941
- \`\`\`
2942
- `;
2943
- await fs_1.promises.writeFile((0, path_1.join)(targetDir, '.claude/commands/swarm-patterns.md'), swarmPatternsContent);
2944
- // Create agent-types.md
2945
- const agentTypesContent = `# Agent Types and Specializations
2946
-
2947
- ## 🤖 Primary Development Agents
2948
-
2949
- ### widget-creator
2950
- **Specialization**: Service Portal widgets, HTML/CSS/JS, responsive design
2951
- **When spawned**: Any widget-related objective
2952
- **Key capabilities**:
2953
- - HTML template generation
2954
- - CSS styling and animations
2955
- - Client-side JavaScript controllers
2956
- - Server-side data scripts
2957
- - Chart.js and data visualization
2958
- - Mobile responsiveness
2959
-
2960
- ### flow-builder
2961
- **Specialization**: Flow Designer, process automation, approvals
2962
- **When spawned**: Workflow and automation objectives
2963
- **Key capabilities**:
2964
- - Trigger configuration
2965
- - Conditional logic
2966
- - Approval routing
2967
- - Email notifications
2968
- - Integration with catalog items
2969
- - Subflow creation
2970
-
2971
- ### script-writer
2972
- **Specialization**: Business rules, script includes, client scripts
2973
- **When spawned**: Scripting and automation objectives
2974
- **Key capabilities**:
2975
- - GlideRecord operations
2976
- - Business rule creation
2977
- - Script include development
2978
- - Background scripts
2979
- - Fix scripts
2980
- - Scheduled jobs
2981
-
2982
- ### app-architect
2983
- **Specialization**: Application design, data modeling, system architecture
2984
- **When spawned**: Full application development
2985
- **Key capabilities**:
2986
- - Table design and relationships
2987
- - Application scoping
2988
- - Security model design
2989
- - Integration architecture
2990
- - Performance optimization
2991
- - Scalability planning
2992
-
2993
- ## 🛠️ Supporting Agents
2994
-
2995
- ### researcher
2996
- **Specialization**: Discovery, best practices, documentation
2997
- **When spawned**: Complex or unknown requirements
2998
- **Key capabilities**:
2999
- - ServiceNow best practices
3000
- - Platform feature discovery
3001
- - Existing artifact analysis
3002
- - Documentation generation
3003
- - Knowledge base creation
3004
-
3005
- ### tester
3006
- **Specialization**: Quality assurance, validation, performance testing
3007
- **When spawned**: After any development task
3008
- **Key capabilities**:
3009
- - Unit test creation
3010
- - Integration testing
3011
- - UI/UX validation
3012
- - Performance benchmarking
3013
- - Security testing
3014
- - Accessibility compliance
3015
-
3016
- ### security
3017
- **Specialization**: Access controls, compliance, vulnerability assessment
3018
- **When spawned**: Enterprise or sensitive applications
3019
- **Key capabilities**:
3020
- - ACL configuration
3021
- - Role management
3022
- - Data encryption
3023
- - Compliance validation
3024
- - Security scanning
3025
- - Audit trail setup
3026
-
3027
- ### ui-designer
3028
- **Specialization**: User experience, design patterns, accessibility
3029
- **When spawned**: Complex UI requirements
3030
- **Key capabilities**:
3031
- - Design system implementation
3032
- - Accessibility (WCAG) compliance
3033
- - Responsive layouts
3034
- - User journey mapping
3035
- - Style guide creation
3036
-
3037
- ## 🎯 How Agents are Selected
3038
-
3039
- The Queen Agent analyzes your objective and automatically selects the optimal team:
3040
-
3041
- ### Example 1: "create incident dashboard"
3042
- - **Primary**: widget-creator
3043
- - **Supporting**: ui-designer, tester
3044
- - **Reasoning**: Widget development with UI focus
3045
-
3046
- ### Example 2: "build approval workflow"
3047
- - **Primary**: flow-builder
3048
- - **Supporting**: security, tester
3049
- - **Reasoning**: Process automation with security needs
3050
-
3051
- ### Example 3: "create ITSM application"
3052
- - **Primary**: app-architect
3053
- - **Supporting**: flow-builder, widget-creator, security, tester
3054
- - **Reasoning**: Full application requiring all capabilities
3055
-
3056
- ## 💡 Agent Coordination Patterns
3057
-
3058
- ### Sequential Coordination
3059
- Used when tasks have dependencies:
3060
- \`\`\`
3061
- app-architect → widget-creator → flow-builder → tester
3062
- \`\`\`
3063
-
3064
- ### Parallel Coordination
3065
- Used when tasks are independent:
3066
- \`\`\`
3067
- widget-creator ⟷ flow-builder ⟷ script-writer
3068
- ↓ ↓ ↓
3069
- tester
3070
- \`\`\`
3071
-
3072
- ### Hybrid Coordination
3073
- Used for complex projects:
3074
- \`\`\`
3075
- Phase 1: app-architect (solo)
3076
- Phase 2: widget-creator + flow-builder (parallel)
3077
- Phase 3: security + tester (parallel)
3078
- Phase 4: Final integration (sequential)
3079
- \`\`\`
3080
-
3081
- ## 🔧 Manual Agent Control
3082
-
3083
- While the Queen Agent handles selection automatically, you can influence agent selection:
3084
-
3085
- ### Request Specific Expertise
3086
- \`\`\`bash
3087
- snow-flow swarm "create widget with heavy security focus"
3088
- # Queen will prioritize security agent
3089
- \`\`\`
3090
-
3091
- ### Exclude Certain Agents
3092
- \`\`\`bash
3093
- snow-flow swarm "simple widget" --max-agents 2
3094
- # Queen will use only essential agents
3095
- \`\`\`
3096
-
3097
- ### Force Comprehensive Team
3098
- \`\`\`bash
3099
- snow-flow swarm "production-ready incident system" --max-agents 8
3100
- # Queen will assemble full team with all specialists
3101
- \`\`\`
3102
- `;
3103
- await fs_1.promises.writeFile((0, path_1.join)(targetDir, '.claude/commands/agent-types.md'), agentTypesContent);
3104
- // Create mcp-tools-quick-ref.md
3105
- const mcpToolsContent = `# MCP Tools Quick Reference
3106
-
3107
- ## 🔐 Authentication & Connection
3108
-
3109
- ### snow_validate_live_connection
3110
- \`\`\`javascript
3111
- snow_validate_live_connection({
3112
- test_level: "permissions" // basic, full, permissions
3113
- })
3114
- \`\`\`
3115
- **Use for**: Checking ServiceNow connection and OAuth status
3116
-
3117
- ### snow_auth_diagnostics
3118
- \`\`\`javascript
3119
- snow_auth_diagnostics({
3120
- include_recommendations: true,
3121
- run_write_test: true
3122
- })
3123
- \`\`\`
3124
- **Use for**: Debugging authentication issues
3125
-
3126
- ## 🔍 Discovery & Search
3127
-
3128
- ### snow_find_artifact
3129
- \`\`\`javascript
3130
- snow_find_artifact({
3131
- query: "incident dashboard widget",
3132
- type: "widget" // widget, flow, script, application, any
3133
- })
3134
- \`\`\`
3135
- **Use for**: Finding existing ServiceNow artifacts with natural language
3136
-
3137
- ### snow_catalog_item_search
3138
- \`\`\`javascript
3139
- snow_catalog_item_search({
3140
- query: "laptop",
3141
- fuzzy_match: true,
3142
- include_variables: true
3143
- })
3144
- \`\`\`
3145
- **Use for**: Finding catalog items with intelligent matching
3146
-
3147
- ### snow_get_by_sysid
3148
- \`\`\`javascript
3149
- snow_get_by_sysid({
3150
- sys_id: "<artifact_sys_id>",
3151
- table: "sp_widget"
3152
- })
3153
- \`\`\`
3154
- **Use for**: Direct lookup when you have the sys_id
3155
-
3156
- ## 🚀 Deployment Tools
3157
-
3158
- ### snow_deploy (Universal - v1.1.73+)
3159
- \`\`\`javascript
3160
- snow_deploy({
3161
- type: "widget", // widget, flow, application, script, batch
3162
- config: {
3163
- name: "incident_dashboard",
3164
- title: "Incident Dashboard",
3165
- template: htmlContent,
3166
- css: cssContent,
3167
- client_script: clientJS,
3168
- server_script: serverJS
3169
- },
3170
- auto_update_set: true
3171
- })
3172
- \`\`\`
3173
- **Use for**: All deployments - replaces individual deploy tools
3174
-
3175
- ## 🔄 Flow Development
3176
-
3177
- ### snow_create_flow
3178
- \`\`\`javascript
3179
- snow_create_flow({
3180
- instruction: "create approval flow for purchases over $1000",
3181
- deploy_immediately: true,
3182
- enable_intelligent__analysis: true
3183
- })
3184
- \`\`\`
3185
- **Use for**: Creating flows from natural language
3186
-
3187
- ### snow_test_flow_with_mock
3188
- \`\`\`javascript
3189
- snow_test_flow_with_mock({
3190
- flow_id: "equipment_approval",
3191
- create_test_user: true,
3192
- mock_catalog_items: true,
3193
- simulate_approvals: true,
3194
- cleanup_after_test: true
3195
- })
3196
- \`\`\`
3197
- **Use for**: Testing flows without affecting real data
3198
-
3199
- ### snow_link_catalog_to_flow
3200
- \`\`\`javascript
3201
- snow_link_catalog_to_flow({
3202
- catalog_item_id: "New Laptop",
3203
- flow_id: "laptop_provisioning",
3204
- variable_mapping: [{
3205
- catalog_variable: "model",
3206
- flow_input: "equipment_type"
3207
- }]
3208
- })
3209
- \`\`\`
3210
- **Use for**: Connecting catalog items to flows
3211
-
3212
- ## 📦 Update Set Management
3213
-
3214
- ### snow_update_set_create
3215
- \`\`\`javascript
3216
- snow_update_set_create({
3217
- name: "Widget Development - Jan 2024",
3218
- description: "Dashboard widgets for incident management",
3219
- auto_switch: true
3220
- })
3221
- \`\`\`
3222
- **Use for**: Creating new update sets
3223
-
3224
- ### snow_update_set_add_artifact
3225
- \`\`\`javascript
3226
- snow_update_set_add_artifact({
3227
- type: "widget",
3228
- sys_id: "<artifact_sys_id>",
3229
- name: "incident_dashboard"
3230
- })
3231
- \`\`\`
3232
- **Use for**: Tracking artifacts in update sets
3233
-
3234
- ### snow_smart_update_set
3235
- \`\`\`javascript
3236
- snow_smart_update_set({
3237
- detect_context: true,
3238
- separate_by_task: true,
3239
- close_previous: true
3240
- })
3241
- \`\`\`
3242
- **Use for**: Automatic update set management
3243
-
3244
- ## 🧪 Testing Tools
3245
-
3246
- ### snow_widget_test
3247
- \`\`\`javascript
3248
- snow_widget_test({
3249
- sys_id: "widget_sys_id",
3250
- test_scenarios: [{
3251
- name: "No data test",
3252
- input: { incidents: [] },
3253
- expected: { message: "No incidents found" }
3254
- }],
3255
- validate_dependencies: true
3256
- })
3257
- \`\`\`
3258
- **Use for**: Widget functionality testing
3259
-
3260
- ### snow_comprehensive_flow_test
3261
- \`\`\`javascript
3262
- snow_comprehensive_flow_test({
3263
- flow_sys_id: "flow_id",
3264
- test_data_generation: "automatic",
3265
- edge_case_detection: true,
3266
- performance_validation: true
3267
- })
3268
- \`\`\`
3269
- **Use for**: Comprehensive flow testing
3270
-
3271
- ## 🔄 Batch Operations
3272
-
3273
- ### Parallel Tool Execution
3274
- \`\`\`javascript
3275
- // Execute multiple operations in one message
3276
- Promise.all([
3277
- snow_find_artifact({ query: "widget" }),
3278
- snow_catalog_item_search({ query: "laptop" }),
3279
- snow_update_set_current()
3280
- ])
3281
- \`\`\`
3282
- **Use for**: Maximum performance with concurrent operations
3283
-
3284
- ## 💡 Common Patterns
3285
-
3286
- ### Pre-flight Check Pattern
3287
- \`\`\`javascript
3288
- // Always start with authentication
3289
- const auth = await snow_validate_live_connection();
3290
- if (!auth.success) {
3291
- // Switch to planning mode
3292
- return "Run: snow-flow auth login";
3293
- }
3294
-
3295
- // Then discover existing artifacts
3296
- const existing = await snow_find_artifact({
3297
- query: "similar to what I want to create"
3298
- });
3299
-
3300
- // Finally deploy new artifact
3301
- const result = await snow_deploy({
3302
- type: "widget",
3303
- config: widgetConfig
3304
- });
3305
- \`\`\`
3306
-
3307
- ### Error Recovery Pattern
3308
- \`\`\`javascript
3309
- try {
3310
- await snow_deploy({ type: "flow", config });
3311
- } catch (error) {
3312
- if (error.includes("permissions")) {
3313
- // Try global scope
3314
- await snow_escalate_permissions();
3315
- } else if (error.includes("validation")) {
3316
- // Create manual deployment guide
3317
- await snow_create_manual_guide();
3318
- }
3319
- }
3320
- \`\`\`
3321
-
3322
- ### Update Set Pattern
3323
- \`\`\`javascript
3324
- // Ensure update set exists
3325
- await snow_smart_update_set();
3326
-
3327
- // Deploy artifact
3328
- const artifact = await snow_deploy({ type: "widget", config });
3329
-
3330
- // Track in update set
3331
- await snow_update_set_add_artifact({
3332
- type: "widget",
3333
- sys_id: artifact.sys_id,
3334
- name: artifact.name
3335
- });
3336
- \`\`\`
3337
- `;
3338
- await fs_1.promises.writeFile((0, path_1.join)(targetDir, '.claude/commands/mcp-tools-quick-ref.md'), mcpToolsContent);
3339
- // Create examples directory
3340
- await fs_1.promises.mkdir((0, path_1.join)(targetDir, 'examples'), { recursive: true });
3341
- // Create memory patterns directory and sample patterns
3342
- await fs_1.promises.mkdir((0, path_1.join)(targetDir, 'memory/patterns'), { recursive: true });
3343
- const successfulPatternsContent = {
3344
- patterns: [
3345
- {
3346
- objective: "create incident dashboard widget",
3347
- agents: ["widget-creator", "ui-designer", "tester"],
3348
- mcpTools: ["snow_deploy", "snow_widget_test", "snow_preview_widget"],
3349
- successRate: 0.95,
3350
- avgDuration: "5-10 minutes",
3351
- commonIssues: ["Missing Chart.js dependency", "Mobile responsiveness"],
3352
- bestPractices: ["Always test on mobile", "Use Chart.js from CDN"]
3353
- },
3354
- {
3355
- objective: "create approval workflow",
3356
- agents: ["flow-builder", "security", "tester"],
3357
- mcpTools: ["snow_create_flow", "snow_test_flow_with_mock", "snow_link_catalog_to_flow"],
3358
- successRate: 0.92,
3359
- avgDuration: "10-15 minutes",
3360
- commonIssues: ["Complex approval routing", "Email notification setup"],
3361
- bestPractices: ["Test all approval paths", "Use mock data first"]
3362
- },
3363
- {
3364
- objective: "create ITSM application",
3365
- agents: ["app-architect", "flow-builder", "widget-creator", "security", "tester"],
3366
- mcpTools: ["snow_deploy", "snow_create_flow", "snow_update_set_create"],
3367
- successRate: 0.88,
3368
- avgDuration: "30-45 minutes",
3369
- commonIssues: ["Table relationships", "Permission model"],
3370
- bestPractices: ["Design data model first", "Use Update Sets throughout"]
3371
- }
3372
- ],
3373
- agentCapabilities: {
3374
- "widget-creator": {
3375
- strengths: ["HTML/CSS/JS", "Chart.js", "Responsive design"],
3376
- limitations: ["Complex backend logic", "Database design"]
3377
- },
3378
- "flow-builder": {
3379
- strengths: ["Process automation", "Conditional logic", "Approvals"],
3380
- limitations: ["UI development", "Complex integrations"]
3381
- },
3382
- "app-architect": {
3383
- strengths: ["System design", "Data modeling", "Architecture"],
3384
- limitations: ["Detailed implementation", "UI/UX design"]
3385
- }
3386
- },
3387
- mcpToolPatterns: {
3388
- "authentication_first": {
3389
- pattern: "Always start with snow_validate_live_connection",
3390
- reason: "Ensures OAuth is valid before attempting operations"
3391
- },
3392
- "discovery_before_creation": {
3393
- pattern: "Use snow_find_artifact before snow_deploy",
3394
- reason: "Prevents duplicate artifacts and wasted effort"
3395
- },
3396
- "update_set_tracking": {
3397
- pattern: "Create Update Set, deploy, then track artifacts",
3398
- reason: "Professional change management like ServiceNow pros"
3399
- }
3400
- }
3401
- };
3402
- await fs_1.promises.writeFile((0, path_1.join)(targetDir, 'memory/patterns/successful-deployments.json'), JSON.stringify(successfulPatternsContent, null, 2));
3403
- // Create workflow patterns JSON
3404
- const workflowPatternsContent = {
3405
- workflowTemplates: [
3406
- {
3407
- name: "Standard Widget Development",
3408
- steps: [
3409
- "snow_validate_live_connection",
3410
- "snow_find_artifact (check existing)",
3411
- "snow_update_set_create",
3412
- "snow_deploy (type: widget)",
3413
- "snow_widget_test",
3414
- "snow_update_set_add_artifact"
3415
- ]
3416
- },
3417
- {
3418
- name: "Flow Development with Testing",
3419
- steps: [
3420
- "snow_validate_live_connection",
3421
- "snow_discover_existing_flows",
3422
- "snow_create_flow (with deploy_immediately: true)",
3423
- "snow_test_flow_with_mock",
3424
- "snow_link_catalog_to_flow (if needed)",
3425
- "snow_comprehensive_flow_test (if authenticated)"
3426
- ]
3427
- },
3428
- {
3429
- name: "Full Application Deployment",
3430
- steps: [
3431
- "snow_validate_live_connection",
3432
- "snow_analyze_requirements",
3433
- "snow_update_set_create",
3434
- "snow_deploy (multiple artifacts)",
3435
- "snow_create_flow (for flows)",
3436
- "snow_deploy (for widgets)",
3437
- "snow_update_set_complete"
3438
- ]
3439
- }
3440
- ]
3441
- };
3442
- await fs_1.promises.writeFile((0, path_1.join)(targetDir, 'memory/patterns/workflow-templates.json'), JSON.stringify(workflowPatternsContent, null, 2));
3443
- }
3444
2630
  // Helper functions
3445
2631
  async function copyCLAUDEmd(targetDir, force = false) {
3446
2632
  let claudeMdContent = '';