shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-ja/skills/nextjs-vibe-coding/patterns/csp.md

@@ -0,0 +1,97 @@
+# Content Security Policy (CSP) - Next.js 向け
+
+## 本番環境の CSP 設定
+
+Monaco Editor や Radix UI を使用する Next.js アプリに必要な CSP 設定：
+
+```typescript
+// lib/csp-nonce.ts
+export function buildCspHeader(nonce: string, isDevelopment: boolean): string {
+  const cspDirectives = isDevelopment
+    ? [
+        "default-src 'self'",
+        "script-src 'self' 'unsafe-inline' 'unsafe-eval'",  // HMR に eval が必要
+        "style-src 'self' 'unsafe-inline'",
+        "worker-src 'self' blob:",  // Monaco Editor workers
+        "img-src 'self' data: blob:",
+        "font-src 'self' data:",
+        "connect-src 'self' ws: wss:",  // HMR WebSocket
+        "frame-ancestors 'none'",
+      ]
+    : [
+        "default-src 'self'",
+        "script-src 'self' 'nonce-${nonce}' 'strict-dynamic'",  // Nonce ベース
+        "style-src 'self' 'unsafe-inline'",  // Radix UI/Monaco に必要
+        "worker-src 'self' blob:",  // Monaco Editor workers
+        "img-src 'self' data: blob:",
+        "font-src 'self' data:",
+        "connect-src 'self'",
+        "frame-ancestors 'none'",
+        "base-uri 'self'",
+        "form-action 'self'",
+        "object-src 'none'",
+        "upgrade-insecure-requests",
+      ]
+
+  return cspDirectives.join("; ")
+}
+```
+
+## `style-src 'unsafe-inline'` が必要な理由
+
+- **Monaco Editor**: シンタックスハイライト・行番号等にインラインスタイルを動的生成
+- **Radix UI**: ポップアップ配置・アニメーションにインラインスタイルを注入
+- **next-themes**: テーマ切替時にインラインスタイルを注入する場合がある
+
+これらはランタイムでスタイルを注入するため、nonce ベースのスタイルが使用できない。
+
+## `worker-src 'self' blob:` が必要な理由
+
+Monaco Editor が Web Worker を使用する項目：
+- 言語サービス（TypeScript, JSON バリデーション）
+- シンタックスハイライト
+- コード補完
+
+Worker は blob URL から生成されるため `worker-src` に `blob:` が必要。
+
+## よくある CSP エラーと修正
+
+| エラー | 不足している CSP ディレクティブ |
+|--------|-------------------------------|
+| "style-src ... violated" | style-src に `'unsafe-inline'` |
+| "worker ... blob: violated" | worker-src に `blob:` |
+| Monaco のシンタックスカラーなし | 上記の両方が不足 |
+
+## ミドルウェア実装
+
+リクエストごとの nonce で CSP を適用：
+
+```typescript
+// middleware.ts
+import { generateNonce, buildCspHeader } from "@/lib/csp-nonce"
+
+export default function middleware(request: NextRequest) {
+  const nonce = generateNonce()
+  const cspHeader = buildCspHeader(nonce)
+
+  const response = handleI18nRouting(request)
+  response.headers.set("Content-Security-Policy", cspHeader)
+  response.headers.set("x-nonce", nonce)
+
+  return response
+}
+```
+
+## 外部ストレージの画像ホスト
+
+S3 等の外部ストレージを使用する場合、`img-src` にホストを追加：
+
+```typescript
+const storageHost = process.env.NEXT_PUBLIC_STORAGE_PUBLIC_URL
+  ? new URL(process.env.NEXT_PUBLIC_STORAGE_PUBLIC_URL).origin
+  : ""
+
+const imgSrc = storageHost
+  ? `img-src 'self' data: blob: ${storageHost}`
+  : "img-src 'self' data: blob:"
+```

package/plugin/shirokuma-skills-ja/skills/nextjs-vibe-coding/patterns/csrf-protection.md

@@ -0,0 +1,153 @@
+# CSRF 保護パターン
+
+## 概要
+
+Server Actions を Origin/Referer ヘッダー検証で CSRF 攻撃から保護する。二関数パターンにより、全ミューテーションに CSRF 保護を適用する。
+
+---
+
+## 実装
+
+### CSRF バリデーションユーティリティ
+
+```typescript
+// lib/csrf.ts
+import { headers } from "next/headers"
+
+export async function validateCsrfToken(allowedOrigin?: string): Promise<void> {
+  const expectedOrigin = allowedOrigin || process.env.NEXT_PUBLIC_APP_URL
+  const headersList = await headers()
+  const origin = headersList.get("origin")
+  const referer = headersList.get("referer")
+
+  // Origin ヘッダーを優先チェック
+  if (origin && origin !== expectedOrigin) {
+    throw new Error("CSRF validation failed: Invalid origin")
+  }
+
+  // Referer ヘッダーにフォールバック
+  if (!origin && referer) {
+    const refererOrigin = new URL(referer).origin
+    if (refererOrigin !== expectedOrigin) {
+      throw new Error("CSRF validation failed: Invalid referer")
+    }
+  }
+
+  // 両ヘッダーが欠如している場合は拒否
+  if (!origin && !referer) {
+    throw new Error("CSRF validation failed: Missing headers")
+  }
+}
+```
+
+---
+
+## 二関数認証パターン
+
+```typescript
+// lib/auth-utils.ts
+import { headers } from "next/headers"
+import { validateCsrfToken } from "./csrf"
+import { verifyAdminAuth } from "./auth"
+
+// 読み取り操作用（CSRF 不要）
+export async function verifyAdmin(): Promise<string> {
+  const session = await verifyAdminAuth(await headers())
+  if (!session?.user?.id) throw new Error("Unauthorized")
+  return session.user.id
+}
+
+// ミューテーション用（CSRF + 認証）
+export async function verifyAdminMutation(): Promise<string> {
+  await validateCsrfToken()  // Step 1: CSRF 検証
+  return await verifyAdmin() // Step 2: 認証チェック
+}
+```
+
+---
+
+## 使い分けルール
+
+| 操作タイプ | 関数 | CSRF チェック |
+|-----------|------|--------------|
+| GET（一覧、詳細） | `verifyAdmin()` | ❌ なし |
+| POST（作成） | `verifyAdminMutation()` | ✅ あり |
+| PUT/PATCH（更新） | `verifyAdminMutation()` | ✅ あり |
+| DELETE | `verifyAdminMutation()` | ✅ あり |
+
+---
+
+## 使用例
+
+### クエリ（読み取り）- CSRF なし
+
+```typescript
+export async function getFeatures(page: number = 1) {
+  await verifyAdmin()  // 読み取りに CSRF は不要
+  return await db.select().from(features).limit(20)
+}
+```
+
+### ミューテーション（書き込み）- CSRF 必須
+
+```typescript
+export async function createFeature(formData: FormData): Promise<ActionResult | void> {
+  const userId = await verifyAdminMutation()  // CSRF + 認証
+  // ... バリデーションと DB 操作
+}
+```
+
+---
+
+## 公開アプリパターン
+
+公開向けアクション（コメント等）では明示的に CSRF を検証：
+
+```typescript
+export async function createComment(postId: string, content: string): Promise<Result> {
+  // CSRF 保護 - 明示的呼び出し
+  try {
+    await validateCsrfToken()
+  } catch (error) {
+    return { success: false, error: "post.errors.csrfValidationFailed" }
+  }
+
+  // 認証 - verifyAdmin ではなく getUser を使用
+  const session = await getUser(await headers())
+  if (!session?.user?.id) {
+    return { success: false, error: "post.errors.loginRequired" }
+  }
+
+  // 操作を続行...
+}
+```
+
+---
+
+## CSRF 保護のテスト
+
+```typescript
+// CSRF が検証されることをテスト
+it("rejects requests with invalid origin", async () => {
+  // 不正な origin でヘッダーをモック
+  mockHeaders.mockResolvedValueOnce(new Headers({
+    origin: "https://evil.com"
+  }))
+
+  const result = await createFeature(validFormData())
+  expect(result).toEqual({
+    success: false,
+    error: "CSRF validation failed",
+    code: "CSRF_INVALID"
+  })
+})
+```
+
+---
+
+## セキュリティ上の注意
+
+1. **ミューテーションでは CSRF を絶対にスキップしない** - 全 POST/PUT/PATCH/DELETE 操作で CSRF を検証
+2. **環境変数を使用** - `NEXT_PUBLIC_APP_URL` を全環境で正しく設定
+3. **Origin ヘッダーを優先** - Referer ヘッダーより信頼性が高い
+4. **ヘッダー欠如を処理** - Origin と Referer の両方がないリクエストを拒否

package/plugin/shirokuma-skills-ja/skills/nextjs-vibe-coding/patterns/documentation.md

@@ -0,0 +1,220 @@
+# ドキュメントパターン
+
+## テストドキュメント生成
+
+テストファイルからドキュメントを自動生成する：
+
+```bash
+# テストドキュメント生成（HTML + Markdown）
+pnpm docs:tests
+
+# 出力:
+# - docs/portal/test-cases.html（インタラクティブHTML、コード表示付き）
+# - docs/generated/test-cases.md（Markdown形式）
+```
+
+**機能:**
+- サイドバーナビゲーション（ファイル別）
+- テストコードの展開表示（クリックで詳細表示）
+- JSDocコメントの抽出と表示
+- 行番号表示（ソースへの参照）
+- コピーボタン（クリップボードへコピー）
+- 検索・フィルタリング機能
+
+## テストファイルの JSDoc
+
+テストファイルにJSDocコメントを書くことで自動的にドキュメントに反映される：
+
+```typescript
+/**
+ * テストの説明（ファイルレベル）
+ * テスト環境や前提条件を記載
+ */
+describe("機能名", () => {
+  // describeの前にコメントを書くとドキュメントに表示される
+
+  /**
+   * 個別テストの詳細説明
+   * 期待される動作や条件を記載
+   */
+  test("テスト名", async () => {
+    // テストコード
+  })
+})
+```
+
+## API ドキュメント（TypeDoc）
+
+Server Actions や型定義にJSDocを書くことでAPIドキュメントを自動生成：
+
+```bash
+# APIドキュメント生成
+pnpm docs:api
+
+# 出力: docs/generated/api-html/
+```
+
+### JSDoc ベストプラクティス
+
+```typescript
+/**
+ * 関数の概要（1行目）
+ *
+ * 詳細な説明（2行目以降）。
+ * 処理フローや注意点を記載。
+ *
+ * ## セクション見出し
+ * - リスト項目1
+ * - リスト項目2
+ *
+ * @param paramName - パラメータの説明
+ * @returns 戻り値の説明
+ *
+ * @example
+ * ```typescript
+ * // 使用例
+ * const result = await myFunction(params)
+ * console.log(result)
+ * ```
+ *
+ * @see {@link relatedFunction} - 関連する関数への参照
+ * @throws {Error} エラー条件の説明
+ *
+ * @category カテゴリ名
+ */
+export async function myFunction(paramName: string): Promise<Result> {
+  // implementation
+}
+```
+
+### 使用するタグ
+
+| タグ | 用途 |
+|------|------|
+| `@param` | パラメータの説明 |
+| `@returns` | 戻り値の説明 |
+| `@example` | 使用例（コードブロック付き） |
+| `@see` | 関連する関数・型への参照 |
+| `@throws` | スローする可能性のあるエラー |
+| `@category` | TypeDocでのカテゴリ分類 |
+| `@internal` | 内部関数（ドキュメントから除外） |
+
+### Interface/Type のドキュメント
+
+```typescript
+/**
+ * 型の概要
+ *
+ * @typeParam T - ジェネリック型の説明
+ *
+ * @example
+ * ```typescript
+ * const result: PaginatedResult<Post> = {
+ *   items: posts,
+ *   total: 150,
+ *   page: 1,
+ *   pageSize: 10,
+ *   totalPages: 15
+ * }
+ * ```
+ *
+ * @category 型定義
+ */
+export interface PaginatedResult<T> {
+  /** 現在のページのアイテム配列 */
+  items: T[]
+  /** 全アイテム数 */
+  total: number
+  // ...
+}
+```
+
+## ドキュメントポータルのアーキテクチャ
+
+自動生成コンテンツを含む Next.js プロジェクト向け統合ドキュメントポータル。
+
+### マルチアプリ対応（モノレポ）
+
+モノレポで複数アプリがある場合、機能はアプリごとに自動分類される：
+
+**パスベースのアプリ推定**:
+| パスパターン | 推定アプリ |
+|-------------|-----------|
+| `apps/admin/...` | Admin |
+| `apps/public/...` | Public |
+| `apps/web/...` | Web |
+| `packages/...` | Shared |
+
+**ポータル構成**:
+```
+docs/portal/
+├── details/
+│   ├── actions/
+│   │   ├── AdminOnly/        # Admin アプリのアクション
+│   │   ├── PublicOnly/       # Public アプリのアクション
+│   │   └── Shared/           # 横断的なアクション
+│   ├── components/
+│   └── screens/
+└── feature-map/
+    └── index.html            # アプリベースの機能グルーピング
+```
+
+**メリット**:
+- 所有権の明確化: どのアプリがどの機能を所有するか
+- アノテーション不要: ディレクトリ構造から推定
+- 一貫したナビゲーション: アプリごとにグループ化された機能マップ
+
+### Action タイプの分類
+
+Server Actions はアノテーションではなく**ディレクトリ構造**で分類：
+
+**ディレクトリ構造**:
+```
+lib/actions/
+├── crud/                    # テーブル駆動の CRUD アクション
+│   ├── organizations.ts     # → CRUD（ディレクトリから推定）
+│   ├── projects.ts
+│   └── entities.ts
+│
+├── domain/                  # ドメイン駆動の複合アクション
+│   ├── dashboard.ts         # → Domain（ディレクトリから推定）
+│   ├── publishing.ts
+│   └── onboarding.ts
+│
+└── types.ts
+```
+
+**分類基準**:
+| ディレクトリ | タイプ | 特徴 | 例 |
+|-------------|--------|------|-----|
+| `crud/` | CRUD | 単一テーブル、標準CRUD | `getProjects`, `createEntity` |
+| `domain/` | Domain | 複数テーブル、ビジネスワークフロー | `getDashboardStats`, `publishPost` |
+
+**ポータル表示**:
+- 機能マップに `[CRUD]` または `[Domain]` バッジ（パスから推定）
+- アクションタイプでフィルタリング可能
+- Domain アクションのテーブル関係を可視化
+
+### ディレクトリ構造
+
+| パス | 用途 |
+|------|------|
+| `docs/portal/index.html` | メインポータルページ |
+| `docs/portal/viewer.html` | Markdown ビューア（シンタックスハイライト付き） |
+| `docs/portal/test-cases.html` | 生成されたテストドキュメント |
+| `docs/portal/feature-map/` | 機能マップ（アプリ別グルーピング） |
+| `docs/generated/api-html/` | TypeDoc API ドキュメント |
+| `docs/generated/test-cases.md` | テストケース Markdown |
+| `docs/generated/deps/` | 依存関係グラフ（SVG） |
+| `docs/generated/dbml/` | データベーススキーマ図 |
+| `docs/phase*/` | 実装フェーズドキュメント（任意） |
+
+### コマンドリファレンス
+
+```bash
+# ドキュメント生成
+pnpm docs:tests     # テストドキュメント生成
+pnpm docs:api       # APIドキュメント生成（TypeDoc）
+pnpm docs:dbml      # DBスキーマ図生成
+pnpm docs:deps      # 依存関係図生成
+```