@astrofoundry/pi-astro 0.31.0 → 0.33.0

package/specialists/entry/specialist-install.sh

@@ -0,0 +1,459 @@
+#!/bin/sh
+# /usr/local/sbin/specialist-install: installs the specialist user's Node, wrappers,
+# arcane-cli, and trendarr from downloads it checks itself. Installed root-owned 0755.
+# Runs as root through
+#   cortex ALL=(root) NOPASSWD: /usr/local/sbin/specialist-install
+# It runs only system binaries and the Node it installed, never anything the cortex
+# user can write (all of Homebrew), and it touches the specialist's home only as that
+# user, so links the specialist plants there cannot redirect a root write.
+#
+#   specialist-install node|wrappers|arcane-cli|trendarr <version>
+#   specialist-install rollback node|wrappers|arcane-cli|trendarr
+#   specialist-install status
+set -eu
+PATH=/usr/bin:/bin:/usr/sbin:/sbin
+export PATH
+umask 077
+cd /
+
+SPECIALIST=specialist
+NODE_BASE=/usr/local/libexec/specialist-node
+# Same list as the allowlist in specialist-cli; a new specialist needs both reinstalled.
+SERVICES="arcane identity network dns edge security backup proxmox inference media"
+
+usage() {
+  echo "usage: specialist-install node|wrappers|arcane-cli|trendarr <version> | rollback node|wrappers|arcane-cli|trendarr | status" >&2
+  exit 2
+}
+
+fail() {
+  echo "specialist-install: $*" >&2
+  exit 1
+}
+
+# x.y.z with plain decimal parts; the character check also rules out newlines.
+valid_version() {
+  case "$1" in '' | *[!0-9.]*) return 1 ;; esac
+  printf '%s\n' "$1" | /usr/bin/grep -Eq '^(0|[1-9][0-9]{0,5})\.(0|[1-9][0-9]{0,5})\.(0|[1-9][0-9]{0,5})$'
+}
+
+# True when version $1 is older than version $2.
+version_lt() {
+  old_ifs=$IFS
+  IFS=.
+  set -- $1 $2
+  IFS=$old_ifs
+  [ "$1" -lt "$4" ] && return 0
+  [ "$1" -gt "$4" ] && return 1
+  [ "$2" -lt "$5" ] && return 0
+  [ "$2" -gt "$5" ] && return 1
+  [ "$3" -lt "$6" ]
+}
+
+component_ok() {
+  case "$1" in node | wrappers | arcane-cli | trendarr) return 0 ;; esac
+  return 1
+}
+
+command=${1:-}
+case "$command" in
+  node | wrappers | arcane-cli | trendarr)
+    [ $# -eq 2 ] || usage
+    valid_version "$2" || usage
+    ;;
+  rollback)
+    [ $# -eq 2 ] || usage
+    component_ok "$2" || usage
+    ;;
+  status) [ $# -eq 1 ] || usage ;;
+  *) usage ;;
+esac
+
+[ "$(/usr/bin/id -u)" = 0 ] || fail "must run as root: sudo /usr/local/sbin/specialist-install $*"
+[ "$(/usr/bin/uname -s)" = Darwin ] && [ "$(/usr/bin/uname -m)" = arm64 ] || fail "only macOS on arm64 is supported"
+/usr/bin/id -u "$SPECIALIST" >/dev/null 2>&1 || fail "user $SPECIALIST does not exist"
+
+work=$(/usr/bin/mktemp -d /private/var/tmp/specialist-install.XXXXXX)
+trap '/bin/rm -rf "$work"' EXIT
+trap 'exit 1' HUP INT TERM
+
+# A directory only root can change: owned by uid 0, not a link, writable by nobody else.
+check_root_dir() {
+  [ -d "$1" ] && [ ! -L "$1" ] || fail "$1 is not a directory"
+  set -- "$1" $(/usr/bin/stat -f '%u %Lp' "$1")
+  [ "$2" = 0 ] || fail "$1 is not owned by root"
+  case "$3" in *[2367] | *[2367]?) fail "$1 is writable by group or others" ;; esac
+}
+
+ensure_root_dir() {
+  [ -e "$1" ] || { /bin/mkdir -m 0755 "$1" && /usr/sbin/chown root:wheel "$1"; }
+  check_root_dir "$1"
+}
+
+check_node_base() {
+  check_root_dir /
+  check_root_dir /usr
+  check_root_dir /usr/local
+  ensure_root_dir /usr/local/libexec
+  ensure_root_dir "$NODE_BASE"
+}
+
+fetch() {
+  /usr/bin/curl --proto '=https' --proto-redir '=https' --tlsv1.2 -fsSL --retry 2 --max-time 900 -o "$2" "$1" || fail "download failed: $1"
+}
+
+json_field() {
+  /usr/bin/plutil -extract "$2" raw -o - "$1" 2>/dev/null
+}
+
+# $1 directory, $2 file name in it, $3 a "<sha256>  <name>" list.
+check_sha256() {
+  want=$(/usr/bin/awk -v f="$2" '$2 == f && length($1) == 64 { print $1; exit }' "$3")
+  [ -n "$want" ] || fail "no checksum for $2"
+  got=$(/usr/bin/shasum -a 256 "$1/$2" | /usr/bin/awk '{ print $1 }')
+  [ "$got" = "$want" ] || fail "checksum mismatch for $2"
+}
+
+# Downloads an npm package tarball after checking it against the registry's sha512 integrity.
+fetch_npm() {
+  meta="$work/$3.meta.json"
+  fetch "https://registry.npmjs.org/$1/$2" "$meta"
+  [ "$(json_field "$meta" version)" = "$2" ] || fail "$1@$2 is not in the npm registry"
+  tarball=$(json_field "$meta" dist.tarball) || fail "$1@$2 has no tarball"
+  integrity=$(json_field "$meta" dist.integrity) || fail "$1@$2 has no integrity"
+  case "$tarball" in https://registry.npmjs.org/*) ;; *) fail "unexpected tarball location for $1@$2" ;; esac
+  fetch "$tarball" "$work/$3.tgz"
+  [ "sha512-$(/usr/bin/openssl dgst -sha512 -binary "$work/$3.tgz" | /usr/bin/base64)" = "$integrity" ] || fail "integrity mismatch for $1@$2"
+}
+
+# Runs a script as the specialist user with fixed arguments; the script never sees root's environment.
+as_specialist() {
+  script=$1
+  shift
+  /usr/bin/sudo -n -u "$SPECIALIST" -H /bin/sh -c "set -eu; umask 077; PATH=/usr/bin:/bin:/usr/sbin:/sbin; cd \"\$HOME\"; $script" specialist-install "$@"
+}
+
+# Root-owned staging for files the specialist then copies into its home.
+make_stage() {
+  /bin/chmod 0711 "$work"
+  stage="$work/stage"
+  /bin/mkdir -m 0700 "$stage"
+}
+
+hand_stage() {
+  /usr/sbin/chown -R "$SPECIALIST:$(/usr/bin/id -gn "$SPECIALIST")" "$stage"
+}
+
+node_link() {
+  target=$(/usr/bin/readlink "$NODE_BASE/$1" 2>/dev/null) || return 0
+  valid_version "$target" && [ -x "$NODE_BASE/$target/bin/node" ] && printf '%s' "$target"
+  return 0
+}
+
+switch_node_link() {
+  /bin/rm -f "$NODE_BASE/.$1.tmp"
+  (umask 022 && /bin/ln -s "$2" "$NODE_BASE/.$1.tmp")
+  /bin/mv -h "$NODE_BASE/.$1.tmp" "$NODE_BASE/$1"
+}
+
+current_node() {
+  node=$(node_link current)
+  [ -n "$node" ] || fail "no specialist Node yet: run specialist-install node <version> first"
+  printf '%s' "$NODE_BASE/$node/bin/node"
+}
+
+# Specialist side: every installed wrapper answers --help with Node $1; nothing to check before the first install.
+SMOKE_INSTALLED='node=$1; shift
+bin="$HOME/.specialists/bin"
+[ -d "$bin/lib" ] || exit 0
+for s in "$@"; do
+  "$node" --disable-warning=ExperimentalWarning "$bin/$s/run.ts" --caller specialist-install -- --help >/dev/null 2>&1 || { echo "$s --help failed with $node" >&2; exit 1; }
+done'
+
+smoke_installed_wrappers() {
+  as_specialist "$SMOKE_INSTALLED" "$1" $SERVICES
+}
+
+install_node() {
+  version=$1
+  check_node_base
+  current=$(node_link current)
+  if [ -n "$current" ] && version_lt "$version" "$current"; then fail "node $version is older than the installed $current; use rollback"; fi
+  [ "$current" != "$version" ] || { echo "node $version is already current"; return 0; }
+
+  fetch https://nodejs.org/dist/index.json "$work/index.json"
+  i=0
+  found=""
+  while [ "$i" -lt 400 ]; do
+    v=$(json_field "$work/index.json" "$i.version") || break
+    if [ "$v" = "v$version" ]; then found=$i; break; fi
+    i=$((i + 1))
+  done
+  [ -n "$found" ] || fail "node $version is not among the 400 newest releases"
+  [ "$(json_field "$work/index.json" "$found.lts")" != false ] || fail "node $version is not an LTS release"
+  /usr/bin/plutil -extract "$found.files" json -o - "$work/index.json" | /usr/bin/grep -q '"osx-arm64-tar"' || fail "node $version has no macOS arm64 build"
+
+  name="node-v$version-darwin-arm64.tar.gz"
+  fetch "https://nodejs.org/dist/v$version/$name" "$work/$name"
+  fetch "https://nodejs.org/dist/v$version/SHASUMS256.txt" "$work/SHASUMS256.txt"
+  check_sha256 "$work" "$name" "$work/SHASUMS256.txt"
+
+  dest="$NODE_BASE/$version"
+  /bin/rm -rf "$dest.partial"
+  /bin/mkdir -m 0755 "$dest.partial"
+  /usr/bin/tar -xzf "$work/$name" -C "$dest.partial" --strip-components 1
+  /usr/sbin/chown -R root:wheel "$dest.partial"
+  /bin/chmod -R u=rwX,go=rX "$dest.partial"
+  [ "$("$dest.partial/bin/node" --version)" = "v$version" ] || fail "node $version does not run"
+  /bin/rm -rf "$dest"
+  /bin/mv "$dest.partial" "$dest"
+  smoke_installed_wrappers "$dest/bin/node" || fail "the installed wrappers fail with node $version; current stays ${current:-unset}"
+
+  [ -z "$current" ] || switch_node_link previous "$current"
+  switch_node_link current "$version"
+  for d in "$NODE_BASE"/*; do
+    n=${d##*/}
+    case "$n" in current | previous | "$version" | "$current") continue ;; esac
+    /bin/rm -rf "$d"
+  done
+  echo "node $version is current${current:+; previous $current}"
+}
+
+rollback_node() {
+  check_node_base
+  current=$(node_link current)
+  previous=$(node_link previous)
+  [ -n "$current" ] && [ -n "$previous" ] || fail "no previous node to roll back to"
+  smoke_installed_wrappers "$NODE_BASE/$previous/bin/node" || fail "the installed wrappers fail with node $previous"
+  switch_node_link current "$previous"
+  switch_node_link previous "$current"
+  echo "node $previous is current; previous $current"
+}
+
+WRAPPER_VERSION='v=$(cat "$HOME/.specialists/bin/VERSION" 2>/dev/null) || exit 0; printf "%s" "$v"'
+
+# Moves the new wrapper files in and the old ones aside, two renames per item, then
+# checks every wrapper; on failure the old files come back.
+SWAP_WRAPPERS='node=$1; stage=$2; shift 2
+bin="$HOME/.specialists/bin"; back="$HOME/.specialists/rollback/wrappers"
+items="lib provision.sh VERSION $*"
+smoke() { d=$1; shift; for s in "$@"; do "$node" --disable-warning=ExperimentalWarning "$d/$s/run.ts" --caller specialist-install -- --help >/dev/null 2>&1 || { echo "$s --help failed" >&2; return 1; }; done; }
+smoke "$stage" "$@" || exit 1
+mkdir -p "$bin" "$HOME/.specialists/rollback"
+rm -rf "$back.new"; mkdir "$back.new"
+for i in $items; do rm -rf "$bin/.new-$i"; cp -R "$stage/$i" "$bin/.new-$i"; done
+for i in $items; do
+  [ ! -e "$bin/$i" ] || mv "$bin/$i" "$back.new/$i"
+  mv "$bin/.new-$i" "$bin/$i"
+done
+chmod -R go-rwx "$bin"
+if ! smoke "$bin" "$@"; then
+  for i in $items; do rm -rf "$bin/$i"; [ ! -e "$back.new/$i" ] || mv "$back.new/$i" "$bin/$i"; done
+  rm -rf "$back.new"
+  echo "restored the previous wrappers" >&2
+  exit 1
+fi
+rm -rf "$back"; mv "$back.new" "$back"'
+
+install_wrappers() {
+  version=$1
+  node=$(current_node)
+  current=$(as_specialist "$WRAPPER_VERSION")
+  valid_version "$current" || current=""
+  if [ -n "$current" ] && version_lt "$version" "$current"; then fail "wrappers $version are older than the installed $current; use rollback"; fi
+
+  fetch_npm @astrofoundry/pi-astro "$version" pi-astro
+  /bin/mkdir "$work/pkg"
+  /usr/bin/tar -xzf "$work/pi-astro.tgz" -C "$work/pkg" --strip-components 1
+  src="$work/pkg/specialists"
+  [ -d "$src/lib" ] && [ -f "$src/provision/provision.sh" ] || fail "pi-astro $version has no specialists/lib or provision.sh"
+  make_stage
+  /bin/cp -R "$src/lib" "$stage/lib"
+  for s in $SERVICES; do
+    [ -f "$src/$s/run.ts" ] || fail "pi-astro $version has no $s wrapper"
+    /bin/mkdir "$stage/$s"
+    /bin/cp "$src/$s/run.ts" "$stage/$s/run.ts"
+  done
+  /bin/cp "$src/provision/provision.sh" "$stage/provision.sh"
+  /usr/bin/find "$stage" -type f -name '*.test.ts' -delete
+  printf '%s\n' "$version" > "$stage/VERSION"
+  hand_stage
+  as_specialist "$SWAP_WRAPPERS" "$node" "$stage" $SERVICES || fail "wrappers $version failed their check; ${current:-no} previous version kept"
+  echo "wrappers $version installed${current:+; previous $current}"
+}
+
+ROLLBACK_WRAPPERS='node=$1; shift
+bin="$HOME/.specialists/bin"; back="$HOME/.specialists/rollback/wrappers"
+[ -f "$back/VERSION" ] || { echo "no previous wrappers to roll back to" >&2; exit 1; }
+items="lib provision.sh VERSION $*"
+swap() { for i in $items; do
+  [ ! -e "$bin/$i" ] || mv "$bin/$i" "$bin/.old-$i"
+  [ ! -e "$back/$i" ] || mv "$back/$i" "$bin/$i"
+  [ ! -e "$bin/.old-$i" ] || mv "$bin/.old-$i" "$back/$i"
+done; }
+swap
+for s in "$@"; do
+  "$node" --disable-warning=ExperimentalWarning "$bin/$s/run.ts" --caller specialist-install -- --help >/dev/null 2>&1 || { swap; echo "$s --help failed; nothing changed" >&2; exit 1; }
+done
+cat "$bin/VERSION"'
+
+rollback_wrappers() {
+  node=$(current_node)
+  restored=$(as_specialist "$ROLLBACK_WRAPPERS" "$node" $SERVICES) || fail "wrapper rollback failed"
+  echo "wrappers $restored restored"
+}
+
+ARCANE_VERSION='out=$("$HOME/.specialists/bin/arcane-cli" --version 2>/dev/null) || exit 0
+printf "%s\n" "$out" | awk '"'"'{ for (i = 1; i < NF; i++) if ($i == "version") { print $(i + 1); exit } }'"'"''
+
+INSTALL_ARCANE='stage=$1; v=$2
+bin="$HOME/.specialists/bin"
+check() { "$1" --version 2>/dev/null | awk -v v="$v" '"'"'{ for (i = 1; i < NF; i++) if ($i == "version" && $(i + 1) == v) f = 1 } END { exit !f }'"'"'; }
+mkdir -p "$bin"
+cp "$stage/arcane-cli" "$bin/.arcane-cli.new"
+chmod 0700 "$bin/.arcane-cli.new"
+check "$bin/.arcane-cli.new" || { rm -f "$bin/.arcane-cli.new"; echo "the new arcane-cli does not report version $v" >&2; exit 1; }
+had=no
+if [ -e "$bin/arcane-cli" ]; then mv "$bin/arcane-cli" "$bin/arcane-cli.previous"; had=yes; fi
+mv "$bin/.arcane-cli.new" "$bin/arcane-cli"
+if ! check "$bin/arcane-cli"; then
+  rm -f "$bin/arcane-cli"
+  [ "$had" = no ] || mv "$bin/arcane-cli.previous" "$bin/arcane-cli"
+  echo "restored the previous arcane-cli" >&2
+  exit 1
+fi'
+
+install_arcane_cli() {
+  version=$1
+  current=$(as_specialist "$ARCANE_VERSION")
+  valid_version "$current" || current=""
+  if [ -n "$current" ] && version_lt "$version" "$current"; then fail "arcane-cli $version is older than the installed $current; use rollback"; fi
+
+  asset=arcane-cli_darwin_arm64.tar.gz
+  base="https://github.com/getarcaneapp/arcane/releases/download/v$version"
+  fetch "$base/$asset" "$work/$asset"
+  fetch "$base/arcane_${version}_checksums.txt" "$work/checksums.txt"
+  check_sha256 "$work" "$asset" "$work/checksums.txt"
+  /bin/mkdir "$work/acli"
+  /usr/bin/tar -xzf "$work/$asset" -C "$work/acli"
+  cli=$(/usr/bin/find "$work/acli" -type f -name arcane-cli | /usr/bin/head -n 1)
+  [ -n "$cli" ] || fail "no arcane-cli binary in $asset"
+  make_stage
+  /bin/cp "$cli" "$stage/arcane-cli"
+  hand_stage
+  as_specialist "$INSTALL_ARCANE" "$stage" "$version" || fail "arcane-cli $version failed its check"
+  echo "arcane-cli $version installed${current:+; previous $current}"
+}
+
+ROLLBACK_ARCANE='bin="$HOME/.specialists/bin"
+[ -e "$bin/arcane-cli.previous" ] || { echo "no previous arcane-cli to roll back to" >&2; exit 1; }
+mv "$bin/arcane-cli" "$bin/.arcane-cli.old"
+mv "$bin/arcane-cli.previous" "$bin/arcane-cli"
+mv "$bin/.arcane-cli.old" "$bin/arcane-cli.previous"
+"$bin/arcane-cli" --version'
+
+rollback_arcane_cli() {
+  out=$(as_specialist "$ROLLBACK_ARCANE") || fail "arcane-cli rollback failed"
+  echo "restored $out"
+}
+
+# trendarr lives in versioned directories behind the stable link bin/trendarr, so
+# media.json's trendarrCli path never changes; bin/trendarr.previous keeps the last one.
+TRENDARR_COMMON='bin="$HOME/.specialists/bin"
+cli() { printf "%s/node_modules/@astrofoundry/trendarr/dist/cli.js" "$1"; }
+version_of() { plutil -extract version raw -o - "$1/node_modules/@astrofoundry/trendarr/package.json" 2>/dev/null; }
+link() { rm -f "$bin/.$1.tmp"; ln -s "$2" "$bin/.$1.tmp"; mv -h "$bin/.$1.tmp" "$bin/$1"; }'
+
+TRENDARR_VERSION="$TRENDARR_COMMON"'
+[ -e "$bin/trendarr" ] || exit 0
+version_of "$bin/trendarr" || exit 0'
+
+# A hand-installed bin/trendarr directory (the first media setup) becomes trendarr-<version>
+# behind the link; one without a readable package moves aside to bin/trendarr.unknown.
+INSTALL_TRENDARR="$TRENDARR_COMMON"'
+node=$1; npm=$2; v=$3
+if [ -d "$bin/trendarr" ] && [ ! -L "$bin/trendarr" ]; then
+  old=$(version_of "$bin/trendarr" || true)
+  case "$old" in
+    "" | *[!0-9.]*) rm -rf "$bin/trendarr.unknown"; mv "$bin/trendarr" "$bin/trendarr.unknown" ;;
+    *) rm -rf "$bin/trendarr-$old"; mv "$bin/trendarr" "$bin/trendarr-$old"; link trendarr "trendarr-$old" ;;
+  esac
+fi
+dir="$bin/trendarr-$v"
+mkdir -p "$bin"
+rm -rf "$dir.partial"
+"$node" "$npm" install --prefix "$dir.partial" --omit=dev --ignore-scripts --no-audit --no-fund --no-update-notifier "@astrofoundry/trendarr@$v" >/dev/null
+[ "$("$node" "$(cli "$dir.partial")" --version)" = "$v" ] || { rm -rf "$dir.partial"; echo "trendarr $v does not report its version" >&2; exit 1; }
+before=$(readlink "$bin/trendarr" 2>/dev/null || true)
+rm -rf "$dir"
+mv "$dir.partial" "$dir"
+link trendarr "trendarr-$v"
+if [ "$("$node" "$(cli "$bin/trendarr")" --version)" != "$v" ]; then
+  if [ -n "$before" ]; then link trendarr "$before"; else rm -f "$bin/trendarr"; fi
+  echo "restored the previous trendarr" >&2
+  exit 1
+fi
+if [ -n "$before" ] && [ "$before" != "trendarr-$v" ]; then link trendarr.previous "$before"; fi
+keep=$(readlink "$bin/trendarr.previous" 2>/dev/null || true)
+for d in "$bin"/trendarr-*; do
+  [ -d "$d" ] || continue
+  n=${d##*/}
+  [ "$n" = "trendarr-$v" ] || [ "$n" = "$keep" ] || rm -rf "$d"
+done'
+
+install_trendarr() {
+  version=$1
+  node=$(current_node)
+  npm="${node%/bin/node}/lib/node_modules/npm/bin/npm-cli.js"
+  [ -f "$npm" ] || fail "the specialist Node has no npm"
+  current=$(as_specialist "$TRENDARR_VERSION")
+  valid_version "$current" || current=""
+  if [ -n "$current" ] && version_lt "$version" "$current"; then fail "trendarr $version is older than the installed $current; use rollback"; fi
+  [ "$current" != "$version" ] || { echo "trendarr $version is already current"; return 0; }
+  as_specialist "$INSTALL_TRENDARR" "$node" "$npm" "$version" || fail "trendarr $version failed its check"
+  echo "trendarr $version installed${current:+; previous $current}"
+}
+
+ROLLBACK_TRENDARR="$TRENDARR_COMMON"'
+node=$1
+previous=$(readlink "$bin/trendarr.previous" 2>/dev/null) || { echo "no previous trendarr to roll back to" >&2; exit 1; }
+current=$(readlink "$bin/trendarr")
+[ -d "$bin/$previous" ] || { echo "$previous is missing" >&2; exit 1; }
+link trendarr "$previous"
+link trendarr.previous "$current"
+"$node" "$(cli "$bin/trendarr")" --version'
+
+rollback_trendarr() {
+  node=$(current_node)
+  out=$(as_specialist "$ROLLBACK_TRENDARR" "$node") || fail "trendarr rollback failed"
+  echo "trendarr $out restored"
+}
+
+json_version() {
+  if valid_version "$1"; then printf '"%s"' "$1"; else printf 'null'; fi
+}
+
+status() {
+  wrappers=$(as_specialist "$WRAPPER_VERSION" || true)
+  arcane=$(as_specialist "$ARCANE_VERSION" || true)
+  trendarr=$(as_specialist "$TRENDARR_VERSION" || true)
+  printf '{"node":{"current":%s,"previous":%s},"wrappers":%s,"arcaneCli":%s,"trendarr":%s}\n' \
+    "$(json_version "$(node_link current)")" "$(json_version "$(node_link previous)")" \
+    "$(json_version "$wrappers")" "$(json_version "$arcane")" "$(json_version "$trendarr")"
+}
+
+case "$command" in
+  node) install_node "$2" ;;
+  wrappers) install_wrappers "$2" ;;
+  arcane-cli) install_arcane_cli "$2" ;;
+  trendarr) install_trendarr "$2" ;;
+  rollback)
+    case "$2" in
+      node) rollback_node ;;
+      wrappers) rollback_wrappers ;;
+      arcane-cli) rollback_arcane_cli ;;
+      trendarr) rollback_trendarr ;;
+    esac
+    ;;
+  status) status ;;
+esac

package/specialists/entry/specialist-install.test.ts

@@ -0,0 +1,95 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const SCRIPT = join(import.meta.dirname, "specialist-install.sh");
+const ENTRY = join(import.meta.dirname, "specialist-cli.sh");
+// As root the script would really install; these tests only exercise what runs before the root check.
+const isRoot = process.getuid?.() === 0;
+
+function install(...args: string[]) {
+    return spawnSync("/bin/sh", [SCRIPT, ...args], { encoding: "utf-8" });
+}
+
+/** Runs one shell function of the script on its own, followed by `call`. */
+function shellFunction(name: string, call: string) {
+    const match = new RegExp(`^${name}\\(\\) \\{\\n[\\s\\S]*?^\\}`, "m").exec(readFileSync(SCRIPT, "utf-8"));
+    if (!match) throw new Error(`${name} not found in the script`);
+    return spawnSync("/bin/sh", ["-c", `${match[0]}\n${call}`], { encoding: "utf-8" });
+}
+
+describe("specialist-install", () => {
+    it("parses as POSIX sh", () => {
+        expect(spawnSync("/bin/sh", ["-n", SCRIPT]).status).toBe(0);
+    });
+
+    it.each([
+        [[]],
+        [["upgrade", "1.2.3"]],
+        [["node"]],
+        [["node", "24.22"]],
+        [["node", "v24.22.0"]],
+        [["node", "024.22.0"]],
+        [["node", "24.22.0\nrm"]],
+        [["node", "24.22.0", "extra"]],
+        [["wrappers", "../../1.2.3"]],
+        [["arcane-cli", "2.16.1-beta"]],
+        [["trendarr", ""]],
+        [["rollback"]],
+        [["rollback", "pi"]],
+        [["rollback", "node", "extra"]],
+        [["status", "now"]],
+    ])("refuses %j with a usage error before anything else", (args) => {
+        const result = install(...args);
+        expect(result.status).toBe(2);
+        expect(result.stderr).toMatch(/^usage: specialist-install/);
+    });
+
+    it.skipIf(isRoot).each([[["node", "24.22.0"]], [["wrappers", "0.31.0"]], [["arcane-cli", "2.16.1"]], [["trendarr", "0.6.0"]], [["rollback", "trendarr"]], [["status"]]])(
+        "accepts %j and then requires root",
+        (args) => {
+            const result = install(...args);
+            expect(result.status).toBe(1);
+            expect(result.stderr).toContain("must run as root");
+        },
+    );
+
+    it.each(["0.0.0", "1.2.3", "24.22.0", "2.16.1", "100000.0.1"])("valid_version accepts %s", (v) => {
+        expect(shellFunction("valid_version", `valid_version '${v}'`).status).toBe(0);
+    });
+
+    it.each(["", "1.2", "1.2.3.4", "01.2.3", "1.2.3a", "-1.2.3", "1..3", "1000000.0.0"])("valid_version rejects %j", (v) => {
+        expect(shellFunction("valid_version", `valid_version '${v}'`).status).toBe(1);
+    });
+
+    it.each([
+        ["24.21.0", "24.22.0", true],
+        ["24.22.0", "24.22.0", false],
+        ["24.22.1", "24.22.0", false],
+        ["2.9.9", "2.16.1", true],
+        ["10.0.0", "9.99.99", false],
+        ["0.6.0", "0.31.0", true],
+    ])("version_lt %s < %s is %s", (a, b, older) => {
+        expect(shellFunction("version_lt", `version_lt ${a} ${b}`).status).toBe(older ? 0 : 1);
+    });
+
+    it("installs the same services specialist-cli accepts", () => {
+        const services = /^SERVICES="([^"]+)"$/m.exec(readFileSync(SCRIPT, "utf-8"))?.[1].split(" ");
+        const allowed = /^ {2}([a-z|]+)\) ;;$/m.exec(readFileSync(ENTRY, "utf-8"))?.[1].split("|");
+        expect(services).toBeDefined();
+        expect(services).toEqual(allowed);
+    });
+
+    it("never runs Homebrew binaries", () => {
+        expect(readFileSync(SCRIPT, "utf-8")).not.toContain("/opt/homebrew");
+    });
+});
+
+describe("specialist-cli", () => {
+    it("runs the wrappers with the root-owned Node only", () => {
+        const text = readFileSync(ENTRY, "utf-8");
+        expect(text).toContain("exec /usr/local/libexec/specialist-node/current/bin/node ");
+        expect(text).not.toContain("/opt/homebrew/bin/node");
+    });
+});