chore: rename repository state file to STATE.md

STATE.md

@@ -0,0 +1,83 @@
+# Repository state
+
+## Project summary
+- Name: `netupgrade`
+- Language: Bash
+- Entry point: `bin/netupgrade`
+- Purpose: interactive CLI to run maintenance and upgrade actions on multiple remote hosts over SSH
+- Config model: Bash 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
+- `TODO.md`: prioritized next actions and follow-up work
+- `docs/`: project documentation
+
+## Current behavior
+- Loads a Bash configuration file
+- Expects a `NODES` array with entries formatted as `host;display-name;action1;action2;...`
+- Displays an interactive multi-select checklist using `whiptail`
+- Executes selected actions sequentially over SSH
+- Uses `root@host` by default, or `SSH_USER@host` when configured
+- Writes execution logs to `~/netupgrade.log`
+- Opens the log with `$EDITOR`, then `nano`, `vi`, or `less`; if none is available, prints the log path and continues with the existing optional cleanup prompt
+
+## Supported actions
+- `apt`
+- `yum`
+- `pkg`
+- `pacman`
+- `apk`
+- `reboot`
+- `cmd:<remote command>`
+- `docker-stacks:<directory>`
+
+## Architecture and constraints
+- The project is intentionally lightweight and shell-based
+- The main execution flow still lives mostly in a single Bash script
+- Configuration is code-driven rather than declarative, because config files are sourced as shell files
+- Config files are trusted inputs and imply arbitrary code execution
+- Remote operations are sequential, not parallel
+- Logging is file-based and tightly coupled to command execution
+- Backward compatibility for existing config files should be preserved where possible
+- Changes to SSH command construction require extra care because quoting regressions are easy to introduce
+
+## Notable implementation details
+- SSH execution is centralized through a `runSSH` helper
+- `SSH_USER` is configurable and defaults to `root`
+- `NODES` parsing was hardened to preserve spaces in action values such as `cmd:...`
+- `cmd:<...>` is executed through a remote shell to support shell operators, but remains intentionally powerful and unsafe
+- `reboot` uses a detached remote command to reduce false failures caused by expected SSH disconnects
+- `docker-stacks` runs through a remote shell script sent over SSH stdin to improve path handling and quoting
+- Startup dependency checks cover required local commands, including `mv` for log-summary rewriting
+
+## Sensitive areas for future changes
+- SSH command construction and shell quoting behavior
+- `cmd:<...>` execution semantics
+- `docker-stacks:<...>` path handling and remote shell behavior
+- Package-manager cleanup commands and confirmation flags
+- Error propagation consistency across action types
+- Documentation and runtime behavior alignment
+- Sample configuration accuracy to avoid operator mistakes
+
+## Recent meaningful changes
+- README and CLI help were aligned with current behavior, including the meaning of `-f`
+- Startup dependency checks were added and updated
+- Log viewer fallback was made more flexible
+- `NODES` parsing was hardened to preserve spaces in action values
+- SSH execution was centralized and made configurable through `SSH_USER`
+- Remote command construction was improved for `pacman`, `docker-stacks`, and `reboot`
+- Log summary generation was rewritten to avoid `sed -i` interpolation and now replaces the log atomically
+- `apk` and `apt` cleanup behavior was corrected to better match real package-manager semantics
+- The sample configuration in `config/netupgrade/hypervisor-01.cfg` now keeps the alternate `docker-01` reboot example commented out rather than active by default
+
+## Change guidance
+- `STATE.md` should stay focused on current state, architecture, and constraints
+- `TODO.md` should hold prioritized follow-up work and next implementation steps
+- Prefer small, reviewable hardening changes over broad rewrites
+- Keep the tool simple and admin-friendly
+- Treat documentation consistency as part of functional correctness
+- Be cautious with remote command construction, because quoting changes can easily introduce regressions
+- Avoid introducing a global `set -euo pipefail` baseline in one step without first documenting and validating the intended failure semantics
+- Focus future testing first on parsing, command construction, and result reporting