Agent-System/scripts/git-workflow-helper.sh

#!/usr/bin/env bash
# =============================================================================
# Git 分支工作流辅助检查工具 (git-workflow-helper.sh)
# 作用：校验分支合规性、协助功能子分支检出与阶段发布节点标记
# =============================================================================

set -eo pipefail

COMMAND="$1"
ARG="$2"

CURRENT_BRANCH="$(git branch --show-current 2>/dev/null || echo '')"

show_help() {
    cat <<EOF
Git 3 分支工作流辅助工具:

用法:
    $0 check                     # 检查当前分支状态及工作流提示
    $0 feature <name>            # 基于 dev 检出 feature/<name> 子分支
    $0 fix <name>                # 基于 dev 检出 fix/<name> 子分支
    $0 merge-to-dev              # 将当前功能子分支测试后合回 dev
    $0 promote-to-test <tag>     # 将 dev 合并到 test 并打候选版本 tag (如 rc-v1.1.0-beta.1)
    $0 release-to-main <tag>     # 将 test 合并到 main 并打正式版本 tag (如 v1.1.0)
EOF
    exit 1
}

case "${COMMAND}" in
    check)
        echo "=== 当前 Git 分支与工作流检查 ==="
        echo "当前分支: [${CURRENT_BRANCH}]"
        echo ""
        case "${CURRENT_BRANCH}" in
            dev)
                echo "状态: 正处于【开发合入基线】。"
                echo "提示: 禁止直接 commit。请从最新 dev 创建 feature/<name> 或 fix/<name>，自测后占集成槽位 merge --no-ff 合回。"
                ;;
            test)
                echo "状态: 正处于【测试分支】。"
                echo "提示: 仅用于长期实际部署和运维测试。新功能开发请切换至 dev。"
                ;;
            main)
                echo "状态: 正处于【主分支 (Release)】。"
                echo "警告: 严禁直接在 main 上开发代码！只有经过 test 验证的稳定节点才能合入 main。"
                ;;
            feature/*|fix/*)
                echo "状态: 正处于功能子分支 [${CURRENT_BRANCH}]。"
                echo "提示: 自测完成后，使用 '$0 merge-to-dev' 合回 dev 分支。"
                ;;
            *)
                echo "提示: 当前处于非常规分支 [${CURRENT_BRANCH}]。"
                ;;
        esac
        echo ""
        git status --short
        ;;

    feature)
        if [[ -z "${ARG}" ]]; then
            echo "错误: 请提供 feature 名称，例如: $0 feature session-cache"
            exit 1
        fi
        echo "==> 从 dev 切换并创建 feature/${ARG}..."
        git checkout dev
        git pull --rebase origin dev 2>/dev/null || true
        git checkout -b "feature/${ARG}"
        echo "成功切换至 feature/${ARG}"
        ;;

    fix)
        if [[ -z "${ARG}" ]]; then
            echo "错误: 请提供 fix 名称，例如: $0 fix db-pool-leak"
            exit 1
        fi
        echo "==> 从 dev 切换并创建 fix/${ARG}..."
        git checkout dev
        git pull --rebase origin dev 2>/dev/null || true
        git checkout -b "fix/${ARG}"
        echo "成功切换至 fix/${ARG}"
        ;;

    merge-to-dev)
        if [[ "${CURRENT_BRANCH}" != feature/* && "${CURRENT_BRANCH}" != fix/* ]]; then
            echo "错误: 当前分支为 ${CURRENT_BRANCH}，不是 feature/* 或 fix/* 分支！"
            exit 1
        fi
        SRC_BRANCH="${CURRENT_BRANCH}"
        echo "==> 准备将 ${SRC_BRANCH} 合并回 dev 分支..."
        git checkout dev
        git pull --rebase origin dev 2>/dev/null || true
        git merge --no-ff "${SRC_BRANCH}" -m "merge: 合并 ${SRC_BRANCH} 到开发分支 dev"
        echo "合并成功！可运行 'git branch -d ${SRC_BRANCH}' 删除已合入的本地临时分支。"
        ;;

    promote-to-test)
        TAG="${ARG}"
        if [[ -z "${TAG}" ]]; then
            echo "错误: 请提供测试候选 Tag 名称，例如: $0 promote-to-test rc-v1.0.0-beta.1"
            exit 1
        fi
        # Wave 2B / PU5B: require PASS receipt (or timed waiver) for local `dev` HEAD.
        SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
        DEV_SHA="$(git rev-parse dev)"
        echo "==> promotion-receipt gate for dev@${DEV_SHA:0:12}..."
        "${SCRIPT_DIR}/promotion-receipt-check.sh" --commit "${DEV_SHA}"
        echo "==> 切换至 test 分支并合并本地 dev 当前稳定节点..."
        git checkout test
        # 本地晋升默认不 rebase origin（分叉时会把数百提交重放并易冲突）。需要同步远端时请显式 pull --ff-only/merge。
        git merge --no-ff dev -m "release-candidate: 汇集 dev 功能至 test 分支，准备长期实测 [Tag: ${TAG}]"
        git tag -a "${TAG}" -m "实测候选版本: ${TAG}"
        echo "已成功合并至 test 并打上标签: ${TAG}！请启动 test 环境进行运维与功能测试。"
        ;;

    release-to-main)
        TAG="${ARG}"
        if [[ -z "${TAG}" ]]; then
            echo "错误: 请提供正式发布 Tag 名称，例如: $0 release-to-main v1.0.0"
            exit 1
        fi
        # Wave 2B / PU5B: require PASS receipt (or timed waiver) for local `test` HEAD.
        SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
        TEST_SHA="$(git rev-parse test)"
        echo "==> promotion-receipt gate for test@${TEST_SHA:0:12}..."
        "${SCRIPT_DIR}/promotion-receipt-check.sh" --commit "${TEST_SHA}"
        echo "==> 切换至 main 分支并合并 test 验证节点..."
        git checkout main
        git pull --rebase origin main 2>/dev/null || true
        git merge --no-ff test -m "release: 经长期测试与运维验证通过，正式发布 ${TAG}"
        git tag -a "${TAG}" -m "正式发布版本: ${TAG}"
        echo "已成功合并至 main 并打上正式发布标签: ${TAG}！"
        ;;

    *)
        show_help
        ;;
esac