@nightnetwork/dpm — Dusk Package Manager

A fast, npm-compatible package manager built for both Node.js and DuskJS runtimes.

Features

• Full npm compatibility — drop-in replacement for npm, npx, and pnpm commands
• Registry support — works with the public npm registry and custom registries
• Lockfile support — generates and reads package-lock.json v3 format
• Content-addressable cache — SHA-512 integrity-based caching for fast offline installs
• Integrity verification — SHA-1, SHA-256, and SHA-512 SRI verification of all tarballs
• Bin shims — automatic node_modules/.bin shim generation with native binary detection
• Semver resolution — built-in semver parser supporting ^, ~, hyphen ranges, x-ranges, || alternatives, and prerelease tags
• Dependency hoisting — npm-compatible hoisting with nested fallback for version conflicts
• Parallel installs — concurrent BFS dependency resolution and parallel tarball fetching
• Lifecycle scripts — runs preinstall, install, postinstall, prepublish, and prepare scripts
• CLI aliases — provides npm, npx, and pnpm compatibility shims
• Dual runtime — works in standard Node.js and as /bin/dpm inside DuskJS

Installation

npm install -g @nightnetwork/dpm

CLI Usage

dpm — Dusk Package Manager

Usage:
  dpm install [packages...]     Install dependencies (alias: dpm i, dpm add)
  dpm uninstall <pkg>           Remove a package (alias: dpm rm, dpm remove)
  dpm run <script> [args...]    Run a package.json script
  dpm exec <command> [args...]  Run a local-bin command
  dpm list                      List installed packages
  dpm init [--yes]              Initialize a new package.json
  dpm cache <clean|verify|ls>   Manage the cache
  dpm config <get|set|delete>   Manage config
  dpm --version                 Print dpm version
  dpm --help                    Show help

Options:
  -D, --save-dev                Save to devDependencies
  -S, --save                    Save to dependencies (default)
  --silent                      Suppress output
  --registry <url>              Custom registry URL

Install dependencies

# Install all dependencies from package.json
dpm install

# Add a package to dependencies
dpm install express

# Add a package to devDependencies
dpm install -D vitest

# Install from a custom registry
dpm install --registry https://registry.example.com

Remove a package

dpm uninstall lodash
# or
dpm rm lodash

Run scripts

dpm run build
dpm run test -- --watch

Execute binaries

# Run a locally installed binary
dpm exec vitest

# Run with dpx (like npx)
dpx create-react-app my-app
dpx -p typescript tsc --init

List installed packages

dpm list

Initialize a project

dpm init
dpm init --yes

Cache management

dpm cache ls
dpm cache verify
dpm cache clean

Configuration

dpm config get registry
dpm config set registry https://registry.example.com
dpm config delete registry

npm / npx / pnpm Compatibility

dpm ships with compatibility aliases that map directly to dpm commands:

Alias	Maps to
npm install	dpm install
npm uninstall	dpm uninstall
npm run	dpm run
npm exec	dpm exec
npm list	dpm list
npm init	dpm init
npm cache	dpm cache
npm config	dpm config
npx <cmd>	dpx <cmd>
pnpm add	dpm install
pnpm remove	dpm uninstall
pnpm dlx	dpx
pnpm run	dpm run
pnpm exec	dpm exec
pnpm list	dpm list
pnpm init	dpm init

Architecture

Core Modules

Module	Description
core/resolver	Concurrent BFS dependency resolver with npm-compatible hoisting and nested fallback. Handles registry semver ranges, URL tarballs, file: deps, and dist-tags. Includes a multi-pass hoisting algorithm that lifts nested packages to the highest conflict-free position.
core/registry	HTTP client for npm-compatible registries. Fetches packument metadata (abbreviated format) and tarball bytes.
core/tarball	Pure-TypeScript gzip decompression and ustar tar parser. Extracts tarballs to disk with configurable component stripping.
core/lockfile	Reads and writes package-lock.json in lockfile v3 format. Builds lockfile entries from the resolved dependency graph.
core/cache	Content-addressable filesystem cache using SHA-512 hex sharding (<cacheDir>/<alg>/<AA>/<BB>/<hex>).
core/integrity	Tarball integrity verification supporting SHA-512, SHA-256, and SHA-1 SRI hashes, plus legacy hex shasums.
core/bin-shims	Creates node_modules/.bin shims with automatic detection of native binaries (ELF/Mach-O/PE), shebanged scripts, and plain JS files.
core/manifest	package.json read/write helpers, dependency merging, and package root discovery.
core/scripts	Lifecycle script runner (preinstall, install, postinstall, prepublish, prepare) with npm-compatible environment variables.
semver	Minimal built-in semver implementation supporting ^, ~, >, >=, <, <=, =, `

Dependency Resolution Strategy

1. Walk the dependency graph in BFS waves with configurable concurrency
2. For each transitive dependency, try to satisfy with an already-hoisted version (walking up the parent chain)
3. If no compatible hoisted version exists, install at the highest level with no conflict
4. If a transitive dependency's range is incompatible with the hoisted version, install nested under the parent
5. Post-resolution hoisting pass lifts nested packages to the highest conflict-free ancestor
6. Single-path lift pass catches remaining deeply-nested packages that can be promoted

Supported Spec Types

• Registry semver ranges: ^1.2.3, ~1.0.0, >=1, *, latest
• URL tarballs: https://example.com/foo-1.0.0.tgz
• File dependencies: file:./packages/shared
• Dist-tags: latest, next, etc.
• npm aliases: npm:package@version

DuskJS Integration

When running inside DuskJS, dpm operates as the built-in package manager at /bin/dpm. The runtime is auto-detected via detectRuntime() and isDuskJS() helpers from util/env.

Key differences in DuskJS mode:

• Cache directory defaults to the DuskJS system cache path
• Registry URL can be overridden via DuskJS configuration
• Bin shims include a /bin/node fallback path for JS scripts without shebangs

Configuration

dpm reads configuration via dpm config:

# Set a custom registry
dpm config set registry https://registry.example.com

# View current registry
dpm config get registry

# Remove a config key
dpm config delete registry

The --registry flag on install commands takes precedence over config values.

Programmatic API

dpm exports its core modules for programmatic use:

import {
  installCommand,
  uninstallCommand,
  createRegistryClient,
  resolveDeps,
  extractTarball,
  parseTar,
  verifyIntegrity,
  computeIntegrity,
  createCache,
  readPackageJson,
  writePackageJson,
  buildLockfile,
  readLockfile,
  writeLockfile,
  detectRuntime,
  isDuskJS,
  semver,
} from '@nightnetwork/dpm';

// Resolve dependencies programmatically
const registry = createRegistryClient('https://registry.npmjs.org');
const plan = await resolveDeps({
  registry,
  rootDeps: { express: '^4.18.0' },
});

console.log(`Resolved ${plan.resolved.size} packages`);

Contributing

Contributions are welcome. Please open an issue or pull request on GitHub.

git clone https://github.com/nightnetwork/dpm.git
cd dpm
npm install
npm run build
npm run test

License

Apache-2.0