Skip to content

Add Aspire CLI npm package release integration - #17297

Merged
Adam Ratzman (adamint) merged 39 commits into
microsoft:mainfrom
adamint:dev/adamint/npm-cli-package-followups
May 31, 2026
Merged

Adam Ratzman (adamint) merged 39 commits into
microsoft:mainfrom
adamint:dev/adamint/npm-cli-package-followups

Conversation

@adamint

@adamint Adam Ratzman (adamint) commented May 20, 2026 •

Copy link
Copy Markdown
Member

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?

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

David Fowler (davidfowl) and others added 7 commits May 7, 2026 20:28
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>
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>
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>
- 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>
…tion

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>
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>
…eout

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>
Adam Ratzman (adamint) and others added 3 commits May 28, 2026 15:08
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>
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 <rid>.tgz && npm install -g --omit=optional <pointer>.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>
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>
@adamint

Copy link
Copy Markdown
Member Author

Copilot review

@adamint
Adam Ratzman (adamint) marked this pull request as ready for review May 28, 2026 21:32
@adamint
Adam Ratzman (adamint) marked this pull request as draft May 28, 2026 21:32
@adamint
Adam Ratzman (adamint) changed the base branch from davidfowl/npm-cli-package to main May 28, 2026 21:33
…ackage-followups

# Conflicts:
#	docs/release-process.md
#	eng/pipelines/release-publish-nuget.yml
#	src/Aspire.Cli/Commands/UpdateCommand.cs
#	src/Aspire.Cli/Resources/UpdateCommandStrings.Designer.cs
#	src/Aspire.Cli/Resources/UpdateCommandStrings.resx
#	src/Aspire.Cli/Utils/CliUpdateNotifier.cs

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@github-actions

github-actions Bot commented May 28, 2026 •

Copy link
Copy Markdown
Contributor

🚀 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"

Adam Ratzman (adamint) and others added 3 commits May 28, 2026 17:49
…i-package-followups

# Conflicts:
#	docs/release-process.md
#	eng/pipelines/azure-pipelines.yml
#	eng/pipelines/release-publish-nuget.yml

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
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>
Use Node 22 for native CLI npm packaging and install-validation CI paths.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@adamint Adam Ratzman (adamint) changed the title Add npm publishing workflow for Aspire CLI packages Add Aspire CLI npm package release integration May 29, 2026
@adamint
Adam Ratzman (adamint) marked this pull request as ready for review May 29, 2026 03:43
Copilot AI review requested due to automatic review settings May 29, 2026 03:43
@adamint

Copy link
Copy Markdown
Member Author

/backport to release/13.4

@github-actions

Copy link
Copy Markdown
Contributor

Started backporting to release/13.4 (link to workflow run)

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Adam Ratzman (@adamint) backporting to release/13.4 failed, the patch most likely resulted in conflicts. Please backport manually!

git am output
$ git am --3way --empty=keep --ignore-whitespace --keep-non-patch changes.patch

Applying: Add npm packages for Aspire CLI
Applying: Document Aspire CLI npm package POC
Applying: Add npm prior art to CLI package spec
Applying: Add npm publish workflow with provenance and OIDC support
Applying: Fix shell subshell variable scope bug in npm publish tarball verification
Applying: Fix npm workflow: ensure meta package waits for RID packages
Applying: Fix npm publish workflow: exact version matching and configurable timeout
Applying: Move @microsoft/aspire-cli npm publishing into the AzDO release pipeline
Using index info to reconstruct a base tree...
M	.github/workflows/build-cli-native-archives.yml
M	docs/release-process.md
M	eng/clipack/Common.projitems
M	eng/pipelines/azure-pipelines-unofficial.yml
M	eng/pipelines/azure-pipelines.yml
M	eng/pipelines/release-publish-nuget.yml
Falling back to patching base and 3-way merge...
Auto-merging .github/workflows/build-cli-native-archives.yml
Auto-merging docs/release-process.md
CONFLICT (content): Merge conflict in docs/release-process.md
Auto-merging eng/clipack/Common.projitems
Auto-merging eng/pipelines/azure-pipelines-unofficial.yml
Auto-merging eng/pipelines/azure-pipelines.yml
Auto-merging eng/pipelines/release-publish-nuget.yml
CONFLICT (content): Merge conflict in eng/pipelines/release-publish-nuget.yml
error: Failed to merge in the changes.
hint: Use 'git am --show-current-patch=diff' to see the failed patch
hint: When you have resolved this problem, run "git am --continue".
hint: If you prefer to skip this patch, run "git am --skip" instead.
hint: To restore the original branch and stop patching, run "git am --abort".
hint: Disable this message with "git config set advice.mergeConflict false"
Patch failed at 0008 Move @microsoft/aspire-cli npm publishing into the AzDO release pipeline
Error: The process '/usr/bin/git' failed with exit code 128

Link to workflow output

@adamint
Adam Ratzman (adamint) merged commit 3662de6 into microsoft:main May 31, 2026
617 of 621 checks passed
@github-actions github-actions Bot modified the milestones: 13.4, 13.5 May 31, 2026
Adam Ratzman (adamint) added a commit to adamint/aspire that referenced this pull request May 31, 2026
Backport of microsoft#17297 to release/13.4.

Adds npm packaging and release-pipeline publishing for the Aspire CLI:
pack/sign/verify of the @microsoft/aspire-cli pointer package and its
seven RID packages, npm install validation steps, npm publish + registry
validation stages in release-publish-nuget.yml, npm pipeline variables,
and CLI npm-install detection/update messaging.

The docs/release-process.md changes from the source PR are intentionally
omitted: on main they are interleaved with VS Code extension / Marketplace
release documentation that does not apply to release/13.4 (the VS Code
extension is not released from this branch).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Ankit Jain (radical) added a commit to radical/aspire that referenced this pull request May 31, 2026
Integrate the npm CLI package work from microsoft#17297 with the perf
restructure:

* azure-pipelines.yml Windows Build job: conflict resolved in our
  favor — Split C still removes the native-archive download tasks
  here (they live in the Assemble stage now).
* azure-pipelines.yml Assemble stage: stage-native-cli-tool-packages
  call updated with the new -RequireNpmPackages switch and renamed
  to match upstream's "Stage Native CLI Packages" display.
* eng/scripts/download-native-archives.ps1: extract
  microsoft-aspire-cli*.tgz alongside the existing nupkgs so the
  staging step finds them. Doc + warning text updated.
* DownloadNativeArchivesTests.cs happy-path test extended to
  include a tgz entry per RID and assert it lands in the nupkgs
  target dir.
* eng/Publishing.props, BuildAndTest.yml, build_sign_native.yml
  auto-merged cleanly.

The three new NpmInstall validation jobs land in prepare_installers
unchanged from upstream; that stage is already downstream of
Assemble in our restructure.
Ankit Jain (radical) added a commit to radical/aspire that referenced this pull request May 31, 2026
Brings in 48 commits from main, including:
* PR microsoft#17297 Aspire CLI npm package release integration (touches Publishing.props
  and the pipeline YAMLs my branch also touches for CLI symbols — both blocks
  coexist cleanly; download_native_symbols template reference preserved).
* Several PRs that landed on main as the forward-port equivalents of the
  release/13.4 backport commits this branch carried in its base (Foundry hosted
  agent APIs, Aspire skills installer, dashboard logging, CLI cancellation,
  VS Code extension fixes). All such conflicts resolved by taking main's
  version, which is the canonical forward-port.
Adam Ratzman (adamint) added a commit to microsoft/aspire.dev that referenced this pull request Jun 1, 2026
* Document Aspire CLI npm install method

Document npm distribution of the Aspire CLI (@microsoft/aspire-cli),
added in microsoft/aspire#17297:

- Add an "Install with npm" section to the install guide.
- Document install-aware `aspire update --self` behavior, including
  the npm update guidance the CLI prints.
- Note the npm install option in the 13.4 what's new page.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Note install-source-aware update in upgrade guide

Clarify that `aspire update --self` prints the package-manager command
for npm and .NET tool installs instead of replacing a managed binary.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Update src/frontend/src/content/docs/get-started/install-cli.mdx

* Address PR 1142 docs feedback

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Jose Perez Rodriguez (joperezr) pushed a commit that referenced this pull request Jun 2, 2026
* [release/13.4] Add Aspire CLI npm package release integration

Backport of #17297 to release/13.4.

Adds npm packaging and release-pipeline publishing for the Aspire CLI:
pack/sign/verify of the @microsoft/aspire-cli pointer package and its
seven RID packages, npm install validation steps, npm publish + registry
validation stages in release-publish-nuget.yml, npm pipeline variables,
and CLI npm-install detection/update messaging.

The docs/release-process.md changes from the source PR are intentionally
omitted: on main they are interleaved with VS Code extension / Marketplace
release documentation that does not apply to release/13.4 (the VS Code
extension is not released from this branch).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix Aspire CLI npm signing scope (#17770)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
pull Bot pushed a commit to tooniez/aspire that referenced this pull request Jun 2, 2026
Brings 43 release-branch commits forward onto main now that 13.4.0 has shipped.
This PR replaces the original automated merge (microsoft#17804) which had to be closed so
that conflict resolution and post-merge cleanups could be made on a non-protected
branch.

Conflict resolution summary (33 files):

* Equivalent backports (took main's commit identity): ChannelUpdateWorkflowTests,
  LoggingHelpersTests, the four extension test files, AspireEditorCommandProvider,
  appHostDiscovery.

* Release-only forwards (preserved): microsoft#17732 / microsoft#17756 Foundry hosted-agent protocol
  selection and cross-compute-environment endpoint references, microsoft#17573 stabilize
  PrebuiltAppHostServer staging globalPackagesFolder path, microsoft#17743 staging-identity
  CLI darc feed routing.

* Main-only forwards (preserved): microsoft#17506 Show discovered AppHosts in Aspire pane,
  microsoft#17547 Localize Aspire skills metadata errors, microsoft#17801 VS Code v1.12.0, microsoft#17297
  Aspire CLI npm package release integration, microsoft#17576 TerminalRun IAsyncDisposable,
  microsoft#17721 / microsoft#17723 VS Code telemetry, microsoft#17671 ATS baseline fix (re-applied manually
  on top of Foundry source taken from release).

* Hybrid (manually spliced): docs/contributing.md - kept main's restructured
  layout and inserted release's staging-validation paragraph; HostedAgentBuilder-
  Extension - took release base then re-applied microsoft#17671 asHostedAgent rename;
  UpdateCommandTests - took main and injected microsoft#17743's
  OverrideCliInformationalVersionConfigKey block.

Post-merge cleanups included in this PR:

* eng/Versions.props: revert StabilizePackageVersion to false (was flipped to
  true on release/13.4 by microsoft#17520 for shipping 13.4.0; main must stay in preview
  mode).

* .github/workflows/generate-api-diffs.yml: retarget back to main (was pointed
  at release/13.4 by microsoft#17696 release prep).

* .github/workflows/backmerge-release.yml: update from release/13.3 to
  release/13.4 (was stale - missed the 13.4 release-time bump).

* .github/workflows/milestone-assignment.yml: audited - already correct
  (main -> 13.5, release/13.4 -> 13.4.x); no change.

This merge commit must be preserved - do not squash on merge.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@github-actions github-actions Bot locked and limited conversation to collaborators Jul 1, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Ship Aspire CLI as an npm package

4 participants