env-module-manager 0.1.2__tar.gz → 0.3.0__tar.gz

env_module_manager-0.3.0/AGENTS.md

@@ -0,0 +1,98 @@
+# 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`
+
+## 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.1.2 → env_module_manager-0.3.0}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: env-module-manager
-Version: 0.1.2
-Summary: Deploy Python and Rust CLI tools behind GNU environment modulefiles
+Version: 0.3.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 and Rust 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:
 
@@ -71,14 +71,41 @@ module-manager deploy-rust ripgrep 14.1.1 \
   --module-root /prod/modulefiles
 ```
 
+Deploy a shell script:
+
+```sh
+module-manager deploy-script my-tool 1.0.0 \
+  --script ./scripts/my-tool \
+  --prefix /prod/tools \
+  --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
 module use /prod/modulefiles
-module load ruff/0.8.0
+module load ruff
 ruff --version
 ```
 
+Deployments make the deployed version the module default. Add `--no-default`
+when you want to write the versioned modulefile without changing the default.
+
+Remove a deployed version:
+
+```sh
+module-manager uninstall ruff 0.8.0 \
+  --prefix /prod/tools \
+  --module-root /prod/modulefiles
+```
+
 ## Documentation
 
 Full documentation lives in `docs/` and can be served with MkDocs:
@@ -88,4 +115,5 @@ uv run mkdocs serve
 ```
 
 Start with `docs/index.md` for installation, configuration, Python tools, Rust
-tools, and local development notes.
+tools, shell scripts, collective environments, uninstall, and local development
+notes.

{env_module_manager-0.1.2 → env_module_manager-0.3.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 and Rust 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:
 
@@ -39,14 +39,41 @@ module-manager deploy-rust ripgrep 14.1.1 \
   --module-root /prod/modulefiles
 ```
 
+Deploy a shell script:
+
+```sh
+module-manager deploy-script my-tool 1.0.0 \
+  --script ./scripts/my-tool \
+  --prefix /prod/tools \
+  --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
 module use /prod/modulefiles
-module load ruff/0.8.0
+module load ruff
 ruff --version
 ```
 
+Deployments make the deployed version the module default. Add `--no-default`
+when you want to write the versioned modulefile without changing the default.
+
+Remove a deployed version:
+
+```sh
+module-manager uninstall ruff 0.8.0 \
+  --prefix /prod/tools \
+  --module-root /prod/modulefiles
+```
+
 ## Documentation
 
 Full documentation lives in `docs/` and can be served with MkDocs:
@@ -56,4 +83,5 @@ uv run mkdocs serve
 ```
 
 Start with `docs/index.md` for installation, configuration, Python tools, Rust
-tools, and local development notes.
+tools, shell scripts, collective environments, uninstall, and local development
+notes.

env_module_manager-0.3.0/docs/collective-environments.md

@@ -0,0 +1,82 @@
+# 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"]
+
+[[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.3.0/docs/environment-modules.md

@@ -0,0 +1,60 @@
+# Environment Modules
+
+Generated modulefiles are Tcl modulefiles for Environment Modules.
+
+Use a generated module tree:
+
+```sh
+module use /prod/modulefiles
+module load ruff
+ruff --version
+```
+
+You can also load an explicit version:
+
+```sh
+module load ruff/0.8.0
+ruff --version
+```
+
+## Generated Modulefile Behavior
+
+Each modulefile:
+
+- prepends the tool's versioned `bin` directory to `PATH`
+- sets `<TOOL>_ROOT`
+- includes `module-whatis`
+- includes install guidance in `module help`
+
+For `ruff/0.8.0`, the root variable is:
+
+```sh
+RUFF_ROOT=/prod/tools/ruff/0.8.0
+```
+
+## Default Versions
+
+Deploy commands write a default-version selector by default:
+
+```text
+/prod/modulefiles/<name>/.version
+```
+
+For `ruff/0.8.0`, this makes `module load ruff` resolve to `ruff/0.8.0`.
+
+Use `--no-default` when a deployment should not update the default version:
+
+```sh
+module-manager deploy-python ruff 0.8.0 \
+  --package 'ruff==0.8.0' \
+  --prefix /prod/tools \
+  --module-root /prod/modulefiles \
+  --no-default
+```
+
+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.1.2 → env_module_manager-0.3.0}/docs/index.md

@@ -1,7 +1,7 @@
 # module-manager
 
-`module-manager` deploys versioned Python and Rust 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
@@ -47,3 +50,6 @@ ruff --version
 - Set shared defaults in [Configuration](configuration.md).
 - 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.1.2 → env_module_manager-0.3.0}/docs/python-tools.md

@@ -21,6 +21,10 @@ Without `--execute-install`, the command creates the versioned directories and
 modulefile only. The module help includes the `uv tool install` command that an
 administrator can run later.
 
+Deployments also make the deployed version the module default, so `module load
+ruff` resolves to `ruff/0.8.0`. Add `--no-default` to leave the current default
+unchanged.
+
 ## Deploy from a Private Index
 
 ```sh

env_module_manager-0.3.0/docs/reference.md

@@ -0,0 +1,94 @@
+# CLI Reference
+
+Show top-level help:
+
+```sh
+module-manager --help
+```
+
+Show Python deployment options:
+
+```sh
+module-manager deploy-python --help
+```
+
+Show Rust deployment options:
+
+```sh
+module-manager deploy-rust --help
+```
+
+Show shell script deployment options:
+
+```sh
+module-manager deploy-script --help
+```
+
+Show collective environment deployment options:
+
+```sh
+module-manager deploy-env --help
+```
+
+Show uninstall options:
+
+```sh
+module-manager uninstall --help
+```
+
+## Python Command
+
+```sh
+module-manager deploy-python NAME VERSION \
+  --package PACKAGE \
+  [--python PYTHON] \
+  [--index URL] \
+  [--find-links PATH_OR_URL] \
+  [--prefix PATH] \
+  [--module-root PATH] \
+  [--no-default] \
+  [--execute-install]
+```
+
+## Rust Command
+
+```sh
+module-manager deploy-rust NAME VERSION \
+  [--binary PATH] \
+  [--prefix PATH] \
+  [--module-root PATH] \
+  [--no-default] \
+  [--dry-run]
+```
+
+## Shell Script Command
+
+```sh
+module-manager deploy-script NAME VERSION \
+  [--script PATH] \
+  [--prefix PATH] \
+  [--module-root PATH] \
+  [--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
+
+```sh
+module-manager uninstall NAME VERSION \
+  [--prefix PATH] \
+  [--module-root PATH] \
+  [--keep-default] \
+  [--dry-run]
+```

{env_module_manager-0.1.2 → env_module_manager-0.3.0}/docs/rust-tools.md

@@ -22,3 +22,17 @@ and creates:
 ```
 
 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.3.0/docs/shell-tools.md

@@ -0,0 +1,39 @@
+# Shell Scripts
+
+Shell scripts can be copied directly into the versioned prefix.
+
+```sh
+module-manager deploy-script my-tool 1.0.0 \
+  --script ./scripts/my-tool \
+  --prefix /prod/tools \
+  --module-root /prod/modulefiles
+```
+
+This writes the script to:
+
+```text
+/prod/tools/my-tool/1.0.0/bin/my-tool
+```
+
+and creates:
+
+```text
+/prod/modulefiles/my-tool/1.0.0
+```
+
+The deployed script is marked executable, and the generated modulefile prepends
+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.3.0/docs/uninstall.md

@@ -0,0 +1,42 @@
+# Uninstall
+
+Remove one deployed tool version with the `uninstall` command:
+
+```sh
+module-manager uninstall ruff 0.8.0 \
+  --prefix /prod/tools \
+  --module-root /prod/modulefiles
+```
+
+This removes:
+
+```text
+/prod/tools/ruff/0.8.0
+/prod/modulefiles/ruff/0.8.0
+```
+
+If the default selector points at the same version, it is removed too:
+
+```text
+/prod/modulefiles/ruff/.version
+```
+
+If the default selector points at a different version, it is left in place.
+
+Preview an uninstall without deleting files:
+
+```sh
+module-manager uninstall ruff 0.8.0 \
+  --prefix /prod/tools \
+  --module-root /prod/modulefiles \
+  --dry-run
+```
+
+Leave the default selector untouched even when it points at the removed version:
+
+```sh
+module-manager uninstall ruff 0.8.0 \
+  --prefix /prod/tools \
+  --module-root /prod/modulefiles \
+  --keep-default
+```

{env_module_manager-0.1.2 → env_module_manager-0.3.0}/mkdocs.yml

@@ -1,5 +1,5 @@
 site_name: module-manager
-site_description: Deploy Python and Rust 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:
@@ -45,6 +45,9 @@ nav:
   - Configuration: configuration.md
   - 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
   - CLI Reference: reference.md