Packaging & Install Orchestration
Use this skill for any change or validation pass touching how Chelis is installed, how a toolchain version is selected, or how a clone is provisioned.
Surface
Three layers (design: spec/design/chelis_packaging_and_install.md):
- Layer 0 —
chelisup(crates/chelisup): the toolchain installer and the pin-resolvingchelisshim. One binary, dual role byargv[0]: invoked aschelisit resolves + execs a toolchain; invoked aschelisupit runs the installer CLI (install,link,default,show,list-installed,which,uninstall,update,self {uninstall,update}).link <dir>registers an external toolchain directory as a store link (design §5.1.1). Bootstrap:crates/chelisup/bootstrap/chelisup.sh(the one permitted shell script). - Layer 1 — reef (
crates/chelis-reef): resolve/verify/place source packages, chelis-std, source crates (reef src), and binary artifacts ([artifacts]/LockSource::Binary). - Layer 2 — orchestration (
crates/chelis-cli):chelis reef setupand the unifiedchelis reef doctor.
Bootstrap & private-repo auth. chelisup.sh drops the chelisup prebuilt on
a bare machine; chelisup install <ver> then fetches toolchains. Public releases
work without a GitHub token. The script uses an authenticated gh when
available and otherwise fetches the public release URL with curl. chelisup
resolves GITHUB_TOKEN first, then gh auth token; without either it sends
anonymous GitHub REST requests. Private releases require a token with read
access. Docs to keep in sync: docs/book/src/install.md §1, README.md, and the
design doc §5.5.
Store Layout
$CHELIS_HOME (default ~/.chelis), resolved identically by
chelisup::paths::resolve_home and chelis_reef::chelis_home:
~/.chelis/
bin/{chelis, chelisup} the shim + the installer
toolchains/<ver>/ side-by-side toolchains (<ver>/bin/chelis is real,
or <ver> is a `chelisup link`)
reef/ the reef registry
src/ the source-crate store
default the recorded default versionIn tests, the single CHELIS_HOME seam isolates the toolchain store, the
shim/default, and the binary-artifact dir at once.
Nix chelisup Closure
The Nix package uses bin/chelisup as a wrapper around libexec/chelisup.
Before install or default, the wrapper creates
$CHELIS_HOME/nix-gcroots/chelisup.next.
After success, it promotes $CHELIS_HOME/nix-gcroots/chelisup and removes the
staging root. A failed install preserves the stable root.
If the install copied a new binary, the wrapper promotes
$CHELIS_HOME/nix-gcroots/chelisup.partial.
It removes a partial root that points to the same package as the stable root.
A new attempt recovers a stale staging root before it changes that root.
After success, the Nix wrapper restores itself at $CHELIS_HOME/bin/chelisup.
If restoration fails, the wrapper names the destination file and returns failure.
Help and missing-operand requests change no root and need no nix-store.
The generic Rust installer contains no Nix root path or cleanup logic. The
installed Nix wrapper removes all three roots after the real self uninstall
command succeeds. It also intercepts link and uninstall <ver>. A link to
a store path gets the root $CHELIS_HOME/nix-gcroots/toolchain-<ver>, and a
successful uninstall removes that root.
After a successful install, the wrapper removes each toolchain root whose
toolchains/<ver> entry is no longer a link into the store path of that root.
A failed install keeps every toolchain root.
The wrapper, package inventory, self-uninstall behavior, Nix contract test, and native Nix workflows form one contract. A direct Nix-built executable copy is invalid because external copies do not become Nix GC roots.
The wrapper sets CHELISUP_UPGRADE_ADVICE, which changes only advice text.
A refusal of a newer release then names the Nix upgrade command, not the
bootstrap installer. An unset or blank setting retains the bootstrap advice.
The Embedded chelis-std Runtime
Each binary embeds the chelis-std archive and shell. crates/chelis-std-bundle's
build script stages packages/chelis-std (its reef.toml, the .ch files
under its source roots, and its declared metadata files) and packs it with
chelis_reef::pack_runtime_package at archive mtime 0 whatever
SOURCE_DATE_EPOCH says. chelis reef build runs the same packing step but
archives every file under src/ and honours SOURCE_DATE_EPOCH, so it writes
the embedded pair only from a copy holding just those inputs, with the epoch
unset. Editing a std .ch file and rebuilding is the whole workflow; nothing
generated is committed.
chelis-reefnever depends on the bundle (the bundle build-depends on reef). Every reef andchelis-compiler-apigraph entry point takes the runtime as&'static EmbeddedRuntime; binaries pass&chelis_std_bundle::EMBEDDED_RUNTIME. Only binaries and test harnesses depend on the bundle, so do not add a global provider or a library edge to it.- Never commit
packages/chelis-std/dist/,crates/chelis-std-bundle/dist/, or areef.lockrecording the bundled runtime: every lock names the running binary's runtime hashes.scripts/check_std_bundle_untracked.pyrefuses them. bundled_chelis_std_loader's fixed-point test requireschelis reef buildof such a copy to reproduce the embedded pair and its locks to name those bytes;scripts/check_std_bundle_reproducible.pyrequires two builds to agree.
Shim Resolution Order (first match wins)
- leading
+<ver>arg (chelis +0.13.0 build main.ch) CHELIS_TOOLCHAINenv- nearest
chelis-toolchainfile walking up (ranks above the package pin) - nearest
reef.tomlcompiler =pin walking up - recorded default (
chelisup default <ver>)
Invariants to preserve:
- No auto-install, no silent fallback in the shim. A resolved-but-not-
installed version is a loud error naming
chelisup install <ver>. The shim never downloads oncdand never routes to a different installed version. - Concrete pins only.
+latestis not supported (ambiguous); pins are exactX.Y.Z.is_safe_path_componentgates any version joined into a path.
reef setup And The Shim-Corruption Trap
chelis reef setup [--path] (cmd_reef_setup) runs, in order: ensure the
pinned toolchain → reef install --from-lockfile (if reef.lock) → reef src sync (if [chelis-src]) → reef doctor summary.
- The toolchain step auto-installs by subprocessing the real
chelisupbinary. This is explicit, user-invoked provisioning, exempt from the shim's "no auto-install" rule (which governs only the implicit per-invocation shim). It is not exempt from good taste: it skips the install when the pin is already present, and errors loudly whenchelisupitself is absent. - NEVER call
chelisup::install::install(...)in-process fromchelis-cli. That helper callsensure_shim_installed, which copiescurrent_exe()into<home>/bin/{chelis,chelisup}. From thecheliscompiler binary that would overwrite the shim and the installer with the compiler. - The guard is compile-time. chelisup's
install,ensure_shim_installed,uninstall, andself_uninstallarepub(crate)(only chelisup's owncli.rscalls them; the only external uses are the pure asset-naming helpersdetect_slug,host_is_musl,release_buildandasset_name, fromreef_setup.rs, andnss::use_builtin_services, whichchelis'smaincalls first). Any in-process reference from another crate is anE0603build error caught by the normal clippy/build/test stages. Do NOT widen that visibility topub; keep the call-site comment and the test asserting the shim stays chelisup after an auto-install.
reef doctor
Read-only, never installs. Prints a machine header (chelis home, shim,
default), then per shell: toolchain (chelisup store, chelisup install fix),
source-crate drift (reef src sync fix), and [artifacts] binaries
(reef install --from-lockfile fix). The toolchain check reads the chelisup
store, not the retired ~/.local/share/chelis / install_chelis_toolchain.py.
§5.4 Unknown-Subcommand Hint
main() uses Cli::try_parse(); only clap::error::ErrorKind::InvalidSubcommand
is augmented (chelis version + pin source via chelisup::resolve + +<ver>
guidance). Help, version, unknown flags, and extra positionals defer to clap
byte-for-byte. When adding a subcommand-bearing node, keep it positional-free
so a bogus token stays InvalidSubcommand and the hint still fires.
Validation Rules (positive + negative parity)
reef setup: toolchain present → proceeds; missing + chelisup available → auto-installs and the shim stays chelisup; missing + chelisup absent → loud error namingchelisup install <ver>, neverinstall_chelis_toolchain.py; bad/missingreef.toml→ clear error.reef doctor: toolchain installed → ok; absent → MISSING +chelisup install; artifact present/absent → ok/MISSING.- hint: unknown subcommand → hint fires;
--help/--version/unknown-flag → no hint, clap-native exit codes. - chelisup: exercise the resolution table (each of the five levels) and the not-installed loud error.
Offline Test Seams
CHELIS_HOME— isolate the whole store to a tempdir.CHELISUP_RELEASE_BASE— read the toolchain tarball (chelis-vX.Y.Z-<build>.tar.gz, gzip; name it withchelisup::install::asset_nameandrelease_build, which on Linux names the preferred build:linux-x86_64-muslon a musl host (host_is_musl:/bin/sh's program interpreter is anld-musl-*loader), elselinux-x86_64-static;installfalls back tolinux-x86_64-static, thenlinux-x86_64-glibc2.31, for a release without the preferred one) from a local dir instead of GitHub.CHELISUP_GITHUB_BASE_API,CHELISUP_REPO— wiremock the GitHub REST path.CHELISUP_BIN— pointreef setupat a specificchelisupbinary.CHELIS_REEF_GITHUB_BASE_API,CHELIS_SRC_REMOTE,CHELIS_SRC_HOME— the reef-side seams reused by setup's install/src steps.
Mirror crates/chelis-cli/tests/reef_setup.rs,
reef_doctor_unified.rs, and unknown_subcommand_hint.rs.
Documentation Sync
Behavior changes here must update, in the same change set:
spec/design/chelis_packaging_and_install.md, docs/book/src/install.md,
docs/book/src/reef.md, and the chelis reef rustdoc / help text. Keep the
AGENTS.md (= CLAUDE.md) "Toolchain and packaging" pointer
honest.
Authoritative References
- Design:
spec/design/chelis_packaging_and_install.md - User guide:
docs/book/src/install.md,docs/book/src/reef.md - Shim + store:
crates/chelisup/src/{resolve,paths,install,shim,cli}.rs - Orchestrator + doctor + hint:
crates/chelis-cli/src/main.rs(cmd_reef_setup,ensure_pinned_toolchain,cmd_reef_doctor,handle_parse_error,eprint_pin_hint) - Binary artifacts:
crates/chelis-reef/src/lib.rs(LockSource::Binary,install_binary_artifact,which_artifact)