From e7801501b1125165eb55b0dde1cd9f5fb8c9c42c Mon Sep 17 00:00:00 2001
From: anonymoususer72041
 <247563575+anonymoususer72041@users.noreply.github.com>
Date: Tue, 23 Jun 2026 15:23:08 +0200
Subject: [PATCH 1/5] Route existing installations through maintenance

---
 installwizard.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/installwizard.php b/installwizard.php
index b59c6e9a7..760b37d3a 100755
--- a/installwizard.php
+++ b/installwizard.php
@@ -401,7 +401,7 @@
                                             If you choose to use the existing OpenCATS installation, you can always run<br />
                                             the installer again later and choose a different option.<br />
                                             <br />
-                                            <input style="float: right;" type="button" class="button" value="Next -->" onclick="if (getCheckedValue(document.getElementsByName('installgroupexists')) == 'current') Installpage_populate('a=resumeParsing'); else {document.getElementById('catsUpToDate').style.display='none';showTextBlock('queryResetDatabase');}" />
+                                            <input style="float: right;" type="button" class="button" value="Next -->" onclick="if (getCheckedValue(document.getElementsByName('installgroupexists')) == 'current') Installpage_upgradeExisting(); else {document.getElementById('catsUpToDate').style.display='none';showTextBlock('queryResetDatabase');}" />
                                         </div>
                                         <div id="queryInstallBackup" style="display: none;">
                                             <span style="font-weight:bold;">Loading Data - Restore from Backup</span><br />

From 09bad52d71ebbc1b238eb97f390af622c0d94e12 Mon Sep 17 00:00:00 2001
From: anonymoususer72041
 <247563575+anonymoususer72041@users.noreply.github.com>
Date: Tue, 23 Jun 2026 15:23:22 +0200
Subject: [PATCH 2/5] Add existing-installation maintenance flow

---
 js/install.js | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/js/install.js b/js/install.js
index 1cbd2cf02..54546e3fa 100755
--- a/js/install.js
+++ b/js/install.js
@@ -28,6 +28,7 @@
 
 var response;
 var maxSteps;
+var installMaintNextAction = "a=reindexResumes";
 
 
 function setActiveStep(step)
@@ -121,7 +122,8 @@ function Installpage_maint()
 
         if (response.indexOf("setProgressUpdating") == -1)
  		{	
-	        Installpage_populate("a=reindexResumes");
+	        Installpage_populate(installMaintNextAction);
+	        installMaintNextAction = "a=reindexResumes";
         }
         else
         {
@@ -141,6 +143,18 @@ function Installpage_maint()
     );
 }
 
+function Installpage_upgradeExisting()
+{
+    Installpage_populate("a=upgradeExisting");
+}
+
+function Installpage_upgradeExistingMaint()
+{
+    /* Existing installations must run schema maintenance before later installer questions. */
+    installMaintNextAction = "a=upgradeExistingMaintComplete";
+    Installpage_maint();
+}
+
 function Installpage_append(postData, message)
 {
     var htmlObjectID = "subFormBlock";

From e4341b0ed42b4cdfe77c1d7b410bb9c1830b09c4 Mon Sep 17 00:00:00 2001
From: anonymoususer72041
 <247563575+anonymoususer72041@users.noreply.github.com>
Date: Tue, 23 Jun 2026 15:23:45 +0200
Subject: [PATCH 3/5] Resume installer questions after existing upgrade
 migrations

---
 modules/install/ajax/ui.php | 51 +++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/modules/install/ajax/ui.php b/modules/install/ajax/ui.php
index cc601d92f..737b03fbd 100755
--- a/modules/install/ajax/ui.php
+++ b/modules/install/ajax/ui.php
@@ -679,6 +679,12 @@
         break;
 
     case 'resetDatabase':
+        @session_name(CATS_SESSION_NAME);
+        session_start();
+
+        unset($_SESSION['existingUpgradeMaintStarted']);
+        unset($_SESSION['existingUpgradeMaintComplete']);
+
         MySQLConnect();
 
         foreach ($tables as $table => $data)
@@ -971,6 +977,15 @@
         @session_name(CATS_SESSION_NAME);
         session_start();
 
+        if (isset($_SESSION['existingUpgradeMaintComplete']))
+        {
+            unset($_SESSION['existingUpgradeMaintStarted']);
+            unset($_SESSION['existingUpgradeMaintComplete']);
+
+            echo '<script type="text/javascript">Installpage_populate(\'a=reindexResumes\');</script>';
+            break;
+        }
+
         if (isset($_SESSION['CATS']))
         {
             unset($_SESSION['CATS']);
@@ -987,6 +1002,42 @@
               </script>';
         break;
 
+    case 'upgradeExisting':
+        @session_name(CATS_SESSION_NAME);
+        session_start();
+
+        $_SESSION['existingUpgradeMaintStarted'] = true;
+        unset($_SESSION['existingUpgradeMaintComplete']);
+
+        if (isset($_SESSION['CATS']))
+        {
+            unset($_SESSION['CATS']);
+        }
+
+        if (isset($_SESSION['modules']))
+        {
+            unset($_SESSION['modules']);
+        }
+
+        echo '<script type="text/javascript">
+                  showTextBlock(\'installingComponentsMaint\');
+                  setTimeout("Installpage_upgradeExistingMaint();", 2000);
+              </script>';
+        break;
+
+    case 'upgradeExistingMaintComplete':
+        @session_name(CATS_SESSION_NAME);
+        session_start();
+
+        if (isset($_SESSION['existingUpgradeMaintStarted']))
+        {
+            $_SESSION['existingUpgradeMaintComplete'] = true;
+            unset($_SESSION['existingUpgradeMaintStarted']);
+        }
+
+        echo '<script type="text/javascript">Installpage_populate(\'a=resumeParsing\');</script>';
+        break;
+
     case 'reindexResumes':
         echo '<script type="text/javascript">
                   showTextBlock(\'installingComponentsMaintResume\');

From f5a6e6e1e4cb2ee293bdd5cbcd7fe4381a03062b Mon Sep 17 00:00:00 2001
From: anonymoususer72041
 <247563575+anonymoususer72041@users.noreply.github.com>
Date: Wed, 24 Jun 2026 13:40:24 +0200
Subject: [PATCH 4/5] Guard installer maintenance continuation

---
 js/install.js | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/js/install.js b/js/install.js
index 54546e3fa..035e819de 100755
--- a/js/install.js
+++ b/js/install.js
@@ -121,9 +121,12 @@ function Installpage_maint()
         response = http.responseText;
 
         if (response.indexOf("setProgressUpdating") == -1)
- 		{	
-	        Installpage_populate(installMaintNextAction);
-	        installMaintNextAction = "a=reindexResumes";
+ 		{
+	        if (http.status == 200)
+	        {
+	            Installpage_populate(installMaintNextAction);
+	            installMaintNextAction = "a=reindexResumes";
+	        }
         }
         else
         {

From 8c8c69d9923f79b78fd5cb70539e90b2c66ae540 Mon Sep 17 00:00:00 2001
From: anonymoususer72041
 <247563575+anonymoususer72041@users.noreply.github.com>
Date: Wed, 24 Jun 2026 13:46:14 +0200
Subject: [PATCH 5/5] Cover existing-installation maintenance flow

---
 .../UnitTests/ExistingInstallFlowTest.php     | 274 ++++++++++++++++++
 1 file changed, 274 insertions(+)
 create mode 100644 src/OpenCATS/Tests/UnitTests/ExistingInstallFlowTest.php

diff --git a/src/OpenCATS/Tests/UnitTests/ExistingInstallFlowTest.php b/src/OpenCATS/Tests/UnitTests/ExistingInstallFlowTest.php
new file mode 100644
index 000000000..8b24fd73a
--- /dev/null
+++ b/src/OpenCATS/Tests/UnitTests/ExistingInstallFlowTest.php
@@ -0,0 +1,274 @@
+<?php
+use PHPUnit\Framework\TestCase;
+
+class ExistingInstallFlowTest extends TestCase
+{
+    private $uiSource;
+    private $jsSource;
+
+    protected function setUp(): void
+    {
+        $root = dirname(__DIR__, 4);
+
+        $uiPath = $root . '/modules/install/ajax/ui.php';
+        $jsPath = $root . '/js/install.js';
+
+        $this->assertFileExists($uiPath);
+        $this->assertFileExists($jsPath);
+
+        $this->uiSource = file_get_contents($uiPath);
+        $this->jsSource = file_get_contents($jsPath);
+    }
+
+    public function testUpgradeExistingActionSetsSessionFlagAndCallsExistingMaint()
+    {
+        $block = $this->extractSwitchCase($this->uiSource, 'upgradeExisting');
+        $this->assertNotEmpty($block, 'case upgradeExisting must exist in ui.php');
+
+        $this->assertStringContains(
+            $block,
+            "['existingUpgradeMaintStarted']",
+            'upgradeExisting must set the existingUpgradeMaintStarted session flag'
+        );
+
+        $this->assertStringContains(
+            $block,
+            "unset(\$_SESSION['existingUpgradeMaintComplete'])",
+            'upgradeExisting must clear the existingUpgradeMaintComplete flag'
+        );
+
+        $this->assertMatches(
+            '/Installpage_upgradeExistingMaint\s*\(\s*\)/',
+            $block,
+            'upgradeExisting must invoke Installpage_upgradeExistingMaint()'
+        );
+    }
+
+    public function testJsUpgradeExistingMaintSetsNextActionThenCallsMaint()
+    {
+        $this->assertMatches(
+            '/function\s+Installpage_upgradeExistingMaint\s*\(/',
+            $this->jsSource,
+            'Installpage_upgradeExistingMaint() must be defined in install.js'
+        );
+
+        $fnBody = $this->extractJsFunction($this->jsSource, 'Installpage_upgradeExistingMaint');
+        $this->assertNotEmpty($fnBody, 'Installpage_upgradeExistingMaint function body must be extractable');
+
+        $this->assertMatches(
+            '/installMaintNextAction\s*=\s*["\']a=upgradeExistingMaintComplete["\']/',
+            $fnBody,
+            'Installpage_upgradeExistingMaint must set installMaintNextAction to upgradeExistingMaintComplete'
+        );
+
+        $this->assertMatches(
+            '/Installpage_maint\s*\(\s*\)/',
+            $fnBody,
+            'Installpage_upgradeExistingMaint must call Installpage_maint()'
+        );
+
+        $setPos = $this->firstMatchPosition(
+            '/installMaintNextAction\s*=/',
+            $fnBody
+        );
+        $callPos = $this->firstMatchPosition(
+            '/Installpage_maint\s*\(/',
+            $fnBody
+        );
+        $this->assertNotNull($setPos);
+        $this->assertNotNull($callPos);
+        $this->assertGreaterThan(
+            $setPos,
+            $callPos,
+            'installMaintNextAction must be set before Installpage_maint() is called'
+        );
+    }
+
+    public function testUpgradeExistingMaintCompleteResumesInstaller()
+    {
+        $block = $this->extractSwitchCase($this->uiSource, 'upgradeExistingMaintComplete');
+        $this->assertNotEmpty($block, 'case upgradeExistingMaintComplete must exist in ui.php');
+
+        $this->assertStringContains(
+            $block,
+            "['existingUpgradeMaintComplete']",
+            'upgradeExistingMaintComplete must reference the existingUpgradeMaintComplete session key'
+        );
+
+        $this->assertMatches(
+            '/a=resumeParsing/',
+            $block,
+            'upgradeExistingMaintComplete must redirect to a=resumeParsing'
+        );
+    }
+
+    public function testMaintActionSkipsSecondRunAfterExistingUpgrade()
+    {
+        $block = $this->extractSwitchCase($this->uiSource, 'maint');
+        $this->assertNotEmpty($block, 'case maint must exist in ui.php');
+
+        $this->assertStringContains(
+            $block,
+            "['existingUpgradeMaintComplete']",
+            'maint must check for the existingUpgradeMaintComplete session flag'
+        );
+
+        $this->assertMatches(
+            '/unset\s*\(\s*\$_SESSION\s*\[\s*[\'"]existingUpgradeMaintStarted[\'"]\s*\]\s*\)/',
+            $block,
+            'maint must unset existingUpgradeMaintStarted'
+        );
+
+        $this->assertMatches(
+            '/unset\s*\(\s*\$_SESSION\s*\[\s*[\'"]existingUpgradeMaintComplete[\'"]\s*\]\s*\)/',
+            $block,
+            'maint must unset existingUpgradeMaintComplete'
+        );
+
+        $this->assertMatches(
+            '/a=reindexResumes/',
+            $block,
+            'maint must continue to a=reindexResumes when skipping existing-upgrade maintenance'
+        );
+
+        $normalMaintPattern = '/Installpage_maint\s*\(\s*\)/';
+        $this->assertMatches(
+            $normalMaintPattern,
+            $block,
+            'maint must still contain the normal Installpage_maint() call for non-existing-upgrade paths'
+        );
+    }
+
+    public function testMaintContinuationRequiresSuccessfulHttpStatus()
+    {
+        $fnBody = $this->extractJsFunction($this->jsSource, 'Installpage_maint');
+        $this->assertNotEmpty($fnBody, 'Installpage_maint function body must be extractable');
+
+        $statusPos = $this->firstMatchPosition('/http\\.status\\s*==\\s*200/', $fnBody);
+        $populatePos = $this->firstMatchPosition('/Installpage_populate\\s*\\(\\s*installMaintNextAction\\s*\\)/', $fnBody);
+        $resetPos = $this->firstMatchPosition('/installMaintNextAction\\s*=\\s*[\'"]a=reindexResumes[\'"]\\s*;/', $fnBody);
+
+        $this->assertNotNull($statusPos, 'Installpage_maint must check for a successful HTTP status before continuing');
+        $this->assertNotNull($populatePos, 'Installpage_maint must continue using installMaintNextAction after successful maintenance');
+        $this->assertNotNull($resetPos, 'Installpage_maint must reset installMaintNextAction after using it');
+
+        $this->assertGreaterThan(
+            $statusPos,
+            $populatePos,
+            'Installpage_maint must check the HTTP status before using installMaintNextAction'
+        );
+
+        $this->assertGreaterThan(
+            $populatePos,
+            $resetPos,
+            'Installpage_maint must reset installMaintNextAction after using it'
+        );
+    }
+
+    public function testResetDatabaseClearsExistingUpgradeFlags()
+    {
+        $block = $this->extractSwitchCase($this->uiSource, 'resetDatabase');
+        $this->assertNotEmpty($block, 'case resetDatabase must exist in ui.php');
+
+        $this->assertMatches(
+            '/unset\s*\(\s*\$_SESSION\s*\[\s*[\'"]existingUpgradeMaintStarted[\'"]\s*\]\s*\)/',
+            $block,
+            'resetDatabase must clear existingUpgradeMaintStarted'
+        );
+
+        $this->assertMatches(
+            '/unset\s*\(\s*\$_SESSION\s*\[\s*[\'"]existingUpgradeMaintComplete[\'"]\s*\]\s*\)/',
+            $block,
+            'resetDatabase must clear existingUpgradeMaintComplete'
+        );
+    }
+
+    // ------------------------------------------------------------------
+    // Helpers
+    // ------------------------------------------------------------------
+
+    private function extractSwitchCase(string $source, string $caseName): string
+    {
+        $pattern = '/case\s+[\'"]' . preg_quote($caseName, '/') . '[\'"]\s*:/';
+        if (!preg_match($pattern, $source, $m, PREG_OFFSET_CAPTURE)) {
+            return '';
+        }
+
+        $start = $m[0][1];
+        $bodyStart = $start + strlen($m[0][0]);
+        $len = strlen($source);
+        $depth = 0;
+
+        for ($i = $bodyStart; $i < $len; $i++) {
+            $ch = $source[$i];
+
+            if ($ch === '{') {
+                $depth++;
+            } elseif ($ch === '}') {
+                $depth--;
+                if ($depth < 0) {
+                    return substr($source, $start, $i - $start);
+                }
+            }
+
+            if ($depth === 0 && ($ch === 'c' || $ch === 'd')) {
+                if (preg_match('/^(?:case\s+[\'"]|default\s*:)/', substr($source, $i))) {
+                    return substr($source, $start, $i - $start);
+                }
+            }
+        }
+
+        return substr($source, $start);
+    }
+
+    private function extractJsFunction(string $source, string $funcName): string
+    {
+        $pattern = '/function\s+' . preg_quote($funcName, '/') . '\s*\([^)]*\)\s*\{/';
+        if (!preg_match($pattern, $source, $m, PREG_OFFSET_CAPTURE)) {
+            return '';
+        }
+
+        $braceStart = strpos($source, '{', $m[0][1]);
+        $depth = 0;
+        $i = $braceStart;
+        $len = strlen($source);
+
+        while ($i < $len) {
+            if ($source[$i] === '{') {
+                $depth++;
+            } elseif ($source[$i] === '}') {
+                $depth--;
+                if ($depth === 0) {
+                    return substr($source, $braceStart, $i - $braceStart + 1);
+                }
+            }
+            $i++;
+        }
+
+        return '';
+    }
+
+    private function firstMatchPosition(string $pattern, string $subject): ?int
+    {
+        if (preg_match($pattern, $subject, $m, PREG_OFFSET_CAPTURE)) {
+            return $m[0][1];
+        }
+        return null;
+    }
+
+    private function assertStringContains(string $haystack, string $needle, string $message = ''): void
+    {
+        $this->assertTrue(
+            strpos($haystack, $needle) !== false,
+            $message ?: "Failed asserting that string contains '{$needle}'"
+        );
+    }
+
+    private function assertMatches(string $pattern, string $string, string $message = ''): void
+    {
+        $this->assertTrue(
+            (bool) preg_match($pattern, $string),
+            $message ?: "Failed asserting that string matches pattern {$pattern}"
+        );
+    }
+}