@aramassa/ai-rules 0.5.2 → 0.6.0

package/artifact/instructions/rules/package-publish/npm.md

@@ -0,0 +1,666 @@
+---
+type: development-rules
+category: package-publish
+framework: npm
+language:
+  - typescript
+  - nodejs
+applyTo: ".github/workflows/**/*.yml"
+---
+
+# npm Package Publishing Workflow 実装ルール
+
+このドキュメントは、npmパッケージ（GitHub PackagesとnpmjsへのDual Registry公開）のための
+GitHub Actions ワークフローの標準実装ルールを定義します。
+
+## 目的
+
+- 複数リポジトリで一貫したpublishワークフローを実現
+- バージョン管理、ビルド、公開プロセスの標準化
+- メンテナンス性と再利用性の向上
+
+## ワークフロー全体構造
+
+```yaml
+name: Publish package
+
+on:
+  workflow_dispatch:
+    inputs:
+      version_bump:
+        description: |-
+          Version bump type:
+          - `current`: Use current version (no version update)
+          - `patch`: Patch version update (e.g., 0.3.0 → 0.3.1)
+          - `minor`: Minor version update (e.g., 0.3.0 → 0.4.0)
+          - `major`: Major version update (e.g., 0.3.0 → 1.0.0)
+        required: true
+        default: "current"
+        type: choice
+        options:
+          - current
+          - patch
+          - minor
+          - major
+      release_type:
+        description: |-
+          Release type determines where the package is published:
+          - `stable`: Publish to both npmjs.org and GitHub Packages (production release)
+          - `pre-build`: Publish to GitHub Packages only (development/testing release)
+        required: true
+        default: "pre-build"
+        type: choice
+        options:
+          - stable
+          - pre-build
+
+jobs:
+  version-bump:
+    # バージョンバンプとGitHubリリース作成
+  
+  build:
+    # ビルドとテスト実行、アーティファクトアップロード
+  
+  publish-github:
+    # GitHub Packagesへの公開
+  
+  publish-npm:
+    # npmjs.orgへの公開（stableのみ）
+```
+
+## Job 1: version-bump
+
+### 目的
+- package.jsonのバージョン更新
+- Gitタグの作成とプッシュ
+- GitHubリリースの作成（自動リリースノート生成）
+
+### 実装
+
+```yaml
+version-bump:
+  if: github.event_name == 'workflow_dispatch' && github.event.inputs.version_bump != 'current'
+  runs-on: ubuntu-latest
+  permissions:
+    contents: write
+  outputs:
+    new_version: ${{ steps.bump_version.outputs.new_version }}
+    new_tag: ${{ steps.bump_version.outputs.new_tag }}
+  steps:
+    - uses: actions/checkout@v4
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Configure Git
+      run: |
+        git config user.name "github-actions[bot]"
+        git config user.email "github-actions[bot]@users.noreply.github.com"
+
+    - uses: actions/setup-node@v4
+      with:
+        node-version: 20
+
+    - name: Bump version and create tag
+      id: bump_version
+      run: |
+        # Run npm version and capture the new version
+        NEW_VERSION=$(npm version ${{ github.event.inputs.version_bump }} --git-tag-version=true)
+        echo "new_version=${NEW_VERSION}" >> $GITHUB_OUTPUT
+        echo "new_tag=${NEW_VERSION}" >> $GITHUB_OUTPUT
+        echo "Version bumped to: ${NEW_VERSION}"
+
+    - name: Push changes and tags
+      run: |
+        git push origin HEAD:${{ github.ref_name }}
+        git push origin --tags
+
+    - name: Create GitHub Release
+      uses: softprops/action-gh-release@v2
+      with:
+        tag_name: ${{ steps.bump_version.outputs.new_tag }}
+        name: Release ${{ steps.bump_version.outputs.new_version }}
+        draft: false
+        prerelease: false
+        generate_release_notes: true
+```
+
+### 重要ポイント
+
+1. **条件付き実行**: `version_bump != 'current'`の場合のみ実行
+2. **permissions**: `contents: write`が必須（タグプッシュとリリース作成のため）
+3. **Git設定**: github-actions[bot]として実行
+4. **npm version**: `--git-tag-version=true`でタグも同時作成
+5. **リリース作成**: `softprops/action-gh-release@v2`を使用（v1よりv2推奨）
+   - `generate_release_notes: true`で自動的にリリースノート生成
+   - `draft: false`, `prerelease: false`で即座に公開
+
+### outputs
+- `new_version`: バージョン番号（例: `v0.5.3`）
+- `new_tag`: Gitタグ名（例: `v0.5.3`）
+
+## Job 2: build
+
+### 目的
+- 依存関係のインストール
+- テストの実行
+- パッケージのビルド
+- 公開用アーティファクトのアップロード
+
+### 実装
+
+```yaml
+build:
+  needs: [version-bump]
+  if: always() && (needs.version-bump.result == 'success' || needs.version-bump.result == 'skipped')
+  runs-on: ubuntu-latest
+  outputs:
+    version: ${{ steps.get_version.outputs.version }}
+    release_type: ${{ steps.determine_release_type.outputs.release_type }}
+  steps:
+    - uses: actions/checkout@v4
+      with:
+        # If version was bumped, checkout the new tag; otherwise checkout the current ref
+        ref: ${{ needs.version-bump.outputs.new_tag || github.ref_name }}
+        fetch-depth: 0
+
+    - name: Get package version
+      id: get_version
+      run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
+
+    - name: Determine release type
+      id: determine_release_type
+      run: |
+        if [ "${{ github.event_name }}" = "push" ]; then
+          echo "release_type=stable" >> $GITHUB_OUTPUT
+        elif [ "${{ github.event_name }}" = "workflow_dispatch" ] && [ "${{ github.event.inputs.version_bump }}" != "current" ]; then
+          # For version bump workflows, use stable since we're creating an official release
+          echo "release_type=stable" >> $GITHUB_OUTPUT
+        else
+          echo "release_type=${{ github.event.inputs.release_type }}" >> $GITHUB_OUTPUT
+        fi
+
+    - uses: actions/setup-node@v4
+      with:
+        node-version: 20
+
+    - name: Setup npmrc for GitHub Packages
+      uses: ./.github/actions/setup-npmrc
+      with:
+        github_token: ${{ secrets.GH_TOKEN }}
+      env:
+        NPM_CONFIG_USERCONFIG: ~/.npmrc
+
+    - name: Install dependencies
+      run: npm install
+
+    - name: Build packages
+      run: npm run build:pkg:clean && npm run root:build
+
+    - name: Run tests
+      run: npm test
+
+    - name: Upload artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: package
+        path: |
+          dist/
+          package.json
+          package-lock.json
+          artifact/
+          presets/
+          schemas/
+          README-npmjs.md
+          .github/actions/
+        retention-days: 1
+```
+
+### 重要ポイント
+
+1. **needs依存**: `version-bump`ジョブに依存
+2. **条件付き実行**: `always()`で常に評価し、version-bumpが成功またはスキップされた場合のみ実行
+3. **checkout ref**: バージョンバンプされた場合は新しいタグをcheckout、そうでなければ現在のref
+4. **fetch-depth: 0**: 完全なGit履歴を取得（リリースノート生成などに必要）
+5. **カスタムアクション**: `.github/actions/setup-npmrc`を使用してnpmrc設定を一元管理
+6. **ビルドコマンド**: プロジェクト固有のビルドコマンドに合わせて調整
+   - 例: `npm run build:clean`, `npm run build:pkg:clean && npm run root:build`
+7. **アーティファクトパス**: プロジェクトに必要なファイルをすべて含める
+   - 必須: `dist/`, `package.json`, `package-lock.json`
+   - オプション: `README-npmjs.md`, プロジェクト固有のディレクトリ
+   - カスタムアクション再利用: `.github/actions/`
+
+### outputs
+- `version`: 現在のパッケージバージョン
+- `release_type`: 実際のリリースタイプ（stable/pre-build）
+
+### プロジェクト固有の調整が必要な箇所
+
+1. **ビルドコマンド**: `npm run build:pkg:clean && npm run root:build`
+   - monorepoの場合: workspace対応のビルドコマンド
+   - 単一パッケージの場合: `npm run build:clean`
+   
+2. **アーティファクトパス**: プロジェクトの公開ファイルに合わせる
+   ```yaml
+   path: |
+     dist/
+     package.json
+     package-lock.json
+     # プロジェクト固有のディレクトリ
+     artifact/      # ai-rulesの場合
+     presets/       # ai-rulesの場合
+     schemas/       # ai-rulesの場合
+     README-npmjs.md  # npmjs用READMEがある場合
+     .github/actions/  # カスタムアクションを再利用する場合
+   ```
+
+## Job 3: publish-github
+
+### 目的
+- GitHub Packagesへのパッケージ公開
+- プレリリースバージョンの管理
+
+### 実装
+
+```yaml
+publish-github:
+  needs: build
+  runs-on: ubuntu-latest
+  permissions:
+    contents: read
+    packages: write
+  steps:
+    - uses: actions/download-artifact@v4
+      with:
+        name: package
+        path: .
+
+    - uses: actions/setup-node@v4
+      with:
+        node-version: 20
+        registry-url: "https://npm.pkg.github.com/"
+
+    - name: Setup npmrc for GitHub Packages
+      uses: ./.github/actions/setup-npmrc
+      with:
+        github_token: ${{ secrets.GH_TOKEN }}
+      env:
+        NPM_CONFIG_USERCONFIG: ~/.npmrc
+
+    - name: Setup prerelease version
+      if: needs.build.outputs.release_type != 'stable'
+      run: |
+        TIMESTAMP=$(date +%Y%m%d%H%M%S)
+        PRERELEASE_VERSION="${{ needs.build.outputs.version }}-${{ needs.build.outputs.release_type }}.${TIMESTAMP}"
+        npm version $PRERELEASE_VERSION --no-git-tag-version
+
+    - name: Publish to GitHub Packages
+      run: |
+        if [ "${{ needs.build.outputs.release_type }}" = "stable" ]; then
+          npm publish --tag latest --verbose
+        else
+          npm publish --tag ${{ needs.build.outputs.release_type }} --verbose
+        fi
+      env:
+        NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### 重要ポイント
+
+1. **permissions**: `contents: read`, `packages: write`が必須
+2. **アーティファクトダウンロード**: buildジョブでアップロードしたファイルを取得
+3. **registry-url**: GitHub Packages用のレジストリURL
+4. **プレリリースバージョン**: タイムスタンプ付きバージョンを生成
+   - フォーマット: `{version}-{release_type}.{YYYYMMDDHHMMSS}`
+   - 例: `0.5.2-pre-build.20241028123456`
+5. **タグ管理**:
+   - stable: `--tag latest`（デフォルトインストール対象）
+   - pre-build: `--tag pre-build`（明示的に指定が必要）
+6. **認証**: `NODE_AUTH_TOKEN`に`secrets.GITHUB_TOKEN`を使用
+
+## Job 4: publish-npm
+
+### 目的
+- npmjs.orgへのパッケージ公開（stableリリースのみ）
+- npm provenanceのサポート
+
+### 実装
+
+```yaml
+publish-npm:
+  needs: build
+  if: needs.build.outputs.release_type == 'stable'
+  runs-on: ubuntu-latest
+  permissions:
+    contents: read
+    id-token: write # for npm provenance
+  steps:
+    - uses: actions/download-artifact@v4
+      with:
+        name: package
+        path: .
+
+    - uses: actions/setup-node@v4
+      with:
+        node-version: 20
+        registry-url: "https://registry.npmjs.org/"
+
+    - name: Prepare minimal package for npmjs.org
+      run: |
+        cp README-npmjs.md README.md
+
+    - name: Verify package contents (npmjs.org)
+      run: |
+        echo "Package contents preview for npmjs.org:"
+        npm pack --dry-run
+
+    - name: Publish to npmjs.org
+      run: npm publish --access public --provenance --verbose
+      env:
+        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+### 重要ポイント
+
+1. **条件付き実行**: `release_type == 'stable'`の場合のみ実行
+2. **permissions**: `id-token: write`が必須（npm provenance用）
+3. **registry-url**: npmjs.org用のレジストリURL
+4. **README準備**: `README-npmjs.md`が存在する場合は置き換え
+   - プロジェクト固有のREADMEをnpmjs用に最適化
+5. **検証**: `npm pack --dry-run`で公開内容を事前確認
+6. **公開オプション**:
+   - `--access public`: スコープ付きパッケージを公開する場合必須
+   - `--provenance`: パッケージの来歴情報を付与（セキュリティ向上）
+   - `--verbose`: 詳細ログ出力
+7. **認証**: `NODE_AUTH_TOKEN`に`secrets.NPM_TOKEN`を使用
+
+### README-npmjs.mdについて
+
+npmjs.orgとGitHub（リポジトリ/GitHub Packages）で異なるREADMEを使いたい場合：
+
+1. **README.md**: GitHubリポジトリ用（開発者向け、詳細な情報）
+2. **README-npmjs.md**: npmjs.org用（ユーザー向け、シンプルな説明）
+
+存在しない場合は、この手順をスキップまたは削除してください。
+
+## カスタムアクション: setup-npmrc
+
+### 目的
+- npmrc設定を一元管理
+- 複数ジョブでの再利用性向上
+
+### ファイル構造
+
+```
+.github/
+  actions/
+    setup-npmrc/
+      action.yml
+```
+
+### 実装: .github/actions/setup-npmrc/action.yml
+
+```yaml
+name: Setup npmrc
+description: Setup npmrc for GitHub Packages authentication
+
+inputs:
+  github_token:
+    description: 'GitHub token for authentication'
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Setup .npmrc
+      shell: bash
+      run: |
+        cat > ~/.npmrc << EOF
+        @aramassa:registry=https://npm.pkg.github.com
+        //npm.pkg.github.com/:_authToken=${{ inputs.github_token }}
+        registry=https://registry.npmjs.org/
+        EOF
+        echo "Created ~/.npmrc for GitHub Packages"
+```
+
+### 重要ポイント
+
+1. **スコープ設定**: `@aramassa:registry`をGitHub Packagesに設定
+2. **認証トークン**: `//npm.pkg.github.com/:_authToken`で認証
+3. **デフォルトレジストリ**: `registry=https://registry.npmjs.org/`（npmjsをデフォルトに）
+4. **組織名**: `@aramassa`は実際の組織名/ユーザー名に置き換える
+
+### プロジェクト固有の調整
+
+```yaml
+@{your-org-or-username}:registry=https://npm.pkg.github.com
+```
+
+## package.json 設定
+
+### 必須設定
+
+```json
+{
+  "name": "@aramassa/package-name",
+  "version": "0.5.2",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://npm.pkg.github.com/"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "bin": {
+    "package-name": "dist/cli.js"
+  }
+}
+```
+
+### 重要ポイント
+
+1. **name**: スコープ付き（`@aramassa/`）にする
+2. **publishConfig**:
+   - `access: "public"`: 公開パッケージとして設定
+   - `registry`: GitHub Packagesをデフォルトに（publish-npmジョブでnpmjs.orgを明示的に指定）
+3. **files**: 公開するファイルを明示的に指定
+   - `dist/`: ビルド成果物
+   - プロジェクト固有のディレクトリ（`artifact/`, `presets/`, `schemas/`など）
+4. **bin**: CLIツールの場合は必須
+
+### monorepoの場合
+
+ルートpackage.jsonとworkspaceパッケージのpackage.jsonで設定が必要：
+
+```json
+{
+  "workspaces": [
+    "packages/extract",
+    "packages/core"
+  ],
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com/"
+  }
+}
+```
+
+## Secrets設定
+
+### 必要なシークレット
+
+| Secret名 | 用途 | 取得方法 |
+|----------|------|----------|
+| `GITHUB_TOKEN` | GitHub Packages公開、リリース作成 | 自動提供（設定不要） |
+| `GH_TOKEN` | GitHub Packages認証（依存関係インストール） | Personal Access Token (classic) |
+| `NPM_TOKEN` | npmjs.org公開 | npmjs.org Automation Token |
+
+### GH_TOKEN の作成
+
+1. GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
+2. Generate new token (classic)
+3. 権限: `read:packages`, `write:packages`
+4. リポジトリの Settings → Secrets and variables → Actions → New repository secret
+5. Name: `GH_TOKEN`, Value: 生成したトークン
+
+### NPM_TOKEN の作成
+
+1. npmjs.org → Account Settings → Access Tokens
+2. Generate New Token → Automation
+3. リポジトリの Settings → Secrets and variables → Actions → New repository secret
+4. Name: `NPM_TOKEN`, Value: 生成したトークン
+
+## 使用方法
+
+### 1. プレリリース公開（GitHub Packagesのみ）
+
+```
+Actions → Publish package → Run workflow
+- version_bump: current
+- release_type: pre-build
+→ Run workflow
+```
+
+**結果**:
+- GitHub Packagesに`{version}-pre-build.{timestamp}`として公開
+- タグ: `pre-build`
+
+### 2. 正式リリース（バージョンアップなし）
+
+```
+Actions → Publish package → Run workflow
+- version_bump: current
+- release_type: stable
+→ Run workflow
+```
+
+**結果**:
+- GitHub Packagesとnpmjsにstableバージョンとして公開
+- タグ: `latest`
+
+### 3. 正式リリース（パッチバージョンアップ）
+
+```
+Actions → Publish package → Run workflow
+- version_bump: patch
+- release_type: stable
+→ Run workflow
+```
+
+**結果**:
+- バージョンが`0.5.2`→`0.5.3`に更新
+- Gitタグ`v0.5.3`が作成
+- GitHubリリース作成
+- GitHub Packagesとnpmjsにstableバージョンとして公開
+
+## トラブルシューティング
+
+### エラー: "This request requires authentication"
+
+**原因**: `GH_TOKEN`が設定されていないか、権限が不足
+
+**解決策**:
+1. `GH_TOKEN`がSecretsに登録されているか確認
+2. トークンの権限に`read:packages`, `write:packages`が含まれているか確認
+
+### エラー: "You cannot publish over the previously published versions"
+
+**原因**: 同じバージョンが既に公開されている
+
+**解決策**:
+1. `version_bump`を`current`以外に設定してバージョンを上げる
+2. または、package.jsonのバージョンを手動で更新してコミット
+
+### エラー: "npm ERR! 404 Not Found - GET https://npm.pkg.github.com/@aramassa/..."
+
+**原因**: 依存関係がGitHub Packagesに存在しないか、認証エラー
+
+**解決策**:
+1. `.github/actions/setup-npmrc`が正しく実行されているか確認
+2. `GH_TOKEN`の権限を確認
+3. 依存関係のpackage.jsonの`publishConfig.registry`を確認
+
+### ビルドが失敗する
+
+**確認ポイント**:
+1. ローカルで`npm install && npm test && npm run build`が成功するか
+2. Node.jsバージョンが一致しているか（ワークフローではv20を使用）
+3. `.github/actions/setup-npmrc`が存在するか
+
+### npm provenanceエラー
+
+**原因**: `id-token: write`権限が不足
+
+**解決策**:
+```yaml
+publish-npm:
+  permissions:
+    contents: read
+    id-token: write  # この行を追加
+```
+
+## ベストプラクティス
+
+### 1. バージョン管理戦略
+
+- **プレリリース**: `version_bump: current`, `release_type: pre-build`
+  - 頻繁なテスト公開
+  - 開発中の機能確認
+  
+- **正式リリース**: `version_bump: patch/minor/major`, `release_type: stable`
+  - セマンティックバージョニングに従う
+  - GitHubリリースも作成される
+
+### 2. ワークフロー実行順序
+
+1. まずプレリリースで動作確認（`pre-build`）
+2. 問題なければ正式リリース（`stable`）
+3. バージョンバンプは正式リリース時に実施
+
+### 3. README管理
+
+- **README.md**: 開発者向け（詳細なビルド手順、貢献ガイドライン）
+- **README-npmjs.md**: ユーザー向け（インストール方法、基本的な使い方）
+
+### 4. アーティファクト管理
+
+- `retention-days: 1`: 不要なストレージ使用を避ける
+- 必要最小限のファイルのみアップロード
+
+### 5. セキュリティ
+
+- `npm publish --provenance`: パッケージの来歴を記録
+- `permissions`: 各ジョブで必要最小限の権限のみ付与
+- `secrets.GITHUB_TOKEN`: 自動提供されるトークンを優先使用
+
+## チェックリスト
+
+新しいリポジトリにこのワークフローを実装する際のチェックリスト：
+
+- [ ] `.github/workflows/publish.yml`を作成
+- [ ] `.github/actions/setup-npmrc/action.yml`を作成
+- [ ] package.jsonに`publishConfig`を追加
+- [ ] `GH_TOKEN`をSecretsに登録
+- [ ] `NPM_TOKEN`をSecretsに登録（npmjs公開する場合）
+- [ ] `README-npmjs.md`を作成（必要に応じて）
+- [ ] ビルドコマンドをプロジェクトに合わせて調整
+- [ ] アーティファクトパスをプロジェクトに合わせて調整
+- [ ] `@aramassa`をプロジェクトの組織名/ユーザー名に置き換え
+- [ ] ローカルで`npm install && npm test && npm run build`が成功することを確認
+- [ ] プレリリースで動作確認（`pre-build`）
+- [ ] 正式リリースのテスト（`stable`）
+
+## 参考実装
+
+このルールは以下の3つの実装から良い点を統合したものです：
+
+1. **ai-rules**: `.github/workflows/publish.yml`
+   - 柔軟なバージョンバンプ戦略
+   - 詳細なアーティファクト管理
+   
+2. **mcp-docs-collector**: `.github/workflows/publish-root.yml`
+   - `softprops/action-gh-release`の使用
+   - カスタムアクションによるnpmrc設定
+   
+3. **skel-extractor**: `.github/workflows/publish-gpr.yml`
+   - シンプルなプレリリースバージョン管理
+   - 効率的なアーティファクト処理