Update Package-Toolkit.ps1 to support preview deployment files

src/optimization-engine/package-manifest.json

@@ -1,20 +1,20 @@
 {
-    "deploySubDir": "optimization-engine/latest",
-    "deploySubDirVersioned": "optimization-engine/{version}",
-    "deployFiles": [
-        {
-            "source": "azuredeploy.bicep",
-            "destination": "azuredeploy.bicep"
-        },
-        {
-            "source": "azuredeploy-nested.bicep",
-            "destination": "azuredeploy-nested.bicep"
-        }
+  "deployment": {
+    "files": [
+      {
+        "source": "azuredeploy.bicep",
+        "destination": "azuredeploy.bicep"
+      },
+      {
+        "source": "azuredeploy-nested.bicep",
+        "destination": "azuredeploy-nested.bicep"
+      }
     ],
-    "deployDirectories": [
-        {
-            "source": "runbooks",
-            "destination": "runbooks"
-        }
+    "directories": [
+      {
+        "source": "runbooks",
+        "destination": "runbooks"
+      }
     ]
-}
+  }
+}

src/scripts/Package-Toolkit.ps1

@@ -17,6 +17,9 @@
     .PARAMETER PowerBI
     Optional. Indicates whether to open Power BI files as part of the packaging process. Default = false.
 
+    .PARAMETER Preview
+    Optional. Indicates that the template(s) should be saved as a preview only. Does not package other files. Default = false.
+
     .EXAMPLE
     ./Package-Toolkit
 
@@ -35,7 +38,8 @@
 Param(
     [Parameter(Position = 0)][string]$Template = "*",
     [switch]$Build,
-    [switch]$PowerBI
+    [switch]$PowerBI,
+    [switch]$Preview
 )
 
 # Use the debug flag from common parameters to determine whether to run in debug mode
@@ -60,142 +64,140 @@ if ($Template -ne "*" -and -not (Test-Path $relDir))
 
 # Package templates
 $version = & "$PSScriptRoot/Get-Version"
-Write-Host "Packaging v$version templates..."
+Write-Host "Packaging $(if ($Template) { "$Template v$version template" } else { "v$version templates" })..."
 
 $isPrerelease = $version -like '*-*'
 
 Write-Verbose "Removing existing ZIP files..."
 Remove-Item "$relDir/*.zip" -Force
 
-$templates = Get-ChildItem $relDir -Directory `
+$templates = Get-ChildItem "$relDir/$Template*" -Directory `
 | ForEach-Object {
     Write-Verbose ("Packaging $_" -replace (Get-Item $relDir).FullName, '.')
-    $path = $_
-    $versionSubFolder = (Join-Path $path $version)
-    $zip = Join-Path (Get-Item $relDir) "$($path.Name)-v$version.zip"
+    $srcPath = $_
+    $templateName = $srcPath.Name
+    $versionSubFolder = (Join-Path $srcPath $version)
+    $zip = Join-Path (Get-Item $relDir) "$templateName-v$version.zip"
 
     Write-Verbose "Checking for a nested version folder: $versionSubFolder"
     if ((Test-Path -Path $versionSubFolder -PathType Container) -eq $true)
     {
         Write-Verbose "  Switching to sub folder"
-        $path = $versionSubFolder
+        $srcPath = $versionSubFolder
     }
 
     # Skip if template is a Bicep Registry module
     Write-Verbose "Checking version.json to see if it's targeting the Bicep Registry"
-    if (Test-Path $path/version.json)
+    if (Test-Path $srcPath/version.json)
     {
-        $versionSchema = (Get-Content "$path\version.json" -Raw | ConvertFrom-Json | Select-Object -ExpandProperty '$schema')
+        $versionSchema = (Get-Content "$srcPath\version.json" -Raw | ConvertFrom-Json | Select-Object -ExpandProperty '$schema')
         if ($versionSchema -like '*bicep-registry-module*')
         {
             Write-Verbose "Skipping Bicep Registry module (not included in releases)"
             return
         }
     }
 
-    Write-Verbose "Updating $($path.Name) deployment file in docs..."
+    Write-Verbose "Updating $templateName deployment files in docs..."
 
-    $packageManifestPath = "$path/package-manifest.json"
-    if (Test-Path $packageManifestPath)
+    function Copy-DeploymentFiles($suffix)
     {
-        $packageManifest = Get-Content $packageManifestPath -Raw | ConvertFrom-Json
-        $docsDeployDir = $deployDir
-        if ($packageManifest.deploySubDir)
-        {
-            $docsDeployDir = "$deployDir/$($packageManifest.deploySubDir)"
-            & "$PSScriptRoot/New-Directory" $docsDeployDir
-        }
-        if ($packageManifest.deploySubDirVersioned)
-        {
-            $docsDeployDirVersioned = "$deployDir/$($packageManifest.deploySubDirVersioned.Replace('{version}', $version))"
-            & "$PSScriptRoot/New-Directory" $docsDeployDirVersioned
-        }
-        foreach ($file in $packageManifest.deployFiles)
+        $packageManifestPath = "$srcPath/package-manifest.json"
+        if (Test-Path $packageManifestPath)
         {
-            Copy-Item "$path/$($file.source)" "$docsDeployDir/$($file.destination.Replace('{version}', $version))"
-            if ($packageManifest.deploySubDirVersioned)
-            {
-                Copy-Item "$path/$($file.source)" "$docsDeployDirVersioned/$($file.destination.Replace('{version}', $version))"
+            # Read files/directories from package-manifest.json
+            $packageManifest = Get-Content $packageManifestPath -Raw | ConvertFrom-Json
+
+            # Create release directory
+            $targetDir = "$deployDir/$templateName/$suffix"
+            & "$PSScriptRoot/New-Directory" $targetDir
+
+            # Copy files and directories
+            $packageManifest.deployment.Files | ForEach-Object { Copy-Item "$srcPath/$($_.source)" "$targetDir/$($_.destination)" -Force }
+            $packageManifest.deployment.Directories | ForEach-Object {
+                & "$PSScriptRoot/New-Directory" "$targetDir/$($_.destination)"
+                Get-ChildItem "$srcPath/$($_.source)" | Copy-Item -Destination "$targetDir/$($_.destination)" -Recurse -Force
             }
         }
-        foreach ($directory in $packageManifest.deployDirectories)
+        else
         {
-            & "$PSScriptRoot/New-Directory" "$($docsDeployDir)/$($directory.destination)"
-            Get-ChildItem "$path/$($directory.source)" | Copy-Item -Destination "$($docsDeployDir)/$($directory.destination)" -Recurse -Force
-            if ($packageManifest.deploySubDirVersioned)
-            {
-                & "$PSScriptRoot/New-Directory" "$($docsDeployDirVersioned)/$($directory.destination)"
-                Get-ChildItem "$path/$($directory.source)" | Copy-Item -Destination "$($docsDeployDirVersioned)/$($directory.destination)" -Recurse -Force
-            }
+            # Copy azuredeploy.json to docs/deploy folder
+            Copy-Item "$srcPath/azuredeploy.json" "$deployDir/$templateName-$suffix.json"
+            Copy-Item "$srcPath/createUiDefinition.json" "$deployDir/$templateName-$suffix.ui.json"
         }
     }
+
+    if ($Preview)
+    {
+        Copy-DeploymentFiles "preview"
+    }
     else
     {
-        # TODO include this fallback logic in a fallback package-manifest.json file
-        # Copy azuredeploy.json to docs/deploy folder
-        Copy-Item "$path/azuredeploy.json" "$deployDir/$($path.Name)-$version.json"
-        Copy-Item "$path/azuredeploy.json" "$deployDir/$($path.Name)-latest.json"
-        Copy-Item "$path/createUiDefinition.json" "$deployDir/$($path.Name)-$version.ui.json"
-        Copy-Item "$path/createUiDefinition.json" "$deployDir/$($path.Name)-latest.ui.json"
+        Copy-DeploymentFiles $version
+        Copy-DeploymentFiles "latest"
     }
 
-    Write-Verbose ("Compressing $path to $zip" -replace (Get-Item $relDir).FullName, '.')
-    Compress-Archive -Path "$path/*" -DestinationPath $zip
+    Write-Verbose ("Compressing $srcPath to $zip" -replace (Get-Item $relDir).FullName, '.')
+    Compress-Archive -Path "$srcPath/*" -DestinationPath $zip
     return $zip
 }
-Write-Host "✅ $($templates.Count) templates"
+Write-Host "✅ $($templates.Count) template$(if ($templates.Count -ne 1) { 's' })"
 Write-Host "ℹ️ Deployment files updated... Please commit the changes manually..."
 
-# Copy open data files
-Write-Verbose "Copying open data files..."
-Copy-Item "$PSScriptRoot/../open-data/*.csv" $relDir
-Copy-Item "$PSScriptRoot/../open-data/*.json" $relDir
-Write-Host "✅ $((@(Get-ChildItem "$relDir/*.csv") + @(Get-ChildItem "$relDir/*.json")).Count) open data files"
-
-# Package sample data files together
-Write-Verbose "Packaging open data files..."
-Get-ChildItem -Path "$PSScriptRoot/../open-data" -Directory `
-| ForEach-Object {
-    $dir = $_
-    Compress-Archive -Path "$dir/*.*" -DestinationPath "$relDir/$($dir.BaseName).zip"
-    Write-Host "✅ $((Get-ChildItem "$dir/*.*").Count) $($dir.BaseName) files"
-}
-
-# Copy PBIX files
-Write-Verbose "Copying PBIX files..."
-Copy-Item "$PSScriptRoot/../power-bi/*.pbix" $relDir -Force
-Write-Host "✅ $((Get-ChildItem "$PSScriptRoot/../power-bi/*.pbix").Count) PBIX files"
-
-# Open Power BI projects
-$pbi = Get-ChildItem "$PSScriptRoot/../power-bi/*.pbip"
-if ($PowerBI)
-{
-    Write-Host "ℹ️ $($pbi.Count) Power BI projects must be converted manually... Opening..."
-    $pbi | Invoke-Item
-}
-elseif ($isPrerelease)
-{
-    Write-Host "✖️ Skipping $($pbi.Count) Power BI projects for prerelease version"
-}
-else
-{
-    Write-Host "⚠️ $($pbi.Count) Power BI projects must be converted manually!"
-    Write-Host '     To open them, run: ' -NoNewline
-    Write-Host './Package-Toolkit -PowerBI' -ForegroundColor Cyan
-}
-
-# Update version in docs
-$docVersionPath = "$PSScriptRoot/../../docs/_includes/ftkver.txt"
-$versionInDocs = Get-Content $docVersionPath -Raw
-if ($versionInDocs -eq $version)
-{
-    Write-Host "✅ Version in docs ($versionInDocs) already up-to-date"
-}
-else
+# Only package remaining files if not preview
+if (-not $Preview)
 {
-    Write-Verbose "Updating version in docs..."
-    $version | Out-File $docVersionPath -NoNewline
-    Write-Host "ℹ️ Version updated in docs... Please commit the changes manually..."
+    # Copy open data files
+    Write-Verbose "Copying open data files..."
+    Copy-Item "$PSScriptRoot/../open-data/*.csv" $relDir
+    Copy-Item "$PSScriptRoot/../open-data/*.json" $relDir
+    Write-Host "✅ $((@(Get-ChildItem "$relDir/*.csv") + @(Get-ChildItem "$relDir/*.json")).Count) open data files"
+
+    # Package sample data files together
+    Write-Verbose "Packaging open data files..."
+    Get-ChildItem -Path "$PSScriptRoot/../open-data" -Directory `
+    | ForEach-Object {
+        $dir = $_
+        Compress-Archive -Path "$dir/*.*" -DestinationPath "$relDir/$($dir.BaseName).zip"
+        Write-Host "✅ $((Get-ChildItem "$dir/*.*").Count) $($dir.BaseName) files"
+    }
+
+    # Copy PBIX files
+    Write-Verbose "Copying PBIX files..."
+    Copy-Item "$PSScriptRoot/../power-bi/*.pbix" $relDir -Force
+    Write-Host "✅ $((Get-ChildItem "$PSScriptRoot/../power-bi/*.pbix").Count) PBIX files"
+
+    # Open Power BI projects
+    $pbi = Get-ChildItem "$PSScriptRoot/../power-bi/*.pbip"
+    if ($PowerBI)
+    {
+        Write-Host "ℹ️ $($pbi.Count) Power BI projects must be converted manually... Opening..."
+        $pbi | Invoke-Item
+    }
+    elseif ($isPrerelease)
+    {
+        Write-Host "✖️ Skipping $($pbi.Count) Power BI projects for prerelease version"
+    }
+    else
+    {
+        Write-Host "⚠️ $($pbi.Count) Power BI projects must be converted manually!"
+        Write-Host '     To open them, run: ' -NoNewline
+        Write-Host './Package-Toolkit -PowerBI' -ForegroundColor Cyan
+    }
+
+    # Update version in docs
+    $docVersionPath = "$PSScriptRoot/../../docs/_includes/ftkver.txt"
+    $versionInDocs = Get-Content $docVersionPath -Raw
+    if ($versionInDocs -eq $version)
+    {
+        Write-Host "✅ Version in docs ($versionInDocs) already up-to-date"
+    }
+    else
+    {
+        Write-Verbose "Updating version in docs..."
+        $version | Out-File $docVersionPath -NoNewline
+        Write-Host "ℹ️ Version updated in docs... Please commit the changes manually..."
+    }
 }
 
 Write-Host '...done!'

src/scripts/README.md

@@ -311,11 +311,12 @@ Example:
 
 [Package-Toolkit.ps1](./Package-Toolkit.ps1) packages all toolkit templates as ZIP files for release.
 
-| Parameter   | Description                                                                                           |
-| ----------- | ----------------------------------------------------------------------------------------------------- |
-| `‑Template` | Optional. Name of the template or module to package. Default = \* (all).                              |
-| `‑Build`    | Optional. Indicates whether the Build-Toolkit command should be executed first. Default = false.      |
-| `‑PowerBI`  | Optional. Indicates whether to open Power BI files as part of the packaging process. Default = false. |
+| Parameter   | Description                                                                                                                |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `‑Template` | Optional. Name of the template or module to package. Default = \* (all).                                                   |
+| `‑Build`    | Optional. Indicates whether the Build-Toolkit command should be executed first. Default = false.                           |
+| `‑PowerBI`  | Optional. Indicates whether to open Power BI files as part of the packaging process. Default = false.                      |
+| `‑Preview`  | Optional. Indicates that the template(s) should be saved as a preview only. Does not package other files. Default = false. |
 
 Examples:
 
@@ -329,6 +330,11 @@ Examples:
 
   ```powershell
   ./Package-Toolkit -Build
+
+- Builds the latest version of a specific template and updates the deployment files for the website.
+
+  ```powershell
+  ./Package-Toolkit governance-workbook -Build -Preview
   ```
 
 <br>