project-auto-wizard 0.12.2 → 0.13.1

package/README.ja.md

@@ -0,0 +1,165 @@
+<div align="center">
+
+[English](README.md) · [한국어](README.ko.md) · [简体中文](README.zh-CN.md) · **日本語**
+
+# project-auto-wizard
+
+**コマンド 1 つで、バージョン管理、CHANGELOG、GitHub Release、CI/CD をリポジトリに導入します。**
+
+インストールされるのは、すべてあなた自身のリポジトリ内の通常の GitHub Actions です。API キーもホスティングサービスも不要です。
+
+[ドキュメント](https://twin-fang.github.io/project-auto-wizard/ja/) · [クイックスタート](#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 ごとに、同じ手順が 1 つのワークフローで実行されます。
+
+リリースノートはデフォルトでルールベースです。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 を含む | 含む（プロジェクトタイプ別） | なし | なし | なし |
+| モノレポ | タイプ別のパス、共通の 1 つのバージョン | パッケージごとのバージョン | コミュニティプラグイン | パッケージごとのバージョン |
+
+他のツールのほうが優れている点:
+
+- **release-please** は成熟していて広く使われており、多くのエコシステムのバージョンファイルを更新でき、モノレポで独立したバージョンのパッケージも扱えます。
+- **semantic-release** は手作業なしで npm などのレジストリに公開でき、プラグインのエコシステムが大きいです。
+- **changesets** は、多数のパッケージを公開する JavaScript のモノレポに最適で、変更内容をコミットから導出せず人が書きます。
+
+## 使うべきとき、使わないとき
+
+次の場合に使います:
+
+- リポジトリを新しく始め、初日からリリースが動く状態にしたい
+- チームが `develop` を `main` にマージしていて、ノートと CHANGELOG 付きのリリース PR がほしい
+- Spring、Flutter、React、Next.js、Python、Go のプロジェクトで、CI/CD とリリース自動化を 1 回の設定で導入したい
+- 1 つのリポジトリに複数のスタック（例: Spring のバックエンドと React のフロントエンド）があり、バージョンを共有している
+
+次の場合は使いません:
+
+- 単一パッケージがすでに release-please や semantic-release で問題なくリリースできている
+- リリース自体がパッケージレジストリへの公開を伴う必要がある（このリポジトリが npm 向けにしているように、Release イベントで動く独自のワークフローを追加してください。`GITHUB_TOKEN` で作成したリリースは他のワークフローを起動しないため、`WORKFLOW_PAT` が必要です）
+- パッケージごとに独立したバージョンが必要
+- リポジトリが 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` / フォールバック | リリース自動化のみ |
+
+1 つのリポジトリに複数のタイプを置けます（`--type spring,react`）。モノレポのサブフォルダーは `--paths "flutter=app,react=client"` で指定します。
+
+<a id="post-install"></a>
+
+## インストール後に確認すること
+
+| 項目 | すること |
+|---|---|
+| Workflow permissions | インストールされるワークフローは、必要な権限を自分で宣言します。自分のワークフローがデフォルト値に依存している場合のみ、Settings → Actions → General → Workflow permissions を **Read and write permissions** に設定してください |
+| Merge commit | リリース PR が automerge できるよう、merge commit を許可してください |
+| `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/ja/) にあり、英語と韓国語で読めます。中国語（簡体字）と日本語はトップページとクイックスタートのみで、それ以外のページは英語で表示されます。内容は次のとおりです:
+
+- すべての 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/README.ko.md

@@ -0,0 +1,165 @@
+<div align="center">
+
+[English](README.md) · **한국어** · [简体中文](README.zh-CN.md) · [日本語](README.ja.md)
+
+# project-auto-wizard
+
+**명령 한 번으로 버전 관리, CHANGELOG, GitHub Release, CI/CD를 레포에 설치합니다.**
+
+설치되는 것은 전부 내 레포 안의 일반 GitHub Actions입니다. API 키도, 외부 서비스도 필요 없습니다.
+
+[문서](https://twin-fang.github.io/project-auto-wizard/ko/) · [빠른 시작](#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 요약 댓글, 새 이슈의 브랜치명 제안 |
+| `.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 포함 | 포함, 프로젝트 타입별 | 없음 | 없음 | 없음 |
+| 모노레포 | 타입별 경로, 하나의 공유 버전 | 패키지별 버전 | 커뮤니티 플러그인 | 패키지별 버전 |
+
+다른 도구가 더 나은 점:
+
+- **release-please**는 성숙했고 널리 쓰이며, 여러 생태계의 버전 파일을 갱신하고 모노레포에서 독립 버전 패키지를 다룹니다.
+- **semantic-release**는 수동 단계 없이 npm 등 레지스트리에 배포하고 플러그인 생태계가 큽니다.
+- **changesets**는 여러 패키지를 배포하는 JavaScript 모노레포에 가장 잘 맞고, 변경 내역을 커밋에서 뽑지 않고 사람이 직접 씁니다.
+
+## 언제 쓰고, 언제 쓰지 말아야 하나
+
+이런 경우에 씁니다:
+
+- 새 레포를 시작하며 첫날부터 릴리스가 동작하게 하고 싶을 때
+- 팀이 `develop`을 `main`에 병합하고, 노트와 CHANGELOG가 포함된 릴리스 PR을 원할 때
+- Spring, Flutter, React, Next.js, Python, Go 프로젝트에서 CI/CD와 릴리스 자동화를 한 번에 설정하고 싶을 때
+- 한 레포에 여러 스택(예: Spring 백엔드와 React 프론트엔드)이 있고 버전을 공유할 때
+
+이런 경우에는 쓰지 않습니다:
+
+- 패키지 하나가 이미 release-please나 semantic-release로 잘 릴리스되고 있을 때
+- 릴리스 자체가 패키지 레지스트리에 배포까지 해야 할 때 (이 레포가 npm에 배포하듯 Release 이벤트에 직접 워크플로우를 추가하세요. 이때 `WORKFLOW_PAT`이 필요합니다. `GITHUB_TOKEN`으로 만든 릴리스는 다른 워크플로우를 트리거하지 않기 때문입니다)
+- 패키지마다 독립된 버전이 필요할 때
+- 레포가 GitHub에 있지 않을 때
+
+## 지원 프로젝트 타입
+
+| 타입 | 감지 기준 | 릴리스 자동화에 더해 설치되는 것 |
+|---|---|---|
+| `spring` | `build.gradle`, `build.gradle.kts`, `pom.xml` | CI, 서버 배포 (단일 서버 / Nginx·Traefik 무중단), PR 프리뷰 |
+| `flutter` | `pubspec.yaml` | CI, Android (Firebase, Play Store, self-hosted, 테스트 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` / fallback | 릴리스 자동화만 |
+
+한 레포에 여러 타입을 둘 수 있고(`--type spring,react`), 모노레포 하위 폴더는 `--paths "flutter=app,react=client"`로 지정합니다.
+
+<a id="post-install"></a>
+
+## 설치 후 확인할 것
+
+| 항목 | 할 일 |
+|---|---|
+| Workflow permissions | 설치된 워크플로우는 필요한 권한을 각자 선언합니다. 직접 만든 워크플로우가 기본값에 의존할 때만 Settings → Actions → General → Workflow permissions를 **Read and write permissions**로 바꾸세요 |
+| Merge commit | 릴리스 PR이 automerge되려면 merge commit을 허용하세요 |
+| `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/ko/project-types/flutter/)에 있습니다.
+
+## 문서
+
+전체 문서는 [twin-fang.github.io/project-auto-wizard](https://twin-fang.github.io/project-auto-wizard/ko/)에 영어와 한국어로 있습니다. 중국어(간체)와 일본어는 첫 화면과 빠른 시작을 다루며, 나머지 페이지는 영어로 표시됩니다. 다음 내용을 다룹니다:
+
+- 모든 CLI 옵션, `--mode status`, `--mode doctor`, `--dry-run`, `--mode uninstall`
+- Flutter 스토어 배포, 배포 모드, 필요한 secret, `ExportOptions.plist`
+- 릴리스 노트 엔진 체인과 Copilot 과금
+- 타입별 워크플로우 상세, 실행 로그, 설계 원칙, 아키텍처
+
+## 기여하기
+
+이슈와 풀 리퀘스트를 환영합니다. `develop`에서 브랜치를 만들고 `develop`을 대상으로 PR을 여세요. 설정과 테스트(`npm test`)는 [CONTRIBUTING.md](CONTRIBUTING.md)를 참고하세요. 이 레포는 마법사가 설치하는 워크플로우로 스스로 릴리스됩니다.
+
+## 라이선스
+
+[MIT](LICENSE)