From 68829b8439f3fa8a47456bbf8edfb02013eae886 Mon Sep 17 00:00:00 2001
From: Mo Mesgin <mmesgin@Mos-M2-MacBook-Pro.local>
Date: Mon, 13 Jan 2025 16:04:42 -0800
Subject: [PATCH 1/9] restrict installed apps upgrade

---
 shell/assets/translations/en-us.yaml          |  2 +
 shell/list/catalog.cattle.io.app.vue          | 25 +++++-
 shell/mixins/__tests__/chart.test.ts          |  9 +-
 shell/mixins/chart.js                         |  4 +-
 .../__tests__/catalog.cattle.io.app.test.ts   | 88 +++++++++++++++++++
 shell/models/catalog.cattle.io.app.js         | 85 +++++++++++-------
 .../pages/c/_cluster/explorer/tools/index.vue |  4 +-
 shell/store/catalog.js                        | 21 +++--
 8 files changed, 188 insertions(+), 50 deletions(-)
 create mode 100644 shell/models/__tests__/catalog.cattle.io.app.test.ts

diff --git a/shell/assets/translations/en-us.yaml b/shell/assets/translations/en-us.yaml
index 758c7a19d37..603f216ab2a 100644
--- a/shell/assets/translations/en-us.yaml
+++ b/shell/assets/translations/en-us.yaml
@@ -903,6 +903,8 @@ catalog:
         label: Resources
         busy: The related resources will appear when {app} is fully installed.
       values: Values YAML
+    upgrade:
+      uncertainUpgradeWarningTooltip: Unable to identify source chart and repository for this application in order to determine if an upgrade is available
   chart:
     registry:
       label: Container Registry
diff --git a/shell/list/catalog.cattle.io.app.vue b/shell/list/catalog.cattle.io.app.vue
index 05aaa0c4606..dab3e3e3983 100644
--- a/shell/list/catalog.cattle.io.app.vue
+++ b/shell/list/catalog.cattle.io.app.vue
@@ -1,5 +1,6 @@
 <script>
 import PaginatedResourceTable from '@shell/components/PaginatedResourceTable';
+import { APP_UPGRADE_STATUS } from '@shell/store/catalog';
 
 export default {
   name:       'ListApps',
@@ -21,6 +22,10 @@ export default {
     }
   },
 
+  data() {
+    return { APP_UPGRADE_STATUS };
+  },
+
   async fetch() {
     await this.$store.dispatch('catalog/load');
   },
@@ -36,18 +41,30 @@ export default {
   >
     <template #cell:upgrade="{row}">
       <span
-        v-if="row.upgradeAvailable"
+        v-if="row.upgradeAvailable === APP_UPGRADE_STATUS.SINGLE_UPGRADE"
         class="badge-state bg-warning hand"
-        @click="row.goToUpgrade(row.upgradeAvailable)"
+        @click="row.goToUpgrade(row.upgradeAvailableVersion)"
       >
-        {{ row.upgradeAvailable }}
+        {{ row.upgradeAvailableVersion }}
         <i class="icon icon-upload" />
       </span>
       <span
-        v-else-if="row.upgradeAvailable === false"
+        v-else-if="row.upgradeAvailable === APP_UPGRADE_STATUS.NOT_APPLICABLE"
         v-t="'catalog.app.managed'"
         class="text-muted"
       />
+      <span
+        v-else-if="row.upgradeAvailable === APP_UPGRADE_STATUS.NO_UPGRADE"
+        class="text-muted"
+      />
+      <span
+        v-else-if="row.upgradeAvailable === APP_UPGRADE_STATUS.MULTIPLE_UPGRADES"
+      >
+        <i
+          v-clean-tooltip="t('catalog.app.upgrade.uncertainUpgradeWarningTooltip')"
+          class="icon icon-info"
+        />
+      </span>
     </template>
   </PaginatedResourceTable>
 </template>
diff --git a/shell/mixins/__tests__/chart.test.ts b/shell/mixins/__tests__/chart.test.ts
index ca2ac4844ce..0e0f4761bfd 100644
--- a/shell/mixins/__tests__/chart.test.ts
+++ b/shell/mixins/__tests__/chart.test.ts
@@ -1,6 +1,7 @@
 import ChartMixin from '@shell/mixins/chart';
 import { OPA_GATE_KEEPER_ID } from '@shell/pages/c/_cluster/gatekeeper/index.vue';
 import { mount } from '@vue/test-utils';
+import { APP_UPGRADE_STATUS } from '@shell/store/catalog';
 
 describe('chartMixin', () => {
   const testCases = {
@@ -10,10 +11,10 @@ describe('chartMixin', () => {
       ['any_other_id', 0]
     ],
     managedApps: [
-      [false, false, 0],
-      [true, null, 0],
-      [true, true, 0],
-      [true, false, 1],
+      [false, APP_UPGRADE_STATUS.NOT_APPLICABLE, 0],
+      [true, APP_UPGRADE_STATUS.NO_UPGRADE, 0],
+      [true, 'some-version', 0],
+      [true, APP_UPGRADE_STATUS.NOT_APPLICABLE, 1],
     ],
   };
 
diff --git a/shell/mixins/chart.js b/shell/mixins/chart.js
index 27ffbd7710f..c9dc554dd9b 100644
--- a/shell/mixins/chart.js
+++ b/shell/mixins/chart.js
@@ -14,7 +14,7 @@ import { formatSi, parseSi } from '@shell/utils/units';
 import { CAPI, CATALOG } from '@shell/config/types';
 import { isPrerelease } from '@shell/utils/version';
 import difference from 'lodash/difference';
-import { LINUX } from '@shell/store/catalog';
+import { LINUX, APP_UPGRADE_STATUS } from '@shell/store/catalog';
 import { clone } from '@shell/utils/object';
 import { merge } from 'lodash';
 
@@ -181,7 +181,7 @@ export default {
         warnings.unshift(this.t('gatekeeperIndex.deprecated', {}, true));
       }
 
-      if (this.existing && this.existing.upgradeAvailable === false) {
+      if (this.existing && this.existing.upgradeAvailable === APP_UPGRADE_STATUS.NOT_APPLICABLE) {
         warnings.unshift(this.t('catalog.install.warning.managed', {
           name:    this.existing.name,
           version: this.chart ? this.query.versionName : null
diff --git a/shell/models/__tests__/catalog.cattle.io.app.test.ts b/shell/models/__tests__/catalog.cattle.io.app.test.ts
new file mode 100644
index 00000000000..61c6d74c13b
--- /dev/null
+++ b/shell/models/__tests__/catalog.cattle.io.app.test.ts
@@ -0,0 +1,88 @@
+import CatalogApp from '@shell/models/catalog.cattle.io.app';
+import { APP_UPGRADE_STATUS } from '@shell/store/catalog';
+
+const latestVersion = '1.16.2';
+const secondLatestVersion = '1.16.1';
+const chartName = 'cert-manager';
+
+const appCo = {
+  repoName: 'appCo',
+  home:     'https://apps.rancher.io/applications/cert-manager'
+};
+
+const certManagerFromCli = { home: 'https://github.com/jetstack/cert-manager' };
+
+const certManagerOfficial = {
+  repoName: 'certManagerOfficial',
+  home:     'https://cert-manager.io'
+};
+
+// cert-manager chart from application collection OCI repo
+const matchingChart1 = {
+  name:     chartName,
+  repoName: appCo.repoName,
+  versions: [{
+    version:     latestVersion,
+    home:        appCo.home,
+    repoName:    appCo.repoName,
+    annotations: {}
+  }]
+};
+
+// cert-manager chart from its official helm repo 'https://cert-manager.io' added to Rancher UI repositories
+const matchingChart2 = {
+  name:     chartName,
+  repoName: certManagerOfficial.repoName,
+  versions: [{
+    version:     latestVersion,
+    home:        certManagerOfficial.home,
+    repoName:    certManagerOfficial.repoName,
+    annotations: {},
+  }]
+};
+
+const installedChartFromCli = {
+  metadata: {
+    name:    chartName,
+    home:    certManagerFromCli.home,
+    version: secondLatestVersion
+  }
+};
+
+const installedChartFromRancherUI = {
+  metadata: {
+    name:    chartName,
+    home:    certManagerOfficial.home,
+    version: secondLatestVersion
+  }
+};
+
+// // home is not set
+// const installedCustomChartFromRancherUI = {
+//   metadata: {
+//     name:    chartName,
+//     version: secondLatestVersion
+//   }
+// };
+
+describe('class CatalogApp', () => {
+  describe('upgradeAvailable', () => {
+    // TODO: more test cases
+    const testCases = [
+      [installedChartFromCli, [matchingChart1, matchingChart2], APP_UPGRADE_STATUS.NO_UPGRADE],
+      [installedChartFromRancherUI, [matchingChart1, matchingChart2], APP_UPGRADE_STATUS.SINGLE_UPGRADE]
+    ];
+
+    it.each(testCases)('should return the correct upgrade status', (installedChart: Object, matchingCharts: any, expected: any) => {
+      const catalogApp = new CatalogApp({ spec: { chart: installedChart } }, {
+        rootGetters: {
+          'catalog/chart': () => matchingCharts,
+          currentCluster:  { workerOSs: ['linux'] },
+          'prefs/get':     () => false
+        }
+      });
+
+      expect(catalogApp.upgradeAvailable).toBe(expected);
+    });
+  });
+});
diff --git a/shell/models/catalog.cattle.io.app.js b/shell/models/catalog.cattle.io.app.js
index e2de968d6f1..0b9ce122f14 100644
--- a/shell/models/catalog.cattle.io.app.js
+++ b/shell/models/catalog.cattle.io.app.js
@@ -9,7 +9,7 @@ import { SHOW_PRE_RELEASE } from '@shell/store/prefs';
 import { set } from '@shell/utils/object';
 
 import SteveModel from '@shell/plugins/steve/steve-class';
-import { compatibleVersionsFor } from '@shell/store/catalog';
+import { compatibleVersionsFor, APP_UPGRADE_STATUS } from '@shell/store/catalog';
 
 export default class CatalogApp extends SteveModel {
   showMasthead(mode) {
@@ -22,6 +22,8 @@ export default class CatalogApp extends SteveModel {
     set(this, 'skipCRDs', false);
     set(this, 'timeout', 300);
     set(this, 'wait', true);
+    set(this, 'foundMultipleUpgradeMatches', false);
+    set(this, 'upgradeAvailableVersion', '');
   }
 
   get _availableActions() {
@@ -40,7 +42,7 @@ export default class CatalogApp extends SteveModel {
   }
 
   get warnDeletionMessage() {
-    if (this.upgradeAvailable === false) {
+    if (this.upgradeAvailable === APP_UPGRADE_STATUS.NOT_APPLICABLE) {
       return this.t('catalog.delete.warning.managed', { name: this.name });
     }
 
@@ -56,16 +58,33 @@ export default class CatalogApp extends SteveModel {
 
     const chartName = chart.metadata?.name;
     const repoName = chart.metadata?.annotations?.[CATALOG_ANNOTATIONS.SOURCE_REPO_NAME] || this.metadata?.labels?.[CATALOG_ANNOTATIONS.CLUSTER_REPO_NAME];
-    const preferRepoType = chart.metadata?.annotations?.[CATALOG_ANNOTATIONS.SOURCE_REPO_TYPE] || 'cluster';
 
-    const match = this.$rootGetters['catalog/chart']({
+    const matchingCharts = this.$rootGetters['catalog/chart']({
       chartName,
       repoName,
-      preferRepoType,
-      includeHidden
-    });
+      includeHidden,
+      multiple: true
+    }) || [];
+
+    if (matchingCharts.length === 0) {
+      return;
+    }
+
+    // narrowing down the matches by checking more properties, like home url
+    // we let a match pass if home url is not set since we support custom charts and they might not follow the best practices to include the home url
+    const thisHome = chart?.metadata?.home;
+    const bestMatches = matchingCharts.filter((m) => !thisHome || m.versions[0]?.home === thisHome);
+
+    if (bestMatches.length === 0) {
+      return;
+    }
+
+    if (bestMatches.length === 1) {
+      return bestMatches[0];
+    }
 
-    return match;
+    // found multiple matches but couldn't choose one unique match
+    this.foundMultipleUpgradeMatches = true;
   }
 
   get currentVersion() {
@@ -73,28 +92,33 @@ export default class CatalogApp extends SteveModel {
   }
 
   get upgradeAvailable() {
-    // false = does not apply (managed by fleet)
-    // null = no upgrade found
-    // object = version available to upgrade to
+    // one the following statuses gets returned:
+    // NOT_APPLICABLE - managed by fleet
+    // NO_UPGRADE - no upgrade found
+    // SINGLE_UPGRADE - a version available to upgrade to
+    // MULTIPLE_UPGRADES - more than one match found
 
     if (
       this.spec?.chart?.metadata?.annotations?.[CATALOG_ANNOTATIONS.MANAGED] ||
       this.spec?.chart?.metadata?.annotations?.[FLEET.BUNDLE_ID]
     ) {
       // Things managed by fleet shouldn't show upgrade available even if there might be.
-      return false;
+      return APP_UPGRADE_STATUS.NOT_APPLICABLE;
     }
     const chart = this.matchingChart(false);
 
+    if (this.foundMultipleUpgradeMatches) {
+      return APP_UPGRADE_STATUS.MULTIPLE_UPGRADES;
+    }
+
     if ( !chart ) {
-      return null;
+      return APP_UPGRADE_STATUS.NO_UPGRADE;
     }
 
     const workerOSs = this.$rootGetters['currentCluster'].workerOSs;
 
     const showPreRelease = this.$rootGetters['prefs/get'](SHOW_PRE_RELEASE);
 
-    const thisVersion = this.spec?.chart?.metadata?.version;
     let versions = chart.versions;
 
     if (!showPreRelease) {
@@ -106,45 +130,45 @@ export default class CatalogApp extends SteveModel {
     const newestChart = versions?.[0];
     const newestVersion = newestChart?.version;
 
-    if ( !thisVersion || !newestVersion ) {
-      return null;
+    if ( !this.currentVersion || !newestVersion ) {
+      return APP_UPGRADE_STATUS.NO_UPGRADE;
     }
 
-    if ( compare(thisVersion, newestVersion) < 0 ) {
-      return cleanupVersion(newestVersion);
+    if ( compare(this.currentVersion, newestVersion) < 0 ) {
+      // set the available upgrade version to be used in other places
+      this.upgradeAvailableVersion = cleanupVersion(newestVersion);
+
+      return APP_UPGRADE_STATUS.SINGLE_UPGRADE;
     }
 
-    return null;
+    return APP_UPGRADE_STATUS.NO_UPGRADE;
   }
 
   get upgradeAvailableSort() {
-    const version = this.upgradeAvailable;
-
-    if ( !version ) {
-      return '~'; // Tilde sorts after all numbers and letters
+    if (this.upgradeAvailable === APP_UPGRADE_STATUS.SINGLE_UPGRADE) {
+      return sortable(this.upgradeAvailableVersion);
     }
 
-    return sortable(version);
+    return '~'; // Tilde sorts after all numbers and letters
   }
 
   get currentVersionCompatible() {
     const workerOSs = this.$rootGetters['currentCluster'].workerOSs;
 
     const chart = this.matchingChart(false);
-    const thisVersion = this.spec?.chart?.metadata?.version;
 
     if (!chart) {
       return true;
     }
 
-    const versionInChart = chart.versions.find((version) => version.version === thisVersion);
+    const versionInChart = chart.versions.find((version) => version.version === this.currentVersion);
 
     if (!versionInChart) {
       return true;
     }
     const compatibleVersions = compatibleVersionsFor(chart, workerOSs, true) || [];
 
-    const thisVersionCompatible = !!compatibleVersions.find((version) => version.version === thisVersion);
+    const thisVersionCompatible = !!compatibleVersions.find((version) => version.version === this.currentVersion);
 
     return thisVersionCompatible;
   }
@@ -153,7 +177,7 @@ export default class CatalogApp extends SteveModel {
     if (this.currentVersionCompatible) {
       return null;
     }
-    if (this.upgradeAvailable) {
+    if (this.upgradeAvailableVersion) {
       return this.t('catalog.os.versionIncompatible');
     }
 
@@ -162,11 +186,10 @@ export default class CatalogApp extends SteveModel {
 
   goToUpgrade(forceVersion, fromTools) {
     const match = this.matchingChart(true);
-    const versionName = this.spec?.chart?.metadata?.version;
     const query = {
       [NAMESPACE]: this.metadata.namespace,
       [NAME]:      this.metadata.name,
-      [VERSION]:   forceVersion || versionName,
+      [VERSION]:   forceVersion || this.currentVersion,
     };
 
     if ( match ) {
@@ -221,7 +244,7 @@ export default class CatalogApp extends SteveModel {
   }
 
   get versionDisplay() {
-    return cleanupVersion(this.spec?.chart?.metadata?.version);
+    return cleanupVersion(this.currentVersion);
   }
 
   get versionSort() {
diff --git a/shell/pages/c/_cluster/explorer/tools/index.vue b/shell/pages/c/_cluster/explorer/tools/index.vue
index d01c18bbbc6..0c02f6c3867 100644
--- a/shell/pages/c/_cluster/explorer/tools/index.vue
+++ b/shell/pages/c/_cluster/explorer/tools/index.vue
@@ -326,8 +326,8 @@ export default {
             >{{ t('catalog.charts.deploysOnWindows') }}</label>
           </div>
           <div class="version">
-            <template v-if="opt.app && opt.app.upgradeAvailable">
-              v{{ opt.app.currentVersion }} <b><i class="icon icon-chevron-right" /> v{{ opt.app.upgradeAvailable }}</b>
+            <template v-if="opt.app && opt.app.upgradeAvailableVersion">
+              v{{ opt.app.currentVersion }} <b><i class="icon icon-chevron-right" /> v{{ opt.app.upgradeAvailableVersion }}</b>
             </template>
             <template v-else-if="opt.app">
               v{{ opt.app.currentVersion }}
diff --git a/shell/store/catalog.js b/shell/store/catalog.js
index 9f021474ffe..481df65e519 100644
--- a/shell/store/catalog.js
+++ b/shell/store/catalog.js
@@ -31,6 +31,13 @@ const CERTIFIED_SORTS = {
   other:                               3,
 };
 
+export const APP_UPGRADE_STATUS = {
+  NOT_APPLICABLE:    'not_applicable', // managed by fleet
+  NO_UPGRADE:        'no_upgrade', // no upgrade found
+  SINGLE_UPGRADE:    'single_upgrade', // a version available to upgrade to
+  MULTIPLE_UPGRADES: 'multiple_upgrades' // more than one match found
+};
+
 export const WINDOWS = 'windows';
 export const LINUX = 'linux';
 
@@ -101,7 +108,7 @@ export const getters = {
 
   chart(state, getters) {
     return ({
-      key, repoType, repoName, chartName, preferRepoType, preferRepoName, includeHidden, showDeprecated
+      key, repoType, repoName, chartName, includeHidden, showDeprecated, multiple
     }) => {
       if ( key && !repoType && !repoName && !chartName) {
         const parsed = parseKey(key);
@@ -111,7 +118,7 @@ export const getters = {
         chartName = parsed.chartName;
       }
 
-      let matching = filterBy(getters.charts, {
+      let matchingCharts = filterBy(getters.charts, {
         repoType,
         repoName,
         chartName,
@@ -119,18 +126,18 @@ export const getters = {
       });
 
       if ( includeHidden === false ) {
-        matching = matching.filter((x) => !x.hidden);
+        matchingCharts = matchingCharts.filter((x) => !x.hidden);
       }
 
-      if ( !matching.length ) {
+      if ( !matchingCharts.length ) {
         return;
       }
 
-      if ( preferRepoType && preferRepoName ) {
-        preferSameRepo(matching, preferRepoType, preferRepoName);
+      if (multiple) {
+        return matchingCharts;
       }
 
-      return matching[0];
+      return matchingCharts[0];
     };
   },
 

From ac388ad8bc57c379777d0776f31c86a8d460f039 Mon Sep 17 00:00:00 2001
From: Mo Mesgin <mmesgin@Mos-M2-MacBook-Pro.local>
Date: Tue, 14 Jan 2025 16:14:45 -0800
Subject: [PATCH 2/9] update filtering condition

---
 shell/models/catalog.cattle.io.app.js | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/shell/models/catalog.cattle.io.app.js b/shell/models/catalog.cattle.io.app.js
index 0b9ce122f14..a4cce5ab53f 100644
--- a/shell/models/catalog.cattle.io.app.js
+++ b/shell/models/catalog.cattle.io.app.js
@@ -70,10 +70,10 @@ export default class CatalogApp extends SteveModel {
       return;
     }
 
-    // narrowing down the matches by checking more properties, like home url
-    // we let a match pass if home url is not set since we support custom charts and they might not follow the best practices to include the home url
+    // narrowing down the matches by checking if the current version includes in the list of available versions from a matched chart
+    // Filtering matches by verifying if the current version is in the matched chart's available versions, and that the home value matches as well
     const thisHome = chart?.metadata?.home;
-    const bestMatches = matchingCharts.filter((m) => !thisHome || m.versions[0]?.home === thisHome);
+    const bestMatches = matchingCharts.filter((m) => m.versions.some(v => v.version === this.currentVersion && v.home === thisHome));
 
     if (bestMatches.length === 0) {
       return;

From f9a58fcdd084803af4d6cd644271bca5e19341dd Mon Sep 17 00:00:00 2001
From: Mo Mesgin <mmesgin@Mos-M2-MacBook-Pro.local>
Date: Tue, 14 Jan 2025 16:15:50 -0800
Subject: [PATCH 3/9] lint

---
 shell/models/catalog.cattle.io.app.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/shell/models/catalog.cattle.io.app.js b/shell/models/catalog.cattle.io.app.js
index a4cce5ab53f..8d68e53e00d 100644
--- a/shell/models/catalog.cattle.io.app.js
+++ b/shell/models/catalog.cattle.io.app.js
@@ -73,7 +73,7 @@ export default class CatalogApp extends SteveModel {
     // narrowing down the matches by checking if the current version includes in the list of available versions from a matched chart
     // Filtering matches by verifying if the current version is in the matched chart's available versions, and that the home value matches as well
     const thisHome = chart?.metadata?.home;
-    const bestMatches = matchingCharts.filter((m) => m.versions.some(v => v.version === this.currentVersion && v.home === thisHome));
+    const bestMatches = matchingCharts.filter((m) => m.versions.some((v) => v.version === this.currentVersion && v.home === thisHome));
 
     if (bestMatches.length === 0) {
       return;

From f24ef55f5c4b143306d8cb5c857f3999fac1bc7e Mon Sep 17 00:00:00 2001
From: Mo Mesgin <mmesgin@Mos-M2-MacBook-Pro.local>
Date: Tue, 14 Jan 2025 16:17:48 -0800
Subject: [PATCH 4/9] removed extra comment

---
 shell/models/catalog.cattle.io.app.js | 1 -
 1 file changed, 1 deletion(-)

diff --git a/shell/models/catalog.cattle.io.app.js b/shell/models/catalog.cattle.io.app.js
index 8d68e53e00d..a0c3d49581e 100644
--- a/shell/models/catalog.cattle.io.app.js
+++ b/shell/models/catalog.cattle.io.app.js
@@ -70,7 +70,6 @@ export default class CatalogApp extends SteveModel {
       return;
     }
 
-    // narrowing down the matches by checking if the current version includes in the list of available versions from a matched chart
     // Filtering matches by verifying if the current version is in the matched chart's available versions, and that the home value matches as well
     const thisHome = chart?.metadata?.home;
     const bestMatches = matchingCharts.filter((m) => m.versions.some((v) => v.version === this.currentVersion && v.home === thisHome));

From e0bbde3d8fb9113409d9c2267a92aeeb29a53260 Mon Sep 17 00:00:00 2001
From: Mo Mesgin <mmesgin@Mos-M2-MacBook-Pro.local>
Date: Wed, 15 Jan 2025 08:40:17 -0800
Subject: [PATCH 5/9] optimize the iteration through matching charts versions

---
 shell/models/catalog.cattle.io.app.js | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/shell/models/catalog.cattle.io.app.js b/shell/models/catalog.cattle.io.app.js
index a0c3d49581e..4ac7eb20b4e 100644
--- a/shell/models/catalog.cattle.io.app.js
+++ b/shell/models/catalog.cattle.io.app.js
@@ -72,7 +72,17 @@ export default class CatalogApp extends SteveModel {
 
     // Filtering matches by verifying if the current version is in the matched chart's available versions, and that the home value matches as well
     const thisHome = chart?.metadata?.home;
-    const bestMatches = matchingCharts.filter((m) => m.versions.some((v) => v.version === this.currentVersion && v.home === thisHome));
+    const bestMatches = matchingCharts.filter(({ versions }) => {
+      for (let i = 0; i < versions.length; i++) {
+        const { version, home } = versions[i];
+
+        if (version === this.currentVersion && home === thisHome) {
+          return true;
+        }
+      }
+
+      return false;
+    });
 
     if (bestMatches.length === 0) {
       return;

From a14d79f1d6ec41c3a12123c5f221e9e3cc2b0db3 Mon Sep 17 00:00:00 2001
From: Mo Mesgin <mmesgin@Mos-M2-MacBook-Pro.local>
Date: Sun, 19 Jan 2025 12:59:44 -0800
Subject: [PATCH 6/9] more test cases

---
 .../__tests__/catalog.cattle.io.app.test.ts   | 95 +++++++++++++++----
 1 file changed, 76 insertions(+), 19 deletions(-)

diff --git a/shell/models/__tests__/catalog.cattle.io.app.test.ts b/shell/models/__tests__/catalog.cattle.io.app.test.ts
index 61c6d74c13b..c7481f41bbe 100644
--- a/shell/models/__tests__/catalog.cattle.io.app.test.ts
+++ b/shell/models/__tests__/catalog.cattle.io.app.test.ts
@@ -10,15 +10,31 @@ const appCo = {
   home:     'https://apps.rancher.io/applications/cert-manager'
 };
 
-const certManagerFromCli = { home: 'https://github.com/jetstack/cert-manager' };
-
 const certManagerOfficial = {
   repoName: 'certManagerOfficial',
-  home:     'https://cert-manager.io'
+  home:     'https://cert-manager.io',
+  oldHome:  'https://github.com/jetstack/cert-manager' // older versions of cert-manager used to have this home url(e.g. 1.7.1)
 };
 
 // cert-manager chart from application collection OCI repo
-const matchingChart1 = {
+const appCoMatchingChart1 = {
+  name:     chartName,
+  repoName: appCo.repoName,
+  versions: [{
+    version:     latestVersion,
+    home:        appCo.home,
+    repoName:    appCo.repoName,
+    annotations: {}
+  },
+  {
+    version:     secondLatestVersion,
+    home:        appCo.home,
+    repoName:    appCo.repoName,
+    annotations: {}
+  }]
+};
+
+const appCoMatchingChart2 = {
   name:     chartName,
   repoName: appCo.repoName,
   versions: [{
@@ -26,11 +42,34 @@ const matchingChart1 = {
     home:        appCo.home,
     repoName:    appCo.repoName,
     annotations: {}
+  },
+  {
+    version:     secondLatestVersion,
+    home:        appCo.home,
+    repoName:    appCo.repoName,
+    annotations: {}
   }]
 };
 
 // cert-manager chart from its official helm repo 'https://cert-manager.io' added to Rancher UI repositories
-const matchingChart2 = {
+const certManagerOfficialMatchingChart1 = {
+  name:     chartName,
+  repoName: certManagerOfficial.repoName,
+  versions: [{
+    version:     latestVersion,
+    home:        certManagerOfficial.home,
+    repoName:    certManagerOfficial.repoName,
+    annotations: {},
+  },
+  {
+    version:     secondLatestVersion,
+    home:        certManagerOfficial.oldHome,
+    repoName:    certManagerOfficial.repoName,
+    annotations: {},
+  }]
+};
+
+const certManagerOfficialMatchingChart2 = {
   name:     chartName,
   repoName: certManagerOfficial.repoName,
   versions: [{
@@ -38,39 +77,57 @@ const matchingChart2 = {
     home:        certManagerOfficial.home,
     repoName:    certManagerOfficial.repoName,
     annotations: {},
+  },
+  {
+    version:     secondLatestVersion,
+    home:        certManagerOfficial.oldHome,
+    repoName:    certManagerOfficial.repoName,
+    annotations: {},
   }]
 };
 
-const installedChartFromCli = {
+const installedCertManagerAppCoFromRancherUI = {
   metadata: {
     name:    chartName,
-    home:    certManagerFromCli.home,
+    home:    appCo.home,
     version: secondLatestVersion
   }
 };
 
-const installedChartFromRancherUI = {
+const installedCertManagerOfficialFromCli = {
   metadata: {
     name:    chartName,
-    home:    certManagerOfficial.home,
+    home:    certManagerOfficial.oldHome,
     version: secondLatestVersion
   }
 };
 
-// // home is not set
-// const installedCustomChartFromRancherUI = {
-//   metadata: {
-//     name:    chartName,
-//     version: secondLatestVersion
-//   }
-// };
+const installedCertManagerOfficialFromRancherUI = {
+  metadata: {
+    name:    chartName,
+    home:    certManagerOfficial.oldHome,
+    version: secondLatestVersion
+  }
+};
 
 describe('class CatalogApp', () => {
   describe('upgradeAvailable', () => {
-    // TODO: more test cases
     const testCases = [
-      [installedChartFromCli, [matchingChart1, matchingChart2], APP_UPGRADE_STATUS.NO_UPGRADE],
-      [installedChartFromRancherUI, [matchingChart1, matchingChart2], APP_UPGRADE_STATUS.SINGLE_UPGRADE]
+      // when you follow Rancher Installation docs to install cert-manager through CLI
+      [installedCertManagerOfficialFromCli, [], APP_UPGRADE_STATUS.NO_UPGRADE],
+      [installedCertManagerOfficialFromCli, [appCoMatchingChart1], APP_UPGRADE_STATUS.NO_UPGRADE],
+      [installedCertManagerOfficialFromCli, [appCoMatchingChart1, appCoMatchingChart2], APP_UPGRADE_STATUS.NO_UPGRADE],
+      [installedCertManagerOfficialFromCli, [appCoMatchingChart1, appCoMatchingChart2, certManagerOfficialMatchingChart1], APP_UPGRADE_STATUS.SINGLE_UPGRADE],
+      // when you add application collection OCI repo through UI
+      [installedCertManagerAppCoFromRancherUI, [], APP_UPGRADE_STATUS.NO_UPGRADE],
+      [installedCertManagerAppCoFromRancherUI, [appCoMatchingChart1], APP_UPGRADE_STATUS.SINGLE_UPGRADE],
+      [installedCertManagerAppCoFromRancherUI, [appCoMatchingChart1, certManagerOfficialMatchingChart1], APP_UPGRADE_STATUS.SINGLE_UPGRADE],
+      [installedCertManagerAppCoFromRancherUI, [appCoMatchingChart1, appCoMatchingChart2], APP_UPGRADE_STATUS.MULTIPLE_UPGRADES],
+      // when you add cert-manager official helm repo through UI
+      [installedCertManagerOfficialFromRancherUI, [], APP_UPGRADE_STATUS.NO_UPGRADE],
+      [installedCertManagerOfficialFromRancherUI, [certManagerOfficialMatchingChart1], APP_UPGRADE_STATUS.SINGLE_UPGRADE],
+      [installedCertManagerOfficialFromRancherUI, [certManagerOfficialMatchingChart1, appCoMatchingChart1], APP_UPGRADE_STATUS.SINGLE_UPGRADE],
+      [installedCertManagerOfficialFromRancherUI, [certManagerOfficialMatchingChart1, certManagerOfficialMatchingChart2], APP_UPGRADE_STATUS.MULTIPLE_UPGRADES]
     ];
 
     it.each(testCases)('should return the correct upgrade status', (installedChart: Object, matchingCharts: any, expected: any) => {

From dfc0865a40892bd6d9eb697ecec7c3128e19f834 Mon Sep 17 00:00:00 2001
From: Mo Mesgin <mmesgin@Mos-M2-MacBook-Pro.local>
Date: Wed, 22 Jan 2025 17:29:22 -0800
Subject: [PATCH 7/9] check version compatibility when there are multiple
 matchings + refactor

---
 shell/models/catalog.cattle.io.app.js         | 83 +++++++++++++------
 .../pages/c/_cluster/apps/charts/install.vue  |  2 +-
 .../pages/c/_cluster/explorer/tools/index.vue |  2 +-
 3 files changed, 58 insertions(+), 29 deletions(-)

diff --git a/shell/models/catalog.cattle.io.app.js b/shell/models/catalog.cattle.io.app.js
index 4ac7eb20b4e..5f239ac396b 100644
--- a/shell/models/catalog.cattle.io.app.js
+++ b/shell/models/catalog.cattle.io.app.js
@@ -22,7 +22,6 @@ export default class CatalogApp extends SteveModel {
     set(this, 'skipCRDs', false);
     set(this, 'timeout', 300);
     set(this, 'wait', true);
-    set(this, 'foundMultipleUpgradeMatches', false);
     set(this, 'upgradeAvailableVersion', '');
   }
 
@@ -49,11 +48,11 @@ export default class CatalogApp extends SteveModel {
     return null;
   }
 
-  matchingChart(includeHidden) {
+  matchingCharts(includeHidden) {
     const chart = this.spec?.chart;
 
     if ( !chart ) {
-      return;
+      return [];
     }
 
     const chartName = chart.metadata?.name;
@@ -67,7 +66,7 @@ export default class CatalogApp extends SteveModel {
     }) || [];
 
     if (matchingCharts.length === 0) {
-      return;
+      return [];
     }
 
     // Filtering matches by verifying if the current version is in the matched chart's available versions, and that the home value matches as well
@@ -76,7 +75,7 @@ export default class CatalogApp extends SteveModel {
       for (let i = 0; i < versions.length; i++) {
         const { version, home } = versions[i];
 
-        if (version === this.currentVersion && home === thisHome) {
+        if (version === this.currentVersion && (!home || !thisHome || home === thisHome)) {
           return true;
         }
       }
@@ -84,16 +83,7 @@ export default class CatalogApp extends SteveModel {
       return false;
     });
 
-    if (bestMatches.length === 0) {
-      return;
-    }
-
-    if (bestMatches.length === 1) {
-      return bestMatches[0];
-    }
-
-    // found multiple matches but couldn't choose one unique match
-    this.foundMultipleUpgradeMatches = true;
+    return bestMatches;
   }
 
   get currentVersion() {
@@ -101,7 +91,7 @@ export default class CatalogApp extends SteveModel {
   }
 
   get upgradeAvailable() {
-    // one the following statuses gets returned:
+    // one of the following statuses gets returned:
     // NOT_APPLICABLE - managed by fleet
     // NO_UPGRADE - no upgrade found
     // SINGLE_UPGRADE - a version available to upgrade to
@@ -114,18 +104,27 @@ export default class CatalogApp extends SteveModel {
       // Things managed by fleet shouldn't show upgrade available even if there might be.
       return APP_UPGRADE_STATUS.NOT_APPLICABLE;
     }
-    const chart = this.matchingChart(false);
 
-    if (this.foundMultipleUpgradeMatches) {
-      return APP_UPGRADE_STATUS.MULTIPLE_UPGRADES;
-    }
+    const charts = this.matchingCharts(false);
 
-    if ( !chart ) {
+    if (charts.length === 0) {
       return APP_UPGRADE_STATUS.NO_UPGRADE;
     }
 
-    const workerOSs = this.$rootGetters['currentCluster'].workerOSs;
+    // Handle single chart logic
+    if (charts.length === 1) {
+      return this.evaluateUpgradeForChart(charts[0]);
+    }
+
+    // Handle multiple upgrade matches
+    return this.handleMultipleUpgradeMatches(charts);
+  }
 
+  /**
+   * Evaluates upgrade status for a single chart.
+   */
+  evaluateUpgradeForChart(chart) {
+    const workerOSs = this.$rootGetters['currentCluster'].workerOSs;
     const showPreRelease = this.$rootGetters['prefs/get'](SHOW_PRE_RELEASE);
 
     let versions = chart.versions;
@@ -139,12 +138,42 @@ export default class CatalogApp extends SteveModel {
     const newestChart = versions?.[0];
     const newestVersion = newestChart?.version;
 
-    if ( !this.currentVersion || !newestVersion ) {
+    if (!this.currentVersion || !newestVersion) {
       return APP_UPGRADE_STATUS.NO_UPGRADE;
     }
 
-    if ( compare(this.currentVersion, newestVersion) < 0 ) {
-      // set the available upgrade version to be used in other places
+    if (compare(this.currentVersion, newestVersion) < 0) {
+      // Set the available upgrade version to be used in other places
+      this.upgradeAvailableVersion = cleanupVersion(newestVersion);
+
+      return APP_UPGRADE_STATUS.SINGLE_UPGRADE;
+    }
+
+    return APP_UPGRADE_STATUS.NO_UPGRADE;
+  }
+
+  /**
+   * Handles the case where multiple upgrade matches are found.
+   * @param charts - Array of matching charts
+   */
+  handleMultipleUpgradeMatches(charts) {
+    const qualifiedCharts = [];
+
+    for (const chart of charts) {
+      const status = this.evaluateUpgradeForChart(chart);
+
+      if (status === APP_UPGRADE_STATUS.SINGLE_UPGRADE) {
+        qualifiedCharts.push(chart);
+      }
+    }
+
+    if (qualifiedCharts.length > 1) {
+      return APP_UPGRADE_STATUS.MULTIPLE_UPGRADES;
+    }
+
+    if (qualifiedCharts.length === 1) {
+      const newestVersion = qualifiedCharts[0]?.versions?.[0]?.version;
+
       this.upgradeAvailableVersion = cleanupVersion(newestVersion);
 
       return APP_UPGRADE_STATUS.SINGLE_UPGRADE;
@@ -164,7 +193,7 @@ export default class CatalogApp extends SteveModel {
   get currentVersionCompatible() {
     const workerOSs = this.$rootGetters['currentCluster'].workerOSs;
 
-    const chart = this.matchingChart(false);
+    const chart = this.matchingChart(false)[0];
 
     if (!chart) {
       return true;
@@ -194,7 +223,7 @@ export default class CatalogApp extends SteveModel {
   }
 
   goToUpgrade(forceVersion, fromTools) {
-    const match = this.matchingChart(true);
+    const match = this.matchingChart(true)[0];
     const query = {
       [NAMESPACE]: this.metadata.namespace,
       [NAME]:      this.metadata.name,
diff --git a/shell/pages/c/_cluster/apps/charts/install.vue b/shell/pages/c/_cluster/apps/charts/install.vue
index c84dab2069c..7a75dc52687 100644
--- a/shell/pages/c/_cluster/apps/charts/install.vue
+++ b/shell/pages/c/_cluster/apps/charts/install.vue
@@ -502,7 +502,7 @@ export default {
     },
 
     charts() {
-      const current = this.existing?.matchingChart(true);
+      const current = this.existing?.matchingChart(true)[0];
 
       const out = this.$store.getters['catalog/charts'].filter((x) => {
         if ( x.key === current?.key || x.chartName === current?.chartName ) {
diff --git a/shell/pages/c/_cluster/explorer/tools/index.vue b/shell/pages/c/_cluster/explorer/tools/index.vue
index 0c02f6c3867..bc0568b9743 100644
--- a/shell/pages/c/_cluster/explorer/tools/index.vue
+++ b/shell/pages/c/_cluster/explorer/tools/index.vue
@@ -60,7 +60,7 @@ export default {
       const out = {};
 
       for (const app of (this.installedApps || [])) {
-        const matching = app.matchingChart();
+        const matching = app.matchingCharts()[0];
 
         if ( !matching ) {
           continue;

From 15b7001da5bb5c14b53959e881d728a70417b33d Mon Sep 17 00:00:00 2001
From: Mo Mesgin <mmesgin@Mos-M2-MacBook-Pro.local>
Date: Thu, 23 Jan 2025 11:15:44 -0800
Subject: [PATCH 8/9] fix typo

---
 shell/models/catalog.cattle.io.app.js          | 4 ++--
 shell/pages/c/_cluster/apps/charts/install.vue | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/shell/models/catalog.cattle.io.app.js b/shell/models/catalog.cattle.io.app.js
index 5f239ac396b..1c50e2a3714 100644
--- a/shell/models/catalog.cattle.io.app.js
+++ b/shell/models/catalog.cattle.io.app.js
@@ -193,7 +193,7 @@ export default class CatalogApp extends SteveModel {
   get currentVersionCompatible() {
     const workerOSs = this.$rootGetters['currentCluster'].workerOSs;
 
-    const chart = this.matchingChart(false)[0];
+    const chart = this.matchingCharts(false)[0];
 
     if (!chart) {
       return true;
@@ -223,7 +223,7 @@ export default class CatalogApp extends SteveModel {
   }
 
   goToUpgrade(forceVersion, fromTools) {
-    const match = this.matchingChart(true)[0];
+    const match = this.matchingCharts(true)[0];
     const query = {
       [NAMESPACE]: this.metadata.namespace,
       [NAME]:      this.metadata.name,
diff --git a/shell/pages/c/_cluster/apps/charts/install.vue b/shell/pages/c/_cluster/apps/charts/install.vue
index 7a75dc52687..3ce408e3ab4 100644
--- a/shell/pages/c/_cluster/apps/charts/install.vue
+++ b/shell/pages/c/_cluster/apps/charts/install.vue
@@ -502,7 +502,7 @@ export default {
     },
 
     charts() {
-      const current = this.existing?.matchingChart(true)[0];
+      const current = this.existing?.matchingCharts(true)[0];
 
       const out = this.$store.getters['catalog/charts'].filter((x) => {
         if ( x.key === current?.key || x.chartName === current?.chartName ) {

From 6912d69f54fc3bafebe76f1a4ab4e0b815b3b69f Mon Sep 17 00:00:00 2001
From: Mo Mesgin <mmesgin@Mos-M2-MacBook-Pro.local>
Date: Thu, 23 Jan 2025 11:57:06 -0800
Subject: [PATCH 9/9] refine matching logic + add documenting and comments

---
 shell/models/catalog.cattle.io.app.js | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/shell/models/catalog.cattle.io.app.js b/shell/models/catalog.cattle.io.app.js
index 1c50e2a3714..f046efea827 100644
--- a/shell/models/catalog.cattle.io.app.js
+++ b/shell/models/catalog.cattle.io.app.js
@@ -48,6 +48,13 @@ export default class CatalogApp extends SteveModel {
     return null;
   }
 
+  /**
+   * Finds matching charts based on the current chart's name, repository, and other attributes.
+   * The function filters out charts that do not meet specific criteria, including version and home value matches.
+   *
+   * @param includeHidden - Whether to include hidden charts in the search.
+   * @returns An array of matching chart objects that meet the specified criteria.
+  */
   matchingCharts(includeHidden) {
     const chart = this.spec?.chart;
 
@@ -72,9 +79,16 @@ export default class CatalogApp extends SteveModel {
     // Filtering matches by verifying if the current version is in the matched chart's available versions, and that the home value matches as well
     const thisHome = chart?.metadata?.home;
     const bestMatches = matchingCharts.filter(({ versions }) => {
-      for (let i = 0; i < versions.length; i++) {
+      // First checking if the latest version has the same home value
+      if (thisHome === versions[0]?.home) {
+        return true;
+      }
+
+      for (let i = 1; i < versions.length; i++) {
         const { version, home } = versions[i];
 
+        // Finding the exact version, if the version is not there, then most likely it's not a match
+        // if the exact version is found, then we can compare the home values when they exist
         if (version === this.currentVersion && (!home || !thisHome || home === thisHome)) {
           return true;
         }