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

Non-workflow docs/config only (CLAUDE.md, README, branch-protection, ISSUE_TEMPLATE/config.yml,
ci-issue-reporter). Workflow files, manifest schema, and Makefile install paths left for the
forge-rebrand gate. Authored-by: Moko Consulting

.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.57.03
 # BRIEF: Auto-create feature branch when an issue is opened
 
 name: "Universal: Issue Branch"

CHANGELOG.md

@@ -1,6 +1,15 @@
 # Changelog
+
 ## [Unreleased]
 
+## [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.57.03
 BRIEF: Security vulnerability reporting and handling policy
 -->
 

source/packages/com_mokosuitebackup/mokosuitebackup.xml

@@ -17,7 +17,7 @@
 		display label there.
 	-->
 	<name>MokoSuiteBackup</name>
-	<version>02.56.11</version>
+	<version>02.57.03</version>
 	<creationDate>2026-06-02</creationDate>
 	<author>Moko Consulting</author>
 	<authorEmail>hello@mokoconsulting.tech</authorEmail>

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.03.sql

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

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/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.57.03</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.57.03</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.57.03</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.57.03</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.57.03</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.57.03</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,8 +389,7 @@ 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');
 
 			if (!$result['success']) {
 				Factory::getApplication()->enqueueMessage(

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