fix(release): Address PR review findings for portable packaging

Align npm tag resolution between dry-run and production publish, enforce\nrelease asset ordering before Homebrew tap updates, and harden portable\npackaging scripts with checksum verification and safer argument parsing.\n\nAlso improve docs command fence parsing, memoize resource-root resolution\nwith test reset hooks, and reduce duplicated AXe helper fixtures in key\npress UI automation tests.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: cameroncooke

.github/workflows/release.yml

@@ -74,6 +74,22 @@ jobs:
             # For tag-based releases, package.json was already updated by release script
           fi
 
+      - name: Resolve npm tag from version
+        id: resolve_npm_tag
+        run: |
+          VERSION="${{ steps.get_version.outputs.VERSION }}"
+          if [[ "$VERSION" == *"-beta"* ]]; then
+            NPM_TAG="beta"
+          elif [[ "$VERSION" == *"-alpha"* ]]; then
+            NPM_TAG="alpha"
+          elif [[ "$VERSION" == *"-rc"* ]]; then
+            NPM_TAG="rc"
+          else
+            NPM_TAG="latest"
+          fi
+          echo "NPM_TAG=$NPM_TAG" >> "$GITHUB_OUTPUT"
+          echo "Resolved npm tag: $NPM_TAG"
+
       - name: Generate GitHub release notes (production releases only)
         if: github.event_name == 'push'
         run: |
@@ -88,13 +104,7 @@ jobs:
         if: github.event_name == 'workflow_dispatch'
         run: |
           echo "🧪 Testing package creation (dry run)"
-          VERSION="${{ steps.get_version.outputs.VERSION }}"
-          if [[ "$VERSION" == *"-"* ]]; then
-            NPM_TAG="next"
-          else
-            NPM_TAG="latest"
-          fi
-          npm publish --dry-run --access public --tag "$NPM_TAG"
+          npm publish --dry-run --access public --tag "${{ steps.resolve_npm_tag.outputs.NPM_TAG }}"
 
       - name: Publish to NPM (production releases only)
         if: github.event_name == 'push'
@@ -105,17 +115,7 @@ jobs:
             echo "✅ xcodebuildmcp@$VERSION already on NPM. Skipping publish."
             exit 0
           fi
-          # Determine the appropriate npm tag based on version
-          if [[ "$VERSION" == *"-beta"* ]]; then
-            NPM_TAG="beta"
-          elif [[ "$VERSION" == *"-alpha"* ]]; then
-            NPM_TAG="alpha"
-          elif [[ "$VERSION" == *"-rc"* ]]; then
-            NPM_TAG="rc"
-          else
-            # For stable releases, explicitly use latest tag
-            NPM_TAG="latest"
-          fi
+          NPM_TAG="${{ steps.resolve_npm_tag.outputs.NPM_TAG }}"
           echo "📦 Publishing to NPM with tag: $NPM_TAG"
           npm publish --access public --tag "$NPM_TAG"
 
@@ -314,7 +314,7 @@ jobs:
 
   publish_portable_assets:
     if: github.event_name == 'push'
-    needs: [release, build_universal_and_verify]
+    needs: [release, build_and_package_macos, build_universal_and_verify]
     runs-on: ubuntu-latest
     steps:
       - name: Download arm64 artifact
@@ -350,7 +350,7 @@ jobs:
 
   update_homebrew_tap:
     if: github.event_name == 'push'
-    needs: [release, build_and_package_macos]
+    needs: [release, build_and_package_macos, publish_portable_assets]
     runs-on: ubuntu-latest
     env:
       HOMEBREW_TAP_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
@@ -400,7 +400,7 @@ jobs:
         run: |
           VERSION="${{ needs.release.outputs.version }}"
           DEFAULT_BRANCH="main"
-          git clone "https://x-access-token:${GH_TOKEN}@github.com/cameroncooke/homebrew-xcodebuildmcp.git" tap-repo
+          gh repo clone cameroncooke/homebrew-xcodebuildmcp tap-repo
           mkdir -p tap-repo/Formula
           cp dist/homebrew/Formula/xcodebuildmcp.rb tap-repo/Formula/xcodebuildmcp.rb
           cd tap-repo

docs/dev/PROJECT_CONFIG_PLAN.md

@@ -119,7 +119,7 @@ Responsibilities:
 
 ### 7) Runtime overrides
 **File:** runtime entrypoints
-- Pass overrides into bootstrap/config store, so explicit runtime overrides have highest precedence.
+- Pass overrides into bootstrap/config store, so explicit runtime overrides have the highest precedence.
 
 ### 8) Documentation updates
 - Update `docs/CONFIGURATION.md`, `docs/GETTING_STARTED.md`, `docs/SESSION_DEFAULTS.md`.

scripts/check-docs-cli-commands.js

@@ -85,7 +85,7 @@ function extractCommandCandidates(content) {
   const lines = content.split(/\r?\n/u);
   const candidates = [];
   const inlineCodeRegex = /`([^`\n]+)`/g;
-  const fenceHeaderRegex = /^\s*```([a-z0-9_-]*)\s*$/iu;
+  const fenceHeaderRegex = /^\s*(?:```|~~~)([a-z0-9_-]*)\s*$/iu;
   const codeFenceLanguages = new Set(['', 'bash', 'sh', 'zsh', 'shell', 'console']);
 
   let inFence = false;

scripts/create-homebrew-formula.sh

@@ -15,26 +15,41 @@ Usage:
 EOF
 }
 
+require_arg_value() {
+  local flag_name="$1"
+  local value="${2:-}"
+  if [[ -z "$value" || "$value" == -* ]]; then
+    echo "Error: $flag_name requires a value"
+    usage
+    exit 1
+  fi
+}
+
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --version)
-      VERSION="${2:-}"
+      require_arg_value "--version" "${2:-}"
+      VERSION="$2"
       shift 2
       ;;
     --arm64-sha)
-      ARM64_SHA="${2:-}"
+      require_arg_value "--arm64-sha" "${2:-}"
+      ARM64_SHA="$2"
       shift 2
       ;;
     --x64-sha)
-      X64_SHA="${2:-}"
+      require_arg_value "--x64-sha" "${2:-}"
+      X64_SHA="$2"
       shift 2
       ;;
     --base-url)
-      BASE_URL="${2:-}"
+      require_arg_value "--base-url" "${2:-}"
+      BASE_URL="$2"
       shift 2
       ;;
     --out)
-      OUT_PATH="${2:-}"
+      require_arg_value "--out" "${2:-}"
+      OUT_PATH="$2"
       shift 2
       ;;
     -h|--help)

scripts/package-macos-portable.sh

@@ -25,30 +25,45 @@ Notes:
 EOF
 }
 
+require_arg_value() {
+  local flag_name="$1"
+  local value="${2:-}"
+  if [[ -z "$value" || "$value" == -* ]]; then
+    echo "Missing value for $flag_name"
+    usage
+    exit 1
+  fi
+}
+
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --arch)
-      ARCH="${2:-}"
+      require_arg_value "--arch" "${2:-}"
+      ARCH="$2"
       shift 2
       ;;
     --universal)
       UNIVERSAL=true
       shift
       ;;
     --arm64-root)
-      ARM64_ROOT="${2:-}"
+      require_arg_value "--arm64-root" "${2:-}"
+      ARM64_ROOT="$2"
       shift 2
       ;;
     --x64-root)
-      X64_ROOT="${2:-}"
+      require_arg_value "--x64-root" "${2:-}"
+      X64_ROOT="$2"
       shift 2
       ;;
     --dist-dir)
-      DIST_DIR="${2:-}"
+      require_arg_value "--dist-dir" "${2:-}"
+      DIST_DIR="$2"
       shift 2
       ;;
     --version)
-      VERSION="${2:-}"
+      require_arg_value "--version" "${2:-}"
+      VERSION="$2"
       shift 2
       ;;
     -h|--help)
@@ -153,38 +168,55 @@ install_node_runtime_for_arch() {
   esac
 
   local archive_name="node-v${node_version}-darwin-${node_arch}.tar.gz"
+  local checksums_name="SHASUMS256.txt"
   local download_url="https://nodejs.org/dist/v${node_version}/${archive_name}"
+  local checksums_url="https://nodejs.org/dist/v${node_version}/${checksums_name}"
   local temp_dir
   temp_dir="$(mktemp -d)"
+  cleanup_temp_dir() {
+    if [[ -d "$temp_dir" ]]; then
+      rm -r "$temp_dir"
+    fi
+  }
+  trap cleanup_temp_dir RETURN
 
   curl -fLsS "$download_url" -o "$temp_dir/$archive_name"
+  curl -fLsS "$checksums_url" -o "$temp_dir/$checksums_name"
+
+  local expected_sha
+  expected_sha="$(awk -v target="$archive_name" '$2 == target {print $1}' "$temp_dir/$checksums_name")"
+  if [[ -z "$expected_sha" ]]; then
+    echo "Unable to find checksum for $archive_name in ${checksums_name}"
+    exit 1
+  fi
+
+  local actual_sha
+  actual_sha="$(shasum -a 256 "$temp_dir/$archive_name" | awk '{print $1}')"
+  if [[ "$actual_sha" != "$expected_sha" ]]; then
+    echo "Node runtime checksum mismatch for $archive_name"
+    echo "Expected: $expected_sha"
+    echo "Actual:   $actual_sha"
+    exit 1
+  fi
+
   tar -xzf "$temp_dir/$archive_name" -C "$temp_dir"
 
   local extracted_node="$temp_dir/node-v${node_version}-darwin-${node_arch}/bin/node"
   if [[ ! -x "$extracted_node" ]]; then
     echo "Failed to locate extracted Node runtime at $extracted_node"
-    rm -r "$temp_dir"
     exit 1
   fi
 
   cp "$extracted_node" "$output_path"
   chmod +x "$output_path"
-  rm -r "$temp_dir"
 }
 
 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'
+  cat > "$libexec_dir/_resolve-resource-root.sh" <<'EOF'
 #!/usr/bin/env bash
 set -euo pipefail
 SOURCE="${BASH_SOURCE[0]}"
@@ -194,29 +226,39 @@ while [[ -L "$SOURCE" ]]; do
   [[ "$SOURCE" != /* ]] && SOURCE="$DIR/$SOURCE"
 done
 SCRIPT_DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
-RESOURCE_ROOT="$(cd "$SCRIPT_DIR/../libexec" && pwd)"
+RESOURCE_ROOT="$(cd "$SCRIPT_DIR" && pwd)"
 export XCODEBUILDMCP_RESOURCE_ROOT="$RESOURCE_ROOT"
 export DYLD_FRAMEWORK_PATH="$RESOURCE_ROOT/bundled/Frameworks${DYLD_FRAMEWORK_PATH:+:$DYLD_FRAMEWORK_PATH}"
+EOF
+
+  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
+SCRIPT_DIR="$(cd -P "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../libexec/_resolve-resource-root.sh"
 exec "$RESOURCE_ROOT/xcodebuildmcp" "$@"
 EOF
 
   cat > "$bin_dir/xcodebuildmcp-doctor" <<'EOF'
 #!/usr/bin/env bash
 set -euo pipefail
-SOURCE="${BASH_SOURCE[0]}"
-while [[ -L "$SOURCE" ]]; do
-  DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
-  SOURCE="$(readlink "$SOURCE")"
-  [[ "$SOURCE" != /* ]] && SOURCE="$DIR/$SOURCE"
-done
-SCRIPT_DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
-RESOURCE_ROOT="$(cd "$SCRIPT_DIR/../libexec" && pwd)"
-export XCODEBUILDMCP_RESOURCE_ROOT="$RESOURCE_ROOT"
-export DYLD_FRAMEWORK_PATH="$RESOURCE_ROOT/bundled/Frameworks${DYLD_FRAMEWORK_PATH:+:$DYLD_FRAMEWORK_PATH}"
+SCRIPT_DIR="$(cd -P "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../libexec/_resolve-resource-root.sh"
 exec "$RESOURCE_ROOT/xcodebuildmcp" doctor "$@"
 EOF
 
-  chmod +x "$libexec_dir/xcodebuildmcp" "$bin_dir/xcodebuildmcp" "$bin_dir/xcodebuildmcp-doctor"
+  chmod +x \
+    "$libexec_dir/_resolve-resource-root.sh" \
+    "$libexec_dir/xcodebuildmcp" \
+    "$bin_dir/xcodebuildmcp" \
+    "$bin_dir/xcodebuildmcp-doctor"
 }
 
 create_tarball_and_checksum() {
@@ -229,7 +271,7 @@ create_tarball_and_checksum() {
     cd "$(dirname "$portable_root")"
     tar -czf "$tarball_path" "$(basename "$portable_root")"
   )
-  shasum -a 256 "$tarball_path" > "$checksum_path"
+  shasum -a 256 "$tarball_path" | awk '{print $1}' > "$checksum_path"
   echo "Created artifact: $tarball_path"
   echo "Created checksum: $checksum_path"
 }

scripts/verify-portable-install.sh

@@ -36,13 +36,20 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
+cleanup() {
+  if [[ -n "$TEMP_DIR" && -d "$TEMP_DIR" ]]; then
+    rm -r "$TEMP_DIR"
+  fi
+}
+
 if [[ -z "$ARCHIVE_PATH" && -z "$PORTABLE_ROOT" ]]; then
   usage
   exit 1
 fi
 
 if [[ -n "$ARCHIVE_PATH" ]]; then
   TEMP_DIR="$(mktemp -d)"
+  trap cleanup EXIT
   tar -xzf "$ARCHIVE_PATH" -C "$TEMP_DIR"
   extracted_count="$(find "$TEMP_DIR" -mindepth 1 -maxdepth 1 -type d | wc -l | tr -d ' ')"
   if [[ "$extracted_count" -ne 1 ]]; then
@@ -52,13 +59,6 @@ if [[ -n "$ARCHIVE_PATH" ]]; then
   PORTABLE_ROOT="$(find "$TEMP_DIR" -mindepth 1 -maxdepth 1 -type d | head -1)"
 fi
 
-cleanup() {
-  if [[ -n "$TEMP_DIR" && -d "$TEMP_DIR" ]]; then
-    rm -r "$TEMP_DIR"
-  fi
-}
-trap cleanup EXIT
-
 if [[ ! -d "$PORTABLE_ROOT/bin" || ! -d "$PORTABLE_ROOT/libexec" ]]; then
   echo "Portable layout missing bin/ or libexec/: $PORTABLE_ROOT"
   exit 1
@@ -105,8 +105,8 @@ if [[ -z "$RUNTIME_ARCHS" ]]; then
 fi
 
 NORMALIZED_HOST_ARCH="$HOST_ARCH"
-if [[ "$HOST_ARCH" == "x86_64" ]]; then
-  NORMALIZED_HOST_ARCH="x86_64"
+if [[ "$HOST_ARCH" == "aarch64" ]]; then
+  NORMALIZED_HOST_ARCH="arm64"
 fi
 
 CAN_EXECUTE="false"

src/core/__tests__/resource-root.test.ts

@@ -7,6 +7,7 @@ import {
   getBundledFrameworksDir,
   getManifestsDir,
   getResourceRoot,
+  resetResourceRootCacheForTests,
 } from '../resource-root.ts';
 
 describe('resource-root', () => {
@@ -18,6 +19,7 @@ describe('resource-root', () => {
     originalExecPath = process.execPath;
     originalResourceRoot = process.env.XCODEBUILDMCP_RESOURCE_ROOT;
     tempDir = mkdtempSync(join(tmpdir(), 'xbmcp-resource-root-'));
+    resetResourceRootCacheForTests();
   });
 
   afterEach(() => {
@@ -28,6 +30,7 @@ describe('resource-root', () => {
       process.env.XCODEBUILDMCP_RESOURCE_ROOT = originalResourceRoot;
     }
     rmSync(tempDir, { recursive: true, force: true });
+    resetResourceRootCacheForTests();
   });
 
   it('uses XCODEBUILDMCP_RESOURCE_ROOT when set', () => {