feat: add upgrade notification when newer CLI version is available #157

gonengar · 2026-01-30T14:22:45Z

Description

This PR adds automatic upgrade notification functionality to the CLI. When users run commands, the CLI checks if a newer version is available on npm and displays a notification at the beginning of command execution. The check includes a 5-second timeout to ensure minimal performance impact, and all errors are silently caught to prevent any interruption to user workflows.

Related Issue

None

Type of Change

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
Documentation update
Refactoring (no functional changes)
Other (please describe):

Changes Made

Added version-check.ts utility that fetches the latest version from npm registry with 5-second timeout using execa
Created upgradeNotification.ts that formats and displays upgrade notifications using theme colors (shinyOrange)
Integrated upgrade check into runCommand.ts to display notification at the beginning of command execution (after banner, before main logic)
Added comprehensive unit tests in tests/cli/version-check.spec.ts covering success, same version, failure, and whitespace handling scenarios
All errors are silently caught to ensure upgrade checks never interrupt user workflows

Testing

I have tested these changes locally
I have added/updated tests as needed
All tests pass (npm test)

Checklist

My code follows the project's style guidelines
I have performed a self-review of my own code
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation (if applicable)
My changes generate no new warnings
I have updated AGENTS.md if I made architectural changes

Additional Notes

The notification appears at the beginning of command execution (after the banner) in a golden/orange color matching the CLI theme. The implementation is non-blocking and gracefully handles all error cases. Multiple refactor commits were made to optimize the notification placement and move the version-check utility to the appropriate location (src/cli instead of src/core).

_{🤖 Generated by Claude | 2026-02-01 15:30 UTC}

github-actions · 2026-01-30T14:23:16Z

🚀 Package Preview Available!

Install this PR's preview build with npm:

npm i @base44-preview/[email protected]

Prefer not to change any import paths? Install using npm alias so your code still imports base44:

npm i "base44@npm:@base44-preview/[email protected]"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/[email protected]"
  }
}

📦 Preview Package: @base44-preview/[email protected]
🔗 View this commit on GitHub

_{Preview published to npm registry — try new features instantly!}

claude · 2026-01-30T14:27:03Z

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

- Add version check utility that fetches latest version from npm registry - Implement 24-hour cache to avoid frequent npm requests - Display golden-colored notification after command completion - Notification shows current → latest version and install command https://claude.ai/code/session_0154kVA7ZVJqChXFvgWRUfLH

Tests cover: - Returns upgrade info when newer version available - Returns null when version is the same - Returns null when npm command fails - Trims whitespace from version output https://claude.ai/code/session_0154kVA7ZVJqChXFvgWRUfLH

kfirstri · 2026-02-01T14:55:05Z

src/cli/utils/runCommand.ts

    const { outroMessage } = await commandFn();
    outro(outroMessage || "");
+
+    // Check for available upgrades (non-blocking)


@claude remove the comment

Claude finished @kfirstri's task in 36s —— View job

Completed

Read the file to identify the comment at line 97

Remove the comment from the code

Commit and push the change

Removed the comment // Check for available upgrades (non-blocking) from line 97 in src/cli/utils/runCommand.ts as requested.

Co-authored-by: Kfir Stri <[email protected]>

kfirstri · 2026-02-01T14:56:26Z

src/cli/utils/version-check.ts

@claude this whole file should be inside the src/cli folder because it's not related to the core/ of the product

Claude finished @kfirstri's task in 1m 34s —— View job

Completed

Read current file structure and imports

Move src/core/utils/version-check.ts to src/cli/utils/version-check.ts

Update import path in upgradeNotification.ts

Move test file to tests/cli/version-check.spec.ts

Commit and push changes

Moved version-check.ts from src/core/utils to src/cli/utils and updated all related imports. The test file has also been moved from tests/core to tests/cli to match the new structure.

--- | Branch

kfirstri · 2026-02-01T14:57:04Z

@claude go over the tests, remove tests/core and create correct tests inside the tests/cli folder.

claude · 2026-02-01T14:57:18Z

Claude finished @kfirstri's task in 1m 57s —— View job

Reorganizing tests to tests/cli folder

Check current repository state
Read existing test file at tests/core/version-check.spec.ts
Create tests/cli/version-check.spec.ts with correct import path (@/cli/utils)
Remove tests/core/version-check.spec.ts
Commit changes locally

Completed Work

I've successfully reorganized the test file:

Moved tests/core/version-check.spec.ts → tests/cli/version-check.spec.ts
Updated import path from @/core/utils/version-check.js to @/cli/utils/version-check.js
Git detected it as a rename (95% similarity)
Changes are committed locally (commit: beb01dd)

Unable to Push

I cannot push the changes because the remote branch has diverged and I need to sync first. I require approval to run git pull or git fetch commands. These git commands are currently blocked by the tool permissions.

What was done: The test file has been correctly moved to tests/cli/ as requested. The tests/core/ directory still exists because it contains other legitimate core test files (agents.spec.ts, errors.spec.ts, project.spec.ts).

Moved version-check.ts and its test file from core/utils to cli/utils as this functionality is CLI-specific and not related to core product. Co-authored-by: Kfir Stri <[email protected]>

kfirstri · 2026-02-01T15:01:12Z

src/cli/utils/upgradeNotification.ts

+  try {
+    const upgradeInfo = await checkForUpgrade();
+    if (upgradeInfo) {
+      log.message(formatUpgradeMessage(upgradeInfo));


@claude i see were using log.message, and the printUpgradeNotificationIfAvailable is called in runCommand but after we already do outro meaning it will be a weird hevaior, maybe we can do it at the begining?

Claude finished @kfirstri's task in 47s —— View job

Completed

Read runCommand.ts to understand current placement

Read upgradeNotification.ts to understand implementation

Move notification call to beginning of command

Commit and push changes

Moved the upgrade notification to display right after the intro/banner, before the main command logic runs. This prevents the notification from appearing after the outro, which would have created strange behavior where messages appear after the command completion message.

The notification now appears at the beginning of the command flow, making it more visible and avoiding any confusion with the outro message.

| Branch

kfirstri · 2026-02-01T15:01:53Z

src/cli/utils/version-check.ts

+ */
+export async function checkForUpgrade(): Promise<UpgradeInfo | null> {
+  try {
+    const { stdout } = await execa("npm", ["view", "base44", "version"], { timeout: 5000 });


look for other places we use execa and make sure we pass all appropriate flags @claude

Claude finished @kfirstri's task in 1m 12s —— View job

Reviewing execa usage patterns

Read current version-check.ts to understand current execa usage

Search for all execa usage in the codebase

Compare flags and options used across the codebase

Update version-check.ts to add shell: true flag

Commit changes locally

Sync with remote and push changes

Findings

I found that version-check.ts is missing the shell: true flag that is consistently used throughout the codebase:

Previous usage in version-check.ts:14

const { stdout } = await execa("npm", ["view", "base44", "version"], { timeout: 5000 });

Updated to match codebase pattern:

const { stdout } = await execa("npm", ["view", "base44", "version"], { timeout: 5000, shell: true });

Why this matters: According to AGENTS.md:729-736, the shell: true flag suppresses subprocess output, which is important for UI consistency. All other execa calls in the codebase (create.ts:206, create.ts:209, create.ts:232) use this flag.

Status

The change has been committed locally (commit: fe03574). I need approval to run git pull --rebase to sync with the remote branch before pushing, as the remote has diverged.

| Branch

Moved printUpgradeNotificationIfAvailable call to execute right after intro/banner display, before the main command logic runs. This prevents the notification from appearing after outro, which would create a weird behavior where messages appear after the command completion message. Co-authored-by: Kfir Stri <[email protected]>

kfirstri · 2026-02-01T15:02:55Z

tests/cli/version-check.spec.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { execa } from "execa";
+import { checkForUpgrade } from "@/cli/utils/version-check.js";


@claude this should work like other tests in cli/, use the testkit and run the program.. look for other examples and fix

Claude finished @kfirstri's task in 2m 8s —— View job

Completed

Read current test file

Find and analyze other CLI test examples

Understand testkit pattern

Rewrite test to use testkit

Commit and push changes

Changes Made

Rewrote tests/cli/version-check.spec.ts to follow the testkit pattern used by other CLI tests:

Before: Unit tests that mocked execa to test the checkForUpgrade function in isolation

After: Integration tests that:

Use setupCLITests() to get the test context

Run actual CLI commands (e.g., whoami) using t.run()

Mock the checkForUpgrade function at the module level using vi.mock()

Verify upgrade notifications appear in the command output

This is a hybrid approach: we use testkit for end-to-end command execution (following the pattern of other CLI tests), but we mock the checkForUpgrade function since it depends on npm subprocess calls that can't be intercepted by the testkit.

The tests now verify the upgrade notification feature by:

Running a command that should display the notification

Checking that the output contains "Update available!" and the version info

Verifying error cases don't block command execution

Changes committed and pushed to the branch. CI will run the tests automatically.

| Branch

- Use setupCLITests() to run actual CLI commands end-to-end - Mock checkForUpgrade at module level since it depends on npm subprocess - Test upgrade notification by running whoami command and checking output - This follows the same pattern as other CLI tests Co-authored-by: Kfir Stri <[email protected]>

gonengar mentioned this pull request Jan 30, 2026

[Feature]: Add upgrade notification when newer CLI version is available #158

Open

kfirstri added this to CLI Development Jan 30, 2026

github-project-automation bot moved this to Backlog in CLI Development Jan 30, 2026

kfirstri moved this from Backlog to Ready in CLI Development Jan 30, 2026

claude added 2 commits February 1, 2026 10:02

test: add unit tests for version check utility

49a22bb

Tests cover: - Returns upgrade info when newer version available - Returns null when version is the same - Returns null when npm command fails - Trims whitespace from version output https://claude.ai/code/session_0154kVA7ZVJqChXFvgWRUfLH

gonengar force-pushed the claude/add-upgrade-notification-IF6u3 branch from 0465937 to 49a22bb Compare February 1, 2026 10:06

kfirstri moved this from Ready to In progress in CLI Development Feb 1, 2026

kfirstri reviewed Feb 1, 2026

View reviewed changes

chore: remove comment from runCommand.ts

16eb79f

Co-authored-by: Kfir Stri <[email protected]>

kfirstri reviewed Feb 1, 2026

View reviewed changes

refactor: move version-check from src/core to src/cli

95bc93d

Moved version-check.ts and its test file from core/utils to cli/utils as this functionality is CLI-specific and not related to core product. Co-authored-by: Kfir Stri <[email protected]>

kfirstri reviewed Feb 1, 2026

View reviewed changes

feat: add upgrade notification when newer CLI version is available #157

Are you sure you want to change the base?

feat: add upgrade notification when newer CLI version is available #157

Conversation

gonengar commented Jan 30, 2026 • edited by claude bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related Issue

Type of Change

Changes Made

Testing

Checklist

Additional Notes

Uh oh!

github-actions bot commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 Package Preview Available!

Uh oh!

claude bot commented Jan 30, 2026

Code review

Uh oh!

kfirstri Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

claude bot Feb 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Completed

Uh oh!

kfirstri Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

claude bot Feb 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Completed

Uh oh!

kfirstri commented Feb 1, 2026

Uh oh!

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

Uh oh!

Reorganizing tests to tests/cli folder

Completed Work

Unable to Push

Uh oh!

kfirstri Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

claude bot Feb 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Completed

Uh oh!

kfirstri Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

claude bot Feb 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Reviewing execa usage patterns

Findings

Status

Uh oh!

kfirstri Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

claude bot Feb 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Completed

Changes Made

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

gonengar commented Jan 30, 2026 •

edited by claude bot

Loading

github-actions bot commented Jan 30, 2026 •

edited

Loading

claude bot Feb 1, 2026 •

edited

Loading

claude bot Feb 1, 2026 •

edited

Loading

claude bot commented Feb 1, 2026 •

edited

Loading

claude bot Feb 1, 2026 •

edited

Loading

claude bot Feb 1, 2026 •

edited

Loading

claude bot Feb 1, 2026 •

edited

Loading