Align scripts with MSX PowerShell guidance

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: MariusStorhaug

.github/actions/update-index/action.yml

@@ -16,4 +16,4 @@ runs:
         ClientID: ${{ inputs.ClientID }}
         PrivateKey: ${{ inputs.PrivateKey }}
         Script: |
-          ${{ github.action_path }}/src/main.ps1
+          ${{ github.action_path }}/src/Invoke-UpdateIndex.ps1

.github/actions/update-index/src/Invoke-UpdateIndex.ps1

@@ -0,0 +1,42 @@
+#Requires -Version 7.0
+
+<#
+    .SYNOPSIS
+    Updates generated index content for the docs repository.
+
+    .DESCRIPTION
+    Orchestrates the update-index action flow by collecting organization repository
+    metadata and regenerating module catalog documentation artifacts.
+
+    .EXAMPLE
+    ./Invoke-UpdateIndex.ps1
+#>
+[CmdletBinding()]
+param()
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+Import-Module -Name (Join-Path $PSScriptRoot 'update-index.Helpers.psm1')
+
+LogGroup 'Initialize update-index run' {
+    Write-Host "Starting update-index in [$PSScriptRoot]"
+}
+
+LogGroup 'Collect repositories' {
+    $repos = Show-RepoList
+    Write-Host "Repository collection complete: $($repos.Count) records"
+}
+
+LogGroup 'Skipped generators' {
+    Write-Host 'Update-ActionList is currently disabled in Invoke-UpdateIndex.ps1'
+    Write-Host 'Update-FunctionAppList is currently disabled in Invoke-UpdateIndex.ps1'
+}
+
+LogGroup 'Update module catalog docs' {
+    Update-ModuleList -Repos $repos
+}
+
+LogGroup 'Finalize update-index run' {
+    Write-Host 'update-index run completed'
+}

.github/actions/update-index/src/main.ps1

@@ -1,15 +1,36 @@
+#Requires -Version 7.0
+
+<#
+    .SYNOPSIS
+    Removes pull request preview artifacts and related environment state.
+
+    .DESCRIPTION
+    Deletes previews/pr-<number> from gh-pages, deactivates and removes preview
+    deployments, deletes the preview environment, and updates the PR comment.
+
+    .EXAMPLE
+    ./Cleanup-PreviewDocs.ps1 -Repository "PSModule/docs" -Token $token -PullRequestNumber 42 -PreviewUrl "https://psmodule.io/docs/previews/pr-42/" -EnvironmentName "pr-preview-42"
+#>
+[CmdletBinding()]
 param(
+    # Repository in owner/name format.
     [Parameter(Mandatory = $true)]
     [string]$Repository,
+    # GitHub App token used for authenticated git and gh operations.
     [Parameter(Mandatory = $true)]
     [string]$Token,
+    # Pull request number used for preview path and comment targeting.
     [Parameter(Mandatory = $true)]
     [int]$PullRequestNumber,
+    # Public preview URL for PR comments.
     [Parameter(Mandatory = $true)]
     [string]$PreviewUrl,
+    # Environment name to clean up from repository environments.
     [Parameter(Mandatory = $true)]
     [string]$EnvironmentName,
+    # Working directory used to clone gh-pages.
     [string]$PagesDirectory = '_pages',
+    # Branch used as the Pages source branch.
     [string]$BaseBranch = 'gh-pages'
 )
 

…hub/actions/update-index/src/Helper.psm1 …date-index/src/update-index.Helpers.psm1.github/actions/update-index/src/Helper.psm1 renamed to .github/actions/update-index/src/update-index.Helpers.psm1 .github/actions/update-index/src/Helper.psm1 renamed to .github/actions/update-index/src/update-index.Helpers.psm1

@@ -1,13 +1,33 @@
+#Requires -Version 7.0
+
+<#
+    .SYNOPSIS
+    Publishes live docs content to the gh-pages branch.
+
+    .DESCRIPTION
+    Clones gh-pages, replaces live content while keeping previews, and pushes
+    the updated branch using the GitHub App token identity.
+
+    .EXAMPLE
+    ./Publish-LiveDocs.ps1 -Repository "PSModule/docs" -Token $token -BuildDirectory "$PWD/src/site" -CommitSha $env:GITHUB_SHA
+#>
+[CmdletBinding()]
 param(
+    # Repository in owner/name format.
     [Parameter(Mandatory = $true)]
     [string]$Repository,
+    # GitHub App token used for authenticated git and gh operations.
     [Parameter(Mandatory = $true)]
     [string]$Token,
+    # Full path to the built static site directory.
     [Parameter(Mandatory = $true)]
     [string]$BuildDirectory,
+    # Commit SHA used in the publish commit message.
     [Parameter(Mandatory = $true)]
     [string]$CommitSha,
+    # Working directory used to clone gh-pages.
     [string]$PagesDirectory = '_pages',
+    # Branch used as the Pages source branch.
     [string]$BaseBranch = 'gh-pages'
 )
 

.github/scripts/docs/Cleanup-PreviewDocs.ps1

@@ -1,15 +1,36 @@
+#Requires -Version 7.0
+
+<#
+    .SYNOPSIS
+    Publishes pull request preview docs content to gh-pages.
+
+    .DESCRIPTION
+    Writes the PR preview build output into previews/pr-<number> on gh-pages,
+    pushes branch updates, and ensures the preview comment is present on the PR.
+
+    .EXAMPLE
+    ./Publish-PreviewDocs.ps1 -Repository "PSModule/docs" -Token $token -PullRequestNumber 42 -PreviewUrl "https://psmodule.io/docs/previews/pr-42/" -BuildDirectory "$PWD/src/site"
+#>
+[CmdletBinding()]
 param(
+    # Repository in owner/name format.
     [Parameter(Mandatory = $true)]
     [string]$Repository,
+    # GitHub App token used for authenticated git and gh operations.
     [Parameter(Mandatory = $true)]
     [string]$Token,
+    # Pull request number used for preview path and comment targeting.
     [Parameter(Mandatory = $true)]
     [int]$PullRequestNumber,
+    # Public preview URL for PR comments and environment metadata.
     [Parameter(Mandatory = $true)]
     [string]$PreviewUrl,
+    # Full path to the built static site directory.
     [Parameter(Mandatory = $true)]
     [string]$BuildDirectory,
+    # Working directory used to clone gh-pages.
     [string]$PagesDirectory = '_pages',
+    # Branch used as the Pages source branch.
     [string]$BaseBranch = 'gh-pages'
 )
 

.github/scripts/docs/Publish-LiveDocs.ps1

@@ -1,6 +1,22 @@
+#Requires -Version 7.0
+
+<#
+    .SYNOPSIS
+    Sets the site_url field in a Zensical configuration file.
+
+    .DESCRIPTION
+    Replaces the existing top-level site_url assignment in the provided
+    zensical.toml file so workflow builds use the expected canonical URL.
+
+    .EXAMPLE
+    ./Set-ZensicalSiteUrl.ps1 -ConfigPath "$PWD/src/zensical.toml" -SiteUrl "https://psmodule.io/docs/previews/pr-42/"
+#>
+[CmdletBinding()]
 param(
+    # Full path to the Zensical config file.
     [Parameter(Mandatory = $true)]
     [string]$ConfigPath,
+    # Canonical URL to write to site_url.
     [Parameter(Mandatory = $true)]
     [string]$SiteUrl
 )