project-auto-wizard 0.12.2 → 0.13.0

package/README.zh-CN.md

@@ -0,0 +1,165 @@
+<div align="center">
+
+[English](README.md) · [한국어](README.ko.md) · **简体中文** · [日本語](README.ja.md)
+
+# project-auto-wizard
+
+**一条命令，为你的仓库配置版本管理、CHANGELOG、GitHub Release 和 CI/CD。**
+
+它安装的全部内容都是你自己仓库里的普通 GitHub Actions。不需要 API 密钥，也没有托管服务。
+
+[文档](https://twin-fang.github.io/project-auto-wizard/zh-cn/) · [快速开始](#quickstart) · [变更日志](CHANGELOG.md)
+
+[![CI](https://github.com/Twin-Fang/project-auto-wizard/actions/workflows/CI.yaml/badge.svg)](https://github.com/Twin-Fang/project-auto-wizard/actions/workflows/CI.yaml)
+[![npm version](https://img.shields.io/npm/v/project-auto-wizard)](https://www.npmjs.com/package/project-auto-wizard)
+[![npm downloads](https://img.shields.io/npm/dm/project-auto-wizard)](https://www.npmjs.com/package/project-auto-wizard)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D20.12-brightgreen)](package.json)
+
+<img src="https://raw.githubusercontent.com/Twin-Fang/project-auto-wizard/main/assets/demo/install.gif" alt="使用向导为 Spring 项目安装发布自动化" width="800">
+
+</div>
+
+## 最新版本
+
+最新版本和完整的变更记录见 [CHANGELOG.md](CHANGELOG.md)。
+
+## 为什么做这个
+
+每个新项目在写第一个功能之前，都要先做同样的杂事：决定版本怎么递增，维护 CHANGELOG，撰写发布说明，给发布打标签，再把上一个项目的 CI/CD 工作流复制过来修修改改。这要花几个小时，而且每个仓库最后都会略有不同。
+
+project-auto-wizard 用几个提问一次性完成这些配置。之后只要合并发布 PR，就能完成一次发布。
+
+<a id="quickstart"></a>
+
+## 快速开始
+
+在仓库根目录运行（需要 Node.js 20.12 或更高版本）：
+
+```bash
+npx project-auto-wizard
+```
+
+它会检测项目类型，询问几个问题（分支策略、部署方式、是否使用 Copilot 生成摘要），然后写入文件。在 CI 或脚本中，可以用非交互方式运行：
+
+```bash
+npx project-auto-wizard --mode full --force --type spring,react
+npx project-auto-wizard --mode full --force --type node --dry-run   # preview only, writes nothing
+```
+
+提交生成的文件并 push。`npx project-auto-wizard --mode doctor` 会检查工作流所依赖的仓库设置。
+
+## 安装内容
+
+| 安装项 | 用途 |
+|---|---|
+| `.github/workflows/PROJECT-COMMON-*.yaml` | 发布自动化：版本递增、发布 PR 说明、CHANGELOG、标签和 GitHub Release、README 版本行、PR 摘要评论、为新 issue 建议分支名 |
+| `.github/workflows/PROJECT-<TYPE>-*` | 对应技术栈（Spring、Flutter、React、Next.js、Python、Go）的 CI/CD |
+| `.github/scripts/*.py` | 工作流背后的逻辑，仅使用标准库的 Python |
+| `version.yml` | 版本、项目类型、路径、分支和选项的唯一来源 |
+| `README.md` 版本部分 | 每次发布后自动更新 |
+
+这些文件归你所有，可以随意阅读和修改。再次运行向导会更新它们：如果上游版本没有变化，你修改过的文件会被保留；如果双方都有变化，向导会询问是保留你的文件、备份后替换，还是把新版本放在旁边。
+
+默认的 `pr-flow` 策略下，一次发布的流程如下：
+
+```
+feature PRs ──▶ develop ──▶ release PR (develop → main)
+                              │  next version from commit types: feat → minor, ! → major, else patch
+                              │  release notes written, CHANGELOG.md / CHANGELOG.json updated
+                              ▼
+                           automerge ──▶ tag vX.Y.Z + GitHub Release ──▶ README version updated
+```
+
+使用 `trunk-based`（发布分支 = 开发分支）时，每次 push 到发布分支，都会在一个工作流中执行相同的步骤。
+
+发布说明默认基于规则生成。你可以开启 GitHub Copilot（消耗你的 Copilot AI Credits），或者指向任何兼容 OpenAI 的 API。如果模型不可用或调用失败，会回退到规则生成，因此发布不会被摘要步骤卡住。
+
+## 使用前后对比
+
+| | 不使用 | 使用 project-auto-wizard |
+|---|---|---|
+| 初始配置 | 从旧仓库复制工作流并修改 | 运行 `npx project-auto-wizard`，回答几个问题 |
+| 下一个版本号 | 手动决定并输入 | 根据发布 PR 中的提交类型得出 |
+| CHANGELOG | 手写，经常被跳过 | 发布 PR 合并时更新 |
+| 标签和 Release | 手动创建 | 合并后自动创建 |
+| 各技术栈的 CI/CD | 每个项目单独编写 | 按检测到的类型安装 |
+| AI 摘要 | 需要 API 密钥和自定义脚本 | 可选；基于规则的方式无需密钥 |
+
+## 与其他工具的比较
+
+| | project-auto-wizard | release-please | semantic-release | changesets |
+|---|---|---|---|---|
+| 接入方式 | 安装可编辑的工作流文件 | GitHub Action + 配置 | 在 CI 中运行的 npm 包 + 插件 | CLI + GitHub Action |
+| 版本决定依据 | 提交类型（非 Conventional 的提交 → patch） | Conventional Commits | Conventional Commits（可配置） | 开发者编写的 changeset 文件 |
+| 发布 PR | 有（或 trunk-based） | 有 | 没有，push 时直接发布 | 有（"Version Packages"） |
+| 发布到 npm / PyPI | 否 | 否 | 是，通过插件 | 是（npm） |
+| 包含各技术栈 CI/CD | 是，按项目类型 | 否 | 否 | 否 |
+| Monorepo | 按类型划分路径，共用一个版本 | 各包独立版本 | 社区插件 | 各包独立版本 |
+
+其他工具做得更好的地方：
+
+- **release-please** 成熟且被广泛使用，能更新多种生态的版本文件，并支持 monorepo 中独立版本的包。
+- **semantic-release** 无需手动步骤即可发布到 npm 等仓库，并且拥有庞大的插件生态。
+- **changesets** 最适合发布多个包的 JavaScript monorepo，变更条目由人来写，而不是从提交中推导。
+
+## 何时使用，何时不用
+
+适合使用的情况：
+
+- 你刚开始一个仓库，希望从第一天起就能发布
+- 你的团队把 `develop` 合并到 `main`，并希望有带说明和 CHANGELOG 的发布 PR
+- 你有 Spring、Flutter、React、Next.js、Python 或 Go 项目，想一次配置好 CI/CD 和发布自动化
+- 一个仓库里有多个技术栈（例如 Spring 后端和 React 前端），并共用一个版本
+
+不适合的情况：
+
+- 单个包已经用 release-please 或 semantic-release 发布得很好
+- 发布本身必须推送到包仓库（请在 Release 事件上添加你自己的工作流，就像本仓库发布 npm 那样；这需要 `WORKFLOW_PAT`，因为用 `GITHUB_TOKEN` 创建的 Release 不会触发其他工作流）
+- 你的包需要独立的版本号
+- 仓库不在 GitHub 上
+
+## 支持的项目类型
+
+| 类型 | 检测依据 | 在发布自动化之外额外安装 |
+|---|---|---|
+| `spring` | `build.gradle`、`build.gradle.kts`、`pom.xml` | CI、服务器部署（单台服务器 / Nginx 或 Traefik 零停机）、PR 预览 |
+| `flutter` | `pubspec.yaml` | CI、Android（Firebase、Play Store、自托管、测试 APK）、iOS TestFlight |
+| `react`、`next` | `package.json` 的 dependencies | CI、CI + CD |
+| `python` | `pyproject.toml`、`setup.py`、`requirements.txt` | CI、PR 预览、服务器部署 |
+| `go` | `go.mod` | CI、PR 预览、服务器部署 |
+| `node`、`react-native`、`react-native-expo`、`basic` | `package.json` / 兜底 | 仅发布自动化 |
+
+一个仓库里可以有多种类型（`--type spring,react`），monorepo 的子目录用 `--paths "flutter=app,react=client"` 指定。
+
+<a id="post-install"></a>
+
+## 安装之后
+
+| 事项 | 需要做什么 |
+|---|---|
+| Workflow permissions | 已安装的工作流会自行声明所需权限。只有当你自己的工作流依赖默认值时，才需要把 Settings → Actions → General → Workflow permissions 设为 **Read and write permissions** |
+| Merge commit | 允许 merge commit，发布 PR 才能 automerge |
+| `WORKFLOW_PAT`（可选） | 没有它时，`GITHUB_TOKEN` 回退方案会在约 20 秒后完成发布，包括发布分支上的部署工作流。只有当你自己添加了由 Release 事件触发的工作流时才需要。请用 bot 或 machine 账号签发（scopes：`repo`、`workflow`） |
+| Copilot 摘要（可选） | 默认关闭。会消耗 Copilot AI Credits；组织需要允许向组织计费的 Copilot CLI |
+
+<a id="flutter-store"></a>
+
+Flutter 商店部署（Play Store、Firebase、TestFlight）的设置见[文档站点的 Flutter 页面](https://twin-fang.github.io/project-auto-wizard/project-types/flutter/)。
+
+## 文档
+
+完整文档位于 [twin-fang.github.io/project-auto-wizard](https://twin-fang.github.io/project-auto-wizard/zh-cn/)，提供英文和韩文版本。简体中文和日文目前涵盖首页和快速开始，其余页面显示英文。内容包括：
+
+- 所有 CLI 选项、`--mode status`、`--mode doctor`、`--dry-run` 和 `--mode uninstall`
+- Flutter 商店部署、部署模式、所需的 secret 以及 `ExportOptions.plist`
+- 发布说明引擎链和 Copilot 计费
+- 各类型的工作流详情、运行日志、设计原则和架构
+
+## 参与贡献
+
+欢迎提交 issue 和 pull request。请从 `develop` 创建分支，并向 `develop` 发起 PR；环境搭建和测试（`npm test`）见 [CONTRIBUTING.md](CONTRIBUTING.md)。本仓库使用它自己安装的工作流来发布自身。
+
+## 许可证
+
+[MIT](LICENSE)

package/bin/project-auto-wizard.js

@@ -14,6 +14,5 @@ const indexPath = join(here, "..", "src", "index.js");
 const { run } = await import(pathToFileURL(indexPath).href);
 
 const code = await run(process.argv.slice(2), { cwd: process.cwd() });
-// process.exit() 금지 — fetch(undici) keep-alive 소켓·타이머와 경합해
-// Windows libuv assertion(src/win/async.c)으로 비정상 종료(127)한다. 실측 확인.
+// process.exit() 대신 exitCode — 파이프로 연결된 stdout/stderr가 끝까지 flush된 뒤 종료되게 한다.
 process.exitCode = code;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-auto-wizard",
-  "version": "0.12.2",
+  "version": "0.13.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",
@@ -13,12 +13,16 @@
   "files": [
     "bin/",
     "src/",
-    "payload/"
+    "payload/",
+    "!**/__pycache__/",
+    "!**/*.pyc"
   ],
   "scripts": {
     "test": "npm run test:node && npm run test:py",
     "test:node": "node --test --test-concurrency=1",
-    "test:py": "node scripts/run-py-tests.mjs"
+    "test:py": "node scripts/run-py-tests.mjs",
+    "sync:dogfood": "node scripts/sync-dogfood.mjs",
+    "sync:dogfood:check": "node scripts/sync-dogfood.mjs --check"
   },
   "repository": {
     "type": "git",

package/payload/config/breaking-changes.json

@@ -2,23 +2,47 @@
   "0.10.1": [
     {
       "severity": "warning",
+      "types": ["flutter"],
       "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",
+      "types": ["flutter"],
       "title": "Flutter 환경변수 기본 방식이 dart-define으로 변경",
       "message": "신규 설치의 기본값이 dart-define(--dart-define-from-file)으로 바뀝니다. 기존 설치는 version.yml에 저장값이 없으면 dotenv(.env 생성)를 유지하며, 바꾸려면 마법사 '수정하기 > 환경변수 방식' 또는 --flutter-env-mode를 쓰세요."
     },
     {
       "severity": "warning",
+      "types": ["flutter"],
       "title": "Flutter 워크플로우가 FLUTTER_PROJECT_DIR 기준으로 동작",
       "message": "FIREBASE·SELFHOSTED·CI·TEST-APK·IOS-TEST-TESTFLIGHT도 PLAYSTORE처럼 Flutter 루트(FLUTTER_PROJECT_DIR)에서 동작합니다. Flutter가 하위 폴더에 있는 모노레포는 --paths flutter=<경로>로 지정하세요."
     },
     {
       "severity": "warning",
+      "types": ["flutter", "go", "next", "python", "react", "spring"],
       "title": "모노레포 CI required check는 ci-gate 하나만 등록",
       "message": "CI 워크플로우(Flutter·Go·Next·Python·React·Spring CI)는 항상 실행되고 변경이 없으면 job을 건너뜁니다. required check로 쓰려면 개별 job이 아닌 CI Gate(ci-gate) 하나만 등록하세요."
     }
+  ],
+  "0.12.0": [
+    {
+      "severity": "warning",
+      "title": "AI 요약이 GitHub Copilot opt-in으로 바뀌어 기본으로 꺼짐",
+      "message": "GitHub Models 종료로 AI 요약 엔진이 GitHub Copilot CLI로 바뀌었고, AI Credits를 소비하므로 기본값이 꺼짐(copilot_ai: false)입니다. 업데이트 후 릴리스 노트·PR 요약은 규칙 기반으로 만들어집니다. 계속 쓰려면 --copilot으로 다시 설치하거나 version.yml의 copilot_ai를 true로 바꾼 뒤 다시 실행하세요."
+    }
+  ],
+  "0.12.1": [
+    {
+      "severity": "warning",
+      "types": ["spring"],
+      "title": "Spring nexus·GitHub Packages publish 옵션 제거",
+      "message": "PROJECT-SPRING-NEXUS-PUBLISH.yml·PROJECT-SPRING-GITHUB-PACKAGES-PUBLISH.yml을 더 이상 설치하지 않고, PROJECT-SPRING-NEXUS-CI.yml은 PROJECT-SPRING-CI.yml로 바뀌어 항상 설치됩니다. 업데이트하면 손대지 않은 이전 파일은 삭제되고 수정한 파일은 .bak으로 옮겨집니다. 계속 배포하려면 .bak을 직접 관리하는 워크플로우로 옮기세요."
+    },
+    {
+      "severity": "warning",
+      "title": "Secret 서버 백업 워크플로우(secret_backup 옵션) 제거",
+      "message": "PROJECT-COMMON-SECRET-FILE-UPLOAD.yaml을 더 이상 설치하지 않습니다. 설치해 두었다면 업데이트 때 손대지 않은 파일은 삭제되고 수정한 파일은 .bak으로 옮겨집니다. 계속 쓰려면 .bak을 직접 관리하는 워크플로우로 옮기세요."
+    }
   ]
 }

package/payload/config/wizard-prompts.yml

@@ -50,6 +50,51 @@ SSH_AUTH_METHOD:
   help: "배포 서버 접속 방식입니다. 둘 중 하나를 그대로 입력하세요."
   example: "password 또는 key"
 
+SSH_PORT:
+  label: "SSH 포트"
+  help: "배포 서버에서 SSH가 열려 있는 포트입니다 (일반 서버는 보통 22, NAS 등은 따로 정한 포트)."
+  example: "22"
+
+BLUE_PORT:
+  label: "무중단 배포 Blue 포트"
+  help: "Blue/Green으로 번갈아 뜨는 컨테이너 중 Blue 쪽 호스트 포트입니다. 다른 서비스·Green 포트와 겹치지 않게 정하세요."
+  example: "8080"
+
+GREEN_PORT:
+  label: "무중단 배포 Green 포트"
+  help: "Blue/Green으로 번갈아 뜨는 컨테이너 중 Green 쪽 호스트 포트입니다. Blue 포트와 달라야 합니다."
+  example: "8081"
+
+NGINX_RP_CONF:
+  label: "Nginx 리버스 프록시 설정 파일 경로"
+  help: "배포 때 proxy_pass 포트를 Blue/Green으로 바꿔 쓰는 서버의 Nginx 설정 파일입니다. 경로가 틀리면 무중단 전환이 동작하지 않습니다."
+  example: "/etc/nginx/sites-enabled/my-service.conf"
+
+NGINX_BACKUP_DIR:
+  label: "Nginx 설정 백업 폴더"
+  help: "설정 파일을 바꾸기 전에 백업을 남길 서버의 폴더입니다."
+  example: "/volume1/projects/nginx/backups"
+
+JAR_PATH:
+  label: "빌드 산출물(JAR) 경로"
+  help: "Gradle 빌드 후 PR 프리뷰 컨테이너에 넣을 JAR 파일 경로입니다 (프로젝트 루트 기준, 와일드카드 가능)."
+  example: "build/libs/*.jar"
+
+PREVIEW_DOMAIN_SUFFIX:
+  label: "PR 프리뷰 도메인 접미사"
+  help: "PR마다 뜨는 프리뷰 서버 주소의 뒷부분입니다. 이 도메인의 와일드카드 DNS가 서버(Traefik)를 가리켜야 합니다."
+  example: "pr.example.com"
+
+PROJECT_TARGET_DIR:
+  label: "PR 프리뷰 호스트 볼륨 경로"
+  help: "PR 프리뷰 컨테이너에 마운트할 서버의 데이터 디렉토리입니다. 비워 두면 마운트하지 않습니다."
+  example: "/volume1/projects/my-service"
+
+PROJECT_MNT_DIR:
+  label: "PR 프리뷰 컨테이너 마운트 경로"
+  help: "위 호스트 볼륨이 PR 프리뷰 컨테이너 안에서 보일 위치입니다."
+  example: "/mnt/my-service"
+
 ISSUE_HELPER_CREATE_BRANCH:
   label: "이슈 생성 시 브랜치 자동 생성"
   help: "이슈가 열리면 base 브랜치 기준으로 브랜치를 자동으로 만듭니다. 원치 않으면 기본값(아니오)을 그대로 두세요."