mcp-maestro-mobile-ai 1.3.1 → 1.6.0

package/src/mcp-server/utils/yamlGenerator.js

@@ -0,0 +1,426 @@
+/**
+ * YAML Generator with Warnings Support
+ * 
+ * Generates Maestro YAML from analyzed prompts.
+ * Supports:
+ * - Clean YAML for complete prompts
+ * - YAML with warnings for force-generated (incomplete) prompts
+ * - Automatic application of interaction patterns
+ */
+
+import { CompletenessLevel, getDefaultAssumptions } from './promptAnalyzer.js';
+import { getInteractionPatternHints, getYamlGenerationRules } from './knownIssues.js';
+
+/**
+ * Generate YAML from analysis result
+ * 
+ * @param {object} analysis - Result from analyzePrompt()
+ * @param {object} options - Generation options
+ * @returns {object} { yaml, warnings, assumptions, success }
+ */
+export function generateYamlFromAnalysis(analysis, options = {}) {
+  const { extracted, assessment } = analysis;
+  const { forceGenerate = false, includeComments = true } = options;
+  
+  // Check if generation is possible
+  if (assessment.level === CompletenessLevel.INSUFFICIENT && !forceGenerate) {
+    return {
+      success: false,
+      yaml: null,
+      error: 'Cannot generate YAML: missing required information (app ID)',
+      missing: assessment.missing,
+    };
+  }
+  
+  if (assessment.level === CompletenessLevel.NEEDS_CLARIFICATION && !forceGenerate) {
+    return {
+      success: false,
+      yaml: null,
+      needsClarification: true,
+      level: assessment.level,
+    };
+  }
+  
+  // Get defaults for assumptions
+  const defaults = getDefaultAssumptions(analysis);
+  const warnings = [];
+  const assumptions = [];
+  
+  // Build YAML
+  const yamlParts = [];
+  
+  // App ID header
+  const appId = extracted.appContext.appId || options.appId;
+  if (!appId) {
+    return {
+      success: false,
+      yaml: null,
+      error: 'App ID is required',
+    };
+  }
+  
+  yamlParts.push(`appId: ${appId}`);
+  yamlParts.push('---');
+  
+  // Add warning header if force generating
+  if (forceGenerate && assessment.level !== CompletenessLevel.COMPLETE) {
+    const warningHeader = generateWarningHeader(assessment, defaults);
+    yamlParts.push(warningHeader);
+    warnings.push(...assessment.assumptions);
+  }
+  
+  // Standard start
+  yamlParts.push('- clearState');
+  yamlParts.push('- launchApp');
+  yamlParts.push('');
+  
+  // Wait for initial screen
+  if (includeComments) {
+    yamlParts.push('# Wait for app to fully load');
+  }
+  yamlParts.push('- waitForAnimationToEnd');
+  yamlParts.push('');
+  
+  // Generate steps based on detected pattern
+  const steps = generateStepsFromSequence(analysis, defaults, options);
+  yamlParts.push(...steps.yaml);
+  warnings.push(...steps.warnings);
+  assumptions.push(...steps.assumptions);
+  
+  // Add verification if detected or assumed
+  const verification = generateVerification(analysis, defaults, options);
+  if (verification.yaml.length > 0) {
+    yamlParts.push('');
+    yamlParts.push(...verification.yaml);
+    if (verification.assumed) {
+      assumptions.push('Verification element assumed based on common patterns');
+    }
+  }
+  
+  return {
+    success: true,
+    yaml: yamlParts.join('\n'),
+    warnings,
+    assumptions,
+    forceGenerated: forceGenerate && assessment.level !== CompletenessLevel.COMPLETE,
+    completenessScore: assessment.score,
+  };
+}
+
+/**
+ * Generate warning header for force-generated YAML
+ */
+function generateWarningHeader(assessment, defaults) {
+  const lines = [
+    '# ⚠️ GENERATED WITH ASSUMPTIONS',
+    '# The following values were assumed - verify they match your app:',
+  ];
+  
+  for (const assumption of assessment.assumptions) {
+    lines.push(`#   - ${assumption}`);
+  }
+  
+  if (defaults.alternatives) {
+    lines.push('#');
+    lines.push('# Alternative selectors to try if defaults fail:');
+    for (const [field, alts] of Object.entries(defaults.alternatives)) {
+      lines.push(`#   ${field}: ${alts.join(' / ')}`);
+    }
+  }
+  
+  lines.push('#');
+  lines.push('');
+  
+  return lines.join('\n');
+}
+
+/**
+ * Generate steps from analyzed sequence
+ */
+function generateStepsFromSequence(analysis, defaults, options) {
+  const { extracted } = analysis;
+  const yaml = [];
+  const warnings = [];
+  const assumptions = [];
+  
+  const includeComments = options.includeComments !== false;
+  
+  // Track if we've had text input (need to hide keyboard before buttons)
+  let hadTextInput = false;
+  
+  for (const step of extracted.sequence) {
+    switch (step.action) {
+      case 'INPUT': {
+        const fieldLabel = step.element || defaults.usernameField || '{field_name}';
+        const value = step.value || extracted.values[step.elementType?.toLowerCase()] || '{value}';
+        
+        if (includeComments) {
+          yaml.push(`# Enter ${step.elementType || 'text'}`);
+        }
+        yaml.push(`- tapOn: "${fieldLabel}"`);
+        yaml.push(`- inputText: "${value}"`);
+        yaml.push('');
+        
+        hadTextInput = true;
+        
+        if (!step.element) {
+          assumptions.push(`Field label assumed: "${fieldLabel}"`);
+        }
+        if (!step.value) {
+          warnings.push(`Value placeholder used for: ${fieldLabel}`);
+        }
+        break;
+      }
+      
+      case 'TAP':
+      case 'SUBMIT': {
+        // Hide keyboard before tapping if we had text input
+        if (hadTextInput) {
+          if (includeComments) {
+            yaml.push('# Hide keyboard before tapping button');
+          }
+          yaml.push('- hideKeyboard');
+          yaml.push('- waitForAnimationToEnd');
+          yaml.push('');
+        }
+        
+        const buttonLabel = step.element || defaults.submitButton || '{button_text}';
+        
+        if (includeComments) {
+          yaml.push(`# Tap ${step.action === 'SUBMIT' ? 'submit button' : 'element'}`);
+        }
+        yaml.push(`- tapOn: "${buttonLabel}"`);
+        yaml.push('');
+        
+        if (!step.element) {
+          assumptions.push(`Button text assumed: "${buttonLabel}"`);
+        }
+        break;
+      }
+      
+      case 'SELECT': {
+        // Hide keyboard before dropdown
+        if (hadTextInput) {
+          yaml.push('- hideKeyboard');
+          yaml.push('- waitForAnimationToEnd');
+          yaml.push('');
+        }
+        
+        const dropdownTrigger = step.element || '{dropdown_trigger}';
+        const optionValue = step.value || '{option_to_select}';
+        
+        if (includeComments) {
+          yaml.push('# Dropdown interaction');
+        }
+        yaml.push(`- tapOn: "${dropdownTrigger}"`);
+        yaml.push('- waitForAnimationToEnd');
+        yaml.push(`- tapOn: "${optionValue}"`);
+        yaml.push('- waitForAnimationToEnd');
+        yaml.push('');
+        
+        if (!step.element) {
+          assumptions.push(`Dropdown trigger assumed: "${dropdownTrigger}"`);
+        }
+        if (!step.value) {
+          warnings.push(`Dropdown option placeholder used`);
+        }
+        break;
+      }
+      
+      case 'SCROLL': {
+        if (includeComments) {
+          yaml.push('# Scroll to find element');
+        }
+        yaml.push('- scroll');
+        yaml.push('- waitForAnimationToEnd');
+        yaml.push('');
+        break;
+      }
+      
+      case 'SEARCH': {
+        const searchField = step.element || defaults.searchField || 'Search';
+        const searchValue = step.value || extracted.values.search || '{search_term}';
+        
+        if (includeComments) {
+          yaml.push('# Search');
+        }
+        yaml.push(`- tapOn: "${searchField}"`);
+        yaml.push(`- inputText: "${searchValue}"`);
+        yaml.push('- pressKey: enter');
+        yaml.push('- waitForAnimationToEnd');
+        yaml.push('');
+        
+        hadTextInput = true;
+        break;
+      }
+      
+      case 'NAVIGATE': {
+        if (step.element) {
+          if (includeComments) {
+            yaml.push(`# Navigate to ${step.element}`);
+          }
+          yaml.push(`- tapOn: "${step.element}"`);
+          yaml.push('- waitForAnimationToEnd');
+          yaml.push('');
+        }
+        break;
+      }
+      
+      case 'VERIFY': {
+        // Verifications are handled separately
+        break;
+      }
+      
+      default: {
+        if (step.element) {
+          yaml.push(`- tapOn: "${step.element}"`);
+          yaml.push('');
+        }
+      }
+    }
+  }
+  
+  // If no explicit steps but we have values, generate login-like pattern
+  if (yaml.length === 0 && Object.keys(extracted.values).length > 0) {
+    const { values } = extracted;
+    
+    if (values.username || values.email || values.user) {
+      yaml.push(`- tapOn: "${defaults.usernameField || 'Username'}"`);
+      yaml.push(`- inputText: "${values.username || values.email || values.user}"`);
+      yaml.push('');
+      assumptions.push('Assumed login pattern from username/password values');
+    }
+    
+    if (values.password || values.pass) {
+      yaml.push(`- tapOn: "${defaults.passwordField || 'Password'}"`);
+      yaml.push(`- inputText: "${values.password || values.pass}"`);
+      yaml.push('');
+    }
+    
+    // Add submit
+    yaml.push('- hideKeyboard');
+    yaml.push('- waitForAnimationToEnd');
+    yaml.push('');
+    yaml.push(`- tapOn: "${defaults.submitButton || 'Sign In'}"`);
+    yaml.push('');
+  }
+  
+  return { yaml, warnings, assumptions };
+}
+
+/**
+ * Generate verification steps
+ */
+function generateVerification(analysis, defaults, options) {
+  const { extracted } = analysis;
+  const yaml = [];
+  let assumed = false;
+  
+  const includeComments = options.includeComments !== false;
+  
+  if (extracted.verifications.length > 0) {
+    if (includeComments) {
+      yaml.push('# Verify expected result');
+    }
+    
+    // Wait for navigation/loading
+    yaml.push('- extendedWaitUntil:');
+    
+    for (const verification of extracted.verifications) {
+      if (verification.target) {
+        yaml.push(`    visible: "${verification.target}"`);
+        yaml.push('    timeout: 30000');
+        yaml.push('');
+        yaml.push(`- assertVisible: "${verification.target}"`);
+        break; // Just use first verification for extendedWaitUntil
+      }
+    }
+    
+    // Add remaining verifications as assertions
+    for (let i = 1; i < extracted.verifications.length; i++) {
+      const v = extracted.verifications[i];
+      if (v.target) {
+        yaml.push(`- assertVisible: "${v.target}"`);
+      }
+    }
+  } else {
+    // No explicit verification - add warning comment
+    if (includeComments) {
+      yaml.push('# ⚠️ WARNING: No success verification specified');
+      yaml.push('# Add: - assertVisible: "{your_success_element}"');
+    }
+    yaml.push('- waitForAnimationToEnd');
+    assumed = true;
+  }
+  
+  return { yaml, assumed };
+}
+
+/**
+ * Generate YAML structure with applied interaction patterns
+ * This ensures best practices are followed
+ */
+export function applyInteractionPatterns(yaml) {
+  const rules = getYamlGenerationRules();
+  let modifiedYaml = yaml;
+  const appliedPatterns = [];
+  
+  // Pattern: tapOn before inputText
+  if (rules.mandatory.tapBeforeInput) {
+    // Check for inputText without preceding tapOn
+    const lines = modifiedYaml.split('\n');
+    const fixedLines = [];
+    
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const prevLine = i > 0 ? lines[i - 1] : '';
+      
+      if (line.trim().startsWith('- inputText:') && !prevLine.trim().startsWith('- tapOn:')) {
+        // This is a pattern violation - add warning comment
+        fixedLines.push('# ⚠️ PATTERN: tapOn should precede inputText');
+        appliedPatterns.push('Added tapOn reminder before inputText');
+      }
+      fixedLines.push(line);
+    }
+    
+    modifiedYaml = fixedLines.join('\n');
+  }
+  
+  return {
+    yaml: modifiedYaml,
+    appliedPatterns,
+  };
+}
+
+/**
+ * Format a complete YAML generation response
+ */
+export function formatGenerationResponse(result) {
+  if (!result.success) {
+    return {
+      success: false,
+      error: result.error,
+      needsClarification: result.needsClarification || false,
+      missing: result.missing || [],
+    };
+  }
+  
+  return {
+    success: true,
+    yaml: result.yaml,
+    forceGenerated: result.forceGenerated || false,
+    completenessScore: result.completenessScore,
+    warnings: result.warnings || [],
+    assumptions: result.assumptions || [],
+    message: result.forceGenerated
+      ? 'YAML generated with assumptions. Review warnings and update placeholders.'
+      : 'YAML generated successfully.',
+  };
+}
+
+export default {
+  generateYamlFromAnalysis,
+  applyInteractionPatterns,
+  formatGenerationResponse,
+};
+