@fenwave/agent 1.1.0

package/docker-actions/apps.js

@@ -0,0 +1,3256 @@
+import { docker } from "./containers.js";
+import fs from "fs";
+import path, { dirname } from "path";
+import os from "os";
+import yaml from "js-yaml";
+import { exec } from "child_process";
+import axios from "axios";
+import chalk from "chalk";
+import { loadSession } from "../auth.js";
+import { loadConfig } from "../store/configStore.js";
+import { fileURLToPath } from "url";
+import {
+  toDockerComposeConfig,
+  generateHostEnvScript,
+  generateEnvFile,
+  generateComposeDeploy,
+} from "./config-transformer.js";
+
+// ES Module equivalent of __dirname
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Load configuration
+const config = loadConfig();
+const APP_BUILDER_URL = config.appBuilderUrl;
+const BACKEND_URL = config.backendUrl;
+
+// Fenwave workspace configuration paths
+const FENWAVE_CONFIG_DIR = path.join(os.homedir(), ".fenwave", "config");
+const WORKSPACE_REGISTRY_PATH = path.join(
+  FENWAVE_CONFIG_DIR,
+  "workspaces.json"
+);
+
+/**
+ * Workspace metadata management
+ */
+
+// Ensure Fenwave config directory exists
+function ensureFenwaveConfigDir() {
+  if (!fs.existsSync(FENWAVE_CONFIG_DIR)) {
+    fs.mkdirSync(FENWAVE_CONFIG_DIR, { recursive: true });
+  }
+}
+
+// Load workspace registry (maps appId -> workspace path)
+function loadWorkspaceRegistry() {
+  ensureFenwaveConfigDir();
+  if (!fs.existsSync(WORKSPACE_REGISTRY_PATH)) {
+    return {};
+  }
+  try {
+    const data = fs.readFileSync(WORKSPACE_REGISTRY_PATH, "utf8");
+    return JSON.parse(data);
+  } catch (error) {
+    console.warn("⚠️  Failed to load workspace registry:", error.message);
+    return {};
+  }
+}
+
+// Save workspace registry
+function saveWorkspaceRegistry(registry) {
+  ensureFenwaveConfigDir();
+  try {
+    fs.writeFileSync(
+      WORKSPACE_REGISTRY_PATH,
+      JSON.stringify(registry, null, 2),
+      "utf8"
+    );
+  } catch (error) {
+    console.error("❌ Failed to save workspace registry:", error.message);
+  }
+}
+
+// Register a workspace for an app version
+function registerWorkspace(appId, appName, appVersion, workspacePath) {
+  const registry = loadWorkspaceRegistry();
+  const registryKey = `${appId}-${appVersion}`;
+  registry[registryKey] = {
+    appId,
+    appName,
+    appVersion,
+    workspacePath,
+    registeredAt: new Date().toISOString(),
+  };
+  saveWorkspaceRegistry(registry);
+}
+
+// Unregister a workspace for an app version
+function unregisterWorkspace(appId, appVersion) {
+  const registry = loadWorkspaceRegistry();
+  const registryKey = `${appId}-${appVersion}`;
+  if (registry[registryKey]) {
+    delete registry[registryKey];
+    saveWorkspaceRegistry(registry);
+    return true;
+  }
+  return false;
+}
+
+// Get registered workspace path for an app version
+function getRegisteredWorkspace(appId, appVersion) {
+  const registry = loadWorkspaceRegistry();
+  const registryKey = `${appId}-${appVersion}`;
+  return registry[registryKey] || null;
+}
+
+// Delete workspace folder recursively
+function deleteWorkspaceFolder(workspacePath) {
+  if (workspacePath && fs.existsSync(workspacePath)) {
+    try {
+      fs.rmSync(workspacePath, { recursive: true, force: true });
+      console.log(`🗑️  Deleted workspace folder: ${workspacePath}`);
+      return true;
+    } catch (error) {
+      console.warn(`⚠️  Failed to delete workspace folder: ${error.message}`);
+      return false;
+    }
+  }
+  return false;
+}
+
+// Create workspace metadata file
+function createWorkspaceMetadata(workspacePath, appId, appName) {
+  const fenwaveDir = path.join(workspacePath, ".fenwave");
+  if (!fs.existsSync(fenwaveDir)) {
+    fs.mkdirSync(fenwaveDir, { recursive: true });
+  }
+
+  const metadata = {
+    appId,
+    appName,
+    createdAt: new Date().toISOString(),
+    lastSyncedAt: new Date().toISOString(),
+  };
+
+  const metadataPath = path.join(fenwaveDir, "workspace.json");
+  fs.writeFileSync(metadataPath, JSON.stringify(metadata, null, 2), "utf8");
+}
+
+// Update workspace metadata (e.g., after sync)
+function updateWorkspaceMetadata(workspacePath) {
+  const metadataPath = path.join(workspacePath, ".fenwave", "workspace.json");
+
+  if (!fs.existsSync(metadataPath)) {
+    return;
+  }
+
+  try {
+    const metadata = JSON.parse(fs.readFileSync(metadataPath, "utf8"));
+    metadata.lastSyncedAt = new Date().toISOString();
+    fs.writeFileSync(metadataPath, JSON.stringify(metadata, null, 2), "utf8");
+  } catch (error) {
+    console.warn("⚠️  Failed to update workspace metadata:", error.message);
+  }
+}
+
+// Verify workspace is valid (has .fenwave/workspace.json)
+function isValidWorkspace(workspacePath) {
+  const metadataPath = path.join(workspacePath, ".fenwave", "workspace.json");
+  return fs.existsSync(metadataPath);
+}
+
+// Resolve workspace path for each app version
+function resolveWorkspacePath(appId, appName, appVersion, context = "default") {
+  // Check if workspace is registered
+  const registered = getRegisteredWorkspace(appId, appVersion);
+
+  if (registered) {
+    // Verify the registered path is still valid
+    if (isValidWorkspace(registered.workspacePath)) {
+      return registered.workspacePath;
+    } else {
+      if (context === "delete") {
+        console.warn(
+          `⚠️  Registered workspace not found at ${registered.workspacePath}, skipping workspace deletion...`
+        );
+      } else if (context !== "sync") {
+        console.warn(
+          `⚠️  Registered workspace not found at ${registered.workspacePath}, will recreate...`
+        );
+      }
+    }
+  }
+
+  // Create new workspace in ~/.fenwave/docker/
+  const fenwaveDockerDir = path.join(os.homedir(), ".fenwave", "docker");
+  const normalizedAppName = appName.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+  const newWorkspacePath = path.join(
+    fenwaveDockerDir,
+    `${normalizedAppName}-${appVersion}`
+  );
+
+  return newWorkspacePath;
+}
+
+// Resolve workspace path for draft apps (no version suffix)
+function resolveWorkspacePathForDraft(appId, appName, context = "default") {
+  // Check if workspace is registered for draft (using "draft" as version key)
+  const registered = getRegisteredWorkspace(appId, "draft");
+
+  if (registered) {
+    // Verify the registered path is still valid
+    if (isValidWorkspace(registered.workspacePath)) {
+      return registered.workspacePath;
+    } else {
+      if (context === "delete") {
+        console.warn(
+          `⚠️  Registered workspace not found at ${registered.workspacePath}, skipping workspace deletion...`
+        );
+      } else if (context !== "sync") {
+        console.warn(
+          `⚠️  Registered workspace not found at ${registered.workspacePath}, will recreate...`
+        );
+      }
+    }
+  }
+
+  // Create new workspace in ~/.fenwave/docker/ without version suffix
+  const fenwaveDockerDir = path.join(os.homedir(), ".fenwave", "docker");
+  const normalizedAppName = appName.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+  const newWorkspacePath = path.join(fenwaveDockerDir, normalizedAppName);
+
+  return newWorkspacePath;
+}
+
+// Backup existing docker-compose.yml before sync
+function backupDockerCompose(workspacePath) {
+  const dockerComposePath = path.join(workspacePath, "docker-compose.yml");
+  const backupPath = path.join(workspacePath, "docker-compose.backup.yml");
+
+  if (fs.existsSync(dockerComposePath)) {
+    try {
+      fs.copyFileSync(dockerComposePath, backupPath);
+      console.log(`📦 Backed up existing docker-compose.yml`);
+      return true;
+    } catch (error) {
+      console.warn("⚠️  Failed to backup docker-compose.yml:", error.message);
+      return false;
+    }
+  }
+  return false;
+}
+
+/**
+ * Check if an app has ever been run locally (has containers created)
+ * @param {string} appName - The app name to check
+ * @returns {Promise<boolean>} - True if the app has been run at least once
+ */
+async function checkAppHasBeenRun(appName) {
+  if (!appName) {
+    return false;
+  }
+
+  try {
+    // Normalize app name to match Docker container naming convention
+    const normalizedAppName = appName
+      .replace(/[^a-z0-9-]/gi, "-")
+      .toLowerCase();
+
+    const containers = await docker.listContainers({ all: true });
+    const appContainers = containers.filter((container) => {
+      const containerName = container.Names[0].replace(/^\//, "");
+      return (
+        containerName.startsWith(normalizedAppName) ||
+        container.Labels["com.docker.compose.project"] === normalizedAppName ||
+        container.Labels["app"] === normalizedAppName
+      );
+    });
+
+    return appContainers.length > 0;
+  } catch (error) {
+    // If we can't check containers, assume the app has been run
+    // to avoid missing important update notifications
+    console.warn(
+      `⚠️  Failed to check containers for app ${appName}: ${error.message}`
+    );
+    return true;
+  }
+}
+
+/**
+ * Acknowledge an event after processing (e.g., after syncing)
+ */
+async function acknowledgeEvent(eventId, changeId) {
+  try {
+    const session = loadSession();
+    if (!session || !session.token) {
+      console.warn("⚠️  No session token available to acknowledge event");
+      return false;
+    }
+
+    const response = await axios.post(
+      `${BACKEND_URL}/api/agent-cli/acknowledge-event`,
+      {
+        token: session.token,
+        eventId,
+        changeId,
+      },
+      {
+        headers: {
+          "Content-Type": "application/json",
+        },
+        timeout: 5000,
+      }
+    );
+
+    if (response.data && response.data.success) {
+      return true;
+    }
+
+    return false;
+  } catch (error) {
+    console.warn(`⚠️  Failed to acknowledge event: ${error.message}`);
+    return false;
+  }
+}
+
+async function handleAppAction(ws, action, payload) {
+  switch (action) {
+    case "fetchApps":
+      return await handleFetchApps(ws, payload);
+    case "fetchAppVersions":
+      return await handleFetchAppVersions(ws, payload);
+    case "startApp":
+      return await handleStartApp(ws, payload);
+    case "stopApp":
+      return await handleStopApp(ws, payload);
+    case "restartApp":
+      return await handleRestartApp(ws, payload);
+    case "deleteApp":
+      return await handleDeleteApp(ws, payload);
+    case "deleteAppVersions":
+      return await handleDeleteAppVersions(ws, payload);
+    case "createApp":
+      return await handleCreateApp(ws, payload);
+    case "validateCompose":
+      return await handleValidateCompose(ws, payload);
+    case "syncApp":
+      return await handleSyncApp(ws, payload);
+    case "changeVersion":
+      return await handleChangeVersion(ws, payload);
+    default:
+      throw new Error(`Unknown app action: ${action}`);
+  }
+}
+
+// Fetch published applications from Backstage app-builder
+async function fetchBackstageApps(userEntityRef) {
+  if (!APP_BUILDER_URL) {
+    console.warn("APP_BUILDER_URL not configured, skipping Backstage apps");
+    return [];
+  }
+
+  try {
+    // Load session token for authentication
+    const session = loadSession();
+    if (!session || !session.token) {
+      console.warn(
+        "No valid session found, skipping Backstage apps. Please run: fenwave login"
+      );
+      return [];
+    }
+
+    const url = `${APP_BUILDER_URL}/api/app-builder/applications`;
+
+    // Fetch both published apps and user's drafts
+    const [publishedResponse, draftResponse] = await Promise.all([
+      // Fetch all published apps
+      axios
+        .get(url, {
+          params: { status: "published" },
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${session.token}`,
+          },
+          timeout: 10000,
+        })
+        .catch((err) => {
+          const isConnRefused =
+            (err.message && err.message.includes("ECONNREFUSED")) ||
+            err.code === "ECONNREFUSED";
+
+          if (isConnRefused) {
+            console.error(
+              chalk.red(
+                "❌ Failed to fetch published apps: Please ensure backstage is running."
+              )
+            );
+          } else {
+            console.error(
+              chalk.red("❌ Failed to fetch published apps:", err.message)
+            );
+          }
+
+          return { data: [] };
+        }),
+      // Fetch user's draft apps
+      axios
+        .get(url, {
+          params: {
+            status: "draft",
+            created_by: userEntityRef,
+          },
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${session.token}`,
+          },
+          timeout: 10000,
+        })
+        .catch((err) => {
+          const isConnRefused =
+            (err.message && err.message.includes("ECONNREFUSED")) ||
+            err.code === "ECONNREFUSED";
+
+          if (isConnRefused) {
+            console.error(
+              chalk.red(
+                "❌ Failed to fetch draft apps: Please ensure backstage is running."
+              )
+            );
+          } else {
+            console.error(
+              chalk.red("❌ Failed to fetch draft apps:", err.message)
+            );
+          }
+
+          return { data: [] };
+        }),
+    ]);
+
+    const publishedApps = publishedResponse.data || [];
+    const draftApps = draftResponse.data || [];
+    const allApps = [...publishedApps, ...draftApps];
+
+    // Transform Backstage apps to local app format (now async to check container status)
+    return await Promise.all(allApps.map((app) => transformBackstageApp(app)));
+  } catch (error) {
+    console.error("Failed to fetch Backstage apps:", error.message);
+    return [];
+  }
+}
+
+// Transform Backstage app to local app format
+async function transformBackstageApp(backstageApp) {
+  // Fetch all versions for this app
+  const session = loadSession();
+  let allVersions = [];
+
+  if (session && session.token && APP_BUILDER_URL) {
+    try {
+      const versionsResponse = await axios.get(
+        `${APP_BUILDER_URL}/api/app-builder/applications/${backstageApp.id}/versions`,
+        {
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${session.token}`,
+          },
+          timeout: 10000,
+        }
+      );
+      allVersions = versionsResponse.data || [];
+    } catch (err) {
+      console.error(
+        `Failed to fetch versions for app ${backstageApp.id}:`,
+        err.message
+      );
+    }
+  }
+
+  // If no versions found, use activeVersion from app
+  if (allVersions.length === 0 && backstageApp.activeVersion) {
+    allVersions = [backstageApp.activeVersion];
+  }
+
+  // Check if there are running Docker containers for this app
+  const appName = backstageApp.name.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+
+  // Get container info to determine which version is running (or: has ran) locally
+  let containers = [];
+  let runningVersion = null; // Track which version is actually running
+
+  try {
+    containers = await docker.listContainers({ all: true });
+    containers = containers.filter((container) => {
+      const containerName = container.Names[0].replace(/^\//, "");
+      return (
+        containerName.startsWith(appName) ||
+        container.Labels["com.docker.compose.project"] === appName ||
+        container.Labels["app"] === appName
+      );
+    });
+
+    // Try to determine the running version (or: that has ran) from container labels
+    if (containers.length > 0) {
+      // Check the first container for version label
+      const versionLabel = containers[0].Labels["app.version"];
+      if (versionLabel) {
+        runningVersion = versionLabel;
+      }
+    }
+  } catch (error) {
+    console.error(
+      `Error checking containers for app ${appName}:`,
+      error.message
+    );
+  }
+
+  const containerCount = containers.length;
+  const hasRunningContainer = containers.some((c) => c.State === "running");
+  const appStatus = hasRunningContainer
+    ? "running"
+    : containerCount > 0
+    ? "stopped"
+    : "stopped";
+
+  // Calculate firstRun and lastRun times for containers
+  let firstRunTime = "Never";
+  let lastRunTime = "Never";
+
+  if (containers.length > 0) {
+    const creationTimestamps = containers.map((c) =>
+      new Date(c.Created * 1000).getTime()
+    );
+    const oldestCreationTimestamp = Math.min(...creationTimestamps);
+
+    const startTimestamps = [];
+    for (const container of containers) {
+      try {
+        const containerInfo = await docker.getContainer(container.Id).inspect();
+        if (containerInfo.State.StartedAt) {
+          startTimestamps.push(
+            new Date(containerInfo.State.StartedAt).getTime()
+          );
+        }
+      } catch (err) {
+        startTimestamps.push(new Date(container.Created * 1000).getTime());
+      }
+    }
+
+    const mostRecentStartTimestamp = Math.max(...startTimestamps);
+    const now = Date.now();
+
+    // Calculate firstRun
+    const firstDiff = now - oldestCreationTimestamp;
+    const firstMinutes = Math.floor(firstDiff / (1000 * 60));
+    const firstHours = Math.floor(firstMinutes / 60);
+    const firstDays = Math.floor(firstHours / 24);
+
+    if (firstDays > 0)
+      firstRunTime = `${firstDays} day${firstDays > 1 ? "s" : ""} ago`;
+    else if (firstHours > 0)
+      firstRunTime = `${firstHours} hour${firstHours > 1 ? "s" : ""} ago`;
+    else if (firstMinutes > 0)
+      firstRunTime = `${firstMinutes} minute${firstMinutes > 1 ? "s" : ""} ago`;
+    else firstRunTime = "Just now";
+
+    // Calculate lastRun
+    const lastDiff = now - mostRecentStartTimestamp;
+    const lastMinutes = Math.floor(lastDiff / (1000 * 60));
+    const lastHours = Math.floor(lastMinutes / 60);
+    const lastDays = Math.floor(lastHours / 24);
+
+    if (lastDays > 0)
+      lastRunTime = `${lastDays} day${lastDays > 1 ? "s" : ""} ago`;
+    else if (lastHours > 0)
+      lastRunTime = `${lastHours} hour${lastHours > 1 ? "s" : ""} ago`;
+    else if (lastMinutes > 0)
+      lastRunTime = `${lastMinutes} minute${lastMinutes > 1 ? "s" : ""} ago`;
+    else lastRunTime = "Just now";
+  }
+
+  // Transform all versions to include local run status
+  const transformedVersions = allVersions.map((version) => {
+    const nodes = version.nodes || [];
+    const componentTypes = nodes.map((n) => n?.data?.type).filter(Boolean);
+    const language = componentTypes[0] || "Unknown";
+
+    // Check if THIS specific version is the one running (or: that has ran) locally
+    const isThisVersionRunning =
+      runningVersion && version.version === runningVersion;
+    const versionHasRun = isThisVersionRunning && containerCount > 0;
+
+    return {
+      id: version.id,
+      version: version.version || "1.0.0",
+      status: version.status, // draft, published, or archived
+      description:
+        version.description ||
+        backstageApp.description ||
+        "Backstage application",
+      nodes: nodes,
+      edges: version.edges || [],
+      tags: version.tags || [],
+      language: language,
+      created_at: version.created_at,
+      created_by: version.created_by,
+      // Mark if THIS SPECIFIC version has ran locally
+      hasRanLocally: versionHasRun,
+      containers: versionHasRun ? containerCount : 0,
+      firstRun: versionHasRun ? firstRunTime : "Never",
+      lastRun: versionHasRun ? lastRunTime : "Never",
+      appStatus: versionHasRun ? appStatus : "stopped",
+    };
+  });
+
+  // Get the active published version
+  const activeVersion =
+    allVersions.find((v) => v.status === "published") || allVersions[0] || {};
+  const nodes = activeVersion.nodes || [];
+  const componentTypes = nodes.map((n) => n?.data?.type).filter(Boolean);
+  const language = componentTypes[0] || "Unknown";
+
+  return {
+    id: `backstage-${backstageApp.id}`,
+    name: backstageApp.name,
+    description:
+      backstageApp.description ||
+      activeVersion.description ||
+      "Backstage application",
+    language: language,
+    status: appStatus,
+    containers: containerCount,
+    firstRun: firstRunTime,
+    lastRun: lastRunTime,
+    url: "N/A", // Will be set after running
+    repo: backstageApp.metadata?.repo || "N/A",
+    icon: backstageApp.name.substring(0, 1).toUpperCase(),
+    source: "backstage",
+    backstageId: backstageApp.id,
+    backstageStatus: activeVersion.status || backstageApp.status,
+    version: activeVersion.version || "1.0.0",
+    tags: activeVersion.tags || [],
+    nodes: nodes,
+    edges: activeVersion.edges || [],
+    createdBy: backstageApp.created_by,
+    publishedAt: backstageApp.published_at,
+    publishedBy: backstageApp.published_by,
+    versions: transformedVersions,
+  };
+}
+
+// Helper function to find apps (Backstage only)
+async function findApps(userEntityRef) {
+  try {
+    // Only fetch Backstage apps (no local Docker containers)
+    const backstageApps = await fetchBackstageApps(userEntityRef);
+
+    return backstageApps;
+  } catch (error) {
+    console.error("Error finding apps:", error);
+    return [];
+  }
+}
+
+// Find Docker Compose apps
+async function findComposeApps() {
+  try {
+    // This is a placeholder. In a real implementation, you would scan for
+    // docker-compose.yml files in the user's projects directory
+    return [];
+  } catch (error) {
+    console.error("Error finding compose apps:", error);
+    return [];
+  }
+}
+
+// Group containers into apps based on labels or networks
+async function groupContainersIntoApps() {
+  try {
+    const containers = await docker.listContainers({ all: true });
+    const apps = {};
+
+    const detectLanguage = (image) => {
+      const imageLower = image.toLowerCase();
+
+      if (imageLower.includes("node") || imageLower.includes("javascript"))
+        return "JavaScript";
+      if (imageLower.includes("python")) return "Python";
+      if (imageLower.includes("ruby")) return "Ruby";
+      if (imageLower.includes("php")) return "PHP";
+      if (imageLower.includes("java")) return "Java";
+      if (imageLower.includes("go")) return "Go";
+      if (imageLower.includes("rust")) return "Rust";
+      if (imageLower.includes("dotnet") || imageLower.includes("csharp"))
+        return "C#";
+
+      return "Unknown";
+    };
+
+    const formatRelativeTime = (timestamp) => {
+      const now = Date.now();
+      const diff = now - timestamp;
+
+      const minutes = Math.floor(diff / (1000 * 60));
+      const hours = Math.floor(minutes / 60);
+      const days = Math.floor(hours / 24);
+      const weeks = Math.floor(days / 7);
+
+      if (weeks > 0) return `${weeks} week${weeks > 1 ? "s" : ""} ago`;
+      if (days > 0) return `${days} day${days > 1 ? "s" : ""} ago`;
+      if (hours > 0) return `${hours} hour${hours > 1 ? "s" : ""} ago`;
+      if (minutes > 0) return `${minutes} minute${minutes > 1 ? "s" : ""} ago`;
+      return "Just now";
+    };
+
+    // Group by common labels or networks
+    for (const container of containers) {
+      const appName =
+        container.Labels["com.docker.compose.project"] ||
+        container.Labels["app"] ||
+        container.Names[0].replace(/^\//, "").split("_")[0];
+
+      if (!appName) continue;
+
+      // Create or update app
+      if (!apps[appName]) {
+        const containerInfo = await docker.getContainer(container.Id).inspect();
+        const image = containerInfo.Config.Image;
+        const createdTime = new Date(containerInfo.Created).getTime();
+
+        // Use StartedAt for lastRun if available, otherwise fall back to Created
+        const startedAt = containerInfo.State.StartedAt
+          ? new Date(containerInfo.State.StartedAt).getTime()
+          : createdTime;
+
+        apps[appName] = {
+          id: `app-${appName}`,
+          name: appName,
+          description: `Application using ${image}`,
+          language: detectLanguage(image),
+          status: containerInfo.State.Running ? "running" : "stopped",
+          containers: 1,
+          firstRun: formatRelativeTime(createdTime),
+          lastRun: formatRelativeTime(startedAt),
+          oldestCreationTime: createdTime, // Track oldest creation for firstRun
+          newestStartTime: startedAt, // Track most recent start for lastRun
+          url: `http://localhost:${
+            containerInfo.NetworkSettings.Ports
+              ? Object.keys(containerInfo.NetworkSettings.Ports)[0]?.split(
+                  "/"
+                )[0]
+              : "8080"
+          }`,
+          repo: container.Labels["repo"] || "local",
+          icon: appName.substring(0, 1).toUpperCase(),
+        };
+      } else {
+        // Update app with additional container
+        apps[appName].containers += 1;
+
+        // Update status if any container is running
+        const containerInfo = await docker.getContainer(container.Id).inspect();
+        if (containerInfo.State.Running) {
+          apps[appName].status = "running";
+        }
+
+        // Track oldest creation time and newest start time
+        const createdTime = new Date(containerInfo.Created).getTime();
+        const startedAt = containerInfo.State.StartedAt
+          ? new Date(containerInfo.State.StartedAt).getTime()
+          : createdTime;
+
+        // Update firstRun if this container was created earlier
+        if (createdTime < apps[appName].oldestCreationTime) {
+          apps[appName].oldestCreationTime = createdTime;
+          apps[appName].firstRun = formatRelativeTime(createdTime);
+        }
+
+        // Update lastRun if this container was started more recently
+        if (startedAt > apps[appName].newestStartTime) {
+          apps[appName].newestStartTime = startedAt;
+          apps[appName].lastRun = formatRelativeTime(startedAt);
+        }
+      }
+    }
+
+    // Clean up temporary tracking fields before returning
+    const cleanedApps = Object.values(apps).map((app) => {
+      const { oldestCreationTime, newestStartTime, ...cleanApp } = app;
+      return cleanApp;
+    });
+
+    return cleanedApps;
+  } catch (error) {
+    console.error("Error grouping containers into apps:", error);
+    return [];
+  }
+}
+
+async function handleFetchApps(ws, payload = {}) {
+  try {
+    // Extract user context from payload (passed from frontend)
+    const userEntityRef = payload.userEntityRef || null;
+
+    // Fetch apps (local + Backstage)
+    const apps = await findApps(userEntityRef);
+
+    ws.send(
+      JSON.stringify({
+        type: "apps",
+        apps,
+        requestId: payload.requestId,
+      })
+    );
+  } catch (error) {
+    console.error("Error fetching apps:", error);
+    ws.send(
+      JSON.stringify({
+        type: "error",
+        error: "Failed to fetch apps: " + error.message,
+        requestId: payload.requestId,
+      })
+    );
+  }
+}
+
+async function handleFetchAppVersions(ws, payload) {
+  try {
+    const { backstageId, requestId } = payload;
+
+    if (!backstageId) {
+      throw new Error("backstageId is required");
+    }
+
+    if (!APP_BUILDER_URL) {
+      throw new Error("APP_BUILDER_URL not configured");
+    }
+
+    // Load session token for authentication
+    const session = loadSession();
+    if (!session || !session.token) {
+      throw new Error("No valid session found. Please run: fenwave login");
+    }
+
+    // Fetch app info to get the name for container matching
+    const appUrl = `${APP_BUILDER_URL}/api/app-builder/applications/${backstageId}`;
+    const appResponse = await axios.get(appUrl, {
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${session.token}`,
+      },
+      timeout: 10000,
+    });
+    const appData = appResponse.data;
+    const appName = appData.name.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+
+    // Check for existing containers to determine running version
+    let runningVersion = null;
+    let containers = [];
+    try {
+      containers = await docker.listContainers({ all: true });
+      containers = containers.filter((container) => {
+        const containerName = container.Names[0].replace(/^\//, "");
+        return (
+          containerName.startsWith(appName) ||
+          container.Labels["com.docker.compose.project"] === appName ||
+          container.Labels["app"] === appName
+        );
+      });
+      if (containers.length > 0 && containers[0].Labels["app.version"]) {
+        runningVersion = containers[0].Labels["app.version"];
+      }
+    } catch (err) {
+      console.warn("Error checking containers:", err.message);
+    }
+
+    const url = `${APP_BUILDER_URL}/api/app-builder/applications/${backstageId}/versions`;
+    const response = await axios.get(url, {
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${session.token}`,
+      },
+      timeout: 10000,
+    });
+
+    const rawVersions = response.data || [];
+
+    // Enrich versions with local run status
+    const versions = rawVersions.map((version) => {
+      const isThisVersionRunning =
+        runningVersion && version.version === runningVersion;
+      const versionHasRun = isThisVersionRunning && containers.length > 0;
+
+      return {
+        ...version,
+        hasRanLocally: versionHasRun,
+        containers: versionHasRun ? containers.length : 0,
+        firstRun: versionHasRun ? "Yes" : "Never",
+        lastRun: versionHasRun ? "Yes" : "Never",
+        appStatus: versionHasRun
+          ? containers.some((c) => c.State === "running")
+            ? "running"
+            : "stopped"
+          : "stopped",
+      };
+    });
+
+    ws.send(
+      JSON.stringify({
+        type: "appVersions",
+        versions,
+        appId: backstageId,
+        requestId,
+      })
+    );
+  } catch (error) {
+    console.error("Error fetching app versions:", error);
+    ws.send(
+      JSON.stringify({
+        type: "error",
+        error: "Failed to fetch app versions: " + error.message,
+        requestId: payload.requestId,
+      })
+    );
+  }
+}
+
+async function handleStartApp(ws, payload) {
+  try {
+    const { id, yamlContent, requestId } = payload;
+
+    // Extract user context from payload
+    const userEntityRef = payload.userEntityRef || null;
+
+    // Case 1: Called from App Builder with yamlContent
+    if (yamlContent && !id) {
+      // Parse YAML and extract application name safely
+      const appDefinition = yaml.load(yamlContent);
+      const appNameRaw =
+        appDefinition?.application?.name ?? appDefinition?.name;
+
+      if (!appNameRaw || typeof appNameRaw !== "string") {
+        throw new Error("Application name not found or invalid in YAML");
+      }
+
+      const appName = appNameRaw.trim();
+      const normalizedAppName = appName
+        .replace(/[^a-z0-9-]/gi, "-")
+        .toLowerCase();
+
+      // Find the app in Backstage
+      const apps = await findApps(userEntityRef);
+      const app = apps.find(
+        (a) =>
+          a.name === appName ||
+          a.name.replace(/[^a-z0-9-]/gi, "-").toLowerCase() ===
+            normalizedAppName
+      );
+
+      if (app) {
+        // Check if containers exist for this app
+        const containers = await docker.listContainers({ all: true });
+        const appContainers = containers.filter((container) => {
+          const containerName = container.Names[0].replace(/^\//, "");
+          const projectLabel = container.Labels["com.docker.compose.project"];
+
+          return (
+            containerName.startsWith(normalizedAppName) ||
+            projectLabel === normalizedAppName ||
+            container.Labels["app"] === normalizedAppName
+          );
+        });
+
+        // If containers exist, handle start or report already running
+        if (appContainers.length > 0) {
+          const hasRunningContainer = appContainers.some(
+            (c) => c.State === "running"
+          );
+
+          if (hasRunningContainer) {
+            console.log(
+              `⚠️  App "${appName}" is already running. Use the DevApp to manage it.`
+            );
+
+            ws.send(
+              JSON.stringify({
+                type: "error",
+                error: "Application is already running",
+                message: `App "${appName}" is already running. Use the DevApp to manage it.`,
+                isWarning: true,
+                requestId,
+              })
+            );
+            return;
+          }
+
+          // Unified start log
+          const isDraft = app.backstageStatus === "draft";
+
+          if (isDraft) {
+            console.log(`🚀 Running draft "${app.name}"...`);
+          } else {
+            console.log(
+              `🚀 Running application "${app.name} (${app.version})"...`
+            );
+          }
+
+          // Start any stopped containers
+          for (const container of appContainers) {
+            if (container.State !== "running") {
+              await docker.getContainer(container.Id).start();
+            }
+          }
+
+          if (isDraft) {
+            console.log(`✅ Draft "${app.name}" ran successfully!`);
+          } else {
+            console.log(
+              `✅ Application "${app.name} (${app.version})" ran successfully!`
+            );
+          }
+
+          ws.send(
+            JSON.stringify({
+              type: "runCompleted",
+              app: {
+                ...app,
+                status: "running",
+                containers: appContainers.length,
+              },
+              requestId,
+            })
+          );
+          return;
+        }
+
+        // No containers exist - run the app for the first time
+        await runBackstageApp(ws, app, yamlContent, requestId);
+        return;
+      }
+
+      // App not found in Backstage - run as a new YAML-based app
+      const newApp = {
+        id: `app-${Date.now()}`,
+        name: appName,
+        backstageId: null,
+        source: "yaml",
+      };
+
+      await runBackstageApp(ws, newApp, yamlContent, requestId);
+      return;
+    }
+
+    // Case 2: Called from local app list with id
+    if (!id) {
+      throw new Error("Either id or yamlContent is required");
+    }
+
+    // Find the app
+    const apps = await findApps(userEntityRef);
+    const app = apps.find((a) => a.id === id);
+
+    if (!app) {
+      throw new Error("App not found");
+    }
+
+    // Normalize app name for container matching
+    const appName = app.name.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+
+    // Find containers belonging to this app
+    const containers = await docker.listContainers({ all: true });
+    const appContainers = containers.filter((container) => {
+      const containerName = container.Names[0].replace(/^\//, "");
+      const projectLabel = container.Labels["com.docker.compose.project"];
+
+      return (
+        containerName.startsWith(appName) ||
+        projectLabel === appName ||
+        container.Labels["app"] === appName
+      );
+    });
+
+    // If containers exist, just start them (don't re-run)
+    if (appContainers.length > 0) {
+      // Get version from container labels (the actual running version)
+      const runningVersion =
+        appContainers[0].Labels["app.version"] || app.version || "1.0.0";
+      const isDraft = app.backstageStatus === "draft";
+
+      // Log with appropriate format for draft vs published
+      if (isDraft) {
+        console.log(`🚀 Running draft "${app.name}"...`);
+      } else {
+        console.log(
+          `🚀 Running application "${app.name} (${runningVersion})"...`
+        );
+      }
+
+      for (const container of appContainers) {
+        if (container.State !== "running") {
+          await docker.getContainer(container.Id).start();
+        }
+      }
+
+      if (isDraft) {
+        console.log(`✅ Draft "${app.name}" ran successfully!`);
+      } else {
+        console.log(
+          `✅ Application "${app.name} (${runningVersion})" ran successfully!`
+        );
+      }
+
+      ws.send(
+        JSON.stringify({
+          type: "appStarted",
+          app: {
+            ...app,
+            status: "running",
+            containers: appContainers.length,
+          },
+          requestId,
+        })
+      );
+      return;
+    }
+
+    // No containers exist - run the app for the first time
+    if (app.source === "backstage" && app.nodes && app.nodes.length > 0) {
+      // Convert Backstage app to YAML and run
+      const yamlContent = convertNodesToYAML(app);
+      await runBackstageApp(ws, app, yamlContent, requestId);
+      return;
+    }
+
+    // No containers and not a runnable app
+    throw new Error("No containers found for this app. Unable to start.");
+  } catch (error) {
+    console.error("Error starting app:", error.message || error);
+    ws.send(
+      JSON.stringify({
+        type: "error",
+        error: "Failed to start app: " + (error.message || String(error)),
+        requestId: payload.requestId,
+      })
+    );
+  }
+}
+
+async function handleStopApp(ws, payload) {
+  try {
+    const { id, requestId } = payload;
+
+    // Extract user context from payload
+    const userEntityRef = payload.userEntityRef || null;
+
+    // Find the app
+    const apps = await findApps(userEntityRef);
+    const app = apps.find((a) => a.id === id);
+
+    if (!app) {
+      throw new Error("App not found");
+    }
+
+    // Normalize app name for container matching
+    const appName = app.name.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+
+    // Find containers belonging to this app
+    const containers = await docker.listContainers({ all: true });
+    const appContainers = containers.filter((container) => {
+      const containerName = container.Names[0].replace(/^\//, "");
+      const projectLabel = container.Labels["com.docker.compose.project"];
+
+      return (
+        containerName.startsWith(appName) ||
+        projectLabel === appName ||
+        container.Labels["app"] === appName
+      );
+    });
+
+    // Get version from container labels (the actual running version)
+    const runningVersion =
+      appContainers.length > 0 && appContainers[0].Labels["app.version"]
+        ? appContainers[0].Labels["app.version"]
+        : app.version || "1.0.0";
+    const isDraft = app.backstageStatus === "draft";
+
+    // Log with appropriate format for draft vs published
+    if (isDraft) {
+      console.log(`⏹️ Stopping draft "${app.name}"...`);
+    } else {
+      console.log(
+        `⏹️ Stopping application "${app.name} (${runningVersion})"...`
+      );
+    }
+
+    // Stop all containers
+    for (const container of appContainers) {
+      if (container.State === "running") {
+        await docker.getContainer(container.Id).stop();
+      }
+    }
+
+    // Success log with appropriate format
+    if (isDraft) {
+      console.log(`✅ Draft "${app.name}" stopped successfully!`);
+    } else {
+      console.log(
+        `✅ Application "${app.name} (${runningVersion})" stopped successfully!`
+      );
+    }
+
+    ws.send(
+      JSON.stringify({
+        type: "appStopped",
+        app: {
+          ...app,
+          status: "stopped",
+        },
+        requestId,
+      })
+    );
+  } catch (error) {
+    console.error("Error stopping app:", error);
+    ws.send(
+      JSON.stringify({
+        type: "error",
+        error: "Failed to stop app: " + error.message,
+        requestId: payload.requestId,
+      })
+    );
+  }
+}
+
+async function handleRestartApp(ws, payload) {
+  try {
+    const { id, requestId } = payload;
+
+    // Extract user context from payload
+    const userEntityRef = payload.userEntityRef || null;
+
+    // Find the app
+    const apps = await findApps(userEntityRef);
+    const app = apps.find((a) => a.id === id);
+
+    if (!app) {
+      throw new Error("App not found");
+    }
+
+    // Normalize app name for container matching
+    const appName = app.name.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+
+    // Find containers belonging to this app
+    const containers = await docker.listContainers({ all: true });
+    const appContainers = containers.filter((container) => {
+      const containerName = container.Names[0].replace(/^\//, "");
+      const projectLabel = container.Labels["com.docker.compose.project"];
+
+      return (
+        containerName.startsWith(appName) ||
+        projectLabel === appName ||
+        container.Labels["app"] === appName
+      );
+    });
+
+    // Get version from container labels (the actual running version)
+    const runningVersion =
+      appContainers.length > 0 && appContainers[0].Labels["app.version"]
+        ? appContainers[0].Labels["app.version"]
+        : app.version || "1.0.0";
+    const isDraft = app.backstageStatus === "draft";
+
+    // Log with appropriate format for draft vs published
+    if (isDraft) {
+      console.log(`🔄 Restarting draft "${app.name}"...`);
+    } else {
+      console.log(
+        `🔄 Restarting application "${app.name} (${runningVersion})"...`
+      );
+    }
+
+    // Restart all containers
+    for (const container of appContainers) {
+      await docker.getContainer(container.Id).restart();
+    }
+
+    // Success log with appropriate format
+    if (isDraft) {
+      console.log(`✅ Draft "${app.name}" restarted successfully!`);
+    } else {
+      console.log(
+        `✅ Application "${app.name} (${runningVersion})" restarted successfully!`
+      );
+    }
+
+    ws.send(
+      JSON.stringify({
+        type: "appRestarted",
+        app: {
+          ...app,
+          status: "running",
+          containers: appContainers.length,
+        },
+        requestId,
+      })
+    );
+  } catch (error) {
+    console.error("Error restarting app:", error);
+    ws.send(
+      JSON.stringify({
+        type: "error",
+        error: "Failed to restart app: " + error.message,
+        requestId: payload.requestId,
+      })
+    );
+  }
+}
+
+async function handleDeleteApp(ws, payload) {
+  try {
+    const { id, requestId } = payload;
+
+    // Extract user context from payload
+    const userEntityRef = payload.userEntityRef || null;
+
+    // Find the app
+    const apps = await findApps(userEntityRef);
+    const app = apps.find((a) => a.id === id);
+
+    if (!app) {
+      throw new Error("App not found");
+    }
+
+    const appVersion = app.version || "1.0.0";
+    const appId = app.backstageId || app.id;
+    const isDraft = app.backstageStatus === "draft";
+
+    // Normalize app name for container matching
+    const appName = app.name.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+
+    // Find containers belonging to this app
+    const containers = await docker.listContainers({ all: true });
+    const appContainers = containers.filter((container) => {
+      const containerName = container.Names[0].replace(/^\//, "");
+      const projectLabel = container.Labels["com.docker.compose.project"];
+
+      return (
+        containerName.startsWith(appName) ||
+        projectLabel === appName ||
+        container.Labels["app"] === appName
+      );
+    });
+
+    // Remove all containers
+    for (const container of appContainers) {
+      await docker.getContainer(container.Id).remove({ force: true });
+    }
+
+    // Delete workspace folder - use "draft" for drafts, version for published
+    const workspacePath = isDraft
+      ? resolveWorkspacePathForDraft(appId, appName, "delete")
+      : resolveWorkspacePath(appId, appName, appVersion, "delete");
+    const registryVersion = isDraft ? "draft" : appVersion;
+
+    if (fs.existsSync(workspacePath)) {
+      deleteWorkspaceFolder(workspacePath);
+      unregisterWorkspace(appId, registryVersion);
+    }
+
+    // If app is from backstage, delete from backend database
+    if (app.source === "backstage" && app.backstageId) {
+      // Log with appropriate format for draft vs published
+      if (isDraft) {
+        console.log(`🗑️  Deleting draft "${app.name}"...`);
+      } else {
+        console.log(
+          `🗑️  Deleting application "${app.name} (${appVersion})"...`
+        );
+      }
+
+      const session = loadSession();
+      if (!session || !session.token) {
+        console.error(
+          chalk.red("❌ No active session found. Cannot delete from database.")
+        );
+        throw new Error("No active session. Please login first.");
+      }
+
+      const deleteUrl = `${APP_BUILDER_URL}/api/app-builder/applications/${app.backstageId}`;
+
+      try {
+        await axios.delete(deleteUrl, {
+          headers: {
+            Authorization: `Bearer ${session.token}`,
+            "Content-Type": "application/json",
+          },
+          timeout: 10000,
+        });
+        // Success log with appropriate format
+        if (isDraft) {
+          console.log(`✅ Draft "${app.name}" deleted successfully!`);
+        } else {
+          console.log(
+            `✅ Application "${app.name} (${appVersion})" deleted successfully!`
+          );
+        }
+      } catch (dbError) {
+        console.error(
+          chalk.red("❌ Error deleting from database: ", dbError.message)
+        );
+
+        // If it's an authentication error, throw it so the user knows
+        if (dbError.response?.status === 401) {
+          throw new Error(
+            "Authentication failed. Please login again with: fenwave login"
+          );
+        }
+      }
+    }
+
+    ws.send(
+      JSON.stringify({
+        type: "appDeleted",
+        id,
+        success: true,
+        requestId,
+      })
+    );
+  } catch (error) {
+    console.error("Error deleting app:", error);
+    ws.send(
+      JSON.stringify({
+        type: "error",
+        error: "Failed to delete app: " + error.message,
+        requestId: payload.requestId,
+      })
+    );
+  }
+}
+
+/**
+ * Handle deletion of specific app versions
+ */
+async function handleDeleteAppVersions(ws, payload) {
+  try {
+    const { appName, backstageId, versions, requestId } = payload;
+
+    if (!appName || !versions || versions.length === 0) {
+      throw new Error("appName and versions are required");
+    }
+
+    const normalizedAppName = appName
+      .replace(/[^a-z0-9-]/gi, "-")
+      .toLowerCase();
+    const appId = backstageId || appName;
+
+    const versionWord = versions.length === 1 ? "version" : "versions";
+
+    const deletedVersions = [];
+    const failedVersions = [];
+
+    for (const version of versions) {
+      const isDraft = version === "draft";
+
+      try {
+        if (isDraft) {
+          console.log(`🗑️  Deleting draft "${appName}"...`);
+        } else {
+          console.log(`🗑️  Deleting version ${version} of "${appName}"...`);
+        }
+
+        // Find containers for this specific version
+        const containers = await docker.listContainers({ all: true });
+        const versionContainers = containers.filter((container) => {
+          const containerName = container.Names[0].replace(/^\//, "");
+          const projectLabel = container.Labels["com.docker.compose.project"];
+          const containerVersion = container.Labels["app.version"];
+
+          const matchesApp =
+            containerName.startsWith(normalizedAppName) ||
+            projectLabel === normalizedAppName ||
+            container.Labels["app"] === normalizedAppName;
+
+          if (!matchesApp) return false;
+
+          // For drafts, match containers without version label or with draft project name
+          if (isDraft) {
+            return !containerVersion || projectLabel === normalizedAppName;
+          }
+
+          // If container has version label, match by version
+          if (containerVersion) {
+            const matchesVersion = containerVersion === version;
+            return matchesVersion;
+          }
+
+          // If no version label, also match by project name suffix (e.g., app-name-v1.0.0)
+          // This handles containers created before version labels were added
+          const matchesByName =
+            projectLabel === `${normalizedAppName}-${version}` ||
+            containerName.includes(`-${version}`);
+          return matchesByName;
+        });
+
+        // Remove containers for this version (force remove even if running)
+        for (const container of versionContainers) {
+          try {
+            await docker.getContainer(container.Id).remove({ force: true });
+          } catch (removeErr) {
+            console.warn(
+              `   ⚠️  Failed to remove container ${container.Names[0]}: ${removeErr.message}`
+            );
+          }
+        }
+
+        // Delete workspace folder for this version
+        // For drafts, use the draft workspace path
+        const workspacePath = isDraft
+          ? resolveWorkspacePathForDraft(appId, normalizedAppName, "delete")
+          : resolveWorkspacePath(appId, normalizedAppName, version, "delete");
+        const registryKey = isDraft ? "draft" : version;
+
+        if (fs.existsSync(workspacePath)) {
+          deleteWorkspaceFolder(workspacePath);
+          unregisterWorkspace(appId, registryKey);
+        }
+
+        if (isDraft) {
+          console.log(`✅ Draft deleted successfully`);
+        } else {
+          console.log(`✅ Version ${version} deleted successfully`);
+        }
+        deletedVersions.push(version);
+      } catch (versionError) {
+        console.error(
+          chalk.red(
+            `   ❌ Failed to delete version ${version}:`,
+            versionError.message
+          )
+        );
+        failedVersions.push({ version, error: versionError.message });
+      }
+    }
+
+    ws.send(
+      JSON.stringify({
+        type: "appVersionsDeleted",
+        appName,
+        backstageId,
+        deletedVersions,
+        failedVersions,
+        success: failedVersions.length === 0,
+        requestId,
+      })
+    );
+  } catch (error) {
+    console.error("Error deleting app versions:", error);
+    ws.send(
+      JSON.stringify({
+        type: "error",
+        error: "Failed to delete app versions: " + error.message,
+        requestId: payload.requestId,
+      })
+    );
+  }
+}
+
+async function handleCreateApp(ws, payload) {
+  try {
+    const { templateName, yamlContent, requestId } = payload;
+    const url = `${APP_BUILDER_URL}/api/app-builder/import-template`;
+    try {
+      await axios.post(
+        url,
+        {
+          templateName,
+          yamlContent,
+        },
+        {
+          headers: {
+            "Content-Type": "application/json",
+          },
+          timeout: 10000,
+        }
+      );
+
+      ws.send(
+        JSON.stringify({
+          type: "appCreated",
+          templateName,
+          success: true,
+          forwardedToComposer: true,
+          requestId,
+        })
+      );
+    } catch (forwardError) {
+      console.error(
+        chalk.red(
+          "❌ Failed to forward template to app-builder:",
+          forwardError.message
+        )
+      );
+
+      // Still log the template locally even if forwarding fails
+      ws.send(
+        JSON.stringify({
+          type: "appCreated",
+          templateName,
+          success: true,
+          forwardedToComposer: false,
+          forwardError: forwardError.message,
+          requestId,
+        })
+      );
+    }
+  } catch (error) {
+    console.error("Error logging template:", error);
+    ws.send(
+      JSON.stringify({
+        type: "error",
+        error: "Failed to log template: " + error.message,
+        requestId: payload.requestId,
+      })
+    );
+  }
+}
+
+/**
+ * Helper function to create a new bind mount (file or directory)
+ * @param {string} appDownloadDir - The app workspace directory
+ * @param {object} bindMount - The bind mount configuration
+ * @param {string} baseName - The base name extracted from container path
+ * @param {boolean} isDirectory - Whether this is a directory mount
+ * @param {string} randomSuffix - Random suffix for the file/directory name
+ * @returns {{hostPath: string, log: string}} The relative host path for docker-compose and log message
+ */
+function createNewBindMount(
+  appDownloadDir,
+  bindMount,
+  baseName,
+  isDirectory,
+  randomSuffix
+) {
+  if (isDirectory) {
+    // For directory mounts, create a directory and a file inside it
+    const hostDirName = `${baseName}.${randomSuffix}`;
+    const hostDirPath = path.join(appDownloadDir, hostDirName);
+
+    // Create the directory
+    if (!fs.existsSync(hostDirPath)) {
+      fs.mkdirSync(hostDirPath, { recursive: true });
+    }
+
+    // Create a default file inside the directory
+    const fileName = `${baseName}.toml`;
+    const hostFilePath = path.join(hostDirPath, fileName);
+    fs.writeFileSync(hostFilePath, bindMount.content, "utf8");
+    const log = `📁 Created bind mount directory: ${hostDirName}/ with file: ${fileName}`;
+
+    return { hostPath: `./${hostDirName}`, log };
+  } else {
+    // For file mounts, create the file directly
+    const hostFileName = `${baseName}.${randomSuffix}`;
+    const hostFilePath = path.join(appDownloadDir, hostFileName);
+
+    // Write the content to the file
+    fs.writeFileSync(hostFilePath, bindMount.content, "utf8");
+    const log = `📝 Created bind mount file: ${hostFileName}`;
+
+    return { hostPath: `./${hostFileName}`, log };
+  }
+}
+
+function generateDockerCompose(
+  appDefinition,
+  outputPath,
+  dockerComposeConfig = null
+) {
+  if (!appDefinition.application) {
+    throw new Error('Invalid YAML: missing "application" key');
+  }
+
+  const name = appDefinition.application.name;
+  const version = appDefinition.application.version || "1.0.0";
+
+  if (!name || typeof name !== "string") {
+    console.error(chalk.red("❌ Invalid application name:", name));
+    throw new Error(
+      `Invalid application name: expected string, got ${typeof name}`
+    );
+  }
+
+  const services = {};
+  const volumes = {};
+  const networks = {};
+
+  for (const component of appDefinition.application.components) {
+    const serviceName = component.name.toLowerCase();
+    const service = {};
+
+    // Handle image or build context
+    if (component.docker?.build && component.docker?.dockerfile) {
+      service.build = {
+        context: ".",
+        dockerfile_inline: component.docker.dockerfile
+          .trim()
+          .replace(/\\n/g, "\n"),
+      };
+    } else if (component.docker?.image) {
+      service.image = component.docker.image;
+    }
+
+    // container_name
+    service.container_name = serviceName;
+
+    // Hostname
+    if (component.hostname) {
+      service.hostname = component.hostname;
+    }
+
+    // Add labels to track the version
+    service.labels = {
+      "app.version": version,
+      "app.name": name,
+    };
+
+    // Add custom labels if present
+    if (component.labels && component.labels.length > 0) {
+      component.labels.forEach((labelStr) => {
+        if (typeof labelStr === "string" && labelStr.includes("=")) {
+          const [key, ...valueParts] = labelStr.split("=");
+          service.labels[key] = valueParts.join("=");
+        }
+      });
+    }
+
+    // Ports - support multiple ports
+    if (component.ports && Array.isArray(component.ports)) {
+      // Multiple ports format - normalize single ports to host:container format
+      service.ports = component.ports.map((p) => {
+        const portStr = String(p);
+        // If already in host:container format, use as-is; otherwise, map same port
+        return portStr.includes(":") ? portStr : `${portStr}:${portStr}`;
+      });
+    } else if (component.port) {
+      // Legacy single port support
+      // For databases, map to their standard internal ports
+      const standardPorts = {
+        mysql: "3306",
+        postgresql: "5432",
+        mongo: "27017",
+        redis: "6379",
+        rabbitmq: "5672",
+        elasticsearch: "9200",
+      };
+
+      const internalPort = standardPorts[component.type] || component.port;
+      service.ports = [`${component.port}:${internalPort}`];
+    }
+
+    // Command - preserve user's format
+    if (component.command && component.command.length > 0) {
+      service.command = component.command;
+    }
+
+    // Environment variables
+    if (component.env) {
+      service.environment = component.env;
+    }
+
+    // env_file - extract file names only, content will be written separately
+    if (component.env_file && component.env_file.length > 0) {
+      service.env_file = component.env_file.map((ef) =>
+        typeof ef === "string" ? ef : `./${ef.name || ".env"}`
+      );
+    }
+
+    // Memory options
+    if (component.mem_reservation) {
+      service.mem_reservation = component.mem_reservation;
+    }
+    if (component.mem_limit) {
+      service.mem_limit = component.mem_limit;
+    }
+
+    // Apply global run config environment variables
+    if (dockerComposeConfig && dockerComposeConfig.containerEnv) {
+      service.environment = {
+        ...dockerComposeConfig.containerEnv,
+        ...(service.environment || {}),
+      };
+    }
+
+    // depends_on (from manual configuration only)
+    if (component.dependsOn?.length) {
+      service.depends_on = component.dependsOn.map((dep) => dep.toLowerCase());
+    }
+
+    // Restart policy
+    if (component.restartPolicy) {
+      service.restart = component.restartPolicy;
+    }
+
+    // User (run container as specific user)
+    if (component.user) {
+      service.user = component.user;
+    }
+
+    // Volumes
+    if (component.volumes?.length) {
+      service.volumes = component.volumes
+        .filter((vol) => vol.name && (vol.mountPath || vol.mount_path))
+        .map((vol) => {
+          const mountPath = vol.mountPath || vol.mount_path;
+          return `${vol.name}:${mountPath}`;
+        });
+
+      // Only add named volumes to top-level volumes (not bind mounts/host paths)
+      component.volumes.forEach((vol) => {
+        if (vol.name && !volumes[vol.name]) {
+          // Skip bind mounts (paths starting with ./ or /)
+          if (!vol.name.startsWith("./") && !vol.name.startsWith("/")) {
+            volumes[vol.name] = { driver: "local" };
+          }
+        }
+      });
+    }
+
+    // Bind mounts with content - these will be handled separately
+    // Store bind mounts for later file creation
+    if (component.bindMounts?.length) {
+      // Bind mounts will be processed after files are created
+      // The _hostPath will be added to each bindMount during file creation
+    }
+
+    // Networks
+    const builtinNetworks = ["bridge", "host", "none"];
+    const componentNetworks = component.networks || [];
+
+    const builtinSelected = componentNetworks.filter((n) =>
+      builtinNetworks.includes(n.name || n)
+    );
+    const customSelected = componentNetworks.filter(
+      (n) => !builtinNetworks.includes(n.name || n)
+    );
+
+    if (builtinSelected.length === 1 && componentNetworks.length === 1) {
+      service.network_mode = builtinSelected[0].name || builtinSelected[0];
+    } else if (componentNetworks.length === 0) {
+      // default to bridge
+    } else {
+      // Handle custom networks with aliases support
+      const serviceNetworks = {};
+      customSelected.forEach((n) => {
+        const name = typeof n === "string" ? n : n.name;
+        const aliases =
+          typeof n === "object" && n.aliases && n.aliases.length > 0
+            ? n.aliases
+            : null;
+
+        if (aliases) {
+          serviceNetworks[name] = { aliases };
+        } else {
+          serviceNetworks[name] = null;
+        }
+      });
+
+      // If any network has aliases, use object format; otherwise use array
+      const hasAliases = Object.values(serviceNetworks).some((v) => v !== null);
+      if (hasAliases) {
+        service.networks = serviceNetworks;
+      } else {
+        service.networks = customSelected.map((n) =>
+          typeof n === "string" ? n : n.name
+        );
+      }
+
+      // Define networks globally
+      customSelected.forEach((n) => {
+        const name = typeof n === "string" ? n : n.name;
+        if (!networks[name]) {
+          networks[name] = {
+            driver: typeof n === "object" && n.driver ? n.driver : "bridge",
+          };
+        }
+      });
+    }
+
+    // Apply global run config resources and scaling
+    if (dockerComposeConfig) {
+      const deploy = generateComposeDeploy(
+        dockerComposeConfig.resources,
+        dockerComposeConfig.replicas
+      );
+      if (deploy) {
+        service.deploy = deploy;
+      }
+    }
+
+    // Process bind mounts - add to volumes array
+    if (component.bindMounts?.length) {
+      const bindMountVolumes = component.bindMounts
+        .filter((bm) => {
+          // For 'generated' mode, require _hostPath
+          if (bm.mode === "generated" || !bm.mode) {
+            return bm.containerPath && bm._hostPath;
+          }
+          // For 'existing' mode, require hostPath
+          if (bm.mode === "existing") {
+            return bm.containerPath && bm.hostPath;
+          }
+          return false;
+        })
+        .map((bm) => {
+          const mountOption = bm.mountOption || "rw";
+
+          // Use _hostPath for generated mode, hostPath for existing mode
+          const hostPath = bm.mode === "existing" ? bm.hostPath : bm._hostPath;
+
+          return `${hostPath}:${bm.containerPath}${
+            mountOption === "ro" ? ":ro" : ""
+          }`;
+        });
+
+      if (bindMountVolumes.length > 0) {
+        service.volumes = [...(service.volumes || []), ...bindMountVolumes];
+      }
+    }
+
+    // Final cleanup of undefined
+    services[serviceName] = Object.fromEntries(
+      Object.entries(service).filter(([, value]) => value !== undefined)
+    );
+  }
+
+  const compose = {
+    name,
+    services,
+  };
+
+  // adding volumes in the root level if defined
+  if (Object.keys(volumes).length > 0) {
+    compose.volumes = volumes;
+  }
+
+  // adding networks in the root level if defined
+  if (Object.keys(networks).length > 0) {
+    compose.networks = networks;
+  }
+
+  const dumpOptions = {
+    noRefs: true,
+    lineWidth: -1,
+    replacer: (key, value) => {
+      if (key === "dockerfile_inline" && typeof value === "string") {
+        return value;
+      }
+      return value;
+    },
+  };
+
+  const yamlStr = yaml.dump(compose, dumpOptions);
+  fs.writeFileSync(outputPath, yamlStr, "utf8");
+}
+
+// Convert Backstage app nodes to YAML format
+function convertNodesToYAML(app) {
+  const components = app.nodes
+    .filter((node) => node.type === "component")
+    .map((node) => {
+      const config = node.data.config || {};
+      const component = {
+        name: node.data.name,
+        type: node.data.type,
+      };
+
+      // Build Docker image reference
+      const registry = config.dockerRegistry || "";
+      const repository = config.dockerRepository || "";
+      const image = config.dockerImage || "";
+      const tag = config.dockerTag || "latest";
+
+      if (image) {
+        const fullImage = [registry, repository, image]
+          .filter(Boolean)
+          .join("/");
+        component.docker = {
+          image: `${fullImage}:${tag}`,
+        };
+      }
+
+      // Add ports (multiple ports support)
+      if (config.ports && config.ports.length > 0) {
+        component.ports = config.ports;
+      }
+
+      // Add hostname
+      if (config.hostname) {
+        component.hostname = config.hostname;
+      }
+
+      // Add commands
+      if (config.commands && config.commands.length > 0) {
+        component.command = config.commands;
+      }
+
+      // Add labels
+      if (config.labels && config.labels.length > 0) {
+        component.labels = config.labels.map((l) => `${l.key}=${l.value}`);
+      }
+
+      // Add env_file (with content to write)
+      if (config.envFiles && config.envFiles.length > 0) {
+        component.env_file = config.envFiles
+          .filter((ef) => ef.content && ef.content.trim())
+          .map((ef) => ({
+            name: ef.name || ".env",
+            content: ef.content,
+          }));
+      }
+
+      // Add memory options
+      if (config.memReservation) {
+        component.mem_reservation = config.memReservation;
+      }
+      if (config.memLimit) {
+        component.mem_limit = config.memLimit;
+      }
+
+      // Add hostname
+      if (config.hostname) {
+        component.hostname = config.hostname;
+      }
+
+      // Add commands
+      if (config.commands && config.commands.length > 0) {
+        component.command = config.commands;
+      }
+
+      // Add labels
+      if (config.labels && config.labels.length > 0) {
+        component.labels = config.labels.map((l) => `${l.key}=${l.value}`);
+      }
+
+      // Add env_file (with content to write)
+      if (config.envFiles && config.envFiles.length > 0) {
+        component.env_file = config.envFiles
+          .filter((ef) => ef.content && ef.content.trim())
+          .map((ef) => ({
+            name: ef.name || ".env",
+            content: ef.content,
+          }));
+      }
+
+      // Add memory options
+      if (config.memReservation) {
+        component.mem_reservation = config.memReservation;
+      }
+      if (config.memLimit) {
+        component.mem_limit = config.memLimit;
+      }
+
+      // Add environment variables
+      if (config.env && Object.keys(config.env).length > 0) {
+        component.env = config.env;
+      }
+
+      // Add volumes
+      if (config.volumeMounts && config.volumeMounts.length > 0) {
+        component.volumes = config.volumeMounts.map((v) => ({
+          name: v.name,
+          mount_path: v.mountPath,
+          size: v.size || "1Gi",
+        }));
+      }
+
+      // Add bind mounts with support for both modes
+      if (config.bindMounts && config.bindMounts.length > 0) {
+        component.bindMounts = config.bindMounts.map((bm) => {
+          const baseMount = {
+            containerPath: bm.containerPath,
+            mountOption: bm.mountOption || "rw",
+            mode: bm.mode || "generated",
+          };
+
+          if (bm.mode === "existing" && bm.hostPath) {
+            return {
+              ...baseMount,
+              hostPath: bm.hostPath,
+            };
+          } else if ((bm.mode === "generated" || !bm.mode) && bm.content) {
+            return {
+              ...baseMount,
+              content: bm.content,
+            };
+          }
+
+          // Fallback for legacy bind mounts
+          return {
+            ...baseMount,
+            content: bm.content || "",
+          };
+        });
+      }
+
+      // Add networks
+      if (config.networks && config.networks.length > 0) {
+        component.networks = config.networks;
+      }
+
+      // Add depends_on
+      if (config.dependsOn && config.dependsOn.length > 0) {
+        component.depends_on = config.dependsOn;
+      }
+
+      // Add restart policy
+      if (config.restartPolicy && config.restartPolicy !== "no") {
+        component.restartPolicy = config.restartPolicy;
+      }
+
+      // Add user option
+      // if (config.user) {
+      //   component.user = config.user;
+      // }
+
+      return component;
+    });
+
+  const appDefinition = {
+    application: {
+      name: app.name.replace(/[^a-z0-9-]/gi, "-").toLowerCase(),
+      version: app.version || "1.0.0",
+      components: components,
+    },
+  };
+
+  return yaml.dump(appDefinition);
+}
+
+// Run a Backstage app
+async function runBackstageApp(ws, app, yamlContent, requestId, context = {}) {
+  const { isSync = false } = context;
+  try {
+    // Determine if this is a draft or published app
+    const isDraft = app.backstageStatus === "draft" || app.status === "draft";
+    const appVersion = app.version || "1.0.0";
+
+    // Log with appropriate format for draft vs published
+    if (!isSync) {
+      if (isDraft) {
+        console.log(`🚀 Running draft "${app.name}"...`);
+      } else {
+        console.log(`🚀 Running application "${app.name} (${appVersion})"...`);
+      }
+    }
+
+    // Send run started notification
+    ws.send(
+      JSON.stringify({
+        type: "runStarted",
+        requestId,
+      })
+    );
+
+    // Resolve workspace path (check registry or create new)
+    const appId = app.backstageId || app.id;
+    const appName = app.name.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+    // For drafts, don't include version in workspace path
+    // Pass 'sync' context to suppress duplicate warning during sync
+    const resolveContext = isSync ? "sync" : "default";
+    const appDownloadDir = isDraft
+      ? resolveWorkspacePathForDraft(appId, appName, resolveContext)
+      : resolveWorkspacePath(appId, appName, appVersion, resolveContext);
+    const isNewWorkspace = !fs.existsSync(appDownloadDir);
+
+    // Parse YAML to extract run config
+    const appDefinition = yaml.load(yamlContent);
+    // Validate components have either an image or build context before proceeding
+    const missingImageComponents = (
+      appDefinition?.application?.components || []
+    )
+      .filter((component) => {
+        const hasBuild = !!(
+          component?.docker?.build && component?.docker?.dockerfile
+        );
+        const hasImage = !!component?.docker?.image;
+        return !hasBuild && !hasImage;
+      })
+      .map((c) => c?.name)
+      .filter(Boolean);
+
+    if (missingImageComponents.length > 0) {
+      // Send a recognizable error that frontend will tailor into a toast
+      const detail =
+        missingImageComponents.length === 1
+          ? `Component "${missingImageComponents[0]}" has neither an image nor a build context specified`
+          : `Components ${missingImageComponents
+              .map((n) => `"${n}"`)
+              .join(", ")} have neither an image nor a build context specified`;
+
+      ws.send(
+        JSON.stringify({
+          type: "error",
+          error: detail,
+          requestId,
+        })
+      );
+      console.log(chalk.red(`❌ Run aborted: ${detail}`));
+
+      return; // Do not generate docker-compose or proceed further
+    }
+
+    // Now create the workspace directory (validation passed)
+    if (!fs.existsSync(appDownloadDir)) {
+      fs.mkdirSync(appDownloadDir, { recursive: true });
+      // Log workspace creation immediately after it's created
+      console.log(`📁 Created workspace at: ${appDownloadDir}`);
+    }
+
+    const runConfig = appDefinition.application?.deploymentConfig;
+
+    // Transform run config to Docker Compose format
+    let dockerComposeConfig = null;
+    if (runConfig) {
+      dockerComposeConfig = toDockerComposeConfig(runConfig);
+
+      // Generate host environment script if there are host env vars
+      if (Object.keys(dockerComposeConfig.hostEnv).length > 0) {
+        const hostEnvScript = generateHostEnvScript(
+          dockerComposeConfig.hostEnv
+        );
+        const hostEnvPath = path.join(appDownloadDir, "host-env.sh");
+        fs.writeFileSync(hostEnvPath, hostEnvScript, "utf8");
+        fs.chmodSync(hostEnvPath, "755"); // Make executable
+      }
+
+      // Generate .env file for Docker Compose
+      if (
+        Object.keys(dockerComposeConfig.containerEnv).length > 0 ||
+        Object.keys(dockerComposeConfig.secretRefs).length > 0
+      ) {
+        const envFileContent = generateEnvFile(
+          dockerComposeConfig.containerEnv,
+          dockerComposeConfig.secretRefs
+        );
+        const envFilePath = path.join(appDownloadDir, ".env");
+        fs.writeFileSync(envFilePath, envFileContent, "utf8");
+      }
+    }
+
+    // Write component-specific env files with content
+    // Collect logs to display in proper order
+    const envFileLogs = [];
+    const bindMountCreatedLogs = [];
+    const bindMountExistingLogs = [];
+
+    if (
+      appDefinition &&
+      appDefinition.application &&
+      appDefinition.application.components
+    ) {
+      for (const component of appDefinition.application.components) {
+        if (component.env_file && Array.isArray(component.env_file)) {
+          for (const envFile of component.env_file) {
+            // Only write if it has content (new format)
+            if (typeof envFile === "object" && envFile.content) {
+              const envFileName = envFile.name || ".env";
+              const envFilePath = path.join(appDownloadDir, envFileName);
+
+              // Check if env file already exists - if so, skip creation
+              if (fs.existsSync(envFilePath)) {
+                envFileLogs.push(`✅ Env file already exists: ${envFileName}`);
+              } else {
+                fs.writeFileSync(envFilePath, envFile.content, "utf8");
+                envFileLogs.push(`📝 Created env file: ${envFileName}`);
+              }
+            }
+          }
+        }
+
+        // Write bind mount files with content or prepare existing paths
+        if (component.bindMounts && Array.isArray(component.bindMounts)) {
+          for (const bindMount of component.bindMounts) {
+            if (!bindMount.containerPath) {
+              console.warn(`⚠️  Skipping bind mount without containerPath`);
+              continue;
+            }
+
+            const containerPath = bindMount.containerPath;
+            const mode = bindMount.mode || "generated";
+
+            // Handle existing host path mode
+            if (mode === "existing") {
+              if (!bindMount.hostPath) {
+                console.warn(
+                  `⚠️  Skipping bind mount in 'existing' mode without hostPath: ${containerPath}`
+                );
+                continue;
+              }
+
+              // Use the user-provided host path directly
+              bindMount._hostPath = bindMount.hostPath;
+              bindMountExistingLogs.push(
+                `🔧 Using existing host path for ${containerPath} : ${bindMount.hostPath}`
+              );
+              continue;
+            }
+
+            // Handle generated content mode
+            if (!bindMount.content) {
+              console.warn(
+                `⚠️  Skipping bind mount in 'generated' mode without content: ${containerPath}`
+              );
+              continue;
+            }
+
+            // Skip special system paths that should bind to host directly
+            const systemPaths = [
+              "/var/run/docker.sock",
+              "/var/run/docker.sock.raw",
+            ];
+            if (systemPaths.includes(containerPath)) {
+              console.log(
+                `⚠️  Skipping file creation for system path: ${containerPath} (will bind to host)`
+              );
+              bindMount._hostPath = containerPath;
+              continue;
+            }
+
+            // Determine if this is a file or directory based on the path
+            const isDirectory =
+              !path.extname(containerPath) || containerPath.endsWith("/");
+            const baseName = path.basename(containerPath.replace(/\/$/, ""));
+
+            // Check if an existing bind mount with the same prefix already exists
+            const existingFiles = fs.readdirSync(appDownloadDir);
+            const existingMatch = existingFiles.find((file) => {
+              // Match pattern: baseName.suffix
+              const regex = new RegExp(`^${baseName}\\.[a-z0-9]+$`, "i");
+              return regex.test(file);
+            });
+
+            let hostPath;
+
+            if (existingMatch) {
+              // Reuse existing bind mount
+              const existingPath = path.join(appDownloadDir, existingMatch);
+              const existingStat = fs.statSync(existingPath);
+
+              if (isDirectory && existingStat.isDirectory()) {
+                // Check and update the file inside the directory
+                const fileName = `${baseName}.toml`;
+                const existingFilePath = path.join(existingPath, fileName);
+
+                try {
+                  // Check if content needs updating
+                  let needsUpdate = true;
+                  if (fs.existsSync(existingFilePath)) {
+                    const existingContent = fs.readFileSync(
+                      existingFilePath,
+                      "utf8"
+                    );
+                    needsUpdate = existingContent !== bindMount.content;
+                  }
+
+                  if (needsUpdate) {
+                    fs.writeFileSync(
+                      existingFilePath,
+                      bindMount.content,
+                      "utf8"
+                    );
+                    bindMountCreatedLogs.push(
+                      `📎 Updated bind mount directory: ${existingMatch}/ with file: ${fileName}`
+                    );
+                  } else {
+                    bindMountCreatedLogs.push(
+                      `📎 Bind mount directory already up-to-date: ${existingMatch}/`
+                    );
+                  }
+                } catch (err) {
+                  // Permission denied ('ro' mount)
+                  console.log(
+                    `⚠️  Cannot update ${existingMatch}/ (${
+                      err.code || "permission denied"
+                    }), keeping existing content`
+                  );
+                }
+
+                hostPath = `./${existingMatch}`;
+              } else if (!isDirectory && existingStat.isFile()) {
+                // Update the existing file
+                try {
+                  let needsUpdate = true;
+                  const existingContent = fs.readFileSync(existingPath, "utf8");
+                  needsUpdate = existingContent !== bindMount.content;
+
+                  if (needsUpdate) {
+                    fs.writeFileSync(existingPath, bindMount.content, "utf8");
+                    bindMountCreatedLogs.push(
+                      `📎 Updated bind mount file: ${existingMatch}`
+                    );
+                  } else {
+                    bindMountCreatedLogs.push(
+                      `📎 Bind mount file already up-to-date: ${existingMatch}`
+                    );
+                  }
+                } catch (err) {
+                  console.log(
+                    `⚠️  Cannot update ${existingMatch} (${
+                      err.code || "permission denied"
+                    }), keeping existing content`
+                  );
+                }
+
+                hostPath = `./${existingMatch}`;
+              } else {
+                // Type mismatch, create new
+                const randomSuffix = Math.random().toString(36).substring(2, 8);
+                const result = createNewBindMount(
+                  appDownloadDir,
+                  bindMount,
+                  baseName,
+                  isDirectory,
+                  randomSuffix
+                );
+                hostPath = result.hostPath;
+                bindMountCreatedLogs.push(result.log);
+              }
+            } else {
+              // No existing match, create new bind mount
+              const randomSuffix = Math.random().toString(36).substring(2, 8);
+              const result = createNewBindMount(
+                appDownloadDir,
+                bindMount,
+                baseName,
+                isDirectory,
+                randomSuffix
+              );
+              hostPath = result.hostPath;
+              bindMountCreatedLogs.push(result.log);
+            }
+
+            // Store the generated host path for docker-compose generation (relative path)
+            bindMount._hostPath = hostPath;
+          }
+        }
+      }
+    }
+
+    // Generate Docker Compose file directly
+    const dockerComposePath = path.join(appDownloadDir, "docker-compose.yml");
+    generateDockerCompose(
+      appDefinition,
+      dockerComposePath,
+      dockerComposeConfig
+    );
+    console.log(`🐳 Docker Compose downloaded to: ${dockerComposePath}`);
+
+    // Now print collected logs in order
+    for (const log of envFileLogs) {
+      console.log(log);
+    }
+    for (const log of bindMountCreatedLogs) {
+      console.log(log);
+    }
+    for (const log of bindMountExistingLogs) {
+      console.log(log);
+    }
+
+    // Send docker compose generated notification
+    ws.send(
+      JSON.stringify({
+        type: "dockerComposeGenerated",
+        dockerComposePath,
+        requestId,
+      })
+    );
+
+    // Build docker-compose command
+    // If there's a host-env.sh, source it before running docker-compose
+    let dockerComposeCommand;
+    if (
+      dockerComposeConfig &&
+      Object.keys(dockerComposeConfig.hostEnv).length > 0
+    ) {
+      dockerComposeCommand = `cd "${appDownloadDir}" && source ./host-env.sh && docker-compose up -d`;
+    } else {
+      dockerComposeCommand = `cd "${appDownloadDir}" && docker-compose up -d`;
+    }
+
+    if (isSync) {
+      if (isDraft) {
+        console.log(`✅ Draft "${app.name}" synced successfully!`);
+      } else {
+        console.log(
+          `✅ Application "${app.name} (${appVersion})" synced successfully!`
+        );
+      }
+      if (isDraft) {
+        console.log(`🚀 Running draft "${app.name}"...`);
+      } else {
+        console.log(`🚀 Running application "${app.name} (${appVersion})"...`);
+      }
+    }
+
+    exec(dockerComposeCommand, async (error, stdout, stderr) => {
+      if (error) {
+        // Clean up workspace folder if run failed and it was newly created
+        if (isNewWorkspace && fs.existsSync(appDownloadDir)) {
+          try {
+            fs.rmSync(appDownloadDir, { recursive: true, force: true });
+            console.log(`🧹 Cleaned up failed workspace: ${appDownloadDir}`);
+          } catch (cleanupErr) {
+            console.warn(
+              `⚠️  Failed to clean up workspace: ${cleanupErr.message}`
+            );
+          }
+        }
+        ws.send(
+          JSON.stringify({
+            type: "error",
+            error: `Docker Compose failed: ${error.message}`,
+            stderr: stderr,
+            requestId,
+          })
+        );
+        return;
+      }
+
+      // Count the running containers
+      const appName = app.name.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+      let containerCount = 0;
+      try {
+        const containers = await docker.listContainers({ all: true });
+        const appContainers = containers.filter((container) => {
+          const containerName = container.Names[0].replace(/^\//, "");
+          return (
+            containerName.startsWith(appName) ||
+            container.Labels["com.docker.compose.project"] === appName ||
+            container.Labels["app"] === appName
+          );
+        });
+        containerCount = appContainers.length;
+      } catch (countError) {
+        console.error("Error counting containers:", countError);
+      }
+
+      if (isDraft) {
+        console.log(`✅ Draft "${app.name}" ran successfully!`);
+      } else {
+        console.log(
+          `✅ Application "${app.name} (${app.version})" ran successfully!`
+        );
+      }
+
+      // Create workspace metadata on first successful run, or update if exists
+      if (!isValidWorkspace(appDownloadDir)) {
+        createWorkspaceMetadata(appDownloadDir, appId, app.name);
+        // Register with "draft" key for drafts, or version for published apps
+        const registryVersion = isDraft ? "draft" : appVersion;
+        registerWorkspace(appId, app.name, registryVersion, appDownloadDir);
+      } else {
+        updateWorkspaceMetadata(appDownloadDir);
+      }
+
+      // Send success notification
+      ws.send(
+        JSON.stringify({
+          type: "runCompleted",
+          app: {
+            ...app,
+            status: "running",
+            containers: containerCount,
+          },
+          message: "Application ran successfully!",
+          stdout: stdout || "Run completed",
+          stderr: stderr || "",
+          downloadPath: appDownloadDir,
+          requestId,
+        })
+      );
+    });
+  } catch (error) {
+    console.error(chalk.red("❌ Run error:", error));
+    ws.send(
+      JSON.stringify({
+        type: "error",
+        error: `Run failed: ${error.message}`,
+        requestId,
+      })
+    );
+  }
+}
+
+/**
+ * Validate Docker Compose configuration using real docker-compose CLI
+ * This provides accurate validation against the local environment
+ */
+async function handleValidateCompose(ws, payload) {
+  const { composeYaml, envVars, requestId } = payload;
+
+  console.log("🔍 Validating Docker Compose configuration...");
+
+  try {
+    // Create temporary directory for validation using system temp directory
+    const tempDir = path.join(os.tmpdir(), `fenwave-validate-${Date.now()}`);
+    fs.mkdirSync(tempDir, { recursive: true });
+
+    const composePath = path.join(tempDir, "docker-compose.yml");
+    const envPath = path.join(tempDir, ".env");
+
+    try {
+      // Write docker-compose.yml
+      fs.writeFileSync(composePath, composeYaml, "utf-8");
+      console.log(`✅ Written docker-compose.yml to ${composePath}`);
+
+      // Write .env file if provided
+      if (envVars && Object.keys(envVars).length > 0) {
+        const envContent = Object.entries(envVars)
+          .map(([key, value]) => `${key}=${value}`)
+          .join("\n");
+        fs.writeFileSync(envPath, envContent, "utf-8");
+        console.log(
+          `✅ Written .env file with ${Object.keys(envVars).length} variables`
+        );
+      }
+
+      // Run docker-compose config to validate
+      const command = `cd "${tempDir}" && docker-compose config --quiet`;
+
+      await new Promise((resolve, reject) => {
+        exec(command, { timeout: 10000 }, (error, stdout, stderr) => {
+          if (error) {
+            // Docker Compose found errors
+            console.error(
+              chalk.red(
+                "❌ Docker Compose validation failed:",
+                stderr || error.message
+              )
+            );
+
+            // Send validation errors back to client
+            ws.send(
+              JSON.stringify({
+                type: "validateCompose_result",
+                requestId,
+                data: {
+                  valid: false,
+                  errors: [stderr || error.message],
+                  warnings: [],
+                },
+              })
+            );
+
+            reject(error);
+          } else {
+            console.log("✅ Docker Compose validation passed");
+
+            // Send success result
+            ws.send(
+              JSON.stringify({
+                type: "validateCompose_result",
+                requestId,
+                data: {
+                  valid: true,
+                  errors: [],
+                  warnings: [],
+                },
+              })
+            );
+
+            resolve();
+          }
+        });
+      });
+    } finally {
+      // Cleanup temporary files
+      try {
+        if (fs.existsSync(composePath)) {
+          fs.unlinkSync(composePath);
+        }
+        if (fs.existsSync(envPath)) {
+          fs.unlinkSync(envPath);
+        }
+        if (fs.existsSync(tempDir)) {
+          fs.rmdirSync(tempDir);
+        }
+        console.log("🧹 Cleaned up temporary validation files");
+      } catch (cleanupError) {
+        console.warn("⚠️  Failed to cleanup temp files:", cleanupError.message);
+      }
+    }
+  } catch (error) {
+    console.error(chalk.red("❌ Validation error:", error));
+    ws.send(
+      JSON.stringify({
+        type: "error",
+        error: `Validation failed: ${error.message}`,
+        requestId,
+      })
+    );
+  }
+}
+
+/**
+ * Sync applications:
+ * - Stops & removes existing containers, fetches latest app definition from Backstage,
+ *   regenerates docker-compose and runs the app (recreate all containers).
+ * - Preserves the run state (running/stopped) from before sync.
+ * - Uses non-destructive backup approach for docker-compose.yml
+ */
+async function handleSyncApp(ws, payload = {}) {
+  const { backstageId, appData, id, requestId, keepRunning, changeId } =
+    payload;
+  try {
+    // Extract backstageId from id if needed
+    const actualBackstageId =
+      backstageId ||
+      (id && id.startsWith("backstage-") ? id.replace("backstage-", "") : id);
+
+    if (!actualBackstageId)
+      throw new Error("backstageId or id required for sync");
+
+    ws.send(
+      JSON.stringify({
+        type: "syncProgress",
+        requestId,
+        message: "Starting sync...",
+        progress: 10,
+      })
+    );
+
+    let latestApp;
+
+    // If appData is provided (from App Builder), use it directly
+    if (appData) {
+      ws.send(
+        JSON.stringify({
+          type: "syncProgress",
+          requestId,
+          message: "Processing app blueprint...",
+          progress: 20,
+        })
+      );
+
+      latestApp = {
+        id: `backstage-${actualBackstageId}`,
+        backstageId: actualBackstageId,
+        name: appData.name,
+        nodes: appData.nodes,
+        edges: appData.edges,
+        description: appData.description,
+        version: appData.version,
+        status: appData.status,
+        source: "backstage",
+      };
+    } else {
+      // Fetch from Backstage API (called from DevApp)
+      ws.send(
+        JSON.stringify({
+          type: "syncProgress",
+          requestId,
+          message: "Fetching app info from Backstage...",
+          progress: 20,
+        })
+      );
+
+      const session = loadSession();
+      if (!session || !session.token) {
+        throw new Error("No valid session found. Please run: fenwave login");
+      }
+
+      // Fetch app metadata first to get the app name
+      const appUrl = `${APP_BUILDER_URL}/api/app-builder/applications/${actualBackstageId}`;
+      const appResponse = await axios.get(appUrl, {
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${session.token}`,
+        },
+        timeout: 10000,
+      });
+
+      const fetchedApp = appResponse.data;
+
+      // Now check for existing containers using the ACTUAL app name
+      const normalizedAppName = fetchedApp.name
+        .replace(/[^a-z0-9-]/gi, "-")
+        .toLowerCase();
+
+      const containers = await docker.listContainers({ all: true });
+      const existingContainers = containers.filter((container) => {
+        const containerName = container.Names[0].replace(/^\//, "");
+        const projectLabel = container.Labels["com.docker.compose.project"];
+        return (
+          containerName.startsWith(normalizedAppName) ||
+          projectLabel === normalizedAppName ||
+          container.Labels["app"] === normalizedAppName
+        );
+      });
+
+      let versionToFetch = null;
+      if (
+        existingContainers.length > 0 &&
+        existingContainers[0].Labels["app.version"]
+      ) {
+        versionToFetch = existingContainers[0].Labels["app.version"];
+      }
+
+      // Fetch versions separately if we need a specific version
+      let allVersions = [];
+      if (versionToFetch) {
+        try {
+          const versionsUrl = `${APP_BUILDER_URL}/api/app-builder/applications/${actualBackstageId}/versions`;
+          const versionsResponse = await axios.get(versionsUrl, {
+            headers: {
+              "Content-Type": "application/json",
+              Authorization: `Bearer ${session.token}`,
+            },
+            timeout: 10000,
+          });
+          allVersions = versionsResponse.data || [];
+        } catch (err) {
+          console.warn(`Failed to fetch versions: ${err.message}`);
+        }
+      }
+
+      // If we have a specific version to preserve, use that version's blueprint from the versions array
+      let versionData = null;
+      if (versionToFetch && allVersions.length > 0) {
+        versionData = allVersions.find((v) => v.version === versionToFetch);
+
+        if (versionData) {
+          ws.send(
+            JSON.stringify({
+              type: "syncProgress",
+              requestId,
+              message: `Using version ${versionToFetch} blueprint...`,
+              progress: 25,
+            })
+          );
+        }
+      }
+
+      // Use version-specific data if available, otherwise use active version
+      const blueprintSource =
+        versionData || fetchedApp.activeVersion || fetchedApp;
+      const finalVersion =
+        versionToFetch ||
+        blueprintSource.version ||
+        fetchedApp.activeVersion?.version ||
+        "1.0.0";
+
+      latestApp = {
+        id: `backstage-${actualBackstageId}`,
+        backstageId: actualBackstageId,
+        name: fetchedApp.name,
+        nodes: blueprintSource.nodes || [],
+        edges: blueprintSource.edges || [],
+        description: blueprintSource.description || "",
+        version: finalVersion,
+        status:
+          fetchedApp.status || fetchedApp.activeVersion?.status || "draft",
+        source: "backstage",
+      };
+    }
+
+    // Resolve workspace path (use registered or create new)
+    const appId = latestApp.backstageId || latestApp.id;
+    const appVersion = latestApp.version || "1.0.0";
+    const isDraft = latestApp.status === "draft";
+
+    if (isDraft) {
+      console.log(`🚀 Syncing draft "${latestApp.name}"...`);
+    } else {
+      console.log(
+        `🚀 Syncing application "${latestApp.name} (${appVersion})"...`
+      );
+    }
+
+    const appDownloadDir = isDraft
+      ? resolveWorkspacePathForDraft(appId, latestApp.name)
+      : resolveWorkspacePath(appId, latestApp.name, appVersion);
+
+    // Backup existing docker-compose.yml before regenerating
+    ws.send(
+      JSON.stringify({
+        type: "syncProgress",
+        requestId,
+        message: "Backing up existing configuration...",
+        progress: 28,
+      })
+    );
+
+    if (fs.existsSync(appDownloadDir)) {
+      backupDockerCompose(appDownloadDir);
+    }
+
+    // Normalize app name for container matching
+    const appName = latestApp.name.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+
+    // Detect existing containers
+    const containers = await docker.listContainers({ all: true });
+    const appContainers = containers.filter((container) => {
+      const containerName = container.Names[0].replace(/^\//, "");
+      const projectLabel = container.Labels["com.docker.compose.project"];
+      return (
+        containerName.startsWith(appName) ||
+        projectLabel === appName ||
+        container.Labels["app"] === appName
+      );
+    });
+
+    // Record whether it was running
+    const wasRunning = appContainers.some((c) => c.State === "running");
+
+    ws.send(
+      JSON.stringify({
+        type: "syncProgress",
+        requestId,
+        message: `Stopping ${appContainers.length} containers...`,
+        progress: 30,
+      })
+    );
+
+    // Stop running containers
+    for (const c of appContainers) {
+      try {
+        if (c.State === "running") {
+          await docker.getContainer(c.Id).stop();
+        }
+      } catch (err) {
+        console.warn("Error stopping container", c.Id, err.message);
+      }
+    }
+
+    ws.send(
+      JSON.stringify({
+        type: "syncProgress",
+        requestId,
+        message: "Removing old containers...",
+        progress: 50,
+      })
+    );
+
+    // Remove containers
+    for (const c of appContainers) {
+      try {
+        await docker.getContainer(c.Id).remove({ force: true });
+      } catch (err) {
+        console.warn("Error removing container", c.Id, err.message);
+      }
+    }
+
+    // Prepare YAML for the latest version and run
+    const yamlContent = convertNodesToYAML(latestApp);
+
+    ws.send(
+      JSON.stringify({
+        type: "syncProgress",
+        requestId,
+        message: "Regenerating compose and creating containers...",
+        progress: 70,
+      })
+    );
+
+    // Reuse runBackstageApp flow to create docker-compose and run
+    await runBackstageApp(ws, latestApp, yamlContent, requestId, {
+      isSync: true,
+    });
+
+    ws.send(
+      JSON.stringify({
+        type: "syncProgress",
+        requestId,
+        message: "Restoring run state...",
+        progress: 90,
+      })
+    );
+
+    // If original was stopped AND we're not doing auto-sync-before-start, stop the newly created containers
+    // keepRunning flag indicates this sync is part of auto-sync-then-start flow
+    if (!wasRunning && !keepRunning) {
+      // Wait a moment for containers to fully start before stopping them
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+
+      const postContainers = await docker.listContainers({ all: true });
+      const newAppContainers = postContainers.filter((container) => {
+        const containerName = container.Names[0].replace(/^\//, "");
+        const projectLabel = container.Labels["com.docker.compose.project"];
+        return (
+          containerName.startsWith(appName) ||
+          projectLabel === appName ||
+          container.Labels["app"] === appName
+        );
+      });
+      for (const c of newAppContainers) {
+        if (c.State === "running") {
+          try {
+            await docker.getContainer(c.Id).stop();
+          } catch (stopErr) {
+            console.warn(
+              "Failed to stop container after recreate",
+              c.Id,
+              stopErr.message
+            );
+          }
+        }
+      }
+      ws.send(
+        JSON.stringify({
+          type: "syncProgress",
+          requestId,
+          message: "Preserved stopped state",
+          progress: 95,
+        })
+      );
+    }
+
+    // Acknowledge the event to prevent it from being broadcasted again
+    if (changeId) {
+      await acknowledgeEvent(null, changeId);
+    }
+
+    // Final success - determine final state
+    const finalState = keepRunning || wasRunning ? "running" : "stopped";
+    ws.send(
+      JSON.stringify({
+        type: "syncCompleted",
+        requestId,
+        app: { ...latestApp, status: finalState },
+        message: "Sync completed successfully",
+        progress: 100,
+      })
+    );
+
+    // Acknowledge the event after successful sync
+    if (payload.eventId) {
+      const ackSuccess = await acknowledgeEvent(
+        payload.eventId,
+        payload.changeId
+      );
+      if (ackSuccess) {
+        console.log(`✅ Event ${payload.eventId} acknowledged successfully`);
+      } else {
+        console.warn(`⚠️  Failed to acknowledge event ${payload.eventId}`);
+      }
+    }
+  } catch (error) {
+    console.error(chalk.red("❌ Sync failed:", error.message || error));
+    ws.send(
+      JSON.stringify({
+        type: "syncFailed",
+        requestId,
+        error: error.message || String(error),
+      })
+    );
+  }
+}
+
+/**
+ * Change app version:
+ * - Stops & removes existing containers
+ * - Fetches the specified version from Backstage
+ * - Regenerates docker-compose and runs the app with the selected version
+ */
+async function handleChangeVersion(ws, payload = {}) {
+  const { backstageId, id, targetVersion, requestId } = payload;
+
+  try {
+    // Extract backstageId from id if needed
+    const actualBackstageId =
+      backstageId ||
+      (id && id.startsWith("backstage-") ? id.replace("backstage-", "") : id);
+
+    if (!actualBackstageId) {
+      throw new Error("backstageId or id required for version change");
+    }
+
+    if (!targetVersion) {
+      throw new Error("targetVersion is required");
+    }
+
+    ws.send(
+      JSON.stringify({
+        type: "versionChangeProgress",
+        requestId,
+        message: "Starting version change...",
+        progress: 10,
+      })
+    );
+
+    // Fetch app info from Backstage
+    ws.send(
+      JSON.stringify({
+        type: "versionChangeProgress",
+        requestId,
+        message: "Fetching app info from Backstage...",
+        progress: 15,
+      })
+    );
+
+    const session = loadSession();
+    if (!session || !session.token) {
+      throw new Error("No valid session found. Please run: fenwave login");
+    }
+
+    // Fetch app metadata
+    const appUrl = `${APP_BUILDER_URL}/api/app-builder/applications/${actualBackstageId}`;
+    const appResponse = await axios.get(appUrl, {
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${session.token}`,
+      },
+      timeout: 10000,
+    });
+
+    const fetchedApp = appResponse.data;
+
+    // Fetch all versions
+    ws.send(
+      JSON.stringify({
+        type: "versionChangeProgress",
+        requestId,
+        message: "Fetching target version...",
+        progress: 20,
+      })
+    );
+
+    const versionsUrl = `${APP_BUILDER_URL}/api/app-builder/applications/${actualBackstageId}/versions`;
+    const versionsResponse = await axios.get(versionsUrl, {
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${session.token}`,
+      },
+      timeout: 10000,
+    });
+
+    const allVersions = versionsResponse.data || [];
+
+    // Find the target version
+    const versionData = allVersions.find((v) => v.version === targetVersion);
+
+    if (!versionData) {
+      throw new Error(`Version ${targetVersion} not found`);
+    }
+
+    ws.send(
+      JSON.stringify({
+        type: "versionChangeProgress",
+        requestId,
+        message: `Switching to version ${targetVersion}...`,
+        progress: 25,
+      })
+    );
+
+    // Build the app object with the target version's data
+    const targetApp = {
+      id: `backstage-${actualBackstageId}`,
+      backstageId: actualBackstageId,
+      name: fetchedApp.name,
+      nodes: versionData.nodes || [],
+      edges: versionData.edges || [],
+      description: versionData.description || fetchedApp.description || "",
+      version: targetVersion,
+      status: versionData.status || "published",
+      source: "backstage",
+    };
+
+    // Normalize app name for container matching
+    const appName = targetApp.name.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+
+    // Detect existing containers
+    const containers = await docker.listContainers({ all: true });
+    const appContainers = containers.filter((container) => {
+      const containerName = container.Names[0].replace(/^\//, "");
+      const projectLabel = container.Labels["com.docker.compose.project"];
+      return (
+        containerName.startsWith(appName) ||
+        projectLabel === appName ||
+        container.Labels["app"] === appName
+      );
+    });
+
+    ws.send(
+      JSON.stringify({
+        type: "versionChangeProgress",
+        requestId,
+        message: `Stopping ${appContainers.length} containers...`,
+        progress: 30,
+      })
+    );
+
+    // Stop running containers
+    for (const c of appContainers) {
+      try {
+        if (c.State === "running") {
+          await docker.getContainer(c.Id).stop();
+        }
+      } catch (err) {
+        console.warn("Error stopping container", c.Id, err.message);
+      }
+    }
+
+    ws.send(
+      JSON.stringify({
+        type: "versionChangeProgress",
+        requestId,
+        message: "Removing old containers...",
+        progress: 50,
+      })
+    );
+
+    // Remove containers
+    for (const c of appContainers) {
+      try {
+        await docker.getContainer(c.Id).remove({ force: true });
+      } catch (err) {
+        console.warn("Error removing container", c.Id, err.message);
+      }
+    }
+
+    // Prepare YAML for the target version and run
+    const yamlContent = convertNodesToYAML(targetApp);
+
+    ws.send(
+      JSON.stringify({
+        type: "versionChangeProgress",
+        requestId,
+        message: "Creating containers for new version...",
+        progress: 70,
+      })
+    );
+
+    // Reuse runBackstageApp flow to create docker-compose and run
+    await runBackstageApp(ws, targetApp, yamlContent, requestId);
+
+    console.log(
+      `✅ Application "${targetApp.name} (${targetVersion})" version changed successfully!`
+    );
+
+    ws.send(
+      JSON.stringify({
+        type: "versionChangeCompleted",
+        requestId,
+        app: { ...targetApp, status: "running" },
+        message: `Successfully changed to version ${targetVersion}`,
+        progress: 100,
+      })
+    );
+  } catch (error) {
+    console.error(
+      chalk.red("❌ Version change failed:", error.message || error)
+    );
+    ws.send(
+      JSON.stringify({
+        type: "versionChangeFailed",
+        requestId,
+        error: error.message || String(error),
+      })
+    );
+  }
+}
+
+export default { handleAppAction, checkAppHasBeenRun };
+
+export { handleAppAction, checkAppHasBeenRun };