universal-dev-standards 5.2.0 → 5.3.0

package/bundled/locales/zh-TW/skills/deploy-assistant/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: deploy
+source: ../../../../skills/deploy-assistant/SKILL.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-26
+status: current
+description: "[UDS] 引導無 CI/CD 平台下的可靠部署 — 生成 deploy.sh、verify.sh、rollback.sh、Makefile"
+allowed-tools: Read, Bash(cat VERSION:*), Bash(git describe:*), Bash(which nginx:*), Bash(which rsync:*)
+argument-hint: "[project type | 專案類型: node/python/docker/go]"
+---
+
+# 無 CI/CD 部署助手
+
+> **語言**: [English](../../../../skills/deploy-assistant/SKILL.md) | 繁體中文
+
+在沒有 GitHub Actions 或 GitLab CI 的環境中，引導建立可靠的部署腳本組。採用三層架構：防錯、驗證、回復。
+
+## 三層部署架構
+
+```
+Layer 1: 防止錯誤部署
+  └─ set -euo pipefail + 版本 tag 強制 + deploy.lock
+
+Layer 2: 驗證部署正確
+  └─ Smoke Test + /health 端點 + 版本號比對 + 自動 rollback
+
+Layer 3: 快速回復能力
+  └─ Blue-Green 切換（Nginx）+ rollback.sh（< 30 秒）
+```
+
+## 引導式問答
+
+Skill 啟動後，AI 助手應詢問：
+
+| 問題 | 選項 | 影響 |
+|------|------|------|
+| 專案類型 | node / python / go / docker | 建置命令 |
+| 部署目標 | SSH+rsync / Docker Compose | 傳輸方式 |
+| 是否支援 Blue-Green | yes / no | 生成 rollback.sh |
+| 健康檢查 URL | 輸入 URL | verify.sh 目標 |
+| 版本來源 | VERSION 檔案 / package.json / git tag | 版本比對邏輯 |
+
+## 生成的腳本組
+
+### deploy.sh（主部署腳本）
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+LOCK_FILE="/tmp/deploy.lock"
+trap "rm -f $LOCK_FILE" EXIT
+
+# 防並發
+if [ -f "$LOCK_FILE" ]; then
+  echo "❌ 部署進行中（PID: $(cat $LOCK_FILE)）"
+  exit 1
+fi
+echo $$ > "$LOCK_FILE"
+
+# 版本 tag 強制
+CURRENT_TAG=$(git describe --exact-match --tags HEAD 2>/dev/null || echo "")
+if [ -z "$CURRENT_TAG" ]; then
+  echo "❌ 請先建立版本 tag：git tag vX.Y.Z && git push --tags"
+  exit 1
+fi
+
+echo "[1/4] 執行測試..."
+# {TEST_COMMAND}
+
+echo "[2/4] 建置產物..."
+# {BUILD_COMMAND}
+
+echo "[3/4] 推送到伺服器..."
+rsync -avz --delete ./dist/ {USER}@{SERVER}:/app/
+
+echo "[4/4] 驗證部署..."
+./verify.sh || { echo "驗證失敗，執行 rollback..."; ./rollback.sh; exit 1; }
+
+echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"version\":\"$CURRENT_TAG\",\"operator\":\"$(whoami)\",\"result\":\"success\"}" >> /var/log/deployments.jsonl
+echo "✅ 部署成功：$CURRENT_TAG"
+```
+
+### verify.sh（Smoke Test）
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+HEALTH_URL="${HEALTH_URL:-{HEALTH_URL}}"
+EXPECTED_VERSION=$(cat VERSION)
+
+for i in $(seq 1 3); do
+  RESPONSE=$(curl -sf --max-time 10 "$HEALTH_URL" 2>/dev/null) && break
+  echo "健康檢查嘗試 $i/3 失敗，等待 5s..."
+  sleep 5
+done
+
+ACTUAL_VERSION=$(echo "$RESPONSE" | python3 -c "import json,sys; print(json.load(sys.stdin)['version'])")
+
+if [ "$ACTUAL_VERSION" != "$EXPECTED_VERSION" ]; then
+  echo "❌ 版本不符！預期 $EXPECTED_VERSION，實際 $ACTUAL_VERSION"
+  exit 1
+fi
+
+echo "✅ 版本驗證通過：$ACTUAL_VERSION"
+```
+
+### rollback.sh（Blue-Green 回滾）
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+CURRENT=$(readlink /app/current 2>/dev/null || echo "/app/blue")
+TARGET=$([[ "$CURRENT" == *"green"* ]] && echo "/app/blue" || echo "/app/green")
+
+ln -sfn "$TARGET" /app/current
+nginx -s reload
+
+echo "✅ 已切回 $TARGET（$(date -u +%Y-%m-%dT%H:%M:%SZ)）"
+echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"event\":\"rollback\",\"from\":\"$CURRENT\",\"to\":\"$TARGET\",\"operator\":\"$(whoami)\"}" >> /var/log/deployments.jsonl
+```
+
+### Makefile
+
+```makefile
+.PHONY: deploy rollback verify status
+
+deploy:
+	@./deploy.sh
+
+rollback:
+	@./rollback.sh
+
+verify:
+	@./verify.sh
+
+status:
+	@echo "Current slot: $$(readlink /app/current 2>/dev/null || echo 'N/A')"
+	@curl -s $${HEALTH_URL:-http://localhost/health} | python3 -m json.tool 2>/dev/null || echo "Health check failed"
+```
+
+## 使用方式
+
+```bash
+/deploy              # 互動式引導，自動偵測專案類型
+/deploy node         # 指定 Node.js 專案直接生成
+/deploy docker       # Docker Compose 部署模式
+/deploy --verify-only  # 只生成 verify.sh
+```
+
+## 輸出確認清單
+
+生成後，AI 助手必須確認：
+
+- [ ] `deploy.sh` 包含 `set -euo pipefail`
+- [ ] `deploy.sh` 包含 deploy.lock 防並發邏輯
+- [ ] `verify.sh` 比對版本號（不只檢查 HTTP 200）
+- [ ] `rollback.sh` 在驗證失敗時自動觸發
+- [ ] `Makefile` 提供 `make deploy / make rollback / make status`
+
+## 下一步引導
+
+`/deploy` 完成後，AI 助手應建議：
+
+> **部署腳本已生成。建議下一步：**
+> - `chmod +x deploy.sh verify.sh rollback.sh` — 設定執行權限
+> - `make verify` — 測試健康檢查設定
+> - `git tag v1.0.0 && git push --tags` — 建立版本 tag
+> - `make deploy` — 執行第一次部署
+
+## 參考
+
+- 核心標準：[no-cicd-deployment.md](../../../../core/no-cicd-deployment.md)
+- 核心標準：[deployment-standards.md](../../../../core/deployment-standards.md)
+- 相關 Skill：[ci-cd-assistant](../../skills/ci-cd-assistant/SKILL.md) — 有 CI/CD 平台的場景

package/bundled/skills/deploy-assistant/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: deploy
+scope: universal
+description: |
+  Guide reliable deployments without CI/CD platforms (GitHub Actions / GitLab CI).
+  Use when: deploying to VPS, air-gapped servers, or environments without CI/CD infrastructure.
+  Keywords: deployment, no-cicd, shell script, blue-green, smoke test, rollback, 無CI/CD, 部署.
+allowed-tools: Read, Bash(cat VERSION:*), Bash(git describe:*), Bash(which nginx:*), Bash(which rsync:*)
+argument-hint: "[project type | 專案類型: node/python/docker/go]"
+---
+
+# No-CI/CD Deploy Assistant | 無 CI/CD 部署助手
+
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/deploy-assistant/SKILL.md)
+
+Guide reliable deployments in environments without GitHub Actions or GitLab CI, using a three-layer architecture: prevent errors, verify correctness, recover fast.
+
+引導無 CI/CD 平台環境下的可靠部署，採用三層架構：防錯、驗證、快速回復。
+
+## Three-Layer Architecture | 三層部署架構
+
+```
+Layer 1: Prevent Wrong Deployments   Layer 2: Verify Correctness   Layer 3: Fast Recovery
+  set -euo pipefail                    Smoke Test + /health           Blue-Green switching
+  Version tag enforcement              Version number comparison      rollback.sh < 30s
+  deploy.lock concurrency guard        Auto-rollback on failure
+```
+
+## Interactive Questionnaire | 引導式問答
+
+| Question | Options | Impact |
+|----------|---------|--------|
+| Project type | node / python / go / docker | Build command |
+| Deploy target | SSH+rsync / Docker Compose | Transfer method |
+| Blue-Green support | yes / no | rollback.sh generation |
+| Health check URL | URL input | verify.sh target |
+| Version source | VERSION file / package.json / git tag | Version comparison logic |
+
+## Generated Script Set | 生成的腳本組
+
+### deploy.sh — Main Deploy Script
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+LOCK_FILE="/tmp/deploy.lock"
+trap "rm -f $LOCK_FILE" EXIT
+
+# Concurrency guard | 防並發
+if [ -f "$LOCK_FILE" ]; then
+  echo "❌ Deploy in progress (PID: $(cat $LOCK_FILE))"
+  exit 1
+fi
+echo $$ > "$LOCK_FILE"
+
+# Version tag enforcement | 版本 tag 強制
+CURRENT_TAG=$(git describe --exact-match --tags HEAD 2>/dev/null || echo "")
+if [ -z "$CURRENT_TAG" ]; then
+  echo "❌ No version tag on HEAD. Run: git tag vX.Y.Z && git push --tags"
+  exit 1
+fi
+
+echo "[1/4] Running tests..."
+# {TEST_COMMAND}
+
+echo "[2/4] Building artifact..."
+# {BUILD_COMMAND}
+
+echo "[3/4] Syncing to server..."
+rsync -avz --delete ./dist/ {USER}@{SERVER}:/app/
+
+echo "[4/4] Verifying deployment..."
+./verify.sh || { echo "Verification failed, rolling back..."; ./rollback.sh; exit 1; }
+
+echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"version\":\"$CURRENT_TAG\",\"operator\":\"$(whoami)\",\"result\":\"success\"}" >> /var/log/deployments.jsonl
+echo "✅ Deploy successful: $CURRENT_TAG"
+```
+
+### verify.sh — Smoke Test
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+HEALTH_URL="${HEALTH_URL:-{HEALTH_URL}}"
+EXPECTED_VERSION=$(cat VERSION)
+
+for i in $(seq 1 3); do
+  RESPONSE=$(curl -sf --max-time 10 "$HEALTH_URL" 2>/dev/null) && break
+  echo "Health check attempt $i/3 failed, retrying in 5s..."
+  sleep 5
+done
+
+ACTUAL_VERSION=$(echo "$RESPONSE" | python3 -c "import json,sys; print(json.load(sys.stdin)['version'])")
+
+if [ "$ACTUAL_VERSION" != "$EXPECTED_VERSION" ]; then
+  echo "❌ Version mismatch! Expected $EXPECTED_VERSION, got $ACTUAL_VERSION"
+  exit 1
+fi
+
+echo "✅ Version verified: $ACTUAL_VERSION"
+```
+
+### rollback.sh — Blue-Green Rollback
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+CURRENT=$(readlink /app/current 2>/dev/null || echo "/app/blue")
+TARGET=$([[ "$CURRENT" == *"green"* ]] && echo "/app/blue" || echo "/app/green")
+
+ln -sfn "$TARGET" /app/current
+nginx -s reload
+
+echo "✅ Rolled back to $TARGET ($(date -u +%Y-%m-%dT%H:%M:%SZ))"
+echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"event\":\"rollback\",\"from\":\"$CURRENT\",\"to\":\"$TARGET\",\"operator\":\"$(whoami)\"}" >> /var/log/deployments.jsonl
+```
+
+### Makefile
+
+```makefile
+.PHONY: deploy rollback verify status
+
+deploy:
+	@./deploy.sh
+
+rollback:
+	@./rollback.sh
+
+verify:
+	@./verify.sh
+
+status:
+	@echo "Current slot: $$(readlink /app/current 2>/dev/null || echo 'N/A')"
+	@curl -s $${HEALTH_URL:-http://localhost/health} | python3 -m json.tool 2>/dev/null || echo "Health check failed"
+```
+
+## Output Checklist | 輸出確認清單
+
+After generation, AI assistant must confirm:
+
+- [ ] `deploy.sh` includes `set -euo pipefail`
+- [ ] `deploy.sh` includes deploy.lock concurrency guard
+- [ ] `verify.sh` compares version number (not just HTTP 200)
+- [ ] `rollback.sh` triggers automatically on verify failure
+- [ ] `Makefile` provides `make deploy / make rollback / make status`
+
+## Usage | 使用方式
+
+```bash
+/deploy              # Interactive mode — auto-detect project type
+/deploy node         # Node.js project, generate directly
+/deploy docker       # Docker Compose deploy mode
+/deploy --verify-only  # Generate verify.sh only
+```
+
+## Next Steps Guidance | 下一步引導
+
+After `/deploy` completes, the AI assistant should suggest:
+
+> **Deploy scripts generated. Suggested next steps / 部署腳本已生成，建議下一步：**
+> - `chmod +x deploy.sh verify.sh rollback.sh` — Set executable permissions | 設定執行權限
+> - `make verify` — Test health check configuration | 測試健康檢查設定
+> - `git tag v1.0.0 && git push --tags` — Create version tag | 建立版本 tag
+> - `make deploy` — First deployment | 執行第一次部署
+
+## Reference | 參考
+
+- Core standard: [no-cicd-deployment.md](../../core/no-cicd-deployment.md)
+- Core standard: [deployment-standards.md](../../core/deployment-standards.md)
+- Related: [ci-cd-assistant](../ci-cd-assistant/SKILL.md) — For environments WITH CI/CD
+
+## Version History | 版本歷史
+
+| Version | Date | Changes | 變更說明 |
+|---------|------|---------|----------|
+| 1.0.0 | 2026-04-26 | Initial release — XSPEC-085 Phase 1b | 初始版本 |
+
+## License | 授權
+
+CC BY 4.0 — Documentation content

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-dev-standards",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "description": "CLI tool for adopting Universal Development Standards",
   "keywords": [
     "documentation",

package/standards-registry.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "lastUpdated": "2026-04-16",
   "description": "Standards registry for universal-dev-standards with integrated skills and AI-optimized formats",
   "formats": {
@@ -58,14 +58,14 @@
     "standards": {
       "name": "universal-dev-standards",
       "url": "https://github.com/AsiaOstrich/universal-dev-standards",
-      "version": "5.2.0"
+      "version": "5.3.0"
     },
     "skills": {
       "name": "universal-dev-standards",
       "url": "https://github.com/AsiaOstrich/universal-dev-standards",
       "localPath": "skills",
       "rawUrl": "https://raw.githubusercontent.com/AsiaOstrich/universal-dev-standards/main/skills",
-      "version": "5.2.0",
+      "version": "5.3.0",
       "note": "Skills are now included in the main repository under skills/"
     }
   },
@@ -2062,6 +2062,62 @@
       },
       "category": "core",
       "description": "MISSING vs OUTDATED distinction, semver-aware severity (PATCH/MINOR/MAJOR), and automation integration (pre-commit hook, release gate) for multi-locale documentation"
+    },
+    {
+      "id": "push-standards",
+      "name": "Git Push Safety Gates",
+      "nameZh": "Git Push 安全閘門標準",
+      "source": {
+        "human": "skills/push/SKILL.md",
+        "ai": "ai/standards/push-standards.ai.yaml"
+      },
+      "category": "skill",
+      "skillName": "push",
+      "description": "Git push safety gates, protected branch detection, force-push guardrails, pre-push quality gate enforcement, and push receipt audit trail"
+    },
+    {
+      "id": "no-cicd-deployment",
+      "name": "No-CI/CD Deployment Strategy",
+      "nameZh": "無 CI/CD 部署策略",
+      "source": {
+        "human": "core/no-cicd-deployment.md",
+        "ai": "ai/standards/no-cicd-deployment.ai.yaml"
+      },
+      "category": "core",
+      "description": "Reliable deployment strategy without CI/CD platforms: shell scripts with fail-fast, smoke test verification, Blue-Green rollback"
+    },
+    {
+      "id": "rollback-standards",
+      "name": "Rollback Standards",
+      "nameZh": "回滾標準",
+      "source": {
+        "human": "core/rollback-standards.md",
+        "ai": "ai/standards/rollback-standards.ai.yaml"
+      },
+      "category": "core",
+      "description": "Rollback trigger conditions, auto vs manual decisions, and error budget integration"
+    },
+    {
+      "id": "cd-deployment-strategies",
+      "name": "CD Deployment Strategies",
+      "nameZh": "CD 部署策略",
+      "source": {
+        "human": "core/cd-deployment-strategies.md",
+        "ai": "ai/standards/cd-deployment-strategies.ai.yaml"
+      },
+      "category": "core",
+      "description": "Strategy selection matrix for blue-green, canary, rolling, and recreate deployments"
+    },
+    {
+      "id": "pipeline-security-gates",
+      "name": "Pipeline Security Gates",
+      "nameZh": "CI Pipeline 安全閘門",
+      "source": {
+        "human": "core/pipeline-security-gates.md",
+        "ai": "ai/standards/pipeline-security-gates.ai.yaml"
+      },
+      "category": "core",
+      "description": "Security checkpoints embedded in CI pipeline — SAST, DAST, SCA, secrets scan with block/warn/log behavior"
     }
   ]
 }