docs: harden vercel deploy wrapper

Author: Shooksie

docs/contributing/development.md

@@ -104,22 +104,28 @@ pinned in the root `Cargo.toml` and `crates/orchestrator-cli/Cargo.toml`.
 `npm run docs:deploy` wraps the required preflight in order: sync check,
 production site build, then a Vercel production deploy. The deploy helper
 runs the sync check directly, uses the repo-local `vitepress` binary from
-`node_modules/.bin` for the site build, then runs `npx vercel --yes --prod`
-through `timeout`/`gtimeout`. The `npx` path points npm at a temporary cache
+`node_modules/.bin` for the site build, then prefers a directly installed
+`vercel` binary and falls back to `npx vercel --yes --prod` through
+`timeout`/`gtimeout`. The `npx` fallback points npm at a temporary cache
 directory so the deploy command does not depend on a writable `~/.npm/`.
+If VitePress hits the transient missing `.vitepress/.temp/*.md.js` render
+failure, the helper clears temp/cache state and retries the local build once
+before failing.
 The deploy timeout defaults to `300` seconds and can be raised with
 `ANIMUS_VERCEL_TIMEOUT_SECONDS=<seconds> npm run docs:deploy`.
 
 The deploy step assumes the shell is already authenticated with Vercel. When
-using `npx`, it also assumes the runner can reach `registry.npmjs.org` to
+using the `npx` fallback, it also assumes the runner can reach
+`registry.npmjs.org` to
 resolve `vercel`. In restricted environments, expect the deploy phase to fail
 once it needs fresh network access, even when the docs are otherwise in sync.
 If `npm`/`npx` are missing from `PATH`, `scripts/deploy-docs.sh` also checks
 the repo-local `node_modules/.bin`, the active Node install's sibling `bin/`,
 common `nvm`/`volta`/`fnm`/`asdf` locations, and Homebrew paths before giving
-up. If none of those locations contain `npx`, the final Vercel deploy cannot
-proceed. The script also requires `timeout` (GNU coreutils) or `gtimeout`
-to bound the Vercel deploy step.
+up. The same PATH search applies to a directly installed `vercel` binary
+before the script falls back to `npx`. If neither route is available, the
+final Vercel deploy cannot proceed. The script also requires `timeout` (GNU
+coreutils) or `gtimeout` to bound the Vercel deploy step.
 
 Protocol schema exports live at the repo root:
 

scripts/deploy-docs.sh

@@ -61,11 +61,23 @@ resolve_timeout_bin() {
   return 1
 }
 
-if command -v vitepress >/dev/null 2>&1; then
+build_docs_once() {
+  local vitepress_build_log="$1"
+
   rm -rf docs/.vitepress/.temp docs/.vitepress/.cache
+  vitepress build docs >"$vitepress_build_log" 2>&1
+}
+
+if command -v vitepress >/dev/null 2>&1; then
   vitepress_build_log="$(mktemp "${TMPDIR:-/tmp}/animus-vitepress.XXXXXX")"
-  if ! vitepress build docs >"$vitepress_build_log" 2>&1; then
-    if rg -q '@rollup/rollup-darwin-arm64|ERR_DLOPEN_FAILED|Team IDs' "$vitepress_build_log"; then
+  if ! build_docs_once "$vitepress_build_log"; then
+    if rg -q "ERR_MODULE_NOT_FOUND.*docs/.vitepress/.temp.*\\.md\\.js|Cannot find module '.*/docs/.vitepress/.temp/.*\\.md\\.js'" "$vitepress_build_log"; then
+      echo "VitePress hit the transient missing-temp-module render failure; retrying once after a clean temp/cache reset." >&2
+      if ! build_docs_once "$vitepress_build_log"; then
+        cat "$vitepress_build_log" >&2
+        exit 1
+      fi
+    elif rg -q '@rollup/rollup-darwin-arm64|ERR_DLOPEN_FAILED|Team IDs' "$vitepress_build_log"; then
       echo "Local VitePress build is blocked by the known Rollup macOS native-module signing issue." >&2
       echo "Continuing to Vercel so the remote build can validate and publish the docs." >&2
     else
@@ -82,10 +94,20 @@ fi
 echo "Deploying docs with Vercel..."
 echo "Prerequisites: network access for Vercel and a valid Vercel login."
 
-npx_bin="$(resolve_node_package_manager_bin npx)" || {
-  echo "Unable to find npx. Install Node tooling or expose an existing Node install." >&2
-  exit 1
-}
+vercel_bin=""
+vercel_runner=()
+
+if command -v vercel >/dev/null 2>&1; then
+  vercel_bin="$(command -v vercel)"
+  vercel_runner=("$vercel_bin" --yes --prod)
+else
+  npx_bin="$(resolve_node_package_manager_bin npx)" || {
+    echo "Unable to find npx. Install Node tooling or expose an existing Node install." >&2
+    exit 1
+  }
+  vercel_bin="$npx_bin"
+  vercel_runner=("$npx_bin" vercel --yes --prod)
+fi
 
 npx_cache_dir="$(mktemp -d "${TMPDIR:-/tmp}/animus-vercel.XXXXXX")"
 trap 'rm -rf "$npx_cache_dir"' EXIT
@@ -96,7 +118,7 @@ timeout_bin="$(resolve_timeout_bin)" || {
   exit 1
 }
 vercel_timeout_seconds="${ANIMUS_VERCEL_TIMEOUT_SECONDS:-300}"
-echo "Using npx via $npx_bin."
+echo "Using Vercel command via $vercel_bin."
 echo "Using temporary npm cache at $npx_cache_dir."
 echo "Bounding Vercel deploy to ${vercel_timeout_seconds}s via $timeout_bin."
 
@@ -107,7 +129,7 @@ npm_config_fetch_retries=0 \
 npm_config_fetch_timeout=10000 \
 npm_config_fetch_retry_maxtimeout=10000 \
   "$timeout_bin" --foreground "${vercel_timeout_seconds}s" \
-  "$npx_bin" vercel --yes --prod >"$vercel_deploy_log" 2>&1
+  "${vercel_runner[@]}" >"$vercel_deploy_log" 2>&1
 vercel_exit_code=$?
 set -e