fix: @W-17672756@ update version recommendation logic (#401)

* fix: update version recommendation logic

* chore: address feedback

Author: maliroteh-sf

package.json

@@ -219,7 +219,11 @@
     }
   },
   "apiVersionMetadata": {
-    "comment": "Refer to ApiVersionMetadata in orgUtils.ts for details",
+    "x-apiVersionMetadata-comments": [
+      "Refer to ApiVersionMetadata in orgUtils.ts for more details.",
+      "The 'target' section defines the dev server version (matchingDevServerVersion) and the API version that it can support (versionNumber).",
+      "The 'versionToTagMappings' section defines the mapping between released tags for our CLI plugin and the org version that each tag supports."
+    ],
     "target": {
       "versionNumber": "64.0",
       "matchingDevServerVersion": "~11.5.0"

src/shared/orgUtils.ts

@@ -177,8 +177,9 @@ export class OrgUtils {
 
     if (Version.same(orgVersion, targetVersion) === false) {
       let errorMessage = messages.getMessage('error.org.api-mismatch.message', [orgVersion, targetVersion]);
+      // Find the tag (if any) that can support this org version
       const tagName = pkg.apiVersionMetadata.versionToTagMappings.find(
-        (info) => info.versionNumber === targetVersion
+        (info) => info.versionNumber === orgVersion
       )?.tagName;
       if (tagName) {
         const remediation = messages.getMessage('error.org.api-mismatch.remediation', [