valise-sh 0.2.0 → 0.3.0

package/examples/e2e/module.d/e2e_generated_config.meta

@@ -1,9 +1,8 @@
 name=e2e_generated_config
 requires=e2e_env_setup
 optional=
-shells=sh bash zsh ksh
+shells=posix bash zsh ksh
 platforms=any
 side_effect=read-only
 exports=e2e_config_loaded
-updates=
 load=modules/e2e/generated_config.sh

package/examples/e2e/module.d/e2e_ksh_features.meta

@@ -5,5 +5,4 @@ shells=ksh
 platforms=any
 side_effect=read-only
 exports=e2e_ksh_loaded
-updates=
 load=modules/e2e/ksh_features.sh

package/examples/e2e/module.d/e2e_layer_probe.meta

@@ -1,9 +1,8 @@
 name=e2e_layer_probe
 requires=e2e_env_setup
 optional=contrib_shared_paths
-shells=sh bash zsh ksh
+shells=posix bash zsh ksh
 platforms=any
 side_effect=read-only
 exports=e2e_layer_probe_ok
-updates=
 load=modules/e2e/layer_probe.sh

package/examples/e2e/module.d/e2e_optional_network.meta

@@ -1,9 +1,8 @@
 name=e2e_optional_network
 requires=
 optional=e2e_env_setup
-shells=sh bash zsh ksh
+shells=posix bash zsh ksh
 platforms=any
 side_effect=read-only
 exports=e2e_net_available
-updates=
 load=modules/e2e/optional_network.sh

package/examples/e2e/module.d/e2e_platform_tools.meta

@@ -0,0 +1,8 @@
+name=e2e_platform_tools
+requires=e2e_env_setup
+optional=e2e_platform_tools_darwin e2e_platform_tools_linux e2e_platform_tools_bsd
+shells=posix
+platforms=any
+side_effect=read-only
+exports=
+load=

package/examples/e2e/module.d/e2e_platform_tools_bsd.meta

@@ -1,9 +1,8 @@
 name=e2e_platform_tools_bsd
-requires=platform_bsd
+requires=valise_platform_bsd
 optional=
-shells=sh bash zsh ksh
+shells=posix bash zsh ksh
 platforms=bsd freebsd openbsd netbsd
 side_effect=read-only
 exports=e2e_bsd_tools_ready
-updates=
 load=modules/e2e/platform_tools_bsd.sh

package/examples/e2e/module.d/e2e_platform_tools_darwin.meta

@@ -1,9 +1,8 @@
 name=e2e_platform_tools_darwin
-requires=platform_macos
+requires=valise_platform_macos
 optional=e2e_env_setup
-shells=sh bash zsh ksh
+shells=posix bash zsh ksh
 platforms=darwin
 side_effect=read-only
 exports=e2e_darwin_tools_ready
-updates=
 load=modules/e2e/platform_tools_darwin.sh

package/examples/e2e/module.d/e2e_platform_tools_linux.meta

@@ -1,9 +1,8 @@
 name=e2e_platform_tools_linux
-requires=platform_linux
+requires=valise_platform_linux
 optional=
-shells=sh bash zsh ksh
+shells=posix bash zsh ksh
 platforms=linux
 side_effect=read-only
 exports=e2e_linux_tools_ready
-updates=
 load=modules/e2e/platform_tools_linux.sh

package/examples/e2e/valise.conf

@@ -0,0 +1,4 @@
+# valise project configuration.
+bundle=default
+variant=default
+requires_valise=0.3.0

package/examples/e2e/variants.tsv

@@ -0,0 +1,3 @@
+variant	description	excluded
+default	Every e2e module	
+no-network	Without the network probe	e2e_optional_network

package/examples/local/module.d/hello_valise.meta

@@ -1,9 +1,8 @@
 name=hello_valise
 requires=
 optional=
-shells=sh bash zsh ksh
+shells=posix bash zsh ksh
 platforms=any
 side_effect=read-only
 exports=hello_valise_loaded
-updates=
 load=modules/hello_valise.sh

package/examples/profile-project/README.md

@@ -1,40 +1,32 @@
-# profile-project: a complete valise project
+# profile-project: a small valise project
 
-This is a small but complete consuming project. It shows every piece a
-profile project needs: metadata that describes the modules, module bodies,
-a provider layer contributed by somebody else, a bundle that says which
-roots load, a variant that says what to leave out, and project defaults.
-
-Everything here is plain text. There is no build script and no hand-written
-registry. `valise` reads the metadata and generates what it needs.
+This project has two modules of its own, one module from a provider layer, a
+bundle, and two variants. Everything is plain text; `valise` reads the
+metadata and generates the rest.
 
 ## What is in it
 
 ```
-shell/
-  module.d/                          the project's own modules
-    profile_main.meta                the entry module
-    greeting.meta                    a dependency of profile_main
-  modules/                           the bodies of those modules
-    greeting.sh
-  layers/demo/                       a provider layer
-    module.d/contrib_demo_greeting.meta
-    modules/shared/contrib_demo_greeting.sh
-  release/
-    bundle-roots                     which roots load, per shell
-    install-variants                 named exclusion sets
-    project.conf                     defaults for build and apply
+valise.conf                          default bundle and variant
+module.d/
+  profile_main.meta                  the root: requires greeting
+  greeting.meta                      defines greet
+modules/
+  greeting.sh
+layers/demo/                         a provider layer
+  module.d/contrib_demo_greeting.meta
+  modules/shared/contrib_demo_greeting.sh
+bundles.tsv                          the roots for bash, zsh, and ksh
+variants.tsv                         default and workstation-lean
 ```
 
-`profile_main` is a meta module: it has `requires=greeting` and no body of
-its own, so there is no `modules/profile_main.sh`. It exists only to name
-what the project loads. `greeting` is an ordinary module that defines
-`greet`.
+`profile_main` is a meta module: it has `requires=greeting` and no body. It
+names what the project loads. `greeting` is an ordinary module with
+`shells=posix`.
 
-The layer under `shell/layers/demo/` is a provider layer. Its module is
-named `contrib_demo_greeting`, following the `contrib_<owner>_<thing>`
-convention, and its body lives under `layers/demo/` in the installed
-release, so it never collides with the project's own modules.
+The layer module is named `contrib_demo_greeting`, following the
+`contrib_<owner>_<thing>` convention. A release copies it to
+`layers/demo/`, so it cannot collide with the project's own files.
 
 ## Build it
 
@@ -44,60 +36,38 @@ From this directory:
 valise build
 ```
 
-That compiles a plan for each supported shell and writes a release under
-`build/release/`. The release contains:
-
 ```
 build/release/
-  generated/installed-modules.bash    compiled plan for bash
-  generated/installed-modules.zsh     compiled plan for zsh
-  generated/installed-modules.ksh     compiled plan for ksh
-  vendor/shell-profile/lib/capabilities.sh
-  module.d/                          the project's metadata
-  modules/                           the project's bodies
-  layers/demo/module.d/              the layer's metadata
-  layers/demo/modules/shared/        the layer's bodies
-  shell/release/                     registry, bundle, variants, defaults
-  shell/install/profile-release.manifest
+  valise-release.conf                bundle, variant, roots, modules
+  manifest.tsv                       every file with its size and SHA-256
+  plans/bash.sh                      the compiled plan for bash
+  plans/zsh.sh
+  plans/ksh.sh
+  runtime/capabilities.sh            the sp_cap_* helpers
+  module.d/, modules/                the project's modules
+  layers/demo/                       the layer module
 ```
 
-The plans are plain POSIX shell. You can read one to see exactly what will
-run.
+The plans are plain POSIX shell; read one to see what will run at startup.
+`bundles.tsv` has no `sh` row, so dash and other plain `sh` shells load
+nothing.
 
 ## Load it
 
-```sh
-valise apply
-```
-
-`apply` builds the release, installs it under your XDG data directory, and
-writes a managed block into the startup files your shells read. It prints
-what it changed and where.
-
-The managed block is guarded by a source-once variable, so your login shell
-loads the profile exactly once. It prefers the compiled plan for your shell
-and falls back to the loader if the release has no compiled plan.
-
-zsh does not read `~/.profile` on its own, so when zsh is present `apply`
-writes the same managed block to `~/.zprofile`. bash reads `~/.profile` only
-when no `~/.bash_profile` exists; `apply` never creates one, so it does not
-shadow your `~/.profile`.
-
-Now open a new login shell:
+Run this in a scratch `HOME` (see the main README) unless you want it in your
+real startup files:
 
 ```sh
-bash -l
-greet
+valise apply
+bash -l -c greet
 # hello from the valise profile project
 ```
 
-The same works in zsh and ksh. It does not work in dash: the plans are
-compiled for bash, zsh and ksh, and dash is not one of them.
-
-To undo it, remove the managed block from every startup file `apply`
-reported.
-
-To check the current state:
+`apply` builds the release, installs it under your XDG data directory, and
+writes a managed block into `~/.profile`, `~/.zprofile` when zsh is
+installed, and `~/.bashrc` or `~/.zshrc` when that is your shell. It prints
+each file it wrote. `valise apply --dry-run` prints what it would change
+without changing it.
 
 ```sh
 valise status
@@ -105,77 +75,77 @@ valise status
 
 ```
 project: /path/to/profile-project
-variant: default
-bundle: default
+project default bundle: default
+project default variant: default
 integration: /home/you/.profile: managed block present
 integration: /home/you/.zprofile: managed block present
-registry: up to date
-active release: 0a723dcb0860bcae3ea259c631aaa76ce8e0b4e6991448979018c1d08fc35802
-build output: /path/to/profile-project/build/release
+active release: ad98ea2ba30bb6c6d4f08b6dec59585228cdf855b814543a37f80ee0f0518773
+active bundle: default
+active variant: default
+active built by valise: 0.3.0
+build output: /path/to/profile-project/build/release (bundle default, variant default)
 drift: active release matches build output
 ```
 
-`status` reports the active release, the startup files, and whether the
-installed release still matches what the project would build. If you edit a
-module and re-apply, the release changes and the drift line tells you the
-active release is no longer the one you built.
+Edit a module and run `valise status` again after `valise build`: the drift
+line reports that the active release no longer matches the build.
+
+`valise uninstall` removes the managed blocks, the Fish hook, and the
+installed releases.
 
 ## Try a variant
 
-The project ships two variants. `default` loads everything;
-`workstation-lean` leaves out the provider layer:
+`workstation-lean` leaves out the layer module:
 
 ```sh
 valise explain-variant workstation-lean
 ```
 
-To use the lean variant, set it in `shell/release/project.conf`:
-
-```sh
-variant=workstation-lean
 ```
+Variant: workstation-lean
+Description: No provider layer
+Excluded modules: contrib_demo_greeting@layers/demo/module.d
 
-Then re-apply. The `contrib_demo_greeting` module disappears from the plan
-and the rest still loads.
-
-An exclusion that removes a module something else still depends on is an
-error, not a silent surprise:
-
-```
-ERROR: variant exclusion breaks a required dependency: profile_main requires contrib_demo_greeting
+Per-shell impact (bundle default):
+  bash: 1 of 2 roots, 2 of 3 modules
+  zsh: 1 of 2 roots, 2 of 3 modules
+  ksh: 1 of 2 roots, 2 of 3 modules
 ```
 
+Build it with `valise apply --variant=workstation-lean`, or set
+`variant=workstation-lean` in `valise.conf`. An exclusion that removes a
+module something else still requires fails the build and names both
+modules.
+
 ## Try a bundle
 
-`shell/release/bundle-roots` says which roots load for each shell:
+`bundles.tsv` lists the roots for each shell:
 
 ```
-default	bash	profile_main contrib_demo_greeting@shell/layers/demo/module.d
+default	bash	profile_main contrib_demo_greeting
 ```
 
-The first root is a bare name, meaning a module from the project's own
-`shell/module.d/`. The second is qualified with its source, so it is
-unambiguous even though it lives in a layer.
+A bare name means the project's own module when there is one, otherwise the
+only module with that name. `name@layers/demo/module.d` names the layer's
+copy exactly, which you need when two sources define the same name.
 
 ```sh
 valise explain-bundles
 ```
 
-## Check the layer
-
-A provider layer has rules: the `contrib_` prefix, a version, a body that
-exists, and no dependency that escapes the layer.
+## Check it
 
 ```sh
+valise lint          # metadata, layers, every bundle and variant, syntax
 valise layer-lint demo
 # layer demo: 1 module(s) validated
 ```
 
 ## Where to go next
 
-- [The module ABI](../../docs/module-abi.md) — every metadata field.
-- [The authoring guide](../../docs/contrib-modules.md) — writing modules.
-- [The compile and build contract](../../docs/variants.md) — the registry,
-  bundles, variants, and what a compiled plan contains.
-- [Shared modules](../../docs/shared-modules.md) — how layer modules are
+- [Projects](../../docs/projects.md): bundles, variants, compile, and build.
+- [Writing modules](../../docs/contrib-modules.md): authoring, linting, and
+  testing.
+- [The module ABI](../../docs/module-abi.md): every metadata field.
+- [Shared modules](../../docs/shared-modules.md): how layer modules are
   named and owned.

package/examples/profile-project/bundles.tsv

@@ -0,0 +1,8 @@
+bundle	shell	roots
+# Each row names a bundle, a shell (sh bash zsh ksh fish), and the
+# space-separated root modules for that shell. A bare name means the module
+# in module.d/, else the only module of that name; name@layers/<p>/module.d
+# names a layer module exactly.
+default	bash	profile_main contrib_demo_greeting
+default	zsh	profile_main contrib_demo_greeting
+default	ksh	profile_main contrib_demo_greeting

package/examples/profile-project/{shell/layers → layers}/demo/module.d/contrib_demo_greeting.meta

@@ -3,8 +3,7 @@ version=1.0.0
 side_effect=read-only
 requires=
 optional=
-shells=sh bash zsh ksh
+shells=posix
 platforms=any
 exports=contrib_demo_greeting_ready
-updates=
 load=modules/shared/contrib_demo_greeting.sh

package/examples/profile-project/{shell/module.d → module.d}/greeting.meta

@@ -3,8 +3,7 @@ version=1.0.0
 side_effect=read-only
 requires=
 optional=
-shells=sh bash zsh ksh
+shells=posix
 platforms=any
 exports=greet
-updates=
 load=modules/greeting.sh

package/examples/profile-project/{shell/module.d → module.d}/profile_main.meta

@@ -6,4 +6,3 @@ optional=
 shells=bash zsh ksh
 platforms=any
 exports=
-updates=

package/examples/profile-project/{shell/modules → modules}/greeting.sh

@@ -1,4 +1,4 @@
-# A plain POSIX module. `shells=sh` covers every POSIX shell: sh, bash,
+# A plain POSIX module. `shells=posix` covers every POSIX shell: sh, bash,
 # zsh, ksh, and dash.
 greet() {
   printf '%s\n' "hello from the valise profile project"

package/examples/profile-project/valise.conf

@@ -0,0 +1,4 @@
+# valise project configuration. `valise build` and `valise apply` read these
+# defaults; --bundle and --variant override them.
+bundle=default
+variant=default

package/examples/profile-project/variants.tsv

@@ -0,0 +1,3 @@
+variant	description	excluded
+default	Every module in the project	
+workstation-lean	No provider layer	contrib_demo_greeting@layers/demo/module.d

package/examples/shared/README.md

@@ -9,41 +9,20 @@ be pinned to a reviewed commit in the consuming project.
 
 | Module | Version | Export | Behavior |
 |---|---|---|---|
-| `contrib_shared_paths` | 1.0.0 | `contrib_shared_paths_setup` | Adds `$HOME/.local/bin` and `$HOME/.go/bin` using `contrib_path_prepend`. |
+| `contrib_shared_paths` | 1.0.0 | `contrib_shared_paths_setup` | Adds `$HOME/.local/bin` and `$HOME/.go/bin` using `valise_path_prepend`. |
 | `contrib_shared_umask` | 1.0.0 | `contrib_shared_umask_secure` | Sets `umask 077` when explicitly called. |
 
 The modules and their metadata are under `modules/shared/` and
 `module.d/`. Layer-only modules use the `contrib_` prefix. The paths module
-requires the engine's `contrib_path` module; this exercises dependency
-resolution from a layer into the primary module root.
-
-## Use in the sample profile
-
-From the repository root, build the sample release and install it from the
-e2e directory. Installation adds an integration hook under `HOME`; use a
-temporary home to avoid changing your own shell startup files (see the top
-level README).
-
-```sh
-sh examples/e2e/build-manifest.sh
-cd examples/e2e/build/release
-valise install
-valise release verify
-```
-
-Then load the shared modules from a POSIX shell. The active release path
-below uses the default XDG locations; if you set `XDG_CONFIG_HOME`, use that
-instead.
-
-```sh
-_active=$(cd "$HOME/.config/valise/active" && pwd -P)
-VALISE_MODULE_ROOT="$_active" \
-VALISE_MODULE_PATH="$_active/layer/shared" \
-VALISE_MODULES='e2e_layer_probe contrib_shared_umask' \
-VALISE_MODE=strict \
-. "$_active/entrypoints/profile.sh"
-```
-
-For a Fish example and details about provider pinning, see
-[the end-to-end walkthrough](../e2e/README.md) and the
-[module ABI](../../docs/module-abi.md).
+requires the engine's `valise_path` module; this exercises dependency
+resolution from a layer into the engine's modules.
+
+## Use in a project
+
+A consuming project vendors this directory as `layers/<provider>/`, for
+example `layers/shared/`, and names the modules it wants in `bundles.tsv` or
+in the `requires=` and `optional=` fields of its own modules. `valise build`
+then copies only the provider modules some plan loads into the release under
+`layers/shared/`. [The end-to-end walkthrough](../e2e/README.md) shows the
+steps against the sample project; see the [module ABI](../../docs/module-abi.md)
+for dependency resolution across a project and its layers.

package/examples/shared/module.d/contrib_shared_paths.meta

@@ -1,10 +1,9 @@
 name=contrib_shared_paths
-requires=contrib_path
+requires=valise_path
 optional=
-shells=sh bash zsh ksh
+shells=posix bash zsh ksh
 platforms=any
 side_effect=path-env
 exports=contrib_shared_paths_setup
-updates=
 version=1.0.0
 load=modules/shared/contrib_shared_paths.sh

package/examples/shared/module.d/contrib_shared_umask.meta

@@ -1,10 +1,9 @@
 name=contrib_shared_umask
 requires=
 optional=
-shells=sh bash zsh ksh
+shells=posix bash zsh ksh
 platforms=any
 side_effect=work-only
 exports=contrib_shared_umask_secure
-updates=
 version=1.0.0
 load=modules/shared/contrib_shared_umask.sh

package/examples/shared/modules/shared/contrib_shared_paths.sh

@@ -4,7 +4,7 @@
 # contrib_shared_paths: team-standard development directories on PATH.
 #
 # Puts $HOME/.local/bin and $HOME/.go/bin on PATH through
-# contrib_path_prepend (provided by the engine's contrib_path module,
+# valise_path_prepend (provided by the engine's valise_path module,
 # which this module requires), keeping PATH duplicate-free. When HOME is
 # unset, nothing is added. Prints nothing and succeeds in every case.
 
@@ -12,5 +12,5 @@ contrib_shared_paths_setup() {
   if [ -z "${HOME-}" ]; then
     return 0
   fi
-  contrib_path_prepend "$HOME/.local/bin" "$HOME/.go/bin"
+  valise_path_prepend "$HOME/.local/bin" "$HOME/.go/bin"
 }