WPM - Wiresphere Package Manager

A specialized package manager for managing modular dependencies with support for version ranges and dependency tree resolution.

Features

• Version Range Support: Use Maven-style version ranges like [1.0.0,2.0.0) for flexible dependency management
• Smart Dependency Resolution: Build complete dependency trees before installation to detect conflicts early
• Tree Visualization: Visualize dependency trees with conflict detection
• Local Maven Repository: Optional integration with local Maven repositories
• Container Management: Install and manage container packages
• Interactive Setup: Initialize new projects with an interactive CLI

Installation

npm install -g @wiresphere/wpm

Quick Start

Initialize a New Project

wpm init

This will walk you through setting up a modules.json file with project metadata, dependencies, and configuration.

Install Dependencies

# Install all dependencies from modules.json
wpm install

# Install a specific module
wpm install [email protected]

# Install and save to modules.json
wpm install [email protected] --save

View Dependency Tree

# Show dependency tree for current project
wpm tree

# Show dependency tree for a specific module
wpm tree [email protected]

Version Range Syntax

WPM uses Maven-style version range syntax:

| Syntax | Description | |--------|-------------| | 1.0.0 | Exact version | | [1.0.0,2.0.0) | 1.0.0 (inclusive) to 2.0.0 (exclusive) | | (1.0.0,2.0.0] | 1.0.0 (exclusive) to 2.0.0 (inclusive) | | [1.0.0,2.0.0] | 1.0.0 (inclusive) to 2.0.0 (inclusive) | | (1.0.0,2.0.0) | Both exclusive | | [1.0.0,) | 1.0.0 and above | | (,2.0.0) | Up to 2.0.0 (exclusive) | | [1.0.0,2.0.0],[3.0.0,4.0.0) | Multiple ranges (OR) |

Examples

{
  "dependencies": [
    {
      "package": "[email protected]"
    },
    {
      "package": "number-range@[1.1.1,)"
    },
    {
      "package": "utils@[2.0.0,3.0.0)"
    }
  ]
}

Project Configuration

The modules.json file configures your project:

{
  "name": "my-project",
  "author": "Your Name",
  "version": "1.0.0",
  "modulesFolder": "./modules",
  "modulesSourceFolder": "./wpm_modules",
  "containerFolder": "./",
  "container": "[email protected]",
  "mavenRepository": "./.m2",
  "adminBuildFolder": "./admin",
  "admin": "[email protected]",
  "adminModules": [
    "ws-framework",
    "shop-common"
  ],
  "dependencies": [
    {
      "package": "number-range@[1.1.1,)"
    }
  ]
}

Configuration Options

• name: Project name
• author: Project author
• version: Project version
• modulesFolder: Where compiled modules are placed
• modulesSourceFolder: Where source modules are stored
• container: Container package to use
• containerFolder: Where to install the container
• mavenRepository: Path to local Maven repository (optional)
• admin: Admin package (optional)
• adminBuildFolder: Where to build admin modules (optional)
• adminModules: List of admin modules to include (optional)
• dependencies: Array of package dependencies

Whitelists and Blacklists

WPM allows you to control which sub-modules of a dependency are installed using whitelists and blacklists. This is useful when a package contains multiple modules, but you only need specific ones, or when you want to exclude certain modules.

Common Use Cases:

• A large package with many optional modules (install only what you need)
• Excluding test or example modules from production builds

Whitelist vs Blacklist

You can use either a whitelist or a blacklist on a dependency, but not both. They are mutually exclusive.

• Whitelist: Only install the modules explicitly listed (exclude everything else)
• Blacklist: Install all modules except those explicitly listed

Whitelist Usage

A whitelist specifies which modules should be included. All other modules are excluded.

{
  "dependencies": [
    {
      "package": "[email protected]",
      "whitelist": ["core-module", "utils-module"]
    }
  ]
}

In this example, only core-module and utils-module from ws-framework will be installed. All other modules in the package will be skipped.

Empty Whitelist: An empty whitelist [] will exclude all modules from the package.

{
  "package": "[email protected]",
  "whitelist": []
}

Blacklist Usage

A blacklist specifies which modules should be excluded. All other modules are included.

{
  "dependencies": [
    {
      "package": "[email protected]",
      "blacklist": ["legacy-module", "deprecated-utils"]
    }
  ]
}

In this example, all modules from shop-common will be installed except legacy-module and deprecated-utils.

Complete Example

{
  "name": "my-project",
  "version": "1.0.0",
  "modulesFolder": "./modules",
  "modulesSourceFolder": "./wpm_modules",
  "dependencies": [
    {
      "package": "[email protected]",
      "whitelist": ["core", "api", "common"]
    },
    {
      "package": "[email protected]",
      "blacklist": ["test-utils", "examples"]
    },
    {
      "package": "number-range@[1.1.1,)"
    }
  ]
}

In this configuration:

• ws-framework: Only core, api, and common modules are installed
• shop-common: All modules except test-utils and examples are installed
• number-range: All modules are installed (no filtering)

Validation Rules

WPM enforces these rules automatically:

1. Mutual Exclusivity: A dependency cannot have both whitelist and blacklist defined
2. Validation on Install: WPM validates your configuration before starting installation
3. Error on Conflict: If both are defined, WPM will throw an error:

   Error: Dependency "package@version" cannot have both blacklist and whitelist defined. They are mutually exclusive.

Legacy Support

The old blacklistModules property is still supported but deprecated. Use blacklist instead.

// Deprecated (still works, but shows a warning)
{
  "package": "[email protected]",
  "blacklistModules": ["old-module"]
}

// Recommended
{
  "package": "[email protected]",
  "blacklist": ["old-module"]
}

Commands

wpm install [module]

Install dependencies or a specific module.

Options:

• -s, --save: Save the module to dependencies in modules.json
• -v, --verbose: Display verbose logging

Examples:

wpm install
wpm install [email protected]
wpm install [email protected] --save
wpm install --verbose

If modules-lock.json directly disagrees with modules.json (a locked version outside a declared range, or an exact pin that differs from the locked version), the install fails and lists the disagreements. Resolve by deleting the lockfile (wpm unlock) and reinstalling, or install exactly what the lockfile specifies with wpm install --lock. A locked version that is merely not the latest inside a declared range is a normal lock, not a mismatch.

wpm unlock

Delete modules-lock.json so the next install re-resolves all versions from modules.json.

wpm unlock

wpm tree [module]

Display the dependency tree with conflict detection and install order.

Examples:

wpm tree
wpm tree [email protected]

wpm init

Initialize a new project with interactive prompts.

wpm list

List installed modules.

wpm clean

Clean installed modules and build artifacts.

wpm gen-manifest

Generate a manifest file for a module.

wpm setup

Set up the project environment.

How It Works

Two-Phase Installation Process

1. Build Dependency Tree: Recursively fetch all module manifests and build a complete dependency tree
2. Validate Conflicts: Check for version conflicts across the entire tree
3. Determine Install Order: Topologically sort dependencies to ensure correct installation order
4. Download & Build: Download and build each module in the correct order

This approach ensures:

• Early detection of dependency conflicts
• Optimal installation order
• No redundant downloads
• Clear visibility into the dependency structure

Conflict Detection

WPM automatically detects when the same module is required at incompatible versions:

wpm tree
# Output:
# ✗ Version conflict detected: package-a is required at 1.0.0 and 2.0.0

Development

Build

npm run build

Test

npm test

Run Locally

npm run build
node dist/wpm.js install

License

ISC