From 705b210b2e988cfee545aa154445e9953813c0d7 Mon Sep 17 00:00:00 2001 From: digitallysavvy Date: Mon, 1 Jun 2026 15:57:25 -0400 Subject: [PATCH 1/4] feat(installer): add npm install migration path Add --replace-npm so users with a global npm-managed agoraio-cli can uninstall it before installing the standalone binary. Improve managed-install guidance to show manual uninstall and reinstall steps, and clarify that --force is only for intentional side-by-side installs. --- docs/install.md | 13 +++++++++++-- install.sh | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+), 2 deletions(-) diff --git a/docs/install.md b/docs/install.md index 6e93894..c5086b4 100644 --- a/docs/install.md +++ b/docs/install.md @@ -105,6 +105,8 @@ If your PowerShell execution policy blocks inline scripts, download `install.ps1 --list-versions Print recent published versions and exit. --force Reinstall even if the requested version is present, or proceed past an existing managed install warning. +--replace-npm If an existing npm-managed agora is detected, uninstall + agoraio-cli with npm before installing this binary. # Shell integration (auto-on; pass an opt-out flag to disable) --no-path Don't append the install directory to your shell rc file. @@ -137,7 +139,7 @@ If your PowerShell execution policy blocks inline scripts, download `install.ps1 -SkipShell Umbrella for -NoPath -NoCompletion. ``` -If another managed `agora` install is detected, the installer refuses by default to avoid creating two installs that shadow each other on PATH. Pass `--force` to install alongside it. +If another managed `agora` install is detected, the installer refuses by default to avoid creating two installs that shadow each other on PATH. Uninstall the existing package first, then re-run the standalone installer. For global npm installs, `--replace-npm` can perform that migration for you. Pass `--force` only when you intentionally want a side-by-side install. ## Uninstall @@ -317,7 +319,14 @@ $env:VERSION = "0.2.1" The shell installer refuses to install over an existing managed `agora` to avoid creating two installs that shadow each other on PATH. Either: - Keep using the existing install, or -- Re-run the installer with `--force` to install alongside it. +- Uninstall the existing package, then re-run the standalone installer: + + ```bash + curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh + ``` + +- If it is npm-managed, re-run the installer with `--replace-npm` to run `npm uninstall -g agoraio-cli` before installing the standalone binary. +- Re-run the installer with `--force` only if you intentionally want a side-by-side install. ### PATH issues diff --git a/install.sh b/install.sh index 7a9aca2..28ec3ab 100755 --- a/install.sh +++ b/install.sh @@ -45,6 +45,7 @@ NO_COLOR_ENV="${NO_COLOR:-}" # ---- Mode flags ------------------------------------------------------------ DRY_RUN=0 FORCE=0 +REPLACE_NPM=0 LIST_VERSIONS=0 PRERELEASE=0 QUIET=0 @@ -192,6 +193,8 @@ ${BOLD}Options:${RESET} --list-versions Print recent published versions and exit. --force Reinstall even if the requested version is already present, or proceed past a Homebrew/npm-managed install warning. + --replace-npm If an existing npm-managed agora is detected, uninstall + agoraio-cli with npm before installing this binary. ${BOLD}Shell integration${RESET} ${DIM}(auto-on; pass an opt-out flag to disable)${RESET} --no-path Don't append the install directory to your shell rc file. @@ -281,6 +284,10 @@ parse_args() { FORCE=1 shift ;; + --replace-npm) + REPLACE_NPM=1 + shift + ;; --no-path) NO_PATH=1 shift @@ -755,6 +762,25 @@ guard_managed_install() { return 0 fi + if [ "$MANAGED_INSTALL" = "npm" ] && [ "$REPLACE_NPM" = "1" ]; then + say_step "Replacing npm-managed Agora CLI at ${MANAGED_PATH}" + if [ "$DRY_RUN" = "1" ]; then + say " [dry-run] Would run: npm uninstall -g agoraio-cli" + return 0 + fi + if ! npm uninstall -g agoraio-cli; then + die "Could not uninstall npm-managed agoraio-cli. Run ${MANAGED_UPGRADE_CMD} or uninstall it manually, then retry." "$EXIT_INSTALL" + fi + hash -r 2>/dev/null || true + if current_path=$(command -v agora 2>/dev/null); then + if [ "$current_path" = "$MANAGED_PATH" ]; then + die "npm uninstall completed, but agora is still present at ${MANAGED_PATH}. Remove it manually or run with --force to install alongside it." "$EXIT_INSTALL" + fi + fi + say_ok "Removed npm package agoraio-cli." + return 0 + fi + if [ "$FORCE" = "1" ]; then warn "Detected ${MANAGED_INSTALL}-managed install at ${MANAGED_PATH}. Continuing because --force is set." return 0 @@ -762,6 +788,15 @@ guard_managed_install() { err "Detected ${MANAGED_INSTALL}-managed install at ${MANAGED_PATH}." say " Recommended: ${BOLD}${MANAGED_UPGRADE_CMD}${RESET}" + if [ "$MANAGED_INSTALL" = "npm" ]; then + say " To switch to the standalone installer manually:" + say " ${GREEN}npm uninstall -g agoraio-cli${RESET}" + say " ${GREEN}curl -fsSL https://raw.githubusercontent.com/${GITHUB_REPO}/main/install.sh | sh${RESET}" + say " Or re-run with ${BOLD}--replace-npm${RESET} to uninstall the npm package and install this binary." + else + say " To switch to the standalone installer, uninstall the ${MANAGED_INSTALL} package first, then re-run:" + say " ${GREEN}curl -fsSL https://raw.githubusercontent.com/${GITHUB_REPO}/main/install.sh | sh${RESET}" + fi say " Or re-run with ${BOLD}--force${RESET} to install alongside (may shadow the ${MANAGED_INSTALL} install on PATH)." exit "$EXIT_INSTALL" } From 4ebdd2940ad97a20ca049a800bfafcf9eb66e78a Mon Sep 17 00:00:00 2001 From: digitallysavvy Date: Mon, 1 Jun 2026 15:59:28 -0400 Subject: [PATCH 2/4] docs(release): prepare v0.2.5 notes Document the v0.2.5 installer migration changes and record the v0.2.3/v0.2.4 release history. Update release examples to use the next patch tag. --- CHANGELOG.md | 25 ++++++++++++++++++++++++- README.md | 2 +- RELEASING.md | 4 ++-- 3 files changed, 27 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 40b436a..34c6dc5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,26 @@ Earlier entries pre-date this convention and only carry their version's compare ## [Unreleased] +## [0.2.5] - 2026-06-01 + +Installer migration improvements. + +### Added + +- Add `install.sh --replace-npm` to migrate from a global npm-managed `agoraio-cli` install to the standalone installer by running `npm uninstall -g agoraio-cli` before installing the binary. + +### Changed + +- Improve managed-install errors with explicit uninstall-and-reinstall guidance so users can switch to the standalone installer without relying on side-by-side PATH shadowing. + +## [0.2.4] - 2026-06-01 + +npm release workflow trigger tag for the v0.2.3 Cosign bundle signing fix. + +## [0.2.3] - 2026-06-01 + +Release signing fix. + ### Fixed - Update GoReleaser Cosign signing to emit `checksums.txt.sigstore.json` with `--bundle`, matching Cosign's current bundle-based signing flow. @@ -272,7 +292,10 @@ Set `AGORA_ALLOW_UPGRADE_IN_CI=1` only when a CI job intentionally needs to muta - Support machine-readable JSON output for automation and agent workflows. - Ship automated release packaging through GoReleaser, including cross-platform archives, Linux packages, Homebrew, Scoop, npm wrapper packages, Docker images, and install scripts. -[Unreleased]: https://github.com/AgoraIO/cli/compare/v0.2.2...HEAD +[Unreleased]: https://github.com/AgoraIO/cli/compare/v0.2.5...HEAD +[0.2.5]: https://github.com/AgoraIO/cli/compare/v0.2.4...v0.2.5 +[0.2.4]: https://github.com/AgoraIO/cli/compare/v0.2.3...v0.2.4 +[0.2.3]: https://github.com/AgoraIO/cli/compare/v0.2.2...v0.2.3 [0.2.2]: https://github.com/AgoraIO/cli/compare/v0.2.1...v0.2.2 [0.2.1]: https://github.com/AgoraIO/cli/compare/v0.2.0...v0.2.1 [0.2.0]: https://github.com/AgoraIO/cli/compare/v0.1.9...v0.2.0 diff --git a/README.md b/README.md index 1f6f407..dc5009f 100644 --- a/README.md +++ b/README.md @@ -310,7 +310,7 @@ GitHub Actions are configured for: Release workflow behavior: -- a pushed tag matching `v*` (for example `v0.2.2`) triggers the release workflow +- a pushed tag matching `v*` (for example `v0.2.5`) triggers the release workflow - the workflow runs tests, builds release binaries, packages them, and publishes a GitHub release automatically - release artifacts include checksums diff --git a/RELEASING.md b/RELEASING.md index 028f8e7..305dbf6 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -5,8 +5,8 @@ Releases are fully automated via GoReleaser. Pushing a `v*` tag is the only manu ## Release ```bash -git tag v0.2.2 -git push origin v0.2.2 +git tag v0.2.5 +git push origin v0.2.5 ``` The release workflow (`.github/workflows/release.yml`) then: From d6e75b12016f4d76f6924114693cef9eda51f716 Mon Sep 17 00:00:00 2001 From: digitallysavvy Date: Mon, 1 Jun 2026 16:27:13 -0400 Subject: [PATCH 3/4] updated CHANGELOG to resolve conflicts --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 34c6dc5..edbfa6f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,10 @@ Earlier entries pre-date this convention and only carry their version's compare ## [Unreleased] +### Changed + +- Split npm release authentication: `agoraio-cli` continues to use npm trusted publishing with provenance, while the six native platform packages publish with `NPM_TOKEN`. + ## [0.2.5] - 2026-06-01 Installer migration improvements. From 32a14ae430c5fd74c1f9cdddf171e49def666703 Mon Sep 17 00:00:00 2001 From: digitallysavvy Date: Mon, 1 Jun 2026 16:36:56 -0400 Subject: [PATCH 4/4] updated CHANGELOG --- CHANGELOG.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index edbfa6f..9294e3b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,10 +15,6 @@ Earlier entries pre-date this convention and only carry their version's compare ## [Unreleased] -### Changed - -- Split npm release authentication: `agoraio-cli` continues to use npm trusted publishing with provenance, while the six native platform packages publish with `NPM_TOKEN`. - ## [0.2.5] - 2026-06-01 Installer migration improvements. @@ -35,6 +31,10 @@ Installer migration improvements. npm release workflow trigger tag for the v0.2.3 Cosign bundle signing fix. +### Changed + +- Split npm release authentication: `agoraio-cli` continues to use npm trusted publishing with provenance, while the six native platform packages publish with `NPM_TOKEN`. + ## [0.2.3] - 2026-06-01 Release signing fix.