cdd-cli 3.2.2 → 4.1.0

package/README.es.md

@@ -0,0 +1,222 @@
+# CDD — CLI Docker Dashboard
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/cdd-cli?color=blue&label=npm%20package" alt="npm version"/>
+  <img src="https://img.shields.io/npm/dt/cdd-cli?color=green&label=downloads" alt="npm downloads"/>
+  <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>
+  <a href="https://deepwiki.com/Caertos/cdd"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
+</p>
+
+> **Un dashboard de Docker para la terminal — monitorea, gestiona y crea contenedores sin salir del teclado.**
+
+---
+
+## 🎉 Novedades en v4.1
+
+**Abrí un shell dentro de cualquier contenedor con una sola tecla.**
+
+Presiona `S` y CDD te lleva a un shell interactivo completo (`bash` o `sh`) dentro del contenedor seleccionado — sin necesidad de escribir `docker exec`.
+
+- **Shell auto-detectado** — CDD sondea el contenedor y elige `bash` o `sh` automáticamente
+- **Soporte de terminal completo** — ejecutá `psql`, `python3`, `node`, `redis-cli`, o cualquier comando dentro del contenedor
+- **Salida limpia** — escribí `exit` o presioná `Ctrl+D` para volver al dashboard
+
+---
+
+## Versiones anteriores
+
+### v3.2 — Asistente de creación interactivo
+
+Olvídate de los flags de `docker run`, las variables de entorno olvidadas y los tags `:latest` que fallan en silencio. Presiona `C` y CDD te guía para crear un contenedor en segundos:
+
+- **20 perfiles de imagen curados** disponibles sin conexión — postgres, redis, nginx, node, mysql, mongo y más
+- **Tags por defecto que realmente funcionan**: `postgres:17-alpine`, `redis:7-alpine`, `nginx:1.27-alpine` — sin más fallos silenciosos por `:latest`
+- **Búsqueda en vivo en Docker Hub** con un solo `Tab` — con indicador `[searching Docker Hub...]` para que siempre sepas qué está pasando
+- **Sugerencias contextuales de variables de entorno** — ¿creando un contenedor de Postgres? CDD sugiere `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` automáticamente
+- **HUD sensible al contexto** — solo se muestran las teclas que tienen sentido en ese momento, nada más
+
+Así debería sentirse la experiencia de desarrollo.
+
+---
+
+## Características
+
+- 🐳 Vista en vivo de todos los contenedores Docker con estadísticas de CPU/memoria
+- 🔄 Auto-refresco cada pocos segundos — siempre actualizado
+- ⌨️ Acciones controladas por teclado: iniciar, detener, reiniciar, ver logs, eliminar
+- 🎨 Estados de contenedor codificados por color y retroalimentación visual
+- ✨ **Asistente de creación interactivo** — configuración paso a paso con perfiles curados y búsqueda en Hub
+- 🪵 Streaming de logs en tiempo real para el contenedor seleccionado
+- 🐛 Panel de debug en vivo activable con la tecla `D`
+
+---
+
+## Instalación global
+
+```bash
+npm install -g cdd-cli
+cdd
+```
+
+---
+
+## Inicio rápido (local)
+
+```bash
+git clone https://github.com/caertos/cdd.git
+cd cdd
+npm install
+npm run build
+node dist/index.js
+```
+
+Para usar como comando global durante el desarrollo:
+
+```bash
+npm link
+cdd
+```
+
+---
+
+## Uso
+
+Usa `↑` / `↓` para navegar por los contenedores. Atajos de teclado disponibles:
+
+| Tecla | Acción |
+|-------|--------|
+| `↑` / `↓` | Navegar la lista de contenedores |
+| `I` | Iniciar el contenedor seleccionado |
+| `P` | Detener el contenedor seleccionado |
+| `R` | Reiniciar el contenedor seleccionado |
+| `C` | Abrir el asistente de creación |
+| `L` | Ver logs del contenedor seleccionado en tiempo real |
+| `S` | Abrir shell interactivo dentro del contenedor seleccionado |
+| `E` | Eliminar el contenedor seleccionado — requiere confirmación |
+| `D` | Activar/desactivar panel de debug en vivo |
+| `Q` | Salir |
+
+---
+
+## El Asistente de Creación
+
+Presiona `C` desde el dashboard para abrir el asistente. Un **HUD sensible al contexto** en la parte inferior siempre muestra qué teclas están activas en cada paso — sin adivinar.
+
+### Paso 0 — Imagen
+
+Escribe para filtrar entre **20 perfiles offline curados** (postgres, redis, nginx, node, mysql, mongo, python, golang y más). Los resultados aparecen al instante.
+
+Presiona **`Tab`** en cualquier momento para buscar en Docker Hub en vivo. Un indicador `[searching Docker Hub...]` confirma que la búsqueda está en curso. Usa `↑` / `↓` para navegar las sugerencias y `Enter` para seleccionar.
+
+**Tags inteligentes por defecto:** al seleccionar un perfil de imagen se aplica automáticamente un tag conocido y funcional — `postgres:17-alpine`, `redis:7-alpine`, `nginx:1.27-alpine`, etc. Sin más contenedores que fallan en silencio por un `:latest` desactualizado.
+
+### Paso 1 — Nombre del contenedor
+
+Texto libre. Dale a tu contenedor un nombre memorable.
+
+### Paso 2 — Mapeo de puertos
+
+Ingresa un mapeo de puertos en formato `HOST:CONTENEDOR`, por ejemplo `8080:80`, `5432:5432`. Deja en blanco para omitir.
+
+### Paso 3 — Variables de entorno
+
+Ingresa pares `CLAVE=VALOR` de a uno. Las **sugerencias contextuales** muestran variables recomendadas para la imagen seleccionada:
+
+| Imagen | Variables sugeridas |
+|--------|---------------------|
+| postgres | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` |
+| mysql | `MYSQL_ROOT_PASSWORD`, `MYSQL_DATABASE` |
+| redis | *(sin variables requeridas)* |
+| mongo | `MONGO_INITDB_ROOT_USERNAME`, `MONGO_INITDB_ROOT_PASSWORD` |
+| node / nginx / otros | Variables de runtime comunes según corresponda |
+
+Presiona `Enter` en una línea vacía para terminar y crear el contenedor.
+
+---
+
+## Shell Interactivo
+
+Presiona `S` desde el dashboard con un contenedor en ejecución seleccionado. CDD hará lo siguiente:
+
+1. Detectará el shell disponible dentro del contenedor (`bash` o `sh`)
+2. Abrirá una sesión de terminal interactiva completa
+3. Te dejará en el shell del contenedor
+
+Desde ahí podés ejecutar cualquier comando — `psql` para PostgreSQL, `python3` para Python, `node` para Node.js, `redis-cli` para Redis, etc.
+
+Escribí `exit` o presioná `Ctrl+D` para salir del shell y volver al dashboard de CDD.
+
+---
+
+## Requisitos
+
+- Node.js >= 18
+- Docker instalado y ejecutándose (CDD se conecta al socket local de Docker)
+
+---
+
+## Desarrollo
+
+```bash
+npm install
+npm run build        # compila src/ → dist/
+node dist/index.js   # ejecuta desde la salida compilada
+```
+
+Vuelve a ejecutar `npm run build` después de cualquier cambio en el código fuente. Usa `npm link` para probar el comando global `cdd` localmente.
+
+---
+
+## Tests
+
+```bash
+npm test
+```
+
+Los tests están en `test/` y cubren helpers, servicios y hooks.
+
+---
+
+## Logging
+
+Por defecto CDD muestra mensajes `info`, `warn` y `error`. Para diagnósticos más detallados:
+
+```bash
+CDD_LOG_LEVEL=debug cdd
+```
+
+Presiona `D` dentro del dashboard para activar el panel de debug en vivo. Presiona `D` nuevamente para ocultarlo.
+
+Para capturar los logs en un archivo:
+
+```bash
+CDD_LOG_LEVEL=debug cdd > cdd-debug.log 2>&1
+```
+
+---
+
+## Solución de problemas
+
+- **¿No ves contenedores?** Asegúrate de que Docker esté ejecutándose y de que tu usuario tenga acceso al socket de Docker.
+- **¿Errores de permisos en Linux/macOS?** Prueba con `sudo cdd` o agrega tu usuario al grupo `docker`.
+- **¿Windows?** Ejecuta la terminal como Administrador.
+- **¿Falta el directorio `dist/`?** Ejecuta `npm run build` — está en `.gitignore` y no se incluye en el repositorio.
+- **¿La búsqueda del asistente no funciona?** Verifica tu conexión a internet. Los perfiles offline siempre funcionan sin acceso a la red.
+
+---
+
+## Contribuciones
+
+Consulta [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## Licencia
+
+MIT/ISC — ver [`LICENSE`](LICENSE).
+
+---
+
+🇬🇧 [Read in English](README.md)

package/README.md

@@ -1,4 +1,4 @@
-## CDD-CLI — Docker Dashboard (Terminal)
+# CDD — CLI Docker Dashboard
 
 <p align="center">
   <img src="https://img.shields.io/npm/v/cdd-cli?color=blue&label=npm%20package" alt="npm version"/>
@@ -6,24 +6,50 @@
   <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>
-  <a href="https://caertos.github.io/cdd/">
-    <img src="https://img.shields.io/badge/docs-GitHub%20Pages-blue" alt="Docs" />
-  </a>
   <a href="https://deepwiki.com/Caertos/cdd"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
 </p>
 
-A terminal dashboard for monitoring and managing Docker containers in real time. Shows live CPU/memory stats, supports keyboard-driven actions, and requires no GUI.
+> **A terminal dashboard for Docker containers — monitor, manage, and create, all without leaving your keyboard.**
+
+---
+
+## 🎉 What's new in v4.1
+
+**Open a shell inside any container with a single keystroke.**
+
+Press `S` and CDD drops you into a full interactive shell (`bash` or `sh`) inside the selected container — no `docker exec` typing needed.
+
+- **Auto-detected shell** — CDD probes the container and picks `bash` or `sh` automatically
+- **Full terminal support** — run `psql`, `python3`, `node`, `redis-cli`, or any command inside the container
+- **Clean exit** — type `exit` or press `Ctrl+D` to return to the dashboard
+
+---
+
+## Previous releases
+
+### v3.2 — Interactive creation wizard
+
+Forget `docker run` flags, forgotten env vars, and broken `:latest` tags. Press `C` and CDD guides you through creating a container in seconds:
+
+- **20 curated image profiles** available offline — postgres, redis, nginx, node, mysql, mongo, and more
+- **Smart default tags** that actually work: `postgres:17-alpine`, `redis:7-alpine`, `nginx:1.27-alpine` — no more silent `:latest` failures
+- **Live Docker Hub search** with a single `Tab` keystroke — with a `[searching Docker Hub...]` indicator so you always know what's happening
+- **Contextual env var hints** — creating a Postgres container? CDD suggests `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` automatically
+- **Context-sensitive HUD** — only the keys that make sense right now are shown, nothing more
+
+This is what developer experience should feel like.
 
 ---
 
 ## Features
 
-- 🐳 Clear, compact view of all Docker containers
-- 🔄 Auto-refresh every few seconds
-- ⌨️ Keyboard shortcuts for fast actions (navigate, start, stop, logs, quit)
-- 📊 Live CPU and memory stats for running containers
-- 🪵 Real-time log streaming for selected containers
-- 🎨 Color-coded states and visual feedback
+- 🐳 Live view of all Docker containers with CPU/memory stats
+- 🔄 Auto-refresh every few seconds — always up to date
+- ⌨️ Keyboard-driven actions: start, stop, restart, log streaming, removal
+- 🎨 Color-coded container states and visual feedback
+- ✨ **Interactive creation wizard** — step-by-step container setup with curated profiles and live Hub search
+- 🪵 Real-time log streaming for any selected container
+- 🐛 Toggleable live debug panel (`D` key)
 
 ---
 
@@ -46,7 +72,7 @@ npm run build
 node dist/index.js
 ```
 
-To use it as a global command during development:
+To use as a global command during development:
 
 ```bash
 npm link
@@ -57,25 +83,77 @@ cdd
 
 ## Usage
 
-Use ↑/↓ to navigate containers. Available keyboard shortcuts:
+Use `↑` / `↓` to navigate containers. Available keyboard shortcuts:
 
 | Key | Action |
 |-----|--------|
+| `↑` / `↓` | Navigate container list |
 | `I` | Start selected container |
 | `P` | Stop selected container |
 | `R` | Restart selected container |
-| `C` | Create container (interactive prompt) |
-| `L` | View logs for selected container |
+| `C` | Open creation wizard |
+| `L` | Stream logs for selected container |
+| `S` | Open interactive shell inside selected container |
 | `E` | Erase (remove) selected container — confirmation required |
-| `D` | Toggle live debug log panel |
+| `D` | Toggle live debug panel |
 | `Q` | Quit |
 
 ---
 
+## The Creation Wizard
+
+Press `C` from the dashboard to launch the wizard. A **context-sensitive HUD** at the bottom always shows which keys are active at each step — no guessing required.
+
+### Step 0 — Image
+
+Type to filter through **20 curated offline profiles** (postgres, redis, nginx, node, mysql, mongo, python, golang, and more). Results appear instantly.
+
+Press **`Tab`** at any time to search Docker Hub live. A `[searching Docker Hub...]` indicator confirms the search is running. Use `↑` / `↓` to navigate suggestions, `Enter` to select.
+
+**Smart default tags:** selecting an image profile automatically applies a known-good tag — `postgres:17-alpine`, `redis:7-alpine`, `nginx:1.27-alpine`, etc. No more containers that fail silently because of a stale `:latest`.
+
+### Step 1 — Container name
+
+Free-text input. Give your container a memorable name.
+
+### Step 2 — Port mapping
+
+Enter a port mapping in `HOST:CONTAINER` format, e.g. `8080:80`, `5432:5432`. Leave blank to skip.
+
+### Step 3 — Environment variables
+
+Enter `KEY=VALUE` pairs one at a time. **Contextual hints** show recommended variables for the selected image:
+
+| Image | Suggested vars |
+|-------|---------------|
+| postgres | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` |
+| mysql | `MYSQL_ROOT_PASSWORD`, `MYSQL_DATABASE` |
+| redis | *(no required vars)* |
+| mongo | `MONGO_INITDB_ROOT_USERNAME`, `MONGO_INITDB_ROOT_PASSWORD` |
+| node / nginx / others | Common runtime vars as applicable |
+
+Press `Enter` on an empty line to finish and create the container.
+
+---
+
+## Interactive Shell
+
+Press `S` from the dashboard while a running container is selected. CDD will:
+
+1. Detect the available shell inside the container (`bash` or `sh`)
+2. Open a full interactive terminal session
+3. Drop you into the container's shell
+
+From there you can run any command — `psql` for PostgreSQL, `python3` for Python, `node` for Node.js, `redis-cli` for Redis, etc.
+
+Type `exit` or press `Ctrl+D` to leave the shell and return to the CDD dashboard.
+
+---
+
 ## Requirements
 
 - Node.js >= 18
-- Docker installed and running (CLI connects to the local Docker socket)
+- Docker installed and running (CDD connects to the local Docker socket)
 
 ---
 
@@ -87,7 +165,7 @@ npm run build        # compile src/ → dist/
 node dist/index.js   # run from compiled output
 ```
 
-Re-run `npm run build` after any source changes.
+Re-run `npm run build` after any source changes. Use `npm link` to test the global `cdd` command locally.
 
 ---
 
@@ -97,21 +175,19 @@ Re-run `npm run build` after any source changes.
 npm test
 ```
 
-Tests are in `test/` and cover helpers, services, and hooks.
+Tests live in `test/` and cover helpers, services, and hooks.
 
 ---
 
 ## Logging
 
-By default the CLI shows `info`, `warn`, and `error` messages. For deeper diagnostics:
+By default CDD shows `info`, `warn`, and `error` messages. For deeper diagnostics:
 
 ```bash
 CDD_LOG_LEVEL=debug cdd
-# or
-CDD_LOG_LEVEL=debug node dist/index.js
 ```
 
-Press `D` inside the CLI to toggle the live debug panel. Press `D` again or `Esc` to hide it.
+Press `D` inside the dashboard to toggle the live debug panel in real time. Press `D` again to hide it.
 
 To capture logs to a file:
 
@@ -123,9 +199,11 @@ CDD_LOG_LEVEL=debug cdd > cdd-debug.log 2>&1
 
 ## Troubleshooting
 
-- If you don't see containers, ensure Docker is running and your user has access to the Docker socket.
-- On Linux/macOS, try `sudo cdd` if you have permission issues. On Windows, run as Administrator.
-- `dist/` is generated by the build — it's in `.gitignore` and should not be committed.
+- **No containers visible?** Make sure Docker is running and your user has access to the Docker socket.
+- **Permission errors on Linux/macOS?** Try `sudo cdd` or add your user to the `docker` group.
+- **Windows?** Run your terminal as Administrator.
+- **`dist/` missing?** Run `npm run build` — it's in `.gitignore` and not committed.
+- **Wizard search not working?** Check your internet connection. Offline profiles always work without network access.
 
 ---
 
@@ -138,3 +216,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 ## License
 
 MIT/ISC — see [`LICENSE`](LICENSE).
+
+---
+
+🇪🇸 [Ver en Español](README.es.md)

package/dist/App.js

@@ -32,7 +32,13 @@ export default function App() {
       portInput: controls.portInput,
       envInput: controls.envInput,
       message: controls.message,
-      messageColor: controls.messageColor
+      messageColor: controls.messageColor,
+      suggestions: controls.creation.suggestions,
+      selectedSuggestionIndex: controls.creation.selectedSuggestionIndex,
+      visibleOffset: controls.creation.visibleOffset,
+      isSearchingHub: controls.creation.isSearchingHub,
+      hubResults: controls.creation.hubResults,
+      hasSuggestedEnv: controls.creation.hasSuggestedEnv
     });
   }
   return /*#__PURE__*/React.createElement(React.Fragment, null, /*#__PURE__*/React.createElement(Box, {

package/dist/components/ContainerCreationPrompt.js

@@ -1,7 +1,8 @@
 import React from 'react';
-import { Box, Text } from 'ink';
+import { Box } from 'ink';
 import { PromptField, PromptMessage } from './PromptField.js';
 import { SuggestionPanel } from './SuggestionPanel.js';
+import { ControlsHUD } from './ControlsHUD.js';
 import PropTypes from 'prop-types';
 
 /**
@@ -35,9 +36,15 @@ export default function ContainerCreationPrompt(props) {
     _props$selectedSugges = props.selectedSuggestionIndex,
     selectedSuggestionIndex = _props$selectedSugges === void 0 ? -1 : _props$selectedSugges,
     _props$visibleOffset = props.visibleOffset,
-    visibleOffset = _props$visibleOffset === void 0 ? 0 : _props$visibleOffset;
+    visibleOffset = _props$visibleOffset === void 0 ? 0 : _props$visibleOffset,
+    _props$hubResults = props.hubResults,
+    hubResults = _props$hubResults === void 0 ? null : _props$hubResults,
+    _props$isSearchingHub = props.isSearchingHub,
+    isSearchingHub = _props$isSearchingHub === void 0 ? false : _props$isSearchingHub,
+    _props$hasSuggestedEn = props.hasSuggestedEnv,
+    hasSuggestedEnv = _props$hasSuggestedEn === void 0 ? false : _props$hasSuggestedEn;
   var prompts = [{
-    label: 'Name of the image to create (e.g., nginx:latest):',
+    label: 'Name of the image to create (e.g., nginx:1.27-alpine):',
     value: imageName,
     required: true
   }, {
@@ -57,7 +64,9 @@ export default function ContainerCreationPrompt(props) {
     label = _ref.label,
     value = _ref.value,
     required = _ref.required;
-  var showSuggestions = step === 0 && suggestions.length > 0;
+  var activeItems = hubResults !== null && hubResults !== void 0 ? hubResults : suggestions;
+  var showSuggestions = step === 0 && (isSearchingHub || activeItems.length > 0);
+  var hasSuggestions = (suggestions === null || suggestions === void 0 ? void 0 : suggestions.length) > 0 || (hubResults === null || hubResults === void 0 ? void 0 : hubResults.length) > 0;
   return /*#__PURE__*/React.createElement(Box, {
     flexDirection: "column",
     borderStyle: "round",
@@ -68,15 +77,19 @@ export default function ContainerCreationPrompt(props) {
     value: value,
     required: required
   }), showSuggestions && /*#__PURE__*/React.createElement(SuggestionPanel, {
-    items: suggestions,
+    items: activeItems,
     selectedIndex: selectedSuggestionIndex,
-    visibleOffset: visibleOffset
+    visibleOffset: visibleOffset,
+    isLoading: isSearchingHub
   }), /*#__PURE__*/React.createElement(PromptMessage, {
     message: message,
     color: messageColor
-  }), /*#__PURE__*/React.createElement(Text, {
-    dimColor: true
-  }, "Press Enter to continue, Escape to cancel"));
+  }), /*#__PURE__*/React.createElement(ControlsHUD, {
+    step: step,
+    hasSuggestions: hasSuggestions,
+    isSearchingHub: isSearchingHub,
+    hasSuggestedEnv: hasSuggestedEnv
+  }));
 }
 ContainerCreationPrompt.propTypes = {
   step: PropTypes.number.isRequired,
@@ -88,7 +101,10 @@ ContainerCreationPrompt.propTypes = {
   messageColor: PropTypes.string,
   suggestions: PropTypes.arrayOf(PropTypes.string),
   selectedSuggestionIndex: PropTypes.number,
-  visibleOffset: PropTypes.number
+  visibleOffset: PropTypes.number,
+  hubResults: PropTypes.arrayOf(PropTypes.string),
+  isSearchingHub: PropTypes.bool,
+  hasSuggestedEnv: PropTypes.bool
 };
 
 // Named export for test compatibility with jest ESM interop

package/dist/components/ControlsHUD.js

@@ -0,0 +1,106 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+
+/**
+ * Returns the contextual keyboard hints for the current wizard state.
+ *
+ * @param {number} step - Current wizard step (0-3)
+ * @param {boolean} hasSuggestions - Whether suggestions/hub results are visible
+ * @param {boolean} isSearchingHub - Whether a Hub search is in progress
+ * @param {boolean} [hasSuggestedEnv=false] - Whether the image has suggestedEnv entries
+ * @returns {{ key: string, label: string }[]}
+ */
+function getHints(step, hasSuggestions, isSearchingHub) {
+  var hasSuggestedEnv = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : false;
+  if (step === 0) {
+    if (hasSuggestions) {
+      return [{
+        key: '↑↓',
+        label: 'Navigate'
+      }, {
+        key: 'Enter',
+        label: 'Select'
+      }, {
+        key: 'Esc',
+        label: 'Cancel'
+      }];
+    }
+    var hints = [];
+    if (!isSearchingHub) hints.push({
+      key: 'Tab',
+      label: 'Search Hub'
+    });
+    hints.push({
+      key: '↑↓',
+      label: 'Browse'
+    });
+    hints.push({
+      key: 'Enter',
+      label: 'Confirm'
+    });
+    hints.push({
+      key: 'Esc',
+      label: 'Cancel'
+    });
+    return hints;
+  }
+  if (step === 3) {
+    var _hints = [];
+    if (hasSuggestedEnv) _hints.push({
+      key: 'Tab',
+      label: 'Insert next env'
+    });
+    _hints.push({
+      key: 'Enter',
+      label: 'Continue'
+    });
+    _hints.push({
+      key: 'Esc',
+      label: 'Cancel'
+    });
+    return _hints;
+  }
+  return [{
+    key: 'Enter',
+    label: 'Continue'
+  }, {
+    key: 'Esc',
+    label: 'Cancel'
+  }];
+}
+
+/**
+ * Displays a row of contextual keyboard shortcut hints for the active wizard step.
+ *
+ * @param {Object} props
+ * @param {number} props.step - Current wizard step
+ * @param {boolean} [props.hasSuggestions=false] - Whether suggestions/hub results are visible
+ * @param {boolean} [props.isSearchingHub=false] - Whether a Hub search is in progress
+ * @param {boolean} [props.hasSuggestedEnv=false] - Whether the image has suggestedEnv entries
+ */
+function ControlsHUD(_ref) {
+  var step = _ref.step,
+    _ref$hasSuggestions = _ref.hasSuggestions,
+    hasSuggestions = _ref$hasSuggestions === void 0 ? false : _ref$hasSuggestions,
+    _ref$isSearchingHub = _ref.isSearchingHub,
+    isSearchingHub = _ref$isSearchingHub === void 0 ? false : _ref$isSearchingHub,
+    _ref$hasSuggestedEnv = _ref.hasSuggestedEnv,
+    hasSuggestedEnv = _ref$hasSuggestedEnv === void 0 ? false : _ref$hasSuggestedEnv;
+  var hints = getHints(step, hasSuggestions, isSearchingHub, hasSuggestedEnv);
+  return /*#__PURE__*/React.createElement(Box, {
+    flexDirection: "row",
+    columnGap: 2
+  }, hints.map(function (_ref2) {
+    var key = _ref2.key,
+      label = _ref2.label;
+    return /*#__PURE__*/React.createElement(Box, {
+      key: key
+    }, /*#__PURE__*/React.createElement(Text, {
+      color: "cyan"
+    }, "[", key, "]"), /*#__PURE__*/React.createElement(Text, {
+      dimColor: true
+    }, " ", label));
+  }));
+}
+export default ControlsHUD;
+export { getHints, ControlsHUD };

package/dist/components/SuggestionPanel.js

@@ -19,26 +19,35 @@ export function SuggestionPanel(_ref) {
     selectedIndex = _ref.selectedIndex,
     visibleOffset = _ref.visibleOffset,
     _ref$maxVisible = _ref.maxVisible,
-    maxVisible = _ref$maxVisible === void 0 ? 6 : _ref$maxVisible;
-  if (!items || items.length === 0) return null;
-  var visible = items.slice(visibleOffset, visibleOffset + maxVisible);
+    maxVisible = _ref$maxVisible === void 0 ? 6 : _ref$maxVisible,
+    _ref$isLoading = _ref.isLoading,
+    isLoading = _ref$isLoading === void 0 ? false : _ref$isLoading;
+  var hasItems = items && items.length > 0;
+  if (!hasItems && !isLoading) return null;
+  var visible = hasItems ? items.slice(visibleOffset, visibleOffset + maxVisible) : [];
   return /*#__PURE__*/React.createElement(Box, {
     flexDirection: "column",
     borderStyle: "single",
     borderColor: "cyan",
-    paddingX: 1
+    paddingX: 1,
+    "data-testid": "suggestion-panel"
   }, visible.map(function (item, localIdx) {
     var globalIdx = visibleOffset + localIdx;
     var isFocused = globalIdx === selectedIndex;
     return /*#__PURE__*/React.createElement(Text, {
       key: item,
-      color: isFocused ? 'cyan' : undefined
+      color: isFocused ? 'cyan' : undefined,
+      dimColor: !isFocused
     }, isFocused ? "\u203A ".concat(item) : "  ".concat(item));
-  }));
+  }), isLoading && /*#__PURE__*/React.createElement(Text, {
+    dimColor: true,
+    color: "gray"
+  }, '  [searching Docker Hub...]'));
 }
 SuggestionPanel.propTypes = {
   items: PropTypes.arrayOf(PropTypes.string).isRequired,
   selectedIndex: PropTypes.number.isRequired,
   visibleOffset: PropTypes.number.isRequired,
-  maxVisible: PropTypes.number
+  maxVisible: PropTypes.number,
+  isLoading: PropTypes.bool
 };

package/dist/components/UsageMenu.js

@@ -1,6 +1,6 @@
 import React from 'react';
 import { Box, Text } from 'ink';
-var 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'];
+var 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', 'S to open shell in selected container', 'D to toggle debug log panel', 'E to remove selected container', 'Q to quit'];
 var GRID_COLUMNS = 3;
 
 /**