path: root/kiss

#!/bin/sh -ef
#
# This is a simple package manager written in POSIX 'sh' for use
# in KISS Linux (https://getkiss.org).
#
# This script runs with '-ef' meaning:
# '-e': Abort on any non-zero exit code.
# '-f': Disable globbing globally.
#
# [1] Warnings related to word splitting and globbing are disabled.
# All word splitting in this script is *safe* and intentional.
#
# Dylan Araps.

log() {
    # Print a message prettily.
    #
    # All messages are printed to stderr to allow the user to hide build
    # output which is the only thing printed to stdout.
    #
    # '\033[1;32m'        Set text to color '2' and make it bold.
    # '\033[m':           Reset text formatting.
    # '${3:-->}':         If the 3rd argument is missing, set prefix to '->'.
    # '${2:+\033[1;3Xm}': If the 2nd argument exists, set text style of '$1'.
    # '${2:+\033[m}':     If the 2nd argument exists, reset text formatting.
    printf '\033[1;33m%s \033[m%b%s\033[m %s\n' \
           "${3:-->}" "${2:+\033[1;36m}" "$1" "$2" >&2
}

die() {
    # Print a message and exit with '1' (error).
    log "$1" "$2" "!>"
    exit 1
}

contains() {
    # Check if a "string list" contains a word.
    case " $1 " in *" $2 "*) return 0; esac; return 1
}

prompt() {
    # Ask the user for some input.
    log "Continue?: Press Enter to continue or Ctrl+C to abort here"

    # POSIX 'read' has none of the "nice" options like '-n', '-p'
    # etc etc. This is the most basic usage of 'read'.
    # '_' is used as 'dash' errors when no variable is given to 'read'.
    read -r _
}

root_cache() {
    # This function simply mimics a 'su' prompt to then store
    # the root password for the lifetime of the package manager.
    #
    # This function is called once when needed to cache the
    # password. The password is not accessible to any subprocesses
    # and should never leave the package manager's process.
    #
    # This behavior is needed as there is no POSIX shell method
    # of running a shell function as a different user. We can't
    # selectively lower or raise permissions in a seamless way
    # through "normal" means.
    #
    # Root is only needed when installing/removing packages whereas
    # non-root permissions are needed in countless places throughout.
    #
    # This is the only *workable* solution to 1) not run the entire
    # package manager as root and 2) avoid prompting for password
    # before, during and after builds numerous times.
    #
    # NOTE: Careful consideration has been taken in regards to this
    #       change and I would have loved an inconspicuous solution
    #       to this problem... but it doesn't exist.
    #
    # This change was needed as the existing behavior was not ideal
    # in any way and needed to be fixed.

    # Pointless running this function if the user has chosen to run
    # the package manager as root anyway.
    [ "$(id -u)" != 0 ] || return 0

    printf 'Password: '

    # Disable echoing to the terminal while the password is inputted
    # by the user. The below commands read from '/dev/tty' to ensure
    # they work when run from a subshell.
    #
    # The variable '$cached' is used to check if we've been here
    # before. We cannot check whether or not '$pass' is empty as the
    # '[' command may be external which would result in /proc leakage.
    stty -F /dev/tty -echo
    IFS= read -r pass < /dev/tty && cached=1
    stty -F /dev/tty echo

    printf '\n'

    # Validate the password now with a simple 'true' command as we
    # don't yet need to elevate permissions.
    dosu /bin/true
}

dosu() {
    [ "$cached" ] || root_cache

    # Declare this as a function to avoid repeating it twice
    # below. Great naming of functions all around.
    #
    # Run a command as root using the cached password. The 'su'
    # command allows you to input a password via stdin. To hide
    # the prompt, the command's output is sent to '/dev/tty'
    # and the output of 'su' is sent to '/dev/null'.
    dosudo() { su "${drop_to:-root}" -c "$* >/dev/tty" >/dev/null; }

    # The code below uses the most secure method of sending
    # data over stdin based on what is available in the system.
    #
    # The great debate: Use a heredoc or echo+pipe for password
    # input over stdin? Time to explain.
    #
    # 1) 'printf | cmd' is the most secure IF 'printf' is built
    #    into the shell and NOT an external command. When 'printf'
    #    is external, the password WILL be leaked over '/proc'.
    #
    #    Safe shells here are anything with a builtin 'printf',
    #    'ash', 'dash', 'bash' and most other shells.
    #
    # 2) Using a heredoc is as secure as the above method (when
    #    builtin) IF and only IF the user's shell implements
    #    heredocs WITHOUT the use of temporary files (See bash!).
    #
    #    When using heredocs and a temporary file the risk is a
    #    tiny window in which the input is available inside of
    #    a temporary file.
    #
    #    'ash' and 'dash' are safe here, 'bash' is not ('bash'
    #    falls under (1) however).
    #
    # Which is best? (order is best to worst)
    #
    # 1) builtin 'printf'.
    # 2) heredocs with no temporary file.
    # 3) heredocs with a temporary file.
    #
    # This code below follows the above ordering when deciding
    # which method to use. The '$heredocs' variable is declared
    # in 'main()' after a check to see if 'printf' is builtin.
    if [ "$heredocs" ]; then
        dosudo "$@" <<-EOF
			$pass
		EOF
    else
        printf '%s\n' "$pass" | dosudo "$@"
    fi
}

regex_escape() {
    # Escape all required characters in both the search and
    # replace portions of two strings for use in a 'sed' call
    # as "plain-text".
    sea=$(printf %s "$1" | sed 's/[]\/$*.^[]/\\&/g')
    rep=$(printf %s "$2" | sed 's/[\/&]/\\&/g')
}

pkg_lint() {
    # Check that each mandatory file in the package entry exists.
    log "$1" "Checking repository files"

    repo_dir=$(pkg_find "$1")

    cd "$repo_dir" || die "'$repo_dir' not accessible"
    [ -f sources ] || die "$1" "Sources file not found"
    [ -x build ]   || die "$1" "Build file not found or not executable"
    [ -s version ] || die "$1" "Version file not found or empty"

    read -r _ release < version
    [ "$release" ] || die "Release field not found in version file"
}

pkg_find() {
    # Figure out which repository a package belongs to by
    # searching for directories matching the package name
    # in $KISS_PATH/*.
    [ "$KISS_PATH" ] || die "\$KISS_PATH needs to be set"

    # Turn the argument list into variables as we reset
    # the list below.
    query=$1
    match=$2

    # This ugly mess appends '/.' to the end of each path in
    # '$KISS_PATH' as POSIX 'find' has no '-mindepth'/'-maxdepth'.
    # See: https://unix.stackexchange.com/a/330372
    IFS=:; set --
    for path in $KISS_PATH; do set "$@" "$path/."; done
    IFS=$old_ifs

    # Find the repository containing a package.
    # Searches installed packages if the package is absent
    # from the repositories.
    # See [1] at top of script.
    # shellcheck disable=2046,2086
    set -- $(find "$@" "$sys_db/." \( ! -name . -prune \) -name "$query")

    # A package may also not be found due to a repository not being
    # readable by the current user. Either way, we need to die here.
    [ "$1" ] || die "Package '$query' not in any repository"

    # Show all search results if called from 'kiss search', else
    # print only the first match.
    case $match in
        all) printf '%s\n' "$@" ;;
        *)   printf '%s\n' "$1" ;;
    esac
}

pkg_list() {
    # List installed packages. As the format is files and
    # directories, this just involves a simple for loop and
    # file read.

    # Change directories to the database. This allows us to
    # avoid having to 'basename' each path. If this fails,
    # set '$1' to mimic a failed glob which indicates that
    # nothing is installed.
    cd "$sys_db" 2>/dev/null || set -- "$sys_db/"\*

    # Optional arguments can be passed to check for specific
    # packages. If no arguments are passed, list all. As we
    # loop over '$@', if there aren't any arguments we can
    # just set the directory contents to the argument list.
    [ "$1" ] || { set +f; set -f -- *; }

    # If the 'glob' above failed, exit early as there are no
    # packages installed.
    [ "$1" = "$sys_db/"\* ] && return 1

    # Loop over each package and print its name and version.
    for pkg; do
        [ -d "$pkg" ] || {
            log "Package '$pkg' is not installed"
            return 1
        }

        read -r version 2>/dev/null < "$pkg/version" || version=null
        printf '%s\n' "$pkg $version"
    done
}

pkg_sources() {
    # Download any remote package sources. The existence of local
    # files is also checked.
    log "$1" "Downloading sources"

    # Store each downloaded source in a directory named after the
    # package it belongs to. This avoid conflicts between two packages
    # having a source of the same name.
    mkdir -p "$src_dir/$1" && cd "$src_dir/$1"

    repo_dir=$(pkg_find "$1")

    while read -r src dest || [ "$src" ]; do
        # Remote source (cached).
        if [ -f "${src##*/}" ]; then
            log "$1" "Found cached source '${src##*/}'"

        # Remote git repository.
        elif [ -z "${src##git+*}" ]; then
            # This is a checksums check, skip it.
            [ "$2" ] && continue

            mkdir -p "$mak_dir/$1/$dest"

            # Run in a subshell to keep variables local.
            (
                repo_src=${src##git+}

                [ "${src##*#*}" ] && shallow=--depth=1

                cd "$mak_dir/$1/$dest" &&
                    git clone "${shallow:---}" "${repo_src%#*}" .

            ) || die "$1" "Failed to clone $src"

        # Remote source.
        elif [ -z "${src##*://*}" ]; then
            curl "$src" -fLo "${src##*/}" || {
                rm -f "${src##*/}"
                die "$1" "Failed to download $src"
            }

        # Local source.
        elif [ -f "$repo_dir/$src" ]; then
            log "$1" "Found local file '$src'"

        else
            die "$1" "No local file '$src'"
        fi
    done < "$repo_dir/sources"
}

pkg_extract() {
    # Extract all source archives to the build directory and copy over
    # any local repository files.
    log "$1" "Extracting sources"

    repo_dir=$(pkg_find "$1")

    while read -r src dest || [ "$src" ]; do
        mkdir -p "$mak_dir/$1/$dest" && cd "$mak_dir/$1/$dest"

        case $src in
            # Git repository with supplied commit hash.
            git+*\#*)
                log "Checking out ${src##*#}"

                git reset --hard "${src##*#}" ||
                    die "Commit hash ${src##*#} doesn't exist"
            ;;

            # Git repository.
            git+*)
                continue
            ;;

            # Only 'tar' archives are currently supported for extraction.
            # Any other file-types are simply copied to '$mak_dir' which
            # allows for manual extraction.
            *://*.tar|*://*.tar.??|*://*.tar.???|*://*.tar.????|*://*.tgz)
                tar xf "$src_dir/$1/${src##*/}" --strip-components 1 ||
                    die "$1" "Couldn't extract ${src##*/}"
            ;;

            *)
                # Local file.
                if [ -f "$repo_dir/$src" ]; then
                    cp -f "$repo_dir/$src" .

                # Remote file.
                elif [ -f "$src_dir/$1/${src##*/}" ]; then
                    cp -f "$src_dir/$1/${src##*/}" .

                else
                    die "$1" "Local file $src not found"
                fi
            ;;
        esac
    done < "$repo_dir/sources"
}

pkg_depends() {
    # Resolve all dependencies and generate an ordered list.
    repo_dir=$(pkg_find "$1")

    # This does a depth-first search. The deepest dependencies are
    # listed first and then the parents in reverse order.
    contains "$deps" "$1" || {
        # Filter out non-explicit, aleady installed dependencies.
        # Only filter installed if called from 'pkg_build()'.
        [ "$pkg_build" ] && [ -z "$2" ] &&
            (pkg_list "$1" >/dev/null) && return

        # Recurse through the dependencies of the child packages.
        while read -r dep _ || [ "$dep" ]; do
            [ "${dep##\#*}" ] && pkg_depends "$dep"
        done 2>/dev/null < "$repo_dir/depends" ||:

        # After child dependencies are added to the list,
        # add the package which depends on them.
        [ "$2" = explicit ] || deps="$deps $1 "
    }
}

pkg_strip() {
    # Strip package binaries and libraries. This saves space on the
    # system as well as on the tar-balls we ship for installation.

    # Package has stripping disabled, stop here.
    [ -f "$mak_dir/$pkg/nostrip" ] && return

    log "$1" "Stripping binaries and libraries"

    # Strip only files matching the below ELF types.
    # NOTE: 'readelf' is used in place of 'file' as
    #       it allows us to remove 'file' from the
    #       core repositories altogether.
    find "$pkg_dir/$1" -type f | while read -r file; do
        case $(readelf -h "$file" 2>/dev/null) in
            *" DYN "*)  strip_opt=unneeded ;;
            *" EXEC "*) strip_opt=all ;;
            *" REL "*)  strip_opt=debug ;;
            *) continue
        esac

        # Suppress errors here as some binaries and libraries may
        # fail to strip. This is OK.
        strip "--strip-$strip_opt" "$file" 2>/dev/null ||:
    done
}

pkg_fixdeps() {
    # Dynamically look for missing runtime dependencies by checking
    # each binary and library with 'ldd'. This catches any extra
    # libraries and or dependencies pulled in by the package's
    # build suite.
    log "$1" "Checking for missing dependencies"

    # Go to the directory containing the built package to
    # simplify path building.
    cd "$pkg_dir/$1/$pkg_db/$1"

    # Make a copy of the depends file if it exists to have a
    # reference to 'diff' against.
    [ -f depends ] && cp -f depends depends-copy

    # Generate a list of all installed manifests.
    pkg_name=$1
    set +f
    set -f -- "$sys_db/"*/manifest

    # Get a list of binaries and libraries, false files
    # will be found, however it's faster to get 'ldd' to check
    # them anyway than to filter them out.
    find "$pkg_dir/$pkg_name/" -type f 2>/dev/null |

    while read -r file; do
        # Run 'ldd' on the file and parse each line. The code
        # then checks to see which packages own the linked
        # libraries and it prints the result.
        ldd "$file" 2>/dev/null | while read -r dep; do
            # Skip lines containing 'ldd'.
            [ "${dep##*ldd*}" ] || continue

            # Extract the file path from 'ldd' output.
            dep=${dep#* => }
            dep=${dep% *}

            # Figure out which package owns the file.
            dep=$("$grep" -lFx "${dep##$KISS_ROOT}" "$@")

            # Extract package name from 'grep' match.
            dep=${dep%/*}
            dep=${dep##*/}

            case $dep in
                # Skip listing these packages as dependencies.
                musl|gcc|${PWD##*/}|"") ;;
                *) printf '%s\n' "$dep" ;;
            esac
        done ||:
    done >> depends-copy

    # Remove duplicate entries from the new depends file.
    # This remove duplicate lines looking *only* at the
    # first column.
    sort -u -k1,1 depends-copy > depends-new

    # Display a 'diff' of the new dependencies agaisnt
    # the old ones. '-N' treats non-existent files as blank.
    diff -N depends depends-new ||:

    # Do some clean up as this required a few temporary files.
    mv -f depends-new depends
    rm -f depends-copy
}

pkg_junk() (
    # Optionally remove "junk" files from packages. This includes 'info'
    # files, 'man' pages, gettext files, etc. This is configurable by the
    # user.
    #
    # This function runs as a sub-shell to avoid having to 'cd' back to the
    # prior directory before being able to continue.
    cd "$pkg_dir/$1"

    # Default list of directories and their contents to be removed from
    # built packages. This default assumes a prefix of '/usr' though the
    # user can further configure it to search whatever paths they desire.
    #
    # TODO: This could be nicer as could the interface to it. Something
    #       which allows for the addition/subtraction from the list
    #       would be desirable.
    rm=usr/share/doc:usr/share/gtk-doc:usr/share/info:usr/share/polkit-1
    rm=$rm:usr/share/gettext:usr/share/locale:usr/share/bash-completion
    rm=$rm:etc/bash_completion.d:usr/share/applications
    rm=$rm:usr/share/zsh/site-functions:usr/share/zsh/vendor-completions

    # Split the environment variable on ':' and turn it into an argument
    # list. This works exactly like '$KISS_PATH'.
    #
    # Files which always conflict (such as usr/lib/charset.alias) and are
    # uneeded should be removed regardless.
    #
    # shellcheck disable=2046,2086
    { IFS=:; set -- ${KISS_RM:-$rm} usr/lib/charset.alias; IFS=$old_ifs; }

    # Loop over each junk entry and delete it if it exists.
    for junk; do
        [ -e "./$junk" ] && rm -rf "./$junk" &&
            log "${PWD##*/}" "Removed $junk"
    done ||:
)

pkg_manifest() (
    # Generate the package's manifest file. This is a list of each file
    # and directory inside the package. The file is used when uninstalling
    # packages, checking for package conflicts and for general debugging.
    log "$1" "Generating manifest"

    # This funcion runs as a sub-shell to avoid having to 'cd' back to the
    # prior directory before being able to continue.
    cd "$pkg_dir/$1"

    # find: Print all files and directories and append '/' to directories.
    # sort: Sort the output in *reverse*. Directories appear *after* their
    #       contents.
    # sed:  Remove the first character in each line (./dir -> /dir) and
    #       remove all lines which only contain '.'.
    find . -type d -exec printf '%s/\n' {} + -o -print |
        sort -r | sed '/^\.\/$/d;ss.ss' > "$pkg_dir/$1/$pkg_db/$1/manifest"
)

pkg_tar() {
    # Create a tar-ball from the built package's files.
    # This tar-ball also contains the package's database entry.
    log "$1" "Creating tar-ball"

    # Read the version information to name the package.
    read -r version release < "$(pkg_find "$1")/version"

    # Create a tar-ball from the contents of the built package.
    tar zpcf "$bin_dir/$1#$version-$release.tar.gz" -C "$pkg_dir/$1" . ||
        die "$1" "Failed to create tar-ball"

    log "$1" "Successfully created tar-ball"
}

pkg_build() {
    # Build packages and turn them into packaged tar-balls. This function
    # also checks checksums, downloads sources and ensure all dependencies
    # are installed.
    pkg_build=1

    log "Resolving dependencies"

    for pkg; do
        contains "$explicit" "$pkg" || {
            pkg_depends "$pkg" explicit

            # Mark packages passed on the command-line
            # separately from those detected as dependencies.
            explicit="$explicit $pkg "
        }
    done

    [ "$pkg_update" ] || explicit_build=$explicit

    # If an explicit package is a dependency of another explicit
    # package, remove it from the explicit list as it needs to be
    # installed as a dependency.
    for pkg; do
        # There's no better way to remove a word from a string in
        # POSIX 'sh' sadly.
        contains "$deps" "$pkg" &&
            explicit=$(printf %s "$explicit" | sed "s/ $pkg / /g")
    done

    # See [1] at top of script.
    # shellcheck disable=2046,2086
    set -- $deps $explicit

    log "Building: $*"

    # Only ask for confirmation if more than one package needs to be built.
    [ $# -gt 1 ] || [ "$pkg_update" ] && {
        prompt

        # Prompt for password prior to the build if more than one package
        # will be built and installed. No use in forcing the user to wait
        # for the first password prompt (before caching) if it may take a
        # long long while.
        [ "$cached" ] || root_cache
    }

    log "Checking to see if any dependencies have already been built"
    log "Installing any pre-built dependencies"

    # Install any pre-built dependencies if they exist in the binary
    # directory and are up to date.
    for pkg; do
        # Don't check for a pre-built package if it was passed
        # to KISS directly.
        contains "$explicit_build" "$pkg" || {
            # Figure out the version and release.
            read -r version release < "$(pkg_find "$pkg")/version"

            # Install any pre-built binaries if they exist.
            # This calls 'args' to inherit a root check
            # to 'su' to elevate permissions.
            [ -f "$bin_dir/$pkg#$version-$release.tar.gz" ] && {
                log "$pkg" "Found pre-built binary, installing"

                (KISS_FORCE=1 \
                    pkg_install "$bin_dir/$pkg#$version-$release.tar.gz")

                # Remove the now installed package from the build
                # list. No better way than using 'sed' in POSIX 'sh'.
                # See [1] at top of script.
                # shellcheck disable=2046,2086
                set -- $(printf %s " $* " | sed "s/ $pkg / /")
            }
        }
    done

    for pkg; do pkg_lint "$pkg"; done
    for pkg; do
        # Ensure that checksums exist prior to building the package.
        [ -f "$(pkg_find "$pkg")/checksums" ] || {
            log "$pkg" "Checksums are missing"

            # Instead of dying above, log it to the terminal. Also define a
            # variable so we *can* die after all checksum files have been
            # checked.
            no_sums="$no_sums$pkg "
        }
    done

    # Die here as packages without checksums were found above.
    [ "$no_sums" ] && die "Checksums missing, run 'kiss checksum ${no_sums% }'"

    for pkg; do pkg_sources "$pkg"; done

    # Verify all package checksums. This is achieved by generating
    # a new set of checksums and then comparing those with the old
    # set.
    for pkg; do
        pkg_checksums "$pkg" | cmp -s - "$(pkg_find "$pkg")/checksums" || {
            log "$pkg" "Checksum mismatch"

            # Instead of dying above, log it to the terminal. Also define a
            # variable so we *can* die after all checksum files have been
            # checked.
            mismatch="$mismatch$pkg "
        }
    done

    # Die here as packages with differing checksums were found above.
    [ "$mismatch" ] && die "Checksum mismatch with: ${mismatch% }"

    # Finally build and create tarballs for all passed packages and
    # dependencies.
    for pkg; do
        log "$pkg" "Building package ($((in = in + 1))/$#)"

        pkg_extract "$pkg"
        repo_dir=$(pkg_find "$pkg")

        # Install built packages to a directory under the package name
        # to avoid collisions with other packages.
        mkdir -p "$pkg_dir/$pkg/$pkg_db"

        # Move to the build directory.
        cd "$mak_dir/$pkg"

        log "$pkg" "Starting build"

        # Call the build script, log the output to the terminal
        # and to a file. There's no PIPEFAIL in POSIX shelll so
        # we must resort to tricks like killing the script ourselves.
        { "$repo_dir/build" "$pkg_dir/$pkg" || {
            log "$pkg" "Build failed"
            pkg_clean
            kill 0
        } } 2>&1 | tee "$log_dir/$pkg-$pid-$time" > /dev/tty

        # Delete the log file if the build succeeded to prevent
        # the directory from filling very quickly with useless logs.
        [ "$KISS_DEBUG" = 1 ] || rm -f "$log_dir/$pkg-$pid-$time"

        # Copy the repository files to the package directory.
        # This acts as the database entry.
        cp -LRf "$repo_dir" "$pkg_dir/$pkg/$pkg_db/"

        log "$pkg" "Successfully built package"

        # Create the manifest file early and make it empty.
        # This ensure that the manifest is added to the manifest...
        : > "$pkg_dir/$pkg/$pkg_db/$pkg/manifest"

        pkg_strip    "$pkg"
        pkg_fixdeps  "$pkg"
        pkg_junk     "$pkg"
        pkg_manifest "$pkg"
        pkg_tar      "$pkg"

        # Install only dependencies of passed packages.
        # Skip this check if this is a package update.
        contains "$explicit" "$pkg" && [ -z "$pkg_update" ] && continue

        log "$pkg" "Needed as a dependency or has an update, installing"

        (KISS_FORCE=1 \
            pkg_install "$bin_dir/$pkg#$version-$release.tar.gz")
    done

    # End here as this was a system update and all packages have been installed.
    [ "$pkg_update" ] && return

    log "Successfully built package(s)"

    # Turn the explicit packages into a 'list'.
    # See [1] at top of script.
    # shellcheck disable=2046,2086
    set -- $explicit

    # Only ask for confirmation if more than one package needs to be installed.
    [ $# -gt 1 ] && {
        log "Install built packages? [$*]"

        prompt && {
            args i "$@"
            return
        }
    }

    log "Run 'kiss i $*' to install the package(s)"
}

pkg_checksums() {
    # Generate checksums for packages.
    repo_dir=$(pkg_find "$1")

    while read -r src _ || [ "$src" ]; do
        # File is local to the package.
        if [ -f "$repo_dir/$src" ]; then
            src_path=$repo_dir/${src%/*}

        # File is remote and was downloaded.
        elif [ -f "$src_dir/$1/${src##*/}" ]; then
            src_path=$src_dir/$1

        # File is a git repository.
        elif [ -z "${src##git+*}" ]; then
            printf 'git  %s\n' "$src"
            continue

        # Die here if source for some reason, doesn't exist.
        else
            die "$1" "Couldn't find source '$src'"
        fi

        # An easy way to get 'sha256sum' to print with the 'basename'
        # of files is to 'cd' to the file's directory beforehand.
        (cd "$src_path" && sha256sum "${src##*/}") ||
            die "$1" "Failed to generate checksums"
    done < "$repo_dir/sources"
}

pkg_conflicts() {
    # Check to see if a package conflicts with another.
    log "$2" "Checking for package conflicts"

    # Filter the tarball's manifest and select only files
    # and any files they resolve to on the filesystem
    # (/bin/ls -> /usr/bin/ls).
    tar xf "$1" -O "./$pkg_db/$2/manifest" | while read -r file; do
        case $file in */) continue; esac

        printf '%s/%s\n' \
            "$(readlink -f "$KISS_ROOT/${file%/*}" 2>/dev/null)" \
            "${file##*/}"
    done > "$cac_dir/$pid-m"

    p_name=$2

    # Generate a list of all installed package manifests.
    set +f
    set -f -- "$sys_db"/*/manifest

    # Filter the manifest list and remove the previously
    # installed version of the package if it exists.
    for pkg; do
        i_name=${pkg%/*}
        i_name=${i_name##*/}

        shift "$(($# ? 1 : 0))"

        [ "$p_name" = "$i_name" ] && continue

        set -- "$@" "$pkg"
    done

    [ -s "$cac_dir/$pid-m" ] || return 0

    # Count the total conflicts to determine when to
    # automatically enable the alternatives feature.
    con_total=$("$grep" -Fxf "$cac_dir/$pid-m" -- "$@" | wc -l)

    # Use 'grep' to list matching lines between the to
    # be installed package's manifest and the above filtered
    # list.
    if [ "$KISS_CHOICE" = 1 ] || [ "$con_total" -le 10 ]; then
        "$grep" -Fxf "$cac_dir/$pid-m" -- "$@" |

        # This is a novel way of offering an "alternatives" system.
        # It is entirely dynamic and all "choices" are created and
        # destroyed on the fly.
        #
        # When a conflict is found between two packages, the file
        # is moved to a directory called "choices" and its name
        # changed to store its parent package and its intended
        # location.
        #
        # The package's manifest is then updated to reflect this
        # new location.
        #
        # The 'kiss choices' command parses this directory and
        # offers you the CHOICE of *swapping* entries in this
        # directory for those on the filesystem.
        #
        # The choices command does the same thing we do here,
        # it rewrites manifests and moves files around to make
        # this work.
        #
        # Pretty nifty huh?
        while IFS=: read -r pro con || [ "$pro" ]; do
            log "$p_name" "Found conflict ($con), adding choice"

            # Create the "choices" directory inside of the tarball.
            # This directory will store the conflicting file.
            mkdir -p "$tar_dir/$p_name/${cho_dir:=var/db/kiss/choices}"

            # Construct the file name of the "db" entry of the
            # conflicting file. (pkg_name>usr>bin>ls)
            con_name=$(printf %s "$con" | sed 's|/|>|g')

            # Move the conflicting file to the choices directory
            # and name it according to the format above.
            mv -f "$tar_dir/$p_name/$con" \
                  "$tar_dir/$p_name/$cho_dir/$p_name$con_name"

            regex_escape "$con" "/$cho_dir/$p_name$con_name"
            mani=$tar_dir/$p_name/$pkg_db/$p_name/manifest

            # Rewrite the package's manifest to update its location
            # to its new spot (and name) in the choices directory.
            sed "s/^$sea\$/$rep/" "$mani" > "$mani.1"
            mv -f "$mani.1" "$mani"
        done
    else
        if "$grep" -Fxf "$cac_dir/$pid-m" -- "$@"; then
            log "Package '$p_name' conflicts with another package" "" "!>"
            log "Run 'KISS_CHOICE=1 kiss i $p_name' to add conflicts" "" "!>"
            die "as alternatives."
        fi
    fi
}

pkg_swap() {
    # Swap between package alternatives.

    # Check to see if the package is installed. This
    # will exit with an error if it is not.
    pkg_list "$1" >/dev/null

    alt=$(printf %s "$1$2" | sed 's|/|>|g')
    cd "$sys_db/../choices"

    [ -f "$alt" ] || [ -h "$alt" ] ||
        die "Alternative '$1 $2' doesn't exist"

    if [ -f "$2" ]; then
        # Figure out which package owns the file we are going to
        # swap for another package's.
        #
        # Print the full path to the manifest file which contains
        # the match to our search.
        pkg_owns=$(set +f; "$grep" -lFx "$2" "$sys_db/"*/manifest) ||:

        # Extract the package name from the path above.
        pkg_owns=${pkg_owns%/*}
        pkg_owns=${pkg_owns##*/}

        [ "$pkg_owns" ] ||
            die "File '$2' exists on filesystem but isn't owned"

        log "Swapping '$2' from '$pkg_owns' to '$1'"

        regex_escape "$2" "$PWD/$pkg_owns>${alt#*>}"
        mani=${PWD%/*}/installed/$pkg_owns/manifest

        # Convert the current owner to an alternative and rewrite
        # its manifest file to reflect this.
        dosu cp  -f "'$2'" "'$pkg_owns>${alt#*>}'"
        dosu sed "'s/^$sea\$/$rep/'" \
            "'$mani' > '$mani.1' && mv -f '$mani.1' '$mani'"
    fi

    regex_escape "$PWD/$alt" "$2"
    mani=${PWD%/*}/installed/$1/manifest

    # Convert the desired alternative to a real file and rewrite
    # the manifest file to reflect this. The reverse of above.
    dosu mv  -f "'$alt'" "'$2'"
    dosu sed "'s/^$sea\$/$rep/'" \
        "'$mani' > '$mani.1' && mv -f '$mani.1' '$mani'"
}

pkg_remove() {
    # Remove a package and all of its files. The '/etc' directory
    # is handled differently and configuration files are *not*
    # overwritten.

    # The package is not installed, don't do anything.
    pkg_list "$1" >/dev/null || {
        log "$1" "Not installed"
        return
    }

    # Enable globbing.
    set +f

    # Make sure that nothing depends on this package.
    [ "$2" = check ] && for file in "$sys_db/"*; do
        # Check each depends file for the package and if it's
        # a run-time dependency, append to the $required_by string.
        "$grep" -qFx "$1" "$file/depends" 2>/dev/null &&
            required_by="$required_by'${file##*/}', "
    done

    [ "$required_by" ] &&
        die "$1" "Package is required by ${required_by%, }"

    # Disable globbing.
    set -f

    # Ensure that the user leaves their machine in a working state by
    # refusing to remove the package which providees 'su'.
    grep -q "^$(command -v su)$" "$sys_db/$1/manifest" &&
        die "$1" "Removing su will break the system."

    # Block being able to abort the script with 'Ctrl+C' during removal.
    # Removes all risk of the user aborting a package removal leaving
    # an incomplete package installed.
    trap '' INT

    while read -r file; do
        # The file is in '/etc' skip it. This prevents the package
        # manager from removing user edited configuration files.
        [ "${file##/etc/*}" ] || continue

        if [ -d "$KISS_ROOT/$file" ]; then
            dosu rmdir "'$KISS_ROOT/$file'" 2>/dev/null || continue
        else
            dosu rm -f "'$KISS_ROOT/$file'"
        fi
    done < "$sys_db/$1/manifest"

    # Reset 'trap' to its original value. Removal is done so
    # we no longer need to block 'Ctrl+C'.
    trap pkg_clean EXIT INT

    log "$1" "Removed successfully"
}

pkg_install() {
    # Install a built package tar-ball.

    # Install can also take the full path to a tar-ball.
    # We don't need to check the repository if this is the case.
    if [ -f "$1" ] && [ -z "${1%%*.tar.gz}" ] ; then
        tar_file=$1

    else
        # Read the version information to name the package.
        read -r version release < "$(pkg_find "$1")/version"

        # Construct the name of the package tarball.
        tar_name=$1\#$version-$release.tar.gz

        [ -f "$bin_dir/$tar_name" ] ||
            die "Package '$1' has not been built, run 'kiss build $1'"

        tar_file=$bin_dir/$tar_name
    fi

    # Figure out which package the tar-ball installs by checking for
    # a database entry inside the tar-ball. If no database entry exists,
    # exit here as the tar-ball is *most likely* not a KISS package.
    pkg_name=$(tar tf "$tar_file" | "$grep" -x "\./$pkg_db/.*/version") ||
        die "'${tar_file##*/}' is not a valid KISS package"

    pkg_name=${pkg_name%/*}
    pkg_name=${pkg_name##*/}

    mkdir -p "$tar_dir/$pkg_name"

    # Extract the tar-ball to catch any errors before installation begins.
    dosu tar pxf "'$tar_file'" -C "'$tar_dir/$pkg_name'" ||
        die "$pkg_name" "Failed to extract tar-ball"

    log "$pkg_name" "Checking that all dependencies are installed"

    # Make sure that all run-time dependencies are installed prior to
    # installing the package.
    [ -f "$tar_dir/$pkg_name/$pkg_db/$pkg_name/depends" ] &&
    [ -z "$KISS_FORCE" ] &&
        while read -r dep dep_type || [ "$dep" ]; do
            [ "${dep##\#*}" ] || continue
            [ "$dep_type" ]   || pkg_list "$dep" >/dev/null ||
                install_dep="$install_dep'$dep', "
        done < "$tar_dir/$pkg_name/$pkg_db/$pkg_name/depends"

    [ "$install_dep" ] && die "$1" "Package requires ${install_dep%, }"

    pkg_conflicts "$tar_file" "$pkg_name"

    log "$pkg_name" "Installing package incrementally"

    # Block being able to abort the script with Ctrl+C during installation.
    # Removes all risk of the user aborting a package installation leaving
    # an incomplete package installed.
    trap '' INT

    # If the package is already installed (and this is an upgrade) make a
    # backup of the manifest file.
    old_manifest=$(cat "$sys_db/$pkg_name/manifest" 2>/dev/null ||:)

    # This is repeated multiple times. Better to make it a function.
    pkg_rsync() {
        dosu rsync --chown=root:root --chmod=Du-s,Dg-s,Do-s \
              -WhHKa --no-compress "$1" --exclude /etc \
              "'$tar_dir/$pkg_name/'" "'$KISS_ROOT/'"
    }

    # Install the package by using 'rsync' and overwrite any existing files
    # (excluding '/etc/').
    pkg_rsync --info=progress2

    # If '/etc/' exists in the package, install it but don't overwrite.
    [ -d "$tar_dir/$pkg_name/etc" ] &&
        dosu rsync --chown=root:root -WhHKa --no-compress --ignore-existing \
            "'$tar_dir/$pkg_name/etc'" "'$KISS_ROOT/'"

    # Remove any leftover files if this is an upgrade.
    [ "$old_manifest" ] && {
        printf '%s\n' "$old_manifest" |
        "$grep" -vFxf "$sys_db/$pkg_name/manifest" - |

        while read -r file; do
            # Skip deleting some leftover files.
            case $file in
                /etc/*|*bin/rm|*bin/busybox|*bin/rsync) continue
            esac

            file=$KISS_ROOT/$file

            # Remove files.
            if [ -f "$file" ] && [ ! -L "$file" ]; then
                dosu rm -f "'$file'"

            # Remove file symlinks.
            elif [ -L "$file" ] && [ ! -d "$file" ]; then
                dosu unlink "'$file'" ||:

            # Skip directory symlinks.
            elif [ -L "$file" ] && [ -d "$file" ]; then :

            # Remove directories if empty.
            elif [ -d "$file" ]; then
                dosu rmdir "'$file'" 2>/dev/null ||:
            fi
        done ||:
    }

    # Install the package again to fix any non-leftover files being
    # removed above.
    pkg_rsync -v ||:
    pkg_rsync -v ||:

    # Reset 'trap' to its original value. Installation is done so
    # we no longer need to block 'Ctrl+C'.
    trap pkg_clean EXIT INT

    if [ -x "$sys_db/$pkg_name/post-install" ]; then
        log "$pkg_name" "Running post-install script"
        dosu "'$sys_db/$pkg_name/post-install'" ||:
    fi

    log "$pkg_name" "Installed successfully"
}

pkg_updates() {
    # Check all installed packages for updates. So long as the installed
    # version and the version in the repositories differ, it's considered
    # an update.

    log "Updating repositories"

    # Create a list of all repositories.
    # See [1] at top of script.
    # shellcheck disable=2046,2086
    { IFS=:; set -- $KISS_PATH; IFS=$old_ifs; }

    # Update each repository in '$KISS_PATH'. It is assumed that
    # each repository is 'git' tracked.
    for repo; do
        cd "$repo"

        # Go to the root of the repository (if it exists).
        cd "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null ||:

        [ -d .git ] || {
            log "$repo" " "
            printf '%s\n' "Not a git repository, skipping."
            continue
        }

        [ "$(git remote 2>/dev/null)" ] || {
            log "$repo" " "
            printf '%s\n' "No remote, skipping."
            continue
        }

        contains "$repos" "$PWD" || {
            repos="$repos $PWD "

            # Display a tick if signing is enabled for this
            # repository.
            case $(git config merge.verifySignatures) in
                true) signed='[signed ✓]' ;;
                *)    signed=  ;;
            esac

            log "$PWD" "$signed "

            if [ -w "$PWD" ]; then
                git fetch
                git merge

            else
                log "$PWD" "Need root to update"

                # Find out the owner of the repository and spawn
                # git as this user below.
                #
                # This prevents 'git' from changing the original
                # ownership of files and directories in the rare
                # case that the repository is owned by a 3rd user.
                (drop_to=$(stat -c %U "$PWD")

                dosu git fetch
                dosu git merge)
            fi
        }
    done

    log "Checking for new package versions"

    # Enable globbing.
    set +f

    for pkg in "$sys_db/"*; do
        pkg_name=${pkg##*/}

        # Read version and release information from the installed packages
        # and repository.
        read -r db_ver db_rel < "$pkg/version"
        read -r re_ver re_rel < "$(pkg_find "$pkg_name")/version"

        # Compare installed packages to repository packages.
        [ "$db_ver-$db_rel" != "$re_ver-$re_rel" ] && {
            printf '%s\n' "$pkg_name $db_ver-$db_rel ==> $re_ver-$re_rel"
            outdated="$outdated$pkg_name "
        }
    done

    # If the package manager has an update, handle it first.
    contains "$outdated" kiss && {
        log "Detected package manager update"
        log "The package manager will be updated first"

        prompt

        pkg_build   kiss
        pkg_install kiss

        log "Updated the package manager"
        log "Re-run 'kiss update' to update your system"

        exit 0
    }

    # Disable globbing.
    set -f

    # End here if no packages have an update.
    [ "$outdated" ] || {
        log "Everything is up to date"
        return
    }

    log "Packages to update: ${outdated% }"

    # Tell 'pkg_build' to always prompt before build.
    pkg_update=1

    # Build all packages requiring an update.
    # See [1] at top of script.
    # shellcheck disable=2046,2086
    pkg_build $outdated

    log "Updated all packages"
}

pkg_clean() {
    # Clean up on exit or error. This removes everything related
    # to the build.
    stty -F /dev/tty echo 2>/dev/null

    # Block 'Ctrl+C' while cache is being cleaned.
    trap '' INT

    # Remove temporary items.
    rm -rf -- "$mak_dir" "$pkg_dir" "$tar_dir" "$cac_dir/$pid-m"
}

args() {
    # Parse script arguments manually. POSIX 'sh' has no 'getopts'
    # or equivalent built in. This is rather easy to do in our case
    # since the first argument is always an "action" and the arguments
    # that follow are all package names.
    action=$1

    # 'dash' exits on error here if 'shift' is used and there are zero
    # arguments despite trapping the error ('|| :').
    shift "$(($# > 0 ? 1 : 0))"

    # Unless this is a search, sanitize the user's input. The call to
    # 'pkg_find()' supports basic globbing, ensure input doesn't expand
    # to anything except for when this behavior is needed.
    #
    # This handles the globbing characters '*', '!', '[' and ']' as per:
    # https://pubs.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html
    case $action in
        a|alternatives|s|search) ;;

        *)
            case $@ in
                *'*'*|*'!'*|*'['*|*']'*)
                    die "Arguments contain invalid characters: '!*[]'"
                ;;
            esac
    esac

    # Parse some arguments earlier to remove the need to duplicate code.
    case $action in
        c|checksum|s|search|i|install|r|remove)
            [ "$1" ] || die "'kiss $action' requires an argument"
        ;;
    esac

    # Actions can be abbreviated to their first letter. This saves
    # keystrokes once you memorize the commands.
    case $action in
        a|alternatives)
            if [ "$1" = - ]; then
                while read -r pkg path; do
                    pkg_swap "$pkg" "$path"
                done

            elif [ "$1" ]; then
                pkg_swap "$@"

            else
                log "Alternatives:"

                # Go to the choices directory and hide errors
                # as there is nothing to list if the directory
                # doesn't exist.
                cd "$sys_db/../choices" 2>/dev/null
                set +f

                # Go over each alternative and format the file
                # name for listing. (pkg_name>usr>bin>ls)
                for pkg in *; do
                    [ "$pkg" = '*' ] || printf '%s\n' "$pkg"
                done | sed 's|>| /|;s|>|/|g'
            fi
        ;;

        b|build)
            # If no arguments were passed, rebuild all packages.
            [ "$1" ] || {
                cd "$sys_db" || die "Failed to find package db"

                # Use a glob after 'cd' to generate a list of all installed
                # packages based on directory names.
                set +f; set -f -- *

                # Undo the above 'cd' to ensure we stay in the same location.
                cd - >/dev/null
            }

            pkg_build "$@"
        ;;

        c|checksum)
            for pkg; do pkg_lint    "$pkg"; done
            for pkg; do pkg_sources "$pkg" c; done
            for pkg; do
                pkg_checksums "$pkg" > "$(pkg_find "$pkg")/checksums"

                log "$pkg" "Generated checksums"
            done
        ;;

        i|install)
            # Create a list of each package's dependencies.
            for pkg; do
                case $pkg in
                    *.tar.gz) deps="$deps $pkg " ;;
                    *)        pkg_depends "$pkg" install
                esac
            done

            # Filter the list, only installing explicit packages.
            # The purpose of these two loops is to order the
            # argument list based on dependence.
            for pkg in $deps; do
                ! contains "$*" "$pkg" || pkg_install "$pkg"
            done
        ;;

        r|remove)
            log "Removing packages"

            # Create a list of each package's dependencies.
            for pkg; do pkg_depends "$pkg" remove; done

            # Reverse the list of dependencies filtering out anything
            # not explicitly set for removal.
            for pkg in $deps; do
                contains "$*" "$pkg" && remove_pkgs="$pkg $remove_pkgs"
            done

            for pkg in $remove_pkgs; do
                pkg_list "$pkg" >/dev/null ||
                    die "$pkg" "Not installed"

                pkg_remove "$pkg" "${KISS_FORCE:-check}"
            done
        ;;

        l|list)
            pkg_list "$@"
        ;;

        u|update)
            pkg_updates
        ;;

        s|search)
            for pkg; do pkg_find "$pkg" all; done
        ;;

        v|version|-v|--version)
            log kiss 1.0.5
        ;;

        h|help|-h|--help|'')
            log 'kiss [a|b|c|i|l|r|s|u|v] [pkg] [pkg] [pkg]'
            log 'alternatives: List and swap to alternatives'
            log 'build:        Build a package'
            log 'checksum:     Generate checksums'
            log 'install:      Install a package'
            log 'list:         List installed packages'
            log 'remove:       Remove a package'
            log 'search:       Search for a package'
            log 'update:       Check for updates'
            log 'version:      Package manager version'
        ;;

        *) die "'kiss $action' is not a valid command" ;;
    esac
}

main() {
    # Ensure that debug mode is never enabled to prevent internal
    # package manager information from leaking to stdout.
    set +x

    # Prevent the package manager from running as root. The package
    # manager will elevate permissions where needed.
    [ "$(id -u)" != 0 ] || [ "$KISS_ASROOT" ] || {
        log "kiss must be run as a normal user" "" "!>"
        die "(Run with KISS_ASROOT=1 to ignore this warning)"
    }

    # Use the most secure method of sending data over stdin based on
    # whether or not the 'printf' command is built into the shell.
    [ "$(command -v printf)" = printf ] || heredocs=1

    # Set the location to the repository and package database.
    pkg_db=var/db/kiss/installed

    # The PID of the current shell process is used to isolate directories
    # to each specific KISS instance. This allows multiple package manager
    # instances to be run at once. Store the value in another variable so
    # that it doesn't change beneath us.
    pid=${KISS_PID:-$$}

    # Store the original value of IFS so we can revert back to it if the
    # variable is ever changed.
    old_ifs=$IFS

    # Catch errors and ensure that build files and directories are cleaned
    # up before we die. This occurs on 'Ctrl+C' as well as success and error.
    trap pkg_clean EXIT INT

    # Prefer GNU grep if installed as it is much much faster than busybox's
    # implementation. Very much worth it if you value performance over
    # POSIX correctness.
    grep=$(command -v ggrep) || grep='grep'

    # Store the date and time of script invocation to be used as the name
    # of the log files the package manager creates uring builds.
    time=$(date '+%d-%m-%Y-%H:%M')

    # This allows for automatic setup of a KISS chroot and will
    # do nothing on a normal system.
    mkdir -p "${sys_db:=$KISS_ROOT/$pkg_db}" 2>/dev/null ||:

    # Create the required temporary directories and set the variables
    # which point to them.
    mkdir -p "${cac_dir:=$KISS_ROOT${XDG_CACHE_HOME:-$HOME/.cache}/kiss}" \
             "${mak_dir:=$cac_dir/build-$pid}" \
             "${pkg_dir:=$cac_dir/pkg-$pid}" \
             "${tar_dir:=$cac_dir/extract-$pid}" \
             "${src_dir:=$cac_dir/sources}" \
             "${log_dir:=$cac_dir/logs}" \
             "${bin_dir:=$cac_dir/bin}" \
        || die "Couldn't create cache directories"

    args "$@"
}

main "$@"