cdd-cli 3.1.3 → 3.1.5

package/src/App.jsx

@@ -1,10 +1,12 @@
 /**
  * Main React component for the CDD CLI UI.
+ * Handles container listing, action feedback, optional creation prompt,
+ * and renders the live debug log panel (toggle with the D shortcut).
  *
  * @component
- * @returns {JSX.Element} The rendered app / La app renderizada
+ * @returns {JSX.Element} The rendered app
  * @example
- * // EN: Render the app
+ * // Render the app
  * <App />
  */
 import React from "react";
@@ -51,6 +53,18 @@ export default function App() {
         <Spacer />
         <MessageFeedback message={controls.message} color={controls.messageColor} />
         <UsageMenu />
+        {controls.showDebugLogs && (
+          <Box marginTop={1} flexDirection="column" borderStyle="round" borderColor="gray" padding={1}>
+            <Text color="cyan">Debug log — press D or ESC to close</Text>
+            {controls.debugLogs.length === 0 ? (
+              <Text dimColor>No debug entries yet. Run with CDD_LOG_LEVEL=debug for verbose output.</Text>
+            ) : (
+              controls.debugLogs.slice(-15).map((line, idx) => (
+                <Text key={idx} color="gray">{line}</Text>
+              ))
+            )}
+          </Box>
+        )}
         <Footer />
       </Box>
       {controls.showLogs && (

package/src/components/ContainerCreationPrompt.jsx

@@ -1,7 +1,23 @@
 import React from "react";
 import { Box, Text } from "ink";
 import { PromptField, PromptMessage } from "./PromptField.jsx";
+import PropTypes from 'prop-types';
 
+/**
+ * Prompt UI shown when creating a new container.
+ * Presents a step-by-step form (image, name, ports, env) and displays
+ * a contextual message provided by the creation hook.
+ *
+ * @param {Object} props
+ * @param {number} props.step - Current step index (0..3)
+ * @param {string} props.imageName - Value for the image name field
+ * @param {string} props.containerName - Value for the container name field
+ * @param {string} props.portInput - Value for the ports input field
+ * @param {string} props.envInput - Value for the environment variables field
+ * @param {string} props.message - Contextual message to display (errors/hints)
+ * @param {string} props.messageColor - Color for the contextual message
+ * @returns {JSX.Element}
+ */
 export default function ContainerCreationPrompt(props) {
   const { step, imageName, containerName, portInput, envInput, message, messageColor } = props;
   const prompts = [
@@ -35,3 +51,13 @@ export default function ContainerCreationPrompt(props) {
     </Box>
   );
 }
+
+ContainerCreationPrompt.propTypes = {
+  step: PropTypes.number.isRequired,
+  imageName: PropTypes.string,
+  containerName: PropTypes.string,
+  portInput: PropTypes.string,
+  envInput: PropTypes.string,
+  message: PropTypes.string,
+  messageColor: PropTypes.string,
+};

package/src/components/ContainerList.jsx

@@ -2,32 +2,31 @@
  * List component for Docker containers.
  *
  * @component
- * @param {Object} props - Component props / Props del componente
- * @param {Array} props.containers - Containers to display / Contenedores a mostrar
- * @returns {JSX.Element} Rendered list / Lista renderizada
+ * @param {Object} props - Component props
+ * @param {Array} props.containers - Containers to display
+ * @returns {JSX.Element} Rendered list
  * @example
  * // Render with containers
  * <ContainerList containers={containers} />
  */
 import React from "react";
-import { Box, Text } from "ink";
+import PropTypes from 'prop-types';
+import { Box } from "ink";
 import ContainerRow from "./ContainerRow.jsx";
 
 export default function ContainerList({ containers, selected }) {
   return (
     <>
       {containers.map((container, i) => (
-        <Box key={container.id} flexDirection="row" alignItems="flex-start">
-          <Box width={2} minWidth={2} justifyContent="flex-end">
-            <Text color={i === selected ? "green" : undefined}>
-              {i === selected ? "➤" : "  "}
-            </Text>
-          </Box>
-          <Box flexGrow={1} paddingLeft={1}>
-            <ContainerRow container={container} isSelected={i === selected} />
-          </Box>
+        <Box key={container.id} flexDirection="row" paddingLeft={1}>
+          <ContainerRow container={container} isSelected={i === selected} />
         </Box>
       ))}
     </>
   );
 }
+
+ContainerList.propTypes = {
+  containers: PropTypes.arrayOf(PropTypes.object).isRequired,
+  selected: PropTypes.number,
+};

package/src/components/ContainerRow.jsx

@@ -1,7 +1,9 @@
 import React, { useState, useEffect } from "react";
 import { Box, Text } from "ink";
 import { getStats } from "../helpers/dockerService/serviceComponents/containerStats";
+import { REFRESH_INTERVALS } from "../helpers/constants.js";
 import StatsBar from "./StatsBar.jsx";
+import PropTypes from 'prop-types';
 
 const stateText = (state) => {
   if (state === "running") return { text: "🟢 RUNNING", color: "green" };
@@ -10,7 +12,14 @@ const stateText = (state) => {
   return { text: state.toUpperCase(), color: "gray" };
 };
 
-export default function ContainerRow({ container }) {
+/**
+ * Row component that renders information and live stats for a container.
+ *
+ * @param {Object} props
+ * @param {Object} props.container - Container object with id, name, image, state and ports
+ * @returns {JSX.Element}
+ */
+export default function ContainerRow({ container, isSelected = false }) {
   const { id, name, image, state } = container;
   const [stats, setStats] = useState({
     cpuPercent: 0,
@@ -18,13 +27,19 @@ export default function ContainerRow({ container }) {
     netIO: { rx: 0, tx: 0 },
   });
 
-  // Format ports for display
+  // Format ports for display (no leading space to avoid layout shifts)
   const formatPorts = (ports) => {
     if (!ports || ports.length === 0) return "";
     if (Array.isArray(ports)) {
-      return ports.map((p, i) => ` 🔗 ${p}`).join("  ");
+      return ports.map((p, _i) => `🔗 ${p}`).join("  ");
     }
-    return ` 🔗 ${ports}`;
+    return `🔗 ${ports}`;
+  };
+
+  // Helper to truncate long strings to a max length without adding trailing spaces
+  const truncate = (s, max = 20) => {
+    if (!s) return "";
+    return s.length > max ? s.slice(0, max - 1) + "…" : s;
   };
 
   const [statsError, setStatsError] = useState("");
@@ -49,7 +64,7 @@ export default function ContainerRow({ container }) {
     };
     
     fetchStats();
-    const timer = setInterval(fetchStats, 1500);
+  const timer = setInterval(fetchStats, REFRESH_INTERVALS.CONTAINER_STATS);
     
     return () => {
       isMounted = false;
@@ -60,22 +75,42 @@ export default function ContainerRow({ container }) {
   const stateInfo = stateText(state);
   return (
     <Box flexDirection="column" marginBottom={1}>
-      <Box>
-        <Text color="cyan">{name.padEnd(20)}</Text>
-        <Text color="gray">{image.padEnd(20)}</Text>
-        <Text color={stateInfo.color}>{stateInfo.text}</Text>
-        <Text color="yellow">{formatPorts(container.ports)}</Text>
-        {state === "running" && <Text> </Text>}
-        {state === "running" && (
-          <StatsBar
-            cpu={parseFloat(stats.cpuPercent)}
-            mem={parseFloat(stats.memPercent)}
-          />
-        )}
-        {state === "running" && statsError && (
-          <Text color="red">{statsError}</Text>
-        )}
+      <Box flexDirection="row" alignItems="center">
+        <Box width={2} minWidth={2} justifyContent="flex-end" paddingRight={1}>
+          <Text color={isSelected ? "green" : undefined}>
+            {isSelected ? "➤" : "  "}
+          </Text>
+        </Box>
+        <Box width={18} flexShrink={1} paddingRight={1}>
+          <Text color="cyan">{truncate(name, 18)}</Text>
+        </Box>
+        <Box width={18} flexShrink={1} paddingRight={1}>
+          <Text color="gray">{truncate(image, 18)}</Text>
+        </Box>
+        <Box width={14} minWidth={12} paddingRight={1}>
+          <Text color={stateInfo.color}>{stateInfo.text}</Text>
+        </Box>
+        <Box flexGrow={1} flexShrink={1} paddingLeft={0} paddingRight={1}>
+          <Text color="yellow">{formatPorts(container.ports)}</Text>
+        </Box>
+        <Box flexShrink={0} paddingLeft={1}>
+          {state === "running" ? (
+            <StatsBar cpu={parseFloat(stats.cpuPercent)} mem={parseFloat(stats.memPercent)} />
+          ) : null}
+        </Box>
       </Box>
+      {statsError && <Text color="red">{statsError}</Text>}
     </Box>
   );
 }
+
+ContainerRow.propTypes = {
+  container: PropTypes.shape({
+    id: PropTypes.string.isRequired,
+    name: PropTypes.string.isRequired,
+    image: PropTypes.string,
+    state: PropTypes.string,
+    ports: PropTypes.oneOfType([PropTypes.array, PropTypes.string])
+  }).isRequired,
+  isSelected: PropTypes.bool,
+};

package/src/components/ContainerSection.jsx

@@ -1,10 +1,24 @@
 import React from "react";
 import { Text } from "ink";
 import ContainerList from "./ContainerList.jsx";
+import PropTypes from 'prop-types';
 
+/**
+ * Section that displays the list of containers or a message when none exist.
+ *
+ * @param {Object} props
+ * @param {Array<Object>} props.containers - Array of container objects to display
+ * @param {number} [props.selected] - Index of the currently selected container
+ * @returns {JSX.Element}
+ */
 export default function ContainerSection({ containers, selected }) {
-  if (containers.length === 0) {
+  if (!containers || containers.length === 0) {
     return <Text>No containers found</Text>;
   }
   return <ContainerList containers={containers} selected={selected} />;
 }
+
+ContainerSection.propTypes = {
+  containers: PropTypes.array.isRequired,
+  selected: PropTypes.number,
+};

package/src/components/Footer.jsx

@@ -1,10 +1,15 @@
 import React from "react";
 import { Box, Text } from "ink";
 
+/**
+ * Simple footer displayed at the bottom of the interface.
+ *
+ * @returns {JSX.Element}
+ */
 export default function Footer() {
   return (
     <Box justifyContent="flex-end" width="100%">
-      <Text dimColor>Crafted by Carlos Cochero • 2025</Text>
+      <Text dimColor>Crafted by Carlos Cochero 2025</Text>
     </Box>
   );
 }

package/src/components/Header.jsx

@@ -1,6 +1,18 @@
 import React from "react";
 import { Box, Text } from "ink";
 import chalk from "chalk";
+import PropTypes from 'prop-types';
+
+/**
+ * Header component displayed at the top of the CLI UI.
+ *
+ * @component
+ * @param {Object} props
+ * @param {number} props.count - Number of containers currently detected
+ * @returns {JSX.Element}
+ * @example
+ * <Header count={3} />
+ */
 
 export default function Header({ count }) {
   return (
@@ -15,3 +27,7 @@ export default function Header({ count }) {
     </Box>
   );
 }
+
+Header.propTypes = {
+  count: PropTypes.number.isRequired,
+};

package/src/components/LogViewer.jsx

@@ -1,10 +1,21 @@
 import React from "react";
 import { Text, useInput } from "ink";
+import { safeCall } from "../helpers/safeCall";
+import PropTypes from 'prop-types';
 
+/**
+ * Log viewer overlay component. Shows the most recent lines and closes on ESC.
+ *
+ * @param {Object} props
+ * @param {Array<string>} props.logs - Array of log lines
+ * @param {Function} [props.onExit] - Optional callback when the viewer closes
+ * @param {Object} [props.container] - Optional container metadata (used for title)
+ * @returns {JSX.Element}
+ */
 export default function LogViewer({ logs, onExit, container }) {
   useInput((input, key) => {
     if (key.escape) {
-      onExit();
+      safeCall(onExit);
     }
   });
 
@@ -12,7 +23,7 @@ export default function LogViewer({ logs, onExit, container }) {
 
   return (
     <>
-      <Text color="green">{container?.name || "Container"} logs, press ESC to exit</Text>
+      <Text color="green">{container?.name ?? "Container"} logs, press ESC to exit</Text>
       {visibleLogs.length === 0 ? (
         <Text dimColor>No logs...</Text>
       ) : (
@@ -21,3 +32,9 @@ export default function LogViewer({ logs, onExit, container }) {
     </>
   );
 }
+
+LogViewer.propTypes = {
+  logs: PropTypes.arrayOf(PropTypes.string).isRequired,
+  onExit: PropTypes.func,
+  container: PropTypes.object,
+};

package/src/components/MessageFeedback.jsx

@@ -1,6 +1,15 @@
 import React from "react";
 import { Box, Text } from "ink";
+import PropTypes from 'prop-types';
 
+/**
+ * Small component that shows a feedback message in the UI.
+ *
+ * @param {Object} props
+ * @param {string} props.message - Message to display. If falsy, component returns null.
+ * @param {string} [props.color] - Optional color name for the message text.
+ * @returns {JSX.Element|null}
+ */
 export default function MessageFeedback({ message, color }) {
   if (!message) return null;
   return (
@@ -9,3 +18,8 @@ export default function MessageFeedback({ message, color }) {
     </Box>
   );
 }
+
+MessageFeedback.propTypes = {
+  message: PropTypes.string,
+  color: PropTypes.string,
+};

package/src/components/PromptField.jsx

@@ -1,6 +1,17 @@
 import React from "react";
 import { Text } from "ink";
+import PropTypes from 'prop-types';
 
+/**
+ * PromptField shows a label and the current typed value for an input field.
+ * The cursor is represented with a trailing underscore.
+ *
+ * @param {Object} props
+ * @param {string} props.label - Label shown above the input value
+ * @param {string} props.value - Current value of the input
+ * @param {boolean} [props.required=false] - Whether the field is required
+ * @returns {JSX.Element}
+ */
 export function PromptField({ label, value, required }) {
   // If the field is required and empty, show in red
   const isEmpty = required && !value.trim();
@@ -12,7 +23,26 @@ export function PromptField({ label, value, required }) {
   );
 }
 
+/**
+ * Small helper to show a message below prompts (errors, hints, etc.).
+ *
+ * @param {Object} props
+ * @param {string} props.message - Message text to display
+ * @param {string} [props.color] - Optional color for the message
+ * @returns {JSX.Element|null}
+ */
 export function PromptMessage({ message, color }) {
   if (!message) return null;
   return <Text color={color || "yellow"}>{message}</Text>;
 }
+
+PromptField.propTypes = {
+  label: PropTypes.string,
+  value: PropTypes.string,
+  required: PropTypes.bool,
+};
+
+PromptMessage.propTypes = {
+  message: PropTypes.string,
+  color: PropTypes.string,
+};

package/src/components/StatsBar.jsx

@@ -1,25 +1,64 @@
 import React from "react";
 import { Text } from "ink";
 import chalk from "chalk";
+import PropTypes from 'prop-types';
 
+const BAR_WIDTH = 8;
+
+/**
+ * Small visual bar that shows CPU and memory usage percentages.
+ *
+ * @param {Object} props
+ * @param {number} props.cpu - CPU percentage (values outside 0-100 are clamped)
+ * @param {number} props.mem - Memory percentage (values outside 0-100 are clamped)
+ * @returns {JSX.Element}
+ */
 export default function StatsBar({ cpu, mem }) {
-  const cpuBar = makeBar(cpu);
-  const memBar = makeBar(mem);
+  const cpuBar = makeBar(cpu, BAR_WIDTH);
+  const memBar = makeBar(mem, BAR_WIDTH);
 
   return (
     <Text>
-      CPU: {cpuBar} {colorize(cpu)}%   MEM: {memBar} {colorize(mem)}%
+      CPU:{cpuBar}{colorize(cpu, ` ${formatPercent(cpu)}%`)} MEM:{memBar}{colorize(mem, ` ${formatPercent(mem)}%`)}
     </Text>
   );
 }
 
-function makeBar(value) {
-  const filled = Math.round(value / 10);
-  const empty = 10 - filled;
-  const bar = "▓".repeat(filled) + "░".repeat(empty);
-  return colorize(value, bar);
+StatsBar.propTypes = {
+  cpu: PropTypes.number.isRequired,
+  mem: PropTypes.number.isRequired,
+};
+
+/**
+ * Build a fixed-width bar representation from a numeric percentage.
+ *
+ * @param {number} value - Percentage value (values outside 0-100 are clamped)
+ * @param {number} width - Desired bar width in characters
+ * @returns {string} Colored bar string
+ */
+function makeBar(value, width) {
+  const safeWidth = Math.max(1, Math.round(width));
+  const normalized = Number.isFinite(value) ? Math.min(Math.max(value, 0), 100) : 0;
+  const filled = Math.round((normalized / 100) * safeWidth);
+  const empty = Math.max(0, safeWidth - filled);
+  const bar = "█".repeat(filled) + "░".repeat(empty);
+  return colorize(normalized, bar);
+}
+
+function formatPercent(value) {
+  if (!Number.isFinite(value)) return 0;
+  const normalized = Math.min(Math.max(value, 0), 100);
+  if (normalized >= 10) return Math.round(normalized);
+  return normalized.toFixed(1).replace(/\.0$/, "");
 }
 
+/**
+ * Colorize a value or text depending on thresholds.
+ *
+ * @param {number} value - Numeric value used to pick color; receives clamped percentage
+ * @param {string} [text] - Text to colorize, defaults to the numeric string
+ * @returns {string}
+ */
 function colorize(value, text = value.toString()) {
   if (value < 50) return chalk.greenBright(text);
   if (value < 80) return chalk.yellowBright(text);

package/src/components/UsageMenu.jsx

@@ -1,17 +1,47 @@
 import React from "react";
 import { Box, Text } from "ink";
 
+const SHORTCUTS = [
+  "Use ↑/↓ for navigation",
+  "I to initiate selected container",
+  "P to stop selected container",
+  "R to restart selected container",
+  "C to create a container",
+  "L to view logs of selected container",
+  "D to toggle debug log panel",
+  "E to remove selected container",
+  "Q to quit",
+];
+
+const GRID_COLUMNS = 3;
+
+/**
+ * Small usage menu that explains available keybindings to the user.
+ * Renders entries in a responsive grid to avoid an excessively long column.
+ *
+ * @returns {JSX.Element}
+ */
 export default function UsageMenu() {
+  const rowsPerColumn = Math.ceil(SHORTCUTS.length / GRID_COLUMNS);
+  const columns = Array.from({ length: GRID_COLUMNS }, (_, columnIndex) =>
+    SHORTCUTS.slice(columnIndex * rowsPerColumn, (columnIndex + 1) * rowsPerColumn)
+  ).filter((column) => column.length > 0);
+
   return (
     <Box flexDirection="column" marginTop={1}>
-      <Text>Use ↑/↓ for navigation</Text>
-      <Text>•I to initiate selected container</Text>
-      <Text>•P to stop selected container</Text>
-      <Text>•R to restart selected container</Text>
-      <Text>•C to create a container</Text>
-      <Text>•L to view logs of selected container</Text>
-      <Text>•E to remove selected container</Text>
-      <Text>•Q to quit</Text>
+      <Box flexDirection="row">
+        {columns.map((column, columnIndex) => (
+          <Box
+            key={`shortcut-column-${columnIndex}`}
+            flexDirection="column"
+            marginRight={columnIndex === columns.length - 1 ? 0 : 3}
+          >
+            {column.map((shortcut, rowIndex) => (
+              <Text key={`shortcut-${columnIndex}-${rowIndex}`}>{shortcut}</Text>
+            ))}
+          </Box>
+        ))}
+      </Box>
     </Box>
   );
 }

package/src/helpers/actionHelpers.js

@@ -1,3 +1,5 @@
+import { MESSAGE_TIMEOUTS } from "../helpers/constants.js";
+import { logger } from "./logger.js";
 /**
  * Generic helper to perform a container action with user feedback.
  *
@@ -22,22 +24,29 @@ export async function handleAction({
 }) {
   const c = containers[selected];
   if (!c) return;
-  if (stateCheck && stateCheck(c)) {
-    setMessage(stateCheck(c));
-    setMessageColor("red");
-    setTimeout(() => setMessage(""), 2000);
-    return;
+  if (stateCheck) {
+    const failureReason = stateCheck(c);
+    if (failureReason) {
+      logger.warn("Action %s blocked for container %s: %s", actionLabel, c.id, failureReason);
+      setMessage(failureReason);
+      setMessageColor("red");
+      setTimeout(() => setMessage(""), MESSAGE_TIMEOUTS.SHORT);
+      return;
+    }
   }
   setMessage(`${actionLabel} container...`);
   setMessageColor("green");
+  logger.info("Action %s requested for container %s", actionLabel, c.id);
   try {
     await actionFn(c.id);
     setMessage(`${actionLabel} container completed successfully`);
     setMessageColor("green");
-    setTimeout(() => setMessage(""), 3000);
+    setTimeout(() => setMessage(""), MESSAGE_TIMEOUTS.DEFAULT);
+    logger.info("Action %s completed for container %s", actionLabel, c.id);
   } catch (err) {
     setMessage(`Failed to ${actionLabel.toLowerCase()} container.`);
     setMessageColor("red");
-    setTimeout(() => setMessage(""), 3000);
+    setTimeout(() => setMessage(""), MESSAGE_TIMEOUTS.DEFAULT);
+    logger.error("Action %s failed for container %s", actionLabel, c.id, err);
   }
 }

package/src/helpers/constants.js

@@ -0,0 +1,30 @@
+/**
+ * Time intervals used across the app (milliseconds).
+ * - CONTAINER_LIST: how often to refresh the list of containers
+ * - CONTAINER_STATS: how often to fetch stats for running containers
+ */
+export const REFRESH_INTERVALS = {
+  CONTAINER_LIST: 3000,
+  CONTAINER_STATS: 1500,
+};
+
+/**
+ * Timeout values for UI messages before they disappear.
+ */
+export const MESSAGE_TIMEOUTS = {
+  SHORT: 2000,
+  DEFAULT: 3000,
+};
+
+/**
+ * Delay used before exiting the process when showing an exit message.
+ */
+export const EXIT_DELAY = 500;
+
+/**
+ * Operational timeouts for Docker operations and image pulls.
+ */
+export const TIMEOUTS = {
+  CONTAINER_OP: 30000,
+  PULL_IMAGE: 300000,
+};

package/src/helpers/dockerService/dockerService.js

@@ -4,6 +4,25 @@ import Docker from "dockerode";
 // - /var/run/docker.sock on Linux/Mac
 // - //./pipe/docker_engine on Windows
 // - Environment variables DOCKER_HOST, DOCKER_CERT_PATH, etc.
+
+/**
+ * Typedef for the docker client used in this project.
+ * Use a generic object shape so JSDoc can render a meaningful type.
+ *
+ * @typedef {Object} DockerClient
+ * @property {Function} listContainers
+ * @property {Function} getContainer
+ * @property {Function} listImages
+ * @property {Function} createContainer
+ * @property {Function} pull
+ */
+
+/**
+ * Shared Docker client instance (dockerode). Consumers import { docker }
+ * and use it to list/create/start/stop containers and images.
+ *
+ * @type {DockerClient}
+ */
 const docker = new Docker();
 
 export { docker };