netupgrade/state.md

# Repository analysis

## Project overview
- Project name: `netupgrade`
- Primary language: Bash
- Main entrypoint: `bin/netupgrade`
- Project type: interactive CLI administration tool
- Main purpose: orchestrate remote upgrade and maintenance actions on multiple hosts over SSH
- Configuration model: Bash-based configuration files sourced from `~/.config/netupgrade/*.cfg`

## Repository structure
- `bin/netupgrade`: main executable script containing CLI parsing, node selection, remote execution, and logging
- `config/netupgrade/*.cfg`: sample configuration files defining host groups and action sequences
- `README.md`: installation and usage documentation
- `docs/`: project documentation

## Functional behavior
The tool:
1. Loads a Bash configuration file
2. Expects a `NODES` array populated with entries formatted like:
   `host;display-name;action1;action2;...`
3. Displays an interactive multi-select checklist using `whiptail`
4. Executes the selected actions on each selected host through `ssh root@host`
5. Writes execution logs to `~/netupgrade.log`
6. Opens the log in `nano`, then optionally removes it

Supported action types currently include:
- `apt`
- `yum`
- `pkg`
- `pacman`
- `apk`
- `reboot`
- `cmd:<remote command>`
- `docker-stacks:<directory>`

## Architecture notes
- The project is intentionally lightweight and script-based
- Configuration is code-driven rather than declarative, since config files are sourced as shell files
- The entire execution flow currently lives in a single Bash script
- Remote operations are performed sequentially, not in parallel
- Logging is file-based and coupled directly to command execution

## Strengths
- Very small and easy to deploy
- Clear practical purpose for system administration workflows
- Flexible host/action configuration model
- Supports several Linux/BSD package managers
- Suitable for use from a bastion host or admin workstation

## Main issues identified

### 1. Documentation accuracy problems
- `README.md` and CLI help were updated to better match current behavior
- The previous typo in the configuration path (`netuprade`) has been fixed
- The unsupported `-b` option was removed from the displayed help
- 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:
  this is fragile if values contain spaces or special characters
- Quoting is inconsistent across the script
- Config files are sourced directly, which is flexible but implies arbitrary code execution
- The script does not use a stricter shell safety baseline

### 3. Remote execution correctness and safety
- SSH user is hardcoded to `root`
- `cmd:<...>` intentionally allows arbitrary remote command execution, which should be treated as a powerful unsafe feature
- Some remote command constructions are brittle
- The `pacman` orphan-removal command appears incorrect because command substitution is evaluated locally instead of remotely
- The `docker-stacks` remote loop should be reviewed carefully for quoting and path safety

### 4. UX and dependency issues
- Required runtime dependencies are now checked at startup (`ssh`, `whiptail`, `nano`, `sed`, `tee`)
- 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

### 5. Error handling limitations
- Error propagation is inconsistent depending on the action type
- Cleanup commands often do not affect the final failure state
- The script continues through action sequences without a documented policy
- The advertised “break on error” behavior does not exist yet

### 6. Maintainability limitations
- Most logic is concentrated in one script
- There is duplication in package-manager handling
- No tests or validation tooling are present in the repository
- Some wording, typos, and naming inconsistencies reduce clarity

## Recommended direction

### Short term
- Correct the remote command bugs, especially for `pacman`
- Improve parsing of node entries to avoid whitespace-splitting issues
- 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
- Make SSH user, log path, and editor configurable
- Improve non-interactive usage options
- Standardize error handling and exit codes

### Long term
- Refactor the script into smaller functions with less duplication
- Add shell linting guidance (for example ShellCheck)
- 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
- Keep the tool simple and admin-friendly
- Be cautious with changes to remote command construction, as quoting changes can introduce regressions

## Suggested review focus for future changes
- Correctness of remote command execution
- Safe quoting and shell expansion behavior
- Compatibility of config format with existing user setups
- Usability in both interactive and semi-automated contexts