project-auto-wizard 0.10.0 → 0.12.0

package/README.md

@@ -1,6 +1,6 @@
 # project-auto-wizard
 
-> **One command DevOps** — `npx` 한 줄로 어떤 프로젝트든 GitHub-native AI 릴리스 자동화를 설치하는 마법사
+> **One command DevOps** — `npx` 한 줄로 어떤 프로젝트든 GitHub-native 릴리스 자동화(GitHub Copilot AI 요약은 선택)를 설치하는 마법사
 
 - 새 프로젝트를 시작하면 코드를 작성하기 전부터 버전 관리, 배포 자동화, 변경 기록 작성처럼 먼저 정해야 할 일이 많다. project-auto-wizard는 이 준비 과정을 명령 한 번으로 구성하고, 프로젝트 상태 관리가 GitHub 안에서 자동으로 동작하도록 해 개발자가 기능 구현에 집중하도록 돕는 오픈소스 도구
 
@@ -17,7 +17,7 @@ npx project-auto-wizard
 [![node](https://img.shields.io/badge/node-%3E%3D20.12-brightgreen)](package.json)
 
 <!-- AUTO-VERSION-SECTION: DO NOT EDIT MANUALLY -->
-## 최신 버전 : v0.9.0 (2026-09-18)
+## 최신 버전 : v0.11.0 (2026-09-23)
 
 [전체 버전 기록 보기](CHANGELOG.md)
 
@@ -38,7 +38,7 @@ npx project-auto-wizard --mode full --force --type spring,react   # CI에서 비
 | 축 | 내용 |
 |---|---|
 | ① **npx 마법사** | 마커 파일로 프로젝트 타입 자동 감지 — **10타입 + 멀티타입 + 모노레포 경로**까지. 질문은 최소한만 |
-| ② **GitHub-native AI Release Automation** | 릴리스 PR을 열면: 버전 확정 → **AI가 릴리스 노트 작성** → CHANGELOG 갱신 → automerge → tag + GitHub Release. **API 키 0개** (GitHub Models) |
+| ② **GitHub-native Release Automation** | 릴리스 PR을 열면: 버전 확정 → **릴리스 노트 작성**(기본은 규칙 기반, GitHub Copilot AI는 선택) → CHANGELOG 갱신 → automerge → tag + GitHub Release. **API 키 0개** |
 | ③ **타입별 CI/CD 워크플로우** | Spring(무중단 배포 포함)·Flutter(스토어 배포)·React·Next·Python·Go 등 타입에 맞는 GitHub Actions 자동 배치 |
 
 ### 지원 프로젝트 타입
@@ -66,7 +66,7 @@ flutter.APP_ARTIFACT_NAME:
 
 `spring`/`flutter`는 아래처럼 단일 CI 이상으로 깊게 구성되어 있습니다:
 
-- **flutter**: Android(Firebase/Playstore/Selfhosted/TestAPK 배포), iOS(TestFlight/Test-TestFlight), CI, Lab 트리거까지 8종
+- **flutter**: Android(Firebase/Playstore/Selfhosted/TestAPK 배포), iOS(TestFlight/Test-TestFlight), CI, Lab 트리거까지 8종 — 스토어 배포(Play Store·TestFlight)는 고른 플랫폼만 설치되고 fastlane 파일도 함께 생성됩니다. 환경변수 방식·배포 모드 등 자세한 내용은 아래 "Flutter 워크플로우 상세"를 참고하세요.
 - **spring**: 서버 배포 1종(단일 서버 / 무중단 Nginx / 무중단 Traefik / 배포 안 함 중 택1) + PR 프리뷰 + 라이브러리 publish 2종(Nexus·GitHub Packages, `--nexus` opt-in)
   - 서버 배포 워크플로우는 **서로 대체재**라 하나만 설치합니다. 대화형에서 고르면 그것만 깔리고 **`push` 트리거까지 켜진 채로** 설치됩니다. 비대화형은 `--deploy-style simple|nginx|traefik|none` (기본: `simple`).
   - 고른 방식은 `version.yml`에 기록되므로 다시 실행해도 묻지 않습니다. 방식을 바꾸면 **이전 워크플로우를 마법사가 정리합니다** — 손대지 않은 파일은 삭제하고, 수정한 파일은 `.bak`으로 옮겨 내용을 보존합니다. 남겨두면 배포가 두 번 돕니다.
@@ -75,6 +75,81 @@ flutter.APP_ARTIFACT_NAME:
 - **python**: CI / PR 프리뷰 / SimpleCICD
 - **go**: CI(Dockerfile 불필요, go test/vet/build/lint) / PR 프리뷰 / SimpleCICD(Dockerfile 있는 프로젝트만 해당)
 
+<a id="flutter-store"></a>
+
+#### Flutter 워크플로우 상세
+
+프로젝트 타입에 `flutter`가 포함되면 마법사가 아래 선택지 3개를 묻습니다. 고른 값은 `version.yml`의 `metadata.template.options`(`env_mode`, `flutter_store`, `android_deploy_mode`, `ios_deploy_mode`)에 기록되므로 다시 실행해도 묻지 않고, 나중에 바꾸려면 확인 화면의 **수정하기 > 환경변수 방식 / 스토어 배포 대상 / 배포 모드**를 쓰세요. Flutter가 없는 프로젝트에는 이 질문·저장값이 전혀 나타나지 않습니다.
+
+| 선택지 | 값 | 기본값 | CLI 플래그 |
+|---|---|---|---|
+| 환경변수 방식 | `dart-define` / `dotenv` | 신규 설치는 `dart-define`. `version.yml`이 이미 있고 저장값이 없는 설치는 기존 동작을 보존하려고 `dotenv` 유지 | `--flutter-env-mode` |
+| 스토어 배포 대상 | Android(Play Store) / iOS(TestFlight) 다중 선택 | 대화형 신규 설치는 아무것도 선택하지 않은 상태, 비대화형·플래그 미지정은 현행 동작(둘 다 설치). 저장값이 없는 기존 설치는 이미 설치된 스토어 워크플로우에서 초기 선택을 추론 | `--flutter-store android,ios,none` |
+| 배포 모드 | 고른 플랫폼별 `store_only` / `store_prepare` / `store_submit` | `store_only` | `--android-deploy-mode`, `--ios-deploy-mode` |
+
+**설치되는 구성**
+
+- 항상 설치: `CI`, `ANDROID-FIREBASE-CICD`, `ANDROID-SELFHOSTED-CICD`, `ANDROID-TEST-APK`, `APP-BUILD-TRIGGER`
+- Android를 고르면: `ANDROID-PLAYSTORE-CICD` + `android/fastlane/Fastfile.playstore`
+- iOS를 고르면: `IOS-TESTFLIGHT` + `IOS-TEST-TESTFLIGHT` + `ios/fastlane/Fastfile` + `ios/ExportOptions.plist`
+- fastlane은 위 스토어 배포 워크플로우에서만 씁니다. `SELFHOSTED`와 `TEST-APK`는 `flutter build apk --release`를 직접 실행하며 Ruby·fastlane을 설치하지 않습니다.
+- `Fastfile`과 `ExportOptions.plist`는 **Flutter 루트 기준**으로(모노레포는 `--paths flutter=app`이면 `app/` 아래) **없을 때만 생성**합니다. 이미 있으면 덮어쓰지 않고 설치 요약과 `--dry-run`에 "기존 파일 유지"로 표시하며, `--mode uninstall`도 이 파일들은 건드리지 않습니다(사용자 소유 파일).
+- 스토어 대상을 해제하고 다시 실행하면 배포 방식을 바꿀 때와 같은 규칙으로 정리합니다 — 손대지 않은 워크플로우는 삭제하고, 수정한 것은 `.bak`으로 옮겨 보존합니다. `Fastfile`·`ExportOptions.plist`는 삭제하지 않습니다.
+
+**환경변수 방식**
+
+두 방식 모두 시크릿 `ENV_FILE`(없으면 `ENV`)에 `.env` 형식으로 값을 넣어 두면 됩니다. 두 방식을 동시에 쓰는 모드는 없습니다.
+
+- `dart-define`: `ENV_FILE`을 프로젝트 밖 임시 경로(러너 임시 폴더)에 쓰고 모든 `flutter build`에 `--dart-define-from-file`로 넘깁니다. 프로젝트 루트에는 `.env`를 만들지 않으며, 코드에서는 `String.fromEnvironment('KEY')`로 읽습니다. 값이 아닌 파일 경로를 넘기므로 `--verbose` 로그에도 값이 명령줄에 노출되지 않습니다.
+- `dotenv`: Flutter 루트에 `.env`를 만든 뒤 빌드합니다(`build_runner`가 그 뒤에 실행되는 순서 유지). `flutter_dotenv`·`envied`를 쓰는 프로젝트가 여기에 해당합니다. 이 `.env`에는 아래 파서 제약이 적용되지 않습니다.
+
+`dart-define` 방식에서 `ENV_FILE`은 Flutter의 `--dart-define-from-file` 파서가 읽으므로 다음 범위만 지원됩니다 (근거: Flutter 3.47.5 `flutter_tools/lib/src/runner/flutter_command.dart`의 `DotEnvRegex`).
+
+- 내용이 `{`로 시작하면 JSON 파일로 해석하고, 그렇지 않으면 `KEY=값` 줄로 해석합니다. 키는 `[a-zA-Z_][a-zA-Z0-9_]*` 형태여야 합니다.
+- `#`로 시작하는 주석 줄과 빈 줄은 무시합니다.
+- 값은 `"…"`, `'…'`, `` `…` `` 따옴표가 벗겨지고 그 뒤의 `# 주석`은 제거됩니다. 따옴표 없는 값은 공백 또는 `#` 앞까지 읽으며, 값 안의 `=`는 허용됩니다.
+- `export KEY=값` 형태와 멀티라인(`"""`) 값은 지원하지 않아 빌드가 오류로 종료됩니다.
+
+**배포 모드** — 플랫폼별로 아래처럼 동작합니다(모르는 값은 `store_only`로 취급). 기본값은 워크플로우 표현식의 폴백 자리에 반영되며, 저장소 변수 `ANDROID_DEPLOY_MODE`·`IOS_DEPLOY_MODE`와 `workflow_dispatch` 입력이 항상 우선합니다.
+
+| 모드 | Play Store (Android) | TestFlight / App Store (iOS) |
+|---|---|---|
+| `store_only` | internal 트랙에 업로드 | TestFlight 업로드 |
+| `store_prepare` | production 트랙에 draft 상태로 업로드 (Play Console에서 직접 출시) | 앱 버전·메타데이터 준비까지 (심사 제출 안 함) |
+| `store_submit` | production 트랙에 심사 제출 | 심사 제출까지 |
+
+> `store_submit`을 고르면 **main push마다 심사가 자동 제출**됩니다.
+
+**필요한 Secrets · Variables** — 설치 완료 화면과 실행 로그에도 설치된 워크플로우가 실제로 요구하는 Secret 목록이 출력됩니다.
+
+| 대상 | Secrets | Variables |
+|---|---|---|
+| 모든 Flutter 빌드 | `ENV_FILE` (없으면 `ENV`) | — |
+| Android 서명 (`PLAYSTORE`·`FIREBASE`·`TEST-APK`) | `RELEASE_KEYSTORE_BASE64`, `RELEASE_KEYSTORE_PASSWORD`, `RELEASE_KEY_ALIAS`, `RELEASE_KEY_PASSWORD`, `GOOGLE_SERVICES_JSON` | — |
+| Play Store (`PLAYSTORE`) | `GOOGLE_PLAY_SERVICE_ACCOUNT_JSON_BASE64`, `ANDROID_PACKAGE_NAME` | `ANDROID_PACKAGE_NAME`(Secret이 없을 때 대신 사용), `ANDROID_DEPLOY_MODE`(선택) |
+| iOS (`IOS-TESTFLIGHT`·`IOS-TEST-TESTFLIGHT`) | `APP_STORE_CONNECT_API_KEY_BASE64`, `APP_STORE_CONNECT_API_KEY_ID`, `APP_STORE_CONNECT_ISSUER_ID`, `APPLE_CERTIFICATE_BASE64`, `APPLE_CERTIFICATE_PASSWORD`, `APPLE_PROVISIONING_PROFILE_BASE64`, `IOS_PROVISIONING_PROFILE_NAME`, `IOS_BUNDLE_ID`, `SECRETS_XCCONFIG`(선택) | `IOS_BUNDLE_ID`(Secret이 없을 때 대신 사용), `IOS_DEPLOY_MODE`(선택) |
+| Firebase 배포 (`FIREBASE`·`TEST-APK`) | `FIREBASE_SERVICE_ACCOUNT_JSON_BASE64` | — |
+| Selfhosted 배포 (`SELFHOSTED`) | `SERVER_HOST`, `SERVER_USER`, `SERVER_PASSWORD`, `DEBUG_KEYSTORE` | — |
+
+`ANDROID_PACKAGE_NAME`은 `PLAYSTORE` 워크플로우가 fastlane에 패키지명으로 넘깁니다(`secrets` 우선, 없으면 `vars`). iOS의 `IOS_BUNDLE_ID`와 같은 플랫폼 접두사 규칙입니다.
+
+**`ExportOptions.plist`에 채워야 할 값** — 마법사가 만든 `ios/ExportOptions.plist`에는 아래 플레이스홀더가 들어 있어 실제 값으로 바꿔야 합니다. 채우지 않고 `IOS-TESTFLIGHT`를 실행하면 `xcodebuild`의 알기 어려운 오류 대신 플레이스홀더가 남았다는 메시지로 검증 단계에서 중단되며, `--mode doctor`도 같은 항목을 WARN으로 알려줍니다.
+
+| 플레이스홀더 | 채울 값 |
+|---|---|
+| `__TEAM_ID__` | Apple Developer Team ID |
+| `__BUNDLE_ID__` | 앱 번들 ID (`IOS_BUNDLE_ID`와 같은 값) |
+| `__PROVISIONING_PROFILE_NAME__` | 프로비저닝 프로파일 이름 (`IOS_PROVISIONING_PROFILE_NAME`과 같은 값) |
+
+**모노레포와 `ci-gate`**
+
+- `--paths flutter=app`처럼 Flutter 하위 폴더를 지정하면 모든 Flutter 워크플로우가 그 폴더(`FLUTTER_PROJECT_DIR`)를 기준으로 동작하고, main push로 도는 배포 워크플로우(`PLAYSTORE`·`IOS-TESTFLIGHT`·`SELFHOSTED`·`FIREBASE`)는 `app/**`가 바뀔 때만 실행됩니다(Spring 등 다른 타입과 같은 `paths` 필터).
+- CI 워크플로우(Flutter·Go·Next·Python·React·Spring NEXUS-CI)는 `push`·`pull_request`에서 항상 실행되고, 첫 job `changes`가 변경 파일을 판별해 나머지 job을 건너뜁니다(건너뛴 job은 Success). 마지막 job `ci-gate`는 항상 실행되어 필수 job이 모두 success 또는 skipped이면 통과하고 failure·cancelled가 하나라도 있으면 실패합니다.
+- 브랜치 보호 규칙의 required status check에는 개별 job이 아니라 **`CI Gate`(`ci-gate`) 하나만** 등록하세요. 경로 필터로 워크플로우 자체를 건너뛰면 required check가 Pending에 머물러 머지가 막히지만, job을 건너뛰는 방식은 그렇지 않기 때문입니다.
+- 워크플로우 `paths` 필터는 태그 push에 적용되지 않습니다(GitHub 문서).
+
+**Gemfile** — 스토어 배포 워크플로우(`PLAYSTORE`·`IOS-TESTFLIGHT`·`IOS-TEST-TESTFLIGHT`)는 사용자 `Gemfile`에 `fastlane`이 있으면 그것을 쓰고, 없으면 실행할 때 생성합니다. 마법사는 Gemfile 템플릿을 배포하지 않습니다. fastlane 공식 문서가 권장하는 대로 `Gemfile`(`gem "fastlane"`)과 `Gemfile.lock`을 저장소에 커밋해 두면 버전이 고정되어 재현성이 좋아집니다.
+
 ### 실행 로그 (`.github/.wizard/logs/`)
 
 설치·업데이트·삭제를 실행할 때마다 `.github/.wizard/logs/<시각>-<동작>.log`에 실행 추적이 남습니다. 감지 근거, **파일별 처리 결정과 그 사유**, 치환된 값, 미치환 항목, 등록해야 하는 GitHub Secret이 시간순으로 기록되고, 파일 끝에 결과 요약이 붙습니다.
@@ -108,18 +183,23 @@ npx project-auto-wizard --mode uninstall --force         # 워크플로우·스
 npx project-auto-wizard --mode uninstall --force --purge-readme --purge-gitignore --purge-version  # 완전 삭제
 ```
 
-## API 키 0개 AI — 요약 엔진 체인
+## 요약 엔진 체인
+
+릴리스 노트는 3단 엔진 체인으로 생성됩니다. **어떤 단계가 실패해도 릴리스는 절대 막히지 않습니다.**
 
-릴리스 노트는 3단 엔진 체인으로 생성됩니다. **상용 서드파티 서비스에 전혀 의존하지 않으며, 어떤 단계가 실패해도 릴리스는 절대 막히지 않습니다.**
+> GitHub Models는 2026-07-30에 종료되어 더 이상 사용하지 않습니다.
 
 ```mermaid
 flowchart LR
-    B["사용자 지정 AI<br/>(AI_API_KEY)"] -->|"키 없음/실패"| C["GitHub Models<br/>(GITHUB_TOKEN만, 무료)"]
-    C -->|"rate limit/실패"| D["규칙 기반 fallback<br/>(항상 성공)"]
+    B["사용자 지정 AI<br/>(AI_API_KEY + AI_API_BASE_URL + AI_MODEL)"] -->|"미설정/실패"| C["GitHub Copilot CLI<br/>(선택, GITHUB_TOKEN)"]
+    C -->|"꺼짐/사용 불가/실패"| D["규칙 기반 fallback<br/>(항상 성공)"]
 ```
 
-- 기본값은 **GitHub Models** — Actions의 `GITHUB_TOKEN` + `permissions: models: read`만으로 동작. **비용 0, 설정 0.**
-- `AI_API_KEY`/`AI_API_BASE_URL`/`AI_MODEL` secret으로 OpenAI-호환 엔드포인트(Groq, Gemini 호환 모드, Ollama 등) 교체 가능.
+- 기본값은 **규칙 기반 요약**입니다. 설치 마법사에서 Copilot을 켜면(`--copilot`, `version.yml`의 `copilot_ai: true`) Actions의 `GITHUB_TOKEN` + `permissions: copilot-requests: write`로 Copilot CLI가 요약을 생성합니다 — 별도 API 키는 필요 없습니다.
+- **Copilot은 GitHub Copilot AI Credits를 소비합니다.** 개인 저장소는 저장소 소유자의 Copilot 좌석에, 조직 저장소는 조직에 과금되며 조직은 "Allow use of Copilot CLI billed to the organization" 정책을 켜야 합니다. 사용할 수 없으면 자동으로 규칙 기반 요약으로 전환됩니다. PR에 푸시할 때마다 요약이 새로 생성되므로 그만큼 크레딧이 소비됩니다.
+- Copilot 모델은 저비용 소형 모델(`claude-haiku-4.5`)로 고정되어 있고, 저장소 변수 `COPILOT_MODEL`로 바꿀 수 있습니다.
+- GitHub은 Copilot CLI를 `run` 스텝에서 직접 호출하기보다 Agentic Workflows를 쓰라고 권고하지만, 이 프로젝트는 직접 호출을 택했습니다. 프롬프트 입력이 PR 제목·커밋 메시지·`git diff --stat`뿐이고, 빈 임시 디렉터리에서 shell/write/url 도구와 내장 MCP를 모두 막은 텍스트 생성 전용으로 호출하며, 포크 PR은 기존 가드로 건너뛰어 프롬프트 인젝션 위험을 낮췄기 때문입니다.
+- `AI_API_KEY`(**Secret**)와 `AI_API_BASE_URL`·`AI_MODEL`(**Variables**)을 **모두** 설정하면 OpenAI-호환 엔드포인트(Groq, Gemini 호환 모드, Ollama 등)를 최우선으로 사용합니다. 셋 중 하나라도 없으면 이 단계는 건너뜁니다.
 - 규칙 fallback 3단: 프로젝트 컨벤션 → Conventional Commits → 무형식 bullet. 커밋 컨벤션이 없어도 동작.
 
 ## 릴리스 흐름
@@ -129,7 +209,7 @@ flowchart LR
     subgraph pr-flow ["pr-flow (기본)"]
         D1[develop push] --> PR[develop→main 릴리스 PR]
         PR --> V["버전 확정 (patch+1)"]
-        V --> AI[AI 릴리스 노트]
+        V --> AI[릴리스 노트]
         AI --> CL[CHANGELOG.json/md 갱신]
         CL --> AM[automerge]
         AM --> TAG["tag vX.Y.Z + GitHub Release"]
@@ -154,9 +234,14 @@ npx project-auto-wizard [옵션]
       --main-branch B      릴리스 브랜치 (기본: 감지된 default branch)
       --develop-branch B   개발 브랜치 (기본: develop)
       --deploy-style S     서버 배포 방식: simple | nginx | traefik | none (기본: simple)
+      --flutter-env-mode M     Flutter 환경변수 방식: dart-define | dotenv (신규 기본: dart-define, 저장값 없는 기존 설치는 dotenv 유지)
+      --flutter-store CSV      Flutter 스토어 배포 대상: android,ios,none (미지정 시 둘 다 설치)
+      --android-deploy-mode M  Play Store 배포 모드: store_only | store_prepare | store_submit (기본: store_only)
+      --ios-deploy-mode M      iOS 배포 모드: store_only | store_prepare | store_submit (기본: store_only)
       --nexus              라이브러리 publish 워크플로우 포함 (Nexus + GitHub Packages)
       --secret-backup      Secret 서버 백업 워크플로우 포함
       --semver-auto        커밋 타입 기반 자동 major/minor/patch 승격 (기본: 사용함, --no-semver-auto로 끔)
+      --copilot            Copilot으로 AI 요약 생성 (기본: 사용 안 함, GitHub Copilot AI Credits 소비, --no-copilot으로 끔)
       --dry-run            실제 파일 변경 없이 무엇이 바뀔지만 미리 보여줌
       --purge-readme        --mode uninstall --force 시 README.md 버전 섹션도 제거
       --purge-gitignore     --mode uninstall --force 시 .gitignore 자동 추가 항목도 제거
@@ -173,8 +258,8 @@ npx project-auto-wizard --mode doctor   # 환경 진단 (읽기 전용, 규칙
 
 | 명령 | 내용 |
 |---|---|
-| `--mode status` | 설치된 버전·타입·브랜치 모드·옵션값과, 설치 시점 대비 사용자가 직접 수정한 워크플로우 파일 목록을 보여줍니다. 네트워크 접근 없음(로컬 파일 비교만) |
-| `--mode doctor` | `version.yml` 설치 여부, `gh` CLI 설치/인증 상태, GitHub Actions workflow permissions, `WORKFLOW_PAT` secret 등록 여부, merge commit 허용 설정을 점검합니다. `gh api` 호출을 사용하므로 네트워크 접근이 발생합니다(규칙 기반 점검 — AI 진단 아님) |
+| `--mode status` | 설치된 버전·타입·브랜치 모드·옵션값(Flutter 프로젝트면 환경변수 방식·스토어 배포 대상·배포 모드 포함)과, 설치 시점 대비 사용자가 직접 수정한 워크플로우 파일 목록을 보여줍니다. 네트워크 접근 없음(로컬 파일 비교만) |
+| `--mode doctor` | `version.yml` 설치 여부, `gh` CLI 설치/인증 상태, GitHub Actions workflow permissions, `WORKFLOW_PAT` secret 등록 여부, merge commit 허용 설정을 점검합니다. Flutter 프로젝트에서는 고른 스토어 플랫폼의 필수 파일(`Fastfile`, `ExportOptions.plist` 등)과 `ExportOptions.plist`의 플레이스홀더 잔존 여부도 점검합니다(로컬 파일만 확인, 스토어 시크릿 등록 여부는 점검하지 않음). `gh api` 호출을 사용하므로 네트워크 접근이 발생합니다(규칙 기반 점검 — AI 진단 아님) |
 
 `doctor`는 항목마다 **그 설정이 무엇을 담당하는지**를 라벨에 함께 표시하고, 문제가 있는 항목만 `현상 → 그대로 두면 무엇이 안 되는지 → 어디를 눌러 고치는지 → 문서 링크` 순으로 펼쳐 보여줍니다. 정상 항목은 한 줄로 압축됩니다. GitHub 설정 화면에 실제로 표시되는 문자열(`Read and write permissions` 등)은 화면에서 찾을 수 있도록 원문 그대로 출력합니다.
 
@@ -191,9 +276,10 @@ npx project-auto-wizard --mode doctor   # 환경 진단 (읽기 전용, 규칙
       secret이 없어도 폴백이 자동으로 이어받아 태그·Release까지 진행됩니다 — 실제 병합 후 최대 ~20초 정도 더 걸릴 뿐입니다.
       속도를 더 원한다면 PAT을 등록할 수 있습니다 — 반드시 개인 계정이 아닌 조직 bot/machine 계정으로 발급하세요 (scopes: repo, workflow).
       등록: 레포 Settings → Secrets and variables → Actions → New repository secret · 이름은 WORKFLOW_PAT
-  [i] GitHub Models — AI 릴리스 노트 생성
-      조직 정책으로 차단됐는지는 자동으로 확인할 수 없습니다 (Settings → Models).
-      차단돼 있어도 규칙 기반 요약으로 자동 전환되므로 그대로 두셔도 됩니다.
+  [i] Copilot AI 요약 — AI 릴리스 노트 생성(선택)
+      기본은 꺼져 있습니다 (version.yml의 copilot_ai: false).
+      켜면 GitHub Copilot AI Credits가 소비됩니다 — 조직은 'Allow use of Copilot CLI billed to the organization' 정책이 필요합니다.
+      꺼져 있거나 사용할 수 없으면 규칙 기반 요약으로 자동 전환되므로 그대로 두셔도 됩니다.
 
   ✓ 문제를 찾지 못했습니다.
 ```
@@ -217,7 +303,7 @@ npx project-auto-wizard --no-semver-auto   # 항상 patch+1 (레거시 동작)
 
 ### 자체 AI PR 요약봇
 
-상용 PR 리뷰 SaaS 없이 동작하는 자체 요약봇입니다. 릴리스 브랜치(`--main-branch`)를 대상으로 하는 PR이 열릴 때 API 키 0개 AI 엔진 체인으로 요약 코멘트를 자동으로 답니다.
+상용 PR 리뷰 SaaS 없이 동작하는 자체 요약봇입니다. 릴리스 브랜치(`--main-branch`)를 대상으로 하는 PR이 열릴 때 요약 엔진 체인(기본은 규칙 기반, Copilot은 선택)으로 요약 코멘트를 자동으로 답니다.
 
 기본 설치(pr-flow) 기준으로 일상적인 기능 PR은 `develop`을 대상으로 열리므로, 이 봇은 develop→main 릴리스 PR에서만 실제로 동작합니다 — 해당 PR에서는 `AUTO-CHANGELOG-CONTROL`이 이미 같은 엔진으로 체인지로그 요약을 생성하므로, 이 봇은 그 요약을 PR 코멘트 형태로도 남겨주는 보조 역할입니다. 릴리스 브랜치 = 개발 브랜치인 trunk-based 모드에서는 모든 PR이 곧 릴리스 대상 브랜치를 향하므로 매 PR마다 동작합니다.
 
@@ -229,7 +315,7 @@ npx project-auto-wizard --no-semver-auto   # 항상 patch+1 (레거시 동작)
 |---|---|
 | **`WORKFLOW_PAT` secret** (선택 — 속도 최적화용) | 없어도 `GITHUB_TOKEN` 폴백이 automerge부터 Release 발행까지 자동으로 이어갑니다(실제 병합 후 최대 ~20초 추가). 더 빠르게 하고 싶다면 Settings → Secrets → Actions에 `WORKFLOW_PAT` (scopes: `repo`, `workflow`) 등록 — 반드시 개인 계정이 아닌 조직 bot/machine 계정으로 발급하세요 |
 | **Workflow permissions** | Settings → Actions → Workflow permissions: **Read and write** |
-| **GitHub Models** | 기본 활성 — 별도 설정 불필요. 조직 정책으로 차단된 경우 자동으로 규칙 fallback |
+| **Copilot AI 요약** (선택) | 기본 꺼짐. 켜려면 마법사에서 선택하거나 `version.yml`의 `copilot_ai`를 `true`로 — AI Credits가 소비되며 조직은 "Allow use of Copilot CLI billed to the organization" 정책이 필요합니다. 사용할 수 없으면 자동으로 규칙 fallback |
 
 ## 설계 원칙
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "project-auto-wizard",
-  "version": "0.10.0",
-  "description": "One command DevOps: npx wizard that installs GitHub-native AI Release Automation into any project",
+  "version": "0.12.0",
+  "description": "One command DevOps: npx wizard that installs GitHub-native Release Automation (optional GitHub Copilot AI summaries) into any project",
   "license": "MIT",
   "type": "module",
   "bin": {

package/payload/config/breaking-changes.json

@@ -1 +1,24 @@
-{}
+{
+  "0.10.1": [
+    {
+      "severity": "warning",
+      "title": "Flutter SELFHOSTED·TEST-APK가 flutter build를 직접 실행",
+      "message": "SELFHOSTED·TEST-APK가 fastlane build 대신 flutter build apk --release를 직접 실행하고 Ruby·fastlane 설치 스텝이 사라집니다. fastlane은 스토어 배포 3종(PLAYSTORE·IOS-TESTFLIGHT·IOS-TEST-TESTFLIGHT)에서만 사용합니다."
+    },
+    {
+      "severity": "warning",
+      "title": "Flutter 환경변수 기본 방식이 dart-define으로 변경",
+      "message": "신규 설치의 기본값이 dart-define(--dart-define-from-file)으로 바뀝니다. 기존 설치는 version.yml에 저장값이 없으면 dotenv(.env 생성)를 유지하며, 바꾸려면 마법사 '수정하기 > 환경변수 방식' 또는 --flutter-env-mode를 쓰세요."
+    },
+    {
+      "severity": "warning",
+      "title": "Flutter 워크플로우가 FLUTTER_PROJECT_DIR 기준으로 동작",
+      "message": "FIREBASE·SELFHOSTED·CI·TEST-APK·IOS-TEST-TESTFLIGHT도 PLAYSTORE처럼 Flutter 루트(FLUTTER_PROJECT_DIR)에서 동작합니다. Flutter가 하위 폴더에 있는 모노레포는 --paths flutter=<경로>로 지정하세요."
+    },
+    {
+      "severity": "warning",
+      "title": "모노레포 CI required check는 ci-gate 하나만 등록",
+      "message": "CI 워크플로우(Flutter·Go·Next·Python·React·Spring NEXUS-CI)는 항상 실행되고 변경이 없으면 job을 건너뜁니다. required check로 쓰려면 개별 job이 아닌 CI Gate(ci-gate) 하나만 등록하세요."
+    }
+  ]
+}

package/payload/flutter-app/android/fastlane/Fastfile.playstore

@@ -0,0 +1,86 @@
+# ===================================================================
+# 이 파일은 사용자 소유입니다. 모드별 동작을 여기서 수정하세요.
+# ===================================================================
+#
+# Google Play 배포용 Fastfile 템플릿입니다.
+# PROJECT-FLUTTER-ANDROID-PLAYSTORE-CICD 워크플로우가 이 파일을 android/fastlane/Fastfile로
+# 복사한 뒤 `bundle exec fastlane deploy_internal`을 실행합니다.
+# project-auto-wizard는 이 파일이 이미 있으면 덮어쓰지 않으므로 자유롭게 수정해도 됩니다.
+#
+# 배포 모드 (워크플로우가 DEPLOY_MODE 환경변수로 전달)
+# ┌───────────────┬────────────┬──────────────────┬──────────────────────────────┐
+# │ DEPLOY_MODE   │ track      │ release_status   │ 동작                         │
+# ├───────────────┼────────────┼──────────────────┼──────────────────────────────┤
+# │ store_only    │ internal   │ completed        │ 내부 테스트 트랙에 업로드    │
+# │ store_prepare │ production │ draft            │ 프로덕션에 초안으로 업로드   │
+# │               │            │                  │ (Play Console에서 직접 출시) │
+# │ store_submit  │ production │ completed        │ 프로덕션 심사 제출까지 진행  │
+# └───────────────┴────────────┴──────────────────┴──────────────────────────────┘
+# 알 수 없는 값이나 빈 값은 store_only로 처리합니다.
+#
+# 워크플로우가 넘기는 환경변수
+#   PACKAGE_NAME          앱 패키지명 (ANDROID_PACKAGE_NAME secrets/variables)
+#   AAB_PATH              업로드할 .aab 절대경로
+#   GOOGLE_PLAY_JSON_KEY  서비스 계정 JSON 키 파일 경로
+#   VERSION_NAME          버전 이름 (Play Console의 릴리스 이름)
+#   VERSION_CODE          버전 코드 (변경 이력 파일명과 일치)
+#   DEPLOY_MODE           위 표의 배포 모드
+#
+# 변경 이력은 워크플로우가 android/fastlane/metadata/android/ko-KR/changelogs/<VERSION_CODE>.txt
+# 로 만들어 두며, upload_to_play_store가 metadata_path 아래에서 버전 코드로 찾아 업로드합니다.
+
+default_platform(:android)
+
+platform :android do
+  desc "AAB를 Google Play에 업로드합니다 (DEPLOY_MODE: store_only | store_prepare | store_submit)"
+  lane :deploy_internal do
+    package_name = ENV["PACKAGE_NAME"].to_s.strip
+    if package_name.empty?
+      UI.user_error!("PACKAGE_NAME이 비어 있습니다. ANDROID_PACKAGE_NAME secrets/variables를 등록하세요. (예: com.example.app)")
+    end
+
+    aab_path = ENV["AAB_PATH"].to_s.strip
+    json_key = ENV["GOOGLE_PLAY_JSON_KEY"].to_s.strip
+    version_name = ENV["VERSION_NAME"].to_s.strip
+    version_code = ENV["VERSION_CODE"].to_s.strip
+    if aab_path.empty? || json_key.empty? || version_name.empty? || version_code.empty?
+      UI.user_error!("AAB_PATH, GOOGLE_PLAY_JSON_KEY, VERSION_NAME, VERSION_CODE 환경변수가 모두 필요합니다. 워크플로우에서 전달하는지 확인하세요.")
+    end
+
+    deploy_mode = ENV["DEPLOY_MODE"].to_s.strip
+    track, release_status =
+      case deploy_mode
+      when "store_prepare"
+        ["production", "draft"]
+      when "store_submit"
+        ["production", "completed"]
+      when "store_only"
+        ["internal", "completed"]
+      else
+        UI.important("알 수 없는 DEPLOY_MODE '#{deploy_mode}' 입니다. store_only로 처리합니다.") unless deploy_mode.empty?
+        ["internal", "completed"]
+      end
+
+    # lane은 Fastfile이 있는 android/fastlane 디렉토리에서 실행되므로,
+    # 워크플로우가 변경 이력을 만드는 android/fastlane/metadata/android와 같은 경로를 가리킵니다.
+    metadata_path = File.expand_path("metadata/android")
+    changelog_file = File.join(metadata_path, "ko-KR", "changelogs", "#{version_code}.txt")
+    UI.important("변경 이력 파일이 없습니다: #{changelog_file}") unless File.exist?(changelog_file)
+
+    UI.message("Play 배포: DEPLOY_MODE=#{deploy_mode.inspect} → track=#{track}, release_status=#{release_status}")
+
+    upload_to_play_store(
+      package_name: package_name,
+      json_key: json_key,
+      aab: aab_path,
+      track: track,
+      release_status: release_status,
+      version_name: version_name,
+      metadata_path: metadata_path,
+      skip_upload_apk: true,
+      skip_upload_metadata: true,
+      skip_upload_images: true,
+      skip_upload_screenshots: true
+    )
+  end
+end

package/payload/flutter-app/ios/ExportOptions.plist

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  이 파일은 사용자 소유입니다. 밑줄 두 개로 감싼 자리표시자 3곳을 실제 값으로 바꾼 뒤 커밋하세요.
+
+  PROJECT-FLUTTER-IOS-TESTFLIGHT / PROJECT-FLUTTER-IOS-TEST-TESTFLIGHT 워크플로우가
+  xcodebuild -exportArchive -exportOptionsPlist ExportOptions.plist 로 IPA를 만들 때 사용합니다.
+  자리표시자가 남아 있으면 워크플로우가 중단됩니다.
+  (이 주석에는 자리표시자를 적지 않았습니다. 값을 채운 뒤에도 남아 있는지 검사하기 때문입니다.)
+
+    teamID                 Apple Developer Team ID (10자리, developer.apple.com 계정의 Membership)
+    provisioningProfiles   키는 앱 번들 ID (예: com.example.app),
+                           값은 프로비저닝 프로파일 이름 (GitHub Secret IOS_PROVISIONING_PROFILE_NAME 값과 같게)
+-->
+<plist version="1.0">
+<dict>
+  <key>method</key>
+  <string>app-store-connect</string>
+  <key>teamID</key>
+  <string>__TEAM_ID__</string>
+  <key>signingStyle</key>
+  <string>manual</string>
+  <key>signingCertificate</key>
+  <string>Apple Distribution</string>
+  <key>provisioningProfiles</key>
+  <dict>
+    <key>__BUNDLE_ID__</key>
+    <string>__PROVISIONING_PROFILE_NAME__</string>
+  </dict>
+</dict>
+</plist>

package/payload/flutter-app/ios/fastlane/Fastfile

@@ -0,0 +1,117 @@
+# ===================================================================
+# 이 파일은 사용자 소유입니다. 모드별 동작을 여기서 수정하세요.
+# ===================================================================
+#
+# iOS 배포용 Fastfile 템플릿입니다. Flutter 워크플로우가 IPA를 만든 뒤
+# `cd ios && bundle exec fastlane <lane>`으로 실행합니다.
+# project-auto-wizard는 이 파일이 이미 있으면 덮어쓰지 않으므로 자유롭게 수정해도 됩니다.
+#
+# lane
+#   deploy              PROJECT-FLUTTER-IOS-TESTFLIGHT 워크플로우 (DEPLOY_MODE에 따라 분기)
+#   upload_testflight   PROJECT-FLUTTER-IOS-TEST-TESTFLIGHT 워크플로우 (IPA를 TestFlight에 올리기만 함)
+#
+# deploy lane의 배포 모드 (워크플로우가 DEPLOY_MODE 환경변수로 전달)
+# ┌───────────────┬──────────────────────────────────────────────────────────────┐
+# │ DEPLOY_MODE   │ 동작                                                         │
+# ├───────────────┼──────────────────────────────────────────────────────────────┤
+# │ store_only    │ TestFlight 업로드까지 (upload_to_testflight)                 │
+# │ store_prepare │ TestFlight 업로드 후, App Store 버전과 메타데이터를 준비     │
+# │               │ (upload_to_app_store, submit_for_review: false). 빌드는 이   │
+# │               │ 단계에서 버전에 연결되지 않고, store_submit이 build_number   │
+# │               │ 로 다시 호출될 때 한번에 연결·제출됩니다.                    │
+# │ store_submit  │ store_prepare와 같은 호출이고 심사 제출까지 진행             │
+# │               │ (submit_for_review: true, 이때 빌드가 버전에 연결됩니다)     │
+# └───────────────┴──────────────────────────────────────────────────────────────┘
+# 알 수 없는 값이나 빈 값은 store_only로 처리합니다.
+#
+# 워크플로우가 넘기는 환경변수
+#   APP_STORE_CONNECT_API_KEY_ID   App Store Connect API Key ID
+#   APP_STORE_CONNECT_ISSUER_ID    App Store Connect Issuer ID
+#   API_KEY_PATH                   AuthKey_XXXX.p8 파일 경로
+#   IPA_PATH                       업로드할 .ipa 절대경로
+#   RELEASE_NOTES                  TestFlight "What to Test" 문구 (changelog)
+#   APP_IDENTIFIER                 번들 ID (upload_testflight lane은 없으면 fastlane이 추론하지만,
+#                                  deploy lane의 store_prepare/store_submit은 필수입니다)
+#   DEPLOY_MODE                    위 표의 배포 모드 (deploy lane만)
+#   APP_VERSION, BUILD_NUMBER      앱 버전, 빌드 번호 (deploy lane만)
+#   SKIP_WAITING_FOR_BUILD_PROCESSING  "true"면 빌드 처리 완료를 기다리지 않음 (store_only만 적용)
+#
+# 참고
+# - store_prepare/store_submit은 App Store 버전에 빌드를 연결해야 하므로 빌드 처리가 끝날 때까지
+#   기다립니다 (SKIP_WAITING_FOR_BUILD_PROCESSING을 무시).
+# - 스크린샷은 올리지 않습니다. 메타데이터는 ios/fastlane/metadata/ 아래에 파일이 있을 때만 올립니다.
+#   심사 제출 시 "What's New" 등 필수 항목은 이 폴더나 App Store Connect에서 미리 채워 두세요.
+# - store_submit에서 수출 규정 오류가 나면 Info.plist에 ITSAppUsesNonExemptEncryption을 지정하거나
+#   upload_to_app_store에 submission_information을 추가하세요.
+# - store_submit은 심사 승인 후 자동 출시하지 않습니다 (automatic_release: false).
+
+default_platform(:ios)
+
+def require_env(name)
+  value = ENV[name].to_s.strip
+  UI.user_error!("#{name} 환경변수가 비어 있습니다. 워크플로우에서 값을 전달하는지 확인하세요.") if value.empty?
+  value
+end
+
+def load_api_key
+  app_store_connect_api_key(
+    key_id: require_env("APP_STORE_CONNECT_API_KEY_ID"),
+    issuer_id: require_env("APP_STORE_CONNECT_ISSUER_ID"),
+    key_filepath: require_env("API_KEY_PATH")
+  )
+end
+
+# APP_IDENTIFIER가 있을 때만 옵션에 포함해, 없으면 fastlane 기본 추론에 맡깁니다.
+def app_identifier_option
+  app_identifier = ENV["APP_IDENTIFIER"].to_s.strip
+  app_identifier.empty? ? {} : { app_identifier: app_identifier }
+end
+
+def upload_ipa_to_testflight(api_key, skip_waiting_for_build_processing)
+  options = {
+    api_key: api_key,
+    ipa: require_env("IPA_PATH"),
+    skip_waiting_for_build_processing: skip_waiting_for_build_processing
+  }
+  release_notes = ENV["RELEASE_NOTES"].to_s.strip
+  options[:changelog] = release_notes unless release_notes.empty?
+  upload_to_testflight(**options, **app_identifier_option)
+end
+
+platform :ios do
+  desc "IPA를 TestFlight에 업로드합니다 (테스트 빌드용)"
+  lane :upload_testflight do
+    upload_ipa_to_testflight(load_api_key, false)
+  end
+
+  desc "IPA를 업로드하고 DEPLOY_MODE에 따라 TestFlight / 심사 준비 / 심사 제출까지 진행합니다"
+  lane :deploy do
+    api_key = load_api_key
+    deploy_mode = ENV["DEPLOY_MODE"].to_s.strip
+
+    case deploy_mode
+    when "store_prepare", "store_submit"
+      UI.message("DEPLOY_MODE=#{deploy_mode}: 빌드 처리 완료까지 기다린 뒤 App Store 버전을 준비합니다.")
+      upload_ipa_to_testflight(api_key, false)
+
+      upload_to_app_store(
+        api_key: api_key,
+        app_identifier: require_env("APP_IDENTIFIER"),
+        app_version: require_env("APP_VERSION"),
+        build_number: require_env("BUILD_NUMBER"),
+        skip_binary_upload: true,
+        skip_screenshots: true,
+        skip_metadata: Dir.glob("metadata/*").empty?,
+        submit_for_review: deploy_mode == "store_submit",
+        automatic_release: false,
+        force: true,
+        precheck_include_in_app_purchases: false
+      )
+    when "store_only"
+      upload_ipa_to_testflight(api_key, ENV["SKIP_WAITING_FOR_BUILD_PROCESSING"].to_s.strip.downcase == "true")
+    else
+      UI.important("알 수 없는 DEPLOY_MODE '#{deploy_mode}' 입니다. store_only로 처리합니다.") unless deploy_mode.empty?
+      upload_ipa_to_testflight(api_key, ENV["SKIP_WAITING_FOR_BUILD_PROCESSING"].to_s.strip.downcase == "true")
+    end
+  end
+end