shirokuma-docs 0.1.0-alpha.1

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

@@ -0,0 +1,335 @@
+# Code Patterns
+
+## Action Organization (Directory-Based)
+
+Server Actions should be organized by their nature:
+
+```
+lib/actions/
+├── crud/                    # Table-driven CRUD actions (1:1 with DB tables)
+│   ├── organizations.ts     # CRUD for organizations table
+│   ├── projects.ts          # CRUD for projects table
+│   ├── sessions.ts          # CRUD for work_sessions table
+│   ├── entities.ts          # CRUD for entities table
+│   └── members.ts           # CRUD for team_members table
+│
+├── domain/                  # Domain-driven composite actions
+│   ├── dashboard.ts         # Aggregates data from multiple tables
+│   ├── contexts.ts          # User context management (cross-cutting)
+│   ├── publishing.ts        # Post publishing workflow
+│   ├── moderation.ts        # Content moderation operations
+│   └── onboarding.ts        # User onboarding flow
+│
+└── types.ts                 # Shared types (ActionResult, etc.)
+```
+
+### CRUD Actions (`crud/`)
+
+**Characteristics**:
+- 1:1 mapping with database tables
+- Standard CRUD operations: `get`, `list`, `create`, `update`, `delete`
+- Single table focus (may join for reads, but writes to one table)
+- Predictable naming: `get{Entity}`, `create{Entity}`, etc.
+
+```typescript
+// lib/actions/crud/projects.ts
+/**
+ * @serverAction
+ * @feature ProjectManagement
+ * @dbTables projects
+ */
+
+export async function getProjects(orgId: string) { /* ... */ }
+export async function getProject(id: string) { /* ... */ }
+export async function createProject(formData: FormData) { /* ... */ }
+export async function updateProject(id: string, formData: FormData) { /* ... */ }
+export async function deleteProject(id: string) { /* ... */ }
+```
+
+### Domain Actions (`domain/`)
+
+**Characteristics**:
+- Business capability focused
+- Operates on multiple tables
+- Complex workflows or aggregations
+- Named by business operation, not table
+
+```typescript
+// lib/actions/domain/dashboard.ts
+/**
+ * @serverAction
+ * @feature DashboardManagement
+ * @dbTables projects, sessions, entities, activities
+ */
+
+export async function getDashboardStats(orgId: string) {
+  // Aggregates from: projects, sessions, entities, activities
+}
+
+export async function getRecentActivity(orgId: string, limit: number) {
+  // Joins: activities, users, projects
+}
+```
+
+```typescript
+// lib/actions/domain/publishing.ts
+/**
+ * @serverAction
+ * @feature ContentPublishing
+ * @dbTables posts, categories, tags, post_tags, related_posts
+ */
+
+export async function publishPost(postId: string) {
+  // 1. Validate post is ready
+  // 2. Update post status
+  // 3. Create activity log
+  // 4. Invalidate caches
+  // 5. Send notifications
+}
+
+export async function schedulePost(postId: string, publishAt: Date) { /* ... */ }
+export async function unpublishPost(postId: string) { /* ... */ }
+```
+
+### Decision Guide
+
+| Question | CRUD | Domain |
+|----------|------|--------|
+| Operates on single table? | ✅ | ❌ |
+| Standard get/create/update/delete? | ✅ | ❌ |
+| Business workflow with steps? | ❌ | ✅ |
+| Aggregates from multiple tables? | ❌ | ✅ |
+| Named after table? | ✅ | ❌ |
+| Named after business operation? | ❌ | ✅ |
+
+### Import Pattern
+
+```typescript
+// From components/pages
+import { getProjects, createProject } from "@/lib/actions/crud/projects"
+import { getDashboardStats } from "@/lib/actions/domain/dashboard"
+
+// Re-export for convenience (optional)
+// lib/actions/index.ts
+export * from "./crud/projects"
+export * from "./crud/organizations"
+export * from "./domain/dashboard"
+```
+
+---
+
+## Next.js 16: Async Params
+
+```typescript
+type Props = {
+  params: Promise<{ locale: string; id: string }>
+  searchParams: Promise<{ page?: string }>
+}
+
+export default async function Page({ params, searchParams }: Props) {
+  const { locale, id } = await params
+  const { page } = await searchParams
+}
+```
+
+## ActionResult with Error Codes
+
+Always include error codes for programmatic handling:
+
+```typescript
+type ActionResult<T = void> =
+  | { success: true; data?: T }
+  | { success: false; error: string; code?: ActionErrorCode }
+
+type ActionErrorCode =
+  | "UNAUTHORIZED"
+  | "CSRF_INVALID"
+  | "VALIDATION_FAILED"
+  | "NOT_FOUND"
+  | "FORBIDDEN"
+  | "DUPLICATE"
+  | "RATE_LIMIT_EXCEEDED"
+  | "INTERNAL_ERROR"
+```
+
+## Two-Function Auth Pattern
+
+Use different functions for reads vs mutations:
+
+```typescript
+// lib/auth-utils.ts
+
+// For read operations (no CSRF needed)
+export async function verifyAdmin(): Promise<string> {
+  const session = await verifyAdminAuth(await headers())
+  if (!session?.user?.id) throw new Error("Unauthorized")
+  return session.user.id
+}
+
+// For mutations (CSRF + auth)
+export async function verifyAdminMutation(): Promise<string> {
+  await validateCsrfToken()  // Step 1: CSRF
+  return await verifyAdmin() // Step 2: Auth
+}
+```
+
+**Usage:**
+- Read operations: `verifyAdmin()`
+- Mutations (create/update/delete): `verifyAdminMutation()`
+
+## Server Action Pattern (Mutations)
+
+```typescript
+"use server"
+
+import { z } from "zod"
+import { revalidatePath } from "next/cache"
+import { redirect } from "next/navigation"
+import { verifyAdminMutation } from "@/lib/auth-utils"
+
+const Schema = z.object({
+  name: z.string().min(1).max(100),
+})
+
+export async function createFeature(formData: FormData): Promise<ActionResult<{ id: string }> | void> {
+  // Step 1: Auth + CSRF (verifyAdminMutation does both)
+  const userId = await verifyAdminMutation()
+
+  // Step 2: Validation
+  const validated = Schema.safeParse({ name: formData.get("name") })
+  if (!validated.success) {
+    return { success: false, error: validated.error.errors[0].message, code: "VALIDATION_FAILED" }
+  }
+
+  // Step 3: Business logic (duplicate check, etc.)
+  const existing = await db.select().from(features).where(eq(features.name, validated.data.name)).limit(1)
+  if (existing.length > 0) {
+    return { success: false, error: "Name already exists", code: "DUPLICATE" }
+  }
+
+  // Step 4: Database operation + Cache invalidation + Redirect
+  await db.insert(features).values({ ...validated.data, authorId: userId })
+  revalidatePath("/features")
+  redirect("/features")
+}
+```
+
+## Ownership Check Pattern
+
+Before mutating a resource, verify the user owns it:
+
+```typescript
+export async function updateFeature(id: string, formData: FormData): Promise<ActionResult | void> {
+  const userId = await verifyAdminMutation()
+
+  // Ownership check
+  const existing = await db.select().from(features).where(eq(features.id, id)).limit(1)
+  if (existing.length === 0) {
+    return { success: false, error: "Not found", code: "NOT_FOUND" }
+  }
+  if (existing[0].authorId !== userId) {
+    return { success: false, error: "Not authorized", code: "FORBIDDEN" }
+  }
+
+  // Continue with update...
+}
+```
+
+## Rate Limiting Pattern
+
+Add rate limiting AFTER auth, BEFORE business logic:
+
+```typescript
+export async function deleteFeature(id: string): Promise<ActionResult> {
+  const userId = await verifyAdminMutation()
+
+  // Rate limit check
+  const rateLimitKey = `delete-feature:${userId}`
+  const rateLimitResult = await checkRateLimit(rateLimitKey, RateLimiters.delete)
+
+  if (!rateLimitResult.success) {
+    const waitSeconds = Math.ceil((rateLimitResult.reset * 1000 - Date.now()) / 1000)
+    return {
+      success: false,
+      error: `Rate limit exceeded. Try again in ${waitSeconds}s`,
+      code: "RATE_LIMIT_EXCEEDED"
+    }
+  }
+
+  // Continue with delete...
+}
+```
+
+## Transaction Pattern
+
+Use transactions for related data operations:
+
+```typescript
+await db.transaction(async (tx) => {
+  const result = await tx.insert(posts).values(newPost).returning({ id: posts.id })
+  const postId = result[0].id
+
+  if (tagIds.length > 0) {
+    await tx.insert(postTags).values(
+      tagIds.map((tagId) => ({ postId, tagId }))
+    )
+  }
+})
+```
+
+## Open Redirect Protection
+
+Validate callback URLs to prevent open redirects:
+
+```typescript
+function isInternalUrl(url: string | undefined): boolean {
+  if (!url) return false
+  return url.startsWith("/") && !url.startsWith("//")
+}
+
+// Usage in login form
+const safeCallbackUrl = isInternalUrl(callbackUrl) ? callbackUrl! : "/"
+window.location.href = safeCallbackUrl
+```
+
+## Server Component with i18n
+
+```typescript
+import { getTranslations, setRequestLocale } from "next-intl/server"
+
+export default async function Page({ params }: { params: Promise<{ locale: string }> }) {
+  const { locale } = await params
+  setRequestLocale(locale)  // REQUIRED for static rendering
+
+  const t = await getTranslations("namespace")
+  return <h1>{t("title")}</h1>
+}
+```
+
+## Client Component with Form
+
+```typescript
+"use client"
+
+import { useState, useTransition } from "react"
+import { useTranslations } from "next-intl"
+
+export function FeatureForm() {
+  const [isPending, startTransition] = useTransition()
+  const [error, setError] = useState<string | null>(null)
+  const t = useTranslations("features.form")
+
+  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault()
+    setError(null)
+    const formData = new FormData(e.currentTarget)
+
+    startTransition(async () => {
+      const result = await createFeature(formData)
+      if (!result.success) setError(result.error)
+    })
+  }
+
+  return <form onSubmit={handleSubmit}>{/* ... */}</form>
+}
+```

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

@@ -0,0 +1,324 @@
+# Coding Conventions
+
+## File & Directory Naming
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Components | kebab-case | `post-form.tsx`, `user-nav.tsx` |
+| Pages | kebab-case | `page.tsx`, `layout.tsx` |
+| Utilities | kebab-case | `auth-client.ts`, `utils.ts` |
+| Server Actions | kebab-case | `posts.ts`, `categories.ts` |
+| Test Files | kebab-case + `.test` | `posts.test.ts`, `auth.spec.ts` |
+| Hooks | kebab-case + `use-` | `use-mobile.tsx` |
+| Constants | kebab-case | `constants.ts` |
+
+## Variable & Function Naming
+
+```typescript
+// Variables: camelCase
+const userName = "John"
+const postCount = 10
+const isLoading = false
+
+// Functions: camelCase (verb + noun)
+function getUserById(id: string) { }
+function createPost(data: PostInput) { }
+async function handleSubmit(e: FormEvent) { }
+
+// Components: PascalCase
+function UserProfile() { }
+function PostForm({ post }: PostFormProps) { }
+
+// Constants: UPPER_SNAKE_CASE
+const MAX_RETRIES = 3
+const API_BASE_URL = "/api"
+const DEFAULT_PAGE_SIZE = 10
+
+// Types/Interfaces: PascalCase
+interface UserData { }
+type PostInput = { }
+type ActionResult<T> = { success: true; data: T } | { success: false; error: string }
+
+// Enums: PascalCase with PascalCase members
+enum UserRole {
+  Admin = "admin",
+  Editor = "editor",
+  User = "user",
+}
+```
+
+## Import Organization
+
+Imports should be grouped in this order (with blank lines between groups):
+
+```typescript
+// 1. React/Next.js (framework)
+import { useState, useTransition } from "react"
+import { useRouter } from "next/navigation"
+import Link from "next/link"
+
+// 2. External packages (npm)
+import { z } from "zod"
+import { useTranslations } from "next-intl"
+
+// 3. Internal packages (monorepo)
+import { db, posts, eq } from "@repo/database"
+
+// 4. Local absolute imports (@/ alias)
+import { auth } from "@/lib/auth"
+import { Button } from "@/components/ui/button"
+
+// 5. Relative imports
+import { formatDate } from "./utils"
+import type { PostFormProps } from "./types"
+```
+
+## TypeScript Conventions
+
+```typescript
+// Use explicit return types for public APIs
+export async function getPosts(): Promise<Post[]> { }
+
+// Use `unknown` instead of `any`
+function parse(data: unknown): Item[] {
+  if (!isValidData(data)) throw new Error("Invalid")
+  return data.items
+}
+
+// Use type guards for runtime checks
+function isValidData(data: unknown): data is { items: Item[] } {
+  return typeof data === "object" && data !== null && "items" in data
+}
+
+// Prefix unused variables with underscore
+function handler(_req: Request, res: Response) {
+  // _req is intentionally unused
+}
+
+// Use interfaces for object shapes
+interface PostFormProps {
+  post?: Post
+  categories: Category[]
+}
+
+// Use type for unions, intersections, or aliases
+type ActionResult<T> = { success: true; data: T } | { success: false; error: string }
+type PostStatus = "draft" | "published" | "archived"
+```
+
+## Component Structure
+
+```typescript
+"use client" // or "use server" - directive first
+
+// Imports (grouped as above)
+import { useState } from "react"
+import { Button } from "@/components/ui/button"
+import type { Props } from "./types"
+
+// Type definitions (if small, otherwise separate file)
+interface ComponentProps {
+  title: string
+  onSubmit: (data: FormData) => Promise<void>
+}
+
+// Component function (PascalCase)
+export function MyComponent({ title, onSubmit }: ComponentProps) {
+  // 1. Hooks first
+  const [state, setState] = useState("")
+  const t = useTranslations("namespace")
+
+  // 2. Derived values
+  const isValid = state.length > 0
+
+  // 3. Event handlers
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    setState(e.target.value)
+  }
+
+  // 4. Render
+  return (
+    <div className="space-y-4">
+      {/* JSX content */}
+    </div>
+  )
+}
+```
+
+## Server Action Structure
+
+```typescript
+"use server"
+
+// Imports
+import { revalidatePath } from "next/cache"
+import { headers } from "next/headers"
+import { db, posts, eq } from "@repo/database"
+import { z } from "zod"
+
+// Validation schema (internal)
+const Schema = z.object({
+  title: z.string().min(1).max(200),
+  content: z.string().min(1),
+})
+
+// Return type definition
+// Return type definition
+type ActionResult<T = void> =
+  | { success: true; data?: T }
+  | { success: false; error: string }
+
+/**
+ * JSDoc comment for public actions
+ */
+export async function createPost(formData: FormData): Promise<ActionResult<{ id: string }>> {
+  // 1. Auth check
+  const session = await verifyAdmin(await headers())
+  if (!session) return { success: false, error: "Unauthorized" }
+
+  // 2. Validation
+  const validated = Schema.safeParse({
+    title: formData.get("title"),
+    content: formData.get("content"),
+  })
+  if (!validated.success) {
+    return { success: false, error: validated.error.errors[0].message }
+  }
+
+  // 3. Database operation with try/catch
+  try {
+    const [result] = await db.insert(posts).values(validated.data).returning()
+    revalidatePath("/posts")
+    return { success: true, data: { id: result.id } }
+  } catch (error) {
+    console.error("Failed to create post:", error)
+    return { success: false, error: "Operation failed" }
+  }
+}
+```
+
+## ESLint + Prettier + Stylistic Setup
+
+### eslint.config.mjs
+
+```javascript
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+import reactHooks from "eslint-plugin-react-hooks";
+import stylistic from "@stylistic/eslint-plugin";
+import eslintConfigPrettier from "eslint-config-prettier";
+
+export default tseslint.config(
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  eslintConfigPrettier,  // Prettier互換（先に配置）
+  {
+    files: ["**/*.{ts,tsx}"],
+    plugins: {
+      "react-hooks": reactHooks,
+      "@stylistic": stylistic,
+    },
+    rules: {
+      // TypeScript
+      "@typescript-eslint/no-unused-vars": ["warn", {
+        argsIgnorePattern: "^_",
+        varsIgnorePattern: "^_",
+      }],
+      "@typescript-eslint/no-explicit-any": "warn",
+      "@typescript-eslint/no-empty-object-type": "off",
+
+      // React hooks
+      "react-hooks/rules-of-hooks": "error",
+      "react-hooks/exhaustive-deps": "warn",
+
+      // Stylistic - 型定義は必ず複数行
+      "@stylistic/object-curly-newline": ["error", {
+        TSTypeLiteral: "always",
+        TSInterfaceBody: "always",
+      }],
+
+      // General
+      "no-console": ["warn", { allow: ["warn", "error"] }],
+    },
+  },
+  { ignores: [".next/**", "node_modules/**", "coverage/**", "**/*.d.ts"] }
+);
+```
+
+### .prettierrc
+
+```json
+{
+  "semi": false,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100,
+  "bracketSpacing": true,
+  "arrowParens": "always"
+}
+```
+
+### Commands
+
+```bash
+pnpm --filter {app} lint        # ESLintチェック
+pnpm --filter {app} lint:fix    # ESLint自動修正
+pnpm --filter {app} format      # Prettier整形
+pnpm --filter {app} format:check # Prettier差分確認
+pnpm --filter {app} fix         # 一括修正（推奨）
+```
+
+**Key Rules:**
+- No `any` types (use `unknown`) - warning level
+- Unused variables must be prefixed with `_`
+- React hooks rules enforced
+- **型定義は必ず複数行** (`@stylistic/object-curly-newline`)
+
+## Code Style Guidelines
+
+1. **Maximum Nesting**: 3 levels deep
+   ```typescript
+   // Bad: 4+ levels
+   if (a) {
+     if (b) {
+       if (c) {
+         if (d) { }  // Too deep
+       }
+     }
+   }
+
+   // Good: Early returns
+   if (!a) return
+   if (!b) return
+   if (!c) return
+   // Process d
+   ```
+
+2. **Function Length**: Keep functions focused (< 50 lines)
+
+3. **Parameter Count**: Maximum 3, use object for more
+   ```typescript
+   // Bad
+   function create(name, email, role, dept, manager) { }
+
+   // Good
+   function create(params: CreateParams) { }
+   ```
+
+4. **Magic Numbers**: Use named constants
+   ```typescript
+   // Bad
+   if (password.length < 8) { }
+
+   // Good
+   const MIN_PASSWORD_LENGTH = 8
+   if (password.length < MIN_PASSWORD_LENGTH) { }
+   ```
+
+5. **Boolean Naming**: Use `is`, `has`, `can`, `should` prefix
+   ```typescript
+   const isLoading = true
+   const hasPermission = user.role === "admin"
+   const canEdit = isOwner || isAdmin
+   ```