HPS Update Plugin

A workspace dependency updater plugin for the HPS (Hyperse) build system. It automates running npm-check-updates across all packages in a monorepo, with sensible defaults, caching, and Yarn/NPM detection.

Features

• Monorepo Aware: Iterates all workspace packages using @manypkg/get-packages
• Smart Package Manager: Auto-detects Yarn vs NPM for upgrades
• Sensible Defaults: Generates .ncurc.json on first run
• Caching: Persistent cache to speed up repeated checks; clear with --force
• Safe & Configurable: Respect custom registry, filters, and timeouts via NCU behavior

Installation

# yarn
yarn add @hyperse/hps-plugin-update
# npm
npm install @hyperse/hps-plugin-update
# pnpm
pnpm add @hyperse/hps-plugin-update

Quick Start

import { createUpdatePlugin } from '@hyperse/hps-plugin-update';

const updatePlugin = createUpdatePlugin();

// Register with your HPS wizard
wizard.use(updatePlugin);

Usage

Basic Update

# Update all workspace package dependencies using defaults
hps update

# Force refresh cache (slower, ensures latest info)
hps update --force

# Run from a specific repository root
hps update --project-cwd "/path/to/your/monorepo"

Command Options

| Option | Alias | Description | Default | | --------------- | ----- | -------------------------------- | ----------------- | | --force | - | Force refresh NCU cache | false | | --project-cwd | - | Monorepo root to scan workspaces | Current directory |

Notes:

• The command respects the HPS global flags (e.g., --no-color) when provided by the CLI environment.

Configuration

Generated .ncurc.json

On first run, the plugin will generate a minimal .ncurc.json at your repo root if it does not exist:

{
  "dep": ["prod", "dev", "optional", "packageManager"],
  "reject": []
}

You can customize this file per the npm-check-updates configuration options (e.g., filter, reject, target).

Cache Location

The update result cache is stored under the user config directory:

~/.config/hps-npm-check-update/ncu-cache.json

• Use --force to delete and recreate the cache on the next run.

How It Works

1. Discovers all workspace packages via @manypkg/get-packages from --project-cwd.
2. Ensures a repo-level .ncurc.json exists with sane defaults.
3. Creates a persistent cache file for npm-check-updates.
4. For each workspace, runs npm-check-updates with upgrade: true using Yarn or NPM detected from the repo.

API Reference

createUpdatePlugin()

Creates and returns the update plugin instance for HPS.

Returns: a configured HPS plugin that adds the update command.

update command

Executes workspace upgrades across all detected packages.

Flags:

• --project-cwd <path>: Root directory of the repo.
• --force: Recreate the cache before running.

Utility Functions

These are internal utilities used by the plugin and can inform advanced customization:

• getWorkspacePackages(cwd) — Lists packages in the monorepo, sorted by name
• projectHasYarn(cwd?) — Detects Yarn by walking up to two parent levels
• ncuUpdate(options) — Thin wrapper around npm-check-updates run() with defaults
• writeNcuConfig(cwd) — Ensures .ncurc.json exists with sensible defaults
• writeCacheFile(force?) — Ensures cache directory exists and clears on force
• getNcuCacheFile(name?) — Returns the absolute path to the cache JSON file
• updateWorkspacePackages(options) — Orchestrates the full update flow

Error Handling

• Workspace Resolution: Fails if packages cannot be discovered from the provided --project-cwd.
• Config/Cache: Automatically creates missing files and directories as needed.
• Network/Registry: Honors npm-check-updates timeouts and registry errors; re-run with --force to refresh cache.

Contributing

1. Fork the repository
2. Create a feature branch
3. Implement your changes
4. Add tests
5. Submit a pull request

License

This project is licensed under the GPLv3 LICENSE.