build(portable): Add macOS portable packaging scripts

cameroncooke · claude · cameroncooke · commit 961a40d39f8a · 2026-02-09T15:23:50.000Z
Add portable packaging and verification scripts for macOS tarball distribution, including bin/libexec layout, bundled runtime resources, production dependencies, and artifact checksum generation. Add npm entrypoints for package and verification workflows.

Harden AXe bundling for release provenance by defaulting to remote artifacts, keeping local AXe as explicit opt-in, and enforcing signature checks with CLI-safe Gatekeeper handling.

Co-Authored-By: Claude &lt;noreply@anthropic.com&gt;
diff --git a/package.json b/package.json
@@ -23,6 +23,9 @@
     "hooks:install": "node scripts/install-git-hooks.js",
     "generate:version": "npx tsx scripts/generate-version.ts",
     "bundle:axe": "scripts/bundle-axe.sh",
+    "package:macos": "scripts/package-macos-portable.sh",
+    "package:macos:universal": "scripts/package-macos-portable.sh --universal",
+    "verify:portable": "scripts/verify-portable-install.sh",
     "lint": "eslint 'src/**/*.{js,ts}'",
     "lint:fix": "eslint 'src/**/*.{js,ts}' --fix",
     "format": "prettier --write 'src/**/*.{js,ts}'",
diff --git a/scripts/bundle-axe.sh b/scripts/bundle-axe.sh
@@ -37,8 +37,13 @@ fi
 # Create bundled directory
 mkdir -p "$BUNDLED_DIR"
 
-# Use local AXe build if available (unless AXE_FORCE_REMOTE=1), otherwise download from GitHub releases
-if [ -z "${AXE_FORCE_REMOTE}" ] && [ -d "$AXE_LOCAL_DIR" ] && [ -f "$AXE_LOCAL_DIR/Package.swift" ]; then
+USE_LOCAL_AXE=false
+if [ -z "${AXE_FORCE_REMOTE}" ] && [ "${AXE_USE_LOCAL:-0}" = "1" ]; then
+    USE_LOCAL_AXE=true
+fi
+
+# Use local AXe build only when explicitly requested, otherwise download from GitHub releases.
+if [ "$USE_LOCAL_AXE" = true ] && [ -d "$AXE_LOCAL_DIR" ] && [ -f "$AXE_LOCAL_DIR/Package.swift" ]; then
     echo "🏠 Using local AXe source at $AXE_LOCAL_DIR"
     cd "$AXE_LOCAL_DIR"
 
@@ -80,6 +85,11 @@ if [ -z "${AXE_FORCE_REMOTE}" ] && [ -d "$AXE_LOCAL_DIR" ] && [ -f "$AXE_LOCAL_D
         fi
     done
 else
+    if [ "$USE_LOCAL_AXE" = true ]; then
+        echo "❌ AXE_USE_LOCAL=1 was set, but AXE_LOCAL_DIR is missing or invalid: $AXE_LOCAL_DIR"
+        exit 1
+    fi
+
     echo "📥 Downloading latest AXe release from GitHub..."
 
     # Construct release download URL from pinned version
@@ -154,17 +164,34 @@ if [ "$OS_NAME" = "Darwin" ]; then
     fi
 
     while IFS= read -r framework_path; do
-        if ! codesign --verify --deep --strict "$framework_path"; then
-            echo "❌ Signature verification failed for framework: $framework_path"
+        framework_name="$(basename "$framework_path" .framework)"
+        framework_binary="$framework_path/Versions/A/$framework_name"
+        if [ ! -f "$framework_binary" ]; then
+            framework_binary="$framework_path/Versions/Current/$framework_name"
+        fi
+        if [ ! -f "$framework_binary" ]; then
+            echo "❌ Framework binary not found: $framework_binary"
+            exit 1
+        fi
+        if ! codesign --verify --deep --strict "$framework_binary"; then
+            echo "❌ Signature verification failed for framework binary: $framework_binary"
             exit 1
         fi
     done < <(find "$BUNDLED_DIR/Frameworks" -name "*.framework" -type d)
 
     echo "🛡️ Assessing AXe with Gatekeeper..."
-    if ! spctl --assess --type execute "$BUNDLED_DIR/axe"; then
-        echo "❌ Gatekeeper assessment failed for bundled AXe binary"
-        exit 1
+    SPCTL_LOG="$(mktemp)"
+    if ! spctl --assess --type execute "$BUNDLED_DIR/axe" 2>"$SPCTL_LOG"; then
+        if grep -q "does not seem to be an app" "$SPCTL_LOG"; then
+            echo "⚠️  Gatekeeper execute assessment is inconclusive for CLI binaries; continuing"
+        else
+            cat "$SPCTL_LOG"
+            echo "❌ Gatekeeper assessment failed for bundled AXe binary"
+            rm "$SPCTL_LOG"
+            exit 1
+        fi
     fi
+    rm "$SPCTL_LOG"
 
     echo "🧪 Testing bundled AXe binary..."
     if DYLD_FRAMEWORK_PATH="$BUNDLED_DIR/Frameworks" "$BUNDLED_DIR/axe" --version > /dev/null 2>&1; then
diff --git a/scripts/package-macos-portable.sh b/scripts/package-macos-portable.sh
@@ -0,0 +1,237 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+DIST_DIR_DEFAULT="$PROJECT_ROOT/dist/portable"
+
+ARCH=""
+UNIVERSAL=false
+ARM64_ROOT=""
+X64_ROOT=""
+DIST_DIR="$DIST_DIR_DEFAULT"
+VERSION=""
+
+usage() {
+  cat <<'EOF'
+Usage:
+  scripts/package-macos-portable.sh [--arch arm64|x64] [--dist-dir <path>] [--version <semver>]
+  scripts/package-macos-portable.sh --universal --arm64-root <path> --x64-root <path> [--dist-dir <path>] [--version <semver>]
+
+Notes:
+  - Arch mode packages a bundled Node runtime plus compiled JS entrypoint.
+  - Universal mode expects prebuilt arm64/x64 roots and combines Node runtimes with lipo.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --arch)
+      ARCH="${2:-}"
+      shift 2
+      ;;
+    --universal)
+      UNIVERSAL=true
+      shift
+      ;;
+    --arm64-root)
+      ARM64_ROOT="${2:-}"
+      shift 2
+      ;;
+    --x64-root)
+      X64_ROOT="${2:-}"
+      shift 2
+      ;;
+    --dist-dir)
+      DIST_DIR="${2:-}"
+      shift 2
+      ;;
+    --version)
+      VERSION="${2:-}"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1"
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$VERSION" ]]; then
+  VERSION="$(node -p "require('$PROJECT_ROOT/package.json').version")"
+fi
+
+mkdir -p "$DIST_DIR"
+
+verify_axe_assets() {
+  local bundled_dir="$PROJECT_ROOT/bundled"
+  local axe_bin="$bundled_dir/axe"
+  local frameworks_dir="$bundled_dir/Frameworks"
+
+  if [[ ! -x "$axe_bin" ]]; then
+    echo "Missing executable AXe binary at $axe_bin"
+    exit 1
+  fi
+  if [[ ! -d "$frameworks_dir" ]]; then
+    echo "Missing AXe frameworks at $frameworks_dir"
+    exit 1
+  fi
+  if [[ "$(find "$frameworks_dir" -name "*.framework" -type d | wc -l | tr -d ' ')" -eq 0 ]]; then
+    echo "No frameworks found under $frameworks_dir"
+    exit 1
+  fi
+
+  if [[ "$(uname -s)" == "Darwin" ]]; then
+    codesign --verify --deep --strict "$axe_bin"
+    while IFS= read -r framework_path; do
+      framework_name="$(basename "$framework_path" .framework)"
+      framework_binary="$framework_path/Versions/A/$framework_name"
+      if [[ ! -f "$framework_binary" ]]; then
+        framework_binary="$framework_path/Versions/Current/$framework_name"
+      fi
+      if [[ ! -f "$framework_binary" ]]; then
+        echo "Missing framework binary at $framework_binary"
+        exit 1
+      fi
+      codesign --verify --deep --strict "$framework_binary"
+    done < <(find "$frameworks_dir" -name "*.framework" -type d)
+    spctl_log="$(mktemp)"
+    if ! spctl --assess --type execute "$axe_bin" 2>"$spctl_log"; then
+      if grep -q "does not seem to be an app" "$spctl_log"; then
+        echo "Gatekeeper execute assessment is inconclusive for CLI binaries; continuing"
+      else
+        cat "$spctl_log"
+        rm "$spctl_log"
+        exit 1
+      fi
+    fi
+    rm "$spctl_log"
+  fi
+}
+
+write_wrapper_scripts() {
+  local root="$1"
+  local bin_dir="$root/bin"
+  local libexec_dir="$root/libexec"
+
+  cat > "$libexec_dir/xcodebuildmcp" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec "$ROOT/node-runtime" "$ROOT/build/cli.js" "$@"
+EOF
+
+  cat > "$bin_dir/xcodebuildmcp" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+RESOURCE_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../libexec" && pwd)"
+export XCODEBUILDMCP_RESOURCE_ROOT="$RESOURCE_ROOT"
+export DYLD_FRAMEWORK_PATH="$RESOURCE_ROOT/bundled/Frameworks${DYLD_FRAMEWORK_PATH:+:$DYLD_FRAMEWORK_PATH}"
+exec "$RESOURCE_ROOT/xcodebuildmcp" "$@"
+EOF
+
+  cat > "$bin_dir/xcodebuildmcp-doctor" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+RESOURCE_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../libexec" && pwd)"
+export XCODEBUILDMCP_RESOURCE_ROOT="$RESOURCE_ROOT"
+export DYLD_FRAMEWORK_PATH="$RESOURCE_ROOT/bundled/Frameworks${DYLD_FRAMEWORK_PATH:+:$DYLD_FRAMEWORK_PATH}"
+exec "$RESOURCE_ROOT/xcodebuildmcp" doctor "$@"
+EOF
+
+  chmod +x "$libexec_dir/xcodebuildmcp" "$bin_dir/xcodebuildmcp" "$bin_dir/xcodebuildmcp-doctor"
+}
+
+create_tarball_and_checksum() {
+  local portable_root="$1"
+  local artifact_name="$2"
+  local tarball_path="$DIST_DIR/$artifact_name.tar.gz"
+  local checksum_path="$tarball_path.sha256"
+
+  (
+    cd "$(dirname "$portable_root")"
+    tar -czf "$tarball_path" "$(basename "$portable_root")"
+  )
+  shasum -a 256 "$tarball_path" > "$checksum_path"
+  echo "Created artifact: $tarball_path"
+  echo "Created checksum: $checksum_path"
+}
+
+if [[ "$UNIVERSAL" == "true" ]]; then
+  if [[ -z "$ARM64_ROOT" || -z "$X64_ROOT" ]]; then
+    echo "--universal requires --arm64-root and --x64-root"
+    exit 1
+  fi
+  if [[ ! -x "$ARM64_ROOT/libexec/node-runtime" || ! -x "$X64_ROOT/libexec/node-runtime" ]]; then
+    echo "Missing per-arch node runtimes under provided roots"
+    exit 1
+  fi
+
+  UNIVERSAL_ROOT="$DIST_DIR/xcodebuildmcp-$VERSION-darwin-universal"
+  if [[ -d "$UNIVERSAL_ROOT" ]]; then
+    rm -r "$UNIVERSAL_ROOT"
+  fi
+  mkdir -p "$UNIVERSAL_ROOT/bin" "$UNIVERSAL_ROOT/libexec"
+  cp -R "$ARM64_ROOT/libexec/build" "$UNIVERSAL_ROOT/libexec/"
+  cp -R "$ARM64_ROOT/libexec/manifests" "$UNIVERSAL_ROOT/libexec/"
+  cp -R "$ARM64_ROOT/libexec/bundled" "$UNIVERSAL_ROOT/libexec/"
+  cp -R "$ARM64_ROOT/libexec/node_modules" "$UNIVERSAL_ROOT/libexec/"
+  cp "$ARM64_ROOT/libexec/package.json" "$UNIVERSAL_ROOT/libexec/package.json"
+
+  lipo -create \
+    "$ARM64_ROOT/libexec/node-runtime" \
+    "$X64_ROOT/libexec/node-runtime" \
+    -output "$UNIVERSAL_ROOT/libexec/node-runtime"
+  chmod +x "$UNIVERSAL_ROOT/libexec/node-runtime"
+
+  write_wrapper_scripts "$UNIVERSAL_ROOT"
+  create_tarball_and_checksum "$UNIVERSAL_ROOT" "xcodebuildmcp-$VERSION-darwin-universal"
+  exit 0
+fi
+
+if [[ -z "$ARCH" ]]; then
+  machine_arch="$(uname -m)"
+  if [[ "$machine_arch" == "arm64" ]]; then
+    ARCH="arm64"
+  elif [[ "$machine_arch" == "x86_64" ]]; then
+    ARCH="x64"
+  else
+    echo "Unsupported machine architecture: $machine_arch"
+    exit 1
+  fi
+fi
+
+if [[ "$ARCH" != "arm64" && "$ARCH" != "x64" ]]; then
+  echo "Unsupported arch: $ARCH (expected arm64 or x64)"
+  exit 1
+fi
+
+cd "$PROJECT_ROOT"
+npm run build:tsup
+AXE_FORCE_REMOTE=1 npm run bundle:axe
+verify_axe_assets
+
+PORTABLE_ROOT="$DIST_DIR/xcodebuildmcp-$VERSION-darwin-$ARCH"
+if [[ -d "$PORTABLE_ROOT" ]]; then
+  rm -r "$PORTABLE_ROOT"
+fi
+mkdir -p "$PORTABLE_ROOT/bin" "$PORTABLE_ROOT/libexec"
+
+cp "$(command -v node)" "$PORTABLE_ROOT/libexec/node-runtime"
+chmod +x "$PORTABLE_ROOT/libexec/node-runtime"
+
+cp -R "$PROJECT_ROOT/build" "$PORTABLE_ROOT/libexec/"
+cp -R "$PROJECT_ROOT/manifests" "$PORTABLE_ROOT/libexec/"
+cp -R "$PROJECT_ROOT/bundled" "$PORTABLE_ROOT/libexec/"
+cp "$PROJECT_ROOT/package.json" "$PORTABLE_ROOT/libexec/package.json"
+cp "$PROJECT_ROOT/package-lock.json" "$PORTABLE_ROOT/libexec/package-lock.json"
+npm ci --omit=dev --ignore-scripts --prefix "$PORTABLE_ROOT/libexec"
+
+write_wrapper_scripts "$PORTABLE_ROOT"
+create_tarball_and_checksum "$PORTABLE_ROOT" "xcodebuildmcp-$VERSION-darwin-$ARCH"
diff --git a/scripts/verify-portable-install.sh b/scripts/verify-portable-install.sh
