mcp-maestro-mobile-ai 1.1.0 → 1.3.0

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

@@ -0,0 +1,390 @@
+/**
+ * Runtime Prerequisites Validation
+ * 
+ * This module validates prerequisites when the MCP server starts.
+ * Critical missing dependencies will prevent server startup.
+ */
+
+import { execSync } from "child_process";
+import path from "path";
+import { logger } from "./logger.js";
+
+/**
+ * Execute a command safely and return result
+ */
+function execCommand(command, options = {}) {
+  try {
+    return {
+      success: true,
+      output: execSync(command, {
+        encoding: "utf8",
+        timeout: options.timeout || 10000,
+        stdio: ["pipe", "pipe", "pipe"],
+        ...options,
+      }).trim(),
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * Parse version string to extract major version number
+ */
+function parseVersion(versionString) {
+  if (!versionString) return null;
+  const match = versionString.match(/(\d+)(?:\.(\d+))?/);
+  if (match) {
+    return {
+      major: parseInt(match[1], 10),
+      minor: match[2] ? parseInt(match[2], 10) : 0,
+    };
+  }
+  return null;
+}
+
+/**
+ * Check Node.js version (should always pass since we're running in Node)
+ */
+function checkNodeJs() {
+  const version = process.version;
+  const parsed = parseVersion(version);
+
+  if (!parsed || parsed.major < 18) {
+    return {
+      name: "Node.js",
+      status: "error",
+      installed: true,
+      version: version,
+      required: "18+",
+      message: `Node.js ${version} is outdated. Requires 18+.`,
+      hint: "Upgrade Node.js from https://nodejs.org/",
+    };
+  }
+
+  return {
+    name: "Node.js",
+    status: "ok",
+    installed: true,
+    version: version,
+    message: `Node.js ${version}`,
+  };
+}
+
+/**
+ * Check Java version
+ */
+function checkJava() {
+  // Try java --version first (Java 9+)
+  let result = execCommand("java --version");
+
+  // Fall back to java -version
+  if (!result.success) {
+    result = execCommand("java -version 2>&1");
+  }
+
+  if (!result.success) {
+    return {
+      name: "Java",
+      status: "error",
+      installed: false,
+      required: "17+",
+      message: "Java is not installed or not in PATH.",
+      hint: "Install Java 17+ from https://adoptium.net/",
+    };
+  }
+
+  // Parse version
+  const versionMatch = result.output.match(
+    /(?:java|openjdk)\s+(?:version\s+)?["']?(\d+)/i
+  );
+
+  if (versionMatch) {
+    const major = parseInt(versionMatch[1], 10);
+
+    if (major < 17) {
+      return {
+        name: "Java",
+        status: "error",
+        installed: true,
+        version: `${major}`,
+        required: "17+",
+        message: `Java ${major} is outdated. Requires 17+.`,
+        hint: "Upgrade to Java 17+ from https://adoptium.net/",
+      };
+    }
+
+    return {
+      name: "Java",
+      status: "ok",
+      installed: true,
+      version: `${major}`,
+      message: `Java ${major}`,
+    };
+  }
+
+  // Can't determine version but Java is installed
+  return {
+    name: "Java",
+    status: "warning",
+    installed: true,
+    version: "unknown",
+    message: "Java installed (version unknown)",
+  };
+}
+
+/**
+ * Check Maestro CLI
+ */
+function checkMaestro() {
+  const result = execCommand("maestro --version");
+
+  if (!result.success) {
+    return {
+      name: "Maestro CLI",
+      status: "error",
+      installed: false,
+      message: "Maestro CLI is not installed or not in PATH.",
+      hint: "Install Maestro: curl -Ls https://get.maestro.mobile.dev | bash",
+      hintWindows: "Install Maestro: iwr https://get.maestro.mobile.dev | iex",
+    };
+  }
+
+  return {
+    name: "Maestro CLI",
+    status: "ok",
+    installed: true,
+    version: result.output,
+    message: `Maestro ${result.output}`,
+  };
+}
+
+/**
+ * Check Android SDK / ADB
+ */
+function checkAndroidSdk() {
+  const androidHome = process.env.ANDROID_HOME;
+
+  if (!androidHome) {
+    return {
+      name: "Android SDK",
+      status: "warning",
+      installed: false,
+      message: "ANDROID_HOME environment variable is not set.",
+      hint: "Set ANDROID_HOME to your Android SDK path for reliable ADB access.",
+    };
+  }
+
+  // Check if ADB is accessible
+  const adbPath = path.join(androidHome, "platform-tools", "adb");
+  const result = execCommand(`"${adbPath}" --version`);
+
+  if (!result.success) {
+    // Try system PATH
+    const pathResult = execCommand("adb --version");
+    if (pathResult.success) {
+      return {
+        name: "Android SDK",
+        status: "ok",
+        installed: true,
+        message: `Android SDK (ADB available via PATH)`,
+      };
+    }
+
+    return {
+      name: "Android SDK",
+      status: "warning",
+      installed: true,
+      message: "ANDROID_HOME set but ADB not accessible.",
+      hint: "Ensure platform-tools is installed in Android SDK.",
+    };
+  }
+
+  return {
+    name: "Android SDK",
+    status: "ok",
+    installed: true,
+    path: androidHome,
+    message: `Android SDK configured`,
+  };
+}
+
+/**
+ * Check for connected device/emulator
+ */
+function checkDevice() {
+  const androidHome = process.env.ANDROID_HOME;
+  let adbCmd = "adb";
+
+  if (androidHome) {
+    adbCmd = `"${path.join(androidHome, "platform-tools", "adb")}"`;
+  }
+
+  const result = execCommand(`${adbCmd} devices`);
+
+  if (!result.success) {
+    return {
+      name: "Device/Emulator",
+      status: "warning",
+      connected: false,
+      message: "Could not check for connected devices.",
+      hint: "Ensure ADB is properly configured.",
+    };
+  }
+
+  // Parse device list
+  const lines = result.output.split("\n").filter((l) => l.trim());
+  const devices = lines
+    .slice(1)
+    .filter((l) => l.includes("device") && !l.includes("offline"))
+    .map((l) => l.split("\t")[0]);
+
+  if (devices.length === 0) {
+    return {
+      name: "Device/Emulator",
+      status: "warning",
+      connected: false,
+      message: "No Android device or emulator connected.",
+      hint: "Start an emulator or connect a device via USB.",
+    };
+  }
+
+  return {
+    name: "Device/Emulator",
+    status: "ok",
+    connected: true,
+    devices: devices,
+    message: `${devices.length} device(s) connected`,
+  };
+}
+
+/**
+ * Run all prerequisite checks
+ * @param {Object} options - Options
+ * @param {boolean} options.exitOnError - Exit process if critical error found
+ * @param {boolean} options.checkDevice - Also check for connected device
+ * @returns {Object} Results object
+ */
+export async function validatePrerequisites(options = {}) {
+  const { exitOnError = true, checkDevice: shouldCheckDevice = false } = options;
+
+  logger.info("Validating prerequisites...");
+
+  const checks = [
+    { fn: checkNodeJs, critical: true },
+    { fn: checkJava, critical: true },
+    { fn: checkMaestro, critical: true },
+    { fn: checkAndroidSdk, critical: false },
+  ];
+
+  if (shouldCheckDevice) {
+    checks.push({ fn: checkDevice, critical: false });
+  }
+
+  const results = [];
+  let hasErrors = false;
+  let hasWarnings = false;
+
+  for (const { fn, critical } of checks) {
+    const result = fn();
+    results.push({ ...result, critical });
+
+    if (result.status === "error") {
+      if (critical) {
+        hasErrors = true;
+        logger.error(`❌ ${result.name}: ${result.message}`);
+      } else {
+        hasWarnings = true;
+        logger.warn(`⚠️ ${result.name}: ${result.message}`);
+      }
+    } else if (result.status === "warning") {
+      hasWarnings = true;
+      logger.warn(`⚠️ ${result.name}: ${result.message}`);
+    } else {
+      logger.info(`✅ ${result.name}: ${result.message}`);
+    }
+  }
+
+  // Collect hints for failed checks
+  const hints = results
+    .filter((r) => r.hint && (r.status === "error" || r.status === "warning"))
+    .map((r) => {
+      // Use Windows hint if available and on Windows
+      if (process.platform === "win32" && r.hintWindows) {
+        return r.hintWindows;
+      }
+      return r.hint;
+    });
+
+  if (hints.length > 0) {
+    logger.info("");
+    logger.info("💡 To fix issues:");
+    hints.forEach((hint) => {
+      logger.info(`   → ${hint}`);
+    });
+  }
+
+  // Handle critical errors
+  if (hasErrors && exitOnError) {
+    logger.error("");
+    logger.error("═══════════════════════════════════════════════════════");
+    logger.error("  CRITICAL: Required prerequisites are missing.");
+    logger.error("  The MCP server cannot start without them.");
+    logger.error("═══════════════════════════════════════════════════════");
+    logger.error("");
+    process.exit(2); // Exit code 2 for infrastructure errors
+  }
+
+  return {
+    success: !hasErrors,
+    hasWarnings,
+    results,
+    hints,
+  };
+}
+
+/**
+ * Quick check for critical prerequisites only
+ * Used for fast startup validation
+ */
+export function quickCheck() {
+  const java = checkJava();
+  const maestro = checkMaestro();
+
+  const errors = [];
+  
+  if (java.status === "error") {
+    errors.push({
+      name: "Java",
+      message: java.message,
+      hint: java.hint,
+    });
+  }
+
+  if (maestro.status === "error") {
+    errors.push({
+      name: "Maestro CLI",
+      message: maestro.message,
+      hint: process.platform === "win32" ? maestro.hintWindows : maestro.hint,
+    });
+  }
+
+  return {
+    success: errors.length === 0,
+    errors,
+  };
+}
+
+export default {
+  validatePrerequisites,
+  quickCheck,
+  checkNodeJs,
+  checkJava,
+  checkMaestro,
+  checkAndroidSdk,
+  checkDevice,
+};
+