Add support for custom templates + customizations

Actions/AL-Go-Helper.ps1

@@ -13,13 +13,15 @@ $errorActionPreference = "Stop"; $ProgressPreference = "SilentlyContinue"; Set-S
 $ALGoFolderName = '.AL-Go'
 $ALGoSettingsFile = Join-Path '.AL-Go' 'settings.json'
 $RepoSettingsFile = Join-Path '.github' 'AL-Go-Settings.json'
+$IndirectTemplateRepoSettingsFile = Join-Path '.github' 'templateRepoSettings.json'
+$IndirectTemplateProjectSettingsFile = Join-Path '.github' 'templateProjectSettings.json'
 [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'defaultCICDPushBranches', Justification = 'False positive.')]
 $defaultCICDPushBranches = @( 'main', 'release/*', 'feature/*' )
 [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'defaultCICDPullRequestBranches', Justification = 'False positive.')]
 $defaultCICDPullRequestBranches = @( 'main' )
 $runningLocal = $local.IsPresent
 $defaultBcContainerHelperVersion = "preview" # Must be double quotes. Will be replaced by BcContainerHelperVersion if necessary in the deploy step - ex. "https://github.com/organization/navcontainerhelper/archive/refs/heads/branch.zip"
-$notSecretProperties = @("Scopes","TenantId","BlobName","ContainerName","StorageAccountName","ServerUrl","ppUserName","GitHubAppClientId")
+$notSecretProperties = @("Scopes","TenantId","BlobName","ContainerName","StorageAccountName","ServerUrl","ppUserName","GitHubAppClientId","EnvironmentName")
 
 $runAlPipelineOverrides = @(
     "DockerPull"
@@ -38,6 +40,8 @@ $runAlPipelineOverrides = @(
     "InstallMissingDependencies"
     "PreCompileApp"
     "PostCompileApp"
+    "PipelineInitialize"
+    "PipelineFinalize"
 )
 
 # Well known AppIds
@@ -500,6 +504,10 @@ function MergeCustomObjectIntoOrderedDictionary {
             if ($srcPropType -eq "PSCustomObject" -and $dstPropType -eq "OrderedDictionary") {
                 MergeCustomObjectIntoOrderedDictionary -dst $dst."$prop" -src $srcProp
             }
+            elseif ($dstProp -is [String] -and $srcProp -is [Object[]]) {
+                # For properties like "runs-on", which is a string, you can specify an array in settings, which gets joined with a comma
+                $dst."$prop" = $srcProp -join ', '
+            }
             elseif ($dstPropType -ne $srcPropType -and !($srcPropType -eq "Int64" -and $dstPropType -eq "Int32")) {
                 # Under Linux, the Int fields read from the .json file will be Int64, while the settings defaults will be Int32
                 # This is not seen as an error and will not throw an error
@@ -535,8 +543,10 @@ function MergeCustomObjectIntoOrderedDictionary {
 # Read settings from the settings files
 # Settings are read from the following files:
 # - ALGoOrgSettings (github Variable)                 = Organization settings variable
+# - .github/templateRepoSettings.json                 = Repository settings from indirect template
 # - .github/AL-Go-Settings.json                       = Repository Settings file
 # - ALGoRepoSettings (github Variable)                = Repository settings variable
+# - .github/templateProjectSettings.json              = Project settings from indirect template
 # - <project>/.AL-Go/settings.json                    = Project settings file
 # - .github/<workflowName>.settings.json              = Workflow settings file
 # - <project>/.AL-Go/<workflowName>.settings.json     = Project workflow settings file
@@ -591,6 +601,7 @@ function ReadSettings {
     $settings = [ordered]@{
         "type"                                          = "PTE"
         "unusedALGoSystemFiles"                         = @()
+        "customALGoSystemFiles"                         = @()
         "projects"                                      = @()
         "powerPlatformSolutionFolder"                   = ""
         "country"                                       = "us"
@@ -733,6 +744,9 @@ function ReadSettings {
         $settingsObjects += @($orgSettingsVariableObject)
     }
     # Read settings from repository settings file
+    $indirectTemplateRepoSettingsObject = GetSettingsObject -Path (Join-Path $baseFolder $IndirectTemplateRepoSettingsFile)
+    $settingsObjects += @($indirectTemplateRepoSettingsObject)
+    # Read settings from repository settings file
     $repoSettingsObject = GetSettingsObject -Path (Join-Path $baseFolder $RepoSettingsFile)
     $settingsObjects += @($repoSettingsObject)
     # Read settings from repository settings variable (parameter)
@@ -741,6 +755,9 @@ function ReadSettings {
         $settingsObjects += @($repoSettingsVariableObject)
     }
     if ($project) {
+        # Read settings from repository settings file
+        $indirectTemplateProjectSettingsObject = GetSettingsObject -Path (Join-Path $baseFolder $IndirectTemplateProjectSettingsFile)
+        $settingsObjects += @($indirectTemplateProjectSettingsObject)
         # Read settings from project settings file
         $projectFolder = Join-Path $baseFolder $project -Resolve
         $projectSettingsObject = GetSettingsObject -Path (Join-Path $projectFolder $ALGoSettingsFile)

Actions/AL-Go-TestRepoHelper.ps1

@@ -1,4 +1,6 @@
-function Test-Property {
+. (Join-Path $PSScriptRoot "AL-Go-Helper.ps1")
+
+function Test-Property {
     Param(
         [HashTable] $json,
         [string] $settingsDescription,
@@ -174,13 +176,16 @@ function TestALGoRepository {
     # Test .json files are formatted correctly
     # Get-ChildItem needs -force to include folders starting with . (e.x. .github / .AL-Go) on Linux
     Get-ChildItem -Path $baseFolder -Filter '*.json' -Recurse -Force | ForEach-Object {
-        if ($_.Directory.Name -eq '.AL-Go' -and $_.BaseName -eq 'settings') {
+        if ($_.Directory.Name -eq ([System.IO.Path]::GetDirectoryName($ALGoSettingsFile)) -and $_.Name -eq ([System.IO.Path]::GetFileName($ALGoSettingsFile))) {
             Test-JsonFile -jsonFile $_.FullName -baseFolder $baseFolder -type 'Project'
         }
-        elseif ($_.Directory.Name -eq '.github' -and $_.BaseName -like '*ettings') {
-            if ($_.BaseName -eq 'AL-Go-Settings') {
+        elseif ($_.Directory.Name -eq ([System.IO.Path]::GetDirectoryName($RepoSettingsFile)) -and $_.BaseName -like '*ettings') {
+            if ($_.Name -eq ([System.IO.Path]::GetFileName($RepoSettingsFile)) -or $_.Name -eq ([System.IO.Path]::GetFileName($IndirectTemplateRepoSettingsFile))) {
                 $type = 'Repo'
             }
+            elseif ($_.Name -eq ([System.IO.Path]::GetFileName($IndirectTemplateProjectSettingsFile))) {
+                $type = 'Project'
+            }
             else {
                 $type = 'Workflow'
             }

Actions/CheckForUpdates/CheckForUpdates.HelperFunctions.ps1

@@ -1,3 +1,17 @@
+function GetCustomizationAnchors {
+    return @{
+        "_BuildALGoProject.yaml" = @{
+            "BuildALGoProject" = @(
+                @{ "Step" = 'Read settings'; "Before" = $false }
+                @{ "Step" = 'Read secrets'; "Before" = $false }
+                @{ "Step" = 'Build'; "Before" = $true }
+                @{ "Step" = 'Build'; "Before" = $false }
+                @{ "Step" = 'Cleanup'; "Before" = $true }
+            )
+        }
+    }
+}
+
 <#
 .SYNOPSIS
 Downloads a template repository and returns the path to the downloaded folder
@@ -446,7 +460,7 @@ function IsDirectALGo {
 
 function GetSrcFolder {
     Param(
-        [hashtable] $repoSettings,
+        [string] $repoType,
         [string] $templateUrl,
         [string] $templateFolder,
         [string] $srcPath
@@ -458,7 +472,7 @@ function GetSrcFolder {
         return ''
     }
     if (IsDirectALGo -templateUrl $templateUrl) {
-        switch ($repoSettings.type) {
+        switch ($repoType) {
             "PTE" {
                 $typePath = "Per Tenant Extension"
             }
@@ -488,33 +502,139 @@ function GetSrcFolder {
 function UpdateSettingsFile {
     Param(
         [string] $settingsFile,
-        [hashtable] $updateSettings,
-        [hashtable] $additionalSettings = @{}
+        [hashtable] $updateSettings
     )
 
+    $modified = $false
     # Update Repo Settings file with the template URL
     if (Test-Path $settingsFile) {
         $settings = Get-Content $settingsFile -Encoding UTF8 | ConvertFrom-Json
     }
     else {
         $settings = [PSCustomObject]@{}
+        $modified = $true
     }
     foreach($key in $updateSettings.Keys) {
         if ($settings.PSObject.Properties.Name -eq $key) {
-            $settings."$key" = $updateSettings."$key"
+            if ($settings."$key" -ne $updateSettings."$key") {
+                $settings."$key" = $updateSettings."$key"
+                $modified = $true
+            }
         }
         else {
             # Add the property if it doesn't exist
             $settings | Add-Member -MemberType NoteProperty -Name "$key" -Value $updateSettings."$key"
+            $modified = $true
         }
     }
-    # Grab settings from additionalSettings if they are not already in settings
-    foreach($key in $additionalSettings.Keys) {
-        if (!($settings.PSObject.Properties.Name -eq $key)) {
-            # Add the property if it doesn't exist
-            $settings | Add-Member -MemberType NoteProperty -Name "$key" -Value $additionalSettings."$key"
+    if ($modified) {
+        # Save the file with LF line endings and UTF8 encoding
+        $settings | Set-JsonContentLF -path $settingsFile
+    }
+    return $modified
+}
+
+function GetCustomALGoSystemFiles {
+    Param(
+        [string] $baseFolder,
+        [hashtable] $settings,
+        [string[]] $projects
+    )
+
+    function YieldItem{
+        Param(
+            [string] $baseFolder,
+            [string] $source,
+            [string] $destination,
+            [string[]] $projects
+        )
+
+        if ($destination -like ".AL-Go$([IO.Path]::DirectorySeparatorChar)*") {
+            $destinations = $projects | ForEach-Object { Join-Path $_ $destination }
+        }
+        else {
+            $destinations = @($destination)
+        }
+        $destinations | ForEach-Object {
+            Write-Host "- $_"
+            $content = Get-ContentLF -Path $source
+            $existingFile = Join-Path $baseFolder $_
+            $existingContent = ''
+            if (Test-Path -Path $existingFile) {
+                $existingContent = Get-ContentLF -Path $existingFile
+            }
+            if ($content -ne $existingContent) {
+                Write-Output @{ "DstFile" = $_; "content" = $content }
+            }
+        }
+    }
+
+    if ($settings.customALGoSystemFiles -isnot [Array]) {
+        throw "customALGoSystemFiles setting is wrongly formatted, must be an array of objects. See https://aka.ms/algosettings#customalgosystemfiles."
+    }
+    foreach($customspec in $settings.customALGoSystemFiles) {
+        if ($customspec -isnot [Hashtable]) {
+            throw "customALGoSystemFiles setting is wrongly formatted, must be an array of objects. See https://aka.ms/algosettings#customalgosystemfiles."
+        }
+        if (!($customSpec.ContainsKey('Source') -and $customSpec.ContainsKey('Destination'))) {
+            throw "customALGoSystemFiles setting is wrongly formatted, Source and Destination must be specified. See https://aka.ms/algosettings#customalgosystemfiles."
+        }
+        $source = $customspec.Source
+        $destination = $customSpec.Destination.Replace('/',[IO.Path]::DirectorySeparatorChar).Replace('\',[IO.Path]::DirectorySeparatorChar)
+        if ($destination -isnot [string] -or $destination -eq '') {
+            throw "customALGoSystemFiles setting is wrongly formatted, Destination must be a string, which isn't blank. See https://aka.ms/algosettings#customalgosystemfiles."
+        }
+        if ($source -isnot [string] -or $source -notlike 'https://*' -or (-not [System.Uri]::IsWellFormedUriString($source,1))) {
+            throw "customALGoSystemFiles setting is wrongly formatted, Source must secure download URL. See https://aka.ms/algosettings#customalgosystemfiles."
+        }
+
+        $tempFolder = Join-Path ([System.IO.Path]::GetTempPath()) ([Guid]::NewGuid().ToString())
+        New-Item -Path $tempFolder -ItemType Directory | Out-Null
+        $ext = [System.IO.Path]::GetExtension($source)
+        $zipName = "$tempFolder$ext"
+        try {
+            if ($ext -eq '.zip') {
+                Write-Host "$($destination):"
+                if ($customSpec.ContainsKey('FileSpec')) { $fileSpec = $customSpec.FileSpec } else { $fileSpec = '*' }
+                if ($customSpec.ContainsKey('Recurse')) { $recurse = $customSpec.Recurse } else { $recurse = $true }
+                if ($fileSpec -isnot [string] -or $recurse -isnot [boolean]) {
+                    throw "customALGoSystemFiles setting is wrongly formatted, fileSpec must be string and Recurse must be boolean. See https://aka.ms/algosettings#customalgosystemfiles."
+                }
+                if (!($destination.EndsWith('/') -or $destination.EndsWith('\'))) {
+                    throw "customALGoSystemFiles setting is wrongly formatted, destination must be a folder (terminated with / or \). See https://aka.ms/algosettings#customalgosystemfiles."
+                }
+                Invoke-RestMethod -UseBasicParsing -Method Get -Uri $source -OutFile $zipName
+                Expand-Archive -Path $zipName -DestinationPath $tempFolder -Force
+                $subFolder = Join-Path $tempFolder ([System.IO.Path]::GetDirectoryName($fileSpec)) -Resolve
+                Push-Location -Path $subFolder
+                try {
+                    Get-ChildItem -Path $subFolder -Filter ([System.IO.Path]::GetFileName($fileSpec)) -Recurse:$recurse -File | ForEach-Object {
+                        $destRelativeFileName = Resolve-Path $_.FullName -Relative
+                        $destFileName = Join-Path $destination $destRelativeFileName
+                        $destFileName = $destFileName.TrimStart('\/')
+                        YieldItem -baseFolder $baseFolder -source $_.FullName -destination $destFileName -projects $projects
+                    }
+                }
+                finally {
+                    Pop-Location
+                }
+            }
+            else {
+                if ($customSpec.ContainsKey('FileSpec') -or $customSpec.ContainsKey('Recurse')) {
+                    throw "customALGoSystemFiles setting is wrongly formatted, FileSpec and Recurse are only allowed with .zip files. See https://aka.ms/algosettings#customalgosystemfiles."
+                }
+                if ($destination.endsWith([IO.Path]::DirectorySeparatorChar)) {
+                    $destination = Join-Path $destination ([System.IO.Path]::GetFileName($source))
+                }
+                Write-Host "$($destination):"
+                $tempFilename = Join-Path $tempFolder ([System.IO.Path]::GetFileName($source))
+                Invoke-RestMethod -UseBasicParsing -Method Get -Uri $source -OutFile $tempFilename
+                YieldItem -baseFolder $baseFolder -source $tempFilename -destination $destination -projects $projects
+            }
+        }
+        finally {
+            if (Test-Path -Path $zipName) { Remove-Item $zipName -Force }
+            Remove-Item -Path $tempFolder -Recurse -Force
         }
     }
-    # Save the file with LF line endings and UTF8 encoding
-    $settings | Set-JsonContentLF -path $settingsFile
 }