shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-en/skills/nextjs-vibe-coding/templates/server-action-split/types.ts.template

@@ -0,0 +1,60 @@
+// lib/actions/{{name}}s/types.ts
+/**
+ * {{Name}} Types
+ *
+ * Shared types for {{name}} actions.
+ */
+
+import { z } from "zod"
+
+// ============================================================================
+// Action Result Type
+// ============================================================================
+
+export type ActionResult<T = void> =
+  | { success: true; data?: T }
+  | { success: false; error: string }
+
+// ============================================================================
+// Entity Types
+// ============================================================================
+
+export type {{Name}} = {
+  id: string
+  name: string
+  description: string | null
+  createdAt: Date
+  updatedAt: Date
+}
+
+export type {{Name}}WithRelations = {{Name}} & {
+  // Add relation types here
+  // author?: User
+}
+
+// ============================================================================
+// Validation Schemas
+// ============================================================================
+
+export const {{Name}}Schema = z.object({
+  name: z.string().min(1, "Name is required").max(100, "Name must be 100 characters or less"),
+  description: z.string().max(500, "Description must be 500 characters or less").nullable().optional(),
+})
+
+export type {{Name}}Input = z.infer<typeof {{Name}}Schema>
+
+// ============================================================================
+// Pagination Types
+// ============================================================================
+
+export type PaginationMeta = {
+  page: number
+  pageSize: number
+  total: number
+  totalPages: number
+}
+
+export type Paginated<T> = {
+  items: T[]
+  pagination: PaginationMeta
+}

package/plugin/shirokuma-skills-en/skills/nextjs-vibe-coding/templates/server-action.md

@@ -0,0 +1,345 @@
+# Server Action Module Template
+
+## Usage
+
+Server Actions モジュールを新規作成する際のテンプレート。
+
+## File Structure
+
+```
+lib/actions/
+├── {module}.ts           # Server Actions (このテンプレート)
+├── {module}-types.ts     # 型定義+定数
+└── types.ts              # 共通型（ActionResult）
+```
+
+## Template: {module}.ts
+
+```typescript
+"use server"
+
+/**
+ * [モジュール名]サーバーアクション / [Module Name] Server Actions
+ *
+ * [1-2行の概要説明]
+ *
+ * @serverAction
+ * @feature [FeatureName]
+ * @layer Application - Server Actions
+ *
+ * @usedInScreen [Screen1], [Screen2]
+ * @usedComponents [Component1], [Component2]
+ *
+ * @dbTables [table1], [table2]
+ * @dbOperations SELECT, INSERT, UPDATE, DELETE
+ *
+ * @authPattern
+ *   1. verifyAuth() - Read operations
+ *   2. verifyAuthMutation() - Write operations
+ *
+ * @category Server Actions - [カテゴリ名]
+ */
+
+// ============================================================
+// Imports
+// ============================================================
+import { revalidatePath } from "next/cache"
+import { eq, desc, and } from "drizzle-orm"
+import { db, tableName } from "@repo/database"
+import { verifyAuth, verifyAuthMutation } from "@/lib/auth-utils"
+import { z } from "zod"
+import type { ActionResult } from "./types"
+import { CONSTANTS, type ModuleType } from "./{module}-types"
+
+// ============================================================
+// Validation Schemas
+// ============================================================
+
+/**
+ * 作成用バリデーションスキーマ
+ *
+ * @validation CreateSchema
+ */
+const CreateSchema = z.object({
+  name: z.string().min(1, "名前は必須です").max(100),
+  // 他のフィールド
+})
+
+/**
+ * 更新用バリデーションスキーマ
+ *
+ * @validation UpdateSchema
+ */
+const UpdateSchema = CreateSchema.partial()
+
+// ============================================================
+// Server Actions (Read)
+// ============================================================
+
+/**
+ * [アイテム]一覧を取得 / Get [items] list
+ *
+ * @description 認証済みユーザーの[アイテム]一覧を取得します。
+ *
+ * @serverAction
+ * @feature [FeatureName]
+ * @dbTables [tableName]
+ *
+ * @returns [アイテム]の配列
+ * @throws 認証エラー - ユーザーが認証されていない場合
+ *
+ * @example
+ * ```ts
+ * const items = await getItems()
+ * ```
+ */
+export async function getItems(): Promise<ModuleType[]> {
+  const session = await verifyAuth()
+  if (!session?.user?.id) {
+    return []
+  }
+
+  const items = await db
+    .select()
+    .from(tableName)
+    .where(eq(tableName.userId, session.user.id))
+    .orderBy(desc(tableName.createdAt))
+
+  return items
+}
+
+/**
+ * [アイテム]を取得 / Get [item] by ID
+ *
+ * @description 指定されたIDの[アイテム]を取得します。
+ *
+ * @serverAction
+ * @feature [FeatureName]
+ * @dbTables [tableName]
+ *
+ * @param id - [アイテム]ID
+ * @returns [アイテム]、見つからない場合は null
+ * @throws 認証エラー
+ *
+ * @example
+ * ```ts
+ * const item = await getItem("uuid-here")
+ * ```
+ */
+export async function getItem(id: string): Promise<ModuleType | null> {
+  await verifyAuth()
+
+  const [item] = await db
+    .select()
+    .from(tableName)
+    .where(eq(tableName.id, id))
+    .limit(1)
+
+  return item ?? null
+}
+
+// ============================================================
+// Server Actions (Write)
+// ============================================================
+
+/**
+ * [アイテム]を作成 / Create [item]
+ *
+ * @description 新しい[アイテム]を作成します。
+ *
+ * @serverAction
+ * @feature [FeatureName]
+ * @dbTables [tableName]
+ *
+ * @param formData - フォームデータ
+ *   - name: [アイテム]名
+ * @returns 成功: `{ success: true }` / 失敗: `{ success: false, error }`
+ *
+ * @example
+ * ```tsx
+ * <form action={createItem}>
+ *   <input name="name" />
+ *   <button type="submit">作成</button>
+ * </form>
+ * ```
+ */
+export async function createItem(formData: FormData): Promise<ActionResult> {
+  const session = await verifyAuthMutation()
+  if (!session?.user?.id) {
+    return { success: false, error: "認証が必要です" }
+  }
+
+  const validated = CreateSchema.safeParse({
+    name: formData.get("name"),
+  })
+
+  if (!validated.success) {
+    return { success: false, error: validated.error.errors[0].message }
+  }
+
+  try {
+    await db.insert(tableName).values({
+      ...validated.data,
+      userId: session.user.id,
+    })
+
+    revalidatePath("/items")
+    return { success: true }
+  } catch (error) {
+    console.error("Failed to create item:", error)
+    return { success: false, error: "作成に失敗しました" }
+  }
+}
+
+/**
+ * [アイテム]を更新 / Update [item]
+ *
+ * @description 既存の[アイテム]を更新します。
+ *
+ * @serverAction
+ * @feature [FeatureName]
+ * @dbTables [tableName]
+ *
+ * @param id - [アイテム]ID
+ * @param formData - フォームデータ
+ * @returns 成功: `{ success: true }` / 失敗: `{ success: false, error }`
+ */
+export async function updateItem(
+  id: string,
+  formData: FormData
+): Promise<ActionResult> {
+  const session = await verifyAuthMutation()
+  if (!session?.user?.id) {
+    return { success: false, error: "認証が必要です" }
+  }
+
+  const validated = UpdateSchema.safeParse({
+    name: formData.get("name"),
+  })
+
+  if (!validated.success) {
+    return { success: false, error: validated.error.errors[0].message }
+  }
+
+  try {
+    // オーナーシップ確認
+    const [existing] = await db
+      .select({ userId: tableName.userId })
+      .from(tableName)
+      .where(eq(tableName.id, id))
+      .limit(1)
+
+    if (!existing || existing.userId !== session.user.id) {
+      return { success: false, error: "権限がありません" }
+    }
+
+    await db
+      .update(tableName)
+      .set({ ...validated.data, updatedAt: new Date() })
+      .where(eq(tableName.id, id))
+
+    revalidatePath("/items")
+    return { success: true }
+  } catch (error) {
+    console.error("Failed to update item:", error)
+    return { success: false, error: "更新に失敗しました" }
+  }
+}
+
+/**
+ * [アイテム]を削除 / Delete [item]
+ *
+ * @description 指定された[アイテム]を削除します。
+ *
+ * @serverAction
+ * @feature [FeatureName]
+ * @dbTables [tableName]
+ *
+ * @param id - [アイテム]ID
+ * @returns 成功: `{ success: true }` / 失敗: `{ success: false, error }`
+ */
+export async function deleteItem(id: string): Promise<ActionResult> {
+  const session = await verifyAuthMutation()
+  if (!session?.user?.id) {
+    return { success: false, error: "認証が必要です" }
+  }
+
+  try {
+    // オーナーシップ確認
+    const [existing] = await db
+      .select({ userId: tableName.userId })
+      .from(tableName)
+      .where(eq(tableName.id, id))
+      .limit(1)
+
+    if (!existing || existing.userId !== session.user.id) {
+      return { success: false, error: "権限がありません" }
+    }
+
+    await db.delete(tableName).where(eq(tableName.id, id))
+
+    revalidatePath("/items")
+    return { success: true }
+  } catch (error) {
+    console.error("Failed to delete item:", error)
+    return { success: false, error: "削除に失敗しました" }
+  }
+}
+```
+
+## Template: {module}-types.ts
+
+```typescript
+/**
+ * [モジュール名]型定義 / [Module Name] Types
+ *
+ * [モジュール名]関連の型定義と定数
+ *
+ * @skip-test 型定義のみ - ランタイムロジックなし
+ */
+import type { tableName } from "@repo/database"
+
+// ============================================================
+// Constants
+// ============================================================
+
+/**
+ * ステータスの選択肢
+ */
+export const STATUSES = ["active", "inactive", "archived"] as const
+
+// ============================================================
+// Types
+// ============================================================
+
+/**
+ * ステータス型
+ */
+export type Status = (typeof STATUSES)[number]
+
+/**
+ * 基本型（スキーマ推論）
+ */
+export type ModuleType = typeof tableName.$inferSelect
+
+/**
+ * 新規作成用型
+ */
+export type NewModuleType = typeof tableName.$inferInsert
+```
+
+## Checklist
+
+- [ ] `@serverAction` タグがモジュールヘッダーにある
+- [ ] `@feature` タグがモジュールヘッダーにある
+- [ ] `@dbTables` タグがモジュールヘッダーにある
+- [ ] 全 public 関数に `@serverAction` `@feature` `@returns` タグ
+- [ ] セクション区切りコメントがある
+- [ ] 型定義は `*-types.ts` に分離（`@skip-test` タグ付き）
+
+## Validation
+
+```bash
+# shirokuma-docs で検証
+cd [project] && node ../shirokuma-docs/dist/index.js lint-code -v
+```

package/plugin/shirokuma-skills-en/skills/nextjs-vibe-coding/templates/server-action.test.ts.template

@@ -0,0 +1,267 @@
+// __tests__/lib/actions/{{name}}.test.ts
+/**
+ * Server Action Tests for {{Name}}
+ *
+ * Uses queue-based mock pattern for Drizzle ORM.
+ * See KNOWLEDGE.md for detailed pattern explanation.
+ */
+
+// Mock database with FIFO queue for multiple queries
+jest.mock("@repo/database", () => {
+  const queryResults: any[] = []
+
+  const createQueryBuilder = () => {
+    const builder: any = {
+      from: jest.fn(() => builder),
+      where: jest.fn(() => builder),
+      orderBy: jest.fn(() => builder),
+      limit: jest.fn(() => builder),
+      offset: jest.fn(() => builder),
+      set: jest.fn(() => builder),
+      returning: jest.fn(() => builder),
+      leftJoin: jest.fn(() => builder),
+      groupBy: jest.fn(() => builder),
+      then: (resolve: any, reject: any) => {
+        const result = queryResults.shift() ?? []
+        if (result instanceof Error) {
+          return Promise.reject(result).catch(reject)
+        }
+        return Promise.resolve(result).then(resolve)
+      },
+      catch: (handler: any) => Promise.resolve([]).catch(handler),
+    }
+    return builder
+  }
+
+  return {
+    db: {
+      select: jest.fn(() => createQueryBuilder()),
+      insert: jest.fn(() => createQueryBuilder()),
+      update: jest.fn(() => createQueryBuilder()),
+      delete: jest.fn(() => createQueryBuilder()),
+    },
+    {{name}}s: {
+      id: "id",
+      name: "name",
+      createdAt: "createdAt",
+      updatedAt: "updatedAt",
+    },
+    eq: jest.fn((col, val) => ({ type: "eq", col, val })),
+    and: jest.fn((...conds) => ({ type: "and", conds })),
+    desc: jest.fn((col) => ({ type: "desc", col })),
+    count: jest.fn(() => "count"),
+    __queryResults__: queryResults,
+  }
+})
+
+// Mock auth
+const mockVerifyAdmin = jest.fn()
+jest.mock("@/lib/auth", () => ({
+  verifyAdmin: () => mockVerifyAdmin(),
+}))
+
+// Mock headers
+jest.mock("next/headers", () => ({
+  headers: jest.fn(() => new Headers()),
+}))
+
+// Mock cache
+jest.mock("next/cache", () => ({
+  revalidatePath: jest.fn(),
+  revalidateTag: jest.fn(),
+}))
+
+// Import after mocking
+import { db } from "@repo/database"
+import { revalidatePath } from "next/cache"
+import {
+  get{{Name}}s,
+  get{{Name}},
+  create{{Name}},
+  update{{Name}},
+  delete{{Name}},
+} from "../{{name}}"
+
+// Get queue reference
+const dbModule = require("@repo/database") as any
+const queryResults = dbModule.__queryResults__ as any[]
+
+// Helper functions
+const queueQueryResult = (...results: any[]) => {
+  results.forEach((r) => queryResults.push(r))
+}
+const clearQueryResults = () => {
+  queryResults.length = 0
+}
+
+describe("{{Name}} Actions", () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    clearQueryResults()
+    mockVerifyAdmin.mockResolvedValue({
+      user: { id: "admin-1", email: "admin@example.com", role: "admin" },
+    })
+  })
+
+  describe("get{{Name}}s", () => {
+    it("should return paginated {{name}}s", async () => {
+      const mock{{Name}}s = [
+        { id: "1", name: "{{Name}} 1" },
+        { id: "2", name: "{{Name}} 2" },
+      ]
+
+      // Queue: count query, then {{name}}s query
+      queueQueryResult([{ count: 10 }], mock{{Name}}s)
+
+      const result = await get{{Name}}s(1, 10)
+
+      expect(result.data).toHaveLength(2)
+      expect(result.total).toBe(10)
+    })
+
+    it("should throw error when not authenticated", async () => {
+      mockVerifyAdmin.mockResolvedValueOnce(null)
+
+      await expect(get{{Name}}s(1, 10)).rejects.toThrow("Unauthorized")
+    })
+
+    it("should propagate database error", async () => {
+      queueQueryResult(new Error("Database connection lost"))
+
+      await expect(get{{Name}}s(1, 10)).rejects.toThrow("Database connection lost")
+    })
+  })
+
+  describe("get{{Name}}", () => {
+    it("should return a single {{name}} by id", async () => {
+      const mock{{Name}} = { id: "1", name: "{{Name}} 1" }
+
+      queueQueryResult([mock{{Name}}])
+
+      const result = await get{{Name}}("1")
+
+      expect(result).toEqual(mock{{Name}})
+    })
+
+    it("should return null for non-existent {{name}}", async () => {
+      queueQueryResult([])
+
+      const result = await get{{Name}}("non-existent")
+
+      expect(result).toBeNull()
+    })
+  })
+
+  describe("create{{Name}}", () => {
+    it("should create a {{name}} with valid data", async () => {
+      const formData = new FormData()
+      formData.append("name", "New {{Name}}")
+
+      queueQueryResult([{ id: "new-id" }])
+
+      const result = await create{{Name}}(formData)
+
+      expect(result.success).toBe(true)
+      expect(result.data?.id).toBe("new-id")
+      expect(revalidatePath).toHaveBeenCalledWith("/{{name}}s")
+    })
+
+    it("should return error for missing name", async () => {
+      const formData = new FormData()
+      formData.append("name", "")
+
+      const result = await create{{Name}}(formData)
+
+      expect(result.success).toBe(false)
+      expect(result.error).toBeDefined()
+    })
+
+    it("should return error when not authenticated", async () => {
+      mockVerifyAdmin.mockResolvedValueOnce(null)
+
+      const formData = new FormData()
+      formData.append("name", "New {{Name}}")
+
+      const result = await create{{Name}}(formData)
+
+      expect(result.success).toBe(false)
+      expect(result.error).toBe("Unauthorized")
+    })
+
+    it("should handle database error", async () => {
+      const formData = new FormData()
+      formData.append("name", "New {{Name}}")
+
+      queueQueryResult(new Error("Insert failed"))
+
+      await expect(create{{Name}}(formData)).rejects.toThrow("Insert failed")
+    })
+  })
+
+  describe("update{{Name}}", () => {
+    it("should update a {{name}} with valid data", async () => {
+      const formData = new FormData()
+      formData.append("name", "Updated {{Name}}")
+
+      queueQueryResult([{ id: "1" }])
+
+      const result = await update{{Name}}("1", formData)
+
+      expect(result.success).toBe(true)
+      expect(revalidatePath).toHaveBeenCalled()
+    })
+
+    it("should return error for non-existent {{name}}", async () => {
+      const formData = new FormData()
+      formData.append("name", "Updated {{Name}}")
+
+      queueQueryResult([])
+
+      const result = await update{{Name}}("non-existent", formData)
+
+      expect(result.success).toBe(false)
+      expect(result.error).toContain("not found")
+    })
+
+    it("should return error when not authenticated", async () => {
+      mockVerifyAdmin.mockResolvedValueOnce(null)
+
+      const formData = new FormData()
+      formData.append("name", "Updated {{Name}}")
+
+      const result = await update{{Name}}("1", formData)
+
+      expect(result.success).toBe(false)
+      expect(result.error).toBe("Unauthorized")
+    })
+  })
+
+  describe("delete{{Name}}", () => {
+    it("should delete a {{name}}", async () => {
+      queueQueryResult([{ id: "1" }])
+
+      const result = await delete{{Name}}("1")
+
+      expect(result.success).toBe(true)
+      expect(revalidatePath).toHaveBeenCalledWith("/{{name}}s")
+    })
+
+    it("should return error for non-existent {{name}}", async () => {
+      queueQueryResult([])
+
+      const result = await delete{{Name}}("non-existent")
+
+      expect(result.success).toBe(false)
+      expect(result.error).toContain("not found")
+    })
+
+    it("should return error when not authenticated", async () => {
+      mockVerifyAdmin.mockResolvedValueOnce(null)
+
+      const result = await delete{{Name}}("1")
+
+      expect(result.success).toBe(false)
+      expect(result.error).toBe("Unauthorized")
+    })
+  })
+})