starred/ProxmoxScripts

Fork 0

mirror of https://github.com/coelacant1/ProxmoxScripts.git synced 2026-04-26 17:35:49 +03:00

[PR #19] [MERGED] V2.0 - Proxmox Scripts Update #22

New issue

Closed

opened 2026-03-03 01:17:26 +03:00 by kerem · 0 comments

kerem commented

2026-03-03 01:17:26 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/coelacant1/ProxmoxScripts/pull/19
Author: @coelacant1
Created: 11/25/2025
Status: ✅ Merged
Merged: 11/25/2025
Merged by: @coelacant1

Base: main ← Head: testing

📝 Commits (10+)

c9aeb16 Refactor of VM functionality
04eda8b Extra scripts (storage, hibernate, pause, resume, net, storage, touch pointer), minor fixes,
35d0227 Extra scripts (storage, hibernate, pause, resume, net, storage, touch pointer), minor fixes,
c05c383 Edited BatchRunCLI.sh to allow separate branch calling for testing
cf0fa64 Removed interactive aspects of AddStorage
16697ce Added ArgumentParser and fixed BulkCloneSetIP.sh
421b5ce Added ArgumentParser and fixed BulkCloneSetIP.sh
368c237 Merge branch 'testing' of https://github.com/coelacant1/ProxmoxScripts into testing
7d4f507 V2.0.0 - Major refactor + additional utilities
cd3f695 V2.0.1 - Implementation of ArgumentParser across the codebase and improved scripting standards

📊 Changes

255 files changed (+46987 additions, -11647 deletions)

View changed files

📝 .check/ConvertLineEndings.py (+36 -10)
➕ .check/DeadCodeCheck.py (+322 -0)
➕ .check/DependencyCycleCheck.py (+337 -0)
➕ .check/DocumentationCheck.py (+357 -0)
➕ .check/ErrorHandlingCheck.py (+381 -0)
➕ .check/FormatCheck.py (+232 -0)
➕ .check/LoggingCoverageCheck.py (+201 -0)
➕ .check/README.md (+517 -0)
➕ .check/SecurityCheck.py (+374 -0)
📝 .check/ShellCheck.py (+31 -1)
📝 .check/UpdateFunctionIndex.py (+53 -15)
📝 .check/UpdateUtilityDocumentation.py (+601 -54)
➕ .check/ValidateScriptNotes.py (+388 -0)
📝 .check/VerifySourceCalls.py (+250 -58)
➖ .check/_RunChecks.bat (+0 -4)
📝 .check/_RunChecks.sh (+518 -4)
➕ .docs/GenerateContentDiff.sh (+159 -0)
➕ .docs/HTMLToMarkdown.py (+649 -0)
➕ .docs/README.md (+32 -0)
➕ .docs/TODO.md (+105 -0)

...and 80 more files

📄 Description

name: V2.0 - Proxmox Scripts Update
about: Major refactor introducing unified utility frameworks, testing system, and remote cluster management
title: "[PR] V2.0 - Unified Utility Framework and Remote Cluster Management"
labels: enhancement
assignees: 'coelacant1'

Description

Version 2.0 is an architectural refactor that provides comprehensive utility frameworks, standardizes script behavior across the entire codebase, and adds remote cluster management capabilities.

Key Improvements:

Unified Utility Framework

ArgumentParser.sh - Standardized argument parsing with built-in validation, automatic help text generation, and support for common types (vmid, string, integer, boolean, range)
BulkOperations.sh - Unified framework for bulk VM/LXC operations with consistent error handling, progress reporting, and operation summaries
Operations.sh (formerly ProxmoxAPI.sh) - Centralized Proxmox API wrapper functions for VM/LXC operations, disk management, and pool operations
Network.sh - Network utility functions for IP validation, manipulation, and network configuration
TestFramework.sh - Comprehensive testing framework with unit testing, integration testing, and automated testing

Remote Cluster Management

Execute scripts on single or multiple Proxmox nodes without re-downloading the repository
Temporary multi-remote mode supporting IP ranges (192.168.1.100-200) or VMID ranges
Dual log output with separate .log and .debug.log files for structured logging (local and remote)
Debug flag support (./GUI.sh -d) for detailed remote execution logging
Interrupt handling (Ctrl+C) cleanly cancels remaining nodes during remote operations

Comprehensive Testing System

Test suites for all major utility frameworks (_TestArgumentParser.sh, _TestBulkOperations.sh, _TestNetwork.sh, _TestOperations.sh, _TestStateManager.sh)
RunAllTests.sh for automated test execution across all utilities
Integration test examples demonstrating proper framework usage
Unit testing capabilities with assertion functions and result reporting

Script Compliance Standards

All scripts refactored with consistent headers: shebang -> documentation -> Function Index -> set -euo pipefail -> code
Standardized set -euo pipefail for robust error handling (fixed duplicates and misplaced commands)
All bulk operation scripts (80+ files) migrated to use ArgumentParser and BulkOperations frameworks
Consistent error handling and user feedback across entire codebase
Automated source dependency verification with VerifySourceCalls.py

Quality Assurance Tools

Enhanced .check/_RunChecks.sh with better validation and reporting
UpdateUtilityDocumentation.py for automatic utility function documentation
VerifySourceCalls.py with fix mode for adding/removing dependencies and shellcheck directives
_ScriptComplianceChecklist.md for code quality verification

Cross-Platform GUI Improvements

Auto-detects package manager (apt, dnf, yum, zypper, pacman) for any Linux distribution
Polymorphic menu system with centralized common operations (settings, help, back, exit)
Branch management accessible from all menus
Simplified navigation with consistent input prompts
Parameter history with readline shortcuts

New Utility Scripts

VirtualMachines/Operations/BulkHibernate.sh, BulkSuspend.sh, BulkResume.sh
VirtualMachines/Hardware/BulkToggleTabletPointer.sh
VirtualMachines/Storage/BulkConfigureDisk.sh
Storage/AddStorage.sh (NFS, SMB/CIFS, PBS support)
Storage/RemoveStorage.sh (safe removal with usage checks)

Type of Change

Bug fix (non-breaking change fixing an issue)
New feature (non-breaking change adding functionality)
Breaking change (fix or feature that would break existing functionality)
Documentation update
Other (please describe):

Breaking Changes:

Renamed utilities: ProxmoxAPI.sh -> Operations.sh, Queries.sh -> Cluster.sh, NetworkHelper.sh -> Network.sh
Removed BatchRunCLI.sh (functionality integrated into GUI.sh)
Function renames: __prompt_yes_no__ -> __prompt_user_yn__

How Has This Been Tested?

Test Infrastructure:

Created comprehensive test suites for all major utility frameworks
RunAllTests.sh executes automated tests for ArgumentParser, BulkOperations, Network, Operations, StateManager, and RemoteExec utilities
Integration test examples demonstrate proper framework usage patterns

Testing Performed:

All utility test suites pass successfully
ArgumentParser validation for common types (vmid, string, integer, boolean, range)
BulkOperations framework with 80+ refactored scripts tested for consistency
Remote execution tested on single and multiple Proxmox nodes
Cross-platform GUI tested on multiple Linux distributions (Debian, Ubuntu, Fedora, Arch)
Source dependency verification with VerifySourceCalls.py
Script header standardization across entire codebase

Test Configuration:

Proxmox VE 9.x cluster with 5 nodes and Proxmox VE 8.4.X cluster with 20 nodes
Remote execution from Arch workstation
Test VMs and LXC containers for bulk operation validation
Various storage backends (local, Ceph, NFS, SMB) for storage script testing

Checklist

I have performed a self-review of my own code.
I have commented my code where necessary.
I have made corresponding changes to the documentation.
My changes do not generate new warnings or errors.
I have tested this code.

Additional Compliance:

All scripts follow standardized header format (per CONTRIBUTING.md)
ArgumentParser integration for non-interactive scripts
Proper utility sourcing with shellcheck directives
Function documentation with @function, @description, @param tags
Communication functions (__info__, __ok__, __err__) instead of plain echo
set -euo pipefail for error handling
Updated Utilities/_Utilities.md with comprehensive function documentation
All source dependencies verified with VerifySourceCalls.py
Test coverage for all new frameworks

This pull request adds significant improvements and addresses several architectural concerns:

Standardizes script behavior and error handling
Reduces code duplication through utility frameworks
Adds remote cluster management capabilities
Adds testing infrastructure for quality assurance
Adds cross-platform compatibility for GUI execution

Related to ongoing work documented in CHANGELOG.md sections [2.0.0] through [2.1.5].

Documentation Updates

README.md - Updated with V2.0 features, remote execution guide, and cross-platform information
CONTRIBUTING.md - Enhanced with ArgumentParser standards (Section 3.10) and compliance requirements
CHANGELOG.md - Comprehensive V2.0.0 entry with detailed changes (lines 8-397)
Utilities/_Utilities.md - Expanded with function documentation for all utility frameworks
Script Headers - Headers updated to reflect current state of scripts

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/coelacant1/ProxmoxScripts/pull/19 **Author:** [@coelacant1](https://github.com/coelacant1) **Created:** 11/25/2025 **Status:** ✅ Merged **Merged:** 11/25/2025 **Merged by:** [@coelacant1](https://github.com/coelacant1) **Base:** `main` ← **Head:** `testing` --- ### 📝 Commits (10+) - [`c9aeb16`](https://github.com/coelacant1/ProxmoxScripts/commit/c9aeb16424d588a150da55402f8b2b18cc220132) Refactor of VM functionality - [`04eda8b`](https://github.com/coelacant1/ProxmoxScripts/commit/04eda8b4f0335604a41423adf69ab339b3b3f424) Extra scripts (storage, hibernate, pause, resume, net, storage, touch pointer), minor fixes, - [`35d0227`](https://github.com/coelacant1/ProxmoxScripts/commit/35d0227ac5f183748318b0dae03ce35fa42a205b) Extra scripts (storage, hibernate, pause, resume, net, storage, touch pointer), minor fixes, - [`c05c383`](https://github.com/coelacant1/ProxmoxScripts/commit/c05c38370b260c673e3c09369a56a606eeffcd49) Edited BatchRunCLI.sh to allow separate branch calling for testing - [`cf0fa64`](https://github.com/coelacant1/ProxmoxScripts/commit/cf0fa6462d161b435e3f4a7e5f046522b1b0c99f) Removed interactive aspects of AddStorage - [`16697ce`](https://github.com/coelacant1/ProxmoxScripts/commit/16697ce890883a184393ebd5f5c010e656434138) Added ArgumentParser and fixed BulkCloneSetIP.sh - [`421b5ce`](https://github.com/coelacant1/ProxmoxScripts/commit/421b5ced6e2d999b74486bcb398036a274ccf9cb) Added ArgumentParser and fixed BulkCloneSetIP.sh - [`368c237`](https://github.com/coelacant1/ProxmoxScripts/commit/368c237f7a03ad362c6f991b657da80ad052e16f) Merge branch 'testing' of https://github.com/coelacant1/ProxmoxScripts into testing - [`7d4f507`](https://github.com/coelacant1/ProxmoxScripts/commit/7d4f5070028a4e75bf92a23a525a374199601513) V2.0.0 - Major refactor + additional utilities - [`cd3f695`](https://github.com/coelacant1/ProxmoxScripts/commit/cd3f69510f4f64fcff5e170cffcb1b0fcc57b0e7) V2.0.1 - Implementation of ArgumentParser across the codebase and improved scripting standards ### 📊 Changes **255 files changed** (+46987 additions, -11647 deletions) <details> <summary>View changed files</summary> 📝 `.check/ConvertLineEndings.py` (+36 -10) ➕ `.check/DeadCodeCheck.py` (+322 -0) ➕ `.check/DependencyCycleCheck.py` (+337 -0) ➕ `.check/DocumentationCheck.py` (+357 -0) ➕ `.check/ErrorHandlingCheck.py` (+381 -0) ➕ `.check/FormatCheck.py` (+232 -0) ➕ `.check/LoggingCoverageCheck.py` (+201 -0) ➕ `.check/README.md` (+517 -0) ➕ `.check/SecurityCheck.py` (+374 -0) 📝 `.check/ShellCheck.py` (+31 -1) 📝 `.check/UpdateFunctionIndex.py` (+53 -15) 📝 `.check/UpdateUtilityDocumentation.py` (+601 -54) ➕ `.check/ValidateScriptNotes.py` (+388 -0) 📝 `.check/VerifySourceCalls.py` (+250 -58) ➖ `.check/_RunChecks.bat` (+0 -4) 📝 `.check/_RunChecks.sh` (+518 -4) ➕ `.docs/GenerateContentDiff.sh` (+159 -0) ➕ `.docs/HTMLToMarkdown.py` (+649 -0) ➕ `.docs/README.md` (+32 -0) ➕ `.docs/TODO.md` (+105 -0) _...and 80 more files_ </details> ### 📄 Description --- name: V2.0 - Proxmox Scripts Update about: Major refactor introducing unified utility frameworks, testing system, and remote cluster management title: "[PR] V2.0 - Unified Utility Framework and Remote Cluster Management" labels: enhancement assignees: 'coelacant1' --- ## Description Version 2.0 is an architectural refactor that provides comprehensive utility frameworks, standardizes script behavior across the entire codebase, and adds remote cluster management capabilities. ### Key Improvements: **Unified Utility Framework** - **ArgumentParser.sh** - Standardized argument parsing with built-in validation, automatic help text generation, and support for common types (vmid, string, integer, boolean, range) - **BulkOperations.sh** - Unified framework for bulk VM/LXC operations with consistent error handling, progress reporting, and operation summaries - **Operations.sh** (formerly ProxmoxAPI.sh) - Centralized Proxmox API wrapper functions for VM/LXC operations, disk management, and pool operations - **Network.sh** - Network utility functions for IP validation, manipulation, and network configuration - **TestFramework.sh** - Comprehensive testing framework with unit testing, integration testing, and automated testing **Remote Cluster Management** - Execute scripts on single or multiple Proxmox nodes without re-downloading the repository - Temporary multi-remote mode supporting IP ranges (192.168.1.100-200) or VMID ranges - Dual log output with separate `.log` and `.debug.log` files for structured logging (local and remote) - Debug flag support (`./GUI.sh -d`) for detailed remote execution logging - Interrupt handling (Ctrl+C) cleanly cancels remaining nodes during remote operations **Comprehensive Testing System** - Test suites for all major utility frameworks (_TestArgumentParser.sh, _TestBulkOperations.sh, _TestNetwork.sh, _TestOperations.sh, _TestStateManager.sh) - RunAllTests.sh for automated test execution across all utilities - Integration test examples demonstrating proper framework usage - Unit testing capabilities with assertion functions and result reporting **Script Compliance Standards** - All scripts refactored with consistent headers: shebang -> documentation -> Function Index -> `set -euo pipefail` -> code - Standardized `set -euo pipefail` for robust error handling (fixed duplicates and misplaced commands) - All bulk operation scripts (80+ files) migrated to use ArgumentParser and BulkOperations frameworks - Consistent error handling and user feedback across entire codebase - Automated source dependency verification with VerifySourceCalls.py **Quality Assurance Tools** - Enhanced .check/_RunChecks.sh with better validation and reporting - UpdateUtilityDocumentation.py for automatic utility function documentation - VerifySourceCalls.py with fix mode for adding/removing dependencies and shellcheck directives - _ScriptComplianceChecklist.md for code quality verification **Cross-Platform GUI Improvements** - Auto-detects package manager (apt, dnf, yum, zypper, pacman) for any Linux distribution - Polymorphic menu system with centralized common operations (settings, help, back, exit) - Branch management accessible from all menus - Simplified navigation with consistent input prompts - Parameter history with readline shortcuts **New Utility Scripts** - VirtualMachines/Operations/BulkHibernate.sh, BulkSuspend.sh, BulkResume.sh - VirtualMachines/Hardware/BulkToggleTabletPointer.sh - VirtualMachines/Storage/BulkConfigureDisk.sh - Storage/AddStorage.sh (NFS, SMB/CIFS, PBS support) - Storage/RemoveStorage.sh (safe removal with usage checks) ## Type of Change - [ ] Bug fix (non-breaking change fixing an issue) - [x] New feature (non-breaking change adding functionality) - [x] Breaking change (fix or feature that would break existing functionality) - [x] Documentation update - [ ] Other (please describe): **Breaking Changes:** - Renamed utilities: `ProxmoxAPI.sh` -> `Operations.sh`, `Queries.sh` -> `Cluster.sh`, `NetworkHelper.sh` -> `Network.sh` - Removed `BatchRunCLI.sh` (functionality integrated into GUI.sh) - Function renames: `__prompt_yes_no__` -> `__prompt_user_yn__` ## How Has This Been Tested? **Test Infrastructure:** - Created comprehensive test suites for all major utility frameworks - `RunAllTests.sh` executes automated tests for ArgumentParser, BulkOperations, Network, Operations, StateManager, and RemoteExec utilities - Integration test examples demonstrate proper framework usage patterns **Testing Performed:** - All utility test suites pass successfully - ArgumentParser validation for common types (vmid, string, integer, boolean, range) - BulkOperations framework with 80+ refactored scripts tested for consistency - Remote execution tested on single and multiple Proxmox nodes - Cross-platform GUI tested on multiple Linux distributions (Debian, Ubuntu, Fedora, Arch) - Source dependency verification with VerifySourceCalls.py - Script header standardization across entire codebase **Test Configuration:** - Proxmox VE 9.x cluster with 5 nodes and Proxmox VE 8.4.X cluster with 20 nodes - Remote execution from Arch workstation - Test VMs and LXC containers for bulk operation validation - Various storage backends (local, Ceph, NFS, SMB) for storage script testing ## Checklist - [x] I have performed a self-review of my own code. - [x] I have commented my code where necessary. - [x] I have made corresponding changes to the documentation. - [x] My changes do not generate new warnings or errors. - [x] I have tested this code. **Additional Compliance:** - [x] All scripts follow standardized header format (per CONTRIBUTING.md) - [x] ArgumentParser integration for non-interactive scripts - [x] Proper utility sourcing with shellcheck directives - [x] Function documentation with `@function`, `@description`, `@param` tags - [x] Communication functions (`__info__`, `__ok__`, `__err__`) instead of plain echo - [x] `set -euo pipefail` for error handling - [x] Updated Utilities/_Utilities.md with comprehensive function documentation - [x] All source dependencies verified with VerifySourceCalls.py - [x] Test coverage for all new frameworks ## Related Issues This pull request adds significant improvements and addresses several architectural concerns: - Standardizes script behavior and error handling - Reduces code duplication through utility frameworks - Adds remote cluster management capabilities - Adds testing infrastructure for quality assurance - Adds cross-platform compatibility for GUI execution Related to ongoing work documented in CHANGELOG.md sections [2.0.0] through [2.1.5]. ## Documentation Updates - **README.md** - Updated with V2.0 features, remote execution guide, and cross-platform information - **CONTRIBUTING.md** - Enhanced with ArgumentParser standards (Section 3.10) and compliance requirements - **CHANGELOG.md** - Comprehensive V2.0.0 entry with detailed changes (lines 8-397) - **Utilities/_Utilities.md** - Expanded with function documentation for all utility frameworks - **Script Headers** - Headers updated to reflect current state of scripts --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>