{
  lib,
}:

/*
  This is a set of tools to manipulate update scripts as recognized by update.nix.
  It is still very experimental with **instability** almost guaranteed so any use
  outside Nixpkgs is discouraged.

  update.nix currently accepts the following type:

  type UpdateScript
    // Simple path to script to execute script
    = FilePath
    // Path to execute plus arguments to pass it
    | [ (FilePath | String) ]
    // Advanced attribue set (experimental)
    | {
      // Script to execute (same as basic update script above)
      command : (FilePath | [ (FilePath | String) ])
      // Features that the script supports
      // - commit: (experimental) returns commit message in stdout
      // - silent: (experimental) returns no stdout
      supportedFeatures : ?[ ("commit" | "silent") ]
      // Override attribute path detected by update.nix
      attrPath : ?String
    }
*/

let
  # type ShellArg = String | { __rawShell : String }

  /*
    Quotes all arguments to be safely passed to the Bourne shell.

    escapeShellArgs' : [ShellArg] -> String
  */
  escapeShellArgs' = lib.concatMapStringsSep " " (
    arg: if arg ? __rawShell then arg.__rawShell else lib.escapeShellArg arg
  );

  /*
    processArg : { maxArgIndex : Int, args : [ShellArg], paths : [FilePath] } → (String|FilePath) → { maxArgIndex : Int, args : [ShellArg], paths : [FilePath] }
    Helper reducer function for building a command arguments where file paths are replaced with argv[x] reference.
  */
  processArg =
    {
      maxArgIndex,
      args,
      paths,
    }:
    arg:
    if builtins.isPath arg then
      {
        args = args ++ [ { __rawShell = "\"\$${builtins.toString maxArgIndex}\""; } ];
        maxArgIndex = maxArgIndex + 1;
        paths = paths ++ [ arg ];
      }
    else
      {
        args = args ++ [ arg ];
        inherit maxArgIndex paths;
      };
  /*
    extractPaths : Int → [ (String|FilePath) ] → { maxArgIndex : Int, args : [ShellArg], paths : [FilePath] }
    Helper function that extracts file paths from command arguments and replaces them with argv[x] references.
  */
  extractPaths =
    maxArgIndex: command:
    builtins.foldl' processArg {
      inherit maxArgIndex;
      args = [ ];
      paths = [ ];
    } command;
  /*
    processCommand : { maxArgIndex : Int, commands : [[ShellArg]], paths : [FilePath] } → [ (String|FilePath) ] → { maxArgIndex : Int, commands : [[ShellArg]], paths : [FilePath] }
    Helper reducer function for extracting file paths from individual commands.
  */
  processCommand =
    {
      maxArgIndex,
      commands,
      paths,
    }:
    command:
    let
      new = extractPaths maxArgIndex command;
    in
    {
      commands = commands ++ [ new.args ];
      paths = paths ++ new.paths;
      maxArgIndex = new.maxArgIndex;
    };
  /*
    extractCommands : Int → [[ (String|FilePath) ]] → { maxArgIndex : Int, commands : [[ShellArg]], paths : [FilePath] }
    Helper function for extracting file paths from a list of commands and replacing them with argv[x] references.
  */
  extractCommands =
    maxArgIndex: commands:
    builtins.foldl' processCommand {
      inherit maxArgIndex;
      commands = [ ];
      paths = [ ];
    } commands;

  /*
    commandsToShellInvocation : [[ (String|FilePath) ]] → [ (String|FilePath) ]
    Converts a list of commands into a single command by turning them into a shell script and passing them to `sh -c`.
  */
  commandsToShellInvocation =
    commands:
    let
      extracted = extractCommands 0 commands;
    in
    [
      "sh"
      "-ec"
      (lib.concatMapStringsSep ";" escapeShellArgs' extracted.commands)
      # We need paths as separate arguments so that update.nix can ensure they refer to the local directory
      # rather than a store path.
    ]
    ++ extracted.paths;
in
rec {
  /*
    normalize : UpdateScript → UpdateScript
    EXPERIMENTAL! Converts a basic update script to the experimental attribute set form.
  */
  normalize =
    updateScript:
    {
      command = lib.toList (updateScript.command or updateScript);
      supportedFeatures = updateScript.supportedFeatures or [ ];
    }
    // lib.optionalAttrs (updateScript ? attrPath) {
      inherit (updateScript) attrPath;
    };

  /*
    sequence : [UpdateScript] → UpdateScript
    EXPERIMENTAL! Combines multiple update scripts to run in sequence.
  */
  sequence =
    scripts:

    let
      scriptsNormalized = builtins.map normalize scripts;
    in
    let
      scripts = scriptsNormalized;
      hasCommitSupport =
        lib.findSingle ({ supportedFeatures, ... }: supportedFeatures == [ "commit" ]) null null scripts
        != null;
      hasSilentSupport =
        lib.findFirst ({ supportedFeatures, ... }: supportedFeatures == [ "silent" ]) null scripts != null;
      # Supported features currently only describe the format of the standard output of the update script.
      # Here we ensure that the standard output of the combined update script is well formed.
      validateFeatures =
        if hasCommitSupport then
          # Exactly one update script declares only “commit” feature and all the rest declare only “silent” feature.
          ({ supportedFeatures, ... }: supportedFeatures == [ "commit" ] || supportedFeatures == [ "silent" ])
        else if hasSilentSupport then
          # All update scripts declare only “silent” feature.
          ({ supportedFeatures, ... }: supportedFeatures == [ "silent" ])
        else
          # No update script declares any supported feature to fail loudly on unknown features rather than silently discard them.
          ({ supportedFeatures, ... }: supportedFeatures == [ ]);
    in

    assert lib.assertMsg (lib.all validateFeatures scripts)
      "Combining update scripts with features enabled (other than “silent” scripts and an optional single script with “commit”) is currently unsupported.";
    assert lib.assertMsg (
      builtins.length (
        lib.unique (
          builtins.map (
            {
              attrPath ? null,
              ...
            }:
            attrPath
          ) scripts
        )
      ) == 1
    ) "Combining update scripts with different attr paths is currently unsupported.";

    {
      command = commandsToShellInvocation (builtins.map ({ command, ... }: command) scripts);
      supportedFeatures =
        if hasCommitSupport then
          [ "commit" ]
        else if hasSilentSupport then
          [ "silent" ]
        else
          [ ];
    };

  /*
    copyAttrOutputToFile : String → FilePath → UpdateScript
    EXPERIMENTAL! Simple update script that copies the output of Nix derivation built by `attr` to `path`.
  */
  copyAttrOutputToFile =
    attr: path:

    {
      command = [
        "sh"
        "-c"
        "cp --no-preserve=all \"$(nix-build -A ${attr})\" \"$0\" > /dev/null"
        path
      ];
      supportedFeatures = [ "silent" ];
    };

}