chore: add repository guidance and state context files

state.md

@@ -0,0 +1,121 @@
+# 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` contains a typo in the configuration path (`netuprade` instead of `netupgrade`)
+- The CLI help mentions `-b` but that option is not implemented
+- `--help` exists in code but is not documented in the displayed usage
+- The configuration format is not documented in enough 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
+- `whiptail` is required for selection but is not checked before use
+- `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
+
+### 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
+- Fix documentation and help output to match actual behavior
+- Correct the remote command bugs, especially for `pacman`
+- Add dependency checks for required external tools
+- Either implement or remove unsupported CLI options such as `-b`
+
+### 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
+
+## 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