Resolve Issues #491 and #336 regarding upgrade functionality

[RintaroYamada]

Description:
This PR aims to address the upgrade issues documented in #491 and #336 on the mas-cli main branch. The solution has been derived from the discussion and proposed changes in Pull Request #496.
The following change has been made in Sources/Maskit/Controllers/StoreSearch.swift:

51c51,53
<        components.queryItems = [URLQueryItem(name: "id", value: "\(appId)")]
---
>        components.queryItems = [
>            URLQueryItem(name: "id", value: "\(appId)"),
>            URLQueryItem(name: "entity", value: "desktopSoftware"),
>        ]

This correction enhances the upgrade functionality, aligning it with the expected behavior as discussed in the aforementioned issues and PR.

I have tested these changes on macOS Ventura 13.6, and confirmed the upgrade functionality now works as expected.

[RintaroYamada]

Hi @rgoldberg,

First of all, I want to sincerely thank you for maintaining this incredibly useful project. Thanks to your work, mas-cli has become much more stable and convenient than before. I'm truly grateful, and I would be happy to contribute in any small way I can.

I noticed that this PR was closed by myself earlier, but I saw that you assigned me afterwards — which I really appreciate. To be honest, I wasn't sure if this fix was still relevant, and that's why I closed it. But if there's still value in this change, I'm happy to provide further support or reopen the PR if needed.

Originally, I created this patch to address a problem I observed in earlier versions of mas-cli:
When the macOS version and iOS version of an app differed, mas outdated would incorrectly report the iOS version as newer. This led to unnecessary mas upgrade attempts, which ultimately did nothing. It was a small but recurring inefficiency.

At the time of writing this PR, I was using an Intel Mac running macOS Ventura 13.6. Since then, my system has been updated to macOS Sequoia 15.5, and I no longer encounter the same issue in my current setup.

Additionally, since I’m not using an Apple Silicon Mac, I may not be able to fully test behavior related to iOS apps — which seems increasingly important as mas-cli evolves. I understand that my environment may no longer be ideal for verifying this kind of fix.

That said, this PR still reflects my best effort based on past issues and your previous work in #496. If this patch is still useful or worth revisiting, I would be glad to help however I can — even if it's just as a reference.

Thank you again for your incredible dedication to this project. I’ve learned a lot through this experience.

Best regards,
RintaroYamada

[rgoldberg]

@RintaroYamada Thanks for the kind words, offer of help, & submitting this PR.

I recently assigned unassigned PRs to whoever authored them or subsequently added to them (that I noticed) to track things better & to give credit to everyone.

The same code change from this PR was merged via #496, so no need to look into this PR again.

If you have time to help:

Do you know Swift and/or Objective-C?

Do you know how to investigate Apple private frameworks to find replacement APIs for broken / suboptimal APIs currently used by mas? (Finding public APIs would be even better, but they are unlikely to exist anywhere)

Before looking into replacing / improving specific Apple private framework uses, however, it would be useful to get types for id uses in Objective-C headers extracted from the DSC, as that will aid investigation & use of the frameworks.

Other tasks include:

• obtaining the ADAM ID (aka app ID, aka item identifier) for installed apps from public sources without requiring calls to the iTunes Search web interface.
• obtaining the region of the Mac App Store (as opposed to the region of the macOS user).

I can supply more info about any of the above or about alternate projects (tailored to your skill set & interests), if you're interested.

Thanks.

[RintaroYamada]

Hi @rgoldberg,

Thank you for taking the time to explain everything in such detail — I really appreciate it.

To be transparent, most of my programming experience so far has been with Python. I've only briefly touched Swift and Objective-C (mostly in class or small experiments), so I’m not confident in working with them yet. However, I do find both languages and the domain of Apple system APIs very interesting, and I’d love to explore them further when possible.

That said, I don’t yet have experience with reverse engineering, and I’d prefer to be careful when it comes to areas that may involve Apple’s private frameworks or internal rules. I fully understand the need to find more efficient or reliable APIs, though, and I’m open to helping with that investigation in a way that's respectful of platform boundaries.

If there are smaller or more beginner-friendly tasks — especially involving Swift or related to documentation, testing, or user-facing features — I’d be very glad to assist and learn step-by-step.

Thanks again for your generous guidance and for keeping this project so active and well-maintained.

Best regards,
RintaroYamada

[rgoldberg]

@RintaroYamada Thanks for the reply. I'll try to look for simpler tasks that might be good for those new to Swift.

Off the top of my head, there are 2 newer tasks that are simpler, but they aren't very exciting, so I can understand if you wouldn't want to do them (they are mainly moving documentation from Markdown to strings in the mas code and using a tool to generate docs, but you'd get to look at the code, see the docs, get something useful done without worrying about in-depth Swift knowledge, etc.):

• Generate web documentation with SAP #866
• Generate man pages with SAP #865

SAP is Swift Argument Parser, an Apple open-source project which mas uses to parse command-line arguments, organize its command-line-facing code, etc.

It can generate shell completion scripts (I'm currently working on that), DocC web docs & man pages.

I am thinking about moving the documentation from the mas README.md into our Swift code in ways that SAP can autogenerate both the DocC web docs & man pages for mas (mas doesn't currently have man pages), then updating the homebrew-core & the mas custom tap to automate the install of both.

SAP is spotty, however, so I'm not sure how nicely those will turn out; if there are bugs or missing features (for which you could possibly submit fixes to Apple's SAP project; I've submitted many fixes for their completion code).

After everything is setup to closely mimic the existing documentation (besides fixing obvious typos & obsolete info), we could rewrite some of the documentation. I could do that if you wouldn't want to be bored with that.

It shouldn't take long if SAP works well enough, but might require SAP PRs if not.

I can look for other more exciting tasks that might be novice friendly…

If you do decide to look into any of it, let me know so I can advise.

I can help you get your repo setup to build, etc.

The project is built, listed, tested, etc. via scripts in Scripts/ (in the main branch; in the most recently released version, mas still used script/, but you should need to go backwards only if you're looking through historical code.

I develop using IntelliJ, which isn't made for Swift, but I'm used to it, so only use Xcode when I need to debug or other features that IntelliJ isn't good at. I always build from the command line. The build script must generate a file so that the build can even compile; I've never even setup Xcode to run that build script when it builds, so, if you figure that out, you or I could document that in the README.md or CONTRIBUTING.md.

mas requires Xcode Tools 15.0+ on macOS 13.5+ to build Swift 5.9, but it is best to be on the latest of both. mas will upgrade to Swift 6.0, requiring Xcode 15.0+ on macOS 14.5+ to build, after macOS 13 goes EOL this fall.

Thanks.

[RintaroYamada]

Hi @rgoldberg,

Thanks again for the detailed explanation — it's very helpful.

I’ve started looking into #865 and #866 and setting up the local build environment with the Scripts/ folder. I'll let you know if I run into any issues. I'll also begin reviewing SAP and how the documentation generation works.

I appreciate your support and guidance — this seems like a great way to get more familiar with Swift.

Thanks!

[rgoldberg]

@RintaroYamada Thanks for looking into this.

If you need any help, please let me know.

Generating DocC web documentation is more important than generating man pages, so you probably should try that first.

It will probably make sense to discuss any issues you have in the respective issues, to keep everything organized.

Thanks again.