From 9de65f9aa5a20406bf9b8b05fc12bbc71fa20c10 Mon Sep 17 00:00:00 2001 From: MatMoul Date: Sat, 25 Apr 2026 23:51:29 +0200 Subject: [PATCH] chore: add repository guidance and state context files --- .continue/rules/global-file-standard.md | 13 +++ state.md | 121 ++++++++++++++++++++++++ 2 files changed, 134 insertions(+) create mode 100644 .continue/rules/global-file-standard.md create mode 100644 state.md diff --git a/.continue/rules/global-file-standard.md b/.continue/rules/global-file-standard.md new file mode 100644 index 0000000..6b38aea --- /dev/null +++ b/.continue/rules/global-file-standard.md @@ -0,0 +1,13 @@ +--- +alwaysApply: true +--- + +Apply consistent coding standards, preserve existing project conventions, and avoid introducing breaking changes in all files unless explicitly requested. + +Also read and consider the repository state file when it exists: +- `state.md` + +When this file is present: +- use it as evolving project context, +- keep recommendations aligned with it, +- update suggestions to remain consistent with documented architecture, constraints, and review notes. \ No newline at end of file diff --git a/state.md b/state.md new file mode 100644 index 0000000..09e9bce --- /dev/null +++ b/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:` +- `docker-stacks:` + +## 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