feat: improve npm authentication and plugin health checks during CLI updates by eablack · Pull Request #3547 · heroku/cli

eablack · 2026-02-27T23:33:03Z

Summary

This PR improves the user experience when updating the Heroku CLI by adding better handling for npm authentication and plugin installation issues. Users previously encountered cryptic npm errors when updating while logged out of npm with private plugins installed. This change proactively detects and handles these scenarios with clear messaging and interactive prompts.

Key Changes

1. Pre-update npm authentication check (hooks/preupdate/check-npm-auth.ts)

New preupdate hook that runs before the CLI update begins
Detects private npm plugins by checking package privacy via npm API
Parallelizes npm API calls in batches of 5 for better performance
Prompts users to authenticate with npm if private plugins are detected and user is not authenticated
Provides clear warning messages and recovery instructions if authentication is declined

2. Post-update plugin health check (hooks/update/check-plugin-health.ts)

New update hook that runs after plugin installation
Verifies all configured plugins exist in node_modules
Detects missing plugins that failed to install during update
Provides detailed recovery instructions with specific commands to reinstall or uninstall affected plugins

3. Reusable npm authentication library (lib/npm-auth.ts)

Centralized authentication logic with functions: isNpmAvailable(), isAuthenticated(), isPrivatePackage(), login()
Handles npm's 404 responses for private packages (to avoid leaking package existence)
Designed for testability with extracted exec/spawn methods

4. Cleanup

Removed deprecated v6 plugin migration code (hooks/update/plugin-migrate.ts)
Fixed missing await in hooks/init/terms-of-service.ts
Fixed resource leak in lib/repl.ts (missing historyStream.close())

Type of Change

Feature Additions (minor semver update)

feat: Introduces a new feature to the codebase

Testing

Notes:
The hooks integrate into the existing oclif update lifecycle. The check-npm-auth hook runs before the update starts (preupdate), while check-plugin-health runs after plugin installation (update). Both hooks are non-blocking - errors won't prevent updates from completing. Since this is part of the lifecycle, we'll test this once this gets into the beta release.

Steps:

Install a private npm plugin: heroku plugins:install @private/some-plugin
Log out of npm: npm logout
Attempt to update CLI: heroku update
Verify the check-npm-auth hook prompts for authentication
Choose to authenticate and verify update proceeds successfully
Alternatively, choose not to authenticate and verify clear warning message is displayed

To test plugin health check:

Manually corrupt a plugin installation (delete from node_modules but leave in package.json)
Run heroku update
Verify warning message with specific recovery instructions for affected plugins

Related Issues

https://gus.lightning.force.com/lightning/r/ADM_Work__c/a07EE00002VgjNJYAZ/view

k80bowman

I'm excited about using hooks for this, I think that's a great idea. And I love the idea of adding the plugin health check as well, that's awesome. I do have a few implementation comments, but this is great. I appreciate you figuring this out.

src/hooks/update/check-npm-auth.ts

src/hooks/update/check-plugin-health.ts

test/unit/hooks/check-npm-auth.unit.test.ts

test/unit/hooks/check-plugin-health.unit.test.ts

package.json

…updates This change improves the user experience when updating the Heroku CLI by adding better handling for npm authentication and plugin installation issues. Key changes: - Add preupdate hook (check-npm-auth) that detects private plugins and prompts users to authenticate with npm before attempting the update - Add post-update hook (check-plugin-health) that verifies all plugins installed correctly and provides recovery instructions for missing plugins - Remove deprecated v6 plugin migration code from plugin-migrate hook - Add comprehensive unit tests for both new hooks The check-npm-auth hook: - Reads installed plugins from package.json - Checks which plugins are private (require authentication) - Verifies npm authentication status - Prompts user to login if needed before proceeding with update - Handles user cancellation gracefully with clear messaging The check-plugin-health hook: - Runs after plugin installation during update - Checks if all configured plugins exist in node_modules - Warns users about missing plugins with recovery instructions - Suggests both reinstall and uninstall options This resolves issues where users would get cryptic npm errors during CLI updates when logged out of npm with private plugins installed.

Refactor check-npm-auth hook to check multiple plugins concurrently instead of sequentially. This significantly reduces the time to check plugin privacy when users have many plugins installed. - Process plugins in batches of 5 using Promise.all - Maintains the same behavior and debug logging - Reduces check time from O(n) sequential to O(n/5) batches

- Extract NpmAuth class with testable wrapper methods (exec, spawn) - Add isNpmAvailable() check to skip auth flow when npm is not installed - Treat 404 errors as potentially private packages (npm returns 404 for private packages when not authenticated) - Consolidate duplicate warning messages - Simplify authentication flow to never block updates - always warn and continue - Reduce check-npm-auth hook from 230 lines to 118 lines Tests: - Add 14 unit tests for NpmAuth class methods - Add 9 comprehensive tests for hook orchestration logic - Remove weak "doesn't throw" assertions in favor of specific behavioral checks - All 23 tests passing

- Fix FileHandle deprecation warning by explicitly closing historyStream on REPL exit - Fix terms-of-service hook to properly await async fs.createFile - Simplify check-plugin-health error message by removing redundant text

The hook was registered as 'preupdate' in package.json but was located in the hooks/update directory. Move it to hooks/preupdate to match its actual hook type and improve code organization.

k80bowman

This looks awesome, thank you for all of the fixes!

eablack requested a review from a team as a code owner February 27, 2026 23:33

eablack temporarily deployed to AcceptanceTests February 27, 2026 23:44 — with GitHub Actions Inactive

eablack temporarily deployed to AcceptanceTests February 28, 2026 01:18 — with GitHub Actions Inactive

k80bowman requested changes Mar 2, 2026

View reviewed changes

eablack temporarily deployed to AcceptanceTests March 2, 2026 20:52 — with GitHub Actions Inactive

eablack temporarily deployed to AcceptanceTests March 2, 2026 22:28 — with GitHub Actions Inactive

eablack added 7 commits March 3, 2026 08:59

fix linting

d86b865

fix: resolve deprecation warnings and improve error messaging

444bde8

- Fix FileHandle deprecation warning by explicitly closing historyStream on REPL exit - Fix terms-of-service hook to properly await async fs.createFile - Simplify check-plugin-health error message by removing redundant text

refactor: move check-npm-auth hook to correct preupdate directory

3be927e

The hook was registered as 'preupdate' in package.json but was located in the hooks/update directory. Move it to hooks/preupdate to match its actual hook type and improve code organization.

clean up check-plugin-health and tests

3f367e5

eablack force-pushed the eb/better-messaging-when-failing-from-private-plugins branch from 1e78521 to 3f367e5 Compare March 3, 2026 16:59

eablack temporarily deployed to AcceptanceTests March 3, 2026 16:59 — with GitHub Actions Inactive

update description of test expectation

e5b23b8

eablack temporarily deployed to AcceptanceTests March 3, 2026 17:02 — with GitHub Actions Inactive

correct comment explaining error trap logic.

b24f23d

eablack temporarily deployed to AcceptanceTests March 3, 2026 17:08 — with GitHub Actions Inactive

k80bowman approved these changes Mar 3, 2026

View reviewed changes

eablack merged commit 7e6603d into v11.0.0 Mar 3, 2026
17 checks passed

eablack deleted the eb/better-messaging-when-failing-from-private-plugins branch March 3, 2026 18:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: improve npm authentication and plugin health checks during CLI updates#3547

feat: improve npm authentication and plugin health checks during CLI updates#3547
eablack merged 9 commits intov11.0.0from
eb/better-messaging-when-failing-from-private-plugins

eablack commented Feb 27, 2026 •

edited

Loading

Uh oh!

k80bowman left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

k80bowman left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

eablack commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key Changes

Type of Change

Feature Additions (minor semver update)

Testing

Related Issues

Uh oh!

k80bowman left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

k80bowman left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

eablack commented Feb 27, 2026 •

edited

Loading