docs: expand netupgrade usage and configuration docs

Update the README with installation, requirements, supported actions, config format, and usage details. Align the CLI help text with current behavior and add startup checks for required runtime dependencies.

README.md

@@ -1,32 +1,105 @@
 # netupgrade
 
-Servers full upgrade script
+Interactive CLI tool to run upgrade and maintenance actions on multiple remote hosts over SSH.
 
 ## Where to use
 
-- On a dedicated server (bastion, ...)
+- On a dedicated server (bastion, jump host, ...)
 - On your computer with an alias to your dedicated server
-- On your computer (not recommended)
+- On your computer directly (not recommended)
+
+## Features
+
+- Select one or more hosts from an interactive checklist
+- Run predefined actions on each selected host
+- Write execution logs to `~/netupgrade.log`
+
+Supported actions:
+
+- `apt`
+- `yum`
+- `pkg`
+- `pacman`
+- `apk`
+- `reboot`
+- `cmd:<remote command>`
+- `docker-stacks:<directory>`
+
+## Requirements
+
+- `bash`
+- `ssh`
+- `whiptail`
+- `nano`
+- `sed`
+- `tee`
 
 ## Install
 
-### Bin as root
+### Install the executable
 
-``` bash
+```bash README.md
-cp bin/netupgrade to /usr/local/bin
+cp bin/netupgrade /usr/local/bin/netupgrade
+chmod +x /usr/local/bin/netupgrade
 ```
 
-### Config as user
+### Create the config directory
 
-``` bash
+```bash README.md
-mkdir -p ~/.config/netuprade
+mkdir -p ~/.config/netupgrade
-touch ~/.config/netuprade/index.cfg
+touch ~/.config/netupgrade/index.cfg
 ```
 
 ### Alias on your computer with a dedicated server
 
-You can save it in your .bashrc
+You can save it in your `.bashrc`
 
-``` bash
+```bash README.md
 alias netupgrade='ssh -t user@10.0.0.10 netupgrade'
 ```
+
+## Configuration
+
+The default config file is:
+
+```text README.md
+~/.config/netupgrade/index.cfg
+```
+
+The script sources this file as Bash code. It must define a `NODES` array.
+
+Each entry uses this format:
+
+```text README.md
+host;display-name;action1;action2;...
+```
+
+Example:
+
+```bash README.md
+NODES=(
+  "192.168.1.10;web-01;apt;reboot"
+  "192.168.1.11;db-01;apt;cmd:systemctl restart postgresql"
+  "192.168.1.12;docker-01;docker-stacks:/opt/stacks"
+)
+```
+
+## Usage
+
+```bash README.md
+netupgrade [--help] [-f] [-y] [configfilename]
+```
+
+Options:
+
+- `--help`: show help
+- `-f`: preselect all nodes
+- `-y`: pass non-interactive confirmation flags to supported package managers
+- `configfilename`: path to a config file
+
+## Notes
+
+- SSH connections currently use `root@host`
+- The tool is interactive and intended for manual administration workflows
+- After execution, the log file is opened in `nano`
+- The configuration file is sourced as shell code, so only use trusted config files

bin/netupgrade

@@ -1,12 +1,20 @@
 #!/bin/bash
 
 showHelp() {
-	echo "netupgrade [-f] [-y] [configfilename]"
+	echo "netupgrade [--help] [-f] [-y] [configfilename]"
 	echo ""
-	echo "              -f : Select all nodes"
+	echo "  --help         Show this help message"
-	echo "              -y : No confirmation"
+	echo "  -f             Select all nodes"
-	echo "              -b : Breack on error"
+	echo "  -y             No confirmation for supported package managers"
-	echo "  configfilename : a cfg filename"
+	echo "  configfilename Path to a cfg file"
+}
+
+checkDependencies() {
+	command -v ssh >/dev/null 2>&1 || { echo "Error: ssh is required"; exit 1; }
+	command -v whiptail >/dev/null 2>&1 || { echo "Error: whiptail is required"; exit 1; }
+	command -v nano >/dev/null 2>&1 || { echo "Error: nano is required"; exit 1; }
+	command -v sed >/dev/null 2>&1 || { echo "Error: sed is required"; exit 1; }
+	command -v tee >/dev/null 2>&1 || { echo "Error: tee is required"; exit 1; }
 }
 
 pressAnyKey(){
@@ -238,6 +246,7 @@ while [[ ${#} -gt 0 ]]; do
 	esac
 done
 
+checkDependencies
 loadConfig
 selectNodes
 

state.md

@@ -51,10 +51,10 @@ Supported action types currently include:
 ## Main issues identified
 
 ### 1. Documentation accuracy problems
-- `README.md` contains a typo in the configuration path (`netuprade` instead of `netupgrade`)
+- `README.md` and CLI help were updated to better match current behavior
-- The CLI help mentions `-b` but that option is not implemented
+- The previous typo in the configuration path (`netuprade`) has been fixed
-- `--help` exists in code but is not documented in the displayed usage
+- The unsupported `-b` option was removed from the displayed help
-- The configuration format is not documented in enough detail
+- The configuration format and supported actions are now documented in more detail
 
 ### 2. Shell robustness concerns
 - Node parsing relies on replacing `;` with spaces and re-splitting:
@@ -71,8 +71,7 @@ Supported action types currently include:
 - The `docker-stacks` remote loop should be reviewed carefully for quoting and path safety
 
 ### 4. UX and dependency issues
-- `whiptail` is required for selection but is not checked before use
+- Required runtime dependencies are now checked at startup (`ssh`, `whiptail`, `nano`, `sed`, `tee`)
-- `nano` is required for log viewing but is not checked before use
 - The workflow is highly interactive and not well suited for automation
 - `rm -i` introduces an extra prompt even when the rest of the flow is meant to be streamlined
 
@@ -91,10 +90,10 @@ Supported action types currently include:
 ## Recommended direction
 
 ### Short term
-- Fix documentation and help output to match actual behavior
 - Correct the remote command bugs, especially for `pacman`
-- Add dependency checks for required external tools
+- Improve parsing of node entries to avoid whitespace-splitting issues
-- Either implement or remove unsupported CLI options such as `-b`
+- Review `docker-stacks` remote command quoting and behavior
+- Consider making SSH user, log path, and editor configurable
 
 ### Medium term
 - Improve parsing of node entries to avoid whitespace-splitting issues
@@ -108,6 +107,12 @@ Supported action types currently include:
 - Consider a safer declarative configuration format if the project grows
 - Add test coverage for parsing and command construction
 
+## Recent changes
+- `README.md` was expanded to document installation, requirements, usage, configuration format, and supported actions
+- `bin/netupgrade` help output was aligned with actual CLI behavior and now documents `--help`
+- A startup dependency check was added before loading configuration or opening the interactive selector
+- The unsupported `-b` option remains unimplemented and is no longer shown in help output
+
 ## Change guidance
 - Preserve backward compatibility for existing config files where possible
 - Prefer incremental hardening over a full rewrite