env-module-manager 0.2.0__tar.gz → 0.4.0__tar.gz

env_module_manager-0.4.0/AGENTS.md

@@ -0,0 +1,101 @@
+# Agents
+
+This file gives coding agents the local rules for working in this repository.
+
+## Project Shape
+
+`module-manager` is a Python CLI for deploying versioned command-line tools
+behind GNU Environment Modules on Linux/HPC systems. The published package name
+is `env-module-manager`, the import package is `module_manager`, and the console
+script is `module-manager`.
+
+The core package lives in `module_manager/`, tests live in `tests/`, and MkDocs
+documentation lives in `docs/`.
+
+Important modules:
+
+* `module_manager/cli.py`: Rich Click command group and CLI wrappers.
+* `module_manager/config.py`: TOML and environment configuration loading.
+* `module_manager/deploy.py`: filesystem deployment and uninstall behavior.
+* `module_manager/modulefile.py`: Tcl modulefile and default-version rendering.
+* `tests/test_cli.py`: command-line behavior tests.
+* `tests/test_config.py`: configuration precedence tests.
+* `tests/test_modulefile.py`: modulefile and deployment helper tests.
+
+## Commands
+
+Use these commands when validating changes:
+
+```bash
+uv run ruff format .
+uv run ruff check .
+uv run pytest
+uv run mkdocs build --strict
+uv build
+uv run twine check dist/*
+```
+
+The test suite is configured with coverage and a 90 percent fail-under
+threshold, so targeted pytest runs can fail coverage even when the selected test
+passes. Run the full suite before treating coverage as meaningful.
+
+## Coding Rules
+
+* Preserve user changes. Do not revert unrelated dirty work.
+* Use typed function signatures throughout tests and source code.
+* Use Google-style docstrings for new or edited functions.
+* Keep Click command functions thin; put filesystem behavior in
+  `module_manager.deploy`.
+* Keep modulefile string generation in `module_manager.modulefile`.
+* Prefer `pathlib.Path` over string path manipulation.
+* Prefer structured subprocess calls such as `subprocess.run([...], check=True)`.
+* Keep edits scoped. Avoid opportunistic refactors while fixing a bug.
+* Update docs and `README.md` when changing user-facing CLI behavior.
+
+## CLI Behavior
+
+Deploy commands create versioned install roots under `<prefix>/<name>/<version>`
+and modulefiles under `<module-root>/<name>/<version>`.
+
+Supported deploy commands:
+
+* `deploy-python`: writes a modulefile for a Python CLI, and can install it with
+  `uv tool install`.
+* `deploy-rust`: copies a compiled binary into the versioned `bin` directory.
+* `deploy-script`: copies a shell script into the versioned `bin` directory.
+* `deploy-env`: reads a TOML manifest and deploys Python, Rust, and script
+  tools into one shared environment module.
+
+Deployments write `<module-root>/<name>/.version` by default so `module load
+<name>` resolves to the deployed version. Use `--no-default` to skip that.
+
+Rust, script, collective environment, and uninstall workflows support
+`--dry-run`. Individual `deploy-python` intentionally keeps `--execute-install`
+for its two-step metadata-first workflow.
+
+`uninstall` removes one versioned install root and modulefile. It removes the
+default selector only when it still points at the version being removed. Use
+`--dry-run` to show paths without deleting them, and `--keep-default` to leave
+the default selector untouched.
+
+## Configuration
+
+Configuration can come from `~/.config/module-manager/config.toml`, a path set
+with `MODULE_MANAGER_CONFIG`, environment variables, or CLI options. CLI options
+take precedence over environment values, which take precedence over TOML.
+
+Common settings:
+
+* `prefix` or `MODULE_MANAGER_PREFIX`
+* `module_root` or `MODULE_MANAGER_MODULE_ROOT`
+* `[python].indexes`, `MODULE_MANAGER_INDEX`, or `MODULE_MANAGER_INDEXES`
+* `[python].find_links` or `MODULE_MANAGER_FIND_LINKS`
+* `[python].uv_config_file` for the uv `--config-file` option. Do not add a
+  `MODULE_MANAGER_*` wrapper for this; users should use uv's `UV_CONFIG_FILE`
+  environment variable when they want environment-based uv configuration.
+
+## Documentation
+
+MkDocs Material is used for documentation. Update `mkdocs.yml` navigation when
+adding pages. The Material theme currently prints an upstream warning during
+`mkdocs build --strict`; the build is still valid when the command exits zero.

{env_module_manager-0.2.0 → env_module_manager-0.4.0}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: env-module-manager
-Version: 0.2.0
-Summary: Deploy Python, Rust, and shell CLI tools behind GNU environment modulefiles
+Version: 0.4.0
+Summary: Deploy Python, Rust, shell, and collective CLI environments behind GNU environment modulefiles
 Project-URL: Homepage, https://github.com/ejb90/module-manager
 Project-URL: Documentation, https://module-manager.readthedocs.io/
 Project-URL: Tests, https://app.codecov.io/gh/ejb90/module-manager
 Project-URL: Repository, https://github.com/ejb90/module-manager
 Author: ejb90
 License-Expression: MIT
-License-File: LICENSE
+License-File: LICENSE.md
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: System Administrators
@@ -40,8 +40,8 @@ Description-Content-Type: text/markdown
 [![PyPI](https://img.shields.io/pypi/v/env-module-manager)](https://pypi.org/project/env-module-manager/)
 [![Python versions](https://img.shields.io/pypi/pyversions/env-module-manager)](https://pypi.org/project/env-module-manager/)
 
-`module-manager` deploys versioned Python, Rust, and shell CLI tools behind GNU
-environment modulefiles for Linux/HPC systems.
+`module-manager` deploys versioned Python, Rust, shell, and collective CLI
+environments behind GNU environment modulefiles for Linux/HPC systems.
 
 It writes tools and modulefiles into predictable versioned locations:
 
@@ -50,6 +50,20 @@ It writes tools and modulefiles into predictable versioned locations:
 /prod/modulefiles/<name>/<version>
 ```
 
+## Installation
+
+Install from PyPI:
+
+```sh
+pip install env-module-manager
+```
+
+Or install as a uv-managed tool:
+
+```sh
+uv tool install env-module-manager
+```
+
 ## Quick Start
 
 Deploy a Python CLI with `uv tool install`:
@@ -80,6 +94,13 @@ module-manager deploy-script my-tool 1.0.0 \
   --module-root /prod/modulefiles
 ```
 
+Deploy a collective environment from a TOML manifest:
+
+```sh
+module-manager deploy-env --file dev-tools.toml --dry-run
+module-manager deploy-env --file dev-tools.toml
+```
+
 Use the generated module:
 
 ```sh
@@ -101,11 +122,5 @@ module-manager uninstall ruff 0.8.0 \
 
 ## Documentation
 
-Full documentation lives in `docs/` and can be served with MkDocs:
-
-```sh
-uv run mkdocs serve
-```
-
-Start with `docs/index.md` for installation, configuration, Python tools, Rust
-tools, shell scripts, uninstall, and local development notes.
+Read the full documentation on
+[Read the Docs](https://module-manager.readthedocs.io/).

{env_module_manager-0.2.0 → env_module_manager-0.4.0}/README.md

@@ -8,8 +8,8 @@
 [![PyPI](https://img.shields.io/pypi/v/env-module-manager)](https://pypi.org/project/env-module-manager/)
 [![Python versions](https://img.shields.io/pypi/pyversions/env-module-manager)](https://pypi.org/project/env-module-manager/)
 
-`module-manager` deploys versioned Python, Rust, and shell CLI tools behind GNU
-environment modulefiles for Linux/HPC systems.
+`module-manager` deploys versioned Python, Rust, shell, and collective CLI
+environments behind GNU environment modulefiles for Linux/HPC systems.
 
 It writes tools and modulefiles into predictable versioned locations:
 
@@ -18,6 +18,20 @@ It writes tools and modulefiles into predictable versioned locations:
 /prod/modulefiles/<name>/<version>
 ```
 
+## Installation
+
+Install from PyPI:
+
+```sh
+pip install env-module-manager
+```
+
+Or install as a uv-managed tool:
+
+```sh
+uv tool install env-module-manager
+```
+
 ## Quick Start
 
 Deploy a Python CLI with `uv tool install`:
@@ -48,6 +62,13 @@ module-manager deploy-script my-tool 1.0.0 \
   --module-root /prod/modulefiles
 ```
 
+Deploy a collective environment from a TOML manifest:
+
+```sh
+module-manager deploy-env --file dev-tools.toml --dry-run
+module-manager deploy-env --file dev-tools.toml
+```
+
 Use the generated module:
 
 ```sh
@@ -69,11 +90,5 @@ module-manager uninstall ruff 0.8.0 \
 
 ## Documentation
 
-Full documentation lives in `docs/` and can be served with MkDocs:
-
-```sh
-uv run mkdocs serve
-```
-
-Start with `docs/index.md` for installation, configuration, Python tools, Rust
-tools, shell scripts, uninstall, and local development notes.
+Read the full documentation on
+[Read the Docs](https://module-manager.readthedocs.io/).

env_module_manager-0.4.0/docs/collective-environments.md

@@ -0,0 +1,83 @@
+# Collective Environments
+
+Collective environments package several tools behind one modulefile. Use them
+when a shared workflow needs Python CLIs, Rust binaries, and shell scripts to
+appear together from one `module load`.
+
+Create a TOML manifest:
+
+```toml
+name = "dev-tools"
+version = "2026.05"
+description = "Shared developer command-line tools"
+prefix = "/prod/tools"
+module_root = "/prod/modulefiles"
+default = true
+
+[[tools]]
+type = "python"
+name = "ruff"
+version = "0.8.0"
+package = "ruff==0.8.0"
+python = "3.12"
+indexes = ["https://packages.example/simple"]
+find_links = ["/prod/wheels"]
+uv_config_file = "/prod/config/uv.toml"
+
+[[tools]]
+type = "rust"
+name = "ripgrep"
+version = "14.1.1"
+binary = "./target/release/rg"
+
+[[tools]]
+type = "script"
+name = "lab-helper"
+version = "1.0.0"
+script = "./scripts/lab-helper"
+```
+
+Deploy the environment:
+
+```sh
+module-manager deploy-env --file dev-tools.toml
+```
+
+This writes one shared environment:
+
+```text
+/prod/tools/dev-tools/2026.05/bin
+/prod/modulefiles/dev-tools/2026.05
+```
+
+The generated modulefile prepends the shared `bin` directory to `PATH`, so all
+tools in the manifest are available after:
+
+```sh
+module use /prod/modulefiles
+module load dev-tools
+```
+
+Relative `binary` and `script` paths are resolved relative to the manifest file.
+
+## Preview
+
+Use `--dry-run` to preview the install, copy, and modulefile actions without
+creating files:
+
+```sh
+module-manager deploy-env --file dev-tools.toml --dry-run
+```
+
+## Overrides
+
+The manifest can define `prefix`, `module_root`, and `default`, but CLI options
+can override them:
+
+```sh
+module-manager deploy-env \
+  --file dev-tools.toml \
+  --prefix /scratch/tools \
+  --module-root /scratch/modulefiles \
+  --no-default
+```

{env_module_manager-0.2.0 → env_module_manager-0.4.0}/docs/configuration.md

@@ -17,6 +17,7 @@ module_root = "/prod/modulefiles"
 [python]
 indexes = ["https://packages.example/simple"]
 find_links = ["/prod/wheels"]
+uv_config_file = "/prod/config/uv.toml"
 ```
 
 Use a different config file with `--config`:
@@ -36,6 +37,10 @@ export MODULE_MANAGER_FIND_LINKS=/prod/wheels,/prod/more-wheels
 
 `MODULE_MANAGER_CONFIG` can point to an alternate TOML config file.
 
+There is no `MODULE_MANAGER_*` environment variable for uv configuration files.
+Use uv's own `UV_CONFIG_FILE` environment variable when you want to set that via
+the environment.
+
 ## CLI Precedence
 
 CLI options override both environment variables and TOML config:

{env_module_manager-0.2.0 → env_module_manager-0.4.0}/docs/environment-modules.md

@@ -55,3 +55,6 @@ module-manager deploy-python ruff 0.8.0 \
 Uninstall removes the default selector only when it still points at the version
 being removed. If another deployment has already made a newer version the
 default, that selector is left alone.
+
+Collective environments use the same modulefile behavior, but the versioned
+`bin` directory contains every tool listed in the manifest.

{env_module_manager-0.2.0 → env_module_manager-0.4.0}/docs/index.md

@@ -1,7 +1,7 @@
 # module-manager
 
-`module-manager` deploys versioned Python, Rust, and shell CLI tools behind GNU
-environment modulefiles for Linux/HPC systems.
+`module-manager` deploys versioned Python, Rust, shell, and collective CLI
+environments behind GNU environment modulefiles for Linux/HPC systems.
 
 It is designed for administrators who want reproducible command-line tool
 installations under a production prefix such as `/prod/tools`, with matching
@@ -27,6 +27,9 @@ The generated modulefile is written to:
 /prod/modulefiles/<name>/<version>
 ```
 
+Collective environments use the same layout, but several tools share one
+versioned `bin` directory and one modulefile.
+
 ## Common Workflow
 
 ```sh
@@ -48,4 +51,5 @@ ruff --version
 - Deploy Python packages with [Python Tools](python-tools.md).
 - Deploy Rust binaries with [Rust Tools](rust-tools.md).
 - Deploy shell scripts with [Shell Scripts](shell-tools.md).
+- Deploy shared tool bundles with [Collective Environments](collective-environments.md).
 - Remove deployed versions with [Uninstall](uninstall.md).

{env_module_manager-0.2.0 → env_module_manager-0.4.0}/docs/installation.md

@@ -38,18 +38,24 @@ in every new shell.
 
 ## Install module-manager
 
-From a local checkout:
+From PyPI with pip:
 
 ```sh
-uv tool install .
+pip install env-module-manager
 ```
 
-From PyPI:
+As a uv-managed tool:
 
 ```sh
 uv tool install env-module-manager
 ```
 
+From a local checkout:
+
+```sh
+uv tool install .
+```
+
 During development, use:
 
 ```sh

{env_module_manager-0.2.0 → env_module_manager-0.4.0}/docs/python-tools.md

@@ -51,6 +51,29 @@ module-manager deploy-python gitconductor 0.1.0 \
 
 `--find-links` may be used more than once.
 
+## Use a uv Config File
+
+Pass a specific uv configuration file to `uv tool install`:
+
+```sh
+module-manager deploy-python internal-tool 1.2.3 \
+  --package internal-tool==1.2.3 \
+  --uv-config-file /prod/config/uv.toml \
+  --prefix /prod/tools \
+  --module-root /prod/modulefiles \
+  --execute-install
+```
+
+The same option can be set in the module-manager config file:
+
+```toml
+[python]
+uv_config_file = "/prod/config/uv.toml"
+```
+
+Use uv's own `UV_CONFIG_FILE` environment variable if you want to configure uv
+through the environment.
+
 ## Deploy from VCS
 
 `--package` is passed directly to `uv tool install`, so VCS package specs are

{env_module_manager-0.2.0 → env_module_manager-0.4.0}/docs/reference.md

@@ -24,6 +24,12 @@ Show shell script deployment options:
 module-manager deploy-script --help
 ```
 
+Show collective environment deployment options:
+
+```sh
+module-manager deploy-env --help
+```
+
 Show uninstall options:
 
 ```sh
@@ -38,6 +44,7 @@ module-manager deploy-python NAME VERSION \
   [--python PYTHON] \
   [--index URL] \
   [--find-links PATH_OR_URL] \
+  [--uv-config-file PATH] \
   [--prefix PATH] \
   [--module-root PATH] \
   [--no-default] \
@@ -51,7 +58,8 @@ module-manager deploy-rust NAME VERSION \
   [--binary PATH] \
   [--prefix PATH] \
   [--module-root PATH] \
-  [--no-default]
+  [--no-default] \
+  [--dry-run]
 ```
 
 ## Shell Script Command
@@ -61,7 +69,19 @@ module-manager deploy-script NAME VERSION \
   [--script PATH] \
   [--prefix PATH] \
   [--module-root PATH] \
-  [--no-default]
+  [--no-default] \
+  [--dry-run]
+```
+
+## Collective Environment Command
+
+```sh
+module-manager deploy-env \
+  --file MANIFEST.toml \
+  [--prefix PATH] \
+  [--module-root PATH] \
+  [--no-default] \
+  [--dry-run]
 ```
 
 ## Uninstall Command

{env_module_manager-0.2.0 → env_module_manager-0.4.0}/docs/rust-tools.md

@@ -26,3 +26,13 @@ The generated modulefile prepends the deployed `bin` directory to `PATH`.
 Deployments make the deployed version the module default, so `module load
 ripgrep` resolves to `ripgrep/14.1.1`. Add `--no-default` to leave the current
 default unchanged.
+
+Preview the paths that would be written without copying the binary:
+
+```sh
+module-manager deploy-rust ripgrep 14.1.1 \
+  --binary ./target/release/rg \
+  --prefix /prod/tools \
+  --module-root /prod/modulefiles \
+  --dry-run
+```

{env_module_manager-0.2.0 → env_module_manager-0.4.0}/docs/shell-tools.md

@@ -27,3 +27,13 @@ the deployed `bin` directory to `PATH`.
 Deployments make the deployed version the module default, so `module load
 my-tool` resolves to `my-tool/1.0.0`. Add `--no-default` to leave the current
 default unchanged.
+
+Preview the paths that would be written without copying the script:
+
+```sh
+module-manager deploy-script my-tool 1.0.0 \
+  --script ./scripts/my-tool \
+  --prefix /prod/tools \
+  --module-root /prod/modulefiles \
+  --dry-run
+```

{env_module_manager-0.2.0 → env_module_manager-0.4.0}/mkdocs.yml

@@ -1,5 +1,5 @@
 site_name: module-manager
-site_description: Deploy Python, Rust, and shell CLI tools behind GNU environment modulefiles.
+site_description: Deploy Python, Rust, shell, and collective CLI environments behind GNU environment modulefiles.
 repo_url: https://github.com/ellis/module-manager
 
 theme:
@@ -46,6 +46,7 @@ nav:
   - Python Tools: python-tools.md
   - Rust Tools: rust-tools.md
   - Shell Scripts: shell-tools.md
+  - Collective Environments: collective-environments.md
   - Uninstall: uninstall.md
   - Environment Modules: environment-modules.md
   - Local Development: development.md

{env_module_manager-0.2.0 → env_module_manager-0.4.0}/module_manager/__init__.py

@@ -1,3 +1,3 @@
 """Deployment helpers for HPC environment module files."""
 
-__version__ = "0.1.0"
+__version__ = "0.4.0"