cdd-cli 3.1.4 → 3.1.5

package/.eslintrc.json

@@ -0,0 +1,30 @@
+{
+  "env": {
+    "browser": true,
+    "node": true,
+    "es2021": true,
+    "jest": true
+  },
+  "extends": ["eslint:recommended", "plugin:react/recommended"],
+  "parserOptions": {
+    "ecmaVersion": 2021,
+    "sourceType": "module",
+    "ecmaFeatures": { "jsx": true }
+  },
+  "rules": {
+    "no-unsafe-optional-chaining": "error",
+    "react/react-in-jsx-scope": "off",
+    "no-console": "off",
+    "react/prop-types": "off",
+    "no-unused-vars": [
+      "warn",
+      {
+        "argsIgnorePattern": "^_",
+        "varsIgnorePattern": "^(?:_|React)$"
+      }
+    ]
+  },
+  "settings": {
+    "react": { "version": "detect" }
+  }
+}

package/.github/workflows/docs.yml

@@ -0,0 +1,35 @@
+name: Build and deploy docs
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build docs
+        run: npm run docs
+
+      - name: Deploy to GitHub Pages (push to gh-pages)
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs

package/CHANGELOG.md

@@ -4,6 +4,43 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [Unreleased]
+- Nothing yet.
+
+## [3.1.5] - 2025-10-18
+_Note: I'm sorry about the issues you've run into; this is a brand-new app and I'm still learning, but I'm moving as quickly as I can to deliver a quality experience._
+
+### Added
+
+- `safeCall` utility to safely invoke optional callbacks and avoid uncaught errors from consumer callbacks.
+- PropTypes added to core React components for runtime prop validation (ContainerRow, ContainerList, LogViewer, StatsBar, ContainerCreationPrompt, PromptField, MessageFeedback, Header, ContainerSection).
+
+### Changed
+
+- Container creation now inspects image `EXPOSE` declarations and auto-binds ports when the user leaves the ports step empty, reusing the next free host port to avoid conflicts (e.g. second `nginx` gets `81:80`).
+- CLI clears the terminal when starting and again after exiting with `q` for a cleaner shell experience.
+- Replaced direct optional callback invocations and stream destruction calls with `safeCall` in several modules (`containerLogs`, `useLogsStream`, `useLogsViewer`, `useContainerCreation`, `useContainerActions`, `LogViewer`).
+- ESLint config updated to include `jest` env and allow keeping `import React` for build compatibility.
+- Extracted common magic numbers into `src/helpers/constants.js` and replaced hardcoded values across the codebase:
+	- `REFRESH_INTERVALS.CONTAINER_LIST` (3000)
+	- `REFRESH_INTERVALS.CONTAINER_STATS` (1500)
+	- `MESSAGE_TIMEOUTS.SHORT` (2000) and `MESSAGE_TIMEOUTS.DEFAULT` (3000)
+	- `EXIT_DELAY` (500)
+	- `TIMEOUTS.CONTAINER_OP` (30000) and `TIMEOUTS.PULL_IMAGE` (300000)
+- Files updated to use constants: `useContainers`, `ContainerRow`, `actionHelpers`, `useControls`, `exitWithMessage`, `containerActions`.
+
+### Fixed
+
+- Added unit tests for `safeCall` and adjusted several components to silence lint warnings (unused variables).
+- Clamp `StatsBar` CPU/memory percentages to avoid negative repeat errors when streaming container stats (also refreshed component JSDoc to note the clamping).
+
+### Testing
+
+- Added additional unit tests for Docker service functions and hooks. All tests pass locally (5 suites, 26 tests).
+- Removed generated `dist/` artifacts and deleted obsolete test files that referenced incompatible test helpers.
+
+Incoming fixes and smaller tests / docs updates
+
 ## [3.1.4] - 2025-10-17
 
 ### Changed
@@ -51,10 +88,6 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 - Various runtime & build issues after modularization (import fixes, exposing container action functions, creation flow wiring).
 
-## [Unreleased]
-
-- Incoming fixes and smaller tests / docs updates
-
 ## [3.1.1] - 2025-10-16
 
 ### Fixed

package/README.md

@@ -6,6 +6,10 @@
   <a href="https://github.com/caertos/cdd/actions/workflows/ci.yml">
     <img src="https://github.com/caertos/cdd/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI status" />
   </a>
+  <!-- Documentation published to GitHub Pages -->
+  <a href="https://caertos.github.io/cdd/">
+    <img src="https://img.shields.io/badge/docs-GitHub%20Pages-blue" alt="Docs" />
+  </a>
 </p>
 
 Short, bilingual README with quickstart, development and tests.
@@ -46,6 +50,7 @@ cdd
 - R: restart selected container
 - C: create container (interactive prompt)
 - L: view logs for selected container
+- D: toggle the on-screen debug log panel
 - E: erase (remove) selected container (confirmation required)
 - Q: quit
 
@@ -113,6 +118,27 @@ Tests are located in `test/` and cover utility helpers.
 
 ---
 
+## Logging
+
+- The CLI logs high-level `info`, `warn`, and `error` messages by default so you see meaningful feedback without noise.
+- When you need deeper diagnostics (for example, to troubleshoot why stats or logs are not updating), start the CLI with debug logging enabled:
+
+```bash
+CDD_LOG_LEVEL=debug cdd          # if you installed globally
+# or
+CDD_LOG_LEVEL=debug node dist/index.js
+```
+
+- The same effect can be achieved with `LOG_LEVEL=debug`. Set `LOG_LEVEL=warn` if you only want to see warnings and errors.
+- Inside the CLI, press `D` to toggle the live debug log panel; press `D` again or `Esc` to hide it.
+- Redirect output to a file when users report issues so they can share the log easily:
+
+```bash
+CDD_LOG_LEVEL=debug cdd > cdd-debug.log 2>&1
+```
+
+---
+
 ## License
 
 This project is MIT/ISC licensed (see `LICENSE`).

package/dist/App.js

@@ -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";
@@ -46,7 +48,22 @@ export default function App() {
   }), /*#__PURE__*/React.createElement(Spacer, null), /*#__PURE__*/React.createElement(MessageFeedback, {
     message: controls.message,
     color: controls.messageColor
-  }), /*#__PURE__*/React.createElement(UsageMenu, null), /*#__PURE__*/React.createElement(Footer, null)), controls.showLogs && /*#__PURE__*/React.createElement(LogViewer, {
+  }), /*#__PURE__*/React.createElement(UsageMenu, null), controls.showDebugLogs && /*#__PURE__*/React.createElement(Box, {
+    marginTop: 1,
+    flexDirection: "column",
+    borderStyle: "round",
+    borderColor: "gray",
+    padding: 1
+  }, /*#__PURE__*/React.createElement(Text, {
+    color: "cyan"
+  }, "Debug log \u2014 press D or ESC to close"), controls.debugLogs.length === 0 ? /*#__PURE__*/React.createElement(Text, {
+    dimColor: true
+  }, "No debug entries yet. Run with CDD_LOG_LEVEL=debug for verbose output.") : controls.debugLogs.slice(-15).map(function (line, idx) {
+    return /*#__PURE__*/React.createElement(Text, {
+      key: idx,
+      color: "gray"
+    }, line);
+  })), /*#__PURE__*/React.createElement(Footer, null)), controls.showLogs && /*#__PURE__*/React.createElement(LogViewer, {
     logs: controls.logs,
     onExit: controls.exitLogs,
     container: containers[controls.selected]

package/dist/components/ContainerCreationPrompt.js

@@ -1,6 +1,23 @@
 import React from "react";
 import { Box, Text } from "ink";
 import { PromptField, PromptMessage } from "./PromptField.js";
+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) {
   var step = props.step,
     imageName = props.imageName,
@@ -45,4 +62,13 @@ export default function ContainerCreationPrompt(props) {
   }), /*#__PURE__*/React.createElement(Text, {
     dimColor: true
   }, "Press Enter to continue, Escape to cancel"));
-}
+}
+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/dist/components/ContainerList.js

@@ -2,15 +2,16 @@
  * 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.js";
 export default function ContainerList(_ref) {
   var containers = _ref.containers,
@@ -19,19 +20,14 @@ export default function ContainerList(_ref) {
     return /*#__PURE__*/React.createElement(Box, {
       key: container.id,
       flexDirection: "row",
-      alignItems: "flex-start"
-    }, /*#__PURE__*/React.createElement(Box, {
-      width: 2,
-      minWidth: 2,
-      justifyContent: "flex-end"
-    }, /*#__PURE__*/React.createElement(Text, {
-      color: i === selected ? "green" : undefined
-    }, i === selected ? "➤" : "  ")), /*#__PURE__*/React.createElement(Box, {
-      flexGrow: 1,
       paddingLeft: 1
     }, /*#__PURE__*/React.createElement(ContainerRow, {
       container: container,
       isSelected: i === selected
-    })));
+    }));
   }));
-}
+}
+ContainerList.propTypes = {
+  containers: PropTypes.arrayOf(PropTypes.object).isRequired,
+  selected: PropTypes.number
+};

package/dist/components/ContainerRow.js

@@ -11,7 +11,9 @@ 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 { REFRESH_INTERVALS } from "../helpers/constants.js";
 import StatsBar from "./StatsBar.js";
+import PropTypes from 'prop-types';
 var stateText = function stateText(state) {
   if (state === "running") return {
     text: "🟢 RUNNING",
@@ -30,8 +32,18 @@ var stateText = function stateText(state) {
     color: "gray"
   };
 };
+
+/**
+ * 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(_ref) {
-  var container = _ref.container;
+  var container = _ref.container,
+    _ref$isSelected = _ref.isSelected,
+    isSelected = _ref$isSelected === void 0 ? false : _ref$isSelected;
   var id = container.id,
     name = container.name,
     image = container.image,
@@ -48,15 +60,22 @@ export default function ContainerRow(_ref) {
     stats = _useState2[0],
     setStats = _useState2[1];
 
-  // Format ports for display
+  // Format ports for display (no leading space to avoid layout shifts)
   var formatPorts = function formatPorts(ports) {
     if (!ports || ports.length === 0) return "";
     if (Array.isArray(ports)) {
-      return ports.map(function (p, i) {
-        return " \uD83D\uDD17 ".concat(p);
+      return ports.map(function (p, _i) {
+        return "\uD83D\uDD17 ".concat(p);
       }).join("  ");
     }
-    return " \uD83D\uDD17 ".concat(ports);
+    return "\uD83D\uDD17 ".concat(ports);
+  };
+
+  // Helper to truncate long strings to a max length without adding trailing spaces
+  var truncate = function truncate(s) {
+    var max = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 20;
+    if (!s) return "";
+    return s.length > max ? s.slice(0, max - 1) + "…" : s;
   };
   var _useState3 = useState(""),
     _useState4 = _slicedToArray(_useState3, 2),
@@ -106,7 +125,7 @@ export default function ContainerRow(_ref) {
       };
     }();
     fetchStats();
-    var timer = setInterval(fetchStats, 1500);
+    var timer = setInterval(fetchStats, REFRESH_INTERVALS.CONTAINER_STATS);
     return function () {
       isMounted = false;
       clearInterval(timer);
@@ -116,18 +135,58 @@ export default function ContainerRow(_ref) {
   return /*#__PURE__*/React.createElement(Box, {
     flexDirection: "column",
     marginBottom: 1
-  }, /*#__PURE__*/React.createElement(Box, null, /*#__PURE__*/React.createElement(Text, {
+  }, /*#__PURE__*/React.createElement(Box, {
+    flexDirection: "row",
+    alignItems: "center"
+  }, /*#__PURE__*/React.createElement(Box, {
+    width: 2,
+    minWidth: 2,
+    justifyContent: "flex-end",
+    paddingRight: 1
+  }, /*#__PURE__*/React.createElement(Text, {
+    color: isSelected ? "green" : undefined
+  }, isSelected ? "➤" : "  ")), /*#__PURE__*/React.createElement(Box, {
+    width: 18,
+    flexShrink: 1,
+    paddingRight: 1
+  }, /*#__PURE__*/React.createElement(Text, {
     color: "cyan"
-  }, name.padEnd(20)), /*#__PURE__*/React.createElement(Text, {
+  }, truncate(name, 18))), /*#__PURE__*/React.createElement(Box, {
+    width: 18,
+    flexShrink: 1,
+    paddingRight: 1
+  }, /*#__PURE__*/React.createElement(Text, {
     color: "gray"
-  }, image.padEnd(20)), /*#__PURE__*/React.createElement(Text, {
+  }, truncate(image, 18))), /*#__PURE__*/React.createElement(Box, {
+    width: 14,
+    minWidth: 12,
+    paddingRight: 1
+  }, /*#__PURE__*/React.createElement(Text, {
     color: stateInfo.color
-  }, stateInfo.text), /*#__PURE__*/React.createElement(Text, {
+  }, stateInfo.text)), /*#__PURE__*/React.createElement(Box, {
+    flexGrow: 1,
+    flexShrink: 1,
+    paddingLeft: 0,
+    paddingRight: 1
+  }, /*#__PURE__*/React.createElement(Text, {
     color: "yellow"
-  }, formatPorts(container.ports)), state === "running" && /*#__PURE__*/React.createElement(Text, null, " "), state === "running" && /*#__PURE__*/React.createElement(StatsBar, {
+  }, formatPorts(container.ports))), /*#__PURE__*/React.createElement(Box, {
+    flexShrink: 0,
+    paddingLeft: 1
+  }, state === "running" ? /*#__PURE__*/React.createElement(StatsBar, {
     cpu: parseFloat(stats.cpuPercent),
     mem: parseFloat(stats.memPercent)
-  }), state === "running" && statsError && /*#__PURE__*/React.createElement(Text, {
+  }) : null)), statsError && /*#__PURE__*/React.createElement(Text, {
     color: "red"
-  }, statsError)));
-}
+  }, statsError));
+}
+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/dist/components/ContainerSection.js

@@ -1,14 +1,28 @@
 import React from "react";
 import { Text } from "ink";
 import ContainerList from "./ContainerList.js";
+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(_ref) {
   var containers = _ref.containers,
     selected = _ref.selected;
-  if (containers.length === 0) {
+  if (!containers || containers.length === 0) {
     return /*#__PURE__*/React.createElement(Text, null, "No containers found");
   }
   return /*#__PURE__*/React.createElement(ContainerList, {
     containers: containers,
     selected: selected
   });
-}
+}
+ContainerSection.propTypes = {
+  containers: PropTypes.array.isRequired,
+  selected: PropTypes.number
+};

package/dist/components/Footer.js

@@ -1,10 +1,16 @@
 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 /*#__PURE__*/React.createElement(Box, {
     justifyContent: "flex-end",
     width: "100%"
   }, /*#__PURE__*/React.createElement(Text, {
     dimColor: true
-  }, "Crafted by Carlos Cochero \u2022 2025"));
+  }, "Crafted by Carlos Cochero 2025"));
 }

package/dist/components/Header.js

@@ -1,6 +1,19 @@
 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(_ref) {
   var count = _ref.count;
   return /*#__PURE__*/React.createElement(Box, {
@@ -12,4 +25,7 @@ export default function Header(_ref) {
   }, " \u2014 CLI Docker Dashboard")), /*#__PURE__*/React.createElement(Text, {
     color: "gray"
   }, count, " container", count === 1 ? "" : "s", " found"));
-}
+}
+Header.propTypes = {
+  count: PropTypes.number.isRequired
+};

package/dist/components/LogViewer.js

@@ -1,22 +1,40 @@
 import React from "react";
 import { Text, useInput } from "ink";
+import { safeCall } from "../helpers/safeCall.js";
+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(_ref) {
+  var _container$name;
   var logs = _ref.logs,
     onExit = _ref.onExit,
     container = _ref.container;
   useInput(function (input, key) {
     if (key.escape) {
-      onExit();
+      safeCall(onExit);
     }
   });
   var visibleLogs = logs.slice(-15);
   return /*#__PURE__*/React.createElement(React.Fragment, null, /*#__PURE__*/React.createElement(Text, {
     color: "green"
-  }, (container === null || container === void 0 ? void 0 : container.name) || "Container", " logs, press ESC to exit"), visibleLogs.length === 0 ? /*#__PURE__*/React.createElement(Text, {
+  }, (_container$name = container === null || container === void 0 ? void 0 : container.name) !== null && _container$name !== void 0 ? _container$name : "Container", " logs, press ESC to exit"), visibleLogs.length === 0 ? /*#__PURE__*/React.createElement(Text, {
     dimColor: true
   }, "No logs...") : visibleLogs.map(function (line, idx) {
     return /*#__PURE__*/React.createElement(Text, {
       key: idx
     }, line);
   }));
-}
+}
+LogViewer.propTypes = {
+  logs: PropTypes.arrayOf(PropTypes.string).isRequired,
+  onExit: PropTypes.func,
+  container: PropTypes.object
+};

package/dist/components/MessageFeedback.js

@@ -1,5 +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(_ref) {
   var message = _ref.message,
     color = _ref.color;
@@ -9,4 +19,8 @@ export default function MessageFeedback(_ref) {
   }, /*#__PURE__*/React.createElement(Text, {
     color: color
   }, message));
-}
+}
+MessageFeedback.propTypes = {
+  message: PropTypes.string,
+  color: PropTypes.string
+};

package/dist/components/PromptField.js

@@ -1,5 +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(_ref) {
   var label = _ref.label,
     value = _ref.value,
@@ -10,6 +22,15 @@ export function PromptField(_ref) {
     color: isEmpty ? "red" : "cyan"
   }, value, "_"));
 }
+
+/**
+ * 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(_ref2) {
   var message = _ref2.message,
     color = _ref2.color;
@@ -17,4 +38,13 @@ export function PromptMessage(_ref2) {
   return /*#__PURE__*/React.createElement(Text, {
     color: color || "yellow"
   }, message);
-}
+}
+PromptField.propTypes = {
+  label: PropTypes.string,
+  value: PropTypes.string,
+  required: PropTypes.bool
+};
+PromptMessage.propTypes = {
+  message: PropTypes.string,
+  color: PropTypes.string
+};