20230719A

Author: hugoalh

README.md

@@ -93,6 +93,10 @@ Import-Module -Name 'hugoalh.GitHubActionsToolkit' -Prefix 'GitHubActions' -Scop
 
 ### Example
 
+```ps1
+Set-GitHubActionsOutput -Name 'foo' -Value 'bar'
+```
+
 ```ps1
 Write-GitHubActionNotice -Message 'Hello, world!'
 ```

hugoalh.GitHubActionsToolkit/hugoalh.GitHubActionsToolkit.psd1

@@ -3,7 +3,7 @@
 	RootModule = 'hugoalh.GitHubActionsToolkit.psm1'
 
 	# Version number of this module.
-	ModuleVersion = '1.6.0'
+	ModuleVersion = '1.7.0'
 
 	# Supported PSEditions
 	# CompatiblePSEditions = @()
@@ -70,6 +70,10 @@
 		'Add-StepSummaryLink',
 		'Add-StepSummarySubscriptText',
 		'Add-StepSummarySuperscriptText',
+		'Clear-FileCommand',
+		'Clear-Output',
+		'Clear-State',
+		'Clear-StepSummary',
 		'ConvertFrom-CsvM',
 		'ConvertFrom-CsvS',
 		'Disable-StdOutCommandEcho',
@@ -89,11 +93,11 @@
 		'Get-WebhookEventPayload',
 		'Get-WorkflowRunUri',
 		'Import-Artifact',
+		'Invoke-NodeJsWrapper',
 		'Invoke-ToolCacheToolDownloader',
 		'Register-ToolCacheDirectory',
 		'Register-ToolCacheFile',
 		'Remove-ProblemMatcher',
-		'Remove-StepSummary',
 		'Restore-Cache',
 		'Save-Cache',
 		'Set-EnvironmentVariable',
@@ -175,6 +179,10 @@
 		'Get-WebhookPayload',
 		'Get-WorkflowRunUrl',
 		'Import-Cache',
+		'Remove-FileCommand',
+		'Remove-Output',
+		'Remove-State',
+		'Remove-StepSummary',
 		'Restore-Artifact',
 		'Restore-State',
 		'Resume-CommandProcess',
@@ -266,7 +274,7 @@
 			ReleaseNotes = '(Please visit https://github.com/hugoalh-studio/ghactions-toolkit-powershell/releases.)'
 
 			# Prerelease string of this module
-			# Prerelease = ''
+			Prerelease = 'beta1'
 
 			# Flag to indicate whether the module requires explicit user acceptance for install/update/save
 			RequireLicenseAcceptance = $False

hugoalh.GitHubActionsToolkit/hugoalh.GitHubActionsToolkit.psm1

@@ -1,5 +1,5 @@
 #Requires -PSEdition Core -Version 7.2
-[String[]]$ModulesNames = @(
+[String[]]$ModulesName = @(
 	'artifact',
 	'cache',
 	'command-base',
@@ -16,14 +16,14 @@
 	'utility'
 )
 Import-Module -Name (
-	$ModulesNames |
+	$ModulesName |
 		ForEach-Object -Process { Join-Path -Path $PSScriptRoot -ChildPath 'module' -AdditionalChildPath "$_.psm1" }
 ) -Scope 'Local'
-[PSCustomObject[]]$PackageCommands = Get-Command -Module $ModulesNames -ListImported
-[String[]]$PackageCommandsFunctions = $PackageCommands |
+[PSCustomObject[]]$PackageCommands = Get-Command -Module $ModulesName -ListImported
+[String[]]$PackageFunctions = $PackageCommands |
 	Where-Object -FilterScript { $_.CommandType -ieq 'Function' } |
 	Select-Object -ExpandProperty 'Name'
-[String[]]$PackageCommandsAliases = $PackageCommands |
+[String[]]$PackageAliases = $PackageCommands |
 	Where-Object -FilterScript { $_.CommandType -ieq 'Alias' } |
 	Select-Object -ExpandProperty 'Name'
-Export-ModuleMember -Function $PackageCommandsFunctions -Alias $PackageCommandsAliases
+Export-ModuleMember -Function $PackageFunctions -Alias $PackageAliases

hugoalh.GitHubActionsToolkit/module/artifact.psm1

@@ -13,15 +13,15 @@ Export artifact to persist the data and/or share with the future jobs in the sam
 .PARAMETER Name
 Name of the artifact.
 .PARAMETER Path
-Paths of the files that need to export as artifact.
+Path of the files that need to export as artifact.
 .PARAMETER LiteralPath
-Literal paths of the files that need to export as artifact.
-.PARAMETER BaseRoot
-Absolute literal path of the base root directory of the files for control files structure.
-.PARAMETER ContinueOnIssue
+Literal path of the files that need to export as artifact.
+.PARAMETER RootDirectory
+Absolute literal path of the root directory of the files for control files structure.
+.PARAMETER ContinueOnError
 Whether the export should continue in the event of files fail to export; If not set and issue is encountered, export will stop and queued files will not export, the partial artifact availables which include files up until the issue; If set and issue is encountered, the issue file will ignore and skip, and queued files will still export, the partial artifact availables which include everything but exclude issue files.
-.PARAMETER RetentionTime
-Retention time of the artifact, by days.
+.PARAMETER RetentionDays
+Retention days of the artifact.
 .OUTPUTS
 [PSCustomObject] Metadata of the exported artifact.
 #>
@@ -32,36 +32,38 @@ Function Export-Artifact {
 		[Parameter(Mandatory = $True, Position = 0, ValueFromPipelineByPropertyName = $True)][String]$Name,
 		[Parameter(Mandatory = $True, ParameterSetName = 'Path', Position = 1, ValueFromPipelineByPropertyName = $True)][SupportsWildcards()][Alias('File', 'Files', 'Paths')][String[]]$Path,
 		[Parameter(Mandatory = $True, ParameterSetName = 'LiteralPath', ValueFromPipelineByPropertyName = $True)][Alias('LiteralFile', 'LiteralFiles', 'LiteralPaths', 'LP', 'PSPath', 'PSPaths')][String[]]$LiteralPath,
-		[Parameter(ValueFromPipelineByPropertyName = $True)][ValidateScript({ [System.IO.Path]::IsPathRooted($_) -and (Test-Path -LiteralPath $_ -PathType 'Container') }, ErrorMessage = '`{0}` is not an exist and valid directory!')][Alias('Root')][String]$BaseRoot = $Env:GITHUB_WORKSPACE,
-		[Parameter(ValueFromPipelineByPropertyName = $True)][Alias('ContinueOnError')][Switch]$ContinueOnIssue,
-		[Parameter(ValueFromPipelineByPropertyName = $True)][ValidateRange(1, [Int16]::MaxValue)][Alias('RetentionDay')][Int16]$RetentionTime
+		[Parameter(ValueFromPipelineByPropertyName = $True)][ValidateScript({ [System.IO.Path]::IsPathRooted($_) -and (Test-Path -LiteralPath $_ -PathType 'Container') }, ErrorMessage = '`{0}` is not an exist and valid directory!')][Alias('BaseRoot', 'Root')][String]$RootDirectory = $Env:GITHUB_WORKSPACE,
+		[Parameter(ValueFromPipelineByPropertyName = $True)][Alias('ContinueOnIssue')][Switch]$ContinueOnError,
+		[Parameter(ValueFromPipelineByPropertyName = $True)][ValidateRange(1, [Int16]::MaxValue)][Alias('RetentionDay', 'RetentionTime')][Int16]$RetentionDays
 	)
 	Process {
 		Switch ($PSCmdlet.ParameterSetName) {
 			'LiteralPath' {
-				[String[]]$PathsProceed = $LiteralPath |
-					ForEach-Object -Process { [System.IO.Path]::IsPathRooted($_) ? $_ : (Join-Path -Path $BaseRoot -ChildPath $_) }
+				[String[]]$Items = $LiteralPath |
+					ForEach-Object -Process { [System.IO.Path]::IsPathRooted($_) ? $_ : (Join-Path -Path $RootDirectory -ChildPath $_) }
 			}
 			'Path' {
-				[String[]]$PathsProceed = @()
-				ForEach ($Item In $Path) {
-					Try {
-						$PathsProceed += Resolve-Path -Path ([System.IO.Path]::IsPathRooted($Item) ? $Item : (Join-Path -Path $BaseRoot -ChildPath $Item))
+				[String[]]$Items = $Path |
+					ForEach-Object -Process {
+						Try {
+							Resolve-Path -Path ([System.IO.Path]::IsPathRooted($_) ? $_ : (Join-Path -Path $RootDirectory -ChildPath $_)) |
+								Write-Output
+						}
+						Catch {
+							$_ |
+								Write-Output
+						}
 					}
-					Catch {
-						$PathsProceed += $Item
-					}
-				}
 			}
 		}
 		[Hashtable]$Argument = @{
-			Name = $Name
-			Path = $PathsProceed
-			BaseRoot = $BaseRoot
-			ContinueOnIssue = $ContinueOnIssue.IsPresent
+			'name' = $Name
+			'items' = $Items
+			'rootDirectory' = $RootDirectory
+			'continueOnError' = $ContinueOnError.IsPresent
 		}
-		If ($RetentionTime -gt 0) {
-			$Argument.RetentionTIme = $RetentionTime
+		If ($RetentionDays -gt 0) {
+			$Argument.('retentionDays') = $RetentionDays
 		}
 		Invoke-GitHubActionsNodeJsWrapper -Name 'artifact/upload' -Argument $Argument |
 			Write-Output
@@ -99,15 +101,15 @@ Function Import-Artifact {
 		Switch ($PSCmdlet.ParameterSetName) {
 			'All' {
 				Invoke-GitHubActionsNodeJsWrapper -Name 'artifact/download-all' -Argument @{
-					Destination = $Destination
+					'destination' = $Destination
 				} |
 					Write-Output
 			}
 			'Single' {
 				Invoke-GitHubActionsNodeJsWrapper -Name 'artifact/download' -Argument @{
-					Name = $Name
-					Destination = $Destination
-					CreateSubfolder = $CreateSubfolder.IsPresent
+					'name' = $Name
+					'destination' = $Destination
+					'createSubfolder' = $CreateSubfolder.IsPresent
 				} |
 					Write-Output
 			}

hugoalh.GitHubActionsToolkit/module/cache.psm1

@@ -44,29 +44,26 @@ Function Restore-Cache {
 	)
 	Process {
 		[Hashtable]$Argument = @{
-			PrimaryKey = $Key[0]
-			Path = ($PSCmdlet.ParameterSetName -ieq 'LiteralPath') ? (
+			'primaryKey' = $Key[0]
+			'restoreKeys' = $Key |
+				Select-Object -SkipIndex 0
+			'paths' = ($PSCmdlet.ParameterSetName -ieq 'LiteralPath') ? (
 				$LiteralPath |
 					ForEach-Object -Process { [WildcardPattern]::Escape($_) }
 			) : $Path
-			UseAzureSdk = !$NotUseAzureSdk.IsPresent
-			LookUp = $LookUp.IsPresent
-		}
-		[String[]]$RestoreKey = $Key |
-			Select-Object -SkipIndex 0
-		If ($RestoreKey.Count -gt 0) {
-			$Argument.RestoreKey = $RestoreKey
+			'useAzureSdk' = !$NotUseAzureSdk.IsPresent
+			'lookup' = $LookUp.IsPresent
 		}
 		If ($DownloadConcurrency -gt 0) {
-			$Argument.DownloadConcurrency = $DownloadConcurrency
+			$Argument.('downloadConcurrency') = $DownloadConcurrency
 		}
 		If ($SegmentTimeout -gt 0) {
-			$Argument.SegmentTimeout = $SegmentTimeout * 1000
+			$Argument.('segmentTimeout') = $SegmentTimeout * 1000
 		}
 		If ($Timeout -gt 0) {
-			$Argument.Timeout = $Timeout * 1000
+			$Argument.('timeout') = $Timeout * 1000
 		}
-		(Invoke-GitHubActionsNodeJsWrapper -Name 'cache/restore' -Argument $Argument)?.CacheKey |
+		Invoke-GitHubActionsNodeJsWrapper -Name 'cache/restore' -Argument $Argument |
 			Write-Output
 	}
 }
@@ -82,38 +79,38 @@ Key of the cache.
 Paths of the cache.
 .PARAMETER LiteralPath
 Literal paths of the cache.
-.PARAMETER UploadChunkSizes
-Maximum chunk size of the cache, by KB.
+.PARAMETER UploadChunkSize
+Upload chunk size of the cache, by KB.
 .PARAMETER UploadConcurrency
 Number of parallel uploads of the cache.
 .OUTPUTS
-[String] ID of the cache.
+[UInt64] ID of the cache.
 #>
 Function Save-Cache {
 	[CmdletBinding(DefaultParameterSetName = 'Path', HelpUri = 'https://github.com/hugoalh-studio/ghactions-toolkit-powershell/wiki/api_function_savegithubactionscache')]
-	[OutputType([String])]
+	[OutputType([UInt64])]
 	Param (
 		[Parameter(Mandatory = $True, Position = 0, ValueFromPipelineByPropertyName = $True)][Alias('Name')][String]$Key,
 		[Parameter(Mandatory = $True, ParameterSetName = 'Path', Position = 1, ValueFromPipelineByPropertyName = $True)][SupportsWildcards()][Alias('File', 'Files', 'Paths')][String[]]$Path,
 		[Parameter(Mandatory = $True, ParameterSetName = 'LiteralPath', ValueFromPipelineByPropertyName = $True)][Alias('LiteralFile', 'LiteralFiles', 'LiteralPaths', 'LP', 'PSPath', 'PSPaths')][String[]]$LiteralPath,
-		[Parameter(ValueFromPipelineByPropertyName = $True)][ValidateRange(1, 1MB)][Alias('ChunkSize', 'ChunkSizes', 'UploadChunkSize')][UInt32]$UploadChunkSizes,
+		[Parameter(ValueFromPipelineByPropertyName = $True)][ValidateRange(1, 1MB)][Alias('ChunkSize', 'ChunkSizes', 'UploadChunkSizes')][UInt32]$UploadChunkSize,
 		[Parameter(ValueFromPipelineByPropertyName = $True)][ValidateRange(1, 16)][Alias('Concurrency')][Byte]$UploadConcurrency
 	)
 	Process {
 		[Hashtable]$Argument = @{
-			Key = $Key
-			Path = ($PSCmdlet.ParameterSetName -ieq 'LiteralPath') ? (
+			'key' = $Key
+			'paths' = ($PSCmdlet.ParameterSetName -ieq 'LiteralPath') ? (
 				$LiteralPath |
 					ForEach-Object -Process { [WildcardPattern]::Escape($_) }
 			) : $Path
 		}
-		If ($UploadChunkSizes -gt 0) {
-			$Argument.UploadChunkSizes = $UploadChunkSizes * 1KB
+		If ($UploadChunkSize -gt 0) {
+			$Argument.('uploadChunkSize') = $UploadChunkSize * 1KB
 		}
 		If ($UploadConcurrency -gt 0) {
-			$Argument.UploadConcurrency = $UploadConcurrency
+			$Argument.('uploadConcurrency') = $UploadConcurrency
 		}
-		(Invoke-GitHubActionsNodeJsWrapper -Name 'cache/save' -Argument $Argument)?.CacheId |
+		Invoke-GitHubActionsNodeJsWrapper -Name 'cache/save' -Argument $Argument |
 			Write-Output
 	}
 }

hugoalh.GitHubActionsToolkit/module/command-base.psm1

@@ -15,6 +15,43 @@ Class GitHubActionsStdOutCommand {
 }
 <#
 .SYNOPSIS
+GitHub Actions - Clear File Command
+.DESCRIPTION
+Clear file command.
+.PARAMETER FileCommand
+File command. (LEGACY: Literal path of the file command.)
+.OUTPUTS
+[Void]
+#>
+Function Clear-FileCommand {
+	[CmdletBinding(HelpUri = 'https://github.com/hugoalh-studio/ghactions-toolkit-powershell/wiki/api_function_cleargithubactionsfilecommand')]
+	[OutputType([Void])]
+	Param (
+		[Parameter(Mandatory = $True, Position = 0, ValueFromPipelineByPropertyName = $True)][Alias('Command', 'LiteralPath'<# LEGACY #>, 'Path'<# LEGACY #>)][String]$FileCommand
+	)
+	Process {
+		If (<# LEGACY #>[System.IO.Path]::IsPathFullyQualified($FileCommand)) {
+			[String]$FileCommandPath = $FileCommand
+		}
+		Else {
+			Try {
+				[String]$FileCommandPath = Get-Content -LiteralPath "Env:\$($FileCommand.ToUpper())" -ErrorAction 'Stop'
+			}
+			Catch {
+				Write-Error -Message "Unable to clear the GitHub Actions file command: Environment path ``$($FileCommand.ToUpper())`` is not defined!" -Category 'ResourceUnavailable'
+				Return
+			}
+			If (![System.IO.Path]::IsPathFullyQualified($FileCommandPath)) {
+				Write-Error -Message "Unable to clear the GitHub Actions file command: Environment path ``$($FileCommand.ToUpper())`` is not contain a valid file path!" -Category 'ResourceUnavailable'
+				Return
+			}
+		}
+		Set-Content -LiteralPath $FileCommandPath -Value '' -Confirm:$False -Encoding 'UTF8NoBOM'
+	}
+}
+Set-Alias -Name 'Remove-FileCommand' -Value 'Clear-FileCommand' -Option 'ReadOnly' -Scope 'Local'
+<#
+.SYNOPSIS
 GitHub Actions - Write File Command
 .DESCRIPTION
 Write file command to communicate with the runner machine.
@@ -41,7 +78,7 @@ Function Write-FileCommand {
 		}
 		Else {
 			Try {
-				[String]$FileCommandPath = Get-Content -LiteralPath "Env:\$([WildcardPattern]::Escape($FileCommand.ToUpper()))" -ErrorAction 'Stop'
+				[String]$FileCommandPath = Get-Content -LiteralPath "Env:\$($FileCommand.ToUpper())" -ErrorAction 'Stop'
 			}
 			Catch {
 				Write-Error -Message "Unable to write the GitHub Actions file command: Environment path ``$($FileCommand.ToUpper())`` is not defined!" -Category 'ResourceUnavailable'
@@ -103,8 +140,10 @@ Function Write-StdOutCommand {
 }
 Set-Alias -Name 'Write-Command' -Value 'Write-StdOutCommand' -Option 'ReadOnly' -Scope 'Local'
 Export-ModuleMember -Function @(
+	'Clear-FileCommand',
 	'Write-FileCommand',
 	'Write-StdOutCommand'
 ) -Alias @(
+	'Remove-FileCommand',
 	'Write-Command'
 )

hugoalh.GitHubActionsToolkit/module/environment-variable.psm1

@@ -38,26 +38,25 @@ Function Add-PATH {
 		[Parameter(ValueFromPipelineByPropertyName = $True)][Alias('Scopes')][GitHubActionsEnvironmentVariableScopes]$Scope = [GitHubActionsEnvironmentVariableScopes]3
 	)
 	Process {
-		ForEach ($Item In (
-			$Path |
-				Select-Object -Unique
-		)) {
-			If (!$NoValidator.IsPresent -and !([System.IO.Path]::IsPathRooted($Item) -and (Test-Path -Path $Item -PathType 'Container' -IsValid))) {
-				Write-Error -Message "``$Item`` is not a valid PATH!" -Category 'SyntaxError'
-				Continue
-			}
-			If (($Scope -band [GitHubActionsEnvironmentVariableScopes]::Current) -ieq [GitHubActionsEnvironmentVariableScopes]::Current) {
-				Add-Content -LiteralPath $Env:PATH -Value "$([System.IO.Path]::PathSeparator)$Item" -Confirm:$False -NoNewLine
-			}
-			If (($Scope -band [GitHubActionsEnvironmentVariableScopes]::Subsequent) -ieq [GitHubActionsEnvironmentVariableScopes]::Subsequent) {
-				If ([System.IO.Path]::IsPathFullyQualified($Env:GITHUB_PATH)) {
-					Add-Content -LiteralPath $Env:GITHUB_PATH -Value $Item -Confirm:$False -Encoding 'UTF8NoBOM'
+		$Path |
+			Select-Object -Unique |
+			ForEach-Object -Process {
+				If (!$NoValidator.IsPresent -and !([System.IO.Path]::IsPathRooted($_) -and (Test-Path -Path $_ -PathType 'Container' -IsValid))) {
+					Write-Error -Message "``$_`` is not a valid PATH!" -Category 'SyntaxError'
+					Continue
 				}
-				Else {
-					Write-Error -Message 'Unable to write the GitHub Actions path: Environment path `GITHUB_PATH` is not defined!' -Category 'ResourceUnavailable'
+				If (($Scope -band [GitHubActionsEnvironmentVariableScopes]::Current) -ieq [GitHubActionsEnvironmentVariableScopes]::Current) {
+					Add-Content -LiteralPath $Env:PATH -Value "$([System.IO.Path]::PathSeparator)$_" -Confirm:$False -NoNewLine
+				}
+				If (($Scope -band [GitHubActionsEnvironmentVariableScopes]::Subsequent) -ieq [GitHubActionsEnvironmentVariableScopes]::Subsequent) {
+					If ([System.IO.Path]::IsPathFullyQualified($Env:GITHUB_PATH)) {
+						Add-Content -LiteralPath $Env:GITHUB_PATH -Value $_ -Confirm:$False -Encoding 'UTF8NoBOM'
+					}
+					Else {
+						Write-Error -Message 'Unable to write the GitHub Actions path: Environment path `GITHUB_PATH` is not defined!' -Category 'ResourceUnavailable'
+					}
 				}
 			}
-		}
 	}
 }
 <#