shirokuma-docs 0.1.0-alpha.1

package/plugin/shirokuma-skills-en/skills/nextjs-vibe-coding/patterns/testing.md

@@ -0,0 +1,298 @@
+# Testing Patterns
+
+## Test Documentation (REQUIRED)
+
+All tests MUST have JSDoc comments with @testdoc tags. This enables:
+- Japanese test descriptions in documentation
+- Automated documentation generation
+- Test intent tracking
+
+### JSDoc Format
+
+```typescript
+/**
+ * @testdoc 日本語でのテスト説明
+ * @purpose テストの目的を説明
+ * @precondition 前提条件
+ * @expected 期待される結果
+ */
+it("english test name for code", async () => {
+  // test implementation
+});
+```
+
+### Examples
+
+```typescript
+describe("createUser", () => {
+  /**
+   * @testdoc 有効なデータで新規ユーザーを作成できる
+   * @purpose ユーザー作成の正常系確認
+   * @precondition 有効なメールアドレスとパスワード
+   * @expected ユーザーが作成され、IDが返される
+   */
+  it("should create user with valid data", async () => {
+    // ...
+  });
+
+  /**
+   * @testdoc 重複メールアドレスでエラーを返す
+   * @purpose 重複チェックの動作確認
+   * @expected DUPLICATE_EMAIL エラーが返される
+   */
+  it("should return error for duplicate email", async () => {
+    // ...
+  });
+});
+```
+
+### Lint Test Documentation
+
+```bash
+# Check test documentation coverage
+shirokuma-docs lint-tests -p . -c shirokuma-docs.config.yaml -f summary
+
+# Detailed report
+shirokuma-docs lint-tests -p . -c shirokuma-docs.config.yaml -f terminal
+
+# CI mode with threshold
+shirokuma-docs lint-tests -p . --strict --coverage-threshold 50
+```
+
+### Implementation-Test Coverage Check
+
+```bash
+# Check source-test file mapping
+shirokuma-docs lint-coverage -p . -c shirokuma-docs.config.yaml
+
+# Summary only
+shirokuma-docs lint-coverage -p . -c shirokuma-docs.config.yaml -f summary
+
+# Strict mode (fail on missing tests)
+shirokuma-docs lint-coverage -p . -c shirokuma-docs.config.yaml -s
+```
+
+### @skip-test Annotation
+
+For files that don't need tests, add JSDoc annotation:
+
+```typescript
+/**
+ * @skip-test 自動生成コードのためテスト不要
+ */
+export const generatedSchema = { ... }
+```
+
+Valid skip reasons:
+- 自動生成 (auto-generated code)
+- shadcn/ui (library components)
+- E2Eでカバー (covered by E2E tests)
+- 外部ライブラリ (external library wrapper)
+- 単純なre-export (simple re-export)
+
+## Jest Configuration
+
+```javascript
+// jest.config.js
+const nextJest = require("next/jest")
+
+const createJestConfig = nextJest({ dir: "./" })
+
+module.exports = createJestConfig({
+  setupFilesAfterEnv: ["<rootDir>/jest.setup.ts"],
+  testEnvironment: "jsdom",
+  moduleNameMapper: {
+    "^@/(.*)$": "<rootDir>/$1",
+    "^@repo/database$": "<rootDir>/../../packages/database/src",
+  },
+})
+```
+
+## Jest Setup (Mocks)
+
+```typescript
+// jest.setup.ts
+import "@testing-library/jest-dom"
+
+// Mock next/navigation
+jest.mock("next/navigation", () => ({
+  useRouter: () => ({ push: jest.fn(), replace: jest.fn(), back: jest.fn() }),
+  usePathname: () => "/",
+  useSearchParams: () => new URLSearchParams(),
+}))
+
+// Mock next-intl
+jest.mock("next-intl", () => ({
+  useTranslations: () => (key: string) => key,
+  useLocale: () => "ja",
+}))
+```
+
+## Testing Server Actions (Queue-Based Mock Pattern)
+
+Server Actions often execute multiple database queries. Use the queue-based pattern:
+
+```typescript
+// Mock database with FIFO queue for multiple queries
+jest.mock("@repo/database", () => {
+  const queryResults: any[] = []  // FIFO queue
+
+  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),
+      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()),
+    },
+    posts: { id: "id", title: "title", status: "status" },
+    eq: jest.fn((col, val) => ({ type: "eq", col, val })),
+    __queryResults__: queryResults,
+  }
+})
+
+// Get queue reference
+const dbModule = require("@repo/database") as any
+const queryResults = dbModule.__queryResults__ as any[]
+const queueQueryResult = (...results: any[]) => results.forEach(r => queryResults.push(r))
+const clearQueryResults = () => { queryResults.length = 0 }
+
+// Mock auth
+jest.mock("@/lib/auth", () => ({
+  verifyAdmin: jest.fn().mockResolvedValue({
+    user: { id: "user-1", email: "admin@example.com", role: "admin" },
+  }),
+}))
+
+// Mock headers & cache
+jest.mock("next/headers", () => ({
+  headers: jest.fn().mockResolvedValue(new Headers()),
+}))
+jest.mock("next/cache", () => ({
+  revalidatePath: jest.fn(),
+}))
+
+// Usage in tests
+beforeEach(() => { jest.clearAllMocks(); clearQueryResults() })
+
+it("fetches paginated data", async () => {
+  queueQueryResult([{ count: 50 }], [{ id: "1", title: "Post" }])
+  const result = await getPaginatedPosts(1, 10)
+  expect(result.data).toHaveLength(1)  // Note: `data` not `items`
+})
+```
+
+## Testing Components with i18n
+
+```typescript
+import { render, screen } from "@testing-library/react"
+import { NextIntlClientProvider } from "next-intl"
+
+const messages = { common: { save: "Save" }, features: { title: "Features" } }
+
+function renderWithProviders(ui: React.ReactElement, locale = "en") {
+  return render(
+    <NextIntlClientProvider locale={locale} messages={messages}>
+      {ui}
+    </NextIntlClientProvider>
+  )
+}
+```
+
+## Redirect Mock Pattern
+
+Server Actions that call `redirect()` need special handling in tests:
+
+```typescript
+// Mock next/navigation with redirect that throws
+jest.mock("next/navigation", () => ({
+  redirect: jest.fn((url: string) => {
+    throw new Error(`NEXT_REDIRECT:${url}`)
+  }),
+  useRouter: () => ({ push: jest.fn(), replace: jest.fn(), back: jest.fn() }),
+  usePathname: () => "/",
+}))
+
+// Test redirect behavior
+it("redirects on success", async () => {
+  // Setup mocks...
+  mockVerifyAdminMutation.mockResolvedValueOnce("user-1")
+  queueQueryResult([])  // No duplicate found
+
+  await expect(createFeature(validFormData())).rejects.toThrow("NEXT_REDIRECT:/features")
+  expect(revalidatePath).toHaveBeenCalledWith("/features")
+})
+```
+
+## i18n-Aware E2E Selectors
+
+Use regex with both language alternatives:
+
+```typescript
+// Pattern: /English|日本語/i
+await page.getByRole("heading", { name: /Post Management|投稿管理/i })
+await page.getByText(/Draft|下書き/i)
+await page.getByRole("button", { name: /Update|更新/i })
+await page.getByLabel(/^Email$|^メールアドレス$/i)
+await page.getByRole("button", { name: /login|ログイン|Log in/i })
+```
+
+## E2E Test Setup Pattern
+
+```typescript
+import { test, expect } from "@playwright/test"
+import { TEST_USERS } from "../fixtures/test-users"
+import { redisHelper } from "../helpers/redis"
+
+test.describe.serial("Feature CRUD Operations", () => {
+  test.beforeEach(async ({ page, context }) => {
+    // Clear state
+    await context.clearCookies()
+    await redisHelper.clearAllTestState()
+
+    // Login with i18n-aware selectors
+    await page.goto("/login")
+    await page.getByRole("textbox", { name: /Email|メールアドレス/i }).fill(TEST_USERS.admin.email)
+    await page.getByLabel(/^Password$|^パスワード$/i).fill(TEST_USERS.admin.password)
+    await page.getByRole("button", { name: /login|ログイン|Log in/i }).click()
+    await expect(page).toHaveURL(/\/$/, { timeout: 15000 })
+  })
+
+  test("can create an item", async ({ page }) => {
+    await page.goto("/features/new")
+    await page.getByRole("textbox", { name: /Name|名前/i }).fill("Test Feature")
+    await page.getByRole("button", { name: /Create|作成/i }).click()
+    await expect(page).toHaveURL(/\/features(?:\?.*)?$/, { timeout: 10000 })
+  })
+})
+```
+
+## Command Reference
+
+```bash
+# Testing
+pnpm --filter admin test              # Run all
+pnpm --filter admin test --watch      # Watch mode
+pnpm --filter admin test --coverage   # With coverage
+
+# E2E tests (Playwright Server)
+npx playwright test --reporter=list
+```

package/plugin/shirokuma-skills-en/skills/nextjs-vibe-coding/reference/checklists.md

@@ -0,0 +1,76 @@
+# Implementation Checklists
+
+Checklists for ensuring code quality and TDD compliance.
+
+---
+
+## Server Action Checklist
+
+- [ ] `"use server"` directive at top
+- [ ] **Queries**: `verifyAdmin()` (no CSRF needed)
+- [ ] **Mutations**: `verifyAdminMutation()` (includes CSRF)
+- [ ] Zod schema validation
+- [ ] **Ownership check before update/delete**
+- [ ] **Rate limiting for destructive operations** (delete, password reset)
+- [ ] **Error codes in responses** (`NOT_FOUND`, `FORBIDDEN`, `RATE_LIMIT_EXCEEDED`)
+- [ ] Proper error handling with try/catch
+- [ ] Return typed `ActionResult<T>` response
+- [ ] `revalidatePath()` or `revalidateTag()` for cache
+- [ ] No sensitive data in responses
+
+---
+
+## Page Component Checklist
+
+- [ ] Async params with `await`
+- [ ] `setRequestLocale(locale)` called first
+- [ ] `getTranslations()` for server-side i18n
+- [ ] Proper TypeScript types for props
+- [ ] Suspense boundary for data loading
+- [ ] Error boundary (error.tsx) if needed
+- [ ] Loading state (loading.tsx) if needed
+
+---
+
+## Client Component Checklist
+
+- [ ] `"use client"` directive at top
+- [ ] `useTranslations()` for i18n
+- [ ] `useTransition()` for form submissions
+- [ ] Loading and error states
+- [ ] Proper form validation
+- [ ] Accessible labels and ARIA attributes
+
+---
+
+## i18n Checklist
+
+- [ ] Add keys to `messages/ja.json`
+- [ ] Add keys to `messages/en.json`
+- [ ] Use namespace pattern (e.g., `features.form.name`)
+- [ ] Handle date formatting with locale
+
+---
+
+## Test-First Enforcement Checklist
+
+Before reporting completion, verify:
+
+- [ ] **Test files created BEFORE implementation files**
+- [ ] Server Action tests exist: `__tests__/lib/actions/{{name}}.test.ts`
+- [ ] Component tests exist: `__tests__/components/{{name}}-form.test.tsx`
+- [ ] All tests pass: `pnpm --filter admin test`
+- [ ] No lint errors: `pnpm --filter admin lint`
+- [ ] Implementation report saved to `GitHub Discussions (Reports)`
+
+---
+
+## Completion Requirements
+
+**ALL MUST BE TRUE before marking task complete:**
+
+- [ ] Test files exist for all implementation code
+- [ ] Tests were written before implementation (TDD)
+- [ ] All tests are active and executable (not commented out or skipped)
+- [ ] Tests verify the actual implementation behavior
+- [ ] Implementation report has been saved to `GitHub Discussions (Reports)`

package/plugin/shirokuma-skills-en/skills/nextjs-vibe-coding/reference/large-scale.md

@@ -0,0 +1,141 @@
+# Large-Scale File Organization Rules
+
+Follow these rules for splitting files in large-scale projects.
+
+---
+
+## Split Thresholds
+
+| File Type | Threshold | Action |
+|-----------|-----------|--------|
+| Server Actions | 300 lines or 8+ functions | Split by domain/operation |
+| i18n Messages | 300 lines or 200+ keys | Split by namespace |
+| Components | 250 lines | Extract sub-components |
+| Schema | 20+ tables or 500+ lines | Split by domain (see reference.md) |
+
+---
+
+## Server Actions Split Pattern
+
+**When exceeding 300 lines, split by functionality:**
+
+| File | Purpose |
+|------|---------|
+| `lib/actions/posts/index.ts` | Barrel export |
+| `lib/actions/posts/queries.ts` | getPaginatedPosts, getPostBySlug |
+| `lib/actions/posts/mutations.ts` | createPost, updatePost, deletePost |
+| `lib/actions/posts/filters.ts` | getPostsByCategory, getPostsByTag |
+| `lib/actions/__tests__/posts.test.ts` | Tests (keep in original location) |
+
+**Important**: Keep test files in `lib/actions/__tests__/`. Do not change test structure when splitting actions.
+
+**index.ts:**
+```typescript
+export * from './queries'
+export * from './mutations'
+export * from './filters'
+```
+
+---
+
+## i18n Messages Split Pattern
+
+**When exceeding 300 lines, split by namespace:**
+
+| File | Purpose |
+|------|---------|
+| `messages/{locale}/index.ts` | Combined export |
+| `messages/{locale}/common.json` | Common UI (buttons, labels) |
+| `messages/{locale}/auth.json` | Authentication (login, signup) |
+| `messages/{locale}/content.json` | Content (posts, categories) |
+| `messages/{locale}/errors.json` | Error messages |
+| `messages/{locale}/validation.json` | Input validation |
+
+**index.ts:**
+```typescript
+import common from './common.json'
+import auth from './auth.json'
+import content from './content.json'
+import errors from './errors.json'
+import validation from './validation.json'
+
+export default { common, auth, content, errors, validation }
+```
+
+**Update next-intl config (`i18n/request.ts`):**
+```typescript
+import messages from `@/messages/${locale}`
+return { locale, messages }
+```
+
+---
+
+## Components Split Pattern
+
+**Components exceeding 250 lines should be split into sub-components:**
+
+| File | Purpose |
+|------|---------|
+| `post-form.tsx` | Main wrapper (~80 lines) |
+| `post-form-editor.tsx` | Markdown editor section |
+| `post-form-meta.tsx` | Title, slug, excerpt |
+| `post-form-category.tsx` | Category selection |
+| `post-form-tags.tsx` | Tag selection |
+| `post-form-actions.tsx` | Save/Cancel buttons |
+
+**post-form.tsx:**
+```tsx
+export function PostForm({ post, categories, tags }: PostFormProps) {
+  return (
+    <form action={handleSubmit}>
+      <PostFormMeta defaultValues={post} />
+      <PostFormEditor content={post?.content} />
+      <PostFormCategory categories={categories} />
+      <PostFormTags tags={tags} />
+      <PostFormActions isPending={isPending} />
+    </form>
+  )
+}
+```
+
+---
+
+## Shared Utility Extraction
+
+**Extract logic used across multiple files:**
+
+| File | Purpose |
+|------|---------|
+| `lib/actions/shared/pagination.ts` | Pagination helpers |
+| `lib/actions/shared/filters.ts` | Filtering helpers |
+| `lib/actions/shared/validation.ts` | Common validation |
+
+---
+
+## Split Checklist
+
+- [ ] Create barrel export (index.ts)
+- [ ] Maintain existing import paths (backward compatibility)
+- [ ] Keep tests in `lib/actions/__tests__/` (no split needed)
+- [ ] Update documentation (CLAUDE.md)
+
+---
+
+## Split Templates
+
+When thresholds are exceeded, use these templates:
+
+| Directory | Purpose |
+|-----------|---------|
+| `templates/server-action-split/` | Server Actions splitting |
+| `templates/messages-split/` | i18n Messages splitting |
+
+See [templates/README.md](templates/README.md) for details.
+
+---
+
+## References
+
+- **Template details**: [templates/README.md](templates/README.md)
+- **Schema splitting**: [reference.md - Drizzle ORM](reference.md)
+- **Testing patterns**: [patterns/testing.md](patterns/testing.md)

package/plugin/shirokuma-skills-en/skills/nextjs-vibe-coding/reference/reference.md

@@ -0,0 +1,171 @@
+# Next.js Vibe Coder Knowledge Base
+
+---
+
+## Document Structure
+
+各ファイルの責任範囲：
+
+| ファイル | 責任 | 内容 |
+|---------|------|------|
+| **AGENT.md** | ワークフロー | 8ステップの実装手順のみ |
+| **reference.md** (このファイル) | クイックリファレンス | Tech Stack, Pattern一覧, Known Issues |
+| **checklists.md** | 品質ゲート | 実装完了前のチェックリスト |
+| **templates/README.md** | テンプレート仕様 | テンプレート一覧と使い方 |
+| **large-scale.md** | 分割ルール | ファイル分割の閾値とパターン |
+| **patterns/*.md** | 詳細パターン | 個別の技術パターン（Source of Truth） |
+
+**原則**: 情報は1箇所のみに記載。他は参照リンクのみ。
+
+---
+
+## Tech Stack
+
+| Category | Technology |
+|----------|------------|
+| Frontend | Next.js 16 / React 19 / TypeScript 5 |
+| Database | PostgreSQL 16 + Drizzle ORM |
+| Auth | Better Auth (DB sessions) |
+| i18n | next-intl (ja/en) |
+| Styling | Tailwind CSS v4 + shadcn/ui |
+| Testing | Jest + Playwright |
+
+> 詳細バージョン: プロジェクトの `CLAUDE.md` を参照
+
+---
+
+## Pattern Files
+
+Detailed patterns are organized in `patterns/`.
+
+| File | Description |
+|------|-------------|
+| [coding-conventions.md](patterns/coding-conventions.md) | Naming, imports, TypeScript, component structure |
+| [testing.md](patterns/testing.md) | Jest config, mocks, redirect mock, i18n E2E selectors |
+| [code-patterns.md](patterns/code-patterns.md) | Async params, Server Actions, i18n, forms, ownership check |
+| [drizzle-orm.md](patterns/drizzle-orm.md) | Schema organization, queries, pagination, ILIKE |
+| [better-auth.md](patterns/better-auth.md) | Admin verification, client-side session |
+| [tailwind-v4.md](patterns/tailwind-v4.md) | CSS-first config, variable syntax, shadcn/ui |
+| [radix-ui-hydration.md](patterns/radix-ui-hydration.md) | **CRITICAL** Mounted state pattern for DropdownMenu |
+| [csp.md](patterns/csp.md) | Production CSP, style-src, worker-src configuration |
+| [e2e-testing.md](patterns/e2e-testing.md) | Test isolation, fixtures, loading state testing |
+| [documentation.md](patterns/documentation.md) | Test docs, API docs, JSDoc patterns |
+| [csrf-protection.md](patterns/csrf-protection.md) | Two-function auth pattern, CSRF validation |
+| [rate-limiting.md](patterns/rate-limiting.md) | Redis-based rate limiting, limiter config |
+| [image-optimization.md](patterns/image-optimization.md) | LocalStack workaround, OptimizedAvatar |
+
+---
+
+## Quick Reference
+
+詳細はパターンファイルを参照。ここでは最重要パターンのみ記載。
+
+### Radix UI Hydration (CRITICAL)
+
+```typescript
+const [mounted, setMounted] = useState(false)
+useEffect(() => { setMounted(true) }, [])
+
+if (!mounted) return <PlaceholderWithoutRadixUI />
+return <ComponentWithRadixUI />
+```
+
+→ 詳細: [radix-ui-hydration.md](patterns/radix-ui-hydration.md)
+
+### Key Patterns (詳細は各ファイル参照)
+
+| Pattern | File | 概要 |
+|---------|------|------|
+| Async Params | [code-patterns.md](patterns/code-patterns.md) | `params: Promise<...>` → `await params` |
+| Server Actions | [code-patterns.md](patterns/code-patterns.md) | `verifyAdminMutation()` → Validation → DB → Redirect |
+| CSRF Protection | [csrf-protection.md](patterns/csrf-protection.md) | Queries: `verifyAdmin()`, Mutations: `verifyAdminMutation()` |
+| Rate Limiting | [rate-limiting.md](patterns/rate-limiting.md) | `checkRateLimit()` for destructive ops |
+| Ownership Check | [code-patterns.md](patterns/code-patterns.md) | Verify `authorId === userId` before mutation |
+
+---
+
+## Known Issues
+
+| Issue | Symptom | Fix |
+|-------|---------|-----|
+| Hydration mismatch | Console error "Hydration failed..." | Use `mounted` state pattern |
+| Sidebar overlap | Layout breaks after adding shadcn component | Run CSS variable fix script |
+| ILIKE injection | Search returns unexpected results | Use `escapeLikePattern()` |
+| Slow page load | N+1 queries | Use batch queries with `inArray()` |
+| Static rendering fails | Translations slow | Add `setRequestLocale(locale)` |
+| Japanese 404 | Tag/category pages not found | Use `decodeURIComponent(slug)` |
+| Login redirect loop | Returns to login after success | Use `window.location.href` |
+| CSP: inline style blocked | Production: "style-src ... violated" | Add `'unsafe-inline'` to style-src |
+| Monaco Editor broken | No syntax highlight, worker errors | Add `worker-src 'self' blob:'` to CSP |
+| LocalStack image 400 | Avatar not displayed, 400 Bad Request | Use `unoptimized` prop. See [image-optimization.md](patterns/image-optimization.md) |
+| Rate limit exceeded | "Try again in Xs" error | Expected behavior. Wait or adjust `RateLimiters` config |
+
+---
+
+## Command Reference
+
+```bash
+# Testing
+pnpm --filter admin test              # Run all
+pnpm --filter admin test --watch      # Watch mode
+pnpm --filter admin test --coverage   # With coverage
+npx playwright test --reporter=list   # E2E tests (Playwright Server)
+
+# Linting
+pnpm --filter admin lint              # ESLint
+pnpm --filter admin lint --fix        # Auto-fix
+pnpm --filter admin tsc --noEmit      # TypeScript
+
+# Development
+pnpm dev:admin                        # Start dev server
+pnpm --filter admin build             # Production build
+
+# Database
+pnpm --filter @repo/database db:push  # Apply schema
+pnpm --filter @repo/database db:seed  # Seed data
+```
+
+---
+
+## Seed Data Structure
+
+### Test Accounts
+
+| Role | Email | Password |
+|------|-------|----------|
+| Admin | admin@example.com | Admin@Test2024! |
+| User | user@example.com | User@Test2024! |
+
+### Content Data
+
+| Entity | Count | Notes |
+|--------|-------|-------|
+| Categories | 5 | 技術, プログラミング, Web開発, etc. |
+| Tags | 10 | JavaScript, TypeScript, React, etc. |
+| Posts | 150 | 30 per category, with Markdown content |
+| Comments | ~45 | Mix of approved/pending/deleted, includes replies |
+
+### Running Seed
+
+```bash
+# Inside Docker (uses correct DATABASE_URL)
+docker compose exec -T admin-app pnpm --filter @repo/database db:seed
+
+# Direct with explicit URL
+DATABASE_URL="postgresql://..." pnpm --filter @repo/database db:seed
+```
+
+---
+
+## File Structure Reference
+
+| Path | Purpose |
+|------|---------|
+| `app/[locale]/(dashboard)/features/page.tsx` | List page |
+| `app/[locale]/(dashboard)/features/new/page.tsx` | Create page |
+| `app/[locale]/(dashboard)/features/[id]/edit/page.tsx` | Edit page |
+| `components/ui/` | shadcn/ui components |
+| `components/feature-form.tsx` | Feature-specific form |
+| `lib/actions/features.ts` | Server Actions |
+| `messages/{ja,en}/` | i18n translations (directory format) |
+| `__tests__/` | Unit tests |