lib.modules.wrapper: move "$@" into args at order 1001

Instead of hardcoding "$@" in the wrapper template, inject it into the
args list at order 1001 (just after the default flag order of 1000).
This makes passthrough argument positioning controllable via the
ordering system — flags with order > 1001 appear after "$@".

The wrapper module passes a custom wrapper function to wrapPackage
that omits the hardcoded "$@" since it's now part of args.

Add flags-order check verifying: --early (500) < --greeting (1000) <
"$@" (1001) < --late (1500).

Author: Lassulus

checks/flags-order.nix

@@ -0,0 +1,70 @@
+{
+  pkgs,
+  self,
+}:
+
+let
+  helloModule = self.lib.wrapModule (
+    { config, ... }:
+    {
+      config.package = config.pkgs.hello;
+      config.flags = {
+        # default order 1000: before "$@" (which is 1001)
+        "--greeting" = "hello";
+        # explicit early order: should come first
+        "--early" = {
+          value = true;
+          order = 500;
+        };
+        # explicit late order: should come after "$@"
+        "--late" = {
+          value = true;
+          order = 1500;
+        };
+      };
+    }
+  );
+
+  wrappedPackage = (helloModule.apply { inherit pkgs; }).wrapper;
+
+in
+pkgs.runCommand "flags-order-test" { } ''
+  echo "Testing flag ordering with priorities..."
+
+  wrapperScript="${wrappedPackage}/bin/hello"
+  if [ ! -f "$wrapperScript" ]; then
+    echo "FAIL: Wrapper script not found"
+    exit 1
+  fi
+
+  cat "$wrapperScript"
+
+  # Flatten the script to a single line for position comparison
+  flat=$(cat "$wrapperScript" | tr -d '\n' | tr -s ' ')
+
+  # --early (500) should come before --greeting (1000)
+  # --greeting (1000) should come before "$@" (1001)
+  # "$@" (1001) should come before --late (1500)
+  earlyPos=$(echo "$flat" | grep -bo -- '--early' | head -1 | cut -d: -f1)
+  greetingPos=$(echo "$flat" | grep -bo -- '--greeting' | head -1 | cut -d: -f1)
+  passthruPos=$(echo "$flat" | grep -bo '"\$@"' | head -1 | cut -d: -f1)
+  latePos=$(echo "$flat" | grep -bo -- '--late' | head -1 | cut -d: -f1)
+
+  echo "Positions: early=$earlyPos greeting=$greetingPos passthru=$passthruPos late=$latePos"
+
+  if [ "$earlyPos" -ge "$greetingPos" ]; then
+    echo "FAIL: --early should come before --greeting"
+    exit 1
+  fi
+  if [ "$greetingPos" -ge "$passthruPos" ]; then
+    echo "FAIL: --greeting should come before \"\$@\""
+    exit 1
+  fi
+  if [ "$passthruPos" -ge "$latePos" ]; then
+    echo "FAIL: \"\$@\" should come before --late"
+    exit 1
+  fi
+
+  echo "SUCCESS: Flag ordering test passed"
+  touch $out
+''

lib/modules/wrapper.nix

@@ -31,6 +31,13 @@
       Shell script that runs after patchPhase to modify the wrapper package files.
     '';
   };
+
+  # Inject "$@" (passthrough of user arguments) into args at order 1001,
+  # so it comes just after the default flag order (1000).
+  # Use mkOrder on args to position it; other flags can use order > 1001
+  # to appear after "$@" if needed.
+  config.args = lib.mkOrder 1001 [ "$@" ];
+
   options.outputs.wrapper = lib.mkOption {
     type = lib.types.package;
     readOnly = true;
@@ -58,6 +65,22 @@
         configuration = config;
       }
       // config.passthru;
+      # Custom wrapper function: "$@" is already in args, so don't add it again
+      wrapper =
+        {
+          exePath,
+          flagsString,
+          envString,
+          preHook,
+          postHook,
+          ...
+        }:
+        ''
+          ${envString}
+          ${preHook}
+          ${lib.optionalString (postHook == "") "exec"} ${exePath}${flagsString}
+          ${postHook}
+        '';
     };
   };
   options.wrapper = lib.mkOption {