Moonstone
Moonstone is a cross-platform Lua runtime manager and package manager written in
Zig. It resolves dependencies into deterministic,
runtime-aware project environments backed by a content-addressed store.
Quick start
Create a project, add packages, and synchronize its environment:
moon init . --name my-app --kind script --interpreter [email protected]
moon add inspect
moon add rocks:lua-cjson # LuaRocks resolver
moon sync
Run a script or invoke a command in the project environment:
moon run dev
moon exec -- lua src/main.lua
Use -C or --directory to select a project from another directory:
moon -C ./my-app sync
moon --directory ./my-app run dev
Install runtimes separately from choosing the active one:
moon add --global [email protected]
moon set [email protected]
moon store list --interpreters
moon env
moon remove --global RUNTIME@VERSION removes an unused installed runtime.
It refuses removal while a known project or the global selection references it.
Declared workspace children use the same commands: moon --orbit NAME sync,
moon --orbit NAME exec -- lua main.lua, or moon sync --all for the root and
its direct children. See command workflows for selection,
links, store inspection, and installation lifecycle. See the corrected 0.7.0 release notes for the full
command migration and reinstall instructions.
Operational model
moonstone.toml is the project manifest. It declares metadata, the selected
Lua interpreter, dependencies, and optional [scripts] entries.moonstone.lock records the exact resolution, including package artifacts,
hashes, target profiles, runtime ABI, and materialization details.- The global content-addressed store keeps immutable artifacts under the
Moonstone data directory. Projects share these artifacts rather than copying
them into each project.
moon sync creates or updates .moonstone/env/, a project-local projection
of the locked interpreter, libraries, modules, and binaries.
The store is shared; the environment is project-specific. Use Moonstone
commands to change either one rather than editing .moonstone/env/, the store,
or the lockfile by hand.
run and exec
moon exec -- <command> [args...] is the primitive projected process runner. It
sets the project environment, including executable and Lua module paths, before
starting the command.
moon run <name> selects a named entry in [scripts], projects the same
environment, and forwards arguments directly to the declared command. Shell
expressions require an explicit { shell = "..." } declaration. Keep substantial
orchestration in Lua or ordinary script files. See script arguments.
Runtime and ABI
Moonstone treats PUC Lua and LuaJIT runtimes as first-class packages. Native Lua
modules are checked against the selected runtime ABI and target. Switching, for
example, from Lua 5.4 to LuaJIT changes the ABI profile, so incompatible native
artifacts are not reused until moon sync resolves or rebuilds them.
On Windows, environment projections prefer symbolic links and fall back to
copying when links are unavailable. Developer Mode or symbolic-link privilege
avoids the copy overhead.
Where to go next
Status and license
Moonstone is pre-1.0 alpha. APIs, registry contracts, lockfile details, and CLI
behavior may evolve.
Licensed under Apache License 2.0.
