snow-flow 3.6.4 → 3.6.6

package/.mcp.json.template

@@ -199,7 +199,7 @@
       "args": [
         "{{PROJECT_ROOT}}/dist/mcp/servicenow-local-development-mcp.js"
       ],
-      "description": "Local development bridge for Claude Code - pull any ServiceNow artifact to local files with native tool integration (snow_pull_artifact, snow_push_artifact, snow_validate_artifact_coherence), smart field chunking for large artifacts, ES5 validation, coherence checking, 12+ artifact types support",
+      "description": "UNIVERSAL ARTIFACT DETECTION v3.6.6 - finds ANY ServiceNow record by sys_id using sys_metadata! Pull any artifact (even custom tables) to local files with Claude Code native tools. Supports all tables, generic artifact creation for unknown types, smart chunking, ES5 validation, coherence checking. Tools: snow_pull_artifact, snow_push_artifact, snow_validate_artifact_coherence",
       "env": {
         "SNOW_INSTANCE": "{{SNOW_INSTANCE}}",
         "SNOW_CLIENT_ID": "{{SNOW_CLIENT_ID}}",

package/dist/cli.js

@@ -2646,6 +2646,125 @@ async function createMCPConfig(targetDir, force = false) {
     const claudeSettingsPath = (0, path_1.join)(targetDir, '.claude/settings.json');
     await fs_1.promises.writeFile(claudeSettingsPath, JSON.stringify(claudeSettings, null, 2));
 }
+// Setup MCP configuration function
+async function setupMCPConfig(targetDir, instanceUrl, clientId, clientSecret, force = false) {
+    // Find the Snow-Flow installation root
+    let snowFlowRoot = '';
+    // Try different locations to find the Snow-Flow root
+    const possiblePaths = [
+        (0, path_1.join)(targetDir, 'node_modules/snow-flow'),
+        (0, path_1.join)(targetDir, '../snow-flow-dev/snow-flow'),
+        (0, path_1.join)(process.env.HOME || '', 'Projects/snow-flow-dev/snow-flow'),
+        __dirname.includes('dist') ? (0, path_1.resolve)(__dirname, '..') : __dirname
+    ];
+    for (const testPath of possiblePaths) {
+        try {
+            await fs_1.promises.access((0, path_1.join)(testPath, '.mcp.json.template'));
+            snowFlowRoot = testPath;
+            break;
+        }
+        catch {
+            // Keep trying
+        }
+    }
+    if (!snowFlowRoot) {
+        // Last resort: assume we're running from the installed package
+        snowFlowRoot = (0, path_1.resolve)(__dirname, '..');
+        // Verify we can find the template
+        try {
+            await fs_1.promises.access((0, path_1.join)(snowFlowRoot, '.mcp.json.template'));
+        }
+        catch {
+            throw new Error('Could not find snow-flow project root');
+        }
+    }
+    // Read the template file
+    const templatePath = (0, path_1.join)(snowFlowRoot, '.mcp.json.template');
+    let templateContent;
+    try {
+        templateContent = await fs_1.promises.readFile(templatePath, 'utf-8');
+    }
+    catch (error) {
+        console.error('❌ Could not find .mcp.json.template file');
+        throw error;
+    }
+    // Replace placeholders in template
+    const mcpConfigContent = templateContent
+        .replace(/{{PROJECT_ROOT}}/g, snowFlowRoot)
+        .replace(/{{SNOW_INSTANCE}}/g, '${SNOW_INSTANCE}')
+        .replace(/{{SNOW_CLIENT_ID}}/g, '${SNOW_CLIENT_ID}')
+        .replace(/{{SNOW_CLIENT_SECRET}}/g, '${SNOW_CLIENT_SECRET}')
+        .replace(/{{SNOW_DEPLOYMENT_TIMEOUT}}/g, '${SNOW_DEPLOYMENT_TIMEOUT}')
+        .replace(/{{MCP_DEPLOYMENT_TIMEOUT}}/g, '${MCP_DEPLOYMENT_TIMEOUT}')
+        .replace(/{{NEO4J_URI}}/g, '${NEO4J_URI}')
+        .replace(/{{NEO4J_USER}}/g, '${NEO4J_USER}')
+        .replace(/{{NEO4J_PASSWORD}}/g, '${NEO4J_PASSWORD}')
+        .replace(/{{SNOW_FLOW_ENV}}/g, '${SNOW_FLOW_ENV}');
+    // Parse to ensure it's valid JSON
+    const mcpConfig = JSON.parse(mcpConfigContent);
+    // Keep the standard MCP structure that Claude Code expects
+    const finalConfig = {
+        "mcpServers": mcpConfig.servers
+    };
+    // Create .mcp.json in project root for Claude Code discovery
+    const mcpConfigPath = (0, path_1.join)(targetDir, '.mcp.json');
+    try {
+        await fs_1.promises.access(mcpConfigPath);
+        if (force) {
+            console.log('⚠️  .mcp.json already exists, overwriting with --force flag');
+            await fs_1.promises.writeFile(mcpConfigPath, JSON.stringify(finalConfig, null, 2));
+        }
+        else {
+            console.log('⚠️  .mcp.json already exists, skipping (use --force to overwrite)');
+        }
+    }
+    catch {
+        await fs_1.promises.writeFile(mcpConfigPath, JSON.stringify(finalConfig, null, 2));
+    }
+    // Also create legacy config in .claude for backward compatibility
+    const legacyConfigPath = (0, path_1.join)(targetDir, '.claude/mcp-config.json');
+    await fs_1.promises.writeFile(legacyConfigPath, JSON.stringify(finalConfig, null, 2));
+}
+// Refresh MCP configuration command
+program
+    .command('refresh-mcp')
+    .description('Refresh MCP server configuration to latest version')
+    .option('--force', 'Force overwrite existing configuration')
+    .action(async (options) => {
+    console.log(chalk_1.default.blue.bold(`\n🔄 Refreshing MCP Configuration to v${version_js_1.VERSION}...`));
+    console.log('='.repeat(60));
+    try {
+        // Check if project is initialized
+        const envPath = (0, path_1.join)(process.cwd(), '.env');
+        if (!(0, fs_2.existsSync)(envPath)) {
+            console.error(chalk_1.default.red('\n❌ No .env file found. Please run "snow-flow init" first.'));
+            process.exit(1);
+        }
+        // Load env vars
+        dotenv_1.default.config({ path: envPath });
+        const instanceUrl = process.env.SNOW_INSTANCE;
+        const clientId = process.env.SNOW_CLIENT_ID;
+        const clientSecret = process.env.SNOW_CLIENT_SECRET;
+        if (!instanceUrl || !clientId || !clientSecret) {
+            console.error(chalk_1.default.red('\n❌ Missing ServiceNow credentials in .env file.'));
+            process.exit(1);
+        }
+        console.log('\n📝 Updating MCP configuration...');
+        await setupMCPConfig(process.cwd(), instanceUrl, clientId, clientSecret, options.force || false);
+        console.log(chalk_1.default.green('\n✅ MCP configuration refreshed successfully!'));
+        console.log('\n📢 IMPORTANT: Restart Claude Code to use the new configuration:');
+        console.log(chalk_1.default.cyan('   claude --mcp-config .mcp.json'));
+        console.log('\n💡 The Local Development server now includes:');
+        console.log('   • Universal artifact detection via sys_metadata');
+        console.log('   • Support for ANY ServiceNow table (even custom)');
+        console.log('   • Generic artifact handling for unknown types');
+        console.log('   • Automatic file structure creation');
+    }
+    catch (error) {
+        console.error(chalk_1.default.red('\n❌ Failed to refresh MCP configuration:'), error);
+        process.exit(1);
+    }
+});
 // Direct widget creation command
 program
     .command('create-widget [type]')

package/dist/utils/artifact-local-sync.d.ts

@@ -21,6 +21,7 @@ export interface LocalArtifact {
     createdAt: Date;
     lastSyncedAt: Date;
     artifactConfig?: ArtifactTypeConfig;
+    isGeneric?: boolean;
 }
 export interface LocalFile {
     filename: string;
@@ -55,6 +56,11 @@ export declare class ArtifactLocalSync {
      * DYNAMIC push local changes back to ServiceNow using artifact registry
      */
     pushArtifact(sys_id: string): Promise<boolean>;
+    /**
+     * Push generic artifact changes back to ServiceNow
+     * Only updates known script fields to avoid data corruption
+     */
+    pushGenericArtifact(artifact: LocalArtifact): Promise<boolean>;
     /**
      * Push local changes back to ServiceNow
      * (Wrapper for backward compatibility)
@@ -109,9 +115,14 @@ export declare class ArtifactLocalSync {
     getSyncStatus(sys_id: string): string;
     /**
      * Pull any supported artifact type by detecting table from sys_id
-     * ENHANCED: Better error logging and more robust detection
+     * ENHANCED: Now uses sys_metadata to find ANY table, not just registered ones!
      */
     pullArtifactBySysId(sys_id: string): Promise<LocalArtifact>;
+    /**
+     * Pull a generic artifact from an unknown/custom table
+     * Creates a basic file structure for any ServiceNow record
+     */
+    pullGenericArtifact(tableName: string, sys_id: string): Promise<LocalArtifact>;
     /**
      * Get supported artifact types
      */

package/dist/utils/artifact-local-sync.js

@@ -254,6 +254,10 @@ class ArtifactLocalSync {
         if (!artifact) {
             throw new Error(`No local artifact found for ${sys_id}. Run pullArtifact first.`);
         }
+        // Handle generic artifacts differently
+        if (artifact.isGeneric) {
+            return this.pushGenericArtifact(artifact);
+        }
         const config = artifact.artifactConfig;
         if (!config) {
             throw new Error(`No configuration found for artifact ${sys_id}`);
@@ -354,6 +358,56 @@ class ArtifactLocalSync {
             return false;
         }
     }
+    /**
+     * Push generic artifact changes back to ServiceNow
+     * Only updates known script fields to avoid data corruption
+     */
+    async pushGenericArtifact(artifact) {
+        console.log(`\n🔄 Pushing generic artifact changes to ${artifact.tableName}...`);
+        const updates = {};
+        let hasChanges = false;
+        // Only update known script fields for safety
+        const scriptFields = ['script', 'condition', 'script_plain', 'advanced',
+            'client_script', 'server_script', 'template', 'body'];
+        for (const file of artifact.files) {
+            if (file.field && scriptFields.includes(file.field)) {
+                if (fs.existsSync(file.path)) {
+                    const currentContent = fs.readFileSync(file.path, 'utf8');
+                    if (currentContent !== file.originalContent) {
+                        hasChanges = true;
+                        updates[file.field] = currentContent;
+                        console.log(`   📝 Changed: ${file.filename} (${file.field})`);
+                    }
+                }
+            }
+        }
+        if (!hasChanges) {
+            console.log(`✅ No changes detected. Generic artifact is up to date.`);
+            return true;
+        }
+        try {
+            console.log(`\n📤 Updating generic artifact in ServiceNow...`);
+            const timeoutConfig = (0, mcp_timeout_config_js_1.getMCPTimeoutConfig)();
+            const updateResult = await (0, mcp_timeout_config_js_1.withMCPTimeout)(this.client.updateRecord(artifact.tableName, artifact.sys_id, updates), timeoutConfig.pushToolTimeout, `Update generic artifact ${artifact.sys_id}`);
+            if (!updateResult || !updateResult.success) {
+                const errorMsg = updateResult?.error || 'Unknown API error';
+                console.error(`❌ ServiceNow API returned failure: ${errorMsg}`);
+                artifact.syncStatus = 'pending_upload';
+                return false;
+            }
+            artifact.syncStatus = 'synced';
+            artifact.lastSyncedAt = new Date();
+            console.log(`✅ Generic artifact successfully updated in ServiceNow!`);
+            console.log(`🔗 Table: ${artifact.tableName}`);
+            console.log(`🔗 sys_id: ${artifact.sys_id}`);
+            return true;
+        }
+        catch (error) {
+            console.error(`❌ Failed to update generic artifact:`, error);
+            artifact.syncStatus = 'pending_upload';
+            return false;
+        }
+    }
     /**
      * Push local changes back to ServiceNow
      * (Wrapper for backward compatibility)
@@ -703,20 +757,43 @@ snow-flow sync status ${widget.sys_id}
     }
     /**
      * Pull any supported artifact type by detecting table from sys_id
-     * ENHANCED: Better error logging and more robust detection
+     * ENHANCED: Now uses sys_metadata to find ANY table, not just registered ones!
      */
     async pullArtifactBySysId(sys_id) {
         console.log(`\n🔍 Auto-detecting artifact type for sys_id: ${sys_id}`);
-        console.log(`📋 Checking ${Object.keys(artifact_registry_1.ARTIFACT_REGISTRY).length} supported tables...`);
         // CRITICAL: Add MAXIMUM operation timeout to prevent infinite hanging
         const MAX_OPERATION_TIME = 30000; // 30 seconds max for entire operation
         const operationStart = Date.now();
-        // SMART ORDER: Check most common tables first for better performance
+        const timeoutConfig = (0, mcp_timeout_config_js_1.getMCPTimeoutConfig)();
+        // STEP 1: Try to find the table name using sys_metadata (works for ANY table!)
+        console.log(`🔮 Querying sys_metadata to find table name...`);
+        try {
+            const metadataResponse = await (0, mcp_timeout_config_js_1.withMCPTimeout)(this.client.searchRecords('sys_metadata', `sys_id=${sys_id}`, 1), 5000, `Query sys_metadata for ${sys_id}`);
+            if (metadataResponse.result?.[0]?.sys_class_name) {
+                const tableName = metadataResponse.result[0].sys_class_name;
+                console.log(`   ✅ Found in sys_metadata! Table: ${tableName}`);
+                // Check if this table is in our registry
+                if (artifact_registry_1.ARTIFACT_REGISTRY[tableName]) {
+                    console.log(`   ✅ Table is supported! Proceeding with pull...`);
+                    return this.pullArtifact(tableName, sys_id);
+                }
+                else {
+                    console.log(`   ⚠️ Table '${tableName}' is not in artifact registry`);
+                    console.log(`   🔧 Attempting generic pull for custom table...`);
+                    return this.pullGenericArtifact(tableName, sys_id);
+                }
+            }
+        }
+        catch (error) {
+            console.log(`   ⚠️ sys_metadata query failed: ${error instanceof Error ? error.message : error}`);
+            console.log(`   📋 Falling back to registered table search...`);
+        }
+        // STEP 2: If sys_metadata fails, try common tables first
+        console.log(`\n📋 Checking ${Object.keys(artifact_registry_1.ARTIFACT_REGISTRY).length} registered tables...`);
         const allTables = Object.keys(artifact_registry_1.ARTIFACT_REGISTRY);
         const commonTables = ['sp_widget', 'sys_script_include', 'sys_script', 'sys_ui_page'];
         const otherTables = allTables.filter(t => !commonTables.includes(t));
         const tables = [...commonTables, ...otherTables]; // Common tables first
-        const timeoutConfig = (0, mcp_timeout_config_js_1.getMCPTimeoutConfig)();
         const errors = [];
         for (const table of tables) {
             // Check if we've exceeded maximum operation time
@@ -727,7 +804,7 @@ snow-flow sync status ${widget.sys_id}
             try {
                 console.log(`   🔎 Checking table: ${table}...`);
                 // Reduced timeout per table for faster failure
-                const response = await (0, mcp_timeout_config_js_1.withMCPTimeout)(this.client.searchRecords(table, `sys_id=${sys_id}`, 1), 3000, // 3 second timeout per table (reduced from 8s)
+                const response = await (0, mcp_timeout_config_js_1.withMCPTimeout)(this.client.searchRecords(table, `sys_id=${sys_id}`, 1), 3000, // 3 second timeout per table
                 `Detect table for ${sys_id}`);
                 if (response.result?.[0]) {
                     console.log(`   ✅ Found in table: ${table}`);
@@ -742,12 +819,29 @@ snow-flow sync status ${widget.sys_id}
                 const errorMsg = error instanceof Error ? error.message : String(error);
                 console.log(`   ⚠️ Error checking ${table}: ${errorMsg}`);
                 errors.push({ table, error: errorMsg });
-                // Don't fail on permission errors, timeouts, etc. - keep trying other tables
+            }
+        }
+        // STEP 3: Try a few common custom tables as last resort
+        const customTables = ['sys_ui_script', 'sys_processor', 'sys_ws_operation', 'sys_portal_page'];
+        console.log(`\n🔍 Checking additional custom tables...`);
+        for (const table of customTables) {
+            if (Date.now() - operationStart > MAX_OPERATION_TIME)
+                break;
+            try {
+                console.log(`   🔎 Checking custom table: ${table}...`);
+                const response = await (0, mcp_timeout_config_js_1.withMCPTimeout)(this.client.searchRecords(table, `sys_id=${sys_id}`, 1), 3000, `Check custom table ${table}`);
+                if (response.result?.[0]) {
+                    console.log(`   ✅ Found in custom table: ${table}`);
+                    return this.pullGenericArtifact(table, sys_id);
+                }
+            }
+            catch (error) {
+                // Silent fail for custom tables
             }
         }
         // Generate detailed error message
         console.log(`\n❌ Artifact detection failed!`);
-        console.log(`🔍 Searched ${tables.length} tables for sys_id: ${sys_id}`);
+        console.log(`🔍 Searched sys_metadata + ${tables.length} registered tables + ${customTables.length} custom tables`);
         if (errors.length > 0) {
             console.log(`\n⚠️ Errors encountered:`);
             errors.forEach(({ table, error }) => {
@@ -757,9 +851,92 @@ snow-flow sync status ${widget.sys_id}
         console.log(`\n💡 Troubleshooting tips:`);
         console.log(`   1. Verify the sys_id exists in ServiceNow`);
         console.log(`   2. Check your permissions for the target table`);
-        console.log(`   3. Try specifying the table explicitly: snow_pull_artifact({sys_id, table: 'sp_widget'})`);
-        console.log(`   4. Supported tables: ${tables.join(', ')}`);
-        throw new Error(`Could not find artifact with sys_id ${sys_id} in any supported table. See details above.`);
+        console.log(`   3. Try specifying the table explicitly: snow_pull_artifact({sys_id, table: 'table_name'})`);
+        console.log(`   4. The artifact might be in a custom or scoped application table`);
+        throw new Error(`Could not find artifact with sys_id ${sys_id}. It may be in a custom table or you may lack permissions.`);
+    }
+    /**
+     * Pull a generic artifact from an unknown/custom table
+     * Creates a basic file structure for any ServiceNow record
+     */
+    async pullGenericArtifact(tableName, sys_id) {
+        console.log(`\n🔧 Pulling generic artifact from custom table: ${tableName}`);
+        try {
+            // Fetch the record with all fields
+            const response = await (0, mcp_timeout_config_js_1.withMCPTimeout)(this.client.searchRecords(tableName, `sys_id=${sys_id}`, 1), 10000, `Fetch generic artifact from ${tableName}`);
+            const record = response.result?.[0];
+            if (!record) {
+                throw new Error(`Record not found in ${tableName}`);
+            }
+            // Create a generic folder structure
+            const name = record.name || record.short_description || record.sys_name || sys_id;
+            const sanitizedName = this.sanitizeFilename(name);
+            const artifactPath = path.join(this.baseDir, 'custom', tableName, sanitizedName);
+            // Clean up existing files
+            if (fs.existsSync(artifactPath)) {
+                fs.rmSync(artifactPath, { recursive: true });
+            }
+            fs.mkdirSync(artifactPath, { recursive: true });
+            const files = [];
+            // Create JSON file with all fields
+            const jsonFile = this.createLocalFile(artifactPath, `${sanitizedName}.json`, JSON.stringify(record, null, 2), 'all_fields', 'json');
+            files.push(jsonFile);
+            // Extract common script fields if they exist
+            const scriptFields = ['script', 'condition', 'script_plain', 'advanced',
+                'client_script', 'server_script', 'template', 'body'];
+            for (const field of scriptFields) {
+                if (record[field] && typeof record[field] === 'string' && record[field].trim()) {
+                    const ext = field.includes('template') || field === 'body' ? 'html' : 'js';
+                    const scriptFile = this.createLocalFile(artifactPath, `${sanitizedName}.${field}.${ext}`, record[field], field, ext);
+                    files.push(scriptFile);
+                }
+            }
+            // Create README
+            const readmeContent = `# Generic Artifact: ${name}\n\n` +
+                `**Table:** ${tableName}\n` +
+                `**Sys ID:** ${sys_id}\n` +
+                `**Created:** ${record.sys_created_on || 'Unknown'}\n` +
+                `**Updated:** ${record.sys_updated_on || 'Unknown'}\n\n` +
+                `## Notice\n\n` +
+                `This is a generic artifact from a custom/unknown table.\n` +
+                `Snow-Flow has created a basic file structure to allow editing.\n\n` +
+                `## Files\n\n` +
+                `- **${sanitizedName}.json** - Complete record data\n` +
+                (files.length > 1 ? files.slice(1).map(f => `- **${f.filename}** - ${f.field} field content\n`).join('') : '') +
+                `\n## Push Support\n\n` +
+                `Generic artifacts have limited push support. ` +
+                `Only script fields will be updated when pushing back.\n`;
+            const readmeFile = this.createLocalFile(artifactPath, 'README.md', readmeContent, 'documentation', 'md');
+            files.push(readmeFile);
+            // Create artifact record
+            const artifact = {
+                sys_id: sys_id,
+                name: name,
+                type: `Custom (${tableName})`,
+                tableName: tableName,
+                localPath: artifactPath,
+                files: files,
+                metadata: record,
+                syncStatus: 'synced',
+                createdAt: new Date(),
+                lastSyncedAt: new Date(),
+                isGeneric: true // Mark as generic for special handling
+            };
+            this.artifacts.set(sys_id, artifact);
+            const relativePath = path.relative(process.cwd(), artifactPath);
+            const displayPath = relativePath.startsWith('..') ? artifactPath : relativePath;
+            console.log(`✅ Generic artifact pulled successfully!`);
+            console.log(`📁 Location: ${displayPath}`);
+            console.log(`📄 Files created:`);
+            files.forEach(f => console.log(`   - ${f.filename} (${f.type})`));
+            console.log(`\n⚠️ Note: This is a generic pull from a custom table.`);
+            console.log(`   Full push support may be limited.`);
+            return artifact;
+        }
+        catch (error) {
+            console.error(`❌ Failed to pull generic artifact:`, error);
+            throw error;
+        }
     }
     /**
      * Get supported artifact types

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "snow-flow",
-  "version": "3.6.4",
-  "description": "EARLY AUTO-COMPACT at 65% context usage prevents mid-API failures. v3.6.4 triggers compact BEFORE context window issues, not after. Aggressive compact mode with MCP state preservation. Prevents 'too many tokens' errors during ServiceNow operations. Includes infinite hanging fix, consolidated CLAUDE.md with 18 MCP servers, NO MOCK DATA policy, audit logging, and ES5 enforcement.",
+  "version": "3.6.6",
+  "description": "MCP TEMPLATE FIX - v3.6.6 ensures snow-flow init generates correct .mcp.json with UNIVERSAL ARTIFACT DETECTION. Uses sys_metadata to find ANY ServiceNow record by sys_id alone. Generic artifact support for custom/unknown tables. Auto-creates editable file structure for ANY table type. Includes early auto-compact, audit logging, and consolidated CLAUDE.md.",
   "main": "dist/index.js",
   "type": "commonjs",
   "bin": {