Skip to content

install-source-and-updates.md

Latest commit

 

History

History
48 lines (32 loc) · 4.96 KB

install-source-and-updates.md

File metadata and controls

48 lines (32 loc) · 4.96 KB
Raw
title Installation sources and updates

Installation sources and updates

The public installer is a committed PEP 723 uv --script file generated from Envman's standard-library release protocol. It has no third-party runtime dependencies. It downloads release-manifest-v2.json through GitHub's releases/latest route, then downloads only the immutable assets named by that manifest. The legacy release-manifest.json remains wheel-and-constraints-only so immutable pre-skill installers can continue updating; the immutable v0.1.5 installer still uses that legacy manifest.

Trust boundary

The installer accepts a manifest only when all of these checks pass:

  1. The document is bounded, UTF-8 JSON with the exact envman.release-manifest schema and schema version.
  2. The repository is exactly CruxExperts/envman, the version is strict MAJOR.MINOR.PATCH SemVer, and each asset URL is the immutable https://github.com/CruxExperts/envman/releases/download/vVERSION/... URL for that version.
  3. The wheel and runtime-constraints.txt assets have bounded sizes, matching SHA-256 digests, matching byte lengths, safe basenames, and the expected filenames.
  4. The constraints file contains only exact package pins and includes cryptography. The wheel is inspected as a ZIP without extracting untrusted members, and its Envman metadata must match the manifest version.
  5. Downloads use HTTPS and accept only GitHub-controlled hosts and redirects. Credentials and fragments are rejected.
  6. The host is Linux x86_64 with CPython >=3.12,<3.13, and the invoked uv reports a version >=0.11; newer uv releases are supported.
  7. After installation, the command path is resolved from uv tool dir --bin and that exact executable must report the manifest version. Verification never falls back to a different envman found through PATH.

The installer trusts the local uv executable and selected Python runtime, GitHub release hosting and its controlled asset redirects, and PyPI over TLS for the exact packages in the verified constraints projection. It does not claim a hermetic dependency install. --no-build prevents source builds while installing the verified wheel. The optional skill installer uses the LocalSetup 4.49.2 agent catalog embedded in the release protocol. Its canonical write roots come from LocalSetup's generated platform projection, while supported native and historical roots are recognized for safe refresh. Repository and global boundaries reject traversal and symlink components. Existing unmarked skills are preserved rather than adopted.

The installer does not silently generate or replace the encrypted-backup key. Key setup is deferred to first runtime or the explicit envman key --generate --approve-key-generation command, which requires approval; --yes and --force are not approval.

Receipt-directed updates

After a verified install, the installer creates ${XDG_STATE_HOME:-$HOME/.local/state}/envman/install.json. A missing state directory is created with mode 0700; an existing non-symlink directory keeps its current mode. The receipt is written atomically with mode 0600, refuses symlinks, and has the exact envman.install-receipt schema. It records:

  • installed version and installation time;
  • provider (github-release-wheel) and repository;
  • manifest URL;
  • verified wheel and runtime-constraints asset metadata;
  • installer version (1.0.0 for receipts created by the 1.0.0 installer; older receipts retain their original installer provenance) and uv versions.

envman update reads that receipt and supports only its recorded provider. A standard public receipt points at GitHub's latest-release manifest. The updater fetches that source, rejects a candidate that is older than the recorded version, and reports current without reinstalling an equal tool version. --check stops after reporting availability. --install-skill can still install or refresh the equal release's verified skill for any supported scope and agent target. A tool update downloads and verifies the new assets, prefetches the prior assets, and writes the new receipt only after the replacement succeeds.

Failure, rollback, and uninstall

If replacement fails, the installer attempts to uninstall the partially replaced envman tool, reinstalls the previously verified wheel and constraints, and restores the previous receipt. If rollback itself fails, it reports both failures rather than claiming success.

There is no envman uninstall command. To remove only the uv tool, run:

uv tool uninstall envman

That command does not remove managed values, backups, shell-loader files, or the receipt. A deliberately abandoned installation should remove the stale receipt at ${XDG_STATE_HOME:-$HOME/.local/state}/envman/install.json before a fresh install; otherwise the installer will reject the mismatch between an existing receipt and an absent Envman tool. See storage and shell loading for the data that remains outside the tool installation.