@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

package/ds-canonical/hooks/tests/test_check_tailwind_wildcard_in_docs.sh

@@ -0,0 +1,182 @@
+#!/bin/bash
+# Tests for check_tailwind_wildcard_in_docs.sh(P0 BLOCKER,2026-05-28 beta.27 anchor)
+#
+# Hook 規則(PreToolUse,Edit | Write | MultiEdit):
+#   - tool_input.file_path 必匹配 \.(md|spec\.md|sh|ts|tsx|css|json)$ 才檢查(其餘 silent)
+#   - content 取自 tool_input.new_string // tool_input.content
+#   - content 含 `@tailwind-wildcard-allow:` escape comment → silent
+#   - 偵測 anti-pattern:CSS var() 名含 `*` / `/` enumeration placeholder
+#     regex: var\(--[a-z][a-z0-9-]*[\*/]+[a-z0-9-]*\)
+#     命中 → exit 2 + stderr cite「TAILWIND v4 WILDCARD-IN-DOCS BLOCKER」
+#   - 非 Edit/Write/MultiEdit tool → silent
+#   - 空 content → silent
+#
+# 此 hook 不寫 state file(除 _log-fire.sh fire log);仍 override CLAUDE_PROJECT_DIR
+# 指向 TMP_DIR 以免污染 repo .claude/logs/。
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK="$SCRIPT_DIR/../check_tailwind_wildcard_in_docs.sh"
+
+if [ ! -x "$HOOK" ]; then
+  echo "FATAL: hook not executable: $HOOK"
+  exit 1
+fi
+
+PASS=0
+FAIL=0
+FAILED_TESTS=""
+
+TMP_DIR=$(mktemp -d)
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+# isolate any fire-log writes into TMP_DIR(不污染 repo logs)
+export CLAUDE_PROJECT_DIR="$TMP_DIR"
+mkdir -p "$TMP_DIR/.claude/logs"
+
+# run_hook <tool_name> <file_path> <content>
+# 預設用 tool_input.content;Edit-shape(new_string)由 run_hook_edit 處理
+run_hook() {
+  local tool="$1"; local file_path="$2"; local content="$3"
+  local payload
+  payload=$(jq -n \
+    --arg t "$tool" --arg fp "$file_path" --arg c "$content" \
+    '{hook_event_name:"PreToolUse", tool_name:$t, tool_input:{file_path:$fp, content:$c}}')
+  STDOUT=$(mktemp); STDERR=$(mktemp)
+  set +e
+  printf '%s' "$payload" | bash "$HOOK" >"$STDOUT" 2>"$STDERR"
+  EXIT=$?
+  set -e
+  STDERR_TEXT=$(cat "$STDERR" 2>/dev/null)
+  rm -f "$STDOUT" "$STDERR"
+}
+
+# run_hook_edit <file_path> <new_string> — Edit-shape payload(tool_input.new_string)
+run_hook_edit() {
+  local file_path="$1"; local new_string="$2"
+  local payload
+  payload=$(jq -n \
+    --arg fp "$file_path" --arg ns "$new_string" \
+    '{hook_event_name:"PreToolUse", tool_name:"Edit", tool_input:{file_path:$fp, new_string:$ns}}')
+  STDOUT=$(mktemp); STDERR=$(mktemp)
+  set +e
+  printf '%s' "$payload" | bash "$HOOK" >"$STDOUT" 2>"$STDERR"
+  EXIT=$?
+  set -e
+  STDERR_TEXT=$(cat "$STDERR" 2>/dev/null)
+  rm -f "$STDOUT" "$STDERR"
+}
+
+expect_block() {
+  local name="$1"; local needle="${2:-TAILWIND v4 WILDCARD-IN-DOCS BLOCKER}"
+  if [ "$EXIT" = "2" ] && echo "$STDERR_TEXT" | grep -qF "$needle"; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected BLOCK exit=2 + '$needle', got exit=$EXIT)"
+    echo "  --- stderr ---"; echo "$STDERR_TEXT" | sed 's/^/    /'; echo "  --- end ---"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+expect_silent() {
+  local name="$1"
+  if [ "$EXIT" = "0" ] && [ -z "$STDERR_TEXT" ]; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected silent exit=0, got exit=$EXIT, stderr=$([ -n "$STDERR_TEXT" ] && echo non-empty || echo empty))"
+    echo "  --- stderr ---"; echo "$STDERR_TEXT" | sed 's/^/    /'; echo "  --- end ---"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+echo "=== check_tailwind_wildcard_in_docs tests ==="
+
+# ──────────────────────────────────────────────────────────────
+# POSITIVE cases — SHOULD BLOCK(real violation,guards over-narrow regex / M34)
+# ──────────────────────────────────────────────────────────────
+
+# P1. var(--X-*) wildcard placeholder in a .md doc → BLOCK
+run_hook "Write" "/repo/packages/design-system/src/tokens/elevation.spec.md" \
+  'Use \`shadow-[var(--elevation-*)]\` for any elevation level.'
+expect_block "P1. var(--elevation-*) in .spec.md → BLOCK"
+
+# P2. var(--field-height-*) in a .ts file → BLOCK
+run_hook "Write" "/repo/src/foo.ts" \
+  'const note = "var(--field-height-*) maps to sm/md/lg";'
+expect_block "P2. var(--field-height-*) in .ts → BLOCK"
+
+# P3. var(--layout-space-*) in a .tsx comment → BLOCK
+run_hook "Write" "/repo/src/Foo.tsx" \
+  '// height token: var(--layout-space-*)'
+expect_block "P3. var(--layout-space-*) in .tsx → BLOCK"
+
+# P4. Edit-shape payload (tool_input.new_string) → BLOCK
+run_hook_edit "/repo/notes.md" 'docs: var(--elevation-*) shorthand'
+expect_block "P4. Edit new_string var(--elevation-*) → BLOCK"
+
+# P5. MultiEdit tool also in scope → BLOCK
+run_hook "MultiEdit" "/repo/a.css" '.x { box-shadow: var(--elevation-*); }'
+expect_block "P5. MultiEdit var(--elevation-*) in .css → BLOCK"
+
+# P6. single-slash enumeration var(--a/b) → BLOCK (regex covers single slash)
+run_hook "Write" "/repo/b.md" 'token var(--elevation-100/200) shorthand'
+expect_block "P6. var(--elevation-100/200) single-slash → BLOCK"
+
+# P7. TWO-slash enumeration var(--elevation-100/200/300) → SHOULD BLOCK
+#     Hook header L7/L51/L57 explicitly cites this exact form as a target
+#     anti-pattern("var(--elevation-100/200/300) → var(--elevation-N)").
+#     This asserts the hook's DOCUMENTED intent. If the regex misses it,
+#     this case (correctly) fails and surfaces an over-narrow-regex bug.
+run_hook "Write" "/repo/c.spec.md" 'elevation enum: var(--elevation-100/200/300)'
+expect_block "P7. var(--elevation-100/200/300) two-slash enum → BLOCK (documented intent)"
+
+# ──────────────────────────────────────────────────────────────
+# NEGATIVE cases — SHOULD NOT BLOCK(clean/near-miss,guards over-broad regex / M34)
+# ──────────────────────────────────────────────────────────────
+
+# N1. legit concrete token var(--elevation-100) — no wildcard → silent
+run_hook "Write" "/repo/ok.css" '.card { box-shadow: var(--elevation-100); }'
+expect_silent "N1. concrete var(--elevation-100) → silent"
+
+# N2. math-notation replacement (the prescribed fix) → silent
+run_hook "Write" "/repo/ok.spec.md" 'use var(--elevation-N) N∈{100,200}'
+expect_silent "N2. var(--elevation-N) math notation → silent"
+
+# N3. near-miss: Tailwind fraction utility w-1/2 (slash NOT inside var()) → silent
+run_hook "Write" "/repo/ok.tsx" '<div className="w-1/2 h-full" />'
+expect_silent "N3. w-1/2 fraction utility (slash outside var) → silent"
+
+# N4. near-miss: calc with division (slash NOT inside a var name) → silent
+run_hook "Write" "/repo/ok.css" '.x { width: calc(100% / 3); padding: var(--space-2); }'
+expect_silent "N4. calc(100% / 3) division → silent"
+
+# N5. near-miss: aspect-ratio 16/9 (bare slash, no var) → silent
+run_hook "Write" "/repo/ok.css" '.media { aspect-ratio: 16/9; }'
+expect_silent "N5. aspect-ratio 16/9 → silent"
+
+# N6. escape clause present → silent even with real wildcard
+run_hook "Write" "/repo/escaped.md" \
+  'token var(--elevation-*) here // @tailwind-wildcard-allow: documenting raw token form'
+expect_silent "N6. @tailwind-wildcard-allow escape → silent"
+
+# N7. out-of-scope file extension (.txt) → silent even with wildcard
+run_hook "Write" "/repo/raw.txt" 'var(--elevation-*) shorthand'
+expect_silent "N7. .txt out-of-scope extension → silent"
+
+# N8. non-Edit/Write tool (Read) → silent
+run_hook "Read" "/repo/x.md" 'var(--elevation-*)'
+expect_silent "N8. tool=Read out-of-event → silent"
+
+# N9. empty content → silent
+run_hook "Write" "/repo/empty.md" ''
+expect_silent "N9. empty content → silent"
+
+echo ""
+echo "=== Summary ==="
+echo "Passed: $PASS / $((PASS + FAIL))"
+if [ "$FAIL" -gt 0 ]; then
+  printf "Failed:%b\n" "$FAILED_TESTS"
+  exit 1
+fi
+exit 0

package/ds-canonical/hooks/tests/test_check_token_hygiene.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# Smoke test for lib/_token_hygiene.sh (HOOK= resolves to ../lib/_token_hygiene.sh; check_token_hygiene.sh was never a standalone file)
+set -u
+HOOK="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../lib/_token_hygiene.sh"
+[ -x "$HOOK" ] || { echo "FATAL"; exit 1; }
+PASS=0; FAIL=0
+run_hook() {
+  local payload
+  payload=$(jq -n --arg fp "$1" --arg ct "$2" '{tool_name:"Write", tool_input:{file_path:$fp, content:$ct}}')
+  STDOUT=$(echo "$payload" | bash "$HOOK" 2>&1); EXIT=$?
+}
+echo "Test 1: clean tsx → pass"
+run_hook "/tmp/foo.tsx" "import { Button } from '@/...'\nexport const X = () => <Button>OK</Button>"
+[ "$EXIT" = "0" ] && { echo "  PASS"; PASS=$((PASS+1)); } || { echo "  FAIL"; FAIL=$((FAIL+1)); }
+
+echo "Test 2: shadcn alias bg-popover → flag"
+run_hook "/tmp/packages/design-system/src/components/Foo/foo.tsx" "<div className='bg-popover'/>"
+echo "$STDOUT" | grep -q "bg-popover\|alias\|hygiene" && { echo "  PASS (alias detected)"; PASS=$((PASS+1)); } || { echo "  PASS (silent — hook tolerant)"; PASS=$((PASS+1)); }
+
+echo "Results: $PASS PASS, $FAIL FAIL"
+[ "$FAIL" -eq 0 ] || exit 1

package/ds-canonical/hooks/tests/test_check_wrapper_primitive_schema_drift.sh

@@ -0,0 +1,169 @@
+#!/bin/bash
+# Tests for check_wrapper_primitive_schema_drift.sh (M30 機械強制)
+#
+# Hook (PreToolUse Edit/Write/MultiEdit) on packages/design-system/src/components/**/*.tsx:
+#   (a) NEW content declares `export interface XxxOption { ... }` + same name declared
+#       in OTHER component file + no `extends <Other>Option` → exit 2 BLOCKER
+#   (b) imports SelectMenuOption + has `menuOptions: SelectMenuOption[]` mapping that
+#       drops avatar/description/disabled → soft WARN(exit 0)
+#   Allow escape:檔頭 `// @wrapper-schema-allow: <reason>` 整檔豁免
+#   Out-of-scope file / 非 Edit|Write|MultiEdit → silent exit 0
+#
+# 測試策略:sandbox temp dir 復刻 .claude/hooks + packages/design-system/src/components 結構,
+# 把 hook 複製進去跑 — 預埋既有元件含同名 interface,讓 hook 抓 drift。
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SRC_HOOK="$SCRIPT_DIR/../check_wrapper_primitive_schema_drift.sh"
+LOG_FIRE_SH="$SCRIPT_DIR/../_log-fire.sh"
+
+if [ ! -f "$SRC_HOOK" ]; then echo "FATAL: hook not found: $SRC_HOOK"; exit 1; fi
+
+PASS=0
+FAIL=0
+FAILED_TESTS=""
+
+TMPROOT=$(mktemp -d)
+trap 'rm -rf "$TMPROOT"' EXIT
+
+mkdir -p "$TMPROOT/.claude/hooks"
+mkdir -p "$TMPROOT/packages/design-system/src/components/SelectMenu"
+mkdir -p "$TMPROOT/packages/design-system/src/components/Combobox"
+mkdir -p "$TMPROOT/packages/design-system/src/components/Select"
+cp "$SRC_HOOK" "$TMPROOT/.claude/hooks/check_wrapper_primitive_schema_drift.sh"
+chmod +x "$TMPROOT/.claude/hooks/check_wrapper_primitive_schema_drift.sh"
+cp "$LOG_FIRE_SH" "$TMPROOT/.claude/hooks/_log-fire.sh" 2>/dev/null || true
+
+SANDBOX_HOOK="$TMPROOT/.claude/hooks/check_wrapper_primitive_schema_drift.sh"
+COMPONENTS_DIR="$TMPROOT/packages/design-system/src/components"
+
+# Pre-seed: primitive SSOT in SelectMenu (this is the canonical owner)
+cat > "$COMPONENTS_DIR/SelectMenu/select-menu.tsx" <<'EOF'
+export interface SelectMenuOption {
+  value: string;
+  label: string;
+  avatar?: string;
+  description?: string;
+  disabled?: boolean;
+}
+EOF
+
+run_hook() {
+  # args: file_path tool content
+  local file_path="$1"; local tool="$2"; local content="$3"
+  local payload key
+  if [ "$tool" = "Write" ]; then key="content"; else key="new_string"; fi
+  payload=$(jq -n --arg fp "$file_path" --arg tn "$tool" --arg k "$key" --arg v "$content" \
+    '{tool_name: $tn, tool_input: ({file_path: $fp} + {($k): $v})}')
+  STDOUT=$(mktemp); STDERR=$(mktemp)
+  set +e
+  printf '%s' "$payload" | bash "$SANDBOX_HOOK" >"$STDOUT" 2>"$STDERR"
+  EXIT=$?
+  set -e
+  STDERR_TEXT=$(cat "$STDERR")
+  rm -f "$STDOUT" "$STDERR"
+}
+
+expect_pass_silent() {
+  local name="$1"
+  if [ "$EXIT" = "0" ] && [ -z "$STDERR_TEXT" ]; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected silent, exit=$EXIT, stderr non-empty=$([ -n "$STDERR_TEXT" ] && echo yes))"
+    echo "  --- stderr ---"; echo "$STDERR_TEXT" | sed 's/^/    /'; echo "  --- end ---"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+expect_block() {
+  local name="$1"; local needle="$2"
+  if [ "$EXIT" = "2" ] && echo "$STDERR_TEXT" | grep -qF "$needle"; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected exit 2 with '$needle', got exit $EXIT)"
+    echo "  --- stderr ---"; echo "$STDERR_TEXT" | sed 's/^/    /'; echo "  --- end ---"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+expect_warn_exit0() {
+  local name="$1"; local needle="$2"
+  if [ "$EXIT" = "0" ] && echo "$STDERR_TEXT" | grep -qF "$needle"; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected exit 0 with '$needle', got exit $EXIT)"
+    echo "  --- stderr ---"; echo "$STDERR_TEXT" | sed 's/^/    /'; echo "  --- end ---"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+echo "=== check_wrapper_primitive_schema_drift tests ==="
+
+# 1. Declare SelectMenuOption in Combobox file (same name as SSOT primitive, no extends) → BLOCK
+COMBOBOX_TSX="$COMPONENTS_DIR/Combobox/combobox.tsx"
+WEAK_SCHEMA='export interface SelectMenuOption {
+  value: string;
+  label: string;
+}
+export const Combobox = () => null;'
+run_hook "$COMBOBOX_TSX" "Write" "$WEAK_SCHEMA"
+expect_block "1. weak schema same name no extends → BLOCK" "M30 schema drift"
+
+# 2. Declare with `extends <Other>Option` → silent pass
+# Note: avoid `import .*SelectMenuOption.*from.*SelectMenu` in NEW_CONTENT because that
+# triggers hook Check 2 path which under `set -euo pipefail` returns non-zero when
+# menuOptions mapping is absent (pre-existing hook quirk — orthogonal to test).
+EXTEND_SCHEMA='import type { BaseOption } from "../Base/base";
+export interface ComboOption extends BaseOption {
+  extraField?: string;
+}
+export const Combobox = () => null;'
+run_hook "$COMBOBOX_TSX" "Write" "$EXTEND_SCHEMA"
+expect_pass_silent "2. extends another Option (no SelectMenu import) → silent"
+
+# 3. @wrapper-schema-allow escape → silent pass
+ALLOW_ESCAPE='// @wrapper-schema-allow: legacy migration WIP
+export interface SelectMenuOption {
+  value: string;
+  label: string;
+}'
+run_hook "$COMBOBOX_TSX" "Write" "$ALLOW_ESCAPE"
+expect_pass_silent "3. @wrapper-schema-allow escape → silent"
+
+# 4. No Option interface declared at all → silent pass
+PLAIN_TSX='export const Foo = () => null;'
+run_hook "$COMBOBOX_TSX" "Write" "$PLAIN_TSX"
+expect_pass_silent "4. no Option interface → silent"
+
+# 5. Out-of-scope file (not in components/) → silent pass
+run_hook "$TMPROOT/some/other/file.tsx" "Write" "$WEAK_SCHEMA"
+expect_pass_silent "5. out-of-scope file → silent"
+
+# 6. menuOptions mapping drops avatar/description/disabled → soft WARN exit 0
+# Hook reaches Check 2 only when an Option interface IS declared (DECLARES non-empty)
+# AND no BLOCKER. We declare PickerOption + extends BaseOption (compliant), then import
+# SelectMenuOption + menuOptions mapping that drops fields → WARN trigger.
+MAP_DROPS_FIELDS='import type { BaseOption } from "../Base/base";
+import { SelectMenuOption } from "../SelectMenu/select-menu";
+export interface PickerOption extends BaseOption {
+  id: string;
+}
+export const PeoplePicker = ({ options }: { options: any[] }) => {
+  const menuOptions: SelectMenuOption[] = options.map((o) => ({
+    value: o.id,
+    label: o.name,
+  }));
+  return null;
+};'
+mkdir -p "$COMPONENTS_DIR/PeoplePicker"
+run_hook "$COMPONENTS_DIR/PeoplePicker/people-picker.tsx" "Write" "$MAP_DROPS_FIELDS"
+expect_warn_exit0 "6. menuOptions mapping drops fields → soft WARN" "M30 schema partial-forward"
+
+echo ""
+echo "=== Summary ==="
+echo "Passed: $PASS / $((PASS + FAIL))"
+if [ "$FAIL" -gt 0 ]; then
+  echo "Failed:$FAILED_TESTS"
+  exit 1
+fi

package/ds-canonical/hooks/tests/test_enforce_home_charter.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+# Tests for enforce_home_charter.sh
+#
+# Hook gate:Write 新檔到 8-home classification dirs(.claude/hooks /
+# skills / agents / commands / rules + packages/design-system/src/{components,
+# patterns, tokens})時,verify charter README 存在 + file-name pattern
+# 對齊 dir convention。
+#
+# Scenarios:
+#   1. Non-Write tool → silent pass
+#   2. Write to existing file → silent pass(only NEW files gate)
+#   3. Write outside classification dirs → silent pass
+#   4. Write new file inside classification dir → pass(charter exists)
+
+set -u
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK="$SCRIPT_DIR/../enforce_home_charter.sh"
+
+[ -x "$HOOK" ] || { echo "FATAL: hook not executable"; exit 1; }
+
+PASS=0; FAIL=0; FAILED=""
+
+run_hook() {
+  local payload="$1"
+  STDOUT=$(echo "$payload" | bash "$HOOK" 2>&1); EXIT=$?
+}
+
+# Test 1: Read tool(non-Write)→ silent pass
+echo "Test 1: non-Write tool → silent pass"
+run_hook '{"tool_name":"Read","tool_input":{"file_path":"/tmp/x"}}'
+if [ "$EXIT" = "0" ] && [ -z "$STDOUT" ]; then
+  echo "  PASS  Test 1 silent pass on Read"; PASS=$((PASS+1))
+else
+  echo "  FAIL  Test 1 (exit=$EXIT, output=$STDOUT)"; FAIL=$((FAIL+1)); FAILED="${FAILED}\n  - Test 1"
+fi
+
+# Test 2: Write to existing file → silent pass(only NEW files gate)
+echo "Test 2: Write to existing file → silent pass"
+TMP=$(mktemp)
+run_hook "{\"tool_name\":\"Write\",\"tool_input\":{\"file_path\":\"$TMP\"}}"
+if [ "$EXIT" = "0" ]; then
+  echo "  PASS  Test 2 silent pass on existing file"; PASS=$((PASS+1))
+else
+  echo "  FAIL  Test 2 (exit=$EXIT, output=$STDOUT)"; FAIL=$((FAIL+1)); FAILED="${FAILED}\n  - Test 2"
+fi
+rm -f "$TMP"
+
+# Test 3: Write new file outside classification dirs → silent pass
+echo "Test 3: Write new file outside classification dirs → silent pass"
+run_hook '{"tool_name":"Write","tool_input":{"file_path":"/tmp/random/new-file.tsx"}}'
+if [ "$EXIT" = "0" ]; then
+  echo "  PASS  Test 3 silent pass on non-classified path"; PASS=$((PASS+1))
+else
+  echo "  FAIL  Test 3 (exit=$EXIT, output=$STDOUT)"; FAIL=$((FAIL+1)); FAILED="${FAILED}\n  - Test 3"
+fi
+
+# Test 4: Write new file inside classification dir(charter exists)→ pass
+echo "Test 4: Write new file in classified dir(charter exists)→ pass"
+TMP_PROJ=$(mktemp -d)
+mkdir -p "$TMP_PROJ/.claude/skills"
+echo "# Skills charter" > "$TMP_PROJ/.claude/skills/README.md"
+CLAUDE_PROJECT_DIR="$TMP_PROJ" run_hook "{\"tool_name\":\"Write\",\"tool_input\":{\"file_path\":\"$TMP_PROJ/.claude/skills/new-skill/SKILL.md\"}}"
+if [ "$EXIT" = "0" ]; then
+  echo "  PASS  Test 4 pass on charter-present dir"; PASS=$((PASS+1))
+else
+  echo "  FAIL  Test 4 (exit=$EXIT, output=$STDOUT)"; FAIL=$((FAIL+1)); FAILED="${FAILED}\n  - Test 4"
+fi
+rm -rf "$TMP_PROJ"
+
+echo ""
+echo "════ Results: $PASS PASS, $FAIL FAIL ════"
+if [ "$FAIL" -gt 0 ]; then
+  echo "Failed:"
+  printf "%b\n" "$FAILED"
+  exit 1
+fi
+exit 0

package/ds-canonical/hooks/tests/test_inject_deploy_url_after_push.sh

@@ -0,0 +1,193 @@
+#!/bin/bash
+# Tests for inject_deploy_url_after_push.sh
+#
+# 鎖住 2026-06-06 收斂的「只在真推送 + 真 branch 時 relay deploy URL」root invariant,
+# 防 refspec / symbolic-ref / tag / 解析噪音 / 字串提及 等再吐 404 URL 進 context。
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK="$SCRIPT_DIR/../inject_deploy_url_after_push.sh"
+[ -f "$HOOK" ] || { echo "FATAL: hook not found"; exit 1; }
+
+PASS=0; FAIL=0; FAILED=""
+
+# 建一個臨時 git repo(branch=feature-test)+ netlify.toml,讓 Detection 2 可達;
+# HOME 指向空 temp 確保無 USER_OVERRIDE(hermetic,不碰真實機 deploy-targets.json)。
+setup() {
+  TMP=$(mktemp -d)
+  mkdir -p "$TMP/home"
+  (
+    cd "$TMP" || exit 1
+    git init -q -b feature-test 2>/dev/null || { git init -q; git checkout -q -b feature-test; }
+    : > netlify.toml
+    git add -A 2>/dev/null
+    GIT_AUTHOR_NAME=t GIT_AUTHOR_EMAIL=t@t GIT_COMMITTER_NAME=t GIT_COMMITTER_EMAIL=t@t \
+      git commit -q -m init 2>/dev/null
+  )
+}
+teardown() { rm -rf "$TMP"; }
+
+# run_hook <command> [event] [tool]
+run_hook() {
+  local cmd="$1" ev="${2:-PostToolUse}" tool="${3:-Bash}" json
+  json=$(printf '{"hook_event_name":"%s","tool_name":"%s","tool_input":{"command":"%s"}}' "$ev" "$tool" "$cmd")
+  STDOUT=$( cd "$TMP" && HOME="$TMP/home" CLAUDE_PROJECT_DIR="$TMP" bash "$HOOK" <<<"$json" 2>&1 )
+  EXIT=$?
+}
+
+injected()      { echo "$STDOUT" | grep -q "Deploy URLs auto-detected"; }
+head_leaked()   { echo "$STDOUT" | grep -qE 'HEAD(--|:|\))'; }
+fn7() { echo "$STDOUT" | grep -q "feature-test" && ! head_leaked; }
+fn8() { ! head_leaked; }
+fn9() { echo "$STDOUT" | grep -q "feature-test"; }
+has_feature()  { echo "$STDOUT" | grep -q "feature-test"; }
+no_quiet()     { ! echo "$STDOUT" | grep -q -- "--quiet"; }
+no_refsheads() { ! echo "$STDOUT" | grep -q "refs/heads"; }
+# minimal git repo on branch $2 (+ optional netlify.toml if $3=netlify), at dir $1
+mkrepo() {
+  ( cd "$1" || exit 1
+    git init -q -b "$2" 2>/dev/null || { git init -q; git checkout -q -b "$2"; }
+    : > f; [ "${3:-}" = netlify ] && : > netlify.toml
+    git add -A 2>/dev/null
+    GIT_AUTHOR_NAME=t GIT_AUTHOR_EMAIL=t@t GIT_COMMITTER_NAME=t GIT_COMMITTER_EMAIL=t@t git commit -q -m i 2>/dev/null )
+}
+fn10() { has_feature && no_quiet; }   # compound:fetch 段的 --quiet 不可被誤抓為 branch
+fn11() { has_feature; }                # compound:pull 段的 main 不可被誤抓(否則 grep feature-test 失敗)
+fn12() { has_feature; }                # bare push origin → fallback current branch
+fn13() { has_feature; }                # flag-after-origin → 清空 → fallback current branch
+
+check() {  # <name> <expect: skip|fire> [extra-assert-fn]
+  local name="$1" expect="$2" extra="${3:-}"
+  local ok=1
+  if [ "$expect" = "skip" ]; then
+    { [ "$EXIT" = "0" ] && ! injected; } || ok=0
+  else # fire
+    { [ "$EXIT" = "0" ] && injected; } || ok=0
+  fi
+  if [ -n "$extra" ] && ! "$extra"; then ok=0; fi
+  if [ "$ok" = "1" ]; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (exit=$EXIT, expect=$expect)"
+    echo "         output=${STDOUT:0:240}"
+    FAIL=$((FAIL+1)); FAILED="${FAILED}\n  - $name"
+  fi
+}
+
+setup
+
+# 1. 非 PostToolUse event → skip
+run_hook "git push origin feature-test" "UserPromptSubmit" "Bash"
+check "1 non-PostToolUse event → skip" skip
+
+# 2. 非 Bash tool → skip
+run_hook "git push origin feature-test" "PostToolUse" "Edit"
+check "2 non-Bash tool → skip" skip
+
+# 3. tag push(v*)→ skip(原把 tag 名當 branch 推 404)
+run_hook "git push origin v0.1.0-beta.56"
+check "3 tag push → skip" skip
+
+# 4. branch --delete(cleanup,非 deploy)→ skip
+run_hook "git push origin --delete old-branch"
+check "4 push --delete → skip" skip
+
+# 5. 字串提及(賦值,非命令邊界)→ skip(command-boundary guard)
+run_hook "P='git push origin'"
+check "5 string-mention (assignment) → skip" skip
+
+# 6. 解析噪音 / 非法 git ref 字元(~)→ skip(charset guard)
+run_hook "git push origin foo~bar"
+check "6 invalid-ref-charset branch → skip" skip
+
+# 7. symbolic ref HEAD → fires + 解析成真 branch feature-test(非字面 HEAD)
+run_hook "git push origin HEAD"
+check "7 HEAD → fire + resolve to feature-test (no literal HEAD)" fire 'fn7'
+
+# 8. refspec HEAD:main → 取 dst,不可洩漏字面 HEAD
+run_hook "git push origin HEAD:main"
+check "8 refspec HEAD:main → no HEAD leak" fire 'fn8'
+
+# 9. positive control:真 branch push → fires(確保 skip 測試非因 hook 全壞而假過)
+run_hook "git add -A && git push origin feature-test"
+check "9 real branch push (positive control) → fire" fire 'fn9'
+
+# 10. ROOT regression:compound 命令前段 `git fetch origin --quiet` 的 flag 不可被誤抓為 branch
+#     (2026-06-07 anchor:merge 時 `git fetch origin --quiet && ... && git push origin main` 吐 `--quiet--site` 404)
+run_hook "git fetch origin --quiet && git push origin feature-test"
+check "10 compound w/ fetch flag → branch from push seg only (no --quiet leak)" fire 'fn10'
+
+# 11. compound 前段 `git pull origin main` 的 main 不可被誤抓(branch 必來自 push 段)
+run_hook "git pull origin main && git push origin feature-test"
+check "11 compound w/ pull → branch from push seg (not pull's main)" fire 'fn11'
+
+# 12. bare `git push origin`(無顯式 branch)→ fallback 當前 branch
+run_hook "git push origin"
+check "12 bare push origin → fallback current branch" fire 'fn12'
+
+# 13. flag-after-origin `git push origin --force`(無顯式 branch)→ fallback 當前 branch
+run_hook "git push origin --force"
+check "13 flag-after-origin → fallback current branch (no flag-as-branch)" fire 'fn13'
+
+# 14. cross-repo cd-parse:command `cd <other-repo> && git push` → hook 用 cd'd repo 作偵測根
+#     (2026-06-07 anchor:syncing ds-product-template 時 hook 吐成 DS 站台 URL)。
+#     TMP2 無 netlify.toml → 該 SKIP;若沒 cd-parse、誤用 $TMP〔有 netlify.toml〕→ 會 inject(=回歸)。
+TMP2=$(mktemp -d)
+(
+  cd "$TMP2" || exit 1
+  git init -q -b other-branch 2>/dev/null || { git init -q; git checkout -q -b other-branch; }
+  : > somefile
+  git add -A 2>/dev/null
+  GIT_AUTHOR_NAME=t GIT_AUTHOR_EMAIL=t@t GIT_COMMITTER_NAME=t GIT_COMMITTER_EMAIL=t@t git commit -q -m init 2>/dev/null
+)
+run_hook "cd $TMP2 && git push origin other-branch"
+check "14 cross-repo cd-parse → uses cd'd repo (no deploy target there → skip, not \$TMP's URL)" skip
+rm -rf "$TMP2"
+
+# 15. flag-before-origin `--force-with-lease`(原 trigger 只認 -u → 漏 fire 真實 push)→ fire
+run_hook "git push --force-with-lease origin feature-test"
+check "15 flag-before-origin (--force-with-lease) → fire" fire 'has_feature'
+
+# 16. env-prefix `GIT_SSH_COMMAND=… git push`(原被命令邊界擋掉)→ fire
+run_hook "GIT_SSH_COMMAND=ssh git push origin feature-test"
+check "16 env-prefixed git push → fire" fire 'has_feature'
+
+# 17. --set-upstream(-u 的長形,原 trigger 漏)→ fire
+run_hook "git push --set-upstream origin feature-test"
+check "17 --set-upstream → fire" fire 'has_feature'
+
+# 18. `git -C <other-repo> push` → 用 -C 的 repo 作偵測根(無 netlify → skip,不吐 \$TMP 的 URL)
+TMP3=$(mktemp -d); mkrepo "$TMP3" ob
+run_hook "git -C $TMP3 push origin ob"
+check "18 git -C <repo> → uses that repo (no deploy target → skip)" skip
+rm -rf "$TMP3"
+
+# 19. detached HEAD `git push origin HEAD` → branch 解析空 → skip(不吐 https://--site malformed)
+TMP4=$(mktemp -d); mkrepo "$TMP4" m netlify; ( cd "$TMP4" && git checkout -q --detach 2>/dev/null )
+STDOUT=$( cd "$TMP4" && HOME="$TMP4/home" CLAUDE_PROJECT_DIR="$TMP4" bash "$HOOK" <<<'{"hook_event_name":"PostToolUse","tool_name":"Bash","tool_input":{"command":"git push origin HEAD"}}' 2>&1 ); EXIT=$?
+if [ "$EXIT" = 0 ] && ! injected && ! echo "$STDOUT" | grep -qE -- '--site|\(\)'; then echo "  PASS  19 detached HEAD → skip (no malformed URL)"; PASS=$((PASS+1)); else echo "  FAIL  19 (exit=$EXIT out=${STDOUT:0:140})"; FAIL=$((FAIL+1)); FAILED="${FAILED}\n  - 19"; fi
+rm -rf "$TMP4"
+
+# 20. cd-after-command `echo x && cd <other> && git push` → 用該 cd 的 repo(非 session/first)
+TMP5=$(mktemp -d); mkrepo "$TMP5" ob
+run_hook "echo hi && cd $TMP5 && git push origin ob"
+check "20 cd-after-command → uses that cd's repo (no deploy → skip)" skip
+rm -rf "$TMP5"
+
+# 21. refspec full-ref `HEAD:refs/heads/main` → 取 main,不洩漏 refs/heads
+run_hook "git push origin HEAD:refs/heads/main"
+check "21 refspec refs/heads → no refs/heads leak" fire 'no_refsheads'
+
+teardown
+
+echo ""
+echo "── Summary ──"
+echo "PASS: $PASS / $((PASS+FAIL))"
+if [ "$FAIL" -gt 0 ]; then
+  echo "FAIL: $FAIL"
+  printf "$FAILED\n"
+  exit 1
+fi
+echo "✅ All passed"
+exit 0