chore(version): pre-release bump to 02.58.05-dev [skip ci]

MokoRestore::generateStandaloneScript() rewrites the 'Backup Archive'
pre-check via str_replace(ORIG, REPL) but was missing the third
$php subject argument, so every standalone-mode backup fatally errored
with 'str_replace() expects at least 3 arguments, 2 given' at the
'Generating standalone restore.php...' step. The archive still finalized
and uploaded, but no restore.php was produced -- the underlying cause of
#226 (restore script missing on the remote).

Refs #226

Claude-Session: https://claude.ai/code/session_01WbGBN9VyRK61zczYWcCQ2i

.mokogitea/CLAUDE.md

@@ -59,8 +59,8 @@ Joomla **package** with four sub-extensions:
 - **Attribution**: `Authored-by: Moko Consulting`
 - **Workflow directory**: `.mokogitea/` (not `.gitea/` or `.github/`)
 - **Minification**: handled at build time (CI)
-- **Wiki**: documentation lives in the Gitea wiki, not `docs/` files
-- **Standards**: [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/mokocli/wiki/Home)
+- **Wiki**: documentation lives in the MokoGitea wiki, not `docs/` files
+- **Standards**: [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/.mokogitea/wiki)
 
 ## Coding Standards
 

.mokogitea/workflows/auto-release.yml

@@ -380,10 +380,13 @@ jobs:
           import sys
           version, date = sys.argv[1], sys.argv[2]
           content = open('CHANGELOG.md').read()
-          old = '## [Unreleased]'
-          new = f'## [Unreleased]\n\n## [{version}] --- {date}'
-          content = content.replace(old, new, 1)
-          open('CHANGELOG.md', 'w').write(content)
+          marker = f'## [{version}]'
+          # Idempotent: only promote when this version header isn't already present,
+          # otherwise re-runs (or same-version builds) create empty duplicate headers.
+          if marker not in content:
+              new = f'## [Unreleased]\n\n{marker} --- {date}'
+              content = content.replace('## [Unreleased]', new, 1)
+              open('CHANGELOG.md', 'w').write(content)
           " "$VERSION" "$DATE"
             git add CHANGELOG.md
             git commit -m "chore: promote changelog [Unreleased] → [${VERSION}]" || true

.mokogitea/workflows/issue-branch.yml

@@ -5,7 +5,7 @@
 # FILE INFORMATION
 # DEFGROUP: MokoGitea.Workflow
 # INGROUP: mokocli.Automation
-# VERSION: 02.56.11
+# VERSION: 02.58.05
 # BRIEF: Auto-create feature branch when an issue is opened
 
 name: "Universal: Issue Branch"

CHANGELOG.md

@@ -1,6 +1,39 @@
 # Changelog
+
 ## [Unreleased]
 
+### Fixed
+- Standalone restore script generation no longer aborts backups with `str_replace() expects at least 3 arguments, 2 given`. `MokoRestore::generateStandaloneScript()` had a `str_replace()` call (the "Backup Archive" pre-check rewrite) that was missing its `$php` subject argument, so **every** standalone-mode backup fatally errored while "Generating standalone restore.php…" — the archive still finalized and uploaded, but no `restore.php` was ever produced (the true root cause behind #226). (#226)
+- Remote upload: the standalone restore script upload is no longer silent — its result is now checked and logged, and a failed restore-script upload marks the backup as `warning` (previously the result was discarded, so a missing restore script on the remote went unreported while the archive still showed success). (#226)
+
+## [02.58.00] --- 2026-07-06
+
+### Added
+- SFTP destinations: **upload an SSH private key file** in the Add/Edit Destination modal instead of pasting it (reads the file into the key field client-side; pasting still works).
+
+### Changed
+- Add/Edit Destination modal: wrap the content in a Bootstrap `.container-fluid` and give it a 1rem padding frame via the WAM stylesheet (Bootstrap's `.modal-content` has no padding of its own).
+
+### Fixed
+- Pre-update backup now shows an admin notification on **every** outcome (success / warning / failure) — previously a *successful* pre-update backup fired nothing, so it looked like the notification wasn't working. (#192)
+
+### Changed
+- Component admin CSS now loads via the Joomla **Web Asset Manager** (`media/com_mokosuitebackup/` + `joomla.asset.json`) instead of an inline `<style>` block.
+- "Keep local copy" is configured **per remote destination** (in the Add/Edit Destination modal); the redundant profile-level field and its "Remote" tab are removed.
+- Add/Edit Destination modal: cleaned up the cramped padding/margins.
+
+### Fixed
+- Admin menu / duplicate-component fallout: (a) the orphaned `com_component-mokosuitebackup` is now removed in **preflight** too, so its "Backup" menu no longer collides on install ("The alias backup is already being used"); (b) `ensureSubmenuItems()` **recreates the top-level "Backup" menu** if it was deleted, instead of giving up — so Backup no longer disappears from the admin menu (and the cPanel module / MokoSuiteClient can find it again); (c) the component menu label now uses the short constant `COM_MOKOJOOMBACKUP_SHORT`. (#213 fallout)
+- Installer no longer aborts on MySQL 8 with "This command is not supported in the prepared statement protocol yet" (error 1295). The legacy remote-column purge migration (`02.56.01.sql`) used `PREPARE`/`EXECUTE`/`DEALLOCATE`, which Joomla's installer rejects; the drop now runs in the package installer script via an INFORMATION_SCHEMA-gated plain `ALTER` (portable across MariaDB and MySQL 8). (#213 update path)
+
+## [02.57.00] --- 2026-07-05
+
+### Added
+- `BackupRunner` service — a single synchronous entry point for backups that unifies final status and notification gating across the pre-update, web-cron, pre-install, scheduled-task and CLI triggers (delegates to `BackupEngine`; no double-notify). Returns a normalized result including the real complete/warning/fail status. Dashboard "Backup Now" (AJAX) unchanged; installer progress popup deferred to #196. (#214)
+
+### Fixed
+- Release automation: the changelog-promote step is now idempotent — it only inserts a `## [version]` header when that version isn't already present, preventing the empty, duplicated version headers that repeated/same-version builds were producing. (workflow)
+
 ## [02.56.11] --- 2026-07-05
 
 ### Fixed

CONTRIBUTING.md

@@ -4,7 +4,7 @@ Thank you for your interest in contributing to MokoSuiteBackup.
 
 ## Getting Started
 
-1. Fork the repository on Gitea
+1. Fork the repository on MokoGitea
 2. Create a feature branch from `dev` (`feature/your-feature`)
 3. Make your changes following the coding standards below
 4. Submit a pull request targeting `dev`

SECURITY.md

@@ -23,7 +23,7 @@ DEFGROUP: Template-Joomla
 INGROUP: Template-Joomla.Documentation
 REPO: https://git.mokoconsulting.tech/MokoConsulting/Template-Joomla
 PATH: /SECURITY.md
-VERSION: 02.56.11
+VERSION: 02.58.05
 BRIEF: Security vulnerability reporting and handling policy
 -->
 

source/packages/com_mokosuitebackup/forms/profile.xml

@@ -205,19 +205,9 @@
 		/>
 	</fieldset>
 
-	<fieldset name="remote" label="COM_MOKOJOOMBACKUP_FIELDSET_REMOTE">
-		<field
-			name="remote_keep_local"
-			type="radio"
-			label="COM_MOKOJOOMBACKUP_FIELD_KEEP_LOCAL"
-			description="COM_MOKOJOOMBACKUP_FIELD_KEEP_LOCAL_DESC"
-			default="1"
-			class="btn-group"
-		>
-			<option value="1">JYES</option>
-			<option value="0">JNO</option>
-		</field>
-	</fieldset>
+	<!-- The "Keep local copy" setting is now configured per remote destination
+	     (in the Add/Edit Destination modal), so the profile-level field and its
+	     "Remote" tab have been removed. -->
 
 	<fieldset name="retention" label="COM_MOKOJOOMBACKUP_FIELDSET_RETENTION">
 		<field

source/packages/com_mokosuitebackup/media/css/admin.css

@@ -0,0 +1,33 @@
+/**
+ * MokoSuiteBackup — admin styles (loaded via the Joomla Web Asset Manager).
+ */
+
+/* Add/Edit Destination modal.
+ * The modal content is wrapped in a Bootstrap .container-fluid because
+ * Bootstrap's .modal-content has no padding of its own. Give that container a
+ * single, comfortable 1rem frame and drop the inner sections' horizontal padding
+ * so it isn't doubled. */
+#remoteModal .modal-content > .container-fluid {
+	padding: 1rem;
+}
+
+#remoteModal .modal-header,
+#remoteModal .modal-body,
+#remoteModal .modal-footer {
+	padding-left: 0;
+	padding-right: 0;
+}
+
+#remoteModal .modal-body .row + .row,
+#remoteModal .remote-type-fields {
+	margin-top: 0.25rem;
+}
+
+#remoteModal hr {
+	margin: 1rem 0;
+	opacity: 0.12;
+}
+
+#remoteModal .form-label {
+	margin-bottom: 0.35rem;
+}

source/packages/com_mokosuitebackup/media/joomla.asset.json

@@ -0,0 +1,14 @@
+{
+	"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
+	"name": "com_mokosuitebackup",
+	"version": "1.0.0",
+	"description": "MokoSuiteBackup web assets",
+	"license": "GPL-3.0-or-later",
+	"assets": [
+		{
+			"name": "com_mokosuitebackup.admin",
+			"type": "style",
+			"uri": "com_mokosuitebackup/css/admin.css"
+		}
+	]
+}

source/packages/com_mokosuitebackup/mokosuitebackup.xml

@@ -17,7 +17,7 @@
 		display label there.
 	-->
 	<name>MokoSuiteBackup</name>
-	<version>02.56.11</version>
+	<version>02.58.05</version>
 	<creationDate>2026-06-02</creationDate>
 	<author>Moko Consulting</author>
 	<authorEmail>hello@mokoconsulting.tech</authorEmail>
@@ -47,7 +47,7 @@
 	</update>
 
 	<administration>
-		<menu img="class:archive">Backup</menu>
+		<menu img="class:archive">COM_MOKOJOOMBACKUP_SHORT</menu>
 		<submenu>
 			<menu link="option=com_mokosuitebackup&amp;view=dashboard"
 				  img="class:home"
@@ -78,6 +78,11 @@
 		</languages>
 	</administration>
 
+	<media destination="com_mokosuitebackup" folder="media">
+		<folder>css</folder>
+		<filename>joomla.asset.json</filename>
+	</media>
+
 	<api>
 		<files folder="api">
 			<folder>src</folder>

source/packages/com_mokosuitebackup/sql/updates/mysql/02.56.01.sql

@@ -1,32 +1,13 @@
--- Purge legacy single-remote storage columns from installs where they are still present.
+-- Legacy single-remote storage columns are now purged by the package installer
+-- script (Pkg_MokoSuiteBackupInstallerScript::dropLegacyRemoteColumns()), NOT here.
 --
--- Background: 02.52.25.sql originally used `DROP COLUMN IF EXISTS`, which is a
--- MariaDB-only extension and errors on Oracle MySQL 8.x. On MySQL 8 installs the
--- migration failed but Joomla still recorded the schema as applied, leaving all 26
--- legacy remote_storage/ftp_*/sftp_*/gdrive_*/s3_* columns stranded on the profiles
--- table. This migration removes them portably.
+-- The 26 legacy remote_storage/ftp_*/sftp_*/gdrive_*/s3_* columns must be removed
+-- portably across MariaDB and MySQL 8. `DROP COLUMN IF EXISTS` is MariaDB-only
+-- (errors on MySQL 8); plain `DROP COLUMN` errors when a column is absent. The
+-- previous version gated the ALTER on INFORMATION_SCHEMA and ran it via
+-- PREPARE/EXECUTE/DEALLOCATE — but those statements are rejected by Joomla's
+-- installer SQL path (MySQL error 1295: "This command is not supported in the
+-- prepared statement protocol yet"), which ABORTED the whole component install.
 --
--- It must be safe on BOTH engines AND on installs where the columns are already gone
--- (MariaDB, or anyone who ran the corrected 02.52.25). Plain `DROP COLUMN` errors when
--- a column is absent, and `DROP COLUMN IF EXISTS` errors on MySQL 8 — so neither works
--- unconditionally. We gate the drop on INFORMATION_SCHEMA and build the ALTER via a
--- prepared statement, which runs on MySQL 8 and MariaDB alike. All 26 columns were
--- created and dropped together, so the presence of `remote_storage` gates the whole set.
--- When the columns are absent this is a no-op (`DO 0`).
-
-SET @moko_has_legacy_remote := (
-    SELECT COUNT(*)
-    FROM INFORMATION_SCHEMA.COLUMNS
-    WHERE TABLE_SCHEMA = DATABASE()
-      AND TABLE_NAME = '#__mokosuitebackup_profiles'
-      AND COLUMN_NAME = 'remote_storage'
-);
-
-SET @moko_drop_legacy_remote := IF(@moko_has_legacy_remote > 0,
-    'ALTER TABLE `#__mokosuitebackup_profiles` DROP COLUMN `remote_storage`, DROP COLUMN `ftp_host`, DROP COLUMN `ftp_port`, DROP COLUMN `ftp_username`, DROP COLUMN `ftp_password`, DROP COLUMN `ftp_path`, DROP COLUMN `ftp_passive`, DROP COLUMN `ftp_ssl`, DROP COLUMN `sftp_host`, DROP COLUMN `sftp_port`, DROP COLUMN `sftp_username`, DROP COLUMN `sftp_auth_type`, DROP COLUMN `sftp_password`, DROP COLUMN `sftp_key_data`, DROP COLUMN `sftp_passphrase`, DROP COLUMN `sftp_path`, DROP COLUMN `gdrive_client_id`, DROP COLUMN `gdrive_client_secret`, DROP COLUMN `gdrive_refresh_token`, DROP COLUMN `gdrive_folder_id`, DROP COLUMN `s3_endpoint`, DROP COLUMN `s3_region`, DROP COLUMN `s3_access_key`, DROP COLUMN `s3_secret_key`, DROP COLUMN `s3_bucket`, DROP COLUMN `s3_path`',
-    'DO 0'
-);
-
-PREPARE moko_stmt FROM @moko_drop_legacy_remote;
-EXECUTE moko_stmt;
-DEALLOCATE PREPARE moko_stmt;
+-- The drop is now done in PHP (INFORMATION_SCHEMA gate + a plain ALTER for only the
+-- columns that still exist), so this migration is intentionally a no-op.

source/packages/com_mokosuitebackup/sql/updates/mysql/02.57.00.sql

@@ -0,0 +1 @@
+/* 02.57.00 — no schema changes */

source/packages/com_mokosuitebackup/sql/updates/mysql/02.57.01.sql

@@ -0,0 +1 @@
+/* 02.57.01 — no schema changes */

source/packages/com_mokosuitebackup/sql/updates/mysql/02.57.02.sql

@@ -0,0 +1 @@
+/* 02.57.02 — no schema changes */

source/packages/com_mokosuitebackup/sql/updates/mysql/02.57.04.sql

@@ -0,0 +1 @@
+/* 02.57.04 — no schema changes */

source/packages/com_mokosuitebackup/sql/updates/mysql/02.57.05.sql

@@ -0,0 +1 @@
+/* 02.57.05 — no schema changes */

source/packages/com_mokosuitebackup/sql/updates/mysql/02.57.06.sql

@@ -0,0 +1 @@
+/* 02.57.06 — no schema changes */

source/packages/com_mokosuitebackup/sql/updates/mysql/02.57.07.sql

@@ -0,0 +1 @@
+/* 02.57.07 — no schema changes */

source/packages/com_mokosuitebackup/sql/updates/mysql/02.57.08.sql

@@ -0,0 +1 @@
+/* 02.57.08 — no schema changes */

source/packages/com_mokosuitebackup/sql/updates/mysql/02.57.09.sql

@@ -0,0 +1 @@
+/* 02.57.09 — no schema changes */

source/packages/com_mokosuitebackup/sql/updates/mysql/02.57.10.sql

@@ -0,0 +1 @@
+/* 02.57.10 — no schema changes */

source/packages/com_mokosuitebackup/sql/updates/mysql/02.57.11.sql

@@ -0,0 +1 @@
+/* 02.57.11 — no schema changes */

source/packages/com_mokosuitebackup/sql/updates/mysql/02.57.12.sql

@@ -0,0 +1 @@
+/* 02.57.12 — no schema changes */

source/packages/com_mokosuitebackup/sql/updates/mysql/02.57.13.sql

@@ -0,0 +1 @@
+/* 02.57.13 — no schema changes */

source/packages/com_mokosuitebackup/sql/updates/mysql/02.58.00.sql

@@ -0,0 +1 @@
+/* 02.58.00 — no schema changes */

source/packages/com_mokosuitebackup/sql/updates/mysql/02.58.01.sql

@@ -0,0 +1 @@
+/* 02.58.01 — no schema changes */

source/packages/com_mokosuitebackup/sql/updates/mysql/02.58.02.sql

@@ -0,0 +1 @@
+/* 02.58.02 — no schema changes */

source/packages/com_mokosuitebackup/sql/updates/mysql/02.58.03.sql

@@ -0,0 +1 @@
+/* 02.58.03 — no schema changes */

source/packages/com_mokosuitebackup/sql/updates/mysql/02.58.04.sql

@@ -0,0 +1 @@
+/* 02.58.04 — no schema changes */

source/packages/com_mokosuitebackup/sql/updates/mysql/02.58.05.sql

@@ -0,0 +1 @@
+/* 02.58.05 — no schema changes */

source/packages/com_mokosuitebackup/src/Engine/BackupEngine.php

@@ -304,7 +304,18 @@ class BackupEngine
 							$this->log('  Upload complete: ' . $result['message']);
 
 							if (!empty($restoreScriptPath) && is_file($restoreScriptPath)) {
-								$uploader->upload($restoreScriptPath, basename($restoreScriptPath));
+								$scriptName = basename($restoreScriptPath);
+								$this->log('  Uploading restore script: ' . $scriptName . '...');
+								$scriptResult = $uploader->upload($restoreScriptPath, $scriptName);
+
+								if (!empty($scriptResult['success'])) {
+									$this->log('  Restore script uploaded: ' . ($scriptResult['message'] ?? $scriptName));
+								} else {
+									/* Never silent: a missing restore script makes the archive
+									   much harder to restore, so surface it as a warning. */
+									$uploadFailed = true;
+									$this->log('  WARNING: Restore script upload failed: ' . ($scriptResult['message'] ?? 'unknown error'));
+								}
 							}
 						} else {
 							$uploadFailed = true;

source/packages/com_mokosuitebackup/src/Engine/MokoRestore.php

@@ -204,7 +204,8 @@ ORIG,
         'ok'    => $backupCount > 0,
         'hint'  => 'Place one or more backup ZIP files in the same directory as ' . basename($_SERVER['SCRIPT_NAME']),
     ];
-REPL
+REPL,
+			$php
 		);
 
 		/* Modify remaining pre-checks to use getSelectedBackupFile() */

source/packages/com_mokosuitebackup/src/Service/BackupRunner.php

@@ -0,0 +1,109 @@
+<?php
+
+/**
+ * @package     MokoSuiteBackup
+ * @subpackage  com_mokosuitebackup
+ * @author      Moko Consulting <hello@mokoconsulting.tech>
+ * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
+ * @license     GNU General Public License version 3 or later; see LICENSE
+ *
+ * Single synchronous entry point for running a backup.
+ *
+ * Every non-interactive trigger — the web-cron handler, the pre-install /
+ * pre-update / pre-uninstall hooks, the scheduled task plugin and the CLI
+ * command — runs through here, so the final status, notification gating and
+ * retention are applied identically regardless of what started the backup.
+ * (The dashboard's AJAX "Backup Now" is the interactive equivalent, driven by
+ * SteppedBackupEngine.)
+ *
+ * BackupEngine::run() already sends notifications (gated by the profile's
+ * notify_on_success / notify_on_failure) and applies retention, so this class
+ * DELEGATES rather than reimplementing that logic — there is exactly one
+ * notification layer. Its value is being the documented seam where origin-aware
+ * behaviour can live and normalising the result, including the real
+ * complete / warning / fail status that the engine records but does not return.
+ */
+
+namespace Joomla\Component\MokoSuiteBackup\Administrator\Service;
+
+defined('_JEXEC') or die;
+
+use Joomla\CMS\Factory;
+use Joomla\Component\MokoSuiteBackup\Administrator\Engine\BackupEngine;
+
+final class BackupRunner
+{
+	/**
+	 * Run a full backup synchronously and return a normalised result.
+	 *
+	 * @param   int     $profileId    Profile to back up.
+	 * @param   string  $description  Human-readable description stored on the record.
+	 * @param   string  $origin       Trigger origin (webcron|preaction|scheduled|cli|backend…).
+	 *
+	 * @return  array{success:bool,status:string,message:string,record_id:int,warnings:array}
+	 */
+	public function run(int $profileId, string $description, string $origin = 'backend'): array
+	{
+		// TODO(#196): an interactive progress popup for installer-triggered runs
+		// (onExtensionBeforeUpdate) is a separate follow-up — the installer
+		// request cannot drive the AJAX/stepped progress modal.
+		try {
+			if (!class_exists(BackupEngine::class)) {
+				require_once __DIR__ . '/../Engine/BackupEngine.php';
+			}
+
+			$result = (new BackupEngine())->run($profileId, $description, $origin);
+		} catch (\Throwable $e) {
+			error_log('MokoSuiteBackup: backup run failed (' . $origin . '): ' . $e->getMessage());
+
+			return [
+				'success'   => false,
+				'status'    => 'fail',
+				'message'   => 'Backup failed: ' . $e->getMessage(),
+				'record_id' => 0,
+				'warnings'  => [],
+			];
+		}
+
+		$success  = (bool) ($result['success'] ?? false);
+		$recordId = (int) ($result['record_id'] ?? 0);
+
+		return [
+			'success'   => $success,
+			'status'    => $this->resolveStatus($success, $recordId),
+			'message'   => (string) ($result['message'] ?? ''),
+			'record_id' => $recordId,
+			'warnings'  => $result['warnings'] ?? [],
+		];
+	}
+
+	/**
+	 * Read the status BackupEngine wrote to the record (complete/warning/fail)
+	 * but does not return, so callers can distinguish a warning (archive created,
+	 * remote upload failed) from a clean success.
+	 */
+	private function resolveStatus(bool $success, int $recordId): string
+	{
+		if (!$success) {
+			return 'fail';
+		}
+
+		if ($recordId <= 0) {
+			return 'complete';
+		}
+
+		try {
+			$db    = Factory::getDbo();
+			$query = $db->getQuery(true)
+				->select($db->quoteName('status'))
+				->from($db->quoteName('#__mokosuitebackup_records'))
+				->where($db->quoteName('id') . ' = ' . (int) $recordId);
+			$db->setQuery($query);
+			$status = (string) $db->loadResult();
+
+			return $status !== '' ? $status : 'complete';
+		} catch (\Throwable $e) {
+			return 'complete';
+		}
+	}
+}

source/packages/com_mokosuitebackup/tmpl/profile/edit.php

@@ -19,6 +19,9 @@ HTMLHelper::_('behavior.formvalidator');
 HTMLHelper::_('behavior.keepalive');
 HTMLHelper::_('bootstrap.modal');
 
+/* Component CSS via the Web Asset Manager (declared in media/joomla.asset.json) */
+$this->getDocument()->getWebAssetManager()->useStyle('com_mokosuitebackup.admin');
+
 $profileId = (int) $this->item->id;
 $token     = Session::getFormToken();
 ?>
@@ -121,6 +124,7 @@ $token     = Session::getFormToken();
 <div class="modal fade" id="remoteModal" tabindex="-1" aria-labelledby="remoteModalLabel" aria-hidden="true">
 	<div class="modal-dialog modal-lg">
 		<div class="modal-content">
+			<div class="container-fluid">
 			<div class="modal-header">
 				<h5 class="modal-title" id="remoteModalLabel"><?php echo Text::_('COM_MOKOJOOMBACKUP_REMOTE_ADD'); ?></h5>
 				<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="<?php echo Text::_('JCLOSE'); ?>"></button>
@@ -190,7 +194,9 @@ $token     = Session::getFormToken();
 					</div>
 					<div class="mb-3" id="remoteSftpKeyWrap">
 						<label for="remoteCfg_sftp_key_data" class="form-label"><?php echo Text::_('COM_MOKOJOOMBACKUP_FIELD_SFTP_KEY'); ?></label>
-						<textarea class="form-control" id="remoteCfg_sftp_key_data" rows="4" placeholder="Paste SSH private key or leave as-is to keep existing"></textarea>
+						<input type="file" class="form-control mb-2" id="remoteSftpKeyFile" accept=".pem,.key,.ppk,.openssh,.rsa,.ed25519,text/plain">
+						<textarea class="form-control" id="remoteCfg_sftp_key_data" rows="4" placeholder="Upload a key file above, or paste the SSH private key here (leave as-is to keep existing)"></textarea>
+						<div class="form-text" id="remoteSftpKeyFileMsg"></div>
 					</div>
 					<div class="mb-3" id="remoteSftpPassphraseWrap">
 						<label for="remoteCfg_sftp_passphrase" class="form-label"><?php echo Text::_('COM_MOKOJOOMBACKUP_FIELD_SFTP_PASSPHRASE'); ?></label>
@@ -257,6 +263,7 @@ $token     = Session::getFormToken();
 					<?php echo Text::_('JAPPLY'); ?>
 				</button>
 			</div>
+			</div>
 		</div>
 	</div>
 </div>
@@ -452,6 +459,29 @@ document.addEventListener('DOMContentLoaded', function() {
 		}
 	});
 
+	// ---- Upload SSH key file (fills the key textarea; no paste required) ----
+	const keyFileInput = document.getElementById('remoteSftpKeyFile');
+	if (keyFileInput) {
+		keyFileInput.addEventListener('change', function() {
+			const msg  = document.getElementById('remoteSftpKeyFileMsg');
+			const file = this.files && this.files[0];
+
+			if (!file) {
+				return;
+			}
+
+			const reader = new FileReader();
+			reader.onload = function(ev) {
+				document.getElementById('remoteCfg_sftp_key_data').value = ev.target.result;
+				if (msg) { msg.textContent = 'Loaded "' + file.name + '".'; msg.className = 'form-text text-success'; }
+			};
+			reader.onerror = function() {
+				if (msg) { msg.textContent = 'Could not read that file.'; msg.className = 'form-text text-danger'; }
+			};
+			reader.readAsText(file);
+		});
+	}
+
 	// ---- Add button ----
 	document.getElementById('btnAddRemote').addEventListener('click', function() {
 		openEdit(0);

source/packages/mod_mokosuitebackup_cpanel/mod_mokosuitebackup_cpanel.xml

@@ -8,7 +8,7 @@
  -->
 <extension type="module" client="administrator" method="upgrade">
 	<name>Module - MokoSuiteBackup - cPanel</name>
-	<version>02.56.11</version>
+	<version>02.58.05</version>
 	<creationDate>2026-06-23</creationDate>
 	<author>Moko Consulting</author>
 	<authorEmail>hello@mokoconsulting.tech</authorEmail>

source/packages/plg_actionlog_mokosuitebackup/mokosuitebackup.xml

@@ -7,7 +7,7 @@
  -->
 <extension type="plugin" group="actionlog" method="upgrade">
 	<name>Action Log - MokoSuiteBackup</name>
-	<version>02.56.11</version>
+	<version>02.58.05</version>
 	<creationDate>2026-06-04</creationDate>
 	<author>Moko Consulting</author>
 	<authorEmail>hello@mokoconsulting.tech</authorEmail>

source/packages/plg_console_mokosuitebackup/mokosuitebackup.xml

@@ -7,7 +7,7 @@
  -->
 <extension type="plugin" group="console" method="upgrade">
 	<name>Console - MokoSuiteBackup</name>
-	<version>02.56.11</version>
+	<version>02.58.05</version>
 	<creationDate>2026-06-04</creationDate>
 	<author>Moko Consulting</author>
 	<authorEmail>hello@mokoconsulting.tech</authorEmail>

source/packages/plg_console_mokosuitebackup/src/Command/RunCommand.php

@@ -13,7 +13,7 @@ namespace Joomla\Plugin\Console\MokoSuiteBackup\Command;
 defined('_JEXEC') or die;
 
 use Joomla\CMS\Factory;
-use Joomla\Component\MokoSuiteBackup\Administrator\Engine\BackupEngine;
+use Joomla\Component\MokoSuiteBackup\Administrator\Service\BackupRunner;
 use Joomla\Console\Command\AbstractCommand;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
@@ -40,20 +40,19 @@ class RunCommand extends AbstractCommand
 		$io->title('MokoSuiteBackup — Run Backup');
 		$io->text('Profile ID: ' . $profileId);
 
-		$engineFile = JPATH_ADMINISTRATOR . '/components/com_mokosuitebackup/src/Engine/BackupEngine.php';
+		$runnerFile = JPATH_ADMINISTRATOR . '/components/com_mokosuitebackup/src/Service/BackupRunner.php';
 
-		if (!file_exists($engineFile)) {
+		if (!file_exists($runnerFile)) {
 			$io->error('MokoSuiteBackup component not installed.');
 
 			return 1;
 		}
 
-		if (!class_exists(BackupEngine::class)) {
-			require_once $engineFile;
+		if (!class_exists(BackupRunner::class)) {
+			require_once $runnerFile;
 		}
 
-		$engine = new BackupEngine();
-		$result = $engine->run($profileId, $desc ?: 'CLI backup', 'cli');
+		$result = (new BackupRunner())->run($profileId, $desc ?: 'CLI backup', 'cli');
 
 		if ($result['success']) {
 			$io->success($result['message']);

source/packages/plg_content_mokosuitebackup/mokosuitebackup.xml

@@ -7,7 +7,7 @@
  -->
 <extension type="plugin" group="content" method="upgrade">
 	<name>Content - MokoSuiteBackup</name>
-	<version>02.56.11</version>
+	<version>02.58.05</version>
 	<creationDate>2026-06-04</creationDate>
 	<author>Moko Consulting</author>
 	<authorEmail>hello@mokoconsulting.tech</authorEmail>

source/packages/plg_content_mokosuitebackup/src/Extension/MokoSuiteBackupContent.php

@@ -14,7 +14,7 @@ defined('_JEXEC') or die;
 
 use Joomla\CMS\Factory;
 use Joomla\CMS\Plugin\CMSPlugin;
-use Joomla\Component\MokoSuiteBackup\Administrator\Engine\BackupEngine;
+use Joomla\Component\MokoSuiteBackup\Administrator\Service\BackupRunner;
 use Joomla\Event\Event;
 use Joomla\Event\SubscriberInterface;
 
@@ -61,19 +61,18 @@ final class MokoSuiteBackupContent extends CMSPlugin implements SubscriberInterf
 
 		$session->set('mokosuitebackup.content_last_autobackup', time());
 
-		$engineFile = JPATH_ADMINISTRATOR . '/components/com_mokosuitebackup/src/Engine/BackupEngine.php';
+		$runnerFile = JPATH_ADMINISTRATOR . '/components/com_mokosuitebackup/src/Service/BackupRunner.php';
 
-		if (!file_exists($engineFile)) {
+		if (!file_exists($runnerFile)) {
 			return;
 		}
 
-		if (!class_exists(BackupEngine::class)) {
-			require_once $engineFile;
+		if (!class_exists(BackupRunner::class)) {
+			require_once $runnerFile;
 		}
 
 		try {
-			$engine = new BackupEngine();
-			$engine->run($profileId, $description, 'backend');
+			(new BackupRunner())->run($profileId, $description, 'backend');
 		} catch (\Throwable $e) {
 			// Non-fatal — log and continue with the install/update
 			Factory::getApplication()->enqueueMessage(

source/packages/plg_quickicon_mokosuitebackup/mokosuitebackup.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <extension type="plugin" group="quickicon" method="upgrade">
 	<name>Quick Icon - MokoSuiteBackup</name>
-	<version>02.56.11</version>
+	<version>02.58.05</version>
 	<creationDate>2026-06-02</creationDate>
 	<author>Moko Consulting</author>
 	<authorEmail>hello@mokoconsulting.tech</authorEmail>

source/packages/plg_system_mokosuitebackup/mokosuitebackup.xml

@@ -7,7 +7,7 @@
  -->
 <extension type="plugin" group="system" method="upgrade">
 	<name>System - MokoSuiteBackup</name>
-	<version>02.56.11</version>
+	<version>02.58.05</version>
 	<creationDate>2026-06-02</creationDate>
 	<author>Moko Consulting</author>
 	<authorEmail>hello@mokoconsulting.tech</authorEmail>

source/packages/plg_system_mokosuitebackup/src/Extension/MokoSuiteBackup.php

@@ -15,7 +15,7 @@ defined('_JEXEC') or die;
 use Joomla\CMS\Component\ComponentHelper;
 use Joomla\CMS\Factory;
 use Joomla\CMS\Plugin\CMSPlugin;
-use Joomla\Component\MokoSuiteBackup\Administrator\Engine\BackupEngine;
+use Joomla\Component\MokoSuiteBackup\Administrator\Service\BackupRunner;
 use Joomla\Event\Event;
 use Joomla\Event\SubscriberInterface;
 
@@ -91,8 +91,7 @@ final class MokoSuiteBackup extends CMSPlugin implements SubscriberInterface
 		@ini_set('memory_limit', '512M');
 
 		try {
-			$engine = new BackupEngine();
-			$result = $engine->run($profileId, 'Web cron backup', 'webcron');
+			$result = (new BackupRunner())->run($profileId, 'Web cron backup', 'webcron');
 
 			$this->sendJsonResponse(
 				$result['success'],
@@ -390,14 +389,29 @@ final class MokoSuiteBackup extends CMSPlugin implements SubscriberInterface
 		$profileId = (int) $params->get('default_profile', 1);
 
 		try {
-			$engine = new BackupEngine();
-			$result = $engine->run($profileId, $description, 'preaction');
+			$result = (new BackupRunner())->run($profileId, $description, 'preaction');
+			$app    = Factory::getApplication();
+			$status = $result['status'] ?? (!empty($result['success']) ? 'complete' : 'fail');
 
-			if (!$result['success']) {
-				Factory::getApplication()->enqueueMessage(
-					'MokoSuiteBackup: ' . $description . ' failed — ' . $result['message'],
+			/* Always surface the outcome so the pre-update backup is visible in the
+			   admin — previously only failures produced a message, so a successful
+			   pre-update backup fired no notification at all. */
+			if ($status === 'warning') {
+				$app->enqueueMessage(
+					'MokoSuiteBackup: ' . $description . ' completed with warnings — '
+					. ($result['message'] ?: 'the local archive was created but a remote upload failed; see the backup log.'),
 					'warning'
 				);
+			} elseif ($status === 'fail' || empty($result['success'])) {
+				$app->enqueueMessage(
+					'MokoSuiteBackup: ' . $description . ' failed — ' . ($result['message'] ?: 'unknown error'),
+					'error'
+				);
+			} else {
+				$app->enqueueMessage(
+					'MokoSuiteBackup: ' . $description . ' completed successfully.',
+					'message'
+				);
 			}
 		} catch (\Throwable $e) {
 			error_log('MokoSuiteBackup: ' . $description . ' failed: ' . $e->getMessage());

source/packages/plg_task_mokosuitebackup/mokosuitebackup.xml

@@ -7,7 +7,7 @@
  -->
 <extension type="plugin" group="task" method="upgrade">
 	<name>Task - MokoSuiteBackup</name>
-	<version>02.56.11</version>
+	<version>02.58.05</version>
 	<creationDate>2026-06-02</creationDate>
 	<author>Moko Consulting</author>
 	<authorEmail>hello@mokoconsulting.tech</authorEmail>

source/packages/plg_task_mokosuitebackup/src/Extension/MokoSuiteBackupTask.php

@@ -72,7 +72,7 @@ final class MokoSuiteBackupTask extends CMSPlugin implements SubscriberInterface
 		$profileId = (int) ($params->profile_id ?? 1);
 
 		// Load the backup engine from the component
-		$engineFile = JPATH_ADMINISTRATOR . '/components/com_mokosuitebackup/src/Engine/BackupEngine.php';
+		$engineFile = JPATH_ADMINISTRATOR . '/components/com_mokosuitebackup/src/Service/BackupRunner.php';
 
 		if (!file_exists($engineFile)) {
 			$this->logTask('MokoSuiteBackup component not installed — cannot run backup.');
@@ -81,11 +81,11 @@ final class MokoSuiteBackupTask extends CMSPlugin implements SubscriberInterface
 		}
 
 		// The autoloader should handle this via namespace, but ensure class is available
-		if (!class_exists('\\Joomla\\Component\\MokoSuiteBackup\\Administrator\\Engine\\BackupEngine')) {
+		if (!class_exists('\\Joomla\\Component\\MokoSuiteBackup\\Administrator\\Service\\BackupRunner')) {
 			require_once $engineFile;
 		}
 
-		$engine = new \Joomla\Component\MokoSuiteBackup\Administrator\Engine\BackupEngine();
+		$engine = new \Joomla\Component\MokoSuiteBackup\Administrator\Service\BackupRunner();
 		$result = $engine->run($profileId, 'Scheduled task backup', 'scheduled');
 
 		if ($result['success']) {

source/packages/plg_webservices_mokosuitebackup/mokosuitebackup.xml

@@ -7,7 +7,7 @@
  -->
 <extension type="plugin" group="webservices" method="upgrade">
 	<name>Web Services - MokoSuiteBackup</name>
-	<version>02.56.11</version>
+	<version>02.58.05</version>
 	<creationDate>2026-06-02</creationDate>
 	<author>Moko Consulting</author>
 	<authorEmail>hello@mokoconsulting.tech</authorEmail>

source/pkg_mokosuitebackup.xml

@@ -8,7 +8,7 @@
 <extension type="package" method="upgrade">
 	<name>Package - MokoSuiteBackup</name>
 	<packagename>mokosuitebackup</packagename>
-	<version>02.56.11</version>
+	<version>02.58.05</version>
 	<creationDate>2026-06-02</creationDate>
 	<author>Moko Consulting</author>
 	<authorEmail>hello@mokoconsulting.tech</authorEmail>

source/script.php

@@ -77,6 +77,13 @@ class Pkg_MokoSuiteBackupInstallerScript
 			$this->backupDownloadKey();
 		}
 
+		/* Remove any orphaned mis-registered component BEFORE the component install
+		   recreates its admin menu. The orphan (element com_component-mokosuitebackup)
+		   owns a "Backup" menu with alias "backup"; if it survives, the real
+		   component's menu creation collides ("The alias backup is already being used")
+		   and the whole install aborts. */
+		$this->removeOrphanedComponent();
+
 		return true;
 	}
 
@@ -177,6 +184,10 @@ class Pkg_MokoSuiteBackupInstallerScript
 		   briefly used the "Type - Name" convention. Self-healing on every update. */
 		$this->removeOrphanedComponent();
 
+		/* Drop legacy single-remote storage columns portably (replaces the old
+		   PREPARE/EXECUTE migration that MySQL 8 rejected in Joomla's installer). */
+		$this->dropLegacyRemoteColumns();
+
 		/* Install completion notice (install and update) */
 		$this->installSuccessful();
 
@@ -273,6 +284,54 @@ class Pkg_MokoSuiteBackupInstallerScript
 		}
 	}
 
+	/**
+	 * Drop the 26 legacy single-remote storage columns from the profiles table if
+	 * they are still present. Replaces sql/updates/mysql/02.56.01.sql, whose
+	 * PREPARE/EXECUTE/DEALLOCATE approach is rejected by Joomla's installer on
+	 * MySQL 8 (error 1295) and aborted the whole install. Done here in PHP: gate on
+	 * INFORMATION_SCHEMA, then issue a plain ALTER for only the columns that exist —
+	 * portable across MariaDB and MySQL 8. Idempotent and non-fatal.
+	 *
+	 * @return  void
+	 */
+	private function dropLegacyRemoteColumns(): void
+	{
+		try {
+			$db    = Factory::getDbo();
+			$table = $db->getPrefix() . 'mokosuitebackup_profiles';
+
+			$columns = [
+				'remote_storage',
+				'ftp_host', 'ftp_port', 'ftp_username', 'ftp_password', 'ftp_path', 'ftp_passive', 'ftp_ssl',
+				'sftp_host', 'sftp_port', 'sftp_username', 'sftp_auth_type', 'sftp_password', 'sftp_key_data', 'sftp_passphrase', 'sftp_path',
+				'gdrive_client_id', 'gdrive_client_secret', 'gdrive_refresh_token', 'gdrive_folder_id',
+				's3_endpoint', 's3_region', 's3_access_key', 's3_secret_key', 's3_bucket', 's3_path',
+			];
+
+			// Which legacy columns still exist on this install?
+			$db->setQuery(
+				$db->getQuery(true)
+					->select($db->quoteName('COLUMN_NAME'))
+					->from($db->quoteName('INFORMATION_SCHEMA.COLUMNS'))
+					->where($db->quoteName('TABLE_SCHEMA') . ' = DATABASE()')
+					->where($db->quoteName('TABLE_NAME') . ' = ' . $db->quote($table))
+					->where($db->quoteName('COLUMN_NAME') . ' IN (' . implode(',', array_map([$db, 'quote'], $columns)) . ')')
+			);
+			$present = $db->loadColumn();
+
+			if (empty($present)) {
+				return;
+			}
+
+			$drops = array_map(fn($c) => 'DROP COLUMN ' . $db->quoteName($c), $present);
+			$db->setQuery('ALTER TABLE ' . $db->quoteName($table) . ' ' . implode(', ', $drops));
+			$db->execute();
+		} catch (\Throwable $e) {
+			/* Best-effort — a leftover column is harmless and must never abort the install */
+			Log::add('MokoSuiteBackup legacy-remote-column drop failed: ' . $e->getMessage(), Log::WARNING, 'jerror');
+		}
+	}
+
 	/**
 	 * Recursively delete a directory (version-independent, no Folder dependency).
 	 *
@@ -570,23 +629,7 @@ class Pkg_MokoSuiteBackupInstallerScript
 		try {
 			$db = Factory::getDbo();
 
-			/* Find the parent menu item for our component */
-			$query = $db->getQuery(true)
-				->select([$db->quoteName('id'), $db->quoteName('menutype')])
-				->from($db->quoteName('#__menu'))
-				->where($db->quoteName('client_id') . ' = 1')
-				->where($db->quoteName('level') . ' = 1')
-				->where($db->quoteName('link') . ' LIKE ' . $db->quote('index.php?option=com_mokosuitebackup%'))
-				->setLimit(1);
-			$db->setQuery($query);
-			$parent = $db->loadObject();
-
-			if (!$parent) {
-				error_log('MokoSuiteBackup: ensureSubmenuItems() — parent menu item not found');
-				return;
-			}
-
-			/* Get the component extension_id */
+			/* Component extension_id first — needed to (re)create the parent menu. */
 			$query = $db->getQuery(true)
 				->select($db->quoteName('extension_id'))
 				->from($db->quoteName('#__extensions'))
@@ -601,6 +644,41 @@ class Pkg_MokoSuiteBackupInstallerScript
 				return;
 			}
 
+			/* Find the top-level "Backup" parent menu item for our component */
+			$query = $db->getQuery(true)
+				->select([$db->quoteName('id'), $db->quoteName('menutype')])
+				->from($db->quoteName('#__menu'))
+				->where($db->quoteName('client_id') . ' = 1')
+				->where($db->quoteName('level') . ' = 1')
+				->where($db->quoteName('link') . ' LIKE ' . $db->quote('index.php?option=com_mokosuitebackup%'))
+				->setLimit(1);
+			$db->setQuery($query);
+			$parent = $db->loadObject();
+
+			/* Self-heal: if the top-level menu was deleted (e.g. by a failed install
+			   after the duplicate-component mess), recreate it — otherwise the whole
+			   Backup menu stays gone and dependents (cPanel module, MokoSuiteClient)
+			   can't locate the component. */
+			if (!$parent) {
+				$parent = $this->createTopMenu($componentId);
+
+				if (!$parent) {
+					error_log('MokoSuiteBackup: ensureSubmenuItems() — parent menu missing and could not be created');
+					return;
+				}
+			}
+
+			/* Keep the top-level menu label on the short constant and owned by the
+			   real component. */
+			$db->setQuery(
+				$db->getQuery(true)
+					->update($db->quoteName('#__menu'))
+					->set($db->quoteName('title') . ' = ' . $db->quote('COM_MOKOJOOMBACKUP_SHORT'))
+					->set($db->quoteName('component_id') . ' = ' . (int) $componentId)
+					->where($db->quoteName('id') . ' = ' . (int) $parent->id)
+			);
+			$db->execute();
+
 			foreach ($submenus as $submenu) {
 				/* Check if this submenu item already exists */
 				$query = $db->getQuery(true)
@@ -666,6 +744,59 @@ class Pkg_MokoSuiteBackupInstallerScript
 		}
 	}
 
+	/**
+	 * Create the top-level "Backup" admin menu item for the component when it is
+	 * missing (deleted by a failed install / the duplicate-component fallout).
+	 * Label uses the short constant. Returns a lightweight {id, menutype} object,
+	 * or null on failure.
+	 *
+	 * @param   int  $componentId  Extension id of com_mokosuitebackup
+	 *
+	 * @return  object|null
+	 */
+	private function createTopMenu(int $componentId): ?object
+	{
+		try {
+			$table = Factory::getApplication()
+				->bootComponent('com_menus')
+				->getMVCFactory()
+				->createTable('Menu', 'Administrator');
+
+			$table->menutype     = 'main';
+			$table->title        = 'COM_MOKOJOOMBACKUP_SHORT';
+			$table->alias        = 'backup';
+			$table->link         = 'index.php?option=com_mokosuitebackup';
+			$table->type         = 'component';
+			$table->published    = 1;
+			$table->parent_id    = 1;
+			$table->level        = 1;
+			$table->component_id = $componentId;
+			$table->client_id    = 1;
+			$table->img          = 'class:archive';
+			$table->params       = '{}';
+			$table->language     = '*';
+			$table->access       = 1;
+
+			$table->setLocation(1, 'last-child');
+
+			if (!$table->check() || !$table->store()) {
+				error_log('MokoSuiteBackup: createTopMenu() failed: ' . $table->getError());
+
+				return null;
+			}
+
+			$obj           = new \stdClass();
+			$obj->id       = (int) $table->id;
+			$obj->menutype = 'main';
+
+			return $obj;
+		} catch (\Throwable $e) {
+			error_log('MokoSuiteBackup: createTopMenu() exception: ' . $e->getMessage());
+
+			return null;
+		}
+	}
+
 	private function fixPackageClientId(): void
 	{
 		try {