Nightly build artifact script

docs/installing-nightly.md

@@ -0,0 +1,177 @@
+# Installing the "Nightly" build of DSC CLI
+
+> [!NOTE]
+> Nightly builds contain the latest development features but may have bugs or breaking changes.
+> Only install if you want to test unreleased functionality. If you encounter issues, please
+> [open an issue](https://github.com/PowerShell/DSC/issues/new).
+
+## Using a script
+
+> [!NOTE]
+> This script requires the [GitHub CLI](https://cli.github.com/) to have already been installed.
+
+### DSC CLI
+
+This will install the latest nightly DSC CLI binary to the following location depending on your
+platform:
+
+- **Windows**: `%LOCALAPPDATA%\dsc\dsc.exe`
+- **Linux/macOS**: `~/.dsc/bin/dsc`
+
+1. Retrieve the appropriate script. You can use the PowerShell script for Windows and the Bash script for Linux and macOS.
+
+   - Bash (Linux and macOS):
+
+     ```sh
+     curl -o https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.sh
+     ```
+
+   - PowerShell (Windows):
+
+     ```powershell
+     Invoke-WebRequest -Uri https://raw.githubusercontent.com/PowerShell/DSC/refs/heads/main/sharedScripts/install_cli_nightly.ps1 -OutFile install_cli_nightly.ps1
+     ```
+
+1. Review the script before invoking it.
+1. Invoke the script to install `dsc`:
+
+   - Bash (Linux and macOS):
+
+     ```sh
+     ./install_cli_nightly.sh
+     ```
+
+   - PowerShell (Windows):
+
+     ```powershell
+     ./install_cli_nightly.ps1
+     ```
+
+1. Add the installation directory to your `PATH` environment variable.
+
+## Manual
+
+We don't currently publish nightly releases, but you can get the latest builds by viewing the most
+recent Action workflows for the `main` branch.
+
+The easiest way to get these artifacts is through the GitHub site. The following link directs you
+to the latest successful Action workflows for merges to the `main` branch:
+
+<https://github.com/PowerShell/DSC/actions?query=workflow%3ARust+is%3Asuccess+branch%3Amain+event%3Apush>
+
+Select the first link in the list to show the related artifacts. At the bottom of the page,
+download the artifact by selecting the artifact for your platform:
+
+- `windows-bin` for Windows
+- `linux-bin` for Linux
+- `macos-bin` for macOS
+
+Extract the archive using the following steps:
+
+- The artifact will be downloaded as `<platform>-bin.zip`. You can invoke the following commands to
+  extract the contents into a folder called `dsc` in the current directory:
+
+  - Bash (Linux, macOS)
+
+    ```sh
+    # Be sure to set this to the appropriate platform: 'linux' or 'macos'
+    platform="linux"
+    artifact="$platform-bin.zip"
+    # requires `unzip`, install if needed to expand the zip file
+    unzip $artifact
+    # Expand the tar file
+    tar -xvf bin.tar
+    # Move the subfolder containing the binaries and manifests
+    mv ./bin/debug dsc
+    ```
+
+  - PowerShell (Linux, macOS, Windows):
+
+    ```powershell
+    # Be sure to set this to the appropriate platform: 'linux', 'macos', or 'windows'
+    $platform = 'linux'
+    $artifact = "$platform-bin.zip"
+    # Expand the zip file
+    Expand-Archive -Path $artifact -DestinationPath .
+    # Expand the tar file
+    tar -xvf bin.tar
+    # Move the subfolder containing the binaries and manifests
+    Move-Item -Path ./bin/debug -Destination dsc
+    ```
+
+- Optionally, you can clean up the downloaded archive and intermediary files and folders:
+
+  - Bash (Linux, macOS)
+
+    ```sh
+    rm -rf ./bin ./bin.tar ./linux-bin.zip
+    ```
+
+  - PowerShell (Linux, macOS, Windows)
+
+    ```powershell
+    Remove-Item -Path ./$artifact, ./bin.tar, ./bin -Recurse -Force
+    ```
+
+- Finally, make sure to add the folder containing the extracted binaries and resource manifests to
+  your `PATH` environmental variable
+
+## Advanced script options
+
+### CLI installation options
+
+- Install to a custom directory:
+
+  - Bash (Linux, macOS):
+
+    ```bash
+    install_cli_nightly.sh --install-path /usr/local/bin
+    ```
+
+  - PowerShell (Windows):
+
+    ```powershell
+    install_cli_nightly.ps1 -InstallPath C:\tools\dsc
+    ```
+
+- Install from a forking repository:
+
+  - Bash (Linux, macOS):
+
+    ```bash
+    install_cli_nightly.sh --repo myusername/DSC
+    ```
+
+  - PowerShell (Windows):
+
+    ```powershell
+    install_cli_nightly.ps1 -Repo myusername/DSC"
+    ```
+
+- Install from a branch other than `main`:
+
+  - Bash (Linux, macOS):
+
+    ```bash
+    install_cli_nightly.sh --branch feature-branch
+    ```
+
+  - PowerShell (Windows):
+
+    ```powershell
+    install_cli_nightly.ps1 -Branch feature-branch"
+    ```
+
+- Install from a specific GitHub Action run:
+
+  - Bash (Linux, macOS):
+
+    ```bash
+    install_cli_nightly.sh --run-id 6146657618
+    ```
+
+  - PowerShell (Windows):
+
+    ```powershell
+    install_cli_nightly.ps1 -RunId 6146657618"
+    ```

sharedScripts/install_cli_nightly.ps1

@@ -0,0 +1,136 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+<#
+    .SYNOPSIS
+    Install the latest build of DSC from a GitHub Actions run
+    .DESCRIPTION
+    This script installs a build of DSC from the artifact generated by a GitHub Actions run. The
+    artifact is retrieved as a `.zip` file containing a `.tar` archive with the required files.
+    The script retrieves the artifacts, extracts the contents, and then installs them to the `dsc`
+    folder in `LOCALAPPDATA`.
+    You can override the installation directory with the `-InstallPath` parameter.
+    By default, the script installs the artifact from the latest successful build on the `main`
+    branch in the `PowerShell/DSC` repository. You can select a different branch with the `-Branch`
+    parameter, a different repository with the `-Repo` parameter, and a specific run with the
+    `-RunId` parameter.
+    By default, the script removes the downloaded artifact archive and intermediary files and
+    folders. Use the `-NoClean` parameter to skip this cleanup step if needed.
+    This script requires the `gh` CLI and `tar` executable. If either tool isn't installed and
+    available, the script throws an error.
+    .PARAMETER InstallPath
+    Defines the folder to install DSC to. Defaults to the `dsc` folder in `LOCALAPPDATA`. Define
+    this value as the full path to an alternate location. The script will create the directory
+    path if it doesn't already exist.
+    .PARAMETER Branch
+    Defines which branch to retrieve the build artifact from. Defaults to `main`.
+    .PARAMETER Repo
+    Defines the repository to retrieve the build artifact from. Defaults to `PowerShell/DSC`.
+    Define this value with the user or organization followed by a forward slash and then the
+    repository name, like `SomeUserName/DSC`.
+    .PARAMETER RunId
+    Defines a specific GitHub Action run to retrieve the build artifact from. When this parameter
+    isn't specified, the script retrieves the build artifact from the latest successful build
+    agains the specified branch and repository.
+    .PARAMETER NoClean
+    By default, the script deletes the downloaded artifact and intermediary files and folders after
+    installing DSC to the specified path. Use this parameter to prevent the script from removing
+    these files and folders if needed.
+#>
+[cmdletbinding()]
+param(
+    [string]
+    $InstallPath = [System.IO.Path]::combine($env:LOCALAPPDATA, "dsc"),
+
+    [string]
+    $Branch = 'main',
+
+    [ValidatePattern('^\w+\/\w+$')]
+    [string]
+    $Repo = 'PowerShell/DSC',
+
+    [string]
+    $RunId,
+
+    [switch]
+    $NoClean
+)
+begin {
+    [string[]]$missing = @()
+    if (-not (Get-Command 'gh' -ErrorAction SilentlyContinue)) {
+        $missing += 'gh'
+    }
+    if (-not (Get-Command 'tar' -ErrorAction SilentlyContinue)) {
+        $missing += 'tar'
+    }
+    if ($missing.Count -gt 0) {
+        throw (@(
+            "This script requires the 'gh' CLI and 'tar' executable."
+            'Please install the missing tools before invoking the script again:'
+            "'$($missing -join "', '")'"
+        ) -join ' ')
+    }
+    if ([string]::IsNullOrEmpty($RunId)) {
+        $latestRunParameters = @(
+            '-R', $Repo
+            '--branch', $Branch
+            '--workflow', 'rust'
+            '--status', 'success'
+            '-L', 1
+            '--json', 'databaseId'
+            '-q', '.[0].databaseId'
+        )
+        $RunId = & gh run list @latestRunParameters
+        if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrEmpty($RunId)) {
+            throw "Unable to find a successful build to install from"
+        }
+    }
+    $tmpDir = [System.IO.Path]::combine(
+        [System.IO.Path]::GetTempPath(),
+        [System.IO.Path]::GetRandomFileName()
+    )
+    $installationFiles = Join-Path -Path $tmpDir -ChildPath 'bin' -AdditionalChildPath 'debug'
+    $dscExe = Join-Path $InstallPath "dsc.exe"
+}
+process {
+    $ErrorActionPreference = 'Stop'
+    #region    Download the artifact
+    $downloadArtifactParams = @(
+        '-R', $Repo
+        $RunId
+        '-n', "$platform-bin"
+        "--dir", $tmpDir
+    )
+    gh run download @downloadArtifactParams
+    if ($LASTEXITCODE -ne 0) {
+        throw "Unable to download artifact"
+    }
+    #endregion Download the artifact
+    #region    Expand the tar file
+    $tar = Get-ChildItem -Path $tmpDir | Select-Object -First 1
+    if ($null -eq $tar) {
+        throw "Failed to find downloaded artifact"
+    }
+    tar -xf $tar.FullName -C $tmpDir
+    if ($LASTEXITCODE -ne 0) {
+        throw "Unable to extract the tar file from the artifact"
+    }
+    #endregion Expand the tar file
+    #region    Move extracted files to the install directory
+    # Create the install directory if it doesn't exist
+    if (-not (Test-Path -Path $InstallPath -PathType Container)) {
+        $null = New-Item -ItemType Directory -Force -Path $InstallPath
+    }
+    Move-Item -Path "$installationFiles/*" -Destination $InstallPath -Force -ErrorAction Ignore
+    #endregion Copy extracted files to the install directory
+    #region    Retrieve and display version information
+    $versionStdout = & $dscExe --version; if(!$?) { throw }
+    $version = $versionStdout -replace 'dsc ', ''
+    Write-Information "Installed DSC CLI $version from https://github.com/$Repo/actions/runs/$RunId to $InstallPath"
+    #endregion Retrieve and display version information
+    Write-Information "Make sure to add $InstallPath to your PATH environment variable to use the 'dsc' command."
+}
+clean {
+    if (-not $NoClean) {
+        Remove-Item $tmpDir -Recurse
+    }
+}