valise-sh 0.1.0 → 0.2.0

package/examples/e2e/build-manifest.sh

@@ -3,63 +3,29 @@
 # Copyright (c) 2026 Joseph Cumines
 # SPDX-License-Identifier: MIT
 
-# build-manifest.sh: vendor engine files into the e2e release tree and
+# build-manifest.sh: vendor engine files into an e2e release tree and
 # generate a profile-release.manifest with correct sizes and SHA-256 digests.
 #
-# Usage: run from any directory. The script resolves paths relative to itself.
-# Output: shell/install/profile-release.manifest (overwritten each run).
+# Usage: sh build-manifest.sh [output-dir]
+# Default output-dir: examples/e2e/build/release
 
 set -eu
 
 _script_dir=$(cd "$(dirname "$0")" && pwd -P)
 _repo_root=$(cd "$_script_dir/../.." && pwd -P)
 _e2e_root="$_script_dir"
+_out_dir="${1:-$_e2e_root/build/release}"
+_valise="$_repo_root/bin/valise"
 
-# --- Locate SHA-256 utility ---
-# Match bin/valise fallback chain: sha256sum, shasum -a 256, sha256 (BSD).
-_sha_cmd=""
-if command -v sha256sum >/dev/null 2>&1; then
-  _sha_cmd="sha256sum"
-elif command -v shasum >/dev/null 2>&1; then
-  _sha_cmd="shasum"
-elif command -v sha256 >/dev/null 2>&1; then
-  _sha_cmd="sha256"
-else
-  printf 'ERROR: no SHA-256 utility found (need sha256sum, shasum, or sha256)\n' >&2
-  exit 1
-fi
-
-file_sha256() {
-  _sha_output=""
-  if [ "$_sha_cmd" = "sha256sum" ]; then
-    _sha_output=$(sha256sum "$1")
-  elif [ "$_sha_cmd" = "shasum" ]; then
-    _sha_output=$(shasum -a 256 "$1")
-  else
-    _sha_output=$(sha256 "$1")
-  fi
-  # BSD sha256 prints "SHA256 (filename) = digest"; sha256sum/shasum print
-  # "digest  filename". Gate the BSD strip behind the SHA256 ( prefix to
-  # avoid corrupting output when the filename contains "= ".
-  case "$_sha_output" in
-    "SHA256 ("*) _sha_output=${_sha_output##* = } ;;
-  esac
-  _sha_output=${_sha_output%% *}
-  _sha_output=${_sha_output%%$(printf '\t')*}
-  printf '%s\n' "$_sha_output"
-}
-
-file_bytes() {
-  wc -c < "$1" | tr -d '[:space:]'
-}
+[ -x "$_valise" ] || { printf 'ERROR: valise CLI not found at %s\n' "$_valise" >&2; exit 1; }
 
-# --- Vendor engine files ---
-# These are copies of the engine source that form the release payload.
-# They are NOT committed (see .gitignore); this script regenerates them.
+# Prepare clean output directory
+rm -rf "$_out_dir"
+mkdir -p "$_out_dir"
 
 _vendor_copy() {
   _src="$_repo_root/$1"
-  _dst="$_e2e_root/$1"
+  _dst="$_out_dir/$1"
   _dst_dir=$(dirname "$_dst")
   [ -f "$_src" ] || { printf 'ERROR: engine source missing: %s\n' "$_src" >&2; exit 1; }
   mkdir -p "$_dst_dir"
@@ -67,7 +33,7 @@ _vendor_copy() {
   chmod 0644 "$_dst"
 }
 
-printf 'Vendoring engine files from %s...\n' "$_repo_root"
+printf 'Vendoring engine files into %s...\n' "$_out_dir"
 
 # Core libraries
 _vendor_copy lib/metadata.sh
@@ -79,8 +45,7 @@ _vendor_copy lib/compiler.awk
 _vendor_copy lib/fish/loader.fish
 _vendor_copy lib/fish/metadata.fish
 
-# Generic Fish entrypoint adapter (sourced by the generated Fish
-# integration after it authenticates the active release)
+# Generic Fish entrypoint adapter
 _vendor_copy entrypoints/fish/profile.fish
 
 # Entrypoint
@@ -115,14 +80,37 @@ if [ "$_engine_contrib_count" -eq 0 ]; then
   exit 1
 fi
 
-# --- Vendor shared layer (cross-repo composition) ---
-# The provider tree at examples/shared simulates a version-pinned external
-# repository. Its files are copied under layer/shared/ so the release keeps
-# provider bytes separate from consumer bytes while one manifest covers the
-# whole closure. layer-pin.txt records the pinned provider revision.
+# --- Native e2e example modules ---
+_e2e_meta_count=0
+mkdir -p "$_out_dir/module.d"
+for _meta in "$_e2e_root"/module.d/e2e_*.meta; do
+  [ -f "$_meta" ] || continue
+  cp "$_meta" "$_out_dir/module.d/"
+  chmod 0644 "$_out_dir/module.d/$(basename "$_meta")"
+  _e2e_meta_count=$((_e2e_meta_count + 1))
+done
+
+_e2e_body_count=0
+mkdir -p "$_out_dir/modules/e2e"
+for _body in "$_e2e_root"/modules/e2e/*.sh "$_e2e_root"/modules/e2e/*.fish; do
+  [ -f "$_body" ] || continue
+  cp "$_body" "$_out_dir/modules/e2e/"
+  chmod 0644 "$_out_dir/modules/e2e/$(basename "$_body")"
+  _e2e_body_count=$((_e2e_body_count + 1))
+done
 
+if [ "$_e2e_meta_count" -eq 0 ]; then
+  printf 'ERROR: no e2e module metadata found in %s\n' "$_e2e_root/module.d" >&2
+  exit 1
+fi
+if [ "$_e2e_body_count" -eq 0 ]; then
+  printf 'ERROR: no e2e module bodies found in %s\n' "$_e2e_root/modules/e2e" >&2
+  exit 1
+fi
+
+# --- Vendor shared layer (cross-repo composition) ---
 _shared_src="$_repo_root/examples/shared"
-_shared_dst="$_e2e_root/layer/shared"
+_shared_dst="$_out_dir/layer/shared"
 [ -d "$_shared_src/module.d" ] || { printf 'ERROR: shared provider missing: %s\n' "$_shared_src" >&2; exit 1; }
 mkdir -p "$_shared_dst/module.d" "$_shared_dst/modules"
 for _shared_meta in "$_shared_src"/module.d/*.meta; do
@@ -142,109 +130,9 @@ done
 _shared_rev=$(cd "$_shared_src" && git rev-parse HEAD 2>/dev/null || printf 'unknown')
 printf 'provider=examples/shared\nrevision=%s\n' "$_shared_rev" > "$_shared_dst/layer-pin.txt"
 chmod 0644 "$_shared_dst/layer-pin.txt"
-printf 'Vendored shared layer from %s (revision %s)\n' "$_shared_src" "$_shared_rev"
-
-# --- Generate manifest ---
-_manifest_dir="$_e2e_root/shell/install"
-mkdir -p "$_manifest_dir"
-_manifest="$_manifest_dir/profile-release.manifest"
-
-printf 'Generating manifest...\n'
-
-# Collect all files to include in the manifest.
-# Engine files (vendored) + e2e example modules (native).
-_file_list=""
-
-# Engine files
-for _f in \
-  lib/metadata.sh lib/loader.sh lib/capabilities.sh lib/compiler.awk \
-  lib/fish/loader.fish lib/fish/metadata.fish \
-  entrypoints/profile.sh entrypoints/fish/profile.fish \
-  module.d/platform_posix.meta module.d/platform_macos.meta \
-  module.d/platform_linux.meta module.d/platform_bsd.meta \
-  modules/platform/posix.sh \
-  modules/platform/macos/capabilities.sh \
-  modules/platform/linux/capabilities.sh \
-  modules/platform/bsd/capabilities.sh \
-; do
-  _file_list="$_file_list $_f"
-done
 
-# E2e example module metadata
-_e2e_meta_count=0
-
-# Shareable engine catalog (vendored above)
-for _f in "$_e2e_root"/module.d/contrib_*.meta "$_e2e_root"/modules/system/contrib_*.sh; do
-  [ -f "$_f" ] || continue
-  _rel=${_f#"$_e2e_root"/}
-  _file_list="$_file_list $_rel"
-done
-for _f in "$_e2e_root"/module.d/e2e_*.meta; do
-  [ -f "$_f" ] || continue
-  _rel=${_f#"$_e2e_root"/}
-  _file_list="$_file_list $_rel"
-  _e2e_meta_count=$((_e2e_meta_count + 1))
-done
-
-# E2e example module bodies (POSIX)
-_e2e_sh_count=0
-for _f in "$_e2e_root"/modules/e2e/*.sh; do
-  [ -f "$_f" ] || continue
-  _rel=${_f#"$_e2e_root"/}
-  _file_list="$_file_list $_rel"
-  _e2e_sh_count=$((_e2e_sh_count + 1))
-done
-
-# E2e example module bodies (Fish)
-_e2e_fish_count=0
-for _f in "$_e2e_root"/modules/e2e/*.fish; do
-  [ -f "$_f" ] || continue
-  _rel=${_f#"$_e2e_root"/}
-  _file_list="$_file_list $_rel"
-  _e2e_fish_count=$((_e2e_fish_count + 1))
-done
-
-# Shared layer files (cross-repo composition): provider metadata, bodies,
-# and the pin file recording the vendored revision.
-_shared_count=0
-for _f in "$_e2e_root"/layer/shared/module.d/*.meta "$_e2e_root"/layer/shared/modules/*/*.sh "$_e2e_root"/layer/shared/layer-pin.txt; do
-  [ -f "$_f" ] || continue
-  _rel=${_f#"$_e2e_root"/}
-  _file_list="$_file_list $_rel"
-  _shared_count=$((_shared_count + 1))
-done
-
-# Fail closed when a glob collected nothing: POSIX sh leaves a non-matching
-# glob unexpanded, so without this an empty or missing e2e directory would
-# build a manifest silently missing e2e files.
-if [ "$_e2e_meta_count" -eq 0 ]; then
-  printf 'ERROR: no e2e module metadata found in %s\n' "$_e2e_root/module.d" >&2
-  exit 1
-fi
-if [ "$((_e2e_sh_count + _e2e_fish_count))" -eq 0 ]; then
-  printf 'ERROR: no e2e module bodies found in %s\n' "$_e2e_root/modules/e2e" >&2
-  exit 1
-fi
-if [ "$_shared_count" -eq 0 ]; then
-  printf 'ERROR: no shared layer files found in %s\n' "$_e2e_root/layer/shared" >&2
-  exit 1
-fi
-
-# Write manifest header
-printf 'shell-profile-release-manifest-v1\n' > "$_manifest"
-printf 'destination\tsource\tsource_mode\tinstall_mode\tbytes\tsha256\n' >> "$_manifest"
-
-# Write data rows
-for _rel in $_file_list; do
-  _full="$_e2e_root/$_rel"
-  [ -f "$_full" ] || { printf 'ERROR: file missing: %s\n' "$_full" >&2; exit 1; }
-  [ ! -L "$_full" ] || { printf 'ERROR: symlink in release: %s\n' "$_full" >&2; exit 1; }
-  _bytes=$(file_bytes "$_full")
-  _sha=$(file_sha256 "$_full")
-  # destination == source for this flat release layout
-  # All release files are 0644 source -> 0444 installed (immutable)
-  printf '%s\t%s\t0644\t0444\t%s\t%s\n' "$_rel" "$_rel" "$_bytes" "$_sha" >> "$_manifest"
-done
+# Normalise file modes before manifesting
+find "$_out_dir" -type f -exec chmod 0644 {} +
 
-_file_count=$(awk 'NR > 2 && NF > 0 { count++ } END { print count+0 }' "$_manifest")
-printf 'Manifest written: %s (%d files)\n' "$_manifest" "$_file_count"
+# --- Generate manifest using valise CLI ---
+"$_valise" make-manifest "$_out_dir"

package/examples/profile-project/README.md

@@ -0,0 +1,181 @@
+# profile-project: a complete 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.
+
+## 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
+```
+
+`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`.
+
+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.
+
+## Build it
+
+From this directory:
+
+```sh
+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
+```
+
+The plans are plain POSIX shell. You can read one to see exactly what will
+run.
+
+## 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:
+
+```sh
+bash -l
+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:
+
+```sh
+valise status
+```
+
+```
+project: /path/to/profile-project
+variant: default
+bundle: 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
+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.
+
+## Try a variant
+
+The project ships two variants. `default` loads everything;
+`workstation-lean` leaves out the provider layer:
+
+```sh
+valise explain-variant workstation-lean
+```
+
+To use the lean variant, set it in `shell/release/project.conf`:
+
+```sh
+variant=workstation-lean
+```
+
+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
+```
+
+## Try a bundle
+
+`shell/release/bundle-roots` says which roots load for each shell:
+
+```
+default	bash	profile_main contrib_demo_greeting@shell/layers/demo/module.d
+```
+
+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.
+
+```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.
+
+```sh
+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
+  named and owned.

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

@@ -0,0 +1,10 @@
+name=contrib_demo_greeting
+version=1.0.0
+side_effect=read-only
+requires=
+optional=
+shells=sh bash zsh ksh
+platforms=any
+exports=contrib_demo_greeting_ready
+updates=
+load=modules/shared/contrib_demo_greeting.sh

package/examples/profile-project/shell/layers/demo/modules/shared/contrib_demo_greeting.sh

@@ -0,0 +1,4 @@
+# A provider layer module. Layer-only modules must carry the `contrib_`
+# prefix; `valise layer-lint demo` enforces that, along with the version,
+# the load target, the file modes, and the dependency closure.
+contrib_demo_greeting_ready() { :; }

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

@@ -0,0 +1,10 @@
+name=greeting
+version=1.0.0
+side_effect=read-only
+requires=
+optional=
+shells=sh bash zsh ksh
+platforms=any
+exports=greet
+updates=
+load=modules/greeting.sh

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

@@ -0,0 +1,9 @@
+name=profile_main
+version=1.0.0
+side_effect=read-only
+requires=greeting
+optional=
+shells=bash zsh ksh
+platforms=any
+exports=
+updates=

package/examples/profile-project/shell/modules/greeting.sh

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

package/examples/profile-project/shell/release/bundle-roots

@@ -0,0 +1,9 @@
+# bundle	shell	roots
+# The first row is a header, not a bundle definition. Each row names a
+# bundle, a shell, and the space-separated root modules for that shell.
+#
+# A layer module is named by its qualified identity so the source directory
+# is unambiguous: name@shell/layers/<provider>/module.d
+default	bash	profile_main contrib_demo_greeting@shell/layers/demo/module.d
+default	zsh	profile_main contrib_demo_greeting@shell/layers/demo/module.d
+default	ksh	profile_main contrib_demo_greeting@shell/layers/demo/module.d

package/examples/profile-project/shell/release/install-variants

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

package/examples/profile-project/shell/release/module-registry.tsv

@@ -0,0 +1,4 @@
+name	version	side_effect	requires	optional	shells	platforms	exports	load	updates	source
+greeting	1.0.0	read-only			sh bash zsh ksh	any	greet	modules/greeting.sh		shell/module.d
+profile_main	1.0.0	read-only	greeting		bash zsh ksh	any				shell/module.d
+contrib_demo_greeting	1.0.0	read-only			sh bash zsh ksh	any	contrib_demo_greeting_ready	modules/shared/contrib_demo_greeting.sh		shell/layers/demo/module.d

package/examples/profile-project/shell/release/project.conf

@@ -0,0 +1,3 @@
+# Project defaults. `valise build` and `valise apply` read these.
+variant=default
+bundle=default

package/examples/shared/README.md

@@ -26,9 +26,9 @@ level README).
 
 ```sh
 sh examples/e2e/build-manifest.sh
-cd examples/e2e
+cd examples/e2e/build/release
 valise install
-valise verify-active
+valise release verify
 ```
 
 Then load the shared modules from a POSIX shell. The active release path