Merge pull request 'release: promote dev → main (installer + admin-menu + UI fixes)' (#224) from dev into main

.mokogitea/workflows/issue-branch.yml

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

CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+### 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

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.57.00
+VERSION: 02.57.13
 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.57.00</version>
+	<version>02.57.13</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.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/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.57.00</version>
+	<version>02.57.13</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.57.00</version>
+	<version>02.57.13</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.57.00</version>
+	<version>02.57.13</version>
 	<creationDate>2026-06-04</creationDate>
 	<author>Moko Consulting</author>
 	<authorEmail>hello@mokoconsulting.tech</authorEmail>

source/packages/plg_content_mokosuitebackup/mokosuitebackup.xml

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

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.57.00</version>
+	<version>02.57.13</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.57.00</version>
+	<version>02.57.13</version>
 	<creationDate>2026-06-02</creationDate>
 	<author>Moko Consulting</author>
 	<authorEmail>hello@mokoconsulting.tech</authorEmail>

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

@@ -390,12 +390,28 @@ final class MokoSuiteBackup extends CMSPlugin implements SubscriberInterface
 
 		try {
 			$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.57.00</version>
+	<version>02.57.13</version>
 	<creationDate>2026-06-02</creationDate>
 	<author>Moko Consulting</author>
 	<authorEmail>hello@mokoconsulting.tech</authorEmail>

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.57.00</version>
+	<version>02.57.13</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.57.00</version>
+	<version>02.57.13</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 {