@sk8metal/michi-cli 0.5.0 → 0.8.0

package/scripts/utils/spec-archiver.ts

@@ -0,0 +1,260 @@
+/**
+ * 仕様書アーカイブユーティリティ
+ * 完了した仕様書を .kiro/specs/archive/ に移動する
+ */
+
+import { existsSync, renameSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+import { validateFeatureName as validateFeatureNameStrict } from './feature-name-validator.js';
+
+export interface ArchiveResult {
+  success: boolean;
+  feature: string;
+  archivePath?: string;
+  error?: string;
+}
+
+export interface SpecInfo {
+  feature: string;
+  phase: string;
+  archived: boolean;
+  archivedAt?: string;
+  hasReleaseNotes: boolean;
+  archivePath?: string;
+}
+
+/**
+ * featureName のバリデーション
+ * - kebab-case形式の検証（既存のバリデータを使用）
+ * - パストラバーサル攻撃を防止（追加のセキュリティチェック）
+ * @throws Error 不正な文字が含まれる場合
+ */
+function validateFeatureName(featureName: string): void {
+  // 空文字チェック（最初にチェック）
+  if (!featureName || featureName.trim().length === 0) {
+    throw new Error('Feature name cannot be empty');
+  }
+
+  // パストラバーサル攻撃を防ぐ（セキュリティチェック）
+  if (featureName.includes('..') ||
+      featureName.includes('/') ||
+      featureName.includes('\\') ||
+      featureName.startsWith('.')) {
+    throw new Error(`Invalid feature name: path traversal detected in "${featureName}"`);
+  }
+
+  // kebab-case形式の厳密な検証（既存のバリデータを使用）
+  const result = validateFeatureNameStrict(featureName);
+  if (!result.valid) {
+    throw new Error(result.errors.join('\n'));
+  }
+}
+
+/**
+ * 仕様書がアーカイブ可能かチェック
+ */
+export function canArchiveSpec(
+  featureName: string,
+  projectRoot: string = process.cwd()
+): { canArchive: boolean; reason?: string } {
+  try {
+    validateFeatureName(featureName);
+  } catch (error) {
+    return {
+      canArchive: false,
+      reason: error instanceof Error ? error.message : 'Invalid feature name',
+    };
+  }
+
+  const specDir = resolve(projectRoot, `.kiro/specs/${featureName}`);
+
+  if (!existsSync(specDir)) {
+    return { canArchive: false, reason: 'Spec not found' };
+  }
+
+  // spec.json を読み込み
+  const specJsonPath = resolve(specDir, 'spec.json');
+  if (!existsSync(specJsonPath)) {
+    return { canArchive: false, reason: 'spec.json not found' };
+  }
+
+  try {
+    const specContent = JSON.parse(readFileSync(specJsonPath, 'utf-8'));
+
+    // 既にアーカイブ済みかチェック
+    if (specContent.archived) {
+      return { canArchive: false, reason: 'Already archived' };
+    }
+
+    // phase チェック
+    if (specContent.phase !== 'implementation-complete') {
+      return {
+        canArchive: false,
+        reason: `Phase is ${specContent.phase || 'unknown'}, not implementation-complete`,
+      };
+    }
+
+    // release-notes チェック
+    const files = readdirSync(specDir);
+    const hasReleaseNotes = files.some(f => f.startsWith('release-notes-'));
+
+    if (!hasReleaseNotes) {
+      return { canArchive: false, reason: 'No release notes found' };
+    }
+
+    return { canArchive: true };
+  } catch (error) {
+    return {
+      canArchive: false,
+      reason: `Error reading spec.json: ${error instanceof Error ? error.message : 'Unknown error'}`,
+    };
+  }
+}
+
+/**
+ * 仕様書をアーカイブ
+ */
+export function archiveSpec(
+  featureName: string,
+  options?: { reason?: string },
+  projectRoot: string = process.cwd()
+): ArchiveResult {
+  // Defense in depth: 明示的に検証
+  try {
+    validateFeatureName(featureName);
+  } catch (error) {
+    return {
+      success: false,
+      feature: featureName,
+      error: error instanceof Error ? error.message : 'Invalid feature name',
+    };
+  }
+
+  const check = canArchiveSpec(featureName, projectRoot);
+
+  if (!check.canArchive) {
+    return { success: false, feature: featureName, error: check.reason };
+  }
+
+  const sourceDir = resolve(projectRoot, `.kiro/specs/${featureName}`);
+  const archiveDir = resolve(projectRoot, '.kiro/specs/archive');
+  const targetDir = resolve(archiveDir, featureName);
+
+  // archive ディレクトリ作成
+  if (!existsSync(archiveDir)) {
+    mkdirSync(archiveDir, { recursive: true });
+  }
+
+  try {
+    // ディレクトリ移動
+    renameSync(sourceDir, targetDir);
+
+    // spec.json に archived 情報を追加
+    const specJsonPath = resolve(targetDir, 'spec.json');
+    const spec = JSON.parse(readFileSync(specJsonPath, 'utf-8'));
+    spec.archived = {
+      at: new Date().toISOString(),
+      reason: options?.reason,
+    };
+    spec.lastUpdated = new Date().toISOString();
+    writeFileSync(specJsonPath, JSON.stringify(spec, null, 2), 'utf-8');
+
+    return { success: true, feature: featureName, archivePath: targetDir };
+  } catch (error) {
+    return {
+      success: false,
+      feature: featureName,
+      error: `Failed to archive: ${error instanceof Error ? error.message : 'Unknown error'}`,
+    };
+  }
+}
+
+/**
+ * すべての仕様書を一覧取得
+ */
+export function listSpecs(
+  options?: { includeArchived?: boolean },
+  projectRoot: string = process.cwd()
+): SpecInfo[] {
+  const specs: SpecInfo[] = [];
+  const specsDir = resolve(projectRoot, '.kiro/specs');
+
+  if (!existsSync(specsDir)) {
+    return specs;
+  }
+
+  const entries = readdirSync(specsDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    if (entry.name === 'archive') {
+      if (options?.includeArchived) {
+        // アーカイブ済み仕様書を取得
+        const archiveDir = resolve(specsDir, 'archive');
+        const archivedEntries = readdirSync(archiveDir, { withFileTypes: true });
+
+        for (const archivedEntry of archivedEntries) {
+          if (!archivedEntry.isDirectory()) continue;
+
+          // アーカイブディレクトリ名を検証
+          try {
+            validateFeatureName(archivedEntry.name);
+          } catch (_error) {
+            console.warn(`⚠️  Skipping invalid archived directory name: ${archivedEntry.name}`);
+            continue;
+          }
+
+          const specPath = resolve(archiveDir, archivedEntry.name, 'spec.json');
+          if (existsSync(specPath)) {
+            try {
+              const spec = JSON.parse(readFileSync(specPath, 'utf-8'));
+              const files = readdirSync(resolve(archiveDir, archivedEntry.name));
+
+              specs.push({
+                feature: archivedEntry.name,
+                phase: spec.phase || 'unknown',
+                archived: true,
+                archivedAt: spec.archived?.at,
+                hasReleaseNotes: files.some((f: string) => f.startsWith('release-notes-')),
+                archivePath: resolve(archiveDir, archivedEntry.name),
+              });
+            } catch (_error) {
+              // spec.json の読み取りエラーは無視
+              console.warn(`⚠️  Failed to read archived spec: ${archivedEntry.name}`);
+            }
+          }
+        }
+      }
+      continue;
+    }
+
+    // 仕様書ディレクトリ名を検証
+    try {
+      validateFeatureName(entry.name);
+    } catch (_error) {
+      console.warn(`⚠️  Skipping invalid spec directory name: ${entry.name}`);
+      continue;
+    }
+
+    const specPath = resolve(specsDir, entry.name, 'spec.json');
+    if (existsSync(specPath)) {
+      try {
+        const spec = JSON.parse(readFileSync(specPath, 'utf-8'));
+        const files = readdirSync(resolve(specsDir, entry.name));
+
+        specs.push({
+          feature: entry.name,
+          phase: spec.phase || 'unknown',
+          archived: false,
+          hasReleaseNotes: files.some((f: string) => f.startsWith('release-notes-')),
+        });
+      } catch (_error) {
+        // spec.json の読み取りエラーは無視
+        console.warn(`⚠️  Failed to read spec: ${entry.name}`);
+      }
+    }
+  }
+
+  return specs;
+}

package/scripts/utils/spec-updater.ts

@@ -71,6 +71,10 @@ export interface SpecJson {
       completed?: boolean;
     };
   };
+  archived?: {
+    at: string;
+    reason?: string;
+  };
   lastUpdated?: string;
 }
 

package/templates/claude/agents/pr-size-monitor/AGENT.md

@@ -0,0 +1,330 @@
+---
+name: pr-size-monitor
+description: |
+  PRサイズを監視し、大規模PRを早期に検出する実行エージェント。
+  各タスク完了後に変更行数を分析し、500行超過時にPR分割を推奨。
+  PROACTIVELY: /michi:spec-impl の各タスク実装完了後に使用。
+allowed-tools: Bash, Read, Grep, Glob
+---
+
+# PR Size Monitor Agent
+
+## 目的
+
+レビュアビリティを確保するため、PRサイズを監視し、500行を超える大規模PRを早期に検出して分割を提案する。
+
+## 前提条件
+
+- Gitリポジトリが初期化されている
+- 作業ブランチがベースブランチ（main/develop）から分岐している
+- `gh` コマンド（GitHub CLI）がインストールされている（PR作成時に必要）
+
+## 実行フロー
+
+### Step 1: ベースブランチの特定
+
+```bash
+# ベースブランチを特定（main または develop）
+BASE_BRANCH=""
+
+if git show-ref --verify --quiet refs/heads/main; then
+    BASE_BRANCH="main"
+elif git show-ref --verify --quiet refs/heads/develop; then
+    BASE_BRANCH="develop"
+else
+    echo "⚠️ ベースブランチ（main/develop）が見つかりません"
+    exit 1
+fi
+
+echo "🔍 ベースブランチ: $BASE_BRANCH"
+```
+
+### Step 2: 変更量の計測
+
+```bash
+# ベースブランチとの差分を取得
+echo "=== 変更量計測 ==="
+
+# 除外パターンを定義
+EXCLUDE_PATTERNS=(
+  # ロックファイル
+  "package-lock.json"
+  "yarn.lock"
+  "pnpm-lock.yaml"
+  "composer.lock"
+  "Gemfile.lock"
+  "poetry.lock"
+  "Pipfile.lock"
+  "Cargo.lock"
+  "go.sum"
+
+  # 自動生成ファイル
+  "*.min.js"
+  "*.min.css"
+  "*.map"
+  "dist/*"
+  "build/*"
+  "coverage/*"
+  ".next/*"
+  "node_modules/*"
+)
+
+# git diffコマンドを構築
+EXCLUDE_ARGS=""
+for pattern in "${EXCLUDE_PATTERNS[@]}"; do
+  EXCLUDE_ARGS="$EXCLUDE_ARGS ':!$pattern'"
+done
+
+# 差分統計を取得
+git diff --stat "$BASE_BRANCH"...HEAD $EXCLUDE_ARGS > /tmp/pr-size-diff.txt
+
+# 追加・削除行数を計算
+CHANGES=$(git diff --numstat "$BASE_BRANCH"...HEAD $EXCLUDE_ARGS | awk '
+  $1 != "-" && $2 != "-" {
+    additions += $1
+    deletions += $2
+  }
+  END {
+    print additions + deletions
+  }
+')
+
+# ファイル数を取得
+FILE_COUNT=$(git diff --name-only "$BASE_BRANCH"...HEAD $EXCLUDE_ARGS | wc -l)
+
+echo "📊 変更量サマリー（除外ファイル除く）:"
+echo "  - 変更ファイル数: $FILE_COUNT"
+echo "  - 変更行数: $CHANGES 行"
+```
+
+### Step 3: 閾値判定
+
+```bash
+THRESHOLD=500
+
+if [ "$CHANGES" -lt "$THRESHOLD" ]; then
+    echo "✅ PRサイズ OK: ${CHANGES}行（閾値: ${THRESHOLD}行）"
+    echo "   レビューしやすいサイズです"
+    exit 0
+fi
+
+echo ""
+echo "⚠️  PRサイズが閾値を超えています"
+echo "   現在: ${CHANGES}行"
+echo "   閾値: ${THRESHOLD}行"
+echo ""
+echo "大規模PRはレビューが困難になり、マージまでの時間が長くなります。"
+echo "PR分割を検討してください。"
+```
+
+### Step 4: 変更内容の分析
+
+```bash
+# 変更が大きいファイルをリストアップ
+echo ""
+echo "📋 変更が大きいファイル（上位10件）:"
+git diff --numstat "$BASE_BRANCH"...HEAD $EXCLUDE_ARGS | \
+  awk '$1 != "-" && $2 != "-" {print $1+$2 " " $3}' | \
+  sort -rn | \
+  head -10 | \
+  awk '{printf "  %5d行: %s\n", $1, $2}'
+
+# ディレクトリ別の変更量
+echo ""
+echo "📂 ディレクトリ別変更量:"
+git diff --numstat "$BASE_BRANCH"...HEAD $EXCLUDE_ARGS | \
+  awk '$1 != "-" && $2 != "-" {
+    dir = $3
+    sub(/\/[^\/]*$/, "", dir)
+    if (dir == $3) dir = "."
+    changes[dir] += $1 + $2
+  }
+  END {
+    for (d in changes) {
+      printf "  %5d行: %s\n", changes[d], d
+    }
+  }' | \
+  sort -rn | \
+  head -10
+```
+
+### Step 5: ユーザー確認とアクション提案
+
+```bash
+echo ""
+echo "次のアクションを選択してください:"
+echo "A) 現在の変更でPRを作成する（推奨: 機能が完結している場合）"
+echo "B) 作業を続行する（警告を表示して継続）"
+echo "C) 分割戦略を提案してもらう"
+```
+
+AskUserQuestionツールを使用してユーザーに確認:
+
+```yaml
+questions:
+  - question: "PRサイズが500行を超えています。次のアクションを選択してください。"
+    header: "PRサイズ超過"
+    options:
+      - label: "現在の変更でPRを作成する（Recommended）"
+        description: "品質チェック完了済みの変更をPRとして作成し、新しいブランチで作業を継続します"
+      - label: "作業を続行する"
+        description: "PRを作成せず、このまま実装を継続します（警告あり）"
+      - label: "分割戦略を提案してもらう"
+        description: "変更内容を分析し、適切な分割方法を提案します"
+    multiSelect: false
+```
+
+### Step 6-A: PR作成（選択肢A）
+
+```bash
+if [ "$USER_CHOICE" = "A" ]; then
+    echo ""
+    echo "🚀 PR作成を開始します..."
+
+    # 現在のブランチ名を取得
+    CURRENT_BRANCH=$(git branch --show-current)
+
+    # 変更をcommit（未commitの場合）
+    if ! git diff-index --quiet HEAD --; then
+        echo "⚙️  未commitの変更をcommitします"
+
+        # ユーザーにコミットメッセージを確認
+        echo "コミットメッセージを入力してください（デフォルト: 'feat: implement feature'）:"
+        read -r COMMIT_MESSAGE
+        COMMIT_MESSAGE=${COMMIT_MESSAGE:-"feat: implement feature"}
+
+        git add .
+        git commit -m "$COMMIT_MESSAGE"
+    fi
+
+    # pushしてPR作成
+    echo "⚙️  ブランチをpushします"
+    git push -u origin "$CURRENT_BRANCH"
+
+    echo "⚙️  PRを作成します"
+    gh pr create --fill --base "$BASE_BRANCH"
+
+    if [ $? -eq 0 ]; then
+        # PR URLを取得
+        PR_URL=$(gh pr view --json url -q .url)
+        echo ""
+        echo "✅ PR作成完了"
+        echo "   URL: $PR_URL"
+        echo ""
+
+        # 新しいブランチで作業継続を提案
+        echo "次のアクション:"
+        echo "A) 新しいブランチを作成して作業を継続する"
+        echo "B) 現在のブランチで作業を継続する"
+
+        # ユーザー確認（必要に応じて）
+        # 新しいブランチ名を提案
+        NEXT_BRANCH="${CURRENT_BRANCH}-part2"
+        echo ""
+        echo "推奨: 新しいブランチ '$NEXT_BRANCH' で作業を継続しますか？ (Y/n)"
+    else
+        echo "❌ PR作成に失敗しました"
+        exit 1
+    fi
+fi
+```
+
+### Step 6-B: 作業継続（選択肢B）
+
+```bash
+if [ "$USER_CHOICE" = "B" ]; then
+    echo ""
+    echo "⚠️  PRサイズ警告を無視して作業を継続します"
+    echo ""
+    echo "注意事項:"
+    echo "- レビューアの負担が増加します"
+    echo "- マージまでの時間が長くなる可能性があります"
+    echo "- フィードバックサイクルが遅くなります"
+    echo ""
+    echo "定期的にPRサイズを確認することを推奨します。"
+fi
+```
+
+### Step 6-C: 分割戦略の提案（選択肢C）
+
+```bash
+if [ "$USER_CHOICE" = "C" ]; then
+    echo ""
+    echo "📋 PR分割戦略を提案します"
+    echo ""
+
+    # ディレクトリ別の変更量から分割案を生成
+    echo "## 推奨分割パターン"
+    echo ""
+    echo "### パターン1: ディレクトリ単位で分割"
+    git diff --numstat "$BASE_BRANCH"...HEAD $EXCLUDE_ARGS | \
+      awk '$1 != "-" && $2 != "-" {
+        dir = $3
+        sub(/\/[^\/]*$/, "", dir)
+        if (dir == $3) dir = "."
+        changes[dir] += $1 + $2
+        files[dir]++
+      }
+      END {
+        for (d in changes) {
+          if (changes[d] > 100) {
+            printf "  - PR: %s (%d行, %dファイル)\n", d, changes[d], files[d]
+          }
+        }
+      }' | \
+      sort -rn
+
+    echo ""
+    echo "### パターン2: 機能単位で分割"
+    echo "  1. 基盤・インフラ変更（共通機能、型定義など）"
+    echo "  2. コアロジック実装"
+    echo "  3. UI/UX実装"
+    echo "  4. テストとドキュメント"
+
+    echo ""
+    echo "### パターン3: 段階的な分割"
+    echo "  1. 既存機能への影響が小さい変更を先にPR"
+    echo "  2. 新機能の基本実装"
+    echo "  3. 新機能の拡張とエッジケース対応"
+fi
+```
+
+## 安全性ルール
+
+### 必須確認ケース
+
+1. **PR作成時**: 必ずユーザー確認（AskUserQuestion）
+2. **commit作成時**: コミットメッセージをユーザーに確認
+3. **push実行時**: ブランチ名とリモート先を確認
+
+### 禁止事項
+
+- ❌ ユーザー確認なしでのPR作成
+- ❌ ユーザー確認なしでのcommit作成
+- ❌ ユーザー確認なしでのpush実行
+- ❌ main/masterブランチへの直接push
+
+### 推奨パターン
+
+```
+AIエージェント:
+「⚠️  PRサイズが500行を超えています（現在: 723行）
+
+変更が大きいファイル:
+  312行: src/services/api.ts
+  187行: src/components/Dashboard.tsx
+  124行: src/utils/helpers.ts
+
+次のアクションを選択してください:
+A) 現在の変更でPRを作成する（推奨）
+B) 作業を続行する
+C) 分割戦略を提案してもらう
+
+どの対応を希望しますか？」
+```
+
+## 参考資料
+
+- [Google Engineering Practices - Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html)
+- [The Art of the Pull Request](https://hackernoon.com/the-art-of-pull-requests-6f0f099850f9)
+- [GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow)