create-einja-app 0.3.1 → 0.3.2

package/templates/default/docs/plans/import-alias-refactor.md

@@ -0,0 +1,75 @@
+# インポートエイリアス書き換え: packages/server-core
+
+## 実施日
+2026-02-26
+
+## 目的
+packages/server-core の相対パスインポートを `@/` エイリアスに統一し、コードの可読性と保守性を向上させる。
+
+## 変更ファイル一覧
+
+### 1. tsconfig.json 修正
+
+#### `packages/server-core/tsconfig.json`
+- `paths` エイリアスを追加: `@/*` → `./src/*`
+
+### 2. インポートパス書き換え (8ファイル)
+
+| ファイル | 変更内容 |
+|---------|---------|
+| `src/domain/entities/User.test.ts` | `../../testing` → `@/testing` |
+| `src/domain/repository-interfaces/IUserRepository.ts` | `../../core/result`, `../entities/User` → `@/` 形式 |
+| `src/infrastructure/database/mappers/UserMapper.ts` | `../../../domain/entities/User` → `@/domain/entities/User` |
+| `src/infrastructure/database/repositories/UserRepository.ts` | 5箇所の相対パス → `@/` 形式 |
+| `src/infrastructure/database/mappers/UserMapper.test.ts` | `../../../` 形式 → `@/` 形式 |
+| `src/infrastructure/database/repositories/UserRepository.test.ts` | `../../../` 形式、`../client` → `@/` 形式 |
+| `src/testing/factories/index.ts` | `../../__generated__/fabbrica` → `@/__generated__/fabbrica` |
+| `src/testing/factories/user.factory.ts` | 4箇所の相対パス → `@/` 形式 |
+
+### 3. モノレポ対応 (2ファイル)
+
+#### `apps/web/tsconfig.json`
+- `paths` に `@/*` のマッピングを拡張: `["./src/*", "../../packages/server-core/src/*"]`
+- server-core の `@/` エイリアスを解決できるよう設定
+
+#### `apps/admin/tsconfig.json`
+- 同上
+
+## 検証結果
+
+### TypeScript 型チェック
+```bash
+pnpm prepush:typecheck
+```
+✅ 成功 - モジュール解決エラーなし
+
+### Vitest テスト
+```bash
+pnpm --filter @repo/server-core test
+```
+✅ 全59テスト成功
+
+### 影響範囲
+- **破壊的変更**: なし（内部的なインポートパスの変更のみ）
+- **外部API**: 変更なし
+- **ビルド**: 正常
+
+## 技術メモ
+
+### モノレポでのエイリアス解決
+- `@/` エイリアスは **パッケージ内部の相対パス解決** のためのもの
+- 他パッケージから参照する場合、参照元の tsconfig にもエイリアスマッピングが必要
+- 解決方法:
+  1. TypeScript Project References を使用
+  2. 参照元の `paths` に参照先のエイリアスを追加（今回採用）
+
+### vitest.config.ts
+- 既に `alias: { "@": path.resolve(__dirname, "./src") }` が設定済み
+- 変更不要
+
+## 残存課題
+なし
+
+## 次のステップ
+- 他パッケージでも同様に `@/` エイリアス導入を検討
+- `@repo/front-core` などでも統一

package/templates/default/docs/plans/lazy-percolating-sloth-agent-abda679.md

@@ -0,0 +1,346 @@
+# Plan Review: `/sync` コマンド
+
+## ✅ 総合評価: **実装可能（重要な修正が必要）**
+
+提案されたPlanは基本的に実行可能ですが、**カテゴリ重複問題**という重大な見落としがあります。
+
+---
+
+## 1. 実現可能性: ⚠️ 一部修正が必要
+
+### 1.1 CLI検出ロジック: ✅ 問題なし
+
+```bash
+npx @einja/dev-cli --version 2>/dev/null
+npx create-einja-app --version 2>/dev/null
+```
+
+この方法で両CLIの存在を確認できます。
+
+### 1.2 dry-runの実行: ✅ オプション構文は正しい
+
+| CLI | dry-run | yes | json | categories |
+|-----|---------|-----|------|-----------|
+| dev-cli | `-d, --dry-run` ✅ | `-y, --yes` ✅ | `-j, --json` ✅ | `-o, --only <categories>` ✅ |
+| create-einja-app | `--dry-run` ✅ | なし ⚠️ | なし ⚠️ | `--categories <categories>` ✅ |
+
+**注意**: create-einja-appには `--yes` オプションがないため、dry-run後の実行確認プロンプトは表示されない（`--categories`指定時は対話なしで即実行される）
+
+### 1.3 カテゴリ指定時の対話プロンプトスキップ: ✅ 正しい
+
+create-einja-appの実装（sync.ts:168-184行目）:
+
+```typescript
+if (options.categories) {
+  // --categories指定時: 対話なし
+  categories = options.categories as SyncCategory[];
+  logger.info(`指定されたカテゴリ: ${categories.join(", ")}`);
+}
+```
+
+**結論**: ✅ `--categories` 指定時は対話プロンプトがスキップされる（Planの想定どおり）
+
+---
+
+## 2. ユーザー体験: ✅ 概ね良好
+
+### 2.1 フロー全体
+
+```
+CLI検出 → カテゴリ選択 → dry-run → 実行確認 → sync → コンフリクト解消 → 完了
+```
+
+このフローは直感的で使いやすい。
+
+### 2.2 改善提案: カテゴリ選択UIの強化
+
+**現状のPlan**:
+> multiSelect=true で複数選択
+
+**推奨する具体的なUI（2段階選択）**:
+
+**第1段階: 簡易/詳細選択**
+
+```yaml
+AskUserQuestion:
+  question: "同期方法を選択してください"
+  header: "テンプレート同期"
+  options:
+    - label: "📦 推奨セット（両CLIのデフォルト）"
+      description: "dev-cli全カテゴリ + create-einja-app推奨カテゴリ"
+    - label: "⚙️ カスタム選択"
+      description: "個別にカテゴリを選択する"
+```
+
+**第2段階（カスタム選択時のみ）**:
+
+```yaml
+AskUserQuestion:
+  question: "同期するカテゴリを選択してください（複数選択可）"
+  header: "カテゴリ選択"
+  multiSelect: true
+  options:
+    # dev-cli カテゴリ
+    - label: "📝 commands (dev-cli)"
+      description: "Claude Codeコマンド (.claude/commands/)"
+      default: true
+    - label: "🤖 agents (dev-cli)"
+      description: "Claude Codeエージェント (.claude/agents/)"
+      default: true
+    - label: "🎯 skills (dev-cli)"
+      description: "Claude Codeスキル (.claude/skills/)"
+      default: true
+    - label: "🪝 hooks (dev-cli)"
+      description: "Claude Codeフック (.claude/hooks/)"
+      default: true
+    - label: "📄 docs - Claude関連 (dev-cli)"
+      description: "docs/einja/ 配下のドキュメント"
+      default: true
+    - label: "🔧 env (dev-cli)"
+      description: ".envrc ファイル"
+      default: true
+    - label: "⚙️ tools (dev-cli)"
+      description: ".vscode/settings.json ファイル"
+      default: true
+
+    # create-einja-app カテゴリ
+    - label: "🌍 env (create-einja-app)"
+      description: ".env.example, .node-version, .volta/ 等"
+      default: true
+    - label: "🛠️ tools (create-einja-app)"
+      description: "biome.json, .prettierrc, .editorconfig, .vscode/ 等"
+      default: true
+    - label: "📄 docs - プロジェクト全体 (create-einja-app)"
+      description: "README.md, docs/ 全体"
+      default: true
+    - label: "🔐 git (create-einja-app)"
+      description: ".gitignore, .gitattributes"
+      default: true
+    - label: "🪝 git-hooks (create-einja-app)"
+      description: ".husky/ フック"
+      default: true
+    - label: "🐙 github (create-einja-app)"
+      description: ".github/workflows/, .github/actions/"
+      default: true
+    - label: "🐳 docker (create-einja-app)"
+      description: "Dockerfile*, docker-compose.yml"
+      default: true
+    - label: "📦 monorepo (create-einja-app)"
+      description: "turbo.json, pnpm-workspace.yaml"
+      default: true
+    - label: "📋 root-config (create-einja-app)"
+      description: "package.json, tsconfig.json"
+      default: true
+    - label: "📜 scripts (create-einja-app)"
+      description: "scripts/**"
+      default: true
+    - label: "🚫 apps (create-einja-app)"
+      description: "apps/** （通常は非推奨）"
+      default: false
+    - label: "🚫 packages (create-einja-app)"
+      description: "packages/** （通常は非推奨）"
+      default: false
+```
+
+---
+
+## 3. エッジケース: 🔴 重大な見落としあり
+
+### 3.1 片方のCLIのみインストール済みの場合: ✅ OK
+
+Planの記述どおり、検出されたCLIのみ使用すればよい。
+
+### 3.2 カテゴリ重複問題: 🔴 **重大な問題**
+
+**実装調査結果**:
+
+| カテゴリ | dev-cli | create-einja-app | 管理対象ファイル | 重複 |
+|---------|---------|------------------|-----------------|------|
+| commands | ✅ | ❌ | `.claude/commands/` | ❌ |
+| agents | ✅ | ❌ | `.claude/agents/` | ❌ |
+| skills | ✅ | ❌ | `.claude/skills/` | ❌ |
+| hooks | ✅ | ❌ | `.claude/hooks/` | ❌ |
+| **env** | ✅ `.envrc` | ✅ `.env*`, `.node-version`, `.volta/` | **異なるファイル** | ✅ |
+| **tools** | ✅ `.vscode/settings.json` | ✅ `biome.json`, `.prettierrc`, `.editorconfig`, `.vscode/` | **部分的に重複** | ⚠️ |
+| **docs** | ✅ `docs/einja/` | ✅ `README.md`, `docs/` | **異なる範囲** | ✅ |
+
+**重複カテゴリの詳細**:
+
+#### a) env: ファイルが異なる → 問題なし
+
+- dev-cli: `.envrc` のみ
+- create-einja-app: `.env.example`, `.env.local.example`, `.node-version`, `.nvmrc`, `.volta/`
+
+**結論**: ファイル重複なし。両方実行しても問題ない。
+
+#### b) tools: .vscode/settings.json が重複 → 🔴 **コンフリクトの可能性**
+
+- dev-cli: `.vscode/settings.json`
+- create-einja-app: `biome.json`, `.prettierrc`, `.editorconfig`, `.vscode/`（settings.jsonを含む）
+
+**問題**: 両方実行すると `.vscode/settings.json` が2回同期され、後者が上書きする可能性がある。
+
+**対策**:
+1. ユーザーにツールチップで警告表示
+2. 両方選択された場合、dev-cliのtools実行後にcreate-einja-appのtoolsをスキップ（または統合マージ）
+
+#### c) docs: 範囲が異なる → 問題なし
+
+- dev-cli: `docs/einja/` 配下のみ
+- create-einja-app: `README.md`, `docs/` 全体
+
+**結論**: 範囲が異なるため、両方実行しても問題ない（create-einja-appが上位集合）。
+
+---
+
+### 3.3 コンフリクト発生時のフロー: ⚠️ 詳細化が必要
+
+**Planの記述**:
+> コンフリクトがあれば `einja-conflict-resolver` Skill の手順に従って解消
+
+**問題点**:
+
+1. **conflict-resolver Skillは1ファイルずつユーザー確認を行う**（SKILL.md Step 2参照）
+2. sync操作でのコンフリクトは**gitコンフリクトではない**（マージマーカーが挿入されたファイル）
+3. conflict-resolverはgitコンフリクト専用（rebase/merge/cherry-pick）
+
+**推奨フロー**:
+
+```markdown
+### Step 5-A: コンフリクト検出
+
+1. dev-cliのJSON出力をパース:
+   ```json
+   {
+     "status": "partial_success",
+     "summary": { "conflicts": 3 }
+   }
+   ```
+
+2. create-einja-appの出力から検出:
+   ```
+   ⚠️ コンフリクト: 3ファイル
+   ```
+
+### Step 5-B: コンフリクト解消（簡易版）
+
+**オプション1: 自動マージ再試行**
+
+コンフリクトファイルを読み取り、マージマーカー（`<<<<<<<`, `=======`, `>>>>>>>`）を検出。
+各セクションの内容をユーザーに提示し、AskUserQuestionで解消方針を確認。
+
+**オプション2: conflict-resolverへ委譲（非推奨）**
+
+gitにコミット後、`git reset --soft HEAD^`で擬似的にコンフリクト状態を作り、
+conflict-resolverで解消。ただし、これは不自然なフローのため非推奨。
+
+**推奨**: オプション1の簡易版を実装
+```
+
+---
+
+## 4. create-einja-app syncの非対話実行: ✅ 確認済み
+
+**仕様確認結果**（commands/sync.ts:168-184行目）:
+
+```typescript
+if (options.categories) {
+  // --categories指定時: 対話なし
+  categories = options.categories as SyncCategory[];
+  logger.info(`指定されたカテゴリ: ${categories.join(", ")}`);
+}
+```
+
+**結論**: ✅ `--categories` 指定時は対話プロンプトをスキップする（Planの想定どおり）
+
+---
+
+## 5. 見落とし・追加検討事項
+
+### 5.1 エラーハンドリング: ⚠️ 不足
+
+**追加すべき項目**:
+
+- npxコマンド失敗時の処理（タイムアウト、権限エラー等）
+- 両CLIのバージョン不一致警告（古いバージョンの場合）
+- バックアップファイルの管理（両CLIが別々にバックアップを作成するため、復元時の競合）
+
+### 5.2 実行順序: ⚠️ 明示が必要
+
+**推奨順序**:
+
+1. dev-cli sync（Claude Code関連ファイル）
+2. create-einja-app sync（プロジェクト全体）
+
+**理由**: dev-cliが先にClaude Code環境を整備し、create-einja-appがプロジェクト全体を同期する方が自然な流れ。
+
+### 5.3 結果サマリーの統合: ⚠️ 不足
+
+**Planには結果サマリー表示があるが、詳細が不足**:
+
+```markdown
+### Step 6: 結果サマリー表示
+
+| CLI | カテゴリ | 成功 | スキップ | コンフリクト | 合計 |
+|-----|---------|------|---------|-------------|------|
+| dev-cli | commands, agents, skills | 15 | 2 | 0 | 17 |
+| create-einja-app | env, tools, git | 8 | 1 | 1 | 10 |
+| **合計** | | **23** | **3** | **1** | **27** |
+
+**コンフリクトファイル**:
+- `.vscode/settings.json` (tools重複)
+
+**次のステップ**:
+コンフリクトを解消してください: [解消手順へのリンク]
+```
+
+### 5.4 ビルド時のコピー: ✅ 確認済み
+
+Planに記載のとおり、`.claude/commands/einja/sync.md` は既存の `copy-presets.mjs` で自動的に `presets/default/.claude/commands/einja/sync.md` へコピーされる。
+
+**確認方法**:
+
+```bash
+# ビルド実行
+pnpm build
+
+# コピー確認
+ls presets/default/.claude/commands/einja/sync.md
+```
+
+---
+
+## 最終推奨事項
+
+### 必須修正
+
+1. **カテゴリ選択UIの詳細化**: dev-cli/create-einja-app でカテゴリ名が重複する場合、UI上で明示的に区別する
+2. **tools重複警告の実装**: 両方のtoolsカテゴリが選択された場合、`.vscode/settings.json` 重複を警告
+3. **コンフリクト解消フローの詳細化**: sync専用の簡易的なコンフリクト解消ロジックを記述（conflict-resolver Skillは不適切）
+
+### 推奨改善
+
+1. 実行順序の明示（dev-cli → create-einja-app）
+2. エラーハンドリングの追加
+3. 結果サマリーの統合表示
+
+### オプション
+
+1. 両CLIのバージョンチェック
+2. バックアップ管理の統合
+
+---
+
+## Plan修正案のサマリー
+
+| 項目 | 現状 | 推奨 |
+|-----|------|------|
+| カテゴリ選択UI | 簡易版 | 2段階選択（簡易/詳細） |
+| カテゴリ重複対応 | 未対応 | UI上で区別 + 警告表示 |
+| コンフリクト解消 | conflict-resolver委譲 | sync専用の簡易ロジック |
+| 実行順序 | 未定義 | dev-cli → create-einja-app |
+| 結果サマリー | 基本版 | 統合表示 + コンフリクト詳細 |
+
+---
+
+**最終結論**: このPlanは**実装可能**ですが、カテゴリ重複問題への対応とコンフリクト解消フローの詳細化が必須です。

package/templates/default/docs/plans/lazy-percolating-sloth.md

@@ -0,0 +1,151 @@
+# Plan: `/sync` コマンドの作成
+
+## Context
+
+利用者が別リポジトリでテンプレート更新を取り込む際、`npx @einja/dev-cli sync` と `npx create-einja-app sync` を手動実行する必要がある。これを Claude Code コマンド一発で選択式に実行できるようにする。
+
+## 作成ファイル
+
+**`.claude/commands/einja/sync.md`** — 1ファイルのみ
+
+## コマンド仕様
+
+### フロントマター
+
+```yaml
+---
+description: "テンプレート同期を実行。dev-cli/create-einja-appのsyncをカテゴリ選択式で実行し、コンフリクトも自動解消します"
+allowed-tools: Bash, AskUserQuestion, Read, Grep, Glob
+---
+```
+
+### 処理フロー
+
+#### Step 1: CLI検出
+
+```bash
+npx @einja/dev-cli --version 2>/dev/null
+npx create-einja-app --version 2>/dev/null
+```
+
+- 両方なし → エラー終了
+- 片方のみ → そちらだけ使用
+- 両方あり → 両方利用可能として進む
+
+#### Step 2: カテゴリ選択（AskUserQuestion）
+
+利用可能なCLIに応じて、**2段階**で選択肢を提示。
+
+**質問1: 同期ソースの選択**（両方利用可能な場合のみ）
+- dev-cli のみ（Claude Code関連ファイル）
+- create-einja-app のみ（プロジェクトテンプレート）
+- 両方
+
+**質問2: カテゴリ選択**（multiSelect=true）
+
+dev-cli と create-einja-app のカテゴリは**明確に区別して表示**する。
+
+| 表示名 | CLI | 対象 | デフォルト |
+|--------|-----|------|-----------|
+| [dev-cli] commands | dev-cli | `.claude/commands/` | ON |
+| [dev-cli] agents | dev-cli | `.claude/agents/` | ON |
+| [dev-cli] skills | dev-cli | `.claude/skills/` | ON |
+| [dev-cli] hooks | dev-cli | `.claude/hooks/` | ON |
+| [dev-cli] docs | dev-cli | `docs/einja/` | ON |
+| [dev-cli] env | dev-cli | `.envrc` | ON |
+| [dev-cli] tools | dev-cli | `.vscode/settings.json` | ON |
+| [create-app] env | create-app | `.env*`, `.node-version` | ON |
+| [create-app] tools | create-app | `biome.json`, `.prettierrc`, `.editorconfig` | ON |
+| [create-app] git | create-app | `.gitignore`, `.gitattributes` | ON |
+| [create-app] git-hooks | create-app | `.husky/` | ON |
+| [create-app] github | create-app | `.github/workflows/`, `.github/actions/` | ON |
+| [create-app] docker | create-app | `Dockerfile*`, `docker-compose*.yml` | ON |
+| [create-app] monorepo | create-app | `turbo.json`, `pnpm-workspace.yaml` | ON |
+| [create-app] root-config | create-app | `package.json`, `tsconfig.json` | ON |
+| [create-app] scripts | create-app | `scripts/` | ON |
+| [create-app] docs | create-app | `README.md`, `docs/` | ON |
+| [create-app] apps | create-app | `apps/**` | **OFF** |
+| [create-app] packages | create-app | `packages/**` | **OFF** |
+
+> **重複に関する注意**: dev-cli の `tools` は `.vscode/settings.json` のみ、create-app の `tools` は `biome.json` 等。`.vscode/` 配下は dev-cli 側が管理するため、create-app 側の tools から `.vscode/` を除外する旨を説明に含める。
+
+#### Step 3: dry-run で差分プレビュー
+
+選択されたカテゴリで dry-run を実行し、差分をユーザーに表示。
+
+```bash
+# dev-cli
+npx @einja/dev-cli sync --only <categories> --dry-run --yes
+
+# create-einja-app
+npx create-einja-app sync --categories <categories> --dry-run
+```
+
+#### Step 4: 実行確認 → sync実行
+
+差分プレビューを見せた上で、ユーザーに実行可否を確認。
+
+**実行順序: dev-cli → create-einja-app**（dev-cliがClaude Code設定を先に更新）
+
+```bash
+# dev-cli
+npx @einja/dev-cli sync --only <categories> --yes --json
+
+# create-einja-app
+npx create-einja-app sync --categories <categories>
+```
+
+dev-cli は `--json` で構造化出力を取得しパース。
+
+#### Step 5: コンフリクト検出 → 手動解消サポート
+
+- dev-cli: JSON出力の `status: "partial_success"` + `conflicts > 0` で検出
+- create-einja-app: 出力の「コンフリクト」文字列で検出
+
+**コンフリクト時の対応**（sync固有のコンフリクトはgitコンフリクトとは異なる）:
+1. コンフリクトファイルの一覧を表示
+2. 各ファイルの差分内容を `Read` で確認
+3. ユーザーに解決方針を確認（テンプレート優先 / ローカル優先 / 手動マージ）
+4. 方針に従って `Edit` で解消
+
+#### Step 6: 結果サマリー表示
+
+| 項目 | dev-cli | create-einja-app |
+|------|---------|------------------|
+| 成功 | N件 | N件 |
+| スキップ | N件 | N件 |
+| コンフリクト | N件 | N件 |
+
+#### Step 7: 結果詳細表示
+
+サマリーの後に、各ファイルの詳細結果を表示。
+
+```markdown
+### dev-cli sync 詳細
+  ✓ .claude/commands/einja/task-exec.md (更新)
+  ✓ .claude/skills/einja-coding-standards/SKILL.md (更新)
+  ⏭ .claude/agents/einja/task-executer.md (変更なし)
+  ⚠ .claude/hooks/einja/pre-commit.sh (コンフリクト → 解消済み)
+
+### create-einja-app sync 詳細
+  ✨ .github/workflows/ci.yml (新規)
+  ✓ biome.json (更新)
+  ⏭ .gitignore (変更なし)
+```
+
+- dev-cli: `--json` 出力の `files` 配列をパースして表示
+- create-einja-app: 標準出力から `✓` / `⚠️` / `スキップ` 行を抽出して表示
+
+## 実装の注意点
+
+- コマンドはマークダウンプロンプト（Claude Codeへの指示書）として書く
+- 実際のロジックはClaude Codeが解釈して実行する
+- `npx` 経由で実行（利用者側にインストール不要）
+- create-einja-app sync には `--yes` がないが、`--categories` 指定時は対話プロンプトをスキップする
+- `.vscode/` の重複管理: dev-cli 側で管理。create-app の tools を選択してもClaude Codeが `.vscode/` 以外のファイルのみ対象とする旨を指示
+
+## 検証方法
+
+1. `.claude/commands/einja/sync.md` が正しいフロントマター形式であること
+2. このリポジトリで `/sync` を実行し、フローが正常に動作すること（CLI検出 → カテゴリ選択 → dry-run → 実行）
+3. ビルド時に `presets/default/.claude/commands/einja/sync.md` へ自動コピーされること（既存のcopy-presets.mjsで対応済み）