custom-menu-cli 2.0.1 → 4.0.0

package/README-pt.md

@@ -1,5 +1,7 @@
 # Custom Menu CLI
 
+<img src="./docs/icon.png" alt="Custom Menu CLI Icon" width="600px" height="400px"/>
+
 ![Exemplo de Menu 1](./docs/example1.png)
 ![Exemplo de Menu 2](./docs/example2.png)
 
@@ -11,7 +13,9 @@ Esta é uma ferramenta de interface de linha de comando (CLI) que cria um menu i
 - Estrutura do menu definida por um arquivo JSON.
 - Fácil de configurar e usar.
 - Suporte para execução de comandos com confirmação.
-
+- Execute sequências de ações diretamente da linha de comando.
+- Estrutura interna aprimorada pela unificação da lógica de execução de ações.
+- Validação de dependência aprimorada com verificações de profundidade de recursão para evitar aninhamento excessivo.
 
 ## Lançamentos
 
@@ -88,6 +92,60 @@ async function iniciarMeuMenuCustomizado() {
 iniciarMeuMenuCustomizado();
 ```
 
+### 4. Geração de Menu Baseada em Pastas
+
+O `custom-menu-cli` agora suporta a geração de menus a partir de uma pasta estruturada contendo arquivos JSON. Isso permite uma melhor organização e modularidade das suas definições de menu.
+
+**Estrutura de Exemplo (`test_menus/`):**
+```
+test_menus/
+├── 1-project-a/
+│   ├── 1.1-down-service.json
+│   ├── 1.2-up-service.json
+│   └── 1.3-restart-project-a.json
+├── 2-restart-all.json
+└── 3-restart-project-a-nested.json
+```
+
+Cada arquivo `.json` dentro da pasta (e suas subpastas) representa uma opção de menu. Os diretórios são automaticamente convertidos em opções do tipo `navigation`.
+
+**Como usar:**
+
+Basta passar o caminho para a sua pasta de menu como argumento:
+
+```bash
+custom-menu-cli ./caminho/para/sua/pasta_de_menu
+```
+
+O CLI irá automaticamente descobrir e combinar todos os arquivos JSON válidos em uma única estrutura de menu.
+
+### 5. Execução de Ações pela Linha de Comando
+
+Você pode executar uma sequência de ações diretamente da linha de comando, sem entrar no menu interativo. Isso é útil para scripts e automação.
+
+**Uso:**
+
+```bash
+node index.js menu=<caminho-para-o-menu> custom-action=<id_da_acao_1>,<id_da_acao_2>,...
+```
+
+- `menu=<caminho-para-o-menu>`: O caminho para o seu arquivo ou diretório de menu.
+- `custom-action=<ids_das_acoes>`: Uma lista de IDs de ações, separados por vírgula, para executar em sequência.
+
+**Exemplos:**
+
+```bash
+# Executar uma única ação
+node index.js menu=menu.json custom-action=1.1
+
+# Executar uma sequência de ações
+node index.js menu=./test_menus/ custom-action=1.1,1.2
+```
+
+**Validação de Profundidade de Recursão:**
+
+A ferramenta agora inclui validação de profundidade de recursão para evitar ações customizadas aninhadas excessivamente profundas e potenciais loops infinitos. Se uma sequência de ações customizadas exceder uma profundidade máxima de recursão predefinida, a ferramenta detectará e se recusará a executar, exibindo uma mensagem de erro. Isso ajuda a manter a estabilidade e a previsibilidade em estruturas de menu complexas.
+
 ## Estrutura do JSON
 
 O arquivo JSON que define o menu tem a seguinte estrutura:

package/README.md

@@ -1,5 +1,7 @@
 # Custom Menu CLI
 
+<img src="./docs/icon.png" alt="Custom Menu CLI Icon" width="600px" height="400px"/>
+
 [Português (Brasil)](./README-pt.md)
 
 ![Menu Example 1](./docs/example1.png)
@@ -13,6 +15,9 @@ This is a command-line interface (CLI) tool that creates an interactive menu bas
 - Menu structure defined by a JSON file.
 - Easy to configure and use.
 - Support for command execution with confirmation.
+- Execute action sequences directly from the command line.
+- Improved internal structure by unifying action execution logic.
+- Enhanced dependency validation with recursion depth checks to prevent excessive nesting.
 
 ## Releases
 
@@ -89,6 +94,60 @@ async function startMyCustomMenu() {
 startMyCustomMenu();
 ```
 
+### 4. Folder-based Menu Generation
+
+The `custom-menu-cli` now supports generating menus from a structured folder containing JSON files. This allows for better organization and modularity of your menu definitions.
+
+**Example Structure (`test_menus/`):**
+```
+test_menus/
+├── 1-project-a/
+│   ├── 1.1-down-service.json
+│   ├── 1.2-up-service.json
+│   └── 1.3-restart-project-a.json
+├── 2-restart-all.json
+└── 3-restart-project-a-nested.json
+```
+
+Each `.json` file within the folder (and its subfolders) represents a menu option. Directories are automatically converted into `navigation` type options.
+
+**How to use:**
+
+Simply pass the path to your menu folder as an argument:
+
+```bash
+custom-menu-cli ./path/to/your/menu_folder
+```
+
+The CLI will automatically discover and combine all valid JSON files into a single menu structure.
+
+### 5. Command-Line Action Execution
+
+You can execute a sequence of actions directly from the command line without entering the interactive menu. This is useful for scripting and automation.
+
+**Usage:**
+
+```bash
+node index.js menu=<path-to-menu> custom-action=<action_id_1>,<action_id_2>,...
+```
+
+- `menu=<path-to-menu>`: The path to your menu file or directory.
+- `custom-action=<action_ids>`: A comma-separated list of action IDs to execute in sequence.
+
+**Examples:**
+
+```bash
+# Execute a single action
+node index.js menu=menu.json custom-action=1.1
+
+# Execute a sequence of actions
+node index.js menu=./test_menus/ custom-action=1.1,1.2
+```
+
+**Recursion Depth Validation:**
+
+The tool now includes recursion depth validation to prevent excessively deep nested custom actions and potential infinite loops. If a sequence of custom actions exceeds a predefined maximum recursion depth, the tool will detect it and refuse to execute, displaying an error message. This helps maintain stability and predictability in complex menu structures.
+
 ## JSON Structure
 
 The JSON file that defines the menu has the following structure:

package/index.js

@@ -1,24 +1,40 @@
 #!/usr/bin/env node
 
 const { loadMenuConfig } = require('./src/configLoader.js');
-const { showMenu, buildIdMap } = require('./src/menu.js');
+const { showMenu, buildIdMap, flatMap } = require('./src/menu.js');
 const { displayHeader } = require('./src/header.js');
+const { parseArgs } = require('./src/args.js');
+const { validateRecursionDepth } = require('./src/dependencyValidator.js');
+
+
+const { validateMenu } = require('./src/menuValidator.js');
+
+async function runCli() {
+    const { menuPath, customActions } = parseArgs();
+    const data = await loadMenuConfig(menuPath);
+
+    // 1. Validate the overall menu structure
+    validateMenu(data);
 
-async function runCli(menuPath = null) {
-    const data = loadMenuConfig(menuPath);
     if (data.options) {
         buildIdMap(data.options);
     }
 
-    console.clear();
-
-    displayHeader(data);
+    validateRecursionDepth(flatMap);
 
-    await showMenu(data);
+    if (customActions && customActions.length > 0) {
+        await executeSequence(customActions, flatMap);
+    } else {
+        console.clear();
+        displayHeader(data);
+        await showMenu(data);
+    }
 }
 
 if (require.main === module) {
-    runCli();
+    (async () => {
+        await runCli();
+    })();
 }
 
 module.exports = { runCli };

package/menu.json

@@ -1,5 +1,7 @@
 {
+  "id": "0",
   "name": "custom-menu-cli",
+  "type": "navigation",
   "description": "JSON-based terminal menu",
   "options": [
     {

package/package.json

@@ -1,14 +1,22 @@
 {
   "name": "custom-menu-cli",
-  "version": "2.0.1",
+  "version": "4.0.0",
   "description": "Menu interativo baseado em JSON para execução de comandos no terminal",
   "main": "index.js",
   "bin": "index.js",
   "scripts": {
     "start": "node index.js",
+    "test": "jest",
     "build": "pkg . --targets node16-linux-x64,node16-win-x64,node16-macos-x64 --output dist/custom-menu-v$npm_package_version"
   },
-  "keywords": ["cli", "menu", "json", "terminal", "deploy", "custom"],
+  "keywords": [
+    "cli",
+    "menu",
+    "json",
+    "terminal",
+    "deploy",
+    "custom"
+  ],
   "author": "Mateus Medeiros <https://github.com/mateusmed>",
   "license": "MIT",
   "dependencies": {
@@ -17,6 +25,10 @@
     "inquirer": "^8.2.4"
   },
   "devDependencies": {
+    "jest": "^30.2.0",
     "pkg": "^5.8.1"
+  },
+  "jest": {
+    "testEnvironment": "node"
   }
 }

package/src/actionRunner.js

@@ -0,0 +1,92 @@
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const { terminal } = require('./terminal.js');
+
+async function confirmExecution(message) {
+    const { ok } = await inquirer.prompt([{ type: 'confirm', name: 'ok', message, default: false }]);
+    return ok;
+}
+
+/**
+ * Executes a single action or a sequence of actions from a custom-action.
+ * @param {object} action - The action object to execute.
+ * @param {object} flatMap - The map of all available actions.
+ * @param {boolean} [isConfirmationEnabled=true] - Whether to prompt for confirmation.
+ */
+async function executeAction(action, flatMap, isConfirmationEnabled = true) {
+    if (!action) {
+        console.error(chalk.red('Error: Attempted to execute a null or undefined action.'));
+        return;
+    }
+
+    let proceed = true;
+    if (isConfirmationEnabled && action.confirm) {
+        const message = action.type === 'action'
+            ? `Execute command: [id: ${action.id} name: ${action.name} ]?`
+            : `Execute custom action: [id: ${action.id} name: ${action.name} ]?`;
+        proceed = await confirmExecution(chalk.yellow(message));
+    }
+
+    if (!proceed) {
+        console.log(chalk.yellow(`Execution of action '${action.id}' cancelled.`));
+        return;
+    }
+
+    if (action.type === 'action' && action.command) {
+        console.log(chalk.blue(`Executing command: [id: ${action.id} name: ${action.name} ]`));
+        await terminal.execCommandSync(action.command);
+    } else if (action.type === 'custom-action' && action.idList) {
+        for (const nestedId of action.idList) {
+            const nestedAction = flatMap[nestedId];
+            if (nestedAction) {
+                // Pass `isConfirmationEnabled=false` to prevent repeated prompts for sub-actions.
+                // The parent confirmation is considered sufficient.
+                await executeAction(nestedAction, flatMap, false);
+            } else {
+                console.error(chalk.red(`Error: Nested action with id '${nestedId}' not found within custom-action '${action.id}'.`));
+            }
+        }
+    }
+}
+
+/**
+ * Handles a single action selected in interactive mode.
+ * @param {object} selected - The selected action object.
+ * @param {object} flatMap - The map of all available actions.
+ */
+async function handleAction(selected, flatMap) {
+    // For single actions selected in interactive mode, confirmation is enabled.
+    await executeAction(selected, flatMap, true);
+}
+
+/**
+ * Handles a custom action selected in interactive mode.
+ * @param {object} selected - The selected custom action object.
+ * @param {object} flatMap - The map of all available actions.
+ */
+async function handleCustomAction(selected, flatMap) {
+    // For custom actions selected in interactive mode, confirmation is enabled.
+    await executeAction(selected, flatMap, true);
+}
+
+/**
+ * Executes a sequence of actions triggered from the command line.
+ * @param {string[]} actionIds - An array of action IDs to execute.
+ * @param {object} flatMap - The map of all available actions.
+ */
+async function executeSequence(actionIds, flatMap) {
+    console.log(chalk.blue(`Executing sequence from command line: ${actionIds.join(', ')}`));
+
+    for (const id of actionIds) {
+        const action = flatMap[id];
+        if (action) {
+            // Call the unified executor with confirmations disabled
+            await executeAction(action, flatMap, false);
+        } else {
+            console.error(chalk.red(`Error: Action with id '${id}' not found.`));
+        }
+    }
+}
+
+
+module.exports = { handleAction, handleCustomAction, executeSequence };

package/src/args.js

@@ -0,0 +1,23 @@
+
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const result = {
+        menuPath: null,
+        customActions: [],
+    };
+
+    for (const arg of args) {
+        if (arg.startsWith('menu=')) {
+            result.menuPath = arg.substring('menu='.length);
+        } else if (arg.startsWith('custom-action=')) {
+            result.customActions = arg.substring('custom-action='.length).split(',');
+        } else if (!result.menuPath) {
+            // For backward compatibility, if no prefix is used, assume it's a menu path.
+            result.menuPath = arg;
+        }
+    }
+
+    return result;
+}
+
+module.exports = { parseArgs };

package/src/configLoader.js

@@ -1,4 +1,5 @@
-const fs = require('fs');
+const fs = require('fs').promises;
+const path = require('path');
 const chalk = require('chalk');
 
 const defaultMenu = {
@@ -15,41 +16,71 @@ const defaultMenu = {
     ]
 };
 
-function loadMenuConfig(menuPath = null) {
-    let data;
-    let finalPath = menuPath;
+async function buildMenuOptions(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const options = [];
 
-    // If menuPath is not provided, check command line arguments
-    if (!finalPath) {
-        const args = process.argv.slice(2);
-        finalPath = args[0];
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            const subOptions = await buildMenuOptions(fullPath);
+            options.push({
+                id: entry.name,
+                name: `=> ${entry.name.toUpperCase()}`,
+                type: 'navigation',
+                options: subOptions
+            });
+        } else if (entry.isFile() && entry.name.endsWith('.json')) {
+            const fileContent = await fs.readFile(fullPath, 'utf-8');
+            try {
+                const option = JSON.parse(fileContent);
+                options.push(option);
+            } catch (parseError) {
+                console.error(chalk.red(`Error: Malformed JSON file at: ${fullPath}`));
+                console.error(chalk.red(`Details: ${parseError.message}`));
+                process.exit(1);
+            }
+        }
     }
+    return options;
+}
 
-    if (finalPath && fs.existsSync(finalPath)) {
-        try {
-            data = JSON.parse(fs.readFileSync(finalPath, 'utf-8'));
-        } catch (error) {
-            console.log(chalk.red(`Error parsing JSON file: ${finalPath}`));
-            console.error(error);
-            process.exit(1);
-        }
-    } else if (finalPath) {
-        console.log(chalk.red(`File not found: ${finalPath}`));
-        process.exit(1);
-    } else if (fs.existsSync('./menu.json')) {
+async function loadMenuConfig(menuPath = null) {
+    if (menuPath) {
         try {
-            data = JSON.parse(fs.readFileSync('./menu.json', 'utf-8'));
+            const stats = await fs.stat(menuPath);
+            if (stats.isDirectory()) {
+                return {
+                    name: "Dynamic Menu",
+                    description: `Menu generated from folder: ${menuPath}`,
+                    options: await buildMenuOptions(menuPath)
+                };
+            }
+            return JSON.parse(await fs.readFile(menuPath, 'utf-8'));
         } catch (error) {
-            console.log(chalk.red(`Error parsing JSON file: ./menu.json`));
-            console.error(error);
+            if (error.code === 'ENOENT') {
+                console.error(chalk.red(`Error: The path '${menuPath}' was not found.`));
+            } else {
+                console.error(chalk.red(`Error processing path: ${menuPath}`));
+                console.error(error);
+            }
             process.exit(1);
         }
-    } else {
-        console.log(chalk.yellow("No 'menu.json' found. Loading example menu."));
-        data = defaultMenu;
     }
 
-    return data;
+    // Default to menu.json or example menu
+    const defaultMenuPath = './menu.json';
+    try {
+        const fileContent = await fs.readFile(defaultMenuPath, 'utf-8');
+        return JSON.parse(fileContent);
+    } catch (error) {
+        if (error.code === 'ENOENT') {
+            console.log(chalk.yellow("No 'menu.json' found. Loading example menu."));
+            return defaultMenu;
+        }
+        console.error(chalk.red(`Error loading default menu.json: ${error.message}`));
+        process.exit(1);
+    }
 }
 
 module.exports = { loadMenuConfig };

package/src/dependencyValidator.js

@@ -0,0 +1,41 @@
+const chalk = require('chalk');
+
+
+function validateRecursionDepth(flatMap, maxDepth = 3) {
+    const graph = new Map();
+    const allActions = Object.values(flatMap);
+
+    for (const action of allActions) {
+        if (action.type === 'custom-action' && action.idList) {
+            graph.set(action.id, action.idList);
+        }
+    }
+
+    function checkDepth(actionId, currentDepth, path) {
+        if (currentDepth > maxDepth) {
+            console.error(chalk.red(`Error: Maximum recursion depth of ${maxDepth} exceeded by action '${path[0]}'. Path: ${path.join(' -> ')} -> ${actionId}`));
+            process.exit(1);
+        }
+
+        if (path.includes(actionId)) {
+            // This is a circular dependency. If it reached here, it didn't exceed maxDepth on previous checks
+            // So, for now, we just acknowledge it and don't exit.
+            // If the *cycle itself* is considered a depth violation (e.g., a->b->a, depth 3 for second 'a'),
+            // the check above (currentDepth > maxDepth) should catch it if the cycle is long enough.
+            return;
+        }
+
+        path.push(actionId);
+
+        const dependencies = graph.get(actionId) || [];
+        for (const depId of dependencies) {
+            checkDepth(depId, currentDepth + 1, [...path]); // Pass a copy of the path
+        }
+    }
+
+    for (const actionId of graph.keys()) {
+        checkDepth(actionId, 1, []);
+    }
+}
+
+module.exports = { validateRecursionDepth };

package/src/menu.js

@@ -1,6 +1,6 @@
 const inquirer = require('inquirer');
 const chalk = require('chalk');
-const { handleAction, handleCustomAction, handleNavigation } = require('./actions.js');
+const { handleAction, handleCustomAction, executeSequence } = require('./actionRunner.js');
 
 const flatMap = {};
 

package/src/menuValidator.js

@@ -0,0 +1,51 @@
+const chalk = require('chalk');
+
+function _validateSingleOption(option) {
+    if (!option.id || typeof option.id !== 'string') {
+        console.error(chalk.red(`Validation Error: An option is missing a valid 'id'.`));
+        process.exit(1); return;
+    }
+    if (!option.name || typeof option.name !== 'string') {
+        console.error(chalk.red(`Validation Error in option '${option.id}': 'name' is missing or invalid.`));
+        process.exit(1); return;
+    }
+
+    const validTypes = ['action', 'navigation', 'custom-action'];
+    if (!option.type || !validTypes.includes(option.type)) {
+        console.error(chalk.red(`Validation Error in option '${option.id}': 'type' is missing or invalid.`));
+        process.exit(1); return;
+    }
+
+    if (option.type === 'action') {
+        if (!option.command || typeof option.command !== 'string') {
+            console.error(chalk.red(`Validation Error in option '${option.id}': 'command' is missing or invalid for type 'action'.`));
+            process.exit(1); return;
+        }
+    } else if (option.type === 'custom-action') {
+        if (!Array.isArray(option.idList) || option.idList.length === 0) {
+            console.error(chalk.red(`Validation Error in option '${option.id}': 'idList' is missing or empty for type 'custom-action'.`));
+            process.exit(1); return;
+        }
+    } else if (option.type === 'navigation') {
+        if (!Array.isArray(option.options) || option.options.length === 0) {
+            console.error(chalk.red(`Validation Error in option '${option.id}': 'options' is missing or empty for type 'navigation'.`));
+            process.exit(1); return;
+        }
+        // Recursively validate sub-options
+        option.options.forEach(_validateSingleOption);
+    }
+}
+
+function validateMenu(menuData) {
+    if (!menuData.name || typeof menuData.name !== 'string') {
+        console.error(chalk.red(`Validation Error: Top-level 'name' is missing or invalid in menu configuration.`));
+        process.exit(1); return;
+    }
+    if (!Array.isArray(menuData.options)) {
+        console.error(chalk.red(`Validation Error: Top-level 'options' array is missing or invalid.`));
+        process.exit(1); return;
+    }
+    menuData.options.forEach(_validateSingleOption);
+}
+
+module.exports = { validateMenu };

package/test_menu_circular/a.json

@@ -0,0 +1,6 @@
+{
+    "id": "a",
+    "name": "Action A",
+    "type": "custom-action",
+    "idList": ["b"]
+}

package/test_menu_circular/b.json

@@ -0,0 +1,6 @@
+{
+    "id": "b",
+    "name": "Action B",
+    "type": "custom-action",
+    "idList": ["c"]
+}

package/test_menu_circular/c.json

@@ -0,0 +1,6 @@
+{
+    "id": "c",
+    "name": "Action C",
+    "type": "custom-action",
+    "idList": ["a"]
+}

package/test_menu_example/1-project-a/1.1-down-service.json

@@ -0,0 +1,7 @@
+{
+  "id": "1.1",
+  "name": "Down Service",
+  "type": "action",
+  "command": "echo 'Down A'",
+  "confirm": true
+}

package/test_menu_example/1-project-a/1.2-up-service.json

@@ -0,0 +1,6 @@
+{
+  "id": "1.2",
+  "name": "Up Service",
+  "type": "action",
+  "command": "echo 'Up A'"
+}

package/test_menu_example/1-project-a/1.3-restart-project-a.json

@@ -0,0 +1,7 @@
+{
+  "id": "1.3",
+  "name": "Restart Project A (from inside)",
+  "type": "custom-action",
+  "idList": ["1.1", "1.2"],
+  "confirm": true
+}

package/test_menu_example/2-restart-all.json

@@ -0,0 +1,7 @@
+{
+  "id": "2",
+  "name": "Restart All",
+  "type": "custom-action",
+  "idList": ["1.1", "1.2"],
+  "confirm": true
+}

package/test_menu_example/3-restart-project-a-nested.json

@@ -0,0 +1,7 @@
+{
+  "id": "3",
+  "name": "Restart Project A (Nested)",
+  "type": "custom-action",
+  "idList": ["1.3"],
+  "confirm": true
+}

package/tests/args.test.js

@@ -0,0 +1,44 @@
+const { parseArgs } = require('../src/args');
+
+describe('args', () => {
+    const originalArgv = process.argv;
+
+    afterEach(() => {
+        process.argv = originalArgv;
+    });
+
+    test('should parse menu path and custom actions', () => {
+        process.argv = ['node', 'index.js', 'menu=my-menu.json', 'custom-action=1,2,3'];
+        const { menuPath, customActions } = parseArgs();
+        expect(menuPath).toBe('my-menu.json');
+        expect(customActions).toEqual(['1', '2', '3']);
+    });
+
+    test('should handle only menu path', () => {
+        process.argv = ['node', 'index.js', 'menu=my-menu.json'];
+        const { menuPath, customActions } = parseArgs();
+        expect(menuPath).toBe('my-menu.json');
+        expect(customActions).toEqual([]);
+    });
+
+    test('should handle only custom actions', () => {
+        process.argv = ['node', 'index.js', 'custom-action=a,b'];
+        const { menuPath, customActions } = parseArgs();
+        expect(menuPath).toBeNull();
+        expect(customActions).toEqual(['a', 'b']);
+    });
+
+    test('should handle backward compatibility for menu path', () => {
+        process.argv = ['node', 'index.js', 'my-menu.json'];
+        const { menuPath, customActions } = parseArgs();
+        expect(menuPath).toBe('my-menu.json');
+        expect(customActions).toEqual([]);
+    });
+
+    test('should return null and empty array when no args are provided', () => {
+        process.argv = ['node', 'index.js'];
+        const { menuPath, customActions } = parseArgs();
+        expect(menuPath).toBeNull();
+        expect(customActions).toEqual([]);
+    });
+});

package/tests/dependencyValidator.test.js

@@ -0,0 +1,93 @@
+const { validateRecursionDepth } = require('../src/dependencyValidator');
+
+describe('validateRecursionDepth', () => {
+    const mockExit = jest.spyOn(process, 'exit').mockImplementation(() => {});
+    const mockConsoleError = jest.spyOn(console, 'error').mockImplementation(() => {});
+
+    beforeEach(() => {
+        mockExit.mockClear();
+        mockConsoleError.mockClear();
+    });
+
+    test('should not exit for a valid dependency graph within default recursion depth', () => {
+        const flatMap = {
+            'a': { id: 'a', type: 'custom-action', idList: ['b'] },
+            'b': { id: 'b', type: 'custom-action', idList: ['c'] },
+            'c': { id: 'c', type: 'action', command: 'echo c' }
+        };
+        // Default maxDepth is 3. a -> b (depth 1), b -> c (depth 2), c (depth 3)
+        validateRecursionDepth(flatMap);
+        expect(mockExit).not.toHaveBeenCalled();
+    });
+
+    test('should exit when recursion depth is exceeded by default (depth > 3)', () => {
+        const flatMap = {
+            'a': { id: 'a', type: 'custom-action', idList: ['b'] },
+            'b': { id: 'b', type: 'custom-action', idList: ['c'] },
+            'c': { id: 'c', type: 'custom-action', idList: ['d'] },
+            'd': { id: 'd', type: 'action', command: 'echo d' }
+        };
+        // Default maxDepth is 3. a -> b (1) -> c (2) -> d (3)
+        // If d refers to another custom action, it would exceed depth.
+        // Let's create a chain that explicitly exceeds default maxDepth=3.
+        const deepFlatMap = {
+            'action0': { id: 'action0', type: 'custom-action', idList: ['action1'] },
+            'action1': { id: 'action1', type: 'custom-action', idList: ['action2'] },
+            'action2': { id: 'action2', type: 'custom-action', idList: ['action3'] },
+            'action3': { id: 'action3', type: 'custom-action', idList: ['action4'] },
+            'action4': { id: 'action4', type: 'action', command: 'echo hello' }
+        };
+        validateRecursionDepth(deepFlatMap);
+        expect(mockExit).toHaveBeenCalledWith(1);
+        expect(mockConsoleError).toHaveBeenCalledWith(expect.stringContaining('Maximum recursion depth of 3 exceeded by action \'action0\'. Path: action0 -> action1 -> action2 -> action3 -> action4'));
+    });
+
+    test('should not exit for a valid dependency graph within custom recursion depth', () => {
+        const flatMap = {
+            'a': { id: 'a', type: 'custom-action', idList: ['b'] },
+            'b': { id: 'b', type: 'custom-action', idList: ['c'] },
+            'c': { id: 'c', type: 'action', command: 'echo c' }
+        };
+        // Testing with maxDepth = 4, which should pass
+        validateRecursionDepth(flatMap, 4);
+        expect(mockExit).not.toHaveBeenCalled();
+    });
+
+    test('should exit when custom recursion depth is exceeded', () => {
+        const flatMap = {
+            'a': { id: 'a', type: 'custom-action', idList: ['b'] },
+            'b': { id: 'b', type: 'custom-action', idList: ['c'] },
+            'c': { id: 'c', type: 'action', command: 'echo c' }
+        };
+        // Testing with maxDepth = 2, which should fail at 'b'
+        validateRecursionDepth(flatMap, 2);
+        expect(mockExit).toHaveBeenCalledWith(1);
+        expect(mockConsoleError).toHaveBeenCalledWith(expect.stringContaining('Maximum recursion depth of 2 exceeded by action \'a\'. Path: a -> b -> c'));
+    });
+
+    test('should handle circular dependencies that are within maxDepth without exiting', () => {
+        const flatMap = {
+            'a': { id: 'a', type: 'custom-action', idList: ['b'] },
+            'b': { id: 'b', type: 'custom-action', idList: ['a'] }
+        };
+        // A circular dependency, but if default maxDepth is 3, it should not exit based *solely* on depth
+        // The current implementation of validateRecursionDepth detects depth exceeding, not general cycles.
+        // In this case, `checkDepth` for 'a' with 'b' at depth 1, then 'b' with 'a' at depth 2,
+        // will not exceed the default maxDepth of 3.
+        validateRecursionDepth(flatMap, 3); // maxDepth 3
+        expect(mockExit).not.toHaveBeenCalled();
+    });
+
+    test('should exit for a circular dependency that exceeds maxDepth', () => {
+        const flatMap = {
+            'a': { id: 'a', type: 'custom-action', idList: ['b'] },
+            'b': { id: 'b', type: 'custom-action', idList: ['c'] },
+            'c': { id: 'c', type: 'custom-action', idList: ['a'] }
+        };
+        // With maxDepth = 2, 'a' -> 'b' (depth 1), 'b' -> 'c' (depth 2). When 'c' tries to go to 'a',
+        // the path 'a' -> 'b' -> 'c' -> 'a' would be depth 3 for the second 'a'.
+        validateRecursionDepth(flatMap, 2);
+        expect(mockExit).toHaveBeenCalledWith(1);
+        expect(mockConsoleError).toHaveBeenCalledWith(expect.stringContaining('Maximum recursion depth of 2 exceeded by action \'a\'. Path: a -> b -> c -> a'));
+    });
+});

package/tests/menu.test.js

@@ -0,0 +1,43 @@
+// Important: We need to reset the flatMap between tests.
+// Jest can't easily reset modules, so we'll handle it manually.
+let menu = require('../src/menu');
+
+describe('menu', () => {
+
+    beforeEach(() => {
+        // Reset the flatMap object before each test
+        for (const key in menu.flatMap) {
+            delete menu.flatMap[key];
+        }
+    });
+    
+    test('buildIdMap should correctly flatten a simple menu', () => {
+        const options = [
+            { id: '1', name: 'Action 1' },
+            { id: '2', name: 'Action 2' },
+        ];
+        menu.buildIdMap(options);
+        expect(menu.flatMap).toEqual({
+            '1': { id: '1', name: 'Action 1' },
+            '2': { id: '2', name: 'Action 2' },
+        });
+    });
+
+    test('buildIdMap should correctly flatten a nested menu', () => {
+        const options = [
+            { id: '1', name: 'Nav 1', options: [
+                { id: '1.1', name: 'Action 1.1' },
+            ]},
+            { id: '2', name: 'Action 2' },
+        ];
+        menu.buildIdMap(options);
+        expect(Object.keys(menu.flatMap).length).toBe(3);
+        expect(menu.flatMap['1.1']).toEqual({ id: '1.1', name: 'Action 1.1' });
+    });
+
+    test('buildIdMap should handle an empty options array', () => {
+        const options = [];
+        menu.buildIdMap(options);
+        expect(menu.flatMap).toEqual({});
+    });
+});

package/tests/menuValidator.test.js

@@ -0,0 +1,74 @@
+const { validateMenu } = require('../src/menuValidator');
+
+describe('menuValidator', () => {
+    const mockExit = jest.spyOn(process, 'exit').mockImplementation(() => {});
+    const mockConsoleError = jest.spyOn(console, 'error').mockImplementation(() => {});
+
+    beforeEach(() => {
+        mockExit.mockClear();
+        mockConsoleError.mockClear();
+    });
+
+    const validMenu = {
+        name: 'Valid Menu',
+        options: [
+            { id: '1', name: 'Action 1', type: 'action', command: 'echo 1' },
+            { id: '2', name: 'Nav 1', type: 'navigation', options: [
+                { id: '2.1', name: 'Action 2.1', type: 'action', command: 'echo 2.1' }
+            ]},
+            { id: '3', name: 'Custom 1', type: 'custom-action', idList: ['1'] }
+        ]
+    };
+
+    test('should not throw error for a valid menu', () => {
+        validateMenu(validMenu);
+        expect(mockExit).not.toHaveBeenCalled();
+    });
+
+    test('should exit if top-level name is missing', () => {
+        const invalidMenu = { ...validMenu, name: undefined };
+        validateMenu(invalidMenu);
+        expect(mockExit).toHaveBeenCalledWith(1);
+    });
+
+    test('should exit if top-level options is not an array', () => {
+        const invalidMenu = { ...validMenu, options: 'not-an-array' };
+        validateMenu(invalidMenu);
+        expect(mockExit).toHaveBeenCalledWith(1);
+    });
+
+    test('should exit if an option is missing an id', () => {
+        const invalidMenu = JSON.parse(JSON.stringify(validMenu)); // Deep copy
+        invalidMenu.options[0].id = undefined;
+        validateMenu(invalidMenu);
+        expect(mockExit).toHaveBeenCalledWith(1);
+    });
+
+    test('should exit if an option is missing a name', () => {
+        const invalidMenu = JSON.parse(JSON.stringify(validMenu));
+        invalidMenu.options[0].name = undefined;
+        validateMenu(invalidMenu);
+        expect(mockExit).toHaveBeenCalledWith(1);
+    });
+
+    test('should exit if an action is missing a command', () => {
+        const invalidMenu = JSON.parse(JSON.stringify(validMenu));
+        invalidMenu.options[0].command = undefined;
+        validateMenu(invalidMenu);
+        expect(mockExit).toHaveBeenCalledWith(1);
+    });
+
+    test('should exit if a custom-action is missing an idList', () => {
+        const invalidMenu = JSON.parse(JSON.stringify(validMenu));
+        invalidMenu.options[2].idList = undefined;
+        validateMenu(invalidMenu);
+        expect(mockExit).toHaveBeenCalledWith(1);
+    });
+
+    test('should exit if a navigation is missing options', () => {
+        const invalidMenu = JSON.parse(JSON.stringify(validMenu));
+        invalidMenu.options[1].options = undefined;
+        validateMenu(invalidMenu);
+        expect(mockExit).toHaveBeenCalledWith(1);
+    });
+});

package/src/actions.js

@@ -1,45 +0,0 @@
-const inquirer = require('inquirer');
-const chalk = require('chalk');
-const {terminal} = require('./terminal.js');
-
-async function confirmExecution(message) {
-    const {ok} = await inquirer.prompt({type: 'confirm', name: 'ok', message, default: false});
-    return ok;
-}
-
-async function handleAction(selected) {
-    const proceed = selected.confirm ? await confirmExecution(chalk.yellow(`Executing command: [id: ${selected.id} name: ${selected.name} ]`)) : true;
-    if (proceed) {
-        await terminal.execCommandSync(selected.command);
-    }
-}
-
-async function handleCustomAction(selected, flatMap, depth = 0) {
-    if (depth >= 3) {
-        console.log(chalk.red(`Maximum recursion depth (3) exceeded for custom action: ${selected.id}`));
-        return;
-    }
-    const proceed = selected.confirm ? await confirmExecution(chalk.yellow(`Execute command list ${selected.idList.join(', ')}?`)) : true;
-    if (proceed) {
-        for (const id of selected.idList) {
-            const cmd = flatMap[id];
-            if (cmd) {
-                if (cmd.type === 'action' && cmd.command) {
-                    console.log(chalk.blue(`Executing command: [id: ${cmd.id} name: ${cmd.name} ]`));
-                    await terminal.execCommandSync(cmd.command);
-                } else if (cmd.type === 'custom-action') {
-                    console.log(chalk.blue(`Executing custom action: [id: ${cmd.id} name: ${cmd.name} ]`));
-                    await handleCustomAction(cmd, flatMap, depth + 1);
-                } else {
-                    console.log(chalk.red(`Unknown or unexecutable type for id: ${cmd.id}`));
-                }
-            }
-        }
-    }
-}
-
-async function handleNavigation(selected) {
-    return selected;
-}
-
-module.exports = { handleAction, handleCustomAction, handleNavigation };