Packages

Package Manager & Workspaces

nextviper.toml manifest specification, lockfile resolution, and dependency management.

NextViper Package Manager Specification & Guide

The NextViper Package Manager is a robust, deterministic, and security-first dependency management system for NextViper applications and libraries.

Overview & Architecture

NextViper uses a project manifest (nextviper.toml) and an automatic lockfile (nextviper.lock) to manage local packages, git repositories, and registry modules with cryptographic integrity verification (SHA-256 tree hashing).

code

Project Root/
├── nextviper.toml          # Human-editable project manifest
├── nextviper.lock          # Cryptographically pinned lockfile
├── src/
│   └── main.nv             # Main program entrypoint
├── nextviper_modules/      # Active module symlinks/cache for imports
└── .nextviper/
    └── packages/           # Local/remote resolved dependency store

Manifest: `nextviper.toml`

The manifest defines project metadata, direct dependencies, and developer tools.

Example `nextviper.toml`:

nextviper.toml

[project]
name = "my_analytics_app"
version = "0.1.0"
description = "NextViper data analysis and prediction pipeline"
license = "MIT"
main = "src/main.nv"
authors = ["Junaid <junaid@nextviper.org>"]

[dependencies]
# Path dependencies (local libraries)
math_utils = { path = "../math_utils" }

# Git dependencies
neural_core = { git = "https://github.com/nextviper/neural_core.git", tag = "v1.2.0" }

# SemVer registry dependencies
data = "^1.0.0"

[dev-dependencies]
test_kit = "^0.4.0"

[scripts]
start = "nextviper run src/main.nv"
test = "nextviper test"

Lockfile: `nextviper.lock`

The lockfile records exact versions, source locations, dependency trees, and cryptographic SHA-256 tree hashes for 100% reproducible builds.

Example `nextviper.lock`:

nextviper.toml

# This file is automatically generated by NextViper.
# Manual edits may be overwritten.
version = 1

[[package]]
name = "math_utils"
version = "1.0.0"
source = "path:../math_utils"
checksum = "0806fdeb8c8e2eecad0f026754bb15c3cc007d7445268aafc09c018dac9d46ed"
dependencies = [
    "tensor_core"
]

Semantic Versioning (SemVer 2.0.0)

NextViper supports full SemVer 2.0.0 version requirements:

Requirement	Description	Matches
`^1.2.3`	Caret: Compatible updates (same major version > 0)	`>= 1.2.3, < 2.0.0`
`^0.2.3`	Caret 0.x: Compatible minor updates for pre-1.0	`>= 0.2.3, < 0.3.0`
`~1.2.3`	Tilde: Patch updates within minor release	`>= 1.2.3, < 1.3.0`
`>=1.0.0, <2.0.0`	Range comparison: Exact upper & lower bounds	Between `1.0.0` and `2.0.0`
`1.2.3` / `=1.2.3`	Exact version: Pinned to exact release	Exactly `1.2.3`
`*`	Wildcard: Any version	Any valid SemVer

CLI Command Reference

`nextviper init [name]`

Initializes a new NextViper project in the current directory or specified directory, creating nextviper.toml, src/main.nv, tests/, and .gitignore.

terminal

nextviper init my_project

`nextviper add <pkg> [--path <path>] [--git <url>] [--tag <tag>]`

Adds a dependency to nextviper.toml, resolves the dependency DAG, installs it into nextviper_modules/, and updates nextviper.lock.

terminal

# Add a local path dependency
nextviper add math_lib --path ../math_lib

# Add a git repository dependency
nextviper add neural_net --git https://github.com/example/neural_net.git --tag v1.0.0

# Add a semver dependency
nextviper add data "^1.0.0"

`nextviper remove <pkg>`

Removes a dependency from nextviper.toml, regenerates nextviper.lock, and removes package artifacts from nextviper_modules/.

terminal

nextviper remove math_lib

`nextviper install`

Installs all dependencies declared in nextviper.toml / nextviper.lock and validates SHA-256 tree checksums.

terminal

nextviper install

`nextviper update [pkg]`

Re-evaluates SemVer constraints and updates dependencies to their latest compatible versions, updating nextviper.lock.

terminal

nextviper update

`nextviper list`

Displays the full dependency tree, source locations, and verification status.

terminal

nextviper list

Output:

code

my_project v0.1.0
├── math_lib v1.0.0 (path:../math_lib) [verified: 0806fdeb...]
└── neural_net v1.0.0 (git:https://...#v1.0.0) [verified: 91b7852b...]

`nextviper publish [--access <public|private>] [--dry-run]`

Validates manifest fields (name, version, description, license), computes SHA-256 tree checksums, builds a .nvpkg distribution archive in dist/, and uploads the release directly to the NextViper Cloud Registry.

terminal

# 1. Validate & bundle locally without network upload
nextviper publish --dry-run

# 2. Publish public package (interactively prompts & caches credentials in ~/.nextviperrc on first use)
nextviper publish --access public

# 3. Publish private organization package
nextviper publish --access private

# 4. CI/CD automated pipeline publish with explicit credentials
nextviper publish --user $NEXTVIPER_USER --token $NEXTVIPER_TOKEN --access public

Package Integrity Verification

NextViper computes deterministic SHA-256 tree hashes across all files in a package directory (excluding build artifacts and .git).

If any file in a locked dependency is modified or tampered with, nextviper install aborts with a structured diagnostic:

code

error[NV204]: package integrity verification failed for 'math_lib'
  expected: 0806fdeb8c8e2eecad0f026754bb15c3cc007d7445268aafc09c018dac9d46ed
  actual:   dd94d8268ee73ff13f053077868f67a0c592ec69a0fe4885e6f98e2943590dd6
  help: the package files have been modified since the lockfile was generated.
        run 'nextviper update' if this change was intentional.

Import Resolution Integration

When executing a NextViper program:

main.nv

import math_lib

let result = math_lib.compute_hypotenuse(3, 4)
print("Result:", result)

The runtime ModuleManager resolves import math_lib by searching:

nextviper_modules/math_lib/src/main.nv

nextviper_modules/math_lib/src/lib.nv

nextviper_modules/math_lib/main.nv

nextviper_modules/math_lib/mod.nv

.nextviper/packages/math_lib/...

This provides zero-overhead, modular package consumption for all NextViper programs.