@asagiri-design/labels-config 0.2.2 → 0.3.1

package/docs/NPM_SETUP.md

@@ -0,0 +1,200 @@
+# npm Trusted Publishers (OIDC) セットアップガイド
+
+このプロジェクトは、npm の **Trusted Publishers (OIDC)** 方式を使用して自動的にパッケージを公開しています。
+従来の長期有効なトークンではなく、GitHub Actions が実行時に一時的な認証情報を取得する方式です。
+
+> **⚠️ 重要な注意事項**
+>
+> npm の Trusted Publisher 設定は **Web UI からのみ可能**です。
+> 現時点では npm CLI やターミナルから設定することはできません。
+> 以下の手順に従って、[npmjs.com](https://www.npmjs.com/) から設定してください。
+
+## 🔐 セキュリティ強化について
+
+### npm の新しいセキュリティポリシー（2024年〜）
+
+- **長期トークンの有効期限短縮**: 書き込み可能なトークンはデフォルト7日、最大90日に制限
+- **クラシックトークンの廃止**: 従来の広範な権限を持つトークンは段階的に廃止
+- **TOTP から WebAuthn/パスキーへの移行**: より強力な2要素認証への移行を推奨
+- **Trusted Publishers の推奨**: CI/CD での OIDC 認証方式を標準に
+
+### Trusted Publishers (OIDC) のメリット
+
+✅ **トークン管理不要**: 手動でのトークン生成・更新・ローテーションが不要
+✅ **セキュリティリスク最小化**: 長期有効なトークンが漏洩するリスクがゼロ
+✅ **自動 Provenance**: パッケージの出所証明が自動的に生成される
+✅ **最小権限の原則**: 各 CI/CD ジョブに必要最低限の権限のみ付与
+✅ **npm の推奨方式**: 今後の標準として推奨されている方式
+
+## 📋 必須：npm での Trusted Publisher 設定
+
+このリポジトリのワークフローが正常に動作するためには、npm 側で Trusted Publisher の設定が必要です。
+
+### ステップ 1: npm にログイン
+
+1. [npmjs.com](https://www.npmjs.com/) にアクセス
+2. あなたのアカウントでログイン
+
+### ステップ 2: パッケージの設定画面へ移動
+
+1. パッケージ `@boxpistols/labels-config` のページへ移動
+2. "Settings" タブをクリック
+
+### ステップ 3: Publishing Access の設定
+
+1. 左サイドバーから **"Publishing Access"** を選択
+2. **"Add Trusted Publisher"** または **"Configure OIDC"** をクリック
+
+### ステップ 4: GitHub Actions の情報を入力
+
+以下の情報を入力します：
+
+| 項目 | 値 |
+|------|-----|
+| **Provider** | GitHub |
+| **Organization / Repository owner** | `your-org` |
+| **Repository name** | `labels-config` |
+| **Workflow name** | （以下の3つを個別に追加） |
+
+**追加するワークフロー:**
+
+1. **自動リリース用**（main へのマージ時）
+   - Workflow: `auto-release.yml`
+   - Environment: （空欄のまま）
+   - Job: `auto-patch-release`
+
+2. **手動リリース用**
+   - Workflow: `manual-release.yml`
+   - Environment: （空欄のまま）
+   - Job: `manual-release`
+
+3. **GitHub Release トリガー用**
+   - Workflow: `publish.yml`
+   - Environment: （空欄のまま）
+   - Job: `publish`
+
+### ステップ 5: 設定の保存
+
+各ワークフローを追加後、設定を保存します。
+
+## 🚀 動作確認
+
+### main ブランチへのマージで自動公開
+
+```bash
+# feature ブランチで作業
+git checkout -b feature/new-feature
+# コードを変更
+git add .
+git commit -m "feat: add new feature"
+git push origin feature/new-feature
+
+# PR を作成してマージ
+# → main へのマージ後、自動的にパッチバージョンがリリースされ npm に公開される
+```
+
+### 手動でのバージョン指定リリース
+
+GitHub の Actions タブから "Manual Release" ワークフローを実行：
+
+1. リポジトリの **Actions** タブを開く
+2. **"Manual Release"** を選択
+3. **"Run workflow"** をクリック
+4. バージョンタイプを選択（patch / minor / major / prerelease）
+5. **"Run workflow"** を実行
+
+## 🔍 トラブルシューティング
+
+### エラー: "403 Forbidden" または "OIDC authentication failed"
+
+**原因**: npm で Trusted Publisher が正しく設定されていない
+
+**解決方法**:
+1. npm の Publishing Access 設定を再確認
+2. Organization、Repository、Workflow、Job 名が正確に一致しているか確認
+3. 設定後、数分待ってから再試行
+
+### エラー: "Provenance generation failed"
+
+**原因**: ワークフローの permissions 設定が不足している
+
+**解決方法**:
+- ワークフローファイルに以下が含まれているか確認：
+  ```yaml
+  permissions:
+    contents: write  # または read（ジョブに応じて）
+    id-token: write  # OIDC に必須
+  ```
+
+### リリースがスキップされる
+
+**原因**: コミットメッセージに `[skip ci]` または `[no release]` が含まれている
+
+**解決方法**:
+- これらのキーワードを含まないコミットメッセージを使用
+- または、手動リリースワークフローを使用
+
+## 📚 参考リンク
+
+**プロジェクト内ドキュメント:**
+- [npm Publish 更新フローガイド](./RELEASE_FLOW.md) - リリース方法の詳細
+
+**外部リンク:**
+- [npm: Publishing packages with provenance via GitHub Actions](https://docs.npmjs.com/generating-provenance-statements)
+- [GitHub: Security hardening with OpenID Connect](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+- [npm Blog: Introducing npm package provenance](https://github.blog/2023-04-19-introducing-npm-package-provenance/)
+
+## 🔄 従来のトークン方式からの移行
+
+もし以前 `NPM_TOKEN` シークレットを使用していた場合：
+
+1. ✅ Trusted Publisher の設定を完了
+2. ✅ ワークフローが正常に動作することを確認
+3. ✅ GitHub リポジトリの Settings → Secrets から `NPM_TOKEN` を削除（もう不要です）
+4. ✅ `package.json` の `release:*` スクリプトは廃止されました。今後のリリースは GitHub Actions ワークフロー経由で行います。
+
+### 廃止されたローカルスクリプト
+
+以下のスクリプトは削除されました（GitHub Actions で自動化されているため）：
+
+```bash
+# 🚫 これらのコマンドはもう使用しません
+npm run release:patch  # → GitHub Actions の auto-release が自動実行
+npm run release:minor  # → GitHub Actions の manual-release で実行
+npm run release:major  # → GitHub Actions の manual-release で実行
+npm run release:beta   # → GitHub Actions の manual-release で実行
+```
+
+**新しいリリース方法：**
+- **自動**: main へマージすると自動的にパッチバージョンがリリース
+- **手動**: GitHub Actions UI から Manual Release ワークフローを実行
+
+## 💡 ベストプラクティス
+
+### コミットメッセージ
+
+自動リリースをスキップしたい場合は、コミットメッセージに `[skip ci]` または `[no release]` を含めます：
+
+```bash
+git commit -m "docs: update README [skip ci]"
+git commit -m "chore: update dependencies [no release]"
+```
+
+### バージョニング戦略
+
+- **patch**: バグ修正、小さな改善（main へのマージで自動）
+- **minor**: 新機能追加（手動リリース推奨）
+- **major**: 破壊的変更（手動リリース推奨）
+- **prerelease**: ベータ版リリース（手動リリース）
+
+### 2要素認証の強化
+
+npm アカウントのセキュリティ強化のため、WebAuthn/パスキーの使用を推奨：
+
+1. npm アカウント設定で 2FA を開く
+2. パスキー（YubiKey、Touch ID、Face ID など）を追加
+3. 従来の TOTP（Google Authenticator など）からの移行を検討
+
+---
+
+**設定完了後、このリポジトリは自動的に npm への公開が可能になります 🎉**

package/docs/QUICK_START.md

@@ -0,0 +1,457 @@
+# Quick Start - 3ステップで始めるラベル管理
+
+`@asagiri-design/labels-config` を使って、GitHubリポジトリのラベルを簡単に管理できます。
+
+---
+
+## 🚀 3ステップで完了
+
+### ステップ1: インストール（1回だけ）
+
+```bash
+npm install -g @asagiri-design/labels-config
+```
+
+### ステップ2: GitHub認証（1回だけ）
+
+```bash
+gh auth login
+```
+
+### ステップ3: ラベルを適用
+
+```bash
+# あなたのリポジトリにラベルを適用
+labels-config batch-sync --repos YourName/YourRepo --template prod-ja
+```
+
+**これだけ！** 🎉
+
+---
+
+## 📋 具体例
+
+### 例1: 自分のリポジトリ1つに適用
+
+```bash
+# Foo/Bar リポジトリに prod-ja テンプレートを適用
+labels-config batch-sync --repos Foo/Bar --template prod-ja
+```
+
+**実行結果:**
+```
+📋 Target repositories: 1
+
+✅ [1/1] Foo/Bar
+
+📊 Batch Sync Summary:
+✅ Successful: 1
+```
+
+---
+
+### 例2: 自分の全リポジトリに一括適用
+
+```bash
+# あなたの全リポジトリに適用
+labels-config batch-sync --user Foo --template prod-ja
+```
+
+---
+
+### 例3: 組織の全リポジトリに一括適用
+
+```bash
+# Foo組織の全リポジトリに適用
+labels-config batch-sync --org Foo --template prod-ja
+```
+
+---
+
+### 例4: 複数のリポジトリを指定
+
+```bash
+# 複数のリポジトリに一括適用
+labels-config batch-sync \
+  --repos Foo/Bar,Foo/Baz,Foo/Qux \
+  --template prod-ja
+```
+
+---
+
+## 🔍 ドライランで事前確認
+
+実際に変更する前に、何が変更されるか確認できます：
+
+```bash
+# ドライラン（変更を実行しない）
+labels-config batch-sync --repos Foo/Bar --template prod-ja --dry-run
+```
+
+**出力例:**
+```
+[DRY RUN] 📋 Target repositories: 1
+
+📊 Batch Sync Configuration
+Labels: 14
+Repositories: 1 specified
+Parallel: 3
+Mode: append
+
+✅ [1/1] Foo/Bar
+
+📊 Batch Sync Summary:
+✅ Successful: 1
+```
+
+問題なければ `--dry-run` を外して本番実行してください。
+
+---
+
+## 🎨 利用可能なテンプレート
+
+| テンプレート名 | 説明 | ラベル数 |
+|--------------|------|---------|
+| `minimal` | 基本的な3ラベル (bug, feature, documentation) | 3 |
+| `github` | GitHub標準ラベル | 9 |
+| `prod-ja` | 本番プロジェクト用（日本語） | 14 |
+| `prod-en` | 本番プロジェクト用（英語） | 14 |
+| `react` | React開発用 | 12 |
+| `vue` | Vue.js開発用 | 12 |
+| `frontend` | フロントエンド開発用 | 15 |
+| `agile` | アジャイル/スクラム用 | 18 |
+
+### テンプレートの内容を確認
+
+```bash
+# テンプレートからファイル生成
+labels-config init prod-ja --file labels.json
+
+# ファイルを確認
+cat labels.json
+```
+
+---
+
+## 🎯 よくある使い方
+
+### パターン1: 新しいリポジトリを作ったらすぐ実行
+
+```bash
+# 1. 新しいリポジトリを作成
+gh repo create Foo/NewProject --public
+
+# 2. ラベルを適用
+labels-config batch-sync --repos Foo/NewProject --template prod-ja
+```
+
+---
+
+### パターン2: 既存リポジトリのラベルを統一
+
+```bash
+# 組織の全リポジトリのラベルを統一
+labels-config batch-sync --org Foo --template prod-ja
+```
+
+---
+
+### パターン3: TypeScriptプロジェクトだけに適用
+
+```bash
+# TypeScriptプロジェクトのみフィルタリング
+labels-config batch-sync \
+  --org Foo \
+  --template react \
+  --filter-lang TypeScript
+```
+
+---
+
+### パターン4: 公開リポジトリのみに適用
+
+```bash
+# 公開リポジトリのみに適用
+labels-config batch-sync \
+  --user Foo \
+  --template prod-ja \
+  --filter-vis public
+```
+
+---
+
+## 🔄 2つのモード
+
+### Appendモード（デフォルト）
+
+既存のラベルを保持したまま、新しいラベルを追加・更新します。
+
+```bash
+labels-config batch-sync --repos Foo/Bar --template prod-ja
+```
+
+**動作:**
+- ✅ 新しいラベルを追加
+- ✅ 既存のラベルを更新
+- ✅ 設定にないラベルは保持
+
+---
+
+### Replaceモード
+
+既存のラベルを完全に置き換えます。
+
+```bash
+labels-config batch-sync --repos Foo/Bar --template prod-ja --delete-extra
+```
+
+**動作:**
+- ✅ 新しいラベルを追加
+- ✅ 既存のラベルを更新
+- ❌ 設定にないラベルを削除
+
+---
+
+## ⚙️ オプション一覧
+
+### ターゲット指定（いずれか必須）
+
+| オプション | 説明 | 例 |
+|-----------|------|-----|
+| `--repos <list>` | リポジトリリスト（カンマ区切り） | `--repos Foo/Bar,Foo/Baz` |
+| `--user <name>` | ユーザーの全リポジトリ | `--user Foo` |
+| `--org <name>` | 組織の全リポジトリ | `--org Foo` |
+
+### ラベル指定（いずれか必須）
+
+| オプション | 説明 | 例 |
+|-----------|------|-----|
+| `--template <name>` | テンプレート名 | `--template prod-ja` |
+| `--file <path>` | カスタムラベルファイル | `--file ./labels.json` |
+
+### フィルタリング（オプション）
+
+| オプション | 説明 | 例 |
+|-----------|------|-----|
+| `--filter-lang <lang>` | プログラミング言語でフィルタ | `--filter-lang TypeScript` |
+| `--filter-vis <vis>` | 可視性でフィルタ (public/private/all) | `--filter-vis public` |
+
+### その他（オプション）
+
+| オプション | 説明 | 例 |
+|-----------|------|-----|
+| `--dry-run` | ドライラン（実行しない） | `--dry-run` |
+| `--delete-extra` | Replaceモード（設定外を削除） | `--delete-extra` |
+| `--parallel <num>` | 並列実行数（デフォルト: 3） | `--parallel 5` |
+
+---
+
+## 🔐 必要な権限
+
+### 1. GitHub CLI の認証
+
+```bash
+gh auth login
+```
+
+以下のスコープが必要です：
+- `repo` (リポジトリへのアクセス)
+
+### 2. リポジトリへのアクセス権限
+
+対象リポジトリへの **管理者権限** または **書き込み権限** が必要です。
+
+**確認方法:**
+```bash
+# リポジトリのアクセス権限を確認
+gh repo view Foo/Bar --json permissions
+```
+
+---
+
+## 📚 次のステップ
+
+### カスタムラベルを作成
+
+```bash
+# 1. テンプレートからファイル生成
+labels-config init prod-ja --file my-labels.json
+
+# 2. ファイルを編集
+vim my-labels.json
+
+# 3. 適用
+labels-config batch-sync --repos Foo/Bar --file my-labels.json
+```
+
+### 複雑な設定を使う
+
+複数の条件で異なるテンプレートを適用する場合は、設定ファイルを使用：
+
+```bash
+# 設定ファイルを作成
+cat > batch-config.json << EOF
+{
+  "version": "1.0.0",
+  "targets": [
+    {
+      "organization": "Foo",
+      "filter": { "language": "TypeScript" },
+      "template": "react"
+    },
+    {
+      "repositories": ["Foo/special-project"],
+      "file": "./special-labels.json"
+    }
+  ]
+}
+EOF
+
+# 設定ファイルで実行
+labels-config batch-config batch-config.json
+```
+
+詳細は [BATCH_SYNC.md](./BATCH_SYNC.md) を参照してください。
+
+---
+
+## ❓ トラブルシューティング
+
+### エラー: `command not found: labels-config`
+
+**原因:** パッケージがインストールされていない
+
+**解決方法:**
+```bash
+npm install -g @asagiri-design/labels-config
+```
+
+---
+
+### エラー: `gh: command not found`
+
+**原因:** GitHub CLI がインストールされていない
+
+**解決方法:**
+```bash
+# macOS
+brew install gh
+
+# Windows
+winget install --id GitHub.cli
+
+# Linux
+# https://github.com/cli/cli#installation
+```
+
+---
+
+### エラー: `Permission denied`
+
+**原因:** リポジトリへのアクセス権限がない
+
+**解決方法:**
+1. リポジトリの設定で自分の権限を確認
+2. `gh auth status` で認証状態を確認
+3. `gh auth refresh` で認証を更新
+
+---
+
+### エラー: `API rate limit exceeded`
+
+**原因:** GitHub APIのレート制限に達した
+
+**解決方法:**
+```bash
+# 並列数を減らす
+labels-config batch-sync --user Foo --template prod-ja --parallel 1
+
+# または時間を置いて再実行
+```
+
+---
+
+## 🆘 ヘルプ
+
+```bash
+# ヘルプを表示
+labels-config help
+
+# コマンドの使い方を確認
+labels-config batch-sync --help
+```
+
+---
+
+## 📖 関連ドキュメント
+
+- [Getting Started](./GETTING_STARTED.md) - 詳細な使い方
+- [Batch Sync](./BATCH_SYNC.md) - バッチ同期の詳細
+- [API Documentation](./API.md) - プログラマティックな使い方
+- [GitHub Repository](https://github.com/your-org/labels-config) - ソースコード
+
+---
+
+## 💡 Tips
+
+### Tip 1: エイリアスを作成
+
+```bash
+# .bashrc または .zshrc に追加
+alias label-sync='labels-config batch-sync'
+
+# 使用例
+label-sync --repos Foo/Bar --template prod-ja
+```
+
+### Tip 2: プロジェクトごとの設定ファイル
+
+```bash
+# プロジェクトディレクトリに設定ファイルを作成
+cat > .labelrc.json << EOF
+{
+  "version": "1.0.0",
+  "targets": [
+    {
+      "repositories": ["$(gh repo view --json nameWithOwner -q .nameWithOwner)"],
+      "template": "prod-ja"
+    }
+  ]
+}
+EOF
+
+# いつでも簡単に実行
+labels-config batch-config .labelrc.json
+```
+
+### Tip 3: GitHub Actionsで自動化
+
+新しいリポジトリ作成時に自動でラベルを適用：
+
+```yaml
+# .github/workflows/auto-label.yml
+name: Auto Apply Labels
+on:
+  repository_dispatch:
+    types: [repository-created]
+
+jobs:
+  apply-labels:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@v4
+      - run: npm install -g @asagiri-design/labels-config
+      - run: labels-config batch-sync \
+             --repos ${{ github.repository }} \
+             --template prod-ja
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+---
+
+**さあ、始めましょう！** 🚀
+
+```bash
+labels-config batch-sync --repos YourName/YourRepo --template prod-ja
+```