create-einja-app 0.3.1 → 0.3.2

package/templates/default/docs/plans/optimized-watching-sprout.md

@@ -0,0 +1,149 @@
+# Plan: `@einja:seed` → `@einja:project-private` リネーム＋機能拡張
+
+## Context
+
+einja CLIのsync機能で配布されるmdファイルに、利用者が「プロジェクト固有コンテンツ」を追記できる領域を明示的に提供したい。
+
+**現状の問題:**
+- `@einja:seed` はマーカー名が機能を表していない（「種」より「プロジェクト固有領域」が正しい）
+- 一部ファイル（新規3ファイル等）にseedセクションがない
+- `.claude/` 配下にマーカーがなく、利用者がどこに追記できるか不明
+- seedのみ（managedなし）だと本文がunmanaged扱いになりテンプレート更新が反映されない
+
+**解決策:**
+1. `@einja:seed` → `@einja:project-private` に完全リネーム
+2. 利用者リポジトリの旧マーカーはsync時に自動マイグレーション
+3. managedなしファイルでも使えるよう挙動を拡張
+4. `.claude/` 配下の全配布対象ファイルにproject-privateセクション追加
+
+## 挙動
+
+### managed + project-private（docs/einja/ 等）
+従来のseedと同じ。マーカーベース処理内でローカル版を保持。
+
+### project-privateのみ（managedなし。.claude/ 等）— 新規挙動
+```
+1. base版・テンプレート・ローカルの3つからproject-privateセクションを抽出
+2. 残りの本文を3方向マージで処理（テンプレート更新が反映される）
+3. ローカル版のproject-privateセクションをファイル末尾に再付加
+4. ローカルにproject-privateがなければテンプレート版をseed（マーカーペアが存在すれば空でも「存在する」扱い）
+```
+
+### 自動マイグレーション
+sync時にローカルファイルで `@einja:seed` を検出したら、処理前に自動で `@einja:project-private` にリネーム。
+
+## 変更対象ファイル
+
+### Phase 1: sync engine リネーム＋拡張
+
+| ファイル | 変更内容 |
+|---------|---------|
+| `packages/cli/src/types/sync.ts` | `MarkerSectionType` の `"seed"` → `"project-private"`。`MarkerErrorType` の `"seed_without_id"` → `"project_private_without_id"`。`JsonPathsConfigSchema` の `seed` → `project-private`（キー名変更） |
+| `packages/cli/src/lib/sync/marker-processor.ts` | 全パターンの `seed` → `project-private` 置換。`extractProjectPrivateSections(content)` / `reattachProjectPrivateSections(content, sections)` / `hasManagedMarkers(content)` メソッド追加。`migrateLegacySeedMarkers(content)` メソッド追加（自動マイグレーション用） |
+| `packages/cli/src/lib/sync/seed-synchronizer.ts` → **`project-private-synchronizer.ts`** にリネーム | クラス名・メソッド名リネーム + managedなしファイル用の同期ロジック追加 |
+| `packages/cli/src/lib/sync/json-processor.ts` | `isPathSeed()` → `isPathProjectPrivate()` 等、seed参照12箇所をリネーム |
+| `packages/cli/src/commands/sync.ts` | import変更、`hasMarkers()` の `seed` → `project-private`、managedなしファイルの分岐追加、マイグレーション処理の呼び出し |
+| `packages/cli/src/lib/sync/metadata-manager.ts` | `.einja-sync.json` のマイグレーション処理追加（`jsonPaths.seed` → `jsonPaths["project-private"]`） |
+
+### Phase 2: テスト リネーム＋追加
+
+| ファイル | 変更内容 |
+|---------|---------|
+| `packages/cli/src/lib/sync/marker-processor.test.ts` | 全テストの `seed` → `project-private` + 抽出・再付加テスト追加 + マイグレーションテスト追加 |
+| `packages/cli/src/lib/sync/integration.test.ts` | seed → project-private + managedなしファイルの統合テスト追加（下記シナリオ） |
+| `packages/cli/src/lib/sync/metadata-manager.test.ts` | seed参照置換 + .einja-sync.jsonマイグレーションテスト |
+| `packages/cli/src/lib/sync/conflict-reporter.test.ts` | seed参照があれば置換 |
+| `packages/cli/src/lib/sync/json-processor.test.ts`（存在すれば） | seed参照置換 |
+
+**統合テストシナリオ:**
+- 初回sync: project-privateのみファイル → テンプレート全体がコピーされる
+- 2回目sync: テンプレート本文変更 → 3方向マージで本文更新、project-private保持
+- 2回目sync: ローカル本文も変更 → 3方向マージでコンフリクト検出、project-private保持
+- project-private空セクションの処理（マーカーペアのみ → 存在扱い）
+- 旧 `@einja:seed` マーカー → 自動マイグレーション → 正常処理
+
+### Phase 3: create-einja-app対応
+
+| ファイル | 変更内容 |
+|---------|---------|
+| `packages/create-einja-app/src/utils/merger.ts` | ローカル `MarkerSection` 型、`parseStartMarker()`、`parseEndMarker()` 含め `seed` → `project-private` 置換 + managedなしファイル対応 |
+| `packages/create-einja-app/tests/unit/utils/merger.test.ts` | テスト置換＋追加 |
+
+### Phase 4: 配布対象ファイルのマーカー更新
+
+#### 4-a: 既存26ファイルの `@einja:seed` → `@einja:project-private` 置換
+
+`docs/einja/steering/`, `docs/einja/instructions/`, `docs/einja/memory/` 配下の全seedマーカー付きファイル
+
+#### 4-b: seedセクション未設置の3ファイルに新規追加
+
+| ファイル | ID |
+|---------|-----|
+| `docs/einja/steering/development/coding-standards.md` | `coding-standards-project` |
+| `docs/einja/steering/development/component-design.md` | `component-design-project` |
+| `docs/einja/steering/development/playwright-guidelines.md` | `playwright-guidelines-project` |
+
+#### 4-c: .claude/skills/einja-*/（SKILL.mdのみ、11ファイル）
+
+末尾にproject-privateセクション新規追加。ID: `{skill名}-project`
+
+#### 4-d: .claude/agents/einja/（全17ファイル）
+
+末尾にproject-privateセクション新規追加。ID: `{agent名}-project`
+
+#### 4-e: .claude/commands/einja/（全7ファイル）
+
+末尾にproject-privateセクション新規追加。ID: `{command名}-project`
+
+#### 4-f: CLAUDE.md
+
+`@einja:excluded` セクションの直前にproject-privateセクション追加（ID: `claude-md-project`）
+
+#### 4-g: skill-creatorのドキュメント例示更新
+
+`.claude/skills/einja-skill-creator/SKILL.md` と `scripts/init_skill.py` 内のseed例示をproject-privateに更新
+
+#### 4-h: ドキュメント内のseed参照更新
+
+| ファイル | 内容 |
+|---------|------|
+| `packages/cli/docs/MARKER_SPECIFICATION.md`（存在すれば） | seed → project-private |
+| `packages/cli/README.md` | seed参照があれば更新 |
+| `packages/create-einja-app/README.md` | seed参照があれば更新 |
+| CHANGELOG内のseed参照 | 歴史的記録のため**据え置き** |
+
+### Phase 5: ビルド＋最終確認
+
+1. `pnpm --filter @einja/dev-cli build` でpresets/defaultに反映
+2. `pnpm prepush`（lint + typecheck + test）
+3. `grep -r "@einja:seed" --include="*.ts" --include="*.md" --include="*.py" --include="*.json" --include="*.yml"` — seed残存なし確認（CHANGELOG除く）
+
+## project-privateセクションの共通フォーマット
+
+```markdown
+---
+
+<!-- @einja:project-private:start id="{ID}" -->
+## プロジェクト固有の設定
+
+<!-- このセクションはプロジェクト固有の内容を追記する場所です -->
+<!-- einja syncで上書きされません -->
+<!-- @einja:project-private:end -->
+```
+
+## 除外対象（project-privateを追加しない）
+
+| ファイル | 理由 |
+|---------|------|
+| `.claude/skills/einja-*/references/*.md` | リファレンス資料 |
+| `.claude/skills/einja-*/templates/*.md` | テンプレート定義 |
+| `docs/einja/example/**/*.md` | サンプル教材 |
+| `docs/einja/templates/README.md` | テンプレートREADME |
+
+## 検証方法
+
+1. `pnpm --filter @einja/dev-cli test` — CLIの全テストパス
+2. `pnpm --filter create-einja-app test` — create-einja-appの全テストパス
+3. `pnpm prepush` — lint + typecheck + test パス
+4. `grep -r "@einja:seed" --include="*.ts" --include="*.md" --include="*.py" --include="*.json" --include="*.yml"` — seed残存なし（CHANGELOG除く）
+5. 統合テストシナリオ（Phase 2参照）

package/templates/default/docs/plans/peaceful-beaming-toast-agent-a292da6.md

@@ -0,0 +1,288 @@
+# プリセットファイルのハードコード値調査レポート
+
+## 調査目的
+`einja init` で配布されるプリセットファイル群（`packages/cli/presets/default/`）に、テンプレートリポジトリ（einja-management-template）固有のハードコードされた値が含まれていないかを調査する。
+
+## 調査対象ファイル
+
+### 1. scripts/ 配下のファイル
+
+#### ✅ scripts/init.sh
+**問題なし** - 汎用的なスクリプト
+- package.jsonから動的にNode/pnpmバージョンを取得
+- 環境依存の値なし
+
+#### ✅ scripts/env.ts
+**問題なし** - 汎用的な環境変数ウィザード
+- ファイルパスは相対パス（`process.cwd()`ベース）
+- 環境変数名は一般的な命名（DATABASE_URL, AUTH_SECRET, GITHUB_TOKEN等）
+
+#### ✅ scripts/env-show.ts
+**問題なし** - 汎用的な表示スクリプト
+- 環境設定は共通定義（ENVIRONMENTS配列）を使用
+- 固有の値なし
+
+#### ✅ scripts/env-rotate-secrets.ts
+**問題なし** - 汎用的な秘密鍵ローテーションスクリプト
+- 共通ライブラリ（env-common.ts）を使用
+- 固有の値なし
+
+#### ✅ scripts/setup-dev.ts
+**問題なし** - 汎用的なセットアップスクリプト
+- `process.cwd()`で現在ディレクトリを基準
+- ポート番号等は環境変数や設定ファイルから動的取得（推測）
+
+#### ⚠️ scripts/worktree/dev.ts
+**潜在的な問題あり**
+- **L14**: `import type { AppConfig, WorktreeConfig } from "../../packages/config/src/worktree-config.js";`
+  - **問題**: テンプレートリポジトリ固有のパッケージパス構造に依存
+  - **影響**: 他プロジェクトがこの構造を持たない場合、import失敗でエラー
+- **L101**: `config = loadWorktreeConfig();`
+  - **問題**: worktree.config.jsonの存在を前提としている
+  - **影響**: 設定ファイル未作成時のエラーハンドリングが不明確
+
+#### ✅ scripts/lib/env-common.ts
+**問題なし** - 汎用的な共通ライブラリ
+- 環境設定定義は標準的（local, develop, preview, production, ci）
+- 固有の値なし
+
+---
+
+### 2. .envrc
+**問題なし** - 汎用的なdirenv設定
+- 相対パスのみ（`.env`, `.env.personal`）
+- git worktree対応の汎用ロジック
+
+---
+
+### 3. .mcp.json
+**問題なし** - 汎用的なMCP設定
+- MCPサーバー設定は汎用的
+- `${GITHUB_TOKEN}` は環境変数参照（動的）
+
+---
+
+### 4. CLAUDE.md.template
+**問題なし** - テンプレート化済み
+- `@einja:excluded:start` ~ `@einja:excluded:end` で囲まれた部分は配布時に除外される
+- 変数プレースホルダーは未検出（要確認: テンプレート変換処理の詳細）
+
+---
+
+### 5. preset.yaml
+**問題なし** - プリセット定義
+- 変数定義セクション（`variables:`）でユーザーカスタマイズ可能
+- `PROJECT_NAME`, `INSTALL_COMMAND` 等のプレースホルダーを提供
+
+---
+
+### 6. .claude/settings.json
+**問題なし** - 汎用的なClaude設定
+- パーミッション設定は汎用的
+- フック定義のパスは `$CLAUDE_PROJECT_DIR` を使用（動的）
+
+---
+
+## 追加調査結果
+
+### grep検索結果
+
+#### 1. テンプレートリポジトリ名の検出
+```bash
+grep -r "einja-management-template" packages/cli/presets/default/
+```
+**検出箇所**:
+- `docs/einja/steering/README.md`:
+  ```
+  詳細な仕様は [CLIのマーカー仕様書](https://github.com/einja-inc/einja-management-template/blob/main/packages/cli/docs/MARKER_SPECIFICATION.md) を参照してください。
+  ```
+  - **問題**: ハードコードされたGitHubリポジトリURL
+  - **影響**: 外部リンクが切れる（他プロジェクトには無関係なリンク）
+  - **重要度**: 🟡 中（ドキュメントの参照リンクのみ）
+
+#### 2. ハードコードされたポート番号の検出
+```bash
+grep -r "localhost:300[0-9]" packages/cli/presets/default/
+```
+**検出箇所** (多数):
+
+| ファイル | 行内容 | 重要度 |
+|---------|--------|--------|
+| `.claude/agents/einja/specs/spec-qa-generator.md` | `http://localhost:3000/auth/login` | 🟡 中 |
+| `docs/einja/instructions/environment-setup.md` | `NEXTAUTH_URL="http://localhost:3000"` | 🔴 高 |
+| `docs/einja/example/specs/issues/issue999-example-task/qa-tests/README.md` | `http://localhost:3000` (複数箇所) | 🟢 低（例示） |
+| `docs/einja/steering/acceptance-criteria-and-qa-guide.md` | `http://localhost:3000` (複数箇所) | 🟡 中 |
+| `docs/einja/steering/development/testing-strategy.md` | `baseURL: 'http://localhost:3000'` | 🟡 中 |
+
+**問題点**:
+- テンプレート固有のポート番号（3000）がハードコード
+- 実際のプロジェクトは異なるポート（例: 3001, 8080等）を使用する可能性
+- Worktree環境では動的ポート割り当てが必要
+
+#### 3. ハードコードされたリポジトリURLの検出
+```bash
+grep -r "github.com/einja-inc" packages/cli/presets/default/
+```
+**検出箇所**:
+- `docs/einja/steering/README.md`: 同上（問題1と同じ）
+
+#### 4. 開発者固有の絶対パスの検出
+```bash
+grep -r "/Users/kzp" packages/cli/presets/default/
+```
+**結果**: 検出なし ✅
+
+---
+
+## 修正が必要な箇所
+
+### 🔴 高優先度1: docs/einja/instructions/environment-setup.md
+
+#### 問題: ハードコードされたポート番号
+```
+NEXTAUTH_URL="http://localhost:3000"
+```
+
+**修正案**:
+- 変数プレースホルダーに置き換え:
+  ```
+  NEXTAUTH_URL="http://localhost:${PORT:-3000}"
+  ```
+- またはドキュメント内で「ポート番号は環境に応じて変更してください」と注記
+
+---
+
+### 🔴 高優先度2: scripts/worktree/dev.ts
+
+#### 問題1: packages/config へのハードコードされた依存
+```typescript
+import type { AppConfig, WorktreeConfig } from "../../packages/config/src/worktree-config.js";
+```
+
+**修正案**:
+- オプション1（推奨）: 型定義をスクリプト内にインライン化
+  ```typescript
+  interface AppConfig {
+    id: string;
+    portRangeStart: number;
+    rangeSize: number;
+  }
+  interface WorktreeConfig {
+    apps: AppConfig[];
+    postgres: { port: number; containerName: string };
+  }
+  ```
+- オプション2: worktree.config.json から型を動的に推論
+- オプション3: 設定ファイルのパスを環境変数で指定可能にする
+
+#### 問題2: loadWorktreeConfig() の依存
+```typescript
+import { loadWorktreeConfig } from "../../packages/config/src/worktree-config-loader.js";
+```
+
+**修正案**:
+- `loadWorktreeConfig()` の実装を `dev.ts` 内にインライン化
+- または、設定ファイルが存在しない場合のデフォルト値を提供
+
+---
+
+### 🟡 中優先度: ドキュメント内のポート番号
+
+#### 問題箇所
+- `.claude/agents/einja/specs/spec-qa-generator.md`
+- `docs/einja/steering/acceptance-criteria-and-qa-guide.md`
+- `docs/einja/steering/development/testing-strategy.md`
+
+**修正案**:
+- 例示部分は `http://localhost:${PORT}` のように変数表記に変更
+- または「例: localhost:3000（実際のポートは環境に応じて変更）」と注記を追加
+
+---
+
+### 🟡 中優先度: docs/einja/steering/README.md
+
+#### 問題: 外部リンク
+```
+https://github.com/einja-inc/einja-management-template/blob/main/packages/cli/docs/MARKER_SPECIFICATION.md
+```
+
+**修正案**:
+- 相対パス参照に変更:
+  ```
+  [CLIのマーカー仕様書](../../../packages/cli/docs/MARKER_SPECIFICATION.md)
+  ```
+- または汎用的なドキュメントリンクに変更
+
+---
+
+## 推奨アクション
+
+### 優先度1: 環境依存値の変数化
+1. **docs/einja/instructions/environment-setup.md**
+   - ポート番号を変数化（`${PORT:-3000}`）
+   - 環境変数設定ガイドを追記
+
+### 優先度2: スクリプトの依存解消
+2. **scripts/worktree/dev.ts**
+   - packages/config への依存を解消
+   - worktree.config.json のスキーマ定義をスクリプト内に含める
+   - 設定ファイル不在時のフォールバック処理を追加
+
+### 優先度3: ドキュメントの汎用化
+3. **ドキュメント全体**
+   - 例示のポート番号に「環境依存」の注記を追加
+   - 外部リンクを相対パス参照に変更
+   - テンプレート変換処理（CLAUDE.md.template → CLAUDE.md）の詳細調査
+
+### 優先度4: 検証・ドキュメント化
+4. **追加タスク**
+   - preset.yaml の変数置換ロジックの検証
+   - プリセットファイルのカスタマイズガイド作成
+   - einja init 時の変数入力プロンプトの設計
+
+---
+
+## 調査結果サマリー
+
+### ✅ 問題なし（11ファイル）
+- scripts/init.sh
+- scripts/env.ts
+- scripts/env-show.ts
+- scripts/env-rotate-secrets.ts
+- scripts/setup-dev.ts
+- scripts/lib/env-common.ts
+- .envrc
+- .mcp.json
+- CLAUDE.md.template
+- preset.yaml
+- .claude/settings.json
+
+### ⚠️ 修正必要（5ファイル）
+
+| ファイル | 問題 | 重要度 |
+|---------|------|--------|
+| scripts/worktree/dev.ts | packages/config への依存 | 🔴 高 |
+| docs/einja/instructions/environment-setup.md | ポート番号ハードコード | 🔴 高 |
+| docs/einja/steering/README.md | 外部リンク | 🟡 中 |
+| .claude/agents/einja/specs/spec-qa-generator.md | ポート番号ハードコード | 🟡 中 |
+| docs/einja/steering/acceptance-criteria-and-qa-guide.md | ポート番号ハードコード | 🟡 中 |
+| docs/einja/steering/development/testing-strategy.md | ポート番号ハードコード | 🟡 中 |
+
+### 🟢 例示のみ（修正推奨だが低優先度）
+- docs/einja/example/specs/issues/issue999-example-task/qa-tests/README.md
+
+---
+
+## 次のステップ
+
+1. **ユーザー確認**
+   - この調査結果をユーザーに報告
+   - 修正方針の承認を得る
+
+2. **修正実施**
+   - 承認後、優先度順に修正タスクを実行
+   - コミット・プッシュ
+
+3. **検証**
+   - einja init で新規プロジェクト作成テスト
+   - プリセット適用後の動作確認