From 2305d4f37f5659a7b98992f735f0a3a604082a8c Mon Sep 17 00:00:00 2001 From: David Fowler Date: Thu, 7 May 2026 20:28:21 -0700 Subject: [PATCH 01/35] Add npm packages for Aspire CLI Create pointer and RID-specific npm packages from the native CLI archives and wire npm packaging, verification, and staging into the existing native CLI package build. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../workflows/build-cli-native-archives.yml | 22 +- eng/clipack/Common.projitems | 14 +- eng/clipack/npm/aspire.js | 154 +++++++++++++ eng/pipelines/azure-pipelines-unofficial.yml | 5 +- eng/pipelines/azure-pipelines.yml | 5 +- eng/pipelines/templates/build_sign_native.yml | 20 ++ eng/scripts/pack-cli-npm-package.ps1 | 214 +++++++++++++++++ .../stage-native-cli-tool-packages.ps1 | 174 ++++++++++---- eng/scripts/verify-cli-npm-package.ps1 | 216 ++++++++++++++++++ .../StageNativeCliToolPackagesTests.cs | 38 ++- 10 files changed, 807 insertions(+), 55 deletions(-) create mode 100644 eng/clipack/npm/aspire.js create mode 100644 eng/scripts/pack-cli-npm-package.ps1 create mode 100644 eng/scripts/verify-cli-npm-package.ps1 diff --git a/.github/workflows/build-cli-native-archives.yml b/.github/workflows/build-cli-native-archives.yml index 685e4d89b6b..51d117d22f6 100644 --- a/.github/workflows/build-cli-native-archives.yml +++ b/.github/workflows/build-cli-native-archives.yml @@ -104,8 +104,25 @@ jobs: -Rid $rid ` -ArchivePath $archive[0].FullName - # Upload DCP, Dashboard, and CLI tool NuGets so test/polyglot jobs can download them - - name: Upload RID-specific NuGets + - name: Verify CLI npm package + shell: pwsh + run: | + $ErrorActionPreference = 'Stop' + + $rid = '${{ matrix.targets.rids }}' + $archiveExtension = if ($rid.StartsWith('win-')) { 'zip' } else { 'tar.gz' } + $archive = @(Get-ChildItem -Path 'artifacts/packages/${{ inputs.configuration }}' -Filter "aspire-cli-$rid-*.$archiveExtension" -Recurse -File -ErrorAction SilentlyContinue) + if ($archive.Count -ne 1) { + throw "Expected exactly one CLI archive for $rid, but found $($archive.Count): $($archive.FullName -join ', ')" + } + + eng/scripts/verify-cli-npm-package.ps1 ` + -PackagesDir artifacts/packages/${{ inputs.configuration }} ` + -Rid $rid ` + -ArchivePath $archive[0].FullName + + # Upload DCP, Dashboard, and CLI tool packages so test/polyglot jobs can download them + - name: Upload RID-specific packages uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0 with: name: built-nugets-for-${{ matrix.targets.rids }} @@ -113,6 +130,7 @@ jobs: artifacts/packages/${{ inputs.configuration }}/Shipping/Aspire.Hosting.Orchestration.${{ matrix.targets.rids }}.*.nupkg artifacts/packages/${{ inputs.configuration }}/Shipping/Aspire.Dashboard.Sdk.${{ matrix.targets.rids }}.*.nupkg artifacts/packages/${{ inputs.configuration }}/Shipping/Aspire.Cli.*.nupkg + artifacts/packages/${{ inputs.configuration }}/Shipping/microsoft-aspire-cli*.tgz if-no-files-found: error retention-days: 15 diff --git a/eng/clipack/Common.projitems b/eng/clipack/Common.projitems index 2796b9f4182..1b5e72f504e 100644 --- a/eng/clipack/Common.projitems +++ b/eng/clipack/Common.projitems @@ -141,7 +141,7 @@ --> + DependsOnTargets="_InitializeDotnetToolPackProperties;_ExtractNativeBinaryFromArchive;_PackRidSpecificDotnetTool;_PackPointerDotnetTool;PackNpmPackage" /> $([MSBuild]::NormalizeDirectory($(IntermediateOutputPath), 'tool-publish')) <_CliToolPublishDir>$([MSBuild]::NormalizeDirectory($(_CliToolPublishBaseDir), '$(CliRuntime)')) <_CliToolPointerPublishDir>$([MSBuild]::NormalizeDirectory($(_CliToolPublishBaseDir), 'pointer')) + <_CliNpmPackageStagingDir>$([MSBuild]::NormalizeDirectory($(IntermediateOutputPath), 'npm-packages', '$(CliRuntime)')) + <_CliNpmPackageStagingDirArg>$(_CliNpmPackageStagingDir.TrimEnd('\').TrimEnd('/')) + <_PackageOutputPathArg>$(PackageOutputPath.TrimEnd('\').TrimEnd('/')) + @microsoft/aspire-cli @@ -234,4 +238,12 @@ RemoveProperties="OutputPath;TargetFramework" /> + + + + + + diff --git a/eng/clipack/npm/aspire.js b/eng/clipack/npm/aspire.js new file mode 100644 index 00000000000..d80ff8b64d8 --- /dev/null +++ b/eng/clipack/npm/aspire.js @@ -0,0 +1,154 @@ +#!/usr/bin/env node +'use strict'; + +const childProcess = require('child_process'); +const fs = require('fs'); +const os = require('os'); +const path = require('path'); + +const ridPackageNames = loadRidPackageNames(); + +function loadRidPackageNames() { + const packageMapPath = path.join(__dirname, 'aspire-package-map.json'); + return new Map(Object.entries(JSON.parse(fs.readFileSync(packageMapPath, 'utf8')))); +} + +function detectRid() { + const platform = process.platform; + const arch = process.arch; + + if (platform === 'win32' && (arch === 'x64' || arch === 'arm64')) { + return `win-${arch}`; + } + + if (platform === 'darwin' && (arch === 'x64' || arch === 'arm64')) { + return `osx-${arch}`; + } + + if (platform === 'linux') { + if (arch === 'x64' && isMusl()) { + return 'linux-musl-x64'; + } + + if (arch === 'x64' || arch === 'arm64') { + return `linux-${arch}`; + } + } + + throw new Error(`Unsupported platform: ${platform} ${arch}`); +} + +function isMusl() { + if (process.report && typeof process.report.getReport === 'function') { + const report = process.report.getReport(); + if (report && report.header && report.header.glibcVersionRuntime) { + return false; + } + } + + const lddResult = childProcess.spawnSync('ldd', ['--version'], { encoding: 'utf8' }); + const lddOutput = `${lddResult.stdout || ''}${lddResult.stderr || ''}`.toLowerCase(); + return lddOutput.includes('musl'); +} + +function resolveNativeBinary(rid) { + const packageName = ridPackageNames.get(rid); + if (!packageName) { + throw new Error(`No Aspire CLI npm package is available for RID '${rid}'.`); + } + + let packageJsonPath; + try { + packageJsonPath = require.resolve(`${packageName}/package.json`); + } catch (error) { + throw new Error( + `The Aspire CLI native package '${packageName}' was not installed. ` + + 'Reinstall @microsoft/aspire-cli with optional dependencies enabled.', + { cause: error }); + } + + const binaryName = process.platform === 'win32' ? 'aspire.exe' : 'aspire'; + const binaryPath = path.join(path.dirname(packageJsonPath), 'bin', binaryName); + if (!fs.existsSync(binaryPath)) { + throw new Error(`The Aspire CLI native package '${packageName}' is missing '${binaryName}'.`); + } + + return { binaryPath, packageName, binaryName }; +} + +function ensureCachedBinary(sourcePath, binaryName, version, rid) { + const home = os.homedir() || os.tmpdir(); + const cacheRoot = process.env.ASPIRE_NPM_CACHE_DIR || path.join(home, '.aspire', 'npm'); + const targetDirectory = path.join(cacheRoot, version, rid, 'bin'); + const targetPath = path.join(targetDirectory, binaryName); + + fs.mkdirSync(targetDirectory, { recursive: true }); + + if (!needsCopy(sourcePath, targetPath)) { + return targetPath; + } + + const tempPath = path.join(targetDirectory, `${binaryName}.${process.pid}.${Date.now()}.tmp`); + fs.copyFileSync(sourcePath, tempPath); + + if (process.platform !== 'win32') { + fs.chmodSync(tempPath, 0o755); + } + + try { + fs.rmSync(targetPath, { force: true }); + fs.renameSync(tempPath, targetPath); + } catch (error) { + fs.rmSync(tempPath, { force: true }); + throw error; + } + + return targetPath; +} + +function needsCopy(sourcePath, targetPath) { + try { + const source = fs.statSync(sourcePath); + const target = fs.statSync(targetPath); + return source.size !== target.size; + } catch { + return true; + } +} + +function main() { + const packageJson = require(path.join(__dirname, '..', 'package.json')); + const rid = detectRid(); + const nativeBinary = resolveNativeBinary(rid); + const executablePath = ensureCachedBinary(nativeBinary.binaryPath, nativeBinary.binaryName, packageJson.version, rid); + const child = childProcess.spawn(executablePath, process.argv.slice(2), { + stdio: 'inherit', + env: { + ...process.env, + ASPIRE_NPM_PACKAGE: packageJson.name, + ASPIRE_NPM_PACKAGE_VERSION: packageJson.version, + ASPIRE_NPM_PACKAGE_RID: rid + } + }); + + child.on('error', error => { + console.error(error.message); + process.exit(1); + }); + + child.on('exit', (code, signal) => { + if (signal) { + process.kill(process.pid, signal); + return; + } + + process.exit(code === null ? 1 : code); + }); +} + +try { + main(); +} catch (error) { + console.error(error.message); + process.exit(1); +} diff --git a/eng/pipelines/azure-pipelines-unofficial.yml b/eng/pipelines/azure-pipelines-unofficial.yml index e8ab6268515..23fa469a8f8 100644 --- a/eng/pipelines/azure-pipelines-unofficial.yml +++ b/eng/pipelines/azure-pipelines-unofficial.yml @@ -173,10 +173,11 @@ extends: targetPath: '$(Build.SourcesDirectory)/artifacts/signed-archives/$(_BuildConfig)' - task: DownloadPipelineArtifact@2 - displayName: 🟣Download Native CLI Tool Packages + displayName: 🟣Download Native CLI Packages inputs: itemPattern: | **/Aspire.Cli*.nupkg + **/microsoft-aspire-cli*.tgz targetPath: '$(Build.SourcesDirectory)/artifacts/native-cli-packages/$(_BuildConfig)' - pwsh: | @@ -184,7 +185,7 @@ extends: & "$(Build.SourcesDirectory)/eng/scripts/stage-native-cli-tool-packages.ps1" ` -DownloadRoot "$(Build.SourcesDirectory)/artifacts/native-cli-packages/$(_BuildConfig)" ` -ShippingDir "$(Build.SourcesDirectory)/artifacts/packages/$(_BuildConfig)/Shipping" - displayName: 🟣Stage Native CLI Tool Packages + displayName: 🟣Stage Native CLI Packages - task: PowerShell@2 displayName: 🟣List artifacts packages contents diff --git a/eng/pipelines/azure-pipelines.yml b/eng/pipelines/azure-pipelines.yml index 2f048865d51..9e21278b44e 100644 --- a/eng/pipelines/azure-pipelines.yml +++ b/eng/pipelines/azure-pipelines.yml @@ -261,10 +261,11 @@ extends: targetPath: '$(Build.SourcesDirectory)/artifacts/signed-archives/$(_BuildConfig)' - task: DownloadPipelineArtifact@2 - displayName: 🟣Download Native CLI Tool Packages + displayName: 🟣Download Native CLI Packages inputs: itemPattern: | **/Aspire.Cli*.nupkg + **/microsoft-aspire-cli*.tgz targetPath: '$(Build.SourcesDirectory)/artifacts/native-cli-packages/$(_BuildConfig)' - pwsh: | @@ -272,7 +273,7 @@ extends: & "$(Build.SourcesDirectory)/eng/scripts/stage-native-cli-tool-packages.ps1" ` -DownloadRoot "$(Build.SourcesDirectory)/artifacts/native-cli-packages/$(_BuildConfig)" ` -ShippingDir "$(Build.SourcesDirectory)/artifacts/packages/$(_BuildConfig)/Shipping" - displayName: 🟣Stage Native CLI Tool Packages + displayName: 🟣Stage Native CLI Packages - task: PowerShell@2 displayName: 🟣List artifacts packages contents diff --git a/eng/pipelines/templates/build_sign_native.yml b/eng/pipelines/templates/build_sign_native.yml index 684f339b1b4..66c3d4b80b1 100644 --- a/eng/pipelines/templates/build_sign_native.yml +++ b/eng/pipelines/templates/build_sign_native.yml @@ -122,6 +122,11 @@ jobs: chmod +x $(Build.SourcesDirectory)/artifacts/bin/Aspire.Managed/Release/net10.0/${{ targetRid }}/publish/aspire-managed displayName: 🟣Restore execute permission on aspire-managed + - task: NodeTool@0 + displayName: 🟣Install node.js + inputs: + versionSpec: '20.x' + - script: >- $(Build.SourcesDirectory)/$(dotnetScript) msbuild @@ -165,6 +170,21 @@ jobs: & "$(Build.SourcesDirectory)/eng/scripts/verify-cli-tool-nupkg.ps1" @verifyParams displayName: 🟣Verify CLI tool nupkg (${{ targetRid }}) + - pwsh: | + $ErrorActionPreference = 'Stop' + $verifyParams = @{ + PackagesDir = "$(Build.SourcesDirectory)/artifacts/packages/$(_BuildConfig)" + Rid = "${{ targetRid }}" + } + $archiveFilter = if ("${{ targetRid }}".StartsWith('win-')) { "aspire-cli-${{ targetRid }}-*.zip" } else { "aspire-cli-${{ targetRid }}-*.tar.gz" } + $archive = @(Get-ChildItem -Path $verifyParams.PackagesDir -Filter $archiveFilter -Recurse -File -ErrorAction SilentlyContinue) + if ($archive.Count -ne 1) { + throw "Expected exactly one CLI archive for ${{ targetRid }}, but found $($archive.Count): $($archive.FullName -join ', ')" + } + $verifyParams.ArchivePath = $archive[0].FullName + & "$(Build.SourcesDirectory)/eng/scripts/verify-cli-npm-package.ps1" @verifyParams + displayName: 🟣Verify CLI npm package (${{ targetRid }}) + # Verify the signed CLI archive can execute and create a project. # Only runs when the target RID architecture matches the build agent # (i.e. the binary can execute natively without emulation). diff --git a/eng/scripts/pack-cli-npm-package.ps1 b/eng/scripts/pack-cli-npm-package.ps1 new file mode 100644 index 00000000000..a2911386f8b --- /dev/null +++ b/eng/scripts/pack-cli-npm-package.ps1 @@ -0,0 +1,214 @@ +param( + [Parameter(Mandatory = $true)] + [string]$Rid, + + [Parameter(Mandatory = $true)] + [string]$Version, + + [Parameter(Mandatory = $true)] + [string]$NativeBinaryPath, + + [Parameter(Mandatory = $true)] + [string]$OutputPath, + + [Parameter(Mandatory = $true)] + [string]$StagingRoot, + + [string]$PackageName = '@microsoft/aspire-cli' +) + +$ErrorActionPreference = 'Stop' + +function New-StringList([string[]]$Values) { + $list = [System.Collections.Generic.List[string]]::new() + foreach ($value in $Values) { + $list.Add($value) + } + return ,$list +} + +function Get-RidPackageInfo([string]$PackageRid) { + switch ($PackageRid) { + 'win-x64' { + return [ordered]@{ + BinaryName = 'aspire.exe' + Os = New-StringList 'win32' + Cpu = New-StringList 'x64' + } + } + 'win-arm64' { + return [ordered]@{ + BinaryName = 'aspire.exe' + Os = New-StringList 'win32' + Cpu = New-StringList 'arm64' + } + } + 'linux-x64' { + return [ordered]@{ + BinaryName = 'aspire' + Os = New-StringList 'linux' + Cpu = New-StringList 'x64' + Libc = New-StringList 'glibc' + } + } + 'linux-arm64' { + return [ordered]@{ + BinaryName = 'aspire' + Os = New-StringList 'linux' + Cpu = New-StringList 'arm64' + Libc = New-StringList 'glibc' + } + } + 'linux-musl-x64' { + return [ordered]@{ + BinaryName = 'aspire' + Os = New-StringList 'linux' + Cpu = New-StringList 'x64' + Libc = New-StringList 'musl' + } + } + 'osx-x64' { + return [ordered]@{ + BinaryName = 'aspire' + Os = New-StringList 'darwin' + Cpu = New-StringList 'x64' + } + } + 'osx-arm64' { + return [ordered]@{ + BinaryName = 'aspire' + Os = New-StringList 'darwin' + Cpu = New-StringList 'arm64' + } + } + default { + throw "Unsupported Aspire CLI RID for npm packaging: $PackageRid" + } + } +} + +function Write-JsonFile([string]$Path, [object]$Value) { + $json = $Value | ConvertTo-Json -Depth 20 + $utf8NoBom = [System.Text.UTF8Encoding]::new($false) + [System.IO.File]::WriteAllText($Path, "$json`n", $utf8NoBom) +} + +function Write-TextFile([string]$Path, [string]$Value) { + $utf8NoBom = [System.Text.UTF8Encoding]::new($false) + [System.IO.File]::WriteAllText($Path, $Value, $utf8NoBom) +} + +function Invoke-NpmPack([string]$PackageDirectory, [string]$DestinationDirectory) { + Write-Host "Packing npm package from $PackageDirectory" + & npm pack $PackageDirectory --pack-destination $DestinationDirectory + if ($LASTEXITCODE -ne 0) { + throw "npm pack failed for $PackageDirectory with exit code $LASTEXITCODE." + } +} + +if (-not (Test-Path -LiteralPath $NativeBinaryPath)) { + throw "Native binary path does not exist: $NativeBinaryPath" +} + +$repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '..\..')).Path +$launcherPath = Join-Path $repoRoot 'eng\clipack\npm\aspire.js' +if (-not (Test-Path -LiteralPath $launcherPath)) { + throw "Npm launcher path does not exist: $launcherPath" +} + +$ridInfo = Get-RidPackageInfo $Rid +$ridPackageName = "$PackageName-$Rid" +$supportedRids = @('win-x64', 'win-arm64', 'linux-x64', 'linux-arm64', 'linux-musl-x64', 'osx-x64', 'osx-arm64') + +Remove-Item -LiteralPath $StagingRoot -Recurse -Force -ErrorAction SilentlyContinue +New-Item -ItemType Directory -Path $StagingRoot -Force | Out-Null +New-Item -ItemType Directory -Path $OutputPath -Force | Out-Null + +$ridPackageRoot = Join-Path $StagingRoot 'rid' +$ridPackageBin = Join-Path $ridPackageRoot 'bin' +New-Item -ItemType Directory -Path $ridPackageBin -Force | Out-Null +Copy-Item -LiteralPath $NativeBinaryPath -Destination (Join-Path $ridPackageBin $ridInfo.BinaryName) -Force + +$ridPackageJson = [ordered]@{ + name = $ridPackageName + version = $Version + description = "Native Aspire CLI binary for $Rid." + license = 'MIT' + repository = [ordered]@{ + type = 'git' + url = 'git+https://github.com/microsoft/aspire.git' + } + bugs = [ordered]@{ + url = 'https://github.com/microsoft/aspire/issues' + } + os = $ridInfo.Os + cpu = $ridInfo.Cpu + files = New-StringList @('bin', 'README.md') +} + +if ($ridInfo.Contains('Libc')) { + $ridPackageJson.libc = $ridInfo.Libc +} + +Write-JsonFile (Join-Path $ridPackageRoot 'package.json') $ridPackageJson +Write-TextFile (Join-Path $ridPackageRoot 'README.md') @" +# $ridPackageName + +Native Aspire CLI binary for `$Rid`. + +This package is installed as an optional dependency of `$PackageName`. +"@ + +$pointerPackageRoot = Join-Path $StagingRoot 'pointer' +$pointerPackageBin = Join-Path $pointerPackageRoot 'bin' +New-Item -ItemType Directory -Path $pointerPackageBin -Force | Out-Null +Copy-Item -LiteralPath $launcherPath -Destination (Join-Path $pointerPackageBin 'aspire.js') -Force + +if (-not [System.Runtime.InteropServices.RuntimeInformation]::IsOSPlatform([System.Runtime.InteropServices.OSPlatform]::Windows)) { + chmod +x (Join-Path $pointerPackageBin 'aspire.js') +} + +$optionalDependencies = [ordered]@{} +foreach ($supportedRid in $supportedRids) { + $optionalDependencies["$PackageName-$supportedRid"] = $Version +} + +$ridPackageMap = [ordered]@{} +foreach ($supportedRid in $supportedRids) { + $ridPackageMap[$supportedRid] = "$PackageName-$supportedRid" +} + +$pointerPackageJson = [ordered]@{ + name = $PackageName + version = $Version + description = 'Command line tool for Aspire developers.' + license = 'MIT' + repository = [ordered]@{ + type = 'git' + url = 'git+https://github.com/microsoft/aspire.git' + } + bugs = [ordered]@{ + url = 'https://github.com/microsoft/aspire/issues' + } + bin = [ordered]@{ + aspire = 'bin/aspire.js' + } + engines = [ordered]@{ + node = '>=16' + } + optionalDependencies = $optionalDependencies + files = New-StringList @('bin', 'README.md') +} + +Write-JsonFile (Join-Path $pointerPackageRoot 'package.json') $pointerPackageJson +Write-JsonFile (Join-Path $pointerPackageBin 'aspire-package-map.json') $ridPackageMap +Write-TextFile (Join-Path $pointerPackageRoot 'README.md') @" +# $PackageName + +Npm package for the Aspire CLI. + +This package installs a small JavaScript launcher and resolves the matching native Aspire CLI package for the current platform. +"@ + +Invoke-NpmPack $ridPackageRoot $OutputPath +Invoke-NpmPack $pointerPackageRoot $OutputPath diff --git a/eng/scripts/stage-native-cli-tool-packages.ps1 b/eng/scripts/stage-native-cli-tool-packages.ps1 index 94ac98d0483..1fe8eab95cd 100644 --- a/eng/scripts/stage-native-cli-tool-packages.ps1 +++ b/eng/scripts/stage-native-cli-tool-packages.ps1 @@ -5,36 +5,69 @@ param( [Parameter(Mandatory = $true)] [string]$ShippingDir, - [string]$CanonicalPointerArtifactName = 'native_archives_win_x64' + [string]$CanonicalPointerArtifactName = 'native_archives_win_x64', + + [string]$NpmPackageFilePrefix = 'microsoft-aspire-cli' ) $ErrorActionPreference = 'Stop' New-Item -ItemType Directory -Path $ShippingDir -Force | Out-Null -$packages = @(Get-ChildItem -Path $DownloadRoot -Filter "Aspire.Cli*.nupkg" -File -Recurse | - Where-Object { $_.Name -notmatch '\.symbols\.' } | - Sort-Object FullName) -if ($packages.Count -eq 0) { - throw "No native CLI tool packages were downloaded to $DownloadRoot." +$packageVersionPattern = '(?\d+(?:\.\d+){1,3}(?:-[0-9A-Za-z][0-9A-Za-z.-]*)?)' + +function Get-NativeArchiveArtifact { + param([System.IO.FileInfo]$Package) + + $pathParts = $Package.FullName.Split([char[]]@('\', '/'), [System.StringSplitOptions]::RemoveEmptyEntries) + $nativeArchiveRoot = @($pathParts | Where-Object { $_ -like 'native_archives_*' } | Select-Object -First 1) + + if ($nativeArchiveRoot.Count -eq 0) { + return $null + } + + $artifactName = $nativeArchiveRoot[0] + return [pscustomobject]@{ + Name = $artifactName + Rid = $artifactName.Substring('native_archives_'.Length).Replace('_', '-') + } } -$packageVersionPattern = '(?\d+(?:\.\d+){1,3}(?:-[0-9A-Za-z][0-9A-Za-z.-]*)?)' -$pointerPackagePattern = "^Aspire\.Cli\.$packageVersionPattern\.nupkg$" +function New-ClassifiedPackage { + param( + [System.IO.FileInfo]$Package, + [string]$PackageKind, + [string]$ArtifactName, + [string]$ArtifactRid, + [string]$PackageVersion, + [bool]$IsPointerPackage + ) + + [pscustomobject]@{ + File = $Package + PackageKind = $PackageKind + PackageName = $Package.Name + PackageVersion = $PackageVersion + ArtifactName = $ArtifactName + ArtifactRid = $ArtifactRid + IsPointerPackage = $IsPointerPackage + } +} -$classifiedPackages = @( - foreach ($package in $packages) { - $pathParts = $package.FullName.Split([char[]]@('\', '/'), [System.StringSplitOptions]::RemoveEmptyEntries) - $nativeArchiveRoot = @($pathParts | Where-Object { $_ -like 'native_archives_*' } | Select-Object -First 1) +function Get-ClassifiedNuGetPackages { + $packages = @(Get-ChildItem -Path $DownloadRoot -Filter "Aspire.Cli*.nupkg" -File -Recurse | + Where-Object { $_.Name -notmatch '\.symbols\.' } | + Sort-Object FullName) - if ($nativeArchiveRoot.Count -eq 0) { + foreach ($package in $packages) { + $artifact = Get-NativeArchiveArtifact $package + if ($null -eq $artifact) { Write-Warning "Skipping Aspire.Cli package outside native archive artifacts: $($package.FullName)" continue } - $artifactName = $nativeArchiveRoot[0] - $artifactRid = $artifactName.Substring('native_archives_'.Length).Replace('_', '-') - $artifactRidPattern = [System.Text.RegularExpressions.Regex]::Escape($artifactRid) + $artifactRidPattern = [System.Text.RegularExpressions.Regex]::Escape($artifact.Rid) + $pointerPackagePattern = "^Aspire\.Cli\.$packageVersionPattern\.nupkg$" $ridPackagePattern = "^Aspire\.Cli\.$artifactRidPattern\.$packageVersionPattern\.nupkg$" $isPointerPackage = $false @@ -48,49 +81,96 @@ $classifiedPackages = @( } if ($null -eq $packageVersion) { - throw "Unexpected Aspire.Cli package '$($package.FullName)' in artifact '$artifactName'. Expected either an Aspire.Cli pointer package or an Aspire.Cli.$artifactRid RID-specific package." + throw "Unexpected Aspire.Cli package '$($package.FullName)' in artifact '$($artifact.Name)'. Expected either an Aspire.Cli pointer package or an Aspire.Cli.$($artifact.Rid) RID-specific package." } - [pscustomobject]@{ - File = $package - PackageName = $package.Name - PackageVersion = $packageVersion - ArtifactName = $artifactName - ArtifactRid = $artifactRid - IsPointerPackage = $isPointerPackage - } + New-ClassifiedPackage $package 'NuGet' $artifact.Name $artifact.Rid $packageVersion $isPointerPackage } -) - -if ($classifiedPackages.Count -eq 0) { - throw "No native CLI tool packages were found under native_archives_ artifacts in $DownloadRoot." } -$canonicalPointerPackages = @($classifiedPackages | Where-Object { $_.IsPointerPackage -and $_.ArtifactName -eq $CanonicalPointerArtifactName }) -if ($canonicalPointerPackages.Count -ne 1) { - throw "Expected exactly one canonical Aspire.Cli pointer package from $CanonicalPointerArtifactName, but found $($canonicalPointerPackages.Count): $($canonicalPointerPackages.File.FullName -join ', ')" -} +function Get-ClassifiedNpmPackages { + $packages = @(Get-ChildItem -Path $DownloadRoot -Filter "$NpmPackageFilePrefix*.tgz" -File -Recurse | + Sort-Object FullName) + $escapedPrefix = [System.Text.RegularExpressions.Regex]::Escape($NpmPackageFilePrefix) + + foreach ($package in $packages) { + $artifact = Get-NativeArchiveArtifact $package + if ($null -eq $artifact) { + Write-Warning "Skipping Aspire CLI npm package outside native archive artifacts: $($package.FullName)" + continue + } -$skippedPointerPackages = @($classifiedPackages | Where-Object { $_.IsPointerPackage -and $_.ArtifactName -ne $CanonicalPointerArtifactName }) -foreach ($package in $skippedPointerPackages) { - Write-Host "Skipping non-canonical Aspire.Cli pointer package from $($package.ArtifactName): $($package.File.FullName)" + $artifactRidPattern = [System.Text.RegularExpressions.Regex]::Escape($artifact.Rid) + $pointerPackagePattern = "^$escapedPrefix-$packageVersionPattern\.tgz$" + $ridPackagePattern = "^$escapedPrefix-$artifactRidPattern-$packageVersionPattern\.tgz$" + + $isPointerPackage = $false + $packageVersion = $null + + if ($package.Name -match $pointerPackagePattern) { + $isPointerPackage = $true + $packageVersion = $Matches.Version + } elseif ($package.Name -match $ridPackagePattern) { + $packageVersion = $Matches.Version + } + + if ($null -eq $packageVersion) { + throw "Unexpected Aspire CLI npm package '$($package.FullName)' in artifact '$($artifact.Name)'. Expected either a $NpmPackageFilePrefix pointer package or a $NpmPackageFilePrefix-$($artifact.Rid) RID-specific package." + } + + New-ClassifiedPackage $package 'npm' $artifact.Name $artifact.Rid $packageVersion $isPointerPackage + } } -$canonicalPointerVersion = $canonicalPointerPackages[0].PackageVersion -$ridPackages = @($classifiedPackages | Where-Object { -not $_.IsPointerPackage }) -$duplicateRidPackageGroups = @($ridPackages | Group-Object ArtifactRid | Where-Object { $_.Count -gt 1 }) -if ($duplicateRidPackageGroups.Count -gt 0) { - $details = @($duplicateRidPackageGroups | ForEach-Object { "$($_.Name): $($_.Group.File.FullName -join ', ')" }) - throw "Expected exactly one Aspire.Cli RID-specific package per RID, but found duplicates: $($details -join '; ')" +function Get-PackagesToStage { + param( + [object[]]$ClassifiedPackages, + [string]$PointerPackageDescription, + [string]$RidPackageDescription, + [string]$NoPackagesDescription + ) + + if ($ClassifiedPackages.Count -eq 0) { + throw "No $NoPackagesDescription packages were found under native_archives_ artifacts in $DownloadRoot." + } + + $canonicalPointerPackages = @($ClassifiedPackages | Where-Object { $_.IsPointerPackage -and $_.ArtifactName -eq $CanonicalPointerArtifactName }) + if ($canonicalPointerPackages.Count -ne 1) { + throw "Expected exactly one canonical $PointerPackageDescription pointer package from $CanonicalPointerArtifactName, but found $($canonicalPointerPackages.Count): $($canonicalPointerPackages.File.FullName -join ', ')" + } + + $skippedPointerPackages = @($ClassifiedPackages | Where-Object { $_.IsPointerPackage -and $_.ArtifactName -ne $CanonicalPointerArtifactName }) + foreach ($package in $skippedPointerPackages) { + Write-Host "Skipping non-canonical $PointerPackageDescription pointer package from $($package.ArtifactName): $($package.File.FullName)" + } + + $canonicalPointerVersion = $canonicalPointerPackages[0].PackageVersion + $ridPackages = @($ClassifiedPackages | Where-Object { -not $_.IsPointerPackage }) + $duplicateRidPackageGroups = @($ridPackages | Group-Object ArtifactRid | Where-Object { $_.Count -gt 1 }) + if ($duplicateRidPackageGroups.Count -gt 0) { + $details = @($duplicateRidPackageGroups | ForEach-Object { "$($_.Name): $($_.Group.File.FullName -join ', ')" }) + throw "Expected exactly one $RidPackageDescription RID-specific package per RID, but found duplicates: $($details -join '; ')" + } + + $ridPackageVersionMismatches = @($ridPackages | Where-Object { $_.PackageVersion -ne $canonicalPointerVersion }) + if ($ridPackageVersionMismatches.Count -gt 0) { + $details = @($ridPackageVersionMismatches | ForEach-Object { "$($_.PackageName) has version $($_.PackageVersion)" }) + throw "All $RidPackageDescription RID-specific packages must match canonical pointer package version $canonicalPointerVersion from $CanonicalPointerArtifactName, but found mismatches: $($details -join '; ')" + } + + return @($canonicalPointerPackages[0]) + $ridPackages } -$ridPackageVersionMismatches = @($ridPackages | Where-Object { $_.PackageVersion -ne $canonicalPointerVersion }) -if ($ridPackageVersionMismatches.Count -gt 0) { - $details = @($ridPackageVersionMismatches | ForEach-Object { "$($_.PackageName) has version $($_.PackageVersion)" }) - throw "All Aspire.Cli RID-specific packages must match canonical pointer package version $canonicalPointerVersion from $CanonicalPointerArtifactName, but found mismatches: $($details -join '; ')" +$nugetPackagesToStage = Get-PackagesToStage (Get-ClassifiedNuGetPackages) 'Aspire.Cli' 'Aspire.Cli' 'native CLI tool' +$classifiedNpmPackages = @(Get-ClassifiedNpmPackages) +$npmPackagesToStage = if ($classifiedNpmPackages.Count -eq 0) { + Write-Warning "No Aspire CLI npm packages were found under native_archives_ artifacts in $DownloadRoot." + @() +} else { + Get-PackagesToStage $classifiedNpmPackages 'Aspire CLI npm' 'Aspire CLI npm' 'Aspire CLI npm' } +$packagesToStage = @($nugetPackagesToStage) + @($npmPackagesToStage) -$packagesToStage = @($canonicalPointerPackages[0]) + $ridPackages foreach ($packageToStage in $packagesToStage) { $package = $packageToStage.File Copy-Item -LiteralPath $package.FullName -Destination (Join-Path $ShippingDir $package.Name) -Force diff --git a/eng/scripts/verify-cli-npm-package.ps1 b/eng/scripts/verify-cli-npm-package.ps1 new file mode 100644 index 00000000000..ccb2099d301 --- /dev/null +++ b/eng/scripts/verify-cli-npm-package.ps1 @@ -0,0 +1,216 @@ +param( + [Parameter(Mandatory = $true)] + [string]$PackagesDir, + + [Parameter(Mandatory = $true)] + [string]$Rid, + + [string]$ArchivePath, + + [string]$PackageName = '@microsoft/aspire-cli' +) + +$ErrorActionPreference = 'Stop' + +function Write-Step([string]$Message) { + Write-Host "[verify-cli-npm-package] $Message" +} + +function Assert-SinglePackage([object[]]$Packages, [string]$Description) { + if (-not $Packages -or $Packages.Count -eq 0) { + throw "Could not find $Description." + } + + if ($Packages.Count -gt 1) { + throw "Found multiple packages for ${Description}: $($Packages.Name -join ', ')" + } + + return $Packages[0] +} + +function Expand-Tgz([string]$PackagePath, [string]$Destination) { + New-Item -ItemType Directory -Path $Destination -Force | Out-Null + tar -xzf $PackagePath -C $Destination + if ($LASTEXITCODE -ne 0) { + throw "Failed to extract $PackagePath." + } +} + +function Expand-CliArchive([string]$Archive, [string]$Destination) { + New-Item -ItemType Directory -Path $Destination -Force | Out-Null + + if ($Archive.EndsWith('.zip', [System.StringComparison]::OrdinalIgnoreCase)) { + Add-Type -AssemblyName System.IO.Compression.FileSystem + [System.IO.Compression.ZipFile]::ExtractToDirectory($Archive, $Destination) + return + } + + if ($Archive.EndsWith('.tar.gz', [System.StringComparison]::OrdinalIgnoreCase)) { + tar -xzf $Archive -C $Destination + if ($LASTEXITCODE -ne 0) { + throw "Failed to extract CLI archive $Archive." + } + return + } + + throw "Unsupported archive format: $Archive (expected .zip or .tar.gz)." +} + +function Test-FileContentEqual([string]$ExpectedPath, [string]$ActualPath) { + $expected = Get-Item -LiteralPath $ExpectedPath + $actual = Get-Item -LiteralPath $ActualPath + if ($expected.Length -ne $actual.Length) { + return $false + } + + $expectedStream = [System.IO.File]::OpenRead($expected.FullName) + $actualStream = [System.IO.File]::OpenRead($actual.FullName) + try { + $expectedBuffer = [byte[]]::new(1024 * 1024) + $actualBuffer = [byte[]]::new(1024 * 1024) + + while ($true) { + $expectedRead = $expectedStream.Read($expectedBuffer, 0, $expectedBuffer.Length) + $actualRead = $actualStream.Read($actualBuffer, 0, $actualBuffer.Length) + + if ($expectedRead -ne $actualRead) { + return $false + } + + if ($expectedRead -eq 0) { + return $true + } + + for ($i = 0; $i -lt $expectedRead; $i++) { + if ($expectedBuffer[$i] -ne $actualBuffer[$i]) { + return $false + } + } + } + } + finally { + $expectedStream.Dispose() + $actualStream.Dispose() + } +} + +function Get-NpmPackageFilePrefix([string]$NpmPackageName) { + return $NpmPackageName.TrimStart('@').Replace('/', '-') +} + +$effectiveDir = if (Test-Path (Join-Path $PackagesDir 'Shipping')) { + Join-Path $PackagesDir 'Shipping' +} else { + $PackagesDir +} + +Write-Step "PackagesDir: $effectiveDir" +Write-Step "RID: $Rid" + +if ($ArchivePath) { + if (-not (Test-Path -LiteralPath $ArchivePath)) { + throw "ArchivePath does not exist: $ArchivePath" + } + + $ArchivePath = (Resolve-Path -LiteralPath $ArchivePath).Path + Write-Step "Archive: $ArchivePath" +} + +$packageFilePrefix = Get-NpmPackageFilePrefix $PackageName +$ridPackage = Assert-SinglePackage ` + (Get-ChildItem -Path $effectiveDir -Filter "$packageFilePrefix-$Rid-*.tgz" -ErrorAction SilentlyContinue) ` + "RID-specific npm package for $Rid" +$pointerPackage = Assert-SinglePackage ` + (Get-ChildItem -Path $effectiveDir -Filter "$packageFilePrefix-*.tgz" -ErrorAction SilentlyContinue | + Where-Object { $_.Name -notmatch "^$([System.Text.RegularExpressions.Regex]::Escape($packageFilePrefix))-(win|linux|linux-musl|osx)-(x64|arm64)-" }) ` + 'Aspire CLI npm pointer package' + +Write-Step "RID package: $($ridPackage.Name)" +Write-Step "Pointer package: $($pointerPackage.Name)" + +$root = Join-Path ([System.IO.Path]::GetTempPath()) "aspire-cli-npm-package-$([System.IO.Path]::GetRandomFileName())" +$ridExtract = Join-Path $root 'rid' +$pointerExtract = Join-Path $root 'pointer' +$archiveExtract = Join-Path $root 'archive' + +try { + Expand-Tgz $ridPackage.FullName $ridExtract + Expand-Tgz $pointerPackage.FullName $pointerExtract + + $binaryName = if ($Rid -like 'win-*') { 'aspire.exe' } else { 'aspire' } + $binaryPath = Join-Path $ridExtract "package/bin/$binaryName" + if (-not (Test-Path -LiteralPath $binaryPath)) { + throw "Could not find expected native binary at package/bin/$binaryName in $($ridPackage.Name)." + } + + if ($ArchivePath) { + Expand-CliArchive $ArchivePath $archiveExtract + $archiveBinaryPath = Join-Path $archiveExtract $binaryName + if (-not (Test-Path -LiteralPath $archiveBinaryPath)) { + throw "Could not find $binaryName in CLI archive $ArchivePath." + } + + if (-not (Test-FileContentEqual $archiveBinaryPath $binaryPath)) { + $archiveBinary = Get-Item -LiteralPath $archiveBinaryPath + $npmBinary = Get-Item -LiteralPath $binaryPath + throw "RID npm package binary does not match archive binary '$($archiveBinary.Name)'. Archive size: $($archiveBinary.Length) bytes; npm package size: $($npmBinary.Length) bytes." + } + + Write-Step "RID package binary matches CLI archive binary." + } + + $pointerPackageJsonPath = Join-Path $pointerExtract 'package/package.json' + if (-not (Test-Path -LiteralPath $pointerPackageJsonPath)) { + throw "Pointer package $($pointerPackage.Name) is missing package.json." + } + + $pointerPackageJson = Get-Content -Path $pointerPackageJsonPath -Raw | ConvertFrom-Json + $expectedRidPackageName = "$PackageName-$Rid" + if ($pointerPackageJson.name -ne $PackageName) { + throw "Pointer package name mismatch. Expected '$PackageName', got '$($pointerPackageJson.name)'." + } + + if (-not $pointerPackageJson.bin -or $pointerPackageJson.bin.aspire -ne 'bin/aspire.js') { + throw "Pointer package must expose the aspire bin at bin/aspire.js." + } + + if (-not (Test-Path -LiteralPath (Join-Path $pointerExtract 'package/bin/aspire.js'))) { + throw "Pointer package is missing bin/aspire.js." + } + + $packageMapPath = Join-Path $pointerExtract 'package/bin/aspire-package-map.json' + if (-not (Test-Path -LiteralPath $packageMapPath)) { + throw "Pointer package is missing bin/aspire-package-map.json." + } + + $packageMap = Get-Content -Path $packageMapPath -Raw | ConvertFrom-Json + if ($packageMap.$Rid -ne $expectedRidPackageName) { + throw "Pointer package map does not reference $expectedRidPackageName for $Rid." + } + + $optionalDependencyVersion = $pointerPackageJson.optionalDependencies.$expectedRidPackageName + if ($optionalDependencyVersion -ne $pointerPackageJson.version) { + throw "Pointer package optionalDependencies does not reference $expectedRidPackageName at version $($pointerPackageJson.version)." + } + + $ridPackageJsonPath = Join-Path $ridExtract 'package/package.json' + if (-not (Test-Path -LiteralPath $ridPackageJsonPath)) { + throw "RID package $($ridPackage.Name) is missing package.json." + } + + $ridPackageJson = Get-Content -Path $ridPackageJsonPath -Raw | ConvertFrom-Json + if ($ridPackageJson.name -ne $expectedRidPackageName) { + throw "RID package name mismatch. Expected '$expectedRidPackageName', got '$($ridPackageJson.name)'." + } + + if ($ridPackageJson.version -ne $pointerPackageJson.version) { + throw "RID package version '$($ridPackageJson.version)' does not match pointer package version '$($pointerPackageJson.version)'." + } + + Write-Step "CLI npm package verification passed." +} +finally { + if (Test-Path $root) { + Remove-Item -Path $root -Recurse -Force + } +} diff --git a/tests/Infrastructure.Tests/PowerShellScripts/StageNativeCliToolPackagesTests.cs b/tests/Infrastructure.Tests/PowerShellScripts/StageNativeCliToolPackagesTests.cs index 37deed78201..a7689336e39 100644 --- a/tests/Infrastructure.Tests/PowerShellScripts/StageNativeCliToolPackagesTests.cs +++ b/tests/Infrastructure.Tests/PowerShellScripts/StageNativeCliToolPackagesTests.cs @@ -68,6 +68,36 @@ public async Task StagesCanonicalPointerAndRidPackages() Assert.Contains("Skipping Aspire.Cli package outside native archive artifacts", result.Output); } + [Fact] + [RequiresTools(["pwsh"])] + public async Task StagesNpmPackagesWhenPresent() + { + var downloadRoot = CreateDownloadRoot(); + var shippingDir = CreateShippingDir(); + + CreateNativeArchivePackages(downloadRoot, "win-x64"); + CreateNativeArchivePackage(downloadRoot, "linux-x64", $"Aspire.Cli.linux-x64.{PackageVersion}.nupkg"); + CreateNativeArchiveNpmPackages(downloadRoot, "win-x64"); + CreateNativeArchiveNpmPackages(downloadRoot, "linux-x64"); + + var result = await RunScript(downloadRoot, shippingDir); + + result.EnsureSuccessful(); + + var stagedPackageNames = GetStagedPackageNames(shippingDir); + Assert.Equal( + [ + $"Aspire.Cli.{PackageVersion}.nupkg", + $"Aspire.Cli.linux-x64.{PackageVersion}.nupkg", + $"Aspire.Cli.win-x64.{PackageVersion}.nupkg", + $"microsoft-aspire-cli-{PackageVersion}.tgz", + $"microsoft-aspire-cli-linux-x64-{PackageVersion}.tgz", + $"microsoft-aspire-cli-win-x64-{PackageVersion}.tgz" + ], + stagedPackageNames); + Assert.Contains("Skipping non-canonical Aspire CLI npm pointer package", result.Output); + } + [Fact] [RequiresTools(["pwsh"])] public async Task FailsWhenCanonicalPointerPackageIsMissing() @@ -268,6 +298,12 @@ private static void CreateNativeArchivePackages(string downloadRoot, string rid) CreateNativeArchivePackage(downloadRoot, rid, $"Aspire.Cli.{rid}.{PackageVersion}.nupkg"); } + private static void CreateNativeArchiveNpmPackages(string downloadRoot, string rid) + { + CreateNativeArchivePackage(downloadRoot, rid, $"microsoft-aspire-cli-{PackageVersion}.tgz"); + CreateNativeArchivePackage(downloadRoot, rid, $"microsoft-aspire-cli-{rid}-{PackageVersion}.tgz"); + } + private static void CreateNativeArchivePackage(string downloadRoot, string rid, string packageName) { CreatePackage(downloadRoot, $"native_archives_{rid.Replace('-', '_')}", "Release", "Shipping", packageName); @@ -282,7 +318,7 @@ private static void CreatePackage(string downloadRoot, params string[] pathParts private static string[] GetStagedPackageNames(string shippingDir) { - return Directory.GetFiles(shippingDir, "Aspire.Cli*.nupkg") + return Directory.GetFiles(shippingDir) .Select(Path.GetFileName) .Order(StringComparer.Ordinal) .ToArray()!; From 8669089b62d32dd0eb018c3bbbecc2997d5dd8ec Mon Sep 17 00:00:00 2001 From: David Fowler Date: Thu, 7 May 2026 20:45:21 -0700 Subject: [PATCH 02/35] Document Aspire CLI npm package POC Add a design spec for the npm package POC and targeted comments explaining the launcher cache, generated package map, npm metadata, and package verification assumptions. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/specs/npm-cli-package.md | 161 ++++++++++++++++++ eng/clipack/npm/aspire.js | 11 ++ eng/scripts/pack-cli-npm-package.ps1 | 8 + .../stage-native-cli-tool-packages.ps1 | 4 + eng/scripts/verify-cli-npm-package.ps1 | 6 + 5 files changed, 190 insertions(+) create mode 100644 docs/specs/npm-cli-package.md diff --git a/docs/specs/npm-cli-package.md b/docs/specs/npm-cli-package.md new file mode 100644 index 00000000000..9ced2cf6fd3 --- /dev/null +++ b/docs/specs/npm-cli-package.md @@ -0,0 +1,161 @@ +# Aspire CLI npm package POC + +## Summary + +The Aspire CLI npm package POC distributes the native Aspire CLI through npm using the same native binary archives that feed the dotnet tool packages. The npm package shape follows the native-package convention used by tools such as esbuild and @vscode/ripgrep: a small top-level package exposes the command, while platform-specific packages carry the native payload. + +The POC package name is `@microsoft/aspire-cli`. It is intentionally a POC and does not yet include npm publishing, provenance, registry authentication, or CLI-side npm self-update behavior. + +## Goals + +- Produce npm tarballs as part of the same native CLI package build that produces the dotnet tool packages. +- Keep the signed native CLI archive as the canonical payload for both dotnet tool and npm package outputs. +- Use a top-level npm package with a JavaScript `bin` launcher and RID-specific optional native packages. +- Avoid running the self-extracting native binary directly from `node_modules` or package-manager stores. +- Verify generated npm packages against the native archive before staging them. + +## Non-goals + +- Publishing packages to npm or configuring registry authentication. +- Defining final public package ownership, scope, provenance, or release policy. +- Implementing `aspire update --self` for npm installs. +- Replacing the dotnet tool package flow. + +## Package layout + +The top-level package is: + +```text +@microsoft/aspire-cli +``` + +It contains: + +```text +package.json +README.md +bin/aspire.js +bin/aspire-package-map.json +``` + +The top-level `package.json` declares: + +- `bin.aspire = "bin/aspire.js"` +- `optionalDependencies` for every supported RID package at the same version +- `files = ["bin", "README.md"]` + +RID-specific packages are named by appending the RID: + +```text +@microsoft/aspire-cli-win-x64 +@microsoft/aspire-cli-win-arm64 +@microsoft/aspire-cli-linux-x64 +@microsoft/aspire-cli-linux-arm64 +@microsoft/aspire-cli-linux-musl-x64 +@microsoft/aspire-cli-osx-x64 +@microsoft/aspire-cli-osx-arm64 +``` + +Each RID package contains: + +```text +package.json +README.md +bin/aspire +``` + +or on Windows: + +```text +package.json +README.md +bin/aspire.exe +``` + +RID package metadata uses npm's platform selectors: + +- Windows packages set `os = ["win32"]` and the matching `cpu`. +- macOS packages set `os = ["darwin"]` and the matching `cpu`. +- Linux glibc packages set `os = ["linux"]`, matching `cpu`, and `libc = ["glibc"]`. +- Linux musl packages set `os = ["linux"]`, matching `cpu`, and `libc = ["musl"]`. + +## Launcher behavior + +The top-level `aspire` command runs `bin/aspire.js`. + +The launcher: + +1. Loads `bin/aspire-package-map.json`. +2. Detects the current RID from `process.platform`, `process.arch`, and libc detection for Linux. +3. Resolves the matching RID package with `require.resolve("/package.json")`. +4. Finds `bin/aspire` or `bin/aspire.exe` inside that package. +5. Copies the native binary to an Aspire-owned writable cache. +6. Spawns the cached binary with inherited stdio and forwards all command-line arguments. + +The default cache path is: + +```text +~/.aspire/npm///bin/aspire +``` + +or on Windows: + +```text +%USERPROFILE%\.aspire\npm\\\bin\aspire.exe +``` + +The cache root can be overridden with `ASPIRE_NPM_CACHE_DIR` for tests and diagnostics. + +The copy step is required because the native Aspire CLI self-extracts its embedded bundle relative to the process path on first run. Running the binary directly from `node_modules` could make the extraction target a package directory, pnpm store, Yarn unplugged location, global npm cache, or other read-only package-manager path. Copying to the Aspire cache makes first-run extraction land under an Aspire-owned writable layout. + +The launcher sets these environment variables for future CLI-side npm install detection: + +```text +ASPIRE_NPM_PACKAGE +ASPIRE_NPM_PACKAGE_VERSION +ASPIRE_NPM_PACKAGE_RID +``` + +## Build integration + +`eng\clipack\Common.projitems` wires npm packing into the existing native CLI package flow. + +`PackDotnetTool` depends on `PackNpmPackage`, so the native package build produces: + +- the existing dotnet tool pointer package +- the existing dotnet tool RID-specific package +- the npm pointer tarball +- the npm RID-specific tarball + +`PackNpmPackage` depends on `_ExtractNativeBinaryFromArchive`, which extracts `aspire` or `aspire.exe` from the native CLI archive. The npm pack script receives that extracted binary and repackages it without rebuilding or substituting another payload. + +`eng\scripts\pack-cli-npm-package.ps1` generates temporary npm package directories and invokes `npm pack` for the RID package and pointer package. + +## Verification and staging + +`eng\scripts\verify-cli-npm-package.ps1` verifies each RID build output by: + +1. Finding exactly one RID-specific npm tarball. +2. Finding exactly one npm pointer tarball. +3. Extracting both tarballs. +4. Extracting the native CLI archive. +5. Comparing the RID tarball binary byte-for-byte with the archive binary. +6. Verifying pointer package metadata, `bin/aspire.js`, `aspire-package-map.json`, and optional dependency version alignment. + +`eng\scripts\stage-native-cli-tool-packages.ps1` stages npm `.tgz` artifacts alongside existing native CLI nupkgs. Npm packages are additive: if no npm packages are present, staging warns and continues so older nupkg-only flows remain valid. + +Only one pointer package is staged. The default canonical pointer source is `native_archives_win_x64`, matching the existing native CLI package staging convention. All RID-specific packages are staged. + +## Pipeline integration + +The native archive workflows verify npm tarballs after the existing nupkg verification. + +GitHub Actions uploads `microsoft-aspire-cli*.tgz` with the RID-specific package artifacts. Azure Pipelines installs Node.js before native package build because `npm pack` runs during packaging, verifies the npm packages, downloads `microsoft-aspire-cli*.tgz` in the staging job, and stages them with the native CLI packages. + +## Open follow-ups + +- Decide the final npm scope and package names. +- Add npm publishing, provenance, and registry authentication. +- Decide whether the launcher should use stronger cache freshness than file-size comparison. +- Implement CLI-side npm install detection and self-update guidance. +- Add end-to-end installation tests against a real npm install layout. diff --git a/eng/clipack/npm/aspire.js b/eng/clipack/npm/aspire.js index d80ff8b64d8..b9d2eba8ae0 100644 --- a/eng/clipack/npm/aspire.js +++ b/eng/clipack/npm/aspire.js @@ -6,6 +6,8 @@ const fs = require('fs'); const os = require('os'); const path = require('path'); +// Package names are generated at pack time so changing the npm package name in +// MSBuild does not require editing this launcher. const ridPackageNames = loadRidPackageNames(); function loadRidPackageNames() { @@ -39,6 +41,8 @@ function detectRid() { } function isMusl() { + // npm supports libc-specific packages. Prefer Node's runtime report because + // it avoids spawning a process on glibc systems, then fall back to ldd. if (process.report && typeof process.report.getReport === 'function') { const report = process.report.getReport(); if (report && report.header && report.header.glibcVersionRuntime) { @@ -82,12 +86,17 @@ function ensureCachedBinary(sourcePath, binaryName, version, rid) { const targetDirectory = path.join(cacheRoot, version, rid, 'bin'); const targetPath = path.join(targetDirectory, binaryName); + // The Aspire CLI self-extracts relative to its process path on first run. + // Running directly from node_modules could write into read-only package + // stores, so copy the native binary to an Aspire-owned writable layout. fs.mkdirSync(targetDirectory, { recursive: true }); if (!needsCopy(sourcePath, targetPath)) { return targetPath; } + // Copy through a temp file so concurrent first runs never observe a partial + // executable at the final path. const tempPath = path.join(targetDirectory, `${binaryName}.${process.pid}.${Date.now()}.tmp`); fs.copyFileSync(sourcePath, tempPath); @@ -125,6 +134,8 @@ function main() { stdio: 'inherit', env: { ...process.env, + // Future CLI-side update detection can use these values to distinguish + // npm installs from dotnet tool installs. ASPIRE_NPM_PACKAGE: packageJson.name, ASPIRE_NPM_PACKAGE_VERSION: packageJson.version, ASPIRE_NPM_PACKAGE_RID: rid diff --git a/eng/scripts/pack-cli-npm-package.ps1 b/eng/scripts/pack-cli-npm-package.ps1 index a2911386f8b..a6d8ce5c10f 100644 --- a/eng/scripts/pack-cli-npm-package.ps1 +++ b/eng/scripts/pack-cli-npm-package.ps1 @@ -20,6 +20,8 @@ param( $ErrorActionPreference = 'Stop' function New-StringList([string[]]$Values) { + # PowerShell enumerates single-item arrays when returning from functions. + # Returning a List keeps os/cpu/libc/files as JSON arrays for npm metadata. $list = [System.Collections.Generic.List[string]]::new() foreach ($value in $Values) { $list.Add($value) @@ -28,6 +30,8 @@ function New-StringList([string[]]$Values) { } function Get-RidPackageInfo([string]$PackageRid) { + # Keep npm platform metadata aligned with the RIDs produced by the native + # archive build. npm uses os/cpu/libc to install only the matching package. switch ($PackageRid) { 'win-x64' { return [ordered]@{ @@ -106,6 +110,8 @@ function Invoke-NpmPack([string]$PackageDirectory, [string]$DestinationDirectory } } +# MSBuild extracts this from the signed native CLI archive. This script only +# repackages that payload; it must not rebuild or substitute another binary. if (-not (Test-Path -LiteralPath $NativeBinaryPath)) { throw "Native binary path does not exist: $NativeBinaryPath" } @@ -173,6 +179,8 @@ foreach ($supportedRid in $supportedRids) { $optionalDependencies["$PackageName-$supportedRid"] = $Version } +# The launcher reads this map instead of hardcoding package names so package +# scope/name changes remain an MSBuild property. $ridPackageMap = [ordered]@{} foreach ($supportedRid in $supportedRids) { $ridPackageMap[$supportedRid] = "$PackageName-$supportedRid" diff --git a/eng/scripts/stage-native-cli-tool-packages.ps1 b/eng/scripts/stage-native-cli-tool-packages.ps1 index 1fe8eab95cd..11b812d3983 100644 --- a/eng/scripts/stage-native-cli-tool-packages.ps1 +++ b/eng/scripts/stage-native-cli-tool-packages.ps1 @@ -89,6 +89,8 @@ function Get-ClassifiedNuGetPackages { } function Get-ClassifiedNpmPackages { + # Npm packages are additive to the native CLI nupkgs. If older builds only + # downloaded nupkgs, staging should continue and emit a warning below. $packages = @(Get-ChildItem -Path $DownloadRoot -Filter "$NpmPackageFilePrefix*.tgz" -File -Recurse | Sort-Object FullName) $escapedPrefix = [System.Text.RegularExpressions.Regex]::Escape($NpmPackageFilePrefix) @@ -139,6 +141,8 @@ function Get-PackagesToStage { throw "Expected exactly one canonical $PointerPackageDescription pointer package from $CanonicalPointerArtifactName, but found $($canonicalPointerPackages.Count): $($canonicalPointerPackages.File.FullName -join ', ')" } + # Pointer packages are produced for every RID build. Stage exactly one + # canonical pointer package and all RID-specific packages. $skippedPointerPackages = @($ClassifiedPackages | Where-Object { $_.IsPointerPackage -and $_.ArtifactName -ne $CanonicalPointerArtifactName }) foreach ($package in $skippedPointerPackages) { Write-Host "Skipping non-canonical $PointerPackageDescription pointer package from $($package.ArtifactName): $($package.File.FullName)" diff --git a/eng/scripts/verify-cli-npm-package.ps1 b/eng/scripts/verify-cli-npm-package.ps1 index ccb2099d301..c4abed09171 100644 --- a/eng/scripts/verify-cli-npm-package.ps1 +++ b/eng/scripts/verify-cli-npm-package.ps1 @@ -116,6 +116,8 @@ if ($ArchivePath) { Write-Step "Archive: $ArchivePath" } +# npm pack flattens scoped package names into tarball file names, e.g. +# @microsoft/aspire-cli -> microsoft-aspire-cli-1.0.0.tgz. $packageFilePrefix = Get-NpmPackageFilePrefix $PackageName $ridPackage = Assert-SinglePackage ` (Get-ChildItem -Path $effectiveDir -Filter "$packageFilePrefix-$Rid-*.tgz" -ErrorAction SilentlyContinue) ` @@ -150,6 +152,8 @@ try { throw "Could not find $binaryName in CLI archive $ArchivePath." } + # The signed native archive remains the canonical payload. The npm RID + # tarball must contain the exact same executable bytes. if (-not (Test-FileContentEqual $archiveBinaryPath $binaryPath)) { $archiveBinary = Get-Item -LiteralPath $archiveBinaryPath $npmBinary = Get-Item -LiteralPath $binaryPath @@ -183,6 +187,8 @@ try { throw "Pointer package is missing bin/aspire-package-map.json." } + # The launcher depends on this generated map to resolve the selected RID + # package without hardcoding the package scope/name. $packageMap = Get-Content -Path $packageMapPath -Raw | ConvertFrom-Json if ($packageMap.$Rid -ne $expectedRidPackageName) { throw "Pointer package map does not reference $expectedRidPackageName for $Rid." From cd4208b939a76312949943d82e37775ca0829a27 Mon Sep 17 00:00:00 2001 From: David Fowler Date: Thu, 7 May 2026 20:48:53 -0700 Subject: [PATCH 03/35] Add npm prior art to CLI package spec Document the npm and native package examples that shaped the Aspire CLI npm package POC, including optional platform packages, libc-specific packages, and writable-cache guidance. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/specs/npm-cli-package.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/specs/npm-cli-package.md b/docs/specs/npm-cli-package.md index 9ced2cf6fd3..8365508ab93 100644 --- a/docs/specs/npm-cli-package.md +++ b/docs/specs/npm-cli-package.md @@ -6,6 +6,18 @@ The Aspire CLI npm package POC distributes the native Aspire CLI through npm usi The POC package name is `@microsoft/aspire-cli`. It is intentionally a POC and does not yet include npm publishing, provenance, registry authentication, or CLI-side npm self-update behavior. +## Research and prior art + +This design follows the native npm package pattern used by established packages rather than introducing a custom installer. + +- npm's package metadata defines the primitives this POC uses: `bin` exposes a command on PATH, `optionalDependencies` allow platform-specific packages to be skipped when they do not apply, `files` limits packed content, and `os`/`cpu` select packages by `process.platform` and `process.arch`. See the npm package.json documentation for [`bin`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#bin), [`optionalDependencies`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#optionaldependencies), [`files`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#files), [`os`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#os), and [`cpu`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#cpu). +- [esbuild](https://github.com/evanw/esbuild/blob/main/npm/esbuild/package.json) uses a top-level package with a `bin` entry and platform-specific packages such as [`@esbuild/linux-x64`](https://github.com/evanw/esbuild/blob/main/npm/@esbuild/linux-x64/package.json) listed as optional dependencies. Its platform resolver maps the current Node platform to an optional package and resolves the binary through Node package resolution rather than hardcoded `node_modules` paths. +- [@vscode/ripgrep](https://github.com/microsoft/vscode-ripgrep/blob/main/packages/ripgrep/package.json) uses the same top-level package plus optional platform package shape for an external CLI binary. A platform package such as [`@vscode/ripgrep-linux-x64`](https://github.com/microsoft/vscode-ripgrep/blob/main/packages/ripgrep-linux-x64/package.json) contains a `bin/` payload and declares `os`/`cpu` metadata. +- Rollup, SWC, and sharp show the modern `libc` split for Linux native packages. Examples include [`@rollup/rollup-linux-x64-gnu`](https://github.com/rollup/rollup/blob/master/npm/linux-x64-gnu/package.json), [`@swc/core-linux-x64-gnu`](https://github.com/swc-project/swc/blob/main/packages/core/scripts/npm/linux-x64-gnu/package.json), and [`@img/sharp-linux-x64`](https://github.com/lovell/sharp/blob/main/npm/linux-x64/package.json). Their runtime loaders also distinguish glibc from musl before selecting a native package. +- Yarn's package portability guidance says packages should not write inside their own package directory outside postinstall because package directories may be read-only or backed by package-manager stores. See ["Packages should never write inside their own folder outside of postinstall"](https://yarnpkg.com/advanced/rulebook#packages-should-never-write-inside-their-own-folder-outside-of-postinstall). + +The Aspire-specific adaptation is the writable cache. Unlike most native npm CLIs, the Aspire CLI self-extracts an embedded bundle relative to its process path on first run. That means running the binary directly from the RID package would make the extraction root depend on the package-manager layout. Copying to `~/.aspire/npm///bin` keeps npm installation mechanics separate from Aspire's first-run extraction layout. + ## Goals - Produce npm tarballs as part of the same native CLI package build that produces the dotnet tool packages. From 95fbb67a25a9300c3e07a42b0b8fe3e4e64896ab Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Tue, 19 May 2026 17:56:59 -0400 Subject: [PATCH 04/35] Add npm publish workflow with provenance and OIDC support - Create .github/workflows/publish-npm.yml for manual npm package publishing - Support workflow_dispatch with inputs for version, run_id, dist_tag, pr_number, only_rid, skip_meta, and dry_run - Enable npm provenance via id-token: write permission for Trusted Publisher OIDC - Require admin/maintain permission for non-dry-run publishes - Download artifacts from specified GitHub Actions run_id - Publish RID packages before meta package with fail-fast: false matrix - Wait for RID packages to propagate on npm before publishing meta package - Support fallback to NPM_TOKEN secret until Trusted Publisher OIDC is configured - Include recovery options via only_rid and skip_meta inputs - Generate workflow summary with job status and next steps - Update docs/specs/npm-cli-package.md with publishing section and prerequisites Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/publish-npm.yml | 496 ++++++++++++++++++++++++++++++ docs/specs/npm-cli-package.md | 43 ++- 2 files changed, 535 insertions(+), 4 deletions(-) create mode 100644 .github/workflows/publish-npm.yml diff --git a/.github/workflows/publish-npm.yml b/.github/workflows/publish-npm.yml new file mode 100644 index 00000000000..0e087fa9bc1 --- /dev/null +++ b/.github/workflows/publish-npm.yml @@ -0,0 +1,496 @@ +# Publish Aspire CLI npm packages +# +# This workflow publishes the Aspire CLI npm packages (@microsoft/aspire-cli and +# platform-specific packages) from staged tarballs produced by the native archive build. +# +# Prerequisites: +# - @microsoft scope reservation on npm registry +# - npm Trusted Publisher configured for microsoft/aspire repository +# - Artifacts from build-cli-native-archives.yml must exist in the specified run_id +# +# The workflow: +# 1. Downloads existing GitHub Actions artifacts containing npm tarballs +# 2. Publishes RID-specific packages in parallel +# 3. Waits for RID packages to appear on npm (avoiding race conditions) +# 4. Publishes the meta package that references all RID packages +# +# For full documentation, see: docs/specs/npm-cli-package.md + +name: Publish npm packages + +on: + workflow_dispatch: + inputs: + release_version: + description: 'Release version (SemVer including prerelease, e.g., 9.2.0 or 9.3.0-preview.1)' + required: true + type: string + run_id: + description: 'GitHub Actions run ID containing built-nugets-for- artifacts' + required: true + type: string + dist_tag: + description: 'npm dist-tag to use for publish' + required: true + type: choice + options: + - next + - daily + - latest + - pr + default: next + pr_number: + description: 'PR number (required when dist_tag is "pr", becomes tag pr-)' + required: false + type: string + only_rid: + description: 'Publish only specific RID (for recovery), or "all" for all platforms' + required: false + type: choice + options: + - all + - win-x64 + - win-arm64 + - linux-x64 + - linux-arm64 + - linux-musl-x64 + - osx-x64 + - osx-arm64 + default: all + skip_meta: + description: 'Skip meta package publish (for recovery after RID packages published)' + required: false + type: boolean + default: false + dry_run: + description: 'Dry run mode - validate packages without publishing to npm' + required: false + type: boolean + default: true + +# Limit to one npm publish at a time +concurrency: + group: publish-npm + cancel-in-progress: false + +permissions: + id-token: write # Required for npm provenance via Trusted Publisher + contents: read # Required for actions/checkout and artifact download + actions: read # Required for gh run download + +jobs: + authorize: + name: Authorize + runs-on: ubuntu-latest + # Only require authorization for real publishes, not dry runs + if: ${{ inputs.dry_run != true }} + steps: + - name: Check if user is authorized + env: + GH_TOKEN: ${{ github.token }} + run: | + echo "Checking if ${{ github.actor }} is authorized to publish npm packages..." + + # Get the user's permission level for this repo + PERMISSION=$(gh api repos/${{ github.repository }}/collaborators/${{ github.actor }}/permission --jq '.permission') + + echo "User permission level: $PERMISSION" + + # Only allow admin or maintain permission levels + if [[ "$PERMISSION" != "admin" && "$PERMISSION" != "maintain" ]]; then + echo "❌ ERROR: User ${{ github.actor }} does not have sufficient permissions." + echo "Required: 'admin' or 'maintain' permission level for non-dry-run publishes." + echo "Current: '$PERMISSION'" + exit 1 + fi + + echo "✓ User ${{ github.actor }} is authorized (permission: $PERMISSION)" + + validate: + name: Validate Inputs + runs-on: ubuntu-latest + needs: [authorize] + if: ${{ always() && (needs.authorize.result == 'success' || needs.authorize.result == 'skipped') }} + outputs: + effective_tag: ${{ steps.compute.outputs.effective_tag }} + selected_rids: ${{ steps.compute.outputs.selected_rids }} + steps: + - name: Print Parameters + run: | + echo "=== npm Publish Workflow Parameters ===" + echo "Release Version: ${{ inputs.release_version }}" + echo "Run ID: ${{ inputs.run_id }}" + echo "Dist Tag: ${{ inputs.dist_tag }}" + echo "PR Number: ${{ inputs.pr_number }}" + echo "Only RID: ${{ inputs.only_rid }}" + echo "Skip Meta: ${{ inputs.skip_meta }}" + echo "Dry Run: ${{ inputs.dry_run }}" + echo "=========================================" + + if [ "${{ inputs.dry_run }}" == "true" ]; then + echo "" + echo "⚠️ DRY RUN MODE ENABLED" + echo " Packages will be validated but NOT published to npm." + echo "" + fi + + - name: Validate version format + run: | + VERSION="${{ inputs.release_version }}" + # SemVer regex: major.minor.patch with optional prerelease and metadata + if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9\.\-]+)?(\+[a-zA-Z0-9\.\-]+)?$ ]]; then + echo "❌ Invalid version format: $VERSION" + echo "Expected SemVer format: major.minor.patch[-prerelease][+metadata]" + echo "Examples: 9.2.0, 9.3.0-preview.1, 9.3.0-rc.2+build.123" + exit 1 + fi + echo "✓ Version format is valid: $VERSION" + + - name: Validate run_id format + run: | + RUN_ID="${{ inputs.run_id }}" + if [[ ! "$RUN_ID" =~ ^[0-9]+$ ]]; then + echo "❌ Invalid run_id format: $RUN_ID" + echo "Expected a numeric GitHub Actions run ID" + exit 1 + fi + echo "✓ Run ID format is valid: $RUN_ID" + + - name: Validate pr_number when dist_tag is pr + if: ${{ inputs.dist_tag == 'pr' }} + run: | + PR_NUMBER="${{ inputs.pr_number }}" + if [[ -z "$PR_NUMBER" || ! "$PR_NUMBER" =~ ^[0-9]+$ ]]; then + echo "❌ PR number is required and must be numeric when dist_tag is 'pr'" + echo "Provided PR number: '$PR_NUMBER'" + exit 1 + fi + echo "✓ PR number is valid: $PR_NUMBER" + + - name: Compute effective tag and selected RIDs + id: compute + run: | + # Compute effective npm tag + DIST_TAG="${{ inputs.dist_tag }}" + if [ "$DIST_TAG" == "pr" ]; then + EFFECTIVE_TAG="pr-${{ inputs.pr_number }}" + else + EFFECTIVE_TAG="$DIST_TAG" + fi + echo "effective_tag=$EFFECTIVE_TAG" >> $GITHUB_OUTPUT + echo "Effective npm tag: $EFFECTIVE_TAG" + + # Compute selected RIDs + ONLY_RID="${{ inputs.only_rid }}" + if [ "$ONLY_RID" == "all" ]; then + SELECTED_RIDS='["win-x64","win-arm64","linux-x64","linux-arm64","linux-musl-x64","osx-x64","osx-arm64"]' + else + SELECTED_RIDS='["'"$ONLY_RID"'"]' + fi + echo "selected_rids=$SELECTED_RIDS" >> $GITHUB_OUTPUT + echo "Selected RIDs: $SELECTED_RIDS" + + download: + name: Download Artifacts + runs-on: ubuntu-latest + needs: [validate] + steps: + - name: Checkout code + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + + - name: Download artifacts from run + env: + GH_TOKEN: ${{ github.token }} + run: | + echo "Downloading artifacts from run ${{ inputs.run_id }}..." + mkdir -p npm-staging + + # Download all built-nugets-for- artifacts + SELECTED_RIDS='${{ needs.validate.outputs.selected_rids }}' + + # Parse JSON array of RIDs + echo "$SELECTED_RIDS" | jq -r '.[]' | while read -r RID; do + ARTIFACT_NAME="built-nugets-for-$RID" + echo "Downloading artifact: $ARTIFACT_NAME" + + gh run download ${{ inputs.run_id }} \ + --repo ${{ github.repository }} \ + --name "$ARTIFACT_NAME" \ + --dir "npm-staging/$RID" + done + + echo "✓ Artifact download complete" + + - name: Verify required tarballs exist + run: | + echo "Verifying all required npm tarballs are present..." + SELECTED_RIDS='${{ needs.validate.outputs.selected_rids }}' + MISSING_PACKAGES=0 + + # Check for each RID package + echo "$SELECTED_RIDS" | jq -r '.[]' | while read -r RID; do + # Look for RID-specific tarball in the staging area + # Artifact structure: npm-staging//artifacts/packages/.../Shipping/microsoft-aspire-cli--*.tgz + RID_TARBALL=$(find "npm-staging/$RID" -name "microsoft-aspire-cli-$RID-*.tgz" -type f | head -1) + + if [ -z "$RID_TARBALL" ]; then + echo "❌ Missing RID package tarball for: $RID" + MISSING_PACKAGES=$((MISSING_PACKAGES + 1)) + else + echo "✓ Found RID package: $(basename "$RID_TARBALL")" + fi + done + + # Check for meta package (should be in any RID artifact, we use win-x64 as canonical) + if [[ "${{ inputs.skip_meta }}" != "true" ]]; then + # The meta package tarball should be in the canonical RID artifact (win-x64 if available) + META_TARBALL=$(find npm-staging -name "microsoft-aspire-cli-[0-9]*.tgz" -type f | grep -v -- "-win-\|-linux-\|-osx-" | head -1) + + if [ -z "$META_TARBALL" ]; then + echo "❌ Missing meta package tarball" + MISSING_PACKAGES=$((MISSING_PACKAGES + 1)) + else + echo "✓ Found meta package: $(basename "$META_TARBALL")" + fi + fi + + if [ $MISSING_PACKAGES -gt 0 ]; then + echo "" + echo "❌ ERROR: $MISSING_PACKAGES required package(s) missing from run ${{ inputs.run_id }}" + exit 1 + fi + + echo "" + echo "✓ All required npm tarballs verified" + + - name: Upload staging directory + uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0 + with: + name: npm-publish-staging + path: npm-staging/ + retention-days: 7 + if-no-files-found: error + + publish-rid-packages: + name: Publish RID Package (${{ matrix.rid }}) + runs-on: ubuntu-latest + needs: [validate, download] + strategy: + fail-fast: false + matrix: + rid: ${{ fromJson(needs.validate.outputs.selected_rids) }} + steps: + - name: Download staging artifacts + uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v7.0.1 + with: + name: npm-publish-staging + path: npm-staging + + - name: Setup Node.js + uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v5.3.0 + with: + node-version: '20' + registry-url: 'https://registry.npmjs.org' + + # TODO: Remove this fallback after npm Trusted Publisher OIDC is configured. + # Trusted Publisher should be the primary auth method going forward. + # The NODE_AUTH_TOKEN will be used if present, otherwise npm falls back to OIDC. + - name: Publish RID package + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN || '' }} + run: | + RID="${{ matrix.rid }}" + EFFECTIVE_TAG="${{ needs.validate.outputs.effective_tag }}" + DRY_RUN="${{ inputs.dry_run }}" + + # Find the RID-specific tarball + RID_TARBALL=$(find npm-staging -name "microsoft-aspire-cli-$RID-*.tgz" -type f | head -1) + + if [ -z "$RID_TARBALL" ]; then + echo "❌ ERROR: RID package tarball not found for $RID" + exit 1 + fi + + echo "Publishing: $(basename "$RID_TARBALL")" + echo "Tag: $EFFECTIVE_TAG" + echo "Dry run: $DRY_RUN" + + if [ "$DRY_RUN" == "true" ]; then + # Dry run: validate package structure without publishing + npm publish "$RID_TARBALL" --dry-run --access public --tag "$EFFECTIVE_TAG" + echo "✓ Dry run successful for $RID" + else + # Real publish with provenance + npm publish "$RID_TARBALL" --provenance --access public --tag "$EFFECTIVE_TAG" + echo "✓ Published @microsoft/aspire-cli-$RID@${{ inputs.release_version }} with tag $EFFECTIVE_TAG" + fi + + wait-for-packages: + name: Wait for RID Packages on npm + runs-on: ubuntu-latest + needs: [validate, publish-rid-packages] + if: ${{ inputs.dry_run != true && inputs.skip_meta != true }} + steps: + - name: Setup Node.js + uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v5.3.0 + with: + node-version: '20' + + - name: Wait for all RID packages to appear on npm + run: | + SELECTED_RIDS='${{ needs.validate.outputs.selected_rids }}' + VERSION="${{ inputs.release_version }}" + MAX_ATTEMPTS=30 + SLEEP_SECONDS=10 + + echo "Waiting for RID packages to appear on npm registry..." + echo "Version: $VERSION" + echo "Max wait time: $((MAX_ATTEMPTS * SLEEP_SECONDS)) seconds" + echo "" + + # Parse JSON array of RIDs into bash array + readarray -t RID_ARRAY < <(echo "$SELECTED_RIDS" | jq -r '.[]') + + ALL_VISIBLE=false + ATTEMPT=1 + + while [ $ATTEMPT -le $MAX_ATTEMPTS ] && [ "$ALL_VISIBLE" != "true" ]; do + echo "Attempt $ATTEMPT/$MAX_ATTEMPTS:" + PENDING_COUNT=0 + + for RID in "${RID_ARRAY[@]}"; do + PACKAGE_NAME="@microsoft/aspire-cli-$RID" + + # Try to fetch the specific version from npm + if npm view "$PACKAGE_NAME@$VERSION" version > /dev/null 2>&1; then + echo " ✓ $PACKAGE_NAME@$VERSION is visible" + else + echo " ⏳ $PACKAGE_NAME@$VERSION not yet visible" + PENDING_COUNT=$((PENDING_COUNT + 1)) + fi + done + + if [ $PENDING_COUNT -eq 0 ]; then + ALL_VISIBLE=true + echo "" + echo "✓ All RID packages are visible on npm" + break + fi + + if [ $ATTEMPT -lt $MAX_ATTEMPTS ]; then + echo " Waiting $SLEEP_SECONDS seconds before retry..." + sleep $SLEEP_SECONDS + fi + + ATTEMPT=$((ATTEMPT + 1)) + done + + if [ "$ALL_VISIBLE" != "true" ]; then + echo "" + echo "❌ ERROR: Timeout waiting for RID packages to appear on npm after $((MAX_ATTEMPTS * SLEEP_SECONDS)) seconds" + echo "Some packages may still be propagating. Check npm registry manually before publishing meta package." + exit 1 + fi + + publish-meta-package: + name: Publish Meta Package + runs-on: ubuntu-latest + needs: [validate, wait-for-packages] + if: ${{ always() && inputs.skip_meta != true && (needs.wait-for-packages.result == 'success' || needs.wait-for-packages.result == 'skipped') }} + steps: + - name: Download staging artifacts + uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v7.0.1 + with: + name: npm-publish-staging + path: npm-staging + + - name: Setup Node.js + uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v5.3.0 + with: + node-version: '20' + registry-url: 'https://registry.npmjs.org' + + # TODO: Remove this fallback after npm Trusted Publisher OIDC is configured. + # Trusted Publisher should be the primary auth method going forward. + # The NODE_AUTH_TOKEN will be used if present, otherwise npm falls back to OIDC. + - name: Publish meta package + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN || '' }} + run: | + EFFECTIVE_TAG="${{ needs.validate.outputs.effective_tag }}" + DRY_RUN="${{ inputs.dry_run }}" + + # Find the meta package tarball (no RID suffix in the name) + META_TARBALL=$(find npm-staging -name "microsoft-aspire-cli-[0-9]*.tgz" -type f | grep -v -- "-win-\|-linux-\|-osx-" | head -1) + + if [ -z "$META_TARBALL" ]; then + echo "❌ ERROR: Meta package tarball not found" + exit 1 + fi + + echo "Publishing: $(basename "$META_TARBALL")" + echo "Tag: $EFFECTIVE_TAG" + echo "Dry run: $DRY_RUN" + + if [ "$DRY_RUN" == "true" ]; then + # Dry run: validate package structure without publishing + npm publish "$META_TARBALL" --dry-run --access public --tag "$EFFECTIVE_TAG" + echo "✓ Dry run successful for meta package" + else + # Real publish with provenance + npm publish "$META_TARBALL" --provenance --access public --tag "$EFFECTIVE_TAG" + echo "✓ Published @microsoft/aspire-cli@${{ inputs.release_version }} with tag $EFFECTIVE_TAG" + fi + + summary: + name: Publish Summary + runs-on: ubuntu-latest + needs: [validate, authorize, download, publish-rid-packages, wait-for-packages, publish-meta-package] + if: ${{ always() }} + steps: + - name: Generate summary + run: | + cat >> $GITHUB_STEP_SUMMARY << 'EOF' + # npm Publish Workflow Summary + + ## Configuration + - **Version**: ${{ inputs.release_version }} + - **Effective Tag**: ${{ needs.validate.outputs.effective_tag }} + - **Run ID**: ${{ inputs.run_id }} + - **Selected RIDs**: ${{ needs.validate.outputs.selected_rids }} + - **Skip Meta**: ${{ inputs.skip_meta }} + - **Dry Run**: ${{ inputs.dry_run }} + + ## Job Status + - **Authorization**: ${{ needs.authorize.result }} + - **Validation**: ${{ needs.validate.result }} + - **Download**: ${{ needs.download.result }} + - **RID Package Publish**: ${{ needs.publish-rid-packages.result }} + - **Wait for Packages**: ${{ needs.wait-for-packages.result }} + - **Meta Package Publish**: ${{ needs.publish-meta-package.result }} + + ## Next Steps + EOF + + if [ "${{ inputs.dry_run }}" == "true" ]; then + cat >> $GITHUB_STEP_SUMMARY << 'EOF' + + ✓ Dry run completed successfully. To publish for real: + 1. Re-run this workflow with `dry_run: false` + 2. Ensure npm Trusted Publisher is configured for provenance + EOF + elif [ "${{ needs.publish-meta-package.result }}" == "success" ]; then + cat >> $GITHUB_STEP_SUMMARY << 'EOF' + + ✓ Publish completed successfully! + + Verify packages on npm: + - Meta package: https://www.npmjs.com/package/@microsoft/aspire-cli + - RID packages: https://www.npmjs.com/search?q=%40microsoft%2Faspire-cli- + EOF + else + cat >> $GITHUB_STEP_SUMMARY << 'EOF' + + ⚠️ Workflow completed with errors. Check job logs for details. + EOF + fi diff --git a/docs/specs/npm-cli-package.md b/docs/specs/npm-cli-package.md index 8365508ab93..e84819cbeec 100644 --- a/docs/specs/npm-cli-package.md +++ b/docs/specs/npm-cli-package.md @@ -28,8 +28,6 @@ The Aspire-specific adaptation is the writable cache. Unlike most native npm CLI ## Non-goals -- Publishing packages to npm or configuring registry authentication. -- Defining final public package ownership, scope, provenance, or release policy. - Implementing `aspire update --self` for npm installs. - Replacing the dotnet tool package flow. @@ -164,10 +162,47 @@ The native archive workflows verify npm tarballs after the existing nupkg verifi GitHub Actions uploads `microsoft-aspire-cli*.tgz` with the RID-specific package artifacts. Azure Pipelines installs Node.js before native package build because `npm pack` runs during packaging, verifies the npm packages, downloads `microsoft-aspire-cli*.tgz` in the staging job, and stages them with the native CLI packages. +## Publishing + +The npm packages are published using the manual GitHub Actions workflow `.github/workflows/publish-npm.yml`. + +### Prerequisites + +Before publishing npm packages, the following external setup must be complete: + +1. **@microsoft scope reservation**: The `@microsoft` scope must be reserved and managed by Microsoft on the npm registry. +2. **npm Trusted Publisher configuration**: The microsoft/aspire repository must be configured as a Trusted Publisher on npm to enable provenance via OIDC. This eliminates the need for long-lived NPM_TOKEN secrets. +3. **Microsoft/1ES-managed publishing**: npm publishing should be managed through Microsoft's 1ES-approved processes and infrastructure. + +The workflow includes a temporary fallback to `secrets.NPM_TOKEN` authentication, but Trusted Publisher OIDC is the recommended approach. The fallback will be removed once Trusted Publisher setup is complete. + +### Publishing workflow + +The publish workflow downloads staged npm tarballs from a completed native archive build and publishes them to npm with provenance: + +```bash +# Example: Publish packages from a build run +gh workflow run publish-npm.yml \ + --ref main \ + --field release_version="9.2.0" \ + --field run_id="12345678" \ + --field dist_tag="latest" \ + --field dry_run="false" +``` + +Key features: + +- **Dry run by default**: The workflow defaults to `dry_run: true` to validate packages before real publish. +- **Platform-first ordering**: RID-specific packages are published before the meta package to avoid `optionalDependencies` validation races. +- **Propagation wait**: The workflow polls npm until all RID packages for the target version are visible before publishing the meta package. +- **Recovery options**: The `only_rid` and `skip_meta` inputs support publishing specific RID packages or skipping the meta package if recovery is needed. +- **Provenance**: All publishes use `npm publish --provenance` when not in dry-run mode. +- **Authorization**: Non-dry-run publishes require admin or maintain repository permissions. + +For full workflow documentation, see the workflow file header and inline comments. + ## Open follow-ups -- Decide the final npm scope and package names. -- Add npm publishing, provenance, and registry authentication. - Decide whether the launcher should use stronger cache freshness than file-size comparison. - Implement CLI-side npm install detection and self-update guidance. - Add end-to-end installation tests against a real npm install layout. From 349594d43c1b9e535209392510f00d0dc4df5f42 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Tue, 19 May 2026 18:02:26 -0400 Subject: [PATCH 05/35] Fix shell subshell variable scope bug in npm publish tarball verification The MISSING_PACKAGES counter was incremented inside a pipeline subshell and never propagated to the parent shell, causing the verification check to always see 0 and never fail on missing tarballs. Changed from pipeline (echo | jq | while) to process substitution (while < <(echo | jq)) so the while loop runs in the main shell and variable updates are visible to the later check. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/publish-npm.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/publish-npm.yml b/.github/workflows/publish-npm.yml index 0e087fa9bc1..f1f0e6e2556 100644 --- a/.github/workflows/publish-npm.yml +++ b/.github/workflows/publish-npm.yml @@ -228,7 +228,7 @@ jobs: MISSING_PACKAGES=0 # Check for each RID package - echo "$SELECTED_RIDS" | jq -r '.[]' | while read -r RID; do + while read -r RID; do # Look for RID-specific tarball in the staging area # Artifact structure: npm-staging//artifacts/packages/.../Shipping/microsoft-aspire-cli--*.tgz RID_TARBALL=$(find "npm-staging/$RID" -name "microsoft-aspire-cli-$RID-*.tgz" -type f | head -1) @@ -239,7 +239,7 @@ jobs: else echo "✓ Found RID package: $(basename "$RID_TARBALL")" fi - done + done < <(echo "$SELECTED_RIDS" | jq -r '.[]') # Check for meta package (should be in any RID artifact, we use win-x64 as canonical) if [[ "${{ inputs.skip_meta }}" != "true" ]]; then From 7b6e6bf772229a3bc248729368f27963756d64a5 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Tue, 19 May 2026 18:07:26 -0400 Subject: [PATCH 06/35] Fix npm workflow: ensure meta package waits for RID packages When dry_run=true, wait-for-packages is skipped, which previously allowed publish-meta-package to start without waiting for publish-rid-packages to complete. This violated the spec requirement that RID packages must be published/validated before the meta package. Changes: - Add publish-rid-packages to publish-meta-package job needs - Update if condition to require publish-rid-packages.result == 'success' - Preserve existing behavior: wait-for-packages can be skipped (dry run) but only after RID packages complete successfully Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/publish-npm.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/publish-npm.yml b/.github/workflows/publish-npm.yml index f1f0e6e2556..e32d6e5474b 100644 --- a/.github/workflows/publish-npm.yml +++ b/.github/workflows/publish-npm.yml @@ -395,8 +395,8 @@ jobs: publish-meta-package: name: Publish Meta Package runs-on: ubuntu-latest - needs: [validate, wait-for-packages] - if: ${{ always() && inputs.skip_meta != true && (needs.wait-for-packages.result == 'success' || needs.wait-for-packages.result == 'skipped') }} + needs: [validate, publish-rid-packages, wait-for-packages] + if: ${{ always() && inputs.skip_meta != true && needs.publish-rid-packages.result == 'success' && (needs.wait-for-packages.result == 'success' || needs.wait-for-packages.result == 'skipped') }} steps: - name: Download staging artifacts uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v7.0.1 From d97012c8c253c2b7fd08735c4884cb88a824efa8 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Tue, 19 May 2026 18:16:07 -0400 Subject: [PATCH 07/35] Fix npm publish workflow: exact version matching and configurable timeout Address code review findings: 1. Exact version matching for tarballs: - Replace broad patterns (microsoft-aspire-cli-$RID-*.tgz) with exact version patterns (microsoft-aspire-cli-$RID-$VERSION.tgz) - Apply to download verification, publish-rid-packages, and publish-meta-package steps - Improve error messages to show exact expected filename when missing 2. Configurable propagation timeout: - Add propagation_timeout_seconds workflow input (default 900s = 15min) - Validate input is positive integer in validate job - Compute MAX_ATTEMPTS from timeout/sleep interval, rounding up - Include timeout in workflow summary and parameter output - Preserve bounded polling and dry-run skip behavior Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/publish-npm.yml | 61 ++++++++++++++++++++++--------- 1 file changed, 43 insertions(+), 18 deletions(-) diff --git a/.github/workflows/publish-npm.yml b/.github/workflows/publish-npm.yml index e32d6e5474b..4b174cf3781 100644 --- a/.github/workflows/publish-npm.yml +++ b/.github/workflows/publish-npm.yml @@ -67,6 +67,11 @@ on: required: false type: boolean default: true + propagation_timeout_seconds: + description: 'Maximum seconds to wait for RID packages to appear on npm (default: 900 = 15 minutes)' + required: false + type: number + default: 900 # Limit to one npm publish at a time concurrency: @@ -125,6 +130,7 @@ jobs: echo "Only RID: ${{ inputs.only_rid }}" echo "Skip Meta: ${{ inputs.skip_meta }}" echo "Dry Run: ${{ inputs.dry_run }}" + echo "Propagation Timeout: ${{ inputs.propagation_timeout_seconds }} seconds" echo "=========================================" if [ "${{ inputs.dry_run }}" == "true" ]; then @@ -167,6 +173,17 @@ jobs: fi echo "✓ PR number is valid: $PR_NUMBER" + - name: Validate propagation_timeout_seconds + run: | + TIMEOUT="${{ inputs.propagation_timeout_seconds }}" + # Check if it's a positive integer + if [[ ! "$TIMEOUT" =~ ^[0-9]+$ ]] || [ "$TIMEOUT" -le 0 ]; then + echo "❌ Invalid propagation_timeout_seconds: $TIMEOUT" + echo "Expected a positive integer (seconds)" + exit 1 + fi + echo "✓ Propagation timeout is valid: $TIMEOUT seconds" + - name: Compute effective tag and selected RIDs id: compute run: | @@ -225,16 +242,17 @@ jobs: run: | echo "Verifying all required npm tarballs are present..." SELECTED_RIDS='${{ needs.validate.outputs.selected_rids }}' + VERSION="${{ inputs.release_version }}" MISSING_PACKAGES=0 # Check for each RID package while read -r RID; do - # Look for RID-specific tarball in the staging area - # Artifact structure: npm-staging//artifacts/packages/.../Shipping/microsoft-aspire-cli--*.tgz - RID_TARBALL=$(find "npm-staging/$RID" -name "microsoft-aspire-cli-$RID-*.tgz" -type f | head -1) + # Look for exact version tarball: microsoft-aspire-cli--.tgz + # Artifact structure: npm-staging//artifacts/packages/.../Shipping/microsoft-aspire-cli--.tgz + RID_TARBALL=$(find "npm-staging/$RID" -name "microsoft-aspire-cli-$RID-$VERSION.tgz" -type f | head -1) if [ -z "$RID_TARBALL" ]; then - echo "❌ Missing RID package tarball for: $RID" + echo "❌ Missing expected RID package tarball: microsoft-aspire-cli-$RID-$VERSION.tgz" MISSING_PACKAGES=$((MISSING_PACKAGES + 1)) else echo "✓ Found RID package: $(basename "$RID_TARBALL")" @@ -243,11 +261,11 @@ jobs: # Check for meta package (should be in any RID artifact, we use win-x64 as canonical) if [[ "${{ inputs.skip_meta }}" != "true" ]]; then - # The meta package tarball should be in the canonical RID artifact (win-x64 if available) - META_TARBALL=$(find npm-staging -name "microsoft-aspire-cli-[0-9]*.tgz" -type f | grep -v -- "-win-\|-linux-\|-osx-" | head -1) + # Look for exact version tarball: microsoft-aspire-cli-.tgz (no RID suffix) + META_TARBALL=$(find npm-staging -name "microsoft-aspire-cli-$VERSION.tgz" -type f | head -1) if [ -z "$META_TARBALL" ]; then - echo "❌ Missing meta package tarball" + echo "❌ Missing expected meta package tarball: microsoft-aspire-cli-$VERSION.tgz" MISSING_PACKAGES=$((MISSING_PACKAGES + 1)) else echo "✓ Found meta package: $(basename "$META_TARBALL")" @@ -300,14 +318,15 @@ jobs: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN || '' }} run: | RID="${{ matrix.rid }}" + VERSION="${{ inputs.release_version }}" EFFECTIVE_TAG="${{ needs.validate.outputs.effective_tag }}" DRY_RUN="${{ inputs.dry_run }}" - # Find the RID-specific tarball - RID_TARBALL=$(find npm-staging -name "microsoft-aspire-cli-$RID-*.tgz" -type f | head -1) + # Find the exact version tarball: microsoft-aspire-cli--.tgz + RID_TARBALL=$(find npm-staging -name "microsoft-aspire-cli-$RID-$VERSION.tgz" -type f | head -1) if [ -z "$RID_TARBALL" ]; then - echo "❌ ERROR: RID package tarball not found for $RID" + echo "❌ ERROR: Expected RID package tarball not found: microsoft-aspire-cli-$RID-$VERSION.tgz" exit 1 fi @@ -322,7 +341,7 @@ jobs: else # Real publish with provenance npm publish "$RID_TARBALL" --provenance --access public --tag "$EFFECTIVE_TAG" - echo "✓ Published @microsoft/aspire-cli-$RID@${{ inputs.release_version }} with tag $EFFECTIVE_TAG" + echo "✓ Published @microsoft/aspire-cli-$RID@$VERSION with tag $EFFECTIVE_TAG" fi wait-for-packages: @@ -340,12 +359,16 @@ jobs: run: | SELECTED_RIDS='${{ needs.validate.outputs.selected_rids }}' VERSION="${{ inputs.release_version }}" - MAX_ATTEMPTS=30 + TIMEOUT_SECONDS="${{ inputs.propagation_timeout_seconds }}" SLEEP_SECONDS=10 + # Compute max attempts from timeout, rounding up to honor at least the requested duration + MAX_ATTEMPTS=$(( (TIMEOUT_SECONDS + SLEEP_SECONDS - 1) / SLEEP_SECONDS )) + echo "Waiting for RID packages to appear on npm registry..." echo "Version: $VERSION" - echo "Max wait time: $((MAX_ATTEMPTS * SLEEP_SECONDS)) seconds" + echo "Timeout: $TIMEOUT_SECONDS seconds" + echo "Max attempts: $MAX_ATTEMPTS (checking every $SLEEP_SECONDS seconds)" echo "" # Parse JSON array of RIDs into bash array @@ -387,7 +410,7 @@ jobs: if [ "$ALL_VISIBLE" != "true" ]; then echo "" - echo "❌ ERROR: Timeout waiting for RID packages to appear on npm after $((MAX_ATTEMPTS * SLEEP_SECONDS)) seconds" + echo "❌ ERROR: Timeout waiting for RID packages to appear on npm after $TIMEOUT_SECONDS seconds" echo "Some packages may still be propagating. Check npm registry manually before publishing meta package." exit 1 fi @@ -417,14 +440,15 @@ jobs: env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN || '' }} run: | + VERSION="${{ inputs.release_version }}" EFFECTIVE_TAG="${{ needs.validate.outputs.effective_tag }}" DRY_RUN="${{ inputs.dry_run }}" - # Find the meta package tarball (no RID suffix in the name) - META_TARBALL=$(find npm-staging -name "microsoft-aspire-cli-[0-9]*.tgz" -type f | grep -v -- "-win-\|-linux-\|-osx-" | head -1) + # Find the exact version tarball: microsoft-aspire-cli-.tgz (no RID suffix) + META_TARBALL=$(find npm-staging -name "microsoft-aspire-cli-$VERSION.tgz" -type f | head -1) if [ -z "$META_TARBALL" ]; then - echo "❌ ERROR: Meta package tarball not found" + echo "❌ ERROR: Expected meta package tarball not found: microsoft-aspire-cli-$VERSION.tgz" exit 1 fi @@ -439,7 +463,7 @@ jobs: else # Real publish with provenance npm publish "$META_TARBALL" --provenance --access public --tag "$EFFECTIVE_TAG" - echo "✓ Published @microsoft/aspire-cli@${{ inputs.release_version }} with tag $EFFECTIVE_TAG" + echo "✓ Published @microsoft/aspire-cli@$VERSION with tag $EFFECTIVE_TAG" fi summary: @@ -460,6 +484,7 @@ jobs: - **Selected RIDs**: ${{ needs.validate.outputs.selected_rids }} - **Skip Meta**: ${{ inputs.skip_meta }} - **Dry Run**: ${{ inputs.dry_run }} + - **Propagation Timeout**: ${{ inputs.propagation_timeout_seconds }} seconds ## Job Status - **Authorization**: ${{ needs.authorize.result }} From 76b9e56065f87a3317c1ee2633600e6f06e3197e Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Thu, 28 May 2026 15:08:23 -0400 Subject: [PATCH 08/35] Move @microsoft/aspire-cli npm publishing into the AzDO release pipeline Publishing the @microsoft/aspire-cli scoped npm packages now happens via the AzDO release pipeline (eng/pipelines/release-publish-nuget.yml) using the MicroBuild ESRP publish template, instead of the previous GitHub Actions publish-npm.yml workflow. The release pipeline extends from 1ES.Official.Publish.yml@MicroBuildTemplate so it has access to the DevDivEsrpAzDoSrvConn service connection. Per-platform artifacts and the pointer package are produced and verified during the source build (azure-pipelines.yml + build_sign_native.yml), then flat-shipped via BlobArtifacts (eng/Publishing.props). The release pipeline splits them into RID and pointer pipeline-artifact folders, attaches SBOMs, and submits two MicroBuild.Publish.yml invocations (RID packages first, then pointer) with a configurable propagation delay so the pointer never resolves to a missing optional dependency. Also fixed a cross-platform path bug in eng/clipack/Common.projitems where $(RepoRoot)eng\\scripts\\pack-cli-npm-package.ps1 mixed separators in a way that breaks pwsh resolution on Linux/macOS, and added the actions/setup-node step missing from .github/workflows/build-cli-native-archives.yml now that PackDotnetTool depends on PackNpmPackage (which calls npm pack). Note: the npm contentType for MicroBuild.Publish.yml is documented in the ESRP onboarding doc but the task itself is not yet shipped for npm. The release pipeline is wired against the documented parameter shape so it can go live the moment the task is available; today's release flow can run with SkipNpmPublish=true. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../workflows/build-cli-native-archives.yml | 10 + .github/workflows/publish-npm.yml | 521 ------------------ docs/release-process.md | 339 ++++++------ docs/specs/npm-cli-package.md | 49 +- eng/Publishing.props | 24 + eng/clipack/Common.projitems | 9 +- eng/pipelines/azure-pipelines-unofficial.yml | 3 +- eng/pipelines/azure-pipelines.yml | 3 +- eng/pipelines/release-publish-nuget.yml | 297 +++++++++- .../stage-native-cli-tool-packages.ps1 | 13 +- .../StageNativeCliToolPackagesTests.cs | 19 +- 11 files changed, 540 insertions(+), 747 deletions(-) delete mode 100644 .github/workflows/publish-npm.yml diff --git a/.github/workflows/build-cli-native-archives.yml b/.github/workflows/build-cli-native-archives.yml index 51d117d22f6..a7d49b99d40 100644 --- a/.github/workflows/build-cli-native-archives.yml +++ b/.github/workflows/build-cli-native-archives.yml @@ -38,6 +38,16 @@ jobs: - name: Checkout code uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + # Node.js is required because PackDotnetTool now depends on PackNpmPackage, + # which shells out to `npm pack` to produce the @microsoft/aspire-cli npm + # tarballs alongside the existing dotnet tool packages. GitHub-hosted + # runners ship Node by default, but installing it explicitly pins the + # version and avoids relying on the runner image. + - name: Install node.js + uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0 + with: + node-version: 20.x + # Build RID-specific NuGet packages (DCP + Dashboard) locally instead of # downloading them from the build_packages job. This allows the CLI archive # build to run in parallel with build_packages. diff --git a/.github/workflows/publish-npm.yml b/.github/workflows/publish-npm.yml deleted file mode 100644 index 4b174cf3781..00000000000 --- a/.github/workflows/publish-npm.yml +++ /dev/null @@ -1,521 +0,0 @@ -# Publish Aspire CLI npm packages -# -# This workflow publishes the Aspire CLI npm packages (@microsoft/aspire-cli and -# platform-specific packages) from staged tarballs produced by the native archive build. -# -# Prerequisites: -# - @microsoft scope reservation on npm registry -# - npm Trusted Publisher configured for microsoft/aspire repository -# - Artifacts from build-cli-native-archives.yml must exist in the specified run_id -# -# The workflow: -# 1. Downloads existing GitHub Actions artifacts containing npm tarballs -# 2. Publishes RID-specific packages in parallel -# 3. Waits for RID packages to appear on npm (avoiding race conditions) -# 4. Publishes the meta package that references all RID packages -# -# For full documentation, see: docs/specs/npm-cli-package.md - -name: Publish npm packages - -on: - workflow_dispatch: - inputs: - release_version: - description: 'Release version (SemVer including prerelease, e.g., 9.2.0 or 9.3.0-preview.1)' - required: true - type: string - run_id: - description: 'GitHub Actions run ID containing built-nugets-for- artifacts' - required: true - type: string - dist_tag: - description: 'npm dist-tag to use for publish' - required: true - type: choice - options: - - next - - daily - - latest - - pr - default: next - pr_number: - description: 'PR number (required when dist_tag is "pr", becomes tag pr-)' - required: false - type: string - only_rid: - description: 'Publish only specific RID (for recovery), or "all" for all platforms' - required: false - type: choice - options: - - all - - win-x64 - - win-arm64 - - linux-x64 - - linux-arm64 - - linux-musl-x64 - - osx-x64 - - osx-arm64 - default: all - skip_meta: - description: 'Skip meta package publish (for recovery after RID packages published)' - required: false - type: boolean - default: false - dry_run: - description: 'Dry run mode - validate packages without publishing to npm' - required: false - type: boolean - default: true - propagation_timeout_seconds: - description: 'Maximum seconds to wait for RID packages to appear on npm (default: 900 = 15 minutes)' - required: false - type: number - default: 900 - -# Limit to one npm publish at a time -concurrency: - group: publish-npm - cancel-in-progress: false - -permissions: - id-token: write # Required for npm provenance via Trusted Publisher - contents: read # Required for actions/checkout and artifact download - actions: read # Required for gh run download - -jobs: - authorize: - name: Authorize - runs-on: ubuntu-latest - # Only require authorization for real publishes, not dry runs - if: ${{ inputs.dry_run != true }} - steps: - - name: Check if user is authorized - env: - GH_TOKEN: ${{ github.token }} - run: | - echo "Checking if ${{ github.actor }} is authorized to publish npm packages..." - - # Get the user's permission level for this repo - PERMISSION=$(gh api repos/${{ github.repository }}/collaborators/${{ github.actor }}/permission --jq '.permission') - - echo "User permission level: $PERMISSION" - - # Only allow admin or maintain permission levels - if [[ "$PERMISSION" != "admin" && "$PERMISSION" != "maintain" ]]; then - echo "❌ ERROR: User ${{ github.actor }} does not have sufficient permissions." - echo "Required: 'admin' or 'maintain' permission level for non-dry-run publishes." - echo "Current: '$PERMISSION'" - exit 1 - fi - - echo "✓ User ${{ github.actor }} is authorized (permission: $PERMISSION)" - - validate: - name: Validate Inputs - runs-on: ubuntu-latest - needs: [authorize] - if: ${{ always() && (needs.authorize.result == 'success' || needs.authorize.result == 'skipped') }} - outputs: - effective_tag: ${{ steps.compute.outputs.effective_tag }} - selected_rids: ${{ steps.compute.outputs.selected_rids }} - steps: - - name: Print Parameters - run: | - echo "=== npm Publish Workflow Parameters ===" - echo "Release Version: ${{ inputs.release_version }}" - echo "Run ID: ${{ inputs.run_id }}" - echo "Dist Tag: ${{ inputs.dist_tag }}" - echo "PR Number: ${{ inputs.pr_number }}" - echo "Only RID: ${{ inputs.only_rid }}" - echo "Skip Meta: ${{ inputs.skip_meta }}" - echo "Dry Run: ${{ inputs.dry_run }}" - echo "Propagation Timeout: ${{ inputs.propagation_timeout_seconds }} seconds" - echo "=========================================" - - if [ "${{ inputs.dry_run }}" == "true" ]; then - echo "" - echo "⚠️ DRY RUN MODE ENABLED" - echo " Packages will be validated but NOT published to npm." - echo "" - fi - - - name: Validate version format - run: | - VERSION="${{ inputs.release_version }}" - # SemVer regex: major.minor.patch with optional prerelease and metadata - if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9\.\-]+)?(\+[a-zA-Z0-9\.\-]+)?$ ]]; then - echo "❌ Invalid version format: $VERSION" - echo "Expected SemVer format: major.minor.patch[-prerelease][+metadata]" - echo "Examples: 9.2.0, 9.3.0-preview.1, 9.3.0-rc.2+build.123" - exit 1 - fi - echo "✓ Version format is valid: $VERSION" - - - name: Validate run_id format - run: | - RUN_ID="${{ inputs.run_id }}" - if [[ ! "$RUN_ID" =~ ^[0-9]+$ ]]; then - echo "❌ Invalid run_id format: $RUN_ID" - echo "Expected a numeric GitHub Actions run ID" - exit 1 - fi - echo "✓ Run ID format is valid: $RUN_ID" - - - name: Validate pr_number when dist_tag is pr - if: ${{ inputs.dist_tag == 'pr' }} - run: | - PR_NUMBER="${{ inputs.pr_number }}" - if [[ -z "$PR_NUMBER" || ! "$PR_NUMBER" =~ ^[0-9]+$ ]]; then - echo "❌ PR number is required and must be numeric when dist_tag is 'pr'" - echo "Provided PR number: '$PR_NUMBER'" - exit 1 - fi - echo "✓ PR number is valid: $PR_NUMBER" - - - name: Validate propagation_timeout_seconds - run: | - TIMEOUT="${{ inputs.propagation_timeout_seconds }}" - # Check if it's a positive integer - if [[ ! "$TIMEOUT" =~ ^[0-9]+$ ]] || [ "$TIMEOUT" -le 0 ]; then - echo "❌ Invalid propagation_timeout_seconds: $TIMEOUT" - echo "Expected a positive integer (seconds)" - exit 1 - fi - echo "✓ Propagation timeout is valid: $TIMEOUT seconds" - - - name: Compute effective tag and selected RIDs - id: compute - run: | - # Compute effective npm tag - DIST_TAG="${{ inputs.dist_tag }}" - if [ "$DIST_TAG" == "pr" ]; then - EFFECTIVE_TAG="pr-${{ inputs.pr_number }}" - else - EFFECTIVE_TAG="$DIST_TAG" - fi - echo "effective_tag=$EFFECTIVE_TAG" >> $GITHUB_OUTPUT - echo "Effective npm tag: $EFFECTIVE_TAG" - - # Compute selected RIDs - ONLY_RID="${{ inputs.only_rid }}" - if [ "$ONLY_RID" == "all" ]; then - SELECTED_RIDS='["win-x64","win-arm64","linux-x64","linux-arm64","linux-musl-x64","osx-x64","osx-arm64"]' - else - SELECTED_RIDS='["'"$ONLY_RID"'"]' - fi - echo "selected_rids=$SELECTED_RIDS" >> $GITHUB_OUTPUT - echo "Selected RIDs: $SELECTED_RIDS" - - download: - name: Download Artifacts - runs-on: ubuntu-latest - needs: [validate] - steps: - - name: Checkout code - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - - name: Download artifacts from run - env: - GH_TOKEN: ${{ github.token }} - run: | - echo "Downloading artifacts from run ${{ inputs.run_id }}..." - mkdir -p npm-staging - - # Download all built-nugets-for- artifacts - SELECTED_RIDS='${{ needs.validate.outputs.selected_rids }}' - - # Parse JSON array of RIDs - echo "$SELECTED_RIDS" | jq -r '.[]' | while read -r RID; do - ARTIFACT_NAME="built-nugets-for-$RID" - echo "Downloading artifact: $ARTIFACT_NAME" - - gh run download ${{ inputs.run_id }} \ - --repo ${{ github.repository }} \ - --name "$ARTIFACT_NAME" \ - --dir "npm-staging/$RID" - done - - echo "✓ Artifact download complete" - - - name: Verify required tarballs exist - run: | - echo "Verifying all required npm tarballs are present..." - SELECTED_RIDS='${{ needs.validate.outputs.selected_rids }}' - VERSION="${{ inputs.release_version }}" - MISSING_PACKAGES=0 - - # Check for each RID package - while read -r RID; do - # Look for exact version tarball: microsoft-aspire-cli--.tgz - # Artifact structure: npm-staging//artifacts/packages/.../Shipping/microsoft-aspire-cli--.tgz - RID_TARBALL=$(find "npm-staging/$RID" -name "microsoft-aspire-cli-$RID-$VERSION.tgz" -type f | head -1) - - if [ -z "$RID_TARBALL" ]; then - echo "❌ Missing expected RID package tarball: microsoft-aspire-cli-$RID-$VERSION.tgz" - MISSING_PACKAGES=$((MISSING_PACKAGES + 1)) - else - echo "✓ Found RID package: $(basename "$RID_TARBALL")" - fi - done < <(echo "$SELECTED_RIDS" | jq -r '.[]') - - # Check for meta package (should be in any RID artifact, we use win-x64 as canonical) - if [[ "${{ inputs.skip_meta }}" != "true" ]]; then - # Look for exact version tarball: microsoft-aspire-cli-.tgz (no RID suffix) - META_TARBALL=$(find npm-staging -name "microsoft-aspire-cli-$VERSION.tgz" -type f | head -1) - - if [ -z "$META_TARBALL" ]; then - echo "❌ Missing expected meta package tarball: microsoft-aspire-cli-$VERSION.tgz" - MISSING_PACKAGES=$((MISSING_PACKAGES + 1)) - else - echo "✓ Found meta package: $(basename "$META_TARBALL")" - fi - fi - - if [ $MISSING_PACKAGES -gt 0 ]; then - echo "" - echo "❌ ERROR: $MISSING_PACKAGES required package(s) missing from run ${{ inputs.run_id }}" - exit 1 - fi - - echo "" - echo "✓ All required npm tarballs verified" - - - name: Upload staging directory - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0 - with: - name: npm-publish-staging - path: npm-staging/ - retention-days: 7 - if-no-files-found: error - - publish-rid-packages: - name: Publish RID Package (${{ matrix.rid }}) - runs-on: ubuntu-latest - needs: [validate, download] - strategy: - fail-fast: false - matrix: - rid: ${{ fromJson(needs.validate.outputs.selected_rids) }} - steps: - - name: Download staging artifacts - uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v7.0.1 - with: - name: npm-publish-staging - path: npm-staging - - - name: Setup Node.js - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v5.3.0 - with: - node-version: '20' - registry-url: 'https://registry.npmjs.org' - - # TODO: Remove this fallback after npm Trusted Publisher OIDC is configured. - # Trusted Publisher should be the primary auth method going forward. - # The NODE_AUTH_TOKEN will be used if present, otherwise npm falls back to OIDC. - - name: Publish RID package - env: - NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN || '' }} - run: | - RID="${{ matrix.rid }}" - VERSION="${{ inputs.release_version }}" - EFFECTIVE_TAG="${{ needs.validate.outputs.effective_tag }}" - DRY_RUN="${{ inputs.dry_run }}" - - # Find the exact version tarball: microsoft-aspire-cli--.tgz - RID_TARBALL=$(find npm-staging -name "microsoft-aspire-cli-$RID-$VERSION.tgz" -type f | head -1) - - if [ -z "$RID_TARBALL" ]; then - echo "❌ ERROR: Expected RID package tarball not found: microsoft-aspire-cli-$RID-$VERSION.tgz" - exit 1 - fi - - echo "Publishing: $(basename "$RID_TARBALL")" - echo "Tag: $EFFECTIVE_TAG" - echo "Dry run: $DRY_RUN" - - if [ "$DRY_RUN" == "true" ]; then - # Dry run: validate package structure without publishing - npm publish "$RID_TARBALL" --dry-run --access public --tag "$EFFECTIVE_TAG" - echo "✓ Dry run successful for $RID" - else - # Real publish with provenance - npm publish "$RID_TARBALL" --provenance --access public --tag "$EFFECTIVE_TAG" - echo "✓ Published @microsoft/aspire-cli-$RID@$VERSION with tag $EFFECTIVE_TAG" - fi - - wait-for-packages: - name: Wait for RID Packages on npm - runs-on: ubuntu-latest - needs: [validate, publish-rid-packages] - if: ${{ inputs.dry_run != true && inputs.skip_meta != true }} - steps: - - name: Setup Node.js - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v5.3.0 - with: - node-version: '20' - - - name: Wait for all RID packages to appear on npm - run: | - SELECTED_RIDS='${{ needs.validate.outputs.selected_rids }}' - VERSION="${{ inputs.release_version }}" - TIMEOUT_SECONDS="${{ inputs.propagation_timeout_seconds }}" - SLEEP_SECONDS=10 - - # Compute max attempts from timeout, rounding up to honor at least the requested duration - MAX_ATTEMPTS=$(( (TIMEOUT_SECONDS + SLEEP_SECONDS - 1) / SLEEP_SECONDS )) - - echo "Waiting for RID packages to appear on npm registry..." - echo "Version: $VERSION" - echo "Timeout: $TIMEOUT_SECONDS seconds" - echo "Max attempts: $MAX_ATTEMPTS (checking every $SLEEP_SECONDS seconds)" - echo "" - - # Parse JSON array of RIDs into bash array - readarray -t RID_ARRAY < <(echo "$SELECTED_RIDS" | jq -r '.[]') - - ALL_VISIBLE=false - ATTEMPT=1 - - while [ $ATTEMPT -le $MAX_ATTEMPTS ] && [ "$ALL_VISIBLE" != "true" ]; do - echo "Attempt $ATTEMPT/$MAX_ATTEMPTS:" - PENDING_COUNT=0 - - for RID in "${RID_ARRAY[@]}"; do - PACKAGE_NAME="@microsoft/aspire-cli-$RID" - - # Try to fetch the specific version from npm - if npm view "$PACKAGE_NAME@$VERSION" version > /dev/null 2>&1; then - echo " ✓ $PACKAGE_NAME@$VERSION is visible" - else - echo " ⏳ $PACKAGE_NAME@$VERSION not yet visible" - PENDING_COUNT=$((PENDING_COUNT + 1)) - fi - done - - if [ $PENDING_COUNT -eq 0 ]; then - ALL_VISIBLE=true - echo "" - echo "✓ All RID packages are visible on npm" - break - fi - - if [ $ATTEMPT -lt $MAX_ATTEMPTS ]; then - echo " Waiting $SLEEP_SECONDS seconds before retry..." - sleep $SLEEP_SECONDS - fi - - ATTEMPT=$((ATTEMPT + 1)) - done - - if [ "$ALL_VISIBLE" != "true" ]; then - echo "" - echo "❌ ERROR: Timeout waiting for RID packages to appear on npm after $TIMEOUT_SECONDS seconds" - echo "Some packages may still be propagating. Check npm registry manually before publishing meta package." - exit 1 - fi - - publish-meta-package: - name: Publish Meta Package - runs-on: ubuntu-latest - needs: [validate, publish-rid-packages, wait-for-packages] - if: ${{ always() && inputs.skip_meta != true && needs.publish-rid-packages.result == 'success' && (needs.wait-for-packages.result == 'success' || needs.wait-for-packages.result == 'skipped') }} - steps: - - name: Download staging artifacts - uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v7.0.1 - with: - name: npm-publish-staging - path: npm-staging - - - name: Setup Node.js - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v5.3.0 - with: - node-version: '20' - registry-url: 'https://registry.npmjs.org' - - # TODO: Remove this fallback after npm Trusted Publisher OIDC is configured. - # Trusted Publisher should be the primary auth method going forward. - # The NODE_AUTH_TOKEN will be used if present, otherwise npm falls back to OIDC. - - name: Publish meta package - env: - NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN || '' }} - run: | - VERSION="${{ inputs.release_version }}" - EFFECTIVE_TAG="${{ needs.validate.outputs.effective_tag }}" - DRY_RUN="${{ inputs.dry_run }}" - - # Find the exact version tarball: microsoft-aspire-cli-.tgz (no RID suffix) - META_TARBALL=$(find npm-staging -name "microsoft-aspire-cli-$VERSION.tgz" -type f | head -1) - - if [ -z "$META_TARBALL" ]; then - echo "❌ ERROR: Expected meta package tarball not found: microsoft-aspire-cli-$VERSION.tgz" - exit 1 - fi - - echo "Publishing: $(basename "$META_TARBALL")" - echo "Tag: $EFFECTIVE_TAG" - echo "Dry run: $DRY_RUN" - - if [ "$DRY_RUN" == "true" ]; then - # Dry run: validate package structure without publishing - npm publish "$META_TARBALL" --dry-run --access public --tag "$EFFECTIVE_TAG" - echo "✓ Dry run successful for meta package" - else - # Real publish with provenance - npm publish "$META_TARBALL" --provenance --access public --tag "$EFFECTIVE_TAG" - echo "✓ Published @microsoft/aspire-cli@$VERSION with tag $EFFECTIVE_TAG" - fi - - summary: - name: Publish Summary - runs-on: ubuntu-latest - needs: [validate, authorize, download, publish-rid-packages, wait-for-packages, publish-meta-package] - if: ${{ always() }} - steps: - - name: Generate summary - run: | - cat >> $GITHUB_STEP_SUMMARY << 'EOF' - # npm Publish Workflow Summary - - ## Configuration - - **Version**: ${{ inputs.release_version }} - - **Effective Tag**: ${{ needs.validate.outputs.effective_tag }} - - **Run ID**: ${{ inputs.run_id }} - - **Selected RIDs**: ${{ needs.validate.outputs.selected_rids }} - - **Skip Meta**: ${{ inputs.skip_meta }} - - **Dry Run**: ${{ inputs.dry_run }} - - **Propagation Timeout**: ${{ inputs.propagation_timeout_seconds }} seconds - - ## Job Status - - **Authorization**: ${{ needs.authorize.result }} - - **Validation**: ${{ needs.validate.result }} - - **Download**: ${{ needs.download.result }} - - **RID Package Publish**: ${{ needs.publish-rid-packages.result }} - - **Wait for Packages**: ${{ needs.wait-for-packages.result }} - - **Meta Package Publish**: ${{ needs.publish-meta-package.result }} - - ## Next Steps - EOF - - if [ "${{ inputs.dry_run }}" == "true" ]; then - cat >> $GITHUB_STEP_SUMMARY << 'EOF' - - ✓ Dry run completed successfully. To publish for real: - 1. Re-run this workflow with `dry_run: false` - 2. Ensure npm Trusted Publisher is configured for provenance - EOF - elif [ "${{ needs.publish-meta-package.result }}" == "success" ]; then - cat >> $GITHUB_STEP_SUMMARY << 'EOF' - - ✓ Publish completed successfully! - - Verify packages on npm: - - Meta package: https://www.npmjs.com/package/@microsoft/aspire-cli - - RID packages: https://www.npmjs.com/search?q=%40microsoft%2Faspire-cli- - EOF - else - cat >> $GITHUB_STEP_SUMMARY << 'EOF' - - ⚠️ Workflow completed with errors. Check job logs for details. - EOF - fi diff --git a/docs/release-process.md b/docs/release-process.md index 56aed02a150..424e781346d 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -4,245 +4,232 @@ This document describes the release process for microsoft/aspire, including both ## Overview -The Aspire release process involves two main automation components: - -1. **Azure DevOps Pipeline** (`eng/pipelines/release-publish-nuget.yml`) - - Publishes NuGet packages to NuGet.org - - Promotes the build to the GA channel via darc - -2. **GitHub Actions Workflow** (`.github/workflows/release-github-tasks.yml`) - - Creates Git tags - - Creates GitHub Releases - - Creates merge-back PRs - - Creates baseline version update PRs +The Aspire release process uses two main automation components: + +1. **Azure DevOps release pipeline** (`eng/pipelines/release-publish-nuget.yml`) + - Downloads signed artifacts from a selected official source build. + - Re-publishes NuGet, npm, WinGet, and Homebrew release inputs so 1ES can generate release SBOMs. + - Publishes NuGet packages to NuGet.org. + - Publishes Aspire CLI npm packages through ESRP/MicroBuild. + - Promotes the build to the GA channel via darc. + - Submits WinGet manifests and Homebrew cask PRs. +2. **GitHub Actions workflow** (`.github/workflows/release-github-tasks.yml`) + - Creates Git tags. + - Creates GitHub Releases. + - Creates merge-back PRs. + - Creates baseline version update PRs. ## Prerequisites Before starting a release: -1. **Signed Build**: Have a successful signed build from the official `dotnet-aspire` pipeline - - The build will be selected from a dropdown when running the release pipeline - - The build should have a `BAR ID - NNNNNN` tag (auto-extracted by the pipeline) - -2. **Release Branch**: Ensure the release branch exists (e.g., `release/9.2`) - -3. **Permissions**: - - Access to run Azure DevOps pipelines with the publishing pool - - GitHub write access for creating tags/releases/PRs - -## Step-by-Step Release Process - -### Step 1: Publish NuGet Packages (Azure DevOps) - -1. Navigate to the Azure DevOps pipeline: `release-publish-nuget` -2. Click "Run pipeline" -3. Under **Resources**, select the source build from the `aspire-build` dropdown - - This shows recent builds from the `dotnet-aspire` pipeline - - Select the specific signed build you want to release +1. **Signed build**: Have a successful signed build from the official `dotnet-aspire` pipeline. + - Select this build from the `aspire-build` resource dropdown when running the release pipeline. + - The build should have a `BAR ID - NNNNNN` tag, which the pipeline extracts automatically. + - The build must include native CLI NuGet packages and `microsoft-aspire-cli*.tgz` npm tarballs from the native archive jobs. +2. **Release branch**: Ensure the release branch exists, for example `release/9.2`. +3. **Permissions and approvals**: + - Access to run Azure DevOps pipelines with the publishing pool. + - Permission to use the NuGet.org service connection. + - Approval to use the DevDiv ESRP service connection for MicroBuild npm publishing. + - Valid ESRP owner and approver aliases for npm publishing. + - GitHub write access for creating tags, releases, and PRs. + +## Step-by-step release process + +### Step 1: Publish packages and promote the build (Azure DevOps) + +1. Navigate to the Azure DevOps pipeline: `release-publish-nuget`. +2. Click **Run pipeline**. +3. Under **Resources**, select the source build from the `aspire-build` dropdown. 4. Fill in the parameters: | Parameter | Description | Example | |-----------|-------------|---------| | `GaChannelName` | Target GA channel | `Aspire 9.x GA` | - | `DryRun` | Set `true` to test without publishing | `false` | - | `SkipNuGetPublish` | Set `true` if re-running after NuGet success | `false` | - | `SkipChannelPromotion` | Set `true` if re-running after darc success | `false` | - -5. Click "Run" and monitor the pipeline -6. Verify packages appear on NuGet.org - -### Step 2: GitHub Tasks (GitHub Actions) - -1. Navigate to Actions → "Release GitHub Tasks" -2. Click "Run workflow" + | `DryRun` | Set `true` to validate without publishing | `false` | + | `SkipNuGetPublish` | Set `true` if NuGet publishing already completed | `false` | + | `SkipNpmPublish` | Set `true` if npm publishing already completed | `false` | + | `SkipNpmRidPublish` | Set `true` if npm RID packages completed but the pointer package did not | `false` | + | `SkipChannelPromotion` | Set `true` if darc channel promotion already completed | `false` | + | `SkipWinGetPublish` | Set `true` if WinGet publishing already completed | `false` | + | `SkipHomebrewPublish` | Set `true` if Homebrew publishing already completed | `false` | + | `NpmPublishOwners` | Comma-separated ESRP owner aliases or emails | `alias@microsoft.com` | + | `NpmPublishApprovers` | Comma-separated ESRP approver aliases or emails | `approver@microsoft.com` | + | `NpmRegistryPropagationDelayMinutes` | Delay between npm RID package and pointer package submissions | `10` | + +5. Click **Run** and monitor the pipeline. +6. Verify packages appear on NuGet.org and npm. + +The npm release path publishes the seven RID packages first, waits for ESRP completion, waits for the configured propagation delay, and then publishes the top-level `@microsoft/aspire-cli` pointer package. This avoids installing a pointer package whose optional RID dependencies are not visible yet. + +### Step 2: GitHub tasks (GitHub Actions) + +1. Navigate to Actions -> **Release GitHub Tasks**. +2. Click **Run workflow**. 3. Fill in the parameters: | Parameter | Description | Example | |-----------|-------------|---------| | `release_version` | The version being released | `13.2.0` | - | `commit_sha` | Full 40-char commit SHA from the build | `abc123...` | + | `commit_sha` | Full 40-character commit SHA from the build | `abc123...` | | `release_branch` | Release branch name | `release/9.2` | | `is_prerelease` | `true` for preview releases | `false` | | `dry_run` | `true` to validate without making changes | `false` | - | `skip_tagging` | Skip if tag already created | `false` | + | `skip_tagging` | Skip if tag already exists | `false` | | `skip_github_release` | Skip if release already exists | `false` | - | `skip_merge_pr` | Skip if PR already created | `false` | - | `skip_baseline_pr` | Skip if PR already created | `false` | + | `skip_merge_pr` | Skip if PR already exists | `false` | + | `skip_baseline_pr` | Skip if PR already exists | `false` | -4. Click "Run workflow" and monitor progress +4. Click **Run workflow** and monitor progress. -> **Tip**: Use `dry_run: true` to test the workflow without creating any tags, releases, or PRs. This is useful for validating inputs and checking what actions would be taken. +Use `dry_run: true` to test the workflow without creating tags, releases, or PRs. -### Step 3: Post-Release Tasks (Manual) +### Step 3: Post-release tasks (manual) After automation completes: -1. **Review and merge PRs**: - - Merge-back PR: `$RELEASE_BRANCH` → `main` - - Baseline version PR: Updates `PackageValidationBaselineVersion` - -2. **Verify the release**: - - Check the [GitHub Releases page](https://github.com/microsoft/aspire/releases) - - Verify packages on [NuGet.org](https://www.nuget.org/packages?q=owner%3Adotnet+aspire) - - Test installation: `dotnet new install Aspire.ProjectTemplates::VERSION` - -3. **Communicate**: - - Update any tracking issues - - Notify stakeholders +1. Review and merge PRs: + - Merge-back PR: `$RELEASE_BRANCH` -> `main` + - Baseline version PR: updates `PackageValidationBaselineVersion` +2. Verify the release: + - Check the [GitHub Releases page](https://github.com/microsoft/aspire/releases). + - Verify packages on [NuGet.org](https://www.nuget.org/packages?q=owner%3Adotnet+aspire). + - Verify npm packages on the Microsoft npm profile. + - Test installation: `dotnet new install Aspire.ProjectTemplates::VERSION`. +3. Communicate: + - Update any tracking issues. + - Notify stakeholders. -## Handling Failures +## Handling failures -Both automations are designed to be **idempotent** and safe to re-run. +Both automations are designed to be idempotent and safe to re-run. -### Azure DevOps Pipeline Failures +### Azure DevOps pipeline failures -The pipeline runs as a single stage with all steps in sequence. If a step fails: - -| Step Failed | Resolution | +| Step failed | Resolution | |-------------|------------| -| Validate Parameters | Fix the input parameters and re-run | -| Extract BAR Build ID | Check that the build has a `BAR ID - NNNNNN` tag | -| List/Verify Packages | Check that the build artifacts are available | -| Push Packages to NuGet.org | Check NuGet.org for partial success; the `1ES.PublishNuget@1` task handles duplicates via `allowPackageConflicts: true` | -| Promote Build to Channel | Re-run with `SkipNuGetPublish: true` | - -### GitHub Actions Failures - -| Job Failed | Resolution | +| Validate Parameters | Fix the input parameters and re-run. | +| Extract BAR Build ID | Check that the build has a `BAR ID - NNNNNN` tag. | +| Prepare/List/Verify NuGet Packages | Check that the selected source build produced `PackageArtifacts`. | +| Prepare/List npm Packages | Check that the selected source build produced all eight `microsoft-aspire-cli*.tgz` tarballs in `BlobArtifacts`. | +| Push Packages to NuGet.org | Check NuGet.org for partial success, then re-run with already-completed steps skipped as needed. | +| MicroBuild npm Publish | Check the ESRP release result. If RID packages published but the pointer package did not, re-run with `SkipNuGetPublish: true`, `SkipNpmRidPublish: true`, and `SkipChannelPromotion: true`; do not set `SkipNpmPublish` until the pointer package is published. | +| Promote Build to Channel | Re-run with `SkipNuGetPublish: true` and `SkipNpmPublish: true`. | +| WinGet/Homebrew publishing | Re-run with the corresponding skip flags for completed work. | + +### GitHub Actions failures + +| Job failed | Resolution | |------------|------------| -| validate | Fix the input parameters and re-run | -| create-tag | If tag exists with wrong SHA, requires manual resolution | -| create-release | Re-run with `skip_tagging: true` | -| create-merge-pr | Re-run with `skip_tagging: true`, `skip_github_release: true` | -| create-baseline-pr | Re-run with all prior skips set to `true` | +| validate | Fix the input parameters and re-run. | +| create-tag | If the tag exists with the wrong SHA, resolve it manually. | +| create-release | Re-run with `skip_tagging: true`. | +| create-merge-pr | Re-run with `skip_tagging: true` and `skip_github_release: true`. | +| create-baseline-pr | Re-run with all prior skips set to `true`. | ## Configuration -### 1ES Pipeline Compliance +### 1ES and MicroBuild compliance -The AzDO pipeline extends the 1ES Official Pipeline Templates (`v1/1ES.Official.PipelineTemplate.yml@1ESPipelineTemplates`) to be compliant with Microsoft organization requirements. This provides: -- SDL (Security Development Lifecycle) compliance scanning -- Proper pool configuration for internal pipelines -- Component governance integration -- **Secure NuGet publishing** via the `1ES.PublishNuget@1` task with managed service connections +The Azure DevOps pipeline extends `azure-pipelines/1ES.Official.Publish.yml@MicroBuildTemplate`. This keeps the pipeline on the official 1ES publishing template while allowing the `MicroBuild.Publish.yml@MicroBuildTemplate` step to submit npm packages through ESRP. -> **Note**: This pipeline does not use the MicroBuild template since we're not signing packages - packages are already signed during the main build pipeline. We only download and publish pre-signed artifacts. +The source build creates, signs where platform signing applies, verifies, and stages the package artifacts. The release pipeline consumes those pre-built artifacts; it does not rebuild or re-pack the CLI. -### Variable Groups (Azure DevOps) +### Variable groups -The pipeline uses the `Aspire-Release-Secrets` variable group. Note that NuGet publishing credentials are managed via a service connection, not a variable group secret. +The pipeline uses: -### Service Connections (Azure DevOps) +| Variable group | Purpose | +|----------------|---------| +| `Aspire-Release-Secrets` | Release pipeline secrets. NuGet publishing uses a service connection rather than a variable-group API key. | +| `Aspire-Secrets` | WinGet and Homebrew bot tokens. | -| Connection Name | Purpose | +### Service connections + +| Connection name | Purpose | |-----------------|---------| -| `NuGet.org - microsoft/aspire` | NuGet service connection for publishing packages to NuGet.org | -| `Darc: Maestro Production` | Used for darc channel promotion | +| `NuGet.org - dotnet/aspire` | NuGet service connection for publishing packages to NuGet.org. | +| `DevDivEsrpAzDoSrvConn` | ESRP service connection used by the MicroBuild publish template for npm publishing. | +| `Darc: Maestro Production` | Used for darc channel promotion. | -> **Note**: The `NuGet.org - microsoft/aspire` service connection must be configured in Azure DevOps Project Settings → Service connections with: -> - **Type**: NuGet -> - **Authentication**: ApiKey -> - **Feed URL**: `https://api.nuget.org/v3/index.json` -> - **ApiKey**: A scoped NuGet.org API key with push permissions for Aspire packages +The release definition must be approved for the MicroBuild publishing template and must have permission to use `DevDivEsrpAzDoSrvConn`. -### Approved GitHub Actions +## Troubleshooting -The workflow uses only pre-approved actions: +### Could not find BAR ID tag -- `actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683` (v4) -- `./.github/actions/create-pull-request` (local composite action) +The pipeline expects the build to have a tag in format `BAR ID - NNNNNN`. This is normally added automatically by the Maestro publishing process. If missing: -## Troubleshooting +1. Check if the build completed its post-build steps. +2. Manually look up the BAR ID in Maestro and add the tag. +3. Contact the engineering team if the issue persists. -### "Could not find BAR ID tag" +### npm tarballs are missing from release artifacts -The pipeline expects the build to have a tag in format `BAR ID - NNNNNN`. This is normally added automatically by the Maestro publishing process. If missing: +The official source build should fail staging if npm tarballs are missing. If the release pipeline cannot find them: -1. Check if the build completed its post-build steps -2. Manually look up the BAR ID in Maestro and add the tag -3. Contact the engineering team if the issue persists +1. Confirm the selected source build is from a branch that includes npm packaging. +2. Check the native archive jobs for `verify-cli-npm-package.ps1` failures. +3. Check `BlobArtifacts` for the eight `microsoft-aspire-cli*.tgz` files. -### "Tag already exists but points to different commit" +### npm publish fails after RID packages published -This indicates a mismatch between the expected release commit and an existing tag. Resolution: +If ESRP published the RID packages but failed before publishing `@microsoft/aspire-cli`: -1. Verify you're using the correct commit SHA -2. If the existing tag is wrong, it must be manually deleted (requires admin) -3. If the SHA is wrong, correct it and re-run +1. Verify the RID packages are visible on npm. +2. Re-run the release pipeline with completed non-npm steps skipped. +3. Set `SkipNpmRidPublish: true` and keep `SkipNpmPublish: false` so only the pointer package is submitted. +4. Set `SkipNpmPublish: true` only after the pointer package is visible. -### NuGet publish failures +### Tag already exists but points to different commit -The `1ES.PublishNuget@1` task is configured with `allowPackageConflicts: true`, which means it will skip packages that already exist on NuGet.org. If publishing fails: +This indicates a mismatch between the expected release commit and an existing tag. Resolution: -1. Check the pipeline logs for specific error messages -2. Verify the service connection `NuGet.org - microsoft/aspire` is properly configured -3. Ensure the API key in the service connection has push permissions for the package IDs -4. Re-run the pipeline (it will skip already-published packages) +1. Verify you're using the correct commit SHA. +2. If the existing tag is wrong, it must be manually deleted by someone with the required permission. +3. If the SHA is wrong, correct it and re-run. -### PR creation fails +### NuGet publish failures -The workflow checks for existing PRs before creating. If a PR exists with a different title: +If NuGet publishing fails: -1. Close or merge the existing PR -2. Re-run the workflow +1. Check the pipeline logs for specific error messages. +2. Verify the service connection `NuGet.org - dotnet/aspire` is properly configured. +3. Ensure the service connection has push permissions for the package IDs. +4. Re-run the pipeline with skip flags for work that already completed. -## Architecture Diagram +## Architecture diagram ```text -┌─────────────────────────────────────────────────────────────────────────┐ -│ RELEASE PROCESS FLOW │ -├─────────────────────────────────────────────────────────────────────────┤ -│ │ -│ ┌──────────────────────────────────────────────────────────────────┐ │ -│ │ Azure DevOps Pipeline │ │ -│ │ release-publish-nuget.yml │ │ -│ │ (1ES.Official.PipelineTemplate.yml) │ │ -│ │ │ │ -│ │ Resource: aspire-build (select from dropdown) │ │ -│ │ Input: GaChannelName │ │ -│ │ │ │ -│ │ ┌─────────────┐ ┌──────────────┐ ┌──────────────────────┐ │ │ -│ │ │ Validate │──▶│ Extract BAR │──▶│ Download & Verify │ │ │ -│ │ │ Inputs │ │ Build ID │ │ Packages │ │ │ -│ │ └─────────────┘ └──────────────┘ └──────────────────────┘ │ │ -│ │ │ │ │ -│ │ ▼ │ │ -│ │ ┌──────────────────────┐ │ │ -│ │ │ 1ES.PublishNuget@1 │ │ │ -│ │ │ (via svc connection)│ │ │ -│ │ └──────────────────────┘ │ │ -│ │ │ │ │ -│ │ ▼ │ │ -│ │ ┌──────────────────────┐ │ │ -│ │ │ Promote to Channel │ │ │ -│ │ │ (via darc) │ │ │ -│ │ └──────────────────────┘ │ │ -│ └──────────────────────────────────────────────────────────────────┘ │ -│ │ │ -│ ▼ │ -│ ┌──────────────────────────────────────────────────────────────────┐ │ -│ │ GitHub Actions Workflow │ │ -│ │ .github/workflows/release-github-tasks.yml │ │ -│ │ │ │ -│ │ Input: release_version, commit_sha, release_branch │ │ -│ │ │ │ -│ │ ┌─────────────┐ ┌──────────────┐ ┌──────────────────────┐ │ │ -│ │ │ Validate │──▶│ Create Tag │──▶│ Create GitHub │ │ │ -│ │ │ Inputs │ │ v{version} │ │ Release │ │ │ -│ │ └─────────────┘ └──────────────┘ └──────────────────────┘ │ │ -│ │ │ │ │ -│ │ ┌─────────────────────────┼─────────┐ │ │ -│ │ ▼ ▼ │ │ │ -│ │ ┌───────────────────────┐ ┌────────────────────┐ │ │ -│ │ │ Create Merge PR │ │ Create Baseline PR │ │ │ -│ │ │ release/X.Y → main │ │ Update version │ │ │ -│ │ └───────────────────────┘ └────────────────────┘ │ │ -│ └──────────────────────────────────────────────────────────────────┘ │ -│ │ -└─────────────────────────────────────────────────────────────────────────┘ +Official source build + -> Native archive jobs + -> signed native archives / native CLI packages + -> npm tarballs verified against the native archive + -> PackageArtifacts: NuGet packages + -> BlobArtifacts: microsoft-aspire-cli*.tgz + +Azure DevOps release-publish-nuget.yml + -> PrepareArtifacts + -> republish NuGet artifacts with SBOM + -> split npm RID and pointer artifacts with SBOM + -> ReleaseJob + -> verify NuGet signatures + -> publish NuGet through 1ES.PublishNuget@1 + -> publish npm RID packages through MicroBuild.Publish + -> wait for npm propagation + -> publish npm pointer package through MicroBuild.Publish + -> promote BAR build to GA channel + -> WinGetJob / HomebrewJob + +GitHub release-github-tasks.yml + -> create tag + -> create GitHub release + -> create merge-back PR + -> create baseline version PR ``` -## Related Documentation +## Related documentation - [Contributing Guide](contributing.md) - [Quarantined Tests](quarantined-tests.md) diff --git a/docs/specs/npm-cli-package.md b/docs/specs/npm-cli-package.md index e84819cbeec..9d314f3066c 100644 --- a/docs/specs/npm-cli-package.md +++ b/docs/specs/npm-cli-package.md @@ -4,7 +4,7 @@ The Aspire CLI npm package POC distributes the native Aspire CLI through npm using the same native binary archives that feed the dotnet tool packages. The npm package shape follows the native-package convention used by tools such as esbuild and @vscode/ripgrep: a small top-level package exposes the command, while platform-specific packages carry the native payload. -The POC package name is `@microsoft/aspire-cli`. It is intentionally a POC and does not yet include npm publishing, provenance, registry authentication, or CLI-side npm self-update behavior. +The POC package name is `@microsoft/aspire-cli`. It is intentionally a POC and does not yet include CLI-side npm self-update behavior. ## Research and prior art @@ -25,6 +25,7 @@ The Aspire-specific adaptation is the writable cache. Unlike most native npm CLI - Use a top-level npm package with a JavaScript `bin` launcher and RID-specific optional native packages. - Avoid running the self-extracting native binary directly from `node_modules` or package-manager stores. - Verify generated npm packages against the native archive before staging them. +- Publish through the Azure DevOps release pipeline using Microsoft's ESRP-backed MicroBuild publishing flow. ## Non-goals @@ -152,7 +153,7 @@ ASPIRE_NPM_PACKAGE_RID 5. Comparing the RID tarball binary byte-for-byte with the archive binary. 6. Verifying pointer package metadata, `bin/aspire.js`, `aspire-package-map.json`, and optional dependency version alignment. -`eng\scripts\stage-native-cli-tool-packages.ps1` stages npm `.tgz` artifacts alongside existing native CLI nupkgs. Npm packages are additive: if no npm packages are present, staging warns and continues so older nupkg-only flows remain valid. +`eng\scripts\stage-native-cli-tool-packages.ps1` stages npm `.tgz` artifacts alongside existing native CLI nupkgs. Official CI invokes the script with `-RequireNpmPackages`, so source builds fail before release if the npm tarballs are missing. The default remains warning-only for local or older nupkg-only flows that call the script directly. Only one pointer package is staged. The default canonical pointer source is `native_archives_win_x64`, matching the existing native CLI package staging convention. All RID-specific packages are staged. @@ -160,46 +161,30 @@ Only one pointer package is staged. The default canonical pointer source is `nat The native archive workflows verify npm tarballs after the existing nupkg verification. -GitHub Actions uploads `microsoft-aspire-cli*.tgz` with the RID-specific package artifacts. Azure Pipelines installs Node.js before native package build because `npm pack` runs during packaging, verifies the npm packages, downloads `microsoft-aspire-cli*.tgz` in the staging job, and stages them with the native CLI packages. +Azure Pipelines installs Node.js before native package build because `npm pack` runs during packaging, verifies the npm packages, downloads `microsoft-aspire-cli*.tgz` in the staging job, and stages them with the native CLI packages. The source build then publishes the npm `.tgz` files as shipping flat blob artifacts so the release pipeline can consume them without treating npm tarballs as NuGet-like BAR package assets. ## Publishing -The npm packages are published using the manual GitHub Actions workflow `.github/workflows/publish-npm.yml`. +The npm packages are published from `eng/pipelines/release-publish-nuget.yml`, not from GitHub Actions. The release pipeline extends the MicroBuild publish-enabled 1ES template and submits packages through `MicroBuild.Publish.yml@MicroBuildTemplate` with `intent: PackageDistribution`, `contentType: npm`, and `contentSource: Folder`. -### Prerequisites +The release pipeline prepares two npm artifact folders: -Before publishing npm packages, the following external setup must be complete: +1. `NpmRidPackageArtifacts` contains the seven RID packages. +2. `NpmPointerPackageArtifacts` contains the top-level `@microsoft/aspire-cli` pointer package. -1. **@microsoft scope reservation**: The `@microsoft` scope must be reserved and managed by Microsoft on the npm registry. -2. **npm Trusted Publisher configuration**: The microsoft/aspire repository must be configured as a Trusted Publisher on npm to enable provenance via OIDC. This eliminates the need for long-lived NPM_TOKEN secrets. -3. **Microsoft/1ES-managed publishing**: npm publishing should be managed through Microsoft's 1ES-approved processes and infrastructure. +The split is intentional. The release job submits RID packages first, waits for the ESRP submission to complete, waits an additional npm registry propagation delay, and then submits the pointer package. Publishing the pointer package last avoids optional dependency resolution races when a user installs the top-level package immediately after release. -The workflow includes a temporary fallback to `secrets.NPM_TOKEN` authentication, but Trusted Publisher OIDC is the recommended approach. The fallback will be removed once Trusted Publisher setup is complete. +Before publishing, the release pipeline validates that exactly one pointer tarball and exactly one tarball for each supported RID are present, and that all tarballs have one version. Non-dry-run npm publishing requires release managers to provide `NpmPublishOwners` and `NpmPublishApprovers`, which are passed to ESRP. Re-runs can use `SkipNpmRidPublish` if the RID packages published but the pointer package did not, and `SkipNpmPublish` after npm publishing has completed. -### Publishing workflow +MicroBuild's npm publish template documentation does not currently expose an npm `dist-tag` parameter. Initial publishing therefore relies on the registry's default tag behavior; preview or side-channel tagging needs ESRP/MicroBuild support before it can be enabled safely. -The publish workflow downloads staged npm tarballs from a completed native archive build and publishes them to npm with provenance: +## Product and security tradeoffs -```bash -# Example: Publish packages from a build run -gh workflow run publish-npm.yml \ - --ref main \ - --field release_version="9.2.0" \ - --field run_id="12345678" \ - --field dist_tag="latest" \ - --field dry_run="false" -``` - -Key features: - -- **Dry run by default**: The workflow defaults to `dry_run: true` to validate packages before real publish. -- **Platform-first ordering**: RID-specific packages are published before the meta package to avoid `optionalDependencies` validation races. -- **Propagation wait**: The workflow polls npm until all RID packages for the target version are visible before publishing the meta package. -- **Recovery options**: The `only_rid` and `skip_meta` inputs support publishing specific RID packages or skipping the meta package if recovery is needed. -- **Provenance**: All publishes use `npm publish --provenance` when not in dry-run mode. -- **Authorization**: Non-dry-run publishes require admin or maintain repository permissions. - -For full workflow documentation, see the workflow file header and inline comments. +- **No GitHub npm publishing token**: Publishing is centralized through ESRP/MicroBuild and the Microsoft npm maintainer identity instead of storing an npm token in GitHub or using a repository-local GitHub Actions publisher. +- **Signed payload, unsigned tarball container**: The npm tarball is created from the native CLI archive produced by the signed CI flow, and verification compares the RID tarball binary byte-for-byte with that archive. The `.tgz` container itself is not separately signed; integrity comes from CI verification, SBOM-covered release artifacts, ESRP submission, and npm registry package integrity. +- **Writable cache**: Copying the native binary to `~/.aspire/npm///bin` avoids self-extraction into package-manager stores, but it means the launcher owns cache creation and freshness checks. +- **Update behavior**: npm updates are package-manager driven (`npm update`, reinstalling the global package, or changing the requested version). `aspire update --self` remains out of scope for npm installs until the CLI has explicit npm install detection and guidance. +- **Linux libc split**: Separate glibc and musl packages avoid shipping one Linux binary that is wrong for Alpine-style environments, at the cost of one additional optional dependency package. ## Open follow-ups diff --git a/eng/Publishing.props b/eng/Publishing.props index 9b46fc8f629..5e22b4720f3 100644 --- a/eng/Publishing.props +++ b/eng/Publishing.props @@ -40,6 +40,7 @@ <_ExtensionSignatureFiles Include="$(ArtifactsPackagesDir)**\aspire-vscode-*.signature.p7s" /> <_CliToolPackagesToPublish Include="$(ArtifactsShippingPackagesDir)**\Aspire.Cli*.nupkg" Exclude="$(ArtifactsShippingPackagesDir)**\*.symbols.nupkg" /> + <_CliNpmPackagesToPublish Include="$(ArtifactsShippingPackagesDir)**\microsoft-aspire-cli*.tgz" /> + <_CliRidSpecificNpmPackageFilesWithRid Include="@(_CliRidSpecificNpmPackageFiles)"> + $([System.Text.RegularExpressions.Regex]::Match('%(_CliRidSpecificNpmPackageFiles.FileName)', '^microsoft-aspire-cli-(.*?)-\d+.*').Groups[1].Value) + + + <_MissingCliNpmPackageRids Include="@(_ExpectedCliRids)" Exclude="@(_CliRidSpecificNpmPackageFilesWithRid -> '%(ExtractedRid)')" /> + <_UnexpectedCliNpmPackageRids Include="@(_CliRidSpecificNpmPackageFilesWithRid -> '%(ExtractedRid)')" Exclude="@(_ExpectedCliRids)" /> + <_CliPointerNpmPackages Include="@(_CliNpmPackagesToPublish)" Exclude="@(_CliRidSpecificNpmPackageFilesWithRid)" /> + + + + + @@ -177,6 +195,11 @@ true Package + + true + true + $(_UploadPathRoot)/$(_PackageVersion)/%(Filename)%(Extension) + false true @@ -211,6 +234,7 @@ + diff --git a/eng/clipack/Common.projitems b/eng/clipack/Common.projitems index 1b5e72f504e..37bfa63fa44 100644 --- a/eng/clipack/Common.projitems +++ b/eng/clipack/Common.projitems @@ -243,7 +243,14 @@ - + + + <_PackCliNpmPackageScript>$([MSBuild]::NormalizePath($(RepoRoot), 'eng', 'scripts', 'pack-cli-npm-package.ps1')) + + + diff --git a/eng/pipelines/azure-pipelines-unofficial.yml b/eng/pipelines/azure-pipelines-unofficial.yml index 23fa469a8f8..3ea569cbbd2 100644 --- a/eng/pipelines/azure-pipelines-unofficial.yml +++ b/eng/pipelines/azure-pipelines-unofficial.yml @@ -184,7 +184,8 @@ extends: $ErrorActionPreference = 'Stop' & "$(Build.SourcesDirectory)/eng/scripts/stage-native-cli-tool-packages.ps1" ` -DownloadRoot "$(Build.SourcesDirectory)/artifacts/native-cli-packages/$(_BuildConfig)" ` - -ShippingDir "$(Build.SourcesDirectory)/artifacts/packages/$(_BuildConfig)/Shipping" + -ShippingDir "$(Build.SourcesDirectory)/artifacts/packages/$(_BuildConfig)/Shipping" ` + -RequireNpmPackages displayName: 🟣Stage Native CLI Packages - task: PowerShell@2 diff --git a/eng/pipelines/azure-pipelines.yml b/eng/pipelines/azure-pipelines.yml index 9e21278b44e..cec04e5435c 100644 --- a/eng/pipelines/azure-pipelines.yml +++ b/eng/pipelines/azure-pipelines.yml @@ -272,7 +272,8 @@ extends: $ErrorActionPreference = 'Stop' & "$(Build.SourcesDirectory)/eng/scripts/stage-native-cli-tool-packages.ps1" ` -DownloadRoot "$(Build.SourcesDirectory)/artifacts/native-cli-packages/$(_BuildConfig)" ` - -ShippingDir "$(Build.SourcesDirectory)/artifacts/packages/$(_BuildConfig)/Shipping" + -ShippingDir "$(Build.SourcesDirectory)/artifacts/packages/$(_BuildConfig)/Shipping" ` + -RequireNpmPackages displayName: 🟣Stage Native CLI Packages - task: PowerShell@2 diff --git a/eng/pipelines/release-publish-nuget.yml b/eng/pipelines/release-publish-nuget.yml index 9b0a8b3860b..df776c80d5f 100644 --- a/eng/pipelines/release-publish-nuget.yml +++ b/eng/pipelines/release-publish-nuget.yml @@ -1,8 +1,8 @@ -# Release Pipeline: Publish NuGet Packages and Promote to GA Channel +# Release Pipeline: Publish NuGet/npm Packages and Promote to GA Channel # # This pipeline automates the release process for microsoft/aspire: # 1. Downloads signed packages from a specified build -# 2. Publishes packages to NuGet.org +# 2. Publishes packages to NuGet.org and npm # 3. Promotes the build to the Aspire GA channel via darc # 4. Submits WinGet manifests and Homebrew cask PRs # @@ -28,6 +28,16 @@ parameters: type: boolean default: false + - name: SkipNpmPublish + displayName: 'Skip npm Publishing (set true if already completed)' + type: boolean + default: false + + - name: SkipNpmRidPublish + displayName: 'Skip npm RID Package Publishing (set true if RID packages already completed but pointer package did not)' + type: boolean + default: false + - name: SkipChannelPromotion displayName: 'Skip Channel Promotion (set true if already completed)' type: boolean @@ -43,6 +53,21 @@ parameters: type: boolean default: false + - name: NpmPublishOwners + displayName: 'npm ESRP owners (comma-separated Microsoft aliases or emails)' + type: string + default: '' + + - name: NpmPublishApprovers + displayName: 'npm ESRP approvers (comma-separated Microsoft aliases or emails)' + type: string + default: '' + + - name: NpmRegistryPropagationDelayMinutes + displayName: 'Minutes to wait between npm RID and pointer package submissions' + type: number + default: 10 + variables: - template: /eng/pipelines/common-variables.yml@self - template: /eng/common/templates-official/variables/pool-providers.yml@self @@ -54,9 +79,9 @@ variables: resources: repositories: - - repository: 1ESPipelineTemplates + - repository: MicroBuildTemplate type: git - name: 1ESPipelineTemplates/1ESPipelineTemplates + name: 1ESPipelineTemplates/MicroBuildTemplate ref: refs/tags/release pipelines: - pipeline: aspire-build @@ -65,7 +90,7 @@ resources: trigger: none # Manual trigger only - no automatic releases extends: - template: v1/1ES.Official.PipelineTemplate.yml@1ESPipelineTemplates + template: azure-pipelines/1ES.Official.Publish.yml@MicroBuildTemplate parameters: pool: name: NetCore1ESPool-Internal @@ -105,6 +130,14 @@ extends: displayName: 'Publish PackageArtifacts with SBOM' targetPath: '$(Pipeline.Workspace)/packages/PackageArtifacts' artifactName: 'PackageArtifacts' + - output: pipelineArtifact + displayName: 'Publish npm RID Package Artifacts with SBOM' + targetPath: '$(Pipeline.Workspace)/npm/rid-packages' + artifactName: 'NpmRidPackageArtifacts' + - output: pipelineArtifact + displayName: 'Publish npm Pointer Package Artifact with SBOM' + targetPath: '$(Pipeline.Workspace)/npm/pointer-package' + artifactName: 'NpmPointerPackageArtifacts' - output: pipelineArtifact displayName: 'Publish WinGet Manifests' targetPath: '$(Pipeline.Workspace)/installers/winget-manifests-stable' @@ -121,7 +154,7 @@ extends: Write-Host "Source Build ID: $(resources.pipeline.aspire-build.runID)" Write-Host "Source Build Name: $(resources.pipeline.aspire-build.runName)" Write-Host "This stage downloads artifacts and re-publishes them so 1ES PT can generate SBOM." - Write-Host "Installer-only mode: ${{ and(eq(parameters.SkipNuGetPublish, true), eq(parameters.SkipChannelPromotion, true)) }}" + Write-Host "Installer-only mode: ${{ and(eq(parameters.SkipNuGetPublish, true), eq(parameters.SkipNpmPublish, true), eq(parameters.SkipChannelPromotion, true)) }}" Write-Host "===============================" displayName: 'Log Stage Info' @@ -132,6 +165,12 @@ extends: artifact: PackageArtifacts patterns: '**/*.nupkg' + - ${{ if eq(parameters.SkipNpmPublish, false) }}: + - download: aspire-build + displayName: 'Download npm packages from Source Build' + artifact: BlobArtifacts + patterns: '**/microsoft-aspire-cli*.tgz' + - download: aspire-build displayName: 'Download WinGet Manifests from Source Build' artifact: winget-manifests-stable @@ -175,6 +214,113 @@ extends: Write-Host "Installer-only run detected; created empty PackageArtifacts placeholder." displayName: 'Prepare Empty PackageArtifacts Placeholder' + - ${{ if eq(parameters.SkipNpmPublish, false) }}: + - powershell: | + $sourcePath = "$(Pipeline.Workspace)/aspire-build/BlobArtifacts" + $ridTargetPath = "$(Pipeline.Workspace)/npm/rid-packages" + $pointerTargetPath = "$(Pipeline.Workspace)/npm/pointer-package" + $expectedRids = @( + 'win-x64', + 'win-arm64', + 'linux-x64', + 'linux-arm64', + 'linux-musl-x64', + 'osx-x64', + 'osx-arm64' + ) + + New-Item -ItemType Directory -Path $ridTargetPath -Force | Out-Null + New-Item -ItemType Directory -Path $pointerTargetPath -Force | Out-Null + + Write-Host "Preparing npm packages from $sourcePath" + if (!(Test-Path $sourcePath)) { + Write-Error @" + BlobArtifacts was not downloaded from the source build at '$sourcePath'. + npm CLI packages ship as flat blobs in BlobArtifacts (configured via eng/Publishing.props). + Possible causes: + 1. The source build (azure-pipelines.yml) ran before the npm CLI package work landed. + Re-run the release pipeline with SkipNpmPublish=true, or rebuild from a newer commit. + 2. The source build failed to produce or publish the BlobArtifacts pipeline artifact. + 3. The wrong source build was selected. + "@ + exit 1 + } + + $versionPattern = '\d+(?:\.\d+){1,3}(?:-[0-9A-Za-z][0-9A-Za-z.-]*)?' + $pointerPattern = "^microsoft-aspire-cli-($versionPattern)\.tgz$" + $ridPattern = "^microsoft-aspire-cli-(?.+?)-(?$versionPattern)\.tgz$" + $packages = @(Get-ChildItem -Path $sourcePath -Filter "microsoft-aspire-cli*.tgz" -Recurse -File) + $pointerPackages = @($packages | Where-Object { $_.Name -match $pointerPattern }) + $ridPackages = @($packages | Where-Object { $_.Name -match $ridPattern }) + $unexpectedPackages = @($packages | Where-Object { $_.Name -notmatch $pointerPattern -and $_.Name -notmatch $ridPattern }) + + Write-Host "Found $($packages.Count) npm package(s)." + foreach ($pkg in $packages) { + Write-Host " - $($pkg.Name)" + } + + if ($unexpectedPackages.Count -gt 0) { + Write-Error "Unexpected npm package filename(s): $($unexpectedPackages.Name -join ', ')" + exit 1 + } + + if ($pointerPackages.Count -ne 1) { + Write-Error "Expected exactly one Aspire CLI npm pointer package, but found $($pointerPackages.Count): $($pointerPackages.FullName -join ', ')" + exit 1 + } + + $ridPackageDetails = @($ridPackages | ForEach-Object { + if ($_.Name -match $ridPattern) { + [pscustomobject]@{ + File = $_ + Rid = $Matches.Rid + Version = $Matches.Version + } + } + }) + + $versions = @( + if ($pointerPackages[0].Name -match $pointerPattern) { + $Matches[1] + } + $ridPackageDetails | ForEach-Object { $_.Version } + ) | Sort-Object -Unique + + if ($versions.Count -ne 1) { + Write-Error "Expected one npm package version, but found: $($versions -join ', ')" + exit 1 + } + + $duplicateRidGroups = @($ridPackageDetails | Group-Object Rid | Where-Object { $_.Count -gt 1 }) + if ($duplicateRidGroups.Count -gt 0) { + $details = @($duplicateRidGroups | ForEach-Object { "$($_.Name): $($_.Group.File.Name -join ', ')" }) + Write-Error "Expected exactly one npm RID package per RID, but found duplicates: $($details -join '; ')" + exit 1 + } + + $actualRids = @($ridPackageDetails | ForEach-Object { $_.Rid }) + $missingRids = @($expectedRids | Where-Object { $_ -notin $actualRids }) + $unexpectedRids = @($actualRids | Where-Object { $_ -notin $expectedRids }) + if ($missingRids.Count -gt 0 -or $unexpectedRids.Count -gt 0) { + Write-Error "npm RID package set mismatch. Missing: $($missingRids -join ', '); Unexpected: $($unexpectedRids -join ', ')" + exit 1 + } + + foreach ($pkg in $ridPackages) { + Copy-Item $pkg.FullName -Destination $ridTargetPath -Force + } + Copy-Item $pointerPackages[0].FullName -Destination $pointerTargetPath -Force + + Write-Host "Prepared $($ridPackages.Count) RID npm package(s) and pointer package version $($versions[0])." + displayName: 'Prepare npm Artifacts for Publishing' + + - ${{ if eq(parameters.SkipNpmPublish, true) }}: + - powershell: | + New-Item -ItemType Directory -Path "$(Pipeline.Workspace)/npm/rid-packages" -Force | Out-Null + New-Item -ItemType Directory -Path "$(Pipeline.Workspace)/npm/pointer-package" -Force | Out-Null + Write-Host "Created empty npm artifact placeholders because SkipNpmPublish=true." + displayName: 'Prepare Empty npm Artifact Placeholders' + # Copy installer artifacts to expected locations for output - powershell: | $artifacts = @( @@ -207,14 +353,14 @@ extends: displayName: 'Prepare Installer Artifacts' # ===== STAGE 2: RELEASE ===== - # This releaseJob consumes the artifacts with SBOM and publishes to NuGet.org + # This releaseJob consumes the artifacts with SBOM and publishes to NuGet.org/npm - stage: Release - displayName: 'Release to NuGet and Promote' + displayName: 'Release to NuGet/npm and Promote' dependsOn: PrepareArtifacts jobs: - job: ReleaseJob displayName: 'Validate, Publish, and Promote' - timeoutInMinutes: 120 + timeoutInMinutes: 240 pool: name: NetCore1ESPool-Internal image: windows.vs2026preview.scout.amd64 @@ -230,6 +376,12 @@ extends: - input: pipelineArtifact artifactName: PackageArtifacts targetPath: '$(Pipeline.Workspace)/packages/PackageArtifacts' + - input: pipelineArtifact + artifactName: NpmRidPackageArtifacts + targetPath: '$(Pipeline.Workspace)/npm/rid-packages' + - input: pipelineArtifact + artifactName: NpmPointerPackageArtifacts + targetPath: '$(Pipeline.Workspace)/npm/pointer-package' steps: # ===== VALIDATION ===== # Note: No checkout - releaseJob doesn't allow it. All scripts are inlined. @@ -244,8 +396,10 @@ extends: Write-Host "GA Channel: ${{ parameters.GaChannelName }}" Write-Host "Dry Run: ${{ parameters.DryRun }}" Write-Host "Skip NuGet Publish: ${{ parameters.SkipNuGetPublish }}" + Write-Host "Skip npm Publish: ${{ parameters.SkipNpmPublish }}" + Write-Host "Skip npm RID Publish: ${{ parameters.SkipNpmRidPublish }}" Write-Host "Skip Channel Promotion: ${{ parameters.SkipChannelPromotion }}" - Write-Host "Installer-only mode: ${{ and(eq(parameters.SkipNuGetPublish, true), eq(parameters.SkipChannelPromotion, true)) }}" + Write-Host "Installer-only mode: ${{ and(eq(parameters.SkipNuGetPublish, true), eq(parameters.SkipNpmPublish, true), eq(parameters.SkipChannelPromotion, true)) }}" Write-Host "===================================" displayName: 'Validate Parameters' @@ -399,6 +553,120 @@ extends: Write-Host "=== Skipping NuGet Publishing (SkipNuGetPublish=true) ===" displayName: 'Skip NuGet Publish (flagged)' + # ===== PUBLISH TO npm ===== + - ${{ if eq(parameters.SkipNpmPublish, false) }}: + - powershell: | + $ridPackagesPath = "$(Pipeline.Workspace)/npm/rid-packages" + $pointerPackagePath = "$(Pipeline.Workspace)/npm/pointer-package" + Write-Host "=== npm Package Inventory ===" + + $ridPackages = @(Get-ChildItem -Path $ridPackagesPath -Filter "*.tgz" -File) + $pointerPackages = @(Get-ChildItem -Path $pointerPackagePath -Filter "*.tgz" -File) + + Write-Host "RID packages: $($ridPackages.Count)" + foreach ($pkg in $ridPackages) { + $sizeMB = [math]::Round($pkg.Length / 1MB, 2) + Write-Host " - $($pkg.Name) ($sizeMB MB)" + } + + Write-Host "Pointer packages: $($pointerPackages.Count)" + foreach ($pkg in $pointerPackages) { + $sizeMB = [math]::Round($pkg.Length / 1MB, 2) + Write-Host " - $($pkg.Name) ($sizeMB MB)" + } + + if ($ridPackages.Count -ne 7 -or $pointerPackages.Count -ne 1) { + Write-Error "Expected 7 npm RID packages and 1 npm pointer package." + exit 1 + } + + Write-Host "==============================" + displayName: 'List npm Packages' + + - ${{ if and(eq(parameters.DryRun, true), eq(parameters.SkipNpmPublish, false)) }}: + - powershell: | + Write-Host "=== DRY RUN MODE ===" + Write-Host "The following packages would be submitted to ESRP for npm publishing." + Write-Host "" + if ("${{ parameters.SkipNpmRidPublish }}" -eq "true") { + Write-Host "RID package submission would be skipped because SkipNpmRidPublish=true." + } else { + Write-Host "RID packages would be submitted first:" + Get-ChildItem -Path "$(Pipeline.Workspace)/npm/rid-packages" -Filter "*.tgz" -File | ForEach-Object { + Write-Host " - $($_.Name)" + } + Write-Host "" + Write-Host "Then the pipeline would wait ${{ parameters.NpmRegistryPropagationDelayMinutes }} minute(s) for registry propagation." + } + Write-Host "" + Write-Host "The pointer package would be submitted last:" + Get-ChildItem -Path "$(Pipeline.Workspace)/npm/pointer-package" -Filter "*.tgz" -File | ForEach-Object { + Write-Host " - $($_.Name)" + } + Write-Host "" + Write-Host "=== DRY RUN - No npm packages were actually published ===" + displayName: 'Dry Run - List npm Packages (No Publish)' + + - ${{ if and(eq(parameters.DryRun, false), eq(parameters.SkipNpmPublish, false)) }}: + - powershell: | + $owners = "${{ parameters.NpmPublishOwners }}" + $approvers = "${{ parameters.NpmPublishApprovers }}" + + if ([string]::IsNullOrWhiteSpace($owners)) { + Write-Error "NpmPublishOwners must be set before publishing npm packages." + exit 1 + } + + if ([string]::IsNullOrWhiteSpace($approvers)) { + Write-Error "NpmPublishApprovers must be set before publishing npm packages." + exit 1 + } + + Write-Host "npm ESRP owners and approvers were provided." + displayName: 'Validate npm ESRP Parameters' + + - ${{ if eq(parameters.SkipNpmRidPublish, false) }}: + - template: MicroBuild.Publish.yml@MicroBuildTemplate + parameters: + intent: 'PackageDistribution' + contentType: 'npm' + contentSource: 'Folder' + folderLocation: '$(Pipeline.Workspace)\npm\rid-packages' + waitForReleaseCompletion: true + owners: '${{ parameters.NpmPublishOwners }}' + approvers: '${{ parameters.NpmPublishApprovers }}' + + - powershell: | + $delayMinutes = [int]'${{ parameters.NpmRegistryPropagationDelayMinutes }}' + if ($delayMinutes -le 0) { + Write-Host "Skipping npm registry propagation delay because NpmRegistryPropagationDelayMinutes=$delayMinutes." + exit 0 + } + + Write-Host "Waiting $delayMinutes minute(s) before publishing the pointer package so npm can observe the RID packages." + Start-Sleep -Seconds ($delayMinutes * 60) + displayName: 'Wait for npm RID Package Propagation' + + - ${{ if eq(parameters.SkipNpmRidPublish, true) }}: + - powershell: | + Write-Host "Skipping npm RID package publish because SkipNpmRidPublish=true. The pointer package will still be submitted." + displayName: 'Skip npm RID Publish (flagged)' + + - template: MicroBuild.Publish.yml@MicroBuildTemplate + parameters: + intent: 'PackageDistribution' + contentType: 'npm' + contentSource: 'Folder' + folderLocation: '$(Pipeline.Workspace)\npm\pointer-package' + waitForReleaseCompletion: true + owners: '${{ parameters.NpmPublishOwners }}' + approvers: '${{ parameters.NpmPublishApprovers }}' + + - ${{ if eq(parameters.SkipNpmPublish, true) }}: + - powershell: | + Write-Host "=== Skipping npm Publishing (SkipNpmPublish=true) ===" + displayName: 'Skip npm Publish (flagged)' + # ===== PROMOTE TO CHANNEL ===== - ${{ if eq(parameters.SkipChannelPromotion, false) }}: - powershell: | @@ -487,6 +755,15 @@ extends: } else { Write-Host " (EXECUTED)" } + Write-Host "║ npm Publish: ${{ parameters.SkipNpmPublish }}" -NoNewline + if ("${{ parameters.SkipNpmPublish }}" -eq "true") { + Write-Host " (SKIPPED)" + } elseif ("${{ parameters.DryRun }}" -eq "true") { + Write-Host " (DRY RUN)" + } else { + Write-Host " (EXECUTED)" + } + Write-Host "║ npm RID Skip: ${{ parameters.SkipNpmRidPublish }}" Write-Host "║ Channel Promo: ${{ parameters.SkipChannelPromotion }}" -NoNewline if ("${{ parameters.SkipChannelPromotion }}" -eq "true") { Write-Host " (SKIPPED)" diff --git a/eng/scripts/stage-native-cli-tool-packages.ps1 b/eng/scripts/stage-native-cli-tool-packages.ps1 index 11b812d3983..1779a293f33 100644 --- a/eng/scripts/stage-native-cli-tool-packages.ps1 +++ b/eng/scripts/stage-native-cli-tool-packages.ps1 @@ -7,7 +7,9 @@ param( [string]$CanonicalPointerArtifactName = 'native_archives_win_x64', - [string]$NpmPackageFilePrefix = 'microsoft-aspire-cli' + [string]$NpmPackageFilePrefix = 'microsoft-aspire-cli', + + [switch]$RequireNpmPackages ) $ErrorActionPreference = 'Stop' @@ -89,8 +91,6 @@ function Get-ClassifiedNuGetPackages { } function Get-ClassifiedNpmPackages { - # Npm packages are additive to the native CLI nupkgs. If older builds only - # downloaded nupkgs, staging should continue and emit a warning below. $packages = @(Get-ChildItem -Path $DownloadRoot -Filter "$NpmPackageFilePrefix*.tgz" -File -Recurse | Sort-Object FullName) $escapedPrefix = [System.Text.RegularExpressions.Regex]::Escape($NpmPackageFilePrefix) @@ -168,7 +168,12 @@ function Get-PackagesToStage { $nugetPackagesToStage = Get-PackagesToStage (Get-ClassifiedNuGetPackages) 'Aspire.Cli' 'Aspire.Cli' 'native CLI tool' $classifiedNpmPackages = @(Get-ClassifiedNpmPackages) $npmPackagesToStage = if ($classifiedNpmPackages.Count -eq 0) { - Write-Warning "No Aspire CLI npm packages were found under native_archives_ artifacts in $DownloadRoot." + $message = "No Aspire CLI npm packages were found under native_archives_ artifacts in $DownloadRoot." + if ($RequireNpmPackages) { + throw $message + } + + Write-Warning $message @() } else { Get-PackagesToStage $classifiedNpmPackages 'Aspire CLI npm' 'Aspire CLI npm' 'Aspire CLI npm' diff --git a/tests/Infrastructure.Tests/PowerShellScripts/StageNativeCliToolPackagesTests.cs b/tests/Infrastructure.Tests/PowerShellScripts/StageNativeCliToolPackagesTests.cs index a7689336e39..a8cec4c1207 100644 --- a/tests/Infrastructure.Tests/PowerShellScripts/StageNativeCliToolPackagesTests.cs +++ b/tests/Infrastructure.Tests/PowerShellScripts/StageNativeCliToolPackagesTests.cs @@ -80,7 +80,7 @@ public async Task StagesNpmPackagesWhenPresent() CreateNativeArchiveNpmPackages(downloadRoot, "win-x64"); CreateNativeArchiveNpmPackages(downloadRoot, "linux-x64"); - var result = await RunScript(downloadRoot, shippingDir); + var result = await RunScript(downloadRoot, shippingDir, "-RequireNpmPackages"); result.EnsureSuccessful(); @@ -98,6 +98,23 @@ public async Task StagesNpmPackagesWhenPresent() Assert.Contains("Skipping non-canonical Aspire CLI npm pointer package", result.Output); } + [Fact] + [RequiresTools(["pwsh"])] + public async Task FailsWhenRequiredNpmPackagesAreMissing() + { + var downloadRoot = CreateDownloadRoot(); + var shippingDir = CreateShippingDir(); + + CreateNativeArchivePackages(downloadRoot, "win-x64"); + CreateNativeArchivePackage(downloadRoot, "linux-x64", $"Aspire.Cli.linux-x64.{PackageVersion}.nupkg"); + + var result = await RunScript(downloadRoot, shippingDir, "-RequireNpmPackages"); + + Assert.NotEqual(0, result.ExitCode); + Assert.Contains("No Aspire CLI npm packages were found", result.Output); + Assert.Contains("native_archives_", result.Output); + } + [Fact] [RequiresTools(["pwsh"])] public async Task FailsWhenCanonicalPointerPackageIsMissing() From c5a22928d84d311eb888336ec5a7094ae51a39c5 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Thu, 28 May 2026 15:58:37 -0400 Subject: [PATCH 09/35] Promote @microsoft/aspire-cli npm package from POC to production Brings the npm package path to parity with the brew cask / winget manifest flows: * Add Aspire.Cli.Utils.NpmInstallDetection so 'aspire update --self' and update notifications detect global npm installs via the ASPIRE_NPM_PACKAGE/_VERSION/_RID env vars the launcher already sets, and print 'npm install -g @microsoft/aspire-cli@latest' instead of running the GitHub-binary downloader against npm-owned files. Wired into UpdateCommand (--self path and post-project-update prompt) and CliUpdateNotifier. * Tighten launcher cache freshness in eng/clipack/npm/aspire.js: compare both size and mtime so a stale cache from a prior same-version install cannot shadow a freshly extracted native binary. * Add eng/pipelines/templates/prepare-npm-cli-packages.yml that runs a real 'npm install -g .tgz && npm install -g --omit=optional .tgz' against the just-built tarballs on a scratch npm prefix, asserts 'aspire --version' matches the build version, verifies the launcher's cache layout, uninstalls, and emits validation-summary.json. Wired into the Prepare Installers stage in azure-pipelines.yml alongside Homebrew and WinGet. * Gate release-publish-nuget.yml on the validation summary before invoking MicroBuild.Publish for npm. Download the summary from the source build, re-publish with SBOM in stage 1, then refuse to submit unless validatedByPreparePipeline is true and every required check passed. * Fix a pre-existing here-string parse bug in the 'Prepare npm Artifacts for Publishing' step. PowerShell requires the closing terminator at column 0, but YAML block scalars require every line to stay at or above the block indent. Compose the error message from an array joined with [Environment]::NewLine instead. * Drop POC framing from docs/specs/npm-cli-package.md and document the Sigstore-provenance tradeoff honestly (ESRP's npm publish path does not currently emit Sigstore attestations; integrity is anchored at the signed binary and the Microsoft1ES maintainer identity). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/specs/npm-cli-package.md | 48 ++-- eng/clipack/npm/aspire.js | 22 +- eng/pipelines/azure-pipelines.yml | 30 +++ eng/pipelines/release-publish-nuget.yml | 85 ++++++- .../templates/prepare-npm-cli-packages.yml | 235 ++++++++++++++++++ src/Aspire.Cli/Commands/UpdateCommand.cs | 31 ++- .../UpdateCommandStrings.Designer.cs | 1 + .../Resources/UpdateCommandStrings.resx | 3 + .../Resources/xlf/UpdateCommandStrings.cs.xlf | 5 + .../Resources/xlf/UpdateCommandStrings.de.xlf | 5 + .../Resources/xlf/UpdateCommandStrings.es.xlf | 5 + .../Resources/xlf/UpdateCommandStrings.fr.xlf | 5 + .../Resources/xlf/UpdateCommandStrings.it.xlf | 5 + .../Resources/xlf/UpdateCommandStrings.ja.xlf | 5 + .../Resources/xlf/UpdateCommandStrings.ko.xlf | 5 + .../Resources/xlf/UpdateCommandStrings.pl.xlf | 5 + .../xlf/UpdateCommandStrings.pt-BR.xlf | 5 + .../Resources/xlf/UpdateCommandStrings.ru.xlf | 5 + .../Resources/xlf/UpdateCommandStrings.tr.xlf | 5 + .../xlf/UpdateCommandStrings.zh-Hans.xlf | 5 + .../xlf/UpdateCommandStrings.zh-Hant.xlf | 5 + src/Aspire.Cli/Utils/CliUpdateNotifier.cs | 4 +- src/Aspire.Cli/Utils/NpmInstallDetection.cs | 109 ++++++++ .../Utils/NpmInstallDetectionTests.cs | 78 ++++++ 24 files changed, 678 insertions(+), 33 deletions(-) create mode 100644 eng/pipelines/templates/prepare-npm-cli-packages.yml create mode 100644 src/Aspire.Cli/Utils/NpmInstallDetection.cs create mode 100644 tests/Aspire.Cli.Tests/Utils/NpmInstallDetectionTests.cs diff --git a/docs/specs/npm-cli-package.md b/docs/specs/npm-cli-package.md index 9d314f3066c..b7778a27373 100644 --- a/docs/specs/npm-cli-package.md +++ b/docs/specs/npm-cli-package.md @@ -1,16 +1,16 @@ -# Aspire CLI npm package POC +# Aspire CLI npm package ## Summary -The Aspire CLI npm package POC distributes the native Aspire CLI through npm using the same native binary archives that feed the dotnet tool packages. The npm package shape follows the native-package convention used by tools such as esbuild and @vscode/ripgrep: a small top-level package exposes the command, while platform-specific packages carry the native payload. +The Aspire CLI is distributed through npm using the same signed native binary archives that feed the dotnet tool packages. The npm package shape follows the native-package convention used by tools such as esbuild and `@vscode/ripgrep`: a small top-level package exposes the command, while platform-specific packages carry the native payload. -The POC package name is `@microsoft/aspire-cli`. It is intentionally a POC and does not yet include CLI-side npm self-update behavior. +The published package is `@microsoft/aspire-cli`. It supports global installation (`npm install -g @microsoft/aspire-cli`) on Windows, macOS, and Linux (glibc and musl). The CLI detects npm installs at runtime and routes `aspire update --self` and update notifications through the npm package manager rather than the GitHub-binary downloader. ## Research and prior art This design follows the native npm package pattern used by established packages rather than introducing a custom installer. -- npm's package metadata defines the primitives this POC uses: `bin` exposes a command on PATH, `optionalDependencies` allow platform-specific packages to be skipped when they do not apply, `files` limits packed content, and `os`/`cpu` select packages by `process.platform` and `process.arch`. See the npm package.json documentation for [`bin`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#bin), [`optionalDependencies`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#optionaldependencies), [`files`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#files), [`os`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#os), and [`cpu`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#cpu). +- npm's package metadata defines the primitives this package uses: `bin` exposes a command on PATH, `optionalDependencies` allow platform-specific packages to be skipped when they do not apply, `files` limits packed content, and `os`/`cpu` select packages by `process.platform` and `process.arch`. See the npm package.json documentation for [`bin`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#bin), [`optionalDependencies`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#optionaldependencies), [`files`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#files), [`os`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#os), and [`cpu`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#cpu). - [esbuild](https://github.com/evanw/esbuild/blob/main/npm/esbuild/package.json) uses a top-level package with a `bin` entry and platform-specific packages such as [`@esbuild/linux-x64`](https://github.com/evanw/esbuild/blob/main/npm/@esbuild/linux-x64/package.json) listed as optional dependencies. Its platform resolver maps the current Node platform to an optional package and resolves the binary through Node package resolution rather than hardcoded `node_modules` paths. - [@vscode/ripgrep](https://github.com/microsoft/vscode-ripgrep/blob/main/packages/ripgrep/package.json) uses the same top-level package plus optional platform package shape for an external CLI binary. A platform package such as [`@vscode/ripgrep-linux-x64`](https://github.com/microsoft/vscode-ripgrep/blob/main/packages/ripgrep-linux-x64/package.json) contains a `bin/` payload and declares `os`/`cpu` metadata. - Rollup, SWC, and sharp show the modern `libc` split for Linux native packages. Examples include [`@rollup/rollup-linux-x64-gnu`](https://github.com/rollup/rollup/blob/master/npm/linux-x64-gnu/package.json), [`@swc/core-linux-x64-gnu`](https://github.com/swc-project/swc/blob/main/packages/core/scripts/npm/linux-x64-gnu/package.json), and [`@img/sharp-linux-x64`](https://github.com/lovell/sharp/blob/main/npm/linux-x64/package.json). Their runtime loaders also distinguish glibc from musl before selecting a native package. @@ -25,12 +25,14 @@ The Aspire-specific adaptation is the writable cache. Unlike most native npm CLI - Use a top-level npm package with a JavaScript `bin` launcher and RID-specific optional native packages. - Avoid running the self-extracting native binary directly from `node_modules` or package-manager stores. - Verify generated npm packages against the native archive before staging them. +- Validate the published packages with a real `npm install -g` test in CI before allowing the release pipeline to submit them. - Publish through the Azure DevOps release pipeline using Microsoft's ESRP-backed MicroBuild publishing flow. +- Detect npm installs at runtime so `aspire update --self` and update notifications use `npm install -g @microsoft/aspire-cli@latest` instead of the GitHub-binary downloader. ## Non-goals -- Implementing `aspire update --self` for npm installs. - Replacing the dotnet tool package flow. +- Emitting a Sigstore provenance attestation (`npm publish --provenance`). The ESRP-backed publish path does not currently issue Sigstore attestations from a public OIDC publisher. Integrity is anchored at the signed native binary and the ESRP-tracked submission identity instead. See "Product and security tradeoffs" below. ## Package layout @@ -119,7 +121,7 @@ The cache root can be overridden with `ASPIRE_NPM_CACHE_DIR` for tests and diagn The copy step is required because the native Aspire CLI self-extracts its embedded bundle relative to the process path on first run. Running the binary directly from `node_modules` could make the extraction target a package directory, pnpm store, Yarn unplugged location, global npm cache, or other read-only package-manager path. Copying to the Aspire cache makes first-run extraction land under an Aspire-owned writable layout. -The launcher sets these environment variables for future CLI-side npm install detection: +The launcher sets these environment variables so the CLI can detect that it was launched from an npm install (see `Aspire.Cli.Utils.NpmInstallDetection`) and route `aspire update --self` and update notifications through `npm` instead of the GitHub-binary downloader: ```text ASPIRE_NPM_PACKAGE @@ -127,6 +129,8 @@ ASPIRE_NPM_PACKAGE_VERSION ASPIRE_NPM_PACKAGE_RID ``` +The launcher's cache-freshness check compares both file size and `mtime`. A cached binary is reused only when its size matches the source and its `mtime` is greater than or equal to the source binary's `mtime`. Any other state (different size, older `mtime`, or unreadable cache target) triggers an atomic re-copy through a temp file. + ## Build integration `eng\clipack\Common.projitems` wires npm packing into the existing native CLI package flow. @@ -153,41 +157,49 @@ ASPIRE_NPM_PACKAGE_RID 5. Comparing the RID tarball binary byte-for-byte with the archive binary. 6. Verifying pointer package metadata, `bin/aspire.js`, `aspire-package-map.json`, and optional dependency version alignment. +`eng/pipelines/templates/prepare-npm-cli-packages.yml` runs after the byte-for-byte verification and performs a real end-to-end installation test: + +1. Installs the just-built pointer and matching RID tarball into a scratch npm prefix (`npm install -g`). +2. Invokes the installed `aspire --version` and asserts the version matches the build version. +3. Confirms the launcher's runtime cache landed under the expected `~/.aspire/npm///bin` layout. +4. Emits `validation-summary.json` listing each check's status. The release pipeline refuses to submit the npm packages to ESRP without a successful summary, mirroring the brew cask flow. + `eng\scripts\stage-native-cli-tool-packages.ps1` stages npm `.tgz` artifacts alongside existing native CLI nupkgs. Official CI invokes the script with `-RequireNpmPackages`, so source builds fail before release if the npm tarballs are missing. The default remains warning-only for local or older nupkg-only flows that call the script directly. Only one pointer package is staged. The default canonical pointer source is `native_archives_win_x64`, matching the existing native CLI package staging convention. All RID-specific packages are staged. ## Pipeline integration -The native archive workflows verify npm tarballs after the existing nupkg verification. +The native archive workflows verify npm tarballs after the existing nupkg verification and then run the end-to-end install test above. -Azure Pipelines installs Node.js before native package build because `npm pack` runs during packaging, verifies the npm packages, downloads `microsoft-aspire-cli*.tgz` in the staging job, and stages them with the native CLI packages. The source build then publishes the npm `.tgz` files as shipping flat blob artifacts so the release pipeline can consume them without treating npm tarballs as NuGet-like BAR package assets. +Azure Pipelines installs Node.js before native package build because `npm pack` runs during packaging, verifies the npm packages, downloads `microsoft-aspire-cli*.tgz` in the staging job, and stages them with the native CLI packages. The source build then publishes the npm `.tgz` files as shipping flat blob artifacts so the release pipeline can consume them without treating npm tarballs as NuGet-like BAR package assets. The install-test job also publishes a `validation-summary.json` artifact (`NpmValidationSummary`) the release pipeline requires before publishing. ## Publishing The npm packages are published from `eng/pipelines/release-publish-nuget.yml`, not from GitHub Actions. The release pipeline extends the MicroBuild publish-enabled 1ES template and submits packages through `MicroBuild.Publish.yml@MicroBuildTemplate` with `intent: PackageDistribution`, `contentType: npm`, and `contentSource: Folder`. -The release pipeline prepares two npm artifact folders: +The release pipeline prepares two npm artifact folders and one validation artifact: 1. `NpmRidPackageArtifacts` contains the seven RID packages. 2. `NpmPointerPackageArtifacts` contains the top-level `@microsoft/aspire-cli` pointer package. +3. `NpmValidationSummary` contains the `validation-summary.json` emitted by the source-build install test. The release pipeline reads this summary and refuses to invoke `MicroBuild.Publish` unless every required check passed. -The split is intentional. The release job submits RID packages first, waits for the ESRP submission to complete, waits an additional npm registry propagation delay, and then submits the pointer package. Publishing the pointer package last avoids optional dependency resolution races when a user installs the top-level package immediately after release. +The package split is intentional. The release job submits RID packages first, waits for the ESRP submission to complete, waits an additional npm registry propagation delay, and then submits the pointer package. Publishing the pointer package last avoids optional dependency resolution races when a user installs the top-level package immediately after release. -Before publishing, the release pipeline validates that exactly one pointer tarball and exactly one tarball for each supported RID are present, and that all tarballs have one version. Non-dry-run npm publishing requires release managers to provide `NpmPublishOwners` and `NpmPublishApprovers`, which are passed to ESRP. Re-runs can use `SkipNpmRidPublish` if the RID packages published but the pointer package did not, and `SkipNpmPublish` after npm publishing has completed. +Before publishing, the release pipeline validates that exactly one pointer tarball and exactly one tarball for each supported RID are present, that all tarballs have one version, and that the `NpmValidationSummary` artifact reports `validatedByPreparePipeline: true` with every required check `passed`. Non-dry-run npm publishing also requires release managers to provide `NpmPublishOwners` and `NpmPublishApprovers`, which are passed to ESRP. Re-runs can use `SkipNpmRidPublish` if the RID packages published but the pointer package did not, and `SkipNpmPublish` after npm publishing has completed. MicroBuild's npm publish template documentation does not currently expose an npm `dist-tag` parameter. Initial publishing therefore relies on the registry's default tag behavior; preview or side-channel tagging needs ESRP/MicroBuild support before it can be enabled safely. ## Product and security tradeoffs -- **No GitHub npm publishing token**: Publishing is centralized through ESRP/MicroBuild and the Microsoft npm maintainer identity instead of storing an npm token in GitHub or using a repository-local GitHub Actions publisher. -- **Signed payload, unsigned tarball container**: The npm tarball is created from the native CLI archive produced by the signed CI flow, and verification compares the RID tarball binary byte-for-byte with that archive. The `.tgz` container itself is not separately signed; integrity comes from CI verification, SBOM-covered release artifacts, ESRP submission, and npm registry package integrity. -- **Writable cache**: Copying the native binary to `~/.aspire/npm///bin` avoids self-extraction into package-manager stores, but it means the launcher owns cache creation and freshness checks. -- **Update behavior**: npm updates are package-manager driven (`npm update`, reinstalling the global package, or changing the requested version). `aspire update --self` remains out of scope for npm installs until the CLI has explicit npm install detection and guidance. +- **No GitHub npm publishing token**: Publishing is centralized through ESRP/MicroBuild and the Microsoft1ES npm maintainer identity instead of storing an npm token in GitHub or using a repository-local GitHub Actions publisher. +- **Signed payload, unsigned tarball container**: The npm tarball is created from the native CLI archive produced by the signed CI flow, and verification compares the RID tarball binary byte-for-byte with that archive. The `.tgz` container itself is not separately signed; integrity comes from CI verification, the `NpmValidationSummary` install test, SBOM-covered release artifacts, ESRP submission, and npm registry package integrity. +- **No Sigstore `npm publish --provenance` attestation**: ESRP's npm publish path is not currently configured to emit Sigstore provenance attestations from a public OIDC publisher. Integrity is anchored at the signed native binary, the Microsoft1ES npm maintainer identity, and the ESRP submission audit trail. When ESRP gains support for npm provenance attestations, the release pipeline should opt in and this tradeoff should be revisited. +- **Writable cache**: Copying the native binary to `~/.aspire/npm///bin` avoids self-extraction into package-manager stores, but it means the launcher owns cache creation and freshness checks. The launcher uses size + `mtime` comparison so a stale cache from an earlier same-version install does not silently shadow a re-downloaded binary. +- **Update behavior**: npm updates remain package-manager driven (`npm install -g @microsoft/aspire-cli@latest`). The CLI detects npm installs via the launcher's environment variables and prints the npm-specific update command instead of attempting to overwrite the npm-owned binary with the GitHub-binary downloader. - **Linux libc split**: Separate glibc and musl packages avoid shipping one Linux binary that is wrong for Alpine-style environments, at the cost of one additional optional dependency package. ## Open follow-ups -- Decide whether the launcher should use stronger cache freshness than file-size comparison. -- Implement CLI-side npm install detection and self-update guidance. -- Add end-to-end installation tests against a real npm install layout. +- Add Sigstore provenance once ESRP/MicroBuild's npm publish path supports it. +- Add `npm install --no-optional` guidance and a clearer error message in the launcher when no RID package is installed. diff --git a/eng/clipack/npm/aspire.js b/eng/clipack/npm/aspire.js index b9d2eba8ae0..58c4c68a358 100644 --- a/eng/clipack/npm/aspire.js +++ b/eng/clipack/npm/aspire.js @@ -119,7 +119,21 @@ function needsCopy(sourcePath, targetPath) { try { const source = fs.statSync(sourcePath); const target = fs.statSync(targetPath); - return source.size !== target.size; + + // Size mismatch always means stale cache. Even when the size matches, the + // cached binary is only trusted if its mtime is at or after the source's + // mtime. This catches the case where a same-version reinstall replaces the + // source binary but the cache was left from a prior install with identical + // content size (e.g., partial overwrite, corruption, or a swapped build). + if (source.size !== target.size) { + return true; + } + + if (target.mtimeMs < source.mtimeMs) { + return true; + } + + return false; } catch { return true; } @@ -134,8 +148,10 @@ function main() { stdio: 'inherit', env: { ...process.env, - // Future CLI-side update detection can use these values to distinguish - // npm installs from dotnet tool installs. + // Surface the install context to the CLI so `aspire update --self` and + // update notifications can route through `npm install -g` instead of + // overwriting npm-owned files with the GitHub-binary downloader. See + // Aspire.Cli.Utils.NpmInstallDetection. ASPIRE_NPM_PACKAGE: packageJson.name, ASPIRE_NPM_PACKAGE_VERSION: packageJson.version, ASPIRE_NPM_PACKAGE_RID: rid diff --git a/eng/pipelines/azure-pipelines.yml b/eng/pipelines/azure-pipelines.yml index cec04e5435c..64d0d957555 100644 --- a/eng/pipelines/azure-pipelines.yml +++ b/eng/pipelines/azure-pipelines.yml @@ -498,3 +498,33 @@ extends: artifactVersion: $(aspireArtifactVersion) archiveRoot: $(Pipeline.Workspace)/native-archives skipUrlValidation: ${{ ne(variables['_PackagesPublished'], 'true') }} + + - job: NpmInstall + displayName: npm install validation + timeoutInMinutes: 30 + pool: + name: NetCore1ESPool-Internal + image: 1es-ubuntu-2204 + os: linux + steps: + - checkout: self + fetchDepth: 1 + # Download the just-built npm tarballs the build stage published as + # blob artifacts via stage-native-cli-tool-packages.ps1. Filter to + # avoid pulling unrelated blob assets. + - task: DownloadPipelineArtifact@2 + displayName: 🟣Download npm packages from build + inputs: + artifact: BlobArtifacts + itemPattern: '**/microsoft-aspire-cli*.tgz' + targetPath: '$(Pipeline.Workspace)/npm-packages' + - task: NodeTool@0 + displayName: 🟣Install Node.js + inputs: + versionSpec: '20.x' + - template: /eng/pipelines/templates/prepare-npm-cli-packages.yml@self + parameters: + npmPackagesDir: $(Pipeline.Workspace)/npm-packages + expectedVersion: $(aspireVersion) + rid: linux-x64 + skipRegistryResolution: true diff --git a/eng/pipelines/release-publish-nuget.yml b/eng/pipelines/release-publish-nuget.yml index df776c80d5f..f5c05e5c1ae 100644 --- a/eng/pipelines/release-publish-nuget.yml +++ b/eng/pipelines/release-publish-nuget.yml @@ -138,6 +138,10 @@ extends: displayName: 'Publish npm Pointer Package Artifact with SBOM' targetPath: '$(Pipeline.Workspace)/npm/pointer-package' artifactName: 'NpmPointerPackageArtifacts' + - output: pipelineArtifact + displayName: 'Publish npm Validation Summary' + targetPath: '$(Pipeline.Workspace)/npm/validation-summary' + artifactName: 'NpmValidationSummary' - output: pipelineArtifact displayName: 'Publish WinGet Manifests' targetPath: '$(Pipeline.Workspace)/installers/winget-manifests-stable' @@ -171,6 +175,10 @@ extends: artifact: BlobArtifacts patterns: '**/microsoft-aspire-cli*.tgz' + - download: aspire-build + displayName: 'Download npm validation summary from Source Build' + artifact: npm-validation-summary + - download: aspire-build displayName: 'Download WinGet Manifests from Source Build' artifact: winget-manifests-stable @@ -234,15 +242,20 @@ extends: Write-Host "Preparing npm packages from $sourcePath" if (!(Test-Path $sourcePath)) { - Write-Error @" - BlobArtifacts was not downloaded from the source build at '$sourcePath'. - npm CLI packages ship as flat blobs in BlobArtifacts (configured via eng/Publishing.props). - Possible causes: - 1. The source build (azure-pipelines.yml) ran before the npm CLI package work landed. - Re-run the release pipeline with SkipNpmPublish=true, or rebuild from a newer commit. - 2. The source build failed to produce or publish the BlobArtifacts pipeline artifact. - 3. The wrong source build was selected. - "@ + # Avoid PowerShell here-strings inside YAML block scalars: the + # PowerShell parser requires the closing "@ at column 0, while + # YAML requires every line to be at or above the block indent. + # Composing the message from an array keeps both grammars happy. + $errorLines = @( + "BlobArtifacts was not downloaded from the source build at '$sourcePath'.", + "npm CLI packages ship as flat blobs in BlobArtifacts (configured via eng/Publishing.props).", + "Possible causes:", + " 1. The source build (azure-pipelines.yml) ran before the npm CLI package work landed.", + " Re-run the release pipeline with SkipNpmPublish=true, or rebuild from a newer commit.", + " 2. The source build failed to produce or publish the BlobArtifacts pipeline artifact.", + " 3. The wrong source build was selected." + ) + Write-Error ($errorLines -join [Environment]::NewLine) exit 1 } @@ -311,6 +324,17 @@ extends: } Copy-Item $pointerPackages[0].FullName -Destination $pointerTargetPath -Force + # Copy the install-test validation summary into its own output folder. + # Stage 2 re-validates this summary before submitting to ESRP/MicroBuild. + $summarySource = "$(Pipeline.Workspace)/aspire-build/npm-validation-summary/validation-summary.json" + $summaryTarget = "$(Pipeline.Workspace)/npm/validation-summary" + New-Item -ItemType Directory -Path $summaryTarget -Force | Out-Null + if (!(Test-Path $summarySource)) { + Write-Error "npm validation summary was not downloaded from the source build at '$summarySource'. The source build's npm install-test job must have failed or did not run." + exit 1 + } + Copy-Item $summarySource -Destination (Join-Path $summaryTarget 'validation-summary.json') -Force + Write-Host "Prepared $($ridPackages.Count) RID npm package(s) and pointer package version $($versions[0])." displayName: 'Prepare npm Artifacts for Publishing' @@ -318,6 +342,7 @@ extends: - powershell: | New-Item -ItemType Directory -Path "$(Pipeline.Workspace)/npm/rid-packages" -Force | Out-Null New-Item -ItemType Directory -Path "$(Pipeline.Workspace)/npm/pointer-package" -Force | Out-Null + New-Item -ItemType Directory -Path "$(Pipeline.Workspace)/npm/validation-summary" -Force | Out-Null Write-Host "Created empty npm artifact placeholders because SkipNpmPublish=true." displayName: 'Prepare Empty npm Artifact Placeholders' @@ -382,6 +407,9 @@ extends: - input: pipelineArtifact artifactName: NpmPointerPackageArtifacts targetPath: '$(Pipeline.Workspace)/npm/pointer-package' + - input: pipelineArtifact + artifactName: NpmValidationSummary + targetPath: '$(Pipeline.Workspace)/npm/validation-summary' steps: # ===== VALIDATION ===== # Note: No checkout - releaseJob doesn't allow it. All scripts are inlined. @@ -555,6 +583,45 @@ extends: # ===== PUBLISH TO npm ===== - ${{ if eq(parameters.SkipNpmPublish, false) }}: + - powershell: | + $ErrorActionPreference = 'Stop' + $summaryPath = "$(Pipeline.Workspace)/npm/validation-summary/validation-summary.json" + + if (!(Test-Path $summaryPath)) { + Write-Error "npm validation summary not found: $summaryPath. Refusing to publish without verified prepare-stage validation." + exit 1 + } + + try { + $summary = Get-Content -Raw $summaryPath | ConvertFrom-Json + } + catch { + Write-Error "npm validation summary is invalid JSON: $summaryPath" + throw + } + + if (-not $summary.validatedByPreparePipeline) { + Write-Error "npm validation summary does not indicate successful prepare-stage validation." + exit 1 + } + + $requiredChecks = @('install', 'version', 'launcher', 'uninstall') + foreach ($checkName in $requiredChecks) { + $check = $summary.checks.$checkName + if ($null -eq $check) { + Write-Error "npm validation summary is missing required check '$checkName'." + exit 1 + } + + if ("$($check.status)" -ne 'passed') { + Write-Error "npm validation check '$checkName' did not pass (status='$($check.status)')." + exit 1 + } + } + + Write-Host "npm validation summary verified ($($summary.rid), version $($summary.expectedVersion))." + displayName: 'Validate npm Prepare-Stage Summary' + - powershell: | $ridPackagesPath = "$(Pipeline.Workspace)/npm/rid-packages" $pointerPackagePath = "$(Pipeline.Workspace)/npm/pointer-package" diff --git a/eng/pipelines/templates/prepare-npm-cli-packages.yml b/eng/pipelines/templates/prepare-npm-cli-packages.yml new file mode 100644 index 00000000000..a105690d7bb --- /dev/null +++ b/eng/pipelines/templates/prepare-npm-cli-packages.yml @@ -0,0 +1,235 @@ +parameters: + - name: npmPackagesDir + type: string + default: '' + - name: expectedVersion + type: string + default: '' + - name: rid + type: string + default: 'linux-x64' + # When true, the install test is allowed to run against just-built tarballs + # without contacting the npm registry. PR builds set this to true; release + # validation builds also set this to true. The variable exists so future + # registry-resolution probes can be gated on it. + - name: skipRegistryResolution + type: boolean + default: true + +steps: + - bash: | + set -euo pipefail + packagesDir='${{ parameters.npmPackagesDir }}' + expectedVersion='${{ parameters.expectedVersion }}' + rid='${{ parameters.rid }}' + + if [ -z "$packagesDir" ] || [ ! -d "$packagesDir" ]; then + echo "##[error]npmPackagesDir parameter is required and must point to a directory containing the just-built microsoft-aspire-cli*.tgz files." + exit 1 + fi + + if [ -z "$expectedVersion" ]; then + echo "##[error]expectedVersion parameter is required." + exit 1 + fi + + if [ -z "$rid" ]; then + echo "##[error]rid parameter is required." + exit 1 + fi + + echo "##vso[task.setvariable variable=NpmPackagesDir]$packagesDir" + echo "##vso[task.setvariable variable=NpmExpectedVersion]$expectedVersion" + echo "##vso[task.setvariable variable=NpmTestRid]$rid" + displayName: 🟣Resolve npm install-test inputs + + - bash: | + set -euo pipefail + packagesDir="$(NpmPackagesDir)" + expectedVersion="$(NpmExpectedVersion)" + rid="$(NpmTestRid)" + + # Filename layout produced by eng/scripts/pack-cli-npm-package.ps1: + # microsoft-aspire-cli-.tgz (pointer package) + # microsoft-aspire-cli--.tgz (RID package) + # The pointer filename never embeds a RID, so distinguish them on that. + shopt -s globstar nullglob + mapfile -t allPackages < <(find "$packagesDir" -type f -name "microsoft-aspire-cli*.tgz" | sort -u) + + if [ ${#allPackages[@]} -eq 0 ]; then + echo "##[error]No microsoft-aspire-cli*.tgz files found under $packagesDir" + exit 1 + fi + + pointer="" + ridTarball="" + ridFilename="microsoft-aspire-cli-${rid}-${expectedVersion}.tgz" + pointerFilename="microsoft-aspire-cli-${expectedVersion}.tgz" + + for pkg in "${allPackages[@]}"; do + base="$(basename "$pkg")" + if [ "$base" = "$pointerFilename" ]; then + pointer="$pkg" + elif [ "$base" = "$ridFilename" ]; then + ridTarball="$pkg" + fi + done + + if [ -z "$pointer" ]; then + echo "##[error]Pointer package $pointerFilename was not found under $packagesDir" + echo "Discovered files:" + printf ' %s\n' "${allPackages[@]}" + exit 1 + fi + + if [ -z "$ridTarball" ]; then + echo "##[error]RID package $ridFilename was not found under $packagesDir" + echo "Discovered files:" + printf ' %s\n' "${allPackages[@]}" + exit 1 + fi + + echo "Pointer package: $pointer" + echo "RID package: $ridTarball" + echo "##vso[task.setvariable variable=NpmPointerTarball]$pointer" + echo "##vso[task.setvariable variable=NpmRidTarball]$ridTarball" + displayName: 🟣Locate pointer and RID tarballs + + - bash: | + set -euo pipefail + pointer="$(NpmPointerTarball)" + ridTarball="$(NpmRidTarball)" + expectedVersion="$(NpmExpectedVersion)" + rid="$(NpmTestRid)" + + # Use a scratch npm prefix so the test never mutates the agent's + # global node_modules and so cleanup is a single rm -rf. + prefix="$(Build.StagingDirectory)/npm-validate-prefix" + cache="$(Build.StagingDirectory)/npm-validate-cache" + aspireCache="$(Build.StagingDirectory)/npm-validate-aspire-cache" + rm -rf "$prefix" "$cache" "$aspireCache" + mkdir -p "$prefix" "$cache" "$aspireCache" + + export NPM_CONFIG_PREFIX="$prefix" + export NPM_CONFIG_CACHE="$cache" + export ASPIRE_NPM_CACHE_DIR="$aspireCache" + # Prefer the freshly-built launcher's PATH; do not poison existing aspire binaries. + export PATH="$prefix/bin:$PATH" + + if command -v aspire >/dev/null 2>&1; then + echo "##[error]aspire is already on PATH before install ($(command -v aspire)) — test environment is not clean" + exit 1 + fi + + # Install the RID package first so it lands as a top-level sibling of the + # pointer package. Then install the pointer with --omit=optional so npm + # does not try to fetch the matching RID dep from the registry (the + # just-built version does not yet exist in the public registry during + # this validation step). + echo "Installing RID package..." + npm install -g --foreground-scripts=false --no-audit --no-fund --loglevel=warn "$ridTarball" + + echo "Installing pointer package..." + npm install -g --foreground-scripts=false --no-audit --no-fund --loglevel=warn --omit=optional "$pointer" + + echo "" + echo "Verifying aspire CLI is available on PATH..." + if ! command -v aspire >/dev/null 2>&1; then + echo "##[error]aspire command not found in PATH after npm install" + ls -la "$prefix/bin" || true + exit 1 + fi + echo " Path: $(command -v aspire)" + + # Capture the launcher's reported version. The CLI is set to skip its first-run + # update check in CI via DOTNET_CLI_TELEMETRY_OPTOUT and friends; here we just + # need a clean --version line. + actualVersion="$(aspire --version 2>&1 | tail -n 1 | tr -d '[:space:]')" + echo " Reported version: $actualVersion" + if [ "$actualVersion" != "$expectedVersion" ]; then + echo "##[error]aspire --version reported '$actualVersion' but expected '$expectedVersion'" + exit 1 + fi + + # The launcher copies the native binary into $ASPIRE_NPM_CACHE_DIR///bin/aspire. + cachedBinary="$aspireCache/$expectedVersion/$rid/bin/aspire" + if [ ! -f "$cachedBinary" ]; then + echo "##[error]Expected cached binary at $cachedBinary was not created by the launcher" + find "$aspireCache" -maxdepth 6 -type f || true + exit 1 + fi + if [ ! -x "$cachedBinary" ]; then + echo "##[error]Cached binary at $cachedBinary is not executable" + ls -la "$cachedBinary" + exit 1 + fi + echo " Launcher cache layout verified at $cachedBinary" + + echo "" + echo "Uninstalling pointer and RID packages..." + npm uninstall -g --loglevel=warn '@microsoft/aspire-cli' "@microsoft/aspire-cli-${rid}" + + if command -v aspire >/dev/null 2>&1; then + echo "##[error]aspire command still on PATH after uninstall ($(command -v aspire))" + exit 1 + fi + echo " Confirmed: aspire is no longer in PATH" + + # Surface every status to the summary step via task variables. + echo "##vso[task.setvariable variable=NpmCheckInstall]passed" + echo "##vso[task.setvariable variable=NpmCheckVersion]passed" + echo "##vso[task.setvariable variable=NpmCheckLauncher]passed" + echo "##vso[task.setvariable variable=NpmCheckUninstall]passed" + displayName: 🟣Install, verify, and uninstall @microsoft/aspire-cli + + - bash: | + set -euo pipefail + outputDir="$(Build.StagingDirectory)/npm-validation-summary" + mkdir -p "$outputDir" + outputPath="$outputDir/validation-summary.json" + rid="$(NpmTestRid)" + expectedVersion="$(NpmExpectedVersion)" + skipRegistry='${{ parameters.skipRegistryResolution }}' + + # Lowercase booleans so the JSON is valid. + skipRegistry="$(printf '%s' "$skipRegistry" | tr '[:upper:]' '[:lower:]')" + + cat > "$outputPath" <.tgz && npm install -g --omit=optional .tgz" + }, + "version": { + "status": "$(NpmCheckVersion)", + "details": "aspire --version output matched the build version" + }, + "launcher": { + "status": "$(NpmCheckLauncher)", + "details": "Launcher cached native binary at ASPIRE_NPM_CACHE_DIR///bin/aspire" + }, + "uninstall": { + "status": "$(NpmCheckUninstall)", + "details": "npm uninstall -g @microsoft/aspire-cli @microsoft/aspire-cli-$rid" + } + } + } + EOF + + echo "Wrote npm validation summary to $outputPath" + cat "$outputPath" + displayName: 🟣Write npm validation summary + condition: always() + + - task: 1ES.PublishBuildArtifacts@1 + displayName: 🟣Publish npm validation summary + condition: always() + inputs: + PathtoPublish: '$(Build.StagingDirectory)/npm-validation-summary' + ArtifactName: npm-validation-summary diff --git a/src/Aspire.Cli/Commands/UpdateCommand.cs b/src/Aspire.Cli/Commands/UpdateCommand.cs index e815a74d6f1..3b94663ac7c 100644 --- a/src/Aspire.Cli/Commands/UpdateCommand.cs +++ b/src/Aspire.Cli/Commands/UpdateCommand.cs @@ -109,6 +109,11 @@ public UpdateCommand( return DotNetToolDetection.GetDotNetToolUpdateCommand(); } + private static string? GetNpmUpdateCommand() + { + return NpmInstallDetection.GetNpmUpdateCommand(); + } + protected override async Task ExecuteAsync(ParseResult parseResult, CancellationToken cancellationToken) { var isSelfUpdate = parseResult.GetValue(s_selfOption); @@ -125,6 +130,17 @@ protected override async Task ExecuteAsync(ParseResult parseResult, Cancell return 0; } + // When running from a global npm install, defer to npm rather than overwriting + // npm-owned files with the GitHub-binary downloader. Detected via env vars the + // npm launcher (eng/clipack/npm/aspire.js) sets when spawning the native binary. + var npmUpdateCommand = GetNpmUpdateCommand(); + if (npmUpdateCommand is not null) + { + InteractionService.DisplayMessage(KnownEmojis.Information, UpdateCommandStrings.NpmSelfUpdateMessage); + InteractionService.DisplayPlainText($" {npmUpdateCommand}"); + return 0; + } + if (_cliDownloader is null) { InteractionService.DisplayError("CLI self-update is not available in this environment."); @@ -254,6 +270,14 @@ protected override async Task ExecuteAsync(ParseResult parseResult, Cancell return ExitCodeConstants.Success; } + var npmUpdateCommand = GetNpmUpdateCommand(); + if (npmUpdateCommand is not null) + { + InteractionService.DisplayMessage(KnownEmojis.Information, UpdateCommandStrings.NpmSelfUpdateMessage); + InteractionService.DisplayPlainText($" {npmUpdateCommand}"); + return ExitCodeConstants.Success; + } + // Use the same channel that was selected for the project update return await ExecuteSelfUpdateAsync(parseResult, cancellationToken, channel.Name); } @@ -278,8 +302,11 @@ protected override async Task ExecuteAsync(ParseResult parseResult, Cancell // Check if this is a "no project found" error and prompt for self-update if (string.Equals(ex.Message, ErrorStrings.NoProjectFileFound, StringComparisons.CliInputOrOutput)) { - // Only prompt for self-update if not running as dotnet tool and downloader is available - if (GetDotNetToolUpdateCommand() is null && _cliDownloader is not null) + // Only prompt for self-update when we can actually perform it: not as a + // dotnet tool, not from an npm install, and the GitHub-binary downloader + // is wired up. Otherwise the downloader would overwrite package-manager-owned + // files instead of letting the package manager handle the update. + if (GetDotNetToolUpdateCommand() is null && GetNpmUpdateCommand() is null && _cliDownloader is not null) { var shouldUpdateCli = await InteractionService.PromptConfirmAsync( UpdateCommandStrings.NoAppHostFoundUpdateCliPrompt, diff --git a/src/Aspire.Cli/Resources/UpdateCommandStrings.Designer.cs b/src/Aspire.Cli/Resources/UpdateCommandStrings.Designer.cs index 4d11b077e99..ec2e6c68fa8 100644 --- a/src/Aspire.Cli/Resources/UpdateCommandStrings.Designer.cs +++ b/src/Aspire.Cli/Resources/UpdateCommandStrings.Designer.cs @@ -107,6 +107,7 @@ internal static string ProjectArgumentDescription { internal static string QualityOptionDescription => ResourceManager.GetString("QualityOptionDescription", resourceCulture); internal static string QualityOptionDescriptionWithStaging => ResourceManager.GetString("QualityOptionDescriptionWithStaging", resourceCulture); internal static string DotNetToolSelfUpdateMessage => ResourceManager.GetString("DotNetToolSelfUpdateMessage", resourceCulture); + internal static string NpmSelfUpdateMessage => ResourceManager.GetString("NpmSelfUpdateMessage", resourceCulture); internal static string MigratedToNewSdkFormat => ResourceManager.GetString("MigratedToNewSdkFormat", resourceCulture); internal static string RemovedObsoleteAppHostPackage => ResourceManager.GetString("RemovedObsoleteAppHostPackage", resourceCulture); internal static string NoWritePermissionToInstallDirectory => ResourceManager.GetString("NoWritePermissionToInstallDirectory", resourceCulture); diff --git a/src/Aspire.Cli/Resources/UpdateCommandStrings.resx b/src/Aspire.Cli/Resources/UpdateCommandStrings.resx index de575d67b7a..6db727ac25d 100644 --- a/src/Aspire.Cli/Resources/UpdateCommandStrings.resx +++ b/src/Aspire.Cli/Resources/UpdateCommandStrings.resx @@ -138,6 +138,9 @@ To update the Aspire CLI when installed as a .NET tool, run: + + To update the Aspire CLI when installed from npm, run: + Migrated to new project format: <Project Sdk="Aspire.AppHost.Sdk/{0}"> diff --git a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.cs.xlf b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.cs.xlf index aa20cc66077..d0443721bb9 100644 --- a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.cs.xlf +++ b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.cs.xlf @@ -157,6 +157,11 @@ Nelze zapisovat do instalačního adresáře {0}. Spusťte prosím aktualizaci se zvýšenými oprávněními (např. pomocí sudo v Linuxu nebo macOS). + + To update the Aspire CLI when installed from npm, run: + To update the Aspire CLI when installed from npm, run: + + Directory to create or update the NuGet.config file in Directory to create or update the NuGet.config file in diff --git a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.de.xlf b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.de.xlf index 1034647812b..428a04724ef 100644 --- a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.de.xlf +++ b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.de.xlf @@ -157,6 +157,11 @@ Schreiben in das Installationsverzeichnis „{0}“ ist nicht möglich. Führen Sie das Update mit erhöhten Berechtigungen aus (zum Beispiel mit sudo unter Linux/macOS). + + To update the Aspire CLI when installed from npm, run: + To update the Aspire CLI when installed from npm, run: + + Directory to create or update the NuGet.config file in Directory to create or update the NuGet.config file in diff --git a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.es.xlf b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.es.xlf index 817354bde05..df9576a877b 100644 --- a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.es.xlf +++ b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.es.xlf @@ -157,6 +157,11 @@ No se puede escribir en el directorio de instalación '{0}'. Ejecute la actualización con permisos elevados (por ejemplo, con sudo en Linux o macOS). + + To update the Aspire CLI when installed from npm, run: + To update the Aspire CLI when installed from npm, run: + + Directory to create or update the NuGet.config file in Directory to create or update the NuGet.config file in diff --git a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.fr.xlf b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.fr.xlf index bb81d4b058b..9942285f79d 100644 --- a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.fr.xlf +++ b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.fr.xlf @@ -157,6 +157,11 @@ Impossible d’écrire dans le répertoire d’installation « {0} ». Exécutez la mise à jour avec des autorisations élevées (par exemple, en utilisant sudo sur Linux/macOS). + + To update the Aspire CLI when installed from npm, run: + To update the Aspire CLI when installed from npm, run: + + Directory to create or update the NuGet.config file in Directory to create or update the NuGet.config file in diff --git a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.it.xlf b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.it.xlf index 2e39559bdbc..e62a65d8c6f 100644 --- a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.it.xlf +++ b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.it.xlf @@ -157,6 +157,11 @@ Impossibile scrivere nella directory di installazione "{0}". Eseguire l'aggiornamento con autorizzazioni elevate, ad esempio usando sudo su Linux/macOS. + + To update the Aspire CLI when installed from npm, run: + To update the Aspire CLI when installed from npm, run: + + Directory to create or update the NuGet.config file in Directory to create or update the NuGet.config file in diff --git a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.ja.xlf b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.ja.xlf index 58f0d042195..2fb5b10e056 100644 --- a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.ja.xlf +++ b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.ja.xlf @@ -157,6 +157,11 @@ インストール ディレクトリ '{0}' に書き込めません。管理者権限で更新を実行してください (例: Linux/macOS で sudo を使用)。 + + To update the Aspire CLI when installed from npm, run: + To update the Aspire CLI when installed from npm, run: + + Directory to create or update the NuGet.config file in Directory to create or update the NuGet.config file in diff --git a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.ko.xlf b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.ko.xlf index bdf0ba6229a..077748202ae 100644 --- a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.ko.xlf +++ b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.ko.xlf @@ -157,6 +157,11 @@ 설치 디렉터리 '{0}'에 쓸 수 없습니다. 관리자 권한으로 업데이트를 실행하세요(예: Linux/macOS에서 sudo 사용). + + To update the Aspire CLI when installed from npm, run: + To update the Aspire CLI when installed from npm, run: + + Directory to create or update the NuGet.config file in Directory to create or update the NuGet.config file in diff --git a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.pl.xlf b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.pl.xlf index 249238b4f53..113855388f0 100644 --- a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.pl.xlf +++ b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.pl.xlf @@ -157,6 +157,11 @@ Nie można zapisać w katalogu instalacyjnym „{0}”. Uruchom aktualizację z podniesionymi uprawnieniami (np. używając programu sudo w systemie Linux lub macOS). + + To update the Aspire CLI when installed from npm, run: + To update the Aspire CLI when installed from npm, run: + + Directory to create or update the NuGet.config file in Directory to create or update the NuGet.config file in diff --git a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.pt-BR.xlf b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.pt-BR.xlf index 950b43eb1d8..8c13bb421eb 100644 --- a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.pt-BR.xlf +++ b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.pt-BR.xlf @@ -157,6 +157,11 @@ Não é possível gravar no diretório de instalação '{0}'. Execute a atualização com permissões elevadas (por exemplo, usando sudo no Linux/macOS). + + To update the Aspire CLI when installed from npm, run: + To update the Aspire CLI when installed from npm, run: + + Directory to create or update the NuGet.config file in Directory to create or update the NuGet.config file in diff --git a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.ru.xlf b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.ru.xlf index 43bd862ec89..0a93ce569dd 100644 --- a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.ru.xlf +++ b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.ru.xlf @@ -157,6 +157,11 @@ Не удается записать в каталог установки "{0}". Запустите обновление с повышенными правами (например, используя sudo в Linux или macOS). + + To update the Aspire CLI when installed from npm, run: + To update the Aspire CLI when installed from npm, run: + + Directory to create or update the NuGet.config file in Directory to create or update the NuGet.config file in diff --git a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.tr.xlf b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.tr.xlf index 91964f63232..916442e2615 100644 --- a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.tr.xlf +++ b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.tr.xlf @@ -157,6 +157,11 @@ '{0}' yükleme dizinine yazılamıyor. Lütfen güncellemeyi yükseltilmiş izinlerle (örneğin Linux/macOS'ta sudo kullanarak) çalıştırın. + + To update the Aspire CLI when installed from npm, run: + To update the Aspire CLI when installed from npm, run: + + Directory to create or update the NuGet.config file in Directory to create or update the NuGet.config file in diff --git a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.zh-Hans.xlf b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.zh-Hans.xlf index 408aede0fe6..06fd0eca487 100644 --- a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.zh-Hans.xlf +++ b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.zh-Hans.xlf @@ -157,6 +157,11 @@ 无法写入安装目录“{0}”。请使用提升的权限运行更新(例如,在 Linux/macOS 上使用 sudo)。 + + To update the Aspire CLI when installed from npm, run: + To update the Aspire CLI when installed from npm, run: + + Directory to create or update the NuGet.config file in Directory to create or update the NuGet.config file in diff --git a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.zh-Hant.xlf b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.zh-Hant.xlf index 2c09fa9134d..ba2bcc16813 100644 --- a/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.zh-Hant.xlf +++ b/src/Aspire.Cli/Resources/xlf/UpdateCommandStrings.zh-Hant.xlf @@ -157,6 +157,11 @@ 無法寫入安裝目錄 '{0}'。請使用提高的權限來執行更新 (例如,在Linux/macOS上使用 sudo)。 + + To update the Aspire CLI when installed from npm, run: + To update the Aspire CLI when installed from npm, run: + + Directory to create or update the NuGet.config file in Directory to create or update the NuGet.config file in diff --git a/src/Aspire.Cli/Utils/CliUpdateNotifier.cs b/src/Aspire.Cli/Utils/CliUpdateNotifier.cs index 02b46e25da4..3b5d08d6bc9 100644 --- a/src/Aspire.Cli/Utils/CliUpdateNotifier.cs +++ b/src/Aspire.Cli/Utils/CliUpdateNotifier.cs @@ -50,7 +50,9 @@ public void NotifyIfUpdateAvailable() if (newerVersion is not null) { - var updateCommand = DotNetToolDetection.GetDotNetToolUpdateCommand() ?? "aspire update"; + var updateCommand = DotNetToolDetection.GetDotNetToolUpdateCommand() + ?? NpmInstallDetection.GetNpmUpdateCommand() + ?? "aspire update"; interactionService.DisplayVersionUpdateNotification(newerVersion.ToString(), updateCommand); } diff --git a/src/Aspire.Cli/Utils/NpmInstallDetection.cs b/src/Aspire.Cli/Utils/NpmInstallDetection.cs new file mode 100644 index 00000000000..e8d50e73e13 --- /dev/null +++ b/src/Aspire.Cli/Utils/NpmInstallDetection.cs @@ -0,0 +1,109 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +namespace Aspire.Cli.Utils; + +/// +/// Detects whether the Aspire CLI is running from a global npm install of the +/// @microsoft/aspire-cli package and provides the npm-equivalent +/// self-update command so the CLI surfaces the correct guidance instead of +/// attempting to overwrite npm-owned files with the GitHub-binary downloader. +/// +/// +/// The npm launcher (eng/clipack/npm/aspire.js) sets three environment +/// variables when it spawns the native CLI binary: ASPIRE_NPM_PACKAGE, +/// ASPIRE_NPM_PACKAGE_VERSION, and ASPIRE_NPM_PACKAGE_RID. +/// Presence of ASPIRE_NPM_PACKAGE with the expected package name is +/// treated as the authoritative signal that the CLI was launched by the npm +/// launcher; the other variables are surfaced via accessors for diagnostics. +/// +internal static class NpmInstallDetection +{ + internal const string PackageEnvironmentVariableName = "ASPIRE_NPM_PACKAGE"; + internal const string PackageVersionEnvironmentVariableName = "ASPIRE_NPM_PACKAGE_VERSION"; + internal const string PackageRidEnvironmentVariableName = "ASPIRE_NPM_PACKAGE_RID"; + + internal const string ExpectedPackageName = "@microsoft/aspire-cli"; + + private static readonly AsyncLocal s_environmentOverride = new(); + + internal static bool IsRunningFromNpm() + { + return GetNpmUpdateCommand() is not null; + } + + internal static string? GetNpmUpdateCommand() + { + var env = s_environmentOverride.Value ?? ProcessEnvironmentReader.Instance; + var packageName = env.GetEnvironmentVariable(PackageEnvironmentVariableName); + + if (string.IsNullOrWhiteSpace(packageName)) + { + return null; + } + + // The launcher always writes the canonical "@microsoft/aspire-cli" package name. + // Reject anything else so an unrelated env var collision does not flip the CLI + // into the npm self-update path. + if (!string.Equals(packageName, ExpectedPackageName, StringComparison.Ordinal)) + { + return null; + } + + return $"npm install -g {ExpectedPackageName}@latest"; + } + + internal static string? GetNpmPackageVersion() + { + var env = s_environmentOverride.Value ?? ProcessEnvironmentReader.Instance; + var version = env.GetEnvironmentVariable(PackageVersionEnvironmentVariableName); + + return string.IsNullOrWhiteSpace(version) ? null : version; + } + + internal static string? GetNpmPackageRid() + { + var env = s_environmentOverride.Value ?? ProcessEnvironmentReader.Instance; + var rid = env.GetEnvironmentVariable(PackageRidEnvironmentVariableName); + + return string.IsNullOrWhiteSpace(rid) ? null : rid; + } + + internal static IDisposable UseEnvironmentForTesting(IReadOnlyDictionary environment) + { + var previous = s_environmentOverride.Value; + s_environmentOverride.Value = new DictionaryEnvironmentReader(environment); + return new EnvironmentOverrideScope(previous); + } + + internal interface IEnvironmentReader + { + string? GetEnvironmentVariable(string name); + } + + private sealed class ProcessEnvironmentReader : IEnvironmentReader + { + public static readonly ProcessEnvironmentReader Instance = new(); + + public string? GetEnvironmentVariable(string name) + { + return Environment.GetEnvironmentVariable(name); + } + } + + private sealed class DictionaryEnvironmentReader(IReadOnlyDictionary environment) : IEnvironmentReader + { + public string? GetEnvironmentVariable(string name) + { + return environment.TryGetValue(name, out var value) ? value : null; + } + } + + private sealed class EnvironmentOverrideScope(IEnvironmentReader? previous) : IDisposable + { + public void Dispose() + { + s_environmentOverride.Value = previous; + } + } +} diff --git a/tests/Aspire.Cli.Tests/Utils/NpmInstallDetectionTests.cs b/tests/Aspire.Cli.Tests/Utils/NpmInstallDetectionTests.cs new file mode 100644 index 00000000000..c0ebe865534 --- /dev/null +++ b/tests/Aspire.Cli.Tests/Utils/NpmInstallDetectionTests.cs @@ -0,0 +1,78 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using Aspire.Cli.Utils; + +namespace Aspire.Cli.Tests.Utils; + +public class NpmInstallDetectionTests +{ + [Fact] + public void IsRunningFromNpm_ReturnsTrueWhenPackageEnvironmentVariableMatches() + { + using var scope = NpmInstallDetection.UseEnvironmentForTesting(new Dictionary + { + [NpmInstallDetection.PackageEnvironmentVariableName] = NpmInstallDetection.ExpectedPackageName, + [NpmInstallDetection.PackageVersionEnvironmentVariableName] = "9.4.0", + [NpmInstallDetection.PackageRidEnvironmentVariableName] = "linux-x64", + }); + + Assert.True(NpmInstallDetection.IsRunningFromNpm()); + Assert.Equal( + $"npm install -g {NpmInstallDetection.ExpectedPackageName}@latest", + NpmInstallDetection.GetNpmUpdateCommand()); + Assert.Equal("9.4.0", NpmInstallDetection.GetNpmPackageVersion()); + Assert.Equal("linux-x64", NpmInstallDetection.GetNpmPackageRid()); + } + + [Theory] + [InlineData(null)] + [InlineData("")] + [InlineData(" ")] + [InlineData("@some-other-scope/aspire-cli")] + [InlineData("aspire-cli")] + [InlineData("@Microsoft/Aspire-Cli")] + public void IsRunningFromNpm_ReturnsFalseWhenPackageEnvironmentVariableMissingOrMismatched(string? packageName) + { + using var scope = NpmInstallDetection.UseEnvironmentForTesting(new Dictionary + { + [NpmInstallDetection.PackageEnvironmentVariableName] = packageName, + [NpmInstallDetection.PackageVersionEnvironmentVariableName] = "9.4.0", + [NpmInstallDetection.PackageRidEnvironmentVariableName] = "linux-x64", + }); + + Assert.False(NpmInstallDetection.IsRunningFromNpm()); + Assert.Null(NpmInstallDetection.GetNpmUpdateCommand()); + } + + [Fact] + public void GetNpmPackageVersion_ReturnsNullWhenVariableMissing() + { + using var scope = NpmInstallDetection.UseEnvironmentForTesting(new Dictionary + { + [NpmInstallDetection.PackageEnvironmentVariableName] = NpmInstallDetection.ExpectedPackageName, + }); + + Assert.Null(NpmInstallDetection.GetNpmPackageVersion()); + Assert.Null(NpmInstallDetection.GetNpmPackageRid()); + } + + [Fact] + public void UseEnvironmentForTesting_RestoresPreviousValueOnDispose() + { + // Establish a known baseline that does NOT match, so the test result is + // independent of whatever ASPIRE_NPM_PACKAGE the test host may inherit. + using var baseline = NpmInstallDetection.UseEnvironmentForTesting(new Dictionary()); + Assert.False(NpmInstallDetection.IsRunningFromNpm()); + + using (NpmInstallDetection.UseEnvironmentForTesting(new Dictionary + { + [NpmInstallDetection.PackageEnvironmentVariableName] = NpmInstallDetection.ExpectedPackageName, + })) + { + Assert.True(NpmInstallDetection.IsRunningFromNpm()); + } + + Assert.False(NpmInstallDetection.IsRunningFromNpm()); + } +} From debf4ebf38c0038cbc8d3cbc5285cd02c8ebf255 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Thu, 28 May 2026 16:15:02 -0400 Subject: [PATCH 10/35] Harden npm prepare/publish validation against partial-failure leakage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two adversarial-review findings from local repro of the install-test: 1) prepare-npm-cli-packages: initialize NpmCheck* task variables to 'failed' at the start of the install-test step. If a subsequent bash command exits via 'set -e' before the matching pass marker runs, the summary JSON now records 'failed' instead of an unexpanded '$(NpmCheckXxx)' AzDO token. The release-side gate already rejects anything that is not 'passed', but 'failed' is a much higher-signal diagnostic. 2) prepare-npm-cli-packages: tighten 'aspire --version' parsing. Use a semver-shaped regex against the full output and print the raw output for diagnostics, instead of blindly trusting 'tail -n 1'. System.CommandLine's VersionOption normally just prints the version and exits, but defending against a stray warn/info line makes failures self-explanatory. 3) release-publish-nuget: defense-in-depth — the gate now explicitly rejects status values that still look like an unexpanded '$(SomeVar)' token, in addition to the '!= passed' check. This catches future schema drift in the prepare template too. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- eng/pipelines/release-publish-nuget.yml | 16 ++++++++++++-- .../templates/prepare-npm-cli-packages.yml | 22 ++++++++++++++++--- 2 files changed, 33 insertions(+), 5 deletions(-) diff --git a/eng/pipelines/release-publish-nuget.yml b/eng/pipelines/release-publish-nuget.yml index f5c05e5c1ae..4fd604dc05d 100644 --- a/eng/pipelines/release-publish-nuget.yml +++ b/eng/pipelines/release-publish-nuget.yml @@ -613,8 +613,20 @@ extends: exit 1 } - if ("$($check.status)" -ne 'passed') { - Write-Error "npm validation check '$checkName' did not pass (status='$($check.status)')." + $status = "$($check.status)" + + # AzDO does not error on referencing an unset task.setvariable; the + # variable expansion produces the literal '$(VarName)' token. The + # prepare template initializes every NpmCheck* var to 'failed' to + # prevent this, but defend against schema drift by rejecting any + # status that still looks like an unexpanded variable. + if ($status -like '$(*)') { + Write-Error "npm validation check '$checkName' has unexpanded status token '$status'. This indicates the prepare-stage script aborted before recording a real result." + exit 1 + } + + if ($status -ne 'passed') { + Write-Error "npm validation check '$checkName' did not pass (status='$status')." exit 1 } } diff --git a/eng/pipelines/templates/prepare-npm-cli-packages.yml b/eng/pipelines/templates/prepare-npm-cli-packages.yml index a105690d7bb..350dc14d2ee 100644 --- a/eng/pipelines/templates/prepare-npm-cli-packages.yml +++ b/eng/pipelines/templates/prepare-npm-cli-packages.yml @@ -93,6 +93,17 @@ steps: echo "RID package: $ridTarball" echo "##vso[task.setvariable variable=NpmPointerTarball]$pointer" echo "##vso[task.setvariable variable=NpmRidTarball]$ridTarball" + + # Initialize every check status to 'failed' up front. If any subsequent + # step exits via 'set -e' before flipping one of these to 'passed', the + # summary written by the final step still reflects the real outcome + # instead of a literal '$(NpmCheckXxx)' AzDO variable expansion (which + # the release-side gate would still reject, but the diagnostic value + # of 'failed' is much higher). + echo "##vso[task.setvariable variable=NpmCheckInstall]failed" + echo "##vso[task.setvariable variable=NpmCheckVersion]failed" + echo "##vso[task.setvariable variable=NpmCheckLauncher]failed" + echo "##vso[task.setvariable variable=NpmCheckUninstall]failed" displayName: 🟣Locate pointer and RID tarballs - bash: | @@ -143,10 +154,15 @@ steps: # Capture the launcher's reported version. The CLI is set to skip its first-run # update check in CI via DOTNET_CLI_TELEMETRY_OPTOUT and friends; here we just - # need a clean --version line. - actualVersion="$(aspire --version 2>&1 | tail -n 1 | tr -d '[:space:]')" + # need a clean version line. Match the first line that looks like a semver-ish + # token so we are not thrown off by an incidental warn/info line printed before + # or after the version (System.CommandLine's VersionOption normally just prints + # the version and exits, but be defensive). + versionOutput="$(aspire --version 2>&1)" + actualVersion="$(printf '%s\n' "$versionOutput" | grep -Eo '^[0-9]+\.[0-9]+\.[0-9]+([.-][A-Za-z0-9._-]+)?$' | head -n 1 || true)" + echo " Raw output: $versionOutput" echo " Reported version: $actualVersion" - if [ "$actualVersion" != "$expectedVersion" ]; then + if [ -z "$actualVersion" ] || [ "$actualVersion" != "$expectedVersion" ]; then echo "##[error]aspire --version reported '$actualVersion' but expected '$expectedVersion'" exit 1 fi From 557e6f914bbd0eb15ca9658aa709cb3d2cf523e0 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Thu, 28 May 2026 18:23:24 -0400 Subject: [PATCH 11/35] Fix npm package release validation Block prerelease npm publishes until non-latest dist-tags are supported, validate npm install summaries across Windows/Linux/macOS, and make launcher cache replacement avoid deleting the previous executable before rename. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/release-process.md | 6 +- docs/specs/npm-cli-package.md | 14 +- eng/clipack/npm/aspire.js | 8 +- eng/pipelines/azure-pipelines.yml | 78 ++++++++- eng/pipelines/release-publish-nuget.yml | 154 +++++++++++++----- .../templates/prepare-npm-cli-packages.yml | 48 ++++-- 6 files changed, 240 insertions(+), 68 deletions(-) diff --git a/docs/release-process.md b/docs/release-process.md index f2691420d5a..be9abc7bb5f 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -45,7 +45,7 @@ Before starting a release: - Select this build from the `aspire-build` resource dropdown when running the release pipeline. - The build should have a `BAR ID - NNNNNN` tag, which the pipeline extracts automatically. - The build should also have a `release-version - X.Y.Z` tag, which the pipeline uses when `ReleaseVersion` is left as `auto`. - - The build must include native CLI NuGet packages and `microsoft-aspire-cli*.tgz` npm tarballs from the native archive jobs. + - The build must include native CLI NuGet packages, `microsoft-aspire-cli*.tgz` npm tarballs from the native archive jobs, and the Windows, Linux, and macOS npm install validation summaries. 2. **Release branch**: Ensure the release branch exists, for example `release/9.2`. 3. **Permissions and approvals**: - Access to run Azure DevOps pipelines with the publishing pool. @@ -72,7 +72,7 @@ Before starting a release: | Parameter | Description | Example | |-----------|-------------|---------| | `ReleaseVersion` | Override for the version label (used as `v` tag). Leave as `auto` to derive from the source build's `release-version - *` tag, which is the normal case. Only set this when re-shipping under a corrected tag. | `auto` | - | `IsPrerelease` | `true` for preview releases. | `false` | + | `IsPrerelease` | `true` for preview releases. Non-dry-run npm publishing is blocked for prereleases until the MicroBuild npm publish path supports non-`latest` dist-tags. | `false` | | `DryRun` | Set `true` to test without publishing, promoting, tagging, or creating PRs. | `false` | | `GaChannelName` | Target GA channel. | `Aspire 9.x GA` | @@ -99,7 +99,7 @@ Before starting a release: 5. Click **Run** and monitor the pipeline. The final stage (`GitHubTasks`) dispatches `release-github-tasks.yml`, waits for it to complete, uploads the `aspire-cli-*` archives from the source build's `BlobArtifacts` onto the newly-created GitHub release, and validates the Homebrew cask against that live release. The AzDO pipeline only succeeds if the enabled GitHub tasks, asset upload, and Homebrew validation succeed. 6. Verify packages appear on NuGet.org and npm, and verify that the `aspire-cli-*` archives are attached to the GitHub release. -The npm release path publishes the seven RID packages first, waits for ESRP completion, waits for the configured propagation delay, and then publishes the top-level `@microsoft/aspire-cli` pointer package. This avoids installing a pointer package whose optional RID dependencies are not visible yet. +The npm release path validates Windows, Linux, and macOS install summaries, publishes the seven RID packages first, waits for ESRP completion, waits for the configured propagation delay, and then publishes the top-level `@microsoft/aspire-cli` pointer package. This avoids installing a pointer package whose optional RID dependencies are not visible yet. For prereleases, set `SkipNpmPublish=true` unless the npm publishing path has gained explicit non-`latest` dist-tag support. `commit_sha` and `release_branch` for the GitHub workflow are derived automatically from the source build resource, so there is no need to copy them by hand. diff --git a/docs/specs/npm-cli-package.md b/docs/specs/npm-cli-package.md index b7778a27373..6521717e8ea 100644 --- a/docs/specs/npm-cli-package.md +++ b/docs/specs/npm-cli-package.md @@ -129,7 +129,7 @@ ASPIRE_NPM_PACKAGE_VERSION ASPIRE_NPM_PACKAGE_RID ``` -The launcher's cache-freshness check compares both file size and `mtime`. A cached binary is reused only when its size matches the source and its `mtime` is greater than or equal to the source binary's `mtime`. Any other state (different size, older `mtime`, or unreadable cache target) triggers an atomic re-copy through a temp file. +The launcher's cache-freshness check compares both file size and `mtime`. A cached binary is reused only when its size matches the source and its `mtime` is greater than or equal to the source binary's `mtime`. Any other state (different size, older `mtime`, or unreadable cache target) copies the source through a temp file and atomically renames the temp file over the cache target. ## Build integration @@ -157,12 +157,12 @@ The launcher's cache-freshness check compares both file size and `mtime`. A cach 5. Comparing the RID tarball binary byte-for-byte with the archive binary. 6. Verifying pointer package metadata, `bin/aspire.js`, `aspire-package-map.json`, and optional dependency version alignment. -`eng/pipelines/templates/prepare-npm-cli-packages.yml` runs after the byte-for-byte verification and performs a real end-to-end installation test: +`eng/pipelines/templates/prepare-npm-cli-packages.yml` runs after the byte-for-byte verification and performs real end-to-end installation tests on Windows, Linux, and the native macOS build-pool RID: 1. Installs the just-built pointer and matching RID tarball into a scratch npm prefix (`npm install -g`). 2. Invokes the installed `aspire --version` and asserts the version matches the build version. 3. Confirms the launcher's runtime cache landed under the expected `~/.aspire/npm///bin` layout. -4. Emits `validation-summary.json` listing each check's status. The release pipeline refuses to submit the npm packages to ESRP without a successful summary, mirroring the brew cask flow. +4. Emits a `validation-summary.json` for each platform listing each check's status. The release pipeline refuses to submit the npm packages to ESRP without successful Windows, Linux, and macOS summaries, mirroring the brew cask flow. `eng\scripts\stage-native-cli-tool-packages.ps1` stages npm `.tgz` artifacts alongside existing native CLI nupkgs. Official CI invokes the script with `-RequireNpmPackages`, so source builds fail before release if the npm tarballs are missing. The default remains warning-only for local or older nupkg-only flows that call the script directly. @@ -172,7 +172,7 @@ Only one pointer package is staged. The default canonical pointer source is `nat The native archive workflows verify npm tarballs after the existing nupkg verification and then run the end-to-end install test above. -Azure Pipelines installs Node.js before native package build because `npm pack` runs during packaging, verifies the npm packages, downloads `microsoft-aspire-cli*.tgz` in the staging job, and stages them with the native CLI packages. The source build then publishes the npm `.tgz` files as shipping flat blob artifacts so the release pipeline can consume them without treating npm tarballs as NuGet-like BAR package assets. The install-test job also publishes a `validation-summary.json` artifact (`NpmValidationSummary`) the release pipeline requires before publishing. +Azure Pipelines installs Node.js before native package build because `npm pack` runs during packaging, verifies the npm packages, downloads `microsoft-aspire-cli*.tgz` in the staging job, and stages them with the native CLI packages. The source build then publishes the npm `.tgz` files as shipping flat blob artifacts so the release pipeline can consume them without treating npm tarballs as NuGet-like BAR package assets. The install-test jobs also publish platform-specific validation summary artifacts that the release pipeline aggregates into `NpmValidationSummary` and requires before publishing. ## Publishing @@ -182,13 +182,13 @@ The release pipeline prepares two npm artifact folders and one validation artifa 1. `NpmRidPackageArtifacts` contains the seven RID packages. 2. `NpmPointerPackageArtifacts` contains the top-level `@microsoft/aspire-cli` pointer package. -3. `NpmValidationSummary` contains the `validation-summary.json` emitted by the source-build install test. The release pipeline reads this summary and refuses to invoke `MicroBuild.Publish` unless every required check passed. +3. `NpmValidationSummary` contains the platform `validation-summary.json` files emitted by the source-build install tests. The release pipeline reads these summaries and refuses to invoke `MicroBuild.Publish` unless every required check passed on Windows, Linux, and macOS. The package split is intentional. The release job submits RID packages first, waits for the ESRP submission to complete, waits an additional npm registry propagation delay, and then submits the pointer package. Publishing the pointer package last avoids optional dependency resolution races when a user installs the top-level package immediately after release. -Before publishing, the release pipeline validates that exactly one pointer tarball and exactly one tarball for each supported RID are present, that all tarballs have one version, and that the `NpmValidationSummary` artifact reports `validatedByPreparePipeline: true` with every required check `passed`. Non-dry-run npm publishing also requires release managers to provide `NpmPublishOwners` and `NpmPublishApprovers`, which are passed to ESRP. Re-runs can use `SkipNpmRidPublish` if the RID packages published but the pointer package did not, and `SkipNpmPublish` after npm publishing has completed. +Before publishing, the release pipeline validates that exactly one pointer tarball and exactly one tarball for each supported RID are present, that all tarballs have one version, and that the `NpmValidationSummary` artifact reports `validatedByPreparePipeline: true` with every required check `passed` for Windows, Linux, and macOS install validation. Non-dry-run npm publishing also requires release managers to provide `NpmPublishOwners` and `NpmPublishApprovers`, which are passed to ESRP. Re-runs can use `SkipNpmRidPublish` if the RID packages published but the pointer package did not, and `SkipNpmPublish` after npm publishing has completed. -MicroBuild's npm publish template documentation does not currently expose an npm `dist-tag` parameter. Initial publishing therefore relies on the registry's default tag behavior; preview or side-channel tagging needs ESRP/MicroBuild support before it can be enabled safely. +MicroBuild's npm publish template documentation does not currently expose an npm `dist-tag` parameter. Non-dry-run prerelease npm publishing is blocked until preview packages can be submitted under a non-`latest` tag; release managers can still use `DryRun=true` to inspect the npm publish set without submitting packages. ## Product and security tradeoffs diff --git a/eng/clipack/npm/aspire.js b/eng/clipack/npm/aspire.js index 58c4c68a358..7e7382c151a 100644 --- a/eng/clipack/npm/aspire.js +++ b/eng/clipack/npm/aspire.js @@ -95,8 +95,8 @@ function ensureCachedBinary(sourcePath, binaryName, version, rid) { return targetPath; } - // Copy through a temp file so concurrent first runs never observe a partial - // executable at the final path. + // Copy through a temp file and atomically rename it over the previous cache + // entry so concurrent first runs never observe a missing or partial executable. const tempPath = path.join(targetDirectory, `${binaryName}.${process.pid}.${Date.now()}.tmp`); fs.copyFileSync(sourcePath, tempPath); @@ -104,8 +104,10 @@ function ensureCachedBinary(sourcePath, binaryName, version, rid) { fs.chmodSync(tempPath, 0o755); } + // Node's rename uses replace-existing semantics on all supported platforms. + // If the cached executable is still running on Windows, the rename fails and + // the previous cache entry remains usable instead of being deleted first. try { - fs.rmSync(targetPath, { force: true }); fs.renameSync(tempPath, targetPath); } catch (error) { fs.rmSync(tempPath, { force: true }); diff --git a/eng/pipelines/azure-pipelines.yml b/eng/pipelines/azure-pipelines.yml index f76138ecdca..93d7d5a0790 100644 --- a/eng/pipelines/azure-pipelines.yml +++ b/eng/pipelines/azure-pipelines.yml @@ -530,8 +530,39 @@ extends: channel: $(installerChannel) archiveRoot: $(Pipeline.Workspace)/native-archives - - job: NpmInstall - displayName: npm install validation + - job: NpmInstall_Windows_x64 + displayName: npm install validation (win-x64) + timeoutInMinutes: 30 + pool: + name: NetCore1ESPool-Internal + image: 1es-windows-2022 + os: windows + steps: + - checkout: self + fetchDepth: 1 + # Download the just-built npm tarballs the build stage published as + # blob artifacts via stage-native-cli-tool-packages.ps1. Filter to + # avoid pulling unrelated blob assets. + - task: DownloadPipelineArtifact@2 + displayName: 🟣Download npm packages from build + inputs: + artifact: BlobArtifacts + itemPattern: '**/microsoft-aspire-cli*.tgz' + targetPath: '$(Pipeline.Workspace)/npm-packages' + - task: NodeTool@0 + displayName: 🟣Install Node.js + inputs: + versionSpec: '20.x' + - template: /eng/pipelines/templates/prepare-npm-cli-packages.yml@self + parameters: + npmPackagesDir: $(Pipeline.Workspace)/npm-packages + expectedVersion: $(aspireVersion) + rid: win-x64 + validationSummaryArtifactName: npm-validation-summary-win-x64 + skipRegistryResolution: true + + - job: NpmInstall_Linux_x64 + displayName: npm install validation (linux-x64) timeoutInMinutes: 30 pool: name: NetCore1ESPool-Internal @@ -558,4 +589,47 @@ extends: npmPackagesDir: $(Pipeline.Workspace)/npm-packages expectedVersion: $(aspireVersion) rid: linux-x64 + validationSummaryArtifactName: npm-validation-summary-linux-x64 + skipRegistryResolution: true + + - job: NpmInstall_macOS + displayName: npm install validation (macOS native RID) + timeoutInMinutes: 30 + pool: + name: Azure Pipelines + vmImage: macOS-latest-internal + os: macOS + steps: + - checkout: self + fetchDepth: 1 + - pwsh: | + $ErrorActionPreference = 'Stop' + $rid = switch ('$(Agent.OSArchitecture)') { + 'ARM64' { 'osx-arm64' } + 'X64' { 'osx-x64' } + default { throw "Unsupported macOS agent architecture '$(Agent.OSArchitecture)'." } + } + + Write-Host "Resolved macOS npm validation RID: $rid" + Write-Host "##vso[task.setvariable variable=NpmValidationRid]$rid" + displayName: 🟣Resolve native macOS RID + # Download the just-built npm tarballs the build stage published as + # blob artifacts via stage-native-cli-tool-packages.ps1. Filter to + # avoid pulling unrelated blob assets. + - task: DownloadPipelineArtifact@2 + displayName: 🟣Download npm packages from build + inputs: + artifact: BlobArtifacts + itemPattern: '**/microsoft-aspire-cli*.tgz' + targetPath: '$(Pipeline.Workspace)/npm-packages' + - task: NodeTool@0 + displayName: 🟣Install Node.js + inputs: + versionSpec: '20.x' + - template: /eng/pipelines/templates/prepare-npm-cli-packages.yml@self + parameters: + npmPackagesDir: $(Pipeline.Workspace)/npm-packages + expectedVersion: $(aspireVersion) + rid: $(NpmValidationRid) + validationSummaryArtifactName: npm-validation-summary-osx skipRegistryResolution: true diff --git a/eng/pipelines/release-publish-nuget.yml b/eng/pipelines/release-publish-nuget.yml index 97dad96f6a6..812236f51d0 100644 --- a/eng/pipelines/release-publish-nuget.yml +++ b/eng/pipelines/release-publish-nuget.yml @@ -316,8 +316,16 @@ extends: patterns: '**/microsoft-aspire-cli*.tgz' - download: aspire-build - displayName: 'Download npm validation summary from Source Build' - artifact: npm-validation-summary + displayName: 'Download npm validation summary from Source Build (win-x64)' + artifact: npm-validation-summary-win-x64 + + - download: aspire-build + displayName: 'Download npm validation summary from Source Build (linux-x64)' + artifact: npm-validation-summary-linux-x64 + + - download: aspire-build + displayName: 'Download npm validation summary from Source Build (macOS)' + artifact: npm-validation-summary-osx - ${{ if eq(parameters.SkipWinGetPublish, false) }}: - download: aspire-build @@ -461,16 +469,29 @@ extends: } Copy-Item $pointerPackages[0].FullName -Destination $pointerTargetPath -Force - # Copy the install-test validation summary into its own output folder. - # Stage 2 re-validates this summary before submitting to ESRP/MicroBuild. - $summarySource = "$(Pipeline.Workspace)/aspire-build/npm-validation-summary/validation-summary.json" $summaryTarget = "$(Pipeline.Workspace)/npm/validation-summary" New-Item -ItemType Directory -Path $summaryTarget -Force | Out-Null - if (!(Test-Path $summarySource)) { - Write-Error "npm validation summary was not downloaded from the source build at '$summarySource'. The source build's npm install-test job must have failed or did not run." - exit 1 + + # Copy each install-test validation summary into its own folder. + # Stage 2 re-validates every summary before submitting to ESRP/MicroBuild. + $validationSummaries = @( + @{ Name = 'win-x64'; Artifact = 'npm-validation-summary-win-x64' }, + @{ Name = 'linux-x64'; Artifact = 'npm-validation-summary-linux-x64' }, + @{ Name = 'osx'; Artifact = 'npm-validation-summary-osx' } + ) + + foreach ($validationSummary in $validationSummaries) { + $summarySource = "$(Pipeline.Workspace)/aspire-build/$($validationSummary.Artifact)/validation-summary.json" + $summaryOutputDirectory = Join-Path $summaryTarget $validationSummary.Name + New-Item -ItemType Directory -Path $summaryOutputDirectory -Force | Out-Null + + if (!(Test-Path $summarySource)) { + Write-Error "npm validation summary was not downloaded from the source build at '$summarySource'. The source build's npm install-test job for '$($validationSummary.Name)' must have failed or did not run." + exit 1 + } + + Copy-Item $summarySource -Destination (Join-Path $summaryOutputDirectory 'validation-summary.json') -Force } - Copy-Item $summarySource -Destination (Join-Path $summaryTarget 'validation-summary.json') -Force Write-Host "Prepared $($ridPackages.Count) RID npm package(s) and pointer package version $($versions[0])." displayName: 'Prepare npm Artifacts for Publishing' @@ -480,6 +501,9 @@ extends: New-Item -ItemType Directory -Path "$(Pipeline.Workspace)/npm/rid-packages" -Force | Out-Null New-Item -ItemType Directory -Path "$(Pipeline.Workspace)/npm/pointer-package" -Force | Out-Null New-Item -ItemType Directory -Path "$(Pipeline.Workspace)/npm/validation-summary" -Force | Out-Null + New-Item -ItemType Directory -Path "$(Pipeline.Workspace)/npm/validation-summary/win-x64" -Force | Out-Null + New-Item -ItemType Directory -Path "$(Pipeline.Workspace)/npm/validation-summary/linux-x64" -Force | Out-Null + New-Item -ItemType Directory -Path "$(Pipeline.Workspace)/npm/validation-summary/osx" -Force | Out-Null Write-Host "Created empty npm artifact placeholders because SkipNpmPublish=true." displayName: 'Prepare Empty npm Artifact Placeholders' @@ -566,6 +590,7 @@ extends: Write-Host "Source Build Name: $(resources.pipeline.aspire-build.runName)" Write-Host "Source Build URI: $(resources.pipeline.aspire-build.runURI)" Write-Host "GA Channel: ${{ parameters.GaChannelName }}" + Write-Host "Is Prerelease: ${{ parameters.IsPrerelease }}" Write-Host "Dry Run: ${{ parameters.DryRun }}" Write-Host "Skip NuGet Publish: ${{ parameters.SkipNuGetPublish }}" Write-Host "Skip npm Publish: ${{ parameters.SkipNpmPublish }}" @@ -740,54 +765,88 @@ extends: - ${{ if eq(parameters.SkipNpmPublish, false) }}: - powershell: | $ErrorActionPreference = 'Stop' - $summaryPath = "$(Pipeline.Workspace)/npm/validation-summary/validation-summary.json" + $validationRoot = "$(Pipeline.Workspace)/npm/validation-summary" + # The source build validates the macOS package on the build pool's native architecture. + # Accept either RID here while still requiring a macOS install test to have run. + $validationSummaries = @( + @{ Name = 'win-x64'; ExpectedRids = @('win-x64') }, + @{ Name = 'linux-x64'; ExpectedRids = @('linux-x64') }, + @{ Name = 'osx'; ExpectedRids = @('osx-x64', 'osx-arm64') } + ) + $requiredChecks = @('install', 'version', 'launcher', 'uninstall') + $validatedRids = [System.Collections.Generic.List[string]]::new() + $expectedVersion = $null - if (!(Test-Path $summaryPath)) { - Write-Error "npm validation summary not found: $summaryPath. Refusing to publish without verified prepare-stage validation." - exit 1 - } + foreach ($validationSummary in $validationSummaries) { + $summaryPath = Join-Path $validationRoot "$($validationSummary.Name)/validation-summary.json" - try { - $summary = Get-Content -Raw $summaryPath | ConvertFrom-Json - } - catch { - Write-Error "npm validation summary is invalid JSON: $summaryPath" - throw - } + if (!(Test-Path $summaryPath)) { + Write-Error "npm validation summary not found: $summaryPath. Refusing to publish without verified prepare-stage validation for '$($validationSummary.Name)'." + exit 1 + } - if (-not $summary.validatedByPreparePipeline) { - Write-Error "npm validation summary does not indicate successful prepare-stage validation." - exit 1 - } + try { + $summary = Get-Content -Raw $summaryPath | ConvertFrom-Json + } + catch { + Write-Error "npm validation summary is invalid JSON: $summaryPath" + throw + } - $requiredChecks = @('install', 'version', 'launcher', 'uninstall') - foreach ($checkName in $requiredChecks) { - $check = $summary.checks.$checkName - if ($null -eq $check) { - Write-Error "npm validation summary is missing required check '$checkName'." + if (-not $summary.validatedByPreparePipeline) { + Write-Error "npm validation summary '$summaryPath' does not indicate successful prepare-stage validation." exit 1 } - $status = "$($check.status)" + $summaryRid = "$($summary.rid)" + if ($validationSummary.ExpectedRids -notcontains $summaryRid) { + Write-Error "npm validation summary '$summaryPath' reported RID '$summaryRid', expected one of: $($validationSummary.ExpectedRids -join ', ')." + exit 1 + } - # AzDO does not error on referencing an unset task.setvariable; the - # variable expansion produces the literal '$(VarName)' token. The - # prepare template initializes every NpmCheck* var to 'failed' to - # prevent this, but defend against schema drift by rejecting any - # status that still looks like an unexpanded variable. - if ($status -like '$(*)') { - Write-Error "npm validation check '$checkName' has unexpanded status token '$status'. This indicates the prepare-stage script aborted before recording a real result." + $summaryVersion = "$($summary.expectedVersion)" + if ([string]::IsNullOrWhiteSpace($summaryVersion)) { + Write-Error "npm validation summary '$summaryPath' did not report an expectedVersion." exit 1 } - if ($status -ne 'passed') { - Write-Error "npm validation check '$checkName' did not pass (status='$status')." + if ($null -eq $expectedVersion) { + $expectedVersion = $summaryVersion + } elseif ($summaryVersion -ne $expectedVersion) { + Write-Error "npm validation summaries disagree on expectedVersion. '$summaryPath' reported '$summaryVersion', but earlier summaries reported '$expectedVersion'." exit 1 } + + foreach ($checkName in $requiredChecks) { + $check = $summary.checks.$checkName + if ($null -eq $check) { + Write-Error "npm validation summary '$summaryPath' is missing required check '$checkName'." + exit 1 + } + + $status = "$($check.status)" + + # AzDO does not error on referencing an unset task.setvariable; the + # variable expansion produces the literal '$(VarName)' token. The + # prepare template initializes every NpmCheck* var to 'failed' to + # prevent this, but defend against schema drift by rejecting any + # status that still looks like an unexpanded variable. + if ($status -like '$(*)') { + Write-Error "npm validation check '$checkName' in '$summaryPath' has unexpanded status token '$status'. This indicates the prepare-stage script aborted before recording a real result." + exit 1 + } + + if ($status -ne 'passed') { + Write-Error "npm validation check '$checkName' in '$summaryPath' did not pass (status='$status')." + exit 1 + } + } + + $validatedRids.Add($summaryRid) } - Write-Host "npm validation summary verified ($($summary.rid), version $($summary.expectedVersion))." - displayName: 'Validate npm Prepare-Stage Summary' + Write-Host "npm validation summaries verified ($($validatedRids -join ', '), version $expectedVersion)." + displayName: 'Validate npm Prepare-Stage Summaries' - powershell: | $ridPackagesPath = "$(Pipeline.Workspace)/npm/rid-packages" @@ -841,7 +900,13 @@ extends: Write-Host "=== DRY RUN - No npm packages were actually published ===" displayName: 'Dry Run - List npm Packages (No Publish)' - - ${{ if and(eq(parameters.DryRun, false), eq(parameters.SkipNpmPublish, false)) }}: + - ${{ if and(eq(parameters.DryRun, false), eq(parameters.SkipNpmPublish, false), eq(parameters.IsPrerelease, true)) }}: + - powershell: | + Write-Error "npm publishing is blocked for prerelease runs because the MicroBuild npm publish template does not yet expose a dist-tag parameter. Set SkipNpmPublish=true or run with DryRun=true until prereleases can publish under a non-latest tag." + exit 1 + displayName: 'Block npm Publish for Prerelease' + + - ${{ if and(eq(parameters.DryRun, false), eq(parameters.SkipNpmPublish, false), eq(parameters.IsPrerelease, false)) }}: - powershell: | $owners = "${{ parameters.NpmPublishOwners }}" $approvers = "${{ parameters.NpmPublishApprovers }}" @@ -981,6 +1046,7 @@ extends: Write-Host "║ BAR Build ID: $(BarBuildId)" } Write-Host "║ GA Channel: ${{ parameters.GaChannelName }}" + Write-Host "║ Prerelease: ${{ parameters.IsPrerelease }}" Write-Host "║ Dry Run: ${{ parameters.DryRun }}" Write-Host "╠═══════════════════════════════════════════════════════════════╣" Write-Host "║ NuGet Publish: ${{ parameters.SkipNuGetPublish }}" -NoNewline @@ -994,6 +1060,8 @@ extends: Write-Host " (SKIPPED)" } elseif ("${{ parameters.DryRun }}" -eq "true") { Write-Host " (DRY RUN)" + } elseif ("${{ parameters.IsPrerelease }}" -eq "true") { + Write-Host " (BLOCKED - prerelease requires non-latest npm dist-tag support)" } else { Write-Host " (EXECUTED)" } diff --git a/eng/pipelines/templates/prepare-npm-cli-packages.yml b/eng/pipelines/templates/prepare-npm-cli-packages.yml index 350dc14d2ee..f57ad76aba3 100644 --- a/eng/pipelines/templates/prepare-npm-cli-packages.yml +++ b/eng/pipelines/templates/prepare-npm-cli-packages.yml @@ -8,6 +8,9 @@ parameters: - name: rid type: string default: 'linux-x64' + - name: validationSummaryArtifactName + type: string + default: 'npm-validation-summary' # When true, the install test is allowed to run against just-built tarballs # without contacting the npm registry. PR builds set this to true; release # validation builds also set this to true. The variable exists so future @@ -19,7 +22,16 @@ parameters: steps: - bash: | set -euo pipefail - packagesDir='${{ parameters.npmPackagesDir }}' + to_unix_path() { + local value="$1" + if command -v cygpath >/dev/null 2>&1 && [[ "$value" =~ ^[A-Za-z]:\\ ]]; then + cygpath -u "$value" + else + printf '%s\n' "$value" + fi + } + + packagesDir="$(to_unix_path '${{ parameters.npmPackagesDir }}')" expectedVersion='${{ parameters.expectedVersion }}' rid='${{ parameters.rid }}' @@ -115,9 +127,14 @@ steps: # Use a scratch npm prefix so the test never mutates the agent's # global node_modules and so cleanup is a single rm -rf. - prefix="$(Build.StagingDirectory)/npm-validate-prefix" - cache="$(Build.StagingDirectory)/npm-validate-cache" - aspireCache="$(Build.StagingDirectory)/npm-validate-aspire-cache" + stagingDirectory="$(Build.StagingDirectory)" + if command -v cygpath >/dev/null 2>&1 && [[ "$stagingDirectory" =~ ^[A-Za-z]:\\ ]]; then + stagingDirectory="$(cygpath -u "$stagingDirectory")" + fi + + prefix="$stagingDirectory/npm-validate-prefix" + cache="$stagingDirectory/npm-validate-cache" + aspireCache="$stagingDirectory/npm-validate-aspire-cache" rm -rf "$prefix" "$cache" "$aspireCache" mkdir -p "$prefix" "$cache" "$aspireCache" @@ -125,7 +142,8 @@ steps: export NPM_CONFIG_CACHE="$cache" export ASPIRE_NPM_CACHE_DIR="$aspireCache" # Prefer the freshly-built launcher's PATH; do not poison existing aspire binaries. - export PATH="$prefix/bin:$PATH" + # npm writes POSIX shims to /bin and Windows shims to . + export PATH="$prefix/bin:$prefix:$PATH" if command -v aspire >/dev/null 2>&1; then echo "##[error]aspire is already on PATH before install ($(command -v aspire)) — test environment is not clean" @@ -167,8 +185,13 @@ steps: exit 1 fi - # The launcher copies the native binary into $ASPIRE_NPM_CACHE_DIR///bin/aspire. - cachedBinary="$aspireCache/$expectedVersion/$rid/bin/aspire" + # The launcher copies the native binary into $ASPIRE_NPM_CACHE_DIR///bin/. + binaryName="aspire" + if [[ "$rid" == win-* ]]; then + binaryName="aspire.exe" + fi + + cachedBinary="$aspireCache/$expectedVersion/$rid/bin/$binaryName" if [ ! -f "$cachedBinary" ]; then echo "##[error]Expected cached binary at $cachedBinary was not created by the launcher" find "$aspireCache" -maxdepth 6 -type f || true @@ -200,7 +223,12 @@ steps: - bash: | set -euo pipefail - outputDir="$(Build.StagingDirectory)/npm-validation-summary" + stagingDirectory="$(Build.StagingDirectory)" + if command -v cygpath >/dev/null 2>&1 && [[ "$stagingDirectory" =~ ^[A-Za-z]:\\ ]]; then + stagingDirectory="$(cygpath -u "$stagingDirectory")" + fi + + outputDir="$stagingDirectory/npm-validation-summary" mkdir -p "$outputDir" outputPath="$outputDir/validation-summary.json" rid="$(NpmTestRid)" @@ -228,7 +256,7 @@ steps: }, "launcher": { "status": "$(NpmCheckLauncher)", - "details": "Launcher cached native binary at ASPIRE_NPM_CACHE_DIR///bin/aspire" + "details": "Launcher cached native binary at ASPIRE_NPM_CACHE_DIR///bin/" }, "uninstall": { "status": "$(NpmCheckUninstall)", @@ -248,4 +276,4 @@ steps: condition: always() inputs: PathtoPublish: '$(Build.StagingDirectory)/npm-validation-summary' - ArtifactName: npm-validation-summary + ArtifactName: ${{ parameters.validationSummaryArtifactName }} From 71b26f05427a0c495766260b124b870f5cfb8a2d Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Thu, 28 May 2026 18:24:39 -0400 Subject: [PATCH 12/35] Update CI Node version to 22 Use Node 22 for native CLI npm packaging and install-validation CI paths. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/build-cli-native-archives.yml | 2 +- eng/pipelines/azure-pipelines.yml | 6 +++--- eng/pipelines/templates/build_sign_native.yml | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/build-cli-native-archives.yml b/.github/workflows/build-cli-native-archives.yml index d4e74ef7608..e44973766e2 100644 --- a/.github/workflows/build-cli-native-archives.yml +++ b/.github/workflows/build-cli-native-archives.yml @@ -61,7 +61,7 @@ jobs: - name: Install node.js uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0 with: - node-version: 20.x + node-version: 22.x # Build RID-specific NuGet packages (DCP + Dashboard) locally instead of # downloading them from the build_packages job. This allows the CLI archive diff --git a/eng/pipelines/azure-pipelines.yml b/eng/pipelines/azure-pipelines.yml index 93d7d5a0790..6389b6d547c 100644 --- a/eng/pipelines/azure-pipelines.yml +++ b/eng/pipelines/azure-pipelines.yml @@ -552,7 +552,7 @@ extends: - task: NodeTool@0 displayName: 🟣Install Node.js inputs: - versionSpec: '20.x' + versionSpec: '22.x' - template: /eng/pipelines/templates/prepare-npm-cli-packages.yml@self parameters: npmPackagesDir: $(Pipeline.Workspace)/npm-packages @@ -583,7 +583,7 @@ extends: - task: NodeTool@0 displayName: 🟣Install Node.js inputs: - versionSpec: '20.x' + versionSpec: '22.x' - template: /eng/pipelines/templates/prepare-npm-cli-packages.yml@self parameters: npmPackagesDir: $(Pipeline.Workspace)/npm-packages @@ -625,7 +625,7 @@ extends: - task: NodeTool@0 displayName: 🟣Install Node.js inputs: - versionSpec: '20.x' + versionSpec: '22.x' - template: /eng/pipelines/templates/prepare-npm-cli-packages.yml@self parameters: npmPackagesDir: $(Pipeline.Workspace)/npm-packages diff --git a/eng/pipelines/templates/build_sign_native.yml b/eng/pipelines/templates/build_sign_native.yml index 1dd731a475b..e06831ab7d6 100644 --- a/eng/pipelines/templates/build_sign_native.yml +++ b/eng/pipelines/templates/build_sign_native.yml @@ -172,7 +172,7 @@ jobs: - task: NodeTool@0 displayName: 🟣Install node.js inputs: - versionSpec: '20.x' + versionSpec: '22.x' - script: >- $(Build.SourcesDirectory)/$(dotnetScript) From e6bef396a9fc85feaae2334a32d00b4badbfe5ca Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Thu, 28 May 2026 23:51:14 -0400 Subject: [PATCH 13/35] Add npm package signing coverage Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/release-process.md | 4 +- docs/specs/npm-cli-package.md | 6 +- eng/Publishing.props | 7 +++ eng/Signing.props | 10 ++++ eng/pipelines/azure-pipelines.yml | 2 +- eng/pipelines/release-publish-nuget.yml | 76 +++++++++++++++++++++++- eng/pipelines/templates/BuildAndTest.yml | 35 +++++++++++ 7 files changed, 132 insertions(+), 8 deletions(-) diff --git a/docs/release-process.md b/docs/release-process.md index be9abc7bb5f..174b4f8185f 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -45,7 +45,7 @@ Before starting a release: - Select this build from the `aspire-build` resource dropdown when running the release pipeline. - The build should have a `BAR ID - NNNNNN` tag, which the pipeline extracts automatically. - The build should also have a `release-version - X.Y.Z` tag, which the pipeline uses when `ReleaseVersion` is left as `auto`. - - The build must include native CLI NuGet packages, `microsoft-aspire-cli*.tgz` npm tarballs from the native archive jobs, and the Windows, Linux, and macOS npm install validation summaries. + - The build must include native CLI NuGet packages, `microsoft-aspire-cli*.tgz` npm tarballs from the native archive jobs, matching `.tgz.sig` detached signature sidecars, and the Windows, Linux, and macOS npm install validation summaries. 2. **Release branch**: Ensure the release branch exists, for example `release/9.2`. 3. **Permissions and approvals**: - Access to run Azure DevOps pipelines with the publishing pool. @@ -154,7 +154,7 @@ Both automations are designed to be idempotent and safe to re-run. | Derive ReleaseVersion | Check that the build has a `release-version - X.Y.Z` tag, or pass `ReleaseVersion` explicitly. | | Extract BAR Build ID | Check that the build has a `BAR ID - NNNNNN` tag. | | Prepare/List/Verify NuGet Packages | Check that the selected source build produced `PackageArtifacts`. | -| Prepare/List npm Packages | Check that the selected source build produced all eight `microsoft-aspire-cli*.tgz` tarballs in `BlobArtifacts`. | +| Prepare/List npm Packages | Check that the selected source build produced all eight `microsoft-aspire-cli*.tgz` tarballs and matching `.tgz.sig` sidecars in `BlobArtifacts`. | | Push Packages to NuGet.org | Check NuGet.org for partial success, then re-run with already-completed steps skipped as needed. | | MicroBuild npm Publish | Check the ESRP release result. If RID packages published but the pointer package did not, re-run with `SkipNuGetPublish: true`, `SkipNpmRidPublish: true`, and `SkipChannelPromotion: true`; do not set `SkipNpmPublish` until the pointer package is published. | | Promote Build to Channel | Re-run with completed publish steps skipped. | diff --git a/docs/specs/npm-cli-package.md b/docs/specs/npm-cli-package.md index 6521717e8ea..e302115de85 100644 --- a/docs/specs/npm-cli-package.md +++ b/docs/specs/npm-cli-package.md @@ -172,7 +172,7 @@ Only one pointer package is staged. The default canonical pointer source is `nat The native archive workflows verify npm tarballs after the existing nupkg verification and then run the end-to-end install test above. -Azure Pipelines installs Node.js before native package build because `npm pack` runs during packaging, verifies the npm packages, downloads `microsoft-aspire-cli*.tgz` in the staging job, and stages them with the native CLI packages. The source build then publishes the npm `.tgz` files as shipping flat blob artifacts so the release pipeline can consume them without treating npm tarballs as NuGet-like BAR package assets. The install-test jobs also publish platform-specific validation summary artifacts that the release pipeline aggregates into `NpmValidationSummary` and requires before publishing. +Azure Pipelines installs Node.js before native package build because `npm pack` runs during packaging, verifies the npm packages, downloads `microsoft-aspire-cli*.tgz` in the staging job, and stages them with the native CLI packages. The source build then signs the npm `.tgz` files with detached `.tgz.sig` sidecars and publishes both as shipping flat blob artifacts so the release pipeline can consume them without treating npm tarballs as NuGet-like BAR package assets. The install-test jobs also publish platform-specific validation summary artifacts that the release pipeline aggregates into `NpmValidationSummary` and requires before publishing. ## Publishing @@ -186,14 +186,14 @@ The release pipeline prepares two npm artifact folders and one validation artifa The package split is intentional. The release job submits RID packages first, waits for the ESRP submission to complete, waits an additional npm registry propagation delay, and then submits the pointer package. Publishing the pointer package last avoids optional dependency resolution races when a user installs the top-level package immediately after release. -Before publishing, the release pipeline validates that exactly one pointer tarball and exactly one tarball for each supported RID are present, that all tarballs have one version, and that the `NpmValidationSummary` artifact reports `validatedByPreparePipeline: true` with every required check `passed` for Windows, Linux, and macOS install validation. Non-dry-run npm publishing also requires release managers to provide `NpmPublishOwners` and `NpmPublishApprovers`, which are passed to ESRP. Re-runs can use `SkipNpmRidPublish` if the RID packages published but the pointer package did not, and `SkipNpmPublish` after npm publishing has completed. +Before publishing, the release pipeline validates that exactly one pointer tarball and exactly one tarball for each supported RID are present, that every tarball has a detached `.tgz.sig` sidecar, that all tarballs have one version, and that the `NpmValidationSummary` artifact reports `validatedByPreparePipeline: true` with every required check `passed` for Windows, Linux, and macOS install validation. Non-dry-run npm publishing also requires release managers to provide `NpmPublishOwners` and `NpmPublishApprovers`, which are passed to ESRP. Re-runs can use `SkipNpmRidPublish` if the RID packages published but the pointer package did not, and `SkipNpmPublish` after npm publishing has completed. MicroBuild's npm publish template documentation does not currently expose an npm `dist-tag` parameter. Non-dry-run prerelease npm publishing is blocked until preview packages can be submitted under a non-`latest` tag; release managers can still use `DryRun=true` to inspect the npm publish set without submitting packages. ## Product and security tradeoffs - **No GitHub npm publishing token**: Publishing is centralized through ESRP/MicroBuild and the Microsoft1ES npm maintainer identity instead of storing an npm token in GitHub or using a repository-local GitHub Actions publisher. -- **Signed payload, unsigned tarball container**: The npm tarball is created from the native CLI archive produced by the signed CI flow, and verification compares the RID tarball binary byte-for-byte with that archive. The `.tgz` container itself is not separately signed; integrity comes from CI verification, the `NpmValidationSummary` install test, SBOM-covered release artifacts, ESRP submission, and npm registry package integrity. +- **Signed payload and tarball sidecar**: The npm tarball is created from the native CLI archive produced by the signed CI flow, and verification compares the RID tarball binary byte-for-byte with that archive. The `.tgz` package also receives an Arcade/MicroBuild detached signature sidecar (`.tgz.sig`); the release pipeline validates sidecar coverage while passing only `.tgz` package files to the npm publishing folders. - **No Sigstore `npm publish --provenance` attestation**: ESRP's npm publish path is not currently configured to emit Sigstore provenance attestations from a public OIDC publisher. Integrity is anchored at the signed native binary, the Microsoft1ES npm maintainer identity, and the ESRP submission audit trail. When ESRP gains support for npm provenance attestations, the release pipeline should opt in and this tradeoff should be revisited. - **Writable cache**: Copying the native binary to `~/.aspire/npm///bin` avoids self-extraction into package-manager stores, but it means the launcher owns cache creation and freshness checks. The launcher uses size + `mtime` comparison so a stale cache from an earlier same-version install does not silently shadow a re-downloaded binary. - **Update behavior**: npm updates remain package-manager driven (`npm install -g @microsoft/aspire-cli@latest`). The CLI detects npm installs via the launcher's environment variables and prints the npm-specific update command instead of attempting to overwrite the npm-owned binary with the GitHub-binary downloader. diff --git a/eng/Publishing.props b/eng/Publishing.props index 5e22b4720f3..117dc29bd6d 100644 --- a/eng/Publishing.props +++ b/eng/Publishing.props @@ -41,6 +41,7 @@ <_CliToolPackagesToPublish Include="$(ArtifactsShippingPackagesDir)**\Aspire.Cli*.nupkg" Exclude="$(ArtifactsShippingPackagesDir)**\*.symbols.nupkg" /> <_CliNpmPackagesToPublish Include="$(ArtifactsShippingPackagesDir)**\microsoft-aspire-cli*.tgz" /> + <_CliNpmPackageSignaturesToPublish Include="$(ArtifactsShippingPackagesDir)**\microsoft-aspire-cli*.tgz.sig" /> + + + + @@ -75,6 +84,7 @@ + diff --git a/eng/pipelines/azure-pipelines.yml b/eng/pipelines/azure-pipelines.yml index 6389b6d547c..dc166eadb8a 100644 --- a/eng/pipelines/azure-pipelines.yml +++ b/eng/pipelines/azure-pipelines.yml @@ -287,7 +287,7 @@ extends: - task: UseNode@1 displayName: 🟣Install node.js inputs: - version: '20.x' + version: '22.x' - task: npmAuthenticate@0 displayName: 🟣NPM authenticate diff --git a/eng/pipelines/release-publish-nuget.yml b/eng/pipelines/release-publish-nuget.yml index 812236f51d0..8bd95294d30 100644 --- a/eng/pipelines/release-publish-nuget.yml +++ b/eng/pipelines/release-publish-nuget.yml @@ -192,6 +192,10 @@ extends: displayName: 'Publish npm Validation Summary' targetPath: '$(Pipeline.Workspace)/npm/validation-summary' artifactName: 'NpmValidationSummary' + - output: pipelineArtifact + displayName: 'Publish npm Signature Sidecars' + targetPath: '$(Pipeline.Workspace)/npm/signatures' + artifactName: 'NpmSignatureArtifacts' - ${{ if eq(parameters.SkipWinGetPublish, false) }}: - output: pipelineArtifact displayName: 'Publish WinGet Manifests' @@ -313,7 +317,9 @@ extends: - download: aspire-build displayName: 'Download npm packages from Source Build' artifact: BlobArtifacts - patterns: '**/microsoft-aspire-cli*.tgz' + patterns: | + **/microsoft-aspire-cli*.tgz + **/microsoft-aspire-cli*.tgz.sig - download: aspire-build displayName: 'Download npm validation summary from Source Build (win-x64)' @@ -372,6 +378,7 @@ extends: $sourcePath = "$(Pipeline.Workspace)/aspire-build/BlobArtifacts" $ridTargetPath = "$(Pipeline.Workspace)/npm/rid-packages" $pointerTargetPath = "$(Pipeline.Workspace)/npm/pointer-package" + $signatureTargetPath = "$(Pipeline.Workspace)/npm/signatures" $expectedRids = @( 'win-x64', 'win-arm64', @@ -384,6 +391,7 @@ extends: New-Item -ItemType Directory -Path $ridTargetPath -Force | Out-Null New-Item -ItemType Directory -Path $pointerTargetPath -Force | Out-Null + New-Item -ItemType Directory -Path $signatureTargetPath -Force | Out-Null Write-Host "Preparing npm packages from $sourcePath" if (!(Test-Path $sourcePath)) { @@ -408,20 +416,58 @@ extends: $pointerPattern = "^microsoft-aspire-cli-($versionPattern)\.tgz$" $ridPattern = "^microsoft-aspire-cli-(?.+?)-(?$versionPattern)\.tgz$" $packages = @(Get-ChildItem -Path $sourcePath -Filter "microsoft-aspire-cli*.tgz" -Recurse -File) + $signatureSidecars = @(Get-ChildItem -Path $sourcePath -Filter "microsoft-aspire-cli*.tgz.sig" -Recurse -File) $pointerPackages = @($packages | Where-Object { $_.Name -match $pointerPattern }) $ridPackages = @($packages | Where-Object { $_.Name -match $ridPattern }) $unexpectedPackages = @($packages | Where-Object { $_.Name -notmatch $pointerPattern -and $_.Name -notmatch $ridPattern }) + $signatureSidecarsByPackageName = @{} + $duplicateSignatureSidecars = [System.Collections.Generic.List[string]]::new() Write-Host "Found $($packages.Count) npm package(s)." foreach ($pkg in $packages) { Write-Host " - $($pkg.Name)" } + Write-Host "Found $($signatureSidecars.Count) npm detached signature sidecar(s)." + foreach ($signatureSidecar in $signatureSidecars) { + Write-Host " - $($signatureSidecar.Name)" + + $packageName = $signatureSidecar.Name.Substring(0, $signatureSidecar.Name.Length - '.sig'.Length) + if ($signatureSidecarsByPackageName.ContainsKey($packageName)) { + $duplicateSignatureSidecars.Add($signatureSidecar.Name) + continue + } + + $signatureSidecarsByPackageName[$packageName] = $signatureSidecar + } + + if ($duplicateSignatureSidecars.Count -gt 0) { + Write-Error "Duplicate npm detached signature sidecar(s): $($duplicateSignatureSidecars -join ', ')" + exit 1 + } + if ($unexpectedPackages.Count -gt 0) { Write-Error "Unexpected npm package filename(s): $($unexpectedPackages.Name -join ', ')" exit 1 } + $missingSignaturePackages = @($packages | Where-Object { !$signatureSidecarsByPackageName.ContainsKey($_.Name) }) + if ($missingSignaturePackages.Count -gt 0) { + Write-Error "Missing detached signature sidecar(s) for npm package(s): $($missingSignaturePackages.Name -join ', ')" + exit 1 + } + + $packageNames = [System.Collections.Generic.HashSet[string]]::new([StringComparer]::OrdinalIgnoreCase) + foreach ($pkg in $packages) { + [void]$packageNames.Add($pkg.Name) + } + + $orphanSignatureSidecars = @($signatureSidecarsByPackageName.GetEnumerator() | Where-Object { !$packageNames.Contains($_.Key) } | ForEach-Object { $_.Value }) + if ($orphanSignatureSidecars.Count -gt 0) { + Write-Error "Found detached signature sidecar(s) without a matching npm package: $($orphanSignatureSidecars.Name -join ', ')" + exit 1 + } + if ($pointerPackages.Count -ne 1) { Write-Error "Expected exactly one Aspire CLI npm pointer package, but found $($pointerPackages.Count): $($pointerPackages.FullName -join ', ')" exit 1 @@ -468,6 +514,9 @@ extends: Copy-Item $pkg.FullName -Destination $ridTargetPath -Force } Copy-Item $pointerPackages[0].FullName -Destination $pointerTargetPath -Force + foreach ($signatureSidecar in $signatureSidecars) { + Copy-Item $signatureSidecar.FullName -Destination $signatureTargetPath -Force + } $summaryTarget = "$(Pipeline.Workspace)/npm/validation-summary" New-Item -ItemType Directory -Path $summaryTarget -Force | Out-Null @@ -493,7 +542,7 @@ extends: Copy-Item $summarySource -Destination (Join-Path $summaryOutputDirectory 'validation-summary.json') -Force } - Write-Host "Prepared $($ridPackages.Count) RID npm package(s) and pointer package version $($versions[0])." + Write-Host "Prepared $($ridPackages.Count) RID npm package(s), pointer package version $($versions[0]), and $($signatureSidecars.Count) detached signature sidecar(s)." displayName: 'Prepare npm Artifacts for Publishing' - ${{ if eq(parameters.SkipNpmPublish, true) }}: @@ -504,6 +553,7 @@ extends: New-Item -ItemType Directory -Path "$(Pipeline.Workspace)/npm/validation-summary/win-x64" -Force | Out-Null New-Item -ItemType Directory -Path "$(Pipeline.Workspace)/npm/validation-summary/linux-x64" -Force | Out-Null New-Item -ItemType Directory -Path "$(Pipeline.Workspace)/npm/validation-summary/osx" -Force | Out-Null + New-Item -ItemType Directory -Path "$(Pipeline.Workspace)/npm/signatures" -Force | Out-Null Write-Host "Created empty npm artifact placeholders because SkipNpmPublish=true." displayName: 'Prepare Empty npm Artifact Placeholders' @@ -578,6 +628,9 @@ extends: - input: pipelineArtifact artifactName: NpmValidationSummary targetPath: '$(Pipeline.Workspace)/npm/validation-summary' + - input: pipelineArtifact + artifactName: NpmSignatureArtifacts + targetPath: '$(Pipeline.Workspace)/npm/signatures' steps: # ===== VALIDATION ===== # Note: No checkout - releaseJob doesn't allow it. All scripts are inlined. @@ -851,10 +904,12 @@ extends: - powershell: | $ridPackagesPath = "$(Pipeline.Workspace)/npm/rid-packages" $pointerPackagePath = "$(Pipeline.Workspace)/npm/pointer-package" + $signaturePath = "$(Pipeline.Workspace)/npm/signatures" Write-Host "=== npm Package Inventory ===" $ridPackages = @(Get-ChildItem -Path $ridPackagesPath -Filter "*.tgz" -File) $pointerPackages = @(Get-ChildItem -Path $pointerPackagePath -Filter "*.tgz" -File) + $signatureSidecars = @(Get-ChildItem -Path $signaturePath -Filter "*.tgz.sig" -File) Write-Host "RID packages: $($ridPackages.Count)" foreach ($pkg in $ridPackages) { @@ -868,11 +923,28 @@ extends: Write-Host " - $($pkg.Name) ($sizeMB MB)" } + Write-Host "Signature sidecars: $($signatureSidecars.Count)" + foreach ($signatureSidecar in $signatureSidecars) { + $sizeKB = [math]::Round($signatureSidecar.Length / 1KB, 2) + Write-Host " - $($signatureSidecar.Name) ($sizeKB KB)" + } + if ($ridPackages.Count -ne 7 -or $pointerPackages.Count -ne 1) { Write-Error "Expected 7 npm RID packages and 1 npm pointer package." exit 1 } + $signatureNames = [System.Collections.Generic.HashSet[string]]::new([StringComparer]::OrdinalIgnoreCase) + foreach ($signatureSidecar in $signatureSidecars) { + [void]$signatureNames.Add($signatureSidecar.Name) + } + + $missingSignatures = @($ridPackages + $pointerPackages | Where-Object { !$signatureNames.Contains("$($_.Name).sig") }) + if ($missingSignatures.Count -gt 0) { + Write-Error "Missing detached signature sidecar(s) for npm package(s): $($missingSignatures.Name -join ', ')" + exit 1 + } + Write-Host "==============================" displayName: 'List npm Packages' diff --git a/eng/pipelines/templates/BuildAndTest.yml b/eng/pipelines/templates/BuildAndTest.yml index 11cbde39bbf..2b5552f404d 100644 --- a/eng/pipelines/templates/BuildAndTest.yml +++ b/eng/pipelines/templates/BuildAndTest.yml @@ -55,6 +55,41 @@ steps: /p:BuildExtension=true displayName: 🟣Build + - pwsh: | + $ErrorActionPreference = 'Stop' + $shippingPackagesDir = '${{ parameters.repoArtifactsPath }}/packages/${{ parameters.buildConfig }}/Shipping' + + if (!(Test-Path $shippingPackagesDir)) { + Write-Error "Shipping packages directory not found: $shippingPackagesDir" + exit 1 + } + + $npmPackages = @(Get-ChildItem -Path $shippingPackagesDir -Filter "microsoft-aspire-cli*.tgz" -Recurse -File) + if ($npmPackages.Count -eq 0) { + Write-Error "No Aspire CLI npm packages were found under '$shippingPackagesDir'." + exit 1 + } + + $missingSignatures = @() + foreach ($package in $npmPackages) { + $signaturePath = "$($package.FullName).sig" + if (!(Test-Path $signaturePath)) { + $missingSignatures += $signaturePath + continue + } + + Write-Host "Found npm package signature sidecar: $([System.IO.Path]::GetFileName($signaturePath))" + } + + if ($missingSignatures.Count -gt 0) { + Write-Error "Missing detached signature sidecar(s) for npm package(s): $($missingSignatures -join ', ')" + exit 1 + } + + Write-Host "Validated $($npmPackages.Count) Aspire CLI npm package signature sidecar(s)." + displayName: 🟣Validate npm package signatures + condition: and(succeeded(), eq(variables['_SignType'], 'real')) + # Log MicroBuild environment for debugging # MicroBuildOutputFolderOverride is set by the MicroBuildSigningPlugin task in eng/common/templates-official/job/onelocbuild.yml # which is installed via the Arcade SDK's install-microbuild.yml template that runs before our build steps. From 6fd3c0d86d713fef058ed640b444e287f77d8de5 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Fri, 29 May 2026 13:21:06 -0400 Subject: [PATCH 14/35] Validate npm release parameters before publishing Fail npm publish preflight validation before any irreversible NuGet publishing step so release runs cannot partially publish NuGet packages and then fail on npm ESRP/prerelease prerequisites. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- eng/pipelines/release-publish-nuget.yml | 46 ++++++------ .../ReleasePublishNugetPipelineTests.cs | 71 +++++++++++++++++++ 2 files changed, 94 insertions(+), 23 deletions(-) create mode 100644 tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs diff --git a/eng/pipelines/release-publish-nuget.yml b/eng/pipelines/release-publish-nuget.yml index 8bd95294d30..84492a421bc 100644 --- a/eng/pipelines/release-publish-nuget.yml +++ b/eng/pipelines/release-publish-nuget.yml @@ -650,6 +650,29 @@ extends: Write-Host "Skip npm RID Publish: ${{ parameters.SkipNpmRidPublish }}" Write-Host "Skip Channel Promotion: ${{ parameters.SkipChannelPromotion }}" Write-Host "Installer-only mode: ${{ and(eq(parameters.SkipNuGetPublish, true), eq(parameters.SkipNpmPublish, true), eq(parameters.SkipChannelPromotion, true)) }}" + + if ("${{ parameters.DryRun }}" -eq "false" -and "${{ parameters.SkipNpmPublish }}" -eq "false") { + if ("${{ parameters.IsPrerelease }}" -eq "true") { + Write-Error "npm publishing is blocked for prerelease runs because the MicroBuild npm publish template does not yet expose a dist-tag parameter. Set SkipNpmPublish=true or run with DryRun=true until prereleases can publish under a non-latest tag." + exit 1 + } + + $owners = "${{ parameters.NpmPublishOwners }}" + $approvers = "${{ parameters.NpmPublishApprovers }}" + + if ([string]::IsNullOrWhiteSpace($owners)) { + Write-Error "NpmPublishOwners must be set before publishing npm packages." + exit 1 + } + + if ([string]::IsNullOrWhiteSpace($approvers)) { + Write-Error "NpmPublishApprovers must be set before publishing npm packages." + exit 1 + } + + Write-Host "npm ESRP owners and approvers were provided." + } + Write-Host "===================================" displayName: 'Validate Parameters' @@ -972,30 +995,7 @@ extends: Write-Host "=== DRY RUN - No npm packages were actually published ===" displayName: 'Dry Run - List npm Packages (No Publish)' - - ${{ if and(eq(parameters.DryRun, false), eq(parameters.SkipNpmPublish, false), eq(parameters.IsPrerelease, true)) }}: - - powershell: | - Write-Error "npm publishing is blocked for prerelease runs because the MicroBuild npm publish template does not yet expose a dist-tag parameter. Set SkipNpmPublish=true or run with DryRun=true until prereleases can publish under a non-latest tag." - exit 1 - displayName: 'Block npm Publish for Prerelease' - - ${{ if and(eq(parameters.DryRun, false), eq(parameters.SkipNpmPublish, false), eq(parameters.IsPrerelease, false)) }}: - - powershell: | - $owners = "${{ parameters.NpmPublishOwners }}" - $approvers = "${{ parameters.NpmPublishApprovers }}" - - if ([string]::IsNullOrWhiteSpace($owners)) { - Write-Error "NpmPublishOwners must be set before publishing npm packages." - exit 1 - } - - if ([string]::IsNullOrWhiteSpace($approvers)) { - Write-Error "NpmPublishApprovers must be set before publishing npm packages." - exit 1 - } - - Write-Host "npm ESRP owners and approvers were provided." - displayName: 'Validate npm ESRP Parameters' - - ${{ if eq(parameters.SkipNpmRidPublish, false) }}: - template: MicroBuild.Publish.yml@MicroBuildTemplate parameters: diff --git a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs new file mode 100644 index 00000000000..52ebfaed854 --- /dev/null +++ b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs @@ -0,0 +1,71 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using Xunit; + +namespace Infrastructure.Tests; + +public sealed class ReleasePublishNugetPipelineTests +{ + private readonly string _repoRoot = FindRepoRoot(); + + [Fact] + public async Task ValidatesNpmPublishPreconditionsBeforeNuGetPublish() + { + var pipeline = await ReadRepoFileAsync("eng/pipelines/release-publish-nuget.yml"); + var nuGetPublishIndex = FindRequiredText(pipeline, "task: 1ES.PublishNuget@1"); + + AssertBefore( + pipeline, + "npm publishing is blocked for prerelease runs because the MicroBuild npm publish template does not yet expose a dist-tag parameter.", + nuGetPublishIndex); + + AssertBefore( + pipeline, + "NpmPublishOwners must be set before publishing npm packages.", + nuGetPublishIndex); + + AssertBefore( + pipeline, + "NpmPublishApprovers must be set before publishing npm packages.", + nuGetPublishIndex); + } + + private static void AssertBefore(string contents, string text, int boundaryIndex) + { + var textIndex = FindRequiredText(contents, text); + + Assert.True( + textIndex < boundaryIndex, + $"Expected '{text}' to appear before 'task: 1ES.PublishNuget@1'."); + } + + private static int FindRequiredText(string contents, string text) + { + var index = contents.IndexOf(text, StringComparison.Ordinal); + + Assert.True(index >= 0, $"Expected to find '{text}'."); + + return index; + } + + private Task ReadRepoFileAsync(string relativePath) + => File.ReadAllTextAsync(Path.Combine(_repoRoot, relativePath.Replace('/', Path.DirectorySeparatorChar))); + + private static string FindRepoRoot() + { + string? current = AppContext.BaseDirectory; + + while (current is not null) + { + if (File.Exists(Path.Combine(current, "Aspire.slnx"))) + { + return current; + } + + current = Directory.GetParent(current)?.FullName; + } + + throw new DirectoryNotFoundException("Could not find repository root containing Aspire.slnx"); + } +} From ddfea5cf769fc8db97ff9aa820db67f101cf26f9 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Fri, 29 May 2026 13:31:34 -0400 Subject: [PATCH 15/35] Use offline Homebrew validation for release dry runs Release dry-runs do not upload GitHub release assets, so LiveRelease Homebrew validation cannot pass for a new version without mutating the release. Switch Homebrew validation to LiveArchives when DryRun=true while preserving LiveRelease for non-dry releases. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- eng/homebrew/README.md | 25 ++++---- eng/pipelines/release-publish-nuget.yml | 58 ++++++++++--------- .../ReleasePublishNugetPipelineTests.cs | 17 ++++++ 3 files changed, 62 insertions(+), 38 deletions(-) diff --git a/eng/homebrew/README.md b/eng/homebrew/README.md index 60cdecdb61c..0ebd2f8ba44 100644 --- a/eng/homebrew/README.md +++ b/eng/homebrew/README.md @@ -70,23 +70,24 @@ what `brew install` fetches from the GitHub release URL. ## CI Pipeline -| Pipeline | Prepares | Validates against live release | Publishes | +| Pipeline | Prepares | Release-time validation | Publishes | |---|---|---|---| | `.github/workflows/tests.yml` | Prerelease casks (artifacts only) | — | — | | `azure-pipelines.yml` (prepare stage) | Stable or prerelease casks (artifacts only) | — | — | -| `release-publish-nuget.yml` (release) | — | Stable cask, LiveRelease mode | — (autobump handles bumps; see below) | +| `release-publish-nuget.yml` (release, DryRun=true) | — | Stable cask, LiveArchives mode | — | +| `release-publish-nuget.yml` (release, DryRun=false) | — | Stable cask, LiveRelease mode | — (autobump handles bumps; see below) | The release pipeline's `HomebrewValidateJob` runs `validate-cask-artifact.sh` -in LiveRelease mode against the cask emitted by the source build, after the -release-asset upload step has attached the `aspire-cli-osx-*.tar.gz` -archives to the GitHub release. This is the first point at which the -cask's `url` (a `v#{version}` GitHub release-asset URL) actually resolves; -the source-build prepare stage can only validate offline because the -GitHub release for the version being built does not exist yet. Failures -in this job catch problems that would otherwise only surface to end -users running `brew install aspire`, or block Homebrew/homebrew-cask's -autobump PR a few hours later. Gated by `SkipHomebrewValidation` for -partial-failure re-runs. +against the cask emitted by the source build. In non-dry runs it uses +LiveRelease mode after the release-asset upload step has attached the +`aspire-cli-osx-*.tar.gz` archives to the GitHub release. This is the first +point at which the cask's `url` (a `v#{version}` GitHub release-asset URL) +actually resolves; the source-build prepare stage and release dry-runs use +LiveArchives mode because the GitHub release for the version being built does +not exist yet. Failures in the non-dry LiveRelease job catch problems that +would otherwise only surface to end users running `brew install aspire`, or +block Homebrew/homebrew-cask's autobump PR a few hours later. Gated by +`SkipHomebrewValidation` for partial-failure re-runs. ### Submission: upstream autobump diff --git a/eng/pipelines/release-publish-nuget.yml b/eng/pipelines/release-publish-nuget.yml index 84492a421bc..7518ae3316e 100644 --- a/eng/pipelines/release-publish-nuget.yml +++ b/eng/pipelines/release-publish-nuget.yml @@ -11,6 +11,7 @@ # 6. Uploads aspire-cli-* archives from the source build's BlobArtifacts # onto the GitHub Release as the aspire-repo-bot # 7. Validates the Homebrew cask against the live GitHub release +# (or offline in dry-run mode) # # For full documentation, see: docs/release-process.md @@ -1164,6 +1165,8 @@ extends: Write-Host "║ Homebrew Val: ${{ parameters.SkipHomebrewValidation }}" -NoNewline if ("${{ parameters.SkipHomebrewValidation }}" -eq "true") { Write-Host " (SKIPPED)" + } elseif ("${{ parameters.DryRun }}" -eq "true") { + Write-Host " (LiveArchives dry-run; no release URL fetch)" } else { Write-Host " (validates cask against live GH release after asset upload)" } @@ -1214,15 +1217,11 @@ extends: # and uploads them as assets on the GitHub release that the # dispatch job just created. # - # 3. HomebrewValidateJob — runs the full upstream-equivalent cask - # validation (`brew audit --cask --online --signing` + real - # `brew install`/`brew uninstall`) against the cask generated by - # the source build, with the live GitHub release URL it points - # at. This is the moment when the URL is actually reachable — - # the source-build prepare stage can only validate offline because - # the GitHub release for the version being built does not exist - # yet. Catches problems that would otherwise only surface to - # end users (or block Homebrew/homebrew-cask's autobump PR). + # 3. HomebrewValidateJob — validates the generated cask. Non-dry runs + # run the full upstream-equivalent validation (`brew audit --cask + # --online --signing` + real `brew install`/`brew uninstall`) + # against the live GitHub release URL. Dry-runs use LiveArchives + # mode because no release assets are uploaded. # # Each job has its own skip flag (SkipGitHubTasks / SkipReleaseAssets / # SkipHomebrewValidation) so partial-failure re-runs can recover any @@ -1232,13 +1231,13 @@ extends: # propagated to the GH workflow as dry_run=true (keeps it from # creating tags/releases/PRs) and to the asset script (downloads and # verifies SHA512s but skips the gh release upload). HomebrewValidateJob - # also runs under DryRun — it does not publish anything, it only audits - # and `brew install`/`brew uninstall` against a public URL. If the - # release for the version being validated does not yet exist (DryRun, - # or a re-run after assets were already uploaded), the job is expected - # to surface that as a real failure rather than be silently skipped. - # This lets a release manager validate the full AzDO → GitHub path - # end-to-end without performing a real release. + # also runs under DryRun, but uses LiveArchives validation mode instead + # of LiveRelease because the GitHub release assets do not exist yet. + # LiveArchives validates Ruby syntax, brew style, tap syntax, and + # `brew audit --cask --no-signing` without attempting to fetch the + # release URL. Non-dry runs use LiveRelease mode with full + # `brew audit --cask --online --signing` and real + # `brew install`/`brew uninstall`. - stage: GitHubTasks displayName: 'Dispatch GitHub Release Tasks' # PrepareArtifacts is listed explicitly (in addition to Release) so the @@ -1472,19 +1471,20 @@ extends: ASPIRE_BOT_PRIVATE_KEY: $(aspire-bot-private-key) # Validate the generated Homebrew cask against the live GitHub - # release. Runs `brew audit --cask --online --signing` and a real - # `brew install`/`brew uninstall` against the cask file produced by - # the source build. The cask URL points at + # release in non-dry runs. Runs `brew audit --cask --online + # --signing` and a real `brew install`/`brew uninstall` against the + # cask file produced by the source build. The cask URL points at # github.com/microsoft/aspire/releases/download/v#{version}/..., so # the release for the version being built must already exist for - # this job to pass — normally that happens earlier in this stage - # via PublishReleaseAssetsJob. The dependsOn below is purely + # LiveRelease validation to pass — normally that happens earlier in + # this stage via PublishReleaseAssetsJob. Dry-run uses LiveArchives + # because no release assets are uploaded. The dependsOn below is purely # temporal; the cask artifact itself comes from the aspire-build # resource, not from PublishReleaseAssetsJob. Accepting 'Skipped' # alongside Succeeded lets you re-run with SkipReleaseAssets=true # against a previously uploaded release; if the release is missing - # the job is expected to fail loudly rather than be silently - # gated out. + # in LiveRelease mode, the job is expected to fail loudly rather + # than be silently gated out. # # Modeled on PublishReleaseAssetsJob (regular buildJob with checkout # + a `download: aspire-build` step) rather than WingetJob's @@ -1493,7 +1493,7 @@ extends: # and to consume an artifact from the source build — and 1ES PT's # releaseJob enforces `checkout: none`. - job: HomebrewValidateJob - displayName: 'Validate Homebrew Cask against live release' + displayName: 'Validate Homebrew Cask' dependsOn: PublishReleaseAssetsJob condition: | and( @@ -1523,8 +1523,14 @@ extends: exit 1 fi + validation_mode="LiveRelease" + if [[ '${{ parameters.DryRun }}' == 'true' ]]; then + validation_mode="LiveArchives" + fi + + echo "Homebrew validation mode: $validation_mode" "$(Build.SourcesDirectory)/eng/homebrew/validate-cask-artifact.sh" \ --cask-file "$cask_file" \ --channel stable \ - --validation-mode LiveRelease - displayName: '🟣Validate cask against live GitHub release' + --validation-mode "$validation_mode" + displayName: '🟣Validate Homebrew cask' diff --git a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs index 52ebfaed854..4c4b81abeb1 100644 --- a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs +++ b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs @@ -31,6 +31,23 @@ public async Task ValidatesNpmPublishPreconditionsBeforeNuGetPublish() nuGetPublishIndex); } + [Fact] + public async Task HomebrewDryRunUsesOfflineValidationMode() + { + var pipeline = await ReadRepoFileAsync("eng/pipelines/release-publish-nuget.yml"); + var homebrewJobIndex = FindRequiredText(pipeline, "job: HomebrewValidateJob"); + var validateScriptIndex = FindRequiredText(pipeline, "\"$(Build.SourcesDirectory)/eng/homebrew/validate-cask-artifact.sh\""); + var jobSetup = pipeline[homebrewJobIndex..validateScriptIndex]; + + Assert.Contains("validation_mode=\"LiveRelease\"", jobSetup); + Assert.Contains("'${{ parameters.DryRun }}' == 'true'", jobSetup); + Assert.Contains("validation_mode=\"LiveArchives\"", jobSetup); + + var validateScriptCall = pipeline[validateScriptIndex..Math.Min(pipeline.Length, validateScriptIndex + 500)]; + Assert.Contains("--validation-mode \"$validation_mode\"", validateScriptCall); + Assert.DoesNotContain("--validation-mode LiveRelease", validateScriptCall); + } + private static void AssertBefore(string contents, string text, int boundaryIndex) { var textIndex = FindRequiredText(contents, text); From 74e0477172a43ff81d09f6df7b90dc026178a8eb Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Fri, 29 May 2026 13:35:04 -0400 Subject: [PATCH 16/35] Revert "Use offline Homebrew validation for release dry runs" This reverts commit ddfea5cf769fc8db97ff9aa820db67f101cf26f9. --- eng/homebrew/README.md | 25 ++++---- eng/pipelines/release-publish-nuget.yml | 58 +++++++++---------- .../ReleasePublishNugetPipelineTests.cs | 17 ------ 3 files changed, 38 insertions(+), 62 deletions(-) diff --git a/eng/homebrew/README.md b/eng/homebrew/README.md index 0ebd2f8ba44..60cdecdb61c 100644 --- a/eng/homebrew/README.md +++ b/eng/homebrew/README.md @@ -70,24 +70,23 @@ what `brew install` fetches from the GitHub release URL. ## CI Pipeline -| Pipeline | Prepares | Release-time validation | Publishes | +| Pipeline | Prepares | Validates against live release | Publishes | |---|---|---|---| | `.github/workflows/tests.yml` | Prerelease casks (artifacts only) | — | — | | `azure-pipelines.yml` (prepare stage) | Stable or prerelease casks (artifacts only) | — | — | -| `release-publish-nuget.yml` (release, DryRun=true) | — | Stable cask, LiveArchives mode | — | -| `release-publish-nuget.yml` (release, DryRun=false) | — | Stable cask, LiveRelease mode | — (autobump handles bumps; see below) | +| `release-publish-nuget.yml` (release) | — | Stable cask, LiveRelease mode | — (autobump handles bumps; see below) | The release pipeline's `HomebrewValidateJob` runs `validate-cask-artifact.sh` -against the cask emitted by the source build. In non-dry runs it uses -LiveRelease mode after the release-asset upload step has attached the -`aspire-cli-osx-*.tar.gz` archives to the GitHub release. This is the first -point at which the cask's `url` (a `v#{version}` GitHub release-asset URL) -actually resolves; the source-build prepare stage and release dry-runs use -LiveArchives mode because the GitHub release for the version being built does -not exist yet. Failures in the non-dry LiveRelease job catch problems that -would otherwise only surface to end users running `brew install aspire`, or -block Homebrew/homebrew-cask's autobump PR a few hours later. Gated by -`SkipHomebrewValidation` for partial-failure re-runs. +in LiveRelease mode against the cask emitted by the source build, after the +release-asset upload step has attached the `aspire-cli-osx-*.tar.gz` +archives to the GitHub release. This is the first point at which the +cask's `url` (a `v#{version}` GitHub release-asset URL) actually resolves; +the source-build prepare stage can only validate offline because the +GitHub release for the version being built does not exist yet. Failures +in this job catch problems that would otherwise only surface to end +users running `brew install aspire`, or block Homebrew/homebrew-cask's +autobump PR a few hours later. Gated by `SkipHomebrewValidation` for +partial-failure re-runs. ### Submission: upstream autobump diff --git a/eng/pipelines/release-publish-nuget.yml b/eng/pipelines/release-publish-nuget.yml index 7518ae3316e..84492a421bc 100644 --- a/eng/pipelines/release-publish-nuget.yml +++ b/eng/pipelines/release-publish-nuget.yml @@ -11,7 +11,6 @@ # 6. Uploads aspire-cli-* archives from the source build's BlobArtifacts # onto the GitHub Release as the aspire-repo-bot # 7. Validates the Homebrew cask against the live GitHub release -# (or offline in dry-run mode) # # For full documentation, see: docs/release-process.md @@ -1165,8 +1164,6 @@ extends: Write-Host "║ Homebrew Val: ${{ parameters.SkipHomebrewValidation }}" -NoNewline if ("${{ parameters.SkipHomebrewValidation }}" -eq "true") { Write-Host " (SKIPPED)" - } elseif ("${{ parameters.DryRun }}" -eq "true") { - Write-Host " (LiveArchives dry-run; no release URL fetch)" } else { Write-Host " (validates cask against live GH release after asset upload)" } @@ -1217,11 +1214,15 @@ extends: # and uploads them as assets on the GitHub release that the # dispatch job just created. # - # 3. HomebrewValidateJob — validates the generated cask. Non-dry runs - # run the full upstream-equivalent validation (`brew audit --cask - # --online --signing` + real `brew install`/`brew uninstall`) - # against the live GitHub release URL. Dry-runs use LiveArchives - # mode because no release assets are uploaded. + # 3. HomebrewValidateJob — runs the full upstream-equivalent cask + # validation (`brew audit --cask --online --signing` + real + # `brew install`/`brew uninstall`) against the cask generated by + # the source build, with the live GitHub release URL it points + # at. This is the moment when the URL is actually reachable — + # the source-build prepare stage can only validate offline because + # the GitHub release for the version being built does not exist + # yet. Catches problems that would otherwise only surface to + # end users (or block Homebrew/homebrew-cask's autobump PR). # # Each job has its own skip flag (SkipGitHubTasks / SkipReleaseAssets / # SkipHomebrewValidation) so partial-failure re-runs can recover any @@ -1231,13 +1232,13 @@ extends: # propagated to the GH workflow as dry_run=true (keeps it from # creating tags/releases/PRs) and to the asset script (downloads and # verifies SHA512s but skips the gh release upload). HomebrewValidateJob - # also runs under DryRun, but uses LiveArchives validation mode instead - # of LiveRelease because the GitHub release assets do not exist yet. - # LiveArchives validates Ruby syntax, brew style, tap syntax, and - # `brew audit --cask --no-signing` without attempting to fetch the - # release URL. Non-dry runs use LiveRelease mode with full - # `brew audit --cask --online --signing` and real - # `brew install`/`brew uninstall`. + # also runs under DryRun — it does not publish anything, it only audits + # and `brew install`/`brew uninstall` against a public URL. If the + # release for the version being validated does not yet exist (DryRun, + # or a re-run after assets were already uploaded), the job is expected + # to surface that as a real failure rather than be silently skipped. + # This lets a release manager validate the full AzDO → GitHub path + # end-to-end without performing a real release. - stage: GitHubTasks displayName: 'Dispatch GitHub Release Tasks' # PrepareArtifacts is listed explicitly (in addition to Release) so the @@ -1471,20 +1472,19 @@ extends: ASPIRE_BOT_PRIVATE_KEY: $(aspire-bot-private-key) # Validate the generated Homebrew cask against the live GitHub - # release in non-dry runs. Runs `brew audit --cask --online - # --signing` and a real `brew install`/`brew uninstall` against the - # cask file produced by the source build. The cask URL points at + # release. Runs `brew audit --cask --online --signing` and a real + # `brew install`/`brew uninstall` against the cask file produced by + # the source build. The cask URL points at # github.com/microsoft/aspire/releases/download/v#{version}/..., so # the release for the version being built must already exist for - # LiveRelease validation to pass — normally that happens earlier in - # this stage via PublishReleaseAssetsJob. Dry-run uses LiveArchives - # because no release assets are uploaded. The dependsOn below is purely + # this job to pass — normally that happens earlier in this stage + # via PublishReleaseAssetsJob. The dependsOn below is purely # temporal; the cask artifact itself comes from the aspire-build # resource, not from PublishReleaseAssetsJob. Accepting 'Skipped' # alongside Succeeded lets you re-run with SkipReleaseAssets=true # against a previously uploaded release; if the release is missing - # in LiveRelease mode, the job is expected to fail loudly rather - # than be silently gated out. + # the job is expected to fail loudly rather than be silently + # gated out. # # Modeled on PublishReleaseAssetsJob (regular buildJob with checkout # + a `download: aspire-build` step) rather than WingetJob's @@ -1493,7 +1493,7 @@ extends: # and to consume an artifact from the source build — and 1ES PT's # releaseJob enforces `checkout: none`. - job: HomebrewValidateJob - displayName: 'Validate Homebrew Cask' + displayName: 'Validate Homebrew Cask against live release' dependsOn: PublishReleaseAssetsJob condition: | and( @@ -1523,14 +1523,8 @@ extends: exit 1 fi - validation_mode="LiveRelease" - if [[ '${{ parameters.DryRun }}' == 'true' ]]; then - validation_mode="LiveArchives" - fi - - echo "Homebrew validation mode: $validation_mode" "$(Build.SourcesDirectory)/eng/homebrew/validate-cask-artifact.sh" \ --cask-file "$cask_file" \ --channel stable \ - --validation-mode "$validation_mode" - displayName: '🟣Validate Homebrew cask' + --validation-mode LiveRelease + displayName: '🟣Validate cask against live GitHub release' diff --git a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs index 4c4b81abeb1..52ebfaed854 100644 --- a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs +++ b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs @@ -31,23 +31,6 @@ public async Task ValidatesNpmPublishPreconditionsBeforeNuGetPublish() nuGetPublishIndex); } - [Fact] - public async Task HomebrewDryRunUsesOfflineValidationMode() - { - var pipeline = await ReadRepoFileAsync("eng/pipelines/release-publish-nuget.yml"); - var homebrewJobIndex = FindRequiredText(pipeline, "job: HomebrewValidateJob"); - var validateScriptIndex = FindRequiredText(pipeline, "\"$(Build.SourcesDirectory)/eng/homebrew/validate-cask-artifact.sh\""); - var jobSetup = pipeline[homebrewJobIndex..validateScriptIndex]; - - Assert.Contains("validation_mode=\"LiveRelease\"", jobSetup); - Assert.Contains("'${{ parameters.DryRun }}' == 'true'", jobSetup); - Assert.Contains("validation_mode=\"LiveArchives\"", jobSetup); - - var validateScriptCall = pipeline[validateScriptIndex..Math.Min(pipeline.Length, validateScriptIndex + 500)]; - Assert.Contains("--validation-mode \"$validation_mode\"", validateScriptCall); - Assert.DoesNotContain("--validation-mode LiveRelease", validateScriptCall); - } - private static void AssertBefore(string contents, string text, int boundaryIndex) { var textIndex = FindRequiredText(contents, text); From 8f6007a6fb162b109a53546e61f0d5e762947da6 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Fri, 29 May 2026 14:07:31 -0400 Subject: [PATCH 17/35] Harden npm release validation Add ESRP publish-template and owner invariant coverage, live npm registry smoke validation before channel promotion, a pointer-publish skip for safe reruns, and npm-installed CLI update tests. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/release-process.md | 13 +- eng/pipelines/release-publish-nuget.yml | 321 ++++++++++++++++-- eng/scripts/verify-cli-npm-package.ps1 | 2 +- .../Commands/UpdateCommandTests.cs | 120 +++++++ .../CliUpdateNotificationServiceTests.cs | 52 +++ .../ReleasePublishNugetPipelineTests.cs | 57 ++++ 6 files changed, 540 insertions(+), 25 deletions(-) diff --git a/docs/release-process.md b/docs/release-process.md index 174b4f8185f..8bba0913b6b 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -83,13 +83,14 @@ Before starting a release: | `SkipNuGetPublish` | Set `true` if re-running after NuGet success. | `false` | | `SkipNpmPublish` | Set `true` if re-running after all npm packages are published. | `false` | | `SkipNpmRidPublish` | Set `true` if npm RID packages published but the pointer package did not. | `false` | + | `SkipNpmPointerPublish` | Set `true` if the pointer package published but a later validation or promotion step failed. Registry validation still runs. | `false` | | `SkipChannelPromotion` | Set `true` if re-running after darc success. | `false` | | `SkipWinGetPublish` | Set `true` if re-running after WinGet success. | `true` | | `SkipGitHubTasks` | Set `true` to skip dispatching the GH workflow. | `false` | | `SkipReleaseAssets` | Set `true` to skip uploading `aspire-cli-*` assets to the GitHub release. | `false` | | `SkipHomebrewValidation` | Set `true` if re-running after a successful Homebrew cask validation against the live GitHub release. | `false` | - | `NpmPublishOwners` | Comma-separated ESRP owner aliases or emails. Required when `DryRun` is `false` and npm publishing is not skipped. | `alias@microsoft.com` | - | `NpmPublishApprovers` | Comma-separated ESRP approver aliases or emails. Required when `DryRun` is `false` and npm publishing is not skipped. | `approver@microsoft.com` | + | `NpmPublishOwners` | Comma-separated ESRP owner aliases or emails. Required when `DryRun` is `false` and npm publishing is not skipped; must include `joperezr` and `ankj`. | `joperezr,ankj` | + | `NpmPublishApprovers` | Comma-separated ESRP approver aliases or emails. Required when `DryRun` is `false` and npm publishing is not skipped; must include `adamratzman` and must not overlap owners. | `adamratzman` | | `NpmRegistryPropagationDelayMinutes` | Delay between npm RID package and pointer package submissions. | `10` | | `GitHubTasksWorkflowRef` | Ref to load `release-github-tasks.yml` from when dispatching. Only affects the workflow source; the release branch and commit are passed via inputs. Override only when testing pipeline changes on a topic branch. | `main` | @@ -99,7 +100,7 @@ Before starting a release: 5. Click **Run** and monitor the pipeline. The final stage (`GitHubTasks`) dispatches `release-github-tasks.yml`, waits for it to complete, uploads the `aspire-cli-*` archives from the source build's `BlobArtifacts` onto the newly-created GitHub release, and validates the Homebrew cask against that live release. The AzDO pipeline only succeeds if the enabled GitHub tasks, asset upload, and Homebrew validation succeed. 6. Verify packages appear on NuGet.org and npm, and verify that the `aspire-cli-*` archives are attached to the GitHub release. -The npm release path validates Windows, Linux, and macOS install summaries, publishes the seven RID packages first, waits for ESRP completion, waits for the configured propagation delay, and then publishes the top-level `@microsoft/aspire-cli` pointer package. This avoids installing a pointer package whose optional RID dependencies are not visible yet. For prereleases, set `SkipNpmPublish=true` unless the npm publishing path has gained explicit non-`latest` dist-tag support. +The npm release path validates Windows, Linux, and macOS install summaries, publishes the seven RID packages first, waits for ESRP completion, waits for the configured propagation delay, and then publishes the top-level `@microsoft/aspire-cli` pointer package. After the pointer package publishes, the pipeline installs it from the live npm registry and runs `aspire --version` before channel promotion. This avoids installing a pointer package whose optional RID dependencies are not visible yet and catches registry propagation issues before the release is promoted. For prereleases, set `SkipNpmPublish=true` unless the npm publishing path has gained explicit non-`latest` dist-tag support. `commit_sha` and `release_branch` for the GitHub workflow are derived automatically from the source build resource, so there is no need to copy them by hand. @@ -157,6 +158,7 @@ Both automations are designed to be idempotent and safe to re-run. | Prepare/List npm Packages | Check that the selected source build produced all eight `microsoft-aspire-cli*.tgz` tarballs and matching `.tgz.sig` sidecars in `BlobArtifacts`. | | Push Packages to NuGet.org | Check NuGet.org for partial success, then re-run with already-completed steps skipped as needed. | | MicroBuild npm Publish | Check the ESRP release result. If RID packages published but the pointer package did not, re-run with `SkipNuGetPublish: true`, `SkipNpmRidPublish: true`, and `SkipChannelPromotion: true`; do not set `SkipNpmPublish` until the pointer package is published. | +| Validate Published npm Package from Registry | Confirm the pointer package is visible on npm and that `npm install -g @microsoft/aspire-cli@` works. If registry propagation is slow, re-run with completed publish steps skipped after the package is visible. | | Promote Build to Channel | Re-run with completed publish steps skipped. | | WinGet publishing / Homebrew validation | Re-run with the corresponding skip flags for completed work. | | GitHubTasks dispatch | Re-run with completed AzDO-side work skipped and `SkipGitHubTasks: false`; set `SkipReleaseAssets` according to whether release asset upload already completed. | @@ -181,7 +183,7 @@ Re-run with the corresponding `skip_*` input set to `true` to skip steps that ha ### 1ES and MicroBuild compliance -The AzDO pipeline extends the 1ES Official Pipeline Template (`v1/1ES.Official.PipelineTemplate.yml@1ESPipelineTemplates`) to be compliant with Microsoft organization requirements. It also consumes `MicroBuild.Publish.yml@MicroBuildTemplate` for npm submissions through ESRP. The source build creates, signs where platform signing applies, verifies, and stages the package artifacts; the release pipeline consumes those pre-built artifacts and does not rebuild or re-pack the CLI. +The AzDO pipeline extends the MicroBuild publish-enabled 1ES template (`azure-pipelines/1ES.Official.Publish.yml@MicroBuildTemplate`) to be compliant with Microsoft organization requirements and to grant `MicroBuild.Publish.yml@MicroBuildTemplate` access to the DevDiv ESRP service connection for npm submissions. The source build creates, signs where platform signing applies, verifies, and stages the package artifacts; the release pipeline consumes those pre-built artifacts and does not rebuild or re-pack the CLI. ### Variable groups @@ -236,6 +238,8 @@ If ESRP published the RID packages but failed before publishing `@microsoft/aspi 3. Set `SkipNpmRidPublish: true` and keep `SkipNpmPublish: false` so only the pointer package is submitted. 4. Set `SkipNpmPublish: true` only after the pointer package is visible. +If the pointer package published but the live npm registry validation failed afterward, re-run with `SkipNpmRidPublish: true`, `SkipNpmPointerPublish: true`, and `SkipNpmPublish: false` so the pipeline retries the install smoke without resubmitting already-published packages. + ### Tag already exists but points to different commit This indicates a mismatch between the expected release commit and an existing tag. Resolution: @@ -281,6 +285,7 @@ Azure DevOps release-publish-nuget.yml -> publish npm RID packages through MicroBuild.Publish -> wait for npm propagation -> publish npm pointer package through MicroBuild.Publish + -> install the pointer package from npm and run aspire --version -> promote BAR build to GA channel -> WinGetJob -> GitHubTasks diff --git a/eng/pipelines/release-publish-nuget.yml b/eng/pipelines/release-publish-nuget.yml index 84492a421bc..ab024408a70 100644 --- a/eng/pipelines/release-publish-nuget.yml +++ b/eng/pipelines/release-publish-nuget.yml @@ -63,6 +63,11 @@ parameters: type: boolean default: false + - name: SkipNpmPointerPublish + displayName: 'Skip npm Pointer Package Publishing (set true if pointer package already completed)' + type: boolean + default: false + - name: SkipChannelPromotion displayName: '[Advanced] Skip Channel Promotion (re-run after success)' type: boolean @@ -91,12 +96,12 @@ parameters: - name: NpmPublishOwners displayName: 'npm ESRP owners (comma-separated Microsoft aliases or emails)' type: string - default: '' + default: 'joperezr,ankj' - name: NpmPublishApprovers displayName: 'npm ESRP approvers (comma-separated Microsoft aliases or emails)' type: string - default: '' + default: 'adamratzman' - name: NpmRegistryPropagationDelayMinutes displayName: 'Minutes to wait between npm RID and pointer package submissions' @@ -125,10 +130,6 @@ variables: resources: repositories: - - repository: 1ESPipelineTemplates - type: git - name: 1ESPipelineTemplates/1ESPipelineTemplates - ref: refs/tags/release - repository: MicroBuildTemplate type: git name: 1ESPipelineTemplates/MicroBuildTemplate @@ -140,7 +141,7 @@ resources: trigger: none # Manual trigger only - no automatic releases extends: - template: v1/1ES.Official.PipelineTemplate.yml@1ESPipelineTemplates + template: azure-pipelines/1ES.Official.Publish.yml@MicroBuildTemplate parameters: pool: name: NetCore1ESPool-Internal @@ -648,6 +649,7 @@ extends: Write-Host "Skip NuGet Publish: ${{ parameters.SkipNuGetPublish }}" Write-Host "Skip npm Publish: ${{ parameters.SkipNpmPublish }}" Write-Host "Skip npm RID Publish: ${{ parameters.SkipNpmRidPublish }}" + Write-Host "Skip npm Pointer Publish: ${{ parameters.SkipNpmPointerPublish }}" Write-Host "Skip Channel Promotion: ${{ parameters.SkipChannelPromotion }}" Write-Host "Installer-only mode: ${{ and(eq(parameters.SkipNuGetPublish, true), eq(parameters.SkipNpmPublish, true), eq(parameters.SkipChannelPromotion, true)) }}" @@ -657,8 +659,43 @@ extends: exit 1 } + function ConvertTo-NpmReleaseAliasSet([string] $value, [string] $parameterName) { + $aliases = [System.Collections.Generic.HashSet[string]]::new([StringComparer]::OrdinalIgnoreCase) + + foreach ($entry in $value -split ',') { + $alias = $entry.Trim() + if ([string]::IsNullOrWhiteSpace($alias)) { + continue + } + + if ($alias.EndsWith('@microsoft.com', [StringComparison]::OrdinalIgnoreCase)) { + $alias = $alias.Substring(0, $alias.Length - '@microsoft.com'.Length) + } elseif ($alias.Contains('@')) { + Write-Error "$parameterName entry '$entry' must be a Microsoft alias or @microsoft.com email address." + exit 1 + } + + [void]$aliases.Add($alias.ToLowerInvariant()) + } + + return ,$aliases + } + + function Assert-ContainsRequiredNpmAliases( + [System.Collections.Generic.HashSet[string]] $actualAliases, + [string[]] $requiredAliases, + [string] $parameterName) { + $missing = @($requiredAliases | Where-Object { -not $actualAliases.Contains($_) }) + if ($missing.Count -gt 0) { + Write-Error "$parameterName must include required ESRP alias(es): $($missing -join ', ')." + exit 1 + } + } + $owners = "${{ parameters.NpmPublishOwners }}" $approvers = "${{ parameters.NpmPublishApprovers }}" + $requiredNpmOwners = @('joperezr', 'ankj') + $requiredNpmApprovers = @('adamratzman') if ([string]::IsNullOrWhiteSpace($owners)) { Write-Error "NpmPublishOwners must be set before publishing npm packages." @@ -670,7 +707,29 @@ extends: exit 1 } - Write-Host "npm ESRP owners and approvers were provided." + $normalizedOwners = ConvertTo-NpmReleaseAliasSet $owners 'NpmPublishOwners' + $normalizedApprovers = ConvertTo-NpmReleaseAliasSet $approvers 'NpmPublishApprovers' + + if ($normalizedOwners.Count -eq 0) { + Write-Error "NpmPublishOwners must contain at least one alias before publishing npm packages." + exit 1 + } + + if ($normalizedApprovers.Count -eq 0) { + Write-Error "NpmPublishApprovers must contain at least one alias before publishing npm packages." + exit 1 + } + + Assert-ContainsRequiredNpmAliases $normalizedOwners $requiredNpmOwners 'NpmPublishOwners' + Assert-ContainsRequiredNpmAliases $normalizedApprovers $requiredNpmApprovers 'NpmPublishApprovers' + + $overlappingAliases = @($normalizedOwners | Where-Object { $normalizedApprovers.Contains($_) }) + if ($overlappingAliases.Count -gt 0) { + Write-Error "NpmPublishOwners and NpmPublishApprovers must not contain the same alias(es): $($overlappingAliases -join ', ')." + exit 1 + } + + Write-Host "npm ESRP owners and approvers were provided and include the required release contacts." } Write-Host "===================================" @@ -838,6 +897,12 @@ extends: displayName: 'Skip NuGet Publish (flagged)' # ===== PUBLISH TO npm ===== + - ${{ if eq(parameters.SkipNpmPublish, false) }}: + - task: NodeTool@0 + displayName: 'Install Node.js for npm Validation' + inputs: + versionSpec: '22.x' + - ${{ if eq(parameters.SkipNpmPublish, false) }}: - powershell: | $ErrorActionPreference = 'Stop' @@ -987,14 +1052,72 @@ extends: Write-Host "Then the pipeline would wait ${{ parameters.NpmRegistryPropagationDelayMinutes }} minute(s) for registry propagation." } Write-Host "" - Write-Host "The pointer package would be submitted last:" - Get-ChildItem -Path "$(Pipeline.Workspace)/npm/pointer-package" -Filter "*.tgz" -File | ForEach-Object { - Write-Host " - $($_.Name)" + if ("${{ parameters.SkipNpmPointerPublish }}" -eq "true") { + Write-Host "Pointer package submission would be skipped because SkipNpmPointerPublish=true." + } else { + Write-Host "The pointer package would be submitted last:" + Get-ChildItem -Path "$(Pipeline.Workspace)/npm/pointer-package" -Filter "*.tgz" -File | ForEach-Object { + Write-Host " - $($_.Name)" + } } Write-Host "" Write-Host "=== DRY RUN - No npm packages were actually published ===" displayName: 'Dry Run - List npm Packages (No Publish)' + - pwsh: | + $ErrorActionPreference = 'Stop' + $pointerPackagePath = "$(Pipeline.Workspace)/npm/pointer-package" + $pointerPackages = @(Get-ChildItem -Path $pointerPackagePath -Filter "*.tgz" -File) + if ($pointerPackages.Count -ne 1) { + Write-Error "Expected exactly one npm pointer package in '$pointerPackagePath', found $($pointerPackages.Count)." + exit 1 + } + + $metadataRoot = Join-Path "$(Agent.TempDirectory)" "npm-pointer-package-$([Guid]::NewGuid().ToString('N'))" + New-Item -ItemType Directory -Path $metadataRoot -Force | Out-Null + try { + tar -xzf $pointerPackages[0].FullName -C $metadataRoot + if ($LASTEXITCODE -ne 0) { + Write-Error "Failed to extract pointer package '$($pointerPackages[0].FullName)'." + exit 1 + } + + $packageJsonPath = Join-Path $metadataRoot 'package/package.json' + if (!(Test-Path -LiteralPath $packageJsonPath)) { + Write-Error "Pointer package '$($pointerPackages[0].Name)' is missing package/package.json." + exit 1 + } + + $packageJson = Get-Content -Raw -LiteralPath $packageJsonPath | ConvertFrom-Json + $packageName = "$($packageJson.name)" + $packageVersion = "$($packageJson.version)" + if ([string]::IsNullOrWhiteSpace($packageName) -or [string]::IsNullOrWhiteSpace($packageVersion)) { + Write-Error "Pointer package '$($pointerPackages[0].Name)' must include name and version in package.json." + exit 1 + } + + $packageSpec = "$packageName@$packageVersion" + Write-Host "Dry-run registry smoke target: $packageSpec" + } + finally { + if (Test-Path -LiteralPath $metadataRoot) { + Remove-Item -LiteralPath $metadataRoot -Recurse -Force + } + } + + Write-Host "node version: $(node --version)" + Write-Host "npm version: $(npm --version)" + $pingOutput = npm ping --registry=https://registry.npmjs.org/ --loglevel=warn 2>&1 + if ($LASTEXITCODE -ne 0) { + Write-Host $pingOutput + Write-Error "Unable to reach https://registry.npmjs.org/ from the release job." + exit 1 + } + + Write-Host $pingOutput + Write-Host "Dry run skipped installing '$packageSpec' because the package has not been published." + displayName: 'Dry Run - Validate npm Registry Reachability' + - ${{ if and(eq(parameters.DryRun, false), eq(parameters.SkipNpmPublish, false), eq(parameters.IsPrerelease, false)) }}: - ${{ if eq(parameters.SkipNpmRidPublish, false) }}: - template: MicroBuild.Publish.yml@MicroBuildTemplate @@ -1023,15 +1146,170 @@ extends: Write-Host "Skipping npm RID package publish because SkipNpmRidPublish=true. The pointer package will still be submitted." displayName: 'Skip npm RID Publish (flagged)' - - template: MicroBuild.Publish.yml@MicroBuildTemplate - parameters: - intent: 'PackageDistribution' - contentType: 'npm' - contentSource: 'Folder' - folderLocation: '$(Pipeline.Workspace)\npm\pointer-package' - waitForReleaseCompletion: true - owners: '${{ parameters.NpmPublishOwners }}' - approvers: '${{ parameters.NpmPublishApprovers }}' + - ${{ if eq(parameters.SkipNpmPointerPublish, false) }}: + - template: MicroBuild.Publish.yml@MicroBuildTemplate + parameters: + intent: 'PackageDistribution' + contentType: 'npm' + contentSource: 'Folder' + folderLocation: '$(Pipeline.Workspace)\npm\pointer-package' + waitForReleaseCompletion: true + owners: '${{ parameters.NpmPublishOwners }}' + approvers: '${{ parameters.NpmPublishApprovers }}' + + - ${{ if eq(parameters.SkipNpmPointerPublish, true) }}: + - powershell: | + Write-Host "Skipping npm pointer package publish because SkipNpmPointerPublish=true. Registry validation will still install the selected source build's pointer package version from npm." + displayName: 'Skip npm Pointer Publish (flagged)' + + - pwsh: | + $ErrorActionPreference = 'Stop' + $pointerPackagePath = "$(Pipeline.Workspace)/npm/pointer-package" + $pointerPackages = @(Get-ChildItem -Path $pointerPackagePath -Filter "*.tgz" -File) + if ($pointerPackages.Count -ne 1) { + Write-Error "Expected exactly one npm pointer package in '$pointerPackagePath', found $($pointerPackages.Count)." + exit 1 + } + + $metadataRoot = Join-Path "$(Agent.TempDirectory)" "npm-pointer-package-$([Guid]::NewGuid().ToString('N'))" + New-Item -ItemType Directory -Path $metadataRoot -Force | Out-Null + try { + tar -xzf $pointerPackages[0].FullName -C $metadataRoot + if ($LASTEXITCODE -ne 0) { + Write-Error "Failed to extract pointer package '$($pointerPackages[0].FullName)'." + exit 1 + } + + $packageJsonPath = Join-Path $metadataRoot 'package/package.json' + if (!(Test-Path -LiteralPath $packageJsonPath)) { + Write-Error "Pointer package '$($pointerPackages[0].Name)' is missing package/package.json." + exit 1 + } + + $packageJson = Get-Content -Raw -LiteralPath $packageJsonPath | ConvertFrom-Json + $packageName = "$($packageJson.name)" + $packageVersion = "$($packageJson.version)" + if ([string]::IsNullOrWhiteSpace($packageName) -or [string]::IsNullOrWhiteSpace($packageVersion)) { + Write-Error "Pointer package '$($pointerPackages[0].Name)' must include name and version in package.json." + exit 1 + } + + $packageSpec = "$packageName@$packageVersion" + } + finally { + if (Test-Path -LiteralPath $metadataRoot) { + Remove-Item -LiteralPath $metadataRoot -Recurse -Force + } + } + + $npmRoot = Join-Path "$(Agent.TempDirectory)" "npm-registry-smoke-$([Guid]::NewGuid().ToString('N'))" + $npmPrefix = Join-Path $npmRoot 'prefix' + $npmCache = Join-Path $npmRoot 'cache' + New-Item -ItemType Directory -Path $npmPrefix -Force | Out-Null + New-Item -ItemType Directory -Path $npmCache -Force | Out-Null + + try { + $env:npm_config_prefix = $npmPrefix + $env:npm_config_cache = $npmCache + $env:npm_config_registry = 'https://registry.npmjs.org/' + + Write-Host "node version: $(node --version)" + Write-Host "npm version: $(npm --version)" + Write-Host "Validating published npm package from registry: $packageSpec" + + $pingOutput = npm ping --registry=https://registry.npmjs.org/ --loglevel=warn 2>&1 + if ($LASTEXITCODE -ne 0) { + Write-Host $pingOutput + Write-Error "Unable to reach https://registry.npmjs.org/ from the release job." + exit 1 + } + + $attempts = 10 + $delaySeconds = 30 + $available = $false + $lastViewOutput = $null + for ($attempt = 1; $attempt -le $attempts; $attempt++) { + Write-Host "Checking npm registry metadata for $packageSpec (attempt $attempt/$attempts)..." + $lastViewOutput = npm view $packageSpec version --registry=https://registry.npmjs.org/ --loglevel=warn 2>&1 + if ($LASTEXITCODE -eq 0) { + $viewVersion = @($lastViewOutput | ForEach-Object { "$_".Trim() } | Where-Object { $_ } | Select-Object -First 1) + if ($viewVersion -eq $packageVersion) { + $available = $true + break + } + } + + if ($attempt -lt $attempts) { + Write-Warning "npm registry has not returned $packageSpec yet. Retrying in $delaySeconds second(s)." + Start-Sleep -Seconds $delaySeconds + } + } + + if (!$available) { + Write-Host $lastViewOutput + Write-Error "npm registry did not return '$packageVersion' for '$packageSpec' after $attempts attempt(s)." + exit 1 + } + + $installed = $false + $lastInstallOutput = $null + for ($attempt = 1; $attempt -le $attempts; $attempt++) { + Write-Host "Installing $packageSpec from npm registry (attempt $attempt/$attempts)..." + $lastInstallOutput = npm install -g --foreground-scripts=true --no-audit --no-fund --loglevel=warn --registry=https://registry.npmjs.org/ $packageSpec 2>&1 + if ($LASTEXITCODE -eq 0) { + $installed = $true + break + } + + if ($attempt -lt $attempts) { + Write-Host $lastInstallOutput + Write-Warning "npm install failed while registry propagation may still be in progress. Retrying in $delaySeconds second(s)." + Start-Sleep -Seconds $delaySeconds + } + } + + if (!$installed) { + Write-Host $lastInstallOutput + Write-Error "Failed to install '$packageSpec' from npm registry after $attempts attempt(s)." + exit 1 + } + + Write-Host $lastInstallOutput + + $aspireCommand = if ($IsWindows) { + Join-Path $npmPrefix 'aspire.cmd' + } else { + Join-Path $npmPrefix 'bin/aspire' + } + + if (!(Test-Path -LiteralPath $aspireCommand)) { + Write-Error "npm install succeeded but the Aspire CLI command was not found at '$aspireCommand'." + exit 1 + } + + $versionOutput = & $aspireCommand --version 2>&1 + if ($LASTEXITCODE -ne 0) { + Write-Host $versionOutput + Write-Error "Installed Aspire CLI failed to run --version." + exit 1 + } + + $versionLine = @($versionOutput | ForEach-Object { "$_".Trim() } | Where-Object { $_ } | Select-Object -First 1) + $versionPattern = "^$([System.Text.RegularExpressions.Regex]::Escape($packageVersion))(\+.*)?$" + if ($versionLine -notmatch $versionPattern) { + Write-Host $versionOutput + Write-Error "Installed Aspire CLI version '$versionLine' did not match expected npm package version '$packageVersion'." + exit 1 + } + + Write-Host "aspire --version output matched the published npm package version: $versionLine" + } + finally { + if (Test-Path -LiteralPath $npmRoot) { + Remove-Item -LiteralPath $npmRoot -Recurse -Force + } + } + displayName: 'Validate Published npm Package from Registry' - ${{ if eq(parameters.SkipNpmPublish, true) }}: - powershell: | @@ -1134,10 +1412,13 @@ extends: Write-Host " (DRY RUN)" } elseif ("${{ parameters.IsPrerelease }}" -eq "true") { Write-Host " (BLOCKED - prerelease requires non-latest npm dist-tag support)" + } elseif ("${{ parameters.SkipNpmPointerPublish }}" -eq "true") { + Write-Host " (PARTIAL - pointer publish skipped; registry smoke still ran)" } else { Write-Host " (EXECUTED)" } Write-Host "║ npm RID Skip: ${{ parameters.SkipNpmRidPublish }}" + Write-Host "║ npm Ptr Skip: ${{ parameters.SkipNpmPointerPublish }}" Write-Host "║ Channel Promo: ${{ parameters.SkipChannelPromotion }}" -NoNewline if ("${{ parameters.SkipChannelPromotion }}" -eq "true") { Write-Host " (SKIPPED)" diff --git a/eng/scripts/verify-cli-npm-package.ps1 b/eng/scripts/verify-cli-npm-package.ps1 index c4abed09171..f9791a8d95c 100644 --- a/eng/scripts/verify-cli-npm-package.ps1 +++ b/eng/scripts/verify-cli-npm-package.ps1 @@ -130,7 +130,7 @@ $pointerPackage = Assert-SinglePackage ` Write-Step "RID package: $($ridPackage.Name)" Write-Step "Pointer package: $($pointerPackage.Name)" -$root = Join-Path ([System.IO.Path]::GetTempPath()) "aspire-cli-npm-package-$([System.IO.Path]::GetRandomFileName())" +$root = [System.IO.Directory]::CreateTempSubdirectory('aspire-cli-npm-package-').FullName $ridExtract = Join-Path $root 'rid' $pointerExtract = Join-Path $root 'pointer' $archiveExtract = Join-Path $root 'archive' diff --git a/tests/Aspire.Cli.Tests/Commands/UpdateCommandTests.cs b/tests/Aspire.Cli.Tests/Commands/UpdateCommandTests.cs index 1ca9bb6be7c..3aec58a16e8 100644 --- a/tests/Aspire.Cli.Tests/Commands/UpdateCommandTests.cs +++ b/tests/Aspire.Cli.Tests/Commands/UpdateCommandTests.cs @@ -631,6 +631,82 @@ public async Task UpdateCommand_WhenProjectUpdatedSuccessfullyAndRunningAsCustom Assert.Contains(interactionService.DisplayedPlainText, text => text.Contains($"dotnet tool update --tool-path \"{toolPath}\" Aspire.Cli", StringComparison.Ordinal)); } + [Fact] + public async Task UpdateCommand_WhenProjectUpdatedSuccessfullyAndRunningFromNpm_DisplaysNpmUpdateCommand() + { + using var workspace = TemporaryWorkspace.Create(outputHelper); + using var processPathScope = DotNetToolDetection.UseProcessPathForTesting("/home/test/.aspire/bin/aspire"); + using var npmScope = NpmInstallDetection.UseEnvironmentForTesting(CreateNpmInstallEnvironment()); + var interactionService = new TestInteractionService() + { + ConfirmCallback = (_, _) => true + }; + var downloaderInvoked = false; + + var services = CliTestHelper.CreateServiceCollection(workspace, outputHelper, options => + { + options.ProjectLocatorFactory = _ => new TestProjectLocator() + { + UseOrFindAppHostProjectFileAsyncCallback = (projectFile, _, _) => + { + return Task.FromResult(new FileInfo(Path.Combine(workspace.WorkspaceRoot.FullName, "AppHost.csproj"))); + } + }; + + options.InteractionServiceFactory = _ => interactionService; + options.DotNetCliRunnerFactory = _ => new TestDotNetCliRunner(); + + options.ProjectUpdaterFactory = _ => new TestProjectUpdater() + { + UpdateProjectAsyncCallback = (context, cancellationToken) => + { + return Task.FromResult(new ProjectUpdateResult { UpdatedApplied = true }); + } + }; + + options.PackagingServiceFactory = _ => new TestPackagingService() + { + GetChannelsAsyncCallback = (cancellationToken) => + { + var stableChannel = PackageChannel.CreateExplicitChannel( + "stable", + PackageChannelQuality.Stable, + new[] { new PackageMapping("Aspire*", "https://api.nuget.org/v3/index.json") }, + null!, + features: new TestFeatures(), + configureGlobalPackagesFolder: false, + cliDownloadBaseUrl: "https://aka.ms/dotnet/9/aspire/ga/daily"); + return Task.FromResult>(new[] { stableChannel }); + } + }; + + options.CliUpdateNotifierFactory = _ => new TestCliUpdateNotifier() + { + IsUpdateAvailableCallback = () => true + }; + + options.CliDownloaderFactory = _ => new TestCliDownloader(workspace.WorkspaceRoot) + { + DownloadLatestCliAsyncCallback = (_, _) => + { + downloaderInvoked = true; + return Task.FromResult(string.Empty); + } + }; + }); + + using var provider = services.BuildServiceProvider(); + var command = provider.GetRequiredService(); + var result = command.Parse("update --apphost AppHost.csproj"); + + var exitCode = await result.InvokeAsync().DefaultTimeout(); + + Assert.Equal(CliExitCodes.Success, exitCode); + Assert.False(downloaderInvoked, "Archive self-update should not be used for npm installs."); + Assert.Contains(interactionService.DisplayedPlainText, text => text.Contains("npm install -g @microsoft/aspire-cli@latest", StringComparison.Ordinal)); + Assert.DoesNotContain(interactionService.DisplayedPlainText, text => text.Contains("dotnet tool update", StringComparison.Ordinal)); + } + [Fact] public async Task UpdateCommand_WithoutAutoConfirmOption_UsesFalseConfirmationDefault() { @@ -811,6 +887,40 @@ public async Task UpdateCommand_SelfUpdate_WhenRunningAsNativeAotDotnetTool_Disp Assert.Contains(interactionService.DisplayedPlainText, text => text.Contains("dotnet tool update -g Aspire.Cli", StringComparison.Ordinal)); } + [Fact] + public async Task UpdateCommand_SelfUpdate_WhenRunningFromNpm_DisplaysNpmUpdateCommand() + { + using var workspace = TemporaryWorkspace.Create(outputHelper); + using var processPathScope = DotNetToolDetection.UseProcessPathForTesting("/home/test/.aspire/bin/aspire"); + using var npmScope = NpmInstallDetection.UseEnvironmentForTesting(CreateNpmInstallEnvironment()); + var interactionService = new TestInteractionService(); + var downloaderInvoked = false; + + var services = CliTestHelper.CreateServiceCollection(workspace, outputHelper, options => + { + options.InteractionServiceFactory = _ => interactionService; + options.CliDownloaderFactory = _ => new TestCliDownloader(workspace.WorkspaceRoot) + { + DownloadLatestCliAsyncCallback = (_, _) => + { + downloaderInvoked = true; + return Task.FromResult(string.Empty); + } + }; + }); + + using var provider = services.BuildServiceProvider(); + var command = provider.GetRequiredService(); + var result = command.Parse("update --self"); + + var exitCode = await result.InvokeAsync().DefaultTimeout(); + + Assert.Equal(CliExitCodes.Success, exitCode); + Assert.False(downloaderInvoked, "Archive self-update should not be used for npm installs."); + Assert.Contains(interactionService.DisplayedPlainText, text => text.Contains("npm install -g @microsoft/aspire-cli@latest", StringComparison.Ordinal)); + Assert.DoesNotContain(interactionService.DisplayedPlainText, text => text.Contains("dotnet tool update", StringComparison.Ordinal)); + } + [Fact] public async Task UpdateCommand_SelfUpdate_WhenRunningAsCustomToolPathDotnetTool_DisplaysToolPathUpdateCommand() { @@ -2539,6 +2649,16 @@ private static string GetAspireExecutableName() return OperatingSystem.IsWindows() ? "aspire.exe" : "aspire"; } + private static IReadOnlyDictionary CreateNpmInstallEnvironment() + { + return new Dictionary + { + [NpmInstallDetection.PackageEnvironmentVariableName] = NpmInstallDetection.ExpectedPackageName, + [NpmInstallDetection.PackageVersionEnvironmentVariableName] = "9.4.0", + [NpmInstallDetection.PackageRidEnvironmentVariableName] = "linux-x64" + }; + } + // `aspire update --self` no longer mutates the global identity channel via // IConfigurationService. The freshly extracted binary already carries its own channel // via [AssemblyMetadata("AspireCliChannel")], so the global write is dead weight and diff --git a/tests/Aspire.Cli.Tests/Utils/CliUpdateNotificationServiceTests.cs b/tests/Aspire.Cli.Tests/Utils/CliUpdateNotificationServiceTests.cs index 10cbbd35aeb..bbaf43295b1 100644 --- a/tests/Aspire.Cli.Tests/Utils/CliUpdateNotificationServiceTests.cs +++ b/tests/Aspire.Cli.Tests/Utils/CliUpdateNotificationServiceTests.cs @@ -331,6 +331,48 @@ public async Task NotifyIfUpdateAvailable_UsesAspireUpdateCommandForStandaloneAr Assert.Equal("aspire update", interactionService.LastVersionUpdateCommand); } + [Fact] + public async Task NotifyIfUpdateAvailable_UsesNpmCommandForNpmInstall() + { + using var workspace = TemporaryWorkspace.Create(outputHelper); + using var processPathScope = DotNetToolDetection.UseProcessPathForTesting("/home/test/.aspire/bin/aspire"); + using var npmScope = NpmInstallDetection.UseEnvironmentForTesting(CreateNpmInstallEnvironment()); + TestInteractionService? interactionService = null; + + var services = CliTestHelper.CreateServiceCollection(workspace, outputHelper, configure => + { + configure.NuGetPackageCacheFactory = _ => new FakeNuGetPackageCache + { + GetCliPackagesAsyncCallback = (_, _, _, _) => Task.FromResult>([ + new NuGetPackage { Id = "Aspire.Cli", Version = "9.5.0", Source = "nuget.org" } + ]) + }; + + configure.InteractionServiceFactory = _ => + { + interactionService = new TestInteractionService(); + return interactionService; + }; + + configure.CliUpdateNotifierFactory = sp => + { + var logger = sp.GetRequiredService>(); + var nuGetPackageCache = sp.GetRequiredService(); + var service = sp.GetRequiredService(); + return new CliUpdateNotifierWithPackageVersionOverride("9.4.0", logger, nuGetPackageCache, service); + }; + }); + + using var provider = services.BuildServiceProvider(); + var notifier = provider.GetRequiredService(); + + await notifier.CheckForCliUpdatesAsync(workspace.WorkspaceRoot, CancellationToken.None).DefaultTimeout(); + notifier.NotifyIfUpdateAvailable(); + + Assert.NotNull(interactionService); + Assert.Equal("npm install -g @microsoft/aspire-cli@latest", interactionService.LastVersionUpdateCommand); + } + [Fact] public async Task StableWillNotRecommendUpdatingToPreview() { @@ -447,6 +489,16 @@ private static string GetAspireExecutableName() { return OperatingSystem.IsWindows() ? "aspire.exe" : "aspire"; } + + private static IReadOnlyDictionary CreateNpmInstallEnvironment() + { + return new Dictionary + { + [NpmInstallDetection.PackageEnvironmentVariableName] = NpmInstallDetection.ExpectedPackageName, + [NpmInstallDetection.PackageVersionEnvironmentVariableName] = "9.4.0", + [NpmInstallDetection.PackageRidEnvironmentVariableName] = "linux-x64" + }; + } } internal sealed class CliUpdateNotifierWithPackageVersionOverride(string currentVersion, ILogger logger, INuGetPackageCache nuGetPackageCache, IInteractionService interactionService) : CliUpdateNotifier(logger, nuGetPackageCache, interactionService) diff --git a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs index 52ebfaed854..be157e9ba9c 100644 --- a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs +++ b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs @@ -31,6 +31,63 @@ public async Task ValidatesNpmPublishPreconditionsBeforeNuGetPublish() nuGetPublishIndex); } + [Fact] + public async Task UsesEsrpPublishTemplateForNpmPublishing() + { + var pipeline = await ReadRepoFileAsync("eng/pipelines/release-publish-nuget.yml"); + + Assert.Contains("template: azure-pipelines/1ES.Official.Publish.yml@MicroBuildTemplate", pipeline); + Assert.DoesNotContain("template: v1/1ES.Official.PipelineTemplate.yml@1ESPipelineTemplates", pipeline); + } + + [Fact] + public async Task UsesRequiredNpmEsrpOwnersAndApprover() + { + var pipeline = await ReadRepoFileAsync("eng/pipelines/release-publish-nuget.yml"); + + Assert.Contains("default: 'joperezr,ankj'", pipeline); + Assert.Contains("default: 'adamratzman'", pipeline); + Assert.Contains("$requiredNpmOwners = @('joperezr', 'ankj')", pipeline); + Assert.Contains("$requiredNpmApprovers = @('adamratzman')", pipeline); + Assert.Contains("NpmPublishOwners and NpmPublishApprovers must not contain the same alias(es)", pipeline); + } + + [Fact] + public async Task ValidatesPublishedNpmPackageFromRegistryAfterPublish() + { + var pipeline = await ReadRepoFileAsync("eng/pipelines/release-publish-nuget.yml"); + var pointerPublishIndex = FindRequiredText(pipeline, "folderLocation: '$(Pipeline.Workspace)\\npm\\pointer-package'"); + var registryValidationIndex = FindRequiredText(pipeline, "npm install -g --foreground-scripts=true --no-audit --no-fund --loglevel=warn --registry=https://registry.npmjs.org/ $packageSpec"); + var channelPromotionIndex = FindRequiredText(pipeline, "# ===== PROMOTE TO CHANNEL ====="); + var nodeToolIndex = FindRequiredText(pipeline, "task: NodeTool@0"); + var dryRunReachabilityIndex = FindRequiredText(pipeline, "Dry Run - Validate npm Registry Reachability"); + var pointerSkipIndex = FindRequiredText(pipeline, "SkipNpmPointerPublish"); + + Assert.True( + pointerPublishIndex < registryValidationIndex, + "Expected registry validation to happen after the npm pointer package is published."); + + Assert.True( + registryValidationIndex < channelPromotionIndex, + "Expected registry validation to happen before channel promotion."); + + Assert.True( + nodeToolIndex < registryValidationIndex, + "Expected Node.js to be installed before registry validation uses npm."); + + Assert.True( + dryRunReachabilityIndex < registryValidationIndex, + "Expected dry-run registry reachability validation to exercise npm before the actual publish-only install smoke."); + + Assert.True( + pointerSkipIndex < registryValidationIndex, + "Expected pointer package publishing to be independently skippable so registry validation can be retried without republishing."); + + Assert.Contains("aspire --version output matched the published npm package version", pipeline); + Assert.Contains("npm view $packageSpec version --registry=https://registry.npmjs.org/", pipeline); + Assert.Contains("Registry validation will still install the selected source build's pointer package version from npm.", pipeline); + } + private static void AssertBefore(string contents, string text, int boundaryIndex) { var textIndex = FindRequiredText(contents, text); From 0d27405f1ca52b8038826bd4c02adce1dd24e178 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Fri, 29 May 2026 17:21:48 -0400 Subject: [PATCH 18/35] Use Corepack changes from PR 17630 Applies the dedicated Corepack pinning and Yarn cache seeding diff from microsoft/aspire#17630 instead of keeping a local source-build workaround on this branch. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/tests.yml | 37 +++- eng/pipelines/azure-pipelines-codeql.yml | 54 +++++- eng/pipelines/azure-pipelines-unofficial.yml | 45 ++++- eng/pipelines/azure-pipelines.yml | 45 ++++- eng/pipelines/common-variables.yml | 9 + .../templates/public-pipeline-template.yml | 9 + extension/CONTRIBUTING.MD | 40 +++- extension/Extension.proj | 13 +- extension/build.ps1 | 84 ++++++++- extension/build.sh | 61 +++++- extension/package.json | 1 + extension/scripts/prepareCorepackYarn.mjs | 173 ++++++++++++++++++ 12 files changed, 533 insertions(+), 38 deletions(-) create mode 100644 extension/scripts/prepareCorepackYarn.mjs diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 0e07409471b..ee6d4d513da 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -312,6 +312,9 @@ jobs: extension_tests_win: name: Run VS Code extension tests (Windows) runs-on: windows-latest + env: + NPM_REGISTRY: https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public-npm/npm/registry/ + COREPACK_ENABLE_DOWNLOAD_PROMPT: 0 defaults: run: working-directory: ./extension @@ -322,17 +325,43 @@ jobs: uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0 with: node-version: '20.x' + - name: Install Corepack + run: | + $CorepackVersion = '0.34.7' + # The hosted Windows image already has a yarn shim in npm's global + # prefix. The npm Corepack package owns that shim too, so force only + # in CI where the tool install is isolated to this ephemeral job. + npm install --global --force --registry "$env:NPM_REGISTRY" "corepack@$CorepackVersion" + if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + + $npmGlobalBin = (npm prefix --global).Trim() + $env:PATH = "$npmGlobalBin$([IO.Path]::PathSeparator)$env:PATH" + $npmGlobalBin | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append + + $installed = (corepack --version).Trim() + if ($installed -ne $CorepackVersion) { + Write-Error "corepack version mismatch: expected $CorepackVersion, got '$installed'. The bundled Corepack on PATH may be taking precedence over the npm-global install." + exit 1 + } + + corepack enable + if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + + corepack prepare --activate + if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + + corepack yarn --version - name: Validate lockfile registries run: node -e "const fs = require('fs'); const lock = fs.readFileSync('yarn.lock', 'utf8'); if (/registry\\.(?:npmjs\\.org|yarnpkg\\.com)/.test(lock)) { throw new Error('extension/yarn.lock contains public npm registry URLs. Regenerate it using the internal dotnet-public-npm feed before restoring.'); }" - name: Install dependencies - run: yarn install --frozen-lockfile --non-interactive + run: corepack yarn install --frozen-lockfile --non-interactive - name: Run tests - run: yarn test + run: corepack yarn test - name: Override extension version for PR builds if: ${{ inputs.extensionVersionOverride != '' }} - run: yarn version --new-version "${{ inputs.extensionVersionOverride }}" --no-git-tag-version + run: corepack yarn version --new-version "${{ inputs.extensionVersionOverride }}" --no-git-tag-version - name: Package VSIX - run: yarn run vsce package --pre-release -o out/aspire-extension.vsix + run: corepack yarn run vsce package --pre-release -o out/aspire-extension.vsix - name: Upload VSIX uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0 with: diff --git a/eng/pipelines/azure-pipelines-codeql.yml b/eng/pipelines/azure-pipelines-codeql.yml index 5863fffbd4d..bd3ee48bb32 100644 --- a/eng/pipelines/azure-pipelines-codeql.yml +++ b/eng/pipelines/azure-pipelines-codeql.yml @@ -56,14 +56,60 @@ jobs: inputs: version: '20.x' + - task: npmAuthenticate@0 + displayName: NPM authenticate + inputs: + workingFile: $(Build.SourcesDirectory)\.npmrc + - task: PowerShell@2 - displayName: Install yarn + displayName: Set .npmrc environment + inputs: + targetType: 'inline' + script: Write-Host "##vso[task.setvariable variable=NPM_CONFIG_USERCONFIG]$(Build.SourcesDirectory)\.npmrc" + + - task: PowerShell@2 + displayName: Install Corepack inputs: targetType: 'inline' script: | - npm install -g yarn@1.22.22 - yarn --version - workingDirectory: '$(Build.SourcesDirectory)' + # Install the pinned Corepack shim. Keep this version in sync with + # COREPACK_VERSION in extension/build.sh and $CorepackVersion in + # extension/build.ps1. The Yarn release itself is pinned in + # extension/package.json via the `packageManager` field. + $CorepackVersion = '0.34.7' + $corepackHome = Join-Path '$(Agent.TempDirectory)' 'corepack' + $env:COREPACK_HOME = $corepackHome + Write-Host "##vso[task.setvariable variable=COREPACK_HOME]$corepackHome" + + # Hosted Windows images can already have yarn in npm's global prefix. + # The npm Corepack package owns that shim too, so force only in CI where + # the tool install is job-scoped. + npm install -g --force --registry "$env:NPM_REGISTRY" "corepack@$CorepackVersion" + if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + + $npmGlobalBin = (npm prefix --global).Trim() + $env:PATH = "$npmGlobalBin$([IO.Path]::PathSeparator)$env:PATH" + Write-Host "##vso[task.prependpath]$npmGlobalBin" + + # Verify the version actually on PATH matches our pin. On Windows the + # Node.js installer registers a `corepack.cmd` under + # %ProgramFiles%\nodejs which may shadow the npm-global shim under + # %APPDATA%\npm, so a successful `npm install -g corepack@` + # does NOT guarantee that subsequent `corepack` calls resolve to it. + $installed = (corepack --version).Trim() + if ($installed -ne $CorepackVersion) { + Write-Error "corepack version mismatch: expected $CorepackVersion, got '$installed'. The bundled Corepack on PATH may be taking precedence over the npm-global install." + exit 1 + } + + corepack enable + if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + + node ./scripts/prepareCorepackYarn.mjs + if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + + corepack yarn --version + workingDirectory: '$(Build.SourcesDirectory)\extension' - task: PowerShell@2 displayName: Install vsce diff --git a/eng/pipelines/azure-pipelines-unofficial.yml b/eng/pipelines/azure-pipelines-unofficial.yml index a1cfd1da5a1..31927e23436 100644 --- a/eng/pipelines/azure-pipelines-unofficial.yml +++ b/eng/pipelines/azure-pipelines-unofficial.yml @@ -212,13 +212,50 @@ extends: script: Write-Host "##vso[task.setvariable variable=NPM_CONFIG_USERCONFIG]$(Build.SourcesDirectory)\.npmrc" - task: PowerShell@2 - displayName: 🟣Install yarn + displayName: 🟣Install Corepack inputs: targetType: 'inline' script: | - npm install -g yarn@1.22.22 - yarn --version - workingDirectory: '$(Build.SourcesDirectory)' + # Install the pinned Corepack shim. Keep this version in + # sync with COREPACK_VERSION in extension/build.sh and + # $CorepackVersion in extension/build.ps1. The Yarn release + # itself is pinned in extension/package.json via the + # `packageManager` field. + $CorepackVersion = '0.34.7' + $corepackHome = Join-Path '$(Agent.TempDirectory)' 'corepack' + $env:COREPACK_HOME = $corepackHome + Write-Host "##vso[task.setvariable variable=COREPACK_HOME]$corepackHome" + + # Hosted Windows images can already have yarn in npm's + # global prefix. The npm Corepack package owns that shim too, + # so force only in CI where the tool install is job-scoped. + npm install -g --force --registry "$env:NPM_REGISTRY" "corepack@$CorepackVersion" + if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + + $npmGlobalBin = (npm prefix --global).Trim() + $env:PATH = "$npmGlobalBin$([IO.Path]::PathSeparator)$env:PATH" + Write-Host "##vso[task.prependpath]$npmGlobalBin" + + # Verify the version actually on PATH matches our pin. On + # Windows the Node.js installer registers a `corepack.cmd` + # under %ProgramFiles%\nodejs which may shadow the + # npm-global shim under %APPDATA%\npm, so a successful + # `npm install -g corepack@` does NOT guarantee + # that subsequent `corepack` calls resolve to it. + $installed = (corepack --version).Trim() + if ($installed -ne $CorepackVersion) { + Write-Error "corepack version mismatch: expected $CorepackVersion, got '$installed'. The bundled Corepack on PATH may be taking precedence over the npm-global install." + exit 1 + } + + corepack enable + if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + + node ./scripts/prepareCorepackYarn.mjs + if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + + corepack yarn --version + workingDirectory: '$(Build.SourcesDirectory)\extension' - task: PowerShell@2 displayName: 🟣Install vsce diff --git a/eng/pipelines/azure-pipelines.yml b/eng/pipelines/azure-pipelines.yml index dc166eadb8a..dd02b596019 100644 --- a/eng/pipelines/azure-pipelines.yml +++ b/eng/pipelines/azure-pipelines.yml @@ -301,13 +301,50 @@ extends: script: Write-Host "##vso[task.setvariable variable=NPM_CONFIG_USERCONFIG]$(Build.SourcesDirectory)\.npmrc" - task: PowerShell@2 - displayName: 🟣Install yarn + displayName: 🟣Install Corepack inputs: targetType: 'inline' script: | - npm install -g yarn@1.22.22 - yarn --version - workingDirectory: '$(Build.SourcesDirectory)' + # Install the pinned Corepack shim. Keep this version in + # sync with COREPACK_VERSION in extension/build.sh and + # $CorepackVersion in extension/build.ps1. The Yarn release + # itself is pinned in extension/package.json via the + # `packageManager` field. + $CorepackVersion = '0.34.7' + $corepackHome = Join-Path '$(Agent.TempDirectory)' 'corepack' + $env:COREPACK_HOME = $corepackHome + Write-Host "##vso[task.setvariable variable=COREPACK_HOME]$corepackHome" + + # Hosted Windows images can already have yarn in npm's + # global prefix. The npm Corepack package owns that shim too, + # so force only in CI where the tool install is job-scoped. + npm install -g --force --registry "$env:NPM_REGISTRY" "corepack@$CorepackVersion" + if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + + $npmGlobalBin = (npm prefix --global).Trim() + $env:PATH = "$npmGlobalBin$([IO.Path]::PathSeparator)$env:PATH" + Write-Host "##vso[task.prependpath]$npmGlobalBin" + + # Verify the version actually on PATH matches our pin. On + # Windows the Node.js installer registers a `corepack.cmd` + # under %ProgramFiles%\nodejs which may shadow the + # npm-global shim under %APPDATA%\npm, so a successful + # `npm install -g corepack@` does NOT guarantee + # that subsequent `corepack` calls resolve to it. + $installed = (corepack --version).Trim() + if ($installed -ne $CorepackVersion) { + Write-Error "corepack version mismatch: expected $CorepackVersion, got '$installed'. The bundled Corepack on PATH may be taking precedence over the npm-global install." + exit 1 + } + + corepack enable + if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + + node ./scripts/prepareCorepackYarn.mjs + if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + + corepack yarn --version + workingDirectory: '$(Build.SourcesDirectory)\extension' - task: PowerShell@2 displayName: 🟣Install vsce diff --git a/eng/pipelines/common-variables.yml b/eng/pipelines/common-variables.yml index d5852f31656..30d5b0cbcc0 100644 --- a/eng/pipelines/common-variables.yml +++ b/eng/pipelines/common-variables.yml @@ -10,6 +10,15 @@ variables: - name: _InternalBuildArgs value: '' + # npm global installs and the Corepack Yarn cache seeder don't use the repo + # .npmrc, so pass this registry explicitly. + - name: NPM_REGISTRY + value: https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public-npm/npm/registry/ + # Disable the interactive "Do you want to download yarn@x.y.z?" prompt so + # pipeline steps don't hang waiting for stdin. + - name: COREPACK_ENABLE_DOWNLOAD_PROMPT + value: '0' + - ${{ if notin(variables['Build.Reason'], 'PullRequest') }}: - name: _RunAsPublic value: False diff --git a/eng/pipelines/templates/public-pipeline-template.yml b/eng/pipelines/templates/public-pipeline-template.yml index e560f93ed19..e200857acde 100644 --- a/eng/pipelines/templates/public-pipeline-template.yml +++ b/eng/pipelines/templates/public-pipeline-template.yml @@ -32,6 +32,15 @@ variables: - name: _InternalBuildArgs value: '' + # npm global installs and the Corepack Yarn cache seeder don't use the repo + # .npmrc, so pass this registry explicitly. + - name: NPM_REGISTRY + value: https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public-npm/npm/registry/ + # Disable the interactive "Do you want to download yarn@x.y.z?" prompt so + # pipeline steps don't hang waiting for stdin. + - name: COREPACK_ENABLE_DOWNLOAD_PROMPT + value: '0' + # Set test variants based on parameter or build reason - ${{ if ne(parameters.testVariants, '') }}: - name: testVariants diff --git a/extension/CONTRIBUTING.MD b/extension/CONTRIBUTING.MD index 41e9a739728..905192acca0 100644 --- a/extension/CONTRIBUTING.MD +++ b/extension/CONTRIBUTING.MD @@ -2,8 +2,11 @@ ## Install Prerequisites -- Node.js (LTS version) -- Yarn accessible in the PATH +- Node.js (LTS version) — `npm` must be on the PATH (it ships with Node.js). The + build scripts (`build.sh` / `build.ps1`) install a pinned [Corepack](https://github.com/nodejs/corepack) + via `npm install -g corepack@` from the configured registry and seed + Corepack's cache with the Yarn release pinned by the `packageManager` field in + `extension/package.json`. You do **not** need to install Yarn yourself. - Visual Studio Code (latest) or Visual Studio Code Insiders - [Aspire CLI](https://aspire.dev/get-started/install-cli/) must be installed and available in the PATH @@ -26,12 +29,39 @@ You can use the `Aspire: Extension settings` command to open VS Code settings di ## Updating dependency overrides -The extension is built with **yarn**, so `package.json` uses `resolutions` for transitive dependency pins and `yarn.lock` is the authoritative lockfile. +The extension is built with **yarn**, pinned to the version recorded in `packageManager` of `package.json`. `package.json` uses `resolutions` for transitive dependency pins and `yarn.lock` is the authoritative lockfile. When pinning a transitive dependency (e.g. to address a security advisory), add the pin to `resolutions` and regenerate `yarn.lock` in the same change: ```bash -yarn install +corepack yarn install ``` -The build rejects public npm registry URLs in `yarn.lock`; ensure regenerated entries resolve through the internal `dotnet-public-npm` feed. \ No newline at end of file +The build rejects public npm registry URLs in `yarn.lock`; ensure regenerated entries resolve through the internal `dotnet-public-npm` feed. + +## Updating the Yarn version + +Edit the `"packageManager": "yarn@x.y.z"` field in `extension/package.json`. The next `build.sh` / `build.ps1` run seeds Corepack's cache with that version before calling `corepack yarn …`. No further changes are required in `build.sh`, `build.ps1`, or `extension/Extension.proj`. + +> **Heads up about the internal npm mirror.** The repo's `.npmrc` and the build scripts' `NPM_REGISTRY` default route npm package downloads through the dnceng `dotnet-public-npm` Azure Artifacts feed, which is a pull-through cache of npmjs.org. The first time anyone asks the feed for a version that has never been requested, the feed has to fetch it from npmjs.org — and anonymous pull-through fetches fail with HTTP 401. Subsequent anonymous reads work fine. If you bump the pinned Corepack or Yarn version, pre-seed the feed with credentials using `npm install --global --registry https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public-npm/npm/registry/ corepack@` or `npm pack --registry https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public-npm/npm/registry/ yarn@`. Do not point `COREPACK_NPM_REGISTRY` at this Azure Artifacts feed for Yarn: Corepack requests the `//` npm metadata route, and Azure Artifacts returns 404 for that route even when the package and tarball exist. + +## Troubleshooting + +### `EACCES` from `npm install --global` on Linux/macOS + +The build scripts run `npm install --global corepack@` to pin the Corepack version. On systems where Node.js is installed from a package manager (apt, yum, the official `.pkg`), the npm global prefix is typically `/usr/lib/node_modules` or `/usr/local/lib/node_modules`, which is root-owned. The install will fail with `EACCES`. The cleanest fix is to use a Node version manager that puts the npm prefix in your home directory: + +- [`nvm`](https://github.com/nvm-sh/nvm) — installs Node and configures the npm prefix automatically. +- [`fnm`](https://github.com/Schniz/fnm), [`asdf`](https://asdf-vm.com/), [`volta`](https://volta.sh/) — same idea, different tradeoffs. + +Alternatively, point npm at a user-writable prefix without changing your Node install: + +```bash +mkdir -p ~/.npm-global +npm config set prefix ~/.npm-global +export PATH="$HOME/.npm-global/bin:$PATH" # add to ~/.bashrc or ~/.zshrc +``` + +### `corepack version mismatch` from `build.sh` / `build.ps1` + +This means the `corepack` resolved from `PATH` is not the one we just installed via `npm install -g`. Most often the system Node install (`/usr/bin/corepack`, `%ProgramFiles%\nodejs\corepack.cmd`) is sitting in front of the npm global bin directory. On Windows, ensure `%APPDATA%\npm` comes before `%ProgramFiles%\nodejs` on `PATH`. On Linux/macOS, follow the `EACCES` remediation above and the npm prefix will be on `PATH` ahead of the system Node directory. diff --git a/extension/Extension.proj b/extension/Extension.proj index 5436af60c54..1a7c6149d4c 100644 --- a/extension/Extension.proj +++ b/extension/Extension.proj @@ -31,13 +31,13 @@ - - - + + @@ -88,12 +88,15 @@ - + + - + diff --git a/extension/build.ps1 b/extension/build.ps1 index ccd4be4305b..95d8ca90df9 100644 --- a/extension/build.ps1 +++ b/extension/build.ps1 @@ -2,6 +2,27 @@ $ErrorActionPreference = "Stop" +# Pinned Corepack shim version. Node.js >= 16.10 bundles a Corepack, but the +# bundled version drifts with each Node release and Corepack is on track to be +# unbundled from Node entirely (see https://github.com/nodejs/node/issues/54647). +# Installing a pinned Corepack from npm makes the build reproducible regardless +# of which Node version a developer or CI runner happens to have. +$CorepackVersion = "0.34.7" + +# Yarn version is pinned in extension/package.json via the "packageManager" +# field, which scripts/prepareCorepackYarn.mjs uses to seed Corepack's cache. + +# Point npm at the dnceng internal npm mirror when installing the pinned Corepack +# shim and seeding Corepack's Yarn cache. npm global installs do not use the +# project .npmrc, so pass the registry explicitly. Override locally with +# `$env:NPM_REGISTRY = ''; ./build.ps1`. +if (-not $env:NPM_REGISTRY) { + $env:NPM_REGISTRY = "https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public-npm/npm/registry/" +} +if (-not $env:COREPACK_ENABLE_DOWNLOAD_PROMPT) { + $env:COREPACK_ENABLE_DOWNLOAD_PROMPT = "0" +} + Write-Host "Checking prerequisites..." # Check for Node.js @@ -10,9 +31,10 @@ if (-not (Get-Command node -ErrorAction SilentlyContinue)) { exit 1 } -# Check for Corepack so the build uses the Yarn Classic version that matches extension/yarn.lock. -if (-not (Get-Command corepack -ErrorAction SilentlyContinue)) { - Write-Error "Error: Corepack is not installed. Please install a Node.js version that includes Corepack." +# npm is required to install our pinned Corepack. It ships with every official +# Node.js distribution, so this should only fail on broken installs. +if (-not (Get-Command npm -ErrorAction SilentlyContinue)) { + Write-Error "Error: npm is not available. Reinstall Node.js so npm is on PATH." exit 1 } @@ -35,12 +57,62 @@ if (-not (Get-Command dotnet -ErrorAction SilentlyContinue)) { Write-Host "All prerequisites satisfied." -# Ensure we run from the extension directory +# Ensure we run from the extension directory so corepack/yarn pick up +# extension/.npmrc and extension/package.json (which holds the packageManager pin). Set-Location $PSScriptRoot +Write-Host "" +Write-Host "Installing pinned Corepack $CorepackVersion..." +# Reinstall every time so we overwrite any older Corepack shim that Node.js +# may have placed on PATH ahead of npm's global prefix. npm global installs do +# not use the project .npmrc, so pass the registry explicitly. +npm install --global --registry "$env:NPM_REGISTRY" "corepack@$CorepackVersion" + +if ($LASTEXITCODE -ne 0) { + Write-Error "npm install -g corepack@$CorepackVersion failed with exit code $LASTEXITCODE" + exit $LASTEXITCODE +} + +# Verify the version actually on PATH matches our pin. On Windows the Node.js +# installer registers a `corepack.cmd` under %ProgramFiles%\nodejs which may +# shadow the npm-global shim under %APPDATA%\npm, so a successful +# `npm install -g corepack@` does NOT guarantee that subsequent +# `corepack` calls resolve to it. Fail loudly here so we don't silently run +# with the wrong tool. +$installedCorepack = $null +try { $installedCorepack = (corepack --version).Trim() } catch { } +if ($installedCorepack -ne $CorepackVersion) { + Write-Error @" +corepack version mismatch: expected $CorepackVersion, got '$installedCorepack'. +The bundled Corepack on PATH may be taking precedence over the npm-global install. +Ensure your npm global bin directory (typically %APPDATA%\npm on Windows) comes +before %ProgramFiles%\nodejs on PATH, or run `corepack disable` to remove the +bundled shim before re-running this script. +"@ + exit 1 +} + +Write-Host "" +Write-Host "Enabling Corepack package manager shims..." +corepack enable + +if ($LASTEXITCODE -ne 0) { + Write-Error "corepack enable failed with exit code $LASTEXITCODE" + exit $LASTEXITCODE +} + +Write-Host "" +Write-Host "Preparing Yarn from packageManager pin in package.json..." +node ./scripts/prepareCorepackYarn.mjs + +if ($LASTEXITCODE -ne 0) { + Write-Error "Preparing Yarn for Corepack failed with exit code $LASTEXITCODE" + exit $LASTEXITCODE +} + Write-Host "" Write-Host "Running yarn install..." -corepack yarn@1.22.22 install --frozen-lockfile --non-interactive +corepack yarn install --frozen-lockfile --non-interactive if ($LASTEXITCODE -ne 0) { Write-Error "yarn install failed with exit code $LASTEXITCODE" @@ -49,7 +121,7 @@ if ($LASTEXITCODE -ne 0) { Write-Host "" Write-Host "Running yarn compile..." -corepack yarn@1.22.22 compile +corepack yarn compile if ($LASTEXITCODE -ne 0) { Write-Error "yarn compile failed with exit code $LASTEXITCODE" diff --git a/extension/build.sh b/extension/build.sh index 110967f4215..88c57a263c2 100755 --- a/extension/build.sh +++ b/extension/build.sh @@ -1,6 +1,24 @@ #!/bin/bash set -e +# Pinned Corepack shim version. Node.js >= 16.10 bundles a Corepack, but the +# bundled version drifts with each Node release and Corepack is on track to be +# unbundled from Node entirely (see https://github.com/nodejs/node/issues/54647). +# Installing a pinned Corepack from npm makes the build reproducible regardless +# of which Node version a developer or CI runner happens to have. +COREPACK_VERSION="0.34.7" + +# Yarn version is pinned in extension/package.json via the "packageManager" +# field, which scripts/prepareCorepackYarn.mjs uses to seed Corepack's cache. + +# Point npm at the dnceng internal npm mirror when installing the pinned Corepack +# shim and seeding Corepack's Yarn cache. npm global installs do not use the +# project .npmrc, so pass the registry explicitly. Override locally with +# `NPM_REGISTRY= ./build.sh`. +: "${NPM_REGISTRY:=https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public-npm/npm/registry/}" +: "${COREPACK_ENABLE_DOWNLOAD_PROMPT:=0}" +export COREPACK_ENABLE_DOWNLOAD_PROMPT + echo "Checking prerequisites..." # Check for Node.js @@ -9,9 +27,10 @@ if ! command -v node &> /dev/null; then exit 1 fi -# Check for Corepack so the build uses the Yarn Classic version that matches extension/yarn.lock. -if ! command -v corepack &> /dev/null; then - echo "Error: Corepack is not installed. Please install a Node.js version that includes Corepack." +# npm is required to install our pinned Corepack. It ships with every official +# Node.js distribution, so this should only fail on broken installs. +if ! command -v npm &> /dev/null; then + echo "Error: npm is not available. Reinstall Node.js so npm is on PATH." exit 1 fi @@ -31,17 +50,47 @@ fi echo "All prerequisites satisfied." -# Ensure we run from the extension directory +# Ensure we run from the extension directory so corepack/yarn pick up +# extension/.npmrc and extension/package.json (which holds the packageManager pin). SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" cd "$SCRIPT_DIR" +echo "" +echo "Installing pinned Corepack ${COREPACK_VERSION}..." +# Reinstall every time so we overwrite any older Corepack shim that Node.js +# may have placed on PATH ahead of npm's global prefix. npm global installs do +# not use the project .npmrc, so pass the registry explicitly. +npm install --global --registry "$NPM_REGISTRY" "corepack@${COREPACK_VERSION}" + +# Verify the version actually on PATH matches our pin. If a system-bundled +# Corepack shim shadows the npm-global install (common on Windows; possible on +# macOS/Linux when /usr/local/bin precedes the npm prefix), `npm install -g` +# can "succeed" while subsequent `corepack` calls still resolve to the bundled +# version. Fail loudly here so we don't silently run with the wrong tool. +installed_corepack=$(corepack --version 2>/dev/null || echo "") +if [ "$installed_corepack" != "$COREPACK_VERSION" ]; then + echo "Error: corepack version mismatch: expected $COREPACK_VERSION, got '$installed_corepack'." + echo "The bundled Corepack on PATH may be taking precedence over the npm-global install." + echo "Ensure your npm global bin directory comes before any other Node.js install on PATH," + echo "or use a Node version manager (nvm, asdf, fnm) that places the npm prefix appropriately." + exit 1 +fi + +echo "" +echo "Enabling Corepack package manager shims..." +corepack enable + +echo "" +echo "Preparing Yarn from packageManager pin in package.json..." +node ./scripts/prepareCorepackYarn.mjs + echo "" echo "Running yarn install..." -corepack yarn@1.22.22 install --frozen-lockfile --non-interactive +corepack yarn install --frozen-lockfile --non-interactive echo "" echo "Running yarn compile..." -corepack yarn@1.22.22 compile +corepack yarn compile echo "" echo "Building Aspire CLI..." diff --git a/extension/package.json b/extension/package.json index 095c39616c3..ab429f71ee6 100644 --- a/extension/package.json +++ b/extension/package.json @@ -13,6 +13,7 @@ "engines": { "vscode": "^1.98.0" }, + "packageManager": "yarn@1.22.22", "categories": [ "Programming Languages", "Debuggers", diff --git a/extension/scripts/prepareCorepackYarn.mjs b/extension/scripts/prepareCorepackYarn.mjs new file mode 100644 index 00000000000..3db5c641c21 --- /dev/null +++ b/extension/scripts/prepareCorepackYarn.mjs @@ -0,0 +1,173 @@ +#!/usr/bin/env node + +import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, renameSync, writeFileSync } from 'node:fs'; +import { dirname, join } from 'node:path'; +import { homedir, tmpdir } from 'node:os'; +import { spawnSync } from 'node:child_process'; +import { fileURLToPath } from 'node:url'; +import process from 'node:process'; + +const DefaultNpmRegistry = 'https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public-npm/npm/registry/'; +const PackageManagerPattern = /^yarn@(?\d+\.\d+\.\d+)$/; + +const scriptDirectory = dirname(fileURLToPath(import.meta.url)); +const extensionDirectory = dirname(scriptDirectory); +const packageJsonPath = join(extensionDirectory, 'package.json'); + +const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8')); +const packageManager = packageJson.packageManager; +const match = typeof packageManager === 'string' ? PackageManagerPattern.exec(packageManager) : null; + +if (match?.groups?.version === undefined) { + fail(`Expected packageManager in ${packageJsonPath} to be an exact Yarn Classic version like "yarn@1.22.22", but found ${JSON.stringify(packageManager)}.`); +} + +const yarnVersion = match.groups.version; +const majorVersion = Number(yarnVersion.split('.')[0]); + +if (majorVersion >= 2) { + fail(`The Corepack cache seeding workaround only supports Yarn Classic (<2.0.0), but packageManager is ${packageManager}. Remove this workaround and use Corepack's native prepare/install flow for Yarn Berry.`); +} + +const registry = process.env.NPM_REGISTRY || DefaultNpmRegistry; +const corepackHome = getCorepackHome(); +const installDirectory = join(corepackHome, 'v1', 'yarn', yarnVersion); +const installParentDirectory = dirname(installDirectory); +const corepackMetadataPath = join(installDirectory, '.corepack'); + +if (existsSync(corepackMetadataPath)) { + console.log(`Corepack cache already contains yarn@${yarnVersion} at ${installDirectory}`); + process.exit(0); +} + +rmSync(installDirectory, { recursive: true, force: true }); + +const temporaryDirectory = mkdtempSync(join(tmpdir(), 'aspire-corepack-yarn-')); +mkdirSync(installParentDirectory, { recursive: true }); +const stagingDirectory = mkdtempSync(join(installParentDirectory, `.yarn-${yarnVersion}-`)); +let cacheSeeded = false; + +try { + console.log(`Packing yarn@${yarnVersion} from ${registry}`); + const npm = getNpmInvocation(); + const packResult = run(npm.command, [...npm.args, 'pack', '--json', '--registry', registry, `yarn@${yarnVersion}`], temporaryDirectory); + const packEntries = parseNpmPackJson(packResult.stdout); + const packEntry = packEntries[0]; + + if (packEntry === undefined || typeof packEntry.filename !== 'string' || typeof packEntry.shasum !== 'string') { + fail(`npm pack did not return the expected filename and shasum metadata. Output: ${packResult.stdout}`); + } + + const tarballPath = join(temporaryDirectory, packEntry.filename); + + // Corepack can use COREPACK_NPM_REGISTRY for npmjs.org, but Azure Artifacts + // does not implement the // metadata route Corepack calls. + // Seed the same cache shape Corepack writes, using npm pack because npm can + // resolve Yarn through the Azure Artifacts pull-through feed. + run('tar', ['-xzf', tarballPath, '-C', stagingDirectory, '--strip-components=1'], temporaryDirectory); + + writeFileSync(corepackMetadataPathFor(stagingDirectory), JSON.stringify({ + locator: { + name: 'yarn', + reference: yarnVersion + }, + bin: { + yarn: './bin/yarn.js', + yarnpkg: './bin/yarn.js' + }, + hash: `sha1.${packEntry.shasum}` + })); + + try { + renameSync(stagingDirectory, installDirectory); + cacheSeeded = true; + } catch (error) { + if (error?.code === 'EEXIST') { + console.log(`Corepack cache already contains yarn@${yarnVersion} at ${installDirectory}`); + } else { + throw error; + } + } + + if (cacheSeeded) { + console.log(`Seeded Corepack cache with yarn@${yarnVersion} at ${installDirectory}`); + } +} finally { + rmSync(temporaryDirectory, { recursive: true, force: true }); + rmSync(stagingDirectory, { recursive: true, force: true }); +} + +function getCorepackHome() { + if (process.env.COREPACK_HOME) { + return process.env.COREPACK_HOME; + } + + const baseDirectory = process.env.XDG_CACHE_HOME + ?? process.env.LOCALAPPDATA + ?? join(homedir(), process.platform === 'win32' ? 'AppData/Local' : '.cache'); + + return join(baseDirectory, 'node', 'corepack'); +} + +function getNpmInvocation() { + if (process.platform !== 'win32') { + return { command: 'npm', args: [] }; + } + + const npmCliPath = join(dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js'); + + if (!existsSync(npmCliPath)) { + fail(`Could not find npm CLI at ${npmCliPath}. Corepack Yarn cache seeding requires the npm CLI that ships with Node.js.`); + } + + // Avoid spawning npm.cmd directly on Windows. Some hosted images reject the + // .cmd shim from child_process.spawnSync with EINVAL, while invoking the + // npm CLI through node.exe avoids shell/cmd parsing entirely. + return { command: process.execPath, args: [npmCliPath] }; +} + +function corepackMetadataPathFor(directory) { + return join(directory, '.corepack'); +} + +function parseNpmPackJson(stdout) { + const jsonStart = stdout.indexOf('['); + + if (jsonStart === -1) { + fail(`npm pack did not emit JSON output. Output: ${stdout}`); + } + + return JSON.parse(stdout.slice(jsonStart)); +} + +function run(command, args, cwd) { + const result = spawnSync(command, args, { + cwd, + encoding: 'utf8', + stdio: ['ignore', 'pipe', 'pipe'] + }); + + if (result.status !== 0) { + if (result.stdout) { + process.stderr.write(result.stdout); + } + + if (result.stderr) { + process.stderr.write(result.stderr); + } + + const errorDetails = result.error ? ` (${result.error.message})` : ''; + fail(`${command} ${args.join(' ')} failed with exit code ${result.status ?? 'unknown'}${errorDetails}.`); + } + + if (result.stderr) { + process.stderr.write(result.stderr); + } + + return result; +} + +function fail(message) { + console.error(message); + process.exit(1); +} From b6350b4651e8f90cff5fb469d77bfd78a55b28c3 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Fri, 29 May 2026 17:48:07 -0400 Subject: [PATCH 19/35] Address adversarial review findings - aspire.js: when the atomic rename of a freshly copied native binary fails (e.g. concurrent first-runs racing on Windows where the cached executable is already loaded), check whether the existing target is already a valid copy of the source via needsCopy(). If it is, the other process won the race and our tmp file can be discarded without failing the launcher. Only unexpected errors propagate. - release-publish-nuget.yml: wrap the post-smoke Remove-Item cleanup in the finally block in a try/catch with -ErrorAction Stop and a Write- Warning fallback so a transient Windows file-handle lock during temp- directory teardown does not mask a successful npm registry smoke test. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- eng/clipack/npm/aspire.js | 19 ++++++++++++++++--- eng/pipelines/release-publish-nuget.yml | 11 ++++++++++- 2 files changed, 26 insertions(+), 4 deletions(-) diff --git a/eng/clipack/npm/aspire.js b/eng/clipack/npm/aspire.js index 7e7382c151a..0ed373c28c8 100644 --- a/eng/clipack/npm/aspire.js +++ b/eng/clipack/npm/aspire.js @@ -104,12 +104,25 @@ function ensureCachedBinary(sourcePath, binaryName, version, rid) { fs.chmodSync(tempPath, 0o755); } - // Node's rename uses replace-existing semantics on all supported platforms. - // If the cached executable is still running on Windows, the rename fails and - // the previous cache entry remains usable instead of being deleted first. + // Node's rename uses replace-existing semantics on POSIX. On Windows, the + // rename fails with EBUSY/EPERM if the cached executable is currently + // running (e.g., another concurrent first-run already populated the cache + // and is executing it). When that happens, check whether the existing + // target is already a valid copy of the source - if it is, the other + // process won the race and our tmp can be discarded without failing the + // launcher. Any other error is unexpected and must propagate. try { fs.renameSync(tempPath, targetPath); } catch (error) { + try { + if (!needsCopy(sourcePath, targetPath)) { + fs.rmSync(tempPath, { force: true }); + return targetPath; + } + } catch { + // Fall through and rethrow the original rename error below. + } + fs.rmSync(tempPath, { force: true }); throw error; } diff --git a/eng/pipelines/release-publish-nuget.yml b/eng/pipelines/release-publish-nuget.yml index ab024408a70..571d58e839f 100644 --- a/eng/pipelines/release-publish-nuget.yml +++ b/eng/pipelines/release-publish-nuget.yml @@ -1306,7 +1306,16 @@ extends: } finally { if (Test-Path -LiteralPath $npmRoot) { - Remove-Item -LiteralPath $npmRoot -Recurse -Force + # Best-effort cleanup. On Windows, freshly extracted + # binaries may still be held open briefly by AV / file + # indexers, which can make Remove-Item throw EPERM / + # IOException. Swallow those so a successful smoke + # test isn't masked by a transient cleanup error. + try { + Remove-Item -LiteralPath $npmRoot -Recurse -Force -ErrorAction Stop + } catch { + Write-Warning "Best-effort cleanup of '$npmRoot' failed: $($_.Exception.Message)" + } } } displayName: 'Validate Published npm Package from Registry' From 727fe3ca9dcecbcc6d10d8b4373ae6f5779b25b4 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Fri, 29 May 2026 19:58:11 -0400 Subject: [PATCH 20/35] Make npm install validation script Bash 3.2 compatible The macOS AzDO runner executes Bash@3 tasks with /bin/bash which is still Bash 3.2 on every shipping macOS release. The 'Locate pointer and RID tarballs' step in 'npm install validation (macOS native RID)' was failing with: /Users/runner/work/_temp/.sh: line 10: shopt: globstar: invalid shell option name Bash exited with code '1'. Two constructs in the script require Bash 4+: - 'shopt -s globstar' (not in 3.2; we never used '**' anyway since we enumerate with 'find') - 'mapfile -t' (not in 3.2) Replace both with a portable 'find | while IFS= read' loop that works on Bash 3.2 and survives filenames containing spaces. Verified locally under GNU bash 3.2.57. Add a regression test in Infrastructure.Tests that fails the build if 'shopt -s globstar', 'mapfile', 'readarray', or 'declare -A' are reintroduced into the npm install validation template. Dry-run AzDO build 2987449 (Build def 1602) caught this on the macOS 'Prepare Installers' phase; linux-x64 and win-x64 are unaffected because their bash is already 4+. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../templates/prepare-npm-cli-packages.yml | 14 ++++++++++++-- .../ReleasePublishNugetPipelineTests.cs | 17 +++++++++++++++++ 2 files changed, 29 insertions(+), 2 deletions(-) diff --git a/eng/pipelines/templates/prepare-npm-cli-packages.yml b/eng/pipelines/templates/prepare-npm-cli-packages.yml index f57ad76aba3..bc5e157a399 100644 --- a/eng/pipelines/templates/prepare-npm-cli-packages.yml +++ b/eng/pipelines/templates/prepare-npm-cli-packages.yml @@ -65,8 +65,18 @@ steps: # microsoft-aspire-cli-.tgz (pointer package) # microsoft-aspire-cli--.tgz (RID package) # The pointer filename never embeds a RID, so distinguish them on that. - shopt -s globstar nullglob - mapfile -t allPackages < <(find "$packagesDir" -type f -name "microsoft-aspire-cli*.tgz" | sort -u) + # + # IMPORTANT: This script must stay portable to Bash 3.2 because the + # AzDO Bash@3 task on the macOS image executes scripts with /bin/bash + # which is still 3.2.x. That means: no extended-glob shell options + # (those are 4+), no array-load builtins (those are 4+), no associative + # arrays (4+). We therefore enumerate the tarballs with `find` (always + # available) and read them into a regular indexed array with a + # portable `while read` loop that survives names containing spaces. + allPackages=() + while IFS= read -r pkg; do + [ -n "$pkg" ] && allPackages+=("$pkg") + done < <(find "$packagesDir" -type f -name "microsoft-aspire-cli*.tgz" | LC_ALL=C sort -u) if [ ${#allPackages[@]} -eq 0 ]; then echo "##[error]No microsoft-aspire-cli*.tgz files found under $packagesDir" diff --git a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs index be157e9ba9c..eac3885215a 100644 --- a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs +++ b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs @@ -88,6 +88,23 @@ public async Task ValidatesPublishedNpmPackageFromRegistryAfterPublish() Assert.Contains("Registry validation will still install the selected source build's pointer package version from npm.", pipeline); } + [Fact] + public async Task PrepareNpmCliPackagesScriptIsBash32Compatible() + { + var template = await ReadRepoFileAsync("eng/pipelines/templates/prepare-npm-cli-packages.yml"); + + // macOS AzDO runners execute bash@3 tasks with /bin/bash which is still + // Bash 3.2 on every shipping macOS release. These constructs are Bash 4+ + // and silently break the install/uninstall smoke that gates the npm release. + // See dry-run build 2987449 where `shopt: globstar: invalid shell option name` + // killed `🟣Locate pointer and RID tarballs` on macOS. + Assert.DoesNotContain("shopt -s globstar", template); + Assert.DoesNotContain("mapfile ", template); + Assert.DoesNotContain("readarray ", template); + // declare -A (associative arrays) is also Bash 4+. + Assert.DoesNotContain("declare -A", template); + } + private static void AssertBefore(string contents, string text, int boundaryIndex) { var textIndex = FindRequiredText(contents, text); From 91de8c9d207a8391a945a648b931269e67ff1af2 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Fri, 29 May 2026 21:42:49 -0400 Subject: [PATCH 21/35] Accept SemVer 2.0 +buildmetadata in npm install validation Dry-run AzDO build 2987514 progressed past the macOS Bash 3.2 fix and then failed the install/verify/uninstall smoke on macOS with: Raw output: 13.5.0-preview.1.26279.34+727fe3ca9dcecbcc6d10d8b4373ae6f5779b25b4 Reported version: ##[error]aspire --version reported '' but expected '13.5.0-preview.1.26279.34' The CLI's --version prints the InformationalVersion which is full SemVer 2.0 (MAJOR.MINOR.PATCH-PRE+BUILDMETA where BUILDMETA is the source commit SHA). The previous regex required the line to end at the pre-release segment so the + suffix made the whole match fail and actualVersion became empty. Extend the regex to optionally accept '+', then strip it with the portable POSIX expansion '${var%+*}' before comparing to the npm package version (npm SemVer intentionally ignores build metadata for equality per https://semver.org/#spec-item-10). The PowerShell post-publish smoke in release-publish-nuget.yml already handles this case (line ~1298, regex ends with '(\\+.*)?$') so no change needed there. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../templates/prepare-npm-cli-packages.yml | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/eng/pipelines/templates/prepare-npm-cli-packages.yml b/eng/pipelines/templates/prepare-npm-cli-packages.yml index bc5e157a399..a14bab58d74 100644 --- a/eng/pipelines/templates/prepare-npm-cli-packages.yml +++ b/eng/pipelines/templates/prepare-npm-cli-packages.yml @@ -186,10 +186,22 @@ steps: # token so we are not thrown off by an incidental warn/info line printed before # or after the version (System.CommandLine's VersionOption normally just prints # the version and exits, but be defensive). + # + # The version we get from `aspire --version` is the InformationalVersion from + # the assembly, which the dotnet build embeds as SemVer 2.0 with build metadata + # appended after `+`. For example: + # 13.5.0-preview.1.26279.34+727fe3ca9dcecbcc6d10d8b4373ae6f5779b25b4 + # We accept this form and strip the `+` suffix before comparing to + # the npm package version, which intentionally drops build metadata because + # npm SemVer (npm/semver) doesn't honor it for equality. + # See https://semver.org/#spec-item-10 and https://github.com/npm/node-semver#advanced-range-syntax versionOutput="$(aspire --version 2>&1)" - actualVersion="$(printf '%s\n' "$versionOutput" | grep -Eo '^[0-9]+\.[0-9]+\.[0-9]+([.-][A-Za-z0-9._-]+)?$' | head -n 1 || true)" + versionLine="$(printf '%s\n' "$versionOutput" | grep -Eo '^[0-9]+\.[0-9]+\.[0-9]+([.-][A-Za-z0-9._-]+)?(\+[A-Za-z0-9._-]+)?$' | head -n 1 || true)" + # ${var%+*} strips the longest matching `+*` suffix. POSIX, works in Bash 3.2. + actualVersion="${versionLine%+*}" echo " Raw output: $versionOutput" - echo " Reported version: $actualVersion" + echo " Matched semver line: $versionLine" + echo " Comparable version (no +buildmeta): $actualVersion" if [ -z "$actualVersion" ] || [ "$actualVersion" != "$expectedVersion" ]; then echo "##[error]aspire --version reported '$actualVersion' but expected '$expectedVersion'" exit 1 From 67bc6b3453b466b00716030fcdf419ab35add193 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Fri, 29 May 2026 23:24:05 -0400 Subject: [PATCH 22/35] Skip npm registry resolution in CLI install validation to avoid 9m pool hang The pointer package declares every supported RID as an optionalDependency pinned to the just-built version. Even with --omit=optional, npm still resolves optional dep metadata from the registry while building the dependency tree, and in network-isolated 1ES Linux/Windows pools each of the 7 lookups burns the full fetch-timeout. Dry-run build 2987581 hit a 9-minute hang on the pointer install step for that reason while macOS (unrestricted egress, fast 404) completed in 3 seconds. Pair --omit=optional with --offline so npm never touches the network for this validation: optional deps are skipped without a resolution attempt and the local tarball installs straight from disk. A short --fetch-timeout=15000 is set as belt-and-suspenders. NPM_CONFIG_CACHE already points at a fresh empty directory so --offline cannot reuse a poisoned cache. Local verification against a synthetic 8-dep pointer shows installation completes in 121ms with optional deps marked UNMET (not fetched, not installed); uninstall completes in 88ms. Apply the same args to the uninstall step so an audit/funding call cannot hang the cleanup the way it almost hung the install. Add a PrepareNpmCliPackagesScriptInstallsOfflineWithTimeout regression test to prevent a refactor from quietly removing the flags. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../templates/prepare-npm-cli-packages.yml | 40 ++++++++++++++++--- .../ReleasePublishNugetPipelineTests.cs | 19 +++++++++ 2 files changed, 53 insertions(+), 6 deletions(-) diff --git a/eng/pipelines/templates/prepare-npm-cli-packages.yml b/eng/pipelines/templates/prepare-npm-cli-packages.yml index a14bab58d74..3eb382440ab 100644 --- a/eng/pipelines/templates/prepare-npm-cli-packages.yml +++ b/eng/pipelines/templates/prepare-npm-cli-packages.yml @@ -162,14 +162,39 @@ steps: # Install the RID package first so it lands as a top-level sibling of the # pointer package. Then install the pointer with --omit=optional so npm - # does not try to fetch the matching RID dep from the registry (the - # just-built version does not yet exist in the public registry during - # this validation step). + # does not install the matching RID dep from the registry (the just-built + # version does not yet exist in the public registry during this validation + # step). + # + # IMPORTANT: --omit=optional only prevents the *install* of an optional + # dep; npm still resolves its metadata from the registry while building + # the dependency tree. The pointer declares ALL 7 supported RIDs as + # optionalDependencies pinned to the just-built version, so on a network + # path that doesn't get a fast 404 (some 1ES Linux/Windows pools, where + # the npm registry call gets blackholed by network isolation rules), each + # of the 7 lookups burns the full --fetch-timeout. That's how the pointer + # install took 9m on Linux while only 3s on macOS during dry-run build + # 2987581. Pair --omit=optional with --offline so npm never touches the + # network for this validation: optional deps are skipped without a + # resolution attempt and the local tarball is installed straight from + # disk. A short --fetch-timeout is set as belt-and-suspenders in case any + # code path bypasses --offline (it should not, but if it does we'd rather + # fail in seconds than minutes). NPM_CONFIG_CACHE points at a fresh empty + # directory above, so --offline cannot accidentally use a poisoned cache. + npmInstallArgs=( + --foreground-scripts=false + --no-audit + --no-fund + --loglevel=warn + --offline + --fetch-timeout=15000 + ) + echo "Installing RID package..." - npm install -g --foreground-scripts=false --no-audit --no-fund --loglevel=warn "$ridTarball" + npm install -g "${npmInstallArgs[@]}" "$ridTarball" echo "Installing pointer package..." - npm install -g --foreground-scripts=false --no-audit --no-fund --loglevel=warn --omit=optional "$pointer" + npm install -g "${npmInstallArgs[@]}" --omit=optional "$pointer" echo "" echo "Verifying aspire CLI is available on PATH..." @@ -228,7 +253,10 @@ steps: echo "" echo "Uninstalling pointer and RID packages..." - npm uninstall -g --loglevel=warn '@microsoft/aspire-cli' "@microsoft/aspire-cli-${rid}" + # Reuse the offline/timeout-capped args so a stray audit/funding call + # on an isolated 1ES pool cannot hang the uninstall step the way it + # almost hung the install step. + npm uninstall -g "${npmInstallArgs[@]}" '@microsoft/aspire-cli' "@microsoft/aspire-cli-${rid}" if command -v aspire >/dev/null 2>&1; then echo "##[error]aspire command still on PATH after uninstall ($(command -v aspire))" diff --git a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs index eac3885215a..ecd57851e2c 100644 --- a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs +++ b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs @@ -105,6 +105,25 @@ public async Task PrepareNpmCliPackagesScriptIsBash32Compatible() Assert.DoesNotContain("declare -A", template); } + [Fact] + public async Task PrepareNpmCliPackagesScriptInstallsOfflineWithTimeout() + { + var template = await ReadRepoFileAsync("eng/pipelines/templates/prepare-npm-cli-packages.yml"); + + // The pointer package declares every supported RID as an optionalDependency + // pinned to the just-built version, which does not yet exist in the public + // npm registry. Even with --omit=optional, npm still resolves optional dep + // metadata while building the dep tree. In 1ES Linux/Windows pools the + // registry call is blackholed by network isolation rules and each of 7 + // lookups burns the full fetch-timeout — that's the 9-minute pointer install + // hang observed in dry-run build 2987581. Pair --omit=optional with --offline + // (no registry traffic at all) and cap any accidental fetch with a short + // --fetch-timeout. NPM_CONFIG_CACHE points at a fresh empty directory so + // --offline cannot reuse a poisoned cache. + Assert.Contains("--offline", template); + Assert.Contains("--fetch-timeout=", template); + } + private static void AssertBefore(string contents, string text, int boundaryIndex) { var textIndex = FindRequiredText(contents, text); From 7190d84519915f7406698ea11fc74f4f9aa322e0 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Sat, 30 May 2026 00:18:47 -0400 Subject: [PATCH 23/35] Resync Corepack changes with latest PR #17630 (head 0e2136ef) Re-imports the latest Corepack install template + pinned version + Yarn preparation script from the sibling PR. Required to share the same Corepack pin between the npm-publishing release pipeline and the extension build, and to keep Bash 3.2-safe wiring in place. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/tests.yml | 84 +++++++++++++++++++- .gitignore | 1 + eng/pipelines/azure-pipelines-codeql.yml | 44 +--------- eng/pipelines/azure-pipelines-unofficial.yml | 48 +---------- eng/pipelines/azure-pipelines.yml | 48 +---------- eng/pipelines/templates/install-corepack.yml | 55 +++++++++++++ extension/Extension.proj | 54 +++++++++++-- extension/build.ps1 | 42 ++++++++-- extension/build.sh | 45 +++++++++-- extension/scripts/corepack-version.txt | 1 + extension/scripts/prepareCorepackYarn.mjs | 58 ++++++++++++-- 11 files changed, 317 insertions(+), 163 deletions(-) create mode 100644 eng/pipelines/templates/install-corepack.yml create mode 100644 extension/scripts/corepack-version.txt diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index ee6d4d513da..6aacbfb4001 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -327,7 +327,15 @@ jobs: node-version: '20.x' - name: Install Corepack run: | - $CorepackVersion = '0.34.7' + # Scope Corepack's cache to this job so prepareCorepackYarn.mjs cannot + # collide with any other build sharing the runner's user profile. + # Cannot be set at job-level env: the `runner` context is unavailable + # in job env evaluation, so we forward it through $GITHUB_ENV instead. + $CorepackHome = Join-Path $env:RUNNER_TEMP 'corepack' + $env:COREPACK_HOME = $CorepackHome + "COREPACK_HOME=$CorepackHome" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append + + $CorepackVersion = (Get-Content -Raw -Path 'scripts/corepack-version.txt').Trim() # The hosted Windows image already has a yarn shim in npm's global # prefix. The npm Corepack package owns that shim too, so force only # in CI where the tool install is isolated to this ephemeral job. @@ -347,12 +355,27 @@ jobs: corepack enable if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } - corepack prepare --activate + # Seed Corepack's cache from the internal dnceng npm feed. Corepack's + # built-in `corepack prepare --activate` would download Yarn 1.x from + # registry.yarnpkg.com (hardcoded in Corepack 0.34's config.json and + # not redirectable via COREPACK_NPM_REGISTRY), bypassing the dnceng + # mirror this workflow is supposed to validate. The shared + # prepareCorepackYarn.mjs script does the equivalent via `npm pack` + # against $NPM_REGISTRY, then drops the same on-disk layout Corepack + # would have written. + node ./scripts/prepareCorepackYarn.mjs if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } corepack yarn --version - name: Validate lockfile registries - run: node -e "const fs = require('fs'); const lock = fs.readFileSync('yarn.lock', 'utf8'); if (/registry\\.(?:npmjs\\.org|yarnpkg\\.com)/.test(lock)) { throw new Error('extension/yarn.lock contains public npm registry URLs. Regenerate it using the internal dotnet-public-npm feed before restoring.'); }" + # Allowlist scoped to lines starting with "resolved" (the only lines in + # yarn.lock that carry a tarball URL — `npm:` aliases don't). + # CONTRIBUTING.MD asks contributors to regenerate yarn.lock through the + # internal dotnet-public-npm feed; an allowlist catches drift to any + # other public mirror (npmmirror.com, jsr.io, github.com tarballs, ...) + # rather than only npmjs.org and yarnpkg.com. + run: | + node -e "const fs = require('fs'); const allow = 'pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public-npm'; const bad = fs.readFileSync('yarn.lock', 'utf8').split(/\r?\n/).filter(l => /^\s*resolved\s+\x22/.test(l)).filter(l => !l.includes(allow)); if (bad.length) { throw new Error('extension/yarn.lock contains resolved entries outside the internal dotnet-public-npm feed. Regenerate it through the internal feed before restoring. First offender -> ' + bad[0]); }" - name: Install dependencies run: corepack yarn install --frozen-lockfile --non-interactive - name: Run tests @@ -368,6 +391,60 @@ jobs: name: aspire-extension path: extension/out/aspire-extension.vsix + extension_bootstrap_linux: + name: Validate VS Code extension bootstrap (Linux) + # Without this, the non-Windows code paths in + # extension/scripts/prepareCorepackYarn.mjs (npm invocation that does not go + # through node.exe, POSIX tar) are only exercised on contributor machines + # and never on a fresh CI image. extension_tests_win covers the Windows + # paths; this job covers Linux/macOS. macOS is omitted because the only + # platform-specific branch beyond Linux is the cache path, which is + # explicitly overridden via COREPACK_HOME in the build entrypoints. + runs-on: ubuntu-latest + env: + NPM_REGISTRY: https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public-npm/npm/registry/ + COREPACK_ENABLE_DOWNLOAD_PROMPT: 0 + defaults: + run: + working-directory: ./extension + steps: + - name: Checkout code + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + - name: Setup Node.js environment + uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0 + with: + node-version: '20.x' + - name: Install Corepack + run: | + set -euo pipefail + # Scope Corepack's cache to this job. Set via $GITHUB_ENV because the + # `runner` context is not available in job-level env evaluation. + export COREPACK_HOME="$RUNNER_TEMP/corepack" + echo "COREPACK_HOME=$COREPACK_HOME" >> "$GITHUB_ENV" + + CorepackVersion="$(tr -d '[:space:]' < scripts/corepack-version.txt)" + npm install --global --force --registry "$NPM_REGISTRY" "corepack@${CorepackVersion}" + + installed="$(corepack --version 2>/dev/null || true)" + if [ "$installed" != "$CorepackVersion" ]; then + echo "corepack version mismatch: expected $CorepackVersion, got '$installed'. The bundled Corepack on PATH may be taking precedence over the npm-global install." + exit 1 + fi + + corepack enable + - name: Seed Corepack Yarn cache via prepareCorepackYarn.mjs + # Exercises the script's non-Windows branches against a clean cache + # directory. Failing here means a contributor on Linux/macOS following + # CONTRIBUTING.MD would also be broken. + run: node ./scripts/prepareCorepackYarn.mjs + - name: Validate lockfile registries + # Mirror of the same allowlist guard in extension_tests_win so this + # cross-platform bootstrap also catches drift to a public-registry URL. + run: | + node -e "const fs = require('fs'); const allow = 'pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public-npm'; const bad = fs.readFileSync('yarn.lock', 'utf8').split(/\r?\n/).filter(l => /^\s*resolved\s+\x22/.test(l)).filter(l => !l.includes(allow)); if (bad.length) { throw new Error('extension/yarn.lock contains resolved entries outside the internal dotnet-public-npm feed. Regenerate it through the internal feed before restoring. First offender -> ' + bad[0]); }" + - name: Validate seeded cache via yarn install + run: corepack yarn install --frozen-lockfile --non-interactive + typescript_sdk_tests: name: TypeScript SDK Unit Tests uses: ./.github/workflows/typescript-sdk-tests.yml @@ -393,6 +470,7 @@ jobs: prepare_homebrew_installer_artifacts, build_cli_e2e_image, extension_tests_win, + extension_bootstrap_linux, cli_starter_validation_windows, typescript_sdk_tests, typescript_api_compat, diff --git a/.gitignore b/.gitignore index 60371d10272..edfd6e9b891 100644 --- a/.gitignore +++ b/.gitignore @@ -197,6 +197,7 @@ extension/dist/ extension/.localization/ extension/out/ extension/node_modules/ +extension/.corepack-cache/ **/.vscode-test/ extension/.version diff --git a/eng/pipelines/azure-pipelines-codeql.yml b/eng/pipelines/azure-pipelines-codeql.yml index bd3ee48bb32..273802c5170 100644 --- a/eng/pipelines/azure-pipelines-codeql.yml +++ b/eng/pipelines/azure-pipelines-codeql.yml @@ -67,49 +67,7 @@ jobs: targetType: 'inline' script: Write-Host "##vso[task.setvariable variable=NPM_CONFIG_USERCONFIG]$(Build.SourcesDirectory)\.npmrc" - - task: PowerShell@2 - displayName: Install Corepack - inputs: - targetType: 'inline' - script: | - # Install the pinned Corepack shim. Keep this version in sync with - # COREPACK_VERSION in extension/build.sh and $CorepackVersion in - # extension/build.ps1. The Yarn release itself is pinned in - # extension/package.json via the `packageManager` field. - $CorepackVersion = '0.34.7' - $corepackHome = Join-Path '$(Agent.TempDirectory)' 'corepack' - $env:COREPACK_HOME = $corepackHome - Write-Host "##vso[task.setvariable variable=COREPACK_HOME]$corepackHome" - - # Hosted Windows images can already have yarn in npm's global prefix. - # The npm Corepack package owns that shim too, so force only in CI where - # the tool install is job-scoped. - npm install -g --force --registry "$env:NPM_REGISTRY" "corepack@$CorepackVersion" - if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } - - $npmGlobalBin = (npm prefix --global).Trim() - $env:PATH = "$npmGlobalBin$([IO.Path]::PathSeparator)$env:PATH" - Write-Host "##vso[task.prependpath]$npmGlobalBin" - - # Verify the version actually on PATH matches our pin. On Windows the - # Node.js installer registers a `corepack.cmd` under - # %ProgramFiles%\nodejs which may shadow the npm-global shim under - # %APPDATA%\npm, so a successful `npm install -g corepack@` - # does NOT guarantee that subsequent `corepack` calls resolve to it. - $installed = (corepack --version).Trim() - if ($installed -ne $CorepackVersion) { - Write-Error "corepack version mismatch: expected $CorepackVersion, got '$installed'. The bundled Corepack on PATH may be taking precedence over the npm-global install." - exit 1 - } - - corepack enable - if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } - - node ./scripts/prepareCorepackYarn.mjs - if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } - - corepack yarn --version - workingDirectory: '$(Build.SourcesDirectory)\extension' + - template: /eng/pipelines/templates/install-corepack.yml - task: PowerShell@2 displayName: Install vsce diff --git a/eng/pipelines/azure-pipelines-unofficial.yml b/eng/pipelines/azure-pipelines-unofficial.yml index 31927e23436..6c6304582af 100644 --- a/eng/pipelines/azure-pipelines-unofficial.yml +++ b/eng/pipelines/azure-pipelines-unofficial.yml @@ -211,51 +211,9 @@ extends: targetType: 'inline' script: Write-Host "##vso[task.setvariable variable=NPM_CONFIG_USERCONFIG]$(Build.SourcesDirectory)\.npmrc" - - task: PowerShell@2 - displayName: 🟣Install Corepack - inputs: - targetType: 'inline' - script: | - # Install the pinned Corepack shim. Keep this version in - # sync with COREPACK_VERSION in extension/build.sh and - # $CorepackVersion in extension/build.ps1. The Yarn release - # itself is pinned in extension/package.json via the - # `packageManager` field. - $CorepackVersion = '0.34.7' - $corepackHome = Join-Path '$(Agent.TempDirectory)' 'corepack' - $env:COREPACK_HOME = $corepackHome - Write-Host "##vso[task.setvariable variable=COREPACK_HOME]$corepackHome" - - # Hosted Windows images can already have yarn in npm's - # global prefix. The npm Corepack package owns that shim too, - # so force only in CI where the tool install is job-scoped. - npm install -g --force --registry "$env:NPM_REGISTRY" "corepack@$CorepackVersion" - if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } - - $npmGlobalBin = (npm prefix --global).Trim() - $env:PATH = "$npmGlobalBin$([IO.Path]::PathSeparator)$env:PATH" - Write-Host "##vso[task.prependpath]$npmGlobalBin" - - # Verify the version actually on PATH matches our pin. On - # Windows the Node.js installer registers a `corepack.cmd` - # under %ProgramFiles%\nodejs which may shadow the - # npm-global shim under %APPDATA%\npm, so a successful - # `npm install -g corepack@` does NOT guarantee - # that subsequent `corepack` calls resolve to it. - $installed = (corepack --version).Trim() - if ($installed -ne $CorepackVersion) { - Write-Error "corepack version mismatch: expected $CorepackVersion, got '$installed'. The bundled Corepack on PATH may be taking precedence over the npm-global install." - exit 1 - } - - corepack enable - if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } - - node ./scripts/prepareCorepackYarn.mjs - if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } - - corepack yarn --version - workingDirectory: '$(Build.SourcesDirectory)\extension' + - template: /eng/pipelines/templates/install-corepack.yml + parameters: + displayPrefix: '🟣' - task: PowerShell@2 displayName: 🟣Install vsce diff --git a/eng/pipelines/azure-pipelines.yml b/eng/pipelines/azure-pipelines.yml index dd02b596019..a5545273899 100644 --- a/eng/pipelines/azure-pipelines.yml +++ b/eng/pipelines/azure-pipelines.yml @@ -300,51 +300,9 @@ extends: targetType: 'inline' script: Write-Host "##vso[task.setvariable variable=NPM_CONFIG_USERCONFIG]$(Build.SourcesDirectory)\.npmrc" - - task: PowerShell@2 - displayName: 🟣Install Corepack - inputs: - targetType: 'inline' - script: | - # Install the pinned Corepack shim. Keep this version in - # sync with COREPACK_VERSION in extension/build.sh and - # $CorepackVersion in extension/build.ps1. The Yarn release - # itself is pinned in extension/package.json via the - # `packageManager` field. - $CorepackVersion = '0.34.7' - $corepackHome = Join-Path '$(Agent.TempDirectory)' 'corepack' - $env:COREPACK_HOME = $corepackHome - Write-Host "##vso[task.setvariable variable=COREPACK_HOME]$corepackHome" - - # Hosted Windows images can already have yarn in npm's - # global prefix. The npm Corepack package owns that shim too, - # so force only in CI where the tool install is job-scoped. - npm install -g --force --registry "$env:NPM_REGISTRY" "corepack@$CorepackVersion" - if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } - - $npmGlobalBin = (npm prefix --global).Trim() - $env:PATH = "$npmGlobalBin$([IO.Path]::PathSeparator)$env:PATH" - Write-Host "##vso[task.prependpath]$npmGlobalBin" - - # Verify the version actually on PATH matches our pin. On - # Windows the Node.js installer registers a `corepack.cmd` - # under %ProgramFiles%\nodejs which may shadow the - # npm-global shim under %APPDATA%\npm, so a successful - # `npm install -g corepack@` does NOT guarantee - # that subsequent `corepack` calls resolve to it. - $installed = (corepack --version).Trim() - if ($installed -ne $CorepackVersion) { - Write-Error "corepack version mismatch: expected $CorepackVersion, got '$installed'. The bundled Corepack on PATH may be taking precedence over the npm-global install." - exit 1 - } - - corepack enable - if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } - - node ./scripts/prepareCorepackYarn.mjs - if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } - - corepack yarn --version - workingDirectory: '$(Build.SourcesDirectory)\extension' + - template: /eng/pipelines/templates/install-corepack.yml + parameters: + displayPrefix: '🟣' - task: PowerShell@2 displayName: 🟣Install vsce diff --git a/eng/pipelines/templates/install-corepack.yml b/eng/pipelines/templates/install-corepack.yml new file mode 100644 index 00000000000..efbaa0b7359 --- /dev/null +++ b/eng/pipelines/templates/install-corepack.yml @@ -0,0 +1,55 @@ +parameters: + # Prefix prepended to step displayNames (e.g. the 🟣 emoji used by the + # internal-1ES jobs in azure-pipelines.yml / azure-pipelines-unofficial.yml). + # Public/CodeQL pipelines omit it. Kept as a parameter so the displayName + # convention of each calling pipeline is preserved. + - name: displayPrefix + type: string + default: '' + +steps: + - task: PowerShell@2 + displayName: ${{ parameters.displayPrefix }}Install Corepack + inputs: + targetType: 'inline' + script: | + # Pinned Corepack shim version, sourced from + # extension/scripts/corepack-version.txt so this script, + # extension/build.sh, extension/build.ps1, the GitHub Actions + # workflow, and every AzDO pipeline that references this template + # stay in sync. The Yarn release itself is pinned in + # extension/package.json via the `packageManager` field. + $CorepackVersion = (Get-Content -Raw -Path '$(Build.SourcesDirectory)/extension/scripts/corepack-version.txt').Trim() + $corepackHome = Join-Path '$(Agent.TempDirectory)' 'corepack' + $env:COREPACK_HOME = $corepackHome + Write-Host "##vso[task.setvariable variable=COREPACK_HOME]$corepackHome" + + # Hosted Windows images can already have yarn in npm's global prefix. + # The npm Corepack package owns that shim too, so force only in CI + # where the tool install is job-scoped. + npm install -g --force --registry "$env:NPM_REGISTRY" "corepack@$CorepackVersion" + if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + + $npmGlobalBin = (npm prefix --global).Trim() + $env:PATH = "$npmGlobalBin$([IO.Path]::PathSeparator)$env:PATH" + Write-Host "##vso[task.prependpath]$npmGlobalBin" + + # Verify the version actually on PATH matches our pin. On Windows the + # Node.js installer registers a `corepack.cmd` under + # %ProgramFiles%\nodejs which may shadow the npm-global shim under + # %APPDATA%\npm, so a successful `npm install -g corepack@` + # does NOT guarantee that subsequent `corepack` calls resolve to it. + $installed = (corepack --version).Trim() + if ($installed -ne $CorepackVersion) { + Write-Error "corepack version mismatch: expected $CorepackVersion, got '$installed'. The bundled Corepack on PATH may be taking precedence over the npm-global install." + exit 1 + } + + corepack enable + if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + + node ./scripts/prepareCorepackYarn.mjs + if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + + corepack yarn --version + workingDirectory: '$(Build.SourcesDirectory)\extension' diff --git a/extension/Extension.proj b/extension/Extension.proj index 1a7c6149d4c..c6e350aad2b 100644 --- a/extension/Extension.proj +++ b/extension/Extension.proj @@ -2,6 +2,31 @@ $(DefaultTargetFramework) $(MSBuildThisFileDirectory) + + <_CorepackHome Condition="'$(COREPACK_HOME)' != ''">$(COREPACK_HOME) + <_CorepackHome Condition="'$(_CorepackHome)' == ''">$([MSBuild]::NormalizePath($(ExtensionSrcDir), '.corepack-cache')) @@ -33,11 +58,12 @@ Condition="'$(ExtensionVersionOverride)' != ''" /> - - + + @@ -70,6 +96,14 @@ <_YarnLockPath>$([MSBuild]::NormalizePath($(ExtensionSrcDir), 'yarn.lock')) + + <_AllowedNpmRegistryHost>pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public-npm @@ -79,24 +113,28 @@ - <_PublicNpmRegistryLine Include="@(_YarnLockLine)" Condition="$([System.String]::Copy('%(_YarnLockLine.Identity)').Contains('registry.npmjs.org')) Or $([System.String]::Copy('%(_YarnLockLine.Identity)').Contains('registry.yarnpkg.com'))" /> + <_YarnLockResolvedLine Include="@(_YarnLockLine)" Condition="$([System.String]::Copy('%(_YarnLockLine.Identity)').TrimStart().StartsWith('resolved "'))" /> + <_DisallowedRegistryLine Include="@(_YarnLockResolvedLine)" Condition="!$([System.String]::Copy('%(_YarnLockResolvedLine.Identity)').Contains('$(_AllowedNpmRegistryHost)'))" /> + Text="extension/yarn.lock contains resolved entries outside the internal dotnet-public-npm feed. Regenerate it through the internal feed before building. Offending lines: @(_DisallowedRegistryLine, '; ')" + Condition="'@(_DisallowedRegistryLine)' != ''" /> - + extension directory or Corepack will fall back to its default. + COREPACK_HOME is set explicitly so the Exec inherits the build-scoped + cache the bootstrap scripts seeded, even if the parent shell did not + export it (e.g. when invoked through `./build.sh -build-extension`). --> + - + diff --git a/extension/build.ps1 b/extension/build.ps1 index 95d8ca90df9..94436d77491 100644 --- a/extension/build.ps1 +++ b/extension/build.ps1 @@ -2,12 +2,24 @@ $ErrorActionPreference = "Stop" +# Ensure we run from the extension directory so corepack/yarn pick up +# extension/.npmrc and extension/package.json (which holds the packageManager pin). +Set-Location $PSScriptRoot + # Pinned Corepack shim version. Node.js >= 16.10 bundles a Corepack, but the # bundled version drifts with each Node release and Corepack is on track to be # unbundled from Node entirely (see https://github.com/nodejs/node/issues/54647). # Installing a pinned Corepack from npm makes the build reproducible regardless # of which Node version a developer or CI runner happens to have. -$CorepackVersion = "0.34.7" +# +# The version is stored in scripts/corepack-version.txt so that this script, the +# Bash build script, the GitHub Actions workflow, and the AzDO pipelines all +# read from a single source of truth. +$CorepackVersion = (Get-Content -Raw -Path (Join-Path $PSScriptRoot 'scripts/corepack-version.txt')).Trim() +if ([string]::IsNullOrWhiteSpace($CorepackVersion)) { + Write-Error "scripts/corepack-version.txt is empty or unreadable." + exit 1 +} # Yarn version is pinned in extension/package.json via the "packageManager" # field, which scripts/prepareCorepackYarn.mjs uses to seed Corepack's cache. @@ -23,6 +35,21 @@ if (-not $env:COREPACK_ENABLE_DOWNLOAD_PROMPT) { $env:COREPACK_ENABLE_DOWNLOAD_PROMPT = "0" } +# Pin Corepack's cache directory to a build-scoped location. Without this, every +# build shares the user's default cache (%LOCALAPPDATA%\node\corepack on +# Windows, ~/.cache/node/corepack on Linux, ~/Library/Caches/node/corepack on +# macOS). prepareCorepackYarn.mjs rewrites that cache in place +# (rmSync(installDirectory) followed by renameSync(staging, installDirectory)), +# so concurrent builds racing on the same Corepack home can corrupt each other's +# cache. The CI pipelines already scope this per-job (e.g. AzDO uses +# Agent.TempDirectory); do the same here so multi-worktree setups stay +# isolated. Concurrent builds in the *same* worktree still race on this shared +# directory — prepareCorepackYarn.mjs handles the EEXIST/ENOTEMPTY rename +# collision but is not a substitute for a lock. The directory is gitignored. +if (-not $env:COREPACK_HOME) { + $env:COREPACK_HOME = Join-Path $PSScriptRoot '.corepack-cache' +} + Write-Host "Checking prerequisites..." # Check for Node.js @@ -57,16 +84,19 @@ if (-not (Get-Command dotnet -ErrorAction SilentlyContinue)) { Write-Host "All prerequisites satisfied." -# Ensure we run from the extension directory so corepack/yarn pick up -# extension/.npmrc and extension/package.json (which holds the packageManager pin). -Set-Location $PSScriptRoot - Write-Host "" Write-Host "Installing pinned Corepack $CorepackVersion..." # Reinstall every time so we overwrite any older Corepack shim that Node.js # may have placed on PATH ahead of npm's global prefix. npm global installs do # not use the project .npmrc, so pass the registry explicitly. -npm install --global --registry "$env:NPM_REGISTRY" "corepack@$CorepackVersion" +# +# --force is required because Corepack's npm package declares `yarn`, `yarnpkg`, +# `pnpm`, `pnpx`, and `corepack` as bin entries. Without --force, npm refuses to +# overwrite bins owned by a pre-existing global yarn or pnpm (a very common +# setup, and the state this repo itself was in before this build script existed) +# and aborts with EEXIST. The CI pipelines already pass --force for the same +# reason. +npm install --global --force --registry "$env:NPM_REGISTRY" "corepack@$CorepackVersion" if ($LASTEXITCODE -ne 0) { Write-Error "npm install -g corepack@$CorepackVersion failed with exit code $LASTEXITCODE" diff --git a/extension/build.sh b/extension/build.sh index 88c57a263c2..1fbb702d5ce 100755 --- a/extension/build.sh +++ b/extension/build.sh @@ -1,12 +1,24 @@ #!/bin/bash set -e +# Ensure we run from the extension directory so corepack/yarn pick up +# extension/.npmrc and extension/package.json (which holds the packageManager pin). +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + # Pinned Corepack shim version. Node.js >= 16.10 bundles a Corepack, but the # bundled version drifts with each Node release and Corepack is on track to be # unbundled from Node entirely (see https://github.com/nodejs/node/issues/54647). # Installing a pinned Corepack from npm makes the build reproducible regardless # of which Node version a developer or CI runner happens to have. -COREPACK_VERSION="0.34.7" +# +# The version is stored in scripts/corepack-version.txt so that this script, the +# PowerShell build script, the GitHub Actions workflow, and the AzDO pipelines +# all read from a single source of truth. +COREPACK_VERSION="$(tr -d '[:space:]' < "$SCRIPT_DIR/scripts/corepack-version.txt")" +if [ -z "$COREPACK_VERSION" ]; then + echo "Error: scripts/corepack-version.txt is empty or unreadable." + exit 1 +fi # Yarn version is pinned in extension/package.json via the "packageManager" # field, which scripts/prepareCorepackYarn.mjs uses to seed Corepack's cache. @@ -15,10 +27,29 @@ COREPACK_VERSION="0.34.7" # shim and seeding Corepack's Yarn cache. npm global installs do not use the # project .npmrc, so pass the registry explicitly. Override locally with # `NPM_REGISTRY= ./build.sh`. +# Export NPM_REGISTRY so the child `node ./scripts/prepareCorepackYarn.mjs` +# process inherits it; without `export`, the script silently falls back to its +# own DefaultNpmRegistry constant and any user override of NPM_REGISTRY would +# be ignored when seeding Corepack's Yarn cache. : "${NPM_REGISTRY:=https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public-npm/npm/registry/}" +export NPM_REGISTRY : "${COREPACK_ENABLE_DOWNLOAD_PROMPT:=0}" export COREPACK_ENABLE_DOWNLOAD_PROMPT +# Pin Corepack's cache directory to a build-scoped location. Without this, every +# build shares the user's default cache (~/.cache/node/corepack on Linux, +# ~/Library/Caches/node/corepack on macOS, %LOCALAPPDATA%\node\corepack on +# Windows). prepareCorepackYarn.mjs rewrites that cache in place +# (rmSync(installDirectory) followed by renameSync(staging, installDirectory)), +# so concurrent builds racing on the same Corepack home can corrupt each other's +# cache. The CI pipelines already scope this per-job (e.g. AzDO uses +# Agent.TempDirectory); do the same here so multi-worktree setups stay +# isolated. Concurrent builds in the *same* worktree still race on this shared +# directory — prepareCorepackYarn.mjs handles the EEXIST/ENOTEMPTY rename +# collision but is not a substitute for a lock. The directory is gitignored. +: "${COREPACK_HOME:=$SCRIPT_DIR/.corepack-cache}" +export COREPACK_HOME + echo "Checking prerequisites..." # Check for Node.js @@ -50,9 +81,6 @@ fi echo "All prerequisites satisfied." -# Ensure we run from the extension directory so corepack/yarn pick up -# extension/.npmrc and extension/package.json (which holds the packageManager pin). -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" cd "$SCRIPT_DIR" echo "" @@ -60,7 +88,14 @@ echo "Installing pinned Corepack ${COREPACK_VERSION}..." # Reinstall every time so we overwrite any older Corepack shim that Node.js # may have placed on PATH ahead of npm's global prefix. npm global installs do # not use the project .npmrc, so pass the registry explicitly. -npm install --global --registry "$NPM_REGISTRY" "corepack@${COREPACK_VERSION}" +# +# --force is required because Corepack's npm package declares `yarn`, `yarnpkg`, +# `pnpm`, `pnpx`, and `corepack` as bin entries. Without --force, npm refuses to +# overwrite bins owned by a pre-existing global yarn or pnpm (a very common +# setup, and the state this repo itself was in before this build script existed) +# and aborts with EEXIST. The CI pipelines already pass --force for the same +# reason. +npm install --global --force --registry "$NPM_REGISTRY" "corepack@${COREPACK_VERSION}" # Verify the version actually on PATH matches our pin. If a system-bundled # Corepack shim shadows the npm-global install (common on Windows; possible on diff --git a/extension/scripts/corepack-version.txt b/extension/scripts/corepack-version.txt new file mode 100644 index 00000000000..6e5caff5f25 --- /dev/null +++ b/extension/scripts/corepack-version.txt @@ -0,0 +1 @@ +0.34.7 diff --git a/extension/scripts/prepareCorepackYarn.mjs b/extension/scripts/prepareCorepackYarn.mjs index 3db5c641c21..4660862f9a0 100644 --- a/extension/scripts/prepareCorepackYarn.mjs +++ b/extension/scripts/prepareCorepackYarn.mjs @@ -8,7 +8,26 @@ import { fileURLToPath } from 'node:url'; import process from 'node:process'; const DefaultNpmRegistry = 'https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public-npm/npm/registry/'; -const PackageManagerPattern = /^yarn@(?\d+\.\d+\.\d+)$/; +// Yarn 1.x `packageManager` strings can carry an integrity suffix when written +// by `corepack use yarn@` (the workflow CONTRIBUTING.MD points contributors +// at to update the pin), producing values like +// "yarn@1.22.22+sha512.f7062e6a5ee1f3aa…". +// The suffix is optional but its presence must not break us. Match an optional +// `+` suffix and ignore it; only the version is needed to seed the cache. +// +// Integrity note: when Corepack's `installVersion` finds an existing cache dir +// containing a `.corepack` file, it returns the recorded `hash`/`bin` +// immediately without re-hashing or signature-checking the install (see +// https://github.com/nodejs/corepack/blob/v0.34.7/sources/corepackUtils.ts). +// Its `Mismatch hashes` check fires only on the download path, which a +// pre-seeded cache never reaches. That means the `sha1.${packEntry.shasum}` we +// write to `.corepack` below is recorded for completeness but is never +// re-verified on reuse — trust on the seeded Yarn rests entirely on the +// `npm pack` fetch from `$NPM_REGISTRY` (the internal dnceng feed), which is +// the same authentication and integrity boundary npm uses for any other +// install through this feed. +// Spec: https://nodejs.org/api/packages.html#packagemanager +const PackageManagerPattern = /^yarn@(?\d+\.\d+\.\d+)(?:\+[\w.-]+)?$/; const scriptDirectory = dirname(fileURLToPath(import.meta.url)); const extensionDirectory = dirname(scriptDirectory); @@ -40,7 +59,16 @@ if (existsSync(corepackMetadataPath)) { process.exit(0); } -rmSync(installDirectory, { recursive: true, force: true }); +// Race-safe cleanup: only remove the install directory when it is stale +// (no `.corepack` metadata). The earlier existsSync at line 57 races against +// a concurrent winner whose renameSync could complete between that check and +// here; an unconditional rmSync would destroy that just-seeded cache. A +// narrow residual window remains between this re-check and the rmSync, but +// the rename at line 101 below would then fail with EEXIST/ENOTEMPTY and +// fall through to the existing concurrent-cache recovery path. +if (existsSync(installDirectory) && !existsSync(corepackMetadataPath)) { + rmSync(installDirectory, { recursive: true, force: true }); +} const temporaryDirectory = mkdtempSync(join(tmpdir(), 'aspire-corepack-yarn-')); mkdirSync(installParentDirectory, { recursive: true }); @@ -66,7 +94,7 @@ try { // resolve Yarn through the Azure Artifacts pull-through feed. run('tar', ['-xzf', tarballPath, '-C', stagingDirectory, '--strip-components=1'], temporaryDirectory); - writeFileSync(corepackMetadataPathFor(stagingDirectory), JSON.stringify({ + writeFileSync(join(stagingDirectory, '.corepack'), JSON.stringify({ locator: { name: 'yarn', reference: yarnVersion @@ -82,7 +110,18 @@ try { renameSync(stagingDirectory, installDirectory); cacheSeeded = true; } catch (error) { - if (error?.code === 'EEXIST') { + // Lost a race with a concurrent build (same worktree, same COREPACK_HOME). + // The winner's renameSync atomically populated installDirectory; ours then + // fails because the destination already exists. Filesystem-level error + // codes vary: + // - Windows / macOS HFS+: EEXIST when the destination dir exists. + // - Linux / macOS APFS: ENOTEMPTY (rename(2) rejects renaming over a + // non-empty directory; see + // https://man7.org/linux/man-pages/man2/rename.2.html). + // Both mean the cache is already in place, so log and exit cleanly. Any + // other error code is a real failure (permission, ENOSPC, etc.) and is + // re-thrown. + if (error?.code === 'EEXIST' || error?.code === 'ENOTEMPTY') { console.log(`Corepack cache already contains yarn@${yarnVersion} at ${installDirectory}`); } else { throw error; @@ -102,6 +141,13 @@ function getCorepackHome() { return process.env.COREPACK_HOME; } + // build.sh / build.ps1 / the GitHub Actions workflow / the AzDO pipelines all + // set COREPACK_HOME explicitly to a build-scoped directory. This fallback + // exists only for ad-hoc invocations of this script (e.g. local debugging, + // running `node ./scripts/prepareCorepackYarn.mjs` directly). It mirrors + // Corepack 0.34.x's own cache-path resolution so we seed the directory + // Corepack will later read from. + // Source: https://github.com/nodejs/corepack/blob/v0.34.7/sources/folderUtils.ts const baseDirectory = process.env.XDG_CACHE_HOME ?? process.env.LOCALAPPDATA ?? join(homedir(), process.platform === 'win32' ? 'AppData/Local' : '.cache'); @@ -126,10 +172,6 @@ function getNpmInvocation() { return { command: process.execPath, args: [npmCliPath] }; } -function corepackMetadataPathFor(directory) { - return join(directory, '.corepack'); -} - function parseNpmPackJson(stdout) { const jsonStart = stdout.indexOf('['); From 02d11d80fffc748a6c87d6b17ef1f49a50218c7a Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Sat, 30 May 2026 00:18:53 -0400 Subject: [PATCH 24/35] Fix npm launcher: lazy package map load, musl arm64, signal forwarding * loadRidPackageNames() now runs lazily from main() and surfaces a friendly 'installation is corrupted ... Reinstall' error rather than a raw Node stack trace when the JSON map is missing or malformed. Previously the read happened at module top-level, bypassing the launcher's outer try/catch. * Detect Linux musl on arm64 and throw 'Unsupported platform' rather than silently falling through to the glibc-linked linux-arm64 binary (which crashes at exec with a dynamic-linker error). * Forward SIGINT, SIGTERM, SIGHUP and SIGQUIT to the child process. Previously `kill ` orphaned the native CLI process, which broke programmatic shutdown of long-running commands like 'aspire run' that keep an AppHost alive. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- eng/clipack/npm/aspire.js | 64 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 60 insertions(+), 4 deletions(-) diff --git a/eng/clipack/npm/aspire.js b/eng/clipack/npm/aspire.js index 0ed373c28c8..81539a98b8f 100644 --- a/eng/clipack/npm/aspire.js +++ b/eng/clipack/npm/aspire.js @@ -7,12 +7,30 @@ const os = require('os'); const path = require('path'); // Package names are generated at pack time so changing the npm package name in -// MSBuild does not require editing this launcher. -const ridPackageNames = loadRidPackageNames(); +// MSBuild does not require editing this launcher. Resolved lazily inside main() +// so a missing/corrupt aspire-package-map.json surfaces through the same +// friendly error path used by the rest of the launcher (try/catch around main). +let ridPackageNames = null; function loadRidPackageNames() { const packageMapPath = path.join(__dirname, 'aspire-package-map.json'); - return new Map(Object.entries(JSON.parse(fs.readFileSync(packageMapPath, 'utf8')))); + let raw; + try { + raw = fs.readFileSync(packageMapPath, 'utf8'); + } catch (error) { + throw new Error( + `Aspire CLI installation is corrupted: package map '${packageMapPath}' could not be read. ` + + 'Reinstall @microsoft/aspire-cli.', + { cause: error }); + } + try { + return new Map(Object.entries(JSON.parse(raw))); + } catch (error) { + throw new Error( + `Aspire CLI installation is corrupted: package map '${packageMapPath}' is not valid JSON. ` + + 'Reinstall @microsoft/aspire-cli.', + { cause: error }); + } } function detectRid() { @@ -28,9 +46,18 @@ function detectRid() { } if (platform === 'linux') { - if (arch === 'x64' && isMusl()) { + // libc-mismatched binaries crash at exec with cryptic dynamic-linker errors + // (e.g. missing ld-linux-aarch64.so.1 / "GLIBC_X.Y not found"). Detect musl + // for all supported arches so unsupported combinations fall through to the + // friendly "Unsupported platform" error below, instead of silently + // resolving the glibc-linked RID package. + const musl = isMusl(); + if (arch === 'x64' && musl) { return 'linux-musl-x64'; } + if (arch === 'arm64' && musl) { + throw new Error(`Unsupported platform: ${platform} musl ${arch}`); + } if (arch === 'x64' || arch === 'arm64') { return `linux-${arch}`; @@ -155,6 +182,11 @@ function needsCopy(sourcePath, targetPath) { } function main() { + // Lazy-initialize so a missing/corrupt aspire-package-map.json reaches the + // top-level try/catch and produces a friendly error instead of a Node stack. + if (ridPackageNames === null) { + ridPackageNames = loadRidPackageNames(); + } const packageJson = require(path.join(__dirname, '..', 'package.json')); const rid = detectRid(); const nativeBinary = resolveNativeBinary(rid); @@ -173,6 +205,30 @@ function main() { } }); + // Forward terminating signals to the child so programmatic `kill ` + // does not orphan the native CLI (especially important for long-lived + // `aspire run` sessions that keep an AppHost alive). In TTY usage the kernel + // already broadcasts SIGINT/SIGQUIT to the whole foreground process group, so + // this primarily covers tooling that targets the wrapper PID directly. + // SIGHUP/SIGQUIT are POSIX-only; on Windows Node maps SIGTERM/SIGINT to + // TerminateProcess on the child, which is semantically what callers expect. + // Use `once` so a second signal can still terminate the wrapper if the child + // ignores the first one. + const forwardedSignals = ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT']; + for (const signal of forwardedSignals) { + process.once(signal, () => { + if (!child.killed) { + try { + child.kill(signal); + } catch { + // Best-effort: the child may have exited between the check and kill, + // or the signal may be unsupported on this platform. Either way we + // let the 'exit' handler below run to propagate the final state. + } + } + }); + } + child.on('error', error => { console.error(error.message); process.exit(1); From 2e174cfa70a48ce2caef837b12303c9c33398ec5 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Sat, 30 May 2026 00:19:01 -0400 Subject: [PATCH 25/35] Fix RID README rendering: use literal here-string for PowerShell The previous expandable here-string (@"..."@) interpreted both the markdown code-span backticks AND $Rid / $PackageName as PowerShell escape sequences and interpolations. Result: the shipped README on npmjs.org rendered as 'Native Aspire CLI binary for $Rid.' with no backticks visible. Switch to a non-expanding here-string (@'...'@) plus -replace for __RID__, __PACKAGE_NAME__ and __RID_PACKAGE_NAME__ placeholders so the markdown code spans survive verbatim. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- eng/scripts/pack-cli-npm-package.ps1 | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/eng/scripts/pack-cli-npm-package.ps1 b/eng/scripts/pack-cli-npm-package.ps1 index a6d8ce5c10f..8e24d95fbc1 100644 --- a/eng/scripts/pack-cli-npm-package.ps1 +++ b/eng/scripts/pack-cli-npm-package.ps1 @@ -157,13 +157,24 @@ if ($ridInfo.Contains('Libc')) { } Write-JsonFile (Join-Path $ridPackageRoot 'package.json') $ridPackageJson -Write-TextFile (Join-Path $ridPackageRoot 'README.md') @" -# $ridPackageName +# Use a non-expanding here-string so the markdown backticks (`) survive verbatim. +# In a normal (double-quoted) here-string ` is the PowerShell escape character, which +# both swallows the backticks and suppresses $-interpolation; using @'...'@ and a +# manual -replace lets us emit literal `` code spans for $Rid / $PackageName. +$ridReadmeTemplate = @' +# __RID_PACKAGE_NAME__ -Native Aspire CLI binary for `$Rid`. +Native Aspire CLI binary for `__RID__`. -This package is installed as an optional dependency of `$PackageName`. -"@ +This package is installed as an optional dependency of `__PACKAGE_NAME__`. +'@ + +$ridReadme = $ridReadmeTemplate ` + -replace '__RID_PACKAGE_NAME__', $ridPackageName ` + -replace '__RID__', $Rid ` + -replace '__PACKAGE_NAME__', $PackageName + +Write-TextFile (Join-Path $ridPackageRoot 'README.md') $ridReadme $pointerPackageRoot = Join-Path $StagingRoot 'pointer' $pointerPackageBin = Join-Path $pointerPackageRoot 'bin' From d8966ed11756812d756c053c037f03f198e70702 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Sat, 30 May 2026 00:19:08 -0400 Subject: [PATCH 26/35] Verify RID packages on npm before publishing pointer; reject empty version * Add 'Verify npm RID Packages Present Before Pointer Publish' step that extracts the pointer tgz, walks its optionalDependencies, and runs 'npm view @' for each. If any RID dep is missing on the registry, fail the publish before ESRP submits the pointer. This closes a window where SkipNpmRidPublish=true, an operator partial run, or an ESRP RID-publish failure could ship a pointer package that resolves on install but throws 'native package was not installed' on first 'aspire' invocation. * The preflight reads RIDs from the pointer's own optionalDependencies so it does not drift if RIDs are added or removed. * In the post-publish version smoke, explicitly reject the case where 'aspire --version' exits 0 with empty stdout. The previous @(...) -notmatch sequence produced an empty array on no output, which is falsy in PowerShell and let the bad install slip past the version regex check. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- eng/pipelines/release-publish-nuget.yml | 99 +++++++++++++++++++++++++ 1 file changed, 99 insertions(+) diff --git a/eng/pipelines/release-publish-nuget.yml b/eng/pipelines/release-publish-nuget.yml index 571d58e839f..d30076264e7 100644 --- a/eng/pipelines/release-publish-nuget.yml +++ b/eng/pipelines/release-publish-nuget.yml @@ -1147,6 +1147,93 @@ extends: displayName: 'Skip npm RID Publish (flagged)' - ${{ if eq(parameters.SkipNpmPointerPublish, false) }}: + # Preflight: the pointer package pins all RID packages via + # optionalDependencies at the same version. If even one RID + # tarball is missing from npm at this moment (operator set + # SkipNpmRidPublish=true to re-run only the pointer, or only + # a subset of RIDs landed in a prior attempt), the pointer + # install at end-user time will silently succeed but the + # launcher will throw "The Aspire CLI native package '…' was + # not installed" on first invocation. The post-publish smoke + # below only validates the publish pool's own RID, so a + # missing linux-arm64 would otherwise reach customers + # invisibly. Fail loudly here instead. + # + # Read the RID list from the pointer tarball's own + # optionalDependencies so we don't drift if a RID is added or + # removed. + - pwsh: | + $ErrorActionPreference = 'Stop' + $pointerPackagePath = "$(Pipeline.Workspace)/npm/pointer-package" + $pointerPackages = @(Get-ChildItem -Path $pointerPackagePath -Filter "*.tgz" -File) + if ($pointerPackages.Count -ne 1) { + Write-Error "Expected exactly one npm pointer package in '$pointerPackagePath', found $($pointerPackages.Count)." + exit 1 + } + + $metadataRoot = Join-Path "$(Agent.TempDirectory)" "npm-pointer-preflight-$([Guid]::NewGuid().ToString('N'))" + New-Item -ItemType Directory -Path $metadataRoot -Force | Out-Null + try { + tar -xzf $pointerPackages[0].FullName -C $metadataRoot + if ($LASTEXITCODE -ne 0) { + Write-Error "Failed to extract pointer package '$($pointerPackages[0].FullName)'." + exit 1 + } + + $packageJsonPath = Join-Path $metadataRoot 'package/package.json' + $packageJson = Get-Content -Raw -LiteralPath $packageJsonPath | ConvertFrom-Json + $packageName = "$($packageJson.name)" + $packageVersion = "$($packageJson.version)" + + $optionalDeps = $packageJson.optionalDependencies + if ($null -eq $optionalDeps) { + Write-Error "Pointer package '$packageName' has no optionalDependencies; nothing to preflight." + exit 1 + } + + $depNames = @($optionalDeps.PSObject.Properties.Name) + if ($depNames.Count -eq 0) { + Write-Error "Pointer package '$packageName' has empty optionalDependencies." + exit 1 + } + + $missing = New-Object System.Collections.Generic.List[string] + foreach ($depName in $depNames) { + $depVersion = "$($optionalDeps.$depName)" + $spec = "$depName@$depVersion" + Write-Host "Checking npm registry for $spec" + $resolved = & npm view $spec version 2>&1 + if ($LASTEXITCODE -ne 0 -or -not $resolved) { + Write-Warning "npm view failed for $spec (exit $LASTEXITCODE): $resolved" + $missing.Add($spec) | Out-Null + continue + } + $resolvedLine = @($resolved | ForEach-Object { "$_".Trim() } | Where-Object { $_ } | Select-Object -First 1) + if ($resolvedLine.Count -eq 0 -or [string]::IsNullOrWhiteSpace([string]$resolvedLine[0])) { + Write-Warning "npm view returned empty version for $spec" + $missing.Add($spec) | Out-Null + continue + } + Write-Host " found: $resolvedLine" + } + if ($missing.Count -gt 0) { + Write-Error ("Refusing to publish pointer package '$packageName@$packageVersion' because the following RID packages are not yet available on npm: " + ($missing -join ', ')) + exit 1 + } + Write-Host "All $($depNames.Count) RID packages are present on npm at the pointer's pinned versions. Safe to publish pointer." + } + finally { + if (Test-Path -LiteralPath $metadataRoot) { + Remove-Item -LiteralPath $metadataRoot -Recurse -Force + } + } + displayName: 'Verify npm RID Packages Present Before Pointer Publish' + # DryRun=true never reaches this step because the gating + # parent `if eq(parameters.SkipNpmPointerPublish, false)` + # is only entered in real publish runs (the pointer publish + # step lives directly below this one and is what the gate + # protects). + - template: MicroBuild.Publish.yml@MicroBuildTemplate parameters: intent: 'PackageDistribution' @@ -1295,6 +1382,18 @@ extends: } $versionLine = @($versionOutput | ForEach-Object { "$_".Trim() } | Where-Object { $_ } | Select-Object -First 1) + # `@(...)` wraps to an empty array when no non-empty lines + # are emitted; PowerShell's `-notmatch` against an empty + # array silently returns an empty array (falsy), which + # would let an `aspire --version` that exits 0 with empty + # stdout slip past the version-pattern check. Reject the + # empty case explicitly before the regex compare so the + # smoke test actually validates what it claims to. + if ($versionLine.Count -eq 0 -or [string]::IsNullOrWhiteSpace([string]$versionLine[0])) { + Write-Host $versionOutput + Write-Error "Installed Aspire CLI '$aspireCommand --version' produced no output." + exit 1 + } $versionPattern = "^$([System.Text.RegularExpressions.Regex]::Escape($packageVersion))(\+.*)?$" if ($versionLine -notmatch $versionPattern) { Write-Host $versionOutput From 70d60261d21d98bd81cdd1fd0a28b6ba1cb86044 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Sat, 30 May 2026 00:19:16 -0400 Subject: [PATCH 27/35] Add regression tests for npm launcher, README rendering, and preflight Six new asserts pinning the fixes from the multi-model code review: * RID preflight is wired before the pointer publish step * Empty 'aspire --version' stdout is rejected by the post-publish smoke * Launcher throws on Linux musl arm64 * Launcher forwards SIGINT/SIGTERM/SIGHUP/SIGQUIT to the child process * Launcher loads the RID package map lazily and emits a friendly 'installation is corrupted ... Reinstall' error * pack-cli-npm-package.ps1 uses a literal here-string so markdown backticks survive in the published RID README Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../Pipelines/NpmCliPackageTests.cs | 100 ++++++++++++++++++ .../ReleasePublishNugetPipelineTests.cs | 42 ++++++++ 2 files changed, 142 insertions(+) create mode 100644 tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs diff --git a/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs b/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs new file mode 100644 index 00000000000..544b7687243 --- /dev/null +++ b/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs @@ -0,0 +1,100 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using Xunit; + +namespace Infrastructure.Tests; + +public sealed class NpmCliPackageTests +{ + private readonly string _repoRoot = FindRepoRoot(); + + [Fact] + public async Task LauncherDetectsMuslArm64AndThrowsUnsupported() + { + var launcher = await ReadRepoFileAsync("eng/clipack/npm/aspire.js"); + + // libc-mismatched binaries crash at exec with cryptic dynamic-linker + // errors. Previously the launcher only checked musl for x64 and silently + // fell through to the glibc-linked `linux-arm64` binary on Alpine arm64. + // Assert the musl-arm64 case throws a friendly "Unsupported platform" + // error rather than silently resolving to a binary that will crash. + Assert.Contains("if (arch === 'arm64' && musl)", launcher); + Assert.Contains("Unsupported platform: ${platform} musl ${arch}", launcher); + } + + [Fact] + public async Task LauncherForwardsTerminatingSignalsToChild() + { + var launcher = await ReadRepoFileAsync("eng/clipack/npm/aspire.js"); + + // Programmatic `kill ` was orphaning the native CLI because + // the launcher only handled child exit and never forwarded inbound + // signals to the child. Especially bad for `aspire run` which keeps an + // AppHost alive. Verify all 4 standard termination signals are wired up + // and that we use `once` so a second signal can still kill the wrapper + // if the child ignores the first. + Assert.Contains("const forwardedSignals = ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT']", launcher); + Assert.Contains("process.once(signal", launcher); + Assert.Contains("child.kill(signal)", launcher); + } + + [Fact] + public async Task LauncherLoadsRidPackageMapInsideErrorHandler() + { + var launcher = await ReadRepoFileAsync("eng/clipack/npm/aspire.js"); + + // A missing/corrupt aspire-package-map.json used to throw raw + // ENOENT/SyntaxError with a Node stack at module load — bypassing the + // launcher's top-level try/catch that produces friendly errors. Verify + // the map is loaded lazily inside main() and that read/parse failures + // produce a "corrupted ... Reinstall" message rather than a stack. + Assert.Contains("if (ridPackageNames === null)", launcher); + Assert.Contains("ridPackageNames = loadRidPackageNames()", launcher); + Assert.Contains("Aspire CLI installation is corrupted", launcher); + Assert.Contains("Reinstall @microsoft/aspire-cli", launcher); + } + + [Fact] + public async Task PackScriptUsesLiteralHereStringForRidReadme() + { + var packScript = await ReadRepoFileAsync("eng/scripts/pack-cli-npm-package.ps1"); + + // Previously the RID-package README used an expandable here-string with + // `$Rid` and `$PackageName`. In PowerShell expandable here-strings the + // backtick is the escape character, so the markdown code-span backticks + // were both stripped AND the $-interpolation was suppressed. Result: + // shipped READMEs read `Native Aspire CLI binary for $Rid.` with no + // backticks. Verify the script now uses a literal here-string (@'...'@) + // with explicit -replace placeholders so backticks survive verbatim. + Assert.Contains("$ridReadmeTemplate = @'", packScript); + Assert.Contains("Native Aspire CLI binary for `__RID__`.", packScript); + Assert.Contains("This package is installed as an optional dependency of `__PACKAGE_NAME__`.", packScript); + Assert.Contains("-replace '__RID__', $Rid", packScript); + Assert.Contains("-replace '__PACKAGE_NAME__', $PackageName", packScript); + + // The original broken sequence (expandable here-string with `$Rid`) must + // not be reintroduced. + Assert.DoesNotContain("Native Aspire CLI binary for `$Rid`.", packScript); + } + + private Task ReadRepoFileAsync(string relativePath) + => File.ReadAllTextAsync(Path.Combine(_repoRoot, relativePath.Replace('/', Path.DirectorySeparatorChar))); + + private static string FindRepoRoot() + { + string? current = AppContext.BaseDirectory; + + while (current is not null) + { + if (File.Exists(Path.Combine(current, "Aspire.slnx"))) + { + return current; + } + + current = Directory.GetParent(current)?.FullName; + } + + throw new DirectoryNotFoundException("Could not find repository root containing Aspire.slnx"); + } +} diff --git a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs index ecd57851e2c..2cdb9b4a9b1 100644 --- a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs +++ b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs @@ -124,6 +124,48 @@ public async Task PrepareNpmCliPackagesScriptInstallsOfflineWithTimeout() Assert.Contains("--fetch-timeout=", template); } + [Fact] + public async Task PointerPublishPreflightsRidPackagesAreOnRegistry() + { + var pipeline = await ReadRepoFileAsync("eng/pipelines/release-publish-nuget.yml"); + + // The pointer pins each RID package via optionalDependencies. If any + // RID dep is missing on npm at pointer-publish time (operator set + // SkipNpmRidPublish=true; only some RIDs landed in an earlier attempt; + // ESRP partial failure), end-user `npm install -g @microsoft/aspire-cli` + // succeeds but the launcher throws "The Aspire CLI native package '…' + // was not installed" on first invocation. The post-publish smoke only + // covers the publish-pool's own RID, so missing other-RID tarballs + // reach customers invisibly without this preflight. + Assert.Contains("Verify npm RID Packages Present Before Pointer Publish", pipeline); + Assert.Contains("Refusing to publish pointer package", pipeline); + + var preflightIndex = pipeline.IndexOf("Verify npm RID Packages Present Before Pointer Publish", StringComparison.Ordinal); + Assert.True(preflightIndex > 0); + + // The preflight must precede the actual pointer publish so it can gate + // submission. + var pointerPublishIndex = pipeline.IndexOf( + "folderLocation: '$(Pipeline.Workspace)\\npm\\pointer-package'", + StringComparison.Ordinal); + Assert.True(pointerPublishIndex > preflightIndex, + "Preflight RID-check must appear before the pointer-publish step."); + } + + [Fact] + public async Task PostPublishSmokeRejectsEmptyAspireVersionOutput() + { + var pipeline = await ReadRepoFileAsync("eng/pipelines/release-publish-nuget.yml"); + + // Without an explicit empty-stdout check, `@(...)` wraps an empty + // version line into an empty array and PowerShell's `-notmatch` + // against an empty array silently returns an empty array (falsy), + // letting an `aspire --version` that exits 0 with no output slip past + // the version-pattern check. Assert the explicit guard is present. + Assert.Contains("$versionLine.Count -eq 0", pipeline); + Assert.Contains("produced no output.", pipeline); + } + private static void AssertBefore(string contents, string text, int boundaryIndex) { var textIndex = FindRequiredText(contents, text); From 2af69ee983d2f75edb463cc90a947953463ec77d Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Sat, 30 May 2026 02:39:32 -0400 Subject: [PATCH 28/35] Fix MicroBuild extends template for ESRP authorization MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Use 'MicroBuild.1ES.Official.Publish.yml@MicroBuildTemplate' (composite) instead of '1ES.Official.Publish.yml@MicroBuildTemplate' (plain). Without the 'MicroBuild.' prefix, the MicroBuildAuthorizePublishPlugin task is auto-injected without credential context, causing a 401 against devdiv.pkgs.visualstudio.com/_packaging/MicroBuildToolset. Pattern verified against microsoft/vscode-azuretools, microsoft/pyright, microsoft/vscode-python-environments, microsoft/vscode-deviceid, and microsoft/vscode-common-python-lsp release pipelines — all of which use the composite template for ESRP-based npm publishing. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- eng/pipelines/release-publish-nuget.yml | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/eng/pipelines/release-publish-nuget.yml b/eng/pipelines/release-publish-nuget.yml index d30076264e7..32b6e2c9abb 100644 --- a/eng/pipelines/release-publish-nuget.yml +++ b/eng/pipelines/release-publish-nuget.yml @@ -141,7 +141,16 @@ resources: trigger: none # Manual trigger only - no automatic releases extends: - template: azure-pipelines/1ES.Official.Publish.yml@MicroBuildTemplate + # Use the MicroBuild + 1ES Official composite template (NOT the plain 1ES.Official.Publish.yml). + # The `MicroBuild.` prefix is REQUIRED for ESRP-based publishing — it wires the MicroBuild + # signing/publish credential context so `MicroBuild.Publish.yml@MicroBuildTemplate` and the + # auto-injected `MicroBuildAuthorizePublishPlugin` task can authenticate against the + # `devdiv.pkgs.visualstudio.com/_packaging/MicroBuildToolset` feed. + # Pattern from microsoft/vscode-azuretools, microsoft/pyright, microsoft/vscode-python-environments + # and other Microsoft-owned npm-publishing-via-ESRP pipelines. + # The plain `1ES.Official.Publish.yml@MicroBuildTemplate` (no `MicroBuild.` prefix) injects the + # authorize task without supplying credentials, causing a 401 on the MicroBuildToolset feed. + template: azure-pipelines/MicroBuild.1ES.Official.Publish.yml@MicroBuildTemplate parameters: pool: name: NetCore1ESPool-Internal From d339c6448f96a29bc8f88b758c46dab1c1479480 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Sat, 30 May 2026 02:47:14 -0400 Subject: [PATCH 29/35] Update regression test for MicroBuild.1ES.Official.Publish.yml extends template MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The MicroBuild. prefix is required so the auto-injected MicroBuildAuthorizePublishPlugin task inherits credential context for the devdiv MicroBuildToolset feed. Without it, the task fails with a 401 in the PrepareArtifacts stage before any publishing can begin. Verified against microsoft/vscode-azuretools, microsoft/pyright, and microsoft/vscode-python-environments — all use the MicroBuild. prefix. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../Pipelines/ReleasePublishNugetPipelineTests.cs | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs index 2cdb9b4a9b1..9d49075b7ca 100644 --- a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs +++ b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs @@ -36,8 +36,17 @@ public async Task UsesEsrpPublishTemplateForNpmPublishing() { var pipeline = await ReadRepoFileAsync("eng/pipelines/release-publish-nuget.yml"); - Assert.Contains("template: azure-pipelines/1ES.Official.Publish.yml@MicroBuildTemplate", pipeline); + // The MicroBuild. prefix is REQUIRED for ESRP-based publishing — it wires the MicroBuild + // signing/publish credential context so MicroBuild.Publish.yml and the auto-injected + // MicroBuildAuthorizePublishPlugin task can authenticate against the + // devdiv.pkgs.visualstudio.com/_packaging/MicroBuildToolset feed. + // Plain `1ES.Official.Publish.yml@MicroBuildTemplate` (no `MicroBuild.` prefix) injects + // the authorize task without supplying credentials, causing a 401. + // See microsoft/vscode-azuretools, microsoft/pyright, microsoft/vscode-python-environments. + Assert.Contains("template: azure-pipelines/MicroBuild.1ES.Official.Publish.yml@MicroBuildTemplate", pipeline); Assert.DoesNotContain("template: v1/1ES.Official.PipelineTemplate.yml@1ESPipelineTemplates", pipeline); + // Guard against accidental regression to the plain template (without the MicroBuild. prefix) + Assert.DoesNotContain("template: azure-pipelines/1ES.Official.Publish.yml@MicroBuildTemplate", pipeline); } [Fact] From f66b108af64b5f6dce130a68d26826bbfb423222 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Sat, 30 May 2026 03:03:28 -0400 Subject: [PATCH 30/35] Fix MicroBuildAuthorize 401 and Telemetry TeamName errors The MicroBuild.1ES.Official.Publish.yml@MicroBuildTemplate extends template auto-injects two tasks into every job, both of which were failing in release 2987726: 1. MicroBuildAuthorizePublishPlugin@0 (start of every job) - Defaulted to fetching its nuget package from devdiv.pkgs.visualstudio.com/_packaging/MicroBuildToolset - This pipeline runs in the dnceng collection which does not have devdiv feed credentials - Result: HTTP 401 fails the stage before any customer step runs 2. MicroBuildCleanup@1 (end of every job, displayed as 'MicroBuild Telemetry') - Hard-requires a pipeline variable literally named TeamName - We had _TeamName (Arcade convention) but not TeamName Fixes (both surfaced from MicroBuildTemplate Jobs/PublishJob.yml + Jobs/Job.yml): * Add 'TeamName: dotnet-aspire' at pipeline-scope variables so MicroBuildCleanup@1 succeeds on every job. * On the only job that actually performs an ESRP publish (ReleaseJob via 1ES.PublishNuget@1 / MicroBuild.Publish.yml), set templateContext.mb.publish.feedSource to the dnceng MicroBuildToolset mirror (https://pkgs.dev.azure.com/dnceng/_packaging/MicroBuildToolset/nuget/v3/index.json). This is the same pattern dotnet/roslyn uses. The dnceng feed is accessible to builds in this collection automatically. * On every other job (PrepareJob, WinGetJob, DispatchGitHubTasksJob, PublishReleaseAssetsJob, HomebrewValidateJob), set templateContext.mb.publish.enabled: false. These jobs only download artifacts, push to GitHub via app tokens, or run validation; none of them publish via ESRP, so the publish-authorize plugin should not run at all. Adds two regression tests in ReleasePublishNugetPipelineTests so a future edit that removes TeamName or removes the publish auth overrides fails before the pipeline is queued again. Verified against MicroBuild template source pulled from dev.azure.com/devdiv/MicroBuildTemplates/MicroBuildTemplates (Stages/PublishStage.yml, Jobs/PublishJob.yml, Jobs/Job.yml). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- eng/pipelines/release-publish-nuget.yml | 56 +++++++++++++++++++ .../ReleasePublishNugetPipelineTests.cs | 39 +++++++++++++ 2 files changed, 95 insertions(+) diff --git a/eng/pipelines/release-publish-nuget.yml b/eng/pipelines/release-publish-nuget.yml index 32b6e2c9abb..4f6f72e3836 100644 --- a/eng/pipelines/release-publish-nuget.yml +++ b/eng/pipelines/release-publish-nuget.yml @@ -127,6 +127,15 @@ variables: - group: Aspire-Release-Secrets # Variable group containing aspire-winget-bot-pat for WinGet publishing - group: Aspire-Secrets + # Required by the MicroBuildCleanup@1 telemetry task auto-injected by + # MicroBuild.1ES.Official.Publish.yml@MicroBuildTemplate at the END of every job. + # If absent, the task fails with: "The TeamName variable is required to use MicroBuild." + # common-variables.yml defines `_TeamName: dotnet-aspire` for Arcade build conventions but + # MicroBuild specifically reads the unprefixed `TeamName` variable, so we set it explicitly + # here at pipeline scope so it propagates to all jobs (PrepareJob, ReleaseJob, WinGetJob, etc.). + # See https://devdiv.visualstudio.com/DevDiv/_wiki/wikis/DevDiv.wiki/?pagePath=/MicroBuild/Plugins/MicroBuild + - name: TeamName + value: dotnet-aspire resources: repositories: @@ -185,6 +194,17 @@ extends: variables: SourceBuildId: $(resources.pipeline.aspire-build.runID) templateContext: + # Disable the auto-injected MicroBuildAuthorizePublishPlugin@0 task for jobs + # that do not perform an ESRP publish. PrepareJob only downloads artifacts + # and re-publishes them as pipeline artifacts (so 1ES PT can attach SBOM); + # the actual NuGet/npm push happens in ReleaseJob via 1ES.PublishNuget@1 and + # MicroBuild.Publish.yml. Without this opt-out, the plugin tries to fetch its + # nuget package from devdiv.pkgs.visualstudio.com/_packaging/MicroBuildToolset + # using credentials this pipeline (in the dnceng collection) does not have, + # producing a 401 and failing the stage. See MicroBuildTemplate Jobs/PublishJob.yml. + mb: + publish: + enabled: false outputs: - output: pipelineArtifact displayName: 'Publish PackageArtifacts with SBOM' @@ -625,6 +645,18 @@ extends: templateContext: type: releaseJob isProduction: true + # ReleaseJob is the only job that performs ESRP-backed publish (1ES.PublishNuget@1, + # MicroBuild.Publish.yml for npm via DryRun=true gating). The auto-injected + # MicroBuildAuthorizePublishPlugin@0 task must therefore be able to authenticate + # to the MicroBuildToolset feed. The dnceng collection (b55de4ed-4b5a-4215-a8e4-0a0a5f71e7d8) + # hosts its own mirror at pkgs.dev.azure.com/dnceng/_packaging/MicroBuildToolset, + # which is accessible to builds in this collection automatically. Using the dnceng + # mirror avoids needing the DevDivEsrpAzDoSrvConn service connection (which is + # only required for the actual sign/publish ESRP calls, gated by DryRun=false). + # Pattern: dotnet/roslyn uses the same dnceng MicroBuildToolset mirror. + mb: + publish: + feedSource: 'https://pkgs.dev.azure.com/dnceng/_packaging/MicroBuildToolset/nuget/v3/index.json' inputs: - input: pipelineArtifact artifactName: PackageArtifacts @@ -1587,6 +1619,12 @@ extends: templateContext: type: releaseJob isProduction: true + # No ESRP publish in this job (winget cli + git push to the WinGet community repo + # using a PAT). Skip the auto-injected MicroBuildAuthorizePublishPlugin@0 so it + # does not 401 against the devdiv MicroBuildToolset feed. + mb: + publish: + enabled: false inputs: - input: pipelineArtifact artifactName: winget-manifests-stable @@ -1670,6 +1708,12 @@ extends: variables: # Pulled from the deriveReleaseVersion step in PrepareJob (PrepareArtifacts stage). ReleaseVersionEffective: $[ stageDependencies.PrepareArtifacts.PrepareJob.outputs['deriveReleaseVersion.releaseVersionEffective'] ] + templateContext: + # No ESRP publish in this job (dispatches a GitHub Actions workflow via GH App JWT + # and polls for completion). Skip the auto-injected publish auth task. + mb: + publish: + enabled: false steps: - checkout: self displayName: 'Checkout repo (for dispatch script)' @@ -1765,6 +1809,12 @@ extends: # Mapped here independently of DispatchGitHubTasksJob so this job still gets the # value when SkipGitHubTasks=true causes its sibling to be skipped. ReleaseVersionEffective: $[ stageDependencies.PrepareArtifacts.PrepareJob.outputs['deriveReleaseVersion.releaseVersionEffective'] ] + templateContext: + # No ESRP publish in this job (gh CLI upload to GitHub Release via App-token auth). + # Skip the auto-injected publish auth task. + mb: + publish: + enabled: false steps: - checkout: self displayName: 'Checkout repo (for upload script)' @@ -1903,6 +1953,12 @@ extends: name: Azure Pipelines vmImage: macOS-latest-internal os: macOS + templateContext: + # No ESRP publish in this job (read-only brew audit / brew install of a public cask). + # Skip the auto-injected publish auth task. + mb: + publish: + enabled: false steps: - checkout: self displayName: 'Checkout repo (for validate-cask-artifact.sh)' diff --git a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs index 9d49075b7ca..b98e8b556af 100644 --- a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs +++ b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs @@ -49,6 +49,45 @@ public async Task UsesEsrpPublishTemplateForNpmPublishing() Assert.DoesNotContain("template: azure-pipelines/1ES.Official.Publish.yml@MicroBuildTemplate", pipeline); } + [Fact] + public async Task DefinesTeamNameVariableForMicroBuildTelemetry() + { + var pipeline = await ReadRepoFileAsync("eng/pipelines/release-publish-nuget.yml"); + + // MicroBuild.1ES.Official.Publish.yml@MicroBuildTemplate auto-injects MicroBuildCleanup@1 + // (displayName "🔩 MicroBuild Telemetry") at the END of every job. That task hard-requires + // a variable literally named `TeamName`; if absent the task fails with: + // "The TeamName variable is required to use MicroBuild. Please update your definition + // variables to include your team name in the 'TeamName' variable." + // common-variables.yml defines `_TeamName: dotnet-aspire` for Arcade conventions but + // MicroBuild reads the unprefixed name, so we must declare TeamName at pipeline scope. + Assert.Contains("- name: TeamName", pipeline); + Assert.Contains("value: dotnet-aspire", pipeline); + } + + [Fact] + public async Task RoutesMicroBuildPublishAuthPluginToDncengFeedOrDisablesIt() + { + var pipeline = await ReadRepoFileAsync("eng/pipelines/release-publish-nuget.yml"); + + // MicroBuild.1ES.Official.Publish.yml@MicroBuildTemplate -> Stages/PublishStage.yml + // -> Jobs/PublishJob.yml auto-injects MicroBuildAuthorizePublishPlugin@0 at the START + // of every job. By default that task pulls its nuget package from + // `devdiv.pkgs.visualstudio.com/_packaging/MicroBuildToolset`, which is NOT accessible + // from the dnceng collection -> 401 -> stage fails before any customer step runs. + // Two valid escapes from MicroBuildTemplate are required: + // 1) templateContext.mb.publish.enabled: false (for jobs that don't ESRP-publish) + // 2) templateContext.mb.publish.feedSource: (for the publishing job) + // Both must be present in this pipeline: + // - non-publishing jobs (PrepareJob, WinGetJob, DispatchGitHubTasksJob, + // PublishReleaseAssetsJob, HomebrewValidateJob) -> enabled: false + // - ReleaseJob (the only job that actually publishes) -> feedSource = dnceng mirror + Assert.Contains("enabled: false", pipeline); + Assert.Contains( + "feedSource: 'https://pkgs.dev.azure.com/dnceng/_packaging/MicroBuildToolset/nuget/v3/index.json'", + pipeline); + } + [Fact] public async Task UsesRequiredNpmEsrpOwnersAndApprover() { From 4ee6d2ceb1a9db503a2181599132466d12d51dc3 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Sat, 30 May 2026 04:00:34 -0400 Subject: [PATCH 31/35] harden npm publish: registry pin, retry preflight, semver parse, sig sanity, Node 20, CRLF strip MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Multi-model code review (Aspire arch, Opus 4.8, Opus 4.7) surfaced eight items. The highest-severity issues fixed here are: 1. CRLF regression in Windows install validation (opus-4.7 — blocker) - prepare-npm-cli-packages.yml bash captures 'aspire --version' on Win runners under Git Bash. System.CommandLine 2.x writes CRLF on Windows, bash $() strips LF but NOT CR, anchored semver regex fails on \r. - Fix: pipe through 'tr -d "\r"' before capture. This regressed in commit debf4ebf38 when 'tr -d [:space:]' was replaced with 'grep -Eo'. Dry run 2987740 did NOT exercise this path because SkipNpmPublish=true skips the consumer; Monday's real publish would have failed. 2. Preflight registry pin (opus-4.8) - 'npm view $spec version' in pointer preflight relied on the agent's ambient registry. 1ES images may have internal mirrors via .npmrc / npm_config_registry which (a) could spuriously fail after a successful public publish or (b) pass against a stale mirror and ship a broken pointer to npmjs. - Fix: add explicit '--registry=https://registry.npmjs.org/' pin. 3. Preflight retry loop (opus-4.8) - Single-shot preflight could fail closed AFTER 7 RID packages are already published, forcing manual SkipNpmRidPublish=true re-run. - Fix: wrap in 10x30s retry, matching post-publish smoke. 4. Strict semver-shape filter on 'npm view' output (opus-4.8) - 'npm view --loglevel=warn 2>&1' merges deprecation / peer-dep / EBADENGINE warnings onto stdout. 'Select-Object -First 1' could latch a warning as the version. - Fix: filter to lines matching strict semver regex, and switch metadata 'npm view' to 2>$null. 5. PGP .sig content sanity check (opus-4.8) - Earlier validation only checked .tgz.sig EXISTS. If Arcade SignTool silently produced an empty/garbage sidecar (signing service hiccup, plugin misconfig), the release would publish unverifiable sidecars. - Fix: assert each sig >=64 bytes AND contains an OpenPGP marker (ASCII-armored '-----BEGIN PGP SIGNATURE-----' OR binary packet tag 2 per RFC 9580 — old-format 0x88-0x8B / new-format 0xC2). Added to BOTH source build (BuildAndTest.yml) AND release pipeline so failures surface at PR-time, not just release-time. 6. Node >=20 minimum (Aspire arch review) - aspire.js wrapper uses '{ cause: error }' (Node 16.9+) and rid->arch map covers musl-libc selector (npm >=10.7). 'engines.node = >=16' was technically permissive enough to install on Node 16.x where 'cause' is rejected. - Fix: bump to '>=20' (covers all Node 16.9+ + libc + ESM-safe subprocess + Node 18 EOL was 2025-04-30). Validation: - All 21 Infrastructure.Tests pass locally (was 14, added 7 regression tests). - Dry-run on release pipeline 2987740 already validated MicroBuild paths; this batch hardens against issues that would only have surfaced when SkipNpmPublish=false on Monday. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- eng/pipelines/release-publish-nuget.yml | 112 +++++++++++++-- eng/pipelines/templates/BuildAndTest.yml | 29 ++++ .../templates/prepare-npm-cli-packages.yml | 14 +- eng/scripts/pack-cli-npm-package.ps1 | 8 +- .../Pipelines/NpmCliPackageTests.cs | 22 +++ .../ReleasePublishNugetPipelineTests.cs | 133 ++++++++++++++++++ 6 files changed, 304 insertions(+), 14 deletions(-) diff --git a/eng/pipelines/release-publish-nuget.yml b/eng/pipelines/release-publish-nuget.yml index 4f6f72e3836..e1bf66506cc 100644 --- a/eng/pipelines/release-publish-nuget.yml +++ b/eng/pipelines/release-publish-nuget.yml @@ -1074,6 +1074,47 @@ extends: exit 1 } + # Content sanity check: catch the most likely failure mode + # where ESRP/Arcade silently produces an empty/garbage `.sig` + # file. Full PGP signature verification would require + # importing the LinuxSign500180PGP public key and running + # `gpg --verify` (gpg is not guaranteed on 1ES Windows + # agents). At minimum, assert each sidecar (a) is non-empty + # (a real PGP signature is hundreds of bytes), and (b) + # contains an OpenPGP signature marker — either the + # ASCII-armored header `-----BEGIN PGP SIGNATURE-----` + # (RFC 9580 §6) or a binary OpenPGP signature packet (tag + # 2, RFC 9580 §5.2). RFC 9580 §4.3 packet tag encoding: + # old format with tag 2 = 0x88..0x8B; new format with tag + # 2 = 0xC2; any signature packet must begin with one of + # these bytes when the sig file is binary. + $invalidSignatures = New-Object System.Collections.Generic.List[string] + foreach ($signatureSidecar in $signatureSidecars) { + if ($signatureSidecar.Length -lt 64) { + $invalidSignatures.Add("$($signatureSidecar.Name) (only $($signatureSidecar.Length) bytes)") | Out-Null + continue + } + # Peek at the first chunk so we don't load whole sigs. + # ASCII-armored PGP signatures start with the header + # within the first few bytes; binary OpenPGP signature + # packets are tag 2 and begin with 0x88-0x8B (old) or + # 0xC2 (new). We read 64 bytes which is enough to see + # the armor header verbatim. + $bytes = [System.IO.File]::ReadAllBytes($signatureSidecar.FullName)[0..63] + $asciiPreview = [System.Text.Encoding]::ASCII.GetString($bytes) + $looksArmored = $asciiPreview.Contains('-----BEGIN PGP SIGNATURE-----') + $firstByte = $bytes[0] + $looksBinarySignaturePacket = ($firstByte -ge 0x88 -and $firstByte -le 0x8B) -or $firstByte -eq 0xC2 + if (-not $looksArmored -and -not $looksBinarySignaturePacket) { + $hexPrefix = ($bytes[0..15] | ForEach-Object { '{0:x2}' -f $_ }) -join ' ' + $invalidSignatures.Add("$($signatureSidecar.Name) (no PGP signature marker; first 16 bytes: $hexPrefix)") | Out-Null + } + } + if ($invalidSignatures.Count -gt 0) { + Write-Error ("Detached signature sidecar(s) failed content sanity check: " + ($invalidSignatures -join '; ')) + exit 1 + } + Write-Host "==============================" displayName: 'List npm Packages' @@ -1239,23 +1280,61 @@ extends: } $missing = New-Object System.Collections.Generic.List[string] + # Same propagation tolerance as the post-publish smoke + # below: npm CDN propagation of 7 freshly-published scoped + # tarballs can exceed the fixed NpmRegistryPropagationDelayMinutes + # wait, especially across multiple regions. A single-shot + # `npm view` would fail closed on transient propagation lag + # AFTER all 7 RID packages are already published, forcing a + # manual re-run with SkipNpmRidPublish=true. Bound it with + # the same 10×30s retry the post-publish smoke uses. + $preflightAttempts = 10 + $preflightDelaySeconds = 30 + # Strict semver pattern (1.2.3, 1.2.3-prerelease, 1.2.3+build). + # `npm view` with `--loglevel=warn` merges deprecation / + # peer-dep / EBADENGINE warnings onto stderr; combining + # stderr with stdout and taking `Select-Object -First 1` + # could latch the warning line as the version. Filter to + # the first line that matches a semver shape and only + # then compare to the pinned version. + $semverRegex = '^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$' foreach ($depName in $depNames) { $depVersion = "$($optionalDeps.$depName)" $spec = "$depName@$depVersion" - Write-Host "Checking npm registry for $spec" - $resolved = & npm view $spec version 2>&1 - if ($LASTEXITCODE -ne 0 -or -not $resolved) { - Write-Warning "npm view failed for $spec (exit $LASTEXITCODE): $resolved" - $missing.Add($spec) | Out-Null - continue + $resolvedVersion = $null + $lastError = $null + for ($preflightAttempt = 1; $preflightAttempt -le $preflightAttempts; $preflightAttempt++) { + Write-Host "Checking npm registry for $spec (attempt $preflightAttempt/$preflightAttempts)" + # Every other npm call in the release job explicitly pins + # `--registry=https://registry.npmjs.org/`. The agent's + # ambient registry is not guaranteed to be public npmjs + # (an internal mirror may be configured via .npmrc or + # npm_config_registry). Without the explicit pin, this + # preflight could (a) spuriously fail after a successful + # public publish if the mirror lacks the new package, + # or (b) pass against a stale mirror and let a pointer + # publish reference RIDs the public registry can't serve. + $resolved = & npm view $spec version --registry=https://registry.npmjs.org/ 2>$null + if ($LASTEXITCODE -eq 0 -and $resolved) { + $candidate = $resolved | ForEach-Object { "$_".Trim() } | Where-Object { $_ -match $semverRegex } | Select-Object -First 1 + if ($candidate -eq $depVersion) { + $resolvedVersion = $candidate + Write-Host " found: $resolvedVersion" + break + } + $lastError = "npm view returned '$resolved' (no semver line matched pinned version '$depVersion')" + } else { + $lastError = "npm view exit $LASTEXITCODE for ${spec}: $resolved" + } + if ($preflightAttempt -lt $preflightAttempts) { + Write-Warning "$lastError. Retrying in $preflightDelaySeconds second(s)." + Start-Sleep -Seconds $preflightDelaySeconds + } } - $resolvedLine = @($resolved | ForEach-Object { "$_".Trim() } | Where-Object { $_ } | Select-Object -First 1) - if ($resolvedLine.Count -eq 0 -or [string]::IsNullOrWhiteSpace([string]$resolvedLine[0])) { - Write-Warning "npm view returned empty version for $spec" + if (-not $resolvedVersion) { + Write-Warning "Preflight failed for ${spec}: $lastError" $missing.Add($spec) | Out-Null - continue } - Write-Host " found: $resolvedLine" } if ($missing.Count -gt 0) { Write-Error ("Refusing to publish pointer package '$packageName@$packageVersion' because the following RID packages are not yet available on npm: " + ($missing -join ', ')) @@ -1356,11 +1435,20 @@ extends: $delaySeconds = 30 $available = $false $lastViewOutput = $null + # Strict semver regex catches: 1.2.3, 1.2.3-prerelease, 1.2.3+build. + # `npm view --loglevel=warn` merges deprecation / peer-dep / + # EBADENGINE warnings onto stderr; combining stderr with + # stdout via `2>&1` and taking `Select-Object -First 1` + # could latch the warning line as the version, then burn + # all 10 retries and fail the release even though publish + # succeeded. Filter to the first line that matches a semver + # shape and only then compare to the published version. + $semverRegex = '^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$' for ($attempt = 1; $attempt -le $attempts; $attempt++) { Write-Host "Checking npm registry metadata for $packageSpec (attempt $attempt/$attempts)..." $lastViewOutput = npm view $packageSpec version --registry=https://registry.npmjs.org/ --loglevel=warn 2>&1 if ($LASTEXITCODE -eq 0) { - $viewVersion = @($lastViewOutput | ForEach-Object { "$_".Trim() } | Where-Object { $_ } | Select-Object -First 1) + $viewVersion = $lastViewOutput | ForEach-Object { "$_".Trim() } | Where-Object { $_ -match $semverRegex } | Select-Object -First 1 if ($viewVersion -eq $packageVersion) { $available = $true break diff --git a/eng/pipelines/templates/BuildAndTest.yml b/eng/pipelines/templates/BuildAndTest.yml index 2b5552f404d..5154d51b140 100644 --- a/eng/pipelines/templates/BuildAndTest.yml +++ b/eng/pipelines/templates/BuildAndTest.yml @@ -71,6 +71,7 @@ steps: } $missingSignatures = @() + $invalidSignatures = @() foreach ($package in $npmPackages) { $signaturePath = "$($package.FullName).sig" if (!(Test-Path $signaturePath)) { @@ -78,6 +79,29 @@ steps: continue } + # Content sanity check: catch the most likely silent failure mode + # where Arcade/ESRP signing emits the sidecar file but the content + # is empty or garbage. A real PGP signature is hundreds of bytes + # and starts with either the ASCII-armored header + # `-----BEGIN PGP SIGNATURE-----` (RFC 9580 §6) or an OpenPGP + # binary signature packet (tag 2: old-format 0x88..0x8B or + # new-format 0xC2, RFC 9580 §4.3 / §5.2). + $signatureFile = Get-Item -LiteralPath $signaturePath + if ($signatureFile.Length -lt 64) { + $invalidSignatures += "$signaturePath (only $($signatureFile.Length) bytes)" + continue + } + $bytes = [System.IO.File]::ReadAllBytes($signaturePath)[0..63] + $asciiPreview = [System.Text.Encoding]::ASCII.GetString($bytes) + $looksArmored = $asciiPreview.Contains('-----BEGIN PGP SIGNATURE-----') + $firstByte = $bytes[0] + $looksBinarySignaturePacket = ($firstByte -ge 0x88 -and $firstByte -le 0x8B) -or $firstByte -eq 0xC2 + if (-not $looksArmored -and -not $looksBinarySignaturePacket) { + $hexPrefix = ($bytes[0..15] | ForEach-Object { '{0:x2}' -f $_ }) -join ' ' + $invalidSignatures += "$signaturePath (no PGP signature marker; first 16 bytes: $hexPrefix)" + continue + } + Write-Host "Found npm package signature sidecar: $([System.IO.Path]::GetFileName($signaturePath))" } @@ -86,6 +110,11 @@ steps: exit 1 } + if ($invalidSignatures.Count -gt 0) { + Write-Error "Detached signature sidecar(s) failed content sanity check: $($invalidSignatures -join '; ')" + exit 1 + } + Write-Host "Validated $($npmPackages.Count) Aspire CLI npm package signature sidecar(s)." displayName: 🟣Validate npm package signatures condition: and(succeeded(), eq(variables['_SignType'], 'real')) diff --git a/eng/pipelines/templates/prepare-npm-cli-packages.yml b/eng/pipelines/templates/prepare-npm-cli-packages.yml index 3eb382440ab..7f559d3b7e4 100644 --- a/eng/pipelines/templates/prepare-npm-cli-packages.yml +++ b/eng/pipelines/templates/prepare-npm-cli-packages.yml @@ -220,7 +220,19 @@ steps: # the npm package version, which intentionally drops build metadata because # npm SemVer (npm/semver) doesn't honor it for equality. # See https://semver.org/#spec-item-10 and https://github.com/npm/node-semver#advanced-range-syntax - versionOutput="$(aspire --version 2>&1)" + # + # IMPORTANT: pipe the subprocess output through `tr -d '\r'` BEFORE capturing. + # On Windows runners this template's `bash:` step runs under Git Bash, which + # spawns `aspire.exe` as a Windows console process. System.CommandLine 2.x's + # VersionOption writes through Console.Out.WriteLine, which terminates lines + # with Environment.NewLine = "\r\n" on Windows. Bash command substitution + # `$(...)` strips trailing LF but NOT CR, so the captured variable ends with + # "\r". The semver regex below is anchored with `$`, which matches end-of-line + # but not the literal CR — so without the `tr -d '\r'`, the entire match + # silently fails on Windows and the step exits with + # "##[error]aspire --version reported '' but expected ''". + # Verified locally: `printf 'X\r\n' | grep -Eo '^X$'` produces NO match. + versionOutput="$(aspire --version 2>&1 | tr -d '\r')" versionLine="$(printf '%s\n' "$versionOutput" | grep -Eo '^[0-9]+\.[0-9]+\.[0-9]+([.-][A-Za-z0-9._-]+)?(\+[A-Za-z0-9._-]+)?$' | head -n 1 || true)" # ${var%+*} strips the longest matching `+*` suffix. POSIX, works in Bash 3.2. actualVersion="${versionLine%+*}" diff --git a/eng/scripts/pack-cli-npm-package.ps1 b/eng/scripts/pack-cli-npm-package.ps1 index 8e24d95fbc1..0edf55cd01a 100644 --- a/eng/scripts/pack-cli-npm-package.ps1 +++ b/eng/scripts/pack-cli-npm-package.ps1 @@ -212,8 +212,14 @@ $pointerPackageJson = [ordered]@{ bin = [ordered]@{ aspire = 'bin/aspire.js' } + # Minimum Node 20: the launcher (`bin/aspire.js`) uses Error options-bag + # `new Error(msg, { cause: err })` which was added in Node 16.9.0. The + # `libc` selector in the per-RID optionalDependencies relies on + # npm >= 10.7 (ships with Node 20.10+). Node 18 reaches end-of-life + # 2025-04-30, so Node 20 is the lowest LTS we should support at GA. + # See: https://nodejs.org/en/about/previous-releases engines = [ordered]@{ - node = '>=16' + node = '>=20' } optionalDependencies = $optionalDependencies files = New-StringList @('bin', 'README.md') diff --git a/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs b/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs index 544b7687243..066bc228a1c 100644 --- a/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs +++ b/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs @@ -78,6 +78,28 @@ public async Task PackScriptUsesLiteralHereStringForRidReadme() Assert.DoesNotContain("Native Aspire CLI binary for `$Rid`.", packScript); } + [Fact] + public async Task PointerPackageRequiresNode20OrLater() + { + var packScript = await ReadRepoFileAsync("eng/scripts/pack-cli-npm-package.ps1"); + + // The launcher (`bin/aspire.js`) uses the Error options-bag + // `new Error(msg, { cause: err })` which was added in Node 16.9.0. + // Node 16.0–16.8.x would throw `TypeError: Unknown option 'cause'` + // at module load before the friendly "Aspire CLI installation is + // corrupted" message could be printed. + // The per-RID `libc` selector in optionalDependencies relies on + // npm >= 10.7 which ships with Node 20.10+. Node 18 reaches end + // of life on 2025-04-30, so Node 20 is the lowest LTS we should + // pin at GA. See https://nodejs.org/en/about/previous-releases. + // Guard against accidental regression to `>=16` (or any earlier + // version) which would let the launcher crash on supported Node + // engines. + Assert.Contains("node = '>=20'", packScript); + Assert.DoesNotContain("node = '>=16'", packScript); + Assert.DoesNotContain("node = '>=18'", packScript); + } + private Task ReadRepoFileAsync(string relativePath) => File.ReadAllTextAsync(Path.Combine(_repoRoot, relativePath.Replace('/', Path.DirectorySeparatorChar))); diff --git a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs index b98e8b556af..847eb9e6af8 100644 --- a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs +++ b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs @@ -214,6 +214,139 @@ public async Task PostPublishSmokeRejectsEmptyAspireVersionOutput() Assert.Contains("produced no output.", pipeline); } + [Fact] + public async Task PointerPreflightPinsPublicNpmRegistry() + { + var pipeline = await ReadRepoFileAsync("eng/pipelines/release-publish-nuget.yml"); + + // Every npm command in the publish flow MUST explicitly pin + // `--registry=https://registry.npmjs.org/`. The release agent's + // ambient registry is not guaranteed to be public npmjs — an + // internal mirror may be configured via .npmrc or + // npm_config_registry. Without the explicit pin, the preflight + // could (a) spuriously fail after a successful public publish + // if the mirror lacks the new package, or (b) pass against a + // stale mirror and let the pointer publish reference RIDs the + // public registry can't serve. Guard against future drift by + // asserting the preflight `npm view` is registry-pinned. + Assert.Contains( + "npm view $spec version --registry=https://registry.npmjs.org/", + pipeline); + } + + [Fact] + public async Task PointerPreflightRetriesForPropagationLag() + { + var pipeline = await ReadRepoFileAsync("eng/pipelines/release-publish-nuget.yml"); + + // The post-publish smoke uses 10×30s retry loops to ride out npm + // CDN propagation. The pre-pointer RID preflight must do the same + // because npm propagation of 7 freshly-published scoped tarballs + // can exceed the fixed NpmRegistryPropagationDelayMinutes wait. + // A single-shot preflight would fail closed AFTER all 7 RID + // packages are already published, forcing a manual re-run with + // SkipNpmRidPublish=true. Assert the preflight has its own + // retry loop. + Assert.Contains("$preflightAttempts = 10", pipeline); + Assert.Contains("$preflightDelaySeconds = 30", pipeline); + Assert.Contains("for ($preflightAttempt = 1; $preflightAttempt -le $preflightAttempts;", pipeline); + } + + [Fact] + public async Task NpmViewParsingFiltersToSemverShape() + { + var pipeline = await ReadRepoFileAsync("eng/pipelines/release-publish-nuget.yml"); + + // `npm view --loglevel=warn` merges deprecation / peer-dep / + // EBADENGINE warnings onto stderr. With `2>&1`, taking + // `Select-Object -First 1` could latch a warning line as the + // version, burn all 10 retries, and fail the release even though + // the publish succeeded. Both the preflight and post-publish + // smoke filter to lines that match a semver shape before + // comparing. + var semverRegexUses = System.Text.RegularExpressions.Regex.Matches( + pipeline, + @"\$semverRegex\s*=\s*'\^\\d\+\\\.\\d\+\\\.\\d\+"); + Assert.True( + semverRegexUses.Count >= 2, + $"Expected the semver regex to be defined in both the preflight and post-publish smoke; found {semverRegexUses.Count} occurrence(s)."); + } + + [Fact] + public async Task NpmSignatureSidecarsAreContentSanityChecked() + { + var pipeline = await ReadRepoFileAsync("eng/pipelines/release-publish-nuget.yml"); + var buildAndTest = await ReadRepoFileAsync("eng/pipelines/templates/BuildAndTest.yml"); + + // The earlier validation only checked that the `.tgz.sig` files + // EXIST. If Arcade SignTool silently produced an empty or garbage + // sidecar (signing service hiccup, plugin misconfiguration), the + // release would publish a tarball whose sidecar is unverifiable + // and nothing in CI would catch it. Full PGP verification would + // require importing the LinuxSign500180PGP public key and running + // gpg on every agent. As a low-risk middle ground, both source + // build (BuildAndTest.yml) and release pipeline assert each + // `.sig` is non-empty AND contains an OpenPGP signature marker + // (ASCII-armored "-----BEGIN PGP SIGNATURE-----" per RFC 9580 §6, + // OR a binary OpenPGP signature packet — tag 2, RFC 9580 §4.3 + // / §5.2 — starting with 0x88-0x8B (old format) or 0xC2 (new + // format)). + Assert.Contains("'-----BEGIN PGP SIGNATURE-----'", pipeline); + Assert.Contains("'-----BEGIN PGP SIGNATURE-----'", buildAndTest); + Assert.Contains("0x8B", pipeline); + Assert.Contains("0x8B", buildAndTest); + Assert.Contains("0xC2", pipeline); + Assert.Contains("0xC2", buildAndTest); + Assert.Contains("content sanity check", pipeline); + Assert.Contains("content sanity check", buildAndTest); + } + + [Fact] + public async Task AspireVersionCaptureStripsCarriageReturnForWindowsRunner() + { + var template = await ReadRepoFileAsync("eng/pipelines/templates/prepare-npm-cli-packages.yml"); + + // Regression guard for the CRLF-stripping fix surfaced by opus-4.7 review. + // + // On Windows runners the prepare-npm step runs under Git Bash, which + // launches `aspire.exe` as a Windows console process. System.CommandLine + // 2.x's VersionOption writes through Console.Out.WriteLine, which + // terminates lines with Environment.NewLine = "\r\n" on Windows. Bash + // command substitution `$(...)` strips trailing LF but NOT CR, so the + // captured variable ends with "\r". The semver capture regex used by + // the install validation is anchored with `$` (end-of-line), which does + // not match a literal CR — so without `tr -d '\r'` on the version + // capture, the entire install validation silently fails on Windows with + // "##[error]aspire --version reported '' but expected ''". + // + // Verified locally: `printf 'X\r\n' | grep -Eo '^X$'` produces NO match. + // + // This regressed in commit debf4ebf38 ("Harden npm prepare/publish + // validation against partial-failure leakage"), which replaced the + // earlier `tr -d '[:space:]'` form with a `grep -Eo`+`$` form. The dry + // run on 2987740 did NOT exercise this path because SkipNpmPublish=true + // skips the release-pipeline consumer that reads the win-x64 validation + // summary; the Monday real publish would have hit the bug at the + // first source-build Windows install validation. + Assert.Contains("aspire --version 2>&1 | tr -d '\\r'", template); + } + + [Fact] + public async Task PointerPreflightExplicitlyPinsRegistryOnSpecLine() + { + var pipeline = await ReadRepoFileAsync("eng/pipelines/release-publish-nuget.yml"); + + // The preflight that gates the pointer publish runs `npm view $spec ...` + // (note: `$spec`, not `$packageSpec` — the latter is the post-publish + // smoke). A separate test asserts the post-publish line is registry- + // pinned; this one asserts the preflight line is also pinned, so that + // a future refactor that drops `--registry=https://registry.npmjs.org/` + // from the preflight call would be caught at PR-time rather than + // silently letting a stale internal-mirror result decide whether to + // ship a broken pointer to npmjs. + Assert.Contains("npm view $spec version --registry=https://registry.npmjs.org/", pipeline); + } + private static void AssertBefore(string contents, string text, int boundaryIndex) { var textIndex = FindRequiredText(contents, text); From 38994714c77d89d3e859bc5271fdae939beea76e Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Sat, 30 May 2026 15:14:54 -0400 Subject: [PATCH 32/35] Harden npm CLI release: launcher cache, dry-run validation, summary integrity Address findings from the adversarial review of the npm CLI release path: - Launcher (aspire.js): lstat the cached native binary and reject symlinks / non-regular files before trusting it, closing the cheap cache-redirect vector. Keep the size+mtime fast path; deliberately skip per-launch byte-compare since it would tax the hot startup path for a same-user threat that already defeats the process trust boundary. - release-publish-nuget.yml: run ESRP owner/approver alias validation on dry runs too (not just real publishes) so misconfiguration fails the cheap dry run; keep the prerelease hard-block gated on DryRun=false. - prepare-npm-cli-packages.yml: derive validatedByPreparePipeline from the actual four check results instead of hardcoding true, so the release-side gate that reads it is meaningful. - release-publish-nuget.yml: cross-check the pointer package version about to be submitted to ESRP against the prepare-stage validated version, failing closed if the validated-version variable is missing/unexpanded. Add a launcher regression test for the non-regular-file cache rejection. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- eng/clipack/npm/aspire.js | 20 ++++++++++- eng/pipelines/release-publish-nuget.yml | 34 +++++++++++++++++-- .../templates/prepare-npm-cli-packages.yml | 29 +++++++++++++--- .../Pipelines/NpmCliPackageTests.cs | 15 ++++++++ 4 files changed, 90 insertions(+), 8 deletions(-) diff --git a/eng/clipack/npm/aspire.js b/eng/clipack/npm/aspire.js index 81539a98b8f..c18d97deac8 100644 --- a/eng/clipack/npm/aspire.js +++ b/eng/clipack/npm/aspire.js @@ -159,14 +159,32 @@ function ensureCachedBinary(sourcePath, binaryName, version, rid) { function needsCopy(sourcePath, targetPath) { try { + // lstat (not stat) so the final path component is never followed: a cached + // entry that is a symlink (or any non-regular file) is never trusted and is + // replaced via the atomic temp-file rename below. This blocks the cheap + // attack where a same-user process swaps the cached binary for a symlink + // pointing at attacker-controlled content between launches. + const target = fs.lstatSync(targetPath); + if (!target.isFile()) { + return true; + } + const source = fs.statSync(sourcePath); - const target = fs.statSync(targetPath); // Size mismatch always means stale cache. Even when the size matches, the // cached binary is only trusted if its mtime is at or after the source's // mtime. This catches the case where a same-version reinstall replaces the // source binary but the cache was left from a prior install with identical // content size (e.g., partial overwrite, corruption, or a swapped build). + // + // We deliberately do NOT byte-compare the cached binary against the source + // on every launch. The source is tens of MB and this runs on the hot CLI + // startup path; a same-user attacker who can pre-plant a same-size, + // newer-mtime regular file at the cache path can equally tamper with + // node_modules, PATH, or shell startup files, so per-launch content + // verification would tax startup for a threat that already defeats this + // process's trust boundary (and a TOCTOU window to exec would remain). The + // symlink rejection above closes the only cheap, low-privilege vector. if (source.size !== target.size) { return true; } diff --git a/eng/pipelines/release-publish-nuget.yml b/eng/pipelines/release-publish-nuget.yml index e1bf66506cc..699cfa1b744 100644 --- a/eng/pipelines/release-publish-nuget.yml +++ b/eng/pipelines/release-publish-nuget.yml @@ -694,8 +694,14 @@ extends: Write-Host "Skip Channel Promotion: ${{ parameters.SkipChannelPromotion }}" Write-Host "Installer-only mode: ${{ and(eq(parameters.SkipNuGetPublish, true), eq(parameters.SkipNpmPublish, true), eq(parameters.SkipChannelPromotion, true)) }}" - if ("${{ parameters.DryRun }}" -eq "false" -and "${{ parameters.SkipNpmPublish }}" -eq "false") { - if ("${{ parameters.IsPrerelease }}" -eq "true") { + if ("${{ parameters.SkipNpmPublish }}" -eq "false") { + # Validate ESRP owner/approver configuration on dry runs as well + # as real publishes so a misconfigured alias set fails the cheap + # dry run instead of only surfacing on the real release. The + # prerelease hard-block below stays gated on DryRun=false because + # a dry run never actually publishes and is the documented way to + # exercise the npm path for a prerelease build. + if ("${{ parameters.DryRun }}" -eq "false" -and "${{ parameters.IsPrerelease }}" -eq "true") { Write-Error "npm publishing is blocked for prerelease runs because the MicroBuild npm publish template does not yet expose a dist-tag parameter. Set SkipNpmPublish=true or run with DryRun=true until prereleases can publish under a non-latest tag." exit 1 } @@ -1028,6 +1034,12 @@ extends: } Write-Host "npm validation summaries verified ($($validatedRids -join ', '), version $expectedVersion)." + + # Surface the prepare-stage validated version to later steps in + # this job so the pointer preflight can assert the package about + # to be submitted to ESRP is the exact version that was install- + # tested, not a different build that slipped into staging. + Write-Host "##vso[task.setvariable variable=NpmValidatedExpectedVersion]$expectedVersion" displayName: 'Validate npm Prepare-Stage Summaries' - powershell: | @@ -1267,6 +1279,24 @@ extends: $packageName = "$($packageJson.name)" $packageVersion = "$($packageJson.version)" + # Fail closed if the pointer package about to be published + # is not the exact version the prepare-stage install tests + # validated. NpmValidatedExpectedVersion is set by the + # 'Validate npm Prepare-Stage Summaries' step earlier in this + # job; pointer publish never runs without that gate, so a + # missing/empty/unexpanded token here is itself a signal that + # the gate did not run and we must not publish. + $validatedVersion = "$(NpmValidatedExpectedVersion)" + if ([string]::IsNullOrWhiteSpace($validatedVersion) -or $validatedVersion -like '$(*)') { + Write-Error "NpmValidatedExpectedVersion was not set by the prepare-stage validation gate (got '$validatedVersion'). Refusing to publish pointer package '$packageName' without a verified version." + exit 1 + } + + if ($packageVersion -ne $validatedVersion) { + Write-Error "Pointer package '$packageName' version '$packageVersion' does not match the prepare-stage validated version '$validatedVersion'. The staged packages differ from what was install-tested; refusing to publish." + exit 1 + } + $optionalDeps = $packageJson.optionalDependencies if ($null -eq $optionalDeps) { Write-Error "Pointer package '$packageName' has no optionalDependencies; nothing to preflight." diff --git a/eng/pipelines/templates/prepare-npm-cli-packages.yml b/eng/pipelines/templates/prepare-npm-cli-packages.yml index 7f559d3b7e4..f998c1f642a 100644 --- a/eng/pipelines/templates/prepare-npm-cli-packages.yml +++ b/eng/pipelines/templates/prepare-npm-cli-packages.yml @@ -300,28 +300,47 @@ steps: # Lowercase booleans so the JSON is valid. skipRegistry="$(printf '%s' "$skipRegistry" | tr '[:upper:]' '[:lower:]')" + # Single-quote the AzDO macro expansions so an unexpanded '$(NpmCheckXxx)' + # token is never re-interpreted by the shell as a command substitution. + # Every check is initialized to 'failed' up front (see the locate step), so + # these are always set; validatedByPreparePipeline is true only when all + # four checks actually passed. This keeps the field honest instead of a + # hardcoded 'true', so the release-side gate that reads it is meaningful. + checkInstall='$(NpmCheckInstall)' + checkVersion='$(NpmCheckVersion)' + checkLauncher='$(NpmCheckLauncher)' + checkUninstall='$(NpmCheckUninstall)' + + validatedByPreparePipeline=false + if [ "$checkInstall" = "passed" ] && \ + [ "$checkVersion" = "passed" ] && \ + [ "$checkLauncher" = "passed" ] && \ + [ "$checkUninstall" = "passed" ]; then + validatedByPreparePipeline=true + fi + cat > "$outputPath" <.tgz && npm install -g --omit=optional .tgz" }, "version": { - "status": "$(NpmCheckVersion)", + "status": "$checkVersion", "details": "aspire --version output matched the build version" }, "launcher": { - "status": "$(NpmCheckLauncher)", + "status": "$checkLauncher", "details": "Launcher cached native binary at ASPIRE_NPM_CACHE_DIR///bin/" }, "uninstall": { - "status": "$(NpmCheckUninstall)", + "status": "$checkUninstall", "details": "npm uninstall -g @microsoft/aspire-cli @microsoft/aspire-cli-$rid" } } diff --git a/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs b/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs index 066bc228a1c..ea695179ade 100644 --- a/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs +++ b/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs @@ -23,6 +23,21 @@ public async Task LauncherDetectsMuslArm64AndThrowsUnsupported() Assert.Contains("Unsupported platform: ${platform} musl ${arch}", launcher); } + [Fact] + public async Task LauncherRejectsNonRegularCachedBinary() + { + var launcher = await ReadRepoFileAsync("eng/clipack/npm/aspire.js"); + + // The native binary is copied from the (signed) node_modules source into + // a writable cache before exec. `needsCopy` previously trusted any cache + // entry that matched the source size/mtime, so a same-user process could + // swap the cache entry for a symlink to attacker content and the launcher + // would exec it. Verify the staleness check lstat's the target and only + // trusts regular files, forcing a fresh copy otherwise. + Assert.Contains("const target = fs.lstatSync(targetPath);", launcher); + Assert.Contains("if (!target.isFile()) {", launcher); + } + [Fact] public async Task LauncherForwardsTerminatingSignalsToChild() { From e48d397a224bb4ca72d83564f77f5fae438c59ca Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Sat, 30 May 2026 15:41:20 -0400 Subject: [PATCH 33/35] Harden npm launcher and release pipeline from second review - aspire.js: build the forwarded-signal list per platform so SIGQUIT is never registered on Windows (process.once('SIGQUIT') throws uv_signal_start EINVAL there, which crashed the launcher and orphaned the already-spawned CLI on every Windows invocation); guard each registration. - aspire.js: register signal handlers before spawning so a signal in the spawn/registration window can't orphan the child. - aspire.js: detect musl via process.report.sharedObjects and a /lib/ld-musl-*.so filesystem probe when ldd is missing, with ldd authoritative in both directions to avoid false musl on glibc hosts. - aspire.js: create the binary cache dir owner-only (0700). - release-publish-nuget.yml: assert every staged RID and pointer tarball's package.json version equals NpmValidatedExpectedVersion before the RID publish, since an npm publish is unrevocable and the pointer preflight version check only ran after RID packages were already submitted. - release-publish-nuget.yml: drop a duplicated '# 7.' header comment left by the main merge. - Tests for all of the above. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- eng/clipack/npm/aspire.js | 116 +++++++++++++----- eng/pipelines/release-publish-nuget.yml | 72 ++++++++++- .../Pipelines/NpmCliPackageTests.cs | 65 +++++++++- .../ReleasePublishNugetPipelineTests.cs | 27 ++++ 4 files changed, 247 insertions(+), 33 deletions(-) diff --git a/eng/clipack/npm/aspire.js b/eng/clipack/npm/aspire.js index c18d97deac8..c247e4db7c1 100644 --- a/eng/clipack/npm/aspire.js +++ b/eng/clipack/npm/aspire.js @@ -69,17 +69,52 @@ function detectRid() { function isMusl() { // npm supports libc-specific packages. Prefer Node's runtime report because - // it avoids spawning a process on glibc systems, then fall back to ldd. + // it avoids spawning a process on glibc systems. if (process.report && typeof process.report.getReport === 'function') { const report = process.report.getReport(); + // glibcVersionRuntime is present only when the process is dynamically + // linked against glibc, so its presence definitively rules out musl. if (report && report.header && report.header.glibcVersionRuntime) { return false; } + + // Some Node builds list the loaded shared objects; a musl loader/libc path + // proves musl even when `ldd` is missing (common on minimal Alpine images). + if (report && Array.isArray(report.sharedObjects) && + report.sharedObjects.some(entry => typeof entry === 'string' && /(\/ld-musl-|\/libc\.musl-)/.test(entry))) { + return true; + } } + // `ldd --version` prints a "musl libc" banner on musl and a GNU/glibc banner + // on glibc. Treat ldd as authoritative in BOTH directions when it produces a + // recognizable banner: this keeps a glibc host that happens to have musl + // installed side-by-side (so a /lib/ld-musl-*.so file exists) from being + // misclassified as musl by the filesystem probe below. const lddResult = childProcess.spawnSync('ldd', ['--version'], { encoding: 'utf8' }); const lddOutput = `${lddResult.stdout || ''}${lddResult.stderr || ''}`.toLowerCase(); - return lddOutput.includes('musl'); + if (lddOutput.includes('musl')) { + return true; + } + if (lddOutput.includes('glibc') || lddOutput.includes('gnu libc') || lddOutput.includes('gnu c library')) { + return false; + } + + // Last resort when `ldd` is absent or gave no recognizable banner (common on + // stripped-down Alpine images): the musl dynamic linker is installed as + // /lib/ld-musl-.so.1. Without this probe we would wrongly assume glibc + // and resolve a binary whose dynamic linker is missing, crashing at exec. + for (const dir of ['/lib', '/usr/lib']) { + try { + if (fs.readdirSync(dir).some(name => /^ld-musl-.*\.so/.test(name))) { + return true; + } + } catch { + // Directory unreadable or absent; try the next candidate. + } + } + + return false; } function resolveNativeBinary(rid) { @@ -116,7 +151,12 @@ function ensureCachedBinary(sourcePath, binaryName, version, rid) { // The Aspire CLI self-extracts relative to its process path on first run. // Running directly from node_modules could write into read-only package // stores, so copy the native binary to an Aspire-owned writable layout. - fs.mkdirSync(targetDirectory, { recursive: true }); + // Create the cache as owner-only (0700) so that, if the cache root ever lands + // in a shared location (e.g. an ASPIRE_NPM_CACHE_DIR override or the + // os.tmpdir() fallback when no home directory is available), another local + // user cannot pre-create or read the cached executable. Mode is ignored on + // Windows and on pre-existing directories, so this only hardens dirs we make. + fs.mkdirSync(targetDirectory, { recursive: true, mode: 0o700 }); if (!needsCopy(sourcePath, targetPath)) { return targetPath; @@ -209,7 +249,51 @@ function main() { const rid = detectRid(); const nativeBinary = resolveNativeBinary(rid); const executablePath = ensureCachedBinary(nativeBinary.binaryPath, nativeBinary.binaryName, packageJson.version, rid); - const child = childProcess.spawn(executablePath, process.argv.slice(2), { + + // Forward terminating signals to the child so programmatic `kill ` + // does not orphan the native CLI (especially important for long-lived + // `aspire run` sessions that keep an AppHost alive). In TTY usage the kernel + // already broadcasts SIGINT to the whole foreground process group, so this + // primarily covers tooling that targets the wrapper PID directly. + // + // Register the handlers BEFORE spawning so a signal that arrives between + // spawn and registration cannot terminate the wrapper and orphan the child; + // `child` is captured by reference and is always assigned before any handler + // can run (signal callbacks fire on a later tick, after this stack unwinds). + // + // SIGQUIT is POSIX-only: on Windows `process.once('SIGQUIT', ...)` throws + // `uv_signal_start EINVAL` because libuv cannot map it, which would crash the + // launcher (and orphan the child spawned below) on every Windows invocation. + // So build the list per platform: on Windows Node maps SIGINT/SIGTERM/SIGHUP + // to TerminateProcess on the child and SIGBREAK covers Ctrl+Break; on POSIX + // add SIGQUIT. Each registration is additionally wrapped so an unexpected + // platform/libuv mismatch can never crash the launcher. + // Use `once` so a second signal can still terminate the wrapper if the child + // ignores the first one. + let child; + const forwardedSignals = process.platform === 'win32' + ? ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGBREAK'] + : ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT']; + for (const signal of forwardedSignals) { + try { + process.once(signal, () => { + if (child && !child.killed) { + try { + child.kill(signal); + } catch { + // Best-effort: the child may have exited between the check and kill, + // or the signal may be unsupported on this platform. Either way we + // let the 'exit' handler below run to propagate the final state. + } + } + }); + } catch { + // Registering a listener for a signal this platform's libuv rejects must + // not crash the launcher. + } + } + + child = childProcess.spawn(executablePath, process.argv.slice(2), { stdio: 'inherit', env: { ...process.env, @@ -223,30 +307,6 @@ function main() { } }); - // Forward terminating signals to the child so programmatic `kill ` - // does not orphan the native CLI (especially important for long-lived - // `aspire run` sessions that keep an AppHost alive). In TTY usage the kernel - // already broadcasts SIGINT/SIGQUIT to the whole foreground process group, so - // this primarily covers tooling that targets the wrapper PID directly. - // SIGHUP/SIGQUIT are POSIX-only; on Windows Node maps SIGTERM/SIGINT to - // TerminateProcess on the child, which is semantically what callers expect. - // Use `once` so a second signal can still terminate the wrapper if the child - // ignores the first one. - const forwardedSignals = ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT']; - for (const signal of forwardedSignals) { - process.once(signal, () => { - if (!child.killed) { - try { - child.kill(signal); - } catch { - // Best-effort: the child may have exited between the check and kill, - // or the signal may be unsupported on this platform. Either way we - // let the 'exit' handler below run to propagate the final state. - } - } - }); - } - child.on('error', error => { console.error(error.message); process.exit(1); diff --git a/eng/pipelines/release-publish-nuget.yml b/eng/pipelines/release-publish-nuget.yml index cb1718b0330..20d6b94cecb 100644 --- a/eng/pipelines/release-publish-nuget.yml +++ b/eng/pipelines/release-publish-nuget.yml @@ -11,7 +11,6 @@ # baseline PR) and waits for it to complete # 7. Uploads aspire-cli-* archives from the source build's BlobArtifacts # onto the GitHub Release as the aspire-repo-bot -# 7. Validates the Homebrew cask against the live GitHub release # # For full documentation, see: docs/release-process.md @@ -1201,6 +1200,77 @@ extends: Write-Host "==============================" displayName: 'List npm Packages' + - pwsh: | + $ErrorActionPreference = 'Stop' + + # Fail closed if the prepare-stage validation gate did not run: + # every staged RID and pointer tarball must be the exact version + # that was install-tested. NpmValidatedExpectedVersion is set by + # 'Validate npm Prepare-Stage Summaries' earlier in this job (both + # gated on SkipNpmPublish==false). A missing/empty/unexpanded token + # here means that gate did not run, so we must not publish. + $validatedVersion = "$(NpmValidatedExpectedVersion)" + if ([string]::IsNullOrWhiteSpace($validatedVersion) -or $validatedVersion -like '$(*)') { + Write-Error "NpmValidatedExpectedVersion was not set by the prepare-stage validation gate (got '$validatedVersion'). Refusing to publish npm packages without a verified version." + exit 1 + } + + $ridPackagesPath = "$(Pipeline.Workspace)/npm/rid-packages" + $pointerPackagePath = "$(Pipeline.Workspace)/npm/pointer-package" + $tarballs = @(Get-ChildItem -Path $ridPackagesPath -Filter "*.tgz" -File) + @(Get-ChildItem -Path $pointerPackagePath -Filter "*.tgz" -File) + if ($tarballs.Count -eq 0) { + Write-Error "No npm tarballs found to version-check under '$ridPackagesPath' or '$pointerPackagePath'." + exit 1 + } + + # Assert each staged tarball's OWN package.json version (the bytes + # npm will publish) matches the validated version. This runs BEFORE + # the RID packages are submitted to ESRP, because an npm publish is + # unrevocable: a mismatch caught only at the pointer preflight (which + # runs after RID publish) would already have leaked wrong-version RID + # packages onto the public registry. + Write-Host "=== Verifying staged npm package versions against '$validatedVersion' ===" + foreach ($tarball in $tarballs) { + $metadataRoot = Join-Path "$(Agent.TempDirectory)" "npm-version-check-$([Guid]::NewGuid().ToString('N'))" + New-Item -ItemType Directory -Path $metadataRoot -Force | Out-Null + try { + tar -xzf $tarball.FullName -C $metadataRoot + if ($LASTEXITCODE -ne 0) { + Write-Error "Failed to extract npm package '$($tarball.FullName)'." + exit 1 + } + + $packageJsonPath = Join-Path $metadataRoot 'package/package.json' + if (!(Test-Path -LiteralPath $packageJsonPath)) { + Write-Error "npm package '$($tarball.Name)' is missing package/package.json." + exit 1 + } + + $packageJson = Get-Content -Raw -LiteralPath $packageJsonPath | ConvertFrom-Json + $packageName = "$($packageJson.name)" + $packageVersion = "$($packageJson.version)" + if ([string]::IsNullOrWhiteSpace($packageVersion)) { + Write-Error "npm package '$($tarball.Name)' has no version in package.json." + exit 1 + } + + if ($packageVersion -ne $validatedVersion) { + Write-Error "npm package '$packageName' ($($tarball.Name)) version '$packageVersion' does not match the prepare-stage validated version '$validatedVersion'. The staged packages differ from what was install-tested; refusing to publish." + exit 1 + } + + Write-Host " - $packageName@$packageVersion OK" + } + finally { + if (Test-Path -LiteralPath $metadataRoot) { + Remove-Item -LiteralPath $metadataRoot -Recurse -Force + } + } + } + + Write-Host "All staged npm tarballs match validated version '$validatedVersion'." + displayName: 'Verify Staged npm Package Versions' + - ${{ if and(eq(parameters.DryRun, true), eq(parameters.SkipNpmPublish, false)) }}: - powershell: | Write-Host "=== DRY RUN MODE ===" diff --git a/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs b/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs index ea695179ade..7369d69a380 100644 --- a/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs +++ b/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs @@ -46,14 +46,71 @@ public async Task LauncherForwardsTerminatingSignalsToChild() // Programmatic `kill ` was orphaning the native CLI because // the launcher only handled child exit and never forwarded inbound // signals to the child. Especially bad for `aspire run` which keeps an - // AppHost alive. Verify all 4 standard termination signals are wired up - // and that we use `once` so a second signal can still kill the wrapper - // if the child ignores the first. - Assert.Contains("const forwardedSignals = ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT']", launcher); + // AppHost alive. Verify termination signals are wired up and that we use + // `once` so a second signal can still kill the wrapper if the child + // ignores the first. Assert.Contains("process.once(signal", launcher); Assert.Contains("child.kill(signal)", launcher); } + [Fact] + public async Task LauncherUsesPlatformSpecificSignalListToAvoidWindowsCrash() + { + var launcher = await ReadRepoFileAsync("eng/clipack/npm/aspire.js"); + + // SIGQUIT is POSIX-only: on Windows `process.once('SIGQUIT', ...)` throws + // `uv_signal_start EINVAL`, which (because the child is already spawned) + // would crash the launcher and orphan the running CLI on every Windows + // invocation. Verify the signal list is built per platform so SIGQUIT is + // never registered on Windows, and that each registration is guarded so an + // unexpected platform/libuv mismatch can never crash the launcher. + Assert.Contains("process.platform === 'win32'", launcher); + Assert.Contains("? ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGBREAK']", launcher); + Assert.Contains(": ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT']", launcher); + } + + [Fact] + public async Task LauncherRegistersSignalHandlersBeforeSpawningChild() + { + var launcher = await ReadRepoFileAsync("eng/clipack/npm/aspire.js"); + + // A signal delivered in the window between spawn and handler registration + // could terminate the wrapper and orphan the child - the exact failure the + // forwarding is meant to prevent. Verify `child` is declared before the + // signal loop and assigned by `childProcess.spawn` afterwards. + var declarationIndex = launcher.IndexOf("let child;", System.StringComparison.Ordinal); + var spawnIndex = launcher.IndexOf("child = childProcess.spawn(", System.StringComparison.Ordinal); + Assert.True(declarationIndex >= 0, "Expected `let child;` declaration in launcher."); + Assert.True(spawnIndex >= 0, "Expected `child = childProcess.spawn(` assignment in launcher."); + Assert.True(declarationIndex < spawnIndex, "Signal handlers must be registered before the child is spawned."); + } + + [Fact] + public async Task LauncherDetectsMuslViaFilesystemFallbackWhenLddMissing() + { + var launcher = await ReadRepoFileAsync("eng/clipack/npm/aspire.js"); + + // On minimal Alpine images `ldd` can be absent, in which case the old code + // wrongly assumed glibc and resolved a binary whose dynamic linker is + // missing (crashing at exec). Verify the launcher falls back to probing + // for the musl dynamic linker (/lib/ld-musl-*.so) when ldd gives no + // recognizable banner. + Assert.Contains("ld-musl-", launcher); + Assert.Contains("readdirSync", launcher); + } + + [Fact] + public async Task LauncherCreatesCacheDirectoryOwnerOnly() + { + var launcher = await ReadRepoFileAsync("eng/clipack/npm/aspire.js"); + + // The native binary cache may land in a shared location (an + // ASPIRE_NPM_CACHE_DIR override, or the os.tmpdir() fallback when no home + // directory is available). Create it owner-only so another local user + // cannot pre-create or read the cached executable. + Assert.Contains("recursive: true, mode: 0o700", launcher); + } + [Fact] public async Task LauncherLoadsRidPackageMapInsideErrorHandler() { diff --git a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs index 847eb9e6af8..bcb1a4db648 100644 --- a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs +++ b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs @@ -200,6 +200,33 @@ public async Task PointerPublishPreflightsRidPackagesAreOnRegistry() "Preflight RID-check must appear before the pointer-publish step."); } + [Fact] + public async Task VerifiesStagedNpmPackageVersionsBeforeRidPublish() + { + var pipeline = await ReadRepoFileAsync("eng/pipelines/release-publish-nuget.yml"); + + // An npm publish is unrevocable. The pointer preflight cross-checks the + // pointer version against the prepare-stage validated version, but that + // runs AFTER the 7 RID tarballs are already submitted to ESRP. So every + // staged RID and pointer tarball's own package.json version must be + // asserted against NpmValidatedExpectedVersion BEFORE the RID publish, or + // a wrong-version build that slipped into staging would leak onto the + // public registry before any version gate fires. + Assert.Contains("Verify Staged npm Package Versions", pipeline); + Assert.Contains("does not match the prepare-stage validated version", pipeline); + + var versionCheckIndex = pipeline.IndexOf("Verify Staged npm Package Versions", StringComparison.Ordinal); + Assert.True(versionCheckIndex > 0); + + // The version check must precede the RID-package publish so it can gate + // submission to ESRP. + var ridPublishIndex = pipeline.IndexOf( + "folderLocation: '$(Pipeline.Workspace)\\npm\\rid-packages'", + StringComparison.Ordinal); + Assert.True(ridPublishIndex > versionCheckIndex, + "Staged-version check must appear before the RID-publish step."); + } + [Fact] public async Task PostPublishSmokeRejectsEmptyAspireVersionOutput() { From b1ac0a2e95e43c9f0bb505120e9b14f0234a8c80 Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Sat, 30 May 2026 22:27:28 -0400 Subject: [PATCH 34/35] Add npm launcher behavioral tests and fix version mismatch/cleanup issues - Add AspireJsLauncherTests with real Node execution through fake npm layout - Test version mismatch detection between pointer and RID packages - Test temp file cleanup when chmod fails on POSIX systems - Test happy path: caching, environment variables, and argv passthrough - Test RID coverage against pack-cli-npm-package.ps1 - Update aspire.js to check RID package version matches pointer version - Update aspire.js to wrap copy/chmod in try-finally for temp file cleanup - Ensure temp files are removed even when copyFileSync or chmodSync fails Fixes microsoft/aspire#17297 (Task 1) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- eng/clipack/npm/aspire.js | 105 +++-- .../Npm/AspireJsLauncherTests.cs | 400 ++++++++++++++++++ 2 files changed, 474 insertions(+), 31 deletions(-) create mode 100644 tests/Aspire.Cli.Tests/Npm/AspireJsLauncherTests.cs diff --git a/eng/clipack/npm/aspire.js b/eng/clipack/npm/aspire.js index c247e4db7c1..bf73060bdc4 100644 --- a/eng/clipack/npm/aspire.js +++ b/eng/clipack/npm/aspire.js @@ -33,9 +33,7 @@ function loadRidPackageNames() { } } -function detectRid() { - const platform = process.platform; - const arch = process.arch; +function detectRid(platform = process.platform, arch = process.arch, musl = null) { if (platform === 'win32' && (arch === 'x64' || arch === 'arm64')) { return `win-${arch}`; @@ -51,7 +49,9 @@ function detectRid() { // for all supported arches so unsupported combinations fall through to the // friendly "Unsupported platform" error below, instead of silently // resolving the glibc-linked RID package. - const musl = isMusl(); + if (musl === null) { + musl = isMusl(); + } if (arch === 'x64' && musl) { return 'linux-musl-x64'; } @@ -117,7 +117,7 @@ function isMusl() { return false; } -function resolveNativeBinary(rid) { +function resolveNativeBinary(rid, expectedVersion) { const packageName = ridPackageNames.get(rid); if (!packageName) { throw new Error(`No Aspire CLI npm package is available for RID '${rid}'.`); @@ -127,12 +127,37 @@ function resolveNativeBinary(rid) { try { packageJsonPath = require.resolve(`${packageName}/package.json`); } catch (error) { + if (error && error.code === 'ERR_INVALID_PACKAGE_CONFIG') { + throw new Error( + `Aspire CLI installation is corrupted: native package '${packageName}' package.json is not valid JSON. ` + + 'Reinstall @microsoft/aspire-cli.', + { cause: error }); + } + throw new Error( `The Aspire CLI native package '${packageName}' was not installed. ` + 'Reinstall @microsoft/aspire-cli with optional dependencies enabled.', { cause: error }); } + // Verify the RID package version matches the pointer package version to catch + // partial or mismatched installs before caching or spawning the binary. + let ridPackageJson; + try { + ridPackageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')); + } catch (error) { + throw new Error( + `Aspire CLI installation is corrupted: native package '${packageName}' package.json '${packageJsonPath}' is not valid JSON. ` + + 'Reinstall @microsoft/aspire-cli.', + { cause: error }); + } + if (ridPackageJson.version !== expectedVersion) { + throw new Error( + `The Aspire CLI native package '${packageName}' version ${ridPackageJson.version} ` + + `does not match the pointer package version ${expectedVersion}. ` + + 'Reinstall @microsoft/aspire-cli.'); + } + const binaryName = process.platform === 'win32' ? 'aspire.exe' : 'aspire'; const binaryPath = path.join(path.dirname(packageJsonPath), 'bin', binaryName); if (!fs.existsSync(binaryPath)) { @@ -165,31 +190,41 @@ function ensureCachedBinary(sourcePath, binaryName, version, rid) { // Copy through a temp file and atomically rename it over the previous cache // entry so concurrent first runs never observe a missing or partial executable. const tempPath = path.join(targetDirectory, `${binaryName}.${process.pid}.${Date.now()}.tmp`); - fs.copyFileSync(sourcePath, tempPath); - if (process.platform !== 'win32') { - fs.chmodSync(tempPath, 0o755); - } - - // Node's rename uses replace-existing semantics on POSIX. On Windows, the - // rename fails with EBUSY/EPERM if the cached executable is currently - // running (e.g., another concurrent first-run already populated the cache - // and is executing it). When that happens, check whether the existing - // target is already a valid copy of the source - if it is, the other - // process won the race and our tmp can be discarded without failing the - // launcher. Any other error is unexpected and must propagate. + // Wrap copy and chmod in try-finally to ensure temp file cleanup even when + // copyFileSync or chmodSync fails. Without this, an I/O error or permission + // failure during chmod would leave the .tmp file behind. try { - fs.renameSync(tempPath, targetPath); - } catch (error) { + fs.copyFileSync(sourcePath, tempPath); + + if (process.platform !== 'win32') { + fs.chmodSync(tempPath, 0o755); + } + + // Node's rename uses replace-existing semantics on POSIX. On Windows, the + // rename fails with EBUSY/EPERM if the cached executable is currently + // running (e.g., another concurrent first-run already populated the cache + // and is executing it). When that happens, check whether the existing + // target is already a valid copy of the source - if it is, the other + // process won the race and our tmp can be discarded without failing the + // launcher. Any other error is unexpected and must propagate. try { - if (!needsCopy(sourcePath, targetPath)) { - fs.rmSync(tempPath, { force: true }); - return targetPath; + fs.renameSync(tempPath, targetPath); + } catch (error) { + try { + if (!needsCopy(sourcePath, targetPath)) { + fs.rmSync(tempPath, { force: true }); + return targetPath; + } + } catch { + // Fall through and rethrow the original rename error below. } - } catch { - // Fall through and rethrow the original rename error below. - } + fs.rmSync(tempPath, { force: true }); + throw error; + } + } catch (error) { + // Clean up temp file if copy or chmod failed before rename was attempted fs.rmSync(tempPath, { force: true }); throw error; } @@ -247,7 +282,7 @@ function main() { } const packageJson = require(path.join(__dirname, '..', 'package.json')); const rid = detectRid(); - const nativeBinary = resolveNativeBinary(rid); + const nativeBinary = resolveNativeBinary(rid, packageJson.version); const executablePath = ensureCachedBinary(nativeBinary.binaryPath, nativeBinary.binaryName, packageJson.version, rid); // Forward terminating signals to the child so programmatic `kill ` @@ -322,9 +357,17 @@ function main() { }); } -try { - main(); -} catch (error) { - console.error(error.message); - process.exit(1); +if (require.main === module) { + try { + main(); + } catch (error) { + console.error(error.message); + process.exit(1); + } } + +module.exports = { + __testing: { + detectRid + } +}; diff --git a/tests/Aspire.Cli.Tests/Npm/AspireJsLauncherTests.cs b/tests/Aspire.Cli.Tests/Npm/AspireJsLauncherTests.cs new file mode 100644 index 00000000000..008a74fdf9a --- /dev/null +++ b/tests/Aspire.Cli.Tests/Npm/AspireJsLauncherTests.cs @@ -0,0 +1,400 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using System.Diagnostics; +using System.Runtime.InteropServices; +using System.Text.Json; +using System.Text.RegularExpressions; +using Aspire.TestUtilities; + +namespace Aspire.Cli.Tests.Npm; + +[RequiresTools(["node"])] +public class AspireJsLauncherTests +{ + [Fact] + public void LauncherFailsWhenRidPackageVersionMismatchesPointerPackageVersion() + { + using var testRoot = new TestTempDirectory(); + var pointerVersion = "1.2.3"; + var ridPackageVersion = "1.2.4"; + + var rid = GetCurrentRid(); + var ridPackageName = $"@microsoft/aspire-cli-{rid}"; + var layout = CreateFakeNpmLayout(testRoot.Path, pointerVersion, rid, ridPackageName, ridPackageVersion); + + var result = RunLauncher(layout.LauncherScript, layout.CacheDir, [layout.ProbeScript, "--version"]); + + Assert.NotEqual(0, result.ExitCode); + Assert.Contains("version", result.StdErr, StringComparison.OrdinalIgnoreCase); + Assert.Contains(ridPackageName, result.StdErr); + Assert.Contains(pointerVersion, result.StdErr); + Assert.Contains(ridPackageVersion, result.StdErr); + } + + [Fact] + public void LauncherFailsWithRepairGuidanceWhenRidPackageJsonIsInvalid() + { + using var testRoot = new TestTempDirectory(); + var pointerVersion = "1.2.3"; + var rid = GetCurrentRid(); + var ridPackageName = $"@microsoft/aspire-cli-{rid}"; + var layout = CreateFakeNpmLayout(testRoot.Path, pointerVersion, rid, ridPackageName, pointerVersion); + File.WriteAllText(layout.RidPackageJsonPath, "{ not valid json"); + + var result = RunLauncher(layout.LauncherScript, layout.CacheDir, [layout.ProbeScript, "--version"]); + + Assert.NotEqual(0, result.ExitCode); + Assert.Contains("Aspire CLI installation is corrupted", result.StdErr); + Assert.Contains(ridPackageName, result.StdErr); + Assert.Contains("package.json", result.StdErr); + Assert.Contains("Reinstall @microsoft/aspire-cli", result.StdErr); + } + + [Fact] + public void LauncherCleansUpTempFileWhenChmodFails() + { + Assert.SkipUnless(!RuntimeInformation.IsOSPlatform(OSPlatform.Windows), "chmod is POSIX-only"); + + using var testRoot = new TestTempDirectory(); + var pointerVersion = "1.0.0"; + var rid = GetCurrentRid(); + var ridPackageName = $"@microsoft/aspire-cli-{rid}"; + var layout = CreateFakeNpmLayout(testRoot.Path, pointerVersion, rid, ridPackageName, pointerVersion); + + var monkeyPatchScript = Path.Combine(testRoot.Path, "patch-chmod.js"); + File.WriteAllText(monkeyPatchScript, """ + const fs = require('fs'); + const originalChmodSync = fs.chmodSync; + fs.chmodSync = function(path, mode) { + if (path.includes('.tmp')) { + throw new Error('Simulated chmod failure'); + } + return originalChmodSync.apply(this, arguments); + }; + """); + + var result = RunLauncher(layout.LauncherScript, layout.CacheDir, [layout.ProbeScript, "--version"], requiredScript: monkeyPatchScript); + + Assert.NotEqual(0, result.ExitCode); + Assert.Contains("Simulated chmod failure", result.StdErr); + var tmpFiles = Directory.GetFiles(layout.CacheDir, "*.tmp", SearchOption.AllDirectories); + Assert.Empty(tmpFiles); + } + + [Fact] + public void LauncherCleansUpTempFileWhenCopyFailsAfterCreatingTempFile() + { + using var testRoot = new TestTempDirectory(); + var pointerVersion = "1.0.0"; + var rid = GetCurrentRid(); + var ridPackageName = $"@microsoft/aspire-cli-{rid}"; + var layout = CreateFakeNpmLayout(testRoot.Path, pointerVersion, rid, ridPackageName, pointerVersion); + + var monkeyPatchScript = Path.Combine(testRoot.Path, "patch-copy.js"); + File.WriteAllText(monkeyPatchScript, """ + const fs = require('fs'); + const originalCopyFileSync = fs.copyFileSync; + fs.copyFileSync = function(source, destination, mode) { + originalCopyFileSync.apply(this, arguments); + if (String(destination).includes('.tmp')) { + throw new Error('Simulated copy failure after temp file creation'); + } + }; + """); + + var result = RunLauncher(layout.LauncherScript, layout.CacheDir, [layout.ProbeScript, "--version"], requiredScript: monkeyPatchScript); + + Assert.NotEqual(0, result.ExitCode); + Assert.Contains("Simulated copy failure", result.StdErr); + var tmpFiles = Directory.GetFiles(layout.CacheDir, "*.tmp", SearchOption.AllDirectories); + Assert.Empty(tmpFiles); + } + + [Fact] + public void LauncherCopiesBinaryToCacheAndSetsEnvironmentVariables() + { + using var testRoot = new TestTempDirectory(); + var pointerVersion = "2.0.0"; + var rid = GetCurrentRid(); + var ridPackageName = $"@microsoft/aspire-cli-{rid}"; + var layout = CreateFakeNpmLayout(testRoot.Path, pointerVersion, rid, ridPackageName, pointerVersion); + + var result = RunLauncher(layout.LauncherScript, layout.CacheDir, [layout.ProbeScript, "--test-env"]); + + Assert.Equal(0, result.ExitCode); + + var output = JsonDocument.Parse(result.StdOut); + Assert.Equal("@microsoft/aspire-cli", output.RootElement.GetProperty("ASPIRE_NPM_PACKAGE").GetString()); + Assert.Equal(pointerVersion, output.RootElement.GetProperty("ASPIRE_NPM_PACKAGE_VERSION").GetString()); + Assert.Equal(rid, output.RootElement.GetProperty("ASPIRE_NPM_PACKAGE_RID").GetString()); + + var args = output.RootElement.GetProperty("args"); + Assert.Equal(1, args.GetArrayLength()); + Assert.Equal("--test-env", args[0].GetString()); + + var binaryName = RuntimeInformation.IsOSPlatform(OSPlatform.Windows) ? "aspire.exe" : "aspire"; + var cachedBinaryPath = Path.Combine(layout.CacheDir, pointerVersion, rid, "bin", binaryName); + Assert.True(File.Exists(cachedBinaryPath), $"Expected cached binary at {cachedBinaryPath}"); + } + + [Fact] + public void LauncherSupportsAllRidsDefinedInPackScript() + { + var scriptPath = Path.Combine(GetRepoRoot(), "eng", "scripts", "pack-cli-npm-package.ps1"); + var supportedRids = GetSupportedRidsFromPackScript(scriptPath); + var launcherScriptPath = Path.Combine(GetRepoRoot(), "eng", "clipack", "npm", "aspire.js"); + + using var testRoot = new TestTempDirectory(); + var probeScript = Path.Combine(testRoot.Path, "detect-rids.js"); + File.WriteAllText(probeScript, $$""" + const launcher = require({{JsonSerializer.Serialize(launcherScriptPath)}}); + const cases = {{JsonSerializer.Serialize(supportedRids.Select(CreateRidProbeCase).ToArray())}}; + const detected = cases.map(testCase => launcher.__testing.detectRid(testCase.Platform, testCase.Arch, testCase.Musl)); + console.log(JSON.stringify(detected)); + """); + + var result = RunNodeScript(probeScript); + + Assert.Equal(0, result.ExitCode); + var detectedRids = JsonSerializer.Deserialize(result.StdOut) ?? []; + Assert.Equal(supportedRids.Order(StringComparer.Ordinal).ToArray(), detectedRids.Order(StringComparer.Ordinal).ToArray()); + } + + private static string GetCurrentRid() + { + using var testRoot = new TestTempDirectory(); + var launcherScriptPath = Path.Combine(GetRepoRoot(), "eng", "clipack", "npm", "aspire.js"); + var probeScript = Path.Combine(testRoot.Path, "detect-current-rid.js"); + + // Derive the fixture RID from the Node launcher itself. The Node runtime + // architecture and libc detection can differ from the .NET test host. + File.WriteAllText(probeScript, $$""" + const launcher = require({{JsonSerializer.Serialize(launcherScriptPath)}}); + console.log(launcher.__testing.detectRid()); + """); + + var result = RunNodeScript(probeScript); + + Assert.Equal(0, result.ExitCode); + return result.StdOut.Trim(); + } + + private static string[] GetSupportedRidsFromPackScript(string scriptPath) + { + var scriptContent = File.ReadAllText(scriptPath); + var supportedRidsMatch = Regex.Match(scriptContent, @"\$supportedRids\s*=\s*@\((?[^)]*)\)", RegexOptions.Singleline); + Assert.True(supportedRidsMatch.Success, "Could not find $supportedRids in pack-cli-npm-package.ps1."); + + return Regex.Matches(supportedRidsMatch.Groups["rids"].Value, @"'(?[^']+)'") + .Select(match => match.Groups["rid"].Value) + .Order(StringComparer.Ordinal) + .ToArray(); + } + + private static RidProbeCase CreateRidProbeCase(string rid) + { + if (rid.StartsWith("win-", StringComparison.Ordinal)) + { + return new RidProbeCase("win32", rid["win-".Length..], false); + } + + if (rid.StartsWith("osx-", StringComparison.Ordinal)) + { + return new RidProbeCase("darwin", rid["osx-".Length..], false); + } + + if (rid.StartsWith("linux-musl-", StringComparison.Ordinal)) + { + return new RidProbeCase("linux", rid["linux-musl-".Length..], true); + } + + if (rid.StartsWith("linux-", StringComparison.Ordinal)) + { + return new RidProbeCase("linux", rid["linux-".Length..], false); + } + + throw new InvalidOperationException($"Unsupported RID shape in pack script: {rid}"); + } + + private static FakeNpmLayout CreateFakeNpmLayout( + string rootPath, + string pointerVersion, + string rid, + string ridPackageName, + string ridPackageVersion) + { + var pointerDir = Path.Combine(rootPath, "pointer"); + var pointerBinDir = Path.Combine(pointerDir, "bin"); + var nodeModulesDir = Path.Combine(rootPath, "node_modules"); + var ridPackageDir = Path.Combine(nodeModulesDir, ridPackageName.Replace("/", Path.DirectorySeparatorChar.ToString())); + var ridBinDir = Path.Combine(ridPackageDir, "bin"); + var cacheDir = Path.Combine(rootPath, "cache"); + + Directory.CreateDirectory(pointerBinDir); + Directory.CreateDirectory(ridBinDir); + Directory.CreateDirectory(cacheDir); + + // Create pointer package.json + var pointerPackageJson = new + { + name = "@microsoft/aspire-cli", + version = pointerVersion + }; + File.WriteAllText( + Path.Combine(pointerDir, "package.json"), + JsonSerializer.Serialize(pointerPackageJson, new JsonSerializerOptions { WriteIndented = true })); + + // Copy the real launcher script + var realLauncherPath = Path.Combine(GetRepoRoot(), "eng", "clipack", "npm", "aspire.js"); + var launcherScript = Path.Combine(pointerBinDir, "aspire.js"); + File.Copy(realLauncherPath, launcherScript); + + // Create aspire-package-map.json + var packageMap = new Dictionary { [rid] = ridPackageName }; + File.WriteAllText( + Path.Combine(pointerBinDir, "aspire-package-map.json"), + JsonSerializer.Serialize(packageMap)); + + // Create RID package.json + var ridPackageJson = new + { + name = ridPackageName, + version = ridPackageVersion + }; + File.WriteAllText( + Path.Combine(ridPackageDir, "package.json"), + JsonSerializer.Serialize(ridPackageJson, new JsonSerializerOptions { WriteIndented = true })); + + var binaryName = RuntimeInformation.IsOSPlatform(OSPlatform.Windows) ? "aspire.exe" : "aspire"; + var binaryPath = Path.Combine(ridBinDir, binaryName); + File.Copy(GetNodeExecutablePath(), binaryPath); + + if (!RuntimeInformation.IsOSPlatform(OSPlatform.Windows)) + { + var chmod = Process.Start(new ProcessStartInfo + { + FileName = "chmod", + ArgumentList = { "+x", binaryPath }, + RedirectStandardError = true, + UseShellExecute = false + })!; + chmod.WaitForExit(); + } + + var probeScript = Path.Combine(rootPath, "probe-native.js"); + File.WriteAllText(probeScript, """ + const output = { + ASPIRE_NPM_PACKAGE: process.env.ASPIRE_NPM_PACKAGE, + ASPIRE_NPM_PACKAGE_VERSION: process.env.ASPIRE_NPM_PACKAGE_VERSION, + ASPIRE_NPM_PACKAGE_RID: process.env.ASPIRE_NPM_PACKAGE_RID, + args: process.argv.slice(2) + }; + console.log(JSON.stringify(output)); + """); + + return new FakeNpmLayout(launcherScript, cacheDir, probeScript, Path.Combine(ridPackageDir, "package.json")); + } + + private static ProcessResult RunLauncher(string launcherScript, string cacheDir, string[] args, string? requiredScript = null) + { + var psi = new ProcessStartInfo + { + FileName = "node", + WorkingDirectory = Path.GetDirectoryName(launcherScript), + RedirectStandardOutput = true, + RedirectStandardError = true, + UseShellExecute = false + }; + if (requiredScript is not null) + { + psi.ArgumentList.Add("--require"); + psi.ArgumentList.Add(requiredScript); + } + psi.ArgumentList.Add(launcherScript); + foreach (var arg in args) + { + psi.ArgumentList.Add(arg); + } + psi.Environment["ASPIRE_NPM_CACHE_DIR"] = cacheDir; + + return RunProcess(psi); + } + + private static ProcessResult RunNodeScript(string scriptPath) + { + var psi = new ProcessStartInfo + { + FileName = "node", + WorkingDirectory = Path.GetDirectoryName(scriptPath), + RedirectStandardOutput = true, + RedirectStandardError = true, + UseShellExecute = false + }; + psi.ArgumentList.Add(scriptPath); + + return RunProcess(psi); + } + + private static string GetNodeExecutablePath() + { + var psi = new ProcessStartInfo + { + FileName = "node", + RedirectStandardOutput = true, + RedirectStandardError = true, + UseShellExecute = false + }; + psi.ArgumentList.Add("-p"); + psi.ArgumentList.Add("process.execPath"); + + var result = RunProcess(psi); + + Assert.True(result.ExitCode == 0, result.StdErr); + return result.StdOut.Trim(); + } + + private static ProcessResult RunProcess(ProcessStartInfo psi) + { + using var process = Process.Start(psi)!; + var stdoutTask = process.StandardOutput.ReadToEndAsync(); + var stderrTask = process.StandardError.ReadToEndAsync(); + + using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(30)); + try + { + process.WaitForExitAsync(timeout.Token).GetAwaiter().GetResult(); + } + catch (OperationCanceledException) + { + try + { + process.Kill(entireProcessTree: true); + } + catch (InvalidOperationException) + { + } + + throw new TimeoutException($"Process '{psi.FileName}' did not exit within 30 seconds."); + } + + var stdout = stdoutTask.GetAwaiter().GetResult(); + var stderr = stderrTask.GetAwaiter().GetResult(); + + return new ProcessResult(process.ExitCode, stdout, stderr); + } + + private static string GetRepoRoot() + { + var current = Directory.GetCurrentDirectory(); + while (current is not null && !File.Exists(Path.Combine(current, "Aspire.slnx"))) + { + current = Directory.GetParent(current)?.FullName; + } + return current ?? throw new InvalidOperationException("Could not find repository root"); + } + + private sealed record FakeNpmLayout(string LauncherScript, string CacheDir, string ProbeScript, string RidPackageJsonPath); + private sealed record RidProbeCase(string Platform, string Arch, bool Musl); + private sealed record ProcessResult(int ExitCode, string StdOut, string StdErr); +} From d6a66e41c6215dd5d5d93348755d5e01522d80de Mon Sep 17 00:00:00 2001 From: Adam Ratzman Date: Sat, 30 May 2026 22:51:37 -0400 Subject: [PATCH 35/35] Harden npm release pipeline validation Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/release-process.md | 8 +- docs/specs/npm-cli-package.md | 9 +- eng/pipelines/azure-pipelines.yml | 101 ++------ eng/pipelines/common-variables.yml | 10 + eng/pipelines/release-publish-nuget.yml | 217 ++++++++++++++++-- .../npm-cli-install-validation-steps.yml | 34 +++ .../Npm/AspireJsLauncherTests.cs | 43 ++-- .../Pipelines/NpmCliPackageTests.cs | 90 ++++++++ .../ReleasePublishNugetPipelineTests.cs | 19 +- 9 files changed, 410 insertions(+), 121 deletions(-) create mode 100644 eng/pipelines/templates/npm-cli-install-validation-steps.yml diff --git a/docs/release-process.md b/docs/release-process.md index 238d60b82a5..c78c211464d 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -99,9 +99,10 @@ Before starting a release: | `SkipReleaseAssets` | Set `true` to skip uploading `aspire-cli-*` assets to the GitHub release. | `false` | | `SkipHomebrewValidation` | Set `true` if re-running after a successful Homebrew cask validation against the live GitHub release. | `false` | | `SkipVSCodeExtensionPublish` | Set `false` to publish the signed `aspire-vscode-extension` artifact to the Visual Studio Marketplace. | `true` | - | `NpmPublishOwners` | Comma-separated ESRP owner aliases or emails. Required when `DryRun` is `false` and npm publishing is not skipped; must include `joperezr` and `ankj`. | `joperezr,ankj` | - | `NpmPublishApprovers` | Comma-separated ESRP approver aliases or emails. Required when `DryRun` is `false` and npm publishing is not skipped; must include `adamratzman` and must not overlap owners. | `adamratzman` | + | `NpmPublishOwners` | Optional comma-separated ESRP owner aliases or emails. Leave empty for the repo default; overrides must still include the required owner aliases from `eng/pipelines/common-variables.yml`. | empty | + | `NpmPublishApprovers` | Optional comma-separated ESRP approver aliases or emails. Leave empty for the repo default; overrides must still include the required approver aliases from `eng/pipelines/common-variables.yml` and must not overlap owners. | empty | | `NpmRegistryPropagationDelayMinutes` | Delay between npm RID package and pointer package submissions. | `10` | + | `AllowNpmLatestDistTagMove` | Emergency override for intentionally moving npm `latest` to an older stable version. Older servicing releases should normally use `SkipNpmPublish=true`. | `false` | | `GitHubTasksWorkflowRef` | Ref to load `release-github-tasks.yml` from when dispatching. Only affects the workflow source; the release branch and commit are passed via inputs. Override only when testing pipeline changes on a topic branch. | `main` | 4. Select the **Resources** button in the bottom right, then select the source build from the `aspire-build` dropdown. @@ -118,6 +119,9 @@ To publish only the VS Code extension after merging an extension release PR, run | `IsPrerelease` | `false` for stable, `true` for pre-release | | `DryRun` | `false` | | `SkipNuGetPublish` | `true` | +| `SkipNpmPublish` | `true` | +| `SkipNpmRidPublish` | `true` | +| `SkipNpmPointerPublish` | `true` | | `SkipChannelPromotion` | `true` | | `SkipWinGetPublish` | `true` | | `SkipHomebrewValidation` | `true` | diff --git a/docs/specs/npm-cli-package.md b/docs/specs/npm-cli-package.md index e302115de85..dcff80a051d 100644 --- a/docs/specs/npm-cli-package.md +++ b/docs/specs/npm-cli-package.md @@ -164,6 +164,8 @@ The launcher's cache-freshness check compares both file size and `mtime`. A cach 3. Confirms the launcher's runtime cache landed under the expected `~/.aspire/npm///bin` layout. 4. Emits a `validation-summary.json` for each platform listing each check's status. The release pipeline refuses to submit the npm packages to ESRP without successful Windows, Linux, and macOS summaries, mirroring the brew cask flow. +The source-build install validation covers three install environments: `win-x64`, `linux-x64`, and whichever macOS RID the hosted macOS pool provides (`osx-x64` or `osx-arm64`). It does not perform a real `npm install -g` smoke test for all seven RID packages on every build because the source pipeline does not currently have cheap native agents for every target RID, and cross-installing platform-filtered optional dependencies would not exercise npm's real platform selection behavior. The remaining RID coverage comes from package-shape checks, byte-for-byte payload comparison against the signed native archive, the launcher RID-drift tests, exact RID set validation in the release pipeline, and the pointer preflight that verifies every pinned RID package is present on npm before the top-level package is published. If a future change adds new RID packages, update the pack script, launcher RID mapping/tests, source-build validation artifact list, release validation summary gate, and this document together. + `eng\scripts\stage-native-cli-tool-packages.ps1` stages npm `.tgz` artifacts alongside existing native CLI nupkgs. Official CI invokes the script with `-RequireNpmPackages`, so source builds fail before release if the npm tarballs are missing. The default remains warning-only for local or older nupkg-only flows that call the script directly. Only one pointer package is staged. The default canonical pointer source is `native_archives_win_x64`, matching the existing native CLI package staging convention. All RID-specific packages are staged. @@ -186,7 +188,11 @@ The release pipeline prepares two npm artifact folders and one validation artifa The package split is intentional. The release job submits RID packages first, waits for the ESRP submission to complete, waits an additional npm registry propagation delay, and then submits the pointer package. Publishing the pointer package last avoids optional dependency resolution races when a user installs the top-level package immediately after release. -Before publishing, the release pipeline validates that exactly one pointer tarball and exactly one tarball for each supported RID are present, that every tarball has a detached `.tgz.sig` sidecar, that all tarballs have one version, and that the `NpmValidationSummary` artifact reports `validatedByPreparePipeline: true` with every required check `passed` for Windows, Linux, and macOS install validation. Non-dry-run npm publishing also requires release managers to provide `NpmPublishOwners` and `NpmPublishApprovers`, which are passed to ESRP. Re-runs can use `SkipNpmRidPublish` if the RID packages published but the pointer package did not, and `SkipNpmPublish` after npm publishing has completed. +Before publishing, the release pipeline validates that exactly one pointer tarball and exactly one tarball for each supported RID are present, that every tarball has a detached `.tgz.sig` sidecar, that all tarballs have one version, and that the `NpmValidationSummary` artifact reports `validatedByPreparePipeline: true` with every required check `passed` for Windows, Linux, and macOS install validation. Non-dry-run npm publishing resolves the default ESRP owner and approver aliases from `eng/pipelines/common-variables.yml`; explicit `NpmPublishOwners` and `NpmPublishApprovers` overrides are allowed only if they still include the required release aliases and do not overlap. + +The release pipeline checks only the package groups scheduled for publishing before invoking MicroBuild. If `SkipNpmRidPublish=false`, every staged RID tarball is checked with `npm view @ version`; if `SkipNpmPointerPublish=false`, the pointer tarball is checked the same way. Any scheduled package version that already exists on npm fails before ESRP submission, because npm versions are immutable and a duplicate publish would otherwise fail later in MicroBuild. Re-runs after partial success should use `SkipNpmRidPublish=true` only when every RID package for the selected version is already live, `SkipNpmPointerPublish=true` only when the pointer package is already live, and `SkipNpmPublish=true` only after the entire npm publish path has completed. + +Stable Aspire npm releases publish through npm's default `latest` dist-tag because MicroBuild's npm publish template does not currently expose a dist-tag parameter. To prevent older servicing releases from moving `@microsoft/aspire-cli@latest` backward, the release pipeline compares the scheduled pointer package version with the current public `@microsoft/aspire-cli@latest` version and fails if the scheduled version is lower. Older servicing releases should set `SkipNpmPublish=true`; `AllowNpmLatestDistTagMove=true` exists only as an emergency release-owner override for an intentional latest-tag move. MicroBuild's npm publish template documentation does not currently expose an npm `dist-tag` parameter. Non-dry-run prerelease npm publishing is blocked until preview packages can be submitted under a non-`latest` tag; release managers can still use `DryRun=true` to inspect the npm publish set without submitting packages. @@ -203,3 +209,4 @@ MicroBuild's npm publish template documentation does not currently expose an npm - Add Sigstore provenance once ESRP/MicroBuild's npm publish path supports it. - Add `npm install --no-optional` guidance and a clearer error message in the launcher when no RID package is installed. +- Extract the large release-job PowerShell validation scripts once `releaseJob` can safely consume repository scripts. They remain inline today because `eng/pipelines/release-publish-nuget.yml` runs the ESRP-backed release job with `checkout: none`; extracting them now would require adding a trusted script artifact or changing release-job checkout behavior. diff --git a/eng/pipelines/azure-pipelines.yml b/eng/pipelines/azure-pipelines.yml index 7f7d640c9e9..23f22623e87 100644 --- a/eng/pipelines/azure-pipelines.yml +++ b/eng/pipelines/azure-pipelines.yml @@ -522,28 +522,10 @@ extends: image: 1es-windows-2022 os: windows steps: - - checkout: self - fetchDepth: 1 - # Download the just-built npm tarballs the build stage published as - # blob artifacts via stage-native-cli-tool-packages.ps1. Filter to - # avoid pulling unrelated blob assets. - - task: DownloadPipelineArtifact@2 - displayName: 🟣Download npm packages from build - inputs: - artifact: BlobArtifacts - itemPattern: '**/microsoft-aspire-cli*.tgz' - targetPath: '$(Pipeline.Workspace)/npm-packages' - - task: NodeTool@0 - displayName: 🟣Install Node.js - inputs: - versionSpec: '22.x' - - template: /eng/pipelines/templates/prepare-npm-cli-packages.yml@self - parameters: - npmPackagesDir: $(Pipeline.Workspace)/npm-packages - expectedVersion: $(aspireVersion) - rid: win-x64 - validationSummaryArtifactName: npm-validation-summary-win-x64 - skipRegistryResolution: true + - template: /eng/pipelines/templates/npm-cli-install-validation-steps.yml@self + parameters: + rid: win-x64 + validationSummaryArtifactName: $(NPM_VALIDATION_SUMMARY_WIN_X64_ARTIFACT) - job: NpmInstall_Linux_x64 displayName: npm install validation (linux-x64) @@ -553,28 +535,10 @@ extends: image: 1es-ubuntu-2204 os: linux steps: - - checkout: self - fetchDepth: 1 - # Download the just-built npm tarballs the build stage published as - # blob artifacts via stage-native-cli-tool-packages.ps1. Filter to - # avoid pulling unrelated blob assets. - - task: DownloadPipelineArtifact@2 - displayName: 🟣Download npm packages from build - inputs: - artifact: BlobArtifacts - itemPattern: '**/microsoft-aspire-cli*.tgz' - targetPath: '$(Pipeline.Workspace)/npm-packages' - - task: NodeTool@0 - displayName: 🟣Install Node.js - inputs: - versionSpec: '22.x' - - template: /eng/pipelines/templates/prepare-npm-cli-packages.yml@self - parameters: - npmPackagesDir: $(Pipeline.Workspace)/npm-packages - expectedVersion: $(aspireVersion) - rid: linux-x64 - validationSummaryArtifactName: npm-validation-summary-linux-x64 - skipRegistryResolution: true + - template: /eng/pipelines/templates/npm-cli-install-validation-steps.yml@self + parameters: + rid: linux-x64 + validationSummaryArtifactName: $(NPM_VALIDATION_SUMMARY_LINUX_X64_ARTIFACT) - job: NpmInstall_macOS displayName: npm install validation (macOS native RID) @@ -584,36 +548,19 @@ extends: vmImage: macOS-latest-internal os: macOS steps: - - checkout: self - fetchDepth: 1 - - pwsh: | - $ErrorActionPreference = 'Stop' - $rid = switch ('$(Agent.OSArchitecture)') { - 'ARM64' { 'osx-arm64' } - 'X64' { 'osx-x64' } - default { throw "Unsupported macOS agent architecture '$(Agent.OSArchitecture)'." } - } - - Write-Host "Resolved macOS npm validation RID: $rid" - Write-Host "##vso[task.setvariable variable=NpmValidationRid]$rid" - displayName: 🟣Resolve native macOS RID - # Download the just-built npm tarballs the build stage published as - # blob artifacts via stage-native-cli-tool-packages.ps1. Filter to - # avoid pulling unrelated blob assets. - - task: DownloadPipelineArtifact@2 - displayName: 🟣Download npm packages from build - inputs: - artifact: BlobArtifacts - itemPattern: '**/microsoft-aspire-cli*.tgz' - targetPath: '$(Pipeline.Workspace)/npm-packages' - - task: NodeTool@0 - displayName: 🟣Install Node.js - inputs: - versionSpec: '22.x' - - template: /eng/pipelines/templates/prepare-npm-cli-packages.yml@self - parameters: - npmPackagesDir: $(Pipeline.Workspace)/npm-packages - expectedVersion: $(aspireVersion) - rid: $(NpmValidationRid) - validationSummaryArtifactName: npm-validation-summary-osx - skipRegistryResolution: true + - template: /eng/pipelines/templates/npm-cli-install-validation-steps.yml@self + parameters: + rid: $(NpmValidationRid) + validationSummaryArtifactName: $(NPM_VALIDATION_SUMMARY_OSX_ARTIFACT) + preSteps: + - pwsh: | + $ErrorActionPreference = 'Stop' + $rid = switch ('$(Agent.OSArchitecture)') { + 'ARM64' { 'osx-arm64' } + 'X64' { 'osx-x64' } + default { throw "Unsupported macOS agent architecture '$(Agent.OSArchitecture)'." } + } + + Write-Host "Resolved macOS npm validation RID: $rid" + Write-Host "##vso[task.setvariable variable=NpmValidationRid]$rid" + displayName: 🟣Resolve native macOS RID diff --git a/eng/pipelines/common-variables.yml b/eng/pipelines/common-variables.yml index 30d5b0cbcc0..004aad3c214 100644 --- a/eng/pipelines/common-variables.yml +++ b/eng/pipelines/common-variables.yml @@ -14,6 +14,16 @@ variables: # .npmrc, so pass this registry explicitly. - name: NPM_REGISTRY value: https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public-npm/npm/registry/ + - name: NPM_VALIDATION_SUMMARY_WIN_X64_ARTIFACT + value: npm-validation-summary-win-x64 + - name: NPM_VALIDATION_SUMMARY_LINUX_X64_ARTIFACT + value: npm-validation-summary-linux-x64 + - name: NPM_VALIDATION_SUMMARY_OSX_ARTIFACT + value: npm-validation-summary-osx + - name: NPM_PUBLISH_REQUIRED_OWNERS + value: joperezr,ankj + - name: NPM_PUBLISH_REQUIRED_APPROVERS + value: adamratzman # Disable the interactive "Do you want to download yarn@x.y.z?" prompt so # pipeline steps don't hang waiting for stdin. - name: COREPACK_ENABLE_DOWNLOAD_PROMPT diff --git a/eng/pipelines/release-publish-nuget.yml b/eng/pipelines/release-publish-nuget.yml index 20d6b94cecb..26e7a2bf02c 100644 --- a/eng/pipelines/release-publish-nuget.yml +++ b/eng/pipelines/release-publish-nuget.yml @@ -68,6 +68,11 @@ parameters: type: boolean default: false + - name: AllowNpmLatestDistTagMove + displayName: '[Advanced] Allow npm latest dist-tag to move to an older stable version' + type: boolean + default: false + - name: SkipChannelPromotion displayName: '[Advanced] Skip Channel Promotion (re-run after success)' type: boolean @@ -94,14 +99,14 @@ parameters: default: false - name: NpmPublishOwners - displayName: 'npm ESRP owners (comma-separated Microsoft aliases or emails)' + displayName: 'npm ESRP owners (comma-separated Microsoft aliases or emails; leave blank for repo default)' type: string - default: 'joperezr,ankj' + default: '' - name: NpmPublishApprovers - displayName: 'npm ESRP approvers (comma-separated Microsoft aliases or emails)' + displayName: 'npm ESRP approvers (comma-separated Microsoft aliases or emails; leave blank for repo default)' type: string - default: 'adamratzman' + default: '' - name: NpmRegistryPropagationDelayMinutes displayName: 'Minutes to wait between npm RID and pointer package submissions' @@ -364,15 +369,15 @@ extends: - download: aspire-build displayName: 'Download npm validation summary from Source Build (win-x64)' - artifact: npm-validation-summary-win-x64 + artifact: $(NPM_VALIDATION_SUMMARY_WIN_X64_ARTIFACT) - download: aspire-build displayName: 'Download npm validation summary from Source Build (linux-x64)' - artifact: npm-validation-summary-linux-x64 + artifact: $(NPM_VALIDATION_SUMMARY_LINUX_X64_ARTIFACT) - download: aspire-build displayName: 'Download npm validation summary from Source Build (macOS)' - artifact: npm-validation-summary-osx + artifact: $(NPM_VALIDATION_SUMMARY_OSX_ARTIFACT) - ${{ if eq(parameters.SkipWinGetPublish, false) }}: - download: aspire-build @@ -570,9 +575,9 @@ extends: # Copy each install-test validation summary into its own folder. # Stage 2 re-validates every summary before submitting to ESRP/MicroBuild. $validationSummaries = @( - @{ Name = 'win-x64'; Artifact = 'npm-validation-summary-win-x64' }, - @{ Name = 'linux-x64'; Artifact = 'npm-validation-summary-linux-x64' }, - @{ Name = 'osx'; Artifact = 'npm-validation-summary-osx' } + @{ Name = 'win-x64'; Artifact = '$(NPM_VALIDATION_SUMMARY_WIN_X64_ARTIFACT)' }, + @{ Name = 'linux-x64'; Artifact = '$(NPM_VALIDATION_SUMMARY_LINUX_X64_ARTIFACT)' }, + @{ Name = 'osx'; Artifact = '$(NPM_VALIDATION_SUMMARY_OSX_ARTIFACT)' } ) foreach ($validationSummary in $validationSummaries) { @@ -800,7 +805,7 @@ extends: function Assert-ContainsRequiredNpmAliases( [System.Collections.Generic.HashSet[string]] $actualAliases, - [string[]] $requiredAliases, + [System.Collections.Generic.HashSet[string]] $requiredAliases, [string] $parameterName) { $missing = @($requiredAliases | Where-Object { -not $actualAliases.Contains($_) }) if ($missing.Count -gt 0) { @@ -811,19 +816,21 @@ extends: $owners = "${{ parameters.NpmPublishOwners }}" $approvers = "${{ parameters.NpmPublishApprovers }}" - $requiredNpmOwners = @('joperezr', 'ankj') - $requiredNpmApprovers = @('adamratzman') + $requiredNpmOwnersValue = "$(NPM_PUBLISH_REQUIRED_OWNERS)" + $requiredNpmApproversValue = "$(NPM_PUBLISH_REQUIRED_APPROVERS)" if ([string]::IsNullOrWhiteSpace($owners)) { - Write-Error "NpmPublishOwners must be set before publishing npm packages." - exit 1 + $owners = $requiredNpmOwnersValue + Write-Host "NpmPublishOwners not provided; using NPM_PUBLISH_REQUIRED_OWNERS." } if ([string]::IsNullOrWhiteSpace($approvers)) { - Write-Error "NpmPublishApprovers must be set before publishing npm packages." - exit 1 + $approvers = $requiredNpmApproversValue + Write-Host "NpmPublishApprovers not provided; using NPM_PUBLISH_REQUIRED_APPROVERS." } + $requiredNpmOwners = ConvertTo-NpmReleaseAliasSet $requiredNpmOwnersValue 'NPM_PUBLISH_REQUIRED_OWNERS' + $requiredNpmApprovers = ConvertTo-NpmReleaseAliasSet $requiredNpmApproversValue 'NPM_PUBLISH_REQUIRED_APPROVERS' $normalizedOwners = ConvertTo-NpmReleaseAliasSet $owners 'NpmPublishOwners' $normalizedApprovers = ConvertTo-NpmReleaseAliasSet $approvers 'NpmPublishApprovers' @@ -846,7 +853,12 @@ extends: exit 1 } - Write-Host "npm ESRP owners and approvers were provided and include the required release contacts." + $effectiveOwners = ($normalizedOwners | Sort-Object) -join ',' + $effectiveApprovers = ($normalizedApprovers | Sort-Object) -join ',' + + Write-Host "##vso[task.setvariable variable=NpmPublishOwnersEffective]$effectiveOwners" + Write-Host "##vso[task.setvariable variable=NpmPublishApproversEffective]$effectiveApprovers" + Write-Host "npm ESRP owners and approvers were resolved and include the required release contacts." } Write-Host "===================================" @@ -1354,6 +1366,167 @@ extends: displayName: 'Dry Run - Validate npm Registry Reachability' - ${{ if and(eq(parameters.DryRun, false), eq(parameters.SkipNpmPublish, false), eq(parameters.IsPrerelease, false)) }}: + - pwsh: | + $ErrorActionPreference = 'Stop' + + function Get-NpmTarballPackageIdentity([System.IO.FileInfo] $tarball) { + $metadataRoot = Join-Path "$(Agent.TempDirectory)" "npm-already-published-$([Guid]::NewGuid().ToString('N'))" + New-Item -ItemType Directory -Path $metadataRoot -Force | Out-Null + try { + tar -xzf $tarball.FullName -C $metadataRoot + if ($LASTEXITCODE -ne 0) { + Write-Error "Failed to extract npm package '$($tarball.FullName)'." + exit 1 + } + + $packageJsonPath = Join-Path $metadataRoot 'package/package.json' + if (!(Test-Path -LiteralPath $packageJsonPath)) { + Write-Error "npm package '$($tarball.Name)' is missing package/package.json." + exit 1 + } + + $packageJson = Get-Content -Raw -LiteralPath $packageJsonPath | ConvertFrom-Json + $packageName = "$($packageJson.name)" + $packageVersion = "$($packageJson.version)" + if ([string]::IsNullOrWhiteSpace($packageName) -or [string]::IsNullOrWhiteSpace($packageVersion)) { + Write-Error "npm package '$($tarball.Name)' must include name and version in package.json." + exit 1 + } + + [PSCustomObject]@{ + Name = $packageName + Version = $packageVersion + Spec = "$packageName@$packageVersion" + Tarball = $tarball.FullName + } + } + finally { + if (Test-Path -LiteralPath $metadataRoot) { + Remove-Item -LiteralPath $metadataRoot -Recurse -Force + } + } + } + + $scheduledPackageGroups = [System.Collections.Generic.List[object]]::new() + + if ("${{ parameters.SkipNpmRidPublish }}" -ne "true") { + $scheduledPackageGroups.Add([PSCustomObject]@{ + Name = 'RID' + Path = "$(Pipeline.Workspace)/npm/rid-packages" + }) | Out-Null + } else { + Write-Host "Skipping already-published preflight for RID packages because SkipNpmRidPublish=true." + } + + if ("${{ parameters.SkipNpmPointerPublish }}" -ne "true") { + $scheduledPackageGroups.Add([PSCustomObject]@{ + Name = 'pointer' + Path = "$(Pipeline.Workspace)/npm/pointer-package" + }) | Out-Null + } else { + Write-Host "Skipping already-published preflight for pointer package because SkipNpmPointerPublish=true." + } + + if ($scheduledPackageGroups.Count -eq 0) { + Write-Host "No npm packages are scheduled for publishing; already-published preflight has nothing to check." + exit 0 + } + + $scheduledPackages = [System.Collections.Generic.List[object]]::new() + foreach ($group in $scheduledPackageGroups) { + $tarballs = @(Get-ChildItem -Path $group.Path -Filter "*.tgz" -File) + if ($tarballs.Count -eq 0) { + Write-Error "No $($group.Name) npm tarballs were found under '$($group.Path)' for already-published preflight." + exit 1 + } + + foreach ($tarball in $tarballs) { + $scheduledPackages.Add((Get-NpmTarballPackageIdentity $tarball)) | Out-Null + } + } + + Write-Host "Checking $($scheduledPackages.Count) scheduled npm package(s) for version collisions on https://registry.npmjs.org/." + $semverRegex = '^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$' + $stableSemverRegex = '^\d+\.\d+\.\d+$' + + if ("${{ parameters.AllowNpmLatestDistTagMove }}" -ne "true" -and "${{ parameters.SkipNpmPointerPublish }}" -ne "true") { + $pointerPackages = @($scheduledPackages | Where-Object { $_.Name -eq '@microsoft/aspire-cli' }) + if ($pointerPackages.Count -ne 1) { + Write-Error "Expected exactly one scheduled @microsoft/aspire-cli pointer package while checking the npm latest dist-tag, found $($pointerPackages.Count)." + exit 1 + } + + $pointerPackage = $pointerPackages[0] + if ($pointerPackage.Version -notmatch $stableSemverRegex) { + Write-Error "Stable npm latest dist-tag validation expected a stable SemVer version, but scheduled pointer package version is '$($pointerPackage.Version)'." + exit 1 + } + + $latestOutput = & npm view @microsoft/aspire-cli@latest version --registry=https://registry.npmjs.org/ --loglevel=warn 2>&1 + $latestExitCode = $LASTEXITCODE + $latestText = ($latestOutput | ForEach-Object { "$_" }) -join "`n" + if ($latestExitCode -eq 0) { + $latestVersion = $latestOutput | ForEach-Object { "$_".Trim() } | Where-Object { $_ -match $stableSemverRegex } | Select-Object -First 1 + if ([string]::IsNullOrWhiteSpace($latestVersion)) { + Write-Error "Unable to parse the current @microsoft/aspire-cli@latest version as stable SemVer. Output: $latestText" + exit 1 + } + + if ([version]$pointerPackage.Version -lt [version]$latestVersion) { + Write-Error "Publishing $($pointerPackage.Spec) would move the npm latest dist-tag backward from $latestVersion. Set SkipNpmPublish=true for older servicing releases, or set AllowNpmLatestDistTagMove=true only after release-owner approval." + exit 1 + } + + Write-Host "Scheduled pointer package $($pointerPackage.Version) will not move npm latest backward from $latestVersion." + } elseif ($latestText -match '(?i)(\bE404\b|404 Not Found)') { + Write-Host "@microsoft/aspire-cli@latest is not published yet; latest dist-tag guard has nothing to compare." + } else { + Write-Error "Unable to query @microsoft/aspire-cli@latest before publishing. Output: $latestText" + exit 1 + } + } elseif ("${{ parameters.AllowNpmLatestDistTagMove }}" -eq "true") { + Write-Warning "AllowNpmLatestDistTagMove=true; skipping npm latest dist-tag downgrade guard." + } + + $collisions = [System.Collections.Generic.List[string]]::new() + $verificationFailures = [System.Collections.Generic.List[string]]::new() + + foreach ($package in $scheduledPackages) { + $packageSpec = $package.Spec + Write-Host "Checking npm registry for $packageSpec" + $viewOutput = & npm view $packageSpec version --registry=https://registry.npmjs.org/ --loglevel=warn 2>&1 + $viewExitCode = $LASTEXITCODE + $viewText = ($viewOutput | ForEach-Object { "$_" }) -join "`n" + + if ($viewExitCode -eq 0) { + $resolvedVersion = $viewOutput | ForEach-Object { "$_".Trim() } | Where-Object { $_ -match $semverRegex } | Select-Object -First 1 + if ($resolvedVersion -eq $package.Version) { + $collisions.Add($packageSpec) | Out-Null + } elseif ([string]::IsNullOrWhiteSpace($resolvedVersion)) { + $verificationFailures.Add("npm view $packageSpec succeeded but did not return a semver version. Output: $viewText") | Out-Null + } else { + $verificationFailures.Add("npm view $packageSpec returned unexpected version '$resolvedVersion'. Output: $viewText") | Out-Null + } + } elseif ($viewText -match '(?i)(\bE404\b|404 Not Found)') { + Write-Host " not published yet" + } else { + $verificationFailures.Add("npm view $packageSpec failed with exit code $viewExitCode. Output: $viewText") | Out-Null + } + } + + if ($verificationFailures.Count -gt 0) { + Write-Error ("Unable to verify whether every scheduled npm package is unpublished. " + ($verificationFailures -join ' | ')) + exit 1 + } + + if ($collisions.Count -gt 0) { + Write-Error ("The following scheduled npm package version(s) already exists on npm and cannot be published again: " + ($collisions -join ', ') + ". Set SkipNpmRidPublish=true only when all RID packages for this version are already published and should be skipped. Set SkipNpmPointerPublish=true only when the pointer package for this version is already published and should be skipped.") + exit 1 + } + + Write-Host "No scheduled npm package versions already exist on npm." + displayName: 'Verify npm Packages Are Not Already Published' + - ${{ if eq(parameters.SkipNpmRidPublish, false) }}: - template: MicroBuild.Publish.yml@MicroBuildTemplate parameters: @@ -1362,8 +1535,8 @@ extends: contentSource: 'Folder' folderLocation: '$(Pipeline.Workspace)\npm\rid-packages' waitForReleaseCompletion: true - owners: '${{ parameters.NpmPublishOwners }}' - approvers: '${{ parameters.NpmPublishApprovers }}' + owners: '$(NpmPublishOwnersEffective)' + approvers: '$(NpmPublishApproversEffective)' - powershell: | $delayMinutes = [int]'${{ parameters.NpmRegistryPropagationDelayMinutes }}' @@ -1532,8 +1705,8 @@ extends: contentSource: 'Folder' folderLocation: '$(Pipeline.Workspace)\npm\pointer-package' waitForReleaseCompletion: true - owners: '${{ parameters.NpmPublishOwners }}' - approvers: '${{ parameters.NpmPublishApprovers }}' + owners: '$(NpmPublishOwnersEffective)' + approvers: '$(NpmPublishApproversEffective)' - ${{ if eq(parameters.SkipNpmPointerPublish, true) }}: - powershell: | diff --git a/eng/pipelines/templates/npm-cli-install-validation-steps.yml b/eng/pipelines/templates/npm-cli-install-validation-steps.yml new file mode 100644 index 00000000000..89e458fa1e6 --- /dev/null +++ b/eng/pipelines/templates/npm-cli-install-validation-steps.yml @@ -0,0 +1,34 @@ +parameters: + - name: rid + type: string + - name: validationSummaryArtifactName + type: string + - name: preSteps + type: stepList + default: [] + +steps: + - checkout: self + fetchDepth: 1 + - ${{ each step in parameters.preSteps }}: + - ${{ step }} + # Download the just-built npm tarballs the build stage published as + # blob artifacts via stage-native-cli-tool-packages.ps1. Filter to + # avoid pulling unrelated blob assets. + - task: DownloadPipelineArtifact@2 + displayName: 🟣Download npm packages from build + inputs: + artifact: BlobArtifacts + itemPattern: '**/microsoft-aspire-cli*.tgz' + targetPath: '$(Pipeline.Workspace)/npm-packages' + - task: NodeTool@0 + displayName: 🟣Install Node.js + inputs: + versionSpec: '22.x' + - template: /eng/pipelines/templates/prepare-npm-cli-packages.yml@self + parameters: + npmPackagesDir: $(Pipeline.Workspace)/npm-packages + expectedVersion: $(aspireVersion) + rid: ${{ parameters.rid }} + validationSummaryArtifactName: ${{ parameters.validationSummaryArtifactName }} + skipRegistryResolution: true diff --git a/tests/Aspire.Cli.Tests/Npm/AspireJsLauncherTests.cs b/tests/Aspire.Cli.Tests/Npm/AspireJsLauncherTests.cs index 008a74fdf9a..9c6f3d56711 100644 --- a/tests/Aspire.Cli.Tests/Npm/AspireJsLauncherTests.cs +++ b/tests/Aspire.Cli.Tests/Npm/AspireJsLauncherTests.cs @@ -268,19 +268,7 @@ private static FakeNpmLayout CreateFakeNpmLayout( var binaryName = RuntimeInformation.IsOSPlatform(OSPlatform.Windows) ? "aspire.exe" : "aspire"; var binaryPath = Path.Combine(ridBinDir, binaryName); - File.Copy(GetNodeExecutablePath(), binaryPath); - - if (!RuntimeInformation.IsOSPlatform(OSPlatform.Windows)) - { - var chmod = Process.Start(new ProcessStartInfo - { - FileName = "chmod", - ArgumentList = { "+x", binaryPath }, - RedirectStandardError = true, - UseShellExecute = false - })!; - chmod.WaitForExit(); - } + CreateFakeNativeBinary(binaryPath); var probeScript = Path.Combine(rootPath, "probe-native.js"); File.WriteAllText(probeScript, """ @@ -296,6 +284,35 @@ private static FakeNpmLayout CreateFakeNpmLayout( return new FakeNpmLayout(launcherScript, cacheDir, probeScript, Path.Combine(ridPackageDir, "package.json")); } + private static void CreateFakeNativeBinary(string binaryPath) + { + if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows)) + { + File.Copy(GetNodeExecutablePath(), binaryPath); + return; + } + + // Keep the fake native binary as a small script on Unix. Some macOS CI + // Node builds abort when copied and executed from a different path/name, + // which obscures what this fixture actually needs to validate: launcher + // copy/cache behavior plus environment and argv forwarding. + File.WriteAllText(binaryPath, """ + #!/bin/sh + exec node "$@" + """); + + var result = RunProcess(new ProcessStartInfo + { + FileName = "chmod", + ArgumentList = { "+x", binaryPath }, + RedirectStandardOutput = true, + RedirectStandardError = true, + UseShellExecute = false + }); + + Assert.Equal(0, result.ExitCode); + } + private static ProcessResult RunLauncher(string launcherScript, string cacheDir, string[] args, string? requiredScript = null) { var psi = new ProcessStartInfo diff --git a/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs b/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs index 7369d69a380..34ed923b48f 100644 --- a/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs +++ b/tests/Infrastructure.Tests/Pipelines/NpmCliPackageTests.cs @@ -172,9 +172,99 @@ public async Task PointerPackageRequiresNode20OrLater() Assert.DoesNotContain("node = '>=18'", packScript); } + [Fact] + public async Task NpmInstallValidationJobsUseExplicitJobsSharedStepsTemplateAndCentralArtifactNames() + { + var commonVariables = await ReadRepoFileAsync("eng/pipelines/common-variables.yml"); + var buildPipeline = await ReadRepoFileAsync("eng/pipelines/azure-pipelines.yml"); + var releasePipeline = await ReadRepoFileAsync("eng/pipelines/release-publish-nuget.yml"); + + Assert.Contains("NPM_VALIDATION_SUMMARY_WIN_X64_ARTIFACT", commonVariables); + Assert.Contains("NPM_VALIDATION_SUMMARY_LINUX_X64_ARTIFACT", commonVariables); + Assert.Contains("NPM_VALIDATION_SUMMARY_OSX_ARTIFACT", commonVariables); + + Assert.Equal(3, CountOccurrences(buildPipeline, "template: /eng/pipelines/templates/npm-cli-install-validation-steps.yml@self")); + Assert.DoesNotContain("template: /eng/pipelines/templates/npm-cli-install-validation-job.yml@self", buildPipeline); + Assert.Contains("job: NpmInstall_Windows_x64", buildPipeline); + Assert.Contains("job: NpmInstall_Linux_x64", buildPipeline); + Assert.Contains("job: NpmInstall_macOS", buildPipeline); + Assert.DoesNotContain("validationSummaryArtifactName: npm-validation-summary-win-x64", buildPipeline); + Assert.DoesNotContain("validationSummaryArtifactName: npm-validation-summary-linux-x64", buildPipeline); + Assert.DoesNotContain("validationSummaryArtifactName: npm-validation-summary-osx", buildPipeline); + + Assert.DoesNotContain("artifact: npm-validation-summary-win-x64", releasePipeline); + Assert.DoesNotContain("artifact: npm-validation-summary-linux-x64", releasePipeline); + Assert.DoesNotContain("artifact: npm-validation-summary-osx", releasePipeline); + Assert.Contains("$(NPM_VALIDATION_SUMMARY_WIN_X64_ARTIFACT)", releasePipeline); + Assert.Contains("$(NPM_VALIDATION_SUMMARY_LINUX_X64_ARTIFACT)", releasePipeline); + Assert.Contains("$(NPM_VALIDATION_SUMMARY_OSX_ARTIFACT)", releasePipeline); + } + + [Fact] + public async Task ReleasePipelinePreflightsScheduledNpmPackagesBeforePublishing() + { + var releasePipeline = await ReadRepoFileAsync("eng/pipelines/release-publish-nuget.yml"); + + var preflightIndex = releasePipeline.IndexOf("Verify npm Packages Are Not Already Published", System.StringComparison.Ordinal); + var publishIndex = releasePipeline.IndexOf("template: MicroBuild.Publish.yml@MicroBuildTemplate", System.StringComparison.Ordinal); + + Assert.True(preflightIndex >= 0, "Expected an already-published npm package preflight."); + Assert.True(publishIndex >= 0, "Expected npm MicroBuild publish template usage."); + Assert.True(preflightIndex < publishIndex, "Already-published npm package preflight must run before MicroBuild publish."); + Assert.Contains("SkipNpmRidPublish", releasePipeline); + Assert.Contains("SkipNpmPointerPublish", releasePipeline); + Assert.Contains("npm view $packageSpec version", releasePipeline); + Assert.Contains("already exists on npm", releasePipeline); + Assert.Contains("Set SkipNpmRidPublish=true", releasePipeline); + Assert.Contains("Set SkipNpmPointerPublish=true", releasePipeline); + } + + [Fact] + public async Task ReleasePipelineGuardsNpmLatestDistTagAgainstServicingDowngrade() + { + var releasePipeline = await ReadRepoFileAsync("eng/pipelines/release-publish-nuget.yml"); + + Assert.Contains("AllowNpmLatestDistTagMove", releasePipeline); + Assert.Contains("npm view @microsoft/aspire-cli@latest version", releasePipeline); + Assert.Contains("would move the npm latest dist-tag backward", releasePipeline); + Assert.Contains("SkipNpmPublish=true for older servicing releases", releasePipeline); + } + + [Fact] + public async Task ReleasePipelineUsesEffectiveNpmOwnersAndApproversFromSingleSource() + { + var commonVariables = await ReadRepoFileAsync("eng/pipelines/common-variables.yml"); + var releasePipeline = await ReadRepoFileAsync("eng/pipelines/release-publish-nuget.yml"); + + Assert.Contains("NPM_PUBLISH_REQUIRED_OWNERS", commonVariables); + Assert.Contains("NPM_PUBLISH_REQUIRED_APPROVERS", commonVariables); + Assert.Contains("default: ''", releasePipeline); + Assert.Contains("NpmPublishOwnersEffective", releasePipeline); + Assert.Contains("NpmPublishApproversEffective", releasePipeline); + Assert.Contains("owners: '$(NpmPublishOwnersEffective)'", releasePipeline); + Assert.Contains("approvers: '$(NpmPublishApproversEffective)'", releasePipeline); + Assert.DoesNotContain("$requiredNpmOwners = @('joperezr', 'ankj')", releasePipeline); + Assert.DoesNotContain("owners: '${{ parameters.NpmPublishOwners }}'", releasePipeline); + Assert.DoesNotContain("approvers: '${{ parameters.NpmPublishApprovers }}'", releasePipeline); + } + private Task ReadRepoFileAsync(string relativePath) => File.ReadAllTextAsync(Path.Combine(_repoRoot, relativePath.Replace('/', Path.DirectorySeparatorChar))); + private static int CountOccurrences(string value, string substring) + { + var count = 0; + var index = 0; + + while ((index = value.IndexOf(substring, index, System.StringComparison.Ordinal)) >= 0) + { + count++; + index += substring.Length; + } + + return count; + } + private static string FindRepoRoot() { string? current = AppContext.BaseDirectory; diff --git a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs index bcb1a4db648..6fc5f7401c4 100644 --- a/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs +++ b/tests/Infrastructure.Tests/Pipelines/ReleasePublishNugetPipelineTests.cs @@ -22,12 +22,12 @@ public async Task ValidatesNpmPublishPreconditionsBeforeNuGetPublish() AssertBefore( pipeline, - "NpmPublishOwners must be set before publishing npm packages.", + "$parameterName must include required ESRP alias(es)", nuGetPublishIndex); AssertBefore( pipeline, - "NpmPublishApprovers must be set before publishing npm packages.", + "Assert-ContainsRequiredNpmAliases $normalizedApprovers $requiredNpmApprovers 'NpmPublishApprovers'", nuGetPublishIndex); } @@ -91,12 +91,19 @@ public async Task RoutesMicroBuildPublishAuthPluginToDncengFeedOrDisablesIt() [Fact] public async Task UsesRequiredNpmEsrpOwnersAndApprover() { + var commonVariables = await ReadRepoFileAsync("eng/pipelines/common-variables.yml"); var pipeline = await ReadRepoFileAsync("eng/pipelines/release-publish-nuget.yml"); - Assert.Contains("default: 'joperezr,ankj'", pipeline); - Assert.Contains("default: 'adamratzman'", pipeline); - Assert.Contains("$requiredNpmOwners = @('joperezr', 'ankj')", pipeline); - Assert.Contains("$requiredNpmApprovers = @('adamratzman')", pipeline); + Assert.Contains("- name: NPM_PUBLISH_REQUIRED_OWNERS", commonVariables); + Assert.Contains("value: joperezr,ankj", commonVariables); + Assert.Contains("- name: NPM_PUBLISH_REQUIRED_APPROVERS", commonVariables); + Assert.Contains("value: adamratzman", commonVariables); + Assert.Contains("displayName: 'npm ESRP owners (comma-separated Microsoft aliases or emails; leave blank for repo default)'", pipeline); + Assert.Contains("displayName: 'npm ESRP approvers (comma-separated Microsoft aliases or emails; leave blank for repo default)'", pipeline); + Assert.Contains("$requiredNpmOwnersValue = \"$(NPM_PUBLISH_REQUIRED_OWNERS)\"", pipeline); + Assert.Contains("$requiredNpmApproversValue = \"$(NPM_PUBLISH_REQUIRED_APPROVERS)\"", pipeline); + Assert.Contains("owners: '$(NpmPublishOwnersEffective)'", pipeline); + Assert.Contains("approvers: '$(NpmPublishApproversEffective)'", pipeline); Assert.Contains("NpmPublishOwners and NpmPublishApprovers must not contain the same alias(es)", pipeline); }