chore: Improve doc build error handling and local build ucp-schema version checking (Universal-Commerce-Protocol#224)

* fix: Image (core-concepts diagram) and spec link URLs broken after site/spec version refactor.

* fix: revert the spec link update from core-concepts

* fix: Improve error handling of ucp-schema returned errors during doc build.

* chore: linter reformat

* chore: Add ucp-schema tool version check to build_local script.

* chore: Bash lint updates

* fix: Apply Shfmt to build_local.sh

Author: dwdii

main.py

@@ -101,7 +101,7 @@ def _resolve_schema(
       hyperlink generation in documentation.
 
   Returns:
-    Resolved schema as dict, or None if resolution fails.
+    Resolved schema as dict, or raises RuntimeError if ucp-schema fails.
 
   """
   bundle_suffix = ":bundled" if bundle else ""
@@ -121,20 +121,18 @@ def _resolve_schema(
   if bundle:
     cmd.append("--bundle")
 
-  try:
-    result = subprocess.run(
-      cmd,
-      capture_output=True,
-      text=True,
-      check=False,
-    )
-    if result.returncode == 0:
-      data = json.loads(result.stdout)
-      _resolved_schema_cache[cache_key] = data
-      return data
-  except subprocess.SubprocessError:
-    pass
-  return None
+  result = subprocess.run(
+    cmd,
+    capture_output=True,
+    text=True,
+    check=False,
+  )
+  if result.returncode == 0:
+    data = json.loads(result.stdout)
+    _resolved_schema_cache[cache_key] = data
+    return data
+  else:
+    raise RuntimeError(f"ucp-schema execution error: result = {result}")
 
 
 # Backward compatibility alias

scripts/build_local.sh

@@ -1,6 +1,9 @@
 #!/bin/bash
 set -e
 
+# When did we run this build?
+date
+
 # Ensure we are running from the project root (parent of scripts/)
 cd "$(dirname "$0")/.."
 PROJECT_ROOT=$(pwd)
@@ -15,6 +18,32 @@ GH_PAGES_BRANCH="gh-pages"
 # Also add ucp-schema binary from sibling directory
 export PATH="$PROJECT_ROOT/.venv/bin:$PROJECT_ROOT/../ucp-schema/target/release:$PATH:$HOME/.cargo/bin"
 
+# Check UCP-Schema CLI version vs current Crates.io version and prompt
+PURPLE='\033[1;35m'
+NC='\033[0m' # No Color
+echo "Using ucp-schema CLI: $(which ucp-schema)"
+UCP_CLI_VERSION=$(ucp-schema --version | sed 's/ucp-schema //')
+echo "Local ucp-schema version:  '$UCP_CLI_VERSION'"
+UCP_CRATES_VERSION=$(cargo search ucp-schema -q | sed 's/ucp-schema = "//' | sed 's/".*$//')
+echo "Crates ucp-schema version: '$UCP_CRATES_VERSION'"
+if [[ $UCP_CLI_VERSION != "$UCP_CRATES_VERSION" ]]; then
+	while true; do
+		echo -e "${PURPLE}*ucp-schema version mismatch*${NC}"
+		read -r -p " Continue? (y/n) " yn
+		case $yn in
+		[Yy]*)
+			echo "proceed..."
+			break
+			;;
+		[Nn]*)
+			echo "exiting..."
+			exit
+			;;
+		*) echo "invalid response" ;;
+		esac
+	done
+fi
+
 if ! command -v mike >/dev/null 2>&1; then
 	echo "Error: mike executable not found in PATH."
 	echo "Please ensure you have run 'uv sync' in the root."