@deriv-com/fe-mcp-servers 0.0.12 → 0.0.13

package/dist/maestro-ai/mcp-server.js

@@ -19748,6 +19748,893 @@ function runAllTests(options = {}) {
     execution
   };
 }
+function extractTaskIdFromUrl(url2) {
+  if (!url2 || typeof url2 !== "string") {
+    return {
+      success: false,
+      taskId: null,
+      message: "No URL provided"
+    };
+  }
+  const trimmedUrl = url2.trim();
+  const directPattern = /app\.clickup\.com\/t\/([a-zA-Z0-9]+)/;
+  const directMatch = trimmedUrl.match(directPattern);
+  if (directMatch) {
+    return {
+      success: true,
+      taskId: directMatch[1],
+      message: `Extracted task ID: ${directMatch[1]}`
+    };
+  }
+  const queryPattern = /[?&]p=([a-zA-Z0-9]+)/;
+  const queryMatch = trimmedUrl.match(queryPattern);
+  if (queryMatch) {
+    return {
+      success: true,
+      taskId: queryMatch[1],
+      message: `Extracted task ID from query: ${queryMatch[1]}`
+    };
+  }
+  const listViewPattern = /\/li\/\d+\/([a-zA-Z0-9]+)/;
+  const listViewMatch = trimmedUrl.match(listViewPattern);
+  if (listViewMatch) {
+    return {
+      success: true,
+      taskId: listViewMatch[1],
+      message: `Extracted task ID from list view: ${listViewMatch[1]}`
+    };
+  }
+  const taskIdPattern = /^[a-zA-Z0-9]{6,12}$/;
+  if (taskIdPattern.test(trimmedUrl)) {
+    return {
+      success: true,
+      taskId: trimmedUrl,
+      message: `Using provided value as task ID: ${trimmedUrl}`
+    };
+  }
+  return {
+    success: false,
+    taskId: null,
+    message: `Could not extract task ID from URL: ${trimmedUrl}`
+  };
+}
+async function fetchClickUpTask(options = {}) {
+  const { taskUrl = null } = options;
+  const apiToken = process.env.CLICKUP_API_TOKEN;
+  if (!taskUrl) {
+    return {
+      success: false,
+      skipped: false,
+      needsInput: true,
+      prompt: "Do you have a ClickUp task URL for this feature? Paste the URL to generate tests based on acceptance criteria, or type 'skip' to continue with git-based analysis only.",
+      message: "No ClickUp task URL provided. Provide a URL or skip to continue."
+    };
+  }
+  const skipCommands = ["skip", "no", "none", "n", ""];
+  if (skipCommands.includes(taskUrl.toLowerCase().trim())) {
+    return {
+      success: true,
+      skipped: true,
+      needsInput: false,
+      message: "Skipping ClickUp integration. Continuing with git-based analysis.",
+      task: null
+    };
+  }
+  const extraction = extractTaskIdFromUrl(taskUrl);
+  if (!extraction.success) {
+    return {
+      success: false,
+      skipped: false,
+      needsInput: false,
+      message: extraction.message,
+      error: "Invalid ClickUp URL format"
+    };
+  }
+  const taskId = extraction.taskId;
+  if (!apiToken) {
+    return {
+      success: false,
+      skipped: false,
+      needsInput: false,
+      message: "\u274C CLICKUP_API_TOKEN environment variable is not set. Please configure it in your MCP settings.",
+      error: "Missing API token",
+      taskId
+    };
+  }
+  try {
+    const response = await fetch(
+      `https://api.clickup.com/api/v2/task/${taskId}`,
+      {
+        method: "GET",
+        headers: {
+          Authorization: apiToken,
+          "Content-Type": "application/json"
+        }
+      }
+    );
+    if (!response.ok) {
+      const errorText = await response.text();
+      return {
+        success: false,
+        skipped: false,
+        needsInput: false,
+        message: `\u274C ClickUp API error (${response.status}): ${errorText}`,
+        error: `API returned ${response.status}`,
+        taskId
+      };
+    }
+    const task = await response.json();
+    return {
+      success: true,
+      skipped: false,
+      needsInput: false,
+      message: `\u2705 Successfully fetched task: ${task.name}`,
+      task,
+      taskId,
+      taskName: task.name,
+      taskStatus: task.status?.status,
+      taskUrl: task.url
+    };
+  } catch (error2) {
+    return {
+      success: false,
+      skipped: false,
+      needsInput: false,
+      message: `\u274C Failed to fetch ClickUp task: ${error2.message}`,
+      error: error2.message,
+      taskId
+    };
+  }
+}
+function parseAcceptanceCriteria(options = {}) {
+  const { task, acSource = null } = options;
+  if (!task) {
+    return {
+      success: false,
+      acItems: [],
+      source: null,
+      message: "No task provided for parsing acceptance criteria"
+    };
+  }
+  const sourceConfig = acSource || process.env.CLICKUP_AC_SOURCE || "checklist:Acceptance Criteria";
+  const acItems = [];
+  const sources = sourceConfig.split(",").map((s) => s.trim());
+  const usedSources = [];
+  for (const source of sources) {
+    const [sourceType, sourceName] = source.includes(":") ? source.split(":", 2) : [source, null];
+    switch (sourceType.toLowerCase()) {
+      case "checklist": {
+        const checklists = task.checklists || [];
+        for (const checklist of checklists) {
+          if (!sourceName || checklist.name.toLowerCase().includes(sourceName.toLowerCase())) {
+            const items = checklist.items || [];
+            for (const item of items) {
+              acItems.push({
+                id: item.id,
+                text: item.name,
+                completed: item.resolved || false,
+                source: `checklist:${checklist.name}`,
+                type: "checklist_item",
+                order: item.orderindex
+              });
+            }
+            usedSources.push(`checklist:${checklist.name}`);
+          }
+        }
+        break;
+      }
+      case "custom_field": {
+        const customFields = task.custom_fields || [];
+        for (const field of customFields) {
+          if (!sourceName || field.name.toLowerCase().includes(sourceName.toLowerCase())) {
+            if (field.value) {
+              if (Array.isArray(field.value)) {
+                field.value.forEach((v, idx) => {
+                  acItems.push({
+                    id: `${field.id}_${idx}`,
+                    text: typeof v === "object" ? v.name || v.value : v,
+                    completed: false,
+                    source: `custom_field:${field.name}`,
+                    type: "custom_field_item",
+                    order: idx
+                  });
+                });
+              } else if (typeof field.value === "string") {
+                const lines = field.value.split("\n").filter((l) => l.trim());
+                lines.forEach((line, idx) => {
+                  const checkboxMatch = line.match(/^[\s]*[-*\[\]xX✓✗]\s*(.*)/);
+                  acItems.push({
+                    id: `${field.id}_${idx}`,
+                    text: checkboxMatch ? checkboxMatch[1].trim() : line.trim(),
+                    completed: /^[\s]*[\[x\]✓]/.test(line),
+                    source: `custom_field:${field.name}`,
+                    type: "custom_field_item",
+                    order: idx
+                  });
+                });
+              }
+              usedSources.push(`custom_field:${field.name}`);
+            }
+          }
+        }
+        break;
+      }
+      case "description": {
+        let description = task.description || task.text_content || task.content || "";
+        const rawDescription = description;
+        if (description) {
+          description = description.replace(/<br\s*\/?>/gi, "\n").replace(/<\/p>/gi, "\n").replace(/<\/div>/gi, "\n").replace(/<\/li>/gi, "\n").replace(/<[^>]*>/g, "").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"');
+          description = description.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+          const acSectionPattern = /(?:acceptance\s*criteria|ac|requirements?)[\s:]*\n([\s\S]*?)(?:\n\n|\n#|$)/i;
+          const sectionMatch = description.match(acSectionPattern);
+          const textToParse = sectionMatch ? sectionMatch[1] : description;
+          const lines = textToParse.split("\n").filter((l) => l.trim());
+          lines.forEach((line, idx) => {
+            const itemMatch = line.match(
+              /^[\s]*(?:[-–—*•◦▪▸►‣⁃]|\d+[.)\]:]|\[[\sx✓✗☐☑]?\])\s*(.*)/
+            );
+            if (itemMatch && itemMatch[1] && itemMatch[1].trim().length > 0) {
+              acItems.push({
+                id: `desc_${idx}`,
+                text: itemMatch[1].trim(),
+                completed: /\[[x✓☑]\]/i.test(line),
+                source: "description",
+                type: "description_item",
+                order: idx
+              });
+            }
+          });
+          if (!acItems.some((item) => item.source === "description")) {
+            const headerMatch = description.match(
+              /acceptance\s*criteria\s*:?\s*\n?([\s\S]*)/i
+            );
+            if (headerMatch) {
+              const afterHeader = headerMatch[1].trim();
+              const criteriaLines = afterHeader.split("\n").filter((l) => l.trim());
+              criteriaLines.forEach((line, idx) => {
+                const trimmedLine = line.trim();
+                if (trimmedLine.startsWith("-") || trimmedLine.startsWith("*") || trimmedLine.startsWith("\u2022")) {
+                  acItems.push({
+                    id: `desc_${idx}`,
+                    text: trimmedLine.replace(/^[-*•]\s*/, "").trim(),
+                    completed: false,
+                    source: "description",
+                    type: "description_item",
+                    order: idx
+                  });
+                } else if (trimmedLine.length > 10 && idx < 10) {
+                  acItems.push({
+                    id: `desc_fallback_${idx}`,
+                    text: trimmedLine,
+                    completed: false,
+                    source: "description",
+                    type: "description_item_fallback",
+                    order: idx
+                  });
+                }
+              });
+            }
+          }
+          if (acItems.some((item) => item.source === "description")) {
+            usedSources.push("description");
+          }
+        }
+        if (!acItems.some((item) => item.source === "description")) {
+          if (!task._debug) task._debug = {};
+          task._debug.rawDescription = rawDescription?.substring(0, 500);
+          task._debug.processedDescription = description?.substring(0, 500);
+          task._debug.descriptionLength = description?.length || 0;
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  const result = {
+    success: acItems.length > 0,
+    acItems,
+    sources: usedSources,
+    totalCount: acItems.length,
+    completedCount: acItems.filter((item) => item.completed).length,
+    message: acItems.length > 0 ? `\u2705 Found ${acItems.length} acceptance criteria items from: ${usedSources.join(", ")}` : `\u26A0\uFE0F No acceptance criteria found in sources: ${sourceConfig}`
+  };
+  if (acItems.length === 0 && task._debug) {
+    result.debug = {
+      rawDescriptionPreview: task._debug.rawDescription,
+      processedDescriptionPreview: task._debug.processedDescription,
+      descriptionLength: task._debug.descriptionLength,
+      hint: "Check if the description contains bullet points (-, *, \u2022) or is formatted differently"
+    };
+  }
+  if (acItems.length === 0) {
+    result.taskInfo = {
+      hasDescription: !!(task.description || task.text_content || task.content),
+      hasChecklists: !!(task.checklists && task.checklists.length > 0),
+      checklistNames: task.checklists?.map((c) => c.name) || [],
+      hasCustomFields: !!(task.custom_fields && task.custom_fields.length > 0),
+      customFieldNames: task.custom_fields?.map((f) => f.name) || []
+    };
+  }
+  return result;
+}
+function validateAcceptanceCriteria(options = {}) {
+  const { acItems = [] } = options;
+  if (!acItems || acItems.length === 0) {
+    return {
+      success: false,
+      validatedItems: [],
+      testableCount: 0,
+      message: "No acceptance criteria items provided for validation"
+    };
+  }
+  const validatedItems = acItems.map((item) => {
+    const validation = {
+      ...item,
+      isTestable: true,
+      testabilityScore: 0,
+      testabilityReasons: [],
+      suggestedFlowType: null,
+      uiKeywords: []
+    };
+    const text = item.text.toLowerCase();
+    const uiKeywords = {
+      button: ["click", "button", "tap", "press"],
+      form: ["input", "enter", "fill", "type", "form", "field"],
+      navigation: ["navigate", "go to", "open", "redirect", "page", "screen"],
+      visibility: ["see", "display", "show", "visible", "appear"],
+      modal: ["modal", "dialog", "popup", "overlay"],
+      validation: ["error", "valid", "invalid", "required", "message"]
+    };
+    for (const [category, keywords] of Object.entries(uiKeywords)) {
+      for (const keyword of keywords) {
+        if (text.includes(keyword)) {
+          validation.uiKeywords.push(keyword);
+          validation.testabilityScore += 10;
+          validation.testabilityReasons.push(
+            `Contains UI keyword: "${keyword}"`
+          );
+          if (!validation.suggestedFlowType) {
+            if (category === "form") validation.suggestedFlowType = "form";
+            else if (category === "navigation")
+              validation.suggestedFlowType = "navigation";
+            else if (category === "modal")
+              validation.suggestedFlowType = "modal";
+            else if (category === "button" || category === "visibility")
+              validation.suggestedFlowType = "navigation";
+          }
+        }
+      }
+    }
+    const authKeywords = [
+      "login",
+      "logout",
+      "sign in",
+      "sign out",
+      "password",
+      "authenticate"
+    ];
+    if (authKeywords.some((k) => text.includes(k))) {
+      validation.suggestedFlowType = "auth";
+      validation.testabilityScore += 15;
+      validation.testabilityReasons.push("Contains auth-related keyword");
+    }
+    const sidebarKeywords = ["sidebar", "menu", "panel", "drawer"];
+    if (sidebarKeywords.some((k) => text.includes(k))) {
+      validation.suggestedFlowType = "sidebar";
+      validation.testabilityScore += 10;
+      validation.testabilityReasons.push("Contains sidebar-related keyword");
+    }
+    const nonTestablePatterns = [
+      "backend",
+      "api",
+      "database",
+      "performance",
+      "security",
+      "code review",
+      "documentation"
+    ];
+    if (nonTestablePatterns.some((p) => text.includes(p))) {
+      validation.testabilityScore -= 20;
+      validation.testabilityReasons.push("Contains non-UI pattern");
+    }
+    validation.isTestable = validation.testabilityScore > 0;
+    return validation;
+  });
+  const testableItems = validatedItems.filter((item) => item.isTestable);
+  return {
+    success: testableItems.length > 0,
+    validatedItems,
+    testableCount: testableItems.length,
+    nonTestableCount: validatedItems.length - testableItems.length,
+    message: testableItems.length > 0 ? `\u2705 ${testableItems.length}/${validatedItems.length} items are testable via Maestro` : "\u26A0\uFE0F No testable acceptance criteria found",
+    suggestedFlowTypes: [
+      ...new Set(
+        testableItems.map((item) => item.suggestedFlowType).filter(Boolean)
+      )
+    ]
+  };
+}
+function extractUITextFromFiles(repoPath, files) {
+  const uiTexts = [];
+  for (const file of files) {
+    try {
+      const filePath = join(repoPath, file);
+      if (!existsSync(filePath)) continue;
+      const content = readFileSync(filePath, "utf-8");
+      const jsxTextPattern = />([^<>{}\n]{2,100})</g;
+      let match;
+      while ((match = jsxTextPattern.exec(content)) !== null) {
+        const text = match[1].trim();
+        if (text && !text.startsWith("{") && !text.includes("className")) {
+          uiTexts.push(text);
+        }
+      }
+      const stringLiteralPattern = /['"`]([^'"`\n]{2,50})['"`]/g;
+      while ((match = stringLiteralPattern.exec(content)) !== null) {
+        const text = match[1].trim();
+        if (text && !text.includes("./") && !text.includes("../") && !text.startsWith("http") && !text.includes("className") && !text.match(/^[a-z_]+$/) && // snake_case identifiers
+        !text.match(/^[a-zA-Z]+\.[a-zA-Z]+/)) {
+          uiTexts.push(text);
+        }
+      }
+      const attrPattern = /(?:label|title|placeholder|value|text)=["'`]([^"'`\n]{2,100})["'`]/gi;
+      while ((match = attrPattern.exec(content)) !== null) {
+        uiTexts.push(match[1].trim());
+      }
+    } catch {
+    }
+  }
+  return [...new Set(uiTexts)];
+}
+function mapACToUIElements(options = {}) {
+  const { acItems = [], repoPath = process.cwd(), changedFiles = [] } = options;
+  if (!acItems || acItems.length === 0) {
+    const analysis = analyzeChangesForTest({ repoPath });
+    return {
+      success: true,
+      mode: "git_only",
+      mappings: [],
+      gitAnalysis: analysis.analysis,
+      changedUIFiles: analysis.analysis.changedUIFiles,
+      interactiveElements: analysis.analysis.interactiveElements,
+      suggestedFlowType: analysis.analysis.suggestedFlowType,
+      message: "No AC items provided. Using git-based analysis for test generation.",
+      recommendations: analysis.recommendations
+    };
+  }
+  const gitAnalysis = analyzeChangesForTest({ repoPath });
+  const filesToCheck = changedFiles.length > 0 ? changedFiles : gitAnalysis.analysis.changedUIFiles;
+  const actualUITexts = extractUITextFromFiles(repoPath, filesToCheck);
+  const sourceCode = getSourceCodeContent(repoPath, filesToCheck);
+  const validationErrors = [];
+  const validationWarnings = [];
+  const validationInfo = [];
+  const mappings = acItems.map((item) => {
+    const mapping = {
+      ...item,
+      matchedFiles: [],
+      matchedElements: [],
+      matchedUITexts: [],
+      relatedUIElements: [],
+      confidence: 0,
+      validated: false,
+      validationStatus: "pending",
+      validationMessage: "",
+      intent: extractIntent(item.text)
+    };
+    const acText = item.text;
+    const intent = mapping.intent;
+    const intentMatch = validateIntent(
+      intent,
+      sourceCode,
+      actualUITexts,
+      gitAnalysis
+    );
+    if (intentMatch.found) {
+      mapping.validated = true;
+      mapping.confidence = intentMatch.confidence;
+      mapping.validationStatus = "passed";
+      mapping.validationMessage = intentMatch.message;
+      mapping.matchedUITexts.push(...intentMatch.matches);
+      validationInfo.push({
+        acItem: acText,
+        intent: intent.action,
+        message: `\u2705 Intent validated: ${intentMatch.message}`
+      });
+    } else {
+      const keywordMatch = findRelatedUIElements(
+        acText,
+        actualUITexts,
+        sourceCode
+      );
+      const specificValueCheck = validateSpecificValues(
+        acText,
+        keywordMatch.elements
+      );
+      if (specificValueCheck.hasMismatch) {
+        mapping.validated = false;
+        mapping.validationStatus = "failed";
+        mapping.confidence = 0;
+        mapping.validationMessage = specificValueCheck.message;
+        mapping.relatedUIElements = keywordMatch.elements;
+        validationErrors.push({
+          acItem: acText,
+          expected: specificValueCheck.expected,
+          found: specificValueCheck.found,
+          message: `\u274C ${specificValueCheck.message}`
+        });
+      } else if (keywordMatch.found) {
+        mapping.relatedUIElements = keywordMatch.elements;
+        mapping.confidence = keywordMatch.confidence;
+        if (keywordMatch.confidence >= 70) {
+          mapping.validated = true;
+          mapping.validationStatus = "passed";
+          mapping.validationMessage = `Found related UI elements: ${keywordMatch.elements.slice(0, 3).join(", ")}`;
+          validationInfo.push({
+            acItem: acText,
+            message: `\u2705 Found related UI elements for "${acText}"`,
+            elements: keywordMatch.elements
+          });
+        } else {
+          mapping.validationStatus = "soft_match";
+          mapping.validationMessage = `Possible match with confidence ${keywordMatch.confidence}%`;
+          validationWarnings.push({
+            acItem: acText,
+            message: `\u26A0\uFE0F Weak match for "${acText}" - confidence ${keywordMatch.confidence}%`,
+            elements: keywordMatch.elements
+          });
+        }
+      }
+    }
+    for (const file of filesToCheck) {
+      const fileName = file.toLowerCase();
+      const textWords = acText.toLowerCase().split(/\s+/).filter((w) => w.length > 3);
+      const matchingWords = textWords.filter((word) => fileName.includes(word));
+      if (matchingWords.length > 0) {
+        mapping.matchedFiles.push({
+          file,
+          matchingWords,
+          confidence: Math.min(matchingWords.length * 25, 100)
+        });
+        if (!mapping.validated) {
+          mapping.confidence = Math.max(
+            mapping.confidence,
+            matchingWords.length * 25
+          );
+        }
+      }
+    }
+    for (const element of gitAnalysis.analysis.interactiveElements) {
+      const elementLower = element.toLowerCase();
+      const acLower = acText.toLowerCase();
+      if (acLower.includes(elementLower) || item.uiKeywords?.some((k) => k.toLowerCase() === elementLower)) {
+        mapping.matchedElements.push(element);
+        if (!mapping.validated) {
+          mapping.confidence = Math.max(mapping.confidence, 60);
+        }
+      }
+    }
+    if (mapping.validationStatus === "pending") {
+      if (mapping.confidence >= 50 || mapping.matchedFiles.length > 0 || mapping.matchedElements.length > 0) {
+        mapping.validationStatus = "soft_match";
+        mapping.validationMessage = "Found related code changes but could not verify exact implementation";
+      } else {
+        mapping.validationStatus = "unmatched";
+        mapping.validationMessage = "No matching UI elements or code changes found";
+        validationWarnings.push({
+          acItem: acText,
+          message: `\u26A0\uFE0F Could not find implementation for "${acText}"`,
+          suggestion: "This AC may not be implemented yet, or may be in unchanged files"
+        });
+      }
+    }
+    mapping.confidence = Math.min(mapping.confidence, 100);
+    return mapping;
+  });
+  const passedMappings = mappings.filter(
+    (m) => m.validationStatus === "passed"
+  );
+  const failedMappings = mappings.filter(
+    (m) => m.validationStatus === "failed"
+  );
+  const softMatchMappings = mappings.filter(
+    (m) => m.validationStatus === "soft_match"
+  );
+  const unmatchedMappings = mappings.filter(
+    (m) => m.validationStatus === "unmatched"
+  );
+  const validatedCount = passedMappings.length + softMatchMappings.length;
+  const validationRate = mappings.length > 0 ? passedMappings.length / mappings.length : 0;
+  const success = failedMappings.length === 0 && validationRate >= 0.7;
+  return {
+    success,
+    mode: "ac_with_git",
+    mappings,
+    passedCount: passedMappings.length,
+    softMatchCount: softMatchMappings.length,
+    unmatchedCount: unmatchedMappings.length,
+    validationRate: Math.round(validationRate * 100),
+    validationErrors,
+    validationWarnings,
+    validationInfo,
+    actualUITexts: actualUITexts.slice(0, 50),
+    diagnostics: {
+      filesScanned: filesToCheck.length,
+      uiTextsExtracted: actualUITexts.length,
+      acItemsProcessed: acItems.length,
+      validationApproach: "intent-based"
+    },
+    gitAnalysis: gitAnalysis.analysis,
+    changedUIFiles: gitAnalysis.analysis.changedUIFiles,
+    interactiveElements: gitAnalysis.analysis.interactiveElements,
+    suggestedFlowType: acItems[0]?.suggestedFlowType || gitAnalysis.analysis.suggestedFlowType,
+    message: generateValidationMessage(
+      success,
+      passedMappings,
+      softMatchMappings,
+      failedMappings,
+      unmatchedMappings
+    ),
+    recommendations: generateRecommendations(
+      mappings,
+      actualUITexts,
+      gitAnalysis
+    )
+  };
+}
+function extractIntent(acText) {
+  const text = acText.toLowerCase();
+  const intentPatterns = [
+    {
+      pattern: /(?:should|can|must)\s+(?:be able to\s+)?(click|tap|press|select)/i,
+      action: "click"
+    },
+    {
+      pattern: /(?:should|can|must)\s+(?:be able to\s+)?(see|view|display|show)/i,
+      action: "display"
+    },
+    {
+      pattern: /(?:should|can|must)\s+(?:be able to\s+)?(enter|input|type|fill)/i,
+      action: "input"
+    },
+    {
+      pattern: /(?:should|can|must)\s+(?:be able to\s+)?(navigate|go to|redirect)/i,
+      action: "navigate"
+    },
+    {
+      pattern: /(?:should|can|must)\s+(?:be able to\s+)?(validate|check|verify)/i,
+      action: "validate"
+    },
+    {
+      pattern: /(?:should|can|must)\s+(?:be able to\s+)?(submit|save|send)/i,
+      action: "submit"
+    },
+    {
+      pattern: /(?:should|can|must)\s+(?:be able to\s+)?(open|close|toggle)/i,
+      action: "toggle"
+    }
+  ];
+  for (const { pattern, action } of intentPatterns) {
+    if (pattern.test(text)) {
+      const match = text.match(pattern);
+      const afterAction = text.substring(
+        text.indexOf(match[0]) + match[0].length
+      );
+      const target = afterAction.split(/\s+/).filter((w) => w.length > 2).slice(0, 5).join(" ");
+      return { action, target, text: acText };
+    }
+  }
+  const keywords = text.split(/\s+/).filter((w) => w.length > 3);
+  return { action: "unknown", target: keywords.join(" "), text: acText };
+}
+function validateIntent(intent, sourceCode, uiTexts, gitAnalysis) {
+  const { action, target } = intent;
+  const matches = [];
+  let confidence = 0;
+  const actionPatterns = {
+    click: ["onClick", "onPress", "onTap", "button", "Button", "clickable"],
+    display: ["visible", "show", "display", "render", "return"],
+    input: ["input", "Input", "onChange", "value", "setValue"],
+    navigate: ["navigate", "redirect", "push", "route", "Router"],
+    validate: ["validate", "error", "required", "check", "verify"],
+    submit: ["onSubmit", "submit", "handleSubmit", "post", "send"],
+    toggle: ["toggle", "open", "close", "setState", "setOpen"]
+  };
+  const patterns = actionPatterns[action] || [];
+  const foundPatterns = patterns.filter((p) => sourceCode.includes(p));
+  if (foundPatterns.length > 0) {
+    confidence += 30;
+    matches.push({ type: "code_pattern", patterns: foundPatterns });
+  }
+  const targetWords = target.toLowerCase().split(/\s+/).filter((w) => w.length > 2);
+  const foundTexts = uiTexts.filter(
+    (text) => targetWords.some((word) => text.toLowerCase().includes(word))
+  );
+  if (foundTexts.length > 0) {
+    confidence += 40;
+    matches.push({ type: "ui_text", texts: foundTexts.slice(0, 5) });
+  }
+  const hasInteractiveElements = gitAnalysis.analysis.interactiveElements.some(
+    (el) => patterns.some((p) => el.includes(p))
+  );
+  if (hasInteractiveElements) {
+    confidence += 30;
+    matches.push({ type: "interactive_element" });
+  }
+  return {
+    found: confidence >= 50,
+    confidence: Math.min(confidence, 100),
+    matches,
+    message: confidence >= 50 ? `${action} action detected with ${confidence}% confidence` : `Could not validate ${action} action`
+  };
+}
+function validateSpecificValues(acText, foundUIElements) {
+  const quotedPattern = /["']([^"']+)["']/g;
+  const quotedValues = [];
+  let match;
+  while ((match = quotedPattern.exec(acText)) !== null) {
+    quotedValues.push(match[1]);
+  }
+  if (quotedValues.length === 0) {
+    return { hasMismatch: false };
+  }
+  for (const quotedValue of quotedValues) {
+    const quotedLower = quotedValue.toLowerCase();
+    const exactMatch = foundUIElements.some(
+      (el) => el.toLowerCase() === quotedLower || el.toLowerCase().includes(quotedLower)
+    );
+    if (!exactMatch) {
+      const relatedElements = foundUIElements.filter((el) => {
+        const quotedWords = quotedLower.split(/\s+/).filter((w) => w.length > 2);
+        const elLower = el.toLowerCase();
+        return quotedWords.some((word) => elLower.includes(word));
+      });
+      if (relatedElements.length > 0) {
+        return {
+          hasMismatch: true,
+          expected: quotedValue,
+          found: relatedElements,
+          message: `AC requires "${quotedValue}" but only found: ${relatedElements.slice(0, 5).join(", ")}. The specific value "${quotedValue}" does NOT exist in the UI.`
+        };
+      } else {
+        return {
+          hasMismatch: true,
+          expected: quotedValue,
+          found: [],
+          message: `AC requires "${quotedValue}" but this value was NOT found in any UI element.`
+        };
+      }
+    }
+  }
+  return { hasMismatch: false };
+}
+function findRelatedUIElements(acText, uiTexts, sourceCode) {
+  const elements = [];
+  let confidence = 0;
+  const stopWords = /* @__PURE__ */ new Set([
+    "the",
+    "a",
+    "an",
+    "is",
+    "should",
+    "can",
+    "must",
+    "be",
+    "to",
+    "of",
+    "and",
+    "or"
+  ]);
+  const cleanText = acText.replace(/["'`]/g, "");
+  const keywords = cleanText.toLowerCase().split(/\s+/).filter((w) => w.length > 2 && !stopWords.has(w));
+  for (const uiText of uiTexts) {
+    const uiTextLower = uiText.toLowerCase();
+    const matchingKeywords = keywords.filter((kw) => uiTextLower.includes(kw));
+    if (matchingKeywords.length > 0) {
+      elements.push(uiText);
+      confidence += matchingKeywords.length * 15;
+    }
+  }
+  const codeMatches = keywords.filter(
+    (kw) => sourceCode.toLowerCase().includes(kw)
+  );
+  if (codeMatches.length > 0) {
+    confidence += codeMatches.length * 10;
+  }
+  return {
+    found: elements.length > 0,
+    elements,
+    confidence: Math.min(confidence, 100)
+  };
+}
+function getSourceCodeContent(repoPath, files) {
+  let content = "";
+  for (const file of files) {
+    try {
+      const filePath = join(repoPath, file);
+      if (existsSync(filePath)) {
+        content += readFileSync(filePath, "utf-8") + "\n";
+      }
+    } catch {
+    }
+  }
+  return content;
+}
+function generateValidationMessage(success, passed, softMatch, failed, unmatched) {
+  const total = passed.length + softMatch.length + failed.length + unmatched.length;
+  if (failed.length > 0) {
+    return `\u274C VALIDATION FAILED: ${failed.length} AC item(s) have SPECIFIC VALUE MISMATCHES. Workflow stopped.`;
+  }
+  const validationRate = Math.round(passed.length / total * 100);
+  if (success) {
+    return `\u2705 Validated ${passed.length} AC items with high confidence, ${softMatch.length} with partial evidence (${validationRate}% validation rate)`;
+  } else {
+    return `\u274C VALIDATION FAILED: Only ${validationRate}% validation rate (${passed.length}/${total} items). Workflow stopped - review unmatched items before proceeding.`;
+  }
+}
+function generateRecommendations(mappings, uiTexts, gitAnalysis) {
+  const passed = mappings.filter((m) => m.validationStatus === "passed");
+  const failed = mappings.filter((m) => m.validationStatus === "failed");
+  const softMatch = mappings.filter((m) => m.validationStatus === "soft_match");
+  const unmatched = mappings.filter((m) => m.validationStatus === "unmatched");
+  const total = mappings.length;
+  const validatedCount = passed.length + softMatch.length;
+  const validationRate = total > 0 ? validatedCount / total : 0;
+  const success = failed.length === 0 && validationRate >= 0.7;
+  return `
+## \u{1F3AF} AC Validation Results (Intent-Based + Strict Value Checking)
+
+### \u274C FAILED - Specific Value Mismatches (${failed.length}):
+${failed.length > 0 ? failed.map(
+    (m) => `- **${m.text}**
+  \u274C ${m.validationMessage}
+  Expected: "${m.intent.target}"
+  Found: ${m.relatedUIElements.slice(0, 5).join(", ")}`
+  ).join("\n") : "_None_"}
+
+### \u2705 Validated (${passed.length}):
+${passed.length > 0 ? passed.map(
+    (m) => `- **${m.text}** (${m.confidence}% confidence)
+  ${m.validationMessage}`
+  ).join("\n") : "_None_"}
+
+### \u26A0\uFE0F Partial Matches (${softMatch.length}):
+${softMatch.length > 0 ? softMatch.map(
+    (m) => `- **${m.text}** (${m.confidence}% confidence)
+  ${m.validationMessage}`
+  ).join("\n") : "_None_"}
+
+### \u2753 Unmatched (${unmatched.length}):
+${unmatched.length > 0 ? unmatched.map((m) => `- **${m.text}**
+  ${m.validationMessage}`).join("\n") : "_None_"}
+
+### \u{1F4CB} UI Elements Found (sample):
+${uiTexts.slice(0, 15).map((t) => `- "${t}"`).join("\n")}
+
+### \u{1F4A1} Recommendation:
+${failed.length > 0 ? `\u274C **WORKFLOW STOPPED** - ${failed.length} AC item(s) have SPECIFIC VALUE MISMATCHES
+
+**Critical Issues:**
+${failed.map((m) => `- "${m.text}" expects values that DON'T EXIST in the UI`).join("\n")}
+
+**Action Required:**
+1. Check if the AC has the correct expected values (typos, outdated requirements?)
+2. Verify if the implementation is missing these specific values
+3. Update EITHER the AC OR the implementation to match
+4. Re-run validation after fixes
+
+**Do not proceed with test generation until ALL validations pass.**` : !success ? `\u274C **WORKFLOW STOPPED** - Validation rate too low (${Math.round(validationRate * 100)}%)
+
+**Action Required:**
+1. Review the unmatched AC items above
+2. Verify if they are implemented in unchanged files
+3. Update the AC to match actual implementation, OR
+4. Complete the implementation to match AC requirements
+
+**Do not proceed with test generation until validation passes (\u226570%).**` : passed.length === mappings.length ? "\u2705 All AC items validated - proceed with test generation" : "\u2705 Sufficient validation - safe to proceed with test generation"}
+`;
+}
 
 // maestro-ai/src/mcp-server.js
 var transport = new StdioServerTransport();
@@ -19771,10 +20658,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 
 Checks if Maestro CLI is installed and automatically installs it if missing.
 
-## \u{1F6A8} CRITICAL: Always Call First
-When a user asks to "generate and run tests" or "run Maestro tests", you MUST:
-1. FIRST call maestro_ensure_installed() to verify/install Maestro CLI
-2. THEN proceed with test generation/execution tools
+## \u{1F6A8} CRITICAL: Workflow Order
+When a user asks to "generate and run tests" or "run Maestro tests", follow this exact sequence:
+1. FIRST: maestro_ensure_installed() \u2190 YOU ARE HERE
+2. NEXT: clickup_fetch_task() \u2190 Call this immediately after (asks user for ClickUp URL)
+3. THEN: Based on user response, continue with ClickUp or git-based flow
+
+After this tool succeeds, your NEXT action must be to call clickup_fetch_task() without parameters.
 
 ## Purpose
 Ensures Maestro CLI is available before running any Maestro commands. This tool:
@@ -19816,15 +20706,23 @@ Uses curl installer: \`curl -fsSL "https://get.maestro.mobile.dev" | bash\`
         name: "maestro_generate_test",
         description: `Generates comprehensive Maestro test instructions for web applications.
 
+## \u26D4 PREREQUISITE: Validation Must Pass First!
+
+If you called map_AC_to_UI and it returned success: false:
+- **DO NOT call this tool!**
+- Report validation errors to user first
+- Get user confirmation before proceeding
+
 ## Purpose
 Creates test planning instructions with guidelines, checklists, and best practices.
 
 ## CRITICAL Rules
-1. Only test CHANGED functionality (from git diff)
-2. Never test existing/unchanged UI elements
-3. Use extendedWaitUntil (not fixed timeouts)
-4. Text selectors first, id fallback
-5. Reuse existing flows via runFlow
+1. **Validation must pass** - Don't generate tests for mismatched AC
+2. Only test CHANGED functionality (from git diff)
+3. Never test existing/unchanged UI elements
+4. Use extendedWaitUntil (not fixed timeouts)
+5. Text selectors first, id fallback
+6. Reuse existing flows via runFlow
 
 ## Flow Types (Optional)
 If flowType is provided, includes a starter template:
@@ -20005,6 +20903,13 @@ Each pattern includes "when to use" guidance.`,
         name: "maestro_analyze_changes",
         description: `Analyzes actual git changes in a repository and provides test recommendations.
 
+## Workflow Position: Step 3
+Call this AFTER the clickup_fetch_task() prompt has been resolved:
+1. maestro_ensure_installed() \u2190 Step 1
+2. clickup_fetch_task() \u2190 Step 2 (ask user for ClickUp URL)
+3. maestro_analyze_changes() \u2190 YOU ARE HERE - Step 3
+4. map_AC_to_UI() \u2192 maestro_generate_test() \u2192 maestro_write_test()
+
 ## Purpose
 Automatically runs git commands to:
 - Detect changed files (unstaged, staged, or committed)
@@ -20053,13 +20958,21 @@ Automatically runs git commands to:
         name: "maestro_write_test",
         description: `Writes a Maestro test YAML file to disk and automatically executes it.
 
-## \u{1F6A8} PREREQUISITE: Call maestro_ensure_installed() FIRST before using this tool!
+## \u{1F6A8} PREREQUISITES - Check BOTH before using this tool!
+
+1. **maestro_ensure_installed()** - Must be called first
+2. **map_AC_to_UI validation** - If called with ClickUp AC, validation must pass (success: true)
+
+## \u26D4 DO NOT USE IF:
+- map_AC_to_UI returned success: false (validation failed)
+- User hasn't confirmed how to handle validation mismatches
 
 ## Purpose
 Saves generated test YAML to a file and AUTOMATICALLY RUNS IT. This is the primary tool for "generate and run" workflows.
 
 ## IMPORTANT
 - \u26A0\uFE0F ALWAYS call maestro_ensure_installed() first to ensure Maestro CLI is available!
+- \u26A0\uFE0F If using ClickUp AC, validation MUST pass before generating tests!
 - This tool ALREADY executes the test by default - do NOT call maestro_run_all_tests after this!
 - Use this for running newly generated tests
 - The execution result is included in the response
@@ -20240,6 +21153,166 @@ Discovers and executes ALL existing .yaml test files in the maestro/ directory.
           },
           required: []
         }
+      },
+      {
+        name: "clickup_fetch_task",
+        description: `Fetches a ClickUp task by URL to extract acceptance criteria for test generation.
+
+## \u{1F6A8} ASK FIRST Pattern
+When called WITHOUT a taskUrl, this tool returns a prompt asking the user:
+> "Do you have a ClickUp task URL for this feature? Paste the URL to generate tests based on acceptance criteria, or type 'skip' to continue with git-based analysis only."
+
+## Workflow Position: Step 2
+This is the MANDATORY second step after maestro_ensure_installed():
+1. maestro_ensure_installed() \u2190 Step 1 (completed)
+2. clickup_fetch_task() \u2190 YOU ARE HERE - Step 2
+3. Wait for user response, then:
+   - If URL provided \u2192 validate_acceptance_criteria \u2192 maestro_analyze_changes \u2192 map_AC_to_UI
+   - If skipped \u2192 maestro_analyze_changes \u2192 map_AC_to_UI (git-only mode)
+
+## How to Use
+1. Call WITHOUT parameters first: clickup_fetch_task()
+2. Show the returned prompt to the user
+3. Based on user's response:
+   - URL provided: Call again with clickup_fetch_task(taskUrl: "<user's url>")
+   - User says "skip"/"no": Call with clickup_fetch_task(taskUrl: "skip")
+
+## URL Parsing
+Extracts task ID from various ClickUp URL formats:
+- https://app.clickup.com/t/abc123
+- https://app.clickup.com/t/86abc123
+- https://app.clickup.com/{workspace}/v/...?p=abc123
+
+## Environment Variables
+Requires CLICKUP_API_TOKEN to be set in MCP configuration.
+
+## Output
+- If no URL: Returns prompt for user input (needsInput: true)
+- If URL provided: Returns full task object with checklists, custom fields, description
+- If "skip": Returns { skipped: true } to signal continue without ClickUp`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            taskUrl: {
+              type: "string",
+              description: 'ClickUp task URL (optional - if omitted, returns a prompt asking for URL). Use "skip" to bypass ClickUp integration.'
+            }
+          },
+          required: []
+        }
+      },
+      {
+        name: "validate_acceptance_criteria",
+        description: `Parses and validates acceptance criteria from a ClickUp task for testability.
+
+## Purpose
+Extracts AC items from multiple sources and validates them for Maestro test generation.
+
+## AC Sources (configured via CLICKUP_AC_SOURCE env var)
+- checklist:Checklist Name - Parse from a specific checklist
+- custom_field:Field Name - Parse from a custom field
+- description - Parse from task description
+- Multiple sources: "checklist:Acceptance Criteria,custom_field:AC,description"
+
+## Validation
+Each AC item is analyzed for:
+- UI-related keywords (click, button, form, input, navigate, etc.)
+- Testability score (0-100)
+- Suggested flow type (auth, form, sidebar, modal, navigation)
+- Whether it's testable via Maestro
+
+## Output
+- validatedItems: Array of AC items with testability analysis
+- testableCount: Number of items that can be tested
+- suggestedFlowTypes: Recommended flow types based on AC content`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            task: {
+              type: "object",
+              description: "ClickUp task object (from clickup_fetch_task)"
+            },
+            acSource: {
+              type: "string",
+              description: 'AC source specification (optional, uses CLICKUP_AC_SOURCE env var if not provided). Format: "checklist:Name" or "custom_field:Name" or "description"'
+            }
+          },
+          required: ["task"]
+        }
+      },
+      {
+        name: "map_AC_to_UI",
+        description: `Maps acceptance criteria items to UI elements based on git changes.
+
+## \u{1F6D1} BLOCKING VALIDATION - STOP ON FAILURE!
+
+This tool performs **strict validation** of AC against actual UI implementation.
+## Purpose
+Cross-references AC items with git diff and source code to:
+- Extract actual UI text from
+I source files
+- Compare AC text against real UI strings
+- **FAIL if values don't match** (e.g., AC: "20 days" vs UI: "30 days")
+- Report validation errors that must be resolved
+
+## \u26D4 CRITICAL: When success=false, STOP THE WORKFLOW!
+
+## Modes
+- ac with_git: When AC items are provided, performs HARD validation
+- git_only: When no AC items, uses pure git-based analysis (soft mode)
+
+## Output
+- success: **false** if any AC doesn't match UI, **true** if all validated
+- validationErrors: Array of mismatches (AC expected vs UI actual)
+- validationWarnings: Items that couldn't be fully verified
+- actualUITexts: Sample of UI text strings found in source code
+
+If this tool returns success: false:
+1. **STOP IMMEDIATELY** - Do NOT call any more tools
+3. **END your response** - Do not continue, do not ask questions
+
+## Output Format When Validation Fails:
+## \u2705 CORRECT BEHAVIOR:
+When validation fails, respond with:
+"\u274C Validation failed. The acceptance criteria don't match the UI:
+- [list mismatches]
+
+**Recommendation:** Update the ClickUp task acceptance criteria to match the actual UI implementation, OR fix the UI to match the AC requirements.
+
+**Actual UI values available:** [list what exists]
+
+*Workflow stopped. Re-run after resolving the mismatches.*"
+
+## \u274C FORBIDDEN ACTIONS AFTER FAILURE:
+- Calling maestro_generate_test
+- Calling maestro_write_test
+- Saying "I'll generate a test based on what actually exists"
+- Asking follow-up questions
+- Continuing the workflow in any way
+
+## Output
+- success: **false** = STOP WORKFLOW, output recommendation, END RESPONSE
+- success: **true** = OK to proceed with test generation`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            acItems: {
+              type: "array",
+              items: { type: "object" },
+              description: "Validated AC items from validate_acceptance_criteria (optional - if omitted, uses git-only analysis)"
+            },
+            repoPath: {
+              type: "string",
+              description: "Path to the git repository (default: current directory)"
+            },
+            changedFiles: {
+              type: "array",
+              items: { type: "string" },
+              description: "List of changed files to match against (optional - auto-detected from git if omitted)"
+            }
+          },
+          required: []
+        }
       }
     ]
   };
@@ -20359,6 +21432,41 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       });
       break;
     }
+    case "clickup_fetch_task": {
+      const { taskUrl } = args || {};
+      result = await fetchClickUpTask({
+        taskUrl: taskUrl || null
+      });
+      break;
+    }
+    case "validate_acceptance_criteria": {
+      const { task, acSource } = args || {};
+      const parsed = parseAcceptanceCriteria({
+        task,
+        acSource: acSource || null
+      });
+      if (parsed.success) {
+        const validated = validateAcceptanceCriteria({
+          acItems: parsed.acItems
+        });
+        result = {
+          ...parsed,
+          ...validated
+        };
+      } else {
+        result = parsed;
+      }
+      break;
+    }
+    case "map_AC_to_UI": {
+      const { acItems, repoPath, changedFiles } = args || {};
+      result = mapACToUIElements({
+        acItems: acItems || [],
+        repoPath: repoPath || process.cwd(),
+        changedFiles: changedFiles || []
+      });
+      break;
+    }
     default:
       throw new Error(`Unknown tool: ${name}`);
   }