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

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

@@ -18492,7 +18492,17 @@ var StdioServerTransport = class {
 };
 
 // maestro-ai/src/mcp.js
-import { execSync } from "child_process";
+import { execSync, spawn } from "child_process";
+import {
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  openSync,
+  closeSync,
+  fsyncSync
+} from "fs";
+import { join, dirname } from "path";
 var FLOW_TYPES = {
   auth: {
     description: "Login, signup, or password reset flows",
@@ -18520,6 +18530,156 @@ var FLOW_TYPES = {
     requiresOnboarding: false
   }
 };
+function isMaestroInstalled() {
+  try {
+    execSync("which maestro", { encoding: "utf-8", stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function installMaestro() {
+  const installCmd = 'curl -fsSL "https://get.maestro.mobile.dev" | bash';
+  try {
+    try {
+      execSync(installCmd, {
+        encoding: "utf-8",
+        stdio: "pipe",
+        shell: "/bin/bash",
+        timeout: 12e4
+        // 2 minute timeout for install
+      });
+    } catch (curlError) {
+      const curlOutput = curlError.stderr || curlError.stdout || curlError.message;
+      throw new Error(`Installation failed: ${curlOutput}`);
+    }
+    if (isMaestroInstalled()) {
+      return {
+        success: true,
+        message: "\u2705 Maestro CLI installed successfully!",
+        method: "curl"
+      };
+    }
+    const homeDir = process.env.HOME || process.env.USERPROFILE;
+    const maestroBin = join(homeDir, ".maestro", "bin");
+    process.env.PATH = `${maestroBin}:${process.env.PATH}`;
+    try {
+      execSync(`${join(maestroBin, "maestro")} --version`, {
+        encoding: "utf-8",
+        stdio: "pipe"
+      });
+      return {
+        success: true,
+        message: `\u2705 Maestro CLI installed successfully! Added ${maestroBin} to PATH.`,
+        method: "curl"
+      };
+    } catch {
+      return {
+        success: false,
+        message: `\u26A0\uFE0F Maestro installed but not in PATH. Add ${maestroBin} to your PATH and restart your terminal.`,
+        method: "curl"
+      };
+    }
+  } catch (error2) {
+    return {
+      success: false,
+      message: `\u274C Failed to install Maestro: ${error2.message}
+
+Manual install:
+${installCmd}`,
+      method: "curl"
+    };
+  }
+}
+function ensureMaestroAvailable() {
+  if (isMaestroInstalled()) {
+    return {
+      available: true,
+      message: "Maestro CLI is available",
+      installed: false
+    };
+  }
+  const installResult = installMaestro();
+  return {
+    available: installResult.success,
+    message: installResult.message,
+    installed: installResult.success
+  };
+}
+function getMaestroVersion() {
+  try {
+    const version2 = execSync("maestro --version", {
+      encoding: "utf-8",
+      stdio: "pipe"
+    }).trim();
+    return version2;
+  } catch {
+    return null;
+  }
+}
+function ensureMaestroInstalled(options = {}) {
+  const { autoInstall = true, forceReinstall = false } = options;
+  const result = {
+    installed: false,
+    version: null,
+    wasInstalled: false,
+    message: "",
+    details: {
+      installMethod: null,
+      path: null
+    }
+  };
+  const alreadyInstalled = isMaestroInstalled();
+  const currentVersion = alreadyInstalled ? getMaestroVersion() : null;
+  if (alreadyInstalled && !forceReinstall) {
+    result.installed = true;
+    result.version = currentVersion;
+    result.wasInstalled = false;
+    result.message = `\u2705 Maestro CLI is already installed (${currentVersion || "version unknown"})`;
+    try {
+      const path = execSync("which maestro", {
+        encoding: "utf-8",
+        stdio: "pipe"
+      }).trim();
+      result.details.path = path;
+    } catch {
+    }
+    return result;
+  }
+  if (!autoInstall) {
+    result.installed = false;
+    result.version = null;
+    result.wasInstalled = false;
+    result.message = `\u274C Maestro CLI is not installed. Set autoInstall: true to install automatically.`;
+    result.details.installCommand = 'curl -fsSL "https://get.maestro.mobile.dev" | bash';
+    return result;
+  }
+  const installResult = installMaestro();
+  if (installResult.success) {
+    const newVersion = getMaestroVersion();
+    result.installed = true;
+    result.version = newVersion;
+    result.wasInstalled = true;
+    result.message = installResult.message;
+    result.details.installMethod = installResult.method;
+    try {
+      const path = execSync("which maestro", {
+        encoding: "utf-8",
+        stdio: "pipe"
+      }).trim();
+      result.details.path = path;
+    } catch {
+    }
+  } else {
+    result.installed = false;
+    result.version = null;
+    result.wasInstalled = false;
+    result.message = installResult.message;
+    result.details.installMethod = installResult.method;
+    result.details.installCommand = 'curl -fsSL "https://get.maestro.mobile.dev" | bash';
+  }
+  return result;
+}
 function getMaestroCheatSheet() {
   const commands = [
     {
@@ -19289,138 +19449,1382 @@ ${analysis.shouldCreateTest ? `1. Review the changed UI files above
     }
   };
 }
-
-// maestro-ai/src/mcp-server.js
-var transport = new StdioServerTransport();
-var server = new Server(
-  {
-    name: "Maestro AI MCP Server",
-    version: "0.0.1"
-  },
-  {
-    capabilities: {
-      tools: {}
+function writeTestFile(options = {}) {
+  const {
+    yaml,
+    fileName,
+    directory = "maestro",
+    basePath = process.cwd(),
+    execute = true,
+    deviceId = null,
+    env = {},
+    feature = "",
+    action = "",
+    flowType = null,
+    changedElements = [],
+    existingTests = []
+  } = options;
+  const generation = generateMaestroTest({
+    feature,
+    action,
+    flowType,
+    changedElements,
+    existingTests
+  });
+  if (!yaml || !fileName) {
+    return {
+      success: false,
+      filePath: null,
+      message: "\u274C Missing required parameters: yaml and fileName are required"
+    };
+  }
+  const normalizedFileName = fileName.endsWith(".yaml") ? fileName : `${fileName}.yaml`;
+  const targetDir = join(basePath, directory);
+  const filePath = join(targetDir, normalizedFileName);
+  try {
+    if (!existsSync(targetDir)) {
+      mkdirSync(targetDir, { recursive: true });
+    }
+    writeFileSync(filePath, yaml, "utf-8");
+    const fd = openSync(filePath, "r");
+    fsyncSync(fd);
+    closeSync(fd);
+    const result = {
+      success: true,
+      filePath,
+      message: `\u2705 Test file written successfully to: ${filePath}`,
+      generation
+      // Include test generation guidelines and instructions
+    };
+    if (execute) {
+      const sleep = (ms) => {
+        const end = Date.now() + ms;
+        while (Date.now() < end) {
+        }
+      };
+      sleep(500);
+      const execution = executeTest({
+        flowFile: filePath,
+        deviceId,
+        env
+      });
+      result.execution = execution;
+      result.message += execution.success ? "\n\u2705 Test executed successfully!" : "\n\u274C Test execution failed.";
     }
+    return result;
+  } catch (error2) {
+    return {
+      success: false,
+      filePath: null,
+      message: `\u274C Failed to write test file: ${error2.message}`
+    };
   }
-);
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-  return {
-    tools: [
-      {
-        name: "maestro_generate_test",
-        description: `Generates comprehensive Maestro test instructions for web applications.
-
-## Purpose
-Creates test planning instructions with guidelines, checklists, and best practices.
+}
+function executeTest(options = {}) {
+  const { flowFile, deviceId = null, env = {}, timeout = 12e4 } = options;
+  if (!flowFile) {
+    return {
+      success: false,
+      output: "\u274C Missing required parameter: flowFile",
+      exitCode: 1,
+      duration: 0
+    };
+  }
+  const maestroCheck = ensureMaestroAvailable();
+  if (!maestroCheck.available) {
+    return {
+      success: false,
+      output: maestroCheck.message,
+      exitCode: 1,
+      duration: 0,
+      maestroInstalled: false
+    };
+  }
+  const args = ["test"];
+  if (deviceId) {
+    args.push("--device", deviceId);
+  }
+  Object.entries(env).forEach(([key, value]) => {
+    args.push("-e", `${key}=${value}`);
+  });
+  args.push(flowFile);
+  const command = `maestro ${args.join(" ")}`;
+  const startTime = Date.now();
+  try {
+    const output = execSync(command, {
+      encoding: "utf-8",
+      timeout,
+      maxBuffer: 10 * 1024 * 1024,
+      env: { ...process.env, ...env }
+    });
+    const duration3 = Date.now() - startTime;
+    return {
+      success: true,
+      output: `${maestroCheck.installed ? "\u{1F4E6} " + maestroCheck.message + "\n\n" : ""}\u2705 Test passed!
 
-## 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
+Command: ${command}
 
-## Flow Types (Optional)
-If flowType is provided, includes a starter template:
-- auth: Login, signup flows
-- sidebar: Sidebar panel interactions
-- form: Form fill and submit
-- modal: Modal/dialog interactions
-- navigation: Page-to-page navigation
-- extended: Build on existing flow
+${output}`,
+      exitCode: 0,
+      duration: duration3,
+      command,
+      maestroInstalled: maestroCheck.installed
+    };
+  } catch (error2) {
+    const duration3 = Date.now() - startTime;
+    const output = error2.stdout || error2.stderr || error2.message;
+    return {
+      success: false,
+      output: `${maestroCheck.installed ? "\u{1F4E6} " + maestroCheck.message + "\n\n" : ""}\u274C Test failed!
 
-If flowType is omitted, provides guidance to use other tools (cheat_sheet, pattern, ui_inspection).
+Command: ${command}
 
-## Output
-Returns guidelines checklist, suggested filename, and optionally a template.`,
-        inputSchema: {
-          type: "object",
-          properties: {
-            feature: {
-              type: "string",
-              description: 'The feature being tested (e.g., "User Settings", "Login")'
-            },
-            action: {
-              type: "string",
-              description: 'The action being tested (e.g., "Reset defaults", "Submit form")'
-            },
-            flowType: {
-              type: "string",
-              enum: [
-                "auth",
-                "sidebar",
-                "form",
-                "modal",
-                "navigation",
-                "extended"
-              ],
-              description: "Type of flow template (optional - omit for template-free generation)"
-            },
-            changedElements: {
-              type: "array",
-              items: { type: "string" },
-              description: "List of UI elements that were changed (from git diff)"
-            },
-            existingTests: {
-              type: "array",
-              items: { type: "string" },
-              description: "List of existing related test files to potentially extend"
-            }
-          },
-          required: ["feature", "action"]
-        }
-      },
-      {
-        name: "maestro_cheat_sheet",
-        description: `Returns Maestro commands quick reference.
+${output}`,
+      exitCode: error2.status || 1,
+      duration: duration3,
+      command,
+      maestroInstalled: maestroCheck.installed
+    };
+  }
+}
+function executeTestsSequentially(options = {}) {
+  const {
+    flowFiles = [],
+    deviceId = null,
+    env = {},
+    stopOnFailure = false
+  } = options;
+  if (!flowFiles || flowFiles.length === 0) {
+    return {
+      success: false,
+      results: [],
+      summary: {
+        total: 0,
+        passed: 0,
+        failed: 0,
+        skipped: 0,
+        totalDuration: 0
+      }
+    };
+  }
+  const results = [];
+  let stopped = false;
+  for (const flowFile of flowFiles) {
+    if (stopped) {
+      results.push({
+        flowFile,
+        success: false,
+        output: "\u23ED\uFE0F Skipped due to previous failure",
+        exitCode: -1,
+        duration: 0,
+        skipped: true
+      });
+      continue;
+    }
+    const result = executeTest({ flowFile, deviceId, env });
+    results.push({
+      flowFile,
+      ...result,
+      skipped: false
+    });
+    if (!result.success && stopOnFailure) {
+      stopped = true;
+    }
+  }
+  const passed = results.filter((r) => r.success).length;
+  const failed = results.filter((r) => !r.success && !r.skipped).length;
+  const skipped = results.filter((r) => r.skipped).length;
+  const totalDuration = results.reduce((sum, r) => sum + r.duration, 0);
+  return {
+    success: failed === 0,
+    results,
+    summary: {
+      total: flowFiles.length,
+      passed,
+      failed,
+      skipped,
+      totalDuration,
+      report: `
+## \u{1F4CA} Test Execution Summary
 
-## Includes
-- All core commands (launchApp, tapOn, inputText, etc.)
-- Selector strategy (text \u2192 id \u2192 index \u2192 repeat)
-- Waiting strategy (extendedWaitUntil)
-- File naming conventions
-- Environment variable setup
+| Metric | Value |
+|--------|-------|
+| Total Tests | ${flowFiles.length} |
+| \u2705 Passed | ${passed} |
+| \u274C Failed | ${failed} |
+| \u23ED\uFE0F Skipped | ${skipped} |
+| \u23F1\uFE0F Duration | ${(totalDuration / 1e3).toFixed(2)}s |
 
-Use this before writing any Maestro YAML to ensure correct syntax.`,
-        inputSchema: {
-          type: "object",
-          properties: {},
-          required: []
+### Results by Flow:
+${results.map(
+        (r) => `- ${r.success ? "\u2705" : r.skipped ? "\u23ED\uFE0F" : "\u274C"} \`${r.flowFile}\` (${(r.duration / 1e3).toFixed(2)}s)`
+      ).join("\n")}
+`
+    }
+  };
+}
+function discoverTestFiles(options = {}) {
+  const { directory = "maestro", basePath = process.cwd() } = options;
+  const targetDir = join(basePath, directory);
+  if (!existsSync(targetDir)) {
+    return {
+      files: [],
+      count: 0,
+      message: `\u274C Directory not found: ${targetDir}`
+    };
+  }
+  try {
+    const result = execSync(`find "${targetDir}" -name "*.yaml" -type f`, {
+      encoding: "utf-8"
+    });
+    const files = result.trim().split("\n").filter(Boolean);
+    return {
+      files,
+      count: files.length,
+      message: `Found ${files.length} test file(s) in ${targetDir}`
+    };
+  } catch (error2) {
+    return {
+      files: [],
+      count: 0,
+      message: `\u274C Error discovering files: ${error2.message}`
+    };
+  }
+}
+function runAllTests(options = {}) {
+  const {
+    directory = "maestro",
+    basePath = process.cwd(),
+    deviceId = null,
+    env = {},
+    stopOnFailure = false,
+    files = null
+  } = options;
+  let discovery;
+  let filesToRun;
+  if (files && Array.isArray(files) && files.length > 0) {
+    filesToRun = files.map((f) => {
+      if (f.startsWith("/")) {
+        return f;
+      }
+      return join(basePath, f);
+    });
+    discovery = {
+      files: filesToRun,
+      count: filesToRun.length,
+      message: `Using ${filesToRun.length} specified test file(s)`,
+      mode: "specified"
+    };
+  } else {
+    discovery = discoverTestFiles({ directory, basePath });
+    discovery.mode = "discovered";
+    filesToRun = discovery.files;
+  }
+  if (!filesToRun || filesToRun.length === 0) {
+    return {
+      discovery,
+      execution: {
+        success: false,
+        results: [],
+        summary: {
+          total: 0,
+          passed: 0,
+          failed: 0,
+          skipped: 0,
+          totalDuration: 0,
+          report: "No test files found to execute."
         }
-      },
-      {
-        name: "maestro_flow_template",
-        description: `Returns a specific Maestro flow template by type.
-
-## Available Types
-- auth: Login/signup with onboarding dismissal
-- sidebar: Sidebar panel interactions
-- form: Form fill and submit
-- modal: Modal/dialog interactions
-- navigation: Page-to-page navigation
-- extended: Build on existing flow with runFlow
-
-## Customization Options
-- name: Flow name
-- baseUrl: Override default localhost:8443
-- waitForElement: Initial element to wait for
-- baseFlow: For extended type, the base flow to extend`,
-        inputSchema: {
-          type: "object",
-          properties: {
-            flowType: {
-              type: "string",
-              enum: [
-                "auth",
-                "sidebar",
-                "form",
-                "modal",
-                "navigation",
-                "extended"
-              ],
-              description: "Type of flow template to return"
-            },
-            name: {
+      }
+    };
+  }
+  const execution = executeTestsSequentially({
+    flowFiles: filesToRun,
+    deviceId,
+    env,
+    stopOnFailure
+  });
+  return {
+    discovery,
+    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();
+var server = new Server(
+  {
+    name: "Maestro AI MCP Server",
+    version: "0.0.1"
+  },
+  {
+    capabilities: {
+      tools: {}
+    }
+  }
+);
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "maestro_ensure_installed",
+        description: `\u26A0\uFE0F PREREQUISITE: Call this FIRST before using maestro_write_test or maestro_run_all_tests!
+
+Checks if Maestro CLI is installed and automatically installs it if missing.
+
+## \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:
+- Checks if Maestro CLI is installed on the system
+- Automatically installs it if missing (via Homebrew or curl)
+- Returns version and path information
+
+## When to Use
+- ALWAYS before maestro_write_test (if execute=true)
+- ALWAYS before maestro_run_all_tests
+- When setting up a new development environment
+- To troubleshoot Maestro installation issues
+
+## Installation Method
+Uses curl installer: \`curl -fsSL "https://get.maestro.mobile.dev" | bash\`
+
+## Output
+- installed: Whether Maestro is now installed
+- version: Installed version (if available)
+- wasInstalled: Whether this call performed the installation
+- message: Status message
+- details: Additional info (path, install method)`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            autoInstall: {
+              type: "boolean",
+              description: "Whether to automatically install Maestro if not found (default: true)"
+            },
+            forceReinstall: {
+              type: "boolean",
+              description: "Whether to force reinstall even if already installed (default: false)"
+            }
+          },
+          required: []
+        }
+      },
+      {
+        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. **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:
+- auth: Login, signup flows
+- sidebar: Sidebar panel interactions
+- form: Form fill and submit
+- modal: Modal/dialog interactions
+- navigation: Page-to-page navigation
+- extended: Build on existing flow
+
+If flowType is omitted, provides guidance to use other tools (cheat_sheet, pattern, ui_inspection).
+
+## Output
+Returns guidelines checklist, suggested filename, and optionally a template.`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            feature: {
+              type: "string",
+              description: 'The feature being tested (e.g., "User Settings", "Login")'
+            },
+            action: {
+              type: "string",
+              description: 'The action being tested (e.g., "Reset defaults", "Submit form")'
+            },
+            flowType: {
+              type: "string",
+              enum: [
+                "auth",
+                "sidebar",
+                "form",
+                "modal",
+                "navigation",
+                "extended"
+              ],
+              description: "Type of flow template (optional - omit for template-free generation)"
+            },
+            changedElements: {
+              type: "array",
+              items: { type: "string" },
+              description: "List of UI elements that were changed (from git diff)"
+            },
+            existingTests: {
+              type: "array",
+              items: { type: "string" },
+              description: "List of existing related test files to potentially extend"
+            }
+          },
+          required: ["feature", "action"]
+        }
+      },
+      {
+        name: "maestro_cheat_sheet",
+        description: `Returns Maestro commands quick reference.
+
+## Includes
+- All core commands (launchApp, tapOn, inputText, etc.)
+- Selector strategy (text \u2192 id \u2192 index \u2192 repeat)
+- Waiting strategy (extendedWaitUntil)
+- File naming conventions
+- Environment variable setup
+
+Use this before writing any Maestro YAML to ensure correct syntax.`,
+        inputSchema: {
+          type: "object",
+          properties: {},
+          required: []
+        }
+      },
+      {
+        name: "maestro_flow_template",
+        description: `Returns a specific Maestro flow template by type.
+
+## Available Types
+- auth: Login/signup with onboarding dismissal
+- sidebar: Sidebar panel interactions
+- form: Form fill and submit
+- modal: Modal/dialog interactions
+- navigation: Page-to-page navigation
+- extended: Build on existing flow with runFlow
+
+## Customization Options
+- name: Flow name
+- baseUrl: Override default localhost:8443
+- waitForElement: Initial element to wait for
+- baseFlow: For extended type, the base flow to extend`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            flowType: {
+              type: "string",
+              enum: [
+                "auth",
+                "sidebar",
+                "form",
+                "modal",
+                "navigation",
+                "extended"
+              ],
+              description: "Type of flow template to return"
+            },
+            name: {
               type: "string",
               description: "Custom name for the flow"
             },
@@ -19499,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)
@@ -19542,6 +20953,366 @@ Automatically runs git commands to:
           },
           required: ["repoPath"]
         }
+      },
+      {
+        name: "maestro_write_test",
+        description: `Writes a Maestro test YAML file to disk and automatically executes it.
+
+## \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
+- This tool internally calls maestro_generate_test to provide guidelines and instructions
+
+## Parameters
+- yaml: The YAML content to write (required)
+- fileName: Name of the file, e.g., "login_test.yaml" (required)
+- directory: Target directory (default: "maestro")
+- basePath: Project base path (default: current directory)
+- execute: Whether to auto-execute after writing (default: true)
+- deviceId: Device ID for execution (optional)
+- env: Environment variables for execution (optional)
+- feature: Feature being tested (for test generation guidelines)
+- action: Action being tested (for test generation guidelines)
+- flowType: Type of flow template (auth, sidebar, form, modal, navigation, extended)
+- changedElements: List of UI elements that were changed
+- existingTests: List of existing related test files
+
+## Output
+- success: boolean
+- filePath: Path where file was written
+- message: Status message
+- generation: Test generation guidelines and instructions (from maestro_generate_test)
+- execution: Test execution results (if execute=true)`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            yaml: {
+              type: "string",
+              description: "The YAML content to write"
+            },
+            fileName: {
+              type: "string",
+              description: 'Name of the file (e.g., "login_test.yaml")'
+            },
+            directory: {
+              type: "string",
+              description: 'Target directory (default: "maestro")'
+            },
+            basePath: {
+              type: "string",
+              description: "Project base path (default: current directory)"
+            },
+            execute: {
+              type: "boolean",
+              description: "Whether to auto-execute the test after writing (default: true)"
+            },
+            deviceId: {
+              type: "string",
+              description: "Device ID to run on (optional)"
+            },
+            env: {
+              type: "object",
+              description: "Environment variables to pass",
+              additionalProperties: { type: "string" }
+            },
+            feature: {
+              type: "string",
+              description: 'Feature being tested for generation guidelines (e.g., "User Settings")'
+            },
+            action: {
+              type: "string",
+              description: 'Action being tested for generation guidelines (e.g., "Reset defaults")'
+            },
+            flowType: {
+              type: "string",
+              enum: [
+                "auth",
+                "sidebar",
+                "form",
+                "modal",
+                "navigation",
+                "extended"
+              ],
+              description: "Type of flow template for generation guidelines"
+            },
+            changedElements: {
+              type: "array",
+              items: { type: "string" },
+              description: "List of UI elements that were changed (from git diff)"
+            },
+            existingTests: {
+              type: "array",
+              items: { type: "string" },
+              description: "List of existing related test files to potentially extend"
+            }
+          },
+          required: ["yaml", "fileName"]
+        }
+      },
+      {
+        name: "maestro_discover_tests",
+        description: `Discovers all Maestro test files in a directory.
+
+## Purpose
+Lists all .yaml test files in the maestro/ directory.
+
+## Parameters
+- directory: Directory to search (default: "maestro")
+- basePath: Project base path
+
+## Output
+- files: Array of file paths
+- count: Number of files found`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            directory: {
+              type: "string",
+              description: 'Directory to search (default: "maestro")'
+            },
+            basePath: {
+              type: "string",
+              description: "Project base path"
+            }
+          },
+          required: []
+        }
+      },
+      {
+        name: "maestro_run_all_tests",
+        description: `Runs the ENTIRE Maestro test suite.
+
+## \u{1F6A8} PREREQUISITE: Call maestro_ensure_installed() FIRST before using this tool!
+
+## \u26A0\uFE0F ONLY use when user EXPLICITLY asks to "run all tests" or "run the test suite"
+
+## DO NOT USE for:
+- "generate and run test cases" \u2192 use maestro_write_test instead (it auto-executes)
+- Running a newly generated test \u2192 maestro_write_test already does this
+- Any workflow that involves generating new tests
+
+## Purpose
+Discovers and executes ALL existing .yaml test files in the maestro/ directory.
+
+## Parameters
+- files: Specific test file paths (optional)
+- directory: Directory containing tests (default: "maestro")
+- basePath: Project base path
+- deviceId: Target device ID
+- env: Environment variables
+- stopOnFailure: Stop on first failure (default: false)
+
+## Output
+- discovery: List of test files found
+- execution: Results with pass/fail status for each test
+- summary: Aggregated statistics`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            files: {
+              type: "array",
+              items: { type: "string" },
+              description: "Specific test file paths to run (if provided, only these files are executed instead of discovering all)"
+            },
+            directory: {
+              type: "string",
+              description: 'Directory containing tests (default: "maestro") - only used if files is not provided'
+            },
+            basePath: {
+              type: "string",
+              description: "Project base path"
+            },
+            deviceId: {
+              type: "string",
+              description: "Device ID to run on"
+            },
+            env: {
+              type: "object",
+              description: "Environment variables",
+              additionalProperties: { type: "string" }
+            },
+            stopOnFailure: {
+              type: "boolean",
+              description: "Stop on first failure (default: false)"
+            }
+          },
+          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: []
+        }
       }
     ]
   };
@@ -19550,6 +21321,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
   let result;
   switch (name) {
+    case "maestro_ensure_installed": {
+      const { autoInstall, forceReinstall } = args || {};
+      result = ensureMaestroInstalled({
+        autoInstall: autoInstall !== false,
+        // defaults to true
+        forceReinstall: forceReinstall || false
+      });
+      break;
+    }
     case "maestro_generate_test": {
       const { feature, action, flowType, changedElements, existingTests } = args || {};
       result = generateMaestroTest({
@@ -19600,6 +21380,93 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       });
       break;
     }
+    case "maestro_write_test": {
+      const {
+        yaml,
+        fileName,
+        directory,
+        basePath,
+        execute,
+        deviceId,
+        env,
+        feature,
+        action,
+        flowType,
+        changedElements,
+        existingTests
+      } = args || {};
+      result = writeTestFile({
+        yaml,
+        fileName,
+        directory: directory || "maestro",
+        basePath: basePath || process.cwd(),
+        execute: execute !== false,
+        // defaults to true
+        deviceId: deviceId || null,
+        env: env || {},
+        feature: feature || "",
+        action: action || "",
+        flowType: flowType || null,
+        changedElements: changedElements || [],
+        existingTests: existingTests || []
+      });
+      break;
+    }
+    case "maestro_discover_tests": {
+      const { directory, basePath } = args || {};
+      result = discoverTestFiles({
+        directory: directory || "maestro",
+        basePath: basePath || process.cwd()
+      });
+      break;
+    }
+    case "maestro_run_all_tests": {
+      const { files, directory, basePath, deviceId, env, stopOnFailure } = args || {};
+      result = runAllTests({
+        files: files || null,
+        directory: directory || "maestro",
+        basePath: basePath || process.cwd(),
+        deviceId: deviceId || null,
+        env: env || {},
+        stopOnFailure: stopOnFailure || false
+      });
+      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}`);
   }