cdd-cli 3.1.0 → 3.1.2

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,30 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Run '...'
+3. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots or logs**
+If applicable, add screenshots or logs to help explain your problem.
+
+**Environment (please complete the following information):**
+- OS: (e.g. Ubuntu 22.04)
+- Node version: (e.g. 18.x)
+- cdd-cli version: (e.g. 3.1.0)
+
+**Additional context**
+Add any other context about the problem here.

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

package/.github/PULL_REQUEST_TEMPLATE/pull_request.md

@@ -0,0 +1,14 @@
+<!-- Please replace the placeholders and remove this comment -->
+## Summary
+
+What does this PR change and why?
+
+## Checklist
+
+- [ ] I have read the contributing guidelines
+- [ ] Tests added / updated
+- [ ] Documentation updated
+
+## Related issues
+
+Closes: # (issue)

package/CHANGELOG.md

@@ -25,3 +25,10 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ## [Unreleased]
 
 - Incoming fixes and smaller tests / docs updates
+
+## [3.1.1] - 2025-10-16
+
+### Fixed
+
+- Minor docs typo fixes and README global install note added.
+

package/README.md

@@ -53,6 +53,22 @@ The dashboard auto-refreshes container list every few seconds.
 
 ---
 
+## Install globally
+
+To install the CLI globally so you can run `cdd` from any terminal, use:
+
+```bash
+npm install -g cdd-cli
+```
+
+After installing globally, run the CLI with:
+
+```bash
+cdd
+```
+
+---
+
 ## Development
 
 - Node.js >= 18 is recommended.

package/fix-imports.cjs

@@ -7,6 +7,9 @@ function addJsExtensionToImports(filePath) {
   // Reemplaza imports relativos sin extensión por .js
   code = code.replace(/(import\s+[^'";]+['"])(\.\/[^'".]+)(['"])/g, '$1$2.js$3');
   code = code.replace(/(from\s+['"])(\.{1,2}\/[^'".]+)(['"])/g, '$1$2.js$3');
+  // También reemplaza importaciones que apunten a archivos .jsx por .js
+  code = code.replace(/(from\s+['"])(\.{1,2}\/[^'"\s]+)\.jsx(['"])/g, '$1$2.js$3');
+  code = code.replace(/(import\s+[^'";]+['"])(\.{1,2}\/[^'"\s]+)\.jsx(['"])/g, '$1$2.js$3');
   fs.writeFileSync(filePath, code, 'utf8');
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdd-cli",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "description": "CLI Docker Dashboard",
   "main": "index.js",
   "scripts": {

package/src/App.jsx

@@ -1,12 +1,10 @@
 /**
  * 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";

package/src/components/ContainerList.jsx

@@ -1,14 +1,12 @@
 /**
  * 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";

package/src/components/ContainerRow.jsx

@@ -18,7 +18,7 @@ export default function ContainerRow({ container }) {
     netIO: { rx: 0, tx: 0 },
   });
 
-  // Formatear puertos
+  // Format ports for display
   const formatPorts = (ports) => {
     if (!ports || ports.length === 0) return "";
     if (Array.isArray(ports)) {

package/src/helpers/actionHelpers.js

@@ -1,3 +1,16 @@
+/**
+ * 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 async function handleAction({
   containers,
   selected,

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

@@ -1,3 +1,10 @@
+/**
+ * Remove (delete) a container by id. Force removal so running containers are stopped first.
+ *
+ * @param {string} containerId - Docker container id
+ * @returns {Promise<void>} Resolves when removal completes
+ * @throws {Error} If Docker reports an error
+ */
 export async function removeContainer(containerId) {
   const container = docker.getContainer(containerId);
   try {
@@ -9,6 +16,14 @@ export async function removeContainer(containerId) {
 import { docker } from "../dockerService";
 import { imageExists, pullImage } from "./imageUtils.js";
 
+/**
+ * Create a new container from an image. If the image is missing locally, it will be pulled.
+ *
+ * @param {string} imageName - Image name (e.g. 'nginx:alpine')
+ * @param {Object} [options] - Docker create options (Env, ExposedPorts, HostConfig, name, etc.)
+ * @returns {Promise<string>} The created container id
+ * @throws {Error} If image listing/pull or creation fails
+ */
 export async function createContainer(imageName, options = {}) {
   let exists;
   try {
@@ -36,16 +51,31 @@ export async function createContainer(imageName, options = {}) {
   }
 }
 
+/**
+ * Start a container by id.
+ * @param {string} containerId - Docker container id
+ * @returns {Promise<void>}
+ */
 export async function startContainer(containerId) {
   const container = docker.getContainer(containerId);
   await container.start();
 }
 
+/**
+ * Stop a container by id.
+ * @param {string} containerId - Docker container id
+ * @returns {Promise<void>}
+ */
 export async function stopContainer(containerId) {
   const container = docker.getContainer(containerId);
   await container.stop();
 }
 
+/**
+ * Restart a container by id.
+ * @param {string} containerId - Docker container id
+ * @returns {Promise<void>}
+ */
 export async function restartContainer(containerId) {
   const container = docker.getContainer(containerId);
   await container.restart();

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

@@ -1,5 +1,9 @@
 import { docker } from "../dockerService";
 
+/**
+ * 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) => ({
@@ -16,7 +20,7 @@ export async function getContainers() {
         if (publicPorts.length > 0) {
           return [...new Set(publicPorts)];
         }
-        // Si no hay puertos públicos, mostrar los privados expuestos
+  // If there are no public ports, show private exposed ports
         const privatePorts = container.Ports.filter((port) => port.PrivatePort).map(
           (port) => `:${port.PrivatePort}`
         );

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

@@ -1,5 +1,13 @@
 import { docker } from "../dockerService";
 
+/**
+ * Return a stream of logs from a container and call callbacks for events.
+ *
+ * @param {string} containerId - Docker container id
+ * @param {Function} onData - Called with chunk string when data arrives
+ * @param {Function} onEnd - Called when stream ends
+ * @param {Function} onError - Called on error
+ */
 export function getLogsStream(containerId, onData, onEnd, onError) {
   const container = docker.getContainer(containerId);
   container.logs({

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

@@ -1,5 +1,11 @@
 import { docker } from "../dockerService";
 
+/**
+ * Retrieve a snapshot of container resource usage (CPU, memory, network).
+ *
+ * @param {string} containerId - Docker container id
+ * @returns {Promise<Object>} Object with cpuPercent, memPercent and netIO {rx,tx}
+ */
 export async function getStats(containerId) {
   const container = docker.getContainer(containerId);
   const stream = await container.stats({ stream: false });

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

@@ -1,5 +1,10 @@
 import { docker } from "../dockerService";
 
+/**
+ * Check whether an image exists locally.
+ * @param {string} imageName - Image name or tag
+ * @returns {Promise<boolean>}
+ */
 export async function imageExists(imageName) {
   const images = await docker.listImages();
   return images.some(img =>
@@ -8,6 +13,11 @@ export async function imageExists(imageName) {
   );
 }
 
+/**
+ * Pull an image from the registry.
+ * @param {string} imageName - Image name to pull
+ * @returns {Promise<void>}
+ */
 export async function pullImage(imageName) {
   await new Promise((resolve, reject) => {
     docker.pull(imageName, (err, stream) => {

package/src/helpers/exitWithMessage.js

@@ -1,5 +1,15 @@
 import { spawn } from "child_process";
 
+/**
+ * Show an exit message using provided setters, clear the terminal and exit after a delay.
+ *
+ * @param {Object} params
+ * @param {Function} params.setMessage - Setter for message text
+ * @param {Function} params.setMessageColor - Setter for message color
+ * @param {string} [params.message] - Message to display
+ * @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 }) {
   setMessage(message);
   setMessageColor(color);

package/src/hooks/useContainers.js

@@ -1,11 +1,9 @@
 /**
  * React hook to manage Docker containers state.
- * Hook de React para gestionar el estado de contenedores Docker.
  *
  * @returns {[Array, Function]} [containers, refresh] / [contenedores, refrescar]
  * @example
- * // EN: Use in a component
- * // ES: Usar en un componente
+ * // Use in a component
  * const [containers, refresh] = useContainers();
  */
 import React, { useState, useEffect } from "react";

package/src/hooks/useControls.js

@@ -7,6 +7,29 @@ import { getLogsStream } from "../helpers/dockerService/serviceComponents/contai
 import { createContainer as svcCreateContainer } from "../helpers/dockerService/serviceComponents/containerActions.js";
 
 // Principal hook to manage user inputs and control the app state
+/**
+ * Main hook that wires user input, creation, actions and logs viewing.
+ * It coordinates the modular hooks and exposes a compact API consumed by the App.
+ *
+ * @param {Array<Object>} containers - Current list of Docker containers
+ * @returns {Object} controls - API for the App component
+ * @property {number} selected - Index of the currently selected container
+ * @property {function} setSelected - Setter for selected index
+ * @property {string} message - Current feedback message (creation or actions)
+ * @property {string} messageColor - Color to show for the feedback message
+ * @property {boolean} showLogs - Whether the logs viewer is active
+ * @property {Array<string>} logs - Array of log lines currently collected
+ * @property {function} exitLogs - Helper to close the logs viewer
+ * @property {boolean} creatingContainer - Whether the create-container prompt is open
+ * @property {number} creationStep - Current step in the creation flow
+ * @property {string} imageNameInput - Current value of the image name field
+ * @property {string} containerNameInput - Current value of the container name field
+ * @property {string} portInput - Current value of the port input field
+ * @property {string} envInput - Current value of the env input field
+ * @property {Object} creation - The creation hook API (setters and helpers)
+ * @property {Object} actions - The actions hook API (helpers to start/stop/remove)
+ * @property {Object} logsViewer - The logs viewer hook API
+ */
 export function useControls(containers = []) {
   const [selected, setSelected] = React.useState(0);
   const [creatingContainer, setCreatingContainer] = React.useState(false);
@@ -61,7 +84,7 @@ export function useControls(containers = []) {
   const exitLogs = logsViewer.closeLogs;
 
   useInput((input, key) => {
-    // Confirmación de borrado
+  // Erase confirmation
     if (confirmErase) {
       if (input === "y" || input === "Y") {
         actions.handleAction({

package/src/hooks/useLogsStream.js

@@ -1,6 +1,11 @@
 import React, { useRef, useCallback } from "react";
 import { getLogsStream } from "../helpers/dockerService/serviceComponents/containerLogs";
 
+/**
+ * Hook that manages opening and closing a logs stream for a container.
+ *
+ * @returns {Object} { openLogs, closeLogs }
+ */
 export function useLogsStream() {
   const logsStreamRef = useRef(null);
 

package/src/index.js

@@ -1,17 +1,13 @@
 #!/usr/bin/env node
-
 /**
  * Entry point for the CDD CLI application.
- * Punto de entrada para la aplicación CLI de CDD.
  *
  * @module index
  * @example
- * // EN: Run the CLI
- * // ES: Ejecutar el CLI
+ * // Run the CLI
  * node index.js
  */
 
-
 import React from "react";
 import { render } from "ink";
 import App from './App';