@fixweb/utils-cli

Framework CLI déclaratif avec support YAML et TUI interactif.

Installation

``bash
npm install @fixweb/utils-cli
`

Utilisation rapide

`javascript
// index.js
require("@fixweb/utils-cli").run("./menu.yml");
`

`yaml


menu.yml

title: Mon CLI

menu:
- "Commandes"
- hello: ["echo", "Hello World"]
- greet:
desc: "Dit bonjour"
exec: ["echo", "Bonjour!"]
`

---

Structure YAML

$3

`yaml
title: Mon CLI # Titre affiché (figlet banner)
version: 1.0.0 # Version (optionnel)

vars: # Variables globales
APP_DIR: /opt/myapp
LOG_DIR: /var/log

menu: # Menu principal
- ...
`

---

Éléments du menu

$3

`yaml
menu:
- "Ma Section" # String = label
`

$3

`yaml


Ultra court

- hello: ["echo", "Hello!"]

Avec description

- hello:
desc: "Dit bonjour"
exec: ["echo", "Hello!"]
`

$3

`yaml
- check:
desc: "Vérifie quelque chose"
inline: true
exec: ["sleep", "1"]
`

$3

`yaml
- build:
desc: "Build le projet"
async: true
exec: ["npm", "run", "build"]
`

Le mode async: true exécute la commande en arrière-plan avec un spinner animé.
Contrairement au mode par défaut (sync) qui prend le contrôle du terminal,
le mode async capture la sortie et affiche un résumé à la fin.

| Mode | Comportement |
|------|--------------|
| async: false (défaut) | Prend le contrôle du terminal (stdin/stdout hérités) |
| async: true | Spinner animé, sortie capturée, résumé affiché |
| inline: true | Comme async mais reste dans le TUI |

$3

`yaml
- Outils:
desc: "Outils divers"
items:
- tool1: ["echo", "Tool 1"]
- tool2:
desc: "Second outil"
exec: ["echo", "Tool 2"]
- SousMenu:
desc: "Plus d'outils"
items:
- subtool: ["echo", "Subtool"]
`

$3

`yaml


Dans le menu principal

- "@modules": "Mes Modules"

Dans un fichier inclus

hook: modules
menu:
- mycommand: ["echo", "from module"]
`

---

Variables

$3

`yaml
vars:
PROJECT_DIR: /opt/myproject
LOG_FILE: /var/log/app.log
ENV: production
`

$3

`yaml
- logs: ["tail", "-f", "{{LOG_FILE}}"]
`

Variables système disponibles :
- {{CLI_DIR}} - Dossier du CLI
- {{MODULES_DIR}} - Dossier des modules
- {{CONFIG_DIR}} - Dossier de config
- {{MODULE_DIR}} - Dossier du module courant

---

Prompts interactifs

$3

`yaml
- deploy:
desc: "Déployer l'application"
prompts:
# Selection (liste)
- id: env
type: select
message: "Environnement ?"
choices: [dev, staging, prod]

# Input texte
- id: version
type: input
message: "Version ?"
defaultValue: "1.0.0"

# Confirmation (oui/non)
- id: confirm
type: confirm
message: "Continuer ?"

# Mot de passe (masqué)
- id: password
type: password
message: "Mot de passe ?"

exec: ["./deploy.sh", "{{env}}", "{{version}}"]
`

---

Actions multiples (steps)

$3

`yaml
- build:
desc: "Build all"
steps:
- name: "Build frontend"
exec: ["npm", "run", "build:front"]
- name: "Build backend"
exec: ["npm", "run", "build:back"]
- name: "Build assets"
exec: ["npm", "run", "build:assets"]
`

$3

`yaml
- deploy:
desc: "Deploy app"
mode: sequential
steps:
- name: "1. Tests"
exec: ["npm", "test"]
- name: "2. Build"
exec: ["npm", "run", "build"]
- name: "3. Deploy"
exec: ["./deploy.sh"]
`

---

Includes

$3

`yaml
menu:
- include: ./other-menu.yml
`

$3

`yaml
menu:
# Charge tous les YAML d'un dossier
- include: menus/*.yml

# Charge les commandes de modules
- include: modules/*/commands.yml
`

Le fichier inclus doit avoir une clé menu: :

`yaml


menus/database.yml


menu:
- "Database"
- db-status: ["echo", "DB OK"]
- db-backup:
desc: "Backup database"
exec: ["./backup.sh"]
`

---

Navigation TUI

| Touche | Action |
|--------|--------|
| ↑ ↓ | Naviguer dans le menu |
| → Enter | Entrer dans un sous-menu / Exécuter |
| ← Backspace | Retour au menu parent |
| Ctrl+C q | Quitter |

$3

- ○ Action/commande
- ● Sous-menu
- ▶ Élément sélectionné

---

API JavaScript

$3

`javascript
require("@fixweb/utils-cli").run("./menu.yml");
`

$3

`javascript
const { createCLI } = require("@fixweb/utils-cli");

const cli = createCLI({
name: "mycli",
version: "1.0.0",
title: "My CLI",
menu: [
{ label: "Commands" },
{
command: {
name: "hello",
description: "Say hello",
action: { type: "exec", argv: ["echo", "Hello"] }
}
}
],
vars: {
APP_DIR: "/opt/app"
},
paths: {
cliDir: __dirname,
modulesDir: "./modules"
}
});

cli.run();
`

---

Modules

Structure recommandée :

`
my-cli/
├── index.js
├── menu.yml
├── modules/
│ ├── database/
│ │ ├── commands.yml
│ │ └── scripts/
│ │ └── backup.sh
│ └── docker/
│ ├── commands.yml
│ └── scripts/
│ └── restart.sh
└── menus/
├── admin.yml
└── dev.yml
`

`yaml


menu.yml

modules: ./modules

menu:
- include: modules/*/commands.yml
- include: menus/*.yml
`

---

Types d'actions

| Type | Description |
|------|-------------|
| exec | Exécuter une commande |
| steps | Actions multiples (parallel/sequential) |
| builtin | Actions JS internes (avancé) |

Sécurité

- Les commandes sont exécutées via spawn` (pas de shell)
- Les arguments sont sanitisés (pas d'injection)
- Variables d'environnement filtrées

---

Licence

MIT