@aramassa/ai-rules 0.5.3 → 0.6.1

package/artifact/instructions/rules/test/e2e-cli-execution.md

@@ -0,0 +1,104 @@
+---
+type: test
+category: e2e-test
+focus: cli-execution
+---
+
+# docs-ai/e2e-test ガイドライン
+
+`docs-ai/e2e-test/` ディレクトリは、**プロダクトの E2E テスト・動作確認手順をコマンドライン形式で AI 向けに記録する場所**です。人間が読む `docs/` とは役割が異なり、「どのコマンドを叩けばプロダクトの動作確認ができるか」を機械的にたどれることを重視します。
+
+## ドキュメントの目的
+
+- プロダクトの **E2E テスト手順**を、再現性の高い形で記録する
+- 「どのコマンドを叩けば最低限の動作確認ができるか」を明示する
+- 将来の回帰テストや動作確認の際の **チェックリスト** として活用する
+
+## ファイル命名とスコープの書き方
+
+- ファイル名は、テストする機能やシナリオが分かる名前にする
+  - 例: `mcp-server-basic-e2e.md`, `confluence-sync-e2e.md` など
+- ファイル先頭の frontmatter / 見出しで、以下を明記する
+  - 対象機能（例: `MCPサーバー基本動作`, `CLIツール基本機能`）
+  - 目的（E2E テストコマンド集 など）
+
+## 構成ルール
+
+各ファイルは、概ね次のような構成に揃えます（厳密でなくてOKですが、できるだけ寄せる）：
+
+1. **前提**
+   - 実行場所（例: `cd /repos/ly-work-tools`）
+   - 必要なツール（Node.js / npm / そのほか）
+   - 初期セットアップ手順（`npm install` など）
+2. **全体ビルド・全体テスト**
+   - モノレポ全体の build / test を実行するコマンド
+3. **パッケージ単位の確認**
+   - `common` / `core` / `cli` など、影響がありそうなパッケージごとの build / test
+4. **コマンドライン動作確認**
+   - CLI やサーバなどを **実際に叩くコマンド** を記載
+   - 正常系だけでなく、代表的なエラーケースの確認も含める
+5. **クリーンアップ手順**
+   - グローバルインストールしたものを戻す操作
+   - 一時ファイル、開発用サーバプロセスの停止など
+6. **関連ドキュメントとの整合性チェック（任意）**
+   - `docs/` や `packages/*/README.md` に書かれている利用例と、ここに記載したコマンドが大きく乖離していないかを目視確認するポイントをメモ
+
+## コマンド記述のスタイル
+
+- **コピペでそのまま実行できること** を最優先に書く
+- 可能な限り、以下のように `cd` から書く
+
+```bash
+cd /repos/ly-work-tools
+npm run build
+npm test
+```
+
+- 各ブロックの前に、簡単なコメントで目的を書く
+
+```bash
+# cli パッケージ単体ビルド
+npm run build --workspace=packages/cli
+
+# cli パッケージ単体テスト
+npm test --workspace=packages/cli
+```
+
+- エラー動作の確認では、終了コードも分かるようにするとなお良い
+
+```bash
+# 0 除算でエラーになることを確認
+node packages/cli/dist/index.js calculate divide 10 0 ; echo "exit code: $?"
+```
+
+## クリーンアップに関するルール
+
+コマンドライン確認の手順の中で、環境に影響を与える操作を行った場合は、**必ず対応するクリーンアップ手順も同じファイルに書きます。**
+
+### 例: `npm link` でグローバル CLI を登録した場合
+
+```bash
+# グローバルにリンク
+npm link --workspace=packages/cli
+
+# bin 経由の動作確認
+ly-tools echo "CLI via bin"
+
+# 確認後にリンク解除（任意）
+# ※ npm の仕様上、workspace フラグ付き unlink はエラーになるため、
+#    グローバルからはパッケージ名で unlink する
+npm unlink -g @ly-work-tools/cli
+```
+
+その他、ローカルに残るプロセス・一時ディレクトリなどがあれば、
+
+- 「どこに何ができるのか」
+- 「どうすれば元に戻せるか」
+
+を明示的に書いてください。
+
+## 期待する運用イメージ
+
+- 新しい機能を実装したときや、既存機能を変更したときに、対応する E2E テスト手順を `docs-ai/e2e-test/xxx-e2e.md` に追加・更新する
+- 開発者や AI エージェントが、「この機能ってどうやって動作確認すればいいんだっけ？」と思ったときに、このディレクトリを開けば一通りの手順が分かる状態を目指します。
+- すべてのコードは何らかの形で CLI から実行可能で、その入力と出力をチェックすれば動作が問題ないことを確認できるようにします。

package/artifact/instructions/rules/test/github-actions-test.md

@@ -0,0 +1,402 @@
+---
+type: test
+category: github-actions
+focus: test-workflow
+applyTo: ".github/workflows/*.{yml,yaml}"
+---
+
+# GitHub Actions テストワークフロー標準
+
+## 概要
+
+GitHub Actions でテストワークフローを作成する際の統一的な書き方を定めたルールです。
+一貫性のあるCI/CD設定により、メンテナンス性と信頼性を向上させます。
+
+## 基本方針
+
+### ワークフロー構成の原則
+
+- **明確なトリガー設定**: どのブランチ・イベントでテストを実行するか明示する
+- **適切なNode.jsバージョン指定**: プロジェクトで使用する Node.js バージョンをマトリックスで管理
+- **段階的な実行**: 依存関係のインストール → ビルド → テスト の順序を守る
+- **検証の網羅性**: ビルド成果物の動作確認を含める
+
+## ワークフロー構造
+
+### 必須要素
+
+GitHub Actions のテストワークフローには、以下の要素を必ず含めてください：
+
+#### 1. ワークフロー名とトリガー
+
+```yaml
+name: Test
+
+on:
+  push:
+    branches: [main, develop, feature/*, codex/**, copilot/**]
+  workflow_dispatch:
+```
+
+- `name`: ワークフロー名は `Test` など、目的が明確な名前にする
+- `on.push.branches`: テストを実行する対象ブランチを明示する
+  - メインブランチ（`main`, `develop`）
+  - フィーチャーブランチパターン（`feature/*`, `codex/**`, `copilot/**`）
+- `workflow_dispatch`: 手動実行を可能にする
+
+#### 2. ジョブ定義
+
+```yaml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20.x]
+```
+
+- `runs-on`: `ubuntu-latest` を使用（特別な理由がない限り）
+- `strategy.matrix`: Node.js バージョンをマトリックスで管理
+  - プロジェクトで使用する Node.js のメジャーバージョンを指定
+  - 複数バージョンでテストする場合は配列に追加（例: `[18.x, 20.x]`）
+
+#### 3. ステップ構成
+
+テストワークフローのステップは、以下の順序で構成します：
+
+##### 3.1 リポジトリのチェックアウト
+
+```yaml
+- uses: actions/checkout@v4
+```
+
+- 常に最新の安定版アクション（v4）を使用
+- 特別な理由がない限り追加オプションは不要
+
+##### 3.2 Node.js のセットアップ
+
+```yaml
+- name: Use Node.js ${{ matrix.node-version }}
+  uses: actions/setup-node@v4
+  with:
+    node-version: ${{ matrix.node-version }}
+    cache: "npm"
+```
+
+- アクション名にはマトリックス変数を含めて、どのバージョンを使用しているか明示
+- `cache: "npm"` で依存関係をキャッシュし、実行時間を短縮
+- `node-version` はマトリックスの値を使用
+
+##### 3.3 認証設定（必要な場合）
+
+プライベートパッケージや GitHub Packages を使用する場合：
+
+```yaml
+- name: Setup npmrc
+  uses: ./.github/actions/setup-npmrc
+  with:
+    github_token: ${{ secrets.GH_TOKEN }}
+```
+
+- カスタムアクションやシークレットを使用して認証を設定
+- パブリックパッケージのみの場合は不要
+
+##### 3.4 依存関係のインストール
+
+```yaml
+- name: Install dependencies
+  run: npm ci
+```
+
+- **必ず `npm ci` を使用**（`npm install` ではない）
+- `npm ci` は package-lock.json に基づいて厳密にインストールするため、再現性が高い
+- 既存の node_modules を削除してからインストールするため、クリーンな状態を保証
+
+##### 3.5 ビルド
+
+```yaml
+- name: Build
+  run: npm run build:ci
+```
+
+- プロジェクトの CI 用ビルドスクリプトを実行
+- スクリプト名は `build:ci` または `build` を使用
+- テスト前に必ずビルドを完了させる
+
+##### 3.6 テスト実行
+
+```yaml
+- name: Run tests
+  run: npm run test:ci
+```
+
+- CI 用のテストスクリプトを実行
+- スクリプト名は `test:ci` または `test` を使用
+- 通常は `vitest run` や `jest --ci` など、ウォッチモードを無効にした実行
+
+##### 3.7 成果物の検証（推奨）
+
+ビルド成果物が正しく動作することを検証します：
+
+```yaml
+- name: Verify CLI executable
+  run: |
+    ./dist/cli.js --help
+
+- name: Test CLI functionality
+  run: |
+    # Create a test directory with some markdown files
+    mkdir -p test-workspace/docs
+    echo "# Test Document" > test-workspace/docs/test.md
+    echo "This is a test document" >> test-workspace/docs/test.md
+
+    # Test the extract command
+    ./dist/cli.js extract --src test-workspace/docs --out test-output.md
+
+    # Verify the output file was created
+    if [ -f test-output.md ]; then
+      echo "✅ CLI extract command works correctly"
+      cat test-output.md
+    else
+      echo "❌ CLI extract command failed"
+      exit 1
+    fi
+```
+
+- CLI ツールの場合: ヘルプ表示や基本コマンドの実行を確認
+- API/ライブラリの場合: 簡単なインポートや使用例を実行
+- 検証は実際のユースケースに近い形で行う
+
+## ワークスペース構成の場合
+
+モノレポ（workspace）構成の場合の追加考慮事項：
+
+### ワークスペース全体のテスト
+
+```yaml
+- name: Run all workspace tests
+  run: npm run test:all
+```
+
+- `package.json` の scripts に `test:all: "npm run test --workspaces"` を定義
+- 全パッケージのテストを一括実行
+
+### 個別パッケージのビルド・テスト
+
+必要に応じて、特定のパッケージのみをビルド・テストすることもできます：
+
+```yaml
+- name: Build core package
+  run: npm run build --workspace=packages/core
+
+- name: Test core package
+  run: npm test --workspace=packages/core
+```
+
+## ベストプラクティス
+
+### 1. キャッシュの活用
+
+依存関係のキャッシュを有効にして、実行時間を短縮します：
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: ${{ matrix.node-version }}
+    cache: "npm"  # ← 必須
+```
+
+### 2. 明確なステップ名
+
+各ステップには、何を実行しているか明確に分かる名前を付けます：
+
+```yaml
+# ✅ 良い例
+- name: Install dependencies
+  run: npm ci
+
+# ❌ 悪い例
+- name: Install
+  run: npm ci
+```
+
+### 3. エラー時の動作
+
+デフォルトでは、ステップが失敗すると後続のステップはスキップされます。
+これは通常望ましい動作なので、特別な理由がない限り変更しないでください。
+
+### 4. 環境変数の設定
+
+環境変数が必要な場合は、適切なスコープで設定します：
+
+```yaml
+# ジョブ全体で使用する場合
+jobs:
+  test:
+    env:
+      NODE_ENV: test
+
+# 特定のステップのみで使用する場合
+- name: Run tests
+  run: npm test
+  env:
+    CI: true
+```
+
+### 5. シークレットの使用
+
+機密情報は必ず GitHub Secrets として管理し、直接記述しないでください：
+
+```yaml
+# ✅ 良い例
+with:
+  github_token: ${{ secrets.GH_TOKEN }}
+
+# ❌ 悪い例（絶対にしないこと）
+with:
+  github_token: ghp_xxxxxxxxxxxx
+```
+
+## アンチパターン
+
+### ❌ 避けるべきパターン
+
+1. **`npm install` の使用**
+   ```yaml
+   # ❌ 避ける
+   - run: npm install
+   
+   # ✅ 推奨
+   - run: npm ci
+   ```
+
+2. **ビルドのスキップ**
+   ```yaml
+   # ❌ 避ける
+   - name: Run tests
+     run: npm test  # ビルドせずにテスト
+   
+   # ✅ 推奨
+   - name: Build
+     run: npm run build:ci
+   - name: Run tests
+     run: npm run test:ci
+   ```
+
+3. **不明確なブランチパターン**
+   ```yaml
+   # ❌ 避ける
+   on:
+     push:  # 全ブランチで実行（意図しないブランチでもCI実行）
+   
+   # ✅ 推奨
+   on:
+     push:
+       branches: [main, develop, feature/*]
+   ```
+
+4. **バージョン指定の欠如**
+   ```yaml
+   # ❌ 避ける
+   - uses: actions/checkout  # バージョン未指定
+   
+   # ✅ 推奨
+   - uses: actions/checkout@v4  # 明示的なバージョン指定
+   ```
+
+## テンプレート
+
+### 基本的なテストワークフロー
+
+```yaml
+name: Test
+
+on:
+  push:
+    branches: [main, develop, feature/*, codex/**, copilot/**]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20.x]
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "npm"
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Build
+        run: npm run build:ci
+      
+      - name: Run tests
+        run: npm run test:ci
+```
+
+### CLI ツールのテストワークフロー
+
+```yaml
+name: Test
+
+on:
+  push:
+    branches: [main, develop, feature/*, codex/**, copilot/**]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20.x]
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "npm"
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Build
+        run: npm run build:ci
+      
+      - name: Run tests
+        run: npm run test:ci
+      
+      - name: Verify CLI executable
+        run: |
+          ./dist/cli.js --help
+      
+      - name: Test CLI functionality
+        run: |
+          # 実際のユースケースに基づいた動作確認
+          mkdir -p test-workspace
+          ./dist/cli.js [your-command] --option value
+          # 結果の検証
+```
+
+## 関連ルール
+
+- [GitHub Actions Testing Policy](./github-actions-no-tests.md) - ワークフローファイル自体のテストに関するポリシー
+- [テストタイムアウト設定](./timeout-configuration.md) - テスト実行時のタイムアウト設定
+
+## 参考資料
+
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [actions/setup-node](https://github.com/actions/setup-node)
+- [actions/checkout](https://github.com/actions/checkout)
+- [npm ci vs npm install](https://docs.npmjs.com/cli/v9/commands/npm-ci)
+
+このルールに従うことで、GitHub Actions のテストワークフローを一貫性のある、メンテナンスしやすい形で管理できます。

package/dist/cli.js

@@ -18461,7 +18461,25 @@ async function findYamlFilesRecursively(dir, baseDir = dir) {
     return yamlFiles;
 }
 /**
- * Lists available package presets
+ * Extracts description from a preset YAML file
+ * Reads the top-level 'description' field from the preset
+ */
+async function extractPresetDescription(presetPath) {
+    try {
+        const content = await fs.readFile(presetPath, "utf-8");
+        const data = YAML.parse(content);
+        // Return the description field if it exists
+        if (data?.description && typeof data.description === "string") {
+            return data.description.trim();
+        }
+    }
+    catch {
+        // Ignore file reading or parsing errors
+    }
+    return undefined;
+}
+/**
+ * Lists available package presets with descriptions
  */
 async function listPresets() {
     const packageRoot = findPackageRoot();
@@ -18474,12 +18492,36 @@ async function listPresets() {
             return;
         }
         // eslint-disable-next-line no-console
-        console.log("Available presets:");
-        yamlFiles.forEach((file) => {
+        console.log("Available presets:\n");
+        for (const file of yamlFiles) {
             const presetName = file.replace(/\.(yaml|yml)$/, "");
+            const presetPath = path.join(presetsDir, file);
+            const description = await extractPresetDescription(presetPath);
             // eslint-disable-next-line no-console
             console.log(`  :${presetName}`);
-        });
+            if (description) {
+                // Indent and wrap description text
+                const maxWidth = 70;
+                const words = description.split(" ");
+                let currentLine = "    ";
+                words.forEach((word) => {
+                    if (currentLine.length + word.length + 1 > maxWidth) {
+                        // eslint-disable-next-line no-console
+                        console.log(currentLine);
+                        currentLine = "    " + word;
+                    }
+                    else {
+                        currentLine += (currentLine === "    " ? "" : " ") + word;
+                    }
+                });
+                if (currentLine.trim()) {
+                    // eslint-disable-next-line no-console
+                    console.log(currentLine);
+                }
+                // eslint-disable-next-line no-console
+                console.log("");
+            }
+        }
     }
     catch (error) {
         // eslint-disable-next-line no-console

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aramassa/ai-rules",
-  "version": "0.5.3",
+  "version": "0.6.1",
   "description": "This repository collects guidelines and instructions for developing AI agents. It contains documents covering communication rules, coding standards, testing strategies, and general operational practices.",
   "workspaces": [
     "packages/extract",

package/presets/basic.yaml

@@ -1,3 +1,5 @@
+description: すべてのプロジェクトタイプで共通して必要となる基本的なinstruction構成です。
+
 recipe:
   - title: Communication Rules
     frontmatter:

package/presets/chatmodes.yaml

@@ -1,5 +1,7 @@
 config:
   baseDir: .github/chatmodes
+description: AI対話支援機能（chatmodes）をプロジェクトに統合するための設定です。
+
 recipe:
   - title: Instruction Improve Chatmode
     frontmatter:

package/presets/chrome-extension.yaml

@@ -1,3 +1,5 @@
+description: Chrome Extension（Manifest V3）開発プロジェクト向けの包括的なinstruction構成です。
+
 recipe:
   - import: :basic
   - title: Chrome Extension Manifest V3 - General Architecture & Security

package/presets/docs-ai.yaml

@@ -1,3 +1,5 @@
+description: AI向けドキュメント生成のためのinstruction設定です。
+
 recipe:
   - title: Documentation for AI
     frontmatter:

package/presets/electron.yaml

@@ -1,3 +1,5 @@
+description: Electronアプリケーション開発のベストプラクティスとセキュリティガイドラインです。
+
 recipe:
   - title: Electron Development Best Practices
     frontmatter:

package/presets/github-actions/npm-publish.yaml

@@ -1,3 +1,5 @@
+description: npmパッケージのGitHub Actions公開ワークフローを実装するための設定です。
+
 recipe:
   - import: :basic
   - title: npm Package Publishing Workflow Rules

package/presets/github-actions/test.yaml

@@ -0,0 +1,18 @@
+description: GitHub Actionsのテストワークフローを実装するための設定です。
+
+recipe:
+  - import: :basic
+  - title: GitHub Actions Test Workflow Rules
+    frontmatter:
+      "@type": true
+      "@category": true
+      "@focus": true
+      description: |
+        Implementation rules for test workflows with GitHub Actions.
+        Covers workflow triggers, Node.js version matrix, build and test execution order,
+        and comprehensive validation including build artifact verification.
+      applyTo: ".github/workflows/*.{yml,yaml}"
+    out: ./.github/instructions/github-actions-test.instructions.md
+    type: test
+    category: github-actions
+    focus: test-workflow

package/presets/infrastructure-ansible.yaml

@@ -1,3 +1,5 @@
+description: インフラストラクチャ管理とAnsibleを使用したプロジェクト向けの設定です。
+
 recipe:
   - title: Infrastructure General Principles
     frontmatter:

package/presets/monorepo/nodejs.yaml

@@ -1,3 +1,5 @@
+description: Node.js モノレポ環境でのワークスペース管理ルールです。
+
 config:
   baseDir: .github/instructions
 

package/presets/monorepo/typescript.yaml

@@ -1,3 +1,5 @@
+description: TypeScript モノレポ環境でのプロジェクト参照とワークスペース管理ルールです。
+
 config:
   baseDir: .github/instructions
 

package/presets/prompts/prompt-creation.yaml

@@ -1,3 +1,5 @@
+description: AI向けプロンプト作成のための包括的なルールとガイドラインです。
+
 config:
   baseDir: .github/prompts
 recipe:

package/presets/prompts/todo-planning.yaml

@@ -1,3 +1,5 @@
+description: プロジェクトのTODO計画を管理するためのワークフローとガイドラインです。
+
 config:
   baseDir: .github/prompts
 recipe:

package/presets/typescript.yaml

@@ -1,3 +1,5 @@
+description: TypeScriptプロジェクト向けの標準的なinstruction構成です。
+
 recipe:
   - import: :basic
   - import: :docs-ai