project-auto-wizard 0.1.5

package/payload/workflows/spring/server-deploy/PROJECT-SPRING-SIMPLE-CICD.yaml

@@ -0,0 +1,425 @@
+# ===================================================================
+# Spring Boot CI/CD 배포 (SSH + Docker)
+# ===================================================================
+#
+# deploy 브랜치 푸시 시 Docker 이미지를 빌드하고
+# SSH로 접속 가능한 서버(Synology·AWS EC2·VPS 등)에 자동 배포합니다.
+#
+# ===================================================================
+# 🔑 필수 GitHub Secrets
+# ===================================================================
+# APPLICATION_PROD_YML (선택): application-prod.yml 내용
+# DOCKERHUB_USERNAME: DockerHub 사용자명
+# DOCKERHUB_TOKEN: DockerHub 액세스 토큰
+# SERVER_HOST: 배포 서버 주소
+# SERVER_USER: SSH 사용자명
+# SERVER_PASSWORD: SSH 비밀번호 (SSH_AUTH_METHOD=password일 때)
+# SSH_KEY: SSH 개인키 .pem 내용 (SSH_AUTH_METHOD=key일 때, AWS EC2 등)
+# ===================================================================
+#
+# 🔧 환경변수 설정 (env 섹션에서 설정)
+# ===================================================================
+#
+# 🌐 포트 및 컨테이너:
+# CONTAINER_INTERNAL_PORT: Spring Boot 내부 포트 (기본: 8080)
+# DEPLOY_PORT: 배포 포트
+# CONTAINER_NAME: 컨테이너 이름 (기본: PROJECT_NAME)
+#
+# 📦 볼륨 마운트:
+# ENABLE_VOLUME_MOUNT: 볼륨 마운트 활성화 (true/false)
+# VOLUME_HOST_PATH: 호스트 볼륨 경로
+# VOLUME_CONTAINER_PATH: 컨테이너 내부 마운트 경로
+#
+# 🔌 SSH 연결:
+# SSH_PORT: SSH 포트 (기본: 2022)
+# SSH_COMMAND_TIMEOUT: SSH 명령 타임아웃 (기본: 600s)
+# SSH_CONNECTION_TIMEOUT: SSH 연결 타임아웃 (기본: 60s)
+#
+# ⏱️ 헬스체크:
+# HEALTHCHECK_WAIT_SECONDS: 초기화 대기 시간 (기본: 10초)
+# HEALTHCHECK_PATH: HTTP 엔드포인트 경로 (비어있으면 로그만 사용)
+# HEALTHCHECK_MAX_RETRIES: HTTP 재시도 횟수 (기본: 5회)
+# HEALTHCHECK_RETRY_INTERVAL: 재시도 간격 (기본: 3초)
+# HEALTHCHECK_LOG_PATTERN: Fallback 로그 검색 패턴
+#
+# 💡 HEALTHCHECK_PATH 예시:
+#   Spring Boot (Actuator): "/actuator/health"
+#   커스텀: "/api/v1/health"
+#
+# 💡 HEALTHCHECK_LOG_PATTERN 예시:
+#   Spring Boot: "Tomcat started on port"
+# ===================================================================
+#
+# 🌿 브랜치별 배포:
+# - deploy 브랜치: 자동 배포 (DEPLOY_PORT 사용)
+# - {{MAIN_BRANCH}} 브랜치: 수동 실행만 가능
+# ===================================================================
+
+name: PROJECT-SPRING-SIMPLE-CICD
+
+# ===================================================================
+# 트리거 설정
+# ===================================================================
+# deploy 브랜치에 push할 때 자동으로 CI/CD가 실행됩니다.
+# {{MAIN_BRANCH}} 브랜치는 workflow_dispatch로 수동 실행만 가능합니다.
+on:
+  push:
+    branches:
+      - "{{MAIN_BRANCH}}"  # 배포 환경 (DEPLOY_PORT 사용)
+    # @wizard paths-anchor (모노레포일 때 integrator가 paths 필터를 여기 주입)
+  workflow_dispatch:  # 수동 실행 허용
+
+# ===================================================================
+# 환경 변수 설정
+# ===================================================================
+env:
+  # 🔧 프로젝트 설정 - 실제 프로젝트명으로 변경하세요
+  PROJECT_NAME: "__PROJECT_NAME__"  # @wizard ask:@repo
+
+  # ☁️ Spring Boot 설정
+  SPRING_PROFILE: "prod"
+  JAVA_VERSION: "__JAVA_VERSION__"  # @wizard ask:21
+  GRADLE_OPTS: "-Dspring.profiles.active=prod"
+
+  # 📁 경로 설정
+  APPLICATION_YML_DIR: "__APPLICATION_YML_DIR__"  # @wizard auto:spring-app-yml-dir
+  DOCKERFILE_PATH: "./Dockerfile"
+
+  # 🌐 포트 설정
+  CONTAINER_INTERNAL_PORT: "8080"  # Spring Boot 내부 포트 (고정값)
+  DEPLOY_PORT: "__DEPLOY_PORT__"  # @wizard ask:8080
+
+  # 🐳 컨테이너 이름 설정
+  # 비워두면 PROJECT_NAME을 기본값으로 사용 (예: mapsy-back)
+  # 커스텀 이름을 원하면 직접 입력 (예: "my-custom-container")
+  CONTAINER_NAME: ""
+
+  # 📦 볼륨 마운트 설정
+  # true: 볼륨 마운트 활성화 (디렉토리 없으면 자동 생성)
+  # false: 볼륨 마운트 비활성화 (기본값)
+  ENABLE_VOLUME_MOUNT: "false"
+  VOLUME_HOST_PATH: "/volume1/projects/__PROJECT_NAME__"  # @wizard ask:/volume1/projects/__PROJECT_NAME__
+  VOLUME_CONTAINER_PATH: "/mnt/__PROJECT_NAME__"  # @wizard ask:/mnt/__PROJECT_NAME__
+
+  # 🔐 SSH 인증 방식: "password"(Synology·일반 서버) | "key"(AWS EC2·.pem)
+  #   password → SERVER_PASSWORD secret 사용
+  #   key      → SSH_KEY secret 사용 (.pem 파일 전체 내용을 secret 값으로)
+  SSH_AUTH_METHOD: "password"  # @wizard ask:password
+
+  # 🔌 SSH 연결 설정
+  SSH_PORT: "2022"  # SSH 포트 (Synology 기본: 2022)
+  SSH_COMMAND_TIMEOUT: "600s"  # SSH 명령 실행 타임아웃
+  SSH_CONNECTION_TIMEOUT: "60s"  # SSH 연결 타임아웃
+
+  # ⏱️ 헬스체크 설정
+  HEALTHCHECK_WAIT_SECONDS: "10"  # 컨테이너 초기화 대기 시간 (초)
+  HEALTHCHECK_PATH: "/actuator/health"  # HTTP 엔드포인트 경로 (비어있으면 로그 패턴만 사용)
+  HEALTHCHECK_MAX_RETRIES: "5"  # HTTP 재시도 횟수
+  HEALTHCHECK_RETRY_INTERVAL: "3"  # 재시도 간격 (초)
+  HEALTHCHECK_LOG_PATTERN: "Tomcat started on port"  # Fallback 로그 검색 패턴
+
+jobs:
+  # ===================================================================
+  # 빌드 작업
+  # ===================================================================
+  build:
+    name: Spring Boot 애플리케이션 빌드
+    runs-on: ubuntu-latest
+
+    steps:
+      # 1. 소스코드 체크아웃
+      - name: 코드 체크아웃
+        uses: actions/checkout@v5
+
+      # 2. Java 개발 환경 설정
+      - name: Java 설정
+        uses: actions/setup-java@v4
+        with:
+          java-version: ${{ env.JAVA_VERSION }}
+          distribution: 'temurin'
+          cache: 'gradle'
+
+      # 3. Gradle 실행 권한 부여
+      - name: Gradle Wrapper 실행권한 부여
+        run: chmod +x gradlew
+
+      # 4. Spring Boot 운영 환경 설정 파일 생성
+      # GitHub Secrets에서 APPLICATION_PROD_YML 값을 읽어와서
+      # 리소스 디렉토리에 파일로 생성
+      - name: application-prod.yml 생성
+        run: |
+          # 리소스 디렉토리 생성 (환경변수 사용)
+          mkdir -p ${{ env.APPLICATION_YML_DIR }}
+
+          # GitHub Secrets의 APPLICATION_PROD_YML 내용을 파일로 저장
+          cat << 'EOF' > ./${{ env.APPLICATION_YML_DIR }}/application-prod.yml
+          ${{ secrets.APPLICATION_PROD_YML }}
+          EOF
+
+          echo "✅ application-prod.yml 파일 생성 완료 (${{ env.APPLICATION_YML_DIR }})"
+
+      # 5. Gradle 빌드 실행
+      # 테스트는 제외하고 운영 프로파일로 빌드
+      - name: Build with Gradle
+        run: ./gradlew clean build -x test ${{ env.GRADLE_OPTS }}
+
+      # 6. Docker 빌드 환경 설정
+      - name: Docker 빌드환경 설정
+        uses: docker/setup-buildx-action@v3
+
+      # 7. DockerHub 로그인
+      - name: DockerHub 로그인
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      # 8. Docker 레이어 캐싱 설정
+      # 빌드 속도 향상을 위한 캐시 설정
+      - name: Cache Docker layers
+        uses: actions/cache@v4
+        with:
+          path: /tmp/.buildx-cache
+          key: ${{ runner.os }}-buildx-${{ hashFiles('Dockerfile') }}
+          restore-keys: |
+            ${{ runner.os }}-buildx-
+
+      # 9. Docker 이미지 빌드 및 푸시
+      # 브랜치명을 태그로 사용하여 환경별로 이미지 관리
+      - name: Docker 이미지 빌드 및 푸시
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ${{ env.DOCKERFILE_PATH }}
+          push: true
+          tags: ${{ secrets.DOCKERHUB_USERNAME }}/${{ env.PROJECT_NAME }}:${{ github.ref_name }}
+          cache-from: type=local,src=/tmp/.buildx-cache
+          cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max
+
+      # 10. Docker 캐시 정리
+      - name: Move Docker cache
+        run: |
+          rm -rf /tmp/.buildx-cache
+          mv /tmp/.buildx-cache-new /tmp/.buildx-cache
+
+  # ===================================================================
+  # 배포 작업
+  # ===================================================================
+  deploy:
+    name: 원격 서버 배포
+    needs: build
+    runs-on: ubuntu-latest
+
+    steps:
+      # SSH를 통한 원격 서버 배포 실행
+      - name: Deploy
+        uses: appleboy/ssh-action@v1.0.3
+        env:
+          SSH_AUTH_METHOD: ${{ env.SSH_AUTH_METHOD }}
+        with:
+          host: ${{ secrets.SERVER_HOST }}
+          username: ${{ secrets.SERVER_USER }}
+          password: ${{ secrets.SERVER_PASSWORD }}
+          key: ${{ secrets.SSH_KEY }}
+          port: ${{ env.SSH_PORT }}
+          envs: SSH_AUTH_METHOD
+          script: |
+            set -e
+
+            # ============================================================
+            # 배포 환경 변수 설정
+            # ============================================================
+            echo "🔧 환경변수 설정.."
+            export PATH=$PATH:/usr/local/bin
+            export PW=${{ secrets.SERVER_PASSWORD }}
+
+            # 🔐 SSH 인증 방식에 따른 sudo 추상화
+            #   password 모드: echo $PW | sudo -S  (Synology 등 sudo 비밀번호 필요 서버)
+            #   key 모드: sudo 직접  (AWS EC2 등 passwordless sudo 서버)
+            SSH_AUTH_METHOD="${SSH_AUTH_METHOD:-password}"
+            if [ "${SSH_AUTH_METHOD}" = "key" ]; then
+              SUDO() { sudo "$@"; }
+            else
+              SUDO() { echo "$PW" | sudo -S "$@"; }
+            fi
+            echo "🔐 SSH 인증 방식: ${SSH_AUTH_METHOD}"
+
+            # GitHub에서 전달받은 브랜치명
+            BRANCH=${{ github.ref_name }}
+
+            # 프로젝트 설정
+            PROJECT_NAME="${{ env.PROJECT_NAME }}"
+
+            # ============================================================
+            # 포트 및 컨테이너명 설정
+            # ============================================================
+            PORT=${{ env.DEPLOY_PORT }}
+
+            # 컨테이너 이름 설정 (환경변수가 비어있으면 PROJECT_NAME을 기본값으로 사용)
+            if [ -z "${{ env.CONTAINER_NAME }}" ]; then
+              CONTAINER_NAME="${PROJECT_NAME}"
+              echo "ℹ️ CONTAINER_NAME이 설정되지 않아 PROJECT_NAME을 사용합니다: $CONTAINER_NAME"
+            else
+              CONTAINER_NAME="${{ env.CONTAINER_NAME }}"
+              echo "ℹ️ 사용자 지정 CONTAINER_NAME 사용: $CONTAINER_NAME"
+            fi
+
+            echo "🚀 배포 환경으로 배포합니다 (브랜치: $BRANCH)"
+
+            # 설정 정보 출력
+            echo "📋 배포 설정 정보:"
+            echo "  - 브랜치: $BRANCH"
+            echo "  - 프로젝트: $PROJECT_NAME"
+            echo "  - 컨테이너 이름: $CONTAINER_NAME"
+            echo "  - 포트: $PORT"
+            echo "  - Docker 이미지: ${{ secrets.DOCKERHUB_USERNAME }}/${PROJECT_NAME}:${BRANCH}"
+
+            # ============================================================
+            # Docker 이미지 풀 (Pull)
+            # ============================================================
+            echo "⬇️ Docker 이미지 풀: ${{ secrets.DOCKERHUB_USERNAME }}/${PROJECT_NAME}:${BRANCH}"
+            SUDO docker pull ${{ secrets.DOCKERHUB_USERNAME }}/${PROJECT_NAME}:${BRANCH}
+
+            # ============================================================
+            # 기존 컨테이너 정리
+            # ============================================================
+            echo "🧹 컨테이너 $CONTAINER_NAME 존재 여부 확인 중..."
+
+            # 동일한 이름의 컨테이너가 존재하는지 확인
+            if SUDO docker ps -a --format '{{.Names}}' | grep -Eq "^${CONTAINER_NAME}\$"; then
+              echo "⚠️ 컨테이너 $CONTAINER_NAME 이(가) 존재합니다. 중지 및 삭제 중..."
+              SUDO docker rm -f $CONTAINER_NAME
+              echo "✅ 컨테이너 $CONTAINER_NAME 이(가) 삭제되었습니다."
+            else
+              echo "ℹ️ 존재하는 컨테이너 $CONTAINER_NAME 이(가) 없습니다."
+            fi
+
+            # ============================================================
+            # 새 컨테이너 실행
+            # ============================================================
+            echo "🚀 새로운 컨테이너 $CONTAINER_NAME 실행 중..."
+
+            # 볼륨 마운트 옵션 설정
+            VOLUME_MOUNT_OPTION=""
+            if [ "${{ env.ENABLE_VOLUME_MOUNT }}" == "true" ]; then
+              # 디렉토리가 없으면 생성
+              if [ ! -d "${{ env.VOLUME_HOST_PATH }}" ]; then
+                echo "📁 볼륨 마운트 디렉토리 생성: ${{ env.VOLUME_HOST_PATH }}"
+                SUDO mkdir -p "${{ env.VOLUME_HOST_PATH }}"
+              fi
+              VOLUME_MOUNT_OPTION="-v ${{ env.VOLUME_HOST_PATH }}:${{ env.VOLUME_CONTAINER_PATH }}"
+              echo "📦 볼륨 마운트 활성화: $VOLUME_MOUNT_OPTION"
+            else
+              echo "ℹ️ 볼륨 마운트 비활성화됨"
+            fi
+
+            # Docker 컨테이너 실행
+            # - 포트 매핑: ${PORT}:${{ env.CONTAINER_INTERNAL_PORT }} (외부:내부)
+            # - 시간대: Asia/Seoul
+            # - Spring 프로파일: ${{ env.SPRING_PROFILE }}
+            # - 볼륨 마운트: ENABLE_VOLUME_MOUNT=true일 때만 활성화
+            SUDO docker run -d \
+              -p ${PORT}:${{ env.CONTAINER_INTERNAL_PORT }} \
+              --name $CONTAINER_NAME \
+              -e TZ=Asia/Seoul \
+              -e "SPRING_PROFILES_ACTIVE=${{ env.SPRING_PROFILE }}" \
+              -v /etc/localtime:/etc/localtime:ro \
+              $VOLUME_MOUNT_OPTION \
+              ${{ secrets.DOCKERHUB_USERNAME }}/${PROJECT_NAME}:${BRANCH}
+
+            # ============================================================
+            # 컨테이너 헬스체크
+            # ============================================================
+            echo "⏳ 컨테이너 초기화 대기 중... (${{ env.HEALTHCHECK_WAIT_SECONDS }}초)"
+            sleep ${{ env.HEALTHCHECK_WAIT_SECONDS }}
+
+            # 1단계: 컨테이너 프로세스 확인
+            echo "🏥 컨테이너 헬스체크 중..."
+            if ! SUDO docker ps --format '{{.Names}}' | grep -Eq "^${CONTAINER_NAME}\$"; then
+              echo "❌ 컨테이너 $CONTAINER_NAME 프로세스가 실행되지 않았습니다"
+              SUDO docker logs --tail 50 $CONTAINER_NAME || true
+              exit 1
+            fi
+            echo "✅ 컨테이너 프로세스 실행 확인 완료"
+
+            # 2단계: HTTP 엔드포인트 체크 (설정된 경우)
+            HEALTHCHECK_SUCCESS=false
+            if [ -n "${{ env.HEALTHCHECK_PATH }}" ]; then
+              echo "🌐 HTTP 헬스체크 시작: http://localhost:${PORT}${{ env.HEALTHCHECK_PATH }}"
+
+              for i in $(seq 1 ${{ env.HEALTHCHECK_MAX_RETRIES }}); do
+                echo "  시도 $i/${{ env.HEALTHCHECK_MAX_RETRIES }}..."
+
+                HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:${PORT}${{ env.HEALTHCHECK_PATH }} || echo "000")
+
+                if [ "$HTTP_CODE" = "200" ]; then
+                  echo "✅ HTTP 헬스체크 성공 (응답 코드: $HTTP_CODE)"
+                  HEALTHCHECK_SUCCESS=true
+                  break
+                else
+                  echo "⚠️ HTTP 헬스체크 실패 (응답 코드: $HTTP_CODE)"
+                  if [ $i -lt ${{ env.HEALTHCHECK_MAX_RETRIES }} ]; then
+                    echo "  ${{ env.HEALTHCHECK_RETRY_INTERVAL }}초 후 재시도..."
+                    sleep ${{ env.HEALTHCHECK_RETRY_INTERVAL }}
+                  fi
+                fi
+              done
+
+              # HTTP 체크 실패 시 fallback으로 로그 패턴 매칭
+              if [ "$HEALTHCHECK_SUCCESS" = "false" ]; then
+                echo "⚠️ HTTP 헬스체크 최종 실패, 로그 패턴 매칭으로 fallback..."
+              fi
+            else
+              echo "ℹ️ HEALTHCHECK_PATH가 설정되지 않아 로그 패턴 매칭만 사용합니다"
+            fi
+
+            # 3단계: 로그 패턴 매칭 (HTTP 실패 시 또는 HTTP 체크 비활성화 시)
+            if [ "$HEALTHCHECK_SUCCESS" = "false" ]; then
+              echo "📋 로그 패턴 매칭 시작: '${{ env.HEALTHCHECK_LOG_PATTERN }}'"
+
+              if SUDO docker logs $CONTAINER_NAME 2>&1 | grep -q "${{ env.HEALTHCHECK_LOG_PATTERN }}"; then
+                echo "✅ 로그 패턴 매칭 성공: 애플리케이션이 정상적으로 시작되었습니다"
+                HEALTHCHECK_SUCCESS=true
+              else
+                echo "❌ 로그 패턴 매칭 실패: 애플리케이션 시작 로그를 찾을 수 없습니다"
+                echo ""
+                echo "📋 디버깅 정보:"
+                echo "  - 검색 패턴: ${{ env.HEALTHCHECK_LOG_PATTERN }}"
+                echo "  - 컨테이너: $CONTAINER_NAME"
+                echo "  - 이미지: ${{ secrets.DOCKERHUB_USERNAME }}/${PROJECT_NAME}:${BRANCH}"
+                echo "  - 포트: ${PORT}:${{ env.CONTAINER_INTERNAL_PORT }}"
+                echo "  - 볼륨: $VOLUME_MOUNT_OPTION"
+                echo "  - 프로파일: ${{ env.SPRING_PROFILE }}"
+                echo ""
+                echo "📋 컨테이너 로그 (최근 50줄):"
+                SUDO docker logs --tail 50 $CONTAINER_NAME || true
+                exit 1
+              fi
+            fi
+
+            # 최종 성공 메시지
+            if [ "$HEALTHCHECK_SUCCESS" = "true" ]; then
+              echo "✅ 헬스체크 완료: 컨테이너 $CONTAINER_NAME 이(가) 정상적으로 실행 중입니다"
+            fi
+
+            # ============================================================
+            # 배포 완료 확인
+            # ============================================================
+            echo "✅ 배포가 성공적으로 완료되었습니다!"
+            echo ""
+            echo "📋 배포 결과 요약:"
+            echo "  🎯 프로젝트: $PROJECT_NAME"
+            echo "  🌿 브랜치: $BRANCH"
+            echo "  🐳 컨테이너: $CONTAINER_NAME"
+            echo "  🌐 포트: $PORT"
+            echo "  ⏰ 배포 시간: $(date '+%Y-%m-%d %H:%M:%S')"
+            echo ""
+            echo "🔗 접속 URL: http://${{ secrets.SERVER_HOST }}:${PORT}"
+
+# ===================================================================
+# 📝 사용 방법
+# ===================================================================
+# 1. GitHub Secrets 설정 (DOCKERHUB_*, SERVER_*)
+# 2. env 섹션에서 PROJECT_NAME, DEPLOY_PORT 설정
+# 3. deploy 브랜치에 push → 자동 CI/CD 실행
+# ===================================================================

package/src/cli/args.js

@@ -0,0 +1,95 @@
+// CLI 인자 파싱 (.sh top-level while-case 등가) — template_integrator.sh 842~920.
+import { VALID_TYPES } from "../context.js";
+
+// argv(process.argv.slice(2)) → 파싱 결과. 오류 시 throw(호출부에서 exit 1).
+export function parseArgs(argv) {
+  const result = {
+    mode: "interactive",
+    version: "",             // 통합 대상 프로젝트의 초기 버전 (--project-version)
+    types: [],
+    primaryType: "",
+    includeNexus: null,      // null=미설정
+    includeSecretBackup: null,
+    includeCodeRabbit: null, // --coderabbit / --no-coderabbit (기본 false — DESIGN-SPEC §4 질문②)
+    pathsCsv: "",            // "flutter=app,react=client" 원문 (정규화는 resolve 단계)
+    mainBranch: "",          // 릴리스 브랜치 (--main-branch). 빈값=감지된 default branch
+    developBranch: "",       // 개발 브랜치 (--develop-branch). 빈값=develop
+    force: false,
+    help: false,
+    showVersion: false,      // -v/--version → 패키지 버전 출력 (npm 관례)
+  };
+  const args = [...argv];
+  while (args.length > 0) {
+    const a = args.shift();
+    switch (a) {
+      case "-m": case "--mode":
+        result.mode = args.shift() ?? ""; break;
+      case "-v": case "--version":
+        // npm 관례: -v/--version 은 패키지 버전 출력. (초기 버전 지정은 --project-version)
+        result.showVersion = true; break;
+      case "--project-version":
+        result.version = args.shift() ?? ""; break;
+      case "-t": case "--type": {
+        const csv = args.shift() ?? "";
+        const seen = new Set();
+        const types = [];
+        for (let t of csv.split(",")) {
+          t = t.replace(/\s/g, "");
+          if (t === "") continue;
+          if (seen.has(t)) continue;         // dedup
+          if (!VALID_TYPES.includes(t)) {
+            throw new CliError(`지원하지 않는 타입: '${t}'\n지원 타입: ${VALID_TYPES.join(" ")}`);
+          }
+          seen.add(t);
+          types.push(t);
+        }
+        if (types.length === 0) throw new CliError("--type 인자가 비어 있습니다");
+        result.types = types;
+        result.primaryType = types[0];
+        break;
+      }
+      case "--force": result.force = true; break;
+      case "--nexus": result.includeNexus = true; break;
+      case "--no-nexus": result.includeNexus = false; break;
+      case "--secret-backup": result.includeSecretBackup = true; break;
+      case "--no-secret-backup": result.includeSecretBackup = false; break;
+      case "--coderabbit": result.includeCodeRabbit = true; break;
+      case "--no-coderabbit": result.includeCodeRabbit = false; break;
+      case "--paths": result.pathsCsv = args.shift() ?? ""; break;
+      case "--main-branch": result.mainBranch = args.shift() ?? ""; break;
+      case "--develop-branch": result.developBranch = args.shift() ?? ""; break;
+      case "-h": case "--help": result.help = true; break;
+      default:
+        throw new CliError(`알 수 없는 옵션: ${a}`);
+    }
+  }
+  return result;
+}
+
+export class CliError extends Error {}
+
+// 경로 정규화 (.sh resolve_project_paths §3.4): 앞뒤 공백·\→/·끝 /·앞 ./ 제거, 빈값→"."
+export function normalizePath(p) {
+  let s = String(p).trim();
+  s = s.replace(/\\/g, "/");
+  s = s.replace(/\/+$/, "");   // 끝 /
+  s = s.replace(/^\.\//, "");  // 앞 ./
+  return s === "" ? "." : s;
+}
+
+// "flutter=app,react=client" → Map<type, normalizedPath>. 타입 검증(무효 → throw).
+export function parsePathsCsv(csv) {
+  const map = new Map();
+  if (!csv) return map;
+  for (const pair of csv.split(",")) {
+    if (pair.trim() === "") continue;
+    const eq = pair.indexOf("=");
+    const type = (eq >= 0 ? pair.slice(0, eq) : pair).trim();
+    const rawPath = eq >= 0 ? pair.slice(eq + 1) : "";
+    if (!VALID_TYPES.includes(type)) {
+      throw new CliError(`--paths에 지원하지 않는 타입: '${type}'`);
+    }
+    map.set(type, normalizePath(rawPath));
+  }
+  return map;
+}

package/src/cli/help.js

@@ -0,0 +1,27 @@
+// --help 텍스트.
+export const HELP_TEXT = `project-auto-wizard — One command DevOps: GitHub-native AI 릴리스 자동화 설치 마법사
+
+사용법:
+  npx project-auto-wizard [옵션]
+
+옵션:
+  -m, --mode MODE          통합 모드 (full | version | workflows | revert)
+                           기본: interactive (대화형). revert = 설치물 제거(되돌리기)
+  -t, --type CSV           프로젝트 타입 csv (예: spring,react,python)
+                           지원: spring flutter next react react-native
+                                 react-native-expo node python basic
+      --project-version V  통합 대상의 초기 버전 (예: 1.0.0). 미지정 시 자동 감지
+      --paths "t=p,..."    타입별 프로젝트 경로 (모노레포). 예: flutter=app,react=client
+      --main-branch B      릴리스 브랜치 (기본: 감지된 default branch)
+      --develop-branch B   개발 브랜치 (기본: develop). 릴리스 브랜치와 같으면 trunk-based 모드
+      --nexus / --no-nexus            Nexus 라이브러리 publish 워크플로우 포함/제외
+      --secret-backup / --no-secret-backup   Secret 백업 워크플로우 포함/제외
+      --coderabbit / --no-coderabbit  CodeRabbit PR 요약을 릴리스 노트 1순위로 사용 (기본: 사용 안 함)
+      --force              모든 확인 생략, 비대화형 기본값 사용
+  -v, --version            project-auto-wizard 버전 출력
+  -h, --help               이 도움말 표시
+
+예시:
+  npx project-auto-wizard --mode full --force --type spring,react
+  npx project-auto-wizard --mode workflows --type flutter --paths "flutter=app"
+`;

package/src/commands/full.js

@@ -0,0 +1,53 @@
+// full 모드 오케스트레이터 (.sh execute_integration full case 등가).
+// 복사 순서: workflows(+env 치환) → version.yml → readme → scripts → coderabbit → gitignore
+// (원본의 util/issue/discussion/setup-guide/config 설치는 project-auto-wizard 스코프에서 제외 — DESIGN-SPEC §2)
+import { join } from "node:path";
+import { writeText } from "../core/fsutil.js";
+import { PATHS } from "../core/paths.js";
+import { buildVersionYml } from "../core/version-yml.js";
+import { readVersionYmlTemplate } from "../core/assets.js";
+import { markerForType } from "../core/detect.js";
+import { addVersionSectionToReadme } from "../core/copy/readme.js";
+import { copyWorkflows } from "../core/copy/workflows.js";
+import { copyScripts } from "../core/copy/simple.js";
+import { copyCoderabbit } from "../core/copy/coderabbit.js";
+import { ensureGitignore } from "../core/copy/gitignore.js";
+
+// context: { version, types, paths:Map, branch, versionCode, includeNexus, includeSecretBackup,
+//            force, repoName, resolvers, now, today }
+// payloadRoot: 패키지 payload/ 루트. targetRoot: 통합 대상.
+export function runFull(context, payloadRoot, targetRoot = ".", hooks = {}) {
+  const { version, types = [], paths = new Map(), branch = "main", versionCode = 1,
+    force = true, now, today, templateVersion = "unknown",
+    includeNexus = false, includeSecretBackup = false, includeCodeRabbit = false } = context;
+
+  // project_paths 마커 계산 (.sh existing_marker_in_dir 등가 — 대표 마커명)
+  const pathMarkers = new Map();
+  for (const [t] of paths) pathMarkers.set(t, markerForType(t));
+
+  // 1. 워크플로우 복사 (+ env 치환) — deploy 블록에 쓸 ask 값을 수집한다.
+  //    hooks.decisions: 대화형 충돌 3지선 결정 Map (미지정=skip — 현행 force 동작)
+  const wfCounters = copyWorkflows(context, payloadRoot, targetRoot, hooks);
+  const deployValues = wfCounters.deployValues || new Map(); // Map<type, Map<key,value>>
+
+  // 2. version.yml 생성 (payload/version.yml.template 렌더링 — 전체 재생성 전략 D4)
+  writeText(join(targetRoot, PATHS.versionFile),
+    buildVersionYml({
+      templateText: readVersionYmlTemplate(payloadRoot),
+      version, types, paths, pathMarkers, branch, branches: context.branches, versionCode, now, today,
+      deployValues,
+      templateOptions: { templateVersion, includeNexus, includeSecretBackup, includeCodeRabbit: includeCodeRabbit === true, optionsDate: today },
+    }));
+
+  // 3. README 버전 섹션
+  addVersionSectionToReadme(version, targetRoot);
+
+  // 4. scripts (payload/scripts/*.py → .github/scripts/)
+  copyScripts(payloadRoot, targetRoot);
+
+  // 5. coderabbit (opt-in true일 때만 — DESIGN-SPEC §4 질문②) / gitignore
+  if (includeCodeRabbit === true) copyCoderabbit(payloadRoot, { force }, targetRoot);
+  ensureGitignore(targetRoot);
+
+  return { workflows: wfCounters };
+}