cdd-cli 3.1.2 → 3.1.4

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [3.1.4] - 2025-10-17
+
+### Changed
+
+- Documentation cleanup: translate `FIXES_APPLIED.md` to English, remove Spanish duplicate and references to internal audit doc.
+- No functional code changes.
+
+## [3.1.3] - 2025-10-17
+
+### Fixed
+
+- Addressed critical security and stability issues identified in internal audit.
+- Improved Docker service components robustness (`containerActions`, `containerList`, `containerLogs`, `containerStats`).
+- Strengthened validation helpers and extended unit tests.
+
+### Added
+
+- Documentation: `FIXES_APPLIED.md` summarizing analysis and mitigations.
+
+### Changed
+
+- Minor code refactors and clarifications across components and hooks.
+
+## [3.1.2] - 2025-10-16
+
+### Changed
+
+- Docs cleanup: remove Spanish inline comments; add English JSDoc across source files.
+
 ## [3.1.0] - 2025-10-16
 
 ### Added

package/FIXES_APPLIED.md

@@ -0,0 +1,419 @@
+# Applied Fixes - CDD CLI
+
+**Date:** 2025-10-17  
+**Project:** CDD-CLI (CLI Docker Dashboard)
+
+---
+
+## Fixes Summary
+
+A total of 11 critical fixes were applied to address security, stability, and portability issues identified during the code audit.
+
+---
+
+## 1. APPLIED CRITICAL FIXES
+
+### ✅ 1.1. Import Order Fix
+
+**File:** `src/helpers/dockerService/serviceComponents/containerActions.js`
+
+**Issue:** Imports were declared after exports.
+
+**Applied fix:**
+```javascript
+// BEFORE (incorrect):
+export async function removeContainer(containerId) { ... }
+import { docker } from "../dockerService";
+
+// AFTER (correct):
+import { docker } from "../dockerService";
+import { imageExists, pullImage } from "./imageUtils.js";
+export async function removeContainer(containerId) { ... }
+```
+
+**Impact:** Removes potential reference errors and follows ES6 standards.
+
+---
+
+### ✅ 1.2. Optional Ports in Container Creation
+
+**File:** `src/hooks/creation/useContainerCreation.js`
+
+**Issue:** Users were forced to specify ports, but many containers don’t need them.
+
+**Applied fix:**
+```javascript
+// BEFORE:
+if (!portInput.trim()) {
+  setMessage("You must specify at least one port to expose");
+  return;
+}
+
+// AFTER:
+// Ports are optional — only validate if provided
+if (portInput.trim() && !validatePorts(portInput)) {
+  setMessage("Port format must be host:container...");
+  return;
+}
+```
+
+**Impact:** Allows creating containers without exposed ports (workers, internal services, etc.).
+
+---
+
+### ✅ 1.3. Error Handling in getLogsStream
+
+**File:** `src/helpers/dockerService/serviceComponents/containerLogs.js`
+
+**Issue:** No try-catch to handle synchronous exceptions.
+
+**Applied fix:**
+```javascript
+export function getLogsStream(containerId, onData, onEnd, onError) {
+  try {
+    const container = docker.getContainer(containerId);
+    // ... rest of the code
+  } catch (err) {
+    onError?.(err);
+  }
+}
+```
+
+**Impact:** Prevents crashes when the container doesn’t exist or connection errors occur.
+
+---
+
+### ✅ 1.4. Cross-Platform Docker Socket Configuration
+
+**File:** `src/helpers/dockerService/dockerService.js`
+
+**Issue:** Hardcoded path `/var/run/docker.sock` only works on Linux/macOS.
+
+**Applied fix:**
+```javascript
+// BEFORE:
+const docker = new Docker({ socketPath: "/var/run/docker.sock" });
+
+// AFTER:
+// Use default configuration that automatically handles:
+// - /var/run/docker.sock on Linux/macOS
+// - //./pipe/docker_engine on Windows
+const docker = new Docker();
+```
+
+**Impact:** Works on Windows, Linux, and macOS without manual changes.
+
+---
+
+### ✅ 1.5. Race Condition Prevention in Stats
+
+**File:** `src/components/ContainerRow.jsx`
+
+**Issue:** State updates on unmounted components caused memory leaks.
+
+**Applied fix:**
+```javascript
+useEffect(() => {
+  if (state !== "running") return;
+  
+  let isMounted = true;  // ← Mount flag
+  
+  const fetchStats = async () => {
+    try {
+      const s = await getStats(id);
+      if (isMounted) {  // ← Only update if mounted
+        setStats(s);
+      }
+    } catch (err) {
+      if (isMounted) {
+        setStatsError("Error fetching stats");
+      }
+    }
+  };
+  
+  fetchStats();
+  const timer = setInterval(fetchStats, 1500);
+  
+  return () => {
+    isMounted = false;  // ← Cleanup
+    clearInterval(timer);
+  };
+}, [id, state]);
+```
+
+**Impact:** Eliminates React warnings and prevents memory leaks.
+
+---
+
+### ✅ 1.6. Environment Variables Validation
+
+**File:** `src/helpers/validationHelpers.js`
+
+**Issue:** `validateEnvVars` always returned `true`.
+
+**Applied fix:**
+```javascript
+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("=");
+    if (parts.length < 2) return true;  // Must be VAR=value
+    const varName = parts[0].trim();
+    // Names must be alphanumeric with underscores
+    if (!/^[A-Z_][A-Z0-9_]*$/i.test(varName)) return true;
+    return false;
+  });
+  
+  return !invalid;
+}
+```
+
+**Impact:** Detects malformed variables before sending them to Docker.
+
+---
+
+### ✅ 1.7. CPU Stats Calculation Fix
+
+**File:** `src/helpers/dockerService/serviceComponents/containerStats.js`
+
+**Issue:** Not normalized by number of CPUs, producing wrong values on multi-core hosts.
+
+**Applied fix:**
+```javascript
+// Determine number of CPUs
+const numCpus = stream.cpu_stats.online_cpus || 
+                stream.cpu_stats.cpu_usage.percpu_usage?.length || 1;
+
+// Compute normalized percentage
+const cpuPercent = systemDelta > 0 
+  ? ((cpuDelta / systemDelta) * numCpus * 100) 
+  : 0;
+```
+
+**Impact:** Correct CPU stats on multi-core systems.
+
+---
+
+### ✅ 1.8. Timeouts in Docker Operations
+
+**File:** `src/helpers/dockerService/serviceComponents/containerActions.js`
+
+**Issue:** Operations without timeouts could freeze the UI indefinitely.
+
+**Applied fix:**
+```javascript
+function withTimeout(promise, ms = 30000) {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => 
+      setTimeout(() => reject(new Error('Operation timed out')), ms)
+    )
+  ]);
+}
+
+export async function startContainer(containerId) {
+  const container = docker.getContainer(containerId);
+  await withTimeout(container.start(), 30000);
+}
+```
+
+**Impact:** Prevents frozen UI during long or failing operations.
+
+---
+
+### ✅ 1.9. In-Memory Log Limit
+
+**File:** `src/hooks/useControls.js`
+
+**Issue:** Logs accumulated indefinitely causing a memory leak.
+
+**Applied fix:**
+```javascript
+getLogsStream(
+  containers[selected].id,
+  (data) => logsViewer.setLogs((prev) => {
+    const newLogs = [...prev, ...data.split("\n").filter(Boolean)];
+    // Limit to last 1000 lines
+    return newLogs.slice(-1000);
+  }),
+  // ...
+);
+```
+
+**Impact:** Prevents memory leaks on long-running log streams.
+
+---
+
+### ✅ 1.10. Duplicate Message Fix
+
+**File:** `src/helpers/actionHelpers.js`
+
+**Issue:** Success message was identical to the start message.
+
+**Applied fix:**
+```javascript
+// BEFORE:
+setMessage(`${actionLabel} container...`); // start
+await actionFn(c.id);
+setMessage(`${actionLabel} container...`); // success (duplicate)
+
+// AFTER:
+setMessage(`${actionLabel} container...`); // start
+await actionFn(c.id);
+setMessage(`${actionLabel} container completed successfully`); // success
+```
+
+**Impact:** Clear feedback that the operation completed.
+
+---
+
+### ✅ 1.11. Container Names Validation
+
+**File:** `src/helpers/dockerService/serviceComponents/containerList.js`
+
+**Issue:** Didn’t validate when `Names` was empty.
+
+**Applied fix:**
+```javascript
+// BEFORE:
+name: container.Names[0].replace("/", ""),
+
+// AFTER:
+name: (container.Names && container.Names[0] || 'Unknown').replace("/", ""),
+```
+
+**Impact:** Prevents crashes when Docker returns unexpected data.
+
+---
+
+## 2. TEST IMPROVEMENTS
+
+### ✅ Tests for validateEnvVars
+
+**File:** `test/validationHelpers.test.js`
+
+**New tests added:**
+- Empty input is valid
+- Valid single env var
+- Valid multiple env vars
+- Valid env var with underscores
+- Invalid env var without equals sign
+- Invalid env var with invalid name
+- Invalid env var with special characters in name
+
+**Result:**
+```
+Test Suites: 1 passed, 1 total
+Tests:       12 passed, 12 total (previously: 5)
+```
+
+---
+
+## 3. SECURITY ANALYSIS
+
+### ✅ CodeQL Security Scan
+
+**Result:** ✅ 0 vulnerabilities found
+
+```
+Analysis Result for 'javascript'. Found 0 alert(s):
+- javascript: No alerts found.
+```
+
+---
+
+## 4. BUILD VERIFICATION
+
+### ✅ Successful Build
+
+```bash
+$ npm run build
+Successfully compiled 28 files with Babel (815ms).
+```
+
+---
+
+## 5. OVERALL IMPACT OF FIXES
+
+### Security
+- ✅ No security vulnerabilities detected
+- ✅ Improved input validation
+- ✅ Robust error handling
+
+### Stability
+- ✅ Memory leak prevention
+- ✅ Race condition prevention
+- ✅ Crash prevention due to unhandled errors
+- ✅ Timeouts for potentially long operations
+
+### Portability
+- ✅ Windows compatibility
+- ✅ Linux compatibility
+- ✅ macOS compatibility
+
+### User Experience
+- ✅ Optional ports in container creation
+- ✅ Clearer feedback messages
+- ✅ Correct CPU statistics
+- ✅ Better error handling with informative messages
+
+### Code Quality
+- ✅ ES6 compliant
+- ✅ Better test coverage (5 → 12 tests)
+- ✅ More maintainable code
+
+---
+
+## 6. MODIFIED FILES
+
+1. `src/helpers/dockerService/serviceComponents/containerActions.js`
+2. `src/hooks/creation/useContainerCreation.js`
+3. `src/helpers/dockerService/serviceComponents/containerLogs.js`
+4. `src/helpers/dockerService/dockerService.js`
+5. `src/components/ContainerRow.jsx`
+6. `src/helpers/validationHelpers.js`
+7. `src/helpers/dockerService/serviceComponents/containerStats.js`
+8. `src/hooks/useControls.js`
+9. `src/helpers/actionHelpers.js`
+10. `src/helpers/dockerService/serviceComponents/containerList.js`
+11. `test/validationHelpers.test.js`
+
+---
+
+## 7. FUTURE RECOMMENDATIONS
+
+While the critical issues have been addressed, the internal audit yielded additional recommendations for future improvements:
+
+### Medium Priority
+- Add more unit tests
+- Implement PropTypes or migrate to TypeScript
+- Extract magic numbers into constants
+- Improve the logging system
+
+### Low Priority
+- Implement i18n (internationalization)
+- Improve JSDoc documentation
+- Consider websockets for real-time updates
+- Implement retry logic for Docker reconnection
+
+---
+
+## 8. CONCLUSION
+
+We applied 11 critical fixes that significantly improve:
+
+- Security: 0 vulnerabilities
+- Stability: Prevention of memory leaks and race conditions
+- Portability: Works on Windows, Linux, and macOS
+- Quality: +140% more tests (5 → 12)
+
+All fixes have been tested and verified via:
+- ✅ Unit tests (12/12 passing)
+- ✅ Successful build
+- ✅ CodeQL security analysis (0 alerts)
+
+---
+
+**End of fixes document**

package/dist/App.js

@@ -1,25 +1,23 @@
 /**
  * Main React component for the CDD CLI UI.
- * Componente principal de React para la UI del CLI CDD.
  *
  * @component
  * @returns {JSX.Element} The rendered app / La app renderizada
  * @example
  * // EN: Render the app
- * // ES: Renderizar la app
  * <App />
  */
 import React from "react";
 import { Box, Text, Spacer } from "ink";
 import { useContainers } from "./hooks/useContainers.js";
 import { useControls } from "./hooks/useControls.js";
-import ContainerSection from "./components/ContainerSection.jsx";
-import MessageFeedback from "./components/MessageFeedback.jsx";
-import Header from "./components/Header.jsx";
-import LogViewer from "./components/LogViewer.jsx";
-import ContainerCreationPrompt from "./components/ContainerCreationPrompt.jsx";
-import UsageMenu from "./components/UsageMenu.jsx";
-import Footer from "./components/Footer.jsx";
+import ContainerSection from "./components/ContainerSection.js";
+import MessageFeedback from "./components/MessageFeedback.js";
+import Header from "./components/Header.js";
+import LogViewer from "./components/LogViewer.js";
+import ContainerCreationPrompt from "./components/ContainerCreationPrompt.js";
+import UsageMenu from "./components/UsageMenu.js";
+import Footer from "./components/Footer.js";
 export default function App() {
   var _useContainers = useContainers(),
     containers = _useContainers.containers;

package/dist/components/ContainerCreationPrompt.js

@@ -1,6 +1,6 @@
 import React from "react";
 import { Box, Text } from "ink";
-import { PromptField, PromptMessage } from "./PromptField.jsx";
+import { PromptField, PromptMessage } from "./PromptField.js";
 export default function ContainerCreationPrompt(props) {
   var step = props.step,
     imageName = props.imageName,

package/dist/components/ContainerList.js

@@ -1,19 +1,17 @@
 /**
  * List component for Docker containers.
- * Componente de lista para contenedores Docker.
  *
  * @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
  * @example
- * // EN: Render with containers
- * // ES: Renderizar con contenedores
+ * // Render with containers
  * <ContainerList containers={containers} />
  */
 import React from "react";
 import { Box, Text } from "ink";
-import ContainerRow from "./ContainerRow.jsx";
+import ContainerRow from "./ContainerRow.js";
 export default function ContainerList(_ref) {
   var containers = _ref.containers,
     selected = _ref.selected;

package/dist/components/ContainerRow.js

@@ -11,7 +11,7 @@ function _arrayWithHoles(r) { if (Array.isArray(r)) return r; }
 import React, { useState, useEffect } from "react";
 import { Box, Text } from "ink";
 import { getStats } from "../helpers/dockerService/serviceComponents/containerStats.js";
-import StatsBar from "./StatsBar.jsx";
+import StatsBar from "./StatsBar.js";
 var stateText = function stateText(state) {
   if (state === "running") return {
     text: "🟢 RUNNING",
@@ -48,7 +48,7 @@ export default function ContainerRow(_ref) {
     stats = _useState2[0],
     setStats = _useState2[1];
 
-  // Formatear puertos
+  // Format ports for display
   var formatPorts = function formatPorts(ports) {
     if (!ports || ports.length === 0) return "";
     if (Array.isArray(ports)) {
@@ -64,6 +64,7 @@ export default function ContainerRow(_ref) {
     setStatsError = _useState4[1];
   useEffect(function () {
     if (state !== "running") return;
+    var isMounted = true;
     var fetchStats = /*#__PURE__*/function () {
       var _ref2 = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee() {
         var s, _t;
@@ -75,22 +76,26 @@ export default function ContainerRow(_ref) {
               return getStats(id);
             case 1:
               s = _context.v;
-              setStats(s);
-              setStatsError("");
+              if (isMounted) {
+                setStats(s);
+                setStatsError("");
+              }
               _context.n = 3;
               break;
             case 2:
               _context.p = 2;
               _t = _context.v;
-              setStats({
-                cpuPercent: 0,
-                memPercent: 0,
-                netIO: {
-                  rx: 0,
-                  tx: 0
-                }
-              });
-              setStatsError("Error fetching stats");
+              if (isMounted) {
+                setStats({
+                  cpuPercent: 0,
+                  memPercent: 0,
+                  netIO: {
+                    rx: 0,
+                    tx: 0
+                  }
+                });
+                setStatsError("Error fetching stats");
+              }
             case 3:
               return _context.a(2);
           }
@@ -103,7 +108,8 @@ export default function ContainerRow(_ref) {
     fetchStats();
     var timer = setInterval(fetchStats, 1500);
     return function () {
-      return clearInterval(timer);
+      isMounted = false;
+      clearInterval(timer);
     };
   }, [id, state]);
   var stateInfo = stateText(state);

package/dist/components/ContainerSection.js

@@ -1,6 +1,6 @@
 import React from "react";
 import { Text } from "ink";
-import ContainerList from "./ContainerList.jsx";
+import ContainerList from "./ContainerList.js";
 export default function ContainerSection(_ref) {
   var containers = _ref.containers,
     selected = _ref.selected;

package/dist/helpers/actionHelpers.js

@@ -2,6 +2,19 @@ function _regenerator() { /*! regenerator-runtime -- Copyright (c) 2014-present,
 function _regeneratorDefine2(e, r, n, t) { var i = Object.defineProperty; try { i({}, "", {}); } catch (e) { i = 0; } _regeneratorDefine2 = function _regeneratorDefine(e, r, n, t) { function o(r, n) { _regeneratorDefine2(e, r, function (e) { return this._invoke(r, n, e); }); } r ? i ? i(e, r, { value: n, enumerable: !t, configurable: !t, writable: !t }) : e[r] = n : (o("next", 0), o("throw", 1), o("return", 2)); }, _regeneratorDefine2(e, r, n, t); }
 function asyncGeneratorStep(n, t, e, r, o, a, c) { try { var i = n[a](c), u = i.value; } catch (n) { return void e(n); } i.done ? t(u) : Promise.resolve(u).then(r, o); }
 function _asyncToGenerator(n) { return function () { var t = this, e = arguments; return new Promise(function (r, o) { var a = n.apply(t, e); function _next(n) { asyncGeneratorStep(a, r, o, _next, _throw, "next", n); } function _throw(n) { asyncGeneratorStep(a, r, o, _next, _throw, "throw", n); } _next(void 0); }); }; }
+/**
+ * Generic helper to perform a container action with user feedback.
+ *
+ * @param {Object} params
+ * @param {Array} params.containers - Array of container objects
+ * @param {number} params.selected - Index of the selected container
+ * @param {Function} params.actionFn - Async function that performs the action (receives container id)
+ * @param {string} params.actionLabel - Label used in feedback messages (e.g. 'Starting')
+ * @param {Function} params.setMessage - Setter for feedback message
+ * @param {Function} params.setMessageColor - Setter for feedback color
+ * @param {Function} [params.stateCheck] - Optional function that validates container state before action
+ * @returns {Promise<void>}
+ */
 export function handleAction(_x) {
   return _handleAction.apply(this, arguments);
 }
@@ -36,7 +49,7 @@ function _handleAction() {
           _context.n = 4;
           return actionFn(c.id);
         case 4:
-          setMessage("".concat(actionLabel, " container..."));
+          setMessage("".concat(actionLabel, " container completed successfully"));
           setMessageColor("green");
           setTimeout(function () {
             return setMessage("");

package/dist/helpers/dockerService/dockerService.js

@@ -1,5 +1,8 @@
 import Docker from "dockerode";
-var docker = new Docker({
-  socketPath: "/var/run/docker.sock"
-});
+
+// Use default dockerode configuration which automatically handles:
+// - /var/run/docker.sock on Linux/Mac
+// - //./pipe/docker_engine on Windows
+// - Environment variables DOCKER_HOST, DOCKER_CERT_PATH, etc.
+var docker = new Docker();
 export { docker };