cdd-cli 3.1.3 → 3.1.5

package/src/helpers/dockerService/serviceComponents/containerActions.js

@@ -1,13 +1,18 @@
-import { docker } from "../dockerService";
+import { docker } from "../dockerService.js";
 import { imageExists, pullImage } from "./imageUtils.js";
+import { TIMEOUTS } from "../../constants.js";
+import { logger } from "../../logger.js";
 
 /**
- * Helper to add timeout to promises
- * @param {Promise} promise - Promise to wrap
- * @param {number} ms - Timeout in milliseconds
- * @returns {Promise}
+ * Helper to add timeout to promises. If the provided promise does not settle
+ * within `ms` milliseconds it will reject with an Error.
+ *
+ * @template T
+ * @param {Promise<T>} promise - Promise to wrap
+ * @param {number} [ms=TIMEOUTS.CONTAINER_OP] - Timeout in milliseconds
+ * @returns {Promise<T>} The original promise result or a rejection on timeout
  */
-function withTimeout(promise, ms = 30000) {
+function withTimeout(promise, ms = TIMEOUTS.CONTAINER_OP) {
   return Promise.race([
     promise,
     new Promise((_, reject) => 
@@ -24,10 +29,13 @@ function withTimeout(promise, ms = 30000) {
  * @throws {Error} If Docker reports an error
  */
 export async function removeContainer(containerId) {
+  logger.debug("Removing container %s", containerId);
   const container = docker.getContainer(containerId);
   try {
-    await withTimeout(container.remove({ force: true }), 30000);
+    await withTimeout(container.remove({ force: true }), TIMEOUTS.CONTAINER_OP);
+    logger.info("Removed container %s", containerId);
   } catch (err) {
+    logger.error("Failed to remove container %s", containerId, err);
     throw new Error('Error removing container: ' + err.message);
   }
 }
@@ -41,16 +49,21 @@ export async function removeContainer(containerId) {
  * @throws {Error} If image listing/pull or creation fails
  */
 export async function createContainer(imageName, options = {}) {
+  logger.info("Creating container from image %s", imageName);
   let exists;
   try {
     exists = await withTimeout(imageExists(imageName), 10000);
   } catch (err) {
+    logger.error("Could not check local images for %s", imageName, err);
     throw new Error('Error listing local images: ' + err.message);
   }
   if (!exists) {
+    logger.info("Image %s not found locally, pulling", imageName);
     try {
-      await withTimeout(pullImage(imageName), 300000); // 5 minutes for pull
+      await withTimeout(pullImage(imageName), TIMEOUTS.PULL_IMAGE);
+      logger.info("Pulled image %s", imageName);
     } catch (err) {
+      logger.error("Failed to pull image %s", imageName, err);
       throw new Error('Could not pull image: ' + err.message);
     }
   }
@@ -59,10 +72,87 @@ export async function createContainer(imageName, options = {}) {
     Tty: true,
     ...options,
   };
+
+  const hasUserDefinedPorts = Boolean(createOpts.ExposedPorts && Object.keys(createOpts.ExposedPorts).length);
+
+  if (!hasUserDefinedPorts) {
+    try {
+      const image = docker.getImage(imageName);
+      if (image && typeof image.inspect === "function") {
+        let usedHostPorts = new Set();
+        if (typeof docker.listContainers === "function") {
+          try {
+            const containers = await withTimeout(docker.listContainers({ all: true }), TIMEOUTS.CONTAINER_OP);
+            containers.forEach((container) => {
+              (container.Ports || []).forEach((portInfo) => {
+                if (portInfo && portInfo.PublicPort) {
+                  usedHostPorts.add(String(portInfo.PublicPort));
+                }
+              });
+            });
+          } catch (err) {
+            logger.warn("Could not inspect existing containers to auto-map ports", err);
+          }
+        }
+        const reservePort = (port) => {
+          const portStr = String(port);
+          usedHostPorts.add(portStr);
+        };
+        const pickNextAvailablePort = (base) => {
+          const numericBase = Number.parseInt(base, 10);
+          if (Number.isNaN(numericBase)) {
+            // If the base port is non-numeric, just return the base.
+            if (!usedHostPorts.has(base)) {
+              usedHostPorts.add(base);
+              return base;
+            }
+            let counter = 1;
+            let candidate = `${base}-${counter}`;
+            while (usedHostPorts.has(candidate)) {
+              counter += 1;
+              candidate = `${base}-${counter}`;
+            }
+            usedHostPorts.add(candidate);
+            return candidate;
+          }
+          let candidate = numericBase;
+          while (usedHostPorts.has(String(candidate))) {
+            candidate += 1;
+          }
+          reservePort(candidate);
+          return String(candidate);
+        };
+
+        const inspectData = await withTimeout(image.inspect(), TIMEOUTS.CONTAINER_OP);
+        const exposed = inspectData?.Config?.ExposedPorts || inspectData?.ContainerConfig?.ExposedPorts || {};
+        const exposedKeys = Object.keys(exposed || {});
+        if (exposedKeys.length) {
+          createOpts.ExposedPorts = createOpts.ExposedPorts || {};
+          createOpts.HostConfig = { ...(createOpts.HostConfig || {}) };
+          createOpts.HostConfig.PortBindings = { ...(createOpts.HostConfig.PortBindings || {}) };
+          exposedKeys.forEach((portKey) => {
+            if (!createOpts.ExposedPorts[portKey]) {
+              createOpts.ExposedPorts[portKey] = exposed[portKey] || {};
+            }
+            if (!createOpts.HostConfig.PortBindings[portKey] || !createOpts.HostConfig.PortBindings[portKey].length) {
+              const containerPort = portKey.split("/")[0];
+              const hostPort = pickNextAvailablePort(containerPort);
+              createOpts.HostConfig.PortBindings[portKey] = [{ HostPort: hostPort }];
+            }
+          });
+        }
+      }
+    } catch (err) {
+      logger.warn("Could not inspect image %s for default ports", imageName, err);
+    }
+  }
   try {
-    const container = await withTimeout(docker.createContainer(createOpts), 30000);
+    const container = await withTimeout(docker.createContainer(createOpts), TIMEOUTS.CONTAINER_OP);
+    const containerId = container.id || container.Id;
+    logger.info("Created container %s from image %s", containerId, imageName);
     return container.id || container.Id;
   } catch (err) {
+    logger.error("Failed to create container from image %s", imageName, err);
     throw new Error('Error creating container: ' + err.message);
   }
 }
@@ -74,7 +164,14 @@ export async function createContainer(imageName, options = {}) {
  */
 export async function startContainer(containerId) {
   const container = docker.getContainer(containerId);
-  await withTimeout(container.start(), 30000);
+  logger.debug("Starting container %s", containerId);
+  try {
+    await withTimeout(container.start(), TIMEOUTS.CONTAINER_OP);
+    logger.info("Started container %s", containerId);
+  } catch (err) {
+    logger.error("Failed to start container %s", containerId, err);
+    throw err;
+  }
 }
 
 /**
@@ -84,7 +181,14 @@ export async function startContainer(containerId) {
  */
 export async function stopContainer(containerId) {
   const container = docker.getContainer(containerId);
-  await withTimeout(container.stop(), 30000);
+  logger.debug("Stopping container %s", containerId);
+  try {
+    await withTimeout(container.stop(), TIMEOUTS.CONTAINER_OP);
+    logger.info("Stopped container %s", containerId);
+  } catch (err) {
+    logger.error("Failed to stop container %s", containerId, err);
+    throw err;
+  }
 }
 
 /**
@@ -94,5 +198,12 @@ export async function stopContainer(containerId) {
  */
 export async function restartContainer(containerId) {
   const container = docker.getContainer(containerId);
-  await withTimeout(container.restart(), 30000);
+  logger.debug("Restarting container %s", containerId);
+  try {
+    await withTimeout(container.restart(), TIMEOUTS.CONTAINER_OP);
+    logger.info("Restarted container %s", containerId);
+  } catch (err) {
+    logger.error("Failed to restart container %s", containerId, err);
+    throw err;
+  }
 }

package/src/helpers/dockerService/serviceComponents/containerList.js

@@ -1,30 +1,68 @@
-import { docker } from "../dockerService";
+import { docker } from "../dockerService.js";
+import { logger } from "../../logger.js";
+
+const DEFAULT_CONTAINER_NAME = "Unknown";
+
+/**
+ * Produce a safe, display-friendly container name from the raw Docker payload.
+ *
+ * @param {Object} container Docker container summary as returned by dockerode.
+ * @returns {string} Normalized name without leading slashes and with a fallback applied.
+ */
+function normalizeContainerName(container) {
+  const names = container?.Names;
+
+  let rawName;
+  if (Array.isArray(names) && names.length > 0 && typeof names[0] === "string") {
+    rawName = names[0];
+  } else if (typeof names === "string" && names.trim().length > 0) {
+    rawName = names;
+  } else if (typeof container?.Name === "string" && container.Name.trim().length > 0) {
+    rawName = container.Name;
+  } else {
+    rawName = DEFAULT_CONTAINER_NAME;
+  }
+
+  if (typeof rawName !== "string") {
+    return DEFAULT_CONTAINER_NAME;
+  }
+
+  const cleanedName = rawName.replace(/^\/+/u, "").trim();
+  return cleanedName.length > 0 ? cleanedName : DEFAULT_CONTAINER_NAME;
+}
 
 /**
  * Return a list of containers with normalized fields for the UI.
  * @returns {Promise<Array<Object>>}
  */
 export async function getContainers() {
-  const containers = await docker.listContainers({ all: true });
-  return containers.map((container) => ({
-    id: container.Id,
-    name: (container.Names && container.Names[0] || 'Unknown').replace("/", ""),
-    image: container.Image,
-    state: container.State,
-    status: container.Status,
-    ports:
-      (() => {
-        const publicPorts = container.Ports.filter((port) => port.PublicPort).map(
-          (port) => `${port.PublicPort}:${port.PrivatePort}`
-        );
-        if (publicPorts.length > 0) {
-          return [...new Set(publicPorts)];
-        }
-  // If there are no public ports, show private exposed ports
-        const privatePorts = container.Ports.filter((port) => port.PrivatePort).map(
-          (port) => `:${port.PrivatePort}`
-        );
-        return [...new Set(privatePorts)];
-      })()
-  }));
+  logger.debug("Listing containers");
+  try {
+    const containers = await docker.listContainers({ all: true });
+    logger.debug("Retrieved %d containers", containers.length);
+    return containers.map((container) => ({
+      id: container.Id,
+      name: normalizeContainerName(container),
+      image: container.Image,
+      state: container.State,
+      status: container.Status,
+      ports:
+        (() => {
+          const publicPorts = container.Ports.filter((port) => port.PublicPort).map(
+            (port) => `${port.PublicPort}:${port.PrivatePort}`
+          );
+          if (publicPorts.length > 0) {
+            return [...new Set(publicPorts)];
+          }
+          // Fall back to exposed private ports when there are no bindings.
+          const privatePorts = container.Ports.filter((port) => port.PrivatePort).map(
+            (port) => `${port.PrivatePort}`
+          );
+          return [...new Set(privatePorts)];
+        })()
+    }));
+  } catch (err) {
+    logger.error("Failed to list containers", err);
+    throw err;
+  }
 }

package/src/helpers/dockerService/serviceComponents/containerLogs.js

@@ -1,4 +1,6 @@
-import { docker } from "../dockerService";
+import { docker } from "../dockerService.js";
+import { safeCall } from "../../safeCall.js";
+import { logger } from "../../logger.js";
 
 /**
  * Return a stream of logs from a container and call callbacks for events.
@@ -9,8 +11,11 @@ import { docker } from "../dockerService";
  * @param {Function} onError - Called on error
  */
 export function getLogsStream(containerId, onData, onEnd, onError) {
+  // Use shared safeCall util to call optional callbacks safely
+
   try {
     const container = docker.getContainer(containerId);
+    logger.debug("Opening logs stream for container %s", containerId);
     container.logs({
       follow: true,
       stdout: true,
@@ -18,14 +23,23 @@ export function getLogsStream(containerId, onData, onEnd, onError) {
       tail: 100
     }, (err, stream) => {
       if (err) {
-        onError?.(err);
+        logger.error("Failed to open logs stream for container %s", containerId, err);
+        safeCall(onError, err);
         return;
       }
-      stream.on('data', chunk => onData?.(chunk.toString()));
-      stream.on('end', () => onEnd?.());
-      stream.on('error', err => onError?.(err));
+      logger.info("Logs stream established for container %s", containerId);
+      stream.on('data', chunk => safeCall(onData, chunk.toString()));
+      stream.on('end', () => {
+        logger.debug("Logs stream ended for container %s", containerId);
+        safeCall(onEnd);
+      });
+      stream.on('error', streamErr => {
+        logger.error("Logs stream error for container %s", containerId, streamErr);
+        safeCall(onError, streamErr);
+      });
     });
   } catch (err) {
-    onError?.(err);
+    logger.error("Unexpected error while opening logs stream for container %s", containerId, err);
+    safeCall(onError, err);
   }
 }

package/src/helpers/dockerService/serviceComponents/containerStats.js

@@ -1,4 +1,5 @@
-import { docker } from "../dockerService";
+import { docker } from "../dockerService.js";
+import { logger } from "../../logger.js";
 
 /**
  * Retrieve a snapshot of container resource usage (CPU, memory, network).
@@ -8,7 +9,14 @@ import { docker } from "../dockerService";
  */
 export async function getStats(containerId) {
   const container = docker.getContainer(containerId);
-  const stream = await container.stats({ stream: false });
+  logger.debug("Fetching stats for container %s", containerId);
+  let stream;
+  try {
+    stream = await container.stats({ stream: false });
+  } catch (err) {
+    logger.error("Failed to fetch stats for container %s", containerId, err);
+    throw err;
+  }
 
   const cpuDelta =
     stream.cpu_stats.cpu_usage.total_usage -
@@ -17,8 +25,16 @@ export async function getStats(containerId) {
     stream.cpu_stats.system_cpu_usage - stream.precpu_stats.system_cpu_usage;
   
   // Get number of CPUs for proper normalization
-  const numCpus = stream.cpu_stats.online_cpus || 
-                  stream.cpu_stats.cpu_usage.percpu_usage?.length || 1;
+  let numCpus = 1;
+  if (typeof stream.cpu_stats.online_cpus === 'number' && stream.cpu_stats.online_cpus > 0) {
+    numCpus = stream.cpu_stats.online_cpus;
+  } else if (
+    stream.cpu_stats.cpu_usage &&
+    Array.isArray(stream.cpu_stats.cpu_usage.percpu_usage) &&
+    stream.cpu_stats.cpu_usage.percpu_usage.length > 0
+  ) {
+    numCpus = stream.cpu_stats.cpu_usage.percpu_usage.length;
+  }
   
   // Calculate normalized CPU percentage
   const cpuPercent = systemDelta > 0 
@@ -40,9 +56,12 @@ export async function getStats(containerId) {
         .reduce((a, b) => a + b, 0)
     : 0;
 
-  return {
+  const snapshot = {
     cpuPercent: cpuPercent.toFixed(1),
     memPercent: memPercent.toFixed(1),
     netIO: { rx, tx },
   };
+
+  logger.debug("Stats fetched for container %s", containerId, snapshot);
+  return snapshot;
 }

package/src/helpers/dockerService/serviceComponents/imageUtils.js

@@ -1,4 +1,4 @@
-import { docker } from "../dockerService";
+import { docker } from "../dockerService.js";
 
 /**
  * Check whether an image exists locally.

package/src/helpers/exitWithMessage.js

@@ -1,4 +1,5 @@
 import { spawn } from "child_process";
+import { EXIT_DELAY } from "./constants";
 
 /**
  * Show an exit message using provided setters, clear the terminal and exit after a delay.
@@ -10,7 +11,7 @@ import { spawn } from "child_process";
  * @param {string} [params.color] - Color for the message
  * @param {number} [params.delay] - Delay in milliseconds before exiting
  */
-export function exitWithMessage({ setMessage, setMessageColor, message = "Exiting...", color = "yellow", delay = 1500 }) {
+export function exitWithMessage({ setMessage, setMessageColor, message = "Exiting...", color = "yellow", delay = EXIT_DELAY }) {
   setMessage(message);
   setMessageColor(color);
   setTimeout(() => {

package/src/helpers/logger.js

@@ -0,0 +1,113 @@
+/**
+ * Supported log levels in ascending verbosity.
+ * Lower numeric values represent higher severity.
+ */
+const LOG_LEVELS = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  debug: 3
+};
+
+/**
+ * @typedef {Object} LogEntry
+ * @property {string} level Severity string (error, warn, info, debug)
+ * @property {string} message Primary log message
+ * @property {any[]} args Additional payload values forwarded to listeners
+ * @property {string} timestamp ISO timestamp when the entry was created
+ * @property {string} formatted Preformatted message used for console output
+ */
+
+/**
+ * @callback LogListener
+ * @param {LogEntry} entry Log entry data emitted by the logger
+ */
+
+function parseLevel(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized in LOG_LEVELS) {
+    return LOG_LEVELS[normalized];
+  }
+  return null;
+}
+
+const envLevel =
+  parseLevel(process.env.CDD_LOG_LEVEL) ??
+  parseLevel(process.env.LOG_LEVEL) ??
+  LOG_LEVELS.info;
+
+const currentLevel = typeof envLevel === "number" ? envLevel : LOG_LEVELS.info;
+
+const listeners = new Set();
+
+function shouldLog(level) {
+  const target = LOG_LEVELS[level];
+  return typeof target === "number" && target <= currentLevel;
+}
+
+function log(level, message, ...args) {
+  if (!shouldLog(level)) {
+    return;
+  }
+
+  const timestamp = new Date().toISOString();
+  const upperLevel = level.toUpperCase();
+  const formatted = `[${timestamp}] [${upperLevel}] ${message}`;
+  const entry = { level, message, args, timestamp, formatted };
+
+  const shouldWriteToConsole =
+    listeners.size === 0 || level === "error" || level === "warn";
+
+  if (shouldWriteToConsole) {
+    const method = level === "debug" ? "log" : level;
+    if (typeof console[method] === "function") {
+      console[method](formatted, ...args);
+    } else {
+      console.log(formatted, ...args);
+    }
+  }
+
+  listeners.forEach((listener) => {
+    try {
+      listener(entry);
+    } catch (err) {
+      // Ignore listener errors so logging remains resilient.
+    }
+  });
+}
+
+/**
+ * Shared logger instance with leveled output and in-memory subscriptions.
+ * Consumers can import `{ logger }` to emit messages or to listen for
+ * log entries (used by the CLI debug panel).
+ */
+export const logger = {
+  debug(message, ...args) {
+    log("debug", message, ...args);
+  },
+  info(message, ...args) {
+    log("info", message, ...args);
+  },
+  warn(message, ...args) {
+    log("warn", message, ...args);
+  },
+  error(message, ...args) {
+    log("error", message, ...args);
+  },
+  /**
+   * Subscribe to log events.
+   *
+  * @param {LogListener} listener Listener invoked for every log entry that passes the current level filter.
+  * @returns {function(): void} Cleanup function that removes the listener when called.
+   */
+  subscribe(listener) {
+    if (typeof listener !== "function") {
+      return () => {};
+    }
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  }
+};

package/src/helpers/safeCall.js

@@ -0,0 +1,18 @@
+import { logger } from "./logger.js";
+
+/**
+ * Call a function safely: if it's a function call it with provided args and
+ * catch any errors so they don't bubble to the host application.
+ *
+ * @param {Function} fn
+ * @param  {...any} args
+ */
+export function safeCall(fn, ...args) {
+  if (typeof fn === 'function') {
+    try {
+      return fn(...args);
+    } catch (e) {
+      logger.error("safeCall caught error", e);
+    }
+  }
+}

package/src/helpers/validationHelpers.js

@@ -1,8 +1,17 @@
 // Reusable validations for ports and environment variables
 
+/**
+ * Validate a comma-separated list of port mappings in the form "host:container".
+ * Examples of valid input: "8080:80, 3000:3000"
+ *
+ * @param {string} portInput - Comma-separated port mappings
+ * @returns {boolean} True when all mappings are valid, false otherwise
+ */
 export function validatePorts(portInput) {
+  // Empty or whitespace-only input is considered valid (ports are optional)
+  if (!portInput || !portInput.trim()) return true;
   const ports = portInput.split(",").map(p => p.trim()).filter(Boolean);
-  if (ports.length === 0) return false;
+  if (ports.length === 0) return true;
   const invalid = ports.find(pair => {
     const [host, cont] = pair.split(":");
     return !host || !cont || isNaN(Number(host)) || isNaN(Number(cont));
@@ -10,9 +19,18 @@ export function validatePorts(portInput) {
   return !invalid;
 }
 
+/**
+ * Validate environment variable input as comma-separated VAR=value pairs.
+ * Empty or whitespace-only input is considered valid (no env vars).
+ * Variable names must start with a letter or underscore and contain only
+ * alphanumeric characters and underscores.
+ *
+ * @param {string} envInput - Comma-separated environment variable assignments
+ * @returns {boolean} True when all env var assignments are valid, false otherwise
+ */
 export function validateEnvVars(envInput) {
   if (!envInput || !envInput.trim()) return true; // Empty is valid
-  
+
   const vars = envInput.split(",").map(v => v.trim()).filter(Boolean);
   const invalid = vars.find(v => {
     const parts = v.split("=");
@@ -23,6 +41,6 @@ export function validateEnvVars(envInput) {
     if (!/^[A-Z_][A-Z0-9_]*$/i.test(varName)) return true;
     return false;
   });
-  
+
   return !invalid;
 }

package/src/hooks/creation/useContainerActions.js

@@ -1,4 +1,5 @@
 import { useState } from "react";
+import { safeCall } from "../../helpers/safeCall.js";
 import { startContainer as svcStartContainer, stopContainer as svcStopContainer, restartContainer as svcRestartContainer, removeContainer as svcRemoveContainer } from "../../helpers/dockerService/serviceComponents/containerActions.js";
 
 /**
@@ -36,9 +37,9 @@ export function useContainerActions({ containers, onAction }) {
     setMessageColor("yellow");
     try {
       await actionFn(container.id);
-      setMessage(`${actionLabel} container successful.`);
-      setMessageColor("green");
-      if (onAction) onAction();
+  setMessage(`${actionLabel} container successful.`);
+  setMessageColor("green");
+  safeCall(onAction);
     } catch (err) {
       setMessage(`Failed to ${actionLabel.toLowerCase()} container: ${err.message}`);
       setMessageColor("red");

package/src/hooks/creation/useContainerCreation.js

@@ -1,5 +1,6 @@
 import { useState } from "react";
-import { validatePorts, validateEnvVars } from "../../helpers/validationHelpers.js";
+import { validatePorts } from "../../helpers/validationHelpers.js";
+import { safeCall } from "../../helpers/safeCall.js";
 
 /**
  * Custom hook to manage the container creation flow, step by step.
@@ -60,8 +61,8 @@ export function useContainerCreation({ onCreate, onCancel, dbImages = [] }) {
       return;
     }
     if (step === 3) {
-      // Final step: call onCreate with all data
-      onCreate({ imageName, containerName, portInput, envInput });
+      // Final step: call onCreate with all data (safely)
+      safeCall(onCreate, { imageName, containerName, portInput, envInput });
     }
   }
 
@@ -76,7 +77,7 @@ export function useContainerCreation({ onCreate, onCancel, dbImages = [] }) {
     setEnvInput("");
     setMessage("");
     setMessageColor("yellow");
-    if (onCancel) onCancel();
+    safeCall(onCancel);
   }
 
   return {

package/src/hooks/creation/useLogsViewer.js

@@ -1,4 +1,5 @@
 import { useState, useRef } from "react";
+import { safeCall } from "../../helpers/safeCall.js";
 
 /**
  * Custom hook to manage the logs viewer state and stream reference.
@@ -33,7 +34,7 @@ export function useLogsViewer() {
     setShowLogs(false);
     setLogs([]);
     if (logsStreamRef.current) {
-      logsStreamRef.current.destroy?.();
+      safeCall(logsStreamRef.current.destroy?.bind(logsStreamRef.current));
       logsStreamRef.current = null;
     }
   }