refactor: cross-platform build script compatibility (CUT-5128)

[junioralmeida-82]

Description
Refactored the PowerShell build system in the support repository to ensure full cross-platform compatibility (macOS, Linux, and Windows).

Issues
CUT-5128 - Refactor build scripts for cross-platform support.

What does this solve?
Replaces manual path concatenations with Join-Path to handle different path separators (/ vs ) automatically.

Standardizes variable initialization when dot-sourcing Get-Config.ps1 to prevent "Null Argument" errors on non-Windows environments.

Modernizes the build orchestrator for better stability across different PowerShell versions (5.1 and 7+).

Is there anything particularly tricky?
Safety Bypass: As discussed with @joeworkman, the git push command in Invoke-GitCommit.ps1 has been commented out to prevent accidental commits during the build process until a separate deploy card is addressed.

How should this be tested?
Run the build script from the root of the repository:
pwsh ./PowerShell/Deploy/Build-Module.ps1 -ReleaseType Patch

Verify that all paths in the terminal logs resolve correctly according to the Host OS.

Check if the module manifest (.psd1) and ModuleChangelog.md are updated correctly.

Screenshots

---

Note

Medium Risk
Build/deploy pipeline behavior changes (path resolution, additional build steps, and disabling git commit/push) could affect CI/release automation if assumptions about working directory, generated artifacts, or git publishing still exist.

Overview
Refactors the PowerShell module build pipeline to be cross-platform by standardizing path construction with Join-Path and explicitly passing config parameters when dot-sourcing Get-Config.ps1.

Build-Module.ps1 now also orchestrates additional post-build steps (SDK endpoint sync, help generation, and Pester test file generation) with existence checks, and Invoke-GitCommit.ps1 has its git commit/push calls commented out to prevent accidental publishes during testing.

Bumps module/help version to 3.1.1, updates the manifest metadata/formatting, adds deployment docs (PowerShell/Deploy/README.md), and records the release in ModuleChangelog.md.

^{Reviewed by Cursor Bugbot for commit afc94a0. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Git commit and push permanently disabled in build

Medium Severity

Both git commit and git push commands are commented out, making Invoke-GitCommit a no-op that stages files and shows status but never commits or pushes. While the PR notes this is temporary "until a separate deploy card is addressed," shipping this to the main branch means any CI/CD pipeline depending on this function will silently fail to publish changes.

 

^{Reviewed by Cursor Bugbot for commit 6048ec3. Configure here.}

[jworkmanjc]

The Acceptance Criteria for the card could be more clear but in general I want the Build-Module script to call all of the required build functions:
Get-Config / dependencies → Build-Module →SdkSync/jcapiToSupportSync.ps1 → Build-HelpFiles → Build-PesterTestFiles → BuildNuspecFromPsd1.

Right now the build script is only updating the Module Manifest (.psd1) file so this card can not be marked complete yet.

My aim is to have developers perform work in the module, then run ./Build-Module.ps1 -ReleaseType patch and have that function call perform the work it's doing today and run:
SdkSync/jcapiToSupportSync.ps1
Build-HelpFiles
Build-PesterTestFiles
BuildNuspecFromPsd1

These scripts need to be included in Build-Module in order to mark this work ready for review. The SDK functions can be updated outside of this this repository, when we cut a new release it's important to keep these functions that we autogenerate in sync with our latest powershell release.

Help Files should be generated if we are developing so having the build-module function call build-helpfiles would be important here.

Pester tests are generated automatically if a developer runs Build-PesterTestFiles, these have been forgotten previously so in my opinion they should just be included in the build-module script.

BuildNuspecFromPsd1 this is probably out of scope looking at this now but we did have it in the card. I think CI processes this and we really don't need to build this into the module.

[cursor]

Set-Location not restored if help script throws

Low Severity

The working directory is changed via Set-Location before calling & $BuildHelpPath, and restored afterward on line 90. If the help script throws a terminating error, Set-Location -Path $PreviousLocation is skipped, leaving the process in the "Docs" directory. Subsequent operations like Build-PesterTestFiles.ps1 would then execute from an unexpected location. A try/finally block would ensure the location is always restored.

 

^{Reviewed by Cursor Bugbot for commit 07d64af. Configure here.}

[jworkmanjc]

can remove AI generated content here

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

^{Reviewed by Cursor Bugbot for commit afc94a0. Configure here.}

[cursor]

git add -A still stages files despite disabled commit

Medium Severity

Invoke-GitCommit still executes git add -A (staging all files), git config user.email, and git config user.name even though commit and push are commented out. When called from Build-WikiPages.ps1, this modifies the developer's local git config to "CircleCI" values and stages their entire working tree — real side effects that conflict with the stated goal of safe local testing. If the intent is to bypass git operations, the staging and config commands need to be disabled too.

 

^{Reviewed by Cursor Bugbot for commit afc94a0. Configure here.}

[jworkmanjc]

I'm good with these changes for now, I changed the target branch to v3.1.1_pwshModule

Otherwise approved