A pluggable update runner in bash 3.2

· 4 min read

os-mindset is my bag of shell snippets for macOS and Debian. Its most used command is os-mindset update, which updates every package manager on the machine. This post covers how I turned that command into a small plugin runner. A separate user guide shows how to use it.

Why: two scripts and one copy-paste

update ran two hard-coded scripts one after the other:

  • lib/common/update: one function each for sdkman and flatpak, called at the bottom.
  • lib/<os>/update: on macOS, brew, JetBrains Toolbox and softwareupdate. On Debian, aptitude full-upgrade, apt autoremove, and a commit of /etc to git.

Adding a package manager meant editing one of those files. Both OS scripts had their own copy of jetbrainsToolboxHome and of define_os-update. The only way to customize them was to export a bash function named os-update. The macOS script also had a librewolf_outdated check whose result was evaluated as a bare true or false, so it did nothing.

How: one file per package manager

The new layout:

lib/update.d/
  common/   10-sdkman  20-flatpak
  macosx/   30-brew  50-jetbrains  90-os
  debian/   50-jetbrains  90-os
~/.os-mindset/update.d/common/     # user plugins, any OS
~/.os-mindset/update.d/<os>/       # user plugins, one OS

A plugin is a bash file that defines up to three things:

plugin_description="flatpak packages"
function plugin_available() { command -v flatpak > /dev/null 2>&1; }
function plugin_run() { flatpak update -y; }

The runner, which replaced lib/common/update, does this:

  1. Collect files from all folders as basename|name|source|path lines and sort them by basename. The NN- prefix gives one global order across common, OS and user folders.
  2. Fail if two plugins share a name. The name is the filename without NN-, so 90-os and 95-os clash too. Nothing runs in that case.
  3. For each plugin, source it in a subshell, read whether it is enabled and available, then source it again in a second subshell and call plugin_run.
  4. Report each failure, keep going, and exit non-zero at the end if anything failed.

Sourcing each plugin in its own subshell matters: every plugin defines the same function names, and none of them can leak into the next one.

Design choices

Duplicates fail; nothing gets overridden. My first draft let a user plugin with the same filename replace the built-in one. I dropped that. Silent replacement makes it hard to see what runs. To replace a built-in, you skip it by name and add your own plugin with a different name.

No backwards compatibility. The os-update function hook and the ~/.os-mindset/osupdate-skip file are gone. A skip list (~/.os-mindset/update-skip or OSM_UPDATE_SKIP) covers both.

Opt-in plugins. On Debian, the JetBrains update was commented out. It is now a plugin with plugin_enabled_default=false, and it runs only if jetbrains is listed in ~/.os-mindset/update-enable.

Bash 3.2

On macOS, /bin/bash is still GNU bash, version 3.2.57. The macOS dispatcher in os-mindset already avoided declare -A for that reason, and the runner does too. Lists are strings padded with spaces, and a membership check is a glob match:

function inList() {
    [[ "$1" == *" $2 "* ]]
}

read -ra, read -u, BASH_REMATCH and process substitution all work on 3.2, and I ran the tests under both 3.2 and 5.3.

Surprises

Plugins need stdin. The main loop first read the plugin list from a here-string on stdin. Any plugin that prompts would then read from that list instead of the terminal. apt autoremove asks for confirmation, so this was a real problem. The fix is to give the list its own file descriptor:

while IFS='|' read -r -u 3 base name origin path; do
    ...
    runPlugin "${path}"
done 3<<< "${plugins}"

update started exiting 1. The entry script ended with:

[[ -x ${__lib}/${osType}/${command} ]] && "${__libFolder}"/"${osType}".bash ...

With lib/macosx/update gone, that test is false, so the script’s last status was 1 even when every plugin succeeded. Now it stores the exit code of the command it ran and exits with it, or with 1 when no command matches.

Options never reached the command. The entry script parsed --os and collected the rest into cmdParams, but it called common commands without arguments. --list and --only were silently dropped. It now passes ${cmdParams} and exports osType, so the runner knows which OS folder to read.

Self-update runs first. My first manual os-mindset update --list also ran git pull on os-mindset itself, because self-update runs before every command. Set OSMINDSET_AUTO_UPDATE=0 when you only want to look.

A doubled prefix. Errors print as update:: update: ERROR: unknown option --bogus. showErr adds the prefix that showMsg already adds. That bug is older than this change and is still there.

Tests

The tests use shUnit2. Each test creates a temporary config folder and points the runner at fixture plugins with OSM_UPDATE_BUILTIN, so nothing real gets updated. Each fixture plugin appends its own filename to a log, and the tests compare that log with the expected order:

assertEquals "10-sdkman 40-npm 50-mine 60-extra 90-os " "$(ran)"

The tests cover order, user plugins, every kind of duplicate, skip and enable lists, --only, --list, and a failing plugin that does not stop the others. All 16 pass.