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 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

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