W Wax

Versions and lockfiles

wax.json says which versions are allowed. wax.lock records the versions and download hashes in use.

Version ranges

Wax packages use semantic versions. Manifests accept these range forms:

Form Example Meaning
Exact 1.2.3 or =1.2.3 Only that version
Any * or x Any stable version
Partial 1 or 1.2 Any version matching the written components
Comparison >=1.2.0 <2.0.0 Every comparator separated by whitespace must match
Compatible ^1.2.3 Do not increment the first component that is not zero
Patch or minor line ~1.2.3 At least 1.2.3, below 1.3.0
Alternative `^1.0.0

Prereleases are excluded unless a comparator in the same group explicitly names a prerelease with the same major, minor, and patch.

One version per package

Wax selects one version of each package for the whole project. It considers direct and indirect requirements together, trying older versions when the newest choice conflicts with another dependency. If no combination works, the error lists the packages, aliases, versions, and ranges involved.

add, remove, and update resolve. install resolves only when no lockfile exists.

What wax.lock records

The lockfile binds:

  • a hash of the wax.json file;
  • the registry used for resolution;
  • root aliases and their package identities;
  • every selected package version and dependency alias;
  • archive URLs and SHA 512 integrity values.

Commit the generated file unchanged. Even whitespace edits to wax.json make the lockfile stale because Wax hashes the whole file. Run wax update when that manifest change is intentional; do not edit archive locations or hashes.

Restore and cache packages

With a valid lockfile, wax install downloads only missing archives, checks each against its locked hash, and validates its manifest. It replaces Packages/ only after every package passes. Cached archives are checked again before use.

The default cache is ~/.wax/cache/packages-v1, with the equivalent home directory on Windows. Override it with WAX_CACHE_DIR or --cache PATH.

wax install --cache .build-cache/wax
wax install --cache .build-cache/wax --offline

The second command proves the locked build inputs are available without registry access. Offline mode requires both a valid lockfile and every archive in the selected cache; it never resolves or substitutes versions.

Check for updates

wax outdated
wax update

outdated reports Current (locked), Wanted (newest version allowed by the manifest), and Latest (newest stable published version, even outside the range). It changes nothing. update selects and installs new versions. If that fails, Wax restores the previous lockfile and installed packages.

For details on download checks and safe updates, read Package safety.