mcp-maestro-mobile-ai 1.4.0 → 1.6.0

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

@@ -0,0 +1,381 @@
+/**
+ * YAML Cache System
+ *
+ * Caches generated YAML files for faster execution of recurring test scenarios.
+ *
+ * Features:
+ * - Prompt-based hashing for unique identification
+ * - Hidden internal storage (~/.maestro-mcp/cache/)
+ * - Automatic cache lookup on test execution
+ * - Save successful tests for future reuse
+ * - Invalidation when prompt changes
+ */
+
+import { createHash } from "crypto";
+import fs from "fs/promises";
+import { existsSync } from "fs";
+import { join } from "path";
+import os from "os";
+import { logger } from "./logger.js";
+
+// Cache directory (hidden from user, alongside other maestro-mcp files)
+const CACHE_DIR = join(os.homedir(), ".maestro-mcp", "cache");
+const CACHE_INDEX_FILE = join(CACHE_DIR, "index.json");
+
+/**
+ * Generate a hash from the prompt for unique identification
+ * Normalizes the prompt to handle minor formatting differences
+ */
+export function generatePromptHash(prompt, appId = null) {
+  // Normalize the prompt: lowercase, trim, collapse whitespace
+  const normalized = prompt
+    .toLowerCase()
+    .trim()
+    .replace(/\s+/g, " ")
+    .replace(/['"]/g, ""); // Remove quotes for consistency
+
+  // Include appId in hash if provided
+  const hashInput = appId ? `${appId}::${normalized}` : normalized;
+
+  return createHash("sha256").update(hashInput).digest("hex").substring(0, 16); // Use first 16 chars for readability
+}
+
+/**
+ * Initialize cache directory
+ */
+async function ensureCacheDir() {
+  try {
+    await fs.mkdir(CACHE_DIR, { recursive: true });
+  } catch (error) {
+    logger.error("Failed to create cache directory", { error: error.message });
+  }
+}
+
+/**
+ * Load the cache index
+ */
+async function loadCacheIndex() {
+  try {
+    await ensureCacheDir();
+
+    if (!existsSync(CACHE_INDEX_FILE)) {
+      return {};
+    }
+
+    const content = await fs.readFile(CACHE_INDEX_FILE, "utf8");
+    return JSON.parse(content);
+  } catch (error) {
+    logger.warn("Failed to load cache index, starting fresh", {
+      error: error.message,
+    });
+    return {};
+  }
+}
+
+/**
+ * Save the cache index
+ */
+async function saveCacheIndex(index) {
+  try {
+    await ensureCacheDir();
+    await fs.writeFile(
+      CACHE_INDEX_FILE,
+      JSON.stringify(index, null, 2),
+      "utf8"
+    );
+  } catch (error) {
+    logger.error("Failed to save cache index", { error: error.message });
+  }
+}
+
+/**
+ * Look up cached YAML for a prompt
+ *
+ * @param {string} prompt - The original test prompt
+ * @param {string} appId - App ID for context
+ * @returns {object|null} Cached entry or null if not found
+ */
+export async function lookupCache(prompt, appId = null) {
+  try {
+    const hash = generatePromptHash(prompt, appId);
+    const index = await loadCacheIndex();
+
+    if (!index[hash]) {
+      return null;
+    }
+
+    const entry = index[hash];
+    const yamlPath = join(CACHE_DIR, `${hash}.yaml`);
+
+    // Verify the YAML file exists
+    if (!existsSync(yamlPath)) {
+      // Stale index entry, clean up
+      delete index[hash];
+      await saveCacheIndex(index);
+      return null;
+    }
+
+    // Read the cached YAML
+    const yaml = await fs.readFile(yamlPath, "utf8");
+
+    logger.info(`Cache hit for prompt hash: ${hash}`);
+
+    return {
+      found: true,
+      hash,
+      yaml,
+      testName: entry.testName,
+      appId: entry.appId,
+      cachedAt: entry.cachedAt,
+      executionCount: entry.executionCount || 1,
+      lastUsed: entry.lastUsed,
+      originalPrompt: entry.prompt,
+    };
+  } catch (error) {
+    logger.error("Cache lookup error", { error: error.message });
+    return null;
+  }
+}
+
+/**
+ * Save YAML to cache
+ *
+ * @param {string} prompt - The original test prompt
+ * @param {string} yaml - The generated YAML content
+ * @param {string} testName - Name of the test
+ * @param {string} appId - App ID
+ * @returns {object} Save result
+ */
+export async function saveToCache(prompt, yaml, testName, appId = null) {
+  try {
+    await ensureCacheDir();
+
+    const hash = generatePromptHash(prompt, appId);
+    const yamlPath = join(CACHE_DIR, `${hash}.yaml`);
+
+    // Save YAML file
+    await fs.writeFile(yamlPath, yaml, "utf8");
+
+    // Update index
+    const index = await loadCacheIndex();
+    index[hash] = {
+      prompt: prompt.substring(0, 200), // Store truncated prompt for reference
+      testName,
+      appId,
+      cachedAt: new Date().toISOString(),
+      lastUsed: new Date().toISOString(),
+      executionCount: 1,
+    };
+    await saveCacheIndex(index);
+
+    logger.info(`Cached YAML for prompt hash: ${hash}`);
+
+    return {
+      success: true,
+      hash,
+      path: yamlPath,
+      message: `YAML cached successfully. Future executions of this prompt will use the cached version.`,
+    };
+  } catch (error) {
+    logger.error("Cache save error", { error: error.message });
+    return {
+      success: false,
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * Update cache usage statistics
+ */
+export async function updateCacheUsage(hash) {
+  try {
+    const index = await loadCacheIndex();
+
+    if (index[hash]) {
+      index[hash].lastUsed = new Date().toISOString();
+      index[hash].executionCount = (index[hash].executionCount || 0) + 1;
+      await saveCacheIndex(index);
+    }
+  } catch (error) {
+    logger.warn("Failed to update cache usage", { error: error.message });
+  }
+}
+
+/**
+ * Delete a cached entry
+ */
+export async function deleteFromCache(hash) {
+  try {
+    const index = await loadCacheIndex();
+
+    if (!index[hash]) {
+      return { success: false, error: "Cache entry not found" };
+    }
+
+    // Delete YAML file
+    const yamlPath = join(CACHE_DIR, `${hash}.yaml`);
+    try {
+      await fs.unlink(yamlPath);
+    } catch {
+      // File may not exist
+    }
+
+    // Remove from index
+    delete index[hash];
+    await saveCacheIndex(index);
+
+    return { success: true, message: "Cache entry deleted" };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Clear all cached entries
+ */
+export async function clearCache() {
+  try {
+    const index = await loadCacheIndex();
+    const count = Object.keys(index).length;
+
+    // Delete all YAML files
+    for (const hash of Object.keys(index)) {
+      const yamlPath = join(CACHE_DIR, `${hash}.yaml`);
+      try {
+        await fs.unlink(yamlPath);
+      } catch {
+        // Ignore
+      }
+    }
+
+    // Clear index
+    await saveCacheIndex({});
+
+    return {
+      success: true,
+      cleared: count,
+      message: `Cleared ${count} cached test(s)`,
+    };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * List all cached entries
+ */
+export async function listCache() {
+  try {
+    const index = await loadCacheIndex();
+
+    const entries = Object.entries(index).map(([hash, entry]) => ({
+      hash,
+      testName: entry.testName,
+      appId: entry.appId,
+      prompt: entry.prompt,
+      cachedAt: entry.cachedAt,
+      lastUsed: entry.lastUsed,
+      executionCount: entry.executionCount || 1,
+    }));
+
+    // Sort by last used (most recent first)
+    entries.sort((a, b) => new Date(b.lastUsed) - new Date(a.lastUsed));
+
+    return {
+      success: true,
+      count: entries.length,
+      cacheDir: CACHE_DIR,
+      entries,
+    };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Get cache statistics
+ */
+export async function getCacheStats() {
+  try {
+    const index = await loadCacheIndex();
+    const entries = Object.values(index);
+
+    const totalExecutions = entries.reduce(
+      (sum, e) => sum + (e.executionCount || 1),
+      0
+    );
+    const oldestEntry =
+      entries.length > 0
+        ? entries.reduce((oldest, e) =>
+            new Date(e.cachedAt) < new Date(oldest.cachedAt) ? e : oldest
+          )
+        : null;
+    const mostUsed =
+      entries.length > 0
+        ? entries.reduce((most, e) =>
+            (e.executionCount || 1) > (most.executionCount || 1) ? e : most
+          )
+        : null;
+
+    return {
+      success: true,
+      stats: {
+        totalCached: entries.length,
+        totalExecutions,
+        cacheDir: CACHE_DIR,
+        oldestEntry: oldestEntry
+          ? {
+              testName: oldestEntry.testName,
+              cachedAt: oldestEntry.cachedAt,
+            }
+          : null,
+        mostUsed: mostUsed
+          ? {
+              testName: mostUsed.testName,
+              executionCount: mostUsed.executionCount,
+            }
+          : null,
+      },
+    };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+/**
+ * Check if a prompt matches a cached entry exactly
+ * Returns comparison info for user decision
+ */
+export function promptMatchesCache(newPrompt, cachedPrompt) {
+  const normalizedNew = newPrompt.toLowerCase().trim().replace(/\s+/g, " ");
+  const normalizedCached = cachedPrompt
+    .toLowerCase()
+    .trim()
+    .replace(/\s+/g, " ");
+
+  if (normalizedNew === normalizedCached) {
+    return { exact: true, similarity: 100 };
+  }
+
+  // Calculate simple similarity
+  const words1 = new Set(normalizedNew.split(" "));
+  const words2 = new Set(normalizedCached.split(" "));
+  const intersection = [...words1].filter((w) => words2.has(w));
+  const union = new Set([...words1, ...words2]);
+  const similarity = Math.round((intersection.length / union.size) * 100);
+
+  return { exact: false, similarity };
+}
+
+export default {
+  generatePromptHash,
+  lookupCache,
+  saveToCache,
+  updateCacheUsage,
+  deleteFromCache,
+  clearCache,
+  listCache,
+  getCacheStats,
+  promptMatchesCache,
+};