@powernukkitx/cli 0.0.3 → 1.0.0

package/README.md

@@ -1,177 +1,203 @@
-# pnx-cli
-
-PowerNukkitX CLI est un outil en ligne de commande pour gérer un serveur **Minecraft Bedrock** propulsé par **PowerNukkitX**.
-
-Il propose un menu interactif, la gestion des plugins, des outils de diagnostic, des sauvegardes, et des commandes rapides pour initialiser ou démarrer un serveur.
-
-## Installation
-
-```bash
-npm install -g pnx-cli
-```
-
-Après installation, la commande disponible est `pnx`.
-
-## Prérequis
-
-- [Node.js](https://nodejs.org/) **18 ou plus**
-- Un dossier de serveur PowerNukkitX si vous souhaitez gérer une installation existante
-
-## Démarrage rapide
-
-Lancer le menu interactif :
-
-```bash
-pnx
-```
-
-Afficher l’aide :
-
-```bash
-pnx --help
-```
-
-Choisir la langue :
-
-```bash
-pnx --lang fr
-```
-
-## Fonctionnalités
-
-- Initialiser un nouveau serveur PowerNukkitX
-- Démarrer le serveur avec options de mémoire et redémarrage automatique
-- Installer, lister, rechercher, mettre à jour et supprimer des plugins
-- Vérifier l’état du serveur avec un diagnostic intégré
-- Créer des sauvegardes du serveur
-- Consulter la configuration et les informations du serveur
-- Mettre à jour `powernukkitx.jar`
-- Utiliser l’interface en anglais ou en français
-
-## Commandes disponibles
-
-### Initialiser un serveur
-
-```bash
-pnx init --dir ./pnx-server
-```
-
-Options :
-
-- `-d, --dir <path>` : dossier cible
-- `--dev` : installer la version de développement
-
-### Démarrer le serveur
-
-```bash
-pnx start --memory 4G --restart
-```
-
-Options :
-
-- `-g, --generate-only` : générer la commande de démarrage sans l’exécuter
-- `-r, --restart` : redémarrer automatiquement en cas de crash
-- `-m, --memory <size>` : mémoire allouée, par exemple `2G` ou `4G`
-- `-i, --interactive` : mode interactif avec prompts
-
-### Gérer les plugins
-
-```bash
-pnx plugin list
-pnx plugin search essentials
-pnx plugin info <slug>
-pnx plugin install <name>
-pnx plugin update
-pnx plugin remove <name>
-pnx plugin installed
-```
-
-Sous-commandes :
-
-- `install [names...]` : installer un plugin depuis le marketplace ou une URL `.jar`
-- `list` : afficher les plugins disponibles
-- `search [term]` : rechercher par nom, description ou auteur
-- `info [slug]` : afficher la fiche détaillée d’un plugin
-- `installed` : lister les plugins installés localement
-- `update [names...]` : mettre à jour les plugins installés
-- `remove [names...]` : supprimer des plugins installés
-
-### Mettre à jour le serveur
-
-```bash
-pnx update --force
-```
-
-Options :
-
-- `--dev` : installer la version de développement
-- `-f, --force` : forcer la mise à jour même si la version correspond
-
-### Diagnostics et utilitaires
-
-```bash
-pnx doctor
-pnx backup
-pnx config
-pnx info
-pnx lang --set fr
-```
-
-## Mode interactif
-
-Si vous lancez `pnx` sans sous-commande, l’application ouvre un menu interactif pour :
-
-- créer ou initialiser un serveur
-- démarrer le serveur
-- gérer les plugins
-- mettre à jour PowerNukkitX
-- lancer un diagnostic
-- effectuer une sauvegarde
-- changer la langue
-
-## Développement
-
-Installer les dépendances :
-
-```bash
-npm install
-```
-
-Compiler le projet :
-
-```bash
-npm run build
-```
-
-Lancer la CLI localement :
-
-```bash
-npm start
-```
-
-Surveiller les changements TypeScript :
-
-```bash
-npm run dev
-```
-
-## Exécutables autonomes
-
-Le projet fournit aussi des scripts pour générer des exécutables Windows, Linux et macOS :
-
-```bash
-npm run build:exe:win
-npm run build:exe:linux
-npm run build:exe:mac
-```
-
-## Liens utiles
-
-- Documentation PowerNukkitX : https://docs.powernukkitx.org
-- Dépôt PowerNukkitX : https://github.com/PowerNukkitX/PowerNukkitX
-
-## Licence
-
-MIT
-
-
+# pnx-cli
+
+**PowerNukkitX CLI** — outil en ligne de commande pour gérer un serveur **Minecraft Bedrock** propulsé par [PowerNukkitX](https://github.com/PowerNukkitX/PowerNukkitX).
+
+Créez, démarrez, mettez à jour et diagnostiquez votre serveur, gérez les plugins depuis la marketplace, le tout avec une interface soignée et un menu interactif — en français ou en anglais.
+
+## Sommaire
+
+- [Installation](#installation)
+- [Prérequis](#prérequis)
+- [Démarrage rapide](#démarrage-rapide)
+- [Commandes](#commandes)
+- [Mode interactif](#mode-interactif)
+- [Options globales](#options-globales)
+- [Architecture](#architecture)
+- [Développement](#développement)
+- [Exécutables autonomes](#exécutables-autonomes-sea)
+- [Liens](#liens-utiles)
+- [Licence](#licence)
+
+## Installation
+
+```bash
+npm install -g @powernukkitx/cli
+```
+
+La commande `pnx` devient alors disponible.
+
+Alternativement, téléchargez un exécutable autonome (voir [Exécutables autonomes](#exécutables-autonomes-sea)) — aucun Node.js requis pour l'utiliser.
+
+## Prérequis
+
+- **Node.js 20.12+** (pour l'installation via npm ; inutile pour les binaires autonomes)
+- **Java 21+** pour lancer le serveur ([Adoptium Temurin](https://adoptium.net/) recommandé)
+
+## Démarrage rapide
+
+```bash
+# Menu interactif contextuel
+pnx
+
+# Créer un serveur puis le démarrer
+pnx init --dir ./pnx-server
+pnx start --memory 4G
+
+# Aide
+pnx --help
+pnx <commande> --help
+```
+
+## Commandes
+
+### `init` — créer un serveur
+
+Télécharge le dernier `powernukkitx.jar` et les scripts de démarrage.
+
+```bash
+pnx init --dir ./pnx-server
+```
+
+| Option | Description |
+|---|---|
+| `--dir <path>` | Dossier cible (sinon demandé) |
+| `--dev` | Version de développement |
+
+### `start` — démarrer le serveur
+
+Vérifie Java, construit les arguments JVM optimisés (ZGC générationnel, UTF-8) et lance le serveur.
+
+```bash
+pnx start --memory 4G --restart
+```
+
+| Option | Description |
+|---|---|
+| `--dir <path>` | Dossier du serveur |
+| `--memory <taille>` | Mémoire allouée, ex. `2G`, `4G` (défaut `2G`) |
+| `--restart` | Redémarrage automatique en cas de crash |
+| `--dry-run` | Affiche la commande sans l'exécuter |
+
+### `stop` — arrêter le serveur
+
+Arrête le serveur démarré via son PID mémorisé.
+
+```bash
+pnx stop
+```
+
+### `update` — mettre à jour le core
+
+Sauvegarde l'ancien jar en `.old` puis télécharge la dernière version.
+
+```bash
+pnx update --force
+```
+
+| Option | Description |
+|---|---|
+| `--force` | Force le re-téléchargement (ignore le cache) |
+| `--dev` | Version de développement |
+
+### `plugin` — gérer les plugins
+
+Marketplace officielle + suivi local des versions installées.
+
+```bash
+pnx plugin list                    # catalogue
+pnx plugin search essentials       # recherche
+pnx plugin info <slug>             # fiche détaillée
+pnx plugin install <slug|url.jar>  # installer (marketplace ou URL .jar)
+pnx plugin installed               # plugins locaux
+pnx plugin update [slug]           # mettre à jour
+pnx plugin remove [nom]            # supprimer
+```
+
+Sans argument, `install`, `update` et `remove` proposent une sélection interactive.
+
+### Diagnostics & utilitaires
+
+```bash
+pnx doctor          # Java, RAM, disque, port 19132, plugins/mondes
+pnx info            # état, chemin, plugins, mondes, RAM
+pnx backup          # sauvegarde horodatée du serveur
+pnx config          # affiche pnx.yml / server.properties (coloré)
+pnx use ./serveur   # définit le serveur par défaut
+pnx logs            # derniers logs (avec suivi live)
+pnx console         # console RCON attachée au serveur
+pnx lang --set fr   # langue (fr / en)
+```
+
+`doctor` et `info` acceptent `--json` pour une sortie machine.
+
+## Mode interactif
+
+Lancée sans sous-commande, `pnx` ouvre un **menu contextuel** qui :
+
+- détecte l'état (serveur présent, démarré, PID) ;
+- ne propose que les actions pertinentes (créer si absent, démarrer si arrêté, arrêter si en cours…) ;
+- route vers les commandes existantes.
+
+```bash
+pnx
+```
+
+## Options globales
+
+| Option | Description |
+|---|---|
+| `--json` | Sortie JSON machine (désactive le rendu décoratif) |
+| `--lang <fr\|en>` | Force la langue pour cette exécution |
+| `--no-color` | Désactive les couleurs |
+
+Résolution de la langue : `--lang` > configuration sauvegardée > variable d'environnement > **français** par défaut.
+
+L'état du CLI est stocké dans `~/.pnx-cli/` (config, PID, plugins installés, cache des versions). Variables d'environnement : `PNX_API_URL` (base de l'API marketplace), `PNX_HOME` (répertoire d'état).
+
+## Architecture
+
+Le code suit une architecture en couches — commandes minces, logique métier isolée et testable :
+
+```
+src/
+  cli.ts          point d'entrée (citty) + options globales
+  commands/       parse des arguments → appel service → rendu
+    plugin/       sous-commandes plugin
+  services/       logique métier pure (release, server, process, plugins, backup)
+  infra/          http, store JSON (~/.pnx-cli), constantes/endpoints
+  ui/             système d'affichage unique (clack + chalk), prompts
+  i18n/           traductions fr / en
+```
+
+Règles : les commandes ne font aucun accès réseau/fichier direct (tout passe par `services`/`infra`) ; les services ne rendent rien (ils renvoient des données).
+
+**Stack** : TypeScript, [citty](https://github.com/unjs/citty) (routing), [@clack/prompts](https://github.com/bombshell-dev/clack) (prompts), [chalk](https://github.com/chalk/chalk) (couleurs).
+
+## Développement
+
+```bash
+npm install       # dépendances
+npm run build     # compile TypeScript → dist/ (+ copie des assets i18n)
+npm run dev       # compilation en watch
+npm start         # lance dist/cli.js
+npm test          # tests des services (node:test + tsx)
+```
+
+## Exécutables autonomes (SEA)
+
+Le projet génère un binaire natif via **[Node Single Executable Applications](https://nodejs.org/api/single-executable-applications.html)** (bundling esbuild + injection `postject`) :
+
+```bash
+npm run build:sea
+```
+
+Produit `pnx` (ou `pnx.exe` sous Windows) pour **la plateforme hôte**. SEA ne cross-compile pas : lancez la commande sur chaque système cible (Windows / Linux / macOS) pour obtenir son binaire.
+
+## Liens utiles
+
+- Documentation PowerNukkitX : https://docs.powernukkitx.org
+- Dépôt PowerNukkitX : https://github.com/PowerNukkitX/PowerNukkitX
+
+## Licence
+
+MIT