lib.modules.env: simplify API and move helpers into wlib.env

Response to code review — the previous iteration was over-engineered:
too many options, unclear names, helpers scattered across wlib.

Changes:

- Namespace: wlib.envRef / wlib.renderEnvString / normaliseEnvEntry
  collapse into wlib.env.{ref, render}. normaliseEnvEntry is now
  internal.

- Rename fallback -> ifUnset. "fallback" was vague; "ifUnset" says
  what it does: only apply when the caller's env doesn't already
  have it set. Now uses ${VAR:-} semantics so empty also counts as
  unset.

- Drop prefix / suffix entirely. They were makeWrapper jargon that
  wasn't self-evident. The same thing is now expressed via a list
  value and wlib.env.ref:

      env.PATH.value = [ "/opt/bin" (wlib.env.ref "PATH") ];

- Collapse value + values into a single polymorphic `value` option:
  a plain string for the literal case, or a list of parts (joined
  with separator) for everything else. One concept, one name.

The module submodule is now just four options: value, separator,
ifUnset, unset. List values still merge by concatenation under
apply, so composition works the same.

lib/modules/env.nix shrinks from 203 to 106 lines; the renderer in
lib/default.nix drops from ~180 to ~120. Tests are consolidated
from four files to three.

https://claude.ai/code/session_01UiEmmBrtkNEstoRemZpnp7

Author: claude

CHANGELOG.md

@@ -15,15 +15,12 @@
   were explicitly passing `flagSeparator = " "` to get separate args,
   remove it (or change to `null`).
 
-- `env` option type changed from `attrsOf str` to a richer submodule
-  (see "Added" below). Plain-string and path values keep coercing to
-  the old behaviour, so `env.FOO = "bar"` is unchanged. Passthru
-  `wrapPackage` callers now get the structured form on
-  `passthru.env`; read `passthru.env.<name>.value` instead of
-  `passthru.env.<name>` if you need the literal. The systemd
-  integration reads from `config.outputs.staticEnv` instead of
-  `config.env` and silently drops entries that can't be expressed as
-  a static literal (prefix/suffix, values, fallback, unset).
+- `env` option type changed from `attrsOf str` to a small submodule
+  with `value` / `separator` / `ifUnset` / `unset`. Plain strings
+  and `null` keep working via coercion (`env.FOO = "bar"` and
+  `env.FOO = null` are unchanged). The systemd integration reads
+  from `config.outputs.staticEnv` instead of `config.env` and drops
+  any entries it can't express as a literal assignment.
 
 ### Added
 
@@ -32,30 +29,24 @@
 - `lib/modules/flags.nix`: flags module with per-flag ordering via
   `{ value, order }` submodules. Default order is 1000. Reading
   `config.flags` returns clean values (order is transparent).
-- `lib/modules/env.nix`: env module with richer per-variable options
-  for safe composition, modelled on `makeWrapper`'s `--prefix` /
-  `--suffix` but usable through the NixOS module system.
-  - `env.<VAR>.value`: literal string (same as `env.<VAR> = "..."`).
-  - `env.<VAR>.prefix` / `.suffix`: parts to splice around the
-    existing value of the variable. Empty or unset existing values
-    drop out cleanly with no stray separators.
-  - `env.<VAR>.values`: explicit list of parts to join, with
-    `wlib.envRef "OTHER"` placeholders for runtime env references.
-  - `env.<VAR>.separator`: join separator (default `:`).
-  - `env.<VAR>.fallback = true`: only set the variable when it is
-    not already set in the caller's environment (uses `${VAR+set}`
-    semantics).
+- `lib/modules/env.nix`: env module with per-variable options for
+  safe composition through the NixOS module system.
+  - `env.<VAR>.value`: string for a simple literal, or a list of
+    parts to join with `separator`. List parts can be plain strings
+    or `wlib.env.ref "NAME"` runtime references. Empty/unset refs
+    drop out cleanly, so no dangling separators.
+  - `env.<VAR>.separator`: join separator for a list `value`
+    (default `:`).
+  - `env.<VAR>.ifUnset = true`: only apply when the caller's
+    environment doesn't already have the variable set.
   - `env.<VAR>.unset = true`: emit `unset VAR` instead of an
     assignment. `env.VAR = null` is sugar for this.
-  - List-valued entries (`values`, `prefix`, `suffix`) merge by
-    concatenation when composed via `apply`, so multiple modules can
-    stack contributions onto the same variable without fighting.
-- `wlib.envRef :: name -> envRef`: marker used inside `values` /
-  `prefix` / `suffix` lists to reference another env variable at
-  runtime. Dropped cleanly if the referenced variable is unset.
-- `wlib.renderEnvString :: env -> str`: pure helper that renders an
-  `env` attrset into the shell snippet the wrapper uses. Exposed
-  for testing and downstream composition.
+  - List `value`s merge by concatenation when composed via `apply`,
+    so modules stack contributions without fighting over a string.
+- `wlib.env.ref NAME`: marker for a runtime env-variable reference
+  inside `env.<VAR>.value` lists.
+- `wlib.env.render`: render an `env` attrset into a shell snippet.
+  Exposed for tests and downstream composition.
 - `outputs.staticEnv`: subset of `env` that resolves to a plain
   literal string, used by the systemd integration.
 - `wrapper.nix` injects `"$@"` into args at order 1001, controllable

README.md

@@ -93,61 +93,42 @@ wrappers.lib.wrapPackage {
 
 ### Environment Variables
 
-Environment variables can be set in three forms, with the richer form
-available both via `wrapPackage` and through the `env.<NAME>` option
-of wrapper modules.
+Each `env.<NAME>` entry is either a plain string, `null` (to unset),
+or a small submodule:
 
 ```nix
 {
   env = {
-    # 1. Plain literal string (same as before):
+    # Literal:
     FOO = "bar";
 
-    # 2. Null to explicitly unset a variable inherited from the
-    #    caller's environment:
+    # Unset a variable inherited from the caller:
     NOISY_OLD_VAR = null;
 
-    # 3. Structured form with the following fields:
-    #
-    #    - value: literal string
-    #    - prefix / suffix: parts to splice around the existing value
-    #      of the variable (like `makeWrapper --prefix/--suffix`).
-    #      Empty or unset existing values drop out cleanly.
-    #    - values: explicit list of parts, joined with `separator`.
-    #      Use `wlib.envRef "OTHER"` to reference another variable
-    #      at runtime.
-    #    - separator: join separator (default ":")
-    #    - fallback: only set if the variable isn't already set
-    #    - unset: emit `unset VAR` (takes precedence)
-
-    # Prepend to PATH, keeping the caller's existing entries:
-    PATH.prefix = [ "/opt/bin" ];
-
-    # Append to XDG_DATA_DIRS:
-    XDG_DATA_DIRS.suffix = [ "/opt/share" ];
-
-    # Build LD_LIBRARY_PATH with the existing value somewhere in the
-    # middle, not just at the edges:
-    LD_LIBRARY_PATH.values = [
-      "/opt/lib"
-      (wrappers.lib.envRef "LD_LIBRARY_PATH")
-      "/other/lib"
-    ];
-
-    # Only set EDITOR if the user hasn't picked one already:
-    EDITOR = {
-      value = "vim";
-      fallback = true;
-    };
+    # Prepend to PATH using a list and `wlib.env.ref`. The ref
+    # expands to the caller's existing PATH at runtime; if it's
+    # unset or empty, the ref drops out and no stray separators
+    # are left behind.
+    PATH.value = [ "/opt/bin" (wrappers.lib.env.ref "PATH") ];
+
+    # Only set EDITOR if the caller hasn't already picked one.
+    EDITOR = { value = "vim"; ifUnset = true; };
   };
 }
 ```
 
-`prefix`, `suffix` and `values` are lists, so they compose via module
-merging: multiple modules (or multiple `apply` calls) contributing to
-the same variable stack their contributions instead of fighting over
-a single string. Empty parts are filtered at runtime, so unset env
-references never leave behind dangling separators.
+Submodule options:
+- `value`: literal string *or* a list of parts joined with
+  `separator`. List parts can be plain strings or
+  `wlib.env.ref "NAME"` runtime references.
+- `separator`: join separator for list values (default `:`).
+- `ifUnset`: only apply when the caller's environment doesn't
+  already have the variable set.
+- `unset`: unset the variable (takes precedence over `value`).
+
+List `value`s merge by concatenation when composed via `apply`, so
+multiple modules stack contributions onto the same variable without
+fighting over a single string.
 
 ### Creating Custom Wrapper Modules
 

checks/env-fallback-unset.nix

@@ -0,0 +1,49 @@
+{
+  pkgs,
+  self,
+}:
+
+# `ifUnset` (only set if caller hasn't) and explicit unset.
+let
+  wlib = self.lib;
+
+  showEnv = pkgs.writeShellScriptBin "show-env" ''
+    printf 'EDITOR=%s\n' "''${EDITOR-<unset>}"
+    printf 'BLOAT=%s\n' "''${BLOAT-<unset>}"
+  '';
+
+  wrapped =
+    (wlib.wrapModule (
+      { config, ... }:
+      {
+        config.package = showEnv;
+        config.env.EDITOR = {
+          value = "vim";
+          ifUnset = true;
+        };
+        # `null` sugar for unset.
+        config.env.BLOAT = null;
+      }
+    ).apply { pkgs = pkgs; }).wrapper;
+in
+pkgs.runCommand "env-if-unset-test" { } ''
+  set -eu
+  script="${wrapped}/bin/show-env"
+
+  # ifUnset applied when EDITOR is unset.
+  r=$(unset EDITOR && "$script" | grep '^EDITOR=' | cut -d= -f2-)
+  [ "$r" = "vim" ] || { echo "FAIL: ifUnset unset: '$r'"; cat "$script"; exit 1; }
+  echo "PASS: ifUnset applies when unset"
+
+  # ifUnset yields to an existing value.
+  r=$(EDITOR=nano "$script" | grep '^EDITOR=' | cut -d= -f2-)
+  [ "$r" = "nano" ] || { echo "FAIL: ifUnset overrode existing: '$r'"; exit 1; }
+  echo "PASS: ifUnset preserves existing"
+
+  # Explicit unset beats caller env.
+  r=$(BLOAT=garbage "$script" | grep '^BLOAT=' | cut -d= -f2-)
+  [ "$r" = "<unset>" ] || { echo "FAIL: unset: '$r'"; cat "$script"; exit 1; }
+  echo "PASS: unset overrides caller env"
+
+  touch $out
+''

checks/env-if-unset.nix

@@ -0,0 +1,71 @@
+{
+  pkgs,
+  self,
+}:
+
+# End-to-end test for list-valued `env.<VAR>.value` with
+# `wlib.env.ref` to prepend to an existing variable. Also exercises
+# composition via `apply`: lists merge by concatenation.
+let
+  wlib = self.lib;
+
+  showVar = pkgs.writeShellScriptBin "show-var" ''
+    printf 'TEST_VAR=%s\n' "''${TEST_VAR-<unset>}"
+  '';
+
+  base = wlib.wrapModule (
+    { config, ... }:
+    {
+      config.package = showVar;
+      config.env.TEST_VAR.value = [
+        "/base-front"
+        (wlib.env.ref "TEST_VAR")
+        "/base-back"
+      ];
+    }
+  );
+
+  extended = (base.apply { pkgs = pkgs; }).apply {
+    # List merging via the module system: apply concatenates.
+    env.TEST_VAR.value = [ "/extra" ];
+  };
+
+  wrapped = extended.wrapper;
+in
+pkgs.runCommand "env-list-value-test" { } ''
+  set -eu
+  script="${wrapped}/bin/show-var"
+
+  # Case 1: TEST_VAR unset — envRef drops out, no stray colons.
+  r1=$(unset TEST_VAR && "$script" | grep '^TEST_VAR=' | cut -d= -f2-)
+  case "$r1" in
+    *::*)
+      echo "FAIL: unset case has stray separator: '$r1'"
+      cat "$script"; exit 1 ;;
+    :*|*:)
+      echo "FAIL: unset case has leading/trailing colon: '$r1'" ; exit 1 ;;
+  esac
+  case "$r1" in
+    */base-front*) ;;
+    *) echo "FAIL: base-front missing: '$r1'"; exit 1 ;;
+  esac
+  case "$r1" in
+    */base-back*) ;;
+    *) echo "FAIL: base-back missing: '$r1'"; exit 1 ;;
+  esac
+  case "$r1" in
+    */extra*) ;;
+    *) echo "FAIL: extra missing (list merge via apply): '$r1'"; exit 1 ;;
+  esac
+  echo "PASS: unset case: $r1"
+
+  # Case 2: TEST_VAR=/mid — envRef expands in place.
+  r2=$(TEST_VAR=/mid "$script" | grep '^TEST_VAR=' | cut -d= -f2-)
+  case "$r2" in
+    */mid*) ;;
+    *) echo "FAIL: existing value lost: '$r2'"; exit 1 ;;
+  esac
+  echo "PASS: set case: $r2"
+
+  touch $out
+''