From 3506d75629224fb391e60bb329863c747ef7442a Mon Sep 17 00:00:00 2001 From: Dima Date: Thu, 12 Nov 2026 15:15:06 +0100 Subject: [PATCH 1/6] Prepare all eight Gallery routes with explicit account and review gates --- .github/workflows/release-gallery.yml | 6 ++- .../workflows/validate-release-candidate.yml | 2 +- scripts/ci/Test-ModuleStructure.ps1 | 16 ++++-- scripts/gallery/Build-GalleryPackage.ps1 | 4 +- scripts/gallery/Get-ReleaseConfig.ps1 | 50 +++++++++++++++++-- scripts/gallery/New-ReleaseOutput.ps1 | 17 +++++-- scripts/gallery/Publish-GalleryPackage.ps1 | 2 +- scripts/gallery/Resolve-ReleaseSnapshot.ps1 | 2 +- scripts/gallery/Set-GalleryApiKey.ps1 | 6 +-- scripts/gallery/Test-ReleasePackage.ps1 | 4 +- tests/Test-GalleryAutomation.ps1 | 18 +++++-- tests/Test-GalleryKeySetup.ps1 | 4 +- tests/Test-ReleaseOutput.ps1 | 26 ++++++---- tests/Test-ReleaseSelection.ps1 | 6 +-- tests/Test-WorkflowSafety.cjs | 5 ++ 15 files changed, 125 insertions(+), 43 deletions(-) diff --git a/.github/workflows/release-gallery.yml b/.github/workflows/release-gallery.yml index 815958d..5e42574 100644 --- a/.github/workflows/release-gallery.yml +++ b/.github/workflows/release-gallery.yml @@ -6,7 +6,7 @@ on: description: Module to release type: choice required: true - options: [Bookmarks, 7zip-Archive, Currency-Conv, Base64String, Pipe] + options: [Bookmarks, 7zip-Archive, Currency-Conv, Base64String, Pipe, FolderEncoder, Shell-Functions, MiniModules.Uninstall] version: description: Prepared version number (for example, 1.3.0) type: string @@ -38,12 +38,14 @@ jobs: - name: Validate request shell: pwsh env: + MODULE: ${{ inputs.module }} VERSION: ${{ inputs.version }} MUTATE: ${{ inputs.create_release || !inputs.dry_run }} REF: ${{ github.ref }} run: | if ($env:VERSION -notmatch '^\d+\.\d+\.\d+(\.\d+)?$') { throw 'Stable version required' } if ($env:MUTATE -eq 'true' -and $env:REF -ne 'refs/heads/master') { throw 'Mutations require master' } + if ($env:MUTATE -eq 'true') { ./automation/scripts/gallery/Get-ReleaseConfig.ps1 -Module $env:MODULE -RequirePublication | Out-Null } - name: Resolve the selected module's reviewed release snapshot id: snapshot shell: pwsh @@ -181,7 +183,7 @@ jobs: env: MODULE: ${{ inputs.module }} run: | - $config = ./scripts/gallery/Get-ReleaseConfig.ps1 -Module $env:MODULE + $config = ./scripts/gallery/Get-ReleaseConfig.ps1 -Module $env:MODULE -RequirePublication "name=$($config.GalleryAccount)" >> $env:GITHUB_OUTPUT "secret=$($config.GallerySecret)" >> $env:GITHUB_OUTPUT "Gallery route: $env:MODULE -> $($config.GalleryAccount) ($($config.GallerySecret))" >> $env:GITHUB_STEP_SUMMARY diff --git a/.github/workflows/validate-release-candidate.yml b/.github/workflows/validate-release-candidate.yml index c53611a..f9ab261 100644 --- a/.github/workflows/validate-release-candidate.yml +++ b/.github/workflows/validate-release-candidate.yml @@ -91,7 +91,7 @@ jobs: - uses: actions/upload-artifact@v7.0.2 if: always() with: - name: candidate-${{ matrix.os }}-${{ matrix.shell }} + name: candidate-${{ inputs.module }}-${{ matrix.os }}-${{ matrix.shell }} path: | stage/ source/TestResults/*.xml diff --git a/scripts/ci/Test-ModuleStructure.ps1 b/scripts/ci/Test-ModuleStructure.ps1 index 22c37a6..8742b48 100644 --- a/scripts/ci/Test-ModuleStructure.ps1 +++ b/scripts/ci/Test-ModuleStructure.ps1 @@ -7,8 +7,16 @@ $ErrorActionPreference = 'Stop' $root = (Resolve-Path $SourceRoot).Path $entry = switch ($Module) { FolderEncoder { Join-Path $root 'FolderEncoder/FolderEncoder.psd1' } - Shell-Functions { Join-Path $root 'Shell-Functions/Shell-Function.psd1' } - Uninstall { Join-Path $root 'Uninstall.psm1' } + Shell-Functions { + $canonical = Join-Path $root 'Shell-Functions/Shell-Functions.psd1' + if (Test-Path $canonical -PathType Leaf) { $canonical } + else { Join-Path $root 'Shell-Functions/Shell-Function.psd1' } + } + Uninstall { + $canonical = Join-Path $root 'MiniModules.Uninstall.psd1' + if (Test-Path $canonical -PathType Leaf) { $canonical } + else { Join-Path $root 'Uninstall.psm1' } + } } $results = Join-Path $root 'TestResults' New-Item $results -ItemType Directory -Force | Out-Null @@ -28,7 +36,7 @@ function Add-Check([string]$Name, [scriptblock]$Action) { try { Add-Check 'syntax' { if (-not (Test-Path $entry -PathType Leaf)) { throw "Module entry missing: $entry" } - $files = if ($Module -eq 'Uninstall') { @(Get-Item $entry) } else { + $files = if ($Module -eq 'Uninstall') { @(Get-Item $entry) + @(Get-Item (Join-Path $root 'Uninstall.psm1')) | Sort-Object FullName -Unique } else { @(Get-ChildItem (Split-Path $entry) -File -Recurse | Where-Object { $_.Extension -in '.ps1', '.psm1', '.psd1' -and $_.FullName -notmatch '[/\\]out[/\\]' }) @@ -39,7 +47,7 @@ try { if ($parseErrors.Count) { throw "Syntax errors in $($file.Name): $($parseErrors.Message -join '; ')" } } } - if ($Module -ne 'Uninstall') { + if ([IO.Path]::GetExtension($entry) -eq '.psd1') { Add-Check 'manifest' { Test-ModuleManifest $entry -ErrorAction Stop | Out-Null } } # Import into this script's local scope, then remove by module object in finally. diff --git a/scripts/gallery/Build-GalleryPackage.ps1 b/scripts/gallery/Build-GalleryPackage.ps1 index f5059f0..c4aa58f 100644 --- a/scripts/gallery/Build-GalleryPackage.ps1 +++ b/scripts/gallery/Build-GalleryPackage.ps1 @@ -24,14 +24,14 @@ if ($metadata.PrivateData.PSData.Prerelease) { $destination = Join-Path $OutputRoot $Module if (Test-Path $destination) { throw "Output already exists: $destination. Use a fresh staging directory." } New-Item $destination -ItemType Directory -Force | Out-Null -# These five release packages are flat. Never publish the monorepo, tests, CI, +# These release packages are flat. Never publish the monorepo, tests, CI, # secrets, or nested build output by passing a module source tree wholesale. $allowed = '.ps1', '.psm1', '.psd1', '.dll', '.xml', '.ps1xml', '.md', '.txt', '.ico', '.png' Get-ChildItem $source -File | Where-Object { ($_.Extension -in $allowed -or $_.Name -eq 'LICENSE') -and $_.Name -notmatch '\.(Tests?|SmokeTests)\.ps1$' } | Copy-Item -Destination $destination $license = Join-Path $SourceRoot 'LICENSE' -if (-not (Test-Path (Join-Path $destination 'LICENSE') -PathType Leaf) -and +if ($config.UseRepositoryLicense -and -not (Test-Path (Join-Path $destination 'LICENSE') -PathType Leaf) -and (Test-Path $license -PathType Leaf)) { Copy-Item $license (Join-Path $destination 'LICENSE') } Test-ModuleManifest (Join-Path $destination $config.Manifest) -ErrorAction Stop | Out-Null Write-Host "Validated $Module $ExpectedVersion in $destination" diff --git a/scripts/gallery/Get-ReleaseConfig.ps1 b/scripts/gallery/Get-ReleaseConfig.ps1 index 677a5c1..570bc51 100644 --- a/scripts/gallery/Get-ReleaseConfig.ps1 +++ b/scripts/gallery/Get-ReleaseConfig.ps1 @@ -1,8 +1,10 @@ [CmdletBinding()] param( [Parameter(Mandatory)] - [ValidateSet('Bookmarks', '7zip-Archive', 'Currency-Conv', 'Base64String', 'Pipe')] - [string]$Module + [ValidateSet('Bookmarks', '7zip-Archive', 'Currency-Conv', 'Base64String', 'Pipe', 'FolderEncoder', 'Shell-Functions', 'MiniModules.Uninstall')] + [string]$Module, + [switch]$RequireGalleryAccount, + [switch]$RequirePublication ) # Package branches are deliberately distinct from feature/PR development bases. @@ -43,6 +45,32 @@ $configs = @{ Manifest = 'Pipe.psd1' GalleryAccount = 'MiniModules' } + FolderEncoder = @{ + ReleaseBranch = 'FolderEncoder/release/2.0.1' + PackagePath = 'FolderEncoder/out' + Manifest = 'FolderEncoder.psd1' + GalleryAccount = 'Stadub' + UseRepositoryLicense = $false + PublicationBlockReason = 'The new FolderEncoder release candidate requires owner review and integration approval.' + } + 'Shell-Functions' = @{ + ReleaseBranch = 'Shell-Functions/release/0.0.1' + PackagePath = 'Shell-Functions/out' + Manifest = 'Shell-Functions.psd1' + GalleryAccount = 'MiniModules' + PublicationBlockReason = 'The new Shell-Functions package requires owner review and integration approval.' + } + 'MiniModules.Uninstall' = @{ + ReleaseBranch = 'Uninstall/release/1.0.1' + PackagePath = './out' + Manifest = 'MiniModules.Uninstall.psd1' + CiModule = 'Uninstall' + GalleryAccount = 'MiniModules' + RuntimeFiles = @('Uninstall.psm1') + Readme = 'Uninstall.md' + IncludeIcon = $false + PublicationBlockReason = 'The new MiniModules.Uninstall release candidate requires owner review and integration approval.' + } } # Gallery usernames are public configuration. API key values live only in the # protected environment; module selection never accepts an account/secret input. @@ -51,8 +79,20 @@ $accountSecrets = @{ MiniModules = 'PSGALLERY_API_KEY_MINIMODULES' } $config = $configs[$Module] -if (-not $accountSecrets.ContainsKey($config.GalleryAccount)) { - throw 'No credential route for the configured Gallery account' +if (-not $config.ContainsKey('CiModule')) { $config.CiModule = $Module } +if (-not $config.ContainsKey('UseRepositoryLicense')) { $config.UseRepositoryLicense = $true } +if (-not $config.ContainsKey('IncludeIcon')) { $config.IncludeIcon = $true } +if (-not $config.ContainsKey('RuntimeFiles')) { $config.RuntimeFiles = @() } +if (-not $config.ContainsKey('Readme')) { $config.Readme = 'README.md' } +if (-not $config.ContainsKey('PublicationBlockReason')) { $config.PublicationBlockReason = $null } +$config.GallerySecret = $null +if (-not [string]::IsNullOrWhiteSpace($config.GalleryAccount) -and $accountSecrets.ContainsKey($config.GalleryAccount)) { + $config.GallerySecret = $accountSecrets[$config.GalleryAccount] +} +if (($RequireGalleryAccount -or $RequirePublication) -and -not $config.GallerySecret) { + throw "No approved Gallery account/key mapping for $Module. Owner selection or ownership access is required." +} +if ($RequirePublication -and $config.PublicationBlockReason) { + throw $config.PublicationBlockReason } -$config.GallerySecret = $accountSecrets[$config.GalleryAccount] [pscustomobject]$config diff --git a/scripts/gallery/New-ReleaseOutput.ps1 b/scripts/gallery/New-ReleaseOutput.ps1 index c5a0c34..084f6a9 100644 --- a/scripts/gallery/New-ReleaseOutput.ps1 +++ b/scripts/gallery/New-ReleaseOutput.ps1 @@ -25,21 +25,28 @@ $temporary = Join-Path ([IO.Path]::GetTempPath()) "release-output-$([guid]::NewG try { $package = New-Item (Join-Path $temporary $Module) -ItemType Directory -Force $files = @(Get-Item $manifest) - $files += @(Get-ChildItem $source -Recurse -File | Where-Object { + if ($config.RuntimeFiles) { + # A standalone module at repository root must never recursively collect + # scripts from unrelated modules or infrastructure. + foreach ($relative in $config.RuntimeFiles) { + $files += Get-Item (Join-Path $source $relative) -ErrorAction Stop + } + } else { $files += @(Get-ChildItem $source -Recurse -File | Where-Object { $relative = $_.FullName.Substring($source.Length + 1) $_.Extension -in '.ps1', '.psm1', '.dll', '.ps1xml' -and $relative -notmatch '(^|[/\\])(out|tests?|TestResults|Assets|\.git|\.github)([/\\]|$)' -and $_.Name -notmatch '\.(Tests?|SmokeTests)\.ps1$' - }) - foreach ($name in 'README.md', 'LICENSE') { + }) } + $readme = if ($config.Readme) { $config.Readme } else { 'README.md' } + foreach ($name in $readme, 'LICENSE') { $file = Join-Path $source $name if (Test-Path $file -PathType Leaf) { $files += Get-Item $file } } $icon = Join-Path $source 'Assets/Icon.ico' - if (Test-Path $icon -PathType Leaf) { $files += Get-Item $icon } + if ($config.IncludeIcon -and (Test-Path $icon -PathType Leaf)) { $files += Get-Item $icon } # An explicit module license takes precedence; the repository license is a fallback. $license = Join-Path $sourceRootPath 'LICENSE' - if (-not (Test-Path (Join-Path $source 'LICENSE') -PathType Leaf) -and + if ($config.UseRepositoryLicense -and -not (Test-Path (Join-Path $source 'LICENSE') -PathType Leaf) -and (Test-Path $license -PathType Leaf)) { $files += Get-Item $license } $duplicates = @($files | Group-Object Name | Where-Object Count -gt 1) if ($duplicates.Count) { throw "Ambiguous flat package filenames: $($duplicates.Name -join ', ')" } diff --git a/scripts/gallery/Publish-GalleryPackage.ps1 b/scripts/gallery/Publish-GalleryPackage.ps1 index bf3a438..bfb8626 100644 --- a/scripts/gallery/Publish-GalleryPackage.ps1 +++ b/scripts/gallery/Publish-GalleryPackage.ps1 @@ -6,7 +6,7 @@ param( ) $ErrorActionPreference = 'Stop' -$config = & (Join-Path $PSScriptRoot 'Get-ReleaseConfig.ps1') -Module $Module +$config = & (Join-Path $PSScriptRoot 'Get-ReleaseConfig.ps1') -Module $Module -RequirePublication if ($env:PSGALLERY_ACCOUNT -cne $config.GalleryAccount) { throw "Gallery account mismatch: $Module requires $($config.GalleryAccount). Select its configured credential route." } diff --git a/scripts/gallery/Resolve-ReleaseSnapshot.ps1 b/scripts/gallery/Resolve-ReleaseSnapshot.ps1 index 04ad1cf..2ff1ba9 100644 --- a/scripts/gallery/Resolve-ReleaseSnapshot.ps1 +++ b/scripts/gallery/Resolve-ReleaseSnapshot.ps1 @@ -1,7 +1,7 @@ [CmdletBinding()] param( [Parameter(Mandatory)] - [ValidateSet('Bookmarks', '7zip-Archive', 'Currency-Conv', 'Base64String', 'Pipe')] + [ValidateSet('Bookmarks', '7zip-Archive', 'Currency-Conv', 'Base64String', 'Pipe', 'FolderEncoder', 'Shell-Functions', 'MiniModules.Uninstall')] [string]$Module, [Parameter(Mandatory)] [ValidatePattern('^\d+\.\d+\.\d+(\.\d+)?$')] diff --git a/scripts/gallery/Set-GalleryApiKey.ps1 b/scripts/gallery/Set-GalleryApiKey.ps1 index 18db9cf..71383cc 100644 --- a/scripts/gallery/Set-GalleryApiKey.ps1 +++ b/scripts/gallery/Set-GalleryApiKey.ps1 @@ -13,18 +13,18 @@ the key as a parameter, command argument, environment variable or file. [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Medium')] param( [Parameter(Mandatory)] - [ValidateSet('Bookmarks', '7zip-Archive', 'Currency-Conv', 'Base64String', 'Pipe')] + [ValidateSet('Bookmarks', '7zip-Archive', 'Currency-Conv', 'Base64String', 'Pipe', 'FolderEncoder', 'Shell-Functions', 'MiniModules.Uninstall')] [string]$Module, [ValidatePattern('^[A-Za-z0-9-]+/[A-Za-z0-9_.-]+$')] [string]$Repository = 'stadub/PowershellScripts' ) $ErrorActionPreference = 'Stop' $PSNativeCommandUseErrorActionPreference = $false -$config = & "$PSScriptRoot/Get-ReleaseConfig.ps1" -Module $Module +$config = & "$PSScriptRoot/Get-ReleaseConfig.ps1" -Module $Module -RequireGalleryAccount $environmentName = 'powershell-gallery' $target = "$Repository / $environmentName / $($config.GallerySecret) (Gallery account $($config.GalleryAccount))" if (-not $PSCmdlet.ShouldProcess($target, 'Create or update environment secret')) { return } -try { $ghCommand = Get-Command gh -CommandType Application -ErrorAction Stop } catch { +try { $ghCommand = Get-Command gh -CommandType Application -ErrorAction Stop | Select-Object -First 1 } catch { throw 'Install GitHub CLI (gh) and authenticate to github.com before updating the environment secret.' } $environmentEndpoint = "repos/$Repository/environments/$environmentName" diff --git a/scripts/gallery/Test-ReleasePackage.ps1 b/scripts/gallery/Test-ReleasePackage.ps1 index df00f06..ce797d3 100644 --- a/scripts/gallery/Test-ReleasePackage.ps1 +++ b/scripts/gallery/Test-ReleasePackage.ps1 @@ -28,9 +28,9 @@ try { } Remove-Module $loaded -Force if (-not $InstalledOnly) { - & "$PSScriptRoot/../ci/Invoke-ModuleTests.ps1" -Module $Module -SourceRoot $SourceRoot + & "$PSScriptRoot/../ci/Invoke-ModuleTests.ps1" -Module $config.CiModule -SourceRoot $SourceRoot } - & "$PSScriptRoot/../ci/Invoke-ModuleTests.ps1" -Module $Module -SourceRoot $testRoot + & "$PSScriptRoot/../ci/Invoke-ModuleTests.ps1" -Module $config.CiModule -SourceRoot $testRoot } finally { $reports = Join-Path $SourceRoot 'TestResults' New-Item $reports -ItemType Directory -Force | Out-Null diff --git a/tests/Test-GalleryAutomation.ps1 b/tests/Test-GalleryAutomation.ps1 index b95a310..76fcd9e 100644 --- a/tests/Test-GalleryAutomation.ps1 +++ b/tests/Test-GalleryAutomation.ps1 @@ -24,6 +24,9 @@ try { 'Currency-Conv' = @('Currency-Conv/release/1.5', 'Currency-Conv/out', 'Currency-Conv.psd1', 'Stadub', 'PSGALLERY_API_KEY_STADUB') Base64String = @('base64String/release/latest', 'Shared-Functions/Base64String/out', 'Base64String.psd1', 'MiniModules', 'PSGALLERY_API_KEY_MINIMODULES') Pipe = @('Pipe/release/latest', 'Shared-Functions/Pipe/out', 'Pipe.psd1', 'MiniModules', 'PSGALLERY_API_KEY_MINIMODULES') + FolderEncoder = @('FolderEncoder/release/2.0.1', 'FolderEncoder/out', 'FolderEncoder.psd1', 'Stadub', 'PSGALLERY_API_KEY_STADUB') + 'Shell-Functions' = @('Shell-Functions/release/0.0.1', 'Shell-Functions/out', 'Shell-Functions.psd1', 'MiniModules', 'PSGALLERY_API_KEY_MINIMODULES') + 'MiniModules.Uninstall' = @('Uninstall/release/1.0.1', './out', 'MiniModules.Uninstall.psd1', 'MiniModules', 'PSGALLERY_API_KEY_MINIMODULES') } foreach ($name in $expectedConfigs.Keys) { $config = & "$scripts/Get-ReleaseConfig.ps1" -Module $name @@ -31,6 +34,15 @@ try { throw "Unexpected release configuration for $name" } } + $standalone = & "$scripts/Get-ReleaseConfig.ps1" -Module MiniModules.Uninstall + if ($standalone.CiModule -cne 'Uninstall' -or $standalone.Manifest -cne 'MiniModules.Uninstall.psd1' -or + ($standalone.RuntimeFiles -join '|') -cne 'Uninstall.psm1') { throw 'Standalone component/package identity or runtime scope changed' } + Assert-Throws { & "$scripts/Get-ReleaseConfig.ps1" -Module Uninstall } '*ValidateSet*' + foreach ($name in 'FolderEncoder','Shell-Functions','MiniModules.Uninstall') { + $reason = '*requires owner review*' + Assert-Throws { & "$scripts/Get-ReleaseConfig.ps1" -Module $name -RequirePublication } $reason + Assert-Throws { & "$scripts/Publish-GalleryPackage.ps1" -Module $name -PackageRoot "$fixture/not-a-payload" -ExpectedVersion 1.3.0 } $reason + } # Every module must stage out/, even when a source manifest exists beside it. foreach ($name in $expectedConfigs.Keys) { $config = & "$scripts/Get-ReleaseConfig.ps1" -Module $name @@ -68,7 +80,7 @@ try { Assert-Throws { & "$scripts/Build-GalleryPackage.ps1" -Module Base64String -SourceRoot $source -OutputRoot "$fixture/wrong" -ExpectedVersion 1.3.0 } '*Expected 1.3.0*' Assert-Throws { & "$scripts/Build-GalleryPackage.ps1" -Module Base64String -SourceRoot $source -OutputRoot $stage -ExpectedVersion 1.2.0 } '*Output already exists*' Assert-Throws { & "$scripts/Get-ReleaseConfig.ps1" -Module '../invalid' } '*ValidateSet*' - Assert-Throws { & "$scripts/Get-ReleaseConfig.ps1" -Module 'FolderEncoder' } '*ValidateSet*' + Assert-Throws { & "$scripts/Get-ReleaseConfig.ps1" -Module 'EXportGithub' } '*ValidateSet*' $manifest = Join-Path $built 'Base64String.psd1' $originalManifest = Get-Content $manifest -Raw $prereleaseManifest = $originalManifest.Replace("ModuleVersion = '1.2.0'", "ModuleVersion = '1.2.0'; PrivateData = @{ PSData = @{ Prerelease = 'beta1' } }") @@ -103,7 +115,7 @@ try { $env:PSGALLERY_API_KEY = '' # Validate missing selected credentials for every configured module. These # fixtures contain no module code and the Gallery commands remain mocked. - foreach ($name in $expectedConfigs.Keys) { + foreach ($name in @('Bookmarks','7zip-Archive','Currency-Conv','Base64String','Pipe')) { $config = & "$scripts/Get-ReleaseConfig.ps1" -Module $name $env:PSGALLERY_ACCOUNT = $config.GalleryAccount $accountPackage = Join-Path "$fixture/accounts" $name @@ -131,7 +143,7 @@ try { # Both accounts and all five modules: verify selected-key use and reject # mismatched/missing account routes even if a nonempty key is supplied. $env:GALLERY_TEST_MODE = 'upgrade' - foreach ($name in $expectedConfigs.Keys) { + foreach ($name in @('Bookmarks','7zip-Archive','Currency-Conv','Base64String','Pipe')) { $config = & "$scripts/Get-ReleaseConfig.ps1" -Module $name $env:PSGALLERY_API_KEY = "offline-key-$($config.GalleryAccount)" $env:PSGALLERY_ACCOUNT = 'wrong-account' diff --git a/tests/Test-GalleryKeySetup.ps1 b/tests/Test-GalleryKeySetup.ps1 index da4748b..36d2abd 100644 --- a/tests/Test-GalleryKeySetup.ps1 +++ b/tests/Test-GalleryKeySetup.ps1 @@ -45,7 +45,7 @@ $savedExitCode=$global:LASTEXITCODE try { & $scriptPath -Module Base64String -WhatIf if ($fixtureState.Calls.Count) { throw 'WhatIf contacted gh' } - $expected=@{Bookmarks='PSGALLERY_API_KEY_STADUB';'7zip-Archive'='PSGALLERY_API_KEY_STADUB';'Currency-Conv'='PSGALLERY_API_KEY_STADUB';Base64String='PSGALLERY_API_KEY_MINIMODULES';Pipe='PSGALLERY_API_KEY_MINIMODULES'} + $expected=@{Bookmarks='PSGALLERY_API_KEY_STADUB';'7zip-Archive'='PSGALLERY_API_KEY_STADUB';'Currency-Conv'='PSGALLERY_API_KEY_STADUB';Base64String='PSGALLERY_API_KEY_MINIMODULES';Pipe='PSGALLERY_API_KEY_MINIMODULES';FolderEncoder='PSGALLERY_API_KEY_STADUB';'Shell-Functions'='PSGALLERY_API_KEY_MINIMODULES';'MiniModules.Uninstall'='PSGALLERY_API_KEY_MINIMODULES'} foreach ($name in $expected.Keys) { $fixtureState.Mode='success';$fixtureState.Calls.Clear() $result=& $scriptPath -Module $name @@ -65,5 +65,5 @@ try { Expect-KeySetupFailure verify-failure '*update command succeeded*' $fixtureState.MissingGh=$true Expect-KeySetupFailure missing-gh '*Install GitHub CLI*' - Write-Host 'Key setup contracts passed: five account routes, hidden-prompt arguments, environment-only scope, WhatIf, protection/auth/update/verification failures.' + Write-Host 'Key setup contracts passed: eight owner-approved account routes, hidden-prompt arguments, environment-only scope, WhatIf, protection/auth/update/verification failures.' } finally { $global:LASTEXITCODE=$savedExitCode } diff --git a/tests/Test-ReleaseOutput.ps1 b/tests/Test-ReleaseOutput.ps1 index 865a7da..07394f7 100644 --- a/tests/Test-ReleaseOutput.ps1 +++ b/tests/Test-ReleaseOutput.ps1 @@ -11,43 +11,51 @@ function Assert-OutputFailure([scriptblock]$Action, [string]$Pattern) { try { $source = New-Item "$fixture/source" -ItemType Directory -Force 'canonical license bytes' | Set-Content "$source/LICENSE" - foreach ($name in 'Bookmarks', '7zip-Archive', 'Currency-Conv', 'Base64String', 'Pipe') { + foreach ($name in 'Bookmarks', '7zip-Archive', 'Currency-Conv', 'Base64String', 'Pipe', 'FolderEncoder', 'Shell-Functions', 'MiniModules.Uninstall') { $config = & "$scripts/Get-ReleaseConfig.ps1" -Module $name $modulePath = Join-Path $source ($config.PackagePath -replace '/out$', '') New-Item "$modulePath/Functions", "$modulePath/out", "$modulePath/tests", "$modulePath/Assets" -ItemType Directory -Force | Out-Null $manifest = Join-Path $modulePath $config.Manifest - "@{ ModuleVersion='1.3.0'; GUID='fb5ca217-8826-4570-8241-10a37250331d'; Author='Fixture'; Description='Offline output fixture'; NestedModules=@('Commands.ps1') }" | Set-Content $manifest - 'function Get-Fixture { throw "Runtime code must not execute in generator" }' | Set-Content "$modulePath/Functions/Commands.ps1" + $runtime = if ($config.RuntimeFiles.Count) { $config.RuntimeFiles[0] } else { 'Commands.ps1' } + "@{ ModuleVersion='1.3.0'; GUID='fb5ca217-8826-4570-8241-10a37250331d'; Author='Fixture'; Description='Offline output fixture'; NestedModules=@('$runtime') }" | Set-Content $manifest + $runtimePath = if ($config.RuntimeFiles.Count) { Join-Path $modulePath $runtime } else { "$modulePath/Functions/$runtime" } + 'function Get-Fixture { throw "Runtime code must not execute in generator" }' | Set-Content $runtimePath 'excluded stale artifact' | Set-Content "$modulePath/out/stale.ps1" 'excluded fixture' | Set-Content "$modulePath/tests/Fixtures.ps1" 'excluded tests' | Set-Content "$modulePath/Fixture.Tests.ps1" 'excluded CI' | Set-Content "$modulePath/azure-pipelines.yml" - $expectedLicense = if ($name -eq 'Base64String') { 'explicit module license bytes' } else { 'canonical license bytes' } + $expectedLicense = if ($name -eq 'Base64String') { 'explicit module license bytes' } elseif (-not $config.UseRepositoryLicense) { $null } else { 'canonical license bytes' } if ($name -eq 'Base64String') { $expectedLicense | Set-Content "$modulePath/LICENSE" } - 'reviewed docs' | Set-Content "$modulePath/README.md" + 'reviewed docs' | Set-Content (Join-Path $modulePath $config.Readme) 'icon bytes' | Set-Content "$modulePath/Assets/Icon.ico" foreach ($attempt in 1,2) { & "$scripts/New-ReleaseOutput.ps1" -Module $name -SourceRoot $source -OutputRoot "$fixture/build-$attempt" -ExpectedVersion 1.3.0 } $first = Join-Path "$fixture/build-1" $config.PackagePath $second = Join-Path "$fixture/build-2" $config.PackagePath - if (@(Get-ChildItem $first -File).Count -ne 5) { throw 'Unexpected generated package contents' } + $expectedCount = 3 + [int]$config.IncludeIcon + [int]($null -ne $expectedLicense) + if (@(Get-ChildItem $first -File).Count -ne $expectedCount) { throw "Unexpected generated package contents for $name" } foreach ($file in Get-ChildItem $first -File) { if ((Get-FileHash $file.FullName).Hash -ne (Get-FileHash (Join-Path $second $file.Name)).Hash) { throw 'Non-reproducible output bytes' } } Copy-Item "$source/LICENSE" "$fixture/build-1/LICENSE" -Force & "$scripts/Build-GalleryPackage.ps1" -Module $name -SourceRoot "$fixture/build-1" -OutputRoot "$fixture/stage" -ExpectedVersion 1.3.0 & "$scripts/Assert-SourcePackage.ps1" -Module $name -SourceRoot $source -PackageRoot "$fixture/stage" - if ((Get-Content "$fixture/stage/$name/LICENSE") -ne $expectedLicense) { throw 'Generation/staging lost selected package license' } + if ($null -eq $expectedLicense) { + if (Test-Path "$fixture/stage/$name/LICENSE") { throw 'Repository license incorrectly replaced a module-specific license declaration' } + } elseif ((Get-Content "$fixture/stage/$name/LICENSE") -ne $expectedLicense) { throw 'Generation/staging lost selected package license' } + if ($name -eq 'MiniModules.Uninstall' -and @(Get-ChildItem $first -File | Where-Object { $_.Name -notin @('MiniModules.Uninstall.psd1','Uninstall.psm1','Uninstall.md','LICENSE') }).Count) { throw 'Root standalone package included unrelated repository files' } Assert-OutputFailure { & "$scripts/New-ReleaseOutput.ps1" -Module $name -SourceRoot $source -OutputRoot "$fixture/build-1" -ExpectedVersion 1.3.0 } '*Output already exists*' if ((Get-Content "$modulePath/out/stale.ps1") -ne 'excluded stale artifact') { throw 'Generator modified existing source output' } } - # Negative cases use the last fixture: no partial valid-looking output. + # Negative cases use Pipe: no partial valid-looking output. + $config = & "$scripts/Get-ReleaseConfig.ps1" -Module Pipe + $modulePath = Join-Path $source ($config.PackagePath -replace '/out$', '') Assert-OutputFailure { & "$scripts/New-ReleaseOutput.ps1" -Module Pipe -SourceRoot $source -OutputRoot "$fixture/wrong-version" -ExpectedVersion 1.4.0 } '*Expected 1.4.0*' 'different file' | Set-Content "$modulePath/Commands.ps1" Assert-OutputFailure { & "$scripts/New-ReleaseOutput.ps1" -Module Pipe -SourceRoot $source -OutputRoot "$fixture/ambiguous" -ExpectedVersion 1.3.0 } '*Ambiguous flat package filenames*' Remove-Item "$modulePath/Commands.ps1", "$modulePath/Functions/Commands.ps1" Assert-OutputFailure { & "$scripts/New-ReleaseOutput.ps1" -Module Pipe -SourceRoot $source -OutputRoot "$fixture/missing" -ExpectedVersion 1.3.0 } '*Commands.ps1*' if (Test-Path (Join-Path "$fixture/missing" $config.PackagePath)) { throw 'Invalid package left behind' } - Write-Host 'Release output checks passed: all five routes, deterministic bytes, flattening, exclusions, module-license precedence, no overwrite, version, ambiguity and missing dependencies.' + Write-Host 'Release output checks passed: all eight routes, deterministic bytes, flattening, exclusions, module-license precedence, no overwrite, version, ambiguity and missing dependencies.' } finally { Remove-Item $fixture -Recurse -Force -ErrorAction SilentlyContinue } diff --git a/tests/Test-ReleaseSelection.ps1 b/tests/Test-ReleaseSelection.ps1 index 9122a0b..eb1d908 100644 --- a/tests/Test-ReleaseSelection.ps1 +++ b/tests/Test-ReleaseSelection.ps1 @@ -38,7 +38,7 @@ try { $shaA = Invoke-FixtureGit -C $seed rev-parse HEAD Invoke-FixtureGit -C $seed remote add origin $remote Invoke-FixtureGit -C $seed -c "core.hooksPath=$hooks" push --quiet origin HEAD:refs/heads/fixture - $modules = @('Bookmarks','7zip-Archive','Currency-Conv','Base64String','Pipe') + $modules = @('Bookmarks','7zip-Archive','Currency-Conv','Base64String','Pipe','FolderEncoder','Shell-Functions','MiniModules.Uninstall') foreach ($name in $modules) { $config = & "$PSScriptRoot/../scripts/gallery/Get-ReleaseConfig.ps1" -Module $name Invoke-FixtureGit --git-dir=$remote update-ref "refs/heads/$($config.ReleaseBranch)" $shaA @@ -67,10 +67,10 @@ try { Invoke-FixtureGit --git-dir=$remote update-ref -d refs/heads/7-Zip/release/1.1 Assert-SelectionFailure { & $resolver -Module 7zip-Archive -Version 1.3.0 -RepositoryRoot $seed } '*Cannot resolve the reviewed release branch*' Assert-SelectionFailure { & $resolver -Module Base64String -Version '1.3.0; echo injected' -RepositoryRoot $seed } '*Version*' - Assert-SelectionFailure { & $resolver -Module Uninstall -Version 1.3.0 -RepositoryRoot $seed } '*ValidateSet*' + Assert-SelectionFailure { & $resolver -Module EXportGithub -Version 1.3.0 -RepositoryRoot $seed } '*ValidateSet*' Invoke-FixtureGit -C $seed remote remove origin Assert-SelectionFailure { & $resolver -Module Base64String -Version 1.3.0 -RepositoryRoot $seed } '*Cannot resolve the reviewed release branch*' - Write-Host 'Release selection passed: five configured sources, one immutable SHA, advancing branches, summary evidence, missing refs/origin and invalid inputs.' + Write-Host 'Release selection passed: eight configured sources, one immutable SHA, advancing branches, summary evidence, missing refs/origin and invalid inputs.' } finally { $env:GITHUB_OUTPUT = $savedOutput $env:GITHUB_STEP_SUMMARY = $savedSummary diff --git a/tests/Test-WorkflowSafety.cjs b/tests/Test-WorkflowSafety.cjs index c3fa014..960614b 100644 --- a/tests/Test-WorkflowSafety.cjs +++ b/tests/Test-WorkflowSafety.cjs @@ -63,3 +63,8 @@ for (const name of ['test','release','publish','verify','complete-issues']) { assert.match(jobs.verify, /needs: \[package, publish\]/); assert.match(jobs['complete-issues'], /needs: \[package, publish, verify\]/); console.log('Release form selects a module/version and propagates one resolved immutable snapshot through every job.'); + +for (const moduleName of ['FolderEncoder','Shell-Functions','MiniModules.Uninstall']) assert.ok(dispatchForm.includes(moduleName)); +assert.ok(jobs.package.includes('-RequirePublication')); +assert.ok(selector.includes('-RequirePublication')); +console.log('Expanded publication selector preserves explicit candidate/account review gates before mutation.'); From 42814913be33a4662a57dbf011333b96c5fa294f Mon Sep 17 00:00:00 2001 From: Dima Date: Thu, 12 Nov 2026 15:18:18 +0100 Subject: [PATCH 2/6] Route canonical standalone manifests through Uninstall source CI --- scripts/ci/Resolve-CiSources.ps1 | 2 +- tests/Test-CiSelection.ps1 | 3 +++ tests/Test-CiSources.ps1 | 5 +++++ 3 files changed, 9 insertions(+), 1 deletion(-) diff --git a/scripts/ci/Resolve-CiSources.ps1 b/scripts/ci/Resolve-CiSources.ps1 index 8536d12..7784b18 100644 --- a/scripts/ci/Resolve-CiSources.ps1 +++ b/scripts/ci/Resolve-CiSources.ps1 @@ -16,7 +16,7 @@ foreach ($name in @($all.include.module | Select-Object -Unique)) { foreach ($item in $ChangedPaths) { $path = $item.Replace('\','/') if ($name -eq 'Uninstall') { - $matchesSource = $path -eq 'Uninstall.psm1' -or ($path -notlike '*/*' -and $path -like 'Uninstall*.Tests.ps1') + $matchesSource = $path -in 'Uninstall.psm1','MiniModules.Uninstall.psd1' -or ($path -notlike '*/*' -and $path -like 'Uninstall*.Tests.ps1') } else { $prefix = "$($config.SourcePath)/" $matchesSource = $path.StartsWith($prefix, [StringComparison]::OrdinalIgnoreCase) -and diff --git a/tests/Test-CiSelection.ps1 b/tests/Test-CiSelection.ps1 index 2a7af2a..1958608 100644 --- a/tests/Test-CiSelection.ps1 +++ b/tests/Test-CiSelection.ps1 @@ -12,8 +12,11 @@ $cases = @{ 'Currency-Conv/release/1.5' = 'Currency-Conv' 'Currency-Conv/release/latest' = 'Currency-Conv' 'FolderEncoder/develop' = 'FolderEncoder' + 'FolderEncoder/release/2.0.1' = 'FolderEncoder' 'Shell-Functions/develop' = 'Shell-Functions' + 'Shell-Functions/release/0.0.1' = 'Shell-Functions' 'Uninstall/develop' = 'Uninstall' + 'Uninstall/release/1.0.1' = 'Uninstall' 'Pipe/develop' = 'Pipe' 'Pipe/release/latest' = 'Pipe' 'fix/base64-encoding' = 'Base64String' diff --git a/tests/Test-CiSources.ps1 b/tests/Test-CiSources.ps1 index a6e8675..4064564 100644 --- a/tests/Test-CiSources.ps1 +++ b/tests/Test-CiSources.ps1 @@ -30,6 +30,11 @@ try { $expected=if($entry.module -in 'Base64String','Uninstall') {$current} else {'b'*40} if($entry.source_sha -cne $expected) {throw 'A changed module was ignored or unrelated baseline replaced'} } + $plan=Get-Plan master @('MiniModules.Uninstall.psd1') + if (@($plan.include | Where-Object { $_.module -eq 'Uninstall' -and $_.source_sha -cne $current }).Count -or + @($plan.include | Where-Object { $_.module -ne 'Uninstall' -and $_.source_sha -cne ('b'*40) }).Count) { throw 'New standalone manifest change did not select the Uninstall source snapshot' } + $plan=Get-Plan master @('out/MiniModules.Uninstall.psd1') + if (@($plan.include | Where-Object source_mode -ne development).Count) { throw 'Standalone packaged output replaced source baseline' } $plan=Get-Plan 'Bookmarks/develop' @('Currency-Conv/Functions.ps1') if($plan.include.Count -ne 6 -or @($plan.include|Where-Object source_sha -ne $current).Count) {throw 'Cross-component source changes escaped checks'} $plan=Get-Plan master @('Bookmarks/README.md','Shared-Functions/Base64String/out/Base64String.ps1') From 23598412b96a9fd3a4925d9d21786725e0426b93 Mon Sep 17 00:00:00 2001 From: Dima Date: Thu, 12 Nov 2026 15:21:01 +0100 Subject: [PATCH 3/6] Record three package candidates and validate immutable release payloads --- .../additional-gallery-candidates.yml | 31 +++++ AGENTS.md | 25 ++++ docs/release-pipeline.md | 73 +++++----- docs/releases/new-module-candidates.json | 126 ++++++++++++++++++ docs/releases/new-module-gallery-audit.json | 51 +++++++ docs/releases/new-module-packaging.md | 119 +++++++++++++++++ tests/Test-WorkflowSafety.cjs | 14 ++ 7 files changed, 409 insertions(+), 30 deletions(-) create mode 100644 .github/workflows/additional-gallery-candidates.yml create mode 100644 docs/releases/new-module-candidates.json create mode 100644 docs/releases/new-module-gallery-audit.json create mode 100644 docs/releases/new-module-packaging.md diff --git a/.github/workflows/additional-gallery-candidates.yml b/.github/workflows/additional-gallery-candidates.yml new file mode 100644 index 0000000..2cb79b1 --- /dev/null +++ b/.github/workflows/additional-gallery-candidates.yml @@ -0,0 +1,31 @@ +name: Additional Gallery package candidate validation +on: + push: + branches: [ci/gallery-all-modules] + paths: + - .github/workflows/additional-gallery-candidates.yml + workflow_dispatch: +permissions: + contents: read +jobs: + folderencoder: + uses: stadub/PowershellScripts/.github/workflows/validate-release-candidate.yml@42814913be33a4662a57dbf011333b96c5fa294f + with: + module: FolderEncoder + version: 2.0.1 + source_sha: afb5b7ef10cd53c388d4c6a6b6f6f8d5fb7652d6 + automation_sha: 42814913be33a4662a57dbf011333b96c5fa294f + shell: + uses: stadub/PowershellScripts/.github/workflows/validate-release-candidate.yml@42814913be33a4662a57dbf011333b96c5fa294f + with: + module: Shell-Functions + version: 0.0.1 + source_sha: 5b83779c7c62cca738dc99770ce3724ed4e7fb85 + automation_sha: 42814913be33a4662a57dbf011333b96c5fa294f + uninstall: + uses: stadub/PowershellScripts/.github/workflows/validate-release-candidate.yml@42814913be33a4662a57dbf011333b96c5fa294f + with: + module: MiniModules.Uninstall + version: 1.0.1 + source_sha: a351e867d6fdb14a9650fc1d4f12f67e2dcfdf4c + automation_sha: 42814913be33a4662a57dbf011333b96c5fa294f diff --git a/AGENTS.md b/AGENTS.md index bde6b4d..0de1edd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -296,3 +296,28 @@ The manual release form now selects module and prepared version; it resolves the configured release tip once, records the full SHA, and reuses it throughout the run. It does not rewrite source/package versions or publish development directly. The form becomes visible only after reviewed automation is integrated into master. + +## Additional publishing candidates (owner-authorized 2026-11-12) + +The owner explicitly added FolderEncoder, Shell-Functions and Uninstall to release +preparation, superseding the earlier five-package publication limit. Verified +Gallery ownership maps FolderEncoder to Stadub. The owner explicitly selected +MiniModules for Shell-Functions and the new package name MiniModules.Uninstall. +Do not claim or relist the legacy Uninstall script owned by DimaStadub. + +CI/component identity remains Uninstall; its Gallery manifest/package identity is +MiniModules.Uninstall, RootModule Uninstall.psm1, package directory ./out. The +root standalone generator uses an explicit runtime-file list and module README; +never recursively package the repository. Source and installed checks use the +CiModule mapping. Shell-Functions.psd1 is the canonical package manifest; retain +Shell-Function.psd1 as source compatibility metadata. FolderEncoder keeps its +existing MIT declaration without substituting the repository BSD LICENSE. Other +module licenses, including Base64String WTFPL, remain unchanged. + +Versioned release preparation refs are FolderEncoder/release/2.0.1, +Shell-Functions/release/0.0.1 and Uninstall/release/1.0.1. Their candidate PRs must +explicitly include source preparation and generated out/ and remain unmerged +until separate owner approval. All three new config entries have publication +review blocks: read-only QA is allowed, GitHub release creation and upload are not. +Keep the master-only environment, dry-run default and account-specific keys. +See docs/releases/new-module-packaging.md for exact SHAs, evidence and limits. diff --git a/docs/release-pipeline.md b/docs/release-pipeline.md index 22c733b..6e20107 100644 --- a/docs/release-pipeline.md +++ b/docs/release-pipeline.md @@ -1,8 +1,9 @@ # Tested releases and protected PowerShell Gallery publication This is automation for issue #29, not a deployment of the #22 fix. #22 stays open. -No live Gallery upload, GitHub release creation, issue mutation, secret edit, master -edit, or existing sibling worktree edit was performed by this task. The separately +No live Gallery upload, GitHub release creation, issue completion or secret edit +was performed. The owner approved PR #31 integration into master at +912d1d9bde07b95299f46eb99add2ae58bd2a0c9; its hosted CI passed. The separately authorized Base64String release preparation is recorded in [the 1.3.0 snapshot report](releases/base64string-1.3.0.md). @@ -12,8 +13,9 @@ authorized Base64String release preparation is recorded in `github-actions-ci` worktree and configuration/staging/preflight checks from the read-only `psgallery-deploy` worktree. The sibling files were uncommitted and have continued owner activity: merge this integrated implementation deliberately, not -both its workflow and the sibling `publish-gallery.yml`. Preserve the five publication -routes and Gallery account ownership. Public usernames and the module-to-account +both its workflow and the sibling `publish-gallery.yml`. Preserve the original five +routes and their ownership. The owner subsequently authorized three additional +packages; their candidates remain review-blocked as described below. Public usernames and the module-to-account mapping live in `scripts/gallery/Get-ReleaseConfig.ps1`; API keys live in separate protected environment secrets. The selected key alone is passed to the upload process as `PSGALLERY_API_KEY`. Do not merge a duplicate sibling publishing workflow. @@ -46,6 +48,16 @@ a publication fallback. The configured sources are: | Currency-Conv | Currency-Conv/release/1.5 | Currency-Conv/out | | Base64String | base64String/release/latest | Shared-Functions/Base64String/out | | Pipe | Pipe/release/latest | Shared-Functions/Pipe/out | +| FolderEncoder (review-blocked) | FolderEncoder/release/2.0.1 | FolderEncoder/out | +| Shell-Functions (review-blocked) | Shell-Functions/release/0.0.1 | Shell-Functions/out | +| MiniModules.Uninstall (review-blocked) | Uninstall/release/1.0.1 | ./out | + +The three new release refs begin at their reviewed component baselines; candidate +PRs explicitly add the source preparation and generated out/. Their final integration +requires separate owner approval. See [candidate evidence and limitations](releases/new-module-packaging.md). +`Get-ReleaseConfig.ps1 -RequirePublication` rejects GitHub release creation and +upload for these candidates while review blocks are present; read-only dry-run +and candidate validation remain available after packaging lands. These are literal Git branch names. The owner clarified that GitHub's `/releases/latest` is a release URL alias, not a requirement to create branches @@ -78,6 +90,9 @@ relying on the module manifest's Author field: | [Currency-Conv](https://www.powershellgallery.com/packages/Currency-Conv/1.0.2) | Stadub | PSGALLERY_API_KEY_STADUB | | [Base64String](https://www.powershellgallery.com/packages/Base64String/1.2.0) | MiniModules | PSGALLERY_API_KEY_MINIMODULES | | [Pipe](https://www.powershellgallery.com/packages/Pipe/1.0.0) | MiniModules | PSGALLERY_API_KEY_MINIMODULES | +| [FolderEncoder](https://www.powershellgallery.com/packages/FolderEncoder/2.0.0) | Stadub | PSGALLERY_API_KEY_STADUB | +| Shell-Functions (new; owner-selected account) | MiniModules | PSGALLERY_API_KEY_MINIMODULES | +| MiniModules.Uninstall (new; owner-selected account) | MiniModules | PSGALLERY_API_KEY_MINIMODULES | Usernames are public configuration, not secrets. Each module names its `GalleryAccount`; the account-to-secret-name table in the same script supplies @@ -92,7 +107,8 @@ never values. Dry-runs and non-upload steps never receive either API key. The owner opens repository Settings -> Environments -> powershell-gallery -> Environment secrets -> Add environment secret and creates both named secrets, using a Gallery key generated while signed into the corresponding account. Scope -the Stadub key to its three packages and the MiniModules key to its two packages, +the Stadub key to its four mapped packages and the MiniModules key to its four +mapped packages, including first-publication rights for the two approved new names, with suitable push/update permissions and expiry. Do not replace one account's key when deploying another module. The previous generic `PSGALLERY_API_KEY` environment secret is not read by this workflow and need not be configured. @@ -124,8 +140,8 @@ gh auth login --hostname github.com ./scripts/gallery/Set-GalleryApiKey.ps1 -Module Bookmarks ``` -The MiniModules key is shared by Base64String/Pipe; the Stadub key is shared by -Bookmarks/7zip-Archive/Currency-Conv. Rotating one updates that account's credential +The MiniModules key is shared by Base64String/Pipe/Shell-Functions/MiniModules.Uninstall; +the Stadub key is shared by Bookmarks/7zip-Archive/Currency-Conv/FolderEncoder. Rotating one updates that account's credential for all its mapped modules. The GitHub login and Gallery account are separate identities: enter the Gallery account's publishing key, not a GitHub token. `-Repository owner/repo` can explicitly select another repository; the default is @@ -158,7 +174,8 @@ branch (`master`). A branch-only workflow does not expose the Run workflow form. See [GitHub's manual workflow documentation](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/manually-run-a-workflow). The form contains: -- **Module to release**: Bookmarks, 7zip-Archive, Currency-Conv, Base64String or Pipe. +- **Module to release**: Bookmarks, 7zip-Archive, Currency-Conv, Base64String, Pipe, + FolderEncoder, Shell-Functions or MiniModules.Uninstall. - **Prepared version number**: for example, `1.3.0`. - **Also create the GitHub release during a dry-run**: unchecked by default. - **Validate only; uncheck to publish to PowerShell Gallery**: checked by default. @@ -182,8 +199,8 @@ The same staged artifact is tested on Windows PowerShell 5.1 and pwsh on Windows Linux and macOS (7zip-Archive runtime suites remain Windows-only). Tests use pinned Pester 4.10.1. Source suites run separately against an installed copy, imported by absolute manifest path; suite files never enter the publish payload. Pipe runs its source Pester suites when present, with manifest checks on older -snapshots without suites. CI now covers all eight formal modules; this expansion -does not add publication routes. See the coverage table below. +snapshots without suites. CI covers all eight formal modules. The three newly authorized publication +candidates retain explicit mutation blocks until review. See the coverage table below. Release tags are `-v` at the tested SHA, with `package.tar.gz` and `evidence.json` assets. No automatic closing keywords appear in release notes. @@ -207,7 +224,7 @@ The `gallery-verification` artifact and run log contain verification evidence. ## Populate a missing or stale out/ package -`New-ReleaseOutput.ps1` builds the five configured packages from source; it does +`New-ReleaseOutput.ps1` builds the eight configured packages from source; it does not publish, change versions, recover release-only fixes or overwrite old output. Prepare the module's reviewed release branch first. For Base64String, selectively port the already-reviewed #22 fix and regression suite from development, choose an @@ -265,7 +282,7 @@ in another component adds its coverage. Repository-wide runs pin maintained development commits for unchanged modules and test changed modules at the proposal SHA. Every job records its source identity; see [build repairs and source selection](ci-build-repairs.md). Existing 7zip-Archive runtime suites remain Windows-only; all other entries run pwsh on -Windows, Linux and macOS. The release workflow's publication choices remain five. +Windows, Linux and macOS. The release workflow lists eight packages; the three new routes are review-blocked. | Module | CI checks | | --- | --- | @@ -278,23 +295,19 @@ Windows, Linux and macOS. The release workflow's publication choices remain five | Shell-Functions | Parse source scripts/manifests, validate manifest, import, require exported commands; run source Pester suites when added | | Uninstall | Parse/import standalone Uninstall.psm1, verify exported Uninstall-Application command and SoftwareName/Application parameter contract; run Uninstall*.Tests.ps1 when added | -The three new modules currently have no functional Pester suites. Their checks -produce NUnit-compatible structure reports on success and failure. Uninstall's -smoke checks never invoke its command, access HKLM, start msiexec, or uninstall -software. This checks its loadable public API, not Windows uninstall behavior. - -Local real-source checks: Uninstall passes on macOS pwsh 7.7.0; FolderEncoder fails -because Functions.ps1 is missing; Shell-Functions fails because its manifest imports -an empty module with no exported commands. These are pre-existing module defects, -not successful test runs or allow-failure exceptions. They will block aggregate CI -until repaired through the module development branches. No module implementation -or manifest was modified as part of this expansion. The three development branch -source trees still match this worktree's source at inspection. +FolderEncoder and Shell-Functions import defects were repaired through their +component development PRs #44/#45 and now have 3 and 6 focused source tests. +The new Uninstall packaging candidate adds 3 safe manifest/import/parameter tests. +These run separately against source and installed output. The import/structure +checks also produce NUnit-compatible reports. No test invokes real uninstall, +encoding, downloads or archive roundtrips; those legacy behaviors remain outside +this packaging validation. See [component merge evidence](ci-component-merges.json) +and [the new package candidates](releases/new-module-packaging.md). EXportGithub, Git-Functions and shared infrastructure are the other three inventory components, not formal modules. They do not get invented module entries. All-module -CI still runs on their branches through the default routing. Gallery automation -and issue-completion mappings are unchanged. +CI still runs on their branches through the default routing. Issue-completion mappings remain unchanged; only the exact Base64String 1.3.0 +release SHA can complete #22 after actual verified publication. ## Trusted issue completion @@ -332,10 +345,10 @@ Do not bypass that guard or close manually without verifying deployment evidence ## Owner rollout and remaining blockers -1. Integrate automation into master and port read-only CI automation to maintained - module branches. Run hosted CI and a full production dry-run before enabling required status +1. PR #31 is integrated into master, and the read-only CI automation was ported to + maintained module branches. Run hosted CI and a full production dry-run before enabling required status checks. The prepared Base64String snapshot now has passing hosted validation; - the production manual workflow still needs default-branch integration. + the production manual workflow is now integrated in master via PR #31. 2. For #22, the reviewed fix is commit `5fe9e2344afacccd4cebe02f178d6eb8cd162d2f`, merged by PR #28 into `base64tring/develop` at `4d2e1c86e8083202f74b9b31c48447c0cd82808e`. @@ -348,7 +361,7 @@ Do not bypass that guard or close manually without verifying deployment evidence checkout line endings. The prepared release tip is `6d30dbc22de8bfb8bccda5cd3880ffb9a6655f5f`. See [exact snapshot evidence](releases/base64string-1.3.0.md). -3. Review and integrate the exact issue mapping from PR #31 into master. Run a +3. The exact issue mapping from PR #31 is integrated into master. Run a Base64String 1.3.0 dry-run and verify the resolved SHA matches the prepared snapshot above. Review source and installed NUnit artifacts, including both Windows runtimes. Then optionally create the GitHub release with diff --git a/docs/releases/new-module-candidates.json b/docs/releases/new-module-candidates.json new file mode 100644 index 0000000..802fe1b --- /dev/null +++ b/docs/releases/new-module-candidates.json @@ -0,0 +1,126 @@ +[ + { + "module": "FolderEncoder", + "ciModule": "FolderEncoder", + "version": "2.0.1", + "developmentBranch": "FolderEncoder/develop", + "releaseBranch": "FolderEncoder/release/2.0.1", + "sourcePreparationSha": "25c8ef37a3cae201a6e846010c6c7d0dd23d9fd3", + "candidateSha": "afb5b7ef10cd53c388d4c6a6b6f6f8d5fb7652d6", + "candidateBranch": "prepare/folderencoder-release-candidate", + "packagePath": "FolderEncoder/out", + "localSourceTests": 3, + "localInstalledTests": 3, + "payload": [ + { + "path": "FolderEncoder.psd1", + "sha256": "d55eae9954070edc4282c641cf40e147c08bb4b5161d0ae976fd07a755775933", + "size": 4208 + }, + { + "path": "Functions.ps1", + "sha256": "eff6fd23669f0405b6eb2df6e0e4824e29fccaf49728886493d2d116e6cb8b01", + "size": 8882 + }, + { + "path": "Icon.ico", + "sha256": "3e0b9bf2d056eb321836935306ebc5131de903ea5056c280174362a581f71801", + "size": 3678 + }, + { + "path": "README.md", + "sha256": "2e49bdcfb9d3dfa222a347458fceded15b90783414ab60e5c6a0333e2c7a9cb3", + "size": 4937 + } + ], + "sourcePr": 46, + "reviewedDevelopmentSha": "9b339c1d02e67e601b253da97d770c43242953ca", + "candidatePr": 49 + }, + { + "module": "Shell-Functions", + "ciModule": "Shell-Functions", + "version": "0.0.1", + "developmentBranch": "Shell-Functions/develop", + "releaseBranch": "Shell-Functions/release/0.0.1", + "sourcePreparationSha": "82db53158962a45b510a033f6b2eb87dc7606c08", + "candidateSha": "5b83779c7c62cca738dc99770ce3724ed4e7fb85", + "candidateBranch": "prepare/shell-release-candidate", + "packagePath": "Shell-Functions/out", + "localSourceTests": 6, + "localInstalledTests": 6, + "payload": [ + { + "path": "LICENSE", + "sha256": "1a8f6a9c20c86c73234b3f49a25b2a0ba6bb8cf14f2d9666f44aa1db66915d76", + "size": 1321 + }, + { + "path": "README.md", + "sha256": "ccaa9a45500771b676415688d2456939eaadde6e5fc8208b291bfb786985577e", + "size": 1570 + }, + { + "path": "Shell-Alias.ps1", + "sha256": "e6a0fec9efc97aa55b62e8be1a7de09467f7518c2f1c3beaa20f9f8378c91508", + "size": 97 + }, + { + "path": "Shell-Function.ps1", + "sha256": "b05cdc54d03b96a8b430e9a5ca29244eafe1d51586922cd0c96c1a3b51923506", + "size": 3710 + }, + { + "path": "Shell-Function.psm1", + "sha256": "727ff077ae591dec5fdc97fb95fbd90c332c11f853800adc4f929de06f95f779", + "size": 384 + }, + { + "path": "Shell-Functions.psd1", + "sha256": "c4c4b21b9d87e67cdfc3a48c1660df8302c66b94319708be24442eaa19dba839", + "size": 4194 + } + ], + "sourcePr": 47, + "reviewedDevelopmentSha": "5cd269b6602e973af70387ce04eaf26b82e04b89", + "candidatePr": 50 + }, + { + "module": "MiniModules.Uninstall", + "ciModule": "Uninstall", + "version": "1.0.1", + "developmentBranch": "Uninstall/develop", + "releaseBranch": "Uninstall/release/1.0.1", + "sourcePreparationSha": "b6427503f6d748b3e486d0228fc41f662e8ec6a1", + "candidateSha": "a351e867d6fdb14a9650fc1d4f12f67e2dcfdf4c", + "candidateBranch": "prepare/uninstall-release-candidate", + "packagePath": "out", + "localSourceTests": 3, + "localInstalledTests": 3, + "payload": [ + { + "path": "LICENSE", + "sha256": "1a8f6a9c20c86c73234b3f49a25b2a0ba6bb8cf14f2d9666f44aa1db66915d76", + "size": 1321 + }, + { + "path": "MiniModules.Uninstall.psd1", + "sha256": "2cf53c5ec0a9347f0c056d43af067e6f861ddfe43a290c92069477a02511d006", + "size": 857 + }, + { + "path": "Uninstall.md", + "sha256": "7a5f1b0cbfb0d9269d010eb31963bce12eae4d262a675b1ba521fb07b56f8e6e", + "size": 993 + }, + { + "path": "Uninstall.psm1", + "sha256": "4d0e83f17b18994a2d1ae06de74f0da5581671a16fe80186da254853aa18e0c2", + "size": 1809 + } + ], + "sourcePr": 48, + "reviewedDevelopmentSha": "cb191cc44ec85174187958b994065f6452ae046f", + "candidatePr": 51 + } +] diff --git a/docs/releases/new-module-gallery-audit.json b/docs/releases/new-module-gallery-audit.json new file mode 100644 index 0000000..ce84513 --- /dev/null +++ b/docs/releases/new-module-gallery-audit.json @@ -0,0 +1,51 @@ +[ + { + "name": "FolderEncoder", + "url": "https://www.powershellgallery.com/api/v2/FindPackagesById()?id='FolderEncoder'", + "versions": [ + { + "Id": "FolderEncoder", + "Version": "1.0.0", + "Authors": "Dmitry Stadub", + "Owners": "Stadub", + "PackageTypes": null, + "Listed": null, + "LicenseUrl": "http://opensource.org/licenses/MIT" + }, + { + "Id": "FolderEncoder", + "Version": "2.0.0", + "Authors": "Dmitry Stadub", + "Owners": "Stadub", + "PackageTypes": null, + "Listed": null, + "LicenseUrl": "http://opensource.org/licenses/MIT" + } + ] + }, + { + "name": "Shell-Functions", + "url": "https://www.powershellgallery.com/api/v2/FindPackagesById()?id='Shell-Functions'", + "versions": [] + }, + { + "name": "MiniModules.Uninstall", + "url": "https://www.powershellgallery.com/api/v2/FindPackagesById()?id='MiniModules.Uninstall'", + "versions": [] + }, + { + "name": "Uninstall", + "url": "https://www.powershellgallery.com/api/v2/FindPackagesById()?id='Uninstall'", + "versions": [ + { + "Id": "Uninstall", + "Version": "1.0", + "Authors": "Dima Stadub", + "Owners": "DimaStadub", + "PackageTypes": null, + "Listed": null, + "LicenseUrl": null + } + ] + } +] diff --git a/docs/releases/new-module-packaging.md b/docs/releases/new-module-packaging.md new file mode 100644 index 0000000..b002c0b --- /dev/null +++ b/docs/releases/new-module-packaging.md @@ -0,0 +1,119 @@ +# Three additional Gallery package candidates + +The owner authorized release preparation for all eight formal modules and explicitly +selected MiniModules for both Shell-Functions and the new MiniModules.Uninstall +name. This is preparation only: no Gallery upload, GitHub release, tag, merge, +secret change or environment change is authorized here. + +| CI component | Gallery package | Version | Account | Prepared package path | +| --- | --- | --- | --- | --- | +| FolderEncoder | FolderEncoder | 2.0.1 | Stadub | FolderEncoder/out | +| Shell-Functions | Shell-Functions | 0.0.1 | MiniModules | Shell-Functions/out | +| Uninstall | MiniModules.Uninstall | 1.0.1 | MiniModules | ./out | + +All three publication entries are explicitly review-blocked. `RequirePublication` +rejects GitHub release creation and actual upload before secrets are supplied. +Read-only generation, staging and candidate validation use the public config. +The existing five package/account mappings, dry-run default, master-only secret +boundary and exact verified-publish issue-completion gates remain in effect. +The issue map gains no entries; #22 and #29 remain open. + +## Gallery audit and identity + +On 2026-11-12 the official package API and Gallery pages showed: + +- [FolderEncoder 2.0.0](https://www.powershellgallery.com/packages/FolderEncoder/2.0.0) + is owned by Stadub; 2.0.1 is not present in the exact-name version feed. +- No exact Shell-Functions or Shell-Function release was found, and neither appears + on the [Stadub](https://www.powershellgallery.com/profiles/Stadub) or + [MiniModules](https://www.powershellgallery.com/profiles/MiniModules) profiles. + MiniModules is an explicit owner choice for this new package, not inferred from + its manifest Author field. +- [Uninstall 1.0](https://www.powershellgallery.com/packages/Uninstall/1.0) is an + **unlisted script**, owned by DimaStadub. It is left untouched. The owner chose + the distinct module name MiniModules.Uninstall under MiniModules. No exact + MiniModules.Uninstall API entry was found; this does not reserve the name or + prove API-key rights for first publication. + +See `new-module-gallery-audit.json` for sanitized exact-name API observations. +Authors are attribution; Gallery Owners determine existing package control. +The owner must ensure the existing account keys include these package scopes and +first-publication rights. Only key names/update timestamps were read; no real key +was entered, read or changed. The environment still allows only branch master, +has no required-reviewer rule and permits administrator bypass. Independent +reviewer protection must be configured separately where supported; a sole owner +cannot independently approve their own run with self-review disabled. + +## Source and package changes + +FolderEncoder 2.0.1 builds on reviewed develop commit +`9b339c1d02e67e601b253da97d770c43242953ca`. It preserves its existing MIT LicenseUri; +repository BSD text is deliberately not injected. The version bump, LF policy +and release notes do not change the legacy encoder implementation. The already +approved obsolete Azure/AppVeyor badges are removed from the packaged README. + +Shell-Functions 0.0.1 builds on +`5cd269b6602e973af70387ce04eaf26b82e04b89`. Its canonical manifest is now +Shell-Functions.psd1, matching the package name. Shell-Function.psd1 remains as +source compatibility metadata. Both declare the same exports and required +publication metadata. A local copy of the existing repository BSD-2-Clause license +is packaged. Runtime implementation remains unchanged. + +MiniModules.Uninstall 1.0.1 builds on +`cb191cc44ec85174187958b994065f6452ae046f`. Its new manifest points to the unchanged +Uninstall.psm1; the staged directory/manifest name is MiniModules.Uninstall while +CI remains Uninstall. Explicit runtime-file selection limits the root package to +MiniModules.Uninstall.psd1, Uninstall.psm1, Uninstall.md and LICENSE. Existing runtime +CRLF bytes are preserved explicitly; unrelated repository scripts are excluded. + +All generated output belongs only in the release candidate PRs. Component source +PRs contain metadata/tests/docs and no out/ artifacts. Release candidates explicitly +include their unmerged component-source preparation so review does not assume it +already landed. No whole unrelated module branch is merged into another component. + +## Validation and limits + +Local PowerShell 7.7.0 / Pester 4.10.1 checks passed separately against source and +installed output: FolderEncoder 3 + 3, Shell-Functions 6 + 6, Uninstall 3 + 3. +Manifest/import/export checks also passed. Generation/staging are deterministic, +source/runtime hashes match, and root packaging excludes unrelated modules. +All ten PowerShell offline contract scripts, three Node security/release contract +suites and actionlint 1.7.12 passed locally. Generated copies retain baseline source +whitespace; no runtime bytes were rewritten to silence Git whitespace warnings. + +These are packaging/API checks, not proof of all product behavior. FolderEncoder +checks do not encode files, fetch external tools, or exercise archive roundtrips. +Uninstall checks never read real HKLM entries, invoke msiexec or remove software. +Its existing Windows registry/uninstall implementation is unchanged and remains +unvalidated. Shell link-provider tests mock New-Item; they create no real links. +Windows PowerShell 5.1 and hosted pwsh on Windows/Linux/macOS remain explicit +candidate gates; local macOS results alone do not satisfy them. + +## Review and rollout + +Exact source/candidate SHAs and per-file SHA-256 hashes are in +[new-module-candidates.json](new-module-candidates.json). + +| Package | Component source PR | Release candidate PR | Candidate commit | +| --- | --- | --- | --- | +| FolderEncoder | [#46](https://github.com/stadub/PowershellScripts/pull/46) | [#49](https://github.com/stadub/PowershellScripts/pull/49) | `afb5b7ef10cd53c388d4c6a6b6f6f8d5fb7652d6` | +| Shell-Functions | [#47](https://github.com/stadub/PowershellScripts/pull/47) | [#50](https://github.com/stadub/PowershellScripts/pull/50) | `5b83779c7c62cca738dc99770ce3724ed4e7fb85` | +| MiniModules.Uninstall | [#48](https://github.com/stadub/PowershellScripts/pull/48) | [#51](https://github.com/stadub/PowershellScripts/pull/51) | `a351e867d6fdb14a9650fc1d4f12f67e2dcfdf4c` | + +The separate additional-gallery-candidates.yml workflow pins automation to +42814913be33a4662a57dbf011333b96c5fa294f and each candidate to the full commit +above, then calls the existing read-only four-runtime validator. Artifact names +include the package identity to avoid collisions between the three calls. Versioned release base refs begin at the reviewed +develop baselines; candidate PRs add the prepared source and generated out/. +Until those candidates are integrated, their base refs intentionally have no +matching committed package and production staging fails closed. + +Review source PRs and release candidate PRs separately, then approve their merge +and the automation PR explicitly. New publication review blocks remain until that +approval is recorded in a reviewed config change. No tag or GitHub release is +created by candidate QA. Once approved packages and automation are integrated, +run master with the selected module/version and dry_run=true/create_release=false, +inspect exact SHA/hashes and all runtime reports, then separately authorize an +actual deployment. Only an actual successful upload followed by exact Gallery +package/version/hash and installed-test verification can trigger mapped issue +completion. These three candidates have no completion mapping. diff --git a/tests/Test-WorkflowSafety.cjs b/tests/Test-WorkflowSafety.cjs index 960614b..2a7a7de 100644 --- a/tests/Test-WorkflowSafety.cjs +++ b/tests/Test-WorkflowSafety.cjs @@ -68,3 +68,17 @@ for (const moduleName of ['FolderEncoder','Shell-Functions','MiniModules.Uninsta assert.ok(jobs.package.includes('-RequirePublication')); assert.ok(selector.includes('-RequirePublication')); console.log('Expanded publication selector preserves explicit candidate/account review gates before mutation.'); + +const additionalCandidates = fs.readFileSync('.github/workflows/additional-gallery-candidates.yml','utf8'); +assert.match(additionalCandidates, /permissions:\n contents: read/); +for (const forbidden of ['secrets.', 'secrets[', 'issues: write', 'contents: write', 'environment:', 'Publish-GalleryPackage.ps1']) assert.ok(!additionalCandidates.includes(forbidden)); +const candidateRecords = JSON.parse(fs.readFileSync('docs/releases/new-module-candidates.json','utf8')); +assert.equal(candidateRecords.length, 3); +assert.equal((additionalCandidates.match(/uses: stadub\/PowershellScripts\/.github\/workflows\/validate-release-candidate.yml@[0-9a-f]{40}/g) || []).length, 3); +for (const candidate of candidateRecords) { + assert.match(candidate.candidateSha, /^[0-9a-f]{40}$/); + assert.ok(additionalCandidates.includes(`module: ${candidate.module}\n`)); + assert.ok(additionalCandidates.includes(`source_sha: ${candidate.candidateSha}\n`)); +} +assert.ok(candidateValidation.includes('name: candidate-${{ inputs.module }}-${{ matrix.os }}-${{ matrix.shell }}')); +console.log('Additional package QA pins the reviewed candidate identities and keeps credentials, writes and deployment environments unavailable.'); From e84e8c0fb1ee372935831df26d0ac8857b094ec6 Mon Sep 17 00:00:00 2001 From: Dima Date: Thu, 12 Nov 2026 15:30:24 +0100 Subject: [PATCH 4/6] Record verified four-runtime package evidence and rollout status --- AGENTS.md | 9 +- .../new-module-hosted-validation.json | 189 ++++++++++++++++++ docs/releases/new-module-packaging.md | 10 +- 3 files changed, 202 insertions(+), 6 deletions(-) create mode 100644 docs/releases/new-module-hosted-validation.json diff --git a/AGENTS.md b/AGENTS.md index 0de1edd..7195734 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -85,9 +85,9 @@ new entries run syntax, manifest (where present), import and export checks, and source Pester suites when available. Do not hide current FolderEncoder missing-file or Shell-Functions empty-export failures with allow-failure rules. -Gallery publication remains limited to the original five configured packages. -FolderEncoder, Shell-Functions and Uninstall have no reviewed release branches or -publication configuration. EXportGithub, Git-Functions and shared infrastructure +The original Gallery setup limited publication to five configured packages. +The owner subsequently authorized the three new package candidates documented at +the end of this file; those routes remain review-blocked until separate approval. EXportGithub, Git-Functions and shared infrastructure are script/infrastructure components rather than formal modules; they do not gain module or publishing entries from this CI expansion. @@ -259,7 +259,8 @@ The owner confirmed module-local WTFPL; preserve it during generation/staging an use the repository license only as a fallback. Do not relicense other components. The trusted completion entry maps only #22 to this exact version/SHA, still gated on actual successful Gallery publish and verification. No upload or issue closure -has occurred; production workflow integration into master remains pending. +has occurred. Production workflow integration was explicitly approved and merged +through PR #31 at master 912d1d9bde07b95299f46eb99add2ae58bd2a0c9. CI source selection now pins each unchanged module's maintained development ref to a full SHA and records the identity with test artifacts. Component/release runs diff --git a/docs/releases/new-module-hosted-validation.json b/docs/releases/new-module-hosted-validation.json new file mode 100644 index 0000000..26d491a --- /dev/null +++ b/docs/releases/new-module-hosted-validation.json @@ -0,0 +1,189 @@ +{ + "workflow": { + "id": 43236263855, + "url": "https://github.com/stadub/PowershellScripts/actions/runs/43236263855", + "headSha": "23598412b96a9fd3a4925d9d21786725e0426b93", + "attempt": 1, + "automationSha": "42814913be33a4662a57dbf011333b96c5fa294f", + "conclusion": "success", + "successfulJobs": 12 + }, + "independentArtifactVerification": { + "artifacts": 12, + "pesterAssertions": 96, + "structureAssertions": 72, + "failures": 0, + "skipped": 0, + "payloadHashesMatchCommittedCandidates": true + }, + "artifacts": [ + { + "name": "candidate-FolderEncoder-macos-latest-pwsh", + "id": 13951744387, + "archiveDigest": "sha256:6f0dc218e43f76976b428cd00e76dd23ea1b67a1babe8e5433af5fe078cd438e", + "module": "FolderEncoder", + "version": "2.0.1", + "candidateSha": "afb5b7ef10cd53c388d4c6a6b6f6f8d5fb7652d6", + "sourceTests": 3, + "installedTests": 3, + "structureTests": 6, + "failures": 0, + "skipped": 0, + "payloadMatchesCommittedHashes": true + }, + { + "name": "candidate-FolderEncoder-ubuntu-latest-pwsh", + "id": 13953320843, + "archiveDigest": "sha256:2a78021327bbbe9cfc4d3a8322d38151abab3961eaa6b37b7429cf5be68c2ff0", + "module": "FolderEncoder", + "version": "2.0.1", + "candidateSha": "afb5b7ef10cd53c388d4c6a6b6f6f8d5fb7652d6", + "sourceTests": 3, + "installedTests": 3, + "structureTests": 6, + "failures": 0, + "skipped": 0, + "payloadMatchesCommittedHashes": true + }, + { + "name": "candidate-FolderEncoder-windows-latest-powershell", + "id": 13953495784, + "archiveDigest": "sha256:0c7c07078601161634c20980ad150b3e21f1f3b9dba1cbedd843d347e60bd7aa", + "module": "FolderEncoder", + "version": "2.0.1", + "candidateSha": "afb5b7ef10cd53c388d4c6a6b6f6f8d5fb7652d6", + "sourceTests": 3, + "installedTests": 3, + "structureTests": 6, + "failures": 0, + "skipped": 0, + "payloadMatchesCommittedHashes": true + }, + { + "name": "candidate-FolderEncoder-windows-latest-pwsh", + "id": 13953271033, + "archiveDigest": "sha256:079fdcbd6a354bb47536bbf0131c4b86ef14df35ae98da1e20a91801aaa13d3f", + "module": "FolderEncoder", + "version": "2.0.1", + "candidateSha": "afb5b7ef10cd53c388d4c6a6b6f6f8d5fb7652d6", + "sourceTests": 3, + "installedTests": 3, + "structureTests": 6, + "failures": 0, + "skipped": 0, + "payloadMatchesCommittedHashes": true + }, + { + "name": "candidate-Shell-Functions-macos-latest-pwsh", + "id": 13951629525, + "archiveDigest": "sha256:a543b272f1aa71c39b938c6a1affee2ab06bb89dca5b404ba135a4bb0f98077d", + "module": "Shell-Functions", + "version": "0.0.1", + "candidateSha": "5b83779c7c62cca738dc99770ce3724ed4e7fb85", + "sourceTests": 6, + "installedTests": 6, + "structureTests": 6, + "failures": 0, + "skipped": 0, + "payloadMatchesCommittedHashes": true + }, + { + "name": "candidate-Shell-Functions-ubuntu-latest-pwsh", + "id": 13952013837, + "archiveDigest": "sha256:6ca34cbe84b22c374a7839af4051231ff2377aedb15253bc05b0b9ffccc331ce", + "module": "Shell-Functions", + "version": "0.0.1", + "candidateSha": "5b83779c7c62cca738dc99770ce3724ed4e7fb85", + "sourceTests": 6, + "installedTests": 6, + "structureTests": 6, + "failures": 0, + "skipped": 0, + "payloadMatchesCommittedHashes": true + }, + { + "name": "candidate-Shell-Functions-windows-latest-powershell", + "id": 13953211285, + "archiveDigest": "sha256:f3ff1e753745e9cd7b295aff6512189301e372dc5b6bb32401b6941624d243c6", + "module": "Shell-Functions", + "version": "0.0.1", + "candidateSha": "5b83779c7c62cca738dc99770ce3724ed4e7fb85", + "sourceTests": 6, + "installedTests": 6, + "structureTests": 6, + "failures": 0, + "skipped": 0, + "payloadMatchesCommittedHashes": true + }, + { + "name": "candidate-Shell-Functions-windows-latest-pwsh", + "id": 13952931285, + "archiveDigest": "sha256:0ecf89d99f890ce6fc403c37c2a45416676a9ab4e568359ce2cf09ecdb8e30df", + "module": "Shell-Functions", + "version": "0.0.1", + "candidateSha": "5b83779c7c62cca738dc99770ce3724ed4e7fb85", + "sourceTests": 6, + "installedTests": 6, + "structureTests": 6, + "failures": 0, + "skipped": 0, + "payloadMatchesCommittedHashes": true + }, + { + "name": "candidate-MiniModules.Uninstall-macos-latest-pwsh", + "id": 13953366605, + "archiveDigest": "sha256:7c624acf5e268422243d994f681152e7abe7af097cb179d113be663a0dbce05f", + "module": "MiniModules.Uninstall", + "version": "1.0.1", + "candidateSha": "a351e867d6fdb14a9650fc1d4f12f67e2dcfdf4c", + "sourceTests": 3, + "installedTests": 3, + "structureTests": 6, + "failures": 0, + "skipped": 0, + "payloadMatchesCommittedHashes": true + }, + { + "name": "candidate-MiniModules.Uninstall-ubuntu-latest-pwsh", + "id": 13951978145, + "archiveDigest": "sha256:3a80bc65aa627ef1c0f9e2f3009270cafaedc5cf7a1bfec95b656c2ed7a1ddf2", + "module": "MiniModules.Uninstall", + "version": "1.0.1", + "candidateSha": "a351e867d6fdb14a9650fc1d4f12f67e2dcfdf4c", + "sourceTests": 3, + "installedTests": 3, + "structureTests": 6, + "failures": 0, + "skipped": 0, + "payloadMatchesCommittedHashes": true + }, + { + "name": "candidate-MiniModules.Uninstall-windows-latest-powershell", + "id": 13952138753, + "archiveDigest": "sha256:c8cfc1eee6d2adf42eee1f3c3155be6f86dd0e02da1019c73f71cc2e41d55adf", + "module": "MiniModules.Uninstall", + "version": "1.0.1", + "candidateSha": "a351e867d6fdb14a9650fc1d4f12f67e2dcfdf4c", + "sourceTests": 3, + "installedTests": 3, + "structureTests": 6, + "failures": 0, + "skipped": 0, + "payloadMatchesCommittedHashes": true + }, + { + "name": "candidate-MiniModules.Uninstall-windows-latest-pwsh", + "id": 13952168270, + "archiveDigest": "sha256:3542e26e199a3e4cd15d92265ae39c908ca84d6cab1036235caed626bc25e63d", + "module": "MiniModules.Uninstall", + "version": "1.0.1", + "candidateSha": "a351e867d6fdb14a9650fc1d4f12f67e2dcfdf4c", + "sourceTests": 3, + "installedTests": 3, + "structureTests": 6, + "failures": 0, + "skipped": 0, + "payloadMatchesCommittedHashes": true + } + ] +} diff --git a/docs/releases/new-module-packaging.md b/docs/releases/new-module-packaging.md index b002c0b..2586ab6 100644 --- a/docs/releases/new-module-packaging.md +++ b/docs/releases/new-module-packaging.md @@ -86,8 +86,14 @@ checks do not encode files, fetch external tools, or exercise archive roundtrips Uninstall checks never read real HKLM entries, invoke msiexec or remove software. Its existing Windows registry/uninstall implementation is unchanged and remains unvalidated. Shell link-provider tests mock New-Item; they create no real links. -Windows PowerShell 5.1 and hosted pwsh on Windows/Linux/macOS remain explicit -candidate gates; local macOS results alone do not satisfy them. +Hosted run [43236263855](https://github.com/stadub/PowershellScripts/actions/runs/43236263855) +passed all 12 candidate jobs: Windows PowerShell 5.1 and pwsh on Windows/Linux/macOS +for each package. All 12 artifacts were independently downloaded and verified: +exact candidate SHA/version, committed payload hashes, 96 source/installed Pester +assertions and 72 structure assertions, zero failures/skips. Per-artifact IDs, +archive digests and counts are in +[new-module-hosted-validation.json](new-module-hosted-validation.json). +The payload is identical across all four runtimes for each module. ## Review and rollout From bcb6386ee2ec57b3c8bfd886eeeb00342302d6d4 Mon Sep 17 00:00:00 2001 From: Dima Date: Thu, 12 Nov 2026 16:47:34 +0100 Subject: [PATCH 5/6] Use Gallery version references and reserve the sole major bump for 7Zip --- .github/workflows/ci.yml | 7 +- .github/workflows/release-gallery.yml | 3 +- scripts/gallery/Build-GalleryPackage.ps1 | 2 +- scripts/gallery/Get-ReleaseConfig.ps1 | 9 + scripts/gallery/Resolve-ReleaseSnapshot.ps1 | 1 + .../gallery/Test-ReleaseVersionReference.ps1 | 25 ++ scripts/gallery/version-reference.json | 385 ++++++++++++++++++ tests/Test-GalleryAutomation.ps1 | 10 +- tests/Test-ReleaseVersionReferences.ps1 | 41 ++ tests/Test-WorkflowSafety.cjs | 4 + 10 files changed, 479 insertions(+), 8 deletions(-) create mode 100644 scripts/gallery/Test-ReleaseVersionReference.ps1 create mode 100644 scripts/gallery/version-reference.json create mode 100644 tests/Test-ReleaseVersionReferences.ps1 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 98ff85f..9374450 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -33,6 +33,7 @@ jobs: ./tests/Test-CiRunner.ps1 ./tests/Test-CiStructure.ps1 ./tests/Test-ReleaseSelection.ps1 + ./tests/Test-ReleaseVersionReferences.ps1 ./tests/Test-GalleryAutomation.ps1 ./tests/Test-GalleryKeySetup.ps1 ./tests/Test-ReleaseOutput.ps1 @@ -93,10 +94,12 @@ jobs: ref: ${{ matrix.source_sha }} path: module-source persist-credentials: false - - name: Test release snapshot selection on Windows + - name: Test release selection and Gallery version references on Windows if: ${{ matrix.module == 'Base64String' && matrix.os == 'windows-latest' }} shell: pwsh - run: ./tests/Test-ReleaseSelection.ps1 + run: | + ./tests/Test-ReleaseSelection.ps1 + ./tests/Test-ReleaseVersionReferences.ps1 - name: Run module checks shell: pwsh env: diff --git a/.github/workflows/release-gallery.yml b/.github/workflows/release-gallery.yml index 5e42574..75722e0 100644 --- a/.github/workflows/release-gallery.yml +++ b/.github/workflows/release-gallery.yml @@ -8,7 +8,7 @@ on: required: true options: [Bookmarks, 7zip-Archive, Currency-Conv, Base64String, Pipe, FolderEncoder, Shell-Functions, MiniModules.Uninstall] version: - description: Prepared version number (for example, 1.3.0) + description: Version already prepared for this module; see the release version plan type: string required: true create_release: @@ -69,6 +69,7 @@ jobs: $config = ./automation/scripts/gallery/Get-ReleaseConfig.ps1 -Module $env:MODULE git -C source merge-base --is-ancestor $env:SHA "origin/$($config.ReleaseBranch)" if ($LASTEXITCODE -ne 0) { throw 'Snapshot is not on the configured release branch' } + ./automation/scripts/gallery/Test-ReleaseVersionReference.ps1 -Module $env:MODULE -Version $env:VERSION ./automation/scripts/gallery/Build-GalleryPackage.ps1 -Module $env:MODULE -SourceRoot ./source -OutputRoot ./stage -ExpectedVersion $env:VERSION ./automation/scripts/gallery/Assert-SourcePackage.ps1 -Module $env:MODULE -SourceRoot ./source -PackageRoot ./stage ./automation/scripts/gallery/Package-Evidence.ps1 -Module $env:MODULE -Version $env:VERSION -SourceSha $env:SHA -PackageRoot ./stage -EvidencePath ./stage/evidence.json diff --git a/scripts/gallery/Build-GalleryPackage.ps1 b/scripts/gallery/Build-GalleryPackage.ps1 index c4aa58f..f66dbbf 100644 --- a/scripts/gallery/Build-GalleryPackage.ps1 +++ b/scripts/gallery/Build-GalleryPackage.ps1 @@ -15,7 +15,7 @@ if (-not (Test-Path $manifestPath -PathType Leaf)) { } $metadata = Import-PowerShellDataFile $manifestPath if ([version]$metadata.ModuleVersion -ne $ExpectedVersion) { - throw "Expected $ExpectedVersion, but release manifest declares $($metadata.ModuleVersion)." + throw "Expected $ExpectedVersion for $Module, but release manifest declares $($metadata.ModuleVersion) on $($config.ReleaseBranch). Gallery reference: $($config.LatestGalleryVersion); highest registered: $($config.HighestRegisteredVersion); planned: $($config.PlannedVersion). Entering a version does not change a package; prepare and review matching source/out manifests first." } if ($metadata.PrivateData.PSData.Prerelease) { throw 'This workflow currently supports stable manifest versions only.' diff --git a/scripts/gallery/Get-ReleaseConfig.ps1 b/scripts/gallery/Get-ReleaseConfig.ps1 index 570bc51..1e2b253 100644 --- a/scripts/gallery/Get-ReleaseConfig.ps1 +++ b/scripts/gallery/Get-ReleaseConfig.ps1 @@ -20,6 +20,7 @@ $configs = @{ PackagePath = 'Bookmarks/out' Manifest = 'Bookmarks.psd1' GalleryAccount = 'Stadub' + PublicationBlockReason = 'Bookmarks requires reconciliation with the published 3.0.1 implementation before preparing 3.0.2; do not relabel the repository 2.2.0 implementation.' } '7zip-Archive' = @{ ReleaseBranch = '7-Zip/release/1.1' @@ -79,6 +80,14 @@ $accountSecrets = @{ MiniModules = 'PSGALLERY_API_KEY_MINIMODULES' } $config = $configs[$Module] +$references = Get-Content (Join-Path $PSScriptRoot 'version-reference.json') -Raw | ConvertFrom-Json +$reference = @($references.packages | Where-Object module -eq $Module) +if ($reference.Count -ne 1) { throw "Missing or ambiguous Gallery version reference for $Module" } +$config.LatestGalleryVersion = $reference[0].latestListedVersion +$config.HighestRegisteredVersion = $reference[0].highestRegisteredVersion +$config.PlannedVersion = $reference[0].plannedVersion +$config.VersionChange = $reference[0].change +$config.VersionPlanStatus = $reference[0].status if (-not $config.ContainsKey('CiModule')) { $config.CiModule = $Module } if (-not $config.ContainsKey('UseRepositoryLicense')) { $config.UseRepositoryLicense = $true } if (-not $config.ContainsKey('IncludeIcon')) { $config.IncludeIcon = $true } diff --git a/scripts/gallery/Resolve-ReleaseSnapshot.ps1 b/scripts/gallery/Resolve-ReleaseSnapshot.ps1 index 2ff1ba9..5485918 100644 --- a/scripts/gallery/Resolve-ReleaseSnapshot.ps1 +++ b/scripts/gallery/Resolve-ReleaseSnapshot.ps1 @@ -27,6 +27,7 @@ if ($env:GITHUB_OUTPUT) { } if ($env:GITHUB_STEP_SUMMARY) { "Reviewed release snapshot: $Module $Version | $($config.ReleaseBranch) | $sha" >> $env:GITHUB_STEP_SUMMARY + "Gallery version reference: latest listed $($config.LatestGalleryVersion); highest registered $($config.HighestRegisteredVersion); planned $($config.PlannedVersion) ($($config.VersionChange)). $($config.VersionPlanStatus)" >> $env:GITHUB_STEP_SUMMARY } [pscustomobject]@{ Module = $Module diff --git a/scripts/gallery/Test-ReleaseVersionReference.ps1 b/scripts/gallery/Test-ReleaseVersionReference.ps1 new file mode 100644 index 0000000..b8334c6 --- /dev/null +++ b/scripts/gallery/Test-ReleaseVersionReference.ps1 @@ -0,0 +1,25 @@ +[CmdletBinding()] +param( + [Parameter(Mandatory)][string]$Module, + [Parameter(Mandatory)][ValidatePattern('^\d+\.\d+\.\d+(\.\d+)?$')][string]$Version +) +$ErrorActionPreference = 'Stop' +$config = & "$PSScriptRoot/Get-ReleaseConfig.ps1" -Module $Module +function ConvertTo-ComparableVersion([string]$Value) { + $parsed = [version]$Value + # NuGet treats a zero fourth segment as the same version, not a new patch. + [version]::new($parsed.Major, $parsed.Minor, $parsed.Build, [Math]::Max(0, $parsed.Revision)) +} +$requested = ConvertTo-ComparableVersion $Version +$planned = ConvertTo-ComparableVersion $config.PlannedVersion +if ($config.HighestRegisteredVersion -and + $requested -le (ConvertTo-ComparableVersion $config.HighestRegisteredVersion)) { + throw "$Module $Version must be newer than the recorded highest registered Gallery version $($config.HighestRegisteredVersion), including unlisted versions. Latest listed: $($config.LatestGalleryVersion); planned reference: $($config.PlannedVersion). Prepare and review matching source/out before dispatch." +} +if ($requested.Major -ne $planned.Major) { + throw "$Module $Version does not follow the reviewed version reference $($config.PlannedVersion). Only 7zip-Archive has an authorized new major bump (1.1.0 to 2.0.0); other packages retain their Gallery major or approved initial version." +} +if (-not $config.HighestRegisteredVersion -and $requested -lt $planned) { + throw "$Module is a new package; the approved initial version reference is $($config.PlannedVersion)." +} +Write-Host "Version reference passed: $Module $Version; latest listed $($config.LatestGalleryVersion), highest registered $($config.HighestRegisteredVersion), planned $($config.PlannedVersion). Snapshot/package validation is still required." diff --git a/scripts/gallery/version-reference.json b/scripts/gallery/version-reference.json new file mode 100644 index 0000000..ed5518c --- /dev/null +++ b/scripts/gallery/version-reference.json @@ -0,0 +1,385 @@ +{ + "observedAt": "2026-11-12T15:37:26.266184+00:00", + "policy": "Only 7zip-Archive receives a new major version. All versions are references; they do not mutate manifests or authorize publication.", + "packages": [ + { + "module": "Bookmarks", + "latestListedVersion": "3.0.1", + "highestRegisteredVersion": "3.0.1", + "unlistedVersions": [ + "2.0.0", + "2.0.2", + "2.0.3", + "2.0.4", + "2.1.0" + ], + "plannedVersion": "3.0.2", + "change": "patch", + "status": "blocked: reconcile the Gallery 3.0.1 implementation; do not relabel repository 2.2.0", + "galleryAccount": "Stadub", + "feed": "https://www.powershellgallery.com/api/v2/FindPackagesById()?id='Bookmarks'", + "packagePage": "https://www.powershellgallery.com/packages/Bookmarks/3.0.1", + "developmentBranch": "Bookmarks/develop", + "developmentSha": "5d63a44e4135c5bc3f46f1b7e6cbd928476a2004", + "developmentVersion": "2.2.0", + "releaseBranch": "Bookmarks/release/latest", + "releaseSha": "209e4fe899ed3ec00ae1c1b528eb5afa87aef090", + "releaseSourceVersion": "2.2.0", + "committedPackageVersion": "2.2.0", + "downloadedReference": { + "version": "3.0.1", + "url": "https://www.powershellgallery.com/api/v2/package/Bookmarks/3.0.1", + "nupkgSha256": "89082db4c598a3e3bea7627587e4bab9661f4acb3dfe2a7c4029eee163b5fe3f", + "runtimeFiles": [ + { + "path": "Aliases.ps1", + "sha256": "18d62c659826f2497f6d2a7faa69b30021df4517c3beaa8f2bfb90e75d9a4b32", + "size": 260 + }, + { + "path": "Bookmarks.psd1", + "sha256": "83cd59ac39106d0e61cc4abfff5db520848e4efb6d9db68770ad430da2f153df", + "size": 2161 + }, + { + "path": "Bookmarks.psm1", + "sha256": "0337f5f4de23d9a1eac4dc85d94309648b8e029578b45b57647b9ef4f4319f57", + "size": 860 + }, + { + "path": "cmdlets/Add-PSBookmark.ps1", + "sha256": "142cfdbf02a8734f2e0d34f882fb13c3956db2cb32b22501d861f04fda0090f0", + "size": 976 + }, + { + "path": "cmdlets/Get-BookmarksDataFile.ps1", + "sha256": "76bda1bf03a5d461f62800b7ca2f011588959a3420b7fc58e43e0ee996603d96", + "size": 1387 + }, + { + "path": "cmdlets/Get-PSBookmarks.ps1", + "sha256": "efe86e8c260df1f8d23bfeaf98f9da47dd5bc50595b4e096048bb717eb310375", + "size": 232 + }, + { + "path": "cmdlets/Import-PSBookmarks.ps1", + "sha256": "d0089d8234774fbd09ebabdcd08b68d1b73defccd78431dc7f258ee47e9f8105", + "size": 246 + }, + { + "path": "cmdlets/Open-PSBookmark.ps1", + "sha256": "33a6da2d40c1bbdc9ed90048956fce3589955c8e2678eba7180df1c90af41211", + "size": 631 + }, + { + "path": "cmdlets/Remove-AllPSBookmarks.ps1", + "sha256": "bac327bfbfd89cfac79670055f775d38f4169a3e3853bf18059413ab8970fb28", + "size": 244 + }, + { + "path": "cmdlets/Remove-PSBookmark.ps1", + "sha256": "06fc39cfc59125410623c0ea65b9ef8e03e3646ecc2257c484da68607b56cde9", + "size": 748 + }, + { + "path": "cmdlets/Save-PSBookmarks.ps1", + "sha256": "6ba888dda66cef94aa301285c5b439ee402b97d3ac61abf2c3db177bdf9969f1", + "size": 305 + }, + { + "path": "cmdlets/Update-PSBookmark.ps1", + "sha256": "1a65904d287035cb56edcf4ec32aa1b78fb9bdeae9c514d2e95d1bf890ff69a1", + "size": 1049 + } + ] + } + }, + { + "module": "7zip-Archive", + "latestListedVersion": "1.1.0", + "highestRegisteredVersion": "1.1.0", + "unlistedVersions": [ + "1.0.0", + "1.0.1" + ], + "plannedVersion": "2.0.0", + "change": "major", + "status": "reference only: prepare and validate the reviewed major-release snapshot", + "galleryAccount": "Stadub", + "feed": "https://www.powershellgallery.com/api/v2/FindPackagesById()?id='7zip-Archive'", + "packagePage": "https://www.powershellgallery.com/packages/7zip-Archive/1.1.0", + "developmentBranch": "7Zip/develop", + "developmentSha": "b846f1b01fad8e193cb9e92abdc75a0338c6c823", + "developmentVersion": "1.1.0", + "releaseBranch": "7-Zip/release/1.1", + "releaseSha": "6f8e8f6a8d7bf608af005a5d6f7afa166e70deed", + "releaseSourceVersion": "1.1.0", + "committedPackageVersion": null, + "downloadedReference": { + "version": "1.1.0", + "url": "https://www.powershellgallery.com/api/v2/package/7zip-Archive/1.1.0", + "nupkgSha256": "a3f5bd925d8eb8f5782858a184186cae74e389cdc94f6bb56724ee35a05c181d", + "runtimeFiles": [ + { + "path": "7zip-Archive.psd1", + "sha256": "99791d14e1f6463e3b31cff6b4996556ac535c79682aecd6a8778c427456c7cb", + "size": 5447 + }, + { + "path": "7zip-Archive.psm1", + "sha256": "b5cab60b58b275d666dc8e2846efeb8677cfe5eea1960d0dcfc9fc61b67ab644", + "size": 459 + }, + { + "path": "Aliases.ps1", + "sha256": "6c56af14bdb8ed5fae4fa62d5b8ef09f160c446ccda8e169fe01b8cef4e1402e", + "size": 281 + }, + { + "path": "Functions.ps1", + "sha256": "0cb4b324b6b5418e9d104e831c528d671ad11982e73271324465c66c1a7a88f9", + "size": 15407 + }, + { + "path": "Shared-Functions.ps1", + "sha256": "74e1081fcde2942e5cda911c2fe745f1a96485d16facf2162ef971dd2808c423", + "size": 5170 + } + ] + } + }, + { + "module": "Currency-Conv", + "latestListedVersion": "1.0.2", + "highestRegisteredVersion": "1.5.0", + "unlistedVersions": [ + "1.0.0", + "1.0.1", + "1.5.0" + ], + "plannedVersion": "1.5.1", + "change": "patch", + "status": "reference only: 1.5.0 is registered but unlisted; prepare and validate a new patch", + "galleryAccount": "Stadub", + "feed": "https://www.powershellgallery.com/api/v2/FindPackagesById()?id='Currency-Conv'", + "packagePage": "https://www.powershellgallery.com/packages/Currency-Conv/1.0.2", + "developmentBranch": "Currency-Conv/develop", + "developmentSha": "7306a3b9c3deb1de7257fb51f9b0becdaf7acd4a", + "developmentVersion": "1.5.0", + "releaseBranch": "Currency-Conv/release/1.5", + "releaseSha": "372e316b6da9e418e870785ee6328e28899c0596", + "releaseSourceVersion": "1.5.0", + "committedPackageVersion": null, + "downloadedReference": { + "version": "1.0.2", + "url": "https://www.powershellgallery.com/api/v2/package/Currency-Conv/1.0.2", + "nupkgSha256": "18c02783be50cc648dd4a379d79f1f1b07d0a21e8d85809faf0156babcf7fe13", + "runtimeFiles": [ + { + "path": "Aliases.ps1", + "sha256": "87e32add9064c123a598604e40c08be469033fa044f66dcd49f47c17fbb9712c", + "size": 87 + }, + { + "path": "Currency-Conv.psd1", + "sha256": "d5949085a5f5e3bbc00797e1797f25b1d91e16dd6797f65abeee5e1527e1c099", + "size": 4632 + }, + { + "path": "Currency-Conv.psm1", + "sha256": "ed217b094046d395eadab3c2e84db460c1f6f8f19614e60597636a0dfe9193f6", + "size": 312 + }, + { + "path": "Functions.ps1", + "sha256": "bb68eeff54d2ed30600f68b0d10fa635377d1abd895a2e88f0463164f0195eb3", + "size": 6502 + }, + { + "path": "Shared-Functions.ps1", + "sha256": "e5d3a4313a4247ea5d61a0a37c660d356777503a94dcc93e4e224cce0e63514a", + "size": 3263 + } + ] + } + }, + { + "module": "Base64String", + "latestListedVersion": "1.2.0", + "highestRegisteredVersion": "1.2.0", + "unlistedVersions": [], + "plannedVersion": "1.3.0", + "change": "minor", + "status": "prepared: preserve the owner-approved immutable candidate", + "galleryAccount": "MiniModules", + "feed": "https://www.powershellgallery.com/api/v2/FindPackagesById()?id='Base64String'", + "packagePage": "https://www.powershellgallery.com/packages/Base64String/1.2.0", + "developmentBranch": "base64tring/develop", + "developmentSha": "7eab2ac96dc04bbbfc78a54aeb817fe3cc9f25bd", + "developmentVersion": "1.2.0", + "releaseBranch": "base64String/release/latest", + "releaseSha": "6d30dbc22de8bfb8bccda5cd3880ffb9a6655f5f", + "releaseSourceVersion": "1.3.0", + "committedPackageVersion": "1.3.0", + "downloadedReference": { + "version": "1.2.0", + "url": "https://www.powershellgallery.com/api/v2/package/Base64String/1.2.0", + "nupkgSha256": "5914bc89d35244b33223a0b41a104f008fdc5614e91266a0612483314ed334c9", + "runtimeFiles": [ + { + "path": "Aliases.ps1", + "sha256": "dc0e0e59c1cde104ba421857cb6eef73b00c97f218ddff6ac1227bdf7bab03b4", + "size": 116 + }, + { + "path": "Base64String.ps1", + "sha256": "fc2f208be82cd705ea938861a15900b31a8cca311a29941418bd608f089d8304", + "size": 1574 + }, + { + "path": "Base64String.psd1", + "sha256": "db90fa15a2d96f9b0791442d8a866b2cb1e105e960984770d3a4bdd6b4fef502", + "size": 2944 + } + ] + } + }, + { + "module": "Pipe", + "latestListedVersion": "1.0.0", + "highestRegisteredVersion": "1.0.0", + "unlistedVersions": [], + "plannedVersion": "1.0.1", + "change": "patch", + "status": "reference only: reconcile reviewed development fixes and regenerate out", + "galleryAccount": "MiniModules", + "feed": "https://www.powershellgallery.com/api/v2/FindPackagesById()?id='Pipe'", + "packagePage": "https://www.powershellgallery.com/packages/Pipe/1.0.0", + "developmentBranch": "Pipe/develop", + "developmentSha": "ed959361a5f0d08997a795967402bcd464b85410", + "developmentVersion": "1.0.0", + "releaseBranch": "Pipe/release/latest", + "releaseSha": "77a84404379f6f2a9798e7ffc1d16ac6bd74770d", + "releaseSourceVersion": "1.0.0", + "committedPackageVersion": "1.0.0", + "downloadedReference": { + "version": "1.0.0", + "url": "https://www.powershellgallery.com/api/v2/package/Pipe/1.0.0", + "nupkgSha256": "9ffab4f72ea7cf3140a4fe9e1011847f58c4e0395bfeef591326161edcaf2fc7", + "runtimeFiles": [ + { + "path": "Aliases.ps1", + "sha256": "14dc3eac663a43932ea58bd7952e4ca9b59ff359efa7713bd5284ec7409fe6a1", + "size": 357 + }, + { + "path": "Hide-Out.ps1", + "sha256": "af21f07763af9aa24a1dd3f07fc56561df8fa5cf580047f8d90357b84ee15184", + "size": 213 + }, + { + "path": "Limit-First.ps1", + "sha256": "bdf9becdfecfdd011b3023765cde5114e1953915d242fc08033ff8a55a3e5884", + "size": 180 + }, + { + "path": "Limit-Items.ps1", + "sha256": "76d8f74c2734f103e572acf5b7e043a61fcec62fe04db177ce970493ffb06694", + "size": 738 + }, + { + "path": "Limit-Last.ps1", + "sha256": "a0cbd21147a236fedf2feefc230596807b830c48fd2e4537b8f07c305bfa2ff6", + "size": 303 + }, + { + "path": "Limit-Type.ps1", + "sha256": "1cd8b8b7dad6d5c43e969a84f9bd81f11acd67ce05eda1c601c4e8fe740838ce", + "size": 2034 + }, + { + "path": "Pipe.psd1", + "sha256": "28dce809f5cda43425904547179dde1051f951aae369970b1174cd71b6750d48", + "size": 3470 + }, + { + "path": "Skip-Items.ps1", + "sha256": "e5dbc63eb18f3d8a81f2c87651bc7ca99dd6a7e514a934ffddc38aa0644f618b", + "size": 443 + } + ] + } + }, + { + "module": "FolderEncoder", + "latestListedVersion": "2.0.0", + "highestRegisteredVersion": "2.0.0", + "unlistedVersions": [], + "plannedVersion": "2.0.1", + "change": "patch", + "status": "candidate: source PR46 and release PR49 await review", + "galleryAccount": "Stadub", + "feed": "https://www.powershellgallery.com/api/v2/FindPackagesById()?id='FolderEncoder'", + "packagePage": "https://www.powershellgallery.com/packages/FolderEncoder/2.0.0", + "developmentBranch": "FolderEncoder/develop", + "developmentSha": "9b339c1d02e67e601b253da97d770c43242953ca", + "releaseBranch": "FolderEncoder/release/2.0.1", + "releaseSha": "9b339c1d02e67e601b253da97d770c43242953ca", + "candidateSha": "afb5b7ef10cd53c388d4c6a6b6f6f8d5fb7652d6", + "candidateVersion": "2.0.1", + "downloadedReference": { + "version": "2.0.0", + "url": "https://www.powershellgallery.com/api/v2/package/FolderEncoder/2.0.0", + "nupkgSha256": "65f027db61bf2e5070465e1a1a5343192ad3b192e3c46f5c35de757f8967d886", + "runtimeFiles": [ + { + "path": "FolderEncoder.psd1", + "sha256": "f9026928d01e05d0c7401623d5a3247b18881cbd19efc68dfd21a455c87d4c00", + "size": 4327 + }, + { + "path": "Functions.ps1", + "sha256": "4fdacde482dc7868d1fe8eb084bf33b58a39acba474f2dd2253a562b07c75bad", + "size": 9207 + } + ] + } + }, + { + "module": "Shell-Functions", + "latestListedVersion": null, + "highestRegisteredVersion": null, + "unlistedVersions": [], + "plannedVersion": "0.0.1", + "change": "initial", + "status": "candidate: new owner-approved name; PR47/50 await review", + "galleryAccount": "MiniModules", + "feed": "https://www.powershellgallery.com/api/v2/FindPackagesById()?id='Shell-Functions'", + "packagePage": null, + "developmentBranch": "Shell-Functions/develop", + "developmentSha": "5cd269b6602e973af70387ce04eaf26b82e04b89", + "releaseBranch": "Shell-Functions/release/0.0.1", + "releaseSha": "5cd269b6602e973af70387ce04eaf26b82e04b89", + "candidateSha": "5b83779c7c62cca738dc99770ce3724ed4e7fb85", + "candidateVersion": "0.0.1" + }, + { + "module": "MiniModules.Uninstall", + "latestListedVersion": null, + "highestRegisteredVersion": null, + "unlistedVersions": [], + "plannedVersion": "1.0.1", + "change": "initial", + "status": "candidate: new owner-approved name; PR48/51 await review", + "galleryAccount": "MiniModules", + "feed": "https://www.powershellgallery.com/api/v2/FindPackagesById()?id='MiniModules.Uninstall'", + "packagePage": null, + "developmentBranch": "Uninstall/develop", + "developmentSha": "cb191cc44ec85174187958b994065f6452ae046f", + "releaseBranch": "Uninstall/release/1.0.1", + "releaseSha": "cb191cc44ec85174187958b994065f6452ae046f", + "candidateSha": "a351e867d6fdb14a9650fc1d4f12f67e2dcfdf4c", + "candidateVersion": "1.0.1" + } + ] +} diff --git a/tests/Test-GalleryAutomation.ps1 b/tests/Test-GalleryAutomation.ps1 index 76fcd9e..7e9905a 100644 --- a/tests/Test-GalleryAutomation.ps1 +++ b/tests/Test-GalleryAutomation.ps1 @@ -38,6 +38,8 @@ try { if ($standalone.CiModule -cne 'Uninstall' -or $standalone.Manifest -cne 'MiniModules.Uninstall.psd1' -or ($standalone.RuntimeFiles -join '|') -cne 'Uninstall.psm1') { throw 'Standalone component/package identity or runtime scope changed' } Assert-Throws { & "$scripts/Get-ReleaseConfig.ps1" -Module Uninstall } '*ValidateSet*' + Assert-Throws { & "$scripts/Get-ReleaseConfig.ps1" -Module Bookmarks -RequirePublication } '*do not relabel*' + Assert-Throws { & "$scripts/Publish-GalleryPackage.ps1" -Module Bookmarks -PackageRoot "$fixture/not-a-payload" -ExpectedVersion 3.0.2 } '*do not relabel*' foreach ($name in 'FolderEncoder','Shell-Functions','MiniModules.Uninstall') { $reason = '*requires owner review*' Assert-Throws { & "$scripts/Get-ReleaseConfig.ps1" -Module $name -RequirePublication } $reason @@ -113,9 +115,9 @@ try { Assert-Throws { & "$scripts/Publish-GalleryPackage.ps1" -Module Base64String -PackageRoot $stage -ExpectedVersion 1.2.0 } '*stable manifest versions only*' $originalManifest | Set-Content $manifest $env:PSGALLERY_API_KEY = '' - # Validate missing selected credentials for every configured module. These + # Validate missing selected credentials for every currently unblocked module. These # fixtures contain no module code and the Gallery commands remain mocked. - foreach ($name in @('Bookmarks','7zip-Archive','Currency-Conv','Base64String','Pipe')) { + foreach ($name in @('7zip-Archive','Currency-Conv','Base64String','Pipe')) { $config = & "$scripts/Get-ReleaseConfig.ps1" -Module $name $env:PSGALLERY_ACCOUNT = $config.GalleryAccount $accountPackage = Join-Path "$fixture/accounts" $name @@ -140,10 +142,10 @@ try { if (-not (Test-Path $env:GALLERY_TEST_MARKER)) { throw 'Expected mocked publish call' } Remove-Item $env:GALLERY_TEST_MARKER } - # Both accounts and all five modules: verify selected-key use and reject + # Both accounts and the four currently unblocked modules: verify selected-key use and reject # mismatched/missing account routes even if a nonempty key is supplied. $env:GALLERY_TEST_MODE = 'upgrade' - foreach ($name in @('Bookmarks','7zip-Archive','Currency-Conv','Base64String','Pipe')) { + foreach ($name in @('7zip-Archive','Currency-Conv','Base64String','Pipe')) { $config = & "$scripts/Get-ReleaseConfig.ps1" -Module $name $env:PSGALLERY_API_KEY = "offline-key-$($config.GalleryAccount)" $env:PSGALLERY_ACCOUNT = 'wrong-account' diff --git a/tests/Test-ReleaseVersionReferences.ps1 b/tests/Test-ReleaseVersionReferences.ps1 new file mode 100644 index 0000000..866ff5e --- /dev/null +++ b/tests/Test-ReleaseVersionReferences.ps1 @@ -0,0 +1,41 @@ +# Recorded public Gallery observations only: no network, secrets or publication. +$ErrorActionPreference = 'Stop' +$scripts = Join-Path $PSScriptRoot '../scripts/gallery' +$data = Get-Content (Join-Path $scripts 'version-reference.json') -Raw | ConvertFrom-Json +function Expect-VersionFailure([string]$Module, [string]$Version, [string]$Pattern) { + $caught = $null + try { & "$scripts/Test-ReleaseVersionReference.ps1" -Module $Module -Version $Version } catch { $caught = $_ } + if (-not $caught -or $caught.Exception.Message -notlike $Pattern) { throw "Expected $Module $Version '$Pattern', got '$caught'" } +} +if ($data.packages.Count -ne 8 -or @($data.packages.module | Select-Object -Unique).Count -ne 8) { throw 'Version references must cover exactly eight distinct configured packages' } +if (@($data.packages | Where-Object change -eq major).Count -ne 1 -or + @($data.packages | Where-Object change -eq major)[0].module -cne '7zip-Archive') { throw 'Only 7Zip may receive a new major version' } +foreach ($entry in $data.packages) { + $config = & "$scripts/Get-ReleaseConfig.ps1" -Module $entry.module + if ($config.GalleryAccount -cne $entry.galleryAccount) { throw 'Version reference account differs from trusted package routing' } + & "$scripts/Test-ReleaseVersionReference.ps1" -Module $entry.module -Version $entry.plannedVersion + if ($entry.latestListedVersion) { + $baseline = [version]$entry.latestListedVersion + $planned = [version]$entry.plannedVersion + if ($entry.module -ne '7zip-Archive' -and $planned.Major -ne $baseline.Major) { throw 'Unapproved major bump from Gallery baseline' } + if ($entry.downloadedReference.nupkgSha256 -cnotmatch '^[0-9a-f]{64}$') { throw 'Missing exact downloaded Gallery package evidence' } + } +} +Expect-VersionFailure Bookmarks 1.3.0 '*highest registered Gallery version 3.0.1*' +Expect-VersionFailure Bookmarks 2.2.0 '*highest registered Gallery version 3.0.1*' +Expect-VersionFailure Bookmarks 4.0.0 '*Only 7zip-Archive*' +Expect-VersionFailure Currency-Conv 1.0.3 '*highest registered Gallery version 1.5.0*' +Expect-VersionFailure Currency-Conv 1.5.0 '*including unlisted versions*' +Expect-VersionFailure Currency-Conv 1.5.0.0 '*including unlisted versions*' +Expect-VersionFailure Base64String 2.0.0 '*Only 7zip-Archive*' +Expect-VersionFailure Pipe 2.0.0 '*Only 7zip-Archive*' +Expect-VersionFailure 7zip-Archive 1.2.0 '*Only 7zip-Archive*' +Expect-VersionFailure 7zip-Archive 3.0.0 '*Only 7zip-Archive*' +Expect-VersionFailure Shell-Functions 0.0.0 '*approved initial version*' +Expect-VersionFailure MiniModules.Uninstall 2.0.0 '*Only 7zip-Archive*' +$bookmarks = & "$scripts/Get-ReleaseConfig.ps1" -Module Bookmarks +if ($bookmarks.PlannedVersion -cne '3.0.2') { throw 'Bookmarks was based on stale source instead of Gallery 3.0.1' } +$caught = $null +try { & "$scripts/Get-ReleaseConfig.ps1" -Module Bookmarks -RequirePublication } catch { $caught = $_ } +if (-not $caught -or $caught.Exception.Message -notlike '*do not relabel*2.2.0*') { throw 'Unreconciled Bookmarks publication was not blocked' } +Write-Host 'Version references passed: all eight modules, latest Gallery baselines, unlisted reservation, zero revision normalization, sole 7Zip major bump and unreconciled Bookmarks block.' diff --git a/tests/Test-WorkflowSafety.cjs b/tests/Test-WorkflowSafety.cjs index 2a7a7de..15e71a6 100644 --- a/tests/Test-WorkflowSafety.cjs +++ b/tests/Test-WorkflowSafety.cjs @@ -82,3 +82,7 @@ for (const candidate of candidateRecords) { } assert.ok(candidateValidation.includes('name: candidate-${{ inputs.module }}-${{ matrix.os }}-${{ matrix.shell }}')); console.log('Additional package QA pins the reviewed candidate identities and keeps credentials, writes and deployment environments unavailable.'); + +assert.ok(jobs.package.includes('Test-ReleaseVersionReference.ps1')); +assert.ok(ciWorkflow.includes('Test-ReleaseVersionReferences.ps1')); +console.log('Release requests use recorded Gallery version references before package creation; offline policy tests remain in CI.'); From bc1137bc41d79551b9870be69f2159e4daa7ac0d Mon Sep 17 00:00:00 2001 From: Dima Date: Thu, 12 Nov 2026 16:47:34 +0100 Subject: [PATCH 6/6] Document per-module version decisions and Bookmarks reconciliation blocker --- AGENTS.md | 21 ++++ docs/release-pipeline.md | 25 ++++- docs/releases/gallery-version-reference.md | 113 +++++++++++++++++++++ 3 files changed, 157 insertions(+), 2 deletions(-) create mode 100644 docs/releases/gallery-version-reference.md diff --git a/AGENTS.md b/AGENTS.md index 7195734..4c0ae7c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -322,3 +322,24 @@ until separate owner approval. All three new config entries have publication review blocks: read-only QA is allowed, GitHub release creation and upload are not. Keep the master-only environment, dry-run default and account-specific keys. See docs/releases/new-module-packaging.md for exact SHAs, evidence and limits. + +## Gallery versions as release references (owner direction 2026-11-12) + +Use scripts/gallery/version-reference.json and docs/releases/gallery-version-reference.md +as the dated Gallery baseline. Only 7zip-Archive receives a new major bump: +latest listed 1.1.0 -> planned 2.0.0 because automatic runtime downloads are removed +and an installed native runtime is now required. Preserve Base64String 1.3.0 and +the three already validated new-module candidate versions. Do not blanket-bump. + +Bookmarks Gallery 3.0.1 has a different cmdlets-based implementation from repository +2.2.0; planned 3.0.2 is explicitly blocked pending exact source reconciliation. +No reachable 3.x source manifest was found. Do not relabel the 2.2 monolith or +invent missing runtime helpers. Currency-Conv latest listed is 1.0.2, but 1.5.0 +is registered and unlisted; planned 1.5.1 must follow source/package validation. +Pipe’s reference plan is 1.0.1. These are plans, not prepared release claims. + +The workflow checks recorded registered-version and major-version references +before staging; source/out versions must still match and source hashes/tests +must pass. Reference data never rewrites manifests or changes issue mappings. +Refresh Gallery observations before actual rollout. No merge, tag, GitHub release +or Gallery upload is authorized by this version audit. diff --git a/docs/release-pipeline.md b/docs/release-pipeline.md index 6e20107..33a016a 100644 --- a/docs/release-pipeline.md +++ b/docs/release-pipeline.md @@ -33,7 +33,9 @@ Only require `CI status` after a real hosted run succeeds on each maintained bra ## Inputs and behavior Run `release-gallery.yml` manually. Select a module from the dropdown and enter -its prepared stable version number, such as `1.3.0`. No commit SHA is required in +its prepared stable version number. Use the per-module +[Gallery version reference plan](releases/gallery-version-reference.md); `1.3.0` +is the prepared Base64String version, not a shared default. No commit SHA is required in the form. The workflow resolves the configured reviewed release branch once to a full immutable SHA, records it in the run summary, and passes that exact SHA to every checkout, test, release, publication, verification and issue-completion job. @@ -176,7 +178,8 @@ The form contains: - **Module to release**: Bookmarks, 7zip-Archive, Currency-Conv, Base64String, Pipe, FolderEncoder, Shell-Functions or MiniModules.Uninstall. -- **Prepared version number**: for example, `1.3.0`. +- **Version already prepared for this module**: match that module’s committed + source/out manifests and the [version reference plan](releases/gallery-version-reference.md). - **Also create the GitHub release during a dry-run**: unchecked by default. - **Validate only; uncheck to publish to PowerShell Gallery**: checked by default. @@ -222,6 +225,23 @@ PSGetModuleInfo.xml is excluded from the comparison. A different visible package missing version, download error, hash change, or failed regression blocks completion. The `gallery-verification` artifact and run log contain verification evidence. +## Gallery version references + +`scripts/gallery/version-reference.json` records the observed latest listed and +highest registered stable versions (including unlisted packages), downloaded +reference archive/runtime hashes, source/release SHAs and the next version plan. +`Get-ReleaseConfig.ps1` exposes LatestGalleryVersion, HighestRegisteredVersion, +PlannedVersion, VersionChange and VersionPlanStatus. The release workflow checks +these references before staging and records them in the run summary. Only 7Zip +has a planned major bump. Zero fourth-segment versions cannot bypass registered +version checks. This is a dated reviewed reference, not a live query or a package +builder; refresh it against Gallery before rollout. Actual upload still performs +its existing credential-scoped live Gallery preflight. + +Bookmarks publication/release creation is additionally blocked pending +reconciliation with the downloaded 3.0.1 implementation; do not relabel the stale +2.2.0 source. See [exact version decisions and blockers](releases/gallery-version-reference.md). + ## Populate a missing or stale out/ package `New-ReleaseOutput.ps1` builds the eight configured packages from source; it does @@ -402,6 +422,7 @@ pwsh -NoProfile -NonInteractive -File tests/Test-CiRunner.ps1 pwsh -NoProfile -NonInteractive -File tests/Test-CiStructure.ps1 pwsh -NoProfile -NonInteractive -File tests/Test-GalleryAutomation.ps1 pwsh -NoProfile -NonInteractive -File tests/Test-ReleaseSelection.ps1 +pwsh -NoProfile -NonInteractive -File tests/Test-ReleaseVersionReferences.ps1 pwsh -NoProfile -NonInteractive -File tests/Test-GalleryKeySetup.ps1 pwsh -NoProfile -NonInteractive -File tests/Test-ReleaseOutput.ps1 pwsh -NoProfile -NonInteractive -File tests/Test-ReleaseEvidence.ps1 diff --git a/docs/releases/gallery-version-reference.md b/docs/releases/gallery-version-reference.md new file mode 100644 index 0000000..937e44e --- /dev/null +++ b/docs/releases/gallery-version-reference.md @@ -0,0 +1,113 @@ +# Gallery version references and next release plan + +Checked 2026-11-12 against the official exact-name Gallery API, package pages and +six downloaded latest-listed nupkgs. The owner directs that **only 7Zip receives a +new major version**. These numbers are per-package references, not a shared +version input or a claim that every snapshot is already prepared. + +| Package | Latest listed | Highest registered stable | Next reference | Change | Readiness | +| --- | --- | --- | --- | --- | --- | +| Bookmarks | 3.0.1 | 3.0.1 | 3.0.2 | Patch | Blocked: reconcile the actual 3.0.1 implementation first | +| 7zip-Archive | 1.1.0 | 1.1.0 | 2.0.0 | **Major** | Reference only; reviewed source must be packaged/versioned | +| Currency-Conv | 1.0.2 | **1.5.0, unlisted** | 1.5.1 | Patch above the reserved 1.5.0 | Reference only; reviewed source/package validation required | +| Base64String | 1.2.0 | 1.2.0 | **1.3.0** | Minor, already approved | Preserve prepared snapshot 6d30dbc22de8bfb8bccda5cd3880ffb9a6655f5f | +| Pipe | 1.0.0 | 1.0.0 | 1.0.1 | Patch | Reference only; regenerate matching output from reviewed fixes | +| FolderEncoder | 2.0.0 | 2.0.0 | **2.0.1** | Patch | Preserve validated candidate in PR49 | +| Shell-Functions | None | None | **0.0.1** | First package | Preserve owner-approved MiniModules candidate in PR50 | +| MiniModules.Uninstall | None | None | **1.0.1** | First package under a distinct name | Preserve owner-approved MiniModules candidate in PR51 | + +Source/release SHAs, observed manifest versions, official feed/package links, +reserved unlisted versions, nupkg SHA-256 and runtime-file hashes are recorded in +[version-reference.json](../../scripts/gallery/version-reference.json). API entry +IsLatestVersion identifies the latest listed release; registered but unlisted +stable versions are also considered before choosing a new number. The Gallery +feeds mark their unlisted entries with the 1900 publication sentinel. + +## Why Bookmarks cannot simply become 3.0.2 + +The failed manual run selected Bookmarks with the Base64String example number +1.3.0. Its configured release SHA 209e4fe899ed3ec00ae1c1b528eb5afa87aef090 and +maintained development SHA 5d63a44e4135c5bc3f46f1b7e6cbd928476a2004 both still +declare 2.2.0. Gallery already contains 3.0.1, published on 2025-05-19. + +The downloaded 3.0.1 reference has twelve runtime files: manifest/module, aliases +and nine cmdlet files under cmdlets/. Its release notes describe a restructure, +multiplatform work and removal of the update checker. Repository 2.2.0 instead +uses Functions.ps1 and Shared-Functions.ps1. The 3.0.1 module explicitly imports +and exports Import-PSBookmarks and Save-PSBookmarks in addition to its other +commands; its manifest exposes only six functions and does not declare RootModule. +Those exact published packaging/API differences also need review rather than +assuming the published package is automatically correct. + +A read-only scan of reachable manifest-changing commits found no Bookmarks 3.x +manifest, and no reachable cmdlets/ source history was found. The Gallery package +is therefore a hashed reference payload, not an invented Git source SHA or an +unreviewed source replacement. Reconcile that implementation with reviewed +persistence/update-check repairs through the component workflow before preparing +3.0.2. Trusted configuration now blocks Bookmarks publication and GitHub release +creation until this is reviewed; it never relabels the 2.2 monolith. + +## Why 7Zip is the sole major bump + +The reference is [7zip-Archive 1.1.0](https://www.powershellgallery.com/packages/7zip-Archive/1.1.0), +so the owner-directed next major is **2.0.0**, not 1.2.0 or a shared 1.3.0. +Reviewed develop SHA b846f1b01fad8e193cb9e92abdc75a0338c6c823 contains these +compatibility changes relative to that published payload and release source: + +- Missing runtimes no longer trigger an automatic download of bundled 7za920. + Users must install a current native 7-Zip executable themselves. +- SEVENZIP_PATH explicitly selects a full executable path and invalid overrides + fail rather than silently selecting another runtime. Otherwise discovery uses + PATH and Windows installation locations. +- Linux/macOS discovery targets native 7zz/7z/7za commands instead of assuming a + p7zip wrapper. Initialization no longer creates runtime directories/downloads. +- Native argument quoting is corrected, and invalid HelpInfoURI metadata is + removed because no updatable-help endpoint is published. + +These changes are explicit release-review items. This audit does not modify the +source version, create a 2.0 release ref, merge source, or claim a prepared 2.0.0 +package. The configured historical 1.1 source still has no committed 7Zip/out. +The existing source CI and nineteen Windows tests are evidence for source repairs; +final 2.0.0 source and installed-package validation remains required. + +## Other package decisions + +Currency-Conv 1.5.0 remains registered even though unlisted; it cannot be uploaded +again. The current source/release manifests declare that reserved version and the +configured release ref has no Currency-Conv/out. Use 1.5.1 as the reference patch +after selectively porting the reviewed cache fix and validating source/output. +Do not choose 1.0.3 merely because 1.0.2 is the latest listed package. + +Pipe keeps major 1; its source/import/alias corrections are a 1.0.1 patch plan, +not a new major. The old release output must first be reconciled with reviewed +source and regenerated. Base64String 1.3.0 remains exactly as owner-approved; +its issue22 mapping and immutable SHA are unchanged. + +Downloaded FolderEncoder 2.0.0 differs from reviewed development only in the +corrected manifest export (EncodeFolder -> Invoke-FolderEncode) and a source BOM. +The encoder implementation is otherwise unchanged, supporting the existing +2.0.1 patch candidate. Existing smoke-test limitations still apply; no encoding +roundtrip was run. New Shell/Uninstall names have no preceding package version; +the existing owner-approved candidate numbers are retained without inventing a +Gallery predecessor or taking ownership of the legacy Uninstall script. + +## How automation uses the references + +Get-ReleaseConfig.ps1 exposes latest listed, highest registered, planned version +and status. The manual workflow records them beside its immutable source SHA and +checks Test-ReleaseVersionReference.ps1 before staging. It rejects known registered +versions including unlisted 1.5.0, treats zero fourth-segment versions as the same +version, and permits only the reviewed per-module major number. Mismatch errors +identify the selected module, configured branch, prepared version and references. +Entering a number still does not rewrite any manifest or package. + +The references are dated and must be refreshed before actual rollout. They add +no network dependency to offline tests and do not replace live upload preflight, +exact downloaded-package verification, reviewed source/out matching or the +protected environment. No tag, release, upload, issue closure, secret or setting +was changed during this audit. All existing PRs remain open. + +Official references: [Gallery publishing/version guidance](https://learn.microsoft.com/en-us/powershell/gallery/concepts/publishing-guidelines), +[Bookmarks 3.0.1](https://www.powershellgallery.com/packages/Bookmarks/3.0.1), +[Currency-Conv 1.0.2](https://www.powershellgallery.com/packages/Currency-Conv/1.0.2), +and each exact-name API feed recorded in the JSON evidence.