update-kit

A channel-aware self-update library and CLI for Node.js CLI applications.

Most CLI tools are installed through different channels — npm, Homebrew, direct download, or custom installers — and each channel has its own update semantics. update-kit detects the install channel automatically and selects the right update strategy, so your app updates itself safely without breaking package manager ownership.

Features

• Install Channel Detection — Identifies how your CLI was installed (npm, Homebrew, native binary, or custom) using receipt files, path heuristics, and package manager queries
• Automatic Source Inference — When sources is omitted, automatically derives version sources from package.json fields (name, repository) and prioritizes them based on the detected install channel
• Pluggable Version Sources — Checks for updates from GitHub Releases, npm registry, JSR, Homebrew API, or a custom JSON manifest
• Non-blocking Checks — Returns cached results instantly and refreshes in the background, so app startup is never delayed
• Smart Update Planning — Chooses the safest strategy per channel: in-place binary replacement, delegated package manager command, or manual instructions
• Safe Application — SHA-256 checksum verification, atomic file replacement, HTTPS-only enforcement, and automatic rollback on failure
• Version Listing — Paginated version list from any source (GitHub, npm, JSR) with cursor-based pagination
• Version Switching — Upgrade or downgrade to any specific version through the same channel-aware pipeline
• Lifecycle Hooks — beforeCheck, beforeApply, afterApply, and onError hooks for telemetry, logging, or custom logic
• CLI Included — Built-in update-kit CLI with detect, check, plan, apply, cache, and doctor subcommands

Getting Started

Requirements

• Node.js 18 or later

Install

npm install update-kit

Or with other package managers:

pnpm add update-kit
yarn add update-kit

Usage

import { UpdateKit } from 'update-kit';

// Zero-config: sources are auto-inferred from your package.json
const kit = await UpdateKit.create();

const banner = await kit.checkAndNotify();
if (banner) console.error(banner);

Source check order adapts to the detected install channel — npm-installed apps check npm first, Homebrew-installed apps check brew first. You can still pass explicit sources when you need full control.

Full auto-update

Run the complete pipeline — detect channel, check version, plan strategy, and apply:

const result = await kit.autoUpdate({
  onProgress: (p) => console.log(p.phase),
});

if (result.kind === 'success') {
  console.log(`Updated from ${result.fromVersion} to ${result.toVersion}`);
}

Step-by-step control

Use individual methods when you need more control over the pipeline:

const detection = await kit.detectInstall();
const status = await kit.checkUpdate('blocking');

if (status.kind === 'available') {
  const plan = kit.planUpdate(status, detection);
  if (plan) {
    const result = await kit.applyUpdate(plan);
  }
}

Version listing and switching

List available versions and switch to any version (upgrade or downgrade):

// List available versions with pagination
const versions = await kit.listVersions({ limit: 10 });
if (versions.kind === 'success') {
  for (const v of versions.versions) {
    console.log(`${v.version} — ${v.publishedAt ?? ''}`);
  }
  // Paginate with cursor
  if (versions.nextCursor) {
    const next = await kit.listVersions({ limit: 10, cursor: versions.nextCursor });
  }
}

// Switch to a specific version (downgrade or upgrade)
const result = await kit.switchVersion('1.2.0', { execute: true });
if (result.kind === 'success') {
  console.log(`Switched to ${result.toVersion}`);
}

CLI

The package includes a CLI for debugging and integration:

npx update-kit detect          # Show install channel and confidence
npx update-kit check           # Check for updates
npx update-kit check --blocking # Fetch directly instead of using cache
npx update-kit plan            # Show the update plan
npx update-kit apply           # Run the full update pipeline
npx update-kit cache show      # Display cached version data
npx update-kit cache clear     # Clear the cache
npx update-kit doctor          # Validate config, sources, and connectivity

# All commands support JSON output
npx update-kit detect --json

See the full API documentation for configuration options, version sources, lifecycle hooks, and standalone function exports.

Contributing

Contributions are welcome. Please read the Contributing Guide before submitting a pull request.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Author

Sung YeIn