Zen Package Registry¶

Official package registry and package manager for the Zen programming language.

Features¶

Install, uninstall and upgrade packages
Install several packages in one command
Publish and update packages
Semantic versioning
Install specific package versions
Recursive dependency installation
Automatic dependency detection with zen deps
Native dependency support (.o and .c files)
Read package READMEs in the terminal
Run the official test runner, a test file, or a package's tests
Search and browse packages
Secure account authentication
GitHub-hosted package source
GitHub tag-based releases
Automatic GitHub default branch detection
Library and application package support

CLI Commands¶

Package Management¶

zen install <package>...
zen install <package>@<version>
zen uninstall <package>...
zen upgrade <package>
zen installed
zen search <package>
zen kind <package>
zen read <package> [--raw]
zen test
zen test <file>
zen test <package>
zen mine
zen list
zen publish
zen unpublish
zen deps

Authentication¶

zen signup
zen login
zen whoami
zen logout
zen recovery

Versions¶

zen --version
zen --v
zen version
zen version <package>
zen --v <package>
zen --version <package>

Updating Zen¶

zen update
zen update --dev

Help¶

zen --help
zen --h
zen help

Creating a Package¶

Library¶

zen init mypackage --bin

Application¶

zen init myapp

Library `zen.json`¶

{
  "name": "mypackage",
  "version": "1.0.0",
  "author": "your-github-username",
  "repo": "https://github.com/your-github-username/mypackage",
  "description": "Example package",
  "bin": "lib.zen",
  "dependencies": {}
}

Application `zen.json`¶

{
  "name": "myapp",
  "version": "1.0.0",
  "author": "your-github-username",
  "repo": "https://github.com/your-github-username/myapp",
  "description": "Example application",
  "main": "main.zen",
  "dependencies": {}
}

Package Requirements¶

Every package must:

Have a valid zen.json
Be hosted in a public GitHub repository
Use Semantic Versioning (major.minor.patch)
Have a unique package name
Provide a meaningful description (maximum 400 characters)
Use main for runnable applications
Use bin for library packages

Installing Packages¶

Latest Version¶

Install the latest published version:

zen install http

Multiple Packages¶

Install several packages at once:

zen install http drift axion

Specific Version¶

Install an exact published version:

zen install http@1.0.0

If the requested version does not exist, installation fails.

Library Packages¶

Library packages are installed globally:

~/.zen_packages/

Example:

~/.zen_packages/
└── drift/
    ├── main.zen
    └── zen.json

The installed zen.json contains the currently installed version.

Libraries are imported by package name:

import (App, Request, listen) from "drift"

Runnable Applications¶

Runnable applications are cloned into the current working directory.

Listing Installed Packages¶

Show how many packages are installed:

zen installed

Upgrading Packages¶

Upgrade an installed package:

zen upgrade <package>

Uninstalling Packages¶

Remove an installed package:

zen uninstall <package>

Several packages can be removed at once:

zen uninstall http drift

Reading Package Documentation¶

Render a library package's README in the terminal:

zen read <package>

Print the raw Markdown instead:

zen read <package> --raw

zen read only works for installed library packages that contain a README.md.

Testing¶

Run the official Zen test runner:

zen test

Run a single test file:

zen test <file>

Run the test.zen file of a package:

zen test <package>

Checking Versions¶

Zen version:

zen --v
zen --version
zen version

Installed version of a package:

zen version <package>
zen --v <package>
zen --version <package>

Dependencies¶

Packages can depend on other Zen packages.

Dependencies are stored in zen.json:

{
  "name": "axion",
  "version": "1.0.0",
  "author": "your-github-username",
  "repo": "https://github.com/your-github-username/axion",
  "description": "Example package",
  "bin": "main.zen",
  "dependencies": {
    "drift": "1.0.0"
  }
}

The dependency version specifies the exact version required.

Automatic Dependency Installation¶

When installing a package, Zen automatically reads its dependencies and installs them recursively.

For example:

zen install axion

If Axion contains:

"dependencies": {
  "drift": "1.0.0"
}

Zen automatically performs:

Installing axion...
    ↓
Installing drift@1.0.0...
    ↓
Installed drift
    ↓
Installed axion

Dependencies can themselves have dependencies, and Zen resolves them recursively.

Detecting Dependencies¶

You normally don't need to manually maintain the dependency list.

Run:

zen deps

Zen starts from the package's main or bin entry point and scans imports recursively.

For example:

main.zen
 ├── import "drift"
 └── import "utils.zen"
                  └── import "json-utils"

Zen generates:

"dependencies": {
  "drift": "1.0.0",
  "json-utils": "2.0.0"
}

Local .zen files are scanned recursively but are not added as package dependencies.

Comments are ignored during dependency detection.

Native Dependencies¶

Packages can ship native code.

zen deps detects and records native/*.o files
Native objects are linked automatically
.c files are supported as native dependencies
Extra object files can be linked with --link a.o b.o

Linker flags are set with flags in zen.json, at module level and at standalone level:

{
  "name": "mypackage",
  "version": "1.0.0",
  "bin": "lib.zen",
  "flags": ["-lmariadb"],
  "dependencies": {}
}

Publishing Packages¶

Publish from the package directory:

zen publish

Requirements:

Logged in with zen login
Valid zen.json
Public GitHub repository
Unique package name
Valid Semantic Version
Version must not already exist

Before publishing a new release, update the version in zen.json.

Example:

1.0.0 → 1.0.1

Then create the corresponding Git tag:

git tag v1.0.1
git push origin v1.0.1

Finally:

zen publish

Versioning¶

Zen follows Semantic Versioning:

MAJOR.MINOR.PATCH

Examples:

1.0.0
1.2.0
2.0.1

Each published version is permanently recorded by the registry.

A package can have multiple published versions:

drift
├── 1.0.0
├── 1.0.1
├── 1.1.0
└── 2.0.0

The latest version is used when no version is specified:

zen install drift

A specific version can be selected with:

zen install drift@1.0.0

Zen installs the corresponding Git tag:

v1.0.0

GitHub therefore acts as the source of the actual package release while the Zen registry stores the package/version metadata.

Package Ownership¶

Packages belong to the account that originally published them.

Only the owner can:

Publish new versions
Unpublish the package
Update the repository URL
Update the package description

Authentication¶

Create an account:

zen signup

Login:

zen login

Current account:

zen whoami

Logout:

zen logout

Authentication is stored locally in:

~/.zen/auth.json

Account Recovery¶

When creating an account with zen signup, you receive recovery codes.

Store these codes safely. They cannot be retrieved later.

Recover your account:

zen recovery

You will be prompted for:

Username
Recovery code
New password

Each recovery code can only be used once.

Browsing Packages¶

Browse all packages:

zen list

Search packages:

zen search <package>

Show package type:

zen kind <package>

View packages published by your account:

zen mine

Package Metadata¶

A package's current metadata can be retrieved from the registry:

{
  "name": "mypackage",
  "author": "your-github-username",
  "repo": "https://github.com/your-github-username/mypackage",
  "description": "Example package",
  "latest": "1.0.0"
}

Individual versions are stored separately in the registry.

Release Storage¶

The Zen registry stores metadata for every published version.

For example:

Package: drift

Versions:
  1.0.0 → GitHub tag v1.0.0
  1.1.0 → GitHub tag v1.1.0
  2.0.0 → GitHub tag v2.0.0

The registry does not store the package source code itself.

Package source code remains in the author's GitHub repository.

Important Notes¶

The registry stores metadata for every published version.
The latest field points to the newest published version.
Previous releases remain available through their Git tags.
zen install <package> installs the latest published version.
zen install <package>@<version> installs the requested exact version.
zen install and zen uninstall accept multiple package names.
zen upgrade <package> upgrades an installed package.
Library packages are installed globally under ~/.zen_packages/.
Library packages do not use separate version directories.
Dependencies are installed automatically.
Dependencies can have their own dependencies.
zen deps recursively scans imports to generate the dependency list.
Local .zen imports are not treated as package dependencies.
Library packages are imported by package name without the .zen extension.

Reporting Issues¶

Please open an issue in the Zen repository with:

Clear description
Steps to reproduce
Expected and actual behavior
Environment information

Zen Package Registry¶

Features¶

CLI Commands¶

Package Management¶

Authentication¶

Versions¶

Updating Zen¶

Help¶

Creating a Package¶

Library¶

Application¶

Library zen.json¶

Application zen.json¶

Package Requirements¶

Installing Packages¶

Latest Version¶

Multiple Packages¶

Specific Version¶

Library Packages¶

Runnable Applications¶

Listing Installed Packages¶

Upgrading Packages¶

Uninstalling Packages¶

Reading Package Documentation¶

Testing¶

Checking Versions¶

Dependencies¶

Automatic Dependency Installation¶

Detecting Dependencies¶

Native Dependencies¶

Publishing Packages¶

Versioning¶

Package Ownership¶

Authentication¶

Account Recovery¶

Browsing Packages¶

Package Metadata¶

Release Storage¶

Important Notes¶

Reporting Issues¶

Library `zen.json`¶

Application `zen.json`¶