@hasna/recordings 0.2.11 → 0.2.13

package/packaging/macos/scripts/preinstall

@@ -0,0 +1,297 @@
+#!/bin/bash
+set -euo pipefail
+umask 077
+
+export PATH=/usr/bin:/bin:/usr/sbin:/sbin
+export LC_ALL=C
+export LANG=C
+export TZ=UTC0
+
+PACKAGE_BOOTSTRAP_ID="__RECORDINGS_PACKAGE_BOOTSTRAP_ID__"
+AUTHORIZATION_ROOT="/private/var/db/com.hasna.recordings.bootstrap-authorization"
+AUTHORIZATION_JOURNAL="${AUTHORIZATION_ROOT}/journal"
+AUTHORIZATION_NEXT="${AUTHORIZATION_ROOT}/.journal.next"
+STATE="/var/db/com.hasna.recordings.updater/release-state.json"
+VERIFIER_USER="_recordingsverify"
+VERIFIER_GROUP="_recordingsverify"
+
+[ "$(/usr/bin/id -u)" = "0" ] || {
+  echo "Recordings updater bootstrap must run as root through Installer or MDM." >&2
+  exit 1
+}
+
+path_exists_or_symlink() {
+  [ -e "$1" ] || [ -L "$1" ]
+}
+
+require_no_extended_acl() {
+  local path="$1"
+  local acl_listing acl_status
+  acl_listing="$(/bin/ls -lade "$path")" || {
+    echo "Recordings updater could not inspect target ACLs: $path" >&2
+    exit 1
+  }
+  if /usr/bin/printf '%s\n' "$acl_listing" | /usr/bin/awk '
+    NR == 1 && length($1) == 11 && substr($1, 11, 1) == "+" { found = 1 }
+    NR > 1 && $1 ~ /^[0-9]+:$/ { found = 1 }
+    END { exit found ? 0 : 1 }
+  '; then
+    echo "Recordings updater target trust path has an extended ACL: $path" >&2
+    exit 1
+  else
+    acl_status=$?
+    [ "$acl_status" -eq 1 ] || {
+      echo "Recordings updater could not evaluate target ACLs: $path" >&2
+      exit 1
+    }
+  fi
+}
+
+require_tree_without_extended_acl() {
+  local tree="$1"
+  local acl_listing acl_status
+  require_no_extended_acl "$tree"
+  [ -d "$tree" ] || return 0
+  acl_listing="$(/bin/ls -laeR "$tree")" || {
+    echo "Recordings updater could not recursively inspect target ACLs: $tree" >&2
+    exit 1
+  }
+  if /usr/bin/printf '%s\n' "$acl_listing" | /usr/bin/awk '
+    length($1) == 11 && substr($1, 11, 1) == "+" { found = 1 }
+    $1 ~ /^[0-9]+:$/ { found = 1 }
+    END { exit found ? 0 : 1 }
+  '; then
+    echo "Recordings updater target tree has an extended ACL: $tree" >&2
+    exit 1
+  else
+    acl_status=$?
+    [ "$acl_status" -eq 1 ] || {
+      echo "Recordings updater could not evaluate recursive target ACLs: $tree" >&2
+      exit 1
+    }
+  fi
+}
+
+require_root_owned_nonwritable_directory() {
+  local directory="$1"
+  local mode
+  [ -d "$directory" ] && [ ! -L "$directory" ] && \
+    [ "$(/usr/bin/stat -f '%u' "$directory")" = 0 ] || {
+    echo "Recordings updater target ancestry is missing, linked, or not root-owned: $directory" >&2
+    exit 1
+  }
+  mode="$(/usr/bin/stat -f '%Lp' "$directory")"
+  [ $((8#$mode & 8#022)) -eq 0 ] || {
+    echo "Recordings updater target ancestry is group/other writable: $directory" >&2
+    exit 1
+  }
+  require_no_extended_acl "$directory"
+}
+
+require_managed_applications_directory() {
+  local mode group_id
+  [ -d "/Applications" ] && [ ! -L "/Applications" ] && \
+    [ "$(/usr/bin/stat -f '%u' "/Applications")" = 0 ] || {
+    echo "Recordings updater requires a root-owned canonical /Applications directory." >&2
+    exit 1
+  }
+  require_no_extended_acl "/Applications"
+  mode="$(/usr/bin/stat -f '%Lp' "/Applications")"
+  group_id="$(/usr/bin/stat -f '%g' "/Applications")"
+  case "$mode:$group_id" in
+    755:*|775:80) ;;
+    *) echo "Recordings updater requires ACL-free /Applications mode 0755 or root:admin mode 0775." >&2; exit 1 ;;
+  esac
+}
+
+require_expected_var_link() {
+  local var_target
+  [ -L "/var" ] || { echo "Recordings updater requires the canonical macOS /var system link." >&2; exit 1; }
+  var_target="$(/usr/bin/readlink "/var")" || { echo "Recordings updater could not inspect the macOS /var system link." >&2; exit 1; }
+  [ "$var_target" = "private/var" ] && \
+    [ "$(cd "/var" && /bin/pwd -P)" = "/private/var" ] || {
+    echo "Recordings updater found a noncanonical macOS /var system link." >&2
+    exit 1
+  }
+}
+
+read_journal_value() {
+  local key="$1"
+  /usr/bin/awk -F= -v key="$key" '
+    $1 == key { count += 1; value = substr($0, length(key) + 2) }
+    END { if (count != 1) exit 1; print value }
+  ' "$AUTHORIZATION_JOURNAL"
+}
+
+require_authorization_journal() {
+  path_exists_or_symlink "$AUTHORIZATION_ROOT" && \
+    [ -d "$AUTHORIZATION_ROOT" ] && [ ! -L "$AUTHORIZATION_ROOT" ] && \
+    [ "$(/usr/bin/stat -f '%u:%g:%Lp' "$AUTHORIZATION_ROOT")" = "0:0:700" ] || {
+    echo "Recordings updater authorization evidence is missing or unsafe." >&2
+    exit 1
+  }
+  [ -f "$AUTHORIZATION_JOURNAL" ] && [ ! -L "$AUTHORIZATION_JOURNAL" ] && \
+    [ "$(/usr/bin/stat -f '%u:%g:%Lp' "$AUTHORIZATION_JOURNAL")" = "0:0:400" ] && \
+    [ "$(/usr/bin/stat -f '%l' "$AUTHORIZATION_JOURNAL")" = "1" ] && \
+    [ "$(/usr/bin/wc -l <"$AUTHORIZATION_JOURNAL" | /usr/bin/tr -d ' ')" = "6" ] || {
+    echo "Recordings updater authorization journal is missing or unsafe." >&2
+    exit 1
+  }
+  require_no_extended_acl "$AUTHORIZATION_ROOT"
+  require_no_extended_acl "$AUTHORIZATION_JOURNAL"
+  [ "$(read_journal_value schema_version)" = "1" ] || { echo "Recordings updater authorization journal schema is invalid." >&2; exit 1; }
+  JOURNAL_PHASE="$(read_journal_value phase)"
+  JOURNAL_PACKAGE_SHA256="$(read_journal_value package_sha256)"
+  JOURNAL_PACKAGE_BOOTSTRAP_ID="$(read_journal_value package_bootstrap_id)"
+  JOURNAL_INSTALLER_TEAM_ID="$(read_journal_value installer_team_id)"
+  JOURNAL_INSTALLER_CERTIFICATE_SHA256="$(read_journal_value installer_certificate_sha256)"
+  [[ "$JOURNAL_PACKAGE_SHA256" =~ ^[0-9a-f]{64}$ ]] && \
+    [[ "$JOURNAL_PACKAGE_BOOTSTRAP_ID" =~ ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ ]] && \
+    [[ "$JOURNAL_INSTALLER_TEAM_ID" =~ ^[A-Z0-9]{10}$ ]] && \
+    [[ "$JOURNAL_INSTALLER_CERTIFICATE_SHA256" =~ ^[0-9a-f]{64}$ ]] || {
+    echo "Recordings updater authorization journal values are malformed." >&2
+    exit 1
+  }
+  [ "$JOURNAL_PACKAGE_BOOTSTRAP_ID" = "$PACKAGE_BOOTSTRAP_ID" ] || {
+    echo "Recordings updater authorization journal belongs to a different authenticated package." >&2
+    exit 1
+  }
+}
+
+write_authorization_phase() {
+  local phase="$1"
+  local replacement
+  replacement="$AUTHORIZATION_NEXT"
+  if path_exists_or_symlink "$replacement"; then
+    [ -f "$replacement" ] && [ ! -L "$replacement" ] && \
+      [ "$(/usr/bin/stat -f '%u:%g' "$replacement")" = "0:0" ] && \
+      [ "$(/usr/bin/stat -f '%l' "$replacement")" = "1" ] || {
+      echo "Recordings updater authorization journal staging is unsafe." >&2
+      exit 1
+    }
+    case "$(/usr/bin/stat -f '%Lp' "$replacement")" in 400|600) ;; *) echo "Recordings updater authorization journal staging mode is unsafe." >&2; exit 1 ;; esac
+    require_no_extended_acl "$replacement"
+    /bin/rm -f "$replacement"
+  fi
+  /usr/bin/printf 'schema_version=1\nphase=%s\npackage_sha256=%s\npackage_bootstrap_id=%s\ninstaller_team_id=%s\ninstaller_certificate_sha256=%s\n' \
+    "$phase" "$JOURNAL_PACKAGE_SHA256" "$JOURNAL_PACKAGE_BOOTSTRAP_ID" \
+    "$JOURNAL_INSTALLER_TEAM_ID" "$JOURNAL_INSTALLER_CERTIFICATE_SHA256" >"$replacement"
+  /usr/sbin/chown root:wheel "$replacement"
+  /bin/chmod -N "$replacement"
+  /bin/chmod 0400 "$replacement"
+  require_no_extended_acl "$replacement"
+  /bin/mv -f "$replacement" "$AUTHORIZATION_JOURNAL"
+  /bin/sync
+}
+
+require_safe_existing_cohort_path() {
+  local path="$1"
+  local expected_mode="$2"
+  local entry listing device mode owner links invalid=0
+  [ ! -L "$path" ] && [ "$(/usr/bin/stat -f '%u' "$path")" = "0" ] || {
+    echo "Recordings updater authorized exact-package repair found linked or non-root-owned cohort evidence: $path" >&2
+    exit 1
+  }
+  mode="$(/usr/bin/stat -f '%Lp' "$path")"
+  case "$expected_mode:$mode" in
+    "$mode:$mode"|700-or-755:700|700-or-755:755) ;;
+    *)
+      echo "Recordings updater authorized exact-package repair found cohort mode drift: $path" >&2
+      exit 1
+      ;;
+  esac
+  require_tree_without_extended_acl "$path"
+  if [ -f "$path" ]; then
+    [ "$(/usr/bin/stat -f '%l' "$path")" = "1" ] || { echo "Recordings updater cohort evidence is hard-linked: $path" >&2; exit 1; }
+    return
+  fi
+  [ -d "$path" ] || { echo "Recordings updater cohort evidence is not a regular file or directory: $path" >&2; exit 1; }
+  listing="$(/usr/bin/mktemp -t recordings-preinstall-cohort)"
+  device="$(/usr/bin/stat -f '%d' "$path")"
+  /usr/bin/find -x "$path" -print0 >"$listing" || { /bin/rm -f "$listing"; exit 1; }
+  while IFS= read -r -d '' entry; do
+    owner="$(/usr/bin/stat -f '%u' "$entry")" || { invalid=1; break; }
+    mode="$(/usr/bin/stat -f '%Lp' "$entry")" || { invalid=1; break; }
+    [ ! -L "$entry" ] && [ "$owner" = "0" ] && \
+      [ "$(/usr/bin/stat -f '%d' "$entry")" = "$device" ] && \
+      [ $((8#$mode & 8#022)) -eq 0 ] || { invalid=1; break; }
+    if [ -f "$entry" ]; then
+      links="$(/usr/bin/stat -f '%l' "$entry")" || { invalid=1; break; }
+      [ "$links" = "1" ] || { invalid=1; break; }
+    elif [ ! -d "$entry" ]; then
+      invalid=1
+      break
+    fi
+  done <"$listing"
+  /bin/rm -f "$listing"
+  [ "$invalid" -eq 0 ] || { echo "Recordings updater authorized exact-package repair found unsafe cohort structure: $path" >&2; exit 1; }
+}
+
+require_expected_var_link
+require_managed_applications_directory
+for required_ancestor in \
+  "/" "/Library" "/Library/Application Support" "/Library/PrivilegedHelperTools" "/Library/LaunchDaemons" \
+  "/private" "/private/var" "/private/var/db"; do
+  require_root_owned_nonwritable_directory "$required_ancestor"
+done
+for optional_ancestor in "/Library/Application Support/Hasna" "/Library/Application Support/Hasna/Recordings"; do
+  if path_exists_or_symlink "$optional_ancestor"; then require_root_owned_nonwritable_directory "$optional_ancestor"; fi
+done
+
+require_authorization_journal
+path_exists_or_symlink "$STATE" && {
+  echo "Recordings uses an immutable updater cohort; a bootstrap PKG cannot replace committed anti-rollback state." >&2
+  exit 1
+}
+
+COHORT_PATHS=(
+  "/Library/PrivilegedHelperTools/com.hasna.recordings.updater:555"
+  "/Library/PrivilegedHelperTools/com.hasna.recordings.artifact-verifier:555"
+  "/Library/LaunchDaemons/com.hasna.recordings.updater.plist:444"
+  "/Applications/Recordings.app:755"
+  "/Applications/Recordings.app/Contents/Helpers/recordings-update-client:755"
+  "/Library/Application Support/Hasna/Recordings/Trust:700-or-755"
+  "/Library/Application Support/Hasna/Recordings/Bootstrap:700"
+  "/Library/Application Support/Hasna/Recordings/Updates:700"
+  "/var/db/com.hasna.recordings.updater:700"
+)
+present_count=0
+for cohort_spec in "${COHORT_PATHS[@]}"; do
+  cohort_path="${cohort_spec%:*}"
+  cohort_mode="${cohort_spec##*:}"
+  if path_exists_or_symlink "$cohort_path"; then
+    present_count=$((present_count + 1))
+    require_safe_existing_cohort_path "$cohort_path" "$cohort_mode"
+  fi
+done
+service_present=false
+if /bin/launchctl print system/com.hasna.recordings.updater >/dev/null 2>&1; then service_present=true; fi
+
+case "$JOURNAL_PHASE" in
+  authorized)
+    JOURNAL_PHASE="authorized"
+    [ "$present_count" -eq 0 ] && [ "$service_present" = false ] && \
+      ! /usr/bin/dscl . -read "/Groups/${VERIFIER_GROUP}" >/dev/null 2>&1 && \
+      ! /usr/bin/dscl . -read "/Users/${VERIFIER_USER}" >/dev/null 2>&1 || {
+      echo "Recordings updater found a partial updater cohort without exact-package authorization or another existing unrelated cohort." >&2
+      exit 1
+    }
+    write_authorization_phase "installer-started"
+    ;;
+  installer-started)
+    JOURNAL_PHASE="installer-started"
+    [ "$service_present" = false ] || {
+      echo "Recordings updater refuses Installer replay while the authorized service is already registered." >&2
+      exit 1
+    }
+    ;;
+  *) echo "Recordings updater authorization journal has an invalid phase." >&2; exit 1 ;;
+esac
+
+# This package remains an immutable, one-time bootstrap cohort. Only an
+# interrupted install bearing this exact signed-script identity may repair its
+# own partial updater cohort; all other replacement requires managed reprovisioning.
+if [ "$present_count" -gt 0 ]; then
+  echo "Recordings updater continuing authorized exact-package repair of a partial updater cohort." >&2
+fi
+# Once installed, only app-artifact updates are supported.

package/scripts/build_companion_cli.sh

@@ -0,0 +1,337 @@
+#!/bin/bash
+set -euo pipefail
+
+if [ "$#" -lt 2 ] || [ "$#" -gt 3 ]; then
+  echo "Usage: $0 <output-path> <explicit absolute Bun executable path> [native|universal]" >&2
+  exit 2
+fi
+
+BUILD_KIND="${3:-native}"
+case "$BUILD_KIND" in
+  native|universal) ;;
+  *)
+    echo "Companion CLI build kind must be native or universal." >&2
+    exit 2
+    ;;
+esac
+
+HOST_UNAME_EXECUTABLE="/usr/bin/uname"
+SYSTEM_DIRNAME_EXECUTABLE="/usr/bin/dirname"
+SYSTEM_PWD_EXECUTABLE="/bin/pwd"
+SANITIZED_PATH="/usr/bin:/bin:/usr/sbin:/sbin"
+
+require_executable() {
+  local label="$1"
+  local executable="$2"
+  case "$executable" in
+    /*) ;;
+    *)
+      echo "$label must be configured as an absolute executable path." >&2
+      exit 1
+      ;;
+  esac
+  if [ ! -f "$executable" ] || [ ! -x "$executable" ]; then
+    echo "$label is missing or is not an executable file: $executable" >&2
+    exit 1
+  fi
+}
+
+require_executable "HOST_UNAME_EXECUTABLE" "$HOST_UNAME_EXECUTABLE"
+require_executable "SYSTEM_DIRNAME_EXECUTABLE" "$SYSTEM_DIRNAME_EXECUTABLE"
+require_executable "SYSTEM_PWD_EXECUTABLE" "$SYSTEM_PWD_EXECUTABLE"
+HOST_PLATFORM="$("$HOST_UNAME_EXECUTABLE" -s)"
+readonly HOST_PLATFORM
+
+select_executable() {
+  local system_executable="$1"
+  local test_override="${2:-}"
+  if [ "$HOST_PLATFORM" = "Darwin" ] || [ -z "$test_override" ]; then
+    printf '%s\n' "$system_executable"
+  else
+    printf '%s\n' "$test_override"
+  fi
+}
+
+DIRNAME_EXECUTABLE="$(select_executable "$SYSTEM_DIRNAME_EXECUTABLE" "${RECORDINGS_TEST_COMPANION_DIRNAME_EXECUTABLE:-}")"
+PWD_EXECUTABLE="$(select_executable "$SYSTEM_PWD_EXECUTABLE" "${RECORDINGS_TEST_COMPANION_PWD_EXECUTABLE:-}")"
+CHMOD_EXECUTABLE="$(select_executable "/bin/chmod" "${RECORDINGS_TEST_COMPANION_CHMOD_EXECUTABLE:-}")"
+CP_EXECUTABLE="$(select_executable "/bin/cp" "${RECORDINGS_TEST_COMPANION_CP_EXECUTABLE:-}")"
+ENV_EXECUTABLE="$(select_executable "/usr/bin/env" "${RECORDINGS_TEST_COMPANION_ENV_EXECUTABLE:-}")"
+GREP_EXECUTABLE="$(select_executable "/usr/bin/grep" "${RECORDINGS_TEST_COMPANION_GREP_EXECUTABLE:-}")"
+MKDIR_EXECUTABLE="$(select_executable "/bin/mkdir" "${RECORDINGS_TEST_COMPANION_MKDIR_EXECUTABLE:-}")"
+MKTEMP_EXECUTABLE="$(select_executable "/usr/bin/mktemp" "${RECORDINGS_TEST_COMPANION_MKTEMP_EXECUTABLE:-}")"
+MV_EXECUTABLE="$(select_executable "/bin/mv" "${RECORDINGS_TEST_COMPANION_MV_EXECUTABLE:-}")"
+RM_EXECUTABLE="$(select_executable "/bin/rm" "${RECORDINGS_TEST_COMPANION_RM_EXECUTABLE:-}")"
+LIPO_EXECUTABLE="$(select_executable "/usr/bin/lipo" "${RECORDINGS_TEST_COMPANION_LIPO_EXECUTABLE:-}")"
+
+for executable_spec in \
+  "DIRNAME_EXECUTABLE:$DIRNAME_EXECUTABLE" \
+  "PWD_EXECUTABLE:$PWD_EXECUTABLE" \
+  "CHMOD_EXECUTABLE:$CHMOD_EXECUTABLE" \
+  "CP_EXECUTABLE:$CP_EXECUTABLE" \
+  "ENV_EXECUTABLE:$ENV_EXECUTABLE" \
+  "GREP_EXECUTABLE:$GREP_EXECUTABLE" \
+  "MKDIR_EXECUTABLE:$MKDIR_EXECUTABLE" \
+  "MKTEMP_EXECUTABLE:$MKTEMP_EXECUTABLE" \
+  "MV_EXECUTABLE:$MV_EXECUTABLE" \
+  "RM_EXECUTABLE:$RM_EXECUTABLE"; do
+  require_executable "${executable_spec%%:*}" "${executable_spec#*:}"
+done
+if [ "$BUILD_KIND" = "universal" ]; then
+  require_executable "LIPO_EXECUTABLE" "$LIPO_EXECUTABLE"
+fi
+
+BUN_EXECUTABLE="$2"
+require_bun_executable() {
+  local executable="$1"
+  require_executable "BUN_EXECUTABLE" "$executable"
+  if ! "$ENV_EXECUTABLE" -i \
+    HOME="/tmp" \
+    PATH="$SANITIZED_PATH" \
+    "$executable" -e '
+      import { realpathSync, statSync } from "node:fs";
+      const expected = process.argv[1];
+      const actual = process.execPath;
+      if (!expected || realpathSync(actual) !== realpathSync(expected)) process.exit(66);
+      if (!statSync(actual).isFile()) process.exit(66);
+      if (!/^\d+\.\d+\.\d+(?:[-+].*)?$/.test(Bun.version)) process.exit(66);
+    ' "$executable"; then
+    echo "BUN_EXECUTABLE did not identify the Bun executable that actually ran." >&2
+    exit 1
+  fi
+}
+require_bun_executable "$BUN_EXECUTABLE"
+
+ROOT="$(cd "$("$DIRNAME_EXECUTABLE" "${BASH_SOURCE[0]}")/.." && "$PWD_EXECUTABLE" -P)"
+CURRENT_DIRECTORY="$($PWD_EXECUTABLE -P)"
+OUTPUT="$1"
+case "$OUTPUT" in
+  /*) ;;
+  *) OUTPUT="${CURRENT_DIRECTORY}/${OUTPUT}" ;;
+esac
+case "$OUTPUT" in
+  */)
+    echo "Companion CLI output must be a file path, not a directory path: ${OUTPUT}." >&2
+    exit 1
+    ;;
+esac
+if [ -d "$OUTPUT" ]; then
+  echo "Companion CLI output must not be an existing directory: ${OUTPUT}." >&2
+  exit 1
+fi
+
+ENTRY="${ROOT}/src/cli/index.ts"
+if [ ! -f "$ENTRY" ]; then
+  echo "Recordings CLI source is missing from ${ROOT}." >&2
+  exit 1
+fi
+for required_source in package.json bun.lock bunfig.toml tsconfig.json; do
+  if [ ! -f "${ROOT}/${required_source}" ]; then
+    echo "Recordings companion build input is missing: ${ROOT}/${required_source}." >&2
+    exit 1
+  fi
+done
+
+WORK_DIR="$($MKTEMP_EXECUTABLE -d /tmp/recordings-companion-build.XXXXXX)"
+PUBLISH_OUTPUT=""
+cleanup() {
+  if [ -n "$PUBLISH_OUTPUT" ]; then
+    "$RM_EXECUTABLE" -f "$PUBLISH_OUTPUT"
+  fi
+  "$RM_EXECUTABLE" -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+BUILD_HOME="$WORK_DIR/home"
+BUN_CACHE="$WORK_DIR/bun-cache"
+STAGED_ROOT="$WORK_DIR/package"
+COMPILE_DIR="$WORK_DIR/compile"
+COMPILED_OUTPUT="$COMPILE_DIR/recordings"
+COMPILED_ARM64="$COMPILE_DIR/recordings.arm64"
+COMPILED_X86_64="$COMPILE_DIR/recordings.x86_64"
+"$MKDIR_EXECUTABLE" -p "$BUILD_HOME" "$BUN_CACHE" "$STAGED_ROOT" "$COMPILE_DIR"
+"$CP_EXECUTABLE" "$ROOT/package.json" "$ROOT/bun.lock" "$ROOT/bunfig.toml" "$ROOT/tsconfig.json" "$STAGED_ROOT/"
+"$CP_EXECUTABLE" -R "$ROOT/src" "$STAGED_ROOT/src"
+if [ -d "$ROOT/migrations" ]; then
+  "$CP_EXECUTABLE" -R "$ROOT/migrations" "$STAGED_ROOT/migrations"
+fi
+
+run_bun() {
+  "$ENV_EXECUTABLE" -i \
+    HOME="$BUILD_HOME" \
+    PATH="$SANITIZED_PATH" \
+    TMPDIR="$WORK_DIR" \
+    "$BUN_EXECUTABLE" "$@"
+}
+
+run_lipo() {
+  "$ENV_EXECUTABLE" -i \
+    HOME="$BUILD_HOME" \
+    PATH="$SANITIZED_PATH" \
+    TMPDIR="$WORK_DIR" \
+    "$LIPO_EXECUTABLE" "$@"
+}
+
+verify_exact_binary_architectures() {
+  local binary="$1"
+  shift
+  local actual_architectures
+  local actual_architecture
+  local expected_architecture
+  local actual_count=0
+  local match_count
+
+  if ! actual_architectures="$(run_lipo -archs "$binary")"; then
+    echo "Could not read companion CLI architectures: $binary" >&2
+    return 1
+  fi
+  for actual_architecture in $actual_architectures; do
+    actual_count=$((actual_count + 1))
+    case " $* " in
+      *" $actual_architecture "*) ;;
+      *)
+        echo "Companion CLI contains unsupported architecture: $actual_architecture" >&2
+        return 1
+        ;;
+    esac
+  done
+  if [ "$actual_count" -ne "$#" ]; then
+    echo "Companion CLI architecture count does not match the universal release policy." >&2
+    return 1
+  fi
+  for expected_architecture in "$@"; do
+    match_count=0
+    for actual_architecture in $actual_architectures; do
+      if [ "$actual_architecture" = "$expected_architecture" ]; then
+        match_count=$((match_count + 1))
+      fi
+    done
+    if [ "$match_count" -ne 1 ]; then
+      echo "Companion CLI must contain exactly one $expected_architecture slice." >&2
+      return 1
+    fi
+  done
+}
+
+run_bun install \
+  --cwd "$STAGED_ROOT" \
+  --production \
+  --frozen-lockfile \
+  --ignore-scripts \
+  --minimum-release-age=604800 \
+  --cache-dir "$BUN_CACHE" \
+  --no-progress
+
+if [ "$BUILD_KIND" = "universal" ]; then
+  (
+    cd "$COMPILE_DIR"
+    run_bun build \
+      --compile \
+      --target="bun-darwin-arm64" \
+      --reject-unresolved \
+      --no-compile-autoload-dotenv \
+      --no-compile-autoload-bunfig \
+      --no-compile-autoload-tsconfig \
+      --no-compile-autoload-package-json \
+      "$STAGED_ROOT/src/cli/index.ts" \
+      --outfile "$COMPILED_ARM64"
+    run_bun build \
+      --compile \
+      --target="bun-darwin-x64" \
+      --reject-unresolved \
+      --no-compile-autoload-dotenv \
+      --no-compile-autoload-bunfig \
+      --no-compile-autoload-tsconfig \
+      --no-compile-autoload-package-json \
+      "$STAGED_ROOT/src/cli/index.ts" \
+      --outfile "$COMPILED_X86_64"
+  )
+  run_lipo -create "$COMPILED_ARM64" "$COMPILED_X86_64" -output "$COMPILED_OUTPUT"
+  verify_exact_binary_architectures "$COMPILED_OUTPUT" arm64 x86_64
+else
+  (
+    cd "$COMPILE_DIR"
+    run_bun build \
+      --compile \
+      --reject-unresolved \
+      --no-compile-autoload-dotenv \
+      --no-compile-autoload-bunfig \
+      --no-compile-autoload-tsconfig \
+      --no-compile-autoload-package-json \
+      "$STAGED_ROOT/src/cli/index.ts" \
+      --outfile "$COMPILED_OUTPUT"
+  )
+fi
+
+EXPECTED_VERSION="$(
+  cd "$STAGED_ROOT"
+  run_bun -e 'const pkg = await Bun.file("package.json").json(); process.stdout.write(pkg.version)'
+)"
+run_output() {
+  "$ENV_EXECUTABLE" -i \
+    HOME="$BUILD_HOME" \
+    PATH="$SANITIZED_PATH" \
+    TMPDIR="$WORK_DIR" \
+    "$COMPILED_OUTPUT" "$@"
+}
+ACTUAL_VERSION="$(run_output --version)"
+
+if [ "$ACTUAL_VERSION" != "$EXPECTED_VERSION" ]; then
+  echo "Companion CLI version mismatch: expected ${EXPECTED_VERSION}, got ${ACTUAL_VERSION}." >&2
+  exit 1
+fi
+
+require_command() {
+  if ! run_output "$@" --help >/dev/null 2>&1; then
+    echo "Companion CLI is missing command: $*." >&2
+    exit 1
+  fi
+}
+
+require_flag() {
+  local command_name="$1"
+  local flag="$2"
+  shift 2
+  if ! run_output "$@" --help | "$GREP_EXECUTABLE" -Fq -- "$flag"; then
+    echo "Companion CLI is missing ${command_name} ${flag}." >&2
+    exit 1
+  fi
+}
+
+# Keep this contract in lockstep with every command and option emitted by the Swift app.
+for command in list show search stats delete transcribe save-text rewrite; do
+  require_command "$command"
+done
+require_command project register
+
+require_flag "root" "--json"
+require_flag "root" "--project"
+for flag in --name --path --description; do
+  require_flag "project register" "$flag" project register
+done
+for flag in -n --limit --offset; do
+  require_flag "list" "$flag" list
+done
+require_flag "search" "-n" search
+require_flag "search" "--limit" search
+for flag in --post-processing --prompt --transcriber-prompt --language --recording-id --transcription-model --transcriber-model --enhancement-model --enhance-triggers-json --keyword-transforms-json; do
+  require_flag "transcribe" "$flag" transcribe
+done
+for flag in --text-file --source --model-used --post-processing --audio-path --duration-ms --language --transcriber-prompt --recording-id --transcription-model --transcriber-model --enhancement-model --enhance-triggers-json --keyword-transforms-json; do
+  require_flag "save-text" "$flag" save-text
+done
+for flag in --instruction --post-processing --language --prompt --transcriber-prompt --transcription-model --transcriber-model --enhancement-model --enhance-triggers-json --keyword-transforms-json; do
+  require_flag "rewrite" "$flag" rewrite
+done
+
+OUTPUT_DIRECTORY="$("$DIRNAME_EXECUTABLE" "$OUTPUT")"
+"$MKDIR_EXECUTABLE" -p "$OUTPUT_DIRECTORY"
+PUBLISH_OUTPUT="$($MKTEMP_EXECUTABLE "$OUTPUT_DIRECTORY/.recordings-companion.XXXXXX")"
+"$MV_EXECUTABLE" "$COMPILED_OUTPUT" "$PUBLISH_OUTPUT"
+"$CHMOD_EXECUTABLE" 0755 "$PUBLISH_OUTPUT"
+run_bun -e '
+  import { renameSync } from "node:fs";
+  renameSync(process.argv[1], process.argv[2]);
+' "$PUBLISH_OUTPUT" "$OUTPUT"
+PUBLISH_OUTPUT=""
+echo "Built Recordings companion CLI ${ACTUAL_VERSION}: ${OUTPUT}"