@qijenchen/design-system 0.1.0-beta.69 → 0.1.0-beta.71

package/ds-canonical/fork/hooks/inject_deploy_url_after_push.sh

@@ -0,0 +1,238 @@
+#!/bin/bash
+# inject_deploy_url_after_push.sh — UserPromptSubmit + PostToolUse: 偵測 git push 後自動 inject deploy URL
+#
+# Per user verbatim 2026-05-26:「完成部署之後都應該自動回吐部署的連結,每次必定自動回,不論是現在這個 session 還是其他的」
+# Per user verbatim 2026-05-27:「不管在任何 repo,只要有部署東西到 netlify 上不管是否是 production 都應該要提供連結」
+#
+# Mechanism(2026-05-27 v2 expand scope per user complaint — DS GH Pages also auto-provide URL):
+#   PostToolUse Bash:tool_input.command 含 `git push origin <branch>` → 偵測 → multi-target URL detection:
+#     1. Netlify(scripts/deploy-url.mjs + .netlify/state.json)— PW + fork
+#     2. Netlify dashboard-link(netlify.toml exists,no state.json)— PW with Netlify auto-build
+#     3. GitHub Pages(.github/workflows/*.yml 含 pages action)— DS repo
+#   → output URL list inject into AI context(下個 reply 必看到)
+#
+# 為何走 Hook(per CLAUDE.md governance 8-home L7 Hook 自動化):
+#   - 不靠 AI 記得「每次推完都要 echo URL」(會忘記 — 本 session user 抓「你他媽到底做得怎樣」)
+#   - 不靠 user 每次問「部署到哪?」(無聊重複)
+#   - Hook 機械保證每 push 必觸發,跨 session / 跨 fork user 自動受惠
+#
+# Scope expanded(2026-05-27):
+#   - Netlify CLI-linked (.netlify/state.json + scripts/deploy-url.mjs) → 直接 script 抓 URL
+#   - Netlify dashboard-linked (netlify.toml + branch deploys) → 用 git remote 推導 site name
+#   - GitHub Pages (.github/workflows/*.yml 含 pages.yml OR ci.yml deploy-pages) → 推導 GH Pages URL
+#
+# 對齊:.claude/skills/codex-collab/SKILL.md PostToolUse pattern + check_fork_user_plugin_install.sh detection pattern
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+INPUT=$(cat 2>/dev/null || echo "{}")
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+CMD=$(echo "$INPUT" | jq -r '.tool_input.command // ""' 2>/dev/null)
+
+# Scope:PostToolUse Bash 且 cmd 含 git push to remote(main / branch)
+[ "$EVENT" != "PostToolUse" ] && exit 0
+[ "$TOOL" != "Bash" ] && exit 0
+
+# Heuristic:detect `git push origin <branch>` patterns
+# 2026-06-06 fix:要求 `git push` 在「命令邊界」(行首 / ; / && / || / $( )擋字串提及(`P='git push origin'`)。
+# 2026-06-07 fix(對抗 sweep):容忍 env-prefix(`GIT_SSH_COMMAND=… git push`)/ `git -C <dir>` /
+# push 前後任意 flag(`--force-with-lease` / `-f` / `--set-upstream` / `--no-verify` 等)。原本只認 `-u`
+# → 漏 fire 在這些「真實 push」上 = 該吐 URL 卻沒吐,defeat hook purpose。
+_ENVP='([A-Za-z_][A-Za-z0-9_]*=[^[:space:]]+[[:space:]]+)*'
+_GITPRE='git[[:space:]]+(-C[[:space:]]+[^[:space:]]+[[:space:]]+|-[A-Za-z][^[:space:]]*[[:space:]]+)*push'
+_PUSHFLAGS='([[:space:]]+-{1,2}[A-Za-z][^[:space:]]*)*'
+if ! echo "$CMD" | grep -qE "(^|[;&|(])[[:space:]]*${_ENVP}${_GITPRE}${_PUSHFLAGS}[[:space:]]+origin\b"; then
+  exit 0
+fi
+
+# Skip if push --delete (branch cleanup, not deploy)
+if echo "$CMD" | grep -qE 'push\s+origin\s+--delete'; then
+  exit 0
+fi
+
+CWD=$(pwd)
+# 2026-06-07 fix:偵測「真實 working dir」作 deploy-target 偵測根,跨 repo push 不吐「錯 repo」URL
+# (anchor:syncing ds-product-template 時吐成 DS 站台 URL)。優先 `git -C <dir>`;否則命令鏈中
+# 「最後一個 cd」(= push 時 effective cwd,**非第一個**;`echo x && cd /other && git push` 必用 /other)。
+_GITC=$(echo "$CMD" | grep -oE 'git[[:space:]]+-C[[:space:]]+[^[:space:]]+' | head -1 | sed -E 's/.*-C[[:space:]]+//; s/^"//; s/"$//')
+_LASTCD=$(echo "$CMD" | grep -oE '(^|[;&|(])[[:space:]]*cd[[:space:]]+[^;&|]+' | tail -1 | sed -E 's/.*cd[[:space:]]+//; s/[[:space:]]+$//; s/^"//; s/"$//')
+for _d in "$_GITC" "$_LASTCD"; do
+  if [ -n "$_d" ] && [ -d "$_d" ] && git -C "$_d" rev-parse --git-dir >/dev/null 2>&1; then CWD="$_d"; break; fi
+done
+URLS_FOUND=""
+# 2026-06-07 ROOT fix:只從「git push ... origin <ref>」這一段擷取 branch,不是整條 compound command 的
+# 第一個 `origin X`。否則 `git fetch origin --quiet && git push origin main` 會誤抓 fetch 段的 `--quiet`
+# 當 branch → 推導 `--quiet--site` 404(此前 5 道 guard 都沒擋到,因 `--quiet` 全是合法 git ref 字元)。
+# 隔出 push 段(到下個 command 分隔 ; & | 為止)後,取 origin 後第一個 token。
+# PUSH_SEG 用同一 env/-C/flag-tolerant prefix 隔出 push 段(到下個分隔 ; & | 為止),再取 origin 後第一 token
+PUSH_SEG=$(echo "$CMD" | grep -oE "(^|[;&|(])[[:space:]]*${_ENVP}${_GITPRE}[^;&|]*" | head -1)
+BRANCH=$(echo "$PUSH_SEG" | grep -oE 'origin[[:space:]]+[^[:space:]]+' | head -1 | awk '{print $2}')
+# origin 後第一個 token 是 flag(`git push origin --force` = 無顯式 branch)→ 清空走 current-branch fallback
+case "$BRANCH" in -*) BRANCH="" ;; esac
+# 2026-06-06 fix:refspec `src:dst` → 取 dst(`HEAD:main` → `main`),否則推導出 `HEAD:main--site` 404 URL
+case "$BRANCH" in *:*) BRANCH="${BRANCH##*:}" ;; esac
+# 2026-06-07 fix:full-ref dst — `HEAD:refs/heads/main` → `main`(否則 `refs/heads/main--site` 誤判 preview);
+# `refs/tags/...` → tag push,skip
+case "$BRANCH" in refs/tags/*) exit 0 ;; esac
+BRANCH="${BRANCH#refs/heads/}"
+# 2026-06-06 fix:`git push origin HEAD`(或 `@`)= symbolic ref 指向當前 branch → 解析成真 branch 名。
+# 2026-06-07 fix:detached HEAD 時 show-current 回「空字串 + exit 0」→ BRANCH 留空,交給下方 value-based fallback
+# (原 `|| echo ""` 沒用,因 git 不是失敗而是成功回空)。
+if [ "$BRANCH" = "HEAD" ] || [ "$BRANCH" = "@" ]; then
+  BRANCH=$(git -C "$CWD" branch --show-current 2>/dev/null)
+fi
+# 2026-06-06 fix:BRANCH 含非法 git ref 字元(" ' 空白 \ 等)→ 此命令只是「字串裡含 git push origin」
+# (測試迴圈 / 文件 / echo),非真推送 → skip,避免把 `main"` 等垃圾推導成 404 URL 注入 context。
+# git ref 合法字元集 ⊂ [A-Za-z0-9._/-];非此集 = 必為解析噪音(root guard,涵蓋 refspec/tag 之外的雜訊)。
+if [ -n "$BRANCH" ] && ! echo "$BRANCH" | grep -qE '^[A-Za-z0-9._/-]+$'; then exit 0; fi
+# 2026-06-06 fix:tag push(`v1.2.3` 等)不產 branch-preview / production deploy → skip,
+# 否則把 tag 名當 branch 推導出 `v0.1.0-beta.56--site` 404 URL(release tag push 每次都誤吐)
+if echo "$BRANCH" | grep -qE '^v[0-9]'; then exit 0; fi
+if [ -n "$BRANCH" ] && git -C "$CWD" rev-parse --verify --quiet "refs/tags/$BRANCH" >/dev/null 2>&1; then exit 0; fi
+# 2026-06-07 fix:仍空(bare `git push origin` / detached HEAD / 解析不出)→ 取 current branch(value-based);
+# 仍空 → 無法產生合法 URL(會變 `https://--site` malformed)→ skip,不亂猜 main。
+[ -z "$BRANCH" ] && BRANCH=$(git -C "$CWD" branch --show-current 2>/dev/null)
+[ -z "$BRANCH" ] && exit 0
+
+# v3 2026-05-27:curl HEAD verify URL before reporting(per user「你確定有做到」complaint)
+# v4 2026-05-27:add content sniff(防 squat URLs 200 但 unrelated content)
+verify_url() {
+  local url="$1"
+  local code=$(curl -s -o /dev/null -w "%{http_code}" -L --max-time 5 -I "$url" 2>/dev/null)
+  case "$code" in
+    200|301|302) echo "OK" ;;
+    *) echo "FAIL:$code" ;;
+  esac
+}
+
+# v4 content sniff:check 200 URL 是 Storybook real deploy(not squat)
+# 用 Storybook hallmark patterns(sb-manager / sb-addons / @storybook/core title)
+is_storybook_deploy() {
+  local url="$1"
+  curl -s --max-time 5 -L "$url" 2>/dev/null | grep -qE "sb-manager|sb-addons|@storybook/core|storybook-static"
+}
+
+# Detection 1:Netlify CLI-linked(.netlify/state.json + scripts/deploy-url.mjs)
+DEPLOY_SCRIPT="$CWD/scripts/deploy-url.mjs"
+if [ -f "$DEPLOY_SCRIPT" ] && [ -f "$CWD/.netlify/state.json" ]; then
+  URL_INFO=$(node "$DEPLOY_SCRIPT" --json 2>/dev/null)
+  if [ -n "$URL_INFO" ]; then
+    URL=$(echo "$URL_INFO" | jq -r '.url // ""' 2>/dev/null)
+    IS_PROD=$(echo "$URL_INFO" | jq -r '.isProd // false' 2>/dev/null)
+    if [ -n "$URL" ]; then
+      if [ "$IS_PROD" = "true" ]; then
+        URLS_FOUND="${URLS_FOUND}🚀 Netlify PRODUCTION(${BRANCH}): ${URL}\n"
+      else
+        URLS_FOUND="${URLS_FOUND}🔍 Netlify PREVIEW(${BRANCH}): ${URL}\n"
+      fi
+    fi
+  fi
+fi
+
+# Detection 2:Netlify dashboard-linked(netlify.toml + no state.json)
+# v4:try multiple naming conventions + content sniff to filter squat URLs
+if [ -z "$URLS_FOUND" ] && [ -f "$CWD/netlify.toml" ]; then
+  GH_REMOTE=$(git -C "$CWD" remote get-url origin 2>/dev/null)
+  REPO_NAME=$(echo "$GH_REMOTE" | sed -E 's|.*/([^/.]+)(\.git)?$|\1|')
+  OWNER_REPO=$(echo "$GH_REMOTE" | sed -E 's|.*github\.com[:/]([^/]+/[^/.]+)(\.git)?$|\1|')
+  OWNER=$(echo "$OWNER_REPO" | cut -d/ -f1)
+
+  # v5 multi-candidate strategy(Netlify naming conventions in order of likelihood):
+  # 1. ~/.claude/local/deploy-targets.json overrides(per-user known URLs)— win all
+  # 2. <owner>-<package.json.name>.netlify.app(setup-netlify script convention,per scripts/setup-netlify-access.mjs `${ghUser}-${repoName}` formula)
+  # 3. <owner>-<repo-from-remote>.netlify.app(Netlify Import default,fork users without setup script)
+  # 4. <repo-from-remote>.netlify.app(simple,rare)
+  USER_OVERRIDE=""
+  if [ -f "$HOME/.claude/local/deploy-targets.json" ]; then
+    USER_OVERRIDE=$(jq -r --arg key "$OWNER_REPO" '.[$key] // ""' "$HOME/.claude/local/deploy-targets.json" 2>/dev/null)
+  fi
+  # Read package.json.name for setup-script convention
+  PKG_NAME=""
+  if [ -f "$CWD/package.json" ]; then
+    PKG_NAME=$(jq -r '.name // ""' "$CWD/package.json" 2>/dev/null | sed -E 's|^@[^/]+/||')  # strip npm scope
+  fi
+  CANDIDATES=""
+  if [ -n "$USER_OVERRIDE" ]; then
+    CANDIDATES="$USER_OVERRIDE"
+  else
+    # Setup-script convention candidate(highest match rate for fork users following docs)
+    if [ -n "$OWNER" ] && [ -n "$PKG_NAME" ]; then CANDIDATES="$CANDIDATES https://${OWNER}-${PKG_NAME}.netlify.app"; fi
+    # Netlify Import default(no setup script, manual dashboard import)
+    if [ -n "$OWNER" ] && [ -n "$REPO_NAME" ] && [ "$REPO_NAME" != "$PKG_NAME" ]; then
+      CANDIDATES="$CANDIDATES https://${OWNER}-${REPO_NAME}.netlify.app"
+    fi
+    # Simple fallback
+    if [ -n "$REPO_NAME" ]; then CANDIDATES="$CANDIDATES https://${REPO_NAME}.netlify.app"; fi
+  fi
+
+  REAL_URL=""; REAL_NOTE=""
+  if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+    # 2026-06-07 fix:優先「200 + Storybook content」;沒有則退「200(內容非 Storybook)」,
+    # **不丟棄**已驗 200 的 candidate。anchor:apps/template 是真 product app(非 Storybook)→ 原
+    # is_storybook_deploy 把活著的 200 deploy 誤當 squat 報「全 404」,違反 user「不管是否 production 都給連結」。
+    FALLBACK_URL=""
+    for candidate in $CANDIDATES; do
+      if [ "$(verify_url "$candidate")" = "OK" ]; then
+        if is_storybook_deploy "$candidate"; then
+          REAL_URL="$candidate"; REAL_NOTE="✅ verified 200 + Storybook content"; break
+        elif [ -z "$FALLBACK_URL" ]; then
+          FALLBACK_URL="$candidate"
+        fi
+      fi
+    done
+    if [ -z "$REAL_URL" ] && [ -n "$FALLBACK_URL" ]; then
+      REAL_URL="$FALLBACK_URL"; REAL_NOTE="✅ verified 200(內容非 Storybook — 可能 product app deploy)"
+    fi
+    if [ -n "$REAL_URL" ]; then
+      URLS_FOUND="${URLS_FOUND}🚀 Netlify PRODUCTION(${BRANCH}): ${REAL_URL}  ${REAL_NOTE}\n"
+    else
+      URLS_FOUND="${URLS_FOUND}🚀 Netlify PRODUCTION URL 未驗 — tried: ${CANDIDATES// /, }\n   ⚠️ 全 404。需要 user 手動 share dashboard URL,OR 創 \$HOME/.claude/local/deploy-targets.json:\n   {\"${OWNER_REPO}\": \"https://<actual-site>.netlify.app\"}\n"
+    fi
+  else
+    # Branch preview:always use `<branch>--<sitename>` pattern,but sitename unknown unless USER_OVERRIDE
+    if [ -n "$USER_OVERRIDE" ]; then
+      SITENAME=$(echo "$USER_OVERRIDE" | sed -E 's|https?://([^.]+)\.netlify\.app.*|\1|')
+      CANDIDATE="https://${BRANCH}--${SITENAME}.netlify.app"
+      if [ "$(verify_url "$CANDIDATE")" = "OK" ]; then
+        URLS_FOUND="${URLS_FOUND}🔍 Netlify PREVIEW(${BRANCH}): ${CANDIDATE}  ✅ verified 200\n"
+      else
+        URLS_FOUND="${URLS_FOUND}🔍 Netlify PREVIEW 推導: ${CANDIDATE}  ⚠️ 404(preview 未啟 OR build pending — Netlify build 2-3 min)\n"
+      fi
+    else
+      URLS_FOUND="${URLS_FOUND}🔍 Netlify PREVIEW(${BRANCH}) — sitename 未知;設 \$HOME/.claude/local/deploy-targets.json 後 hook 可推 preview URL\n"
+    fi
+  fi
+fi
+
+# Detection 3:GitHub Pages(.github/workflows/*.yml deploys to gh-pages OR uses actions/deploy-pages)
+if ls "$CWD/.github/workflows/"*.yml >/dev/null 2>&1; then
+  if grep -l "actions/deploy-pages\|gh-pages\|github.io" "$CWD/.github/workflows/"*.yml >/dev/null 2>&1; then
+    GH_REMOTE=$(git -C "$CWD" remote get-url origin 2>/dev/null)
+    OWNER_REPO=$(echo "$GH_REMOTE" | sed -E 's|.*github\.com[:/]([^/]+/[^/.]+)(\.git)?$|\1|')
+    OWNER=$(echo "$OWNER_REPO" | cut -d/ -f1)
+    REPO=$(echo "$OWNER_REPO" | cut -d/ -f2)
+    if [ -n "$OWNER" ] && [ -n "$REPO" ] && { [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; }; then
+      CANDIDATE="https://${OWNER}.github.io/${REPO}/"
+      VERIFY=$(verify_url "$CANDIDATE")
+      if [ "$VERIFY" = "OK" ]; then
+        URLS_FOUND="${URLS_FOUND}📄 GitHub Pages(${BRANCH}): ${CANDIDATE}  ✅ verified 200\n"
+      else
+        URLS_FOUND="${URLS_FOUND}📄 GitHub Pages 推導 URL: ${CANDIDATE}  ⚠️ ${VERIFY}(build ~3-5 min;若仍 404 check Actions tab build status)\n"
+      fi
+    fi
+  fi
+fi
+
+# No deploy target detected → silent skip
+[ -z "$URLS_FOUND" ] && exit 0
+
+# Inject into AI context
+# 2026-05-29 ROOT-CAUSE FIX:PostToolUse hook 的純 stdout **不會**注入 AI context(只進 transcript)→
+# 原 `printf` 輸出讓 AI 看不到 URL → AI 每次 push 都沒 relay 給 user(user verbatim「部署完都沒給我 url」)。
+# 必須輸出 JSON `hookSpecificOutput.additionalContext` 才會真注入 AI context。
+MSG=$(printf '%b' "🚀 Deploy URLs auto-detected — RELAY 給 user(per user 2026-05-26「完成部署都自動回吐連結」+ 2026-05-27「不管 repo」):\n${URLS_FOUND}\n(AI:必須把上面 URL 貼給 user,不可省略)")
+jq -n --arg ctx "$MSG" '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$ctx}}'
+
+exit 0

package/ds-canonical/fork/launchers/fork-governance-dispatcher.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# fork-governance-dispatcher.sh — C-prime 治理派發器(committed in fork,極穩定、幾乎永不改)
+#
+# 這是 fork repo 唯一 commit 的「啟動器」:讀 npm 套件 ship 的 fork 治理 manifest,跑當下這個
+# event 的所有官方 fork hook。DS 未來治理增刪改 → 重生 npm 套件的 manifest → fork `npm install`
+# 後本派發器自動跑新的那套(committed 設定不用動)= 完全同步。
+#
+# 設計鐵則:
+#   - 本體在 node_modules(npm install 覆蓋 = 官方控管、使用者改不動)
+#   - manifest 缺(還沒 npm install)→ exit 0 永不 brick(bootstrap 另外發 notice)
+#   - 任一官方 fork hook exit 2(BLOCKER)→ 派發器 exit 2(轉發攔截)
+#   - 其餘 exit code 不阻擋(soft)
+
+set -uo pipefail
+INPUT=$(cat 2>/dev/null || echo "{}")
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null)
+
+DS_FORK="${CLAUDE_PROJECT_DIR:-.}/node_modules/@qijenchen/design-system/ds-canonical/fork"
+MANIFEST="$DS_FORK/manifest.json"
+
+# 治理本體還沒就位(fork 第一個 session 還沒 npm install)→ 不阻擋(bootstrap 會發 notice)
+[ -f "$MANIFEST" ] || exit 0
+
+# 取這個 event 註冊的官方 fork hook 清單
+HOOK_FILES=$(jq -r --arg ev "$EVENT" '.hooks[$ev][]?.file // empty' "$MANIFEST" 2>/dev/null)
+[ -z "$HOOK_FILES" ] && exit 0
+
+RC=0
+while IFS= read -r hf; do
+  [ -z "$hf" ] && continue
+  body="$DS_FORK/$hf"
+  [ -f "$body" ] || continue   # 個別 body 缺 → skip,不阻擋(派發器穩健)
+  # 依副檔名選 interpreter:.py 用 python3、其餘 bash。
+  # 鐵則:用 bash 跑 .py → syntax error → exit 2 → 被下面誤判成 BLOCKER → 擋掉所有編輯(致命)。
+  # python3 缺(罕見)→ exit 127(非 2)→ 不轉發 = fail-open,不 brick。
+  case "$body" in
+    *.py) echo "$INPUT" | python3 "$body" ;;
+    *)    echo "$INPUT" | bash "$body" ;;
+  esac
+  hc=$?
+  [ "$hc" -eq 2 ] && RC=2       # 官方 hook 攔截 → 轉發攔截
+done <<< "$HOOK_FILES"
+
+exit $RC

package/ds-canonical/fork/launchers/inject_fork_governance_preamble.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# inject_fork_governance_preamble.sh — C-prime SessionStart 治理 init(install-if-missing + 事前指引注入)
+#
+# 2026-06-17 合併原 check_governance_bootstrap 的 install(adversarial run-4 MAJOR — cloud-flow race):
+#   原本 SessionStart 有 3 個 hook(bootstrap 裝 / inject 注入 / dispatcher),Claude Code 同組 hook「並行」跑。
+#   雲端 fresh-clone 時 bootstrap 還在前景 `npm install`(冷裝 30s–4min),inject 並行跑完一次 `[ -f preamble ]`
+#   檢查 → 檔案還沒到 → 靜默 exit 0 → 什麼都沒注入 = proactive 指引在雲端首次 session 失效(且每 session 重演)。
+#   修:把 install 與 inject 放「同一 hook process 內 sequential」→ 消除並行 race + 避免兩個並發 npm install 衝突。
+#   dispatcher 不再掛 SessionStart(manifest 無 SessionStart body = 本來就 no-op);它留在 Pre/Post/UserPromptSubmit。
+#
+# fail-open:install 失敗 / preamble 缺 → notice + exit 0,永不 brick。
+# 對齊既有用 additionalContext 的 hook 輸出契約。
+
+set -uo pipefail
+PD="${CLAUDE_PROJECT_DIR:-.}"
+FORK="$PD/node_modules/@qijenchen/design-system/ds-canonical/fork"
+PREAMBLE="$FORK/preamble.md"
+
+# (1) 治理本體缺(雲端 fresh-clone / 還沒裝)+ 有 package.json → 前景裝 @beta。
+# 這裡 block 到裝完才往下讀 → sequential,後面的讀取保證在 install 之後(消除 race)。
+# codex risk 2:plain `npm install` 會被 lockfile 重現舊樹 → 明確 @beta 拿最新治理。
+if [ ! -f "$PREAMBLE" ] && [ -f "$PD/package.json" ]; then
+  echo "💡 DS 治理本體缺(可能雲端 fresh-clone session)→ 自動裝最新治理(@beta)…" >&2
+  ( cd "$PD" && npm install @qijenchen/design-system@beta @qijenchen/storybook-config@beta --legacy-peer-deps --no-audit --no-fund >/dev/null 2>&1 ) || true
+fi
+
+# (2) 本體在(本機持久 / 剛裝完)→ 讀 + 經 additionalContext 注入設計紀律
+if [ -f "$PREAMBLE" ]; then
+  CONTENT=$(cat "$PREAMBLE" 2>/dev/null)
+  if [ -n "$CONTENT" ]; then
+    jq -n --arg ctx "$CONTENT" '{
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: ("# DS 設計治理(npm-current,事前主動遵循)\n\n" + $ctx)
+      }
+    }'
+    exit 0
+  fi
+fi
+
+# (3) 仍缺(install 失敗 / 無 package.json)→ notice,不阻擋(fail-open)
+cat >&2 << 'EOF'
+💡 DS 治理尚未就位(npm install 未完成或失敗)。請手動執行 → npm install(或 npm run sync-all)。
+   注:現在「不阻擋」你工作,只是提醒;治理本體就位後設計治理 hook 才會機械把關。
+EOF
+exit 0

package/ds-canonical/fork/launchers/settings-hooks.json

@@ -0,0 +1,58 @@
+{
+  "_generated": "build-fork-governance.mjs",
+  "_source": "template/ds-product-template/.claude/settings.json(hooks + permissions 區塊)",
+  "_merge": "sync-all/refresh-fork-launchers.mjs:strip 舊 launcher 註冊 + append canonical hooks + union permissions.allow",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/inject_fork_governance_preamble.sh\""
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/fork-governance-dispatcher.sh\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/fork-governance-dispatcher.sh\""
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/fork-governance-dispatcher.sh\""
+          }
+        ]
+      }
+    ]
+  },
+  "permissions": {
+    "allow": [
+      "Bash(npm install)",
+      "Bash(npm ci)",
+      "Bash(npm run *)",
+      "Bash(npx *)",
+      "Bash(git *)"
+    ]
+  }
+}

package/ds-canonical/fork/manifest.json

@@ -0,0 +1,79 @@
+{
+  "_generated": "build-fork-governance.mjs",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "file": "hooks/check_consumer_app_invariants.sh",
+        "sourceHook": "check_consumer_app_invariants.sh",
+        "bucket": "SHIP_AS_IS"
+      },
+      {
+        "file": "hooks/block_prototype_imports.py",
+        "sourceHook": "block_prototype_imports.py",
+        "bucket": "SHIP_AS_IS"
+      },
+      {
+        "file": "hooks/check_layout_space_magic_numbers.sh",
+        "sourceHook": "check_layout_space_magic_numbers.sh",
+        "bucket": "SHIP_AS_IS"
+      },
+      {
+        "file": "hooks/check_tailwind_wildcard_in_docs.sh",
+        "sourceHook": "check_tailwind_wildcard_in_docs.sh",
+        "bucket": "SHIP_AS_IS"
+      },
+      {
+        "file": "hooks/check_escape_marker_abuse.sh",
+        "sourceHook": "check_escape_marker_abuse.sh",
+        "bucket": "SHIP_REWRITTEN"
+      },
+      {
+        "file": "hooks/inject_deploy_url_after_push.sh",
+        "sourceHook": "inject_deploy_url_after_push.sh",
+        "bucket": "SHIP_REWRITTEN"
+      }
+    ],
+    "PreToolUse": [
+      {
+        "file": "hooks/check_item_list_gap.sh",
+        "sourceHook": "check_item_list_gap.sh",
+        "bucket": "SHIP_AS_IS"
+      },
+      {
+        "file": "hooks/check_pattern_invariants.sh",
+        "sourceHook": "check_pattern_invariants.sh",
+        "bucket": "SHIP_AS_IS"
+      },
+      {
+        "file": "hooks/check_field_family_invariants.sh",
+        "sourceHook": "check_field_family_invariants.sh",
+        "bucket": "SHIP_AS_IS"
+      },
+      {
+        "file": "hooks/check_sidebar_menu_button_implicit_wrap.sh",
+        "sourceHook": "check_sidebar_menu_button_implicit_wrap.sh",
+        "bucket": "SHIP_AS_IS"
+      },
+      {
+        "file": "hooks/check_chrome_header_avatar_canonical.sh",
+        "sourceHook": "check_chrome_header_avatar_canonical.sh",
+        "bucket": "SHIP_AS_IS"
+      },
+      {
+        "file": "hooks/check_opacity_token_usage.sh",
+        "sourceHook": "check_opacity_token_usage.sh",
+        "bucket": "SHIP_REWRITTEN"
+      },
+      {
+        "file": "hooks/check_ds_anchor_preflight.sh",
+        "sourceHook": "check_ds_anchor_preflight.sh",
+        "bucket": "SHIP_REWRITTEN"
+      },
+      {
+        "file": "hooks/check_fork_product_quality.sh",
+        "sourceHook": "check_substantive_edit_approval_preflight.sh",
+        "bucket": "REPLACE"
+      }
+    ]
+  }
+}