@aramassa/ai-rules 0.5.3 → 0.6.1

package/artifact/instructions/rules/development/github-actions-npm-troubleshooting.md

@@ -0,0 +1,611 @@
+---
+type: development
+category: cd
+focus: github-actions, npm-publish, troubleshooting
+language:
+  - typescript
+  - nodejs
+framework: npm
+applyTo: ".github/workflows/**/*.yml"
+---
+
+# GitHub Actions npm Package Publishing Troubleshooting Guide
+
+## 概要
+
+GitHub Actions でnpmパッケージ公開時に発生する一般的なエラーとその解決方法をまとめたガイドです。
+CI/CD環境特有の問題、npm workspaces構成での依存関係管理、Dual Registry公開、バージョン管理など、実際のトラブルシューティング履歴に基づいた知見を提供します。
+
+## 問題1: vitest コマンドが見つからない (ENOENT: vitest: not found)
+
+### 発生したエラー
+
+```bash
+sh: 1: vitest: not found
+npm error Lifecycle script `test` failed with error:
+npm error code 127
+npm error path /home/runner/work/mcp-docs-collector/packages/cli-utils
+npm error command failed
+```
+
+### 原因
+
+npm workspaces 構成において、各パッケージ（`packages/cli-utils`, `packages/common`）の `package.json` で `test` スクリプトが `vitest` コマンドを使用していたが、`vitest` が各パッケージの `devDependencies` に含まれていなかった。
+
+**なぜローカルでは動いていたのか:**
+- ルートの `package.json` に `vitest` が `devDependencies` として存在
+- ローカル環境では npm workspaces のホイスティング機能により、子パッケージからもルートの `node_modules` にある `vitest` にアクセス可能
+- CI環境では、依存関係の解決が異なり、各パッケージが独立して実行されるため、明示的に `devDependencies` に含める必要がある
+
+### 解決方法
+
+各パッケージに必要な `devDependencies` を追加：
+
+```bash
+# packages/cli-utils に追加
+npm install --save-dev vitest typescript @types/node --workspace=packages/cli-utils
+
+# packages/common に追加
+npm install --save-dev vitest typescript @types/node --workspace=packages/common
+
+# クリーンインストール
+rm -rf node_modules package-lock.json
+npm install
+```
+
+**結果の package.json:**
+
+```json
+{
+  "devDependencies": {
+    "@types/node": "^22.16.5",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  }
+}
+```
+
+### 予防策・チェックリスト
+
+#### 開発時の確認事項
+
+- [ ] **新規パッケージ作成時**: 使用する全てのコマンド（テストランナー、ビルドツール等）を `devDependencies` に明示的に追加
+- [ ] **スクリプト追加時**: そのスクリプトが依存する全てのパッケージが `dependencies` または `devDependencies` に含まれているか確認
+- [ ] **ローカルテスト**: 以下のコマンドで各パッケージが独立して動作するか確認
+
+```bash
+# 各パッケージのディレクトリで実行
+cd packages/cli-utils
+rm -rf node_modules
+npm install
+npm test
+npm run build
+```
+
+#### CI/CD 設定時の確認事項
+
+- [ ] **依存関係の明示**: ワークスペース構成では、各パッケージが独立して実行可能な状態にする
+- [ ] **統一性の確認**: 同じツールを使うパッケージ間で、バージョンを統一する
+- [ ] **Docker環境でのテスト**: ローカル環境と異なる動作を検証
+
+```bash
+# Docker環境でのテスト例
+docker run --rm -v $(pwd):/app -w /app node:20 npm install
+docker run --rm -v $(pwd):/app -w /app node:20 npm test
+```
+
+#### 設計原則
+
+**原則1: 明示的依存管理**
+- ホイスティングに依存せず、各パッケージが必要とする依存を明示的に宣言
+- 「動いているから良い」ではなく、「設計として正しい」状態を目指す
+
+**原則2: 独立性の担保**
+- 各パッケージは単独で `npm install && npm test && npm build` が実行できる状態にする
+- ルートパッケージの依存に依存しない
+
+---
+
+## 問題2: npm version コマンドの出力形式エラー (Invalid format 'v0.0.2')
+
+### 発生したエラー
+
+```bash
+Error: Unable to process file command 'output' successfully.
+Error: Invalid format 'v0.0.2'
+```
+
+### 原因
+
+GitHub Actionsの `version-bump` ジョブで、`npm version` コマンドの出力を直接 `$GITHUB_OUTPUT` に書き込んでいたが、以下の問題があった：
+
+1. **出力形式の不確実性**: `npm version` は `v0.0.2` という形式（vプレフィックス付き）で出力するが、処理によっては期待される形式と異なる
+2. **Git統合の複雑さ**: `npm version` の `-m` オプションと Git の自動タグ作成が干渉
+3. **非推奨アクションの使用**: `actions/create-release@v1` が deprecated
+
+### 解決方法
+
+**変更前:**
+```yaml
+- name: Bump version and create tag
+  id: bump
+  working-directory: packages/cli-utils
+  run: |
+    NEW_VERSION=$(npm version ${{ github.event.inputs.version_bump }} -m "chore(cli-utils): release v%s")
+    echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
+    git push origin HEAD --tags
+
+- name: Create GitHub Release
+  uses: actions/create-release@v1
+```
+
+**変更後:**
+```yaml
+- name: Bump version and create tag
+  id: bump
+  working-directory: packages/cli-utils
+  run: |
+    # Bump version without creating git tag
+    npm version ${{ github.event.inputs.version_bump }} --no-git-tag-version
+    
+    # Get the new version from package.json
+    NEW_VERSION=$(node -p "require('./package.json').version")
+    echo "new_version=v${NEW_VERSION}" >> "$GITHUB_OUTPUT"
+    
+    # Commit and tag
+    git add package.json
+    git commit -m "chore(cli-utils): release v${NEW_VERSION}"
+    git tag "cli-utils-v${NEW_VERSION}"
+    git push origin HEAD --tags
+
+- name: Create GitHub Release
+  uses: softprops/action-gh-release@v1
+```
+
+### 予防策・チェックリスト
+
+#### バージョン管理のベストプラクティス
+
+**原則1: Git操作の分離**
+- `--no-git-tag-version` フラグで npm の Git 統合を無効化
+- commit と tag を明示的に作成することで、制御を明確にする
+
+**原則2: 確実なバージョン取得**
+```bash
+# ✅ 推奨: package.json から直接読み取る
+VERSION=$(node -p "require('./package.json').version")
+
+# ❌ 非推奨: npm version の出力に依存
+VERSION=$(npm version patch)  # 出力形式が不確実
+```
+
+**原則3: $GITHUB_OUTPUT の安全な使用**
+```bash
+# ✅ 推奨: 引用符で囲む
+echo "key=value" >> "$GITHUB_OUTPUT"
+
+# ❌ 非推奨: 引用符なし（スペースや特殊文字で問題発生）
+echo "key=value" >> $GITHUB_OUTPUT
+```
+
+#### GitHub Actions のベストプラクティス
+
+- [ ] **最新アクションの使用**: deprecated なアクションは使わない
+  - `actions/create-release@v1` → `softprops/action-gh-release@v1`
+- [ ] **タグの命名規則**: モノレポでは `<package-name>-v<version>` 形式を使用
+- [ ] **冪等性の確保**: 同じ操作を複数回実行しても安全な設計にする
+
+---
+
+## 問題3: Dual Registry での認証エラー (ENEEDAUTH)
+
+### 発生したエラー
+
+```bash
+npm error code ENEEDAUTH
+npm error need auth This command requires you to be logged in to https://npm.pkg.github.com
+npm error need auth You need to authorize this machine using `npm adduser`
+```
+
+### 原因
+
+**根本原因**: `package.json` の `publishConfig.registry` に GitHub Packages のレジストリが設定されていたため、npmjs.org への publish もそのレジストリに向かってしまった。
+
+**詳細**:
+```json
+{
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://npm.pkg.github.com"  // ← これが原因
+  }
+}
+```
+
+- `actions/setup-node@v4` で `registry-url: https://registry.npmjs.org/` を設定しても、`package.json` の `publishConfig.registry` が優先される
+- GitHub Packages 用の認証情報で npmjs.org にアクセスしようとして失敗
+
+### 解決方法
+
+npmjs.org への publish 前に、`publishConfig.registry` を削除するステップを追加：
+
+```yaml
+- name: Update publishConfig for npmjs.org
+  working-directory: packages/cli-utils
+  run: |
+    # Remove GitHub Packages registry from publishConfig
+    node -e "
+      const fs = require('fs');
+      const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+      if (pkg.publishConfig) {
+        delete pkg.publishConfig.registry;
+      }
+      fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
+    "
+    echo "Updated package.json publishConfig for npmjs.org"
+
+- name: Publish to npmjs.org
+  run: npm publish --access public --verbose
+  working-directory: packages/cli-utils
+  env:
+    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+### 予防策・チェックリスト
+
+#### Dual Registry 設計のベストプラクティス
+
+**アプローチ1: publishConfig を動的に変更（今回の方法）**
+
+利点:
+- 1つの `package.json` で管理
+- Git履歴に変更が残らない
+
+欠点:
+- ワークフローが複雑になる
+- 開発者がローカルで publish する際に注意が必要
+
+**アプローチ2: 別々の package.json を管理**
+
+```bash
+# package.json (開発用、GitHub Packages向け)
+{
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
+  }
+}
+
+# package.npmjs.json (npmjs.org向け)
+{
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  }
+}
+```
+
+**アプローチ3: publishConfig.registry を使わない（最もシンプル）**
+
+```json
+{
+  "publishConfig": {
+    "access": "public"
+    // registry は指定しない
+  }
+}
+```
+
+ワークフローで明示的にレジストリを指定：
+```bash
+# GitHub Packages
+npm publish --registry=https://npm.pkg.github.com
+
+# npmjs.org
+npm publish --registry=https://registry.npmjs.org
+```
+
+#### チェックリスト
+
+- [ ] **レジストリの優先順位を理解**
+  1. `package.json` の `publishConfig.registry`
+  2. `.npmrc` ファイル
+  3. `actions/setup-node@v4` の `registry-url`
+  4. コマンドライン引数 `--registry`
+
+- [ ] **認証情報の分離**
+  - GitHub Packages: `NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}`
+  - npmjs.org: `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}`
+
+- [ ] **Dry-run での検証**
+```bash
+# publish 前に必ず実行
+npm publish --dry-run
+```
+
+- [ ] **ローカルテストの注意点**
+  - ローカルの `.npmrc` が CI と異なる動作を引き起こす可能性
+  - テスト用のプライベートレジストリを使用して検証
+
+---
+
+## 問題4: Provenance 機能のリポジトリ可視性エラー
+
+### 発生したエラー
+
+```bash
+npm error code E422
+npm error 422 Unprocessable Entity - PUT https://registry.npmjs.org/@aramassa%2fmcp-docs-collector-cli-utils
+Error verifying sigstore provenance bundle: Unsupported GitHub Actions source repository visibility: "private". 
+Only public source repositories are supported when publishing with provenance.
+```
+
+### 原因
+
+`npm publish --provenance` オプションは**パブリックリポジトリでのみサポート**されている機能。
+
+**Provenance（来歴証明）とは:**
+- npm v9.5.0+ で導入された機能
+- パッケージがどこで、どのように、誰によってビルドされたかを証明
+- Sigstore を使用した署名により、supply chain attack を防止
+- **パブリックリポジトリのみ対応**（プライベートリポジトリでは使用不可）
+
+### 解決方法
+
+`--provenance` フラグを削除：
+
+**変更前:**
+```yaml
+- name: Publish to npmjs.org
+  run: npm publish --provenance --access public --verbose
+```
+
+**変更後:**
+```yaml
+- name: Publish to npmjs.org
+  run: npm publish --access public --verbose
+```
+
+### 予防策・チェックリスト
+
+#### Provenance 使用の判断基準
+
+**✅ Provenance を使うべき場合:**
+- パブリックリポジトリである
+- 広く公開されるパッケージである
+- Supply chain security が重要である
+- npm v9.5.0+ を使用している
+
+**❌ Provenance を使えない/使うべきでない場合:**
+- プライベートリポジトリである
+- 社内専用パッケージである
+- npm のバージョンが古い
+
+#### 条件分岐の実装例
+
+リポジトリの可視性に応じて provenance を切り替える場合：
+
+```yaml
+- name: Check repository visibility
+  id: repo-visibility
+  run: |
+    VISIBILITY=$(gh repo view --json visibility -q .visibility)
+    echo "visibility=$VISIBILITY" >> "$GITHUB_OUTPUT"
+  env:
+    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+- name: Publish to npmjs.org (Public)
+  if: steps.repo-visibility.outputs.visibility == 'public'
+  run: npm publish --provenance --access public --verbose
+
+- name: Publish to npmjs.org (Private)
+  if: steps.repo-visibility.outputs.visibility != 'public'
+  run: npm publish --access public --verbose
+```
+
+#### チェックリスト
+
+- [ ] **リポジトリの可視性を確認**
+  - GitHub リポジトリの Settings > General > Danger Zone
+  - `gh repo view --json visibility`
+
+- [ ] **npm バージョンの確認**
+```bash
+npm --version  # 9.5.0 以上必要
+```
+
+- [ ] **Provenance の検証**
+```bash
+# パッケージ公開後に検証
+npm view <package-name> --json | jq .dist.attestations
+```
+
+---
+
+## 全体的なベストプラクティス
+
+### 1. CI/CD パイプラインの設計原則
+
+#### 原則1: 明示的かつ予測可能
+- 暗黙的な依存や動作に頼らない
+- すべての設定を明示的に記述
+- 環境変数、シークレット、設定ファイルを明確に文書化
+
+#### 原則2: 段階的な検証
+```yaml
+# 推奨: 各段階で検証
+- name: Install dependencies
+  run: npm install
+
+- name: Verify installation
+  run: npm list || true
+
+- name: Run tests
+  run: npm test
+
+- name: Verify build
+  run: npm run build
+
+- name: Verify package contents
+  run: npm pack --dry-run
+```
+
+#### 原則3: 冪等性の確保
+- 同じ入力で何度実行しても同じ結果
+- 失敗時の状態が予測可能
+- ロールバックが容易
+
+### 2. エラーハンドリングのベストプラクティス
+
+#### デバッグ情報の充実
+```yaml
+- name: Debug environment
+  if: failure()
+  run: |
+    echo "=== Environment Variables ==="
+    env | grep -E '^(NODE|NPM|CI)' || true
+    echo "=== npm config ==="
+    npm config list
+    echo "=== .npmrc ==="
+    cat ~/.npmrc || echo "No .npmrc found"
+    echo "=== package.json ==="
+    cat package.json
+```
+
+#### ログの詳細化
+```yaml
+# --verbose フラグを積極的に使用
+npm install --verbose
+npm test --verbose
+npm publish --verbose
+```
+
+### 3. モノレポ（Workspaces）での注意点
+
+#### 依存関係の管理
+```json
+// ルート package.json
+{
+  "workspaces": ["packages/*"],
+  "devDependencies": {
+    // 共通のビルドツール
+    "typescript": "^5.8.3",
+    "eslint": "^8.57.1"
+  }
+}
+
+// 各パッケージ package.json
+{
+  "devDependencies": {
+    // そのパッケージ固有のツール
+    "vitest": "^3.2.4",
+    "@types/node": "^22.16.5"
+  }
+}
+```
+
+#### 独立性のテスト
+```bash
+# 各パッケージが独立して動作するか確認
+for pkg in packages/*; do
+  echo "Testing $pkg"
+  (cd "$pkg" && rm -rf node_modules && npm install && npm test)
+done
+```
+
+### 4. セキュリティのベストプラクティス
+
+#### シークレット管理
+- [ ] `GITHUB_TOKEN`: 自動で提供される（リポジトリアクセス用）
+- [ ] `NPM_TOKEN`: npmjs.org への publish 用（手動設定）
+- [ ] `GH_TOKEN`: より広い権限が必要な場合（手動設定）
+
+#### 最小権限の原則
+```yaml
+permissions:
+  contents: write  # タグ作成に必要
+  id-token: write  # provenance に必要
+  # その他の権限は付与しない
+```
+
+---
+
+## トラブルシューティングフローチャート
+
+```mermaid
+graph TD
+    A[CI/CD エラー発生] --> B{エラーの種類は?}
+    
+    B -->|コマンドが見つからない| C[依存関係の問題]
+    C --> C1[package.json の devDependencies を確認]
+    C1 --> C2[ローカルで npm install && npm test]
+    C2 --> C3[Docker環境でテスト]
+    
+    B -->|認証エラー| D[レジストリ/認証の問題]
+    D --> D1[publishConfig.registry を確認]
+    D1 --> D2[.npmrc の設定を確認]
+    D2 --> D3[NODE_AUTH_TOKEN を確認]
+    
+    B -->|形式エラー| E[出力形式の問題]
+    E --> E1[GITHUB_OUTPUT の形式を確認]
+    E1 --> E2[引用符の有無を確認]
+    E2 --> E3[値の取得方法を見直す]
+    
+    B -->|422エラー| F[Provenance/可視性の問題]
+    F --> F1[リポジトリがパブリックか確認]
+    F1 --> F2{パブリック?}
+    F2 -->|Yes| F3[npm version を確認]
+    F2 -->|No| F4[--provenance を削除]
+```
+
+---
+
+## チェックリスト: 新規パッケージ公開時
+
+### 事前準備
+- [ ] リポジトリの可視性を確認（public/private）
+- [ ] 必要なシークレットを設定（NPM_TOKEN等）
+- [ ] パッケージ名の重複を確認 `npm search <package-name>`
+
+### package.json の確認
+- [ ] `name`: スコープ付きの場合 `@scope/package-name`
+- [ ] `version`: セマンティックバージョニング準拠
+- [ ] `main`, `types`: 正しいエントリポイント
+- [ ] `files`: 公開するファイルを明示
+- [ ] `publishConfig`: レジストリ設定を確認
+- [ ] `dependencies`: 実行時に必要なもののみ
+- [ ] `devDependencies`: ビルド/テストツールを含む
+
+### ワークフローの確認
+- [ ] Node.js バージョンの指定
+- [ ] レジストリの明示的な設定
+- [ ] 認証トークンの正しい使用
+- [ ] dry-run での検証ステップ
+- [ ] エラー時のデバッグ情報出力
+
+### テスト
+- [ ] ローカルでの `npm pack --dry-run`
+- [ ] Docker環境でのテスト
+- [ ] テストレジストリでの公開テスト（verdaccio等）
+
+### 公開後
+- [ ] npmjs.org でパッケージを確認
+- [ ] `npm install <package-name>` で動作確認
+- [ ] README、ドキュメントの表示確認
+
+---
+
+## まとめ
+
+今回の一連のエラー対応を通じて学んだ重要なポイント：
+
+1. **明示的な依存管理**: ホイスティングに頼らず、必要な依存を明示する
+2. **Git操作の分離**: ツールの自動化に頼らず、明示的に制御する
+3. **レジストリ設定の優先順位**: package.json > .npmrc > 環境設定
+4. **機能の制約を理解**: provenance はパブリックリポジトリのみ
+5. **段階的な検証**: 各ステップで動作を確認し、問題を早期発見
+
+これらの知見を活かし、今後は初回からスムーズに CI/CD パイプラインを構築できるようにする。
+
+## 関連ドキュメント
+
+- [npm Package Publishing Workflow 実装ルール](./npm-publish.md) - 標準的なワークフロー実装
+- [GitHub Actions Testing Policy](../test/github-actions-no-tests.md) - ワークフローテストの方針
+- [GitHub Issue Template Rules](./github.md) - Issue作成時のテンプレート使用方法