@oussema_mili/test-pkg-123 1.1.32

package/docker-actions/apps.js

@@ -0,0 +1,3913 @@
+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, spawn } 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 {
+  createAppLogger,
+  getRecentLogs,
+  readLogFile,
+} from "../utils/appLogger.js";
+import {
+  toDockerComposeConfig,
+  generateHostEnvScript,
+  generateEnvFile,
+  generateComposeDeploy,
+} from "./config-transformer.js";
+import setupTasks from "./setup-tasks.js";
+
+// ES Module equivalent of __dirname
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Helper to get current backend URL (loaded fresh each time to pick up config changes)
+function getBackendUrl() {
+  const config = loadConfig();
+  return 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;
+}
+
+/**
+ * Filter containers by app identity using fwId labels
+ * This is the centralized function for matching containers to a specific app version
+ * @param {Array} containers - List of Docker containers
+ * @param {string} fwId - The Fenwave entity ID
+ * @param {boolean} isDraft - Whether the app is a draft
+ * @param {string} appVersion - The app version (only used for published apps)
+ * @returns {Array} - Filtered containers belonging to this specific app
+ */
+function filterContainersByApp(containers, fwId, isDraft, appVersion) {
+  return containers.filter((container) => {
+    const containerFwId = container.Labels["app.fwId"];
+    const containerIsDraft = container.Labels["app.isDraft"];
+    const containerVersion = container.Labels["app.version"];
+
+    // Match by fwId and draft/version status
+    if (containerFwId === fwId) {
+      if (isDraft) return containerIsDraft === "true";
+      return containerIsDraft !== "true" && containerVersion === appVersion;
+    }
+
+    return false;
+  });
+}
+
+/**
+ * Filter containers for any version of a published app (ignores version label)
+ * @param {Array} containers - List of Docker containers
+ * @param {string} fwId - The Fenwave entity ID
+ * @returns {Array} - Filtered containers belonging to this app (any version)
+ */
+function filterContainersAnyVersion(containers, fwId) {
+  return containers.filter((container) => {
+    const containerFwId = container.Labels["app.fwId"];
+    const containerIsDraft = container.Labels["app.isDraft"];
+    return containerFwId === fwId && containerIsDraft !== "true";
+  });
+}
+
+/**
+ * Select the most relevant container from a list deterministically
+ * Prioritizes: 1) running containers, 2) most recently started, 3) newest created
+ * @param {Array} containers - List of Docker containers
+ * @returns {object|null} - The selected container or null if array is empty
+ */
+function selectMostRelevantContainer(containers) {
+  if (!containers || containers.length === 0) return null;
+  if (containers.length === 1) return containers[0];
+
+  // Prioritize running containers
+  const runningContainers = containers.filter((c) => c.State === "running");
+  const candidatePool =
+    runningContainers.length > 0 ? runningContainers : containers;
+
+  // Sort by Created timestamp descending (newest first)
+  const sortedByCreated = [...candidatePool].sort(
+    (a, b) => b.Created - a.Created,
+  );
+
+  return sortedByCreated[0];
+}
+
+/**
+ * Substitute setup wizard variables in an object (deep replacement)
+ * Replaces {{VARIABLE_NAME}} patterns with values from the variables object
+ * @param {any} obj - Object to substitute variables in
+ * @param {Record<string, string>} variables - Variables to substitute
+ * @returns {any} - Object with variables substituted
+ */
+function substituteSetupVariables(obj, variables) {
+  if (!variables || Object.keys(variables).length === 0) {
+    return obj;
+  }
+
+  const substitute = (value) => {
+    if (typeof value === "string") {
+      // Replace {{VARIABLE_NAME}} patterns
+      return value.replace(/\{\{([^}]+)\}\}/g, (match, varName) => {
+        const trimmedName = varName.trim();
+        if (variables[trimmedName] !== undefined) {
+          return variables[trimmedName];
+        }
+        // Return original if variable not found
+        return match;
+      });
+    }
+    if (Array.isArray(value)) {
+      return value.map(substitute);
+    }
+    if (value && typeof value === "object") {
+      const result = {};
+      for (const key of Object.keys(value)) {
+        result[key] = substitute(value[key]);
+      }
+      return result;
+    }
+    return value;
+  };
+
+  return substitute(obj);
+}
+
+/**
+ * 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 backendUrl = getBackendUrl();
+
+    const response = await axios.post(
+      `${backendUrl}/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 "cleanApp":
+      return await handleCleanApp(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);
+    case "fetchAppLogs":
+      return await handleFetchAppLogs(ws, payload);
+    case "fetchLogContent":
+      return await handleFetchLogContent(ws, payload);
+    default:
+      throw new Error(`Unknown app action: ${action}`);
+  }
+}
+
+// Fetch recent logs for an app (or all apps)
+async function handleFetchAppLogs(ws, payload) {
+  const { appName, limit = 20, requestId } = payload;
+
+  try {
+    const logs = getRecentLogs(appName, limit);
+
+    ws.send(
+      JSON.stringify({
+        type: "appLogs",
+        logs: logs.map((log) => ({
+          filename: log.filename,
+          createdAt: log.createdAt.toISOString(),
+          size: log.size,
+        })),
+        requestId,
+      }),
+    );
+  } catch (error) {
+    ws.send(
+      JSON.stringify({
+        type: "error",
+        error: `Failed to fetch logs: ${error.message}`,
+        requestId,
+      }),
+    );
+  }
+}
+
+// Fetch content of a specific log file
+async function handleFetchLogContent(ws, payload) {
+  const { filename, requestId } = payload;
+
+  try {
+    const content = readLogFile(filename);
+
+    if (content === null) {
+      ws.send(
+        JSON.stringify({
+          type: "error",
+          error: `Log file not found: ${filename}`,
+          requestId,
+        }),
+      );
+      return;
+    }
+
+    ws.send(
+      JSON.stringify({
+        type: "logContent",
+        filename,
+        content,
+        requestId,
+      }),
+    );
+  } catch (error) {
+    ws.send(
+      JSON.stringify({
+        type: "error",
+        error: `Failed to read log: ${error.message}`,
+        requestId,
+      }),
+    );
+  }
+}
+
+// Fetch published applications from Fenwave app-builder
+async function fetchFenwaveApps(userEntityRef) {
+  const backendUrl = getBackendUrl();
+  if (!backendUrl) {
+    console.warn("Backend URL not configured, skipping Fenwave apps");
+    return [];
+  }
+
+  try {
+    // Load session token for authentication
+    const session = loadSession();
+    if (!session || !session.token) {
+      console.warn(
+        "No valid session found, skipping Fenwave apps. Please run: fenwave login",
+      );
+      return [];
+    }
+
+    const url = `${backendUrl}/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 Fenwave 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 Fenwave 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 Fenwave apps to local app format (now async to check container status)
+    return await Promise.all(allApps.map((app) => transformFenwaveApp(app)));
+  } catch (error) {
+    console.error("Failed to fetch Fenwave apps:", error.message);
+    return [];
+  }
+}
+
+// Transform Fenwave app to local app format
+async function transformFenwaveApp(fenwaveApp) {
+  // Fetch all versions for this app
+  const session = loadSession();
+  let allVersions = [];
+
+  const backendUrl = getBackendUrl();
+  if (session && session.token && backendUrl) {
+    try {
+      const versionsResponse = await axios.get(
+        `${backendUrl}/api/app-builder/applications/${fenwaveApp.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 ${fenwaveApp.id}:`,
+        err.message,
+      );
+    }
+  }
+
+  // If no versions found, use activeVersion from app
+  if (allVersions.length === 0 && fenwaveApp.activeVersion) {
+    allVersions = [fenwaveApp.activeVersion];
+  }
+
+  // Check if there are running Docker containers for this app
+  const appName = fenwaveApp.name.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+  const fwId = fenwaveApp.id;
+  const isDraft = fenwaveApp.status === "draft";
+  const appVersion = fenwaveApp.activeVersion?.version || "1.0.0";
+
+  // Get container info to determine which version is running (or: has ran) locally
+  let appContainers = [];
+  let runningVersion = null; // Track which version is actually running
+
+  try {
+    const allContainers = await docker.listContainers({ all: true });
+
+    // For published apps, find containers for ANY version of this app (not just the latest)
+    if (isDraft) {
+      appContainers = filterContainersByApp(
+        allContainers,
+        fwId,
+        isDraft,
+        appVersion,
+      );
+    } else {
+      // For published apps, filter by fwId only, not by version (use shared helper)
+      appContainers = filterContainersAnyVersion(allContainers, fwId);
+    }
+
+    // Try to determine the running version from container labels (deterministically)
+    if (appContainers.length > 0) {
+      // Select the most relevant container (running > newest created)
+      const selectedContainer = selectMostRelevantContainer(appContainers);
+      if (selectedContainer) {
+        const versionLabel = selectedContainer.Labels["app.version"];
+        if (versionLabel) {
+          runningVersion = versionLabel;
+        }
+      }
+    }
+  } catch (error) {
+    console.error(
+      `Error checking containers for app ${appName}:`,
+      error.message,
+    );
+  }
+
+  const containerCount = appContainers.length;
+  const hasRunningContainer = appContainers.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 (appContainers.length > 0) {
+    const creationTimestamps = appContainers.map((c) =>
+      new Date(c.Created * 1000).getTime(),
+    );
+    const oldestCreationTimestamp = Math.min(...creationTimestamps);
+
+    const startTimestamps = [];
+    for (const container of appContainers) {
+      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 || fenwaveApp.description || "Fenwave 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 versionToUse = runningVersion || activeVersion.version || "1.0.0";
+
+  // Get nodes/edges from the version that's actually being used
+  const versionData = runningVersion
+    ? allVersions.find((v) => v.version === runningVersion) || activeVersion
+    : activeVersion;
+
+  const nodes = versionData.nodes || [];
+  const componentTypes = nodes.map((n) => n?.data?.type).filter(Boolean);
+  const language = componentTypes[0] || "Unknown";
+
+  // Extract localSetup from the version being used
+  const localSetup = versionData.deploymentConfig?.localSetup || null;
+
+  return {
+    id: `fw-${fenwaveApp.id}`,
+    name: fenwaveApp.name,
+    description:
+      fenwaveApp.description ||
+      versionData.description ||
+      "Fenwave application",
+    language: language,
+    status: appStatus,
+    containers: containerCount,
+    firstRun: firstRunTime,
+    lastRun: lastRunTime,
+    url: "N/A", // Will be set after running
+    repo: fenwaveApp.metadata?.repo || "N/A",
+    icon: fenwaveApp.name.substring(0, 1).toUpperCase(),
+    source: "fenwave",
+    fwId: fenwaveApp.id,
+    fwStatus: activeVersion.status || fenwaveApp.status,
+    version: versionToUse,
+    tags: versionData.tags || [],
+    nodes: nodes,
+    edges: versionData.edges || [],
+    createdBy: fenwaveApp.created_by,
+    publishedAt: fenwaveApp.published_at,
+    publishedBy: fenwaveApp.published_by,
+    versions: transformedVersions,
+    localSetup: localSetup,
+  };
+}
+
+// Helper function to find apps (Fenwave only)
+async function findApps(userEntityRef) {
+  try {
+    // Only fetch Fenwave apps (no local Docker containers)
+    const fenwaveApps = await fetchFenwaveApps(userEntityRef);
+
+    return fenwaveApps;
+  } 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 + Fenwave)
+    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 { fwId, requestId } = payload;
+
+    if (!fwId) {
+      throw new Error("fwId is required");
+    }
+
+    const backendUrl = getBackendUrl();
+    if (!backendUrl) {
+      throw new Error("Backend 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 = `${backendUrl}/api/app-builder/applications/${fwId}`;
+    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 = `${backendUrl}/api/app-builder/applications/${fwId}/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: fwId,
+        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 Fenwave
+      const apps = await findApps(userEntityRef);
+      const app = apps.find(
+        (a) =>
+          a.name === appName ||
+          a.name.replace(/[^a-z0-9-]/gi, "-").toLowerCase() ===
+            normalizedAppName,
+      );
+
+      if (app) {
+        // Get app identity info for container matching
+        const isDraft = app.fwStatus === "draft";
+        const appVersion = app.version || "1.0.0";
+        const fwId = app.fwId || app.id;
+
+        // Check if containers exist for this specific app using centralized filter
+        const allContainers = await docker.listContainers({ all: true });
+        const appContainers = filterContainersByApp(
+          allContainers,
+          fwId,
+          isDraft,
+          appVersion,
+        );
+
+        // 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;
+          }
+
+          // Create a logger for this app run
+          const logger = createAppLogger(app.name, appVersion);
+
+          if (isDraft) {
+            logger.info(`Starting draft "${app.name}"...`);
+          } else {
+            logger.info(
+              `Starting application "${app.name}" version ${appVersion}...`,
+            );
+          }
+
+          // Start any stopped containers
+          for (const container of appContainers) {
+            if (container.State !== "running") {
+              logger.info(`Starting container ${container.Names[0]}...`);
+              await docker.getContainer(container.Id).start();
+            }
+          }
+
+          if (isDraft) {
+            logger.success(`Draft "${app.name}" started successfully!`);
+          } else {
+            logger.success(
+              `Application "${app.name}" version ${appVersion} started successfully!`,
+            );
+          }
+
+          logger.complete(true, "Application started");
+
+          ws.send(
+            JSON.stringify({
+              type: "runCompleted",
+              app: {
+                ...app,
+                status: "running",
+                containers: appContainers.length,
+              },
+              requestId,
+              logFile: logger.filename,
+            }),
+          );
+          return;
+        }
+
+        // No containers exist - run the app for the first time
+        await runFenwaveApp(ws, app, yamlContent, requestId);
+        return;
+      }
+
+      // App not found in Fenwave - run as a new YAML-based app
+      const newApp = {
+        id: `app-${Date.now()}`,
+        name: appName,
+        fwId: null,
+        source: "yaml",
+      };
+
+      await runFenwaveApp(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");
+    }
+
+    const isDraft = app.fwStatus === "draft";
+    const fwId = app.fwId || app.id;
+
+    // First, find all containers for this app to determine the actual running version
+    const allContainers = await docker.listContainers({ all: true });
+    let actualVersion = app.version || "1.0.0";
+
+    if (!isDraft) {
+      const anyAppContainers = filterContainersAnyVersion(allContainers, fwId);
+
+      // If containers exist, use the version from the most relevant container
+      // (prioritizes running > newest created to avoid picking stale versions)
+      if (anyAppContainers.length > 0) {
+        const selectedContainer = selectMostRelevantContainer(anyAppContainers);
+        if (selectedContainer) {
+          const versionLabel = selectedContainer.Labels["app.version"];
+          if (versionLabel) {
+            actualVersion = versionLabel;
+          }
+        }
+      }
+    }
+
+    const appVersion = actualVersion;
+
+    // Find containers belonging to this specific app version using centralized filter
+    const appContainers = filterContainersByApp(
+      allContainers,
+      fwId,
+      isDraft,
+      appVersion,
+    );
+
+    // 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";
+
+      // Create a logger for this app run
+      const logger = createAppLogger(app.name, runningVersion);
+
+      // Log with appropriate format for draft vs published
+      if (isDraft) {
+        logger.info(`Starting draft "${app.name}"...`);
+      } else {
+        logger.info(
+          `Starting application "${app.name}" version ${runningVersion}...`,
+        );
+      }
+
+      for (const container of appContainers) {
+        if (container.State !== "running") {
+          logger.info(`Starting container ${container.Names[0]}...`);
+          await docker.getContainer(container.Id).start();
+        }
+      }
+
+      if (isDraft) {
+        logger.success(`Draft "${app.name}" started successfully!`);
+      } else {
+        logger.success(
+          `Application "${app.name}" version ${runningVersion} started successfully!`,
+        );
+      }
+
+      logger.complete(true, "Application started");
+
+      ws.send(
+        JSON.stringify({
+          type: "appStarted",
+          app: {
+            ...app,
+            status: "running",
+            containers: appContainers.length,
+          },
+          requestId,
+          logFile: logger.filename,
+        }),
+      );
+      return;
+    }
+
+    // No containers exist - run the app for the first time
+    if (app.source === "fenwave" && app.nodes && app.nodes.length > 0) {
+      // Convert Fenwave app to YAML and run
+      const yamlContent = convertNodesToYAML(app);
+      await runFenwaveApp(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");
+    }
+
+    const isDraft = app.fwStatus === "draft";
+    const appVersion = app.version || "1.0.0";
+    const fwId = app.fwId || app.id;
+
+    // Find containers belonging to this specific app using centralized filter
+    const allContainers = await docker.listContainers({ all: true });
+    const appContainers = filterContainersByApp(
+      allContainers,
+      fwId,
+      isDraft,
+      appVersion,
+    );
+
+    // 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";
+
+    // 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");
+    }
+
+    const isDraft = app.fwStatus === "draft";
+    const appVersion = app.version || "1.0.0";
+    const fwId = app.fwId || app.id;
+
+    // Find containers belonging to this specific app using centralized filter
+    const allContainers = await docker.listContainers({ all: true });
+    const appContainers = filterContainersByApp(
+      allContainers,
+      fwId,
+      isDraft,
+      appVersion,
+    );
+
+    // 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";
+
+    // 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.fwId || app.id;
+    const isDraft = app.fwStatus === "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 fenwave, delete from backend database
+    if (app.source === "fenwave" && app.fwId) {
+      // 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 backendUrl = getBackendUrl();
+      const deleteUrl = `${backendUrl}/api/app-builder/applications/${app.fwId}`;
+
+      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 cleaning an app - removes containers, volumes, networks, and workspace
+ * Unlike deleteApp, this does NOT delete from Fenwave backend
+ */
+async function handleCleanApp(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 isDraft = app.fwStatus === "draft";
+    const appName = app.name.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+    const fwId = app.fwId || app.id;
+    const appId = fwId;
+
+    // Log start of cleanup
+    if (isDraft) {
+      console.log(`🧹 Cleaning draft "${app.name}"...`);
+    } else {
+      console.log(`🧹 Cleaning application "${app.name}" (${appVersion})...`);
+    }
+
+    // Find containers belonging to this app
+    const allContainers = await docker.listContainers({ all: true });
+
+    // Use centralized filter for labeled containers
+    let appContainers = filterContainersByApp(
+      allContainers,
+      fwId,
+      isDraft,
+      appVersion,
+    );
+
+    // Also include fallback for older containers without fwId label (for cleanup only)
+    if (appContainers.length === 0) {
+      appContainers = allContainers.filter((container) => {
+        const projectLabel = container.Labels["com.docker.compose.project"];
+        return (
+          projectLabel === appName ||
+          projectLabel === `${appName}-${appVersion}`
+        );
+      });
+    }
+
+    // Collect networks and volumes before removing containers
+    const networksToRemove = new Set();
+    const volumesToRemove = new Set();
+
+    for (const container of appContainers) {
+      // Get container details to find networks and volumes
+      const containerInfo = await docker.getContainer(container.Id).inspect();
+
+      // Collect networks
+      if (containerInfo.NetworkSettings?.Networks) {
+        Object.keys(containerInfo.NetworkSettings.Networks).forEach(
+          (network) => {
+            // Don't remove default networks
+            if (!["bridge", "host", "none"].includes(network)) {
+              networksToRemove.add(network);
+            }
+          },
+        );
+      }
+
+      // Collect volumes
+      if (containerInfo.Mounts) {
+        containerInfo.Mounts.forEach((mount) => {
+          if (mount.Type === "volume" && mount.Name) {
+            volumesToRemove.add(mount.Name);
+          }
+        });
+      }
+    }
+
+    // Stop and remove all containers
+    let containersRemoved = 0;
+    for (const container of appContainers) {
+      try {
+        const containerObj = docker.getContainer(container.Id);
+        if (container.State === "running") {
+          await containerObj.stop();
+        }
+        await containerObj.remove({ force: true });
+        containersRemoved++;
+      } catch (err) {
+        console.warn(
+          `⚠️  Failed to remove container ${container.Names[0]}: ${err.message}`,
+        );
+      }
+    }
+    console.log(`   Removed ${containersRemoved} container(s)`);
+
+    // Remove volumes
+    let volumesRemoved = 0;
+    for (const volumeName of volumesToRemove) {
+      try {
+        await docker.getVolume(volumeName).remove();
+        volumesRemoved++;
+      } catch (err) {
+        // Volume might be in use by other containers or already removed
+        if (
+          !err.message.includes("in use") &&
+          !err.message.includes("No such volume")
+        ) {
+          console.warn(
+            `⚠️  Failed to remove volume ${volumeName}: ${err.message}`,
+          );
+        }
+      }
+    }
+    if (volumesRemoved > 0) {
+      console.log(`   Removed ${volumesRemoved} volume(s)`);
+    }
+
+    // Remove networks
+    let networksRemoved = 0;
+    for (const networkName of networksToRemove) {
+      try {
+        await docker.getNetwork(networkName).remove();
+        networksRemoved++;
+      } catch (err) {
+        // Network might be in use or already removed
+        if (
+          !err.message.includes("has active endpoints") &&
+          !err.message.includes("No such network")
+        ) {
+          console.warn(
+            `⚠️  Failed to remove network ${networkName}: ${err.message}`,
+          );
+        }
+      }
+    }
+    if (networksRemoved > 0) {
+      console.log(`   Removed ${networksRemoved} network(s)`);
+    }
+
+    // Delete workspace folder
+    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);
+      console.log(`   Removed workspace folder`);
+    }
+
+    // Success log
+    if (isDraft) {
+      console.log(`✅ Draft "${app.name}" cleaned successfully!`);
+    } else {
+      console.log(
+        `✅ Application "${app.name}" (${appVersion}) cleaned successfully!`,
+      );
+    }
+
+    ws.send(
+      JSON.stringify({
+        type: "appCleaned",
+        id,
+        success: true,
+        containersRemoved,
+        volumesRemoved,
+        networksRemoved,
+        requestId,
+      }),
+    );
+  } catch (error) {
+    console.error("Error cleaning app:", error);
+    ws.send(
+      JSON.stringify({
+        type: "error",
+        error: "Failed to clean app: " + error.message,
+        requestId: payload.requestId,
+      }),
+    );
+  }
+}
+
+/**
+ * Handle deletion of specific app versions
+ */
+async function handleDeleteAppVersions(ws, payload) {
+  try {
+    const { appName, fwId, 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 = fwId || 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,
+        fwId,
+        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 backendUrl = getBackendUrl();
+    const url = `${backendUrl}/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 app identity
+    service.labels = {
+      "app.version": version,
+      "app.name": name,
+      "app.fwId": appDefinition.application.fwId || "",
+      "app.isDraft": appDefinition.application.isDraft ? "true" : "false",
+    };
+
+    // 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
+    if (
+      component.depends_on &&
+      Array.isArray(component.depends_on) &&
+      component.depends_on.length > 0
+    ) {
+      service.depends_on = component.depends_on.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];
+      }
+    }
+
+    // Mount Docker socket if requested
+    if (component.mountDockerSocket) {
+      const platform = process.platform;
+      let dockerSocketMount;
+
+      if (platform === "win32") {
+        // Windows with Docker Desktop uses named pipe
+        dockerSocketMount = "//var/run/docker.sock:/var/run/docker.sock";
+      } else {
+        // Linux and macOS (Docker Desktop handles the mapping)
+        dockerSocketMount = "/var/run/docker.sock:/var/run/docker.sock";
+      }
+
+      service.volumes = [...(service.volumes || []), dockerSocketMount];
+    }
+
+    // Final cleanup of undefined
+    services[serviceName] = Object.fromEntries(
+      Object.entries(service).filter(([, value]) => value !== undefined),
+    );
+  }
+
+  // Log all services volumes before compose
+  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);
+
+  // Debug: Log the proxy service volumes in final YAML
+  fs.writeFileSync(outputPath, yamlStr, "utf8");
+}
+
+// Convert Fenwave 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;
+      }
+
+      // Add mountDockerSocket flag - check both config and data level
+      const hasMountDockerSocket =
+        config.mountDockerSocket || node.data.mountDockerSocket;
+      if (hasMountDockerSocket) {
+        component.mountDockerSocket = true;
+      }
+
+      return component;
+    });
+
+  const appDefinition = {
+    application: {
+      name: app.name.replace(/[^a-z0-9-]/gi, "-").toLowerCase(),
+      version: app.version || "1.0.0",
+      components: components,
+    },
+  };
+
+  const yamlOutput = yaml.dump(appDefinition);
+
+  return yamlOutput;
+}
+
+// Run a Fenwave app
+async function runFenwaveApp(ws, app, yamlContent, requestId, context = {}) {
+  const {
+    isSync = false,
+    isVersionChange = false,
+    targetVersion = null,
+  } = context;
+
+  // Determine if this is a draft or published app
+  const isDraft = app.fwStatus === "draft" || app.status === "draft";
+  const appVersion = app.version || "1.0.0";
+
+  // Create a logger for this app run
+  const logger = createAppLogger(app.name, appVersion);
+
+  try {
+    // Log with appropriate format for draft vs published
+    if (!isSync) {
+      if (isDraft) {
+        logger.info(`Starting draft "${app.name}"...`);
+      } else {
+        logger.info(
+          `Starting application "${app.name}" version ${appVersion}...`,
+        );
+      }
+    }
+
+    // Send run started notification with log file path
+    ws.send(
+      JSON.stringify({
+        type: "runStarted",
+        requestId,
+        logFile: logger.filename,
+        logPath: logger.logPath,
+      }),
+    );
+
+    // Resolve workspace path (check registry or create new)
+    const appId = app.fwId || 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);
+
+    // Add fwId and isDraft to appDefinition for container labeling
+    if (appDefinition.application) {
+      appDefinition.application.fwId = app.fwId || app.id;
+      appDefinition.application.isDraft = isDraft;
+    }
+
+    // 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;
+          }
+        }
+      }
+    }
+
+    // Load setup wizard variables and substitute in app definition
+    logger.info(
+      `Loading setup wizard progress for appId=${appId}, version=${appVersion}`,
+    );
+    const setupProgress = setupTasks.loadSetupProgress(appId, appVersion);
+    let finalAppDefinition = appDefinition;
+    if (setupProgress) {
+      if (
+        setupProgress.variables &&
+        Object.keys(setupProgress.variables).length > 0
+      ) {
+        logger.info(`📋 Setup wizard variables:`);
+        for (const [key, value] of Object.entries(setupProgress.variables)) {
+          logger.info(`   ${key} = ${value}`);
+        }
+        finalAppDefinition = substituteSetupVariables(
+          appDefinition,
+          setupProgress.variables,
+        );
+        logger.success(
+          `✅ Applied ${Object.keys(setupProgress.variables).length} setup variable(s)`,
+        );
+      }
+    } else {
+      logger.info(`No setup wizard configuration for this app`);
+    }
+
+    // Generate Docker Compose file directly
+    const dockerComposePath = path.join(appDownloadDir, "docker-compose.yml");
+    generateDockerCompose(
+      finalAppDefinition,
+      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) {
+        logger.success(`Draft "${app.name}" synced successfully!`);
+      } else {
+        logger.success(
+          `Application "${app.name} (${appVersion})" synced successfully!`,
+        );
+      }
+      logger.info(`Starting containers...`);
+    }
+
+    logger.info(`Starting containers with docker-compose...`);
+    logger.info(`Working directory: ${appDownloadDir}`);
+    logger.info(`Command: docker compose up -d`);
+
+    // Notify DevApp that docker-compose is starting
+    ws.send(
+      JSON.stringify({
+        type: "runProgress",
+        message:
+          "Starting containers... This may take a while if images need to be pulled.",
+        phase: "docker-compose",
+        logFile: logger.filename,
+        requestId,
+      }),
+    );
+
+    // Use spawn for real-time logging of docker-compose output
+    const spawnProcess = spawn("sh", ["-c", dockerComposeCommand], {
+      cwd: appDownloadDir,
+      env: { ...process.env },
+    });
+
+    let stdoutBuffer = "";
+    let stderrBuffer = "";
+
+    // Capture stdout in real-time
+    spawnProcess.stdout.on("data", (data) => {
+      const output = data.toString();
+      stdoutBuffer += output;
+      logger.docker(output, "stdout");
+    });
+
+    // Capture stderr in real-time (docker-compose outputs progress to stderr)
+    spawnProcess.stderr.on("data", (data) => {
+      const output = data.toString();
+      stderrBuffer += output;
+      logger.docker(output, "stderr");
+    });
+
+    spawnProcess.on("close", async (code) => {
+      if (code !== 0) {
+        // Log error
+        logger.error(`Docker Compose exited with code ${code}`);
+        logger.complete(false, stderrBuffer || `Exit code: ${code}`);
+
+        // 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 });
+            logger.info(`Cleaned up failed workspace: ${appDownloadDir}`);
+          } catch (cleanupErr) {
+            logger.warn(`Failed to clean up workspace: ${cleanupErr.message}`);
+          }
+        }
+
+        // Send detailed error to DevApp with log file
+        ws.send(
+          JSON.stringify({
+            type: "error",
+            error: `Failed to run "${app.name}": Docker Compose exited with code ${code}`,
+            details: {
+              command: "docker compose up -d",
+              stderr: stderrBuffer,
+              stdout: stdoutBuffer,
+              workspacePath: appDownloadDir,
+              exitCode: code,
+            },
+            logFile: logger.filename,
+            logPath: logger.logPath,
+            requestId,
+          }),
+        );
+        return;
+      }
+
+      // Wait a moment for containers to fully start
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+
+      // Check container status and count
+      let containerCount = 0;
+      let runningCount = 0;
+      let exitedContainers = [];
+
+      try {
+        const containers = await docker.listContainers({ all: true });
+        const allAppContainers = filterContainersByApp(
+          containers,
+          app.fwId || app.id,
+          isDraft,
+          appVersion,
+        );
+
+        containerCount = allAppContainers.length;
+
+        for (const container of allAppContainers) {
+          const containerName = container.Names[0].replace(/^\//, "");
+
+          if (container.State === "running") {
+            runningCount++;
+            logger.info(`Container ${containerName}: running`);
+          } else if (container.State === "exited") {
+            exitedContainers.push(containerName);
+            logger.warn(
+              `Container ${containerName}: exited (status: ${container.Status})`,
+            );
+          } else {
+            logger.info(`Container ${containerName}: ${container.State}`);
+          }
+        }
+      } catch (countError) {
+        logger.warn(`Error checking containers: ${countError.message}`);
+      }
+
+      // Log summary
+      logger.info(
+        `Container summary: ${runningCount}/${containerCount} running`,
+      );
+
+      if (exitedContainers.length > 0) {
+        logger.warn(`Exited containers: ${exitedContainers.join(", ")}`);
+      }
+
+      // Log success (even if some containers exited - docker-compose up succeeded)
+      if (isDraft) {
+        logger.success(`Draft "${app.name}" started successfully!`);
+      } else {
+        logger.success(
+          `Application "${app.name} (${app.version})" started successfully!`,
+        );
+      }
+      logger.info(
+        `Containers: ${runningCount} running, ${exitedContainers.length} exited`,
+      );
+      logger.complete(
+        true,
+        `${runningCount}/${containerCount} container(s) running`,
+      );
+
+      // 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 (with warning if containers exited)
+      // If this is a version change, send versionChangeCompleted instead of runCompleted
+      if (isVersionChange) {
+        ws.send(
+          JSON.stringify({
+            type: "versionChangeCompleted",
+            requestId,
+            app: {
+              ...app,
+              status: runningCount > 0 ? "running" : "stopped",
+              containers: containerCount,
+            },
+            message: `Successfully changed to version ${targetVersion || app.version}`,
+            progress: 100,
+          }),
+        );
+      } else {
+        ws.send(
+          JSON.stringify({
+            type: "runCompleted",
+            app: {
+              ...app,
+              status: runningCount > 0 ? "running" : "stopped",
+              containers: containerCount,
+            },
+            message:
+              exitedContainers.length > 0
+                ? `Application started with warnings: ${exitedContainers.length} container(s) exited`
+                : "Application ran successfully!",
+            stdout: stdoutBuffer || "Run completed",
+            stderr: stderrBuffer || "",
+            downloadPath: appDownloadDir,
+            logFile: logger.filename,
+            logPath: logger.logPath,
+            exitedContainers: exitedContainers,
+            requestId,
+          }),
+        );
+      }
+    });
+
+    spawnProcess.on("error", (error) => {
+      logger.error(`Failed to spawn docker-compose: ${error.message}`);
+      logger.complete(false, error.message);
+
+      // Send appropriate error event based on context
+      if (isVersionChange) {
+        ws.send(
+          JSON.stringify({
+            type: "versionChangeFailed",
+            requestId,
+            error: `Failed to run "${app.name}": ${error.message}`,
+          }),
+        );
+      } else {
+        ws.send(
+          JSON.stringify({
+            type: "error",
+            error: `Failed to run "${app.name}": ${error.message}`,
+            logFile: logger.filename,
+            logPath: logger.logPath,
+            requestId,
+          }),
+        );
+      }
+    });
+  } catch (error) {
+    logger.error(`Failed to run: ${error.message}`);
+    if (error.stack) {
+      logger.docker(error.stack, "stderr");
+    }
+    logger.complete(false, error.message);
+
+    // Send appropriate error event based on context
+    if (isVersionChange) {
+      ws.send(
+        JSON.stringify({
+          type: "versionChangeFailed",
+          requestId,
+          error: `Failed to run "${app.name}": ${error.message}`,
+        }),
+      );
+    } else {
+      ws.send(
+        JSON.stringify({
+          type: "error",
+          error: `Failed to run "${app.name}": ${error.message}`,
+          details: {
+            stack: error.stack,
+          },
+          logFile: logger.filename,
+          logPath: logger.logPath,
+          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 Fenwave,
+ *   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 { fwId, appData, id, requestId, keepRunning, changeId } = payload;
+  try {
+    // Extract fwId from id if needed
+    const actualFwId =
+      fwId ||
+      (id &&
+        (id.startsWith("fw-")
+          ? id.replace("fw-", "")
+          : id.startsWith("backstage-")
+            ? id.replace("backstage-", "")
+            : id));
+
+    if (!actualFwId) throw new Error("fwId 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: `fw-${actualFwId}`,
+        fwId: actualFwId,
+        name: appData.name,
+        nodes: appData.nodes,
+        edges: appData.edges,
+        description: appData.description,
+        version: appData.version,
+        status: appData.status,
+        source: "fenwave",
+      };
+    } else {
+      // Fetch from Fenwave API (called from DevApp)
+      ws.send(
+        JSON.stringify({
+          type: "syncProgress",
+          requestId,
+          message: "Fetching app info from Fenwave...",
+          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 backendUrl = getBackendUrl();
+      const appUrl = `${backendUrl}/api/app-builder/applications/${actualFwId}`;
+      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 = `${backendUrl}/api/app-builder/applications/${actualFwId}/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: `fw-${actualFwId}`,
+        fwId: actualFwId,
+        name: fetchedApp.name,
+        nodes: blueprintSource.nodes || [],
+        edges: blueprintSource.edges || [],
+        description: blueprintSource.description || "",
+        version: finalVersion,
+        status:
+          fetchedApp.status || fetchedApp.activeVersion?.status || "draft",
+        source: "fenwave",
+      };
+    }
+
+    // Resolve workspace path (use registered or create new)
+    const appId = latestApp.fwId || 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 runFenwaveApp flow to create docker-compose and run
+    await runFenwaveApp(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 Fenwave
+ * - Regenerates docker-compose and runs the app with the selected version
+ */
+async function handleChangeVersion(ws, payload = {}) {
+  const { fwId, id, targetVersion, requestId } = payload;
+
+  try {
+    // Extract fwId from id if needed
+    const actualFwId =
+      fwId ||
+      (id &&
+        (id.startsWith("fw-")
+          ? id.replace("fw-", "")
+          : id.startsWith("backstage-")
+            ? id.replace("backstage-", "")
+            : id));
+
+    if (!actualFwId) {
+      throw new Error("fwId 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 Fenwave
+    ws.send(
+      JSON.stringify({
+        type: "versionChangeProgress",
+        requestId,
+        message: "Fetching app info from Fenwave...",
+        progress: 15,
+      }),
+    );
+
+    const session = loadSession();
+    if (!session || !session.token) {
+      throw new Error("No valid session found. Please run: fenwave login");
+    }
+
+    // Fetch app metadata
+    const backendUrl = getBackendUrl();
+    const appUrl = `${backendUrl}/api/app-builder/applications/${actualFwId}`;
+    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 = `${backendUrl}/api/app-builder/applications/${actualFwId}/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: `fw-${actualFwId}`,
+      fwId: actualFwId,
+      name: fetchedApp.name,
+      nodes: versionData.nodes || [],
+      edges: versionData.edges || [],
+      description: versionData.description || fetchedApp.description || "",
+      version: targetVersion,
+      status: versionData.status || "published",
+      source: "fenwave",
+    };
+
+    // 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 runFenwaveApp flow to create docker-compose and run
+    // Pass isVersionChange context so the completion event is versionChangeCompleted
+    await runFenwaveApp(ws, targetApp, yamlContent, requestId, {
+      isVersionChange: true,
+      targetVersion,
+    });
+
+    console.log(
+      `✅ Application "${targetApp.name} (${targetVersion})" version change initiated!`,
+    );
+
+    // Note: versionChangeCompleted or versionChangeFailed will be sent by runFenwaveApp
+  } 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 };