fixed updated

docs/modules/PANEL_UPDATE.md

@@ -0,0 +1,200 @@
+# Panel Update Module
+
+## Scope
+
+This document covers the admin Panel updater implemented through:
+
+- `Panel/modules/update/update.php`
+- `Panel/modules/administration/panel_update.php`
+- `Panel/includes/lib_remote.php` for remote agent component updates
+
+## Current Workflow
+
+```text
+Admin opens home.php?m=update
+  -> update.php loads panel_update.php
+  -> gsp_panel_update_section() renders UI
+
+Configured Git update:
+  -> load saved settings
+  -> validate repo/branch/paths/retention
+  -> preflight path and write checks
+  -> create backup when enabled
+  -> git clone configured branch to temp checkout
+  -> resolve source layout
+  -> self-update updater files first if needed
+  -> apply patches
+  -> sync Panel and Website files
+  -> preserve config.inc.php and protected paths
+  -> write LAST_UPDATE.txt and version metadata
+  -> clear cache / fix permissions
+  -> prune backups by retention
+```
+
+## Backup Workflow
+
+Backup helpers:
+
+- `gsp_get_backup_base()`
+- `gsp_get_backup_retention()`
+- `gsp_create_full_backup()`
+- `gsp_safe_component_backup()`
+- `gsp_get_available_backups()`
+- `gsp_get_managed_backup_entries()`
+- `gsp_prune_old_backups()`
+
+Behavior:
+
+- full updater backups use the configured `gsp_update_backup_path`
+- component-only backups also use the configured backup path
+- missing parent directories are created recursively
+- failures are logged to `logs/update_trace.log` with path diagnostics
+- retention is enforced after full backups and component backups
+
+Managed backup directory names:
+
+- full backups: `YYYY-MM-DD_HH-MM-SS`
+- component backups: `component_<name>_YYYY-MM-DD_HH-MM-SS`
+
+Rollback uses only full backups. Component backups are retained and pruned, but are not shown in the rollback selector.
+
+## Retention Workflow
+
+Retention setting:
+
+- `gsp_update_backup_retention`
+- default: `5`
+
+Behavior:
+
+1. Create backup.
+2. Scan all updater-managed backup directories under the configured backup path.
+3. Sort newest to oldest.
+4. Delete entries beyond retention.
+5. Log deleted backup directories to `logs/update_trace.log`.
+
+This applies to both:
+
+- full updater backups
+- component backups created by local component updates
+
+## Required Folders And Permissions
+
+Minimum writable locations:
+
+- configured repository root
+- configured Panel path
+- configured backup path
+- `logs/` under repository root for `update_trace.log`
+
+Required tools when used:
+
+- `git`
+- `tar`
+- `mysqldump` for database backup
+- `mysql` for restore
+
+## Error Handling
+
+The update page should not white-screen for routine helper/runtime failures.
+
+Current protections:
+
+- `update.php` checks that `gsp_panel_update_section()` exists before calling it
+- `update.php` catches `Throwable` and logs unexpected failures
+- `gsp_panel_update_section()` catches action-time `Throwable` and keeps rendering the UI
+- backup directory creation logs detailed path diagnostics
+- missing helper regressions are surfaced as user-visible failures instead of fatal white screens where possible
+
+Log file:
+
+- `GSP_ROOT/logs/update_trace.log`
+
+## Helper Scope Warnings
+
+These helpers must remain top-level:
+
+- `gsp_update_settings()`
+- `gsp_validate_update_settings()`
+- `gsp_checkout_update_source()`
+- `gsp_do_configured_git_update()`
+- `gsp_disable_ssl_vhost()`
+
+If any of these are accidentally nested inside another function, the update page can pass `php -l` but still fail at runtime with `Call to undefined function ...`.
+
+## Scheduler Audit
+
+Current finding:
+
+- the existing `cron` scheduler is game-server oriented
+- it schedules `gamemanager` and `server_content` actions through `ogp_api.php`
+- it does **not** currently expose a first-class scheduled self-update path for:
+  - Panel updates
+  - Website updates
+  - remote Linux agent code updates
+  - remote Windows agent code updates
+
+Result:
+
+- backup/retention integration for scheduled self-updates is currently not applicable because those scheduled self-update jobs do not exist in the current codebase
+- game-server Steam/content scheduler jobs are separate and do not use this updater module
+
+## Remote Agent Update Flow
+
+Remote component updates use:
+
+- `lib_remote.php::component_update()`
+- agent-side `component_update` RPC
+
+The Panel:
+
+1. validates configured repo and source folder
+2. selects Linux or Windows agent source folder
+3. builds an encoded payload
+4. sends the payload over XML-RPC
+5. shows queued/failed results per remote host
+
+## Troubleshooting
+
+### Undefined function crash
+
+Check:
+
+- `php -l Panel/modules/administration/panel_update.php`
+- `php -r 'require "Panel/modules/administration/panel_update.php"; var_dump(function_exists("gsp_checkout_update_source"));'`
+
+If `php -l` passes but `function_exists(...)` is false, a helper was nested inside another function.
+
+### Backup directory creation fails
+
+Check:
+
+- configured `gsp_update_backup_path`
+- parent directory existence
+- web server write access
+- `logs/update_trace.log` for the exact `mkdir` failure
+
+### Retention appears wrong
+
+Remember:
+
+- rollback list shows only full backups
+- managed backup count includes full backups and component backups
+- pruning applies to all updater-managed backup directories
+
+### Update page loads but remote agent updates fail
+
+Check:
+
+- PHP XML-RPC extension on the Panel host
+- agent reachability and encryption key
+- agent-side `component_update` support
+
+## Validation Commands
+
+```bash
+php -l Panel/modules/administration/panel_update.php
+php -l Panel/modules/update/update.php
+php Panel/modules/update/tests/update_config_smoke.php
+php -r 'require "Panel/modules/administration/panel_update.php"; foreach (["gsp_checkout_update_source","gsp_do_configured_git_update","gsp_disable_ssl_vhost"] as $f) echo $f,":",function_exists($f)?"yes":"no",PHP_EOL;'
+```

docs/modules/SCHEDULER.md

@@ -94,3 +94,6 @@ If scheduler behavior needs deeper investigation, start with:
 - `Agent_Linux/ogp_agent.pl` scheduler subroutines
 - `Agent-Windows/ogp_agent.pl` scheduler subroutines
 
+## Current Panel Update Finding
+
+The current scheduler does not provide a first-class path for scheduling Panel, Website, or remote agent self-updates. Existing scheduled update actions are game-server oriented, for example `gamemanager/update&type=steam` and Server Content actions. Backup and retention behavior in `Panel/modules/administration/panel_update.php` therefore applies to manual/admin-triggered updater flows, not to any existing scheduled self-update job.

docs/modules/UPDATE.md

@@ -1,5 +1,9 @@
 # Update Module
 
+Primary operational reference:
+
+- `docs/modules/PANEL_UPDATE.md`
+
 ## Role
 
 `Panel/modules/update` exposes the admin Panel update page. The page delegates most update behavior to: