From afea447887d56fc79e7590e330759935317e3c32 Mon Sep 17 00:00:00 2001 From: MatMoul Date: Sun, 26 Apr 2026 00:45:03 +0200 Subject: [PATCH] docs: update roadmap with review findings and next priorities --- state.md | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/state.md b/state.md index fa477a0..0d5d886 100644 --- a/state.md +++ b/state.md @@ -90,19 +90,23 @@ Supported action types currently include: ### Short term - Tackle the next hardening work as small, reviewable commits instead of one broad patch -- Review the remaining quoting-sensitive areas, especially around remote shell command construction +- Define and document an explicit error-handling policy: what is fatal, what is best-effort, and whether host action sequences continue after a failure +- Review the remaining quoting-sensitive areas, especially around remote shell command construction for `cmd:<...>` and `docker-stacks:<...>` +- Align `README.md`, CLI help, and runtime behavior on dependencies and interaction details, especially the actual meaning of `-f`, current log-file behavior, and whether `sed` is still required +- Review sample configuration files for naming or targeting inconsistencies that could lead to operator mistakes ### Medium term - Make SSH user, log path, and editor configurable -- Improve non-interactive usage options +- Improve non-interactive usage options with explicit batch-friendly flags such as a true `--all`, `--no-log-view`, `--keep-log`, and custom log-path support - Standardize error handling and exit codes with a documented policy for best-effort cleanup steps versus fatal failures +- Add lightweight validation or warnings around sourced config files, for example around trust expectations or overly permissive file permissions - Consider adopting a clearer shell option baseline such as an explicit global `pipefail` policy ### Long term - Refactor the script into smaller functions with less duplication -- Add shell linting guidance (for example ShellCheck) +- Add shell linting guidance and automation (for example ShellCheck, optionally shfmt) - Consider a safer declarative configuration format if the project grows -- Add test coverage for parsing and command construction +- Add test coverage for parsing, command construction, and non-regression around SSH quoting behavior ## Recent changes - `README.md` was expanded to document installation, requirements, usage, configuration format, and supported actions @@ -127,8 +131,10 @@ Supported action types currently include: - Preserve backward compatibility for existing config files where possible - Prefer incremental hardening over a full rewrite - Keep the tool simple and admin-friendly -- Split behavioral fixes into small logical commits when possible, for example: selection handling, log generation, package-manager cleanup semantics, and error-policy changes +- Split behavioral fixes into small logical commits when possible, for example: selection handling, log generation, package-manager cleanup semantics, error-policy changes, and non-interactive CLI improvements - Be cautious with changes to remote command construction, as quoting changes can introduce regressions +- Treat documentation and behavior alignment as part of functional quality, not as a separate cleanup task +- Avoid introducing a global `set -euo pipefail` baseline in one step without first documenting and testing the expected failure semantics ## Suggested review focus for future changes - Correctness of package-manager cleanup commands and confirmation flags @@ -138,3 +144,14 @@ Supported action types currently include: - Error-handling policy consistency across action types - Package-manager command correctness and cleanup-step behavior - Usability in both interactive and semi-automated contexts +- Documentation consistency with actual runtime behavior and dependencies +- Review of sample config accuracy to avoid mislabelled hosts or risky operator confusion + +## Additional recommendations from latest review +- Highest priority should go to defining an explicit execution and failure policy, because it currently affects operator trust more than missing features do +- The next highest priority should be protecting against regressions in SSH command construction by documenting manual test cases for commands with spaces, pipes, redirections, `&&`, `||`, and quoted arguments +- A small CLI usability pass would have strong value: `-f` currently only preselects nodes in `whiptail`, so a true non-interactive selection mode would improve automation without changing the overall project model +- The dependency list should be rechecked: `README.md` still mentions `sed`, while the current implementation no longer appears to require it after the log-summary rewrite +- The sample configuration set should be reviewed for consistency; for example, duplicate or mismatched display names attached to different IPs increase the risk of accidental operations on the wrong host +- Shell quality improvements should favor linting, targeted helpers, and incremental refactors before any broad strict-mode changes +- Future testing should focus first on parser behavior, command construction, and result reporting rather than trying to build a large end-to-end framework immediately