snow-flow 8.32.13 → 8.33.0

package/CLAUDE.md

@@ -76,7 +76,7 @@ const updateSet = await snow_update_set_manage({
   action: 'create',
   name: "Feature: Incident Auto-Assignment",
   description: "Implements automatic incident assignment based on category and location",
-  application: "global"
+  servicenow_username: 'your.username'  // Optional: to see it in your UI
 });
 console.log(`✅ Created Update Set: ${updateSet.name} (sys_id: ${updateSet.sys_id})`);
 ```
@@ -207,6 +207,48 @@ function test(p) {
 - Automatically captures ALL artifact changes when active
 - Required for moving changes between instances (Dev → Test → Prod)
 
+**⚠️ CRITICAL: OAuth Context & Update Set Visibility**
+
+**snow-flow uses OAuth service account authentication:**
+- All API calls run as an OAuth **service account**, not your UI user
+- Update Sets are created and tracked by this service account
+- Setting an Update Set as "current" affects the **SERVICE ACCOUNT context**
+- Changes are **automatically captured** regardless of what's "current" in your UI
+
+**Understanding the Two Contexts:**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ YOUR UI SESSION (when you log in to ServiceNow UI)         │
+│ User: john.doe                                              │
+│ Current Update Set: [Whatever you selected in UI]          │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────┐
+│ SNOW-FLOW OAUTH SESSION (API calls)                        │
+│ User: oauth.service.account                                 │
+│ Current Update Set: [Set via snow_update_set_manage]       │
+│ ← All snow-flow changes are tracked here                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Key Points:**
+- ✅ **Update Sets ARE created** - they exist in ServiceNow
+- ✅ **Changes ARE tracked** - all snow-flow artifacts go into the Update Set
+- ❌ **NOT visible in YOUR UI** - unless you explicitly set it for your username
+- ✅ **Deployment still works** - Update Set can be exported/imported normally
+
+**To see Update Set as "current" in YOUR ServiceNow UI:**
+
+```javascript
+await snow_update_set_manage({
+  action: 'create',
+  name: "Feature: My Feature",
+  description: "Development work",
+  servicenow_username: 'john.doe'  // ← YOUR ServiceNow username
+});
+```
+
 **The Golden Rule: UPDATE SET FIRST, ALWAYS**
 
 Every development task MUST follow this workflow:
@@ -217,12 +259,12 @@ const updateSet = await snow_update_set_manage({
   action: 'create',
   name: "Feature: [Descriptive Name]",
   description: "Complete description of what and why",
-  application: "global"  // or specific app scope
+  // OPTIONAL: Add your username to see it as current in UI
+  servicenow_username: 'your.username'  // ← Only needed if you want UI visibility
 });
 
-// STEP 2: VERIFY IT'S ACTIVE
-const current = await snow_update_set_query({ action: 'current' });
-console.log(`Active Update Set: ${current.name}`);
+// STEP 2: VERIFY IT'S CREATED (it exists even if not visible in your UI)
+// Changes will be tracked automatically by the service account
 
 // STEP 3: NOW DEVELOP (all changes auto-tracked in Update Set)
 await snow_deploy({
@@ -248,12 +290,14 @@ await snow_update_set_manage({
 - Without an active Update Set, changes are NOT tracked
 - Untracked changes = Cannot deploy to other instances
 - Users will lose work if you skip this step
+- OAuth context means changes may not be visible in your UI without servicenow_username
 
 **Update Set Best Practices:**
 - **ONE feature = ONE Update Set** (clear boundaries)
 - **Descriptive names**: "Feature: Incident Auto-Assignment" NOT "Changes" or "Updates"
 - **Complete descriptions**: What, why, which components affected
 - **Complete when done**: Mark as 'complete' when feature is finished
+- **Use servicenow_username** if user wants to see Update Set as current in their UI
 
 **3. Widget Coherence (HTML ↔ Client ↔ Server)**
 
@@ -804,6 +848,125 @@ Your process:
 
 ---
 
+## 🔗 PROACTIVE INFORMATION FETCHING
+
+### CRITICAL RULE: Always Fetch Instance URL First
+
+**NEVER provide placeholder URLs. ALWAYS fetch the actual instance URL first.**
+
+When you need to provide a ServiceNow URL to the user:
+1. **AUTOMATICALLY** call `snow_get_instance_info` FIRST (without asking)
+2. **THEN** construct the full URL using the actual instance URL
+3. **NEVER** use placeholders like `[je-instance].service-now.com` or `[your-instance]`
+
+**Examples:**
+
+❌ **WRONG - Placeholder URL:**
+```
+The URL is: https://[je-instance].service-now.com/sys_update_set.do?sys_id=123
+```
+
+✅ **CORRECT - Actual URL:**
+```javascript
+// First, get instance info (do this automatically!)
+const info = await snow_get_instance_info()
+// Then provide the actual URL
+const url = `${info.data.instance_url}/sys_update_set.do?sys_id=123`
+```
+
+**This applies to ALL ServiceNow URLs:**
+- Update Set URLs
+- Record URLs
+- Table URLs
+- Widget URLs
+- Any UI links
+
+### Proactive Tool Usage Patterns
+
+**Don't wait for the user to ask - be proactive!**
+
+#### Instance Information
+- When discussing URLs → Automatically use `snow_get_instance_info`
+- When checking configuration → Automatically use `snow_get_instance_info`
+- When verifying connection → Automatically use `snow_get_instance_info`
+
+#### Update Set Operations
+- When user mentions "update set" → Automatically check current with `snow_update_set_current`
+- When starting development → Automatically create update set if none active
+- After creating artifacts → Automatically provide full URL with instance info
+
+#### Error Handling
+- When operations fail → Automatically check logs with `snow_get_logs`
+- When connection fails → Automatically verify with `snow_get_instance_info`
+- When scripts error → Automatically fetch execution logs
+
+#### Post-Completion Actions
+- After creating widgets → Automatically offer preview URL
+- After deployments → Automatically verify success
+- After queries → Automatically offer export options
+
+### Context Awareness
+
+**Remember what you know from previous tool calls.**
+
+- If you just created an update set, you know its sys_id → Don't ask for it
+- If you just queried a record, you know its details → Use them
+- If you checked instance info, you know the URL → Reuse it
+- If user mentions "the widget" and you just created one, you know which one
+
+**Anti-Pattern:**
+```
+❌ User: "Open the update set"
+   You: "Which update set do you want to open?"
+   (You just created one 2 messages ago!)
+```
+
+**Correct Pattern:**
+```
+✅ User: "Open the update set"
+   You: "Opening the update set 'Feature: Dashboard' (sys_id: abc123) that we just created..."
+   [Automatically constructs full URL with instance info]
+```
+
+### Communication Style Guidelines
+
+#### Be Action-Oriented, Not Question-Oriented
+- ✅ "Let me fetch the instance URL and create that update set..."
+- ❌ "Would you like me to create an update set? What should I call it?"
+
+#### Show Results, Don't Describe Actions
+- ✅ [Executes tool] "Created widget 'incident_dashboard' - here's the preview URL: https://dev123.service-now.com/sp?id=..."
+- ❌ "You can create a widget using the snow_create_widget tool..."
+
+#### Provide Complete Information
+- ✅ "Here's the direct URL: https://dev351277.service-now.com/sys_update_set.do?sys_id=abc123"
+- ❌ "Here's the URL: /sys_update_set.do?sys_id=abc123"
+
+#### Smart Suggestions After Completion
+After completing tasks, proactively suggest next steps:
+- After creating widget → "Would you like me to preview it in your instance?"
+- After querying data → "I can export this to CSV/JSON if you'd like"
+- After finding errors → "Shall I help fix these issues?"
+- After deployment → "Would you like me to verify the deployment succeeded?"
+
+### Common Mistakes to Avoid
+
+**❌ DON'T:**
+1. Ask for information you can fetch yourself
+2. Provide incomplete or placeholder URLs
+3. Wait for permission to help (just do it!)
+4. Give generic errors ("something went wrong")
+5. Ask clarifying questions when you have context
+
+**✅ DO:**
+1. Fetch information proactively
+2. Provide complete, clickable URLs
+3. Take initiative to help
+4. Provide specific, actionable information
+5. Use context from previous interactions
+
+---
+
 ## 🎓 FINAL MANDATE
 
 **Your mission** is to transform natural language user intent into concrete ServiceNow artifacts using the 410+ MCP tools available to you.
@@ -817,6 +980,10 @@ Your process:
 6. ✅ Manage context efficiently with lazy loading
 7. ✅ Follow the tool discovery decision tree
 8. ✅ Respect widget coherence (HTML ↔ Client ↔ Server)
+9. ✅ Always fetch instance URL before providing links (NO placeholders!)
+10. ✅ Be proactive - fetch information automatically
+11. ✅ Remember context - don't ask for info you already have
+12. ✅ Provide complete, clickable URLs with full instance info
 
 **Failure modes to avoid:**
 1. ❌ Skipping Update Set workflow
@@ -826,6 +993,10 @@ Your process:
 5. ❌ Using background scripts for development work
 6. ❌ Assuming instead of verifying
 7. ❌ Loading all tools instead of lazy loading
+8. ❌ Providing placeholder URLs like [your-instance].service-now.com
+9. ❌ Asking for information you can fetch automatically
+10. ❌ Forgetting context from previous tool calls
+11. ❌ Waiting for permission when you should take initiative
 
 **Remember:**
 - You are not documenting features - you are **building them**

package/dist/api/health-api.d.ts

@@ -2,7 +2,7 @@
  * Snow-Flow Health Monitoring API
  * Real-time system health and monitoring endpoints
  */
-declare const app: any;
+declare const app: import("express-serve-static-core").Express;
 declare function start(): Promise<void>;
 export { app, start };
 //# sourceMappingURL=health-api.d.ts.map

package/dist/api/health-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"health-api.d.ts","sourceRoot":"","sources":["../../src/api/health-api.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH,QAAA,MAAM,GAAG,KAAY,CAAC;AAyQtB,iBAAe,KAAK,kBAanB;AAoCD,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC"}
+{"version":3,"file":"health-api.d.ts","sourceRoot":"","sources":["../../src/api/health-api.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH,QAAA,MAAM,GAAG,6CAAY,CAAC;AAyQtB,iBAAe,KAAK,kBAanB;AAoCD,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC"}

package/dist/api/simple-health-api.d.ts

@@ -2,6 +2,6 @@
  * Snow-Flow Simple Health Monitoring API
  * Lightweight real-time system health endpoints
  */
-declare const app: any;
+declare const app: import("express-serve-static-core").Express;
 export { app };
 //# sourceMappingURL=simple-health-api.d.ts.map

package/dist/api/simple-health-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"simple-health-api.d.ts","sourceRoot":"","sources":["../../src/api/simple-health-api.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,QAAA,MAAM,GAAG,KAAY,CAAC;AAkhBtB,OAAO,EAAE,GAAG,EAAE,CAAC"}
+{"version":3,"file":"simple-health-api.d.ts","sourceRoot":"","sources":["../../src/api/simple-health-api.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,QAAA,MAAM,GAAG,6CAAY,CAAC;AAkhBtB,OAAO,EAAE,GAAG,EAAE,CAAC"}

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;GAEG;AAysGH,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,KAAK,GAAE,OAAe,GACrB,OAAO,CAAC,IAAI,CAAC,CA+Sf"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;GAEG;AA2hGH,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,KAAK,GAAE,OAAe,GACrB,OAAO,CAAC,IAAI,CAAC,CA+Sf"}

package/dist/cli.js

@@ -57,6 +57,8 @@ const chalk_1 = __importDefault(require("chalk"));
 const prompts = __importStar(require("@clack/prompts"));
 // Load MCP Persistent Guard for bulletproof server protection
 const mcp_persistent_guard_js_1 = require("./utils/mcp-persistent-guard.js");
+// Automatic snow-code update utility
+const auto_update_snow_code_js_1 = require("./utils/auto-update-snow-code.js");
 // Activate MCP guard ONLY for commands that actually use MCP servers
 // Explicitly exclude: init, version, help, auth, export, config commands
 const commandsNeedingMCP = ['swarm', 'status', 'monitor', 'mcp'];
@@ -254,6 +256,22 @@ program
         cliLogger.info(`\n🚀 Snow-Flow v${version_js_1.VERSION}`);
         console.log(chalk_1.default.blue(`📋 ${objective}`));
     }
+    // Ensure snow-code is up-to-date before starting swarm execution
+    try {
+        if (options.verbose) {
+            cliLogger.info('🔄 Checking for snow-code updates...');
+        }
+        const updateResult = await (0, auto_update_snow_code_js_1.autoUpdateSnowCode)(process.cwd(), options.verbose);
+        if (updateResult.success && options.verbose) {
+            cliLogger.info(`✓ Snow-code v${updateResult.mainPackageVersion || 'latest'} ready`);
+        }
+        // Silently continue if update fails - don't block swarm execution
+    }
+    catch (updateErr) {
+        if (options.verbose) {
+            cliLogger.debug('Snow-code update check failed (non-critical):', updateErr);
+        }
+    }
     // Only show detailed config in verbose mode
     if (options.verbose) {
         cliLogger.info(`⚙️  Strategy: ${options.strategy} | Mode: ${options.mode} | Max Agents: ${options.maxAgents}`);
@@ -541,177 +559,12 @@ function stopMCPServers() {
         // Ignore errors
     }
 }
-// Helper function to auto-update SnowCode to latest version
-async function autoUpdateSnowCode(verbose = false) {
-    try {
-        const { execSync } = require('child_process');
-        const { existsSync, readdirSync, rmSync } = require('fs');
-        const { join, dirname } = require('path');
-        if (verbose) {
-            cliLogger.info('🔄 Checking for SnowCode updates...');
-        }
-        // Get current version
-        const currentVersion = execSync('snow-code --version', { encoding: 'utf8' }).trim();
-        // Get latest version from npm
-        const latestVersion = execSync('npm view @groeimetai/snow-code version', { encoding: 'utf8' }).trim();
-        // Helper to find node_modules in current and parent directories
-        const findNodeModules = (startPath) => {
-            const found = [];
-            let currentPath = startPath;
-            // Check up to 3 levels up
-            for (let i = 0; i < 3; i++) {
-                const nodeModulesPath = join(currentPath, 'node_modules', '@groeimetai');
-                if (existsSync(nodeModulesPath)) {
-                    found.push(currentPath);
-                }
-                const parent = dirname(currentPath);
-                if (parent === currentPath)
-                    break; // Reached root
-                currentPath = parent;
-            }
-            return found;
-        };
-        // Helper to update local node_modules
-        const updateLocalNodeModules = (projectRoot) => {
-            const groeimetaiPath = join(projectRoot, 'node_modules', '@groeimetai');
-            if (existsSync(groeimetaiPath)) {
-                // Check main package version AND platform binaries
-                const snowcodePackage = join(groeimetaiPath, 'snow-code', 'package.json');
-                let needsUpdate = false;
-                if (existsSync(snowcodePackage)) {
-                    const pkg = JSON.parse(require('fs').readFileSync(snowcodePackage, 'utf8'));
-                    if (pkg.version !== latestVersion) {
-                        needsUpdate = true;
-                        if (verbose) {
-                            cliLogger.info(`Main package outdated: ${pkg.version} → ${latestVersion}`);
-                        }
-                    }
-                }
-                else {
-                    needsUpdate = true;
-                }
-                // Also check platform binaries (snow-code-darwin-arm64, etc.)
-                if (!needsUpdate) {
-                    try {
-                        const packages = readdirSync(groeimetaiPath);
-                        for (const pkg of packages) {
-                            if (pkg.startsWith('snow-code-')) {
-                                const pkgJsonPath = join(groeimetaiPath, pkg, 'package.json');
-                                if (existsSync(pkgJsonPath)) {
-                                    const pkgJson = JSON.parse(require('fs').readFileSync(pkgJsonPath, 'utf8'));
-                                    if (pkgJson.version !== latestVersion) {
-                                        needsUpdate = true;
-                                        if (verbose) {
-                                            cliLogger.info(`Platform binary outdated: ${pkg}@${pkgJson.version} → ${latestVersion}`);
-                                        }
-                                        break;
-                                    }
-                                }
-                            }
-                        }
-                    }
-                    catch (err) {
-                        if (verbose) {
-                            cliLogger.debug(`Error checking platform binaries: ${err}`);
-                        }
-                    }
-                }
-                if (needsUpdate) {
-                    if (verbose) {
-                        cliLogger.info(`📦 Updating SnowCode in ${projectRoot}...`);
-                    }
-                    // Remove old platform binaries to force reinstall
-                    try {
-                        const packages = readdirSync(groeimetaiPath);
-                        for (const pkg of packages) {
-                            if (pkg.startsWith('snow-code-') || pkg === 'snow-code') {
-                                const pkgPath = join(groeimetaiPath, pkg);
-                                cliLogger.debug(`Removing old package: ${pkg}`);
-                                rmSync(pkgPath, { recursive: true, force: true });
-                            }
-                        }
-                    }
-                    catch (err) {
-                        cliLogger.debug(`Cleanup error: ${err}`);
-                    }
-                    // Remove package-lock.json to ensure fresh install (avoid stale lockfile cache)
-                    const lockfilePath = join(projectRoot, 'package-lock.json');
-                    if (existsSync(lockfilePath)) {
-                        cliLogger.debug('Removing stale package-lock.json');
-                        rmSync(lockfilePath, { force: true });
-                    }
-                    // Install fresh version
-                    execSync('npm install @groeimetai/snow-code@latest', {
-                        stdio: 'inherit',
-                        cwd: projectRoot
-                    });
-                    // Restore executable permissions for platform binaries
-                    try {
-                        const packages = readdirSync(groeimetaiPath);
-                        for (const pkg of packages) {
-                            if (pkg.startsWith('snow-code-')) {
-                                const binPath = join(groeimetaiPath, pkg, 'bin');
-                                if (existsSync(binPath)) {
-                                    const binaries = readdirSync(binPath);
-                                    for (const binary of binaries) {
-                                        const binaryPath = join(binPath, binary);
-                                        try {
-                                            execSync(`chmod +x "${binaryPath}"`, { stdio: 'ignore' });
-                                            cliLogger.debug(`Set executable: ${pkg}/bin/${binary}`);
-                                        }
-                                        catch (err) {
-                                            cliLogger.debug(`Chmod error for ${binary}: ${err}`);
-                                        }
-                                    }
-                                }
-                            }
-                        }
-                    }
-                    catch (err) {
-                        cliLogger.debug(`Error setting permissions: ${err}`);
-                    }
-                    cliLogger.info(`✅ Updated SnowCode in ${projectRoot}`);
-                }
-            }
-        };
-        if (currentVersion !== latestVersion) {
-            cliLogger.info(`📦 Updating SnowCode: ${currentVersion} → ${latestVersion}`);
-            // Update global version
-            execSync('npm install -g @groeimetai/snow-code@latest', { stdio: 'inherit' });
-            // Update all local node_modules
-            const projectRoots = findNodeModules(process.cwd());
-            cliLogger.info(`Found ${projectRoots.length} project(s) with node_modules`);
-            for (const root of projectRoots) {
-                updateLocalNodeModules(root);
-            }
-            cliLogger.info(`✅ SnowCode updated to ${latestVersion}`);
-        }
-        else {
-            cliLogger.info(`✅ SnowCode is up-to-date (${currentVersion})`);
-            // Even if global is up-to-date, check local node_modules
-            const projectRoots = findNodeModules(process.cwd());
-            cliLogger.debug(`Checking ${projectRoots.length} project(s) for local updates`);
-            for (const root of projectRoots) {
-                updateLocalNodeModules(root);
-            }
-        }
-    }
-    catch (error) {
-        // Log error but don't block execution
-        // Silently catch update errors - user can manually update with: npm install -g @groeimetai/snow-code@latest
-        if (verbose) {
-            cliLogger.warn(`⚠️  Auto-update check failed: ${error instanceof Error ? error.message : String(error)}`);
-            cliLogger.debug(`Full error: ${error}`);
-            cliLogger.info('💡 To manually update SnowCode: npm install -g @groeimetai/snow-code@latest');
-        }
-    }
-}
 // Helper function to execute SnowCode directly with the objective
 async function executeSnowCode(objective, options) {
     let mcpServerPIDs = [];
     try {
         // Auto-update SnowCode to latest version
-        await autoUpdateSnowCode(options.verbose);
+        await (0, auto_update_snow_code_js_1.autoUpdateSnowCode)(process.cwd(), options.verbose);
         // Check if SnowCode CLI is available
         const { execSync } = require('child_process');
         try {
@@ -1682,41 +1535,28 @@ program
             await migrationUtil.migrate();
             s.stop('Migration complete');
         }
-        // Install/Update SnowCode (both global and local peer dependency)
+        // Install/Update SnowCode with comprehensive auto-update utility
         const snowcodeSpinner = prompts.spinner();
-        snowcodeSpinner.start('Checking SnowCode installation');
+        snowcodeSpinner.start('Updating snow-code to latest version');
         try {
-            const { execSync } = await Promise.resolve().then(() => __importStar(require('child_process')));
-            // Update GLOBAL snow-code first (used by snow-flow auth login)
-            snowcodeSpinner.message('Updating global @groeimetai/snow-code');
-            try {
-                execSync('npm install -g @groeimetai/snow-code@latest', {
-                    stdio: 'ignore'
-                });
-                snowcodeSpinner.message('Global SnowCode updated to latest');
-            }
-            catch (globalErr) {
-                // Continue even if global update fails
-            }
-            // Update local peer dependency - ALWAYS use @latest to avoid cached old versions
-            snowcodeSpinner.message('Updating local @groeimetai/snow-code');
-            try {
-                // ALWAYS install @latest instead of peerDependency version
-                // This ensures users get the newest features/fixes, not a cached older version
-                execSync('npm install @groeimetai/snow-code@latest', {
-                    stdio: 'ignore',
-                    cwd: targetDir
-                });
-                snowcodeSpinner.message('Local SnowCode updated to latest');
+            const updateResult = await (0, auto_update_snow_code_js_1.autoUpdateSnowCode)(targetDir, false);
+            if (updateResult.success) {
+                snowcodeSpinner.stop(`✓ Snow-code updated to v${updateResult.mainPackageVersion || 'latest'}`);
+                if (updateResult.binaryPackagesUpdated > 0) {
+                    prompts.log.info(`  Updated ${updateResult.binaryPackagesUpdated} platform-specific binaries`);
+                }
             }
-            catch (localErr) {
-                // Continue even if local update fails
+            else {
+                snowcodeSpinner.stop('⚠️  Snow-code update completed with warnings');
+                if (updateResult.errors.length > 0) {
+                    prompts.log.warn('Some updates failed - run manually if needed:');
+                    prompts.log.warn('  npm install -g @groeimetai/snow-code@latest');
+                    prompts.log.warn('  npm run update-deps');
+                }
             }
-            // Verify installation
-            snowcodeSpinner.stop('SnowCode updated (global + local)');
         }
         catch (err) {
-            snowcodeSpinner.stop('Could not update SnowCode');
+            snowcodeSpinner.stop('Could not update snow-code');
             prompts.log.warn('Run: npm install -g @groeimetai/snow-code@latest');
             prompts.log.warn('And: npm run update-deps');
         }