refactor: Lock profiles during async operations (phase 1: filesystem)

[traeok]

Proposed changes

This PR is the "first phase" of resolving the issues with authentication prompts and APIs as described in #3329.
It avoids race conditions during filesystem access by leveraging a new lock mechanism for profiles. This is exposed in Zowe Explorer API so that extenders can also leverage the locking mechanism until its rolled out to all core APIs.

I decided to separate the logic into two phases to avoid a large PR and complicated review process:

1. Address high-priority bugs by adding locking mechanism into filesystem
2. Address credential issues for extenders by applying locking mechanism to API functions

How to test

1. Add a PDS to your workspace - search for one under a profile, right-click on it and select "Add to Workspace"

• Yes, all of the tree providers do reload the first time that you add a resource to a workspace. However, this issue is unrelated to this PR and not easily resolvable because VS Code reloads extensions once a workspace is opened.

2. Right-click on your profile and select "Update Credentials." Enter in an invalid username but keep your password as-is.
3. Reload the window. Notice that once the workspace is loaded, an "Invalid Credentials" modal prompt occurs. Click the "Update Credentials" button in this prompt and enter in valid credentials.
4. Once you've entered in valid credentials, select the "Refresh" icon at the top of the Explorer tab to inform VS Code that it needs to fetch the resources again. The PDS is populated with its members and they can be opened/modified in the editor.

As an alternative to step 3, you can select "Cancel" - then go to the Zowe Explorer tab and update the credentials from the tree. Once updated, the profile is unlocked and you can refresh the workspace as outlined in step 4.

Release Notes

Milestone: 3.1.0

Changelogs:

• ZE: Fixed an issue where the filesystem continued to use a profile with invalid credentials to fetch resources. Now, after an authentication error occurs for a profile, it cannot be used again in the filesystem until the authentication error is resolved.
• ZE API: Added an AuthHandler class with functions for locking/unlocking profiles, prompting for credentials and SSO login support. Extenders can now lock profiles after an authentication error, ensuring that an invalid profile is not used asynchronously until the error is resolved.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
  • ZE: Resolves issues with profiles and async processing in the filesystem that caused repeated 401 errors (causing lockouts)
• Enhancement (non-breaking change which adds or improves functionality)
  • ZE API: The AuthHandler class provides authentication prompts to extenders as well as the lock mechanism
• Breaking change (a change that would cause existing functionality to not work as expected)
• Documentation (Markdown, README updates)
• Other (please specify above in "Proposed changes" section)

Checklist

General

• I have read the CONTRIBUTOR GUIDANCE wiki
• All PR dependencies have been merged and published (if applicable)
• A GIF or screenshot is included in the PR for visual changes
• The pre-publish command has been executed:
  • v2 and below: yarn workspace vscode-extension-for-zowe vscode:prepublish
  • v3: pnpm --filter vscode-extension-for-zowe vscode:prepublish

Code coverage

• There is coverage for the code that I have added
• I have added new test cases and they are passing
• I have manually tested the changes

Deployment

• I have added developer documentation (if applicable)
• Documentation should be added to Zowe Docs
  • If you're an outside contributor, please post in the #zowe-doc Slack channel to coordinate documentation.
  • Otherwise, please check with the rest of the squad about any needed documentation before merging.
• These changes may need ported to the appropriate branches (list here):

[codecov]

Codecov Report

Attention: Patch coverage is 94.32624% with 8 lines in your changes missing coverage. Please review.

Project coverage is 93.17%. Comparing base (aea6d92) to head (3dc39b1).

Files with missing lines	Patch %	Lines
...ages/zowe-explorer-api/src/profiles/AuthHandler.ts	91.42%	6 Missing ⚠️
...ckages/zowe-explorer/src/configuration/Profiles.ts	0.00%	1 Missing ⚠️
packages/zowe-explorer/src/utils/AuthUtils.ts	93.33%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3370      +/-   ##
==========================================
- Coverage   93.17%   93.17%   -0.01%     
==========================================
  Files         117      119       +2     
  Lines       12277    12374      +97     
  Branches     2822     2835      +13     
==========================================
+ Hits        11439    11529      +90     
- Misses        837      844       +7     
  Partials        1        1              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[github-actions]

📅 Suggested merge-by date: 1/7/2025