Chasing down library bugs in the screenpipe AppImage

#!/usr/bin/env bash
# screenpipe-appimage-debug — automates the AppImage library-debugging method
# from the "AppImage Library Debugging" guide: extract, inventory bundled
# libs, diff against the system, flag suspects, optionally patch/repackage,
# optionally verify.
#
# Subcommands:
#   inspect  <appimage> [workdir]         extract (if needed) + report suspects
#   patch    <workdir> [--auto|--lib X|--dir Y]   apply fixes into squashfs-root
#   package  <workdir> <output.appimage>  repackage squashfs-root
#   verify   <appimage> [--real-data] [--seconds N]   run it, grep for signal
#   all      <appimage> [workdir] [--auto] [--real-data]   run the full loop
#
# Nothing here auto-launches the app against your real profile unless you
# pass --real-data explicitly to `verify` (or `all --real-data`).

set -uo pipefail

MIN_MINOR_GAP=2       # flag a version diff at or above this many minor versions
SPARSE_RATIO=3         # flag a plugin dir if system has >= this many times the bundled file count
SPARSE_MIN_SYSTEM=4    # only consider a dir "plugin-shaped" if system side has at least this many files

# Version strings sniffed via `strings` on an arbitrary .so are unreliable —
# most libraries embed unrelated version-shaped numbers (vendored sub-deps,
# Unicode table versions, font-format specs, etc), not their own release
# version. Only compare versions for libraries confirmed (by hand, once) to
# embed a clean, unambiguous self-version string. Extend by exporting
# SCREENPIPE_DEBUG_VERSION_LIBS="libfoo.so.1 libbar.so.2" after you've
# manually verified a library's `strings` output is trustworthy.
VERSION_CHECKED_LIBS="libpipewire-0.3.so.0 ${SCREENPIPE_DEBUG_VERSION_LIBS:-}"

c_bold=$'\033[1m'; c_red=$'\033[31m'; c_grn=$'\033[32m'; c_yel=$'\033[33m'; c_dim=$'\033[2m'; c_off=$'\033[0m'
say()  { printf '%s\n' "$*" >&2; }
info() { say "${c_dim}$*${c_off}"; }
warn() { say "${c_yel}$*${c_off}"; }
good() { say "${c_grn}$*${c_off}"; }
bad()  { say "${c_red}$*${c_off}"; }

usage() {
  sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//'
  exit 1
}

version_of() {
  # extract the first plausible X.Y.Z version string embedded in a binary
  strings -a "$1" 2>/dev/null | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -Vu | head -1
}

system_path_for() {
  # find the system copy of a bundled soname, via ldconfig cache first
  local soname="$1" p
  p=$(ldconfig -p 2>/dev/null | awk -v s="$soname" '$1==s {print $NF; exit}')
  if [ -n "${p:-}" ] && [ -e "$p" ]; then printf '%s\n' "$p"; return 0; fi
  for cand in "/usr/lib/$soname" "/usr/lib64/$soname" "/usr/lib/x86_64-linux-gnu/$soname"; do
    [ -e "$cand" ] && { printf '%s\n' "$cand"; return 0; }
  done
  return 1
}

system_dir_for() {
  # given a bundled dir's path relative to usr/lib, find a same-shaped system dir
  local rel="$1"
  for cand in "/usr/lib/$rel" "/usr/lib64/$rel" "/usr/lib/x86_64-linux-gnu/$rel"; do
    [ -d "$cand" ] && { printf '%s\n' "$cand"; return 0; }
  done
  return 1
}

minor_gap() {
  # prints the |minor_a - minor_b| gap, or 99 if majors differ
  local va="$1" vb="$2"
  local maja min_a majb min_b
  maja=${va%%.*}; min_a=$(printf '%s' "$va" | cut -d. -f2)
  majb=${vb%%.*}; min_b=$(printf '%s' "$vb" | cut -d. -f2)
  if [ "$maja" != "$majb" ]; then printf '99\n'; return; fi
  printf '%s\n' "$(( min_a > min_b ? min_a - min_b : min_b - min_a ))"
}

cmd_extract() {
  local appimage="$1" workdir="$2"
  mkdir -p "$workdir"
  if [ -d "$workdir/squashfs-root" ]; then
    info "reusing existing extraction at $workdir/squashfs-root"
    return 0
  fi
  info "extracting $appimage -> $workdir/squashfs-root"
  ( cd "$workdir" && "$appimage" --appimage-extract >/dev/null )
}

cmd_inspect() {
  local appimage="${1:?usage: inspect <appimage> [workdir]}"
  local workdir="${2:-/tmp/screenpipe-appimage-debug/$(basename "$appimage" .appimage)}"
  appimage="$(readlink -f "$appimage")"
  cmd_extract "$appimage" "$workdir"
  local root="$workdir/squashfs-root"

  say ""
  say "${c_bold}== launcher chain: path overrides ==${c_off}"
  grep -nE 'LD_LIBRARY_PATH|PLUGIN_DIR|_PATH=' "$root"/AppRun "$root"/AppRun.* "$root"/apprun-hooks/*.sh 2>/dev/null \
    | sed "s|$root/||" || info "(none found — check AppRun manually, launcher structure may differ)"

  local libs_report="$workdir/inspect-libs.tsv"
  local dirs_report="$workdir/inspect-dirs.tsv"
  : > "$libs_report"; : > "$dirs_report"

  say ""
  say "${c_bold}== bundled libraries: version check (allowlisted libs only) ==${c_off}"
  info "everything else only gets the missing-deps + plugin-dir checks below — see VERSION_CHECKED_LIBS."
  printf '%-32s %-12s %-12s %s\n' "LIBRARY" "BUNDLED" "SYSTEM" "VERDICT"
  while IFS= read -r -d '' f; do
    local soname bver sver gap verdict spath
    soname=$(basename "$f")
    case " $VERSION_CHECKED_LIBS " in *" $soname "*) : ;; *) continue ;; esac
    bver=$(version_of "$f")
    if spath=$(system_path_for "$soname"); then
      sver=$(version_of "$spath")
    else
      spath=""; sver=""
    fi
    if [ -z "$bver" ] || [ -z "$sver" ]; then
      verdict="no-version-string"
    else
      gap=$(minor_gap "$bver" "$sver")
      if [ "$gap" -ge "$MIN_MINOR_GAP" ]; then verdict="MISMATCH"; else verdict="ok"; fi
    fi
    printf '%-32s %-12s %-12s %s\n' "$soname" "${bver:--}" "${sver:--}" "$verdict"
    printf '%s\t%s\t%s\t%s\t%s\t%s\n' "$f" "$spath" "${bver:-}" "${sver:-}" "$verdict" "$soname" >> "$libs_report"
  done < <(find "$root/usr/lib" -maxdepth 1 -name '*.so*' -type f -print0 2>/dev/null)

  say ""
  say "${c_bold}== missing dependencies (ldd, with the bundle's own LD_LIBRARY_PATH) ==${c_off}"
  local main_bin missing
  main_bin=$(find "$root/usr/bin" -maxdepth 1 -type f | head -1)
  if [ -n "${main_bin:-}" ]; then
    missing=$(LD_LIBRARY_PATH="$root/usr/lib" ldd "$main_bin" 2>&1 | grep -i "not found" || true)
    if [ -n "$missing" ]; then
      bad "$missing"
      warn "these are genuinely unresolved at link time — highest-confidence signal in this whole report."
    else
      good "none — everything the binary links against resolves within the bundle."
    fi
  else
    warn "couldn't find a binary under usr/bin to check"
  fi

  say ""
  say "${c_bold}== plugin-shaped directories vs. system ==${c_off}"
  printf '%-40s %-10s %-10s %s\n' "DIR (relative to usr/lib)" "BUNDLED" "SYSTEM" "VERDICT"
  while IFS= read -r -d '' d; do
    local rel bcount scount sdir verdict
    rel=${d#"$root"/usr/lib/}
    [ "$rel" = "$d" ] && continue
    sdir=$(system_dir_for "$rel") || continue
    bcount=$(find "$d" -name '*.so' -type f 2>/dev/null | wc -l)
    scount=$(find "$sdir" -name '*.so' -type f 2>/dev/null | wc -l)
    [ "$scount" -lt "$SPARSE_MIN_SYSTEM" ] && continue
    if [ "$bcount" -gt 0 ] && [ $(( scount / bcount )) -ge "$SPARSE_RATIO" ]; then
      verdict="SPARSE"
    elif [ "$bcount" -eq 0 ]; then
      verdict="SPARSE"
    else
      verdict="ok"
    fi
    printf '%-40s %-10s %-10s %s\n' "$rel" "$bcount" "$scount" "$verdict"
    printf '%s\t%s\t%s\t%s\t%s\n' "$d" "$sdir" "$bcount" "$scount" "$verdict" >> "$dirs_report"
  done < <(find "$root/usr/lib" -mindepth 1 -maxdepth 3 -type d -print0 2>/dev/null)

  say ""
  local n_mismatch n_sparse
  n_mismatch=$(awk -F'\t' '$5=="MISMATCH"' "$libs_report" | wc -l)
  n_sparse=$(awk -F'\t' '$5=="SPARSE"' "$dirs_report" | wc -l)
  if [ "$n_mismatch" -gt 0 ] || [ "$n_sparse" -gt 0 ]; then
    warn "${n_mismatch} library version mismatch(es), ${n_sparse} sparse plugin dir(s) flagged."
    info "review: $libs_report / $dirs_report"
    info "apply fixes: screenpipe-appimage-debug patch $workdir --auto"
  else
    good "nothing flagged — bundled libs look current relative to this system."
  fi
  say "${c_dim}workdir: $workdir${c_off}"
}

cmd_patch() {
  local workdir="${1:?usage: patch <workdir> [--auto|--lib NAME|--dir NAME]}"; shift
  local root="$workdir/squashfs-root"
  local mode="${1:---auto}"
  [ -d "$root" ] || { bad "no extraction at $root — run inspect first"; exit 1; }

  apply_lib() {
    local bpath="$1" spath="$2"
    if [ -z "$spath" ]; then warn "  skip $bpath — no system match recorded"; return; fi
    cp -L "$spath" "$bpath" && good "  patched $(basename "$bpath")"
  }
  apply_dir() {
    local bdir="$1" sdir="$2"
    if [ -z "$sdir" ]; then warn "  skip $bdir — no system match recorded"; return; fi
    rm -rf "$bdir" && cp -rL "$sdir" "$bdir" && good "  patched dir $(basename "$bdir") ($(find "$bdir" -name '*.so' | wc -l) files)"
  }

  case "$mode" in
    --auto)
      say "${c_bold}patching all MISMATCH/SPARSE findings from last inspect${c_off}"
      [ -f "$workdir/inspect-libs.tsv" ] || { bad "no $workdir/inspect-libs.tsv — run inspect first"; exit 1; }
      while IFS=$'\t' read -r bpath spath bver sver verdict soname; do
        [ "$verdict" = "MISMATCH" ] && apply_lib "$bpath" "$spath"
      done < "$workdir/inspect-libs.tsv"
      while IFS=$'\t' read -r bdir sdir bcount scount verdict; do
        [ "$verdict" = "SPARSE" ] && apply_dir "$bdir" "$sdir"
      done < "$workdir/inspect-dirs.tsv"
      ;;
    --lib)
      local name="${2:?--lib needs a soname, e.g. libpipewire-0.3.so.0}"
      local bpath="$root/usr/lib/$name"
      local spath; spath=$(system_path_for "$name") || { bad "no system copy of $name found"; exit 1; }
      apply_lib "$bpath" "$spath"
      ;;
    --dir)
      local rel="${2:?--dir needs a path relative to usr/lib, e.g. spa-0.2}"
      local bdir="$root/usr/lib/$rel"
      local sdir; sdir=$(system_dir_for "$rel") || { bad "no system copy of $rel found"; exit 1; }
      apply_dir "$bdir" "$sdir"
      ;;
    *) usage ;;
  esac
}

cmd_package() {
  local workdir="${1:?usage: package <workdir> <output.appimage>}"
  local out="${2:?usage: package <workdir> <output.appimage>}"
  local root="$workdir/squashfs-root"
  [ -d "$root" ] || { bad "no extraction at $root"; exit 1; }
  command -v appimagetool >/dev/null || { bad "appimagetool not found on PATH"; exit 1; }
  ARCH=x86_64 appimagetool "$root" "$out"
  good "built $out"
}

cmd_verify() {
  local appimage="${1:?usage: verify <appimage> [--real-data] [--seconds N]}"; shift
  local real_data=0 seconds=30
  while [ $# -gt 0 ]; do
    case "$1" in
      --real-data) real_data=1 ;;
      --seconds) seconds="$2"; shift ;;
    esac
    shift
  done
  appimage="$(readlink -f "$appimage")"
  local log; log=$(mktemp /tmp/screenpipe-verify.XXXXXX.log)

  if [ "$real_data" -eq 1 ]; then
    info "launching against your real profile (HOME/XDG_CONFIG_HOME/XDG_DATA_HOME) for up to ${seconds}s..."
    HOME="$HOME" XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}" XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}" \
      "$appimage" > "$log" 2>&1 &
  else
    warn "launching against an isolated scratch profile — this often never reaches the capture code path;"
    warn "pass --real-data for a conclusive check (see the debugging guide, step 7)."
    local scratch; scratch=$(mktemp -d /tmp/screenpipe-verify-data.XXXXXX)
    SCREENPIPE_DATA_DIR="$scratch" SCREENPIPE_SKIP_ONBOARDING=1 "$appimage" > "$log" 2>&1 &
  fi
  local pid=$!

  local waited=0 result="" pattern_ok='started for|capture started'
  local pattern_bad='Creation failed|cannot open shared object file|panicked at'
  while [ "$waited" -lt "$seconds" ]; do
    if grep -qEi "$pattern_bad" "$log" 2>/dev/null; then result="fail"; break; fi
    if grep -qEi "$pattern_ok" "$log" 2>/dev/null; then result="pass"; break; fi
    sleep 1; waited=$((waited + 1))
  done

  # find the real exec'd binary (AppRun chain), not the launcher pid, and kill it
  sleep 1
  local realpid
  realpid=$(pgrep -f 'screenpipe-app$' | head -1)
  [ -n "${realpid:-}" ] && kill "$realpid" 2>/dev/null
  kill "$pid" 2>/dev/null
  sleep 1
  local mnt
  mnt=$(mount | grep 'fuse.screenpipe' | awk '{print $3}' | head -1)
  if [ -n "${mnt:-}" ]; then
    for _ in 1 2 3 4 5; do
      fusermount -u "$mnt" 2>/dev/null && break
      sleep 1
    done
    mount | grep -q 'fuse.screenpipe' && warn "FUSE mount still busy after retries: $mnt (clean up manually with fusermount -u)"
  fi

  case "$result" in
    pass) good "PASS — capture-started signal seen, no failure signature. log: $log" ;;
    fail) bad  "FAIL — failure signature matched:"; grep -Ei "$pattern_bad" "$log" | head -5; info "log: $log" ;;
    *)    warn "INCONCLUSIVE — neither signal seen in ${seconds}s. log: $log"
          [ "$real_data" -eq 0 ] && warn "  (expected with an isolated profile — retry with --real-data)" ;;
  esac
}

cmd_all() {
  local appimage="${1:?usage: all <appimage> [workdir] [--auto] [--real-data]}"; shift
  local workdir="${1:-/tmp/screenpipe-appimage-debug/$(basename "$appimage" .appimage)}"
  [[ "$workdir" == --* ]] && workdir="/tmp/screenpipe-appimage-debug/$(basename "$appimage" .appimage)" || shift
  local auto=0 real_data=0
  for a in "$@"; do
    [ "$a" = "--auto" ] && auto=1
    [ "$a" = "--real-data" ] && real_data=1
  done

  cmd_inspect "$appimage" "$workdir"
  if [ "$auto" -eq 1 ]; then
    say ""
    cmd_patch "$workdir" --auto
    say ""
    cmd_package "$workdir" "$workdir/screenpipe-fixed.appimage"
    say ""
    cmd_verify "$workdir/screenpipe-fixed.appimage" $( [ "$real_data" -eq 1 ] && echo --real-data )
  else
    info "review the report above, then: patch --auto / patch --lib / patch --dir, then package, then verify."
  fi
}

main() {
  local cmd="${1:-}"; shift || true
  case "$cmd" in
    inspect) cmd_inspect "$@" ;;
    patch)   cmd_patch "$@" ;;
    package) cmd_package "$@" ;;
    verify)  cmd_verify "$@" ;;
    all)     cmd_all "$@" ;;
    *) usage ;;
  esac
}
main "$@"