Packages

Install a package

Packages install with one command and resolve automatically at import. The installer only needs Node.js (it is part of the npm launcher) — packages themselves are pure Mozhi source.

mz install strings                      # from the Mozhi registry
mz install datetime@v1.0.0              # pin a release tag
mz install @user/repo                   # any GitHub repo's latest release
mz install @user/repo@v0.2.0            # ... pinned to a tag
mz install ./tool.mz.pkg.zip            # manual / offline install from a zip
mz install ./mytool                     # from a local package directory

Then use it like a native module — installed packages bind with module (namespace) semantics:

import strings

echo(strings.reverse("Mozhi"))              # ihzoM
echo(strings.slugify("Hello Mozhi World")) # hello-mozhi-world

Manage packages

mz list                    # name, version, origin (repo@tag), path
mz search web              # search the registry
mz uninstall strings

Packages live in ~/.mozhi/pkg/<name> (global — the default), or ./.mozhi/pkg/<name> with mz install --local. The interpreter checks the project dir, then $MZ_LIB/pkg/, then the global dir; legacy single-file libraries in ~/.mozhi/libs/ keep working alongside them. Re-installing upgrades in place.

The registry

mz install <name> looks names up in mozhi-registry.json — a version-controlled JSON file in the public mozhi-doc repository, so every registry change is auditable through git history. Registry entries point at a Git repository:

{
  "name": "strings",
  "repo": "crossberry-in/mozhi-strings",
  "dist": "releases",
  "asset": "strings.mz.pkg.zip",
  "import_as": "strings",
  "description": "String manipulation — reverse, capitalize, snake_case, ..."
}

The launcher fetches the registry live, and falls back to a cached copy and a bundled snapshot when offline. Override with MOZHI_REGISTRY_URL (also: MOZHI_GH_API, MOZHI_LIBS_URL).

Create your own package

mz pkg new scaffolds everything — manifest, entry module, example, test, README, MIT license and a GitHub Actions release workflow:

mz pkg new mytool
cd mytool
mozhi test                # the sample test passes out of the box
mz pkg check              # verify package structure

A package is a directory with a package.toml manifest:

mytool/
  package.toml            # name, version, entry = "src/mod.mz"
  src/mod.mz              # entry — everything here becomes the module
  examples/demo.mz        # optional
  tests/mytool.test.mz    # run with: mozhi test

Build a zip locally any time with mz pkg zip — it produces mytool.mz.pkg.zip with a single top-level directory named after the package.

Publish (tag → release → installable)

Push the repo to GitHub and tag a release — that is the whole process. The scaffolded workflow (.github/workflows/release.yml) runs on v* tags, builds the package zip with git archive (CI files are excluded via .gitattributes export-ignore), and attaches <name>.mz.pkg.zip to the auto-created release:

git init && git add -A && git commit -m "initial import"
git remote add origin git@github.com:<you>/mytool.git
git push -u origin main
git tag v0.1.0 && git push origin v0.1.0

Anyone can now install it directly — no registry listing required:

mz install @<you>/mytool

Official packages

mz install strings

mz install datetime

Single-file standard-library extensions (mozhi-html, mozhi-http, mozhi-json, mozhi-math-utils) are also installable — see the standard library page.