From d5c7e22080ed26019f9626f261d1893e81932bf5 Mon Sep 17 00:00:00 2001
From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
Date: Thu, 6 Aug 2026 16:11:53 +0800
Subject: [PATCH] fix(deploy): preflight HK helper capabilities

Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
---
 docs/pr-batch-test-runtime.md  | 16 ++++++++++++++++
 scripts/deploy-test-runtime.sh | 11 +++++++++++
 2 files changed, 27 insertions(+)

diff --git a/docs/pr-batch-test-runtime.md b/docs/pr-batch-test-runtime.md
index 318ff1ac..0bb3db95 100644
--- a/docs/pr-batch-test-runtime.md
+++ b/docs/pr-batch-test-runtime.md
@@ -53,6 +53,22 @@ The remote machine should expose a root-owned deployment command at:
 The dedicated deploy user is expected to have passwordless sudo access to
 that command only.
 
+Install or update that command from the repository copy when the workflow changes:
+
+```bash
+sudo install -o root -g root -m 0755 \
+  scripts/skillhub-test-deploy-remote.sh \
+  /usr/local/bin/skillhub-test-deploy
+```
+
+For sub-path validation, the installed helper must support:
+
+- `--public-url`
+- `--web-base-path`
+
+`scripts/deploy-test-runtime.sh` checks this before deployment and fails fast if the
+HK helper is outdated.
+
 ## Recommended usage
 
 Open the workflow in GitHub Actions and fill in:
diff --git a/scripts/deploy-test-runtime.sh b/scripts/deploy-test-runtime.sh
index f7ac30af..e1078285 100755
--- a/scripts/deploy-test-runtime.sh
+++ b/scripts/deploy-test-runtime.sh
@@ -187,6 +187,17 @@ if [[ -n "${web_base_path}" ]]; then
   normalized_web_base_path="$(normalize_base_path "${web_base_path}")"
 fi
 
+if [[ -n "${public_url}" || -n "${web_base_path}" ]]; then
+  helper_help="$(sudo /usr/local/bin/skillhub-test-deploy --help 2>&1 || true)"
+  if ! grep -Fq -- "--public-url" <<<"${helper_help}" || \
+     ! grep -Fq -- "--web-base-path" <<<"${helper_help}"; then
+    echo "HK deploy helper is outdated: /usr/local/bin/skillhub-test-deploy" >&2
+    echo "Install the current scripts/skillhub-test-deploy-remote.sh on the HK machine before sub-path validation." >&2
+    echo "Required helper options: --public-url and --web-base-path" >&2
+    exit 1
+  fi
+fi
+
 deploy_status=0
 sudo /usr/local/bin/skillhub-test-deploy \
   --deploy-tag "${deploy_tag}" \