Auto Version Checking & Update Prompt for New Releases

[utkarsh232005]

Summary

KDM should automatically check whether a newer version of the CLI is available and notify users when they are running an outdated version.

This feature will help users stay updated with the latest improvements, bug fixes, security patches, and newly introduced features without manually checking npm releases.

---

Problem

Currently, users have no visibility into whether:

• A newer version of KDM is available
• Their installed version is outdated
• Important fixes or breaking changes exist in newer releases

As a result:

• Users may continue using deprecated or buggy versions
• Support/debugging becomes harder due to version mismatches
• New features remain undiscovered
• Critical fixes may not reach users quickly

---

Proposed Solution

Implement automatic version checking whenever the CLI starts or when a command is executed.

The CLI should:

1. Detect the currently installed version
2. Compare it with the latest published npm version
3. Notify the user if an update is available
4. Provide a direct update command

---

Example Behavior

User Running Older Version

kdm monitor

Output:

A newer version of KDM is available!

Current Version : v2.1.2
Latest Version  : v2.2.0

Update using:
npm install -g kdm-cli@latest

---

Suggested Features

Silent Background Version Check

• Perform lightweight version checks asynchronously
• Avoid slowing down command execution
• Cache results temporarily to reduce unnecessary API calls

---

Smart Notification System

• Show update prompts only once per session/day
• Avoid spamming users on every command
• Highlight major or breaking updates separately

---

Semantic Version Awareness

Different messages for:

• Patch updates (2.1.2 → 2.1.3)
• Minor updates (2.1.2 → 2.2.0)
• Major updates (2.x → 3.x)

---

Optional Flags

Examples:

kdm --version
kdm update check
kdm update

---

Additional Enhancements

• Add release notes link in update prompt
• Add auto-update support in future
• Allow users to disable update notifications
• Add update status inside kdm doctor
• Show changelog summary for major releases

---

Benefits

• Keeps users on supported versions
• Improves overall CLI reliability
• Reduces issue reports caused by outdated builds
• Faster adoption of new features
• Better developer and user experience
• More professional CLI ecosystem

---

Suggested Implementation

Possible approaches:

• Use npm registry version checks
• Compare package.json version with latest npm release
• Use lightweight update notifier libraries
• Cache checks locally for performance optimization

---

Expected Outcome

Users should automatically receive a clean and non-intrusive notification whenever a newer KDM version is available, along with a direct command to upgrade easily.

[utkarsh232005]

@CodeRabbit plan

[coderabbitai]

Coding Plan

Summary

• Introduce a version utility that reads from package.json at runtime to eliminate hardcoded version drift
• Create a self-contained update checker service using native fetch against the npm registry with 24-hour caching via the existing conf-based config system
• Add a kdm update check command for manual checks and integrate non-blocking automatic checks into the startup flow
• Provide semantic version awareness in notifications and allow users to disable notifications via config

Design Choices

Design Choice 1: Runtime access to package.json version

Options Considered:

1. Use createRequire from Node's module package to require the JSON file at runtime
2. Use ESM JSON import assertions (import pkg from '../package.json' assert { type: 'json' })
3. Have tsup inject the version at build time via define/replace

Chosen Option: 1

Rationale: createRequire is the most straightforward approach that works reliably with the existing ESM + tsup setup without build configuration changes.

Design Choice 2: npm registry API approach

Options Considered:

1. Use a library like update-notifier or latest-version
2. Direct fetch to npm registry API endpoint

Chosen Option: 2

Rationale: Direct fetch to https://registry.npmjs.org/kdm-cli/latest follows the existing pattern of using native fetch() (as seen in alerts.ts) and avoids adding new dependencies.

Design Choice 3: Cache duration for version checks

Options Considered:

1. Session-based only (in-memory, resets on each CLI invocation)
2. 24-hour persistent cache
3. Configurable cache duration

Chosen Option: 2

Rationale: 24-hour persistent cache stored via the existing conf package provides a good balance—users see the notification at most once daily without configuration complexity.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Version Infrastructure

Establish the foundation for version checking by fixing the hardcoded version issue, extending the configuration schema for caching and preferences, and creating the core version-checking utility.

Task 1: Create Version Utility Module

Create a utility that reads the current version from package.json at runtime using the createRequire pattern.

• Create src/utils/version.ts with a getCurrentVersion() function that uses createRequire(import.meta.url) to load ../../package.json and return the version string
• Export the function for use throughout the codebase

Task 2: Extend Configuration Schema for Version Check Caching

Add fields to the persistent configuration to support caching version check results and user preferences.

• Update KDMConfig interface in src/utils/config.ts to add: update_check_last_run?: number (Unix timestamp in milliseconds), update_check_latest_version?: string, and update_notifications_disabled?: boolean
• Add helper functions getUpdateCheckCache() and setUpdateCheckCache(version: string) that handle reading/writing the cache fields with timestamp

Task 3: Create Version Check Service

Build the core service that fetches the latest version from npm, compares versions, and manages the cache.

• Create src/utils/updateChecker.ts with the following responsibilities:
  • fetchLatestVersion(): Fetch from https://registry.npmjs.org/kdm-cli/latest, extract the version field, handle network errors gracefully (return null on failure)
  • compareVersions(current, latest): Parse semver strings and return an object indicating if update is available and the update type (major/minor/patch)
  • checkForUpdates(options?): Main orchestrator that checks cache validity (24-hour window), fetches if needed, updates cache, and returns update info or null
  • formatUpdateNotification(current, latest, updateType): Generate the styled notification message using chalk, including the npm install -g kdm-cli@latest command and differentiated messaging for major/minor/patch updates
• Use native fetch() following the pattern in src/monitor/alerts.ts
• Implement simple semver comparison by splitting on dots and comparing numeric segments

🤖 Prompt for AI agents

Implement the foundational version infrastructure for the KDM CLI update
checking system. The goal is to create the runtime version reading utility,
extend the config schema for caching, and build the core update checker service.

**Task 1: Create `src/utils/version.ts`**
- Define and export a `getCurrentVersion()` function
- Use `createRequire(import.meta.url)` from Node's `module` package to load
`../../package.json` at runtime
- Return the `version` string field from the loaded package.json

**Task 2: Update `src/utils/config.ts`**
- Extend the `KDMConfig` interface with three new optional fields:
  - `update_check_last_run?: number` — Unix timestamp in milliseconds
  - `update_check_latest_version?: string`
  - `update_notifications_disabled?: boolean`
- Add a `getUpdateCheckCache()` helper that reads the above fields from the
config store
- Add a `setUpdateCheckCache(version: string)` helper that writes the latest
version and sets `update_check_last_run` to `Date.now()`

**Task 3: Create `src/utils/updateChecker.ts`**
- Implement `fetchLatestVersion()`: use native `fetch()` (following the pattern
in `src/monitor/alerts.ts`) to GET `https://registry.npmjs.org/kdm-cli/latest`,
extract the `version` field from the JSON response, and return `null` on any
network or parse error
- Implement `compareVersions(current: string, latest: string)`: split both
strings on `.`, compare numeric segments to determine if an update is available
and classify the update type as `major`, `minor`, or `patch`; return an object
with this info
- Implement `checkForUpdates(options?)`: orchestrate the check by reading the
cache via `getUpdateCheckCache()`, skipping the fetch if the cache is less than
24 hours old (unless bypassed), calling `fetchLatestVersion()` and
`setUpdateCheckCache()` if a fresh fetch is needed, and returning update info or
`null`
- Implement `formatUpdateNotification(current: string, latest: string,
updateType: string)`: use `chalk` to generate a styled notification string,
include the install command `npm install -g kdm-cli@latest`, and tailor
messaging for major/minor/patch update types

Phase 2: Commands and Integration

Create the manual update check command and integrate non-blocking version checks into the CLI startup flow.

Task 1: Create Update Command with Check Subcommand

Add a new kdm update command with a check subcommand for manual version checking.

• Create src/commands/update.ts following the sub-command pattern from src/commands/config.ts
• Implement registerUpdateCommand(program) that creates a parent update command
• Add check subcommand that:
  • Uses createSpinner to show "Checking for updates..."
  • Calls the version check service (bypassing cache for manual checks)
  • Displays the formatted update notification or "You're running the latest version" message
  • Uses logger for consistent output styling
• Add --disable-notifications / --enable-notifications flags on the parent update command to toggle the update_notifications_disabled config setting

Task 2: Register Update Command in Root

Wire up the new update command into the CLI's command registry.

• Update src/commands/root.ts to import and call registerUpdateCommand(program) alongside the existing command registrations

Task 3: Fix Hardcoded Version References

Replace hardcoded version strings with dynamic version reading from the new utility.

• Update src/commands/root.ts to import getCurrentVersion from the version utility
• Replace the hardcoded '1.1.0' in program.version() call with getCurrentVersion()
• Replace the hardcoded '1.1.0' in showWelcomeBanner() call with getCurrentVersion()

Task 4: Integrate Non-Blocking Version Check into Startup

Add automatic version checking to the CLI startup flow that runs asynchronously without blocking command execution.

• In src/commands/root.ts, within the no-args branch of run() (after the welcome banner and connection checks complete):
  • Call the version check service asynchronously
  • If an update is available and notifications are not disabled, print the formatted notification after the help output but before process.exit()
• For the args-present branch (subcommand execution):
  • Fire off the version check as a non-blocking background operation using a pattern like checkForUpdates().then(result => { if (result) console.log(...) }).catch(() => {}) without awaiting
  • This ensures commands execute immediately while the notification may appear after command output
• Respect the update_notifications_disabled config setting

🤖 Prompt for AI agents

Implement the `kdm update` command and integrate automatic non-blocking version
checks into the CLI startup flow in `src/commands/root.ts`.

**Task 1: Create `src/commands/update.ts`**
- Follow the sub-command pattern from `src/commands/config.ts`
- Export `registerUpdateCommand(program)` that registers a parent `update`
command
- On the parent command, add `--disable-notifications` and
`--enable-notifications` flags that write to the `update_notifications_disabled`
field in config
- Add a `check` subcommand:
- Display a spinner via `createSpinner` with the message "Checking for
updates..."
  - Call the version check service with cache bypassed (for manual checks)
- Stop the spinner and display the formatted update notification if an update is
available, or a "You're running the latest version" message otherwise
  - Use `logger` for consistent output styling

**Task 2: Update `src/commands/root.ts` — Register Command**
- Import `registerUpdateCommand` from `./update`
- Call `registerUpdateCommand(program)` alongside the existing command
registrations

**Task 3: Update `src/commands/root.ts` — Fix Hardcoded Version**
- Import `getCurrentVersion` from the version utility (`src/utils/version.ts`)
- Replace both hardcoded `'1.1.0'` strings — one in `program.version()` and one
in `showWelcomeBanner()` — with `getCurrentVersion()`

**Task 4: Update `src/commands/root.ts` — Non-Blocking Startup Check**
- In the no-args branch of `run()`, after the welcome banner and connection
checks complete, call the version check service and await it; if an update is
available and `update_notifications_disabled` is not set, print the formatted
notification before `process.exit()`
- In the args-present branch, fire off the check without awaiting:
`checkForUpdates().then(result => { if (result) console.log(...) }).catch(() =>
{})`
- Always read and respect the `update_notifications_disabled` config setting
before printing any notification

Phase 3: Testing

Add test coverage for the new version checking functionality.

Task 1: Add Unit Tests for Version Utilities

Create tests for the version checking logic following existing test patterns.

• Create src/__tests__/updateChecker.test.ts using Vitest
• Mock fetch to simulate npm registry responses (success, network error, malformed response)
• Mock the config utilities to test cache behavior
• Test compareVersions with various semver combinations (major/minor/patch updates, same version, ahead of registry)
• Test checkForUpdates cache logic (fresh cache returns cached value, stale cache triggers fetch)
• Test formatUpdateNotification produces expected output for different update types

Task 2: Add Tests for Update Command

Create tests for the update command following existing command test patterns.

• Create src/__tests__/update.test.ts using Vitest
• Mock ../utils/updateChecker and ../ui/spinner
• Test check subcommand displays update available message when update exists
• Test check subcommand displays up-to-date message when on latest version
• Test notification toggle flags update the config correctly

🤖 Prompt for AI agents

Add Vitest test coverage for the version checking utilities and the update
command.

**Task 1: Create `src/__tests__/updateChecker.test.ts`**
- Use Vitest for all tests
- Mock the global `fetch` to simulate: successful npm registry response, network
error, and malformed response
- Mock config utilities (`getUpdateCheckCache`, `setUpdateCheckCache`) to
isolate cache behavior
- Write tests for `compareVersions` covering: major update, minor update, patch
update, same version, and local version ahead of registry
- Write tests for `checkForUpdates`: fresh cache (< 24 hours old) should return
cached value without fetching; stale cache (>= 24 hours old) should trigger a
new fetch and update the cache
- Write tests for `formatUpdateNotification` verifying the output string
contains expected content for major, minor, and patch update types, including
the `npm install -g kdm-cli@latest` command

**Task 2: Create `src/__tests__/update.test.ts`**
- Use Vitest for all tests
- Mock `../utils/updateChecker` and `../ui/spinner`
- Test that the `check` subcommand displays the formatted update notification
when an update is available
- Test that the `check` subcommand displays an up-to-date message when already
on the latest version
- Test that `--disable-notifications` and `--enable-notifications` flags
correctly update the `update_notifications_disabled` config setting

Research

KDM is a Kubernetes and Docker monitoring CLI built with Commander.js for command parsing, using ESM modules bundled via tsup. Commands follow a registerXxxCommand(program) pattern in src/commands/. Utilities are plain exported functions/objects in src/utils/. The project uses native fetch() for HTTP calls, chalk for styling, @vr_patel/tui for spinners, and the conf package for persistent configuration storage via KDMConfig interface. Currently, the version is hardcoded as '1.1.0' in src/commands/root.ts (twice), diverging from package.json which declares 1.2.1.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the foundational version infrastructure for the KDM CLI update
checking system. The goal is to create the runtime version reading utility,
extend the config schema for caching, and build the core update checker service.

**Task 1: Create `src/utils/version.ts`**
- Define and export a `getCurrentVersion()` function
- Use `createRequire(import.meta.url)` from Node's `module` package to load
`../../package.json` at runtime
- Return the `version` string field from the loaded package.json

**Task 2: Update `src/utils/config.ts`**
- Extend the `KDMConfig` interface with three new optional fields:
  - `update_check_last_run?: number` — Unix timestamp in milliseconds
  - `update_check_latest_version?: string`
  - `update_notifications_disabled?: boolean`
- Add a `getUpdateCheckCache()` helper that reads the above fields from the
config store
- Add a `setUpdateCheckCache(version: string)` helper that writes the latest
version and sets `update_check_last_run` to `Date.now()`

**Task 3: Create `src/utils/updateChecker.ts`**
- Implement `fetchLatestVersion()`: use native `fetch()` (following the pattern
in `src/monitor/alerts.ts`) to GET `https://registry.npmjs.org/kdm-cli/latest`,
extract the `version` field from the JSON response, and return `null` on any
network or parse error
- Implement `compareVersions(current: string, latest: string)`: split both
strings on `.`, compare numeric segments to determine if an update is available
and classify the update type as `major`, `minor`, or `patch`; return an object
with this info
- Implement `checkForUpdates(options?)`: orchestrate the check by reading the
cache via `getUpdateCheckCache()`, skipping the fetch if the cache is less than
24 hours old (unless bypassed), calling `fetchLatestVersion()` and
`setUpdateCheckCache()` if a fresh fetch is needed, and returning update info or
`null`
- Implement `formatUpdateNotification(current: string, latest: string,
updateType: string)`: use `chalk` to generate a styled notification string,
include the install command `npm install -g kdm-cli@latest`, and tailor
messaging for major/minor/patch update types
===============================================================================

Task: 2

Implement the `kdm update` command and integrate automatic non-blocking version
checks into the CLI startup flow in `src/commands/root.ts`.

**Task 1: Create `src/commands/update.ts`**
- Follow the sub-command pattern from `src/commands/config.ts`
- Export `registerUpdateCommand(program)` that registers a parent `update`
command
- On the parent command, add `--disable-notifications` and
`--enable-notifications` flags that write to the `update_notifications_disabled`
field in config
- Add a `check` subcommand:
- Display a spinner via `createSpinner` with the message "Checking for
updates..."
  - Call the version check service with cache bypassed (for manual checks)
- Stop the spinner and display the formatted update notification if an update is
available, or a "You're running the latest version" message otherwise
  - Use `logger` for consistent output styling

**Task 2: Update `src/commands/root.ts` — Register Command**
- Import `registerUpdateCommand` from `./update`
- Call `registerUpdateCommand(program)` alongside the existing command
registrations

**Task 3: Update `src/commands/root.ts` — Fix Hardcoded Version**
- Import `getCurrentVersion` from the version utility (`src/utils/version.ts`)
- Replace both hardcoded `'1.1.0'` strings — one in `program.version()` and one
in `showWelcomeBanner()` — with `getCurrentVersion()`

**Task 4: Update `src/commands/root.ts` — Non-Blocking Startup Check**
- In the no-args branch of `run()`, after the welcome banner and connection
checks complete, call the version check service and await it; if an update is
available and `update_notifications_disabled` is not set, print the formatted
notification before `process.exit()`
- In the args-present branch, fire off the check without awaiting:
`checkForUpdates().then(result => { if (result) console.log(...) }).catch(() =>
{})`
- Always read and respect the `update_notifications_disabled` config setting
before printing any notification
===============================================================================

Task: 3

Add Vitest test coverage for the version checking utilities and the update
command.

**Task 1: Create `src/__tests__/updateChecker.test.ts`**
- Use Vitest for all tests
- Mock the global `fetch` to simulate: successful npm registry response, network
error, and malformed response
- Mock config utilities (`getUpdateCheckCache`, `setUpdateCheckCache`) to
isolate cache behavior
- Write tests for `compareVersions` covering: major update, minor update, patch
update, same version, and local version ahead of registry
- Write tests for `checkForUpdates`: fresh cache (< 24 hours old) should return
cached value without fetching; stale cache (>= 24 hours old) should trigger a
new fetch and update the cache
- Write tests for `formatUpdateNotification` verifying the output string
contains expected content for major, minor, and patch update types, including
the `npm install -g kdm-cli@latest` command

**Task 2: Create `src/__tests__/update.test.ts`**
- Use Vitest for all tests
- Mock `../utils/updateChecker` and `../ui/spinner`
- Test that the `check` subcommand displays the formatted update notification
when an update is available
- Test that the `check` subcommand displays an up-to-date message when already
on the latest version
- Test that `--disable-notifications` and `--enable-notifications` flags
correctly update the `update_notifications_disabled` config setting

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[Rishiraj-Pathak-27]

Sure! I will let you know and update you as the issue has been resolved by my side.

Thank you,
Regards
Rishiraj Pathak