Add Aspire CLI npm package release integration

[adamint]

Description

This completes the production path for distributing the Aspire CLI through npm while keeping publishing under the existing Microsoft release process.

The PR now:

• Defines the npm package layout: @microsoft/aspire-cli as the pointer package plus RID-specific packages such as @microsoft/aspire-cli-linux-x64, @microsoft/aspire-cli-win-x64, and @microsoft/aspire-cli-osx-arm64.
• Packages npm tarballs from the same signed native CLI archive payloads used by the existing native CLI artifacts, and verifies RID package binaries byte-for-byte against the native archive before upload.
• Adds npm install/update detection so aspire update can point npm-installed users at npm update -g @microsoft/aspire-cli.
• Requires npm tarballs in the native CLI CI staging path and publishes them as flat shipping blob artifacts for release consumption.
• Moves npm publishing into the Azure DevOps release pipeline using MicroBuild/ESRP: RID packages are submitted first, the pipeline waits for registry propagation, then the pointer package is submitted.
• Documents package layout, version/update behavior, publishing flow, recovery flags, and product/security tradeoffs in docs/specs/npm-cli-package.md and docs/release-process.md.

Security considerations

The .tgz container is not separately signed. Integrity relies on the signed native CLI payloads where platform signing applies, CI verification that npm package binaries match the signed native archives, SBOM-covered release artifacts, ESRP/MicroBuild submission controls, and npm registry integrity. Publishing does not use repository-scoped npm tokens or GitHub Actions Trusted Publisher; release operators must provide ESRP owners/approvers through the release pipeline parameters.

Fixes #17045

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
    • If yes, did you have an API Review for it?
      • Yes
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
      • No
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • No
• Does the change require an update in our Aspire docs?
  • Yes
    • Link to aspire.dev issue:
      • New issue
  • No

Validation:

• ./restore.sh
• YAML parse of eng/pipelines/release-publish-nuget.yml, eng/pipelines/azure-pipelines.yml, and eng/pipelines/azure-pipelines-unofficial.yml
• XML parse of eng/Publishing.props
• dotnet test --project tests/Infrastructure.Tests/Infrastructure.Tests.csproj --no-launch-profile -- --filter-class "*.StageNativeCliToolPackagesTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true" (12 passed)
• git diff --check

[adamint]

@copilot review

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 17297

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 17297"

[adamint]

PR review while validating internal CI / release dry-run end-to-end. 3 concrete issues to address:

1. eng/clipack/npm/aspire.js — launcher comment vs. code mismatch; concurrent first-runs can fail on Windows.
2. eng/pipelines/release-publish-nuget.yml — registry smoke-test finally block can mask a successful run on Windows.
3. eng/clipack/npm/aspire.js — unbounded per-version cache growth; no eviction or documented cleanup.

No style / nit comments. Internal CI (build 2987420) and release pipeline 1600 dry-run still in progress — I'll comment separately with the dry-run report.

[adamint]

Addressed the adversarial review findings from review #4392976259 in b6350b4:

#	Finding	Fix
1	aspire.js rename-failure path always rethrew, so concurrent first-runs on Windows could fail spuriously even when the existing cached binary was already valid.	Catch now re-checks needsCopy(sourcePath, targetPath); if the target is already a valid copy, the tmp file is discarded and targetPath is returned. Only unexpected errors propagate.
2	Release pipeline finally { Remove-Item -Recurse -Force } could rethrow on Windows (file lock during cleanup) and mask a successful aspire --version smoke.	finally block now uses Remove-Item -ErrorAction Stop inside a try/catch that downgrades cleanup failures to Write-Warning.
3	Per-version cache grows without bound.	Acknowledged as follow-up — left as-is for this PR; freshness check already prevents stale binaries within a version, multi-version retention policy can ship separately.

Pushed to dnceng/internal and source-built; CI is running off the same commit.

[adamint]

GitHub Actions failures are pre-existing main breakage, not from this PR

The 4 GitHub Actions failures in run 26663931880 (Tests / Setup for tests, Tests / Final Test Results, Stabilization Check, Final Results) all root-cause to the same compile error, and none are caused by changes in this PR:

tests/Aspire.Cli.EndToEnd.Tests/TypeScriptEmptyAppHostTemplateTests.cs(79,24): error CS1061:
  'Hex1bTerminalAutomator' does not contain a definition for 'RunCommandFailFastAsync'

Root cause on main

• Fix TypeScript AppHost async callback deadlock #17575 (4cfc99d) added a new TS deadlock-repro test calling auto.RunCommandFailFastAsync(...) 3 times.
• Fix CLI Ctrl+C/SIGTERM shutdown: responsive cancellation and double-signal bug #17588 (b2df78e) — merged after Fix TypeScript AppHost async callback deadlock #17575 — renamed RunCommandFailFastAsync → RunCommandAsync in tests/Shared/Hex1bAutomatorTestHelpers.cs and removed the old method, breaking the just-added test.

main HEAD (6436994f5f) is broken for the CLI E2E test project. The breakage is masked on push-to-main by .github/workflows/tests.yml:31:

buildArgs: '/p:IncludeTemplateTests=true /p:IncludeCliE2ETests=${{ github.event_name == ''pull_request'' }}'

IncludeCliE2ETests=false on push skips the project. On pull_request events it builds → compile fails → all downstream Tests jobs collapse. Every open PR sees the same failure right now.

Fixes already in flight (not from this PR)

• Fix TypeScript deadlock repro E2E test #17701 "Fix TypeScript deadlock repro E2E test" — JamesNK
• Fix CLI E2E command helper calls #17702 "Fix CLI E2E command helper calls" — sebastienros

Once either merges to main, PRs (including this one) will recover automatically; nothing in this branch needs to change. Merging main into this branch would only inherit the same broken state, so I'm deliberately not doing that. Internal CI (AzDO def 1602) is unaffected and currently green / in-progress on this same commit (b6350b465).

[adamint]

Dry-run progress update

Pushed 727fe3ca9d — a Bash 3.2 portability fix for the npm install validation template.

Why: dry-run build 2987449 progressed through native build ✅, Build (Windows extension/sign/publish) ✅, Publish Assets ✅, and then failed in Prepare Installers → npm install validation (macOS native RID) at the 🟣Locate pointer and RID tarballs step with:

/Users/runner/work/_temp/<id>.sh: line 10: shopt: globstar: invalid shell option name
Bash exited with code '1'.

Root cause: macOS still ships /bin/bash 3.2 (last GPLv2 version), and the AzDO Bash@3 task uses /bin/bash. Two constructs in eng/pipelines/templates/prepare-npm-cli-packages.yml required Bash 4+:

• shopt -s globstar
• mapfile -t

Fix: replaced both with a portable find … | while IFS= read loop. Linux and Windows runners (Git Bash 5) were unaffected — the failure was platform-specific to macOS. Verified locally against GNU bash 3.2.57.

Added regression test in Infrastructure.Tests that fails the build if any of shopt -s globstar, mapfile, readarray, or declare -A are reintroduced into this template.

Queued dry-run build 2987514 off 727fe3ca9d to verify the fix.

GitHub Actions failures on this PR are unrelated to these changes — see the earlier comment about main being broken on PR events (open fix PRs #17701 and #17702).

[adamint]

Dry-run progress update (2)

Pushed 91de8c9d20 — SemVer 2.0 build-metadata acceptance fix in npm install validation.

Why: dry-run build 2987514 progressed past the Bash 3.2 fix and got further (Build/Sign ✅, Build/Windows ✅, Publish Assets ✅, Homebrew Cask ✅, native build ✅) before failing in macOS 🟣Install, verify, and uninstall @microsoft/aspire-cli 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'

Root cause: 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). My previous regex required the line to end at the pre-release segment so the +<sha> suffix made the whole match fail and the extracted version was empty.

Fix: extend the regex to optionally accept +<buildmeta>, then strip it with ${var%+*} (POSIX, Bash 3.2 compatible) before comparing to the npm package version. The PowerShell post-publish smoke in release-publish-nuget.yml already handles this case at line ~1298.

Linux x64 and Windows x64 npm install validation phases were in progress and would have hit the same regex bug; I cancelled the build to save runner time.

Queued dry-run build 2987581 off 91de8c9d20.

GitHub Actions: merged in upstream main (PR #17701 fixed the E2E test breakage that was failing the PR build).

[adamint]

Status update on the npm install validation hang:

Diagnosis: npm install -g --omit=optional <pointer>.tgz still resolves optional-dep metadata from the npm registry while building the dep tree. The pointer declares all 7 supported RIDs as optionalDependencies pinned to the just-built version, which doesn't exist in the public registry during validation. On the 1ES macOS pool that lookup gets a fast 404 (3s total install); on the 1ES Linux/Windows pools the registry call is blackholed by network isolation, so each of the 7 lookups burns the full fetch-timeout — that's the 9-minute hang on Linux/Windows in build 2987581.

Fix (67bc6b3453):

• Add --offline --fetch-timeout=15000 to both npm install and npm uninstall. With --offline npm never touches the network, optional deps are skipped without resolution attempts, and the local pointer/RID tarballs install straight from disk.
• NPM_CONFIG_CACHE already points to a fresh empty directory so --offline cannot reuse a poisoned cache.
• Local verification on a synthetic 8-dep pointer: install in 121ms (vs 9m), uninstall in 88ms, launcher executes correctly.

Regression test: PrepareNpmCliPackagesScriptInstallsOfflineWithTimeout asserts --offline and --fetch-timeout= remain in the script.

Build 2987581 cancelled (Windows still hung on the same step). Fresh dry-run build 2987640 queued at 67bc6b3453.

[adamint]

🔁 Dry-run status update — applied multi-model code-review fixes + resynced with #17630 head 0e2136ef.

New commits (5):

1. 7190d84519 Resync Corepack changes with latest PR Pin Corepack explicitly for the VS Code extension build #17630 (head 0e2136e)
2. 02d11d80ff Fix npm launcher: lazy package map load, musl arm64, signal forwarding
3. 2e174cfa70 Fix RID README rendering: use literal here-string for PowerShell
4. d8966ed117 Verify RID packages on npm before publishing pointer; reject empty version
5. 70d60261d2 Add regression tests for npm launcher, README rendering, and preflight

Issues found / fixed:

Source	Severity	Issue	Fix
Opus 4.7	HIGH	SkipNpmRidPublish=true could ship pointer pkg without its RID deps	Added Verify npm RID Packages Present Before Pointer Publish step that walks pointer optionalDependencies and npm views each before submission
Opus 4.7	MEDIUM	Alpine arm64 (musl) silently fell through to glibc binary	Added if (arch === 'arm64' && musl) throw Unsupported platform
Opus 4.7	MEDIUM	aspire --version with empty stdout passed post-publish smoke	Added explicit $versionLine.Count -eq 0 guard
Opus 4.7	MEDIUM	loadRidPackageNames() ran at module top-level, bypassing top-level catch	Made lazy; wrapped read/parse in try/catch surfacing friendly "installation is corrupted"
Opus 4.8	LOW	Expandable PowerShell here-string ate backticks AND $Rid interpolation	Switched RID README to literal @'...'@ + -replace placeholders
GPT-5.5	MEDIUM	Wrapper never forwarded SIGINT/SIGTERM to native child	Added process.once registration for SIGINT/SIGTERM/SIGHUP/SIGQUIT

Regression test coverage:

• PointerPublishPreflightsRidPackagesAreOnRegistry
• PostPublishSmokeRejectsEmptyAspireVersionOutput
• LauncherDetectsMuslArm64AndThrowsUnsupported
• LauncherForwardsTerminatingSignalsToChild
• LauncherLoadsRidPackageMapInsideErrorHandler
• PackScriptUsesLiteralHereStringForRidReadme

All 12 ReleasePublishNugetPipelineTests + NpmCliPackageTests pass locally.

Dry-run pipeline status:

• Internal CI 1602: queued build 2987671 at 70d60261d2 (ETA ~1h50)
• Release dry-run 1600: will queue on CI success

Cancelled stale build 2987640.

[adamint]

✅ Monday release dry-run: HIGH confidence

Completed comprehensive end-to-end dry-run validation against the internal microsoft-aspire-Release-To-NuGet pipeline (1600) on dnceng — nothing was published.

Validation runs

Build	Pipeline	Result	Purpose
2987671	CI 1602	partiallySucceeded¹	Source-artifact producer (real ESRP-signed .tgz + .sig)
2987740	Release 1600	partiallySucceeded¹	All-Skip-true baseline — proves zero-publish path
2987776	Release 1600	partiallySucceeded¹	Comprehensive: SkipNpmPublish=false + sig sanity + registry reach

¹ Only succeededWithIssues cause: 1ES PT non-blocking "branch validation failed" because dry-runs are off a users/* branch, not main. These warnings will not appear on Monday.

What was exercised end-to-end

• ✅ Pipeline resource pinning (proper API: POST /_apis/pipelines/1600/runs with resources.pipelines.aspire-build.version)
• ✅ Download all 4 source-artifact groups (PackageArtifacts + 3 npm-package platforms) + SBOM/CodeSign validation
• ✅ OpenPGP signature content sanity check against real ESRP-signed .sig sidecars (size ≥64 bytes + ASCII-armor or binary OpenPGP marker)
• ✅ npm ping --registry=https://registry.npmjs.org/ registry reachability
• ✅ MicroBuild Telemetry (TeamName), Network Isolation, dnceng feedSource — all pass
• ✅ Skip-flag wiring routes to no-op tasks correctly
• ✅ Zero failed tasks anywhere
• ✅ Zero external publication: no nuget push, no npm publish, no gh release upload, no winget commit, no homebrew dispatch

Hardening landed (from multi-model review — Opus 4.7/4.8, GPT 5.5, Aspire-arch)

1. engines.node >= "20.0.0" on the pointer package
2. Explicit --registry=https://registry.npmjs.org/ pin on every npm operation (no agent-config dependency)
3. Preflight retry loop (10×30s) for npm registry propagation
4. Strict semver regex on parsed npm view output
5. PGP .sig content sanity check (in both source pipeline BuildAndTest.yml and release pipeline release-publish-nuget.yml)
6. Windows CRLF strip on aspire --version capture (defense-in-depth — current Windows runner happens to not need it, but Bash 3.2/PowerShell roundtripping is fragile)
7. +7 regression tests (16 → 21 total in Infrastructure.Tests, all pass)

Source-build pinning gotcha (carry forward)

The classic POST /_apis/build/builds API silently ignores resources.pipelines.{alias}.version and auto-selects the latest CI build from any branch. Two release runs (2987764, 2987773) failed for this reason. The correct API is POST /_apis/pipelines/{id}/runs, which honors the resource pin. The AzDO UI uses the correct API by default — Monday's queue-from-UI flow will pick the latest main CI build correctly.

Monday checklist

• Pipeline YAML verified correct (this dry-run)
• All hardening + tests landed in 4ee6d2ceb1
• Admin (not testable from pipeline): 1ES signing approval for pipeline 1600, DevDivEsrpAzDoSrvConn grant

Constraint compliance

DryRun=true and SkipNpmPublish=true/SkipNuGetPublish=true (where applicable) were enforced on every queue. Static-audited the YAML: MicroBuild.Publish.yml@MicroBuildTemplate (the actual npm publish call) is gated by and(DryRun=false, SkipNpmPublish=false, IsPrerelease=false) — physically unreachable in any dry-run path.