fix: handle expired gh CLI tokens and macOS restricted file access (#533)

## Summary

Fixes two classes of user-reported failures:

1. **GitHub API 403s when the `gh` CLI token is expired.** The module
attaches the token from `gh auth token` to API requests; when that token
is expired or has insufficient scopes, `api.github.com` returns 403 and
the deployment fails with a misleading downstream error (`The release v
does not exist...`).
2. **macOS file access errors** on protected paths when reading files
without `-Force`.

## Changes

### GitHub auth resiliency

- `Invoke-GitHubApiRequest`: when the attached `gh` token causes a
401/403, automatically retry once without auth (anonymous, subject to
rate limits) and warn the user to run `gh auth login`. Applies to all
three code paths (file download, `SkipHttpErrorCheck`, standard API
call). Factored repeated logic into `Disable-AuthAndWarn` and
`Get-StatusCodeFromError` helpers.
- `Get-GithubReleaseTag`: on 401/403, throw an actionable error naming
the likely cause (expired gh token or rate limiting) and the fix (`gh
auth login`) instead of the generic "check your internet connection"
message.
- `Test-NetworkConnectivity`: inspect the status code from the
`api.github.com` probe and record 401/403 as a Failure with the same
guidance, so connectivity checks surface this issue up front.

### macOS file access

- Added `-Force` to every `Get-Item`, `Get-ChildItem`, and `Get-Content`
call across the module so reads succeed on macOS paths where
hidden/protected attributes would otherwise block access. (`Test-Path` /
`Resolve-Path` intentionally untouched — they do not support `-Force`.)

### UX

- `Get-AzureContext`: clarified that "Querying Azure for management
groups, subscriptions, and regions..." can take up to 30 seconds.

## Testing

- `Invoke-Build -File .\src\ALZ.build.ps1` — passes locally.
- Existing `Test-NetworkConnectivity.Tests.ps1` still covers the mocked
success/failure paths.

Author: jaredfholgate

src/ALZ/ALZ.psm1

@@ -4,6 +4,7 @@ Write-Verbose "Discovering Public & Private src."
 $itemSplat = @{
     Filter      = '*.ps1'
     Recurse     = $true
+    Force       = $true
     ErrorAction = 'Stop'
 }
 try {

src/ALZ/Private/Config-Helpers/Edit-ALZConfigurationFilesInPlace.ps1

@@ -15,12 +15,12 @@ function Edit-ALZConfigurationFilesInPlace {
 
     foreach ($location in $locations) {
         $bicepModules = Join-Path $alzEnvironmentDestination $location
-        $files += @(Get-ChildItem -Path $bicepModules -Recurse -Filter *.parameters.*.json)
+        $files += @(Get-ChildItem -Path $bicepModules -Recurse -Filter *.parameters.*.json -Force)
     }
 
     foreach ($file in $files) {
         Write-Verbose "Checking Bicep parameter file: $($file.Name)"
-        $bicepConfiguration = Get-Content $file.FullName | ConvertFrom-Json -AsHashtable
+        $bicepConfiguration = Get-Content $file.FullName -Force | ConvertFrom-Json -AsHashtable
         $modified = $false
 
         foreach ($configKey in $configuration.PsObject.Properties) {

src/ALZ/Private/Config-Helpers/Get-ALZConfig.ps1

@@ -18,11 +18,11 @@ function Get-ALZConfig {
     }
 
     # Import the config and transform it to a PowerShell object
-    $extension = (Get-Item -Path $configFilePath).Extension.ToLower()
+    $extension = (Get-Item -Path $configFilePath -Force).Extension.ToLower()
     $config = $null
     if ($extension -eq ".yml" -or $extension -eq ".yaml") {
         try {
-            $config = [PSCustomObject](Get-Content -Path $configFilePath | ConvertFrom-Yaml -Ordered)
+            $config = [PSCustomObject](Get-Content -Path $configFilePath -Force | ConvertFrom-Yaml -Ordered)
         } catch {
             $errorMessage = "Failed to parse YAML inputs. Please check the YAML file for errors and try again. $_"
             Write-ToConsoleLog $errorMessage -IsError
@@ -31,7 +31,7 @@ function Get-ALZConfig {
 
     } elseif ($extension -eq ".json") {
         try {
-            $config = [PSCustomObject](Get-Content -Path $configFilePath | ConvertFrom-Json)
+            $config = [PSCustomObject](Get-Content -Path $configFilePath -Force | ConvertFrom-Json)
         } catch {
             $errorMessage = "Failed to parse JSON inputs. Please check the JSON file for errors and try again. $_"
             Write-ToConsoleLog $errorMessage -IsError

src/ALZ/Private/Config-Helpers/Get-AzureRegionData.ps1

@@ -49,7 +49,7 @@ function Get-AzureRegionData {
 
     Invoke-Terraform -moduleFolderPath $regionFolder -autoApprove -output "regions_and_zones" -outputFilePath $outputFilePath -silent
 
-    $json = Get-Content $outputFilePath
+    $json = Get-Content $outputFilePath -Force
     $regionsAndZones = ConvertFrom-Json $json
 
     $zonesSupport = @()

src/ALZ/Private/Deploy-Accelerator-Helpers/Get-AcceleratorFolderConfiguration.ps1

@@ -67,7 +67,7 @@ function Get-AcceleratorFolderConfiguration {
 
     # Try to read and validate inputs.yaml
     try {
-        $inputsContent = Get-Content -Path $inputsYamlPath -Raw
+        $inputsContent = Get-Content -Path $inputsYamlPath -Raw -Force
         $inputsYaml = $inputsContent | ConvertFrom-Yaml
 
         $result.InputsContent = $inputsContent

src/ALZ/Private/Deploy-Accelerator-Helpers/Get-AzureContext.ps1

@@ -40,11 +40,11 @@ function Get-AzureContext {
 
     # Check if valid cache exists
     if (Test-Path $cacheFilePath) {
-        $cacheFile = Get-Item $cacheFilePath
+        $cacheFile = Get-Item $cacheFilePath -Force
         $cacheAge = (Get-Date) - $cacheFile.LastWriteTime
         if ($cacheAge.TotalHours -lt $cacheExpirationHours) {
             try {
-                $cachedContext = Get-Content -Path $cacheFilePath -Raw | ConvertFrom-Json -AsHashtable
+                $cachedContext = Get-Content -Path $cacheFilePath -Raw -Force | ConvertFrom-Json -AsHashtable
                 Write-ToConsoleLog "Using cached Azure context (cached $([math]::Round($cacheAge.TotalMinutes)) minutes ago). Use -clearCache to refresh."
                 Write-ToConsoleLog "Found $($cachedContext.ManagementGroups.Count) management groups, $($cachedContext.Subscriptions.Count) subscriptions, and $($cachedContext.Regions.Count) regions"
                 return $cachedContext
@@ -60,7 +60,7 @@ function Get-AzureContext {
         Regions          = @()
     }
 
-    Write-ToConsoleLog "Querying Azure for management groups, subscriptions, and regions..."
+    Write-ToConsoleLog "Querying Azure for management groups, subscriptions, and regions... (this can take up to 30 seconds)"
 
     try {
         # Get the current tenant ID

src/ALZ/Private/Deploy-Accelerator-Helpers/Get-ModuleVersionData.ps1

@@ -12,7 +12,7 @@ function Get-ModuleVersionData {
     $dataFilePath = Join-Path $targetDirectory ".alz-version-data.json"
 
     if (Test-Path $dataFilePath) {
-        $data = Get-Content $dataFilePath | ConvertFrom-Json
+        $data = Get-Content $dataFilePath -Force | ConvertFrom-Json
         $versionKey = "$($moduleType)Version"
         return $data.$versionKey
     }

src/ALZ/Private/Deploy-Accelerator-Helpers/New-Bootstrap.ps1

@@ -132,7 +132,7 @@ function New-Bootstrap {
         $bootstrapParameters = [PSCustomObject]@{}
 
         Write-Verbose "Getting the bootstrap configuration..."
-        $terraformFiles = Get-ChildItem -Path $bootstrapModulePath -Filter "*.tf" -File
+        $terraformFiles = Get-ChildItem -Path $bootstrapModulePath -Filter "*.tf" -File -Force
         foreach ($terraformFile in $terraformFiles) {
             $bootstrapParameters = Convert-HCLVariablesToInputConfig -targetVariableFile $terraformFile.FullName -hclParserToolPath $hclParserToolPath -appendToObject $bootstrapParameters
         }
@@ -145,7 +145,7 @@ function New-Bootstrap {
         if ($hasStarter) {
             Write-Verbose "Getting the starter configuration..."
             if ($iac -eq "terraform") {
-                $terraformFiles = Get-ChildItem -Path $starterRootModuleFolderPath -Filter "*.tf" -File
+                $terraformFiles = Get-ChildItem -Path $starterRootModuleFolderPath -Filter "*.tf" -File -Force
                 foreach ($terraformFile in $terraformFiles) {
                     $starterParameters = Convert-HCLVariablesToInputConfig -targetVariableFile $terraformFile.FullName -hclParserToolPath $hclParserToolPath -appendToObject $starterParameters
                 }
@@ -215,7 +215,7 @@ function New-Bootstrap {
         if ($iac -eq "terraform") {
             if ($starterFoldersToRetain.Length -gt 0) {
                 Write-Verbose "Removing unwanted folders from the starter module..."
-                $folders = Get-ChildItem -Path $starterModulePath -Directory
+                $folders = Get-ChildItem -Path $starterModulePath -Directory -Force
                 foreach ($folder in $folders) {
                     if ($starterFoldersToRetain -notcontains $folder.Name) {
                         Write-Verbose "Removing folder: $($folder.FullName)"

src/ALZ/Private/Deploy-Accelerator-Helpers/New-ModuleSetup.ps1

@@ -177,7 +177,7 @@ function New-ModuleSetup {
 
             if (!$firstRun) {
                 Write-Verbose "Checking for state files at: $previousStatePath"
-                $previousStateFiles = Get-ChildItem $previousVersionPath -Filter "terraform.tfstate" -Recurse | Select-Object -First 1 | ForEach-Object { $_.FullName }
+                $previousStateFiles = Get-ChildItem $previousVersionPath -Filter "terraform.tfstate" -Recurse -Force | Select-Object -First 1 | ForEach-Object { $_.FullName }
 
                 if ($previousStateFiles.Count -gt 0) {
                     foreach ($stateFile in $previousStateFiles) {

src/ALZ/Private/Deploy-Accelerator-Helpers/Request-ALZConfigurationValue.ps1

@@ -178,7 +178,7 @@ function Request-ALZConfigurationValue {
             Write-ToConsoleLog "Schema file not found at $schemaPath. Proceeding without descriptions." -IsWarning
             $schema = $null
         } else {
-            $schema = Get-Content -Path $schemaPath -Raw | ConvertFrom-Json
+            $schema = Get-Content -Path $schemaPath -Raw -Force | ConvertFrom-Json
         }
 
         # Define the configuration files to process
@@ -192,7 +192,7 @@ function Request-ALZConfigurationValue {
             Write-ToConsoleLog "For more information, see: https://aka.ms/alz/acc/phase0"
 
             # Read the raw content to preserve comments and ordering
-            $inputsYamlContent = Get-Content -Path $inputsYamlPath -Raw
+            $inputsYamlContent = Get-Content -Path $inputsYamlPath -Raw -Force
             $inputsConfig = $inputsYamlContent | ConvertFrom-Yaml -Ordered
             $inputsUpdated = $false
             $sensitiveEnvVars = @{}